@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/dispatch/guard-invocation.d.ts

@@ -0,0 +1,33 @@
+import type { IGuardInvocationInput } from './guard-invocation-input.js';
+import type { IInvocationRejection } from './invocation-rejection.js';
+/**
+ * THE pre-run invocation guard (round 11 §5.2): cheap, no inspection, runs
+ * after the help intercept and before the surface gate and the command body.
+ *
+ * Before it, a wrong command ran something else and exited 0 —
+ * `shrk check rules --tag auth` printed a full green sweep, `shrk templates
+ * lst` printed group help at exit 0, `shrk api-diff status` reported a missing
+ * baseline FILE named `status`. The guard judges only what a handler DECLARES,
+ * so a legitimate free positional (`task "add a thing"`) is never rejected:
+ *
+ *   - a pure command group + a bare token                → unknown subcommand;
+ *   - `positionals: None` + a token that names no subverb → unknown subcommand
+ *     (the closest match, and "`rules` is a command of its own" when it is);
+ *   - `positionals: Path` + a VERB-SHAPED token that is neither a subverb nor
+ *     an existing file → "has no `status` verb, and no file named `status`
+ *     exists", with the sibling commands that do have that verb;
+ *   - declared `flags` → any other flag (the global flags excepted).
+ *
+ * Every rejection exits `usageExitFor(path)` — 3 on a verdict verb, 2
+ * elsewhere — and never 0. The dispatcher calls it through
+ * `judgeInvocation`, which adds the undocumented-flag refusal; the
+ * command-string resolver calls the same function.
+ */
+export declare function guardInvocation(input: IGuardInvocationInput): IInvocationRejection | undefined;
+/**
+ * A token that reads as a VERB, not a path: lowercase kebab starting with a
+ * letter — no `.`, `/`, `\`, `:`, `{`, `=` or uppercase. Inline JSON (`{…}`),
+ * `-` (stdin) and any real path fail it, so the Path rule never blocks them.
+ */
+export declare function isVerbShaped(token: string): boolean;
+//# sourceMappingURL=guard-invocation.d.ts.map

package/dist/dispatch/guard-invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-invocation.d.ts","sourceRoot":"","sources":["../../src/dispatch/guard-invocation.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAOtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,qBAAqB,GAAG,oBAAoB,GAAG,SAAS,CAyB9F;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/dispatch/guard-invocation.js

