spec-controller 0.1.0-alpha.4 → 0.1.0-alpha.40

package/dist/cli-allocate/request.js

@@ -0,0 +1,29 @@
+/**
+ * What an `allocate` invocation asks for, read against the command's registry scope, or the usage
+ * error it is. A usage error is worded as one, so it is never taken for an unknown part.
+ */
+import { isFeaturePart } from "@3f-consulting/spec-controller-core";
+import { checkArgvShape, checkMisplacedHostModifiers, checkUnknownFlags, parseArgs, positionalArguments, } from "../cli-args.js";
+/** The request `argv` makes, or the usage error it is, worded for stderr. */
+export function readRequest(argv, registry, toolVersion) {
+    const why = argvRefusal(argv, registry, toolVersion) ?? partRefusal(positionalArguments(argv, registry, "allocate")[0]);
+    if (why !== null)
+        return { usageError: `spec-controller allocate: usage error — ${why}` };
+    return { part: positionalArguments(argv, registry, "allocate")[0] ?? "", isNew: argv.includes("--new") };
+}
+/** The first refusal the argv earns against the registry, the same checks `balance` makes, in its order. */
+function argvRefusal(argv, registry, toolVersion) {
+    const args = parseArgs(argv);
+    return (checkMisplacedHostModifiers(args, registry, "allocate") ??
+        checkArgvShape(argv, registry, "allocate") ??
+        checkUnknownFlags(args, registry, "allocate", toolVersion));
+}
+/** The refusal for the part given, or null when it is a feature part in canon's form. */
+function partRefusal(part) {
+    if (part === undefined)
+        return "no feature part was given: 'spec-controller allocate <FFF>' takes one, a feature file's header code.";
+    if (isFeaturePart(part))
+        return null;
+    return `'${part}' is not a feature part in canon's form: two to five characters, each A-Z or 0-9.`;
+}
+//# sourceMappingURL=request.js.map

package/dist/cli-allocate/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/cli-allocate/request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EACL,cAAc,EACd,2BAA2B,EAC3B,iBAAiB,EACjB,SAAS,EACT,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AASxB,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CACzB,IAAuB,EACvB,QAAqB,EACrB,WAAmB;IAEnB,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,CAAC,IAAI,WAAW,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxH,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,UAAU,EAAE,2CAA2C,GAAG,EAAE,EAAE,CAAC;IAC1F,OAAO,EAAE,IAAI,EAAE,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;AAC3G,CAAC;AAED,4GAA4G;AAC5G,SAAS,WAAW,CAAC,IAAuB,EAAE,QAAqB,EAAE,WAAmB;IACtF,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CACL,2BAA2B,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC;QACvD,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC;QAC1C,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAC,CAC3D,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,SAAS,WAAW,CAAC,IAAwB;IAC3C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,sGAAsG,CAAC;IACtI,IAAI,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,IAAI,IAAI,mFAAmF,CAAC;AACrG,CAAC"}

package/dist/cli-allocate/stderr.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What the allocator says beside its answer, on stderr, so stdout carries the code alone.
+ */
+import { type Allocation, type UnknownPart } from "@3f-consulting/spec-controller-core";
+import type { HistoryBoundary } from "./readHistory.js";
+/** What was left unread, and what that means for the answer; nothing when history was read whole. */
+export declare function historyBoundaryLine(boundary: HistoryBoundary, allocation: Allocation): string | null;
+/** Where the highest code was seen: a file and line, and the commit when only history carries it. */
+export declare function highestSeenLine(allocation: Allocation): string;
+/** The refusal for a part no feature file's header carries: the part, and the parts that are. */
+export declare function unknownPartRefusal(refusal: UnknownPart): string;
+/** The note for a part asked for as new that a header already carries; nothing otherwise. */
+export declare function alreadyHeadedNote(allocation: Allocation): string | null;
+//# sourceMappingURL=stderr.d.ts.map

package/dist/cli-allocate/stderr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stderr.d.ts","sourceRoot":"","sources":["../../src/cli-allocate/stderr.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,qCAAqC,CAAC;AACvG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAKpG;AAED,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAK9D;AAED,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAM/D;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAGvE"}

package/dist/cli-allocate/stderr.js

