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

package/dist/asset-preview/apply-asset-preview.js

@@ -188,7 +188,7 @@ export function applyAssetPreview(input) {
         rules: 'shrk rules lint',
         paths: 'shrk paths list',
         templates: 'shrk templates drift --min-severity warning',
-        pipelines: 'shrk pipelines lint',
+        pipelines: 'shrk check pipelines',
         boundaries: 'shrk check boundaries --changed-only',
         presets: 'shrk presets list --json',
     };

package/dist/authoring/authoring-kit.d.ts

@@ -1,4 +1,4 @@
-import type { IKnowledgeReference } from '@shrkcrft/knowledge';
+import { type IKnowledgeReference } from '@shrkcrft/knowledge';
 import { AssetProvenanceSource } from '@shrkcrft/inspector';
 import { type ParsedArgs } from '../command-registry.js';
 export interface IAuthoringSource {
@@ -31,6 +31,14 @@ export declare function multiFlagValues(args: ParsedArgs, name: string): string[
 /**
  * Parse a `kind:value[:required]` reference spec. Returns null on
  * invalid input so callers can filter.
+ *
+ * A symbol may pin its declaring file — `symbol:<name>@<path>` — and address a
+ * member — `symbol:Owner.member@<path>`. This is the inverse of
+ * `formatKnowledgeReference`, so what the stale-check prints can be pasted
+ * back as a `--reference`.
+ *
+ * The accepted kinds are {@link KNOWLEDGE_REFERENCE_KINDS} — the one
+ * vocabulary the validator and the stale-check read — never a hand-copied list.
  */
 export declare function parseReferenceSpec(spec: string): IKnowledgeReference | null;
 //# sourceMappingURL=authoring-kit.d.ts.map

package/dist/authoring/authoring-kit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authoring-kit.d.ts","sourceRoot":"","sources":["../../src/authoring/authoring-kit.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EACL,qBAAqB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAgBxD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACnD,MAAM,EAAE,CAiBV;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAExE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CA6B3E"}
+{"version":3,"file":"authoring-kit.d.ts","sourceRoot":"","sources":["../../src/authoring/authoring-kit.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,qBAAqB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAgBxD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACnD,MAAM,EAAE,CAiBV;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAExE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAgC3E"}

package/dist/authoring/authoring-kit.js

@@ -16,6 +16,7 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { KNOWLEDGE_REFERENCE_KINDS, } from '@shrkcrft/knowledge';
 import { AssetProvenanceSource, } from '@shrkcrft/inspector';
 import { flagList } from "../command-registry.js";
 /**
@@ -70,12 +71,22 @@ export function multiFlagValues(args, name) {
 /**
  * Parse a `kind:value[:required]` reference spec. Returns null on
  * invalid input so callers can filter.
+ *
+ * A symbol may pin its declaring file — `symbol:<name>@<path>` — and address a
+ * member — `symbol:Owner.member@<path>`. This is the inverse of
+ * `formatKnowledgeReference`, so what the stale-check prints can be pasted
+ * back as a `--reference`.
+ *
+ * The accepted kinds are {@link KNOWLEDGE_REFERENCE_KINDS} — the one
+ * vocabulary the validator and the stale-check read — never a hand-copied list.
  */
 export function parseReferenceSpec(spec) {
     const parts = spec.split(':');
     if (parts.length < 2)
         return null;
     const [kindRaw, ...rest] = parts;
+    if (!KNOWLEDGE_REFERENCE_KINDS.includes(kindRaw))
+        return null;
     const kind = kindRaw;
     const required = rest[rest.length - 1] === 'required';
     if (required)
@@ -87,20 +98,22 @@ export function parseReferenceSpec(spec) {
         case 'file':
         case 'directory':
             return { kind, path: value, ...(required ? { required: true } : {}) };
-        case 'symbol':
+        case 'symbol': {
+            // `Name@path` pins the declaring file (a symbol name never contains `@`).
+            const at = value.indexOf('@');
+            if (at > 0 && at < value.length - 1) {
+                return {
+                    kind,
+                    symbol: value.slice(0, at),
+                    path: value.slice(at + 1),
+                    ...(required ? { required: true } : {}),
+                };
+            }
             return { kind, symbol: value, ...(required ? { required: true } : {}) };
-        case 'command':
-        case 'template':
-        case 'playbook':
-        case 'construct':
-        case 'helper':
-        case 'policy':
-        case 'boundary-rule':
-        case 'path-convention':
-        case 'package':
-        case 'url':
-            return { kind, id: value, ...(required ? { required: true } : {}) };
+        }
         default:
-            return null;
+            // Every other kind in the vocabulary is id-keyed (a command, a registry
+            // id, a url) — a kind added to the vocabulary is accepted here at once.
+            return { kind, id: value, ...(required ? { required: true } : {}) };
     }
 }

package/dist/bootstrap/unlinked-workspace-dependency.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The one-line message for an unlinked workspace dependency, or `undefined`
+ * for any other error. Pure over its inputs: `locate` maps the importing file
+ * to the package that needs the dependency and the directory the install runs
+ * in; the default reads the nearest package.json files on disk.
+ */
+export declare function unlinkedWorkspaceDependencyMessage(error: unknown, locate?: (importerFile: string) => {
+    readonly packageName?: string;
+    readonly toolRoot: string;
+}): string | undefined;
+//# sourceMappingURL=unlinked-workspace-dependency.d.ts.map

package/dist/bootstrap/unlinked-workspace-dependency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlinked-workspace-dependency.d.ts","sourceRoot":"","sources":["../../src/bootstrap/unlinked-workspace-dependency.ts"],"names":[],"mappings":"AAgCA;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,EACd,MAAM,GAAE,CAAC,YAAY,EAAE,MAAM,KAAK;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAkB,GAC7G,MAAM,GAAG,SAAS,CAepB"}

package/dist/bootstrap/unlinked-workspace-dependency.js

@@ -0,0 +1,99 @@
+/**
+ * The bin bootstrap's one diagnosis (round 13, 13.2): is this load failure a
+ * workspace dependency of the installed tool that is not linked?
+ *
+ * A missing `@shrkcrft/*` link kills the emitted CLI (and the MCP server) at
+ * ESM LINK time — before `main.js` evaluates a line, so its `Fatal:` handler
+ * never runs and Node prints a raw resolver stack naming a `dist/` file. The
+ * bootstrap dynamic-imports the entry, and this function turns that one error
+ * into the sentence the build's link check prints (scripts/lib/workspace-links.ts):
+ *
+ *   shrk: workspace dependency @shrkcrft/x (needed by @shrkcrft/y) is not linked — run `bun install` in <root>
+ *
+ * Two real shapes are recognised: Node's `Cannot find package '@shrkcrft/x'
+ * imported from <file>`, and Bun's `Cannot find module '@shrkcrft/x' from
+ * '<file>'` — a bare package name only, because Bun reports a missing SUBPATH
+ * of a linked package the same way. Anything else returns `undefined`, and the
+ * bootstrap rethrows it untouched.
+ *
+ * node: builtins ONLY — never an `@shrkcrft` import, not even core: the package
+ * it would import could be the one whose link is missing. That is also why the
+ * MCP server carries a byte-identical copy of this file instead of importing
+ * it; r77-bootstrap-rewrite.test.ts locks the two copies together.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Node: the package directory itself was not found from the importing file. */
+const NODE_UNLINKED = /^Cannot find package '(@shrkcrft\/[^'/]+)' imported from (.+)$/;
+/** Bun: honoured for a bare package name only (see the module comment). */
+const BUN_UNLINKED = /^Cannot find module '(@shrkcrft\/[^'/]+)' from '(.+)'$/;
+/**
+ * The one-line message for an unlinked workspace dependency, or `undefined`
+ * for any other error. Pure over its inputs: `locate` maps the importing file
+ * to the package that needs the dependency and the directory the install runs
+ * in; the default reads the nearest package.json files on disk.
+ */
+export function unlinkedWorkspaceDependencyMessage(error, locate = locateInstall) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const { code, message } = error;
+    if (code !== 'ERR_MODULE_NOT_FOUND' || typeof message !== 'string')
+        return undefined;
+    const firstLine = message.split('\n', 1)[0] ?? '';
+    const match = NODE_UNLINKED.exec(firstLine) ?? BUN_UNLINKED.exec(firstLine);
+    const dependency = match?.[1];
+    const importer = match?.[2];
+    if (dependency === undefined || importer === undefined)
+        return undefined;
+    const importerFile = importer.startsWith('file:') ? fileURLToPath(importer) : importer;
+    const { packageName, toolRoot } = locate(importerFile);
+    return (`shrk: workspace dependency ${dependency} (needed by ${packageName ?? importerFile}) ` +
+        `is not linked — run \`bun install\` in ${toolRoot}`);
+}
+/** The package owning `importerFile` (its nearest package.json) and where its install runs. */
+function locateInstall(importerFile) {
+    for (let dir = dirname(importerFile);;) {
+        const manifest = readManifest(join(dir, 'package.json'));
+        if (manifest !== undefined) {
+            const toolRoot = installRootOf(dir);
+            return typeof manifest.name === 'string' ? { packageName: manifest.name, toolRoot } : { toolRoot };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return { toolRoot: dirname(importerFile) };
+        dir = parent;
+    }
+}
+/**
+ * Where the install that links `packageDir`'s dependencies runs: the directory
+ * holding the OUTERMOST `node_modules` when the package is installed (a
+ * consumer repo, a global prefix), else the nearest workspace root — a
+ * package.json declaring `workspaces`, i.e. the tool's own checkout.
+ */
+function installRootOf(packageDir) {
+    const at = packageDir.indexOf(`${sep}node_modules${sep}`);
+    if (at >= 0)
+        return at === 0 ? sep : packageDir.slice(0, at);
+    for (let dir = packageDir;;) {
+        const manifest = readManifest(join(dir, 'package.json'));
+        if (manifest?.workspaces !== undefined)
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return packageDir;
+        dir = parent;
+    }
+}
+/** A package.json's fields, `{}` when it exists but does not parse, `undefined` when absent. */
+function readManifest(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/command-registry.d.ts

@@ -1,3 +1,5 @@
+import type { PositionalMode } from './dispatch/positional-mode.js';
+import type { ISubverbSpec } from './dispatch/subverb-spec.js';
 export interface ParsedArgs {
     positional: string[];
     flags: Map<string, string | boolean>;
@@ -5,6 +7,14 @@ export interface ParsedArgs {
     multiFlags: Map<string, string[]>;
     /** Resolved global cwd (absolute), if --cwd was passed at the top level. */
     globalCwd?: string;
+    /**
+     * The tokens `parseArgs` read, verbatim — how each flag was SPELLED, which
+     * the parsed map cannot tell (`--x` and `-x` both key `x`; `--offset -1`
+     * leaves `offset` valueless and keys `1`). Set by `parseArgs`; absent on a
+     * hand-built ParsedArgs. Read it through {@link spellFlagAsTyped} /
+     * {@link misreadValueHint}.
+     */
+    argv?: readonly string[];
 }
 export interface ICommandHandler {
     name: string;
@@ -18,6 +28,34 @@ export interface ICommandHandler {
      * naturally emits). Optional; commands without it parse exactly as before.
      */
     booleanFlags?: ReadonlySet<string>;
+    /**
+     * Subverbs this handler dispatches internally from `positional[0]`
+     * (`shrk check wiring`). Opt-in: the command index lists each as a
+     * first-class command, and — with `positionals: PositionalMode.None` — the
+     * command-string resolver can prove an unknown bare token is an unknown
+     * subverb instead of a free positional.
+     */
+    subverbs?: readonly ISubverbSpec[];
+    /**
+     * What a `positional[0]` that is not a subverb means. `undefined` = legacy
+     * (unchecked): an unknown tail is reported `prefix-only`, never flagged.
+     */
+    positionals?: PositionalMode;
+    /**
+     * The COMPLETE accepted flag set, when declared. The dispatcher refuses any
+     * other flag BEFORE the handler runs (`usageExitFor`: 3 on a verdict verb, 2
+     * elsewhere), so a typo can never read as an opt-in; the global flags
+     * (`dispatch/global-flags.ts`) are always accepted on top. A declared
+     * subverb's `flags` add to it. Undeclared = the post-run read-tracking
+     * detector judges instead.
+     */
+    flags?: ReadonlySet<string>;
+    /**
+     * The handler re-executes `process.argv` in a child process, so the flags it
+     * uses are read by the child: the post-run read-tracking detector must not
+     * judge this process's parse.
+     */
+    forwardsArgv?: boolean;
     run(args: ParsedArgs): Promise<number> | number;
 }
 /**
@@ -37,6 +75,13 @@ export interface ICommandResolution {
     handler?: ICommandHandler;
     /** The canonical segments that matched (aliases already resolved). */
     matchedPath: string[];
+    /**
+     * The same segments as the user SPELLED them (an alias stays an alias), the
+     * global flags the descent stepped over removed. `[...matchedTokens, ...rest]`
+     * is the argv with its command path first — the view the verdict path and
+     * the usage record read (`withoutPathGlobals`).
+     */
+    matchedTokens: string[];
     /** Tokens left over after the descent stopped (passed to the handler). */
     rest: string[];
     /** The trie node where the descent stopped — useful for help/suggestions. */
@@ -101,8 +146,27 @@ export declare class CommandRegistry {
      *
      * Returns the deepest node's handler, the canonical path that matched,
      * and the remaining tokens (passed to the handler).
+     *
+     * `options.transparent` names flag tokens the descent may step OVER instead
+     * of stopping at (the dispatcher's global `--strict` / `--no-hints`) — only
+     * while they sit INSIDE the command path. A run of them is stepped over when
+     * the token after it continues the path (a child or child alias of the
+     * current node, or a subverb its handler declares); the run is hoisted into
+     * `rest` before any `--` sentinel, so the handler still sees it. So
+     * `shrk --no-hints scaffolds list` resolves `scaffolds list` and
+     * `shrk check --strict wiring` keeps `wiring` as the subverb.
+     *
+     * Past the path, a token `options.bindsValue` names (the bare `--strict`,
+     * which `doctor` reads as `--strict <level>`) stays exactly where it is, in
+     * front of its value: `doctor --strict warnings` leaves `['--strict',
+     * 'warnings']`, never a positional `warnings`. A self-contained one
+     * (`--no-hints`, `--strict=<level>`) is still moved out of the way, so it
+     * never swallows the positional after it (`task --no-hints "add a thing"`).
      */
-    resolve(tokens: readonly string[]): ICommandResolution;
+    resolve(tokens: readonly string[], options?: {
+        readonly transparent?: (token: string) => boolean;
+        readonly bindsValue?: (token: string) => boolean;
+    }): ICommandResolution;
     private descend;
     private collectAll;
 }
@@ -113,6 +177,21 @@ export interface ParseArgsOptions {
     booleanFlags?: ReadonlySet<string>;
 }
 export declare function parseArgs(argv: readonly string[], options?: ParseArgsOptions): ParsedArgs;
+/**
+ * How the user SPELLED a parsed flag. The parser keys `--x` and `-x` alike as
+ * `x`, so a message that inferred the dashes from the key's length named a
+ * flag nobody typed (`graph cycles --x` → `Unknown flag "-x"`). Reads the argv
+ * `parseArgs` kept; without it, the conventional spelling (`-k` for one letter).
+ */
+export declare function spellFlagAsTyped(key: string, argv: readonly string[] | undefined): string;
+/**
+ * `--offset -1`: a flag value never starts with `-`, so `parseArgs` reads `-1`
+ * as a flag of its own and leaves `--offset` valueless. A refusal that said
+ * "-1 is not a flag" named the wrong problem; this names the flag the number
+ * was meant for, and the `=` spelling that passes it as the value. `undefined`
+ * unless `key` is numeric and its token directly follows a value-less `--flag`.
+ */
+export declare function misreadValueHint(key: string, argv: readonly string[] | undefined): string | undefined;
 /**
  * Extracts `--cwd <value>` / `--cwd=<value>` from anywhere in argv. Used as a
  * pre-pass before command dispatch so a user can write `shrk --cwd ./repo doctor`.
@@ -160,6 +239,26 @@ export declare function extractGlobalExitTrailer(argv: readonly string[]): {
 export declare function resolveCwd(args: ParsedArgs): string;
 export declare function flagString(args: ParsedArgs, name: string): string | undefined;
 export declare function flagBool(args: ParsedArgs, name: string): boolean;
+/**
+ * The guard for a per-item query verb whose input SELECTOR is required
+ * (`tests missing --files a,b`). Without it, "you gave me nothing to check"
+ * rendered as "I checked and found nothing": zero bytes, exit 0.
+ *
+ * Returns `null` when any listed flag (or, with `positional: true`, any
+ * positional) was passed; otherwise writes the usage line and the accepted
+ * selectors to stderr and returns `3` — the request itself was malformed.
+ */
+export declare function requireInputSelector(args: ParsedArgs, spec: {
+    readonly flags: readonly string[];
+    readonly positional?: boolean;
+    readonly usage: string;
+}): number | null;
+/**
+ * A selector WAS given but resolved to 0 files (`--since HEAD` on a clean
+ * tree): nothing was analysed, so the answer is `2` (not verified) — never a
+ * confident empty result. `--json` gets a parseable object saying so.
+ */
+export declare function emptySelectionExit(wantJson: boolean): number;
 export declare function flagNumber(args: ParsedArgs, name: string): number | undefined;
 /**
  * Parse a `--limit`/`--depth`-style flag as a positive integer, falling back to

package/dist/command-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-registry.d.ts","sourceRoot":"","sources":["../src/command-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACrC,0EAA0E;IAC1E,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,UAAU,gBAAgB;IACxB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAgBD,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,sEAAsE;IACtE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,6EAA6E;IAC7E,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoC;IACzD,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAE5D,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAIxC,0DAA0D;IAC1D,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAIjE;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAgBnE,qCAAqC;IACrC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAKlD,uCAAuC;IACvC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAKpD,iEAAiE;IACjE,OAAO,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAa9E,gCAAgC;IAChC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAK9C,8BAA8B;IAC9B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAOhE,8DAA8D;IAC9D,KAAK,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,GAAG,SAAS;IAK3D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAInC,UAAU,IAAI,SAAS,MAAM,EAAE;IAW/B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE;IAWpD,2EAA2E;IAC3E,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE;IAUzD,gBAAgB,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;IAI/C,kBAAkB,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;IAIjD,gDAAgD;IAChD,IAAI,IAAI,SAAS,eAAe,EAAE;IAQlC,oDAAoD;IACpD,OAAO,IAAI,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;KAAE,CAAC;IAMjG;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CACL,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,GAAE;QACP,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;KAC7C,GACL,kBAAkB;IAgDrB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,UAAU;CAWnB;AAQD,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,UAAU,CA6C7F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,CAOzF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAMrG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CA+BA;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAC9D,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAkEA;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAgBA;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAKnD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjG,MAAM,GAAG,IAAI,CAaf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAQ5D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;CACrC;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,MAAM,EAAE,CAkCV;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,MAAM,GAAG,SAAS,CAKpB"}

package/dist/command-registry.js

@@ -2,6 +2,17 @@ import * as nodePath from 'node:path';
 function makeTrieNode() {
     return { children: new Map(), aliases: new Map() };
 }
+/**
+ * Does `token` continue the command path below `node` — a trie child (or child
+ * alias), or a subverb the node's handler declares (`check wiring`)?
+ */
+function continuesPath(node, token) {
+    if (token.startsWith('-'))
+        return false;
+    if (node.children.has(node.aliases.get(token) ?? token))
+        return true;
+    return node.handler?.subverbs?.some((s) => s.name === token || s.aliases?.includes(token) === true) === true;
+}
 /**
  * Trie-backed command registry. Supports N-level dispatch
  * (`shrk pack author status`) while keeping the historical 1- and 2-level
@@ -153,13 +164,48 @@ export class CommandRegistry {
      *
      * Returns the deepest node's handler, the canonical path that matched,
      * and the remaining tokens (passed to the handler).
+     *
+     * `options.transparent` names flag tokens the descent may step OVER instead
+     * of stopping at (the dispatcher's global `--strict` / `--no-hints`) — only
+     * while they sit INSIDE the command path. A run of them is stepped over when
+     * the token after it continues the path (a child or child alias of the
+     * current node, or a subverb its handler declares); the run is hoisted into
+     * `rest` before any `--` sentinel, so the handler still sees it. So
+     * `shrk --no-hints scaffolds list` resolves `scaffolds list` and
+     * `shrk check --strict wiring` keeps `wiring` as the subverb.
+     *
+     * Past the path, a token `options.bindsValue` names (the bare `--strict`,
+     * which `doctor` reads as `--strict <level>`) stays exactly where it is, in
+     * front of its value: `doctor --strict warnings` leaves `['--strict',
+     * 'warnings']`, never a positional `warnings`. A self-contained one
+     * (`--no-hints`, `--strict=<level>`) is still moved out of the way, so it
+     * never swallows the positional after it (`task --no-hints "add a thing"`).
      */
-    resolve(tokens) {
+    resolve(tokens, options = {}) {
         let node = this.root;
         const matched = [];
+        const spelled = [];
+        const hoisted = [];
+        const kept = [];
+        const isTransparent = (t) => t !== undefined && t !== '--' && options.transparent?.(t) === true;
         let i = 0;
         while (i < tokens.length) {
             const t = tokens[i];
+            if (isTransparent(t)) {
+                let end = i;
+                while (isTransparent(tokens[end]))
+                    end += 1;
+                const run = tokens.slice(i, end);
+                i = end;
+                const next = tokens[i];
+                if (next !== undefined && continuesPath(node, next)) {
+                    hoisted.push(...run);
+                    continue;
+                }
+                for (const flag of run)
+                    (options.bindsValue?.(flag) === true ? kept : hoisted).push(flag);
+                break;
+            }
             if (t.startsWith('-'))
                 break;
             const canonical = node.aliases.get(t) ?? t;
@@ -168,12 +214,22 @@ export class CommandRegistry {
                 break;
             node = child;
             matched.push(canonical);
+            spelled.push(t);
             i += 1;
         }
+        const rest = [...kept, ...tokens.slice(i)];
+        if (hoisted.length > 0) {
+            const sentinel = rest.indexOf('--');
+            if (sentinel === -1)
+                rest.push(...hoisted);
+            else
+                rest.splice(sentinel, 0, ...hoisted);
+        }
         return {
             handler: node.handler,
             matchedPath: matched,
-            rest: tokens.slice(i),
+            matchedTokens: spelled,
+            rest,
             node,
         };
     }
@@ -248,11 +304,44 @@ export function parseArgs(argv, options = {}) {
             positional.push(arg);
         }
     }
-    const out = { positional, flags, multiFlags };
+    const out = { positional, flags, multiFlags, argv: [...argv] };
     if (options.globalCwd)
         out.globalCwd = options.globalCwd;
     return out;
 }
+/**
+ * How the user SPELLED a parsed flag. The parser keys `--x` and `-x` alike as
+ * `x`, so a message that inferred the dashes from the key's length named a
+ * flag nobody typed (`graph cycles --x` → `Unknown flag "-x"`). Reads the argv
+ * `parseArgs` kept; without it, the conventional spelling (`-k` for one letter).
+ */
+export function spellFlagAsTyped(key, argv) {
+    for (const token of argv ?? []) {
+        if (token === '--')
+            break;
+        if (token === `--${key}` || token.startsWith(`--${key}=`))
+            return `--${key}`;
+        if (token === `-${key}`)
+            return `-${key}`;
+    }
+    return `${key.length === 1 ? '-' : '--'}${key}`;
+}
+/**
+ * `--offset -1`: a flag value never starts with `-`, so `parseArgs` reads `-1`
+ * as a flag of its own and leaves `--offset` valueless. A refusal that said
+ * "-1 is not a flag" named the wrong problem; this names the flag the number
+ * was meant for, and the `=` spelling that passes it as the value. `undefined`
+ * unless `key` is numeric and its token directly follows a value-less `--flag`.
+ */
+export function misreadValueHint(key, argv) {
+    if (argv === undefined || !/^\d+(?:\.\d+)?$/.test(key))
+        return undefined;
+    const at = argv.indexOf(`-${key}`);
+    const owner = at > 0 ? argv[at - 1] : undefined;
+    if (owner === undefined || owner === '--' || !owner.startsWith('--') || owner.includes('='))
+        return undefined;
+    return `-${key} was read as a flag, not as the value of ${owner} — a flag value cannot start with "-" (${owner}=-${key} passes it as the value)`;
+}
 /**
  * Extracts `--cwd <value>` / `--cwd=<value>` from anywhere in argv. Used as a
  * pre-pass before command dispatch so a user can write `shrk --cwd ./repo doctor`.
@@ -414,6 +503,44 @@ export function flagBool(args, name) {
     const v = args.flags.get(name);
     return v === true || v === 'true';
 }
+/**
+ * The guard for a per-item query verb whose input SELECTOR is required
+ * (`tests missing --files a,b`). Without it, "you gave me nothing to check"
+ * rendered as "I checked and found nothing": zero bytes, exit 0.
+ *
+ * Returns `null` when any listed flag (or, with `positional: true`, any
+ * positional) was passed; otherwise writes the usage line and the accepted
+ * selectors to stderr and returns `3` — the request itself was malformed.
+ */
+export function requireInputSelector(args, spec) {
+    const given = spec.flags.some((f) => {
+        const v = args.flags.get(f);
+        return v !== undefined && v !== false && v !== '';
+    });
+    if (given || (spec.positional === true && args.positional.length > 0))
+        return null;
+    const selectors = spec.flags.map((f) => `--${f}`).join('/');
+    const hint = selectors.length === 0
+        ? 'pass a positional argument'
+        : `pass one of ${selectors}${spec.positional ? ' (or a positional argument)' : ''}`;
+    process.stderr.write(`Usage: ${spec.usage}\n  no input selected — ${hint}\n`);
+    return 3;
+}
+/**
+ * A selector WAS given but resolved to 0 files (`--since HEAD` on a clean
+ * tree): nothing was analysed, so the answer is `2` (not verified) — never a
+ * confident empty result. `--json` gets a parseable object saying so.
+ */
+export function emptySelectionExit(wantJson) {
+    const reason = '0 files selected — nothing analysed';
+    if (wantJson) {
+        process.stdout.write(`${JSON.stringify({ files: [], analysed: false, reason, exitCode: 2 })}\n`);
+    }
+    else {
+        process.stderr.write(`${reason} (not verified).\n`);
+    }
+    return 2;
+}
 export function flagNumber(args, name) {
     const v = args.flags.get(name);
     if (typeof v !== 'string')

package/dist/commands/api-diff.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-diff.command.d.ts","sourceRoot":"","sources":["../../src/commands/api-diff.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,eAoB5B,CAAC"}
+{"version":3,"file":"api-diff.command.d.ts","sourceRoot":"","sources":["../../src/commands/api-diff.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,eA+B5B,CAAC"}

package/dist/commands/api-diff.command.js

@@ -3,6 +3,7 @@ import * as nodePath from 'node:path';
 import { diffApiSurfaces, extractApiSurface, extractApiSurfaceWithProgram, } from '@shrkcrft/api-surface-diff';
 import { GraphStore } from '@shrkcrft/graph';
 import { flagBool, flagList, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 /**
  * `shrk api-diff` — compare the current code-graph's public-API
@@ -14,6 +15,17 @@ import { asJson, header, kv } from "../output/format-output.js";
  */
 export const apiDiffCommand = {
     name: 'api-diff',
+    // positional[0] is `capture` or the baseline FILE: a verb-shaped token that
+    // is neither (`api-diff status`) is refused before it can become a path
+    // (it used to read as "Baseline read error: ENOENT …/status").
+    positionals: PositionalMode.Path,
+    subverbs: [
+        {
+            name: 'capture',
+            description: 'Write the current public API surface to a baseline file.',
+            usage: 'shrk api-diff capture --output <path> [--packages @scope/a,@scope/b] [--with-signatures] [--json]',
+        },
+    ],
     description: 'Compare the current public API surface to a saved baseline. Reports added / removed / kind-changed / moved symbols, with breaking-change severity.',
     usage: 'shrk api-diff capture --output <path> [--packages @scope/a,@scope/b] [--with-signatures] | shrk api-diff <baseline.json> [--packages @scope/a,@scope/b] [--with-signatures] [--json] [--fail-on-breaking]   (--packages takes EXACT workspace package names, comma-separated or repeated)',
     async run(args) {

package/dist/commands/apply.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.command.d.ts","sourceRoot":"","sources":["../../src/commands/apply.command.ts"],"names":[],"mappings":"AAqDA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyLhC,eAAO,MAAM,YAAY,EAAE,eAwsB1B,CAAC"}
+{"version":3,"file":"apply.command.d.ts","sourceRoot":"","sources":["../../src/commands/apply.command.ts"],"names":[],"mappings":"AAqDA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0LhC,eAAO,MAAM,YAAY,EAAE,eA0sB1B,CAAC"}

package/dist/commands/apply.command.js

@@ -5,6 +5,7 @@ import { applyAssetPreview } from "../asset-preview/apply-asset-preview.js";
 import { ApplyBatchPlanError, parseApplyBatchPlan, runApplyBatch, } from "../task-next/apply-batch-runner.js";
 import { applyFolderOps, checkFolderOpSafety, diffPlanChanges, diffPlanFolderOps, evaluateSavedPlanInPlace, FileChangeType, FolderOpSafety, generate, isSyntheticTemplateId, OverwriteStrategy, readPlanFromFile, verifyPlan, writeSyntheticPlan, } from '@shrkcrft/generator';
 import { flagBool, flagList, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header } from "../output/format-output.js";
 import { printError } from "../output/print-error.js";
 import { runValidationLoop } from "../validation/run-validation-loop.js";
@@ -178,6 +179,8 @@ async function runApplyBatchFromCli(args, batchPath) {
 }
 export const applyCommand = {
     name: 'apply',
+    // positional[0] is the plan FILE; a verb-shaped non-file is refused.
+    positionals: PositionalMode.Path,
     description: 'Apply a previously-saved generation plan (sharkcraft.plan/v1 JSON). The CLI is the only write path; MCP never writes. Plans that live under .sharkcraft/sessions/<id>/plans/ automatically update the session metadata (signature + divergence + applied + validation).',
     usage: 'shrk [--cwd <dir>] apply <plan.json> [--session <id>] [--force] [--allow-divergent] [--verify-signature] [--require-signature] [--no-verify-signature] [--dry-run] [--validate] [--report] [--json] [--trace] [--explain-dispatch] | shrk apply --asset-preview <draft.ts> --target <file> [--write] [--allow-unknown-target] [--reason <text>] | shrk apply --batch <plan.json> [--allow-divergent] [--dry-run] [--json]',
     async run(args) {

package/dist/commands/arch.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arch.command.d.ts","sourceRoot":"","sources":["../../src/commands/arch.command.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,eAoBzB,CAAC"}
+{"version":3,"file":"arch.command.d.ts","sourceRoot":"","sources":["../../src/commands/arch.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,eAoBzB,CAAC"}