spec-controller 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/cli-args.d.ts

@@ -13,11 +13,9 @@
  * command rather than for the one this code was written beside. `checkUnknownFlags` took the
  * registry and looked `balance` up inside itself; the command is a parameter now, exactly as it
  * became one for `renderCommandHelp` (3F-3298). @SCN-CLI-009's scenario is unchanged and still
- * asks about `balance`: what a second command gets is the same bounding BY CONSTRUCTION, and the
- * residual — that an unregistered flag to `tags` is unproven by a scenario of its own — is named
- * on 3F-3286 rather than left silent.
+ * asks about `balance`: a command added later gets the same bounding BY CONSTRUCTION.
  */
-import type { CliRegistry } from "./cli-registry.js";
+import type { CliRegistry, FlagSpec } from "./cli-registry.js";
 /**
  * Parse `--flag value` pairs from a command's argv into a record, keys with the `--` stripped.
  *
@@ -25,33 +23,88 @@ import type { CliRegistry } from "./cli-registry.js";
  * the boolean flags — `--strict`, `--help` — are recognised: presence is what matters, so callers
  * read them with `!== undefined`.
  *
- * PERMISSIVE BY ITSELF, AND BOUNDED BY THE CALLER. It records whatever it is given, including a
- * flag no registry names; `checkUnknownFlags` below is what turns that into a usage error. The
- * split is deliberate — the parse has no opinion about which command it is reading for, and the
- * bounding has nothing else to do.
+ * PERMISSIVE BY ITSELF, AND BOUNDED BY THE CALLER. It records whatever it is given — a flag no
+ * registry names, the last of two copies, a word after a flag that takes none — and drops a word
+ * that follows no flag. `checkArgvShape` and `checkUnknownFlags` below are what refuse those, before
+ * anything reads the record (3F-3672). The split is deliberate — the parse has no opinion about which
+ * command it is reading for, and the bounding has nothing else to do.
  */
 export declare function parseArgs(argv: readonly string[]): Record<string, string>;