@@ -0,0 +1,33 @@
+/**
+ * What the allocator says beside its answer, on stderr, so stdout carries the code alone.
+ */
+import { featureCodeOf } from "@3f-consulting/spec-controller-core";
+/** What was left unread, and what that means for the answer; nothing when history was read whole. */
+export function historyBoundaryLine(boundary, allocation) {
+    if (boundary.kind === "complete")
+        return null;
+    const unread = boundary.kind === "shallow" ? `shallow clone — history before ${boundary.before} unread` : "not a git repository — none read";
+    const risk = allocation.highest === null ? `a code of ${featureCodeOf(allocation.code) ?? ""}` : `a code above ${allocation.highest.code}`;
+    return `history: ${unread}; ${risk} may have been used before`;
+}
+/** Where the highest code was seen: a file and line, and the commit when only history carries it. */
+export function highestSeenLine(allocation) {
+    const highest = allocation.highest;
+    if (highest === null)
+        return "highest seen: none";
+    const { path, line, commit } = highest.sighting;
+    return `highest seen: ${highest.code}, ${path}:${line}${commit === undefined ? "" : ` in ${commit}`}`;
+}
+/** The refusal for a part no feature file's header carries: the part, and the parts that are. */
+export function unknownPartRefusal(refusal) {
+    const parts = refusal.headerCodes.length === 0 ? "none" : refusal.headerCodes.join(", ");
+    return (`spec-controller allocate: unknown part — no feature file's header carries ${refusal.part}.\n` +
+        `The parts this corpus's feature files carry: ${parts}.`);
+}
+/** The note for a part asked for as new that a header already carries; nothing otherwise. */
+export function alreadyHeadedNote(allocation) {
+    if (allocation.alreadyHeaded !== true)
+        return null;
+    return `note: a feature file's header already carries ${featureCodeOf(allocation.code) ?? ""}, so --new was not needed`;
+}
+//# sourceMappingURL=stderr.js.map

package/dist/cli-allocate/stderr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stderr.js","sourceRoot":"","sources":["../../src/cli-allocate/stderr.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAqC,MAAM,qCAAqC,CAAC;AAGvG,qGAAqG;AACrG,MAAM,UAAU,mBAAmB,CAAC,QAAyB,EAAE,UAAsB;IACnF,IAAI,QAAQ,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,kCAAkC,QAAQ,CAAC,MAAM,SAAS,CAAC,CAAC,CAAC,kCAAkC,CAAC;IAC7I,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAC3I,OAAO,YAAY,MAAM,KAAK,IAAI,4BAA4B,CAAC;AACjE,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,eAAe,CAAC,UAAsB;IACpD,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;IACnC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,oBAAoB,CAAC;IAClD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAChD,OAAO,iBAAiB,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,MAAM,EAAE,EAAE,CAAC;AACxG,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,kBAAkB,CAAC,OAAoB;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzF,OAAO,CACL,6EAA6E,OAAO,CAAC,IAAI,KAAK;QAC9F,gDAAgD,KAAK,GAAG,CACzD,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,iBAAiB,CAAC,UAAsB;IACtD,IAAI,UAAU,CAAC,aAAa,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,iDAAiD,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,2BAA2B,CAAC;AAC1H,CAAC"}

package/dist/cli-allocate/unreadable.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A path allocate is meant to read and cannot. It is the invocation being wrong, the same as a
+ * malformed request, so it is refused as a usage error naming the path and the reason, and no code
+ * is given: an answer computed without the path could hand out a code the unread path carries.
+ */
+/** What allocate could not read: which input it was, where (when the read had a path), and the reason. */
+export declare class UnreadableInput extends Error {
+    readonly subject: string;
+    readonly path: string;
+    readonly reason: string;
+    readonly name = "UnreadableInput";
+    constructor(subject: string, path: string, reason: string);
+}
+/**
+ * The read's answer, or the refusal when the operating system refuses it. Any refusal the OS gives
+ * is the same fault here: not permitted, not the kind of path the read expects, or not there. A
+ * throw that carries no OS code is not a read failing, and is left to surface.
+ */
+export declare function readOrRefuse<T>(subject: string, path: string, read: () => T): T;
+/** Throw the refusal a failed read of `path` is, or the throw itself when it is not a read failing. */
+export declare function refuse(subject: string, path: string, err: unknown): never;
+/** The one stderr line a refusal is written as, in allocate's usage-error form. */
+export declare function refusalLine(refusal: UnreadableInput): string;
+//# sourceMappingURL=unreadable.d.ts.map

package/dist/cli-allocate/unreadable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreadable.d.ts","sourceRoot":"","sources":["../../src/cli-allocate/unreadable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,0GAA0G;AAC1G,qBAAa,eAAgB,SAAQ,KAAK;IAItC,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM;IALzB,SAAkB,IAAI,qBAAqB;gBAGhC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAI1B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAM/E;AAED,uGAAuG;AACvG,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,KAAK,CAIzE;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAE5D"}

package/dist/cli-allocate/unreadable.js