@@ -0,0 +1,183 @@
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { firstUnknownFlag } from "../command-registry.js";
+import { usageExitFor } from "../exit-codes.js";
+import { commandIndexFor, subverbNamesOf } from "../surface/command-index.js";
+import { closestMatches } from "./closest-match.js";
+import { GLOBAL_FLAGS, IMPLICIT_FLAGS } from "./global-flags.js";
+import { InvocationRejectionKind } from "./invocation-rejection-kind.js";
+import { PositionalMode } from "./positional-mode.js";
+import { unknownFlagRefusal } from "./unknown-flag-refusal.js";
+import { walkDeclaredSubverbs } from "./walk-declared-subverbs.js";
+/**
+ * THE pre-run invocation guard (round 11 §5.2): cheap, no inspection, runs
+ * after the help intercept and before the surface gate and the command body.
+ *
+ * Before it, a wrong command ran something else and exited 0 —
+ * `shrk check rules --tag auth` printed a full green sweep, `shrk templates
+ * lst` printed group help at exit 0, `shrk api-diff status` reported a missing
+ * baseline FILE named `status`. The guard judges only what a handler DECLARES,
+ * so a legitimate free positional (`task "add a thing"`) is never rejected:
+ *
+ *   - a pure command group + a bare token                → unknown subcommand;
+ *   - `positionals: None` + a token that names no subverb → unknown subcommand
+ *     (the closest match, and "`rules` is a command of its own" when it is);
+ *   - `positionals: Path` + a VERB-SHAPED token that is neither a subverb nor
+ *     an existing file → "has no `status` verb, and no file named `status`
+ *     exists", with the sibling commands that do have that verb;
+ *   - declared `flags` → any other flag (the global flags excepted).
+ *
+ * Every rejection exits `usageExitFor(path)` — 3 on a verdict verb, 2
+ * elsewhere — and never 0. The dispatcher calls it through
+ * `judgeInvocation`, which adds the undocumented-flag refusal; the
+ * command-string resolver calls the same function.
+ */
+export function guardInvocation(input) {
+    const { handler, matchedPath, parsed } = input;
+    if (matchedPath.length === 0)
+        return undefined;
+    if (!handler) {
+        const token = parsed.positional[0];
+        if (token === undefined)
+            return undefined;
+        return unknownSubcommand(input, matchedPath, token, input.trieChildren);
+    }
+    const walk = walkDeclaredSubverbs(handler, matchedPath, parsed.positional);
+    const token = parsed.positional[walk.consumed];
+    if (token !== undefined) {
+        const specs = walk.level.subverbs ?? [];
+        if (walk.level.positionals === PositionalMode.None) {
+            const names = [...specs.map((s) => s.name), ...(walk.consumed === 0 ? input.trieChildren : [])];
+            return unknownSubcommand(input, walk.path, token, names);
+        }
+        if (walk.level.positionals === PositionalMode.Path && isVerbShaped(token) && !namesAFile(input, token)) {
+            return noSuchVerbOrFile(input, walk.path, token, specs);
+        }
+    }
+    if (walk.flags) {
+        const bad = firstUnknownFlag(parsed, new Set([...walk.flags, ...GLOBAL_FLAGS]));
+        if (bad !== undefined)
+            return unknownFlag(walk.path, bad, walk.flags, parsed.argv);
+    }
+    return undefined;
+}
+const VERB_SHAPED = /^[a-z][a-z0-9-]*$/;
+/**
+ * A token that reads as a VERB, not a path: lowercase kebab starting with a
+ * letter — no `.`, `/`, `\`, `:`, `{`, `=` or uppercase. Inline JSON (`{…}`),
+ * `-` (stdin) and any real path fail it, so the Path rule never blocks them.
+ */
+export function isVerbShaped(token) {
+    return VERB_SHAPED.test(token);
+}
+function indexOf(input) {
+    return input.index ?? commandIndexFor(input.registry);
+}
+/** An existing file or directory under the invocation's cwd (none without a cwd). */
+function namesAFile(input, token) {
+    return input.cwd !== undefined && existsSync(nodePath.resolve(input.cwd, token));
+}
+function subcommandList(names) {
+    return [...new Set(names)].sort();
+}
+/** The closest real subcommands of `label`, as full invocations. */
+function closestSubcommands(label, token, names) {
+    return closestMatches(token, names, 3).map((c) => `shrk ${label} ${c}`);
+}
+function didYouMean(closest) {
+    if (closest.length === 0)
+        return '';
+    return `  Did you mean ${closest.map((c) => `\`${c}\``).join(' or ')}?\n`;
+}
+/** "`rules` is a command of its own: shrk rules add|doctor|…" — when it is. */
+function ownCommandHint(input, token) {
+    const own = input.registry.resolve([token]);
+    const head = own.matchedPath[0];
+    if (own.matchedPath.length !== 1 || head === undefined)
+        return '';
+    const subs = subverbNamesOf(indexOf(input), head);
+    const shown = subs.slice(0, 6).join('|');
+    const tail = subs.length === 0 ? '' : ` ${shown}${subs.length > 6 ? '|…' : ''}`;
+    return `  \`${token}\` is a command of its own: shrk ${head}${tail} — see \`shrk help ${head}\`.\n`;
+}
+/** "`status` is a verb of: shrk graph status, shrk context status, …" — from the index. */
+function siblingVerbHint(input, token) {
+    const owners = indexOf(input)
+        .entries.filter((e) => e.tokens.length > 1 && e.tokens[e.tokens.length - 1] === token)
+        .map((e) => `shrk ${e.path}`);
+    if (owners.length === 0)
+        return '';
+    const shown = owners.slice(0, 6);
+    const more = owners.length > shown.length ? ` (+${owners.length - shown.length} more)` : '';
+    return `  \`${token}\` is a verb of: ${shown.join(', ')}${more}\n`;
+}
+/**
+ * Subverbs that were REMOVED, keyed `<path> <token>`, and the command that
+ * replaced each — named in place of the own-command hint, so `commands explain
+ * doctor` never points at `shrk explain` (the knowledge / rule topic search) as
+ * if it described a command.
+ */
+const RETIRED_SUBVERBS = new Map([
+    ['commands suggest', 'shrk commands search "<partial>"'],
+    ['commands explain', 'shrk help <cmd>'],
+]);
+function unknownSubcommand(input, path, token, names) {
+    const label = path.join(' ');
+    const subs = subcommandList(names);
+    const closest = closestSubcommands(label, token, subs);
+    let message = `\`shrk ${label}\` has no \`${token}\` subcommand.\n`;
+    if (subs.length > 0)
+        message += `  Subcommands: ${subs.join(', ')}\n`;
+    message += didYouMean(closest);
+    const replacement = RETIRED_SUBVERBS.get(`${label} ${token}`);
+    message +=
+        replacement !== undefined
+            ? `  \`${token}\` was removed from \`shrk ${label}\` — use \`${replacement}\`.\n`
+            : ownCommandHint(input, token);
+    message += `  Run \`shrk help ${label}\` for usage.\n`;
+    return {
+        message,
+        exitCode: usageExitFor(label),
+        kind: InvocationRejectionKind.UnknownSubcommand,
+        ...(closest.length > 0 ? { closest } : {}),
+    };
+}
+function noSuchVerbOrFile(input, path, token, specs) {
+    const label = path.join(' ');
+    const closest = closestSubcommands(label, token, specs.map((s) => s.name));
+    let message = `\`shrk ${label}\` has no \`${token}\` verb, and no file named \`${token}\` exists.\n`;
+    if (specs.length > 0) {
+        message += '  Subcommands:\n';
+        for (const s of specs)
+            message += `    ${s.name} — ${(s.usage.split('\n')[0] ?? '').trim()}\n`;
+    }
+    message += didYouMean(closest);
+    message += siblingVerbHint(input, token);
+    message += `  Run \`shrk help ${label}\` for usage.\n`;
+    return {
+        message,
+        exitCode: usageExitFor(label),
+        kind: InvocationRejectionKind.NoSuchVerbOrFile,
+        ...(closest.length > 0 ? { closest } : {}),
+    };
+}
+/**
+ * A flag outside a DECLARED set, worded by THE one refusal format (round 13)
+ * — the same message the documentation refusal prints, plus the declared set
+ * as one `Accepts:` line. It printed `Unknown flag "--x" for \`shrk …\`` while
+ * every other refusal printed `--x is not a flag of this command`. A
+ * `--depth -1` misread names the flag the number was meant for; otherwise the
+ * flag is echoed as TYPED (the key alone cannot tell `--x` from `-x`).
+ */
+function unknownFlag(path, bad, declared, argv) {
+    const label = path.join(' ');
+    const listed = [...declared].filter((f) => !IMPLICIT_FLAGS.has(f));
+    return unknownFlagRefusal({
+        label,
+        flags: [bad],
+        known: listed,
+        accepts: listed,
+        ...(argv !== undefined ? { argv } : {}),
+        exitCode: usageExitFor(label),
+    });
+}

