feat(cli): improve agent ergonomics

Author: salmonumbrella

internal/cmd/agent.go

@@ -0,0 +1,6 @@
+package cmd
+
+// AgentCmd contains helper commands intended to make gog easier to consume from LLM agents.
+type AgentCmd struct {
+	ExitCodes AgentExitCodesCmd `cmd:"" name:"exit-codes" aliases:"exitcodes,exit-code" help:"Print stable exit codes for automation"`
+}

internal/cmd/agent_cmd_test.go

@@ -0,0 +1,32 @@
+package cmd
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/steipete/gogcli/internal/outfmt"
+)
+
+func TestAgentExitCodes_JSON(t *testing.T) {
+	ctx := outfmt.WithMode(context.Background(), outfmt.Mode{JSON: true})
+
+	out := captureStdout(t, func() {
+		if err := (&AgentExitCodesCmd{}).Run(ctx); err != nil {
+			t.Fatalf("Run: %v", err)
+		}
+	})
+
+	var doc struct {
+		ExitCodes map[string]int `json:"exit_codes"`
+	}
+	if err := json.Unmarshal([]byte(out), &doc); err != nil {
+		t.Fatalf("unmarshal: %v (out=%q)", err, out)
+	}
+	if doc.ExitCodes["empty_results"] != emptyResultsExitCode {
+		t.Fatalf("expected empty_results=%d, got %d", emptyResultsExitCode, doc.ExitCodes["empty_results"])
+	}
+	if doc.ExitCodes["auth_required"] != exitCodeAuthRequired {
+		t.Fatalf("expected auth_required=%d, got %d", exitCodeAuthRequired, doc.ExitCodes["auth_required"])
+	}
+}

internal/cmd/agent_desire_paths_test.go

@@ -0,0 +1,91 @@
+package cmd
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestRootDesirePaths_HelpParses(t *testing.T) {
+	tests := [][]string{
+		{"send", "--help"},
+		{"ls", "--help"},
+		{"search", "--help"},
+		{"download", "--help"},
+		{"upload", "--help"},
+		{"open", "--help"},
+		{"login", "--help"},
+		{"logout", "--help"},
+		{"status", "--help"},
+		{"me", "--help"},
+		{"whoami", "--help"},
+		{"exit-codes", "--help"},
+		{"agent", "--help"},
+	}
+
+	for _, args := range tests {
+		args := args
+		t.Run(strings.Join(args, " "), func(t *testing.T) {
+			_ = captureStdout(t, func() {
+				_ = captureStderr(t, func() {
+					if err := Execute(args); err != nil {
+						t.Fatalf("Execute(%v): %v", args, err)
+					}
+				})
+			})
+		})
+	}
+}
+
+func TestDesirePaths_GlobalFlagAliases(t *testing.T) {
+	out := captureStdout(t, func() {
+		_ = captureStderr(t, func() {
+			if err := Execute([]string{"--machine", "version"}); err != nil {
+				t.Fatalf("Execute: %v", err)
+			}
+		})
+	})
+	if !strings.HasPrefix(strings.TrimSpace(out), "{") {
+		t.Fatalf("expected json output with --machine, got: %q", out)
+	}
+
+	out = captureStdout(t, func() {
+		_ = captureStderr(t, func() {
+			if err := Execute([]string{"--tsv", "version"}); err != nil {
+				t.Fatalf("Execute: %v", err)
+			}
+		})
+	})
+	if strings.HasPrefix(strings.TrimSpace(out), "{") {
+		t.Fatalf("expected text output with --tsv, got: %q", out)
+	}
+}
+
+func TestDesirePaths_DryRunAlias_ExitsBeforeAuth(t *testing.T) {
+	out := captureStdout(t, func() {
+		_ = captureStderr(t, func() {
+			if err := Execute([]string{
+				"--json",
+				"--dryrun",
+				"send",
+				"--to", "to@example.com",
+				"--subject", "Hello",
+				"--body", "Test",
+			}); err != nil {
+				t.Fatalf("Execute: %v", err)
+			}
+		})
+	})
+	if !strings.Contains(out, "\"dry_run\": true") {
+		t.Fatalf("expected dry-run json output, got: %q", out)
+	}
+}
+
+func TestDesirePaths_CursorAlias_Parses(t *testing.T) {
+	parser, _, err := newParser("test parser")
+	if err != nil {
+		t.Fatalf("newParser: %v", err)
+	}
+	if _, err := parser.Parse([]string{"drive", "ls", "--cursor", "tok"}); err != nil {
+		t.Fatalf("Parse: %v", err)
+	}
+}

internal/cmd/agent_exit_codes.go

@@ -0,0 +1,61 @@
+package cmd
+
+import (
+	"context"
+	"os"
+	"sort"
+	"strconv"
+
+	"github.com/steipete/gogcli/internal/outfmt"
+)
+
+type AgentExitCodesCmd struct{}
+
+func (c *AgentExitCodesCmd) Run(ctx context.Context) error {
+	// Always emit untransformed JSON, even if the caller enabled global JSON transforms.
+	ctx = outfmt.WithJSONTransform(ctx, outfmt.JSONTransform{})
+
+	codes := map[string]int{
+		"ok":                0,
+		"error":             1,
+		"usage":             2,
+		"empty_results":     emptyResultsExitCode,
+		"auth_required":     exitCodeAuthRequired,
+		"not_found":         exitCodeNotFound,
+		"permission_denied": exitCodePermissionDenied,
+		"rate_limited":      exitCodeRateLimited,
+		"retryable":         exitCodeRetryable,
+		"config":            exitCodeConfig,
+		"cancelled":         exitCodeCancelled,
+	}
+
+	if outfmt.IsJSON(ctx) {
+		return outfmt.WriteJSON(ctx, os.Stdout, map[string]any{"exit_codes": codes})
+	}
+
+	// Plain output is TSV so it's easily machine-parsed.
+	if outfmt.IsPlain(ctx) {
+		keys := make([]string, 0, len(codes))
+		for k := range codes {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+
+		for _, k := range keys {
+			_, _ = os.Stdout.WriteString(k + "\t" + strconv.Itoa(codes[k]) + "\n")
+		}
+
+		return nil
+	}
+
+	// Human output.
+	keys := make([]string, 0, len(codes))
+	for k := range codes {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	for _, k := range keys {
+		_, _ = os.Stdout.WriteString(k + ": " + strconv.Itoa(codes[k]) + "\n")
+	}
+	return nil
+}