openAgent

1// Help-text snapshots for every CLI command + key subcommand. Catches
2// accidental flag removals, renames, and reordering in a single sweep —
3// any change to the user-visible CLI surface shows up here as a diff.
4//
5// This is the broad coverage layer that makes the future Effect CLI
6// migration (yargs → effect-smol/cli) safe to attempt: if a refactor
7// preserves the surface, the snapshots stay green; if it doesn't, the
8// diff tells you exactly which command(s) changed.
9//
10// Snapshots are taken at COLUMNS=120 so wrapping is stable across
11// terminal sizes. The default opencode tui command is excluded —
12// `opencode --help` includes an ASCII banner that pulls in the install
13// version (changes per release), so we'd snapshot a moving target.
14import { describe, expect } from "bun:test"
15import { Effect } from "effect"
16import { cliIt } from "../../lib/cli-process"
17import { normalizeForSnapshot, PATH_SEP } from "../../lib/snapshot"
18 
19// Composes `normalizeForSnapshot` (CRLF + tmpdir) with two help-specific
20// rules:
21//
22//   1. The harness's `oc-cli-XXX` subdir under TMPDIR collapses to `<HOME>`.
23//      `PATH_SEP` matches `/` and `\\` so the rule works on POSIX + Windows.
24//
25//   2. yargs wraps the `[string] [default: "..."]` clause based on the
26//      pre-normalized default's character length, so different random home
27//      path widths produce different leading-whitespace counts (or even
28//      line-wraps onto a fresh line on Windows). `\s+` matches both forms.
29function normalize(text: string): string {
30  return normalizeForSnapshot(text, {
31    pathReplacements: [
32      // Mixed-case [A-Za-z0-9] because node's mkdtemp suffix is mixed-case
33      // (the harness now uses FileSystem.makeTempDirectoryScoped under the
34      // hood). A `[a-z0-9]+` regex would leave uppercase chars trailing.
35      [new RegExp(`<TMPDIR>${PATH_SEP}oc-cli-[A-Za-z0-9]+`, "g"), "<HOME>"],
36      [/\s+\[string\] \[default: "<HOME>"\]/g, ' [string] [default: "<HOME>"]'],
37    ],
38  })
39}
40 
41// Top-level commands. Order matches what `opencode --help` prints today;
42// keep it in that order so the snapshot file reads as a table of contents.
43// `completion` is intentionally excluded — it's a yargs built-in that emits
44// top-level help on `--help` and exits 1; not a real opencode command.
45const TOP_LEVEL = [
46  "acp",
47  "mcp",
48  "attach",
49  "run",
50  "debug",
51  "providers", // aliased to `auth`
52  "agent",
53  "upgrade",
54  "uninstall",
55  "serve",
56  "web",
57  "models",
58  "stats",
59  "export",
60  "import",
61  "github",
62  "pr",
63  "session",
64  "plugin",
65  "db",
66] as const
67 
68// Subcommands worth pinning. Not exhaustive — the goal is one snapshot per
69// distinct argv shape, not every leaf. Add new entries when a subcommand
70// gains user-visible flags that we want to lock in.
71const SUBCOMMANDS = [
72  ["mcp", "list"],
73  ["mcp", "add"],
74  ["mcp", "auth"],
75  ["mcp", "logout"],
76  ["providers", "list"],
77  ["providers", "login"],
78  ["providers", "logout"],
79  ["agent", "create"],
80  ["agent", "list"],
81  ["session", "list"],
82  ["session", "delete"],
83  ["github", "install"],
84  ["github", "run"],
85  ["db", "path"],
86] as const
87 
88// Fixed wrap width so a developer's terminal doesn't affect snapshots.
89// yargs honors COLUMNS; CI runners typically default to 80 which produces
90// different wraps from a 200-col local terminal.
91const SNAPSHOT_ENV = { COLUMNS: "120" }
92 
93describe("opencode CLI help-text snapshots", () => {
94  // Single test, parallel spawns. Each command's help fires under
95  // `concurrency: 8` — wall-clock stays under ~10s even for ~35 commands,
96  // versus ~1 minute if we serialized.
97  cliIt.live(
98    "every documented command emits stable help text",
99    ({ opencode }) =>
100      Effect.gen(function* () {
101        const topLevel = yield* opencode.spawn(["--help"], { env: SNAPSHOT_ENV })
102        expect(topLevel.exitCode).toBe(0)
103        expect(topLevel.stderr.endsWith("\n")).toBe(true)
104        expect(topLevel.stderr).toContain("--mini")
105        expect(topLevel.stderr).not.toContain("--thinking")
106        expect(topLevel.stderr).not.toContain("--variant")
107        expect(topLevel.stderr).not.toContain("--demo")
108 
109        const argvs: Array<readonly string[]> = [...TOP_LEVEL.map((c) => [c] as const), ...SUBCOMMANDS]
110 
111        // Spawn in parallel, then assert in argv order so snapshot output is
112        // deterministic and per-command failures don't abort the rest of
113        // the sweep. `Effect.partition` is the canonical "run all, separate
114        // failures from successes" primitive — no mutable accumulator needed.
115        const [failures, results] = yield* Effect.partition(
116          argvs,
117          (argv) =>
118            Effect.gen(function* () {
119              const result = yield* opencode.spawn([...argv, "--help"], { env: SNAPSHOT_ENV })
120              if (result.exitCode !== 0) {
121                return yield* Effect.fail(`opencode ${argv.join(" ")}: exit ${result.exitCode}`)
122              }
123              return { argv, result }
124            }),
125          { concurrency: 8 },
126        )
127 
128        for (const { argv, result } of results) {
129          // yargs writes --help to stderr, not stdout. Snapshotting stderr
130          // means our test catches the help body; stdout for these commands
131          // is expected to be empty.
132          expect(normalize(result.stderr)).toMatchSnapshot(`opencode ${argv.join(" ")} --help`)
133        }
134        if (failures.length > 0) {
135          throw new Error(`Help text failed for:\n  ${failures.join("\n  ")}`)
136        }
137      }),
138    180_000,
139  )
140})
141