package/dist/dispatch/help-intercept.d.ts

@@ -0,0 +1,22 @@
+import type { ICommandIndex } from '../surface/i-command-index.js';
+/**
+ * `--help` / `-h` ANYWHERE in the leftover tokens — after a subverb, a
+ * positional or another flag — up to the POSIX `--` sentinel. Tokens after
+ * `--` are literal positionals (`shrk languages run -- --help` passes `--help`
+ * through untouched).
+ *
+ * Before round 11 only a LEADING `--help` was intercepted, so on every
+ * internally-dispatched subverb the command body ran instead: `report site
+ * --help` wrote twelve HTML files and `graph index --help` built the store.
+ */
+export declare function wantsHelp(tokens: readonly string[]): boolean;
+/**
+ * The help topic for an intercepted invocation: the matched trie path,
+ * extended through the leading bare tokens to the LONGEST path the command
+ * index knows (`graph importers foo --help` → `graph importers`;
+ * `bundle replay scaffold github-actions --help` → that whole row). An alias
+ * spelling resolves to its canonical entry. A token the index does not know
+ * leaves the topic at the deepest known path — help never invents one.
+ */
+export declare function helpTopicFor(index: ICommandIndex, matchedPath: readonly string[], leftover: readonly string[]): string[];
+//# sourceMappingURL=help-intercept.d.ts.map

