voyage/examples/01-add-verbose-flag/plan.md

Add --verbose flag to small-auth CLI

plan_version: 1.7

Plan quality: A (92/100) — APPROVE

Generated by trekplan v3.1.0 on 2026-05-01.

Context

The small-auth CLI has six commands and emits only final results; no progress, no internal step trace. Operators debugging slow token-refresh or mis-routed users-list calls have no signal between "started" and "finished". This plan adds a --verbose / -v flag that, when set, emits structured progress lines to stderr without changing stdout. The default path stays byte-identical.

This is a textbook minimal-scope addition: the parser is small, centralized, and already supports global flags.

Architecture Diagram

graph TD
    subgraph "Changes in this plan"
        cli["src/cli.mjs<br/>parse globalFlags"]
        ctx["ctx object<br/>+ verbose: boolean"]
        login["src/commands/login.mjs<br/>+ 3 verbose calls"]
        token["src/commands/token-refresh.mjs<br/>+ 4 verbose calls"]
        userlist["src/commands/users-list.mjs<br/>+ 2 verbose calls"]
        usercreate["src/commands/users-create.mjs<br/>+ 3 verbose calls"]
        logout["src/commands/logout.mjs<br/>+ 2 verbose calls"]
        whoami["src/commands/whoami.mjs<br/>(accepts flag, no traces)"]
        help["src/cli.mjs<br/>--help text"]
        tests["tests/cli-verbose-flag.test.mjs<br/>tests/cli-no-verbose-stability.test.mjs"]

        cli --> ctx
        ctx --> login
        ctx --> token
        ctx --> userlist
        ctx --> usercreate
        ctx --> logout
        ctx --> whoami
        cli --> help
        login --> tests
    end

Codebase Analysis

• Tech stack: Node.js ≥ 18, no external runtime dependencies, node:test for tests
• Key patterns: hand-rolled argv parser, two-pass extract (globals → command), handler contract run(positional, flags, ctx)
• Relevant files: src/cli.mjs, src/commands/{login,logout,whoami,token-refresh,users-list,users-create}.mjs, tests/
• Reusable code: existing [error] stderr pattern at src/cli.mjs:67 — mirror it for [verbose]
• External tech: none
• Recent git activity: parser last changed in commit ab1c2d3 (added --version); pattern still current

Research Sources

Internal research only — see research/01-cli-parser-conventions.md.

Implementation Plan

Each step targets 1–2 files and one focused change. TDD structure: test or stability harness comes before behavior change.

Step 1: Capture golden stdout for stability test

