Kjell Tore Guttormsen
182a37c1af
`KNOWN_OPEN` in cli-unknown-flag-rejection.test.mjs named two CLIs as still carrying the argument-swallow defect. That number was the previous session's field of view, not a measurement. Measuring all fourteen found **7** open on the unknown-flag arm and **10** on a second arm the deferral note never described. Arm 1 — unknown flag: with no `else` branch, `--zzz` leaves no trace. exit 0, full payload, a confident answer to a question the caller did not ask. Arm 2 — the sharper one: `a === '--output-file' && args[i + 1]` asks only whether a next token EXISTS, never whether it is a value. `manifest`, `campaign-cli` and `knowledge-refresh-cli` each wrote a file literally named `--json` into the caller's working directory when handed `--output-file --json`, exit 0, with `--json` mode silently dropped. A wrong answer is bad; an unintended file on disk is worse. Two of the CLIs this catches were already in GUARDED and green on arm 1 while arm 2 stood open a few lines away — the guard asserted one relation instead of the invariant. Fixed with a shared gate (`lib/cli-args.mjs`) that runs BEFORE each CLI's own parse loop rather than replacing it: valid argv reaches the existing parser byte-for-byte unchanged, so the byte-stability argument is structural rather than empirical. `drift-cli`, `fix-cli` and `plugin-health-scanner` were already correct on both arms and were moved into GUARDED instead of rewritten. The three CLIs with a bespoke unknown-flag branch had it removed once the gate made it unreachable. Suite 1488 → 1531. Frozen v5.0.0 snapshots untouched; `self-audit --check-readme` passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014P6Rh59Mtj4uYrdYMCYZJE
85 lines
3.3 KiB
JavaScript
85 lines
3.3 KiB
JavaScript
/**
|
|
* Argv precondition shared by the CLIs — the companion to `require-target-dir`.
|
|
*
|
|
* Every CLI here parses argv with a chain of `if (a === '--x') … else if …`.
|
|
* Two things fall through that chain silently:
|
|
*
|
|
* 1. **An unknown flag.** With no `else` branch, `--zzz` leaves no trace: the
|
|
* CLI exits 0 with a full payload — a confident answer to a question the
|
|
* caller did not ask. Measured live (#51): `knowledge-refresh`'s only knob
|
|
* reached the CLI malformed, was ignored, and the command reported "all 14
|
|
* entries re-verified within the last 90 days" about a threshold the user
|
|
* had just overridden.
|
|
*
|
|
* 2. **A value-taking flag whose value is another flag.** The guard
|
|
* `a === '--output-file' && args[i + 1]` asks only whether a next token
|
|
* exists, never whether it is a *value*. Measured live (#57):
|
|
* `manifest --output-file --json` wrote a file literally named `--json`
|
|
* into the caller's working directory, exit 0, with `--json` mode silently
|
|
* dropped. A wrong answer is bad; an unintended file on disk is worse.
|
|
*
|
|
* This runs BEFORE the CLI's own loop and does not replace it. That is
|
|
* deliberate: valid argv reaches the existing parser byte-for-byte unchanged, so
|
|
* no frozen snapshot can move. Malformed argv never reaches it at all.
|
|
*
|
|
* By the exit-code contract, a malformed argument is exit **3** — the scanner
|
|
* did not get to do its job — never 0/1/2, which are verdicts about a
|
|
* configuration that WAS examined.
|
|
*/
|
|
|
|
/**
|
|
* Find the first thing wrong with `args`.
|
|
*
|
|
* @param {string[]} args - argv slice (no node/script entries).
|
|
* @param {{ boolean?: string[], value?: string[] }} spec - the CLI's flag surface.
|
|
* @returns {string|null} diagnostic, or null when argv is well-formed.
|
|
*/
|
|
export function findArgError(args, spec) {
|
|
const booleanFlags = new Set(spec.boolean || []);
|
|
const valueFlags = new Set(spec.value || []);
|
|
|
|
for (let i = 0; i < args.length; i++) {
|
|
const a = args[i];
|
|
|
|
// Positionals and subcommands are the CLI's own business.
|
|
if (!a.startsWith('-')) continue;
|
|
if (booleanFlags.has(a)) continue;
|
|
|
|
if (valueFlags.has(a)) {
|
|
const next = args[i + 1];
|
|
if (next === undefined) {
|
|
return `flag "${a}" needs a value, but nothing followed it`;
|
|
}
|
|
if (next.startsWith('-')) {
|
|
return `flag "${a}" needs a value, but the next argument was another flag: "${next}"`;
|
|
}
|
|
i++; // consume the value so it is never re-examined as a positional
|
|
continue;
|
|
}
|
|
|
|
return `unknown flag "${a}"`;
|
|
}
|
|
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Gate a CLI on well-formed argv. Writes the diagnostic and sets the exit code
|
|
* itself, so callers stay a two-line guard:
|
|
*
|
|
* if (!requireValidArgs(args, ARG_SPEC)) return;
|
|
*
|
|
* Never throws, and never calls `process.exit()` — an abrupt exit discards
|
|
* unflushed stdout when the CLI is on a pipe.
|
|
*
|
|
* @param {string[]} args - argv slice.
|
|
* @param {{ boolean?: string[], value?: string[] }} spec - the CLI's flag surface.
|
|
* @returns {boolean} true when the CLI may proceed.
|
|
*/
|
|
export function requireValidArgs(args, spec) {
|
|
const error = findArgError(args, spec);
|
|
if (error === null) return true;
|
|
process.stderr.write(`Error: ${error}\n`);
|
|
process.exitCode = 3;
|
|
return false;
|
|
}
|