+/**
+ * The value flags of one scope: every flag the registry gives a value placeholder (`arg`), by
+ * name and alias, dashes kept. Read from the registry alone, so a value flag added later is one.
+ */
+export declare function valueFlagsOf(flags: readonly FlagSpec[]): Map<string, FlagSpec>;
+/**
+ * True when the token after a value flag is not a value: there is none, it is the next flag (the
+ * same `--` test `parseArgs` reads a flag by), or it is empty — an unset variable, quoted.
+ */
+export declare function isMissingValue(next: string | undefined): boolean;
+/**
+ * A flag that takes a value, given none, is a usage fault (@SCN-CLI-058, 3F-3639). It reads the
+ * RAW argv, because `parseArgs` has already turned a missing value into the string "true" — which a
+ * path flag then looked for on disk, `--target` recorded, and `--format` dropped on its way to a
+ * verdict `--exit-zero` turned green. Returns the refusal for the first such flag, else null.
+ */
+export declare function checkMissingValues(argv: readonly string[], registry: CliRegistry, command: string): string | null;
+/** The refusal for a value flag given none: the flag, the value it takes, and where the flags are listed. */
+export declare function missingValueRefusal(given: string, flag: FlagSpec, scope: string): string;
+/**
+ * The shape of a command's argv, read against its registry scope (3F-3672): every token is a flag,
+ * or the value of the flag before it, or a usage fault. Returns the refusal for the first token that
+ * is neither, else null.
+ */
+export declare function checkArgvShape(argv: readonly string[], registry: CliRegistry, command: string): string | null;
+/**
+ * The positional arguments in a command's argv, in order: every word that is no flag and no flag's
+ * value. A flag the registry gives no value placeholder takes none, so `--new ZZ` reads ZZ as the
+ * positional, never as `--new`'s value — which `parseArgs` alone would make it.
+ */
+export declare function positionalArguments(argv: readonly string[], registry: CliRegistry, command: string): string[];
+/** The refusal for a flag given more than once that is read once: the flag, and where. */
+export declare function givenTwiceRefusal(given: string, scope: string): string;
+/** A flag written with its value after an `=`, as in `--format=json`: a form this CLI does not read. */
+export declare function isEqualsForm(token: string): boolean;
+/**
+ * The refusal for a flag written `--flag=value` (@SCN-CLI-065, 3F-3672): the form as given, and the
+ * spelling that is read — the flag and its value as two arguments, or the flag alone when it takes
+ * none. Never the unknown-flag pin advice: no version reads the form, so no pin cures it. Refused
+ * rather than split, by ruling: one spelling means one reader of argv, where splitting would teach
+ * every reader of it the same answer.
+ */
+export declare function equalsFormRefusal(token: string, flags: ReadonlyMap<string, FlagSpec>, scope: string): string;
+/**
+ * A host modifier given after the command is out of place, not unknown (@SCN-CLI-061, 3F-3639): the
+ * flag exists, so @SCN-CLI-009's advice to bump a pin to a version that accepts it is false. Its own
+ * check rather than a branch of `checkUnknownFlags`, because the caller refuses this one through
+ * `process.exit` — the unknown-flag path sets a status and returns, which inside a stored run reaches
+ * the scaffold that stamps a run.yaml (3F-3650). Returns the refusal for the first such flag, else null.
+ */
+export declare function checkMisplacedHostModifiers(args: Record<string, string>, registry: CliRegistry, command: string): string | null;
 /**
  * The registry-bounded flag check at a command's CLI edge (@SCN-CLI-009). A command accepts ONLY
  * the flags its per-command registry scope LISTS (by `name` or `alias`); an unregistered flag — a
- * typo like `--strcit`, a stray `--bogus` — is a usage error, NOT silently swallowed the way the
- * permissive parse above would leave it. This is the structural teeth behind "accepted = registry
+ * typo like `--strcit`, a stray `--bogus` — is a usage error, where the permissive parse above would
+ * have recorded it. It bounds flag NAMES and nothing else: a word that is no flag, a value given to a
+ * flag that takes none, a second copy, a `--flag=value` form, are `checkArgvShape`'s, which runs
+ * first (@SCN-CLI-062–066, 3F-3672). This is the structural teeth behind "accepted = registry
  * = help": a flag cannot affect behaviour without a registry entry, and so (by @SCN-CLI-008's
  * guard) without appearing in that command's help.
  *
  * PURE and `@unit`-testable: the parsed args (keys already `--`-stripped) plus the registry and
  * the command to bound against, returning the FIRST unregistered flag as a typed usage error
  * naming it WITH its dashes — routed to stderr and the enumerated usage status 2 by the caller,
- * never 1, never a silent run — else null. The global `--store`/`--run-id` modifiers never reach
- * here: the top-level dispatcher consumes them BEFORE any command is dispatched, so a bounded
- * parse sees only the command's own args.
+ * never 1, never a silent run — else null. The global `--store`/`--run-id` modifiers are consumed
+ * by the top-level dispatcher when they come BEFORE the command; written after it they reach the
+ * command, and `checkMisplacedHostModifiers` refuses them as out of place before this runs
+ * (@SCN-CLI-061).
  *
  * A COMMAND THE REGISTRY DOES NOT NAME ACCEPTS NOTHING, which is the honest reading rather than a
  * degenerate one: an unregistered command has no scope, so every flag given to it is outside it.
  * The dispatcher refuses such a command before this is ever reached, so the case is unreachable
  * today and stated here so it cannot become a silent "accept everything" later.
  *
- * IT NAMES THE VERSION THAT REFUSED, AND THAT IS FOR THE PINNED READER (3F-3105, @SCN-SLF-008).
+ * IT NAMES THE VERSION THAT REFUSED, AND THAT IS FOR THE PINNED READER (3F-3105, @SCN-CLI-009).
  * A consumer pins spec-controller and then moves their own tree; the pinned reader is handed argv
  * it was published too early — or too late — to understand, and an unadorned "unknown flag" is
  * indistinguishable from a typo. Naming the running version makes version skew legible from the CI
@@ -65,6 +118,9 @@ export declare function parseArgs(argv: readonly string[]): Record<string, strin
  * refusal is exactly that forbidden wrapper, and no other adopter could write one either. So the
  * refusal is the tool's own, which makes it universal rather than local.
  *
+ * EXCEPT FOR A FLAG THE COMMAND HAS RETIRED, where the bump is false advice: `retiredFlagRefusal`
+ * below names the retirement and its replacement instead (3F-3528).
+ *
  * THE STATUS DOES NOT MOVE. The caller still routes this to stderr and exit 2. A mistyped `--strcit`
  * is still a usage fault, and giving skew its own status would cost every adopter the ordinary
  * reading to serve the rarer one.

package/dist/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CA0Bf"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAe,QAAQ,EAAkB,MAAM,mBAAmB,CAAC;AAE5F;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBzE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAO9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAUf;AAED,6GAA6G;AAC7G,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW7G;AAgBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAS7G;AAgCD,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtE;AAgBD,wGAAwG;AACxG,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAW5G;AAgDD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CA2Bf"}

package/dist/cli-args.js

@@ -13,9 +13,7 @@
  * command rather than for the one this code was written beside. `checkUnknownFlags` took the
  * registry and looked `balance` up inside itself; the command is a parameter now, exactly as it
  * became one for `renderCommandHelp` (3F-3298). @SCN-CLI-009's scenario is unchanged and still
- * asks about `balance`: what a second command gets is the same bounding BY CONSTRUCTION, and the
- * residual — that an unregistered flag to `tags` is unproven by a scenario of its own — is named
- * on 3F-3286 rather than left silent.
+ * asks about `balance`: a command added later gets the same bounding BY CONSTRUCTION.
  */
 /**
  * Parse `--flag value` pairs from a command's argv into a record, keys with the `--` stripped.
@@ -24,10 +22,11 @@
  * the boolean flags — `--strict`, `--help` — are recognised: presence is what matters, so callers
  * read them with `!== undefined`.
  *
- * PERMISSIVE BY ITSELF, AND BOUNDED BY THE CALLER. It records whatever it is given, including a
- * flag no registry names; `checkUnknownFlags` below is what turns that into a usage error. The
- * split is deliberate — the parse has no opinion about which command it is reading for, and the
- * bounding has nothing else to do.
+ * PERMISSIVE BY ITSELF, AND BOUNDED BY THE CALLER. It records whatever it is given — a flag no
+ * registry names, the last of two copies, a word after a flag that takes none — and drops a word
+ * that follows no flag. `checkArgvShape` and `checkUnknownFlags` below are what refuse those, before
+ * anything reads the record (3F-3672). The split is deliberate — the parse has no opinion about which
+ * command it is reading for, and the bounding has nothing else to do.
  */
 export function parseArgs(argv) {
     const args = {};
@@ -47,27 +46,228 @@ export function parseArgs(argv) {
     }
     return args;
 }