• Files: tests/golden/login.stdout (new file), tests/golden/whoami.stdout (new file), tests/golden/users-list.stdout (new file)
• Changes: Run current CLI for three representative commands, save stdout byte-for-byte. Use node src/cli.mjs login alice > tests/golden/login.stdout and similar.
• Verify: wc -c tests/golden/*.stdout → expected: each file > 0 bytes
• Checkpoint: git commit -m "test(small-auth): capture pre-change golden stdout for verbose-flag stability"
• On failure: revert files; do not proceed. Likely cause: CLI itself broken — investigate before continuing.
• Manifest:

  manifest:
    expected_paths:
      - tests/golden/login.stdout
      - tests/golden/whoami.stdout
      - tests/golden/users-list.stdout
    min_file_count: 3
    commit_message_pattern: "^test\\(small-auth\\): capture"
    bash_syntax_check: []
    forbidden_paths: []
    must_contain: []
  

Step 2: Add stability test (passes today — the canary for step 5 onwards)

• Files: tests/cli-no-verbose-stability.test.mjs (new file)
• Changes: Three subtests, one per golden file. Each runs node src/cli.mjs <cmd> ... and asserts stdout === readFileSync('tests/golden/<cmd>.stdout'). The test should PASS today (no behavior change yet) — it's the canary for step 5 onwards.
• Verify: node --test tests/cli-no-verbose-stability.test.mjs → expected: 3 pass
• Checkpoint: git commit -m "test(small-auth): stdout stability harness for verbose-flag work"
• On failure: escalate — if subtests fail, the goldens are wrong: re-run step 1.
• Manifest:

  manifest:
    expected_paths:
      - tests/cli-no-verbose-stability.test.mjs
    min_file_count: 1
    commit_message_pattern: "^test\\(small-auth\\): stdout stability"
    bash_syntax_check: []
    forbidden_paths: []
    must_contain:
      - path: tests/cli-no-verbose-stability.test.mjs
        pattern: "tests/golden/login\\.stdout"
  

Step 3: Extend parser to recognize --verbose and -v

• Files: src/cli.mjs
• Changes: At src/cli.mjs:34 (alias table) add '-v': '--verbose'. At src/cli.mjs:48 (globalFlags loop) add '--verbose' case that sets globalFlags.verbose = true. Default the field to false. The flag is consumed (removed from argv) like --help and --version.
• Verify: node src/cli.mjs --verbose login alice 2>&1 | head -1 → expected: no parse error
• Checkpoint: git commit -m "feat(cli): recognize --verbose / -v as global flag"
• On failure: revert src/cli.mjs; rerun stability test to confirm clean baseline.
• Manifest:

  manifest:
    expected_paths:
      - src/cli.mjs
    min_file_count: 1
    commit_message_pattern: "^feat\\(cli\\): recognize --verbose"
    bash_syntax_check: []
    forbidden_paths: []
    must_contain:
      - path: src/cli.mjs
        pattern: "globalFlags\\.verbose"
  

Step 4: Pass verbose into handler ctx

• Files: src/cli.mjs
• Changes: At src/cli.mjs:62 (ctx construction) add verbose: globalFlags.verbose to the ctx literal. No handler changes yet.
• Verify: node --test tests/cli-no-verbose-stability.test.mjs → expected: 3 pass (handlers ignore the new field for now)
• Checkpoint: git commit -m "feat(cli): thread verbose into command handler ctx"
• On failure: revert — stability tests fail → ctx mutation broke something. Bisect by reverting and adding back one line at a time.
• Manifest:

  manifest:
    expected_paths:
      - src/cli.mjs
    min_file_count: 1
    commit_message_pattern: "^feat\\(cli\\): thread verbose"
    bash_syntax_check: []
    forbidden_paths: []
    must_contain:
      - path: src/cli.mjs
        pattern: "verbose: globalFlags\\.verbose"
  

Step 5: Wire verbose output in login, token-refresh, users-list, users-create, logout

• Files: src/commands/login.mjs, src/commands/token-refresh.mjs, src/commands/users-list.mjs, src/commands/users-create.mjs, src/commands/logout.mjs, tests/cli-verbose-flag.test.mjs (new file)
• Changes: First the test, tests/cli-verbose-flag.test.mjs: spawn node src/cli.mjs login --verbose alice, capture stderr, assert exit 0, assert stderr contains all three expected verbose lines: "[verbose] parsing argv", "[verbose] credential lookup", "[verbose] issuing session token", in that order. It fails before the wiring below (no verbose lines yet): the test for a behaviour lands in the step that builds it. Then, at each internal step (3 for login, 4 for token-refresh, 2 for users-list, 3 for users-create, 2 for logout — 14 call sites total), add if (ctx.verbose) ctx.stderr.write(\[verbose] \n`);`. Step descriptions per file:
  • login: "parsing argv", "credential lookup", "issuing session token"
  • token-refresh: "parsing argv", "validating refresh token", "rotating session token", "persisting new token"
  • users-list: "parsing argv", "querying user store"
  • users-create: "parsing argv", "validating input", "writing user record"
  • logout: "parsing argv", "invalidating session token"
• Verify: node --test tests/cli-verbose-flag.test.mjs → expected: 1 pass
• Regression: node --test tests/cli-no-verbose-stability.test.mjs → expected: 3 pass (stdout unchanged when flag absent)
• Checkpoint: git commit -m "feat(commands): emit verbose stderr trace for 5 commands"
• On failure: retry — stability tests fail → likely a stray console.log or ctx.stdout.write instead of ctx.stderr.write. Re-grep all five files for stdout mentions added in this step. If the verbose test misses a line, check the [verbose] strings for typos; if its exit code != 0, check that login still works without verbose.
• Manifest:

  manifest:
    expected_paths:
      - src/commands/login.mjs
      - src/commands/token-refresh.mjs
      - src/commands/users-list.mjs
      - src/commands/users-create.mjs
      - src/commands/logout.mjs
      - tests/cli-verbose-flag.test.mjs
    min_file_count: 6
    commit_message_pattern: "^feat\\(commands\\): emit verbose"
    bash_syntax_check: []
    forbidden_paths: []
    must_contain:
      - path: src/commands/login.mjs
        pattern: "ctx\\.verbose"
      - path: src/commands/token-refresh.mjs
        pattern: "ctx\\.verbose"
      - path: tests/cli-verbose-flag.test.mjs
        pattern: "\\[verbose\\] credential lookup"
  

Step 6: Update --help text

• Files: src/cli.mjs
• Changes: At the help-text constant (src/cli.mjs:78), add a line under "Global flags": -v, --verbose emit per-step trace to stderr (single level only).
• Verify: node src/cli.mjs --help | grep -E "verbose" → expected: 1 line containing "emit per-step trace"
• Checkpoint: git commit -m "docs(cli): document --verbose / -v in --help text"
• On failure: revert just the constant; help text isn't load-bearing.
• Manifest:

  manifest:
    expected_paths:
      - src/cli.mjs
    min_file_count: 1
    commit_message_pattern: "^docs\\(cli\\): document --verbose"
    bash_syntax_check: []
    forbidden_paths: []
    must_contain:
      - path: src/cli.mjs
        pattern: "emit per-step trace"
  

Verification

Final acceptance run after step 6:

node --test tests/                                   # all 26 tests pass (24 + 2 new)
node src/cli.mjs login alice > /tmp/out 2>/dev/null
diff /tmp/out tests/golden/login.stdout              # exit 0
node src/cli.mjs login --verbose alice 2>/tmp/err 1>/dev/null
grep -c "\[verbose\]" /tmp/err                       # ≥ 3
node src/cli.mjs --help | grep -c "\-v, --verbose"   # 1

Plan-critic notes

• No deferred decisions: every step names its files, lines, and exact string changes.
• TDD: stability harness (step 2) precedes behavior changes (steps 3-5), and the verbose-content test lands in step 5, with the code it tests.
• Verify commands are runnable, not "test it works".
• Step 5 wires 5 files (and their test) in one commit; this is over the 1–2 file guideline but is justified by symmetry — the change is mechanical and atomic across the five files; splitting would create five tiny commits with no test value between them.

Execution Strategy

Single session, 6 steps, ~15-20 minutes. No parallel decomposition needed.