package/dist/dispatch/help-intercept.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-intercept.d.ts","sourceRoot":"","sources":["../../src/dispatch/help-intercept.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,EAAE,CAaV"}

package/dist/dispatch/help-intercept.js

@@ -0,0 +1,42 @@
+/**
+ * `--help` / `-h` ANYWHERE in the leftover tokens — after a subverb, a
+ * positional or another flag — up to the POSIX `--` sentinel. Tokens after
+ * `--` are literal positionals (`shrk languages run -- --help` passes `--help`
+ * through untouched).
+ *
+ * Before round 11 only a LEADING `--help` was intercepted, so on every
+ * internally-dispatched subverb the command body ran instead: `report site
+ * --help` wrote twelve HTML files and `graph index --help` built the store.
+ */
+export function wantsHelp(tokens) {
+    for (const token of tokens) {
+        if (token === '--')
+            return false;
+        if (token === '--help' || token === '-h')
+            return true;
+    }
+    return false;
+}
+/**
+ * The help topic for an intercepted invocation: the matched trie path,
+ * extended through the leading bare tokens to the LONGEST path the command
+ * index knows (`graph importers foo --help` → `graph importers`;
+ * `bundle replay scaffold github-actions --help` → that whole row). An alias
+ * spelling resolves to its canonical entry. A token the index does not know
+ * leaves the topic at the deepest known path — help never invents one.
+ */
+export function helpTopicFor(index, matchedPath, leftover) {
+    const bare = [];
+    for (const token of leftover) {
+        if (token.startsWith('-'))
+            break;
+        bare.push(token);
+    }
+    for (let k = bare.length; k >= 1; k -= 1) {
+        const candidate = [...matchedPath, ...bare.slice(0, k)].join(' ');
+        const entry = index.byPath.get(candidate) ?? index.entries.find((e) => e.aliases.includes(candidate));
+        if (entry)
+            return [...entry.tokens];
+    }
+    return [...matchedPath];
+}

package/dist/dispatch/i-declared-invocation.d.ts

@@ -0,0 +1,17 @@
+import type { ISubverbSpec } from './subverb-spec.js';
+/**
+ * How far a handler's declarations explain an invocation's positionals: the
+ * walk descends through each positional that names a declared subverb (at any
+ * nesting depth) and stops at the first one that does not.
+ */
+export interface IDeclaredInvocation {
+    /** The trie path plus every declared subverb the positionals named (`search tuning explain`). */
+    readonly path: readonly string[];
+    /** The declaration the walk stopped at: the handler itself, or the deepest matched subverb. */
+    readonly level: Pick<ISubverbSpec, 'subverbs' | 'positionals' | 'flags' | 'usage'>;
+    /** How many positionals named declared subverbs; `positional[consumed]` is the first that did not. */
+    readonly consumed: number;
+    /** The union of every flag set declared along the walk; absent when none was declared. */
+    readonly flags?: ReadonlySet<string>;
+}
+//# sourceMappingURL=i-declared-invocation.d.ts.map

package/dist/dispatch/i-declared-invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-declared-invocation.d.ts","sourceRoot":"","sources":["../../src/dispatch/i-declared-invocation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC,CAAC;IACnF,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACtC"}

package/dist/dispatch/i-declared-invocation.js

@@ -0,0 +1 @@
+export {};

