Misc usability improvements for sandbox CLI (#318)

Author: robinaugh

cmd/rwx/sandbox.go

@@ -127,7 +127,33 @@ var sandboxStartCmd = &cobra.Command{
 var sandboxExecCmd = &cobra.Command{
 	Use:   "exec [config-file] -- <command>",
 	Short: "Execute a command in a sandbox",
-	Args:  cobra.ArbitraryArgs,
+	Long: `Execute a command in a persistent cloud sandbox environment.
+
+OVERVIEW
+  Sandboxes are isolated, reproducible environments running in RWX cloud
+  infrastructure. They persist between commands, allowing you to run multiple
+  commands against the same environment without rebuilding each time.
+
+FILE SYNCING
+  Before each command, local uncommitted changes are automatically synced to
+  the sandbox via git patch. This includes staged and unstaged changes, but
+  untracked files are not synced. You need to "git add" untracked files before
+  running the command.
+  Use --no-sync to skip this step if you want to run against the sandbox's
+  original state.
+
+  Note: Git LFS files cannot be synced and will generate a warning.
+
+CONFIG FILE
+  The sandbox configuration (default: .rwx/sandbox.yml) defines:
+    - Base image and dependencies
+    - Git repository to clone
+    - Any setup tasks that run before the sandbox becomes available
+
+  The config must include a task with "run: rwx-sandbox" which defines the
+  sandbox entry point, and must be dependent on a task that uses git/clone.
+`,
+	Args: cobra.ArbitraryArgs,
 	PreRunE: func(cmd *cobra.Command, args []string) error {
 		return requireAccessToken()
 	},

internal/cli/sandbox_storage_test.go

@@ -348,3 +348,30 @@ func TestSandboxStorage_LoadAndSave(t *testing.T) {
 		require.Contains(t, err.Error(), "unable to parse")
 	})
 }
+
+func TestSandboxTitle(t *testing.T) {
+	t.Run("creates title from project name and branch", func(t *testing.T) {
+		title := cli.SandboxTitle("/home/user/my-project", "main", ".rwx/sandbox.yml")
+		require.Equal(t, "Sandbox: my-project (main)", title)
+	})
+
+	t.Run("uses 'detached' when branch is empty", func(t *testing.T) {
+		title := cli.SandboxTitle("/home/user/my-project", "", ".rwx/sandbox.yml")
+		require.Equal(t, "Sandbox: my-project (detached)", title)
+	})
+
+	t.Run("includes non-default config file", func(t *testing.T) {
+		title := cli.SandboxTitle("/home/user/my-project", "feature/test", ".rwx/custom.yml")
+		require.Equal(t, "Sandbox: my-project (feature/test) [.rwx/custom.yml]", title)
+	})
+
+	t.Run("excludes default config file", func(t *testing.T) {
+		title := cli.SandboxTitle("/home/user/my-project", "develop", ".rwx/sandbox.yml")
+		require.Equal(t, "Sandbox: my-project (develop)", title)
+	})
+
+	t.Run("handles empty config file", func(t *testing.T) {
+		title := cli.SandboxTitle("/home/user/my-project", "main", "")
+		require.Equal(t, "Sandbox: my-project (main)", title)
+	})
+}

internal/cli/service_sandbox.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -228,10 +229,14 @@ func (s Service) StartSandbox(cfg StartSandboxConfig) (*StartSandboxResult, erro
 		finishSpinner = SpinUntilDone("Starting sandbox...", s.StdoutIsTTY, s.Stdout)
 	}
 
+	// Construct a descriptive title for the sandbox run
+	title := SandboxTitle(cwd, branch, cfg.ConfigFile)
+
 	runResult, err := s.InitiateRun(InitiateRunConfig{
 		MintFilePath: cfg.ConfigFile,
 		RwxDirectory: cfg.RwxDirectory,
 		Json:         cfg.Json,
+		Title:        title,
 	})
 
 	if err != nil {
@@ -599,14 +604,36 @@ func (s Service) ResetSandbox(cfg ResetSandboxConfig) (*ResetSandboxResult, erro
 // Helper methods
 
 func (s Service) waitForSandboxReady(runID string, jsonMode bool) (*api.SandboxConnectionInfo, error) {
+	// Check once before showing spinner - sandbox may already be ready
+	connInfo, err := s.APIClient.GetSandboxConnectionInfo(runID)
+	if err != nil {
+		return nil, errors.Wrap(err, "unable to get sandbox connection info")
+	}
+
+	if connInfo.Sandboxable {
+		return &connInfo, nil
+	}
+
+	if connInfo.Polling.Completed {
+		return nil, fmt.Errorf("Sandbox run '%s' completed before becoming ready", runID)
+	}
+
+	// Sandbox not ready yet - start spinner and poll
 	var stopSpinner func()
 	if !jsonMode {
 		stopSpinner = Spin("Waiting for sandbox to be ready...", s.StdoutIsTTY, s.Stdout)
 		defer stopSpinner()
 	}
 
 	for {
-		connInfo, err := s.APIClient.GetSandboxConnectionInfo(runID)
+		// Use backoff from server, or default to 2 seconds
+		backoffMs := 2000
+		if connInfo.Polling.BackoffMs != nil {
+			backoffMs = *connInfo.Polling.BackoffMs
+		}
+		time.Sleep(time.Duration(backoffMs) * time.Millisecond)
+
+		connInfo, err = s.APIClient.GetSandboxConnectionInfo(runID)
 		if err != nil {
 			return nil, errors.Wrap(err, "unable to get sandbox connection info")
 		}
@@ -618,13 +645,6 @@ func (s Service) waitForSandboxReady(runID string, jsonMode bool) (*api.SandboxC
 		if connInfo.Polling.Completed {
 			return nil, fmt.Errorf("Sandbox run '%s' completed before becoming ready", runID)
 		}
-
-		// Use backoff from server, or default to 2 seconds
-		backoffMs := 2000
-		if connInfo.Polling.BackoffMs != nil {
-			backoffMs = *connInfo.Polling.BackoffMs
-		}
-		time.Sleep(time.Duration(backoffMs) * time.Millisecond)
 	}
 }
 
@@ -657,6 +677,24 @@ func (s Service) connectSSH(connInfo *api.SandboxConnectionInfo) error {
 	return nil
 }
 
+// SandboxTitle constructs a descriptive title for sandbox runs using the
+// project directory name, branch, and config file (if non-default).
+func SandboxTitle(cwd, branch, configFile string) string {
+	project := filepath.Base(cwd)
+	if branch == "" {
+		branch = "detached"
+	}
+
+	title := fmt.Sprintf("Sandbox: %s (%s)", project, branch)
+
+	// Include config file if it's not the default
+	if configFile != "" && configFile != ".rwx/sandbox.yml" {
+		title = fmt.Sprintf("%s [%s]", title, configFile)
+	}
+
+	return title
+}
+
 func (s Service) syncChangesToSandbox(jsonMode bool) error {
 	patch, lfsFiles, err := s.GitClient.GeneratePatch(nil)
 	if err != nil {