+/**
+ * The value flags of one scope: every flag the registry gives a value placeholder (`arg`), by
+ * name and alias, dashes kept. Read from the registry alone, so a value flag added later is one.
+ */
+export function valueFlagsOf(flags) {
+    const valueFlags = new Map();
+    for (const flag of flags) {
+        if (flag.arg === undefined)
+            continue;
+        for (const name of [flag.name, ...(flag.aliases ?? [])])
+            valueFlags.set(name, flag);
+    }
+    return valueFlags;
+}
+/**
+ * True when the token after a value flag is not a value: there is none, it is the next flag (the
+ * same `--` test `parseArgs` reads a flag by), or it is empty — an unset variable, quoted.
+ */
+export function isMissingValue(next) {
+    return next === undefined || next === "" || next.startsWith("--");
+}
+/**
+ * A flag that takes a value, given none, is a usage fault (@SCN-CLI-058, 3F-3639). It reads the
+ * RAW argv, because `parseArgs` has already turned a missing value into the string "true" — which a
+ * path flag then looked for on disk, `--target` recorded, and `--format` dropped on its way to a
+ * verdict `--exit-zero` turned green. Returns the refusal for the first such flag, else null.
+ */
+export function checkMissingValues(argv, registry, command) {
+    const entry = registry.commands.find((c) => c.name === command);
+    const valueFlags = valueFlagsOf(entry?.flags ?? []);
+    for (let i = 0; i < argv.length; i++) {
+        const flag = valueFlags.get(argv[i] ?? "");
+        if (flag !== undefined && isMissingValue(argv[i + 1])) {
+            return missingValueRefusal(argv[i] ?? flag.name, flag, `spec-controller ${command}`);
+        }
+    }
+    return null;
+}
+/** The refusal for a value flag given none: the flag, the value it takes, and where the flags are listed. */
+export function missingValueRefusal(given, flag, scope) {
+    return (`The ${given} flag of '${scope}' needs a value — ${given} ${flag.arg ?? ""} — and was given none.\n` +
+        `Run '${scope} --help' to see the flags this version accepts and the values they take.`);
+}
+/**
+ * The shape of a command's argv, read against its registry scope (3F-3672): every token is a flag,
+ * or the value of the flag before it, or a usage fault. Returns the refusal for the first token that
+ * is neither, else null.
+ */
+export function checkArgvShape(argv, registry, command) {
+    const scope = flagScopeOf(registry, command);
+    const seen = new Set();
+    const positionals = positionalsOf(registry, command);
+    const walk = { scope, seen, positionals, slotsLeft: positionals.length };
+    for (let i = 0; i < argv.length; i++) {
+        const read = readToken(argv, i, walk, command);
+        if (typeof read === "string")
+            return read;
+        i += read;
+    }
+    return null;
+}
+/** The positional arguments a command takes, in order; none for a command that takes flags only. */
+function positionalsOf(registry, command) {
+    return registry.commands.find((c) => c.name === command)?.positionals ?? [];
+}
+/**
+ * The positional arguments in a command's argv, in order: every word that is no flag and no flag's
+ * value. A flag the registry gives no value placeholder takes none, so `--new ZZ` reads ZZ as the
+ * positional, never as `--new`'s value — which `parseArgs` alone would make it.
+ */
+export function positionalArguments(argv, registry, command) {
+    const scope = flagScopeOf(registry, command);
+    const words = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (!isFlagShaped(token))
+            words.push(token);
+        else if (scope.get(token)?.arg !== undefined)
+            i++;
+    }
+    return words;
+}
+/** One token of the walk: the refusal it earns, or how many of the tokens after it are its value. */
+function readToken(argv, i, walk, command) {
+    const token = argv[i] ?? "";
+    const next = argv[i + 1];
+    if (isEqualsForm(token))
+        return equalsFormRefusal(token, walk.scope, `spec-controller ${command}`);
+    if (!isFlagShaped(token) && !walk.scope.has(token))
+        return positionalRead(token, walk, command);
+    const flag = walk.scope.get(token);
+    if (flag === undefined)
+        return valueTokensAfter(undefined, next);
+    return registeredFlagRefusal(flag, token, next, walk, command) ?? valueTokensAfter(flag, next);
+}
+/**
+ * The refusal a registered flag earns where it stands: given a second time when the registry does not
+ * mark it `repeatable` (by name or alias, one flag), or given a value it does not take.
+ */
+function registeredFlagRefusal(flag, token, next, walk, command) {
+    if (walk.seen.has(flag) && flag.repeatable !== true)
+        return givenTwiceRefusal(token, `spec-controller ${command}`);
+    walk.seen.add(flag);
+    if (flag.arg === undefined && next !== undefined && !isFlagShaped(next) && !walk.scope.has(next) && walk.slotsLeft === 0) {
+        return takesNoValueRefusal(token, next, command);
+    }
+    return undefined;
+}
+/** The refusal for a flag given more than once that is read once: the flag, and where. */
+export function givenTwiceRefusal(given, scope) {
+    return (`The ${given} flag of '${scope}' was given more than once, and is read once: give it once.\n` +
+        `Run '${scope} --help' to see the flags this version accepts.`);
+}
+/** Every flag of one command's scope, by name and alias, dashes kept. */
+function flagScopeOf(registry, command) {
+    const scope = new Map();
+    for (const flag of registry.commands.find((c) => c.name === command)?.flags ?? []) {
+        for (const name of [flag.name, ...(flag.aliases ?? [])])
+            scope.set(name, flag);
+    }
+    return scope;
+}
+/** A token read as a flag whether or not the scope has it: two dashes, as `parseArgs` reads one. */
+function isFlagShaped(token) {
+    return token.startsWith("--");
+}
+/** A flag written with its value after an `=`, as in `--format=json`: a form this CLI does not read. */
+export function isEqualsForm(token) {
+    return isFlagShaped(token) && token.includes("=");
+}
+/**
+ * The refusal for a flag written `--flag=value` (@SCN-CLI-065, 3F-3672): the form as given, and the
+ * spelling that is read — the flag and its value as two arguments, or the flag alone when it takes
+ * none. Never the unknown-flag pin advice: no version reads the form, so no pin cures it. Refused
+ * rather than split, by ruling: one spelling means one reader of argv, where splitting would teach
+ * every reader of it the same answer.
+ */
+export function equalsFormRefusal(token, flags, scope) {
+    const at = token.indexOf("=");
+    const name = token.slice(0, at);
+    const value = token.slice(at + 1);
+    const flag = flags.get(name);
+    const spelling = flag !== undefined && flag.arg === undefined ? name : `${name} ${value === "" ? (flag?.arg ?? "<value>") : value}`;
+    return (`The ${token} form is not read by '${scope}': a flag and its value are two arguments, as in '${spelling}'.\n` +
+        `Run '${scope} --help' to see the flags this version accepts.`);
+}
+/**
+ * How many tokens after a flag are its value: one for a value flag given one, and — for a flag the
+ * scope does not have — one for the word after it, exactly as `parseArgs` pairs them, so an unknown
+ * flag and its word stay @SCN-CLI-009's to refuse. An empty value is consumed as one, so it stays
+ * @SCN-CLI-058's missing value rather than becoming a stray argument.
+ */
+function valueTokensAfter(flag, next) {
+    if (next === undefined || isFlagShaped(next))
+        return 0;
+    return flag === undefined || flag.arg !== undefined ? 1 : 0;
+}
+/** The refusal for a value given to a flag that takes none: the flag, and the value it was given. */
+function takesNoValueRefusal(flag, value, command) {
+    return (`The ${flag} flag of 'spec-controller ${command}' takes no value, and was given one: '${value}'.\n` +
+        `Run 'spec-controller ${command} --help' to see the flags this version accepts and the values they take.`);
+}
+/** A word that is no flag fills the command's next positional slot, or is refused when none is left. */
+function positionalRead(token, walk, command) {
+    if (walk.slotsLeft === 0) {
+        return walk.positionals.length === 0 ? notAFlagRefusal(token, command) : extraPositionalRefusal(token, walk, command);
+    }
+    walk.slotsLeft--;
+    return 0;
+}
+/** The refusal for a word beyond the positional arguments a command takes: the word, and what it takes. */
+function extraPositionalRefusal(token, walk, command) {
+    const takes = walk.positionals.map((positional) => positional.name).join(" ");
+    return (`The argument '${token}' is more than 'spec-controller ${command}' takes: it takes ${takes} once, and its flags.\n` +
+        `Run 'spec-controller ${command} --help' to see what this version accepts.`);
+}
+/** The refusal for a token that is no flag and no flag's value: the token, and what the command takes. */
+function notAFlagRefusal(token, command) {
+    return (`The argument '${token}' is not a flag, nor the value of the flag before it: ` +
+        `'spec-controller ${command}' takes only flags and their values.\n` +
+        `Run 'spec-controller ${command} --help' to see the flags this version accepts.`);
+}
+/**
+ * A host modifier given after the command is out of place, not unknown (@SCN-CLI-061, 3F-3639): the
+ * flag exists, so @SCN-CLI-009's advice to bump a pin to a version that accepts it is false. Its own
+ * check rather than a branch of `checkUnknownFlags`, because the caller refuses this one through
+ * `process.exit` — the unknown-flag path sets a status and returns, which inside a stored run reaches
+ * the scaffold that stamps a run.yaml (3F-3650). Returns the refusal for the first such flag, else null.
+ */
+export function checkMisplacedHostModifiers(args, registry, command) {
+    const modifiers = new Set(registry.global.map((flag) => flag.name.replace(/^-+/, "")));
+    const key = Object.keys(args).find((k) => modifiers.has(k));
+    if (key === undefined)
+        return null;
+    return (`The --${key} flag is a host modifier: it goes before the command, as in ` +
+        `'spec-controller --${key} <value> ${command} …', never after it.\n` +
+        `Run 'spec-controller --help' to see the host modifiers this version accepts.`);
+}
 /**
  * The registry-bounded flag check at a command's CLI edge (@SCN-CLI-009). A command accepts ONLY
  * the flags its per-command registry scope LISTS (by `name` or `alias`); an unregistered flag — a
- * typo like `--strcit`, a stray `--bogus` — is a usage error, NOT silently swallowed the way the
- * permissive parse above would leave it. This is the structural teeth behind "accepted = registry
+ * typo like `--strcit`, a stray `--bogus` — is a usage error, where the permissive parse above would
+ * have recorded it. It bounds flag NAMES and nothing else: a word that is no flag, a value given to a
+ * flag that takes none, a second copy, a `--flag=value` form, are `checkArgvShape`'s, which runs
+ * first (@SCN-CLI-062–066, 3F-3672). This is the structural teeth behind "accepted = registry
  * = help": a flag cannot affect behaviour without a registry entry, and so (by @SCN-CLI-008's
  * guard) without appearing in that command's help.
  *
  * PURE and `@unit`-testable: the parsed args (keys already `--`-stripped) plus the registry and
  * the command to bound against, returning the FIRST unregistered flag as a typed usage error
  * naming it WITH its dashes — routed to stderr and the enumerated usage status 2 by the caller,
- * never 1, never a silent run — else null. The global `--store`/`--run-id` modifiers never reach
- * here: the top-level dispatcher consumes them BEFORE any command is dispatched, so a bounded
- * parse sees only the command's own args.
+ * never 1, never a silent run — else null. The global `--store`/`--run-id` modifiers are consumed
+ * by the top-level dispatcher when they come BEFORE the command; written after it they reach the
+ * command, and `checkMisplacedHostModifiers` refuses them as out of place before this runs
+ * (@SCN-CLI-061).
  *
  * A COMMAND THE REGISTRY DOES NOT NAME ACCEPTS NOTHING, which is the honest reading rather than a
  * degenerate one: an unregistered command has no scope, so every flag given to it is outside it.
  * The dispatcher refuses such a command before this is ever reached, so the case is unreachable
  * today and stated here so it cannot become a silent "accept everything" later.
  *
- * IT NAMES THE VERSION THAT REFUSED, AND THAT IS FOR THE PINNED READER (3F-3105, @SCN-SLF-008).
+ * IT NAMES THE VERSION THAT REFUSED, AND THAT IS FOR THE PINNED READER (3F-3105, @SCN-CLI-009).
  * A consumer pins spec-controller and then moves their own tree; the pinned reader is handed argv
  * it was published too early — or too late — to understand, and an unadorned "unknown flag" is
  * indistinguishable from a typo. Naming the running version makes version skew legible from the CI
@@ -81,6 +281,9 @@ export function parseArgs(argv) {
  * refusal is exactly that forbidden wrapper, and no other adopter could write one either. So the
  * refusal is the tool's own, which makes it universal rather than local.
  *
+ * EXCEPT FOR A FLAG THE COMMAND HAS RETIRED, where the bump is false advice: `retiredFlagRefusal`
+ * below names the retirement and its replacement instead (3F-3528).
+ *
  * THE STATUS DOES NOT MOVE. The caller still routes this to stderr and exit 2. A mistyped `--strcit`
  * is still a usage fault, and giving skew its own status would cost every adopter the ordinary
  * reading to serve the rarer one.
@@ -102,13 +305,31 @@ export function checkUnknownFlags(args, registry, command, toolVersion) {
     // whose scope refused it — a consumer running two commands needs to know which help to open.
     for (const key of Object.keys(args)) {
         if (!accepted.has(key)) {
-            return (`Unknown flag --${key} for 'spec-controller ${command}' — this is spec-controller ` +
-                `${toolVersion}, and that flag is not in its ${command} scope.\n` +
-                `If this version is pinned, the pin and the tree it is reading have drifted apart: ` +
-                `bump the pin to a version whose '${command}' accepts --${key}.\n` +
-                `Otherwise run 'spec-controller ${command} --help' to see the flags this version accepts.`);
+            return (retiredFlagRefusal(entry, key, command, toolVersion) ??
+                `Unknown flag --${key} for 'spec-controller ${command}' — this is spec-controller ` +
+                    `${toolVersion}, and that flag is not in its ${command} scope.\n` +
+                    `If this version is pinned, the pin and the tree it is reading have drifted apart: ` +
+                    `bump the pin to a version whose '${command}' accepts --${key}.\n` +
+                    `Otherwise run 'spec-controller ${command} --help' to see the flags this version accepts.`);
         }
     }
     return null;
 }
+/**
+ * THE REFUSAL FOR A FLAG THE COMMAND HAS RETIRED (@SCN-CLI-023, 3F-3528), or `undefined` when the
+ * flag is merely unregistered. The drift advice above is true of a flag newer than the pin and
+ * false of a retired one: every earlier version accepts it and no later one will, so the only pin
+ * that satisfies "bump the pin to a version that accepts it" is a downgrade back onto the route
+ * the retirement removed. So this names the retirement and the replacement, and offers no pin.
+ */
+function retiredFlagRefusal(entry, key, command, toolVersion) {
+    const retired = entry?.retiredFlags?.find((flag) => flag.name.replace(/^-+/, "") === key);
+    if (retired === undefined)
+        return undefined;
+    return (`Retired flag ${retired.name} for 'spec-controller ${command}' — retired in spec-controller ` +
+        `${retired.retiredIn}, and no later version accepts it (this is spec-controller ${toolVersion}).\n` +
+        `Do not pin an earlier version to get it back: that restores the route it was retired with. ` +
+        `${retired.replacement}\n` +
+        `Run 'spec-controller ${command} --help' to see the flags this version accepts.`);
+}
 //# sourceMappingURL=cli-args.js.map