package/dist/dispatch/i-unknown-flag-refusal-input.d.ts

@@ -0,0 +1,28 @@
+import type { UnknownFlagRefusalMode } from './unknown-flag-refusal-mode.js';
+/** What {@link unknownFlagRefusal} needs to word one refused invocation. */
+export interface IUnknownFlagRefusalInput {
+    /** When the refusal happens (default {@link UnknownFlagRefusalMode.BeforeRun}). */
+    readonly mode?: UnknownFlagRefusalMode;
+    /**
+     * Per flag key, the OTHER command paths whose documentation names it (a
+     * sibling subverb) — worded `— only \`shrk check boundaries\` documents it`.
+     */
+    readonly documentedOn?: Readonly<Record<string, readonly string[]>>;
+    /** The walked command path (`gates check`, `self-config doctor`) — what the message and help pointer name. */
+    readonly label: string;
+    /** The parsed flag keys being refused, in the order they were supplied. */
+    readonly flags: readonly string[];
+    /** Flag names the command documents — the did-you-mean candidates. */
+    readonly known: readonly string[];
+    /**
+     * The command's complete DECLARED flag set, when it declares one (`gates
+     * check`, `check boundaries`) — printed as one `Accepts:` line. Absent for a
+     * command judged by its documentation.
+     */
+    readonly accepts?: readonly string[];
+    /** The argv the flags were parsed from — to name each flag as TYPED (`-x` vs `--x`). */
+    readonly argv?: readonly string[];
+    /** The exit the refusal returns: `usageExitFor(label)` — 3 on a verdict verb, 2 elsewhere. */
+    readonly exitCode: number;
+}
+//# sourceMappingURL=i-unknown-flag-refusal-input.d.ts.map

package/dist/dispatch/i-unknown-flag-refusal-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-unknown-flag-refusal-input.d.ts","sourceRoot":"","sources":["../../src/dispatch/i-unknown-flag-refusal-input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAE7E,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,sBAAsB,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACpE,8GAA8G;IAC9G,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,wFAAwF;IACxF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B"}

package/dist/dispatch/i-unknown-flag-refusal-input.js

@@ -0,0 +1 @@
+export {};

package/dist/dispatch/invocation-rejection-kind.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a pre-run refusal refused. The dispatcher prints the message either
+ * way; the command-string resolver maps the kind onto its own vocabulary
+ * (`UnknownSubverb` / `UnknownFlag`), so "does this command run?" is answered
+ * by the dispatcher's judgement, never by a parallel model of it.
+ */
+export declare enum InvocationRejectionKind {
+    /** A bare token under a command group, or under a `positionals: None` handler, that names no subverb. */
+    UnknownSubcommand = "unknown-subcommand",
+    /** `positionals: Path` + a verb-shaped token that is neither a subverb nor an existing file. */
+    NoSuchVerbOrFile = "no-such-verb-or-file",
+    /** A flag outside a declared set, or one no documentation of the command names. */
+    UnknownFlag = "unknown-flag"
+}
+//# sourceMappingURL=invocation-rejection-kind.d.ts.map

package/dist/dispatch/invocation-rejection-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-rejection-kind.d.ts","sourceRoot":"","sources":["../../src/dispatch/invocation-rejection-kind.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,uBAAuB;IACjC,yGAAyG;IACzG,iBAAiB,uBAAuB;IACxC,gGAAgG;IAChG,gBAAgB,yBAAyB;IACzC,mFAAmF;IACnF,WAAW,iBAAiB;CAC7B"}

package/dist/dispatch/invocation-rejection-kind.js

