lakebox: add stop command (#5291)

Wires up `databricks lakebox stop <id>` against the existing StopSandbox
proto RPC (POST /api/2.0/lakebox/sandboxes/{id}/stop). Terminates the
backing microVM, preserves the sandbox record and storage. The gateway
auto-starts a stopped sandbox on the next `lakebox ssh`, so a paired
`start` command isn't required today.

Co-authored-by: Isaac

## Changes
<!-- Brief summary of your changes that is easy to understand -->

## Why
<!-- Why are these changes needed? Provide the context that the reviewer
might be missing.
For example, were there any decisions behind the change that are not
reflected in the code itself? -->

## Tests
<!-- How have you tested the changes? -->

<!-- If your PR needs to be included in the release notes for next
release,
add a separate entry in NEXT_CHANGELOG.md as part of your PR. -->

Author: akshaysingla-db

cmd/lakebox/api.go

@@ -288,6 +288,20 @@ func (a *lakeboxAPI) delete(ctx context.Context, id string) error {
 	return a.c.Do(ctx, http.MethodDelete, lakeboxAPIPath+"/"+id, a.headers(), nil, nil, nil)
 }
 
+// stop calls POST /api/2.0/lakebox/sandboxes/{id}/stop and returns the
+// refreshed sandbox. The proto's `StopSandboxRequest` carries `sandbox_id`
+// (redundant with the URL path) under `body: "*"`, so we mirror it
+// explicitly even though the transcoder fills the field from the path.
+func (a *lakeboxAPI) stop(ctx context.Context, id string) (*sandboxEntry, error) {
+	body := map[string]string{"sandbox_id": id}
+	var resp sandboxEntry
+	err := a.c.Do(ctx, http.MethodPost, lakeboxAPIPath+"/"+id+"/stop", a.headers(), nil, body, &resp)
+	if err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}
+
 // registerKey calls POST /api/2.0/lakebox/ssh-keys. An empty `name` is
 // omitted from the wire payload so the server records "unset" rather than
 // an explicit empty string.

cmd/lakebox/lakebox.go

@@ -38,6 +38,7 @@ Common workflows:
 	cmd.AddCommand(newListCommand())
 	cmd.AddCommand(newCreateCommand())
 	cmd.AddCommand(newDeleteCommand())
+	cmd.AddCommand(newStopCommand())
 	cmd.AddCommand(newStatusCommand())
 	cmd.AddCommand(newConfigCommand())
 

cmd/lakebox/stop.go

@@ -0,0 +1,51 @@
+package lakebox
+
+import (
+	"fmt"
+
+	"github.com/databricks/cli/cmd/root"
+	"github.com/databricks/cli/libs/cmdctx"
+	"github.com/databricks/cli/libs/cmdio"
+	"github.com/spf13/cobra"
+)
+
+func newStopCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "stop <lakebox-id>",
+		Short: "Stop a running Lakebox environment",
+		Long: `Stop a running Lakebox environment.
+
+Terminates the backing microVM but preserves the sandbox record and its
+persistent storage. To restart, run 'databricks lakebox ssh' — the
+gateway auto-starts a stopped sandbox on connection.
+
+Stopping an already-stopped sandbox is a no-op.
+
+Example:
+  databricks lakebox stop happy-panda-1234`,
+		Args:    cobra.ExactArgs(1),
+		PreRunE: root.MustWorkspaceClient,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+			w := cmdctx.WorkspaceClient(ctx)
+			api, err := newLakeboxAPI(w)
+			if err != nil {
+				return err
+			}
+
+			lakeboxID := args[0]
+			s := spin(ctx, "Stopping "+lakeboxID+"…")
+			defer s.Close()
+
+			updated, err := api.stop(ctx, lakeboxID)
+			if err != nil {
+				s.fail("Failed to stop " + lakeboxID)
+				return fmt.Errorf("failed to stop lakebox %s: %w", lakeboxID, err)
+			}
+			s.ok("Stopped " + cmdio.Bold(ctx, updated.SandboxID))
+			return nil
+		},
+	}
+
+	return cmd
+}