package/dist/cli-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,IAAuB;IAC/C,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnD,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAClB,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAA4B,EAC5B,QAAqB,EACrB,OAAe,EACf,WAAmB;IAEnB,+FAA+F;IAC/F,6FAA6F;IAC7F,qFAAqF;IACrF,+CAA+C;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QACtC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,2FAA2F;IAC3F,gGAAgG;IAChG,6FAA6F;IAC7F,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CACL,kBAAkB,GAAG,yBAAyB,OAAO,8BAA8B;gBACnF,GAAG,WAAW,iCAAiC,OAAO,WAAW;gBACjE,oFAAoF;gBACpF,oCAAoC,OAAO,eAAe,GAAG,KAAK;gBAClE,kCAAkC,OAAO,iDAAiD,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,IAAuB;IAC/C,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnD,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAClB,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAA0B;IACrD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC/C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;YAAE,SAAS;QACrC,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACrD,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAuB,EACvB,QAAqB,EACrB,OAAe;IAEf,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAChE,MAAM,UAAU,GAAG,YAAY,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IACpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,SAAS,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,mBAAmB,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,IAAc,EAAE,KAAa;IAC9E,OAAO,CACL,OAAO,KAAK,aAAa,KAAK,qBAAqB,KAAK,IAAI,IAAI,CAAC,GAAG,IAAI,EAAE,0BAA0B;QACpG,QAAQ,KAAK,0EAA0E,CACxF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAuB,EAAE,QAAqB,EAAE,OAAe;IAC5F,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAY,CAAC;IACjC,MAAM,WAAW,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,IAAI,GAAS,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;IAC/E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1C,CAAC,IAAI,IAAI,CAAC;IACZ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAWD,oGAAoG;AACpG,SAAS,aAAa,CAAC,QAAqB,EAAE,OAAe;IAC3D,OAAO,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB,EAAE,QAAqB,EAAE,OAAe;IACjG,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aACvC,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,SAAS;YAAE,CAAC,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,qGAAqG;AACrG,SAAS,SAAS,CAAC,IAAuB,EAAE,CAAS,EAAE,IAAU,EAAE,OAAe;IAChF,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,IAAI,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,mBAAmB,OAAO,EAAE,CAAC,CAAC;IACnG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAChG,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACjE,OAAO,qBAAqB,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACjG,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAC5B,IAAc,EACd,KAAa,EACb,IAAwB,EACxB,IAAU,EACV,OAAe;IAEf,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,OAAO,EAAE,CAAC,CAAC;IACnH,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,KAAK,CAAC,EAAE,CAAC;QACzH,OAAO,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,KAAa;IAC5D,OAAO,CACL,OAAO,KAAK,aAAa,KAAK,+DAA+D;QAC7F,QAAQ,KAAK,iDAAiD,CAC/D,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,SAAS,WAAW,CAAC,QAAqB,EAAE,OAAe;IACzD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QAClF,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oGAAoG;AACpG,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,KAAoC,EAAE,KAAa;IAClG,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,QAAQ,GACZ,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IACrH,OAAO,CACL,OAAO,KAAK,yBAAyB,KAAK,qDAAqD,QAAQ,MAAM;QAC7G,QAAQ,KAAK,iDAAiD,CAC/D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,IAA0B,EAAE,IAAwB;IAC5E,IAAI,IAAI,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACvD,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,qGAAqG;AACrG,SAAS,mBAAmB,CAAC,IAAY,EAAE,KAAa,EAAE,OAAe;IACvE,OAAO,CACL,OAAO,IAAI,6BAA6B,OAAO,yCAAyC,KAAK,MAAM;QACnG,wBAAwB,OAAO,0EAA0E,CAC1G,CAAC;AACJ,CAAC;AAED,wGAAwG;AACxG,SAAS,cAAc,CAAC,KAAa,EAAE,IAAU,EAAE,OAAe;IAChE,IAAI,IAAI,CAAC,SAAS,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACxH,CAAC;IACD,IAAI,CAAC,SAAS,EAAE,CAAC;IACjB,OAAO,CAAC,CAAC;AACX,CAAC;AAED,2GAA2G;AAC3G,SAAS,sBAAsB,CAAC,KAAa,EAAE,IAAU,EAAE,OAAe;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9E,OAAO,CACL,iBAAiB,KAAK,mCAAmC,OAAO,qBAAqB,KAAK,yBAAyB;QACnH,wBAAwB,OAAO,4CAA4C,CAC5E,CAAC;AACJ,CAAC;AAED,0GAA0G;AAC1G,SAAS,eAAe,CAAC,KAAa,EAAE,OAAe;IACrD,OAAO,CACL,iBAAiB,KAAK,wDAAwD;QAC9E,oBAAoB,OAAO,wCAAwC;QACnE,wBAAwB,OAAO,iDAAiD,CACjF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAA4B,EAC5B,QAAqB,EACrB,OAAe;IAEf,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACvF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,CACL,SAAS,GAAG,8DAA8D;QAC1E,sBAAsB,GAAG,YAAY,OAAO,wBAAwB;QACpE,8EAA8E,CAC/E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAA4B,EAC5B,QAAqB,EACrB,OAAe,EACf,WAAmB;IAEnB,+FAA+F;IAC/F,6FAA6F;IAC7F,qFAAqF;IACrF,+CAA+C;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QACtC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,2FAA2F;IAC3F,gGAAgG;IAChG,6FAA6F;IAC7F,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CACL,kBAAkB,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,CAAC;gBACpD,kBAAkB,GAAG,yBAAyB,OAAO,8BAA8B;oBACnF,GAAG,WAAW,iCAAiC,OAAO,WAAW;oBACjE,oFAAoF;oBACpF,oCAAoC,OAAO,eAAe,GAAG,KAAK;oBAClE,kCAAkC,OAAO,iDAAiD,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CACzB,KAA8B,EAC9B,GAAW,EACX,OAAe,EACf,WAAmB;IAEnB,MAAM,OAAO,GAAG,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC;IAC1F,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,OAAO,CACL,gBAAgB,OAAO,CAAC,IAAI,yBAAyB,OAAO,iCAAiC;QAC7F,GAAG,OAAO,CAAC,SAAS,8DAA8D,WAAW,MAAM;QACnG,6FAA6F;QAC7F,GAAG,OAAO,CAAC,WAAW,IAAI;QAC1B,wBAAwB,OAAO,iDAAiD,CACjF,CAAC;AACJ,CAAC"}

