feat: lifecycle commands, output formatting, and show-commands mode

Add harness status/logs/stop/start commands wrapping openshell sandbox
lifecycle operations. Add Header() and Table() to status module for
structured output. Add --show-commands flag that prints openshell CLI
commands to stdout as a teaching aid, decoupled from execution so it
survives the future gRPC migration.

Author: robbycochran

cmd/helpers_test.go

@@ -54,7 +54,11 @@ func (m *mockGW) ProviderProfileImport(string) error
 func (m *mockGW) ProviderProfileDelete(string) error                              { return nil }
 func (m *mockGW) SettingsSet(string, string) error                                { return nil }
 func (m *mockGW) SandboxList() ([]string, error)                                  { return nil, nil }
+func (m *mockGW) SandboxStatus() ([]gateway.SandboxInfo, error)                   { return nil, nil }
 func (m *mockGW) SandboxConnect(string) error                                     { return nil }
+func (m *mockGW) SandboxLogs(string, bool) error                                 { return nil }
+func (m *mockGW) SandboxStop(string) error                                        { return nil }
+func (m *mockGW) SandboxStart(string) error                                       { return nil }
 func (m *mockGW) GatewayAdd(string, string, bool, bool) error                    { return nil }
 func (m *mockGW) GatewayRemove(name string) error {
 	if m.onGatewayRemove != nil {

cmd/logs.go

@@ -0,0 +1,27 @@
+package cmd
+
+import (
+	"github.com/robbycochran/harness-openshell/internal/gateway"
+	"github.com/spf13/cobra"
+)
+
+func NewLogsCmd(harnessDir, cli string) *cobra.Command {
+	var follow bool
+
+	cmd := &cobra.Command{
+		Use:   "logs [SANDBOX_NAME]",
+		Short: "Stream sandbox logs",
+		Args:  cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			gw := gateway.New(cli)
+			name := ""
+			if len(args) > 0 {
+				name = args[0]
+			}
+			return gw.SandboxLogs(name, follow)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&follow, "follow", "f", false, "Follow log output")
+	return cmd
+}

cmd/start.go

@@ -0,0 +1,29 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/robbycochran/harness-openshell/internal/gateway"
+	"github.com/robbycochran/harness-openshell/internal/status"
+	"github.com/spf13/cobra"
+)
+
+func NewStartCmd(harnessDir, cli string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "start [SANDBOX_NAME]",
+		Short: "Start a stopped sandbox",
+		Args:  cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			gw := gateway.New(cli)
+			name, err := resolveSandboxName(gw, args)
+			if err != nil {
+				return err
+			}
+			if err := gw.SandboxStart(name); err != nil {
+				return fmt.Errorf("starting %s: %w", name, err)
+			}
+			status.OKf("Started %s", name)
+			return nil
+		},
+	}
+}

cmd/start_test.go

@@ -0,0 +1,24 @@
+package cmd
+
+import (
+	"fmt"
+	"testing"
+)
+
+func TestStart_Success(t *testing.T) {
+	gw := &stopStartMockGW{sandboxNames: []string{"agent"}}
+	name, _ := resolveSandboxName(gw, nil)
+	if err := gw.SandboxStart(name); err != nil {
+		t.Fatal(err)
+	}
+	if len(gw.startedNames) != 1 || gw.startedNames[0] != "agent" {
+		t.Errorf("started = %v", gw.startedNames)
+	}
+}
+
+func TestStart_Error(t *testing.T) {
+	gw := &stopStartMockGW{startErr: fmt.Errorf("sandbox not found")}
+	if err := gw.SandboxStart("missing"); err == nil {
+		t.Fatal("expected error")
+	}
+}

cmd/status_cmd.go

