@shrkcrft/cli 0.1.0-alpha.23 → 0.1.0-alpha.24

package/dist/commands/impact.command.js

@@ -4,7 +4,7 @@ import { analyzeImpact, analyzeTestImpact, findSymbolInProject, FuzzyImpactSourc
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { fuzzyImpactAmbiguousHints, renderFailureHints } from "../output/failure-hints.js";
-import { collectChangedPaths } from "../diff/collect-changed-paths.js";
+import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
 function collectFiles(args, cwd) {
     const diagnostics = [];
     const explicitFiles = flagList(args, 'files');
@@ -297,17 +297,24 @@ async function runDeletedOrphans(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json') || flagString(args, 'format') === 'json';
     const sinceRef = flagString(args, 'since');
-    const changed = collectChangedPaths({ cwd, ...(sinceRef ? { ref: sinceRef } : {}) });
-    if (!changed.isAvailable) {
+    const staged = flagBool(args, 'staged');
+    const scan = await computeDeletedOrphans(cwd, {
+        ...(sinceRef ? { since: sinceRef } : {}),
+        ...(staged ? { staged: true } : {}),
+    });
+    if (!scan.ok) {
         if (wantJson) {
-            process.stdout.write(asJson({ ok: false, error: changed.error }) + '\n');
+            process.stdout.write(asJson({ ok: false, error: scan.error }) + '\n');
+        }
+        else if (scan.reason === 'diff-unavailable') {
+            process.stderr.write(`Cannot resolve diff: ${scan.error ?? 'unknown'}\n`);
         }
         else {
-            process.stderr.write(`Cannot resolve diff: ${changed.error ?? 'unknown'}\n`);
+            process.stderr.write(`${scan.error ?? 'orphan check unavailable'}\n`);
         }
         return 2;
     }
-    const deleted = changed.deleted;
+    const deleted = scan.deleted;
     if (deleted.length === 0) {
         if (wantJson) {
             process.stdout.write(asJson({
@@ -315,33 +322,21 @@ async function runDeletedOrphans(args) {
                 resolvedDeleted: [],
                 unresolvedDeleted: [],
                 orphans: [],
-                diagnostics: [`no deleted files in diff vs ${changed.ref}`],
+                diagnostics: [`no deleted files in diff vs ${scan.ref}`],
             }) + '\n');
             return 0;
         }
         process.stdout.write(header('Deleted-symbol orphans'));
-        process.stdout.write(`No deleted files in diff vs ${changed.ref}.\n`);
+        process.stdout.write(`No deleted files in diff vs ${scan.ref}.\n`);
         return 0;
     }
-    const { GraphStore, GraphQueryApi } = await import('@shrkcrft/graph');
-    if (!new GraphStore(cwd).exists()) {
-        const msg = 'code-graph store missing — run `shrk graph index` first.';
-        if (wantJson) {
-            process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
-        }
-        else {
-            process.stderr.write(msg + '\n');
-        }
-        return 2;
-    }
-    const { findDeletedOrphans } = await import('@shrkcrft/impact-engine');
-    const report = findDeletedOrphans(GraphQueryApi.fromStore(cwd), deleted);
+    const report = scan.report;
     if (wantJson) {
         process.stdout.write(asJson(report) + '\n');
         return report.orphans.length > 0 ? 1 : 0;
     }
     process.stdout.write(header('Deleted-symbol orphans'));
-    process.stdout.write(`Deleted files (vs ${changed.ref}): ${deleted.length}\n`);
+    process.stdout.write(`Deleted files (vs ${scan.ref}): ${deleted.length}\n`);
     if (report.orphans.length === 0) {
         process.stdout.write('no orphaned importers\n');
         for (const d of report.diagnostics.slice(0, 5))

package/dist/commands/smart-context.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AA0BA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAmFhC,eAAO,MAAM,mBAAmB,EAAE,eAmQjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAsF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC;AAqJF,UAAU,eAAe;IACvB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAWzF"}
+{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AA2BA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAmFhC,eAAO,MAAM,mBAAmB,EAAE,eAmQjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAsF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC;AAqJF,UAAU,eAAe;IACvB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAWzF"}

package/dist/commands/smart-context.command.js

@@ -1,9 +1,10 @@
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import * as os from 'node:os';
 import { AiMessageRole, buildPromptMessages, EnhancementPipeline, EnhancementStageKind, OllamaProvider, buildDefaultEnhancementStages, buildFastEnhancementStages, selectAiProvider, } from '@shrkcrft/ai';
 import { buildContext } from '@shrkcrft/context';
+import { runGitLines } from '@shrkcrft/shared';
 import { EdgeKind, GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
 import { buildProjectOverview, buildTaskPacket, contextTuningBoostFor, inspectSharkcraft, renderOverviewText, } from '@shrkcrft/inspector';
 import { flagBool, flagList, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
@@ -2182,45 +2183,21 @@ function isSemanticAutomationDisabled() {
  * ripples through. Empty array on git failure or no-graph.
  */
 function collectChangedPathsWithNeighbors(cwd, gitRef) {
-    // Use `node:child_process` spawnSync (works under both Bun and Node)
-    // instead of `Bun.spawnSync` so the CLI runs cleanly on a pure-Node
-    // runtime after `npm i -g @shrkcrft/cli`. The compat-node preflight
-    // gate flags `Bun.*` direct usages as publish blockers.
-    let changed;
-    try {
-        const out = spawnSync('git', ['-C', cwd, 'diff', '--name-only', `${gitRef}...HEAD`], {
-            encoding: 'utf8',
-        });
-        if (out.status !== 0)
-            return [];
-        changed = (out.stdout ?? '')
-            .split('\n')
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0);
-    }
-    catch {
-        return [];
-    }
-    if (changed.length === 0)
+    // `runGitLines` is shell-free + high-maxBuffer, so a large changeset can't
+    // ENOBUFS-crash the feedback bundle. (It also keeps the CLI on
+    // `node:child_process` rather than `Bun.*`, which the compat-node preflight
+    // gate flags as a publish blocker.)
+    const committed = runGitLines(cwd, ['diff', '--name-only', `${gitRef}...HEAD`]);
+    if (!committed.ok || committed.lines.length === 0)
         return [];
+    const changed = [...committed.lines];
     // Also include uncommitted changes — agent feedback should reflect
     // the *current* working tree, not just committed deltas.
-    try {
-        const out = spawnSync('git', ['-C', cwd, 'diff', '--name-only', 'HEAD'], {
-            encoding: 'utf8',
-        });
-        if (out.status === 0) {
-            const uncommitted = (out.stdout ?? '')
-                .split('\n')
-                .map((s) => s.trim())
-                .filter((s) => s.length > 0);
-            for (const p of uncommitted)
-                if (!changed.includes(p))
-                    changed.push(p);
-        }
-    }
-    catch {
-        // ignore
+    const uncommitted = runGitLines(cwd, ['diff', '--name-only', 'HEAD']);
+    if (uncommitted.ok) {
+        for (const p of uncommitted.lines)
+            if (!changed.includes(p))
+                changed.push(p);
     }
     const set = new Set(changed);
     // One-hop graph expansion if the graph is fresh.

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

@@ -1 +1 @@
-{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,YAAY,EAAE,eAqH1B,CAAC"}
+{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6EhC,eAAO,MAAM,YAAY,EAAE,eAwH1B,CAAC"}

package/dist/commands/trace.command.js

@@ -6,16 +6,86 @@
  * shared query resolver and prints structured trace output.
  */
 import { findSymbolInProject, inspectSharkcraft, QueryMatchKind, resolveQuery, } from '@shrkcrft/inspector';
+import { traceLiteral, TraceRole, } from '@shrkcrft/boundaries';
 import { flagBool, flagList, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
-import { asJson, header } from "../output/format-output.js";
+import { asJson, header, kv } from "../output/format-output.js";
 function describeMatch(m) {
     return `${m.kind.padEnd(12)} ${m.id}${m.label && m.label !== m.id ? ` — ${m.label}` : ''} [${m.score.toFixed(0)}]`;
 }
+const LITERAL_SITE_CAP = 30;
+const TRACE_ROLE_ORDER = [
+    TraceRole.Declare,
+    TraceRole.Register,
+    TraceRole.Consume,
+    TraceRole.Reference,
+];
+function renderTraceLiteral(report, limit) {
+    process.stdout.write(header(`Trace literal: "${report.literal}"`));
+    process.stdout.write(kv('found', `${report.total} site(s) across ${report.files} file(s)`) + '\n');
+    if (report.aliases.length > 0) {
+        process.stdout.write(kv('const aliases', report.aliases.join(', ')) + '\n');
+    }
+    if (report.total === 0) {
+        process.stdout.write('\nNo occurrences of that exact string literal in scope.\n');
+        return;
+    }
+    // Mirror `shrk registry <name> where`'s `<role>  file:line` line idiom so the
+    // two surfaces read the same — `trace literal` is the same scanner + classifier
+    // without a pre-declared registry, just with two extra roles (`registered`,
+    // `reference`). The raw source line stays in `--json` (`text`); the human view
+    // is classification-first (direction), not a grep-style text dump.
+    process.stdout.write('\n');
+    for (const role of TRACE_ROLE_ORDER) {
+        const sites = report.byRole[role];
+        for (const s of sites.slice(0, limit)) {
+            const alias = s.viaAlias ? ` [via ${s.viaAlias}]` : '';
+            process.stdout.write(`  ${role.padEnd(10)} ${s.file}:${s.line}${alias}\n`);
+        }
+        if (sites.length > limit) {
+            process.stdout.write(`  ${role.padEnd(10)} … (${sites.length - limit} more — pass --json)\n`);
+        }
+    }
+}
+/**
+ * `shrk trace literal "<string>"`: trace an EXACT string literal across the
+ * codebase, classified by direction (declare → register → consume), resolving
+ * `const X = "lit"` aliases too. Generalizes `registry … where` to any
+ * cross-fence string contract (a kind slug, permission id, route key) with no
+ * pre-declared registry — the chain grep can't give (direction + role + layer).
+ */
+function runTraceLiteral(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    // `trace literal "<lit>"` → the literal is positional[1] (quoted by the user
+    // so an internal space stays one token); join the rest defensively.
+    const literal = args.positional.slice(1).join(' ');
+    if (literal === '') {
+        process.stderr.write('Usage: shrk trace literal "<string>" [--glob <g1,g2>] [--no-aliases] [--limit N] [--json]\n');
+        return 2;
+    }
+    const globs = flagList(args, 'glob');
+    const report = traceLiteral(cwd, literal, {
+        ...(globs.length > 0 ? { globs } : {}),
+        resolveAliases: !flagBool(args, 'no-aliases'),
+    });
+    if (wantJson) {
+        process.stdout.write(asJson(report) + '\n');
+        return 0;
+    }
+    const limitRaw = flagNumber(args, 'limit');
+    const limit = limitRaw !== undefined && limitRaw > 0 ? Math.floor(limitRaw) : LITERAL_SITE_CAP;
+    renderTraceLiteral(report, limit);
+    return 0;
+}
 export const traceCommand = {
     name: 'trace',
-    description: 'Fuzzy trace — accept any free-form query (file path, construct id, symbol, plugin key, helper id, template id, knowledge id, command). Read-only.',
-    usage: 'shrk trace <query> [--limit <n>] [--kind file|construct|knowledge|template|helper|playbook|policy|command] [--deep] [--json]',
+    description: 'Fuzzy trace — accept any free-form query (file path, construct id, symbol, plugin key, helper id, template id, knowledge id, command). `trace literal "<string>"` traces an exact string literal\'s declare→register→consume chain across layers (alias-resolved). Read-only.',
+    usage: 'shrk trace <query> | shrk trace literal "<string>" [--glob <g>] [--no-aliases] [--limit <n>] [--kind ...] [--deep] [--json]',
+    booleanFlags: new Set(['json', 'deep', 'no-aliases']),
     async run(args) {
+        // `trace literal "<lit>"` — cross-fence string-contract tracer (3.3).
+        if (args.positional[0] === 'literal')
+            return runTraceLiteral(args);
         // Direct symbol trace via --symbol <Name>
         const symbol = flagString(args, 'symbol');
         if (symbol) {

package/dist/commands/wiring.command.d.ts

@@ -0,0 +1,12 @@
+import { type IWiringExplain } from '@shrkcrft/boundaries';
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * Render an {@link IWiringExplain} to stdout. Shared by `wiring explain`,
+ * `wiring test`, and `check wiring --explain` so all three speak the same
+ * dialect. JSON emits the full payload; text mirrors `search tuning explain`
+ * (header → loaded sets → per-site detail → the set-difference → verdict).
+ * Always returns 0 — explain is informational, the verdict is in the output.
+ */
+export declare function renderWiringExplain(report: IWiringExplain, wantJson: boolean): number;
+export declare const wiringCommand: ICommandHandler;
+//# sourceMappingURL=wiring.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAwB,KAAK,eAAe,EAAmB,MAAM,wBAAwB,CAAC;AAKrG;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAsDrF;AA+TD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}

package/dist/commands/wiring.command.js

@@ -0,0 +1,384 @@
+import { buildRegistrationGraph, explainWiring, registrationChain, registrationGraphSignature, registrationOrphans, registrationUnprovided, } from '@shrkcrft/boundaries';
+import { resolveProjectConfig } from '@shrkcrft/inspector';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { flagBool, resolveCwd } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+const SITE_DISPLAY_CAP = 50;
+/**
+ * Render an {@link IWiringExplain} to stdout. Shared by `wiring explain`,
+ * `wiring test`, and `check wiring --explain` so all three speak the same
+ * dialect. JSON emits the full payload; text mirrors `search tuning explain`
+ * (header → loaded sets → per-site detail → the set-difference → verdict).
+ * Always returns 0 — explain is informational, the verdict is in the output.
+ */
+export function renderWiringExplain(report, wantJson) {
+    if (wantJson) {
+        process.stdout.write(asJson(report) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Wiring explain: ${report.ruleId} (${report.mode})`));
+    if (report.description)
+        process.stdout.write(`  ${report.description}\n`);
+    if (report.groupBy)
+        process.stdout.write(kv('groupBy', report.groupBy) + '\n');
+    process.stdout.write(kv('declared', `${report.declared.distinctCount} distinct across ${report.declared.filesScanned} file(s)`) +
+        '\n');
+    process.stdout.write(kv('registered', `${report.registered.distinctCount} distinct across ${report.registered.filesScanned} file(s)`) + '\n');
+    if (report.declared.error)
+        process.stdout.write(`  ! declared side: ${report.declared.error}\n`);
+    if (report.registered.error) {
+        process.stdout.write(`  ! registered side: ${report.registered.error}\n`);
+    }
+    writeSites('Declared sites', report.declared.sites);
+    writeSites('Registered sites', report.registered.sites);
+    if (report.declaredNotRegistered.length > 0) {
+        process.stdout.write(`\nDeclared but NOT registered (${report.declaredNotRegistered.length}):\n`);
+        for (const s of report.declaredNotRegistered.slice(0, SITE_DISPLAY_CAP)) {
+            process.stdout.write(`  ✗ ${s.token}  (${s.file}:${s.line})\n`);
+        }
+        if (report.declaredNotRegistered.length > SITE_DISPLAY_CAP) {
+            process.stdout.write(`  … (${report.declaredNotRegistered.length - SITE_DISPLAY_CAP} more)\n`);
+        }
+    }
+    if (report.registeredNotDeclared.length > 0) {
+        process.stdout.write(`\nRegistered but NOT declared (parity, ${report.registeredNotDeclared.length}):\n`);
+        for (const s of report.registeredNotDeclared.slice(0, SITE_DISPLAY_CAP)) {
+            process.stdout.write(`  ✗ ${s.token}  (${s.file}:${s.line})\n`);
+        }
+        if (report.registeredNotDeclared.length > SITE_DISPLAY_CAP) {
+            process.stdout.write(`  … (${report.registeredNotDeclared.length - SITE_DISPLAY_CAP} more)\n`);
+        }
+    }
+    for (const d of report.diagnostics)
+        process.stdout.write(`  ! ${d}\n`);
+    process.stdout.write(`\nVerdict: ${report.verdict}\n`);
+    return 0;
+}
+function writeSites(label, sites) {
+    process.stdout.write(`\n${label} (${sites.length}):\n`);
+    if (sites.length === 0) {
+        process.stdout.write('  (none extracted)\n');
+        return;
+    }
+    for (const s of sites.slice(0, SITE_DISPLAY_CAP)) {
+        process.stdout.write(`  • ${s.token}  (${s.file}:${s.line})\n`);
+    }
+    if (sites.length > SITE_DISPLAY_CAP) {
+        process.stdout.write(`  … (${sites.length - SITE_DISPLAY_CAP} more)\n`);
+    }
+}
+/** Light structural check: a candidate must at least name an id + both sides. */
+function validateCandidate(raw) {
+    if (raw === null || typeof raw !== 'object') {
+        return { error: 'candidate must be a JSON object describing a wiring rule' };
+    }
+    const r = raw;
+    if (typeof r['id'] !== 'string' || r['id'].length === 0) {
+        return { error: 'candidate is missing a non-empty string "id"' };
+    }
+    const declared = r['declared'];
+    if (declared === null || typeof declared !== 'object' || !Array.isArray(declared.files)) {
+        return { error: 'candidate "declared" must be a source object with a files[] glob list' };
+    }
+    if (r['registered'] === undefined) {
+        return { error: 'candidate is missing "registered" (a source object or an array of them)' };
+    }
+    // Deeper misconfiguration (bad regex / no capture group) is surfaced as a
+    // diagnostic by the engine, not rejected here — that is the point of a dry run.
+    return { rule: raw };
+}
+async function wiringExplain(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const ruleId = args.positional[1];
+    if (!ruleId) {
+        process.stderr.write('Usage: shrk wiring explain <ruleId> [--json]\n');
+        return 2;
+    }
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok) {
+        const msg = loaded.error.message;
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${msg}\n`);
+        return 1;
+    }
+    const rules = loaded.value.config.wiringRules ?? [];
+    const rule = rules.find((r) => r.id === ruleId);
+    if (!rule) {
+        const ids = rules.map((r) => r.id);
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'not-found', ruleId, available: ids }) + '\n');
+            return 2;
+        }
+        process.stderr.write(`No wiring rule "${ruleId}". Configured rules: ${ids.length > 0 ? ids.join(', ') : '(none)'}\n`);
+        return 2;
+    }
+    return renderWiringExplain(explainWiring(cwd, rule), wantJson);
+}
+async function wiringTest(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const candidateArg = args.positional[1];
+    if (!candidateArg) {
+        process.stderr.write('Usage: shrk wiring test <candidate.json | inline-json> [--json]\n' +
+            '  Dry-runs an ephemeral wiring rule against the live tree without writing config.\n');
+        return 2;
+    }
+    // A leading `{` is treated as inline JSON; otherwise the arg is a file path.
+    let source;
+    if (candidateArg.trimStart().startsWith('{')) {
+        source = candidateArg;
+    }
+    else {
+        if (!existsSync(candidateArg)) {
+            const msg = `candidate file not found: ${candidateArg}`;
+            if (wantJson)
+                process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
+            else
+                process.stderr.write(msg + '\n');
+            return 2;
+        }
+        source = readFileSync(candidateArg, 'utf8');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (e) {
+        const msg = `candidate is not valid JSON: ${e instanceof Error ? e.message : String(e)}`;
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
+        else
+            process.stderr.write(msg + '\n');
+        return 2;
+    }
+    const { rule, error } = validateCandidate(parsed);
+    if (!rule) {
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error }) + '\n');
+        else
+            process.stderr.write(`Invalid candidate: ${error}\n`);
+        return 2;
+    }
+    return renderWiringExplain(explainWiring(cwd, rule), wantJson);
+}
+/**
+ * Load the configured DI/registration idioms and build the graph, cached by a
+ * signature of the exact source files it reads + an idiom hash. Repeated session
+ * queries (chain + unprovided + orphans) reuse ONE scan; any edit to a matched
+ * file shifts the signature and rebuilds, so the cache can never return a stale
+ * verdict (no `shrk graph index` required — the cache tracks its real data
+ * source, not the unrelated code-graph digest). Best-effort — any read/write
+ * error falls back to a fresh build.
+ */
+async function loadRegistrationGraph(cwd) {
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok)
+        return { ok: false, idioms: [], error: loaded.error.message };
+    const idioms = loaded.value.config.registrationGraph ?? [];
+    if (idioms.length === 0)
+        return { ok: true, idioms: [] };
+    const cacheKey = registrationCacheKey(cwd, idioms);
+    const cachePath = nodePath.join(cwd, '.sharkcraft', 'cache', 'registration-graph.json');
+    if (cacheKey) {
+        const cached = readRegistrationCache(cachePath, cacheKey);
+        if (cached)
+            return { ok: true, idioms, graph: cached };
+    }
+    const graph = buildRegistrationGraph(cwd, idioms);
+    if (cacheKey)
+        writeRegistrationCache(cachePath, cacheKey, graph);
+    return { ok: true, idioms, graph };
+}
+/**
+ * `<file-signature>:<idiom-hash>` — keyed on the mtime/size signature of the
+ * exact files the graph is built from (its real data source), NOT the code-graph
+ * index digest. Any source edit shifts the signature even when no reindex has
+ * run, so the persisted cache can never return a stale wiring verdict. Undefined
+ * only if signing itself throws (then the query rebuilds every time).
+ */
+function registrationCacheKey(cwd, idioms) {
+    try {
+        const signature = registrationGraphSignature(cwd, idioms);
+        const idiomHash = createHash('sha1').update(JSON.stringify(idioms)).digest('hex').slice(0, 16);
+        return `${signature}:${idiomHash}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readRegistrationCache(cachePath, key) {
+    try {
+        if (!existsSync(cachePath))
+            return undefined;
+        const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
+        return cached.key === key && cached.graph ? cached.graph : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeRegistrationCache(cachePath, key, graph) {
+    try {
+        mkdirSync(nodePath.dirname(cachePath), { recursive: true });
+        writeFileSync(cachePath, JSON.stringify({ key, graph }));
+    }
+    catch {
+        // best-effort cache; a write failure never breaks the query.
+    }
+}
+function noIdiomsHint(wantJson) {
+    if (wantJson) {
+        process.stdout.write(asJson({ schema: 'sharkcraft.registration-graph/v1', idioms: [], tokens: [] }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('Registration graph'));
+    process.stdout.write('  No registration idioms configured. Declare `registrationGraph[]` in\n' +
+        '  sharkcraft.config.ts (declared/provided/consumed shapes) to model your DI\n' +
+        '  wiring as a queryable graph — see docs/wiring.md.\n');
+    return 0;
+}
+function siteLine(s) {
+    return `${s.file}:${s.line} [${s.idiom}]`;
+}
+async function wiringChain(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const token = args.positional[1];
+    if (!token) {
+        process.stderr.write('Usage: shrk wiring chain <token> [--json]\n');
+        return 2;
+    }
+    const loaded = await loadRegistrationGraph(cwd);
+    if (!loaded.ok) {
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: loaded.error }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.error}\n`);
+        return 1;
+    }
+    if (!loaded.graph)
+        return noIdiomsHint(wantJson);
+    const chain = registrationChain(loaded.graph, token);
+    if (!chain) {
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'not-found', token }) + '\n');
+            return 1;
+        }
+        process.stdout.write(header(`Wiring chain: ${token}`));
+        process.stdout.write('  Token not found in the registration graph.\n');
+        return 1;
+    }
+    if (wantJson) {
+        process.stdout.write(asJson(chain) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Wiring chain: ${token}`));
+    const section = (label, sites) => {
+        process.stdout.write(`\n${label} (${sites.length}):\n`);
+        if (sites.length === 0)
+            process.stdout.write('  (none)\n');
+        for (const s of sites)
+            process.stdout.write(`  • ${siteLine(s)}\n`);
+    };
+    section('declared', chain.declared);
+    section('provided', chain.provided);
+    section('consumed', chain.consumed);
+    if (!chain.isProvided && (chain.isDeclared || chain.isConsumed)) {
+        process.stdout.write('\n  ⚠ UNPROVIDED — declared/injected but never provided (silent at runtime).\n');
+    }
+    else if (chain.isProvided && !chain.isConsumed) {
+        process.stdout.write('\n  ⚠ ORPHAN — provided but nothing consumes it.\n');
+    }
+    else {
+        process.stdout.write('\n  ✓ declared → provided → consumed.\n');
+    }
+    return 0;
+}
+async function wiringUnprovided(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const loaded = await loadRegistrationGraph(cwd);
+    if (!loaded.ok) {
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: loaded.error }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.error}\n`);
+        return 1;
+    }
+    if (!loaded.graph)
+        return noIdiomsHint(wantJson);
+    const unprovided = registrationUnprovided(loaded.graph);
+    if (wantJson) {
+        process.stdout.write(asJson({ schema: loaded.graph.schema, total: unprovided.length, unprovided }) + '\n');
+        return unprovided.length > 0 ? 1 : 0;
+    }
+    process.stdout.write(header('Unprovided tokens (declared/injected but never provided)'));
+    if (unprovided.length === 0) {
+        process.stdout.write('  ✓ Every declared/injected token has a provider. ✓\n');
+        return 0;
+    }
+    process.stdout.write(`  ${unprovided.length} token(s) resolve to nothing at runtime:\n`);
+    for (const u of unprovided) {
+        const site = u.declared[0] ?? u.consumed[0];
+        const where = site ? `  (${siteLine(site)})` : '';
+        process.stdout.write(`  ✗ ${u.token}${where}\n`);
+    }
+    return 1;
+}
+async function wiringOrphans(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const loaded = await loadRegistrationGraph(cwd);
+    if (!loaded.ok) {
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: loaded.error }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.error}\n`);
+        return 1;
+    }
+    if (!loaded.graph)
+        return noIdiomsHint(wantJson);
+    const orphans = registrationOrphans(loaded.graph);
+    if (wantJson) {
+        process.stdout.write(asJson({ schema: loaded.graph.schema, total: orphans.length, orphans }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('Orphan registrations (provided but nothing consumes)'));
+    if (orphans.length === 0) {
+        process.stdout.write('  ✓ Every provided token is consumed somewhere. ✓\n');
+        return 0;
+    }
+    process.stdout.write(`  ${orphans.length} provided token(s) nothing injects:\n`);
+    for (const o of orphans) {
+        const site = o.provided[0];
+        process.stdout.write(`  • ${o.token}${site ? `  (${siteLine(site)})` : ''}\n`);
+    }
+    return 0;
+}
+const WIRING_USAGE = 'shrk wiring explain <ruleId> | test <candidate.json|inline> | chain <token> | unprovided | orphans [--json]';
+export const wiringCommand = {
+    name: 'wiring',
+    description: 'Author-loop + runtime-wiring queries (no config write): `explain <ruleId>` / `test <candidate>` show what a wiring rule extracts; `chain <token>` / `unprovided` / `orphans` query the DI/registration graph (declared→provided→consumed) for the silent-at-runtime bugs imports can\'t see.',
+    usage: WIRING_USAGE,
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'explain')
+            return wiringExplain(args);
+        if (sub === 'test')
+            return wiringTest(args);
+        if (sub === 'chain')
+            return wiringChain(args);
+        if (sub === 'unprovided')
+            return wiringUnprovided(args);
+        if (sub === 'orphans')
+            return wiringOrphans(args);
+        process.stderr.write(`Usage: ${WIRING_USAGE}\n`);
+        return 2;
+    },
+};