diff options
| author | Onur Gündüz <ogunduz@gmail.com> | 2026-06-28 06:16:07 +0200 |
|---|---|---|
| committer | Onur Gündüz <ogunduz@gmail.com> | 2026-06-28 06:16:07 +0200 |
| commit | 9eacbb42f9a5931bf33d968f775fc806c46b11b0 (patch) | |
| tree | bf9a34182b2db560023ba0deb060146bdbcc0d34 | |
| parent | 4137fae6df4e77198b8ddd9d9647a1ee0c7c49d3 (diff) | |
| download | colabctl-9eacbb42f9a5931bf33d968f775fc806c46b11b0.tar.gz colabctl-9eacbb42f9a5931bf33d968f775fc806c46b11b0.zip | |
Init
| -rw-r--r-- | README.md | 89 | ||||
| -rw-r--r-- | auth.go | 79 | ||||
| -rw-r--r-- | cp.go | 164 | ||||
| -rw-r--r-- | exec.go | 220 | ||||
| -rw-r--r-- | go.mod | 38 | ||||
| -rw-r--r-- | go.sum | 86 | ||||
| -rw-r--r-- | internal/auth/oauth.go | 163 | ||||
| -rw-r--r-- | internal/config/config.go | 79 | ||||
| -rw-r--r-- | internal/config/sessions.go | 126 | ||||
| -rw-r--r-- | internal/drive/drive.go | 116 | ||||
| -rw-r--r-- | internal/notebook/notebook.go | 106 | ||||
| -rw-r--r-- | list.go | 58 | ||||
| -rw-r--r-- | main.go | 51 | ||||
| -rw-r--r-- | output.go | 118 | ||||
| -rw-r--r-- | run.go | 102 | ||||
| -rw-r--r-- | sessions.go | 85 |
16 files changed, 1680 insertions, 0 deletions
@@ -1 +1,90 @@ # colabctl + +A command-line client for Google Colab written in Go. + +It lets you list, run, and interact with your notebooks from the terminal. + +## Installation + +```sh +go install github.com/tetsuo/colabctl@latest +``` + +## Getting started + +### 1. Create OAuth2 credentials + +1. Go to <https://console.cloud.google.com/apis/credentials>. +2. Create an **OAuth 2.0 Client ID** of type **Desktop application**. +3. Enable the **Google Drive API** for your project. +4. Download or copy the **Client ID** and **Client Secret**. +5. Add yourself to the tests users if your app is sandboxed. + +### 2. Authenticate + +```sh +export COLAB_CLIENT_ID=your-client-id +export COLAB_CLIENT_SECRET=your-client-secret +colabctl auth login +``` + +A browser window opens for Google sign-in. After approval, the token is stored locally in `~/.config/colab/sessions.json`, so you will not need to sign in again until the refresh token expires. + +Alternatively, pass credentials once: + +```sh +colabctl auth login --client-id <id> --client-secret <secret> +``` + +## Usage + +```sh +# List notebooks +colabctl list + +# Run all cells in a notebook (get the ID from colabctl list) +colabctl run ID + +# Interactive REPL +colabctl exec ID + +# Run on T4 GPU +echo '!nvidia-smi' | colabctl exec ID --accelerator T4 + +# Copy files to/from the active runtime +colabctl cp :/content/model.pt ./model.pt # download +colabctl cp train.py :/content/train.py # upload + +# A directory is not copied directly; archive it on the runtime first. +# colabctl exec <id> <<< '!tar czf /content/out.tgz -C /content/model .' +# colabctl cp :content/out.tgz ./out.tgz + +# Check auth status +colabctl auth status + +# Log out +colabctl auth logout +``` + +### REPL multi-line input + +End a line with `\` to continue on the next line: + +``` +>>> for i in range(3): \ +... print(i) +0 +1 +2 +``` + +## How it works + +1. `auth` starts a temporary localhost server for code exchange during authorization. The received refresh token is persisted to your HOME folder and reused automatically. +2. `list` queries the Google Drive API v3 for files with MIME type `application/vnd.google.colaboratory`. +3. `run` / `exec` calls the Colab session API (`POST /api/sessions`) to start a runtime, then connects to the Jupyter kernel over WebSocket using the Jupyter wire protocol (v5) to send `execute_request` messages and stream back output. +4. `cp` uses the Jupyter Contents API (`/api/contents`) over the runtime proxy to download or upload a single file. Paths are relative to the Jupyter server root. Directories are not handled directly; archive them on the runtime (`tar`) and copy the archive. + +## License + +MIT @@ -0,0 +1,79 @@ +package main + +import ( + "fmt" + "os" + + "github.com/spf13/cobra" + + "github.com/tetsuo/colabctl/internal/auth" + "github.com/tetsuo/colabctl/internal/config" +) + +var authCmd = &cobra.Command{ + Use: "auth", + Short: "Manage authentication", +} + +var loginCmd = &cobra.Command{ + Use: "login", + Short: "Log in to Google and store credentials locally", + RunE: func(cmd *cobra.Command, _ []string) error { + id, _ := cmd.Flags().GetString("client-id") + secret, _ := cmd.Flags().GetString("client-secret") + + if id != "" { + clientID = id + } + if secret != "" { + clientSecret = secret + } + requireCredentials() + + if err := auth.Login(cmd.Context(), clientID, clientSecret); err != nil { + return err + } + fmt.Println("Authentication successful. Token saved.") + return nil + }, +} + +var logoutCmd = &cobra.Command{ + Use: "logout", + Short: "Remove locally stored credentials", + RunE: func(_ *cobra.Command, _ []string) error { + if err := config.DeleteToken(); err != nil { + return err + } + fmt.Println("Logged out.") + return nil + }, +} + +var authStatusCmd = &cobra.Command{ + Use: "status", + Short: "Show whether you are currently authenticated", + RunE: func(cmd *cobra.Command, _ []string) error { + tok, err := config.LoadToken() + if err != nil { + fmt.Fprintln(os.Stderr, "Not authenticated. Run `colabctl auth login`.") + return nil + } + if tok.Valid() { + fmt.Println("Authenticated. Token is valid.") + } else { + fmt.Println("Authenticated (token expired, will be refreshed automatically).") + } + return nil + }, +} + +func init() { + loginCmd.Flags().String("client-id", "", "Google OAuth2 client ID (overrides COLAB_CLIENT_ID)") + loginCmd.Flags().String("client-secret", "", "Google OAuth2 client secret (overrides COLAB_CLIENT_SECRET)") + + authCmd.AddCommand(loginCmd) + authCmd.AddCommand(logoutCmd) + authCmd.AddCommand(authStatusCmd) + rootCmd.AddCommand(authCmd) +} @@ -0,0 +1,164 @@ +package main + +import ( + "context" + "fmt" + "os" + "path" + "path/filepath" + "strings" + + "github.com/spf13/cobra" + + "github.com/tetsuo/colabctl/internal/auth" + "github.com/tetsuo/colabctl/internal/colab" +) + +// remoteSpec is a parsed copy endpoint. When isRemote is true the location +// lives on a runtime; endpoint may be empty to mean "the only active runtime". +type remoteSpec struct { + isRemote bool + endpoint string + path string +} + +// parseSpec splits an scp-style argument. An argument is treated as remote when +// it contains a colon that comes before any slash, mirroring scp. The part +// before the colon is the runtime endpoint, or empty for the active runtime. +func parseSpec(arg string) remoteSpec { + idx := strings.IndexByte(arg, ':') + if idx < 0 || strings.IndexByte(arg[:idx], '/') >= 0 { + return remoteSpec{isRemote: false, path: arg} + } + return remoteSpec{isRemote: true, endpoint: arg[:idx], path: arg[idx+1:]} +} + +var cpCmd = &cobra.Command{ + Use: "cp <src> <dst>", + Short: "Copy files between your machine and a Colab runtime (scp-style)", + Long: `Copy a file to or from an active Colab runtime, using scp-style paths. + +A remote location is written as endpoint:path. Leave the endpoint empty to use +the only active runtime: + + # Download a trained model from the active runtime. + colabctl cp :/content/model.pt ./model.pt + + # Upload a training script to a specific runtime. + colabctl cp train.py gpu-t4-s-abc123:/content/train.py + +Get the endpoint from 'colabctl sessions'. Directories are not copied directly; +archive them on the runtime first (tar) and copy the archive.`, + Args: cobra.ExactArgs(2), + RunE: func(cmd *cobra.Command, args []string) error { + requireCredentials() + ctx := cmd.Context() + + src := parseSpec(args[0]) + dst := parseSpec(args[1]) + + if src.isRemote == dst.isRemote { + if src.isRemote { + return fmt.Errorf("copying between two runtimes is not supported") + } + return fmt.Errorf("at least one path must be remote (endpoint:path); use cp(1) for local copies") + } + + httpClient, err := auth.Client(ctx, clientID, clientSecret) + if err != nil { + return err + } + client := colab.New(httpClient) + + if src.isRemote { + return download(ctx, client, src, dst.path) + } + return upload(ctx, client, src.path, dst) + }, +} + +// resolveRuntime finds an active runtime. With an explicit endpoint it looks +// that one up; otherwise it requires exactly one active runtime. +func resolveRuntime(ctx context.Context, client *colab.Client, endpoint string) (*colab.AssignmentInfo, error) { + if endpoint != "" { + return client.AssignmentFromEndpoint(ctx, endpoint) + } + + runtimes, err := client.ListAssignments(ctx) + if err != nil { + return nil, err + } + switch len(runtimes) { + case 0: + return nil, fmt.Errorf("no active runtimes: start one with 'colabctl exec', or name one as endpoint:path") + case 1: + return client.AssignmentFromEndpoint(ctx, runtimes[0].Endpoint) + default: + var b strings.Builder + fmt.Fprintf(&b, "%d active runtimes: name one in the path as endpoint:path:\n", len(runtimes)) + for _, r := range runtimes { + fmt.Fprintf(&b, " %s\n", r.Endpoint) + } + return nil, fmt.Errorf("%s", b.String()) + } +} + +func download(ctx context.Context, client *colab.Client, src remoteSpec, localPath string) error { + assignment, err := resolveRuntime(ctx, client, src.endpoint) + if err != nil { + return err + } + + fc, err := client.FetchFile(ctx, assignment, src.path) + if err != nil { + return err + } + + // If the local target is a directory (or ends with a separator), keep the + // remote file name inside it. + target := localPath + if target == "" || strings.HasSuffix(target, string(os.PathSeparator)) { + target = filepath.Join(target, fc.Name) + } else if fi, statErr := os.Stat(target); statErr == nil && fi.IsDir() { + target = filepath.Join(target, fc.Name) + } + + if dir := filepath.Dir(target); dir != "" { + if err := os.MkdirAll(dir, 0o755); err != nil { + return err + } + } + if err := os.WriteFile(target, fc.Data, 0o644); err != nil { + return err + } + fmt.Fprintf(os.Stderr, "Downloaded %s (%d bytes) -> %s\n", src.path, len(fc.Data), target) + return nil +} + +func upload(ctx context.Context, client *colab.Client, localPath string, dst remoteSpec) error { + data, err := os.ReadFile(localPath) + if err != nil { + return err + } + + assignment, err := resolveRuntime(ctx, client, dst.endpoint) + if err != nil { + return err + } + + // If the remote target names a directory, keep the local file name. + remotePath := dst.path + if remotePath == "" || strings.HasSuffix(remotePath, "/") { + remotePath = path.Join(remotePath, filepath.Base(localPath)) + } + + if err := client.PutFile(ctx, assignment, remotePath, data); err != nil { + return err + } + fmt.Fprintf(os.Stderr, "Uploaded %s (%d bytes) -> %s\n", localPath, len(data), remotePath) + return nil +} + +func init() { + rootCmd.AddCommand(cpCmd) +} @@ -0,0 +1,220 @@ +package main + +import ( + "bufio" + "fmt" + "io" + "os" + "strings" + "time" + + "github.com/spf13/cobra" + + "github.com/tetsuo/colabctl/internal/auth" + "github.com/tetsuo/colabctl/internal/colab" + "github.com/tetsuo/colabctl/internal/config" +) + +var execCmd = &cobra.Command{ + Use: "exec <file-id>", + Short: "Open an interactive REPL connected to a Colab runtime", + Long: `Connects to a Colab runtime and opens an interactive REPL. + +By default a new runtime is allocated. If you already have a runtime running +(see 'colabctl sessions'), pass its endpoint with --session to reuse it instead +of allocating a new one. If only one runtime is active it is reused +automatically. + +Get the file ID from: + + colabctl list`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + requireCredentials() + + fileID := args[0] + ctx := cmd.Context() + sessionEndpoint, _ := cmd.Flags().GetString("session") + accelerator, _ := cmd.Flags().GetString("accelerator") + outputDir, _ := cmd.Flags().GetString("output-dir") + + httpClient, err := auth.Client(ctx, clientID, clientSecret) + if err != nil { + return err + } + + colabClient := colab.New(httpClient) + + var assignment *colab.AssignmentInfo + + // resolveFromCache tries the local session cache for the given endpoint. + // Returns nil (no error) when the cached entry is missing or expired. + resolveFromCache := func(endpoint string) *colab.AssignmentInfo { + s, err := config.LoadSession(endpoint) + if err != nil || s == nil || !s.Valid() { + return nil + } + fmt.Fprintf(os.Stderr, "Using cached session (endpoint %s, token valid until %s)\n\n", + s.Endpoint, s.TokenExpiresAt.Format("15:04:05")) + return &colab.AssignmentInfo{ + Endpoint: s.Endpoint, + RuntimeProxyInfo: colab.RuntimeProxyInfo{ + Token: s.Token, + URL: s.URL, + }, + } + } + + if sessionEndpoint != "" { + // User explicitly named an endpoint; check cache first. + if a := resolveFromCache(sessionEndpoint); a != nil { + assignment = a + } else { + assignment, err = colabClient.AssignmentFromEndpoint(ctx, sessionEndpoint) + if err != nil { + return fmt.Errorf("connect to session %s: %w", sessionEndpoint, err) + } + fmt.Fprintf(os.Stderr, "Connected to existing runtime (endpoint %s)\n\n", assignment.Endpoint) + } + } else { + // Check whether the user already has active runtimes. + runtimes, listErr := colabClient.ListAssignments(ctx) + if listErr == nil && len(runtimes) == 1 { + fmt.Fprintf(os.Stderr, "Reusing existing runtime (endpoint %s)\n", runtimes[0].Endpoint) + fmt.Fprintf(os.Stderr, " Tip: use --session <endpoint> to choose a specific one.\n\n") + if a := resolveFromCache(runtimes[0].Endpoint); a != nil { + assignment = a + } else { + assignment, err = colabClient.AssignmentFromEndpoint(ctx, runtimes[0].Endpoint) + if err != nil { + return fmt.Errorf("connect to existing runtime: %w", err) + } + } + } else if listErr == nil && len(runtimes) > 1 { + fmt.Fprintf(os.Stderr, "You have %d active runtimes. Use --session <endpoint> to pick one:\n\n", len(runtimes)) + for _, r := range runtimes { + accel := r.Accelerator + if accel == "" { + accel = "CPU" + } + fmt.Fprintf(os.Stderr, " %s (%s)\n", r.Endpoint, accel) + } + fmt.Fprintln(os.Stderr) + return fmt.Errorf("specify a runtime with --session <endpoint>") + } else { + // No existing runtimes (or list failed); allocate a new one. + fmt.Fprintf(os.Stderr, "Starting Colab runtime for %s …\n", fileID) + assignment, err = colabClient.Assign(ctx, notebookHash(), "", accelerator) + if err != nil { + return fmt.Errorf("start runtime: %w", err) + } + fmt.Fprintf(os.Stderr, "Runtime ready (endpoint %s)\n\n", assignment.Endpoint) + } + } + + // Persist the assignment so the next invocation skips the assign round-trip. + _ = config.SaveSession(&config.SessionState{ + Endpoint: assignment.Endpoint, + URL: assignment.RuntimeProxyInfo.URL, + Token: assignment.RuntimeProxyInfo.Token, + TokenExpiresAt: time.Now().Add(time.Duration(assignment.RuntimeProxyInfo.TokenExpiresInSecs) * time.Second), + }) + + kernel, err := colab.CreateAndConnectKernel(ctx, assignment) + if err != nil { + return fmt.Errorf("connect to kernel: %w", err) + } + defer kernel.Close() + + // Non-interactive mode: stdin is a pipe; read all input and execute once. + if fi, err := os.Stdin.Stat(); err == nil && fi.Mode()&os.ModeCharDevice == 0 { + input, err := io.ReadAll(os.Stdin) + if err != nil { + return fmt.Errorf("read stdin: %w", err) + } + code := strings.TrimRight(string(input), "\n") + if strings.TrimSpace(code) == "" { + return nil + } + outCh, err := kernel.Execute(ctx, code) + if err != nil { + return fmt.Errorf("execute: %w", err) + } + printOutputs(outCh, outputDir) + return nil + } + + // Interactive REPL. + scanner := bufio.NewScanner(os.Stdin) + // Allow large pastes. + scanner.Buffer(make([]byte, 1024*1024), 1024*1024) + + fmt.Println(`Colab REPL; connected to a live Colab kernel. +Type Python code and press Enter to run a single line. +To run a block: paste or type multiple lines, then press Enter twice on a blank line. +Commands: :quit :exit :help`) + + for { + fmt.Print(">>> ") + var lines []string + prevBlank := false + for { + if !scanner.Scan() { + fmt.Println() + return scanner.Err() + } + line := scanner.Text() + + if len(lines) == 0 { + // First line: handle special commands. + switch line { + case ":quit", ":exit": + return nil + case ":help": + fmt.Println("Type Python code. Press Enter twice on a blank line to execute a block. :quit to exit.") + goto nextPrompt + case "": + // Blank first line; just show a new prompt. + goto nextPrompt + } + } + + // Two consecutive blank lines end the block (same as IPython). + if line == "" && prevBlank { + // Drop the trailing blank lines from the block. + for len(lines) > 0 && lines[len(lines)-1] == "" { + lines = lines[:len(lines)-1] + } + break + } + + prevBlank = line == "" + lines = append(lines, line) + } + + { + code := strings.Join(lines, "\n") + code = strings.TrimRight(code, "\n") + if strings.TrimSpace(code) == "" { + goto nextPrompt + } + + outCh, err := kernel.Execute(ctx, code) + if err != nil { + fmt.Fprintf(os.Stderr, "error: %v\n", err) + goto nextPrompt + } + printOutputs(outCh, outputDir) + } + + nextPrompt: + } + }, +} + +func init() { + execCmd.Flags().StringP("session", "s", "", "Endpoint ID of an existing runtime to reuse (from 'colabctl sessions')") + execCmd.Flags().StringP("accelerator", "a", "", "Accelerator for a new runtime: T4, A100, TPU, L4, A100-80GB (default: CPU)") + execCmd.Flags().StringP("output-dir", "o", "", "Directory to save binary outputs (images, audio, video) into (default: current directory)") + rootCmd.AddCommand(execCmd) +} @@ -0,0 +1,38 @@ +module github.com/tetsuo/colabctl + +go 1.25.8 + +require ( + github.com/gorilla/websocket v1.5.3 + github.com/spf13/cobra v1.8.1 + golang.org/x/oauth2 v0.36.0 + google.golang.org/api v0.286.0 +) + +require ( + cloud.google.com/go/auth v0.20.0 // indirect + cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect + cloud.google.com/go/compute/metadata v0.9.0 // indirect + github.com/cespare/xxhash/v2 v2.3.0 // indirect + github.com/felixge/httpsnoop v1.0.4 // indirect + github.com/go-logr/logr v1.4.3 // indirect + github.com/go-logr/stdr v1.2.2 // indirect + github.com/google/s2a-go v0.1.9 // indirect + github.com/google/uuid v1.6.0 // indirect + github.com/googleapis/enterprise-certificate-proxy v0.3.16 // indirect + github.com/googleapis/gax-go/v2 v2.22.0 // indirect + github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/spf13/pflag v1.0.5 // indirect + go.opentelemetry.io/auto/sdk v1.2.1 // indirect + go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 // indirect + go.opentelemetry.io/otel v1.43.0 // indirect + go.opentelemetry.io/otel/metric v1.43.0 // indirect + go.opentelemetry.io/otel/trace v1.43.0 // indirect + golang.org/x/crypto v0.53.0 // indirect + golang.org/x/net v0.56.0 // indirect + golang.org/x/sys v0.46.0 // indirect + golang.org/x/text v0.38.0 // indirect + google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad // indirect + google.golang.org/grpc v1.81.1 // indirect + google.golang.org/protobuf v1.36.11 // indirect +) @@ -0,0 +1,86 @@ +cloud.google.com/go/auth v0.20.0 h1:kXTssoVb4azsVDoUiF8KvxAqrsQcQtB53DcSgta74CA= +cloud.google.com/go/auth v0.20.0/go.mod h1:942/yi/itH1SsmpyrbnTMDgGfdy2BUqIKyd0cyYLc5Q= +cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc= +cloud.google.com/go/auth/oauth2adapt v0.2.8/go.mod h1:XQ9y31RkqZCcwJWNSx2Xvric3RrU88hAYYbjDWYDL+c= +cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs= +cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10= +github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= +github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg= +github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U= +github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= +github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI= +github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= +github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= +github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= +github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek= +github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0= +github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/googleapis/enterprise-certificate-proxy v0.3.16 h1:F/VPrx0YPBdksZJQdCAp0WUsqnNmZpUZszzfYt0M5Dw= +github.com/googleapis/enterprise-certificate-proxy v0.3.16/go.mod h1:9Yb0eAkH/Xqhvv3zbeKf/+wMJqCeocWc6KIhDvEAuYE= +github.com/googleapis/gax-go/v2 v2.22.0 h1:PjIWBpgGIVKGoCXuiCoP64altEJCj3/Ei+kSU5vlZD4= +github.com/googleapis/gax-go/v2 v2.22.0/go.mod h1:irWBbALSr0Sk3qlqb9SyJ1h68WjgeFuiOzI4Rqw5+aY= +github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg= +github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE= +github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= +github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM= +github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y= +github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= +github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64= +go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y= +go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 h1:OyrsyzuttWTSur2qN/Lm0m2a8yqyIjUVBZcxFPuXq2o= +go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0/go.mod h1:C2NGBr+kAB4bk3xtMXfZ94gqFDtg/GkI7e9zqGh5Beg= +go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I= +go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0= +go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM= +go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY= +go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg= +go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg= +go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw= +go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A= +go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A= +go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0= +golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto= +golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio= +golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o= +golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec= +golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs= +golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q= +golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM= +golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= +golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw= +golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= +golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE= +golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4= +gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4= +gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E= +google.golang.org/api v0.286.0 h1:TdTXMvzYKnWV1/lPbCdbXRqBrkDqjPto22H2xeZZ8LI= +google.golang.org/api v0.286.0/go.mod h1:NlOlUIr8MPoIhT9Bb/oUnRuHbJOLwxb6JSYJM8Yz+jQ= +google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7 h1:XzmzkmB14QhVhgnawEVsOn6OFsnpyxNPRY9QV01dNB0= +google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:L43LFes82YgSonw6iTXTxXUX1OlULt4AQtkik4ULL/I= +google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7 h1:41r6JMbpzBMen0R/4TZeeAmGXSJC7DftGINUodzTkPI= +google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:EIQZ5bFCfRQDV4MhRle7+OgjNtZ6P1PiZBgAKuxXu/Y= +google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad h1:45WmJvIV6C2+O/jjLkPUH+F3aOj/1miDoU2DD0+NWbg= +google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8= +google.golang.org/grpc v1.81.1 h1:VnnIIZ88UzOOKLukQi+ImGz8O1Wdp8nAGGnvOfEIWQQ= +google.golang.org/grpc v1.81.1/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I= +google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE= +google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/internal/auth/oauth.go b/internal/auth/oauth.go new file mode 100644 index 0000000..177bbdd --- /dev/null +++ b/internal/auth/oauth.go @@ -0,0 +1,163 @@ +// Package auth handles Google OAuth2 for the CLI using a local loopback server +// to receive the authorization code. +package auth + +import ( + "context" + "crypto/rand" + "encoding/base64" + "errors" + "fmt" + "net" + "net/http" + "os/exec" + "runtime" + "time" + + "golang.org/x/oauth2" + "golang.org/x/oauth2/google" + + "github.com/tetsuo/colabctl/internal/config" +) + +// Scopes required to use the Drive API and the Colab runtime API. +// The colaboratory scope is mandatory; without it the /tun/m/assign +// endpoint returns 403 SCOPE_NOT_PERMITTED. +var scopes = []string{ + "openid", + "https://www.googleapis.com/auth/userinfo.profile", + "https://www.googleapis.com/auth/userinfo.email", + "https://www.googleapis.com/auth/cloud-platform", + "https://www.googleapis.com/auth/colaboratory", + "https://www.googleapis.com/auth/drive", +} + +// oauthConfig builds an oauth2.Config from the supplied client credentials. +func oauthConfig(clientID, clientSecret, redirectURL string) *oauth2.Config { + return &oauth2.Config{ + ClientID: clientID, + ClientSecret: clientSecret, + RedirectURL: redirectURL, + Scopes: scopes, + Endpoint: google.Endpoint, + } +} + +// Login performs an interactive OAuth2 flow. It starts a temporary local HTTP +// server on a free port, opens the browser for the user, waits for the +// authorization code, exchanges it for tokens, and persists them to disk. +func Login(ctx context.Context, clientID, clientSecret string) error { + // Pick a free port on localhost. + listener, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + return fmt.Errorf("start local server: %w", err) + } + port := listener.Addr().(*net.TCPAddr).Port + redirectURL := fmt.Sprintf("http://127.0.0.1:%d/callback", port) + + cfg := oauthConfig(clientID, clientSecret, redirectURL) + + // Generate a random state value to guard against CSRF. + state, err := randomState() + if err != nil { + return err + } + + authURL := cfg.AuthCodeURL(state, oauth2.AccessTypeOffline, oauth2.ApprovalForce) + + codeCh := make(chan string, 1) + errCh := make(chan error, 1) + + mux := http.NewServeMux() + srv := &http.Server{Handler: mux} + + mux.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) { + if r.URL.Query().Get("state") != state { + http.Error(w, "state mismatch", http.StatusBadRequest) + errCh <- errors.New("oauth2 state mismatch; possible CSRF") + return + } + code := r.URL.Query().Get("code") + if code == "" { + msg := r.URL.Query().Get("error") + http.Error(w, "authorization denied", http.StatusBadRequest) + errCh <- fmt.Errorf("authorization denied: %s", msg) + return + } + fmt.Fprintln(w, "<html><body><h2>Authentication successful; you can close this tab.</h2></body></html>") + codeCh <- code + }) + + go func() { + if err := srv.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) { + errCh <- err + } + }() + + fmt.Printf("Opening browser for authentication.\nIf the browser does not open, visit:\n\n %s\n\n", authURL) + openBrowser(authURL) + + var code string + select { + case code = <-codeCh: + case err = <-errCh: + _ = srv.Shutdown(context.Background()) + return err + case <-time.After(5 * time.Minute): + _ = srv.Shutdown(context.Background()) + return errors.New("timed out waiting for authorization") + } + _ = srv.Shutdown(context.Background()) + + tok, err := cfg.Exchange(ctx, code) + if err != nil { + return fmt.Errorf("exchange code: %w", err) + } + return config.SaveToken(tok) +} + +// TokenSource loads the stored token and wraps it in an auto-refreshing +// TokenSource. Returns an error if no token has been saved (i.e. the user has +// not yet run auth login). +func TokenSource(ctx context.Context, clientID, clientSecret string) (oauth2.TokenSource, error) { + tok, err := config.LoadToken() + if err != nil { + return nil, fmt.Errorf("not authenticated; run \"colabctl auth login\" first: %w", err) + } + cfg := oauthConfig(clientID, clientSecret, "") + return cfg.TokenSource(ctx, tok), nil +} + +// Client returns an *http.Client backed by the stored token. +func Client(ctx context.Context, clientID, clientSecret string) (*http.Client, error) { + ts, err := TokenSource(ctx, clientID, clientSecret) + if err != nil { + return nil, err + } + return oauth2.NewClient(ctx, ts), nil +} + +func randomState() (string, error) { + b := make([]byte, 16) + if _, err := rand.Read(b); err != nil { + return "", fmt.Errorf("generate state: %w", err) + } + return base64.URLEncoding.EncodeToString(b), nil +} + +func openBrowser(url string) { + var cmd string + var args []string + switch runtime.GOOS { + case "darwin": + cmd = "open" + args = []string{url} + case "windows": + cmd = "rundll32" + args = []string{"url.dll,FileProtocolHandler", url} + default: + cmd = "xdg-open" + args = []string{url} + } + _ = exec.Command(cmd, args...).Start() +} diff --git a/internal/config/config.go b/internal/config/config.go new file mode 100644 index 0000000..a850386 --- /dev/null +++ b/internal/config/config.go @@ -0,0 +1,79 @@ +package config + +import ( + "encoding/json" + "errors" + "os" + "path/filepath" + + "golang.org/x/oauth2" +) + +// Dir returns the directory used to store all persistent state. +func Dir() (string, error) { + home, err := os.UserHomeDir() + if err != nil { + return "", err + } + return filepath.Join(home, ".config", "colab"), nil +} + +// TokenPath returns the path to the stored OAuth2 token file. +func TokenPath() (string, error) { + dir, err := Dir() + if err != nil { + return "", err + } + return filepath.Join(dir, "token.json"), nil +} + +// LoadToken reads the stored token from disk. Returns an error wrapping +// os.ErrNotExist when no token has been saved yet. +func LoadToken() (*oauth2.Token, error) { + path, err := TokenPath() + if err != nil { + return nil, err + } + f, err := os.Open(path) + if err != nil { + return nil, err + } + defer f.Close() + + var tok oauth2.Token + if err := json.NewDecoder(f).Decode(&tok); err != nil { + return nil, err + } + return &tok, nil +} + +// SaveToken writes the token to disk, creating parent directories as needed. +func SaveToken(tok *oauth2.Token) error { + dir, err := Dir() + if err != nil { + return err + } + if err := os.MkdirAll(dir, 0700); err != nil { + return err + } + path := filepath.Join(dir, "token.json") + f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600) + if err != nil { + return err + } + defer f.Close() + return json.NewEncoder(f).Encode(tok) +} + +// DeleteToken removes the stored token, effectively logging out. +func DeleteToken() error { + path, err := TokenPath() + if err != nil { + return err + } + err = os.Remove(path) + if errors.Is(err, os.ErrNotExist) { + return nil + } + return err +} diff --git a/internal/config/sessions.go b/internal/config/sessions.go new file mode 100644 index 0000000..cbc9ffa --- /dev/null +++ b/internal/config/sessions.go @@ -0,0 +1,126 @@ +package config + +import ( + "encoding/json" + "errors" + "os" + "path/filepath" + "time" +) + +// SessionState is the on-disk record for one active Colab runtime. +type SessionState struct { + Endpoint string `json:"endpoint"` + URL string `json:"url"` + Token string `json:"token"` + TokenExpiresAt time.Time `json:"tokenExpiresAt"` + KernelID string `json:"kernelId,omitempty"` +} + +// Valid returns true if the session's proxy token has not yet expired. +func (s *SessionState) Valid() bool { + return s.Token != "" && time.Now().Before(s.TokenExpiresAt) +} + +type sessionFile struct { + Sessions map[string]*SessionState `json:"sessions"` +} + +func sessionsPath() (string, error) { + dir, err := Dir() + if err != nil { + return "", err + } + return filepath.Join(dir, "sessions.json"), nil +} + +func loadSessionFile() (*sessionFile, error) { + path, err := sessionsPath() + if err != nil { + return nil, err + } + f, err := os.Open(path) + if errors.Is(err, os.ErrNotExist) { + return &sessionFile{Sessions: map[string]*SessionState{}}, nil + } + if err != nil { + return nil, err + } + defer f.Close() + + var sf sessionFile + if err := json.NewDecoder(f).Decode(&sf); err != nil { + return &sessionFile{Sessions: map[string]*SessionState{}}, nil + } + if sf.Sessions == nil { + sf.Sessions = map[string]*SessionState{} + } + return &sf, nil +} + +func saveSessionFile(sf *sessionFile) error { + dir, err := Dir() + if err != nil { + return err + } + if err := os.MkdirAll(dir, 0700); err != nil { + return err + } + path, err := sessionsPath() + if err != nil { + return err + } + f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600) + if err != nil { + return err + } + defer f.Close() + return json.NewEncoder(f).Encode(sf) +} + +// SaveSession persists a session under the given endpoint key. +func SaveSession(s *SessionState) error { + sf, err := loadSessionFile() + if err != nil { + return err + } + sf.Sessions[s.Endpoint] = s + return saveSessionFile(sf) +} + +// LoadSession returns the saved session for the given endpoint, or nil if not +// found or the token has expired. +func LoadSession(endpoint string) (*SessionState, error) { + sf, err := loadSessionFile() + if err != nil { + return nil, err + } + s, ok := sf.Sessions[endpoint] + if !ok { + return nil, nil + } + return s, nil +} + +// ListSessions returns all saved sessions regardless of token validity. +func ListSessions() ([]*SessionState, error) { + sf, err := loadSessionFile() + if err != nil { + return nil, err + } + out := make([]*SessionState, 0, len(sf.Sessions)) + for _, s := range sf.Sessions { + out = append(out, s) + } + return out, nil +} + +// DeleteSession removes a saved session by endpoint. +func DeleteSession(endpoint string) error { + sf, err := loadSessionFile() + if err != nil { + return err + } + delete(sf.Sessions, endpoint) + return saveSessionFile(sf) +} diff --git a/internal/drive/drive.go b/internal/drive/drive.go new file mode 100644 index 0000000..677880b --- /dev/null +++ b/internal/drive/drive.go @@ -0,0 +1,116 @@ +// Package drive provides a thin wrapper around the Google Drive API v3 for +// operations relevant to Colab notebooks. +package drive + +import ( + "context" + "fmt" + "net/http" + + gdrive "google.golang.org/api/drive/v3" + "google.golang.org/api/googleapi" + "google.golang.org/api/option" +) + +const colabMIMEType = "application/vnd.google.colaboratory" + +// Notebook is a minimal representation of a Colab notebook file in Drive. +type Notebook struct { + ID string + Name string + Modified string // RFC 3339 string + URL string +} + +// Client wraps the Drive API service. +type Client struct { + svc *gdrive.Service +} + +// New creates a Drive client using the provided authenticated HTTP client. +func New(ctx context.Context, httpClient *http.Client) (*Client, error) { + svc, err := gdrive.NewService(ctx, option.WithHTTPClient(httpClient)) + if err != nil { + return nil, fmt.Errorf("create drive service: %w", err) + } + return &Client{svc: svc}, nil +} + +// ListNotebooks returns all Colab notebooks (.ipynb files with the Colab MIME +// type) that are owned by or shared with the authenticated user. +func (c *Client) ListNotebooks(ctx context.Context) ([]*Notebook, error) { + var notebooks []*Notebook + pageToken := "" + fields := googleapi.Field("nextPageToken, files(id, name, modifiedTime, webViewLink)") + query := fmt.Sprintf("mimeType='%s' and trashed=false", colabMIMEType) + + for { + call := c.svc.Files.List(). + Q(query). + Fields(fields). + OrderBy("modifiedTime desc"). + PageSize(100). + Context(ctx) + if pageToken != "" { + call = call.PageToken(pageToken) + } + + resp, err := call.Do() + if err != nil { + return nil, fmt.Errorf("list drive files: %w", err) + } + for _, f := range resp.Files { + notebooks = append(notebooks, &Notebook{ + ID: f.Id, + Name: f.Name, + Modified: f.ModifiedTime, + URL: f.WebViewLink, + }) + } + if resp.NextPageToken == "" { + break + } + pageToken = resp.NextPageToken + } + return notebooks, nil +} + +// GetNotebook fetches the raw JSON bytes of a notebook from Drive by its file +// ID. The content is the raw .ipynb JSON. +func (c *Client) GetNotebook(ctx context.Context, fileID string) ([]byte, error) { + resp, err := c.svc.Files.Export(fileID, "application/json").Context(ctx).Download() + if err != nil { + // Colab files are not Google Docs, so Export will not work. + // Use the plain media download instead. + resp2, err2 := c.svc.Files.Get(fileID).Context(ctx).Download() + if err2 != nil { + return nil, fmt.Errorf("download notebook (file %s): %w", fileID, err) + } + defer resp2.Body.Close() + buf := make([]byte, 0, 512*1024) + tmp := make([]byte, 32*1024) + for { + n, readErr := resp2.Body.Read(tmp) + if n > 0 { + buf = append(buf, tmp[:n]...) + } + if readErr != nil { + break + } + } + return buf, nil + } + defer resp.Body.Close() + buf := make([]byte, 0, 512*1024) + tmp := make([]byte, 32*1024) + for { + n, readErr := resp.Body.Read(tmp) + if n > 0 { + buf = append(buf, tmp[:n]...) + } + if readErr != nil { + break + } + } + return buf, nil +} diff --git a/internal/notebook/notebook.go b/internal/notebook/notebook.go new file mode 100644 index 0000000..9881154 --- /dev/null +++ b/internal/notebook/notebook.go @@ -0,0 +1,106 @@ +// Package notebook parses and represents Jupyter/Colab .ipynb files. +package notebook + +import ( + "encoding/json" + "fmt" +) + +// Cell types used in notebooks. +const ( + CellTypeCode = "code" + CellTypeMarkdown = "markdown" + CellTypeRaw = "raw" +) + +// Source is a notebook cell's source, which can be stored as a single string +// or a list of strings (lines) in the JSON format. +type Source []string + +func (s *Source) UnmarshalJSON(data []byte) error { + // Try string first. + var str string + if err := json.Unmarshal(data, &str); err == nil { + *s = Source{str} + return nil + } + // Fall back to slice. + var lines []string + if err := json.Unmarshal(data, &lines); err != nil { + return err + } + *s = Source(lines) + return nil +} + +// String joins all source lines into one string. +func (s Source) String() string { + out := "" + for _, l := range s { + out += l + } + return out +} + +// Output represents one output entry produced by a cell execution. +type Output struct { + OutputType string `json:"output_type"` + Text Source `json:"text"` + Data json.RawMessage `json:"data"` + EValue Source `json:"evalue"` + Traceback []string `json:"traceback"` +} + +// Cell is a single cell in the notebook. +type Cell struct { + CellType string `json:"cell_type"` + ID string `json:"id"` + Source Source `json:"source"` + Outputs []Output `json:"outputs"` + Metadata struct { + ExecutionCount *int `json:"execution_count"` + } `json:"metadata"` +} + +// Notebook is the top-level structure of a .ipynb file. +type Notebook struct { + NBFormat int `json:"nbformat"` + NBFormatMinor int `json:"nbformat_minor"` + Metadata struct { + KernelInfo struct { + Name string `json:"name"` + } `json:"kernelspec"` + LanguageInfo struct { + Name string `json:"name"` + } `json:"language_info"` + CoLab struct { + Name string `json:"name"` + } `json:"colab"` + } `json:"metadata"` + Cells []*Cell `json:"cells"` +} + +// Parse decodes a .ipynb JSON payload into a Notebook. +func Parse(data []byte) (*Notebook, error) { + var nb Notebook + if err := json.Unmarshal(data, &nb); err != nil { + return nil, fmt.Errorf("parse notebook: %w", err) + } + return &nb, nil +} + +// CodeCells returns only the code cells in order. +func (nb *Notebook) CodeCells() []*Cell { + var out []*Cell + for _, c := range nb.Cells { + if c.CellType == CellTypeCode { + out = append(out, c) + } + } + return out +} + +// Title returns the notebook name from metadata if available. +func (nb *Notebook) Title() string { + return nb.Metadata.CoLab.Name +} @@ -0,0 +1,58 @@ +package main + +import ( + "fmt" + "os" + "text/tabwriter" + "time" + + "github.com/spf13/cobra" + + "github.com/tetsuo/colabctl/internal/auth" + "github.com/tetsuo/colabctl/internal/drive" +) + +var listCmd = &cobra.Command{ + Use: "list", + Aliases: []string{"ls"}, + Short: "List Colab notebooks from Google Drive", + RunE: func(cmd *cobra.Command, _ []string) error { + requireCredentials() + + httpClient, err := auth.Client(cmd.Context(), clientID, clientSecret) + if err != nil { + return err + } + + driveClient, err := drive.New(cmd.Context(), httpClient) + if err != nil { + return err + } + + notebooks, err := driveClient.ListNotebooks(cmd.Context()) + if err != nil { + return err + } + + if len(notebooks) == 0 { + fmt.Println("No Colab notebooks found in your Drive.") + return nil + } + + w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0) + fmt.Fprintln(w, "ID\tNAME\tMODIFIED") + fmt.Fprintln(w, "--\t----\t--------") + for _, nb := range notebooks { + modified := nb.Modified + if t, err := time.Parse(time.RFC3339, nb.Modified); err == nil { + modified = t.Format("2006-01-02 15:04") + } + fmt.Fprintf(w, "%s\t%s\t%s\n", nb.ID, nb.Name, modified) + } + return w.Flush() + }, +} + +func init() { + rootCmd.AddCommand(listCmd) +} @@ -0,0 +1,51 @@ +package main + +import ( + "fmt" + "os" + + "github.com/spf13/cobra" +) + +var ( + clientID = "" + clientSecret = "" +) + +var rootCmd = &cobra.Command{ + Use: "colabctl", +} + +func main() { + if err := rootCmd.Execute(); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +func init() { + // Allow credentials to be provided via environment variables as a + // convenient alternative to build-time injection. + if id := os.Getenv("COLAB_CLIENT_ID"); id != "" { + clientID = id + } + if secret := os.Getenv("COLAB_CLIENT_SECRET"); secret != "" { + clientSecret = secret + } +} + +// requireCredentials prints a helpful error and exits if the OAuth2 client +// credentials have not been configured. +func requireCredentials() { + if clientID == "" || clientSecret == "" { + fmt.Fprintln(os.Stderr, `Error: OAuth2 credentials not set. + +Set COLAB_CLIENT_ID and COLAB_CLIENT_SECRET environment variables, or run: + + colabctl auth login --client-id <id> --client-secret <secret> + +To create credentials, visit: + https://console.cloud.google.com/apis/credentials`) + os.Exit(1) + } +} diff --git a/output.go b/output.go new file mode 100644 index 0000000..1fb405f --- /dev/null +++ b/output.go @@ -0,0 +1,118 @@ +package main + +import ( + "crypto/rand" + "encoding/hex" + "fmt" + "os" + "path/filepath" + "strings" + + "github.com/tetsuo/colabctl/internal/colab" +) + +// mimeExtensions maps MIME types to file extensions for binary outputs. +var mimeExtensions = map[string]string{ + "image/png": ".png", + "image/jpeg": ".jpg", + "image/gif": ".gif", + "image/svg+xml": ".svg", + "audio/wav": ".wav", + "audio/mpeg": ".mp3", + "audio/mp3": ".mp3", + "audio/ogg": ".ogg", + "video/mp4": ".mp4", + "video/webm": ".webm", +} + +// mimeOrder controls which MIME type is saved when a message carries several +// (prefer the highest-quality representation). +var mimeOrder = []string{ + "image/png", "image/jpeg", "image/gif", "image/svg+xml", + "audio/wav", "audio/mpeg", "audio/mp3", "audio/ogg", + "video/mp4", "video/webm", +} + +// printOutputs drains the channel of kernel outputs and writes them to the +// terminal. stdout/result go to os.Stdout; errors/stderr go to os.Stderr. +// Binary outputs (images, audio, video) are saved to files. They go in +// outputDir when it is set, otherwise the current directory. The function +// blocks until the channel is closed. +func printOutputs(ch <-chan colab.KernelOutput, outputDir string) { + fileCount := 0 + for out := range ch { + // One displayed object can arrive in several encodings (a figure as + // both PNG and JPEG, for example). Save only the highest-priority one + // so each object yields a single file. + for _, mime := range mimeOrder { + data, ok := out.BinaryData[mime] + if !ok { + continue + } + ext := mimeExtensions[mime] + fileCount++ + // Prefer a name the cell supplied via display metadata; otherwise + // fall back to a numbered default. + name := fmt.Sprintf("colab-output-%d%s", fileCount, ext) + if out.Filename != "" { + name = out.Filename + } + if outputDir != "" { + if err := os.MkdirAll(outputDir, 0o755); err != nil { + fmt.Fprintf(os.Stderr, "error creating %s: %v\n", outputDir, err) + } + name = filepath.Join(outputDir, name) + } + if err := os.WriteFile(name, data, 0o644); err != nil { + fmt.Fprintf(os.Stderr, "error saving %s: %v\n", mime, err) + } else { + fmt.Fprintf(os.Stderr, "Saved: %s\n", name) + } + break + } + + switch out.Kind { + case colab.OutputStdout, colab.OutputResult: + fmt.Print(out.Text) + if len(out.Text) > 0 && out.Text[len(out.Text)-1] != '\n' { + fmt.Println() + } + case colab.OutputDisplay: + // Only print the text repr when there was no binary output saved. + if len(out.BinaryData) == 0 && out.Text != "" { + fmt.Print(out.Text) + if out.Text[len(out.Text)-1] != '\n' { + fmt.Println() + } + } + case colab.OutputStderr: + fmt.Fprint(os.Stderr, out.Text) + if len(out.Text) > 0 && out.Text[len(out.Text)-1] != '\n' { + fmt.Fprintln(os.Stderr) + } + case colab.OutputError: + fmt.Fprintln(os.Stderr, out.Text) + case colab.OutputStatus: + // busy/idle - not printed to the user. + case colab.OutputInputReq: + fmt.Printf("Input requested: %s", out.Text) + } + } +} + +// notebookHash returns a fresh random notebook hash in the web-safe encoding +// that the Colab assign endpoint expects as the nbh query parameter. +// +// Format: UUID-like hex string with dashes replaced by underscores, padded +// with dots to 44 characters (mirrors uuid_to_web_safe_base64 in colab-cli). +func notebookHash() string { + b := make([]byte, 16) + _, _ = rand.Read(b) + // Format as UUID groups: 8-4-4-4-12 + h := hex.EncodeToString(b) + uuid := h[0:8] + "-" + h[8:12] + "-" + h[12:16] + "-" + h[16:20] + "-" + h[20:32] + // Replace dashes with underscores and pad to 44 chars with dots. + encoded := strings.ReplaceAll(uuid, "-", "_") + encoded += strings.Repeat(".", 44-len(uuid)) + return encoded +} @@ -0,0 +1,102 @@ +package main + +import ( + "fmt" + "os" + + "github.com/spf13/cobra" + + "github.com/tetsuo/colabctl/internal/auth" + "github.com/tetsuo/colabctl/internal/colab" + "github.com/tetsuo/colabctl/internal/drive" + "github.com/tetsuo/colabctl/internal/notebook" +) + +var runCmd = &cobra.Command{ + Use: "run <file-id>", + Short: "Execute all code cells in a Colab notebook", + Long: `Starts a new Colab runtime for the given notebook (identified by its +Drive file ID) and runs every code cell in order, printing the output. + +Get the file ID from: + + colabctl list`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + requireCredentials() + + fileID := args[0] + ctx := cmd.Context() + + httpClient, err := auth.Client(ctx, clientID, clientSecret) + if err != nil { + return err + } + + // Download the notebook so we can iterate its cells. + fmt.Fprintf(os.Stderr, "Fetching notebook %s …\n", fileID) + driveClient, err := drive.New(ctx, httpClient) + if err != nil { + return err + } + + raw, err := driveClient.GetNotebook(ctx, fileID) + if err != nil { + return err + } + + nb, err := notebook.Parse(raw) + if err != nil { + return err + } + + codeCells := nb.CodeCells() + if len(codeCells) == 0 { + fmt.Println("No code cells found in the notebook.") + return nil + } + + accelerator, _ := cmd.Flags().GetString("accelerator") + outputDir, _ := cmd.Flags().GetString("output-dir") + fmt.Fprintf(os.Stderr, "Starting Colab runtime …\n") + colabClient := colab.New(httpClient) + assignment, err := colabClient.Assign(ctx, notebookHash(), "", accelerator) + if err != nil { + return fmt.Errorf("start runtime: %w", err) + } + fmt.Fprintf(os.Stderr, "Runtime assigned (endpoint %s)\n", assignment.Endpoint) + + kernel, err := colab.CreateAndConnectKernel(ctx, assignment) + if err != nil { + return fmt.Errorf("connect to kernel: %w", err) + } + defer kernel.Close() + + for i, cell := range codeCells { + code := cell.Source.String() + if code == "" { + continue + } + + fmt.Printf("\n─── Cell %d ───────────────────────────────────\n", i+1) + fmt.Println(code) + fmt.Println("──────────────────────────────────────────────") + + outCh, err := kernel.Execute(ctx, code) + if err != nil { + return fmt.Errorf("execute cell %d: %w", i+1, err) + } + + printOutputs(outCh, outputDir) + } + + fmt.Fprintln(os.Stderr, "\nAll cells executed.") + return nil + }, +} + +func init() { + runCmd.Flags().StringP("accelerator", "a", "", "Accelerator for the runtime: T4, A100, TPU, L4, A100-80GB (default: CPU)") + runCmd.Flags().StringP("output-dir", "o", "", "Directory to save binary outputs (images, audio, video) into (default: current directory)") + rootCmd.AddCommand(runCmd) +} diff --git a/sessions.go b/sessions.go new file mode 100644 index 0000000..c3f0bf1 --- /dev/null +++ b/sessions.go @@ -0,0 +1,85 @@ +package main + +import ( + "fmt" + "os" + "text/tabwriter" + + "github.com/spf13/cobra" + + "github.com/tetsuo/colabctl/internal/auth" + "github.com/tetsuo/colabctl/internal/colab" + "github.com/tetsuo/colabctl/internal/config" +) + +var sessionsCmd = &cobra.Command{ + Use: "sessions", + Aliases: []string{"ps"}, + Short: "List active Colab runtimes on your account", + RunE: func(cmd *cobra.Command, _ []string) error { + requireCredentials() + + httpClient, err := auth.Client(cmd.Context(), clientID, clientSecret) + if err != nil { + return err + } + client := colab.New(httpClient) + + runtimes, err := client.ListAssignments(cmd.Context()) + if err != nil { + return err + } + + if len(runtimes) == 0 { + fmt.Println("No active runtimes.") + return nil + } + + w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0) + fmt.Fprintln(w, "ENDPOINT\tACCELERATOR\tURL") + fmt.Fprintln(w, "--------\t-----------\t---") + for _, r := range runtimes { + accel := r.Accelerator + if accel == "" { + accel = "CPU" + } + fmt.Fprintf(w, "%s\t%s\t%s\n", r.Endpoint, accel, r.URL) + } + return w.Flush() + }, +} + +var stopCmd = &cobra.Command{ + Use: "stop <endpoint>", + Short: "Stop and release an active Colab runtime", + Long: `Terminates the runtime identified by its endpoint ID. +Get the endpoint from: + + colabctl sessions`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + requireCredentials() + + endpoint := args[0] + ctx := cmd.Context() + + httpClient, err := auth.Client(ctx, clientID, clientSecret) + if err != nil { + return err + } + client := colab.New(httpClient) + + fmt.Fprintf(os.Stderr, "Stopping runtime %s …\n", endpoint) + if err := client.Unassign(ctx, endpoint); err != nil { + return fmt.Errorf("stop runtime: %w", err) + } + _ = config.DeleteSession(endpoint) + fmt.Println("Runtime stopped.") + return nil + }, +} + +func init() { + rootCmd.AddCommand(sessionsCmd) + rootCmd.AddCommand(stopCmd) +} |