@@ -0,0 +1,57 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/robbycochran/harness-openshell/internal/gateway"
+	"github.com/robbycochran/harness-openshell/internal/status"
+	"github.com/spf13/cobra"
+)
+
+func NewStatusCmd(harnessDir, cli string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "status",
+		Short: "Show sandbox and gateway status",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			gw := gateway.New(cli)
+			return runStatus(gw)
+		},
+	}
+}
+
+func runStatus(gw gateway.Gateway) error {
+	status.Header("Gateway")
+	active := gw.ActiveGateway()
+	if active != "" {
+		status.OKf("Active: %s", active)
+		ver := gw.CLIVersion()
+		if ver != "" {
+			status.Infof("CLI: %s", ver)
+		}
+	} else {
+		status.Info("No active gateway")
+	}
+
+	fmt.Println()
+	status.Header("Sandboxes")
+	infos, err := gw.SandboxStatus()
+	if err != nil {
+		if active == "" {
+			status.Info("No active gateway, cannot list sandboxes")
+			return nil
+		}
+		return fmt.Errorf("listing sandboxes: %w", err)
+	}
+	if len(infos) == 0 {
+		status.Info("None running")
+		return nil
+	}
+
+	headers := []string{"NAME", "PHASE"}
+	var rows [][]string
+	for _, info := range infos {
+		rows = append(rows, []string{info.Name, info.Phase})
+	}
+	status.Table(headers, rows)
+	return nil
+}

cmd/status_cmd_test.go

@@ -0,0 +1,52 @@
+package cmd
+
+import (
+	"testing"
+
+	"github.com/robbycochran/harness-openshell/internal/gateway"
+)
+
+type statusMockGW struct {
+	mockGW
+	statusResult []gateway.SandboxInfo
+	statusErr    error
+	activeGW     string
+	cliVer       string
+}
+
+func (m *statusMockGW) SandboxStatus() ([]gateway.SandboxInfo, error) {
+	return m.statusResult, m.statusErr
+}
+func (m *statusMockGW) ActiveGateway() string { return m.activeGW }
+func (m *statusMockGW) CLIVersion() string    { return m.cliVer }
+
+func TestRunStatus_DisplaysSandboxes(t *testing.T) {
+	gw := &statusMockGW{
+		activeGW: "local",
+		cliVer:   "openshell v0.0.58",
+		statusResult: []gateway.SandboxInfo{
+			{Name: "agent", Phase: "Ready"},
+			{Name: "test", Phase: "Stopped"},
+		},
+	}
+	if err := runStatus(gw); err != nil {
+		t.Fatalf("runStatus: %v", err)
+	}
+}
+
+func TestRunStatus_NoSandboxes(t *testing.T) {
+	gw := &statusMockGW{
+		activeGW: "local",
+		cliVer:   "openshell v0.0.58",
+	}
+	if err := runStatus(gw); err != nil {
+		t.Fatalf("runStatus: %v", err)
+	}
+}
+
+func TestRunStatus_NoGateway(t *testing.T) {
+	gw := &statusMockGW{}
+	if err := runStatus(gw); err != nil {
+		t.Fatalf("runStatus: %v", err)
+	}
+}

cmd/stop.go

@@ -0,0 +1,46 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/robbycochran/harness-openshell/internal/gateway"
+	"github.com/robbycochran/harness-openshell/internal/status"
+	"github.com/spf13/cobra"
+)
+
+func NewStopCmd(harnessDir, cli string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "stop [SANDBOX_NAME]",
+		Short: "Stop a running sandbox",
+		Args:  cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			gw := gateway.New(cli)
+			name, err := resolveSandboxName(gw, args)
+			if err != nil {
+				return err
+			}
+			if err := gw.SandboxStop(name); err != nil {
+				return fmt.Errorf("stopping %s: %w", name, err)
+			}
+			status.OKf("Stopped %s", name)
+			return nil
+		},
+	}
+}
+
+func resolveSandboxName(gw gateway.Gateway, args []string) (string, error) {
+	if len(args) > 0 {
+		return args[0], nil
+	}
+	names, err := gw.SandboxList()
+	if err != nil {
+		return "", fmt.Errorf("listing sandboxes: %w", err)
+	}
+	if len(names) == 0 {
+		return "", fmt.Errorf("no sandboxes running")
+	}
+	if len(names) > 1 {
+		return "", fmt.Errorf("multiple sandboxes running, specify one: %v", names)
+	}
+	return names[0], nil
+}

cmd/stop_test.go

