Kjell Tore Guttormsen 14ecda886c feat(voyage)!: bulk content rewrite ultra -> voyage/trek prose [skip-docs]

Sed-pipeline (16 patterns, longest-match-first) sweeper residuelle ultra*-treff
i prose, command-narrativ, agent-prompts, hook-kommentarer, doc-prosa.

Pipeline-utvidelser fra V4-prompten:
- BSD-syntax [[:<:]]ultra[[:>:]] istedenfor \bultra\b (BSD sed mangler \b)
- 6 compound-patterns for ultraplan/ultraexecute/ultraresearch/ultrabrief/
  ultrareview/ultracontinue uten -local-suffiks
- ultra*-stats glob -> trek*-stats glob
- Linje-eksklusjon redusert til ultra-cc-architect (Q8); session-state-
  eksklusjonen var over-protektiv
- File-eksklusjon utvidet til settings.json, package.json, plugin.json,
  hele .claude/-treet (gitignored + V5-territorium)

Q8-undantak holdt: architecture-discovery.mjs + project-discovery.mjs urort.
Filnavn-konvensjon holdt: .session-state.local.json + *.local.* preservert.

Manuell narrative-fix: tests/lib/agent-frontmatter.test.mjs linje 10
mangled "/ultra*-local" til "/voyage*-local" (ingen slik kommando finnes);
korrigert til "/trek*".

Residualer utenfor scope (V5 handterer): package.json + .claude-plugin/
plugin.json (Step 12-14 versjons-bump). .claude/* er gitignored
spec-historikk med tilsiktet BEFORE/AFTER-narrativ.

Part of voyage-rebrand session 3 (Wave 4 / Step 10).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-05 15:08:20 +02:00

3.3 KiB

Raw Blame History

type	research_version	question	confidence	dimensions	created
trekresearch-brief	1.0	How does small-auth currently parse arguments and where should --verbose hook in?	0.85	4	2026-05-01

CLI parser conventions in small-auth

Executive Summary

small-auth uses a hand-rolled argv parser at src/cli.mjs:12-58 with a two-pass approach: first pass extracts global flags (currently --help, --version), second pass dispatches to command handlers in src/commands/*.mjs. Adding --verbose requires touching only the first-pass extractor and a new verbose parameter in the handler contract — six command handlers each get a one-line update.

The parser does not use commander, yargs, or any external library — this is intentional (zero deps) and consistent with the plugin marketplace's broader convention. We keep that.

stderr is currently unused except for fatal errors. Adding verbose output to stderr does not collide with anything.

Confidence: 0.85. The 0.15 uncertainty is around whether --verbose should propagate into nested helper modules (src/lib/auth-token.mjs calls src/lib/db.mjs); the plan should either pass verbose via a context object or use a module-scoped log function. Both work; the brief doesn't specify, so the planner will choose.

Dimensions

1. Argument-parsing layer

The parser at src/cli.mjs:12-58 returns {globalFlags: {help, version}, command, positional, commandFlags}. We add verbose: boolean to globalFlags. The two-pass design means --verbose works in any position automatically — no extra effort.

-v short form maps to --verbose via the existing alias table at src/cli.mjs:34.

2. Command-handler contract

Each handler in src/commands/*.mjs exports async function run(positional, flags, ctx). Today ctx is {stdout, stderr, env}. We extend ctx with verbose: boolean so handlers can branch on it without re-reading globalFlags.

3. Internal log emission pattern

Existing fatal errors call ctx.stderr.write(\[error] ...\n`). The verbose pattern matches: if (ctx.verbose) ctx.stderr.write(`[verbose] ...\n`). No log helper needed for this iteration — six call sites total. Refactoring into a verbose()` helper is reasonable but not required for the goal.

4. Test infrastructure

Tests live in tests/*.test.mjs using node:test. Existing tests run the CLI as a subprocess via child_process.execFile and assert on exit code + stdout. Two new tests are needed:

tests/cli-verbose-flag.test.mjs — assert login --verbose alice exits 0, stderr contains "[verbose]", stdout matches golden file.
tests/cli-no-verbose-stability.test.mjs — assert login alice stdout is byte-identical to tests/golden/login.stdout.

Citations

src/cli.mjs:12-58 — parser implementation
src/commands/login.mjs:8-42 — typical handler shape
tests/cli-help.test.mjs:14 — subprocess testing pattern
package.json:scripts.test — node --test tests/*.test.mjs

Brief anchoring

Brief task: "Add a --verbose flag to the small-auth CLI parser". This research answers the planner's first question: where to hook into. The parser is small and centralized, so the change is minimal-scope.

The brief's success criteria around byte-identical default stdout maps directly to the stability test in dimension 4.

3.3 KiB Raw Blame History