Kjell Tore Guttormsen
c909466c99
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>
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
---
|
|
type: trekresearch-brief
|
|
research_version: 1.0
|
|
question: How does small-auth currently parse arguments and where should --verbose hook in?
|
|
confidence: 0.85
|
|
dimensions: 4
|
|
created: 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.
|