@@ -0,0 +1,15 @@
+/**
+ * What a pre-run refusal refused. The dispatcher prints the message either
+ * way; the command-string resolver maps the kind onto its own vocabulary
+ * (`UnknownSubverb` / `UnknownFlag`), so "does this command run?" is answered
+ * by the dispatcher's judgement, never by a parallel model of it.
+ */
+export var InvocationRejectionKind;
+(function (InvocationRejectionKind) {
+    /** A bare token under a command group, or under a `positionals: None` handler, that names no subverb. */
+    InvocationRejectionKind["UnknownSubcommand"] = "unknown-subcommand";
+    /** `positionals: Path` + a verb-shaped token that is neither a subverb nor an existing file. */
+    InvocationRejectionKind["NoSuchVerbOrFile"] = "no-such-verb-or-file";
+    /** A flag outside a declared set, or one no documentation of the command names. */
+    InvocationRejectionKind["UnknownFlag"] = "unknown-flag";
+})(InvocationRejectionKind || (InvocationRejectionKind = {}));

package/dist/dispatch/invocation-rejection.d.ts

@@ -0,0 +1,18 @@
+import type { InvocationRejectionKind } from './invocation-rejection-kind.js';
+/**
+ * Why the dispatcher refused an invocation BEFORE any command body ran — an
+ * unknown subcommand, a verb-shaped token that is neither a subverb nor an
+ * existing file, a flag outside a handler's declared set, or a flag no
+ * documentation of the command names.
+ */
+export interface IInvocationRejection {
+    /** The complete stderr text, newline-terminated. */
+    readonly message: string;
+    /** `usageExitFor(path)`: 3 on a verdict verb, 2 elsewhere. Never 0. */
+    readonly exitCode: number;
+    /** What was refused — the resolver maps it to a resolution status. */
+    readonly kind: InvocationRejectionKind;
+    /** The closest real invocations (`shrk templates list`, `shrk gates check --changed-only`), nearest first. */
+    readonly closest?: readonly string[];
+}
+//# sourceMappingURL=invocation-rejection.d.ts.map

package/dist/dispatch/invocation-rejection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-rejection.d.ts","sourceRoot":"","sources":["../../src/dispatch/invocation-rejection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,8GAA8G;IAC9G,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC"}

package/dist/dispatch/invocation-rejection.js

@@ -0,0 +1 @@
+export {};

package/dist/dispatch/judge-invocation.d.ts

@@ -0,0 +1,24 @@
+import type { IGuardInvocationInput } from './guard-invocation-input.js';
+import type { IInvocationRejection } from './invocation-rejection.js';
+/**
+ * THE pre-run judgement of one invocation — "would the dispatcher run this?":
+ *
+ *   1. {@link guardInvocation} — what the handler DECLARES (an unknown
+ *      subcommand, a verb-shaped token that is no subverb and no file, a flag
+ *      outside a declared set);
+ *   2. for a handler without a declared flag set (the post-run detector
+ *      tracks it), {@link refuseUndocumentedFlags} — a flag its documentation
+ *      does not name is refused before the body runs;
+ *   3. round 13 (K1), for the same handlers, {@link refuseSiblingValveFlags} —
+ *      a VERDICT-VALVE flag (`--fail-on-dead-units`, `--allow-empty`,
+ *      `--min-referenced`, `--fail-on`) the resolved subverb does not document
+ *      is refused before the body runs, naming the subverbs that accept it
+ *      (`shrk check --fail-on-dead-units` printed the whole sweep, then 3).
+ *
+ * `runCliInner` calls it before the surface gate and the command body, and the
+ * command-string resolver (`resolveCommandString`) calls the same function, so
+ * a string the resolver certifies is one the dispatcher runs — two code paths
+ * never answer "does this command run?" again (round 11 review CLI-1).
+ */
+export declare function judgeInvocation(input: IGuardInvocationInput): IInvocationRejection | undefined;
+//# sourceMappingURL=judge-invocation.d.ts.map

package/dist/dispatch/judge-invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge-invocation.d.ts","sourceRoot":"","sources":["../../src/dispatch/judge-invocation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,qBAAqB,GAAG,oBAAoB,GAAG,SAAS,CAwB9F"}

package/dist/dispatch/judge-invocation.js

