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

package/dist/schemas/json-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-schemas.d.ts","sourceRoot":"","sources":["../../src/schemas/json-schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"json-schemas.d.ts","sourceRoot":"","sources":["../../src/schemas/json-schemas.ts"],"names":[],"mappings":"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"}

package/dist/schemas/json-schemas.js

@@ -198,7 +198,79 @@ export const KnowledgeEntrySchema = {
         appliesWhen: { type: 'array', items: { type: 'string' } },
         content: { type: 'string' },
         summary: { type: 'string' },
+        // Cross-reference ids (resolved by `shrk self-config doctor`).
+        related: { type: 'array', items: { type: 'string' } },
+        // Ids of any registered kind a reader should also look at.
+        seeAlso: { type: 'array', items: { type: 'string' } },
+        // Knowledge ids that replace this entry — non-empty means superseded.
+        supersededBy: { type: 'array', items: { type: 'string' } },
         actionHints: { $ref: 'action-hints.json' },
+        references: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['kind'],
+                properties: {
+                    kind: {
+                        enum: [
+                            'file',
+                            'directory',
+                            'symbol',
+                            'command',
+                            'template',
+                            'playbook',
+                            'construct',
+                            'helper',
+                            'policy',
+                            'boundary-rule',
+                            'path-convention',
+                            'package',
+                            'url',
+                        ],
+                    },
+                    path: { type: 'string' },
+                    // `Name`, or `Owner.member` for a class / interface / enum / object member.
+                    symbol: { type: 'string' },
+                    id: { type: 'string' },
+                    command: { type: 'string' },
+                    required: { type: 'boolean' },
+                    note: { type: 'string' },
+                    // Content assertions (file / symbol references): a literal, a regex.
+                    contains: { type: 'string', minLength: 1 },
+                    matches: { type: 'string', minLength: 1 },
+                    scan: { enum: ['all', 'code', 'strings', 'comments', 'code-and-templates'] },
+                    // A number the entry claims, re-derived by the extraction DSL.
+                    count: {
+                        type: 'object',
+                        required: ['source', 'expected'],
+                        properties: {
+                            source: { type: 'object' },
+                            expected: { type: 'integer', minimum: 0 },
+                            measure: { enum: ['ids', 'sites'] },
+                        },
+                    },
+                },
+            },
+        },
+        anchors: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['id', 'kind'],
+                properties: {
+                    id: { type: 'string' },
+                    kind: {
+                        enum: ['file', 'symbol', 'command', 'construct', 'template', 'helper', 'playbook', 'policy'],
+                    },
+                    path: { type: 'string' },
+                    symbol: { type: 'string' },
+                    targetId: { type: 'string' },
+                    description: { type: 'string' },
+                },
+            },
+        },
+        // The day an author last checked the entry against the code.
+        verifiedOn: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$' },
     },
 };
 export const AdoptionStateSchema = {
@@ -488,7 +560,27 @@ export const ScaffoldPatternSchema = {
         id: { type: 'string' },
         title: { type: 'string' },
         description: { type: 'string' },
-        matchPaths: { type: 'array', items: { type: 'string' }, minItems: 1 },
+        // Round 13: an entry is a glob, or `{ pattern, expectEmpty: true, reason? }`
+        // — a path the pattern names before any file lives there (docs/intended-empty.md).
+        matchPaths: {
+            type: 'array',
+            minItems: 1,
+            items: {
+                oneOf: [
+                    { type: 'string' },
+                    {
+                        type: 'object',
+                        required: ['pattern', 'expectEmpty'],
+                        additionalProperties: false,
+                        properties: {
+                            pattern: { type: 'string', minLength: 1 },
+                            expectEmpty: { const: true },
+                            reason: { type: 'string', minLength: 1 },
+                        },
+                    },
+                ],
+            },
+        },
         excludePaths: { type: 'array', items: { type: 'string' } },
         templateId: { type: 'string' },
         variables: {
@@ -541,7 +633,9 @@ export const QualityReportSchema = {
     type: 'object',
     required: ['overall', 'gates', 'score'],
     properties: {
-        overall: { enum: ['pass', 'warn', 'fail'] },
+        // `not-verified`: no blocking gate failed, but a gate could not run,
+        // examined nothing while required, or examined only part of its scope.
+        overall: { enum: ['pass', 'warn', 'fail', 'not-verified'] },
         blockers: { type: 'integer' },
         warnings: { type: 'integer' },
         score: { type: 'integer' },
@@ -550,6 +644,8 @@ export const QualityReportSchema = {
         note: { type: 'string' },
         nextCommand: { type: 'string' },
         nextRecommendations: { type: 'array', items: { type: 'string' } },
+        coverage: { type: 'object' },
+        shortfalls: { type: 'array', items: { type: 'string' } },
     },
 };
 export const SafetyAuditSchema = {
@@ -762,6 +858,13 @@ export const AreaMapSchema = {
         projectRoot: { type: 'string' },
         areas: { type: 'array' },
         unclassifiedFiles: { type: 'integer' },
+        totalFiles: { type: 'integer' },
+        classifiedFiles: { type: 'integer' },
+        classificationRate: { type: 'number', minimum: 0, maximum: 1 },
+        minClassificationRate: { type: 'number', minimum: 0, maximum: 1 },
+        degraded: { type: 'boolean' },
+        unclassifiedSample: { type: 'array', items: { type: 'string' } },
+        patternSource: { enum: ['built-in', 'config', 'config+built-in'] },
     },
 };
 export const ImpactAnalysisSchema = {
@@ -776,6 +879,14 @@ export const ImpactAnalysisSchema = {
         risk: { type: 'string' },
         affectedFiles: { type: 'array' },
         affectedAreas: { type: 'array' },
+        areaCoverage: {
+            type: 'object',
+            properties: {
+                classificationRate: { type: 'number', minimum: 0, maximum: 1 },
+                degraded: { type: 'boolean' },
+                unclassifiedTargets: { type: 'array', items: { type: 'string' } },
+            },
+        },
     },
 };
 export const TestImpactSchema = {

package/dist/shrk.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=shrk.d.ts.map

package/dist/shrk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shrk.d.ts","sourceRoot":"","sources":["../src/shrk.ts"],"names":[],"mappings":""}

package/dist/shrk.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * This package's bin (round 13, 13.2): a bootstrap that loads `./main.ts`
+ * (emitted as `dist/main.js`) through a dynamic import, so a load failure of
+ * the entry's STATIC module graph reaches a handler at all. One case is
+ * rewritten — a workspace dependency of the installed tool that is not linked
+ * (Node's raw `ERR_MODULE_NOT_FOUND: Cannot find package '@shrkcrft/x'`
+ * resolver stack) — into one line naming the dependency, the package that
+ * needs it and where to run the install, exit 70 (EX_SOFTWARE: the tool's own
+ * install is broken; docs/exit-codes.md). Every other error is rethrown
+ * untouched: the same message, source line and exit code as running
+ * `dist/main.js` directly.
+ *
+ * node: builtins only, through the sibling ./bootstrap module — never an
+ * `@shrkcrft` import: that package's link could be the missing one. The CLI
+ * (`shrk`) and the MCP server (`shrk-mcp`) carry byte-identical copies of this
+ * file and of ./bootstrap/unlinked-workspace-dependency.ts;
+ * r77-bootstrap-rewrite.test.ts locks them together.
+ */
+import { unlinkedWorkspaceDependencyMessage } from "./bootstrap/unlinked-workspace-dependency.js";
+try {
+    await import("./main.js");
+}
+catch (error) {
+    const message = unlinkedWorkspaceDependencyMessage(error);
+    if (message === undefined)
+        throw error;
+    // Exit only once the line is flushed: stderr is asynchronous on a pipe.
+    process.stderr.write(`${message}\n`, () => process.exit(70));
+}

package/dist/surface/audience-applicability.d.ts

@@ -0,0 +1,26 @@
+import { type ICommandRecommendationReport } from '@shrkcrft/inspector';
+import { type buildSurfaceSummary, type ISurfaceCommandView } from './surface-summary.js';
+type SurfaceSummary = ReturnType<typeof buildSurfaceSummary>;
+/**
+ * The surface view a recommended command string names: its first one or two
+ * command words after an optional `$` / `bun run` / `shrk` (the full path
+ * first, then the top-level token).
+ */
+export declare function surfaceViewForCommand(rawCommand: string, summary: SurfaceSummary): ISurfaceCommandView | undefined;
+/**
+ * A command that maintains SharkCraft itself, asked about outside SharkCraft's
+ * own repository: gated by AUDIENCE (exit 78), so it is no recommendation here
+ * at all — not "experimental, not enabled", and never an `Enable:` hint.
+ * Read off THE surface view (`source` is `tool-maintenance` only outside the
+ * tool repo), never a second host check.
+ */
+export declare function notApplicableHere(command: string, summary: SurfaceSummary): boolean;
+/**
+ * THE audience filter over a recommender report, for every surface that prints
+ * one (`shrk recommend`, `shrk context`'s "Top commands"): the rows, the ranked
+ * list and the uncertainty block's suggested commands lose every command that
+ * does not apply here, and `nextCommand` is re-picked by THE rule.
+ */
+export declare function dropNotApplicable(report: ICommandRecommendationReport, summary: SurfaceSummary): ICommandRecommendationReport;
+export {};
+//# sourceMappingURL=audience-applicability.d.ts.map

package/dist/surface/audience-applicability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience-applicability.d.ts","sourceRoot":"","sources":["../../src/surface/audience-applicability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EAAwB,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGhH,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,mBAAmB,GAAG,SAAS,CAgBlH;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAGnF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,4BAA4B,EAAE,OAAO,EAAE,cAAc,GAAG,4BAA4B,CAU7H"}

package/dist/surface/audience-applicability.js

@@ -0,0 +1,60 @@
+import { pickNextCommand } from '@shrkcrft/inspector';
+import { findCommandInSummary } from "./surface-summary.js";
+import { TierSource } from "./tier.js";
+/**
+ * The surface view a recommended command string names: its first one or two
+ * command words after an optional `$` / `bun run` / `shrk` (the full path
+ * first, then the top-level token).
+ */
+export function surfaceViewForCommand(rawCommand, summary) {
+    const tokens = rawCommand.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return undefined;
+    let i = 0;
+    if (tokens[i] === '$')
+        i += 1;
+    if (tokens[i] === 'bun' && tokens[i + 1] === 'run')
+        i += 2;
+    if (tokens[i] === 'shrk')
+        i += 1;
+    const verbTokens = [];
+    for (let j = i; j < tokens.length; j += 1) {
+        const t = tokens[j];
+        if (t.startsWith('-') || t.startsWith('<') || t.startsWith('"'))
+            break;
+        verbTokens.push(t);
+        if (verbTokens.length >= 2)
+            break;
+    }
+    if (verbTokens.length === 0)
+        return undefined;
+    return findCommandInSummary(summary, verbTokens.join(' ')) ?? findCommandInSummary(summary, verbTokens[0]);
+}
+/**
+ * A command that maintains SharkCraft itself, asked about outside SharkCraft's
+ * own repository: gated by AUDIENCE (exit 78), so it is no recommendation here
+ * at all — not "experimental, not enabled", and never an `Enable:` hint.
+ * Read off THE surface view (`source` is `tool-maintenance` only outside the
+ * tool repo), never a second host check.
+ */
+export function notApplicableHere(command, summary) {
+    const view = surfaceViewForCommand(command, summary);
+    return view !== undefined && !view.callable && view.source === TierSource.ToolMaintenance;
+}
+/**
+ * THE audience filter over a recommender report, for every surface that prints
+ * one (`shrk recommend`, `shrk context`'s "Top commands"): the rows, the ranked
+ * list and the uncertainty block's suggested commands lose every command that
+ * does not apply here, and `nextCommand` is re-picked by THE rule.
+ */
+export function dropNotApplicable(report, summary) {
+    const applicable = (command) => !notApplicableHere(command, summary);
+    const recommendations = report.recommendations.filter((r) => applicable(r.command));
+    return {
+        ...report,
+        recommendations,
+        ranked: report.ranked.filter((c) => applicable(c.command)),
+        uncertainty: { ...report.uncertainty, suggestedCommands: report.uncertainty.suggestedCommands.filter(applicable) },
+        nextCommand: pickNextCommand(recommendations, report.confident),
+    };
+}

package/dist/surface/catalog-command-safety.d.ts

@@ -0,0 +1,18 @@
+import { type ICommandSafety } from '@shrkcrft/inspector';
+import type { ICommandIndex } from './i-command-index.js';
+/**
+ * THE declared safety of a command string, from COMMAND_CATALOG — what the
+ * CLI injects into the recommendation ranker (`IRecommendationRankingOptions
+ * .safetyOf`), so a recommended command is labelled and withheld by what its
+ * catalog row DECLARES, never by a regex guess.
+ *
+ * The string is resolved through THE command resolver (`resolveCommandString`
+ * over the command index). The base row of the matched path applies, plus any
+ * flag-variant row whose flags the string carries (`check wiring --fix` over
+ * `check wiring`); the most dangerous row wins. `writesSource` is the catalog
+ * audit's own predicate: `writesSource || safetyLevel === writes-source`.
+ * `undefined` for a string the catalog does not document (the ranker then
+ * falls back to the regex).
+ */
+export declare function catalogCommandSafety(raw: string, index?: ICommandIndex): ICommandSafety | undefined;
+//# sourceMappingURL=catalog-command-safety.d.ts.map

package/dist/surface/catalog-command-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-command-safety.d.ts","sourceRoot":"","sources":["../../src/surface/catalog-command-safety.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAe1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS,CA8BnG"}

package/dist/surface/catalog-command-safety.js

@@ -0,0 +1,62 @@
+import { CommandResolutionStatus } from '@shrkcrft/inspector';
+import { COMMAND_CATALOG, SafetyLevel } from "../commands/command-catalog.js";
+import { buildCommandIndex, findCommandIndexEntry, getActiveCommandIndex } from "./command-index.js";
+import { resolveCommandString } from "./resolve-command-string.js";
+/** Most to least dangerous — the most dangerous applicable catalog row wins. */
+const SAFETY_RANK = {
+    [SafetyLevel.ReadOnly]: 0,
+    [SafetyLevel.WritesSessionOnly]: 1,
+    [SafetyLevel.WritesDraftsOnly]: 2,
+    [SafetyLevel.RunsShell]: 3,
+    [SafetyLevel.WritesSource]: 4,
+};
+let catalogByCommand;
+let fallbackIndex;
+/**
+ * THE declared safety of a command string, from COMMAND_CATALOG — what the
+ * CLI injects into the recommendation ranker (`IRecommendationRankingOptions
+ * .safetyOf`), so a recommended command is labelled and withheld by what its
+ * catalog row DECLARES, never by a regex guess.
+ *
+ * The string is resolved through THE command resolver (`resolveCommandString`
+ * over the command index). The base row of the matched path applies, plus any
+ * flag-variant row whose flags the string carries (`check wiring --fix` over
+ * `check wiring`); the most dangerous row wins. `writesSource` is the catalog
+ * audit's own predicate: `writesSource || safetyLevel === writes-source`.
+ * `undefined` for a string the catalog does not document (the ranker then
+ * falls back to the regex).
+ */
+export function catalogCommandSafety(raw, index) {
+    const idx = index ?? getActiveCommandIndex() ?? (fallbackIndex ??= buildCommandIndex());
+    const resolution = resolveCommandString(idx, raw);
+    if (resolution.matched === undefined ||
+        (resolution.status !== CommandResolutionStatus.Ok && resolution.status !== CommandResolutionStatus.PrefixOnly)) {
+        return undefined;
+    }
+    const entry = findCommandIndexEntry(idx, resolution.matched);
+    if (!entry?.catalogEntry)
+        return undefined;
+    catalogByCommand ??= new Map(COMMAND_CATALOG.map((e) => [e.command, e]));
+    const tokens = new Set(raw.trim().split(/\s+/).map((t) => t.split('=')[0]));
+    const rows = [entry.catalogEntry];
+    for (const variant of entry.variants) {
+        const flags = variant
+            .split(/\s+/)
+            .slice(entry.tokens.length)
+            .filter((t) => t.startsWith('--'));
+        if (flags.length === 0 || !flags.every((f) => tokens.has(f)))
+            continue;
+        const row = catalogByCommand.get(variant);
+        if (row)
+            rows.push(row);
+    }
+    let level = entry.catalogEntry.safetyLevel;
+    let writesSource = false;
+    for (const row of rows) {
+        if ((SAFETY_RANK[row.safetyLevel] ?? 0) > (SAFETY_RANK[level] ?? 0))
+            level = row.safetyLevel;
+        if (row.writesSource === true || row.safetyLevel === SafetyLevel.WritesSource)
+            writesSource = true;
+    }
+    return { safetyLevel: level, writesSource };
+}

package/dist/surface/cli-command-resolver.d.ts

@@ -0,0 +1,21 @@
+import { type ICommandResolution, type ICommandResolveOptions, type ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { ICommandIndex } from './i-command-index.js';
+import type { ICommandStringContext } from './i-command-string-context.js';
+/** Root package.json script names, or `undefined` when there is none to read. */
+export declare function readPackageScripts(projectRoot: string): ReadonlySet<string> | undefined;
+/** The non-shrk sets the resolver checks against, for `projectRoot`. */
+export declare function loadCommandStringContext(projectRoot: string): Promise<ICommandStringContext>;
+/**
+ * A memoised `(raw, options?) => ICommandResolution` over the active command
+ * index, or `undefined` outside a CLI run (no index) — the inspector then
+ * reports every command reference NOT VERIFIED rather than guessing. The memo
+ * keys on the reading too: `doctor` as a command reference and as free shell
+ * text are two different questions.
+ */
+export declare function cliCommandResolver(projectRoot: string, index?: ICommandIndex | undefined): Promise<((raw: string, options?: ICommandResolveOptions) => ICommandResolution) | undefined>;
+/**
+ * `warmReferenceRegistries` plus the injected command resolver. THE warm call
+ * for CLI code: a bare warm leaves every `command` reference Unverifiable.
+ */
+export declare function warmCliReferenceRegistries(inspection: ISharkcraftInspection): Promise<void>;
+//# sourceMappingURL=cli-command-resolver.d.ts.map

package/dist/surface/cli-command-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-resolver.d.ts","sourceRoot":"","sources":["../../src/surface/cli-command-resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAsC3E,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CASvF;AAED,wEAAwE;AACxE,wBAAsB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAQlG;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,aAAa,GAAG,SAAmC,GACzD,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,KAAK,kBAAkB,CAAC,GAAG,SAAS,CAAC,CAY9F;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjG"}

package/dist/surface/cli-command-resolver.js

@@ -0,0 +1,87 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { warmReferenceRegistries, } from '@shrkcrft/inspector';
+import { getActiveCommandIndex } from "./command-index.js";
+import { resolveCommandString } from "./resolve-command-string.js";
+/**
+ * The CLI side of the inspector's command-resolver seam.
+ *
+ * The inspector cannot import the CLI (layer order), so it answers `command`
+ * references through a resolver the CLI injects — built here from the ACTIVE
+ * command index (the registry this run dispatches from). Every CLI site that
+ * warms the reference registries goes through {@link warmCliReferenceRegistries},
+ * so a knowledge reference, a doctor probe and an agent-test expectation are
+ * all answered by the same function.
+ */
+let toolNames;
+/** Registered MCP tool names (loaded once per process, lazily). */
+function loadMcpToolNames() {
+    toolNames ??= importMcpToolNames();
+    return toolNames;
+}
+/**
+ * The lazy import behind {@link loadMcpToolNames}; a failed import reads as
+ * "no MCP tool names". Written as `await import()` — the `import(…).then(…)`
+ * shape is read by `shrk check imports` as an inline type import (an error
+ * that fails release preflight).
+ */
+async function importMcpToolNames() {
+    let mcp;
+    try {
+        mcp = await import('@shrkcrft/mcp-server');
+    }
+    catch {
+        return undefined;
+    }
+    return new Set(mcp.ALL_TOOLS.map((t) => t.name));
+}
+/** Root package.json script names, or `undefined` when there is none to read. */
+export function readPackageScripts(projectRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'));
+        return new Set(Object.keys(pkg.scripts ?? {}));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The non-shrk sets the resolver checks against, for `projectRoot`. */
+export async function loadCommandStringContext(projectRoot) {
+    const scripts = readPackageScripts(projectRoot);
+    const mcpToolNames = await loadMcpToolNames();
+    return {
+        ...(scripts ? { scripts } : {}),
+        ...(mcpToolNames ? { mcpToolNames } : {}),
+        root: projectRoot,
+    };
+}
+/**
+ * A memoised `(raw, options?) => ICommandResolution` over the active command
+ * index, or `undefined` outside a CLI run (no index) — the inspector then
+ * reports every command reference NOT VERIFIED rather than guessing. The memo
+ * keys on the reading too: `doctor` as a command reference and as free shell
+ * text are two different questions.
+ */
+export async function cliCommandResolver(projectRoot, index = getActiveCommandIndex()) {
+    if (!index)
+        return undefined;
+    const ctx = await loadCommandStringContext(projectRoot);
+    const memo = new Map();
+    return (raw, options = {}) => {
+        const key = [options.assumeShrk === true ? 'ref' : 'sh', raw].join(String.fromCharCode(0));
+        const hit = memo.get(key);
+        if (hit)
+            return hit;
+        const resolution = resolveCommandString(index, raw, ctx, options);
+        memo.set(key, resolution);
+        return resolution;
+    };
+}
+/**
+ * `warmReferenceRegistries` plus the injected command resolver. THE warm call
+ * for CLI code: a bare warm leaves every `command` reference Unverifiable.
+ */
+export async function warmCliReferenceRegistries(inspection) {
+    const commandResolver = await cliCommandResolver(inspection.projectRoot);
+    await warmReferenceRegistries(inspection, commandResolver ? { commandResolver } : {});
+}

package/dist/surface/command-dispatch-kind.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How a command-index entry is dispatched.
+ *
+ *   - `Trie`    — a registered handler path (`CommandRegistry.listAll()`).
+ *   - `Subverb` — dispatched internally by a parent handler on a positional
+ *                 (`check wiring`, `graph status`): declared on the handler's
+ *                 `subverbs`, or documented by a catalog row under a real
+ *                 handler.
+ *   - `Meta`    — a bootstrap meta flag handled before dispatch (`--about`,
+ *                 `--help`, `--full-help`, `--version`).
+ *   - `Catalog` — registry-less fallback only: documented by the catalog, but
+ *                 no command registry was available to prove it dispatches.
+ */
+export declare enum CommandDispatchKind {
+    Trie = "trie",
+    Subverb = "subverb",
+    Meta = "meta",
+    Catalog = "catalog"
+}
+//# sourceMappingURL=command-dispatch-kind.d.ts.map

package/dist/surface/command-dispatch-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-dispatch-kind.d.ts","sourceRoot":"","sources":["../../src/surface/command-dispatch-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oBAAY,mBAAmB;IAC7B,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,OAAO,YAAY;CACpB"}

package/dist/surface/command-dispatch-kind.js

@@ -0,0 +1,20 @@
+/**
+ * How a command-index entry is dispatched.
+ *
+ *   - `Trie`    — a registered handler path (`CommandRegistry.listAll()`).
+ *   - `Subverb` — dispatched internally by a parent handler on a positional
+ *                 (`check wiring`, `graph status`): declared on the handler's
+ *                 `subverbs`, or documented by a catalog row under a real
+ *                 handler.
+ *   - `Meta`    — a bootstrap meta flag handled before dispatch (`--about`,
+ *                 `--help`, `--full-help`, `--version`).
+ *   - `Catalog` — registry-less fallback only: documented by the catalog, but
+ *                 no command registry was available to prove it dispatches.
+ */
+export var CommandDispatchKind;
+(function (CommandDispatchKind) {
+    CommandDispatchKind["Trie"] = "trie";
+    CommandDispatchKind["Subverb"] = "subverb";
+    CommandDispatchKind["Meta"] = "meta";
+    CommandDispatchKind["Catalog"] = "catalog";
+})(CommandDispatchKind || (CommandDispatchKind = {}));

package/dist/surface/command-index-entry.d.ts

@@ -0,0 +1,40 @@
+import type { CommandAudience, ICommandCatalogEntry } from '../commands/command-catalog.js';
+import type { PositionalMode } from '../dispatch/positional-mode.js';
+import type { CommandDispatchKind } from './command-dispatch-kind.js';
+/**
+ * One dispatchable command — a row of the command index.
+ *
+ * The index is the ONE answer to "does this command exist, what does it do,
+ * who is it for": `surface list`, `help`, `commands doctor`, the surface gate
+ * and the command-string resolver all read it.
+ */
+export interface ICommandIndexEntry {
+    /** Clean command path, space-joined (`knowledge stale-check`, `check wiring`). */
+    readonly path: string;
+    readonly tokens: readonly string[];
+    readonly dispatch: CommandDispatchKind;
+    /** Catalog description ?? declared-subverb description ?? handler description. */
+    readonly description: string;
+    /** Declared-subverb usage ?? handler usage (catalog-only subverbs have none). */
+    readonly usage?: string;
+    /** True when a COMMAND_CATALOG row documents this path. */
+    readonly catalogued: boolean;
+    /** The base catalog row (the one whose `command` is exactly the clean path, else the first). */
+    readonly catalogEntry?: ICommandCatalogEntry;
+    /**
+     * Catalog rows folded into this entry because they only add flags or
+     * placeholders (`architecture violations --changed-only`, `impact <input>`).
+     * Full `command` strings, sorted.
+     */
+    readonly variants: readonly string[];
+    /** Catalog aliases plus registry alias spellings of this path. */
+    readonly aliases: readonly string[];
+    readonly audience: readonly CommandAudience[];
+    /** For `Subverb`: the handler path that dispatches it. */
+    readonly parent?: string;
+    /** For `Subverb`: declared on the handler (`subverbs`) rather than only documented by the catalog. */
+    readonly declared?: boolean;
+    /** What a non-subverb positional[0] means for this command, when declared. */
+    readonly positionals?: PositionalMode;
+}
+//# sourceMappingURL=command-index-entry.d.ts.map

package/dist/surface/command-index-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-index-entry.d.ts","sourceRoot":"","sources":["../../src/surface/command-index-entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC5F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,gGAAgG;IAChG,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;CACvC"}

package/dist/surface/command-index-entry.js

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