package/dist/cli-balance/cli.d.ts

@@ -32,6 +32,23 @@ export declare function checkLegacyJson(args: Record<string, string>): string |
  * explicit default.
  */
 export declare function sourceTarget(args: Record<string, string>): string;
+/**
+ * Guard the supplied input-file/dir flags at the CLI edge (@SCN-CLI-002). A
+ * mistyped `--vitest` / `--cucumber` / `--features` / `--ci` / `--package-json`
+ * pointing at a non-existent path used to reconcile silently against ZERO evidence —
+ * a terrifying false all-red report meaning "you forgot the reports", not "your code
+ * is broken" (the dogfooding fault). These flags are Examples of ONE boundary
+ * rule: a supplied-but-absent input path is a hard error, and a flag added to the set
+ * inherits it rather than restating it. Scope is existence only
+ * (readability / file-vs-dir type-correctness out of scope; `exists` covers the dir
+ * flag and the file flags alike).
+ *
+ * PURE and `@unit`-testable like `checkLegacyJson` / `sourceTarget`: reads the parsed
+ * args + an injected `exists` fn (no fs), returns the FIRST supplied-but-absent
+ * `(flag, path)` as a typed error naming both — routed to stderr + a non-zero exit by
+ * `refuseUnreadableInputs` (the shared typed-error surface) — else null. An OMITTED flag is not an
+ * error (legitimately optional: simply no evidence of that kind).
+ */
 export declare function checkInputsExist(args: Record<string, string>, exists: (path: string) => boolean): string | null;
 /**
  * Guard the READABILITY of the supplied JSON inputs at the CLI edge (@SCN-CLI-014).
@@ -44,7 +61,7 @@ export declare function checkInputsExist(args: Record<string, string>, exists: (
  *
  * PURE and `@unit`-testable like its sibling guards: reads the parsed args + an injected
  * `read` fn (no fs), returns the FIRST supplied-but-unparseable `(flag, path, failure)` as
- * a typed error naming all three — routed to stderr + exit 2 by `runBalance` — else null.
+ * a typed error naming all three — routed to stderr + exit 2 by `refuseUnreadableInputs` — else null.
  * An omitted flag is not an error, and an unreadable file (a race after the existence
  * check) reports as the same input fault rather than escaping as a crash.
  */

package/dist/cli-balance/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli-balance/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiDH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAS3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEjE;AAuCD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAChC,MAAM,GAAG,IAAI,CAcf;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAef;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAcf;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAsR/C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli-balance/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAuDH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAS3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEjE;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAChC,MAAM,GAAG,IAAI,CAcf;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAef;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,GAAG,IAAI,CAcf;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAoK/C"}