@@ -0,0 +1,50 @@
+import { commandIndexFor } from "../surface/command-index.js";
+import { guardInvocation } from "./guard-invocation.js";
+import { refuseSiblingValveFlags } from "./refuse-sibling-valve-flags.js";
+import { refuseUndocumentedFlags, tracksFlagReads } from "./unread-flags.js";
+import { walkDeclaredSubverbs } from "./walk-declared-subverbs.js";
+/**
+ * THE pre-run judgement of one invocation — "would the dispatcher run this?":
+ *
+ *   1. {@link guardInvocation} — what the handler DECLARES (an unknown
+ *      subcommand, a verb-shaped token that is no subverb and no file, a flag
+ *      outside a declared set);
+ *   2. for a handler without a declared flag set (the post-run detector
+ *      tracks it), {@link refuseUndocumentedFlags} — a flag its documentation
+ *      does not name is refused before the body runs;
+ *   3. round 13 (K1), for the same handlers, {@link refuseSiblingValveFlags} —
+ *      a VERDICT-VALVE flag (`--fail-on-dead-units`, `--allow-empty`,
+ *      `--min-referenced`, `--fail-on`) the resolved subverb does not document
+ *      is refused before the body runs, naming the subverbs that accept it
+ *      (`shrk check --fail-on-dead-units` printed the whole sweep, then 3).
+ *
+ * `runCliInner` calls it before the surface gate and the command body, and the
+ * command-string resolver (`resolveCommandString`) calls the same function, so
+ * a string the resolver certifies is one the dispatcher runs — two code paths
+ * never answer "does this command run?" again (round 11 review CLI-1).
+ */
+export function judgeInvocation(input) {
+    const rejection = guardInvocation(input);
+    if (rejection !== undefined || input.handler === undefined || input.matchedPath.length === 0)
+        return rejection;
+    const handler = input.handler;
+    const walk = walkDeclaredSubverbs(handler, input.matchedPath, input.parsed.positional);
+    if (!tracksFlagReads(handler, walk))
+        return undefined;
+    // One lazily built index for both refusals — the common run pays nothing.
+    let built = input.index;
+    const index = () => (built ??= commandIndexFor(input.registry));
+    return (refuseUndocumentedFlags({
+        handler,
+        matchedPath: input.matchedPath,
+        label: walk.path.join(' '),
+        parsed: input.parsed,
+        index,
+    }) ??
+        refuseSiblingValveFlags({
+            handler,
+            matchedPath: input.matchedPath,
+            parsed: input.parsed,
+            index,
+        }));
+}

package/dist/dispatch/positional-mode.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What a handler's `positional[0]` means when it is NOT one of its subverbs.
+ *
+ * Declared opt-in on {@link ICommandHandler.positionals}; `undefined` means
+ * legacy (unchecked). The command index and the command-string resolver read
+ * it: only a handler that declares `None` can prove an unknown bare token is an
+ * unknown subverb rather than a legitimate free positional.
+ *
+ *   - `None` — every positional[0] must be a declared subverb.
+ *   - `Free` — any other token is a free positional (a query, an id).
+ *   - `Path` — any other token is a file path.
+ */
+export declare enum PositionalMode {
+    None = "none",
+    Free = "free",
+    Path = "path"
+}
+//# sourceMappingURL=positional-mode.d.ts.map

package/dist/dispatch/positional-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positional-mode.d.ts","sourceRoot":"","sources":["../../src/dispatch/positional-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;CACd"}

package/dist/dispatch/positional-mode.js

@@ -0,0 +1,18 @@
+/**
+ * What a handler's `positional[0]` means when it is NOT one of its subverbs.
+ *
+ * Declared opt-in on {@link ICommandHandler.positionals}; `undefined` means
+ * legacy (unchecked). The command index and the command-string resolver read
+ * it: only a handler that declares `None` can prove an unknown bare token is an
+ * unknown subverb rather than a legitimate free positional.
+ *
+ *   - `None` — every positional[0] must be a declared subverb.
+ *   - `Free` — any other token is a free positional (a query, an id).
+ *   - `Path` — any other token is a file path.
+ */
+export var PositionalMode;
+(function (PositionalMode) {
+    PositionalMode["None"] = "none";
+    PositionalMode["Free"] = "free";
+    PositionalMode["Path"] = "path";
+})(PositionalMode || (PositionalMode = {}));