@@ -0,0 +1,43 @@
+/**
+ * A path allocate is meant to read and cannot. It is the invocation being wrong, the same as a
+ * malformed request, so it is refused as a usage error naming the path and the reason, and no code
+ * is given: an answer computed without the path could hand out a code the unread path carries.
+ */
+/** What allocate could not read: which input it was, where (when the read had a path), and the reason. */
+export class UnreadableInput extends Error {
+    subject;
+    path;
+    reason;
+    name = "UnreadableInput";
+    constructor(subject, path, reason) {
+        super(path === "" ? `${subject} could not be read (${reason})` : `${subject} could not be read: ${path} (${reason})`);
+        this.subject = subject;
+        this.path = path;
+        this.reason = reason;
+    }
+}
+/**
+ * The read's answer, or the refusal when the operating system refuses it. Any refusal the OS gives
+ * is the same fault here: not permitted, not the kind of path the read expects, or not there. A
+ * throw that carries no OS code is not a read failing, and is left to surface.
+ */
+export function readOrRefuse(subject, path, read) {
+    try {
+        return read();
+    }
+    catch (err) {
+        return refuse(subject, path, err);
+    }
+}
+/** Throw the refusal a failed read of `path` is, or the throw itself when it is not a read failing. */
+export function refuse(subject, path, err) {
+    const errno = err;
+    if (!(err instanceof Error) || typeof errno.code !== "string")
+        throw err;
+    throw new UnreadableInput(subject, errno.path ?? path, err.message);
+}
+/** The one stderr line a refusal is written as, in allocate's usage-error form. */
+export function refusalLine(refusal) {
+    return `spec-controller allocate: usage error — ${refusal.message}`;
+}
+//# sourceMappingURL=unreadable.js.map

package/dist/cli-allocate/unreadable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreadable.js","sourceRoot":"","sources":["../../src/cli-allocate/unreadable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,0GAA0G;AAC1G,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAI7B;IACA;IACA;IALO,IAAI,GAAG,iBAAiB,CAAC;IAE3C,YACW,OAAe,EACf,IAAY,EACZ,MAAc;QAEvB,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,uBAAuB,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,uBAAuB,IAAI,KAAK,MAAM,GAAG,CAAC,CAAC;QAJ7G,YAAO,GAAP,OAAO,CAAQ;QACf,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;IAGzB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAI,OAAe,EAAE,IAAY,EAAE,IAAa;IAC1E,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,MAAM,CAAC,OAAe,EAAE,IAAY,EAAE,GAAY;IAChE,MAAM,KAAK,GAAG,GAA4B,CAAC;IAC3C,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,MAAM,GAAG,CAAC;IACzE,MAAM,IAAI,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;AACtE,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,OAAwB;IAClD,OAAO,2CAA2C,OAAO,CAAC,OAAO,EAAE,CAAC;AACtE,CAAC"}

package/dist/cli-args.d.ts

@@ -1,7 +1,7 @@
 /**
  * THE ONE READING OF A COMMAND'S ARGV, and the one bounding of it against the registry.
  *
- * WHY IT IS ITS OWN MODULE (3F-3300). Both halves lived inside `cli-balance/cli.ts` while
+ * WHY IT IS ITS OWN MODULE. Both halves lived inside `cli-balance/cli.ts` while
  * `balance` was the only command — `parseArgs` private to it, `checkUnknownFlags` exported for
  * its own `@unit` arm. A second command needs both, and the two ways of giving it them were
  * worse than moving them: copying `parseArgs` would put a second reading of argv in a tree whose
@@ -12,12 +12,12 @@
  * THE BOUNDING IS PER-COMMAND, which is what makes "accepted = registry = help" hold for every
  * 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.
+ * became one for `renderCommandHelp`. The unknown-flag scenario is unchanged and still
+ * 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";
+/** True when a command's argv asks for its help, wherever `--help` or `-h` stands in it. */
+export declare function asksForHelp(argv: readonly string[]): boolean;
 /**
  * Parse `--flag value` pairs from a command's argv into a record, keys with the `--` stripped.
  *
@@ -25,33 +25,85 @@ 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. 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 registry-bounded flag check at a command's CLI edge (@SCN-CLI-009). A command accepts ONLY
+ * 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. 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: 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`: 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: the
+ * flag exists, so the unknown-flag advice to bump a pin to a version that accepts it is false. 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. 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
- * = help": a flag cannot affect behaviour without a registry entry, and so (by @SCN-CLI-008's
+ * 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. This is the structural teeth behind "accepted = registry
+ * = help": a flag cannot affect behaviour without a registry entry, and so (by the help-completeness
  * 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.
  *
  * 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.
  * 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 +117,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.
+ *
  * 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,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE5D;AAED;;;;;;;;;;;;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;;;;GAIG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;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"}