@@ -0,0 +1,81 @@
+package cmd
+
+import (
+	"fmt"
+	"testing"
+)
+
+type stopStartMockGW struct {
+	mockGW
+	sandboxNames []string
+	stoppedNames []string
+	startedNames []string
+	stopErr      error
+	startErr     error
+}
+
+func (m *stopStartMockGW) SandboxList() ([]string, error) { return m.sandboxNames, nil }
+func (m *stopStartMockGW) SandboxStop(name string) error {
+	m.stoppedNames = append(m.stoppedNames, name)
+	return m.stopErr
+}
+func (m *stopStartMockGW) SandboxStart(name string) error {
+	m.startedNames = append(m.startedNames, name)
+	return m.startErr
+}
+
+func TestResolveSandboxName_Explicit(t *testing.T) {
+	gw := &stopStartMockGW{}
+	name, err := resolveSandboxName(gw, []string{"my-agent"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if name != "my-agent" {
+		t.Errorf("got %q, want my-agent", name)
+	}
+}
+
+func TestResolveSandboxName_AutoSingle(t *testing.T) {
+	gw := &stopStartMockGW{sandboxNames: []string{"agent"}}
+	name, err := resolveSandboxName(gw, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if name != "agent" {
+		t.Errorf("got %q, want agent", name)
+	}
+}
+
+func TestResolveSandboxName_AmbiguousError(t *testing.T) {
+	gw := &stopStartMockGW{sandboxNames: []string{"a", "b"}}
+	_, err := resolveSandboxName(gw, nil)
+	if err == nil {
+		t.Fatal("expected error for multiple sandboxes")
+	}
+}
+
+func TestResolveSandboxName_NoneError(t *testing.T) {
+	gw := &stopStartMockGW{}
+	_, err := resolveSandboxName(gw, nil)
+	if err == nil {
+		t.Fatal("expected error for no sandboxes")
+	}
+}
+
+func TestStop_Success(t *testing.T) {
+	gw := &stopStartMockGW{sandboxNames: []string{"agent"}}
+	name, _ := resolveSandboxName(gw, nil)
+	if err := gw.SandboxStop(name); err != nil {
+		t.Fatal(err)
+	}
+	if len(gw.stoppedNames) != 1 || gw.stoppedNames[0] != "agent" {
+		t.Errorf("stopped = %v", gw.stoppedNames)
+	}
+}
+
+func TestStop_Error(t *testing.T) {
+	gw := &stopStartMockGW{stopErr: fmt.Errorf("sandbox not found")}
+	if err := gw.SandboxStop("missing"); err == nil {
+		t.Fatal("expected error")
+	}
+}

internal/gateway/cli.go

@@ -226,6 +226,46 @@ func (c *CLI) SandboxCreate(opts SandboxCreateOpts) error {
 	return c.passthrough(args...)
 }
 
+func (c *CLI) SandboxStatus() ([]SandboxInfo, error) {
+	out, err := c.output("sandbox", "list")
+	if err != nil {
+		return nil, err
+	}
+	var infos []SandboxInfo
+	for i, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+		if i == 0 || strings.TrimSpace(line) == "" {
+			continue
+		}
+		cleaned := ansiRE.ReplaceAllString(line, "")
+		fields := strings.Fields(cleaned)
+		if len(fields) >= 2 {
+			infos = append(infos, SandboxInfo{Name: fields[0], Phase: fields[1]})
+		} else if len(fields) == 1 {
+			infos = append(infos, SandboxInfo{Name: fields[0]})
+		}
+	}
+	return infos, nil
+}
+
+func (c *CLI) SandboxLogs(name string, follow bool) error {
+	args := []string{"sandbox", "logs"}
+	if name != "" {
+		args = append(args, name)
+	}
+	if follow {
+		args = append(args, "--follow")
+	}
+	return c.passthrough(args...)
+}
+
+func (c *CLI) SandboxStop(name string) error {
+	return c.silent("sandbox", "stop", name)
+}
+
+func (c *CLI) SandboxStart(name string) error {
+	return c.silent("sandbox", "start", name)
+}
+
 func (c *CLI) SandboxDelete(name string) error {
 	return c.silent("sandbox", "delete", name)
 }