package/dist/dispatch/read-tracking-map.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A `Map` that records which keys were READ — the substrate of the dispatcher's
+ * post-run unknown-flag detector.
+ *
+ * `runCliInner` swaps `parsed.flags` / `parsed.multiFlags` for tracking copies
+ * before a handler runs; afterwards, a supplied flag the handler never read was
+ * silently dropped. `get` / `has` / `delete` mark one key. Any whole-map read
+ * (iteration, spread, `forEach`, `keys`, `values`, `entries`) marks EVERY key,
+ * so a handler that forwards or copies its flags is never accused of ignoring
+ * them — the detector errs toward silence, never toward a false rejection.
+ */
+export declare class ReadTrackingMap<K, V> extends Map<K, V> {
+    private readonly readKeys;
+    private everyKeyRead;
+    /** A tracking copy of `source`: its entries, nothing marked read yet. */
+    static from<K, V>(source: ReadonlyMap<K, V>): ReadTrackingMap<K, V>;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    keys(): MapIterator<K>;
+    values(): MapIterator<V>;
+    entries(): MapIterator<[K, V]>;
+    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: unknown): void;
+    [Symbol.iterator](): MapIterator<[K, V]>;
+    /** True when `key` was read — individually, or by a whole-map read. */
+    wasRead(key: K): boolean;
+}
+//# sourceMappingURL=read-tracking-map.d.ts.map

package/dist/dispatch/read-tracking-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tracking-map.d.ts","sourceRoot":"","sources":["../../src/dispatch/read-tracking-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,eAAe,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,YAAY,CAAS;IAE7B,yEAAyE;IACzE,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;IAM1D,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAK1B,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAKpB,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAKvB,IAAI;IAKJ,MAAM;IAKN,OAAO;IAKP,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAKxF,CAAC,MAAM,CAAC,QAAQ,CAAC;IAK1B,uEAAuE;IACvE,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;CAGzB"}

package/dist/dispatch/read-tracking-map.js

@@ -0,0 +1,58 @@
+/**
+ * A `Map` that records which keys were READ — the substrate of the dispatcher's
+ * post-run unknown-flag detector.
+ *
+ * `runCliInner` swaps `parsed.flags` / `parsed.multiFlags` for tracking copies
+ * before a handler runs; afterwards, a supplied flag the handler never read was
+ * silently dropped. `get` / `has` / `delete` mark one key. Any whole-map read
+ * (iteration, spread, `forEach`, `keys`, `values`, `entries`) marks EVERY key,
+ * so a handler that forwards or copies its flags is never accused of ignoring
+ * them — the detector errs toward silence, never toward a false rejection.
+ */
+export class ReadTrackingMap extends Map {
+    readKeys = new Set();
+    everyKeyRead = false;
+    /** A tracking copy of `source`: its entries, nothing marked read yet. */
+    static from(source) {
+        const out = new ReadTrackingMap();
+        for (const [key, value] of source)
+            out.set(key, value);
+        return out;
+    }
+    get(key) {
+        this.readKeys.add(key);
+        return super.get(key);
+    }
+    has(key) {
+        this.readKeys.add(key);
+        return super.has(key);
+    }
+    delete(key) {
+        this.readKeys.add(key);
+        return super.delete(key);
+    }
+    keys() {
+        this.everyKeyRead = true;
+        return super.keys();
+    }
+    values() {
+        this.everyKeyRead = true;
+        return super.values();
+    }
+    entries() {
+        this.everyKeyRead = true;
+        return super.entries();
+    }
+    forEach(callbackfn, thisArg) {
+        this.everyKeyRead = true;
+        super.forEach(callbackfn, thisArg);
+    }
+    [Symbol.iterator]() {
+        this.everyKeyRead = true;
+        return super[Symbol.iterator]();
+    }
+    /** True when `key` was read — individually, or by a whole-map read. */
+    wasRead(key) {
+        return this.everyKeyRead || this.readKeys.has(key);
+    }
+}