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

package/dist/commands/helper.command.js

@@ -1,44 +1,80 @@
 /**
  * `shrk helper` commands.
  *
- * shrk helper list
+ * shrk helper list [--source builtin|local|pack]
  * shrk helper get <id>
  * shrk helper plan <id> --var k=v [--dry-run] [--output <plan.json>]
+ * shrk helper doctor [--allow-empty]
  *
- * Dry-run by default; never writes source.
+ * Every verb reads THE helper catalog (`listAllHelpers`): built-in helpers ∪
+ * pack/local-contributed ones — the same list the id resolver and the MCP
+ * helper tools read. Dry-run by default; never writes source.
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { buildHelperPlan, HELPERS, HELPER_SYNTHETIC_TEMPLATE, helperPlanToSavedPlan, renderHelperPlanText, } from '@shrkcrft/inspector';
+import { buildHelperPlan, buildPackHelperPlan, ContributionKind, HELPER_SYNTHETIC_TEMPLATE, helperPlanToSavedPlan, inspectSharkcraft, listAllHelpers, renderHelperPlanText, } from '@shrkcrft/inspector';
 import { savePlanToFile, signPlan } from '@shrkcrft/generator';
 import { flagBool, flagString, flagVars, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header } from "../output/format-output.js";
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
+const HELPER_SOURCES = ['builtin', 'local', 'pack'];
 function writePlanFile(content, outputArg, cwd) {
     const abs = nodePath.isAbsolute(outputArg) ? outputArg : nodePath.resolve(cwd, outputArg);
     mkdirSync(nodePath.dirname(abs), { recursive: true });
     writeFileSync(abs, content + '\n', 'utf8');
     return abs;
 }
+function describeSource(h) {
+    if (h.source === 'pack')
+        return `pack ${h.packageName ?? '?'}`;
+    return h.source;
+}
 export const helperListCommand = {
     name: 'list',
-    description: 'List available helpers (one-shot plan generators).',
-    usage: 'shrk helper list [--json]',
+    description: 'List every helper (built-in + pack/local-contributed) with its source. `--source builtin|local|pack` filters.',
+    usage: 'shrk helper list [--source builtin|local|pack] [--json]',
     async run(args) {
+        const source = flagString(args, 'source');
+        if (args.flags.has('source') && (source === undefined || !HELPER_SOURCES.includes(source))) {
+            process.stderr.write(`Invalid --source ${JSON.stringify(source ?? '')}. Expected one of: ${HELPER_SOURCES.join(', ')}\n`);
+            return 3;
+        }
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const catalog = await listAllHelpers(inspection);
+        const entries = source ? catalog.entries.filter((h) => h.source === source) : catalog.entries;
+        const note = { ...(source ? { source } : {}), next: 'shrk helper doctor' };
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(HELPERS) + '\n');
+            process.stdout.write(asJson(entries) + '\n');
+            await writeRejectedEntriesNote(inspection, [ContributionKind.Helper], { ...note, json: true });
             return 0;
         }
-        process.stdout.write(header(`Helpers (${HELPERS.length})`));
-        for (const h of HELPERS) {
+        process.stdout.write(header(`Helpers (${entries.length})`));
+        if (entries.length > 0) {
+            process.stdout.write(`                ${'ID'.padEnd(34)} ${'SOURCE'.padEnd(24)} DESCRIPTION\n`);
+        }
+        for (const h of entries) {
             const marker = h.destructive ? '[destructive] ' : '              ';
-            process.stdout.write(`  ${marker}${h.id.padEnd(34)} ${h.description}\n`);
+            process.stdout.write(`  ${marker}${h.id.padEnd(34)} ${describeSource(h).padEnd(24)} ${h.description}\n`);
         }
+        // A FILE that did not load is said as such; an ENTRY its loader refused is
+        // named with its reason (round 12, 12.1) — the old line counted both as
+        // "helper file error(s)".
+        const brokenFiles = catalog.files.filter((f) => f.status !== 'loaded').length;
+        if (brokenFiles > 0) {
+            process.stdout.write(`\n${brokenFiles} helper file(s) failed to load or are missing — run \`shrk helper doctor\`.\n`);
+        }
+        // Load failures are the broken-file line above — never said twice.
+        await writeRejectedEntriesNote(inspection, [ContributionKind.Helper], { ...note, loadFailures: false });
         return 0;
     },
 };
 export const helperGetCommand = {
     name: 'get',
-    description: 'Show a helper definition (variables, safety flags).',
+    description: 'Show a helper definition (source, variables, safety flags, operations).',
     usage: 'shrk helper get <id> [--json]',
     async run(args) {
         const id = args.positional[0];
@@ -46,7 +82,8 @@ export const helperGetCommand = {
             process.stderr.write('Usage: shrk helper get <id>\n');
             return 2;
         }
-        const def = HELPERS.find((h) => h.id === id);
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const def = (await listAllHelpers(inspection)).entries.find((h) => h.id === id);
         if (!def) {
             process.stderr.write(`Unknown helper: ${id}\n`);
             return 1;
@@ -56,19 +93,63 @@ export const helperGetCommand = {
             return 0;
         }
         process.stdout.write(header(`Helper: ${def.id}`));
+        process.stdout.write(`  title           ${def.title}\n`);
         process.stdout.write(`  description     ${def.description}\n`);
+        process.stdout.write(`  source          ${describeSource(def)}${def.sourceFile ? ` (${def.sourceFile})` : ''}\n`);
+        process.stdout.write(`  output          ${def.outputKind}\n`);
         process.stdout.write(`  destructive     ${def.destructive ? 'yes' : 'no'}\n`);
         process.stdout.write(`  review          ${def.requiresHumanReview ? 'human review required' : 'auto'}\n`);
+        if (def.requiresProfile)
+            process.stdout.write(`  profile         required\n`);
         process.stdout.write(`  variables       ${def.variables.length}\n`);
         for (const v of def.variables) {
-            process.stdout.write(`    • ${v.name}${v.required ? ' (required)' : ''} — ${v.description}\n`);
+            const dflt = v.defaultValue !== undefined ? ` [default: ${v.defaultValue}]` : '';
+            process.stdout.write(`    • ${v.name}${v.required ? ' (required)' : ''}${dflt} — ${v.description}\n`);
+        }
+        if (def.operations.length > 0) {
+            process.stdout.write(`  operations      ${def.operations.length}\n`);
+            for (const op of def.operations) {
+                // A pack op may omit `description` (a manual-checklist op usually
+                // carries only `checklist[]`) — never interpolate an absent field.
+                const desc = op.description;
+                const detail = desc && desc.trim().length > 0 ? desc : (op.checklist ?? []).join('; ');
+                process.stdout.write(`    • ${op.kind}${op.targetPath ? ` ${op.targetPath}` : ''}${detail ? ` — ${detail}` : ''}\n`);
+            }
+        }
+        if (def.manualChecklist.length > 0) {
+            process.stdout.write(`  checklist       ${def.manualChecklist.length}\n`);
+            for (const c of def.manualChecklist)
+                process.stdout.write(`    • ${c}\n`);
         }
         return 0;
     },
 };
+function writePlanOutput(plan, args, cwd) {
+    const output = flagString(args, 'output');
+    if (flagBool(args, 'json')) {
+        const body = asJson(plan);
+        if (output) {
+            const abs = writePlanFile(body, output, cwd);
+            process.stdout.write(`Wrote ${abs}\n`);
+        }
+        else {
+            process.stdout.write(body + '\n');
+        }
+        return 0;
+    }
+    process.stdout.write(renderHelperPlanText(plan));
+    if (plan.destructive) {
+        process.stdout.write('\n⚠ DESTRUCTIVE — human approval required.\n');
+    }
+    if (output) {
+        const abs = writePlanFile(asJson(plan), output, cwd);
+        process.stdout.write(`\nSaved plan to ${abs}\n`);
+    }
+    return 0;
+}
 export const helperPlanCommand = {
     name: 'plan',
-    description: 'Generate a plan-only helper plan (dry-run by default). Pass --save-plan <file> to emit a saved plan that flows through `shrk apply`.',
+    description: 'Generate a plan-only helper plan (dry-run by default). Built-in helpers: pass --save-plan <file> to emit a saved plan that flows through `shrk apply`. Pack/local helpers render their declarative operations; --save-plan is refused for them.',
     usage: 'shrk helper plan <id> --var k=v [--output <plan.json>] [--save-plan <file>] [--sign] [--json]',
     async run(args) {
         const id = args.positional[0];
@@ -76,23 +157,37 @@ export const helperPlanCommand = {
             process.stderr.write('Usage: shrk helper plan <id> --var k=v\n');
             return 2;
         }
-        const def = HELPERS.find((h) => h.id === id);
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const def = (await listAllHelpers(inspection)).entries.find((h) => h.id === id);
         if (!def) {
             process.stderr.write(`Unknown helper: ${id}\n`);
             return 1;
         }
-        // Helpers with requiresProfile must error explicitly when no
-        // profile is available. Today the helper-registry detects this inside
-        // buildHelperPlan via requireProfile(); we surface a friendly message.
-        if ('requiresProfile' in def && def.requiresProfile) {
+        const vars = flagVars(args);
+        const savePlanPath = flagString(args, 'save-plan');
+        if (def.source !== 'builtin') {
+            if (savePlanPath) {
+                // helperPlanToSavedPlan is an identity stub: writing its output would
+                // produce a file `shrk apply` cannot read. Refuse loudly, never fake it.
+                process.stderr.write(`Refusing --save-plan for ${describeSource(def)} helper "${id}": a declarative helper plan cannot yet be converted into a saved plan \`shrk apply\` reads. Use --output <file> (the preview JSON) and apply the operations by hand.\n`);
+                return 2;
+            }
+            if (def.requiresProfile) {
+                process.stderr.write(`Helper "${id}" requires a registered profile. Available:\n  $ shrk profiles list\n`);
+            }
+            const built = buildPackHelperPlan(def, vars);
+            if (!built.ok) {
+                process.stderr.write(`${built.message}\n`);
+                return 1;
+            }
+            return writePlanOutput(built.plan, args, cwd);
+        }
+        if (def.requiresProfile) {
             process.stderr.write(`Helper "${id}" requires a registered profile. Available:\n  $ shrk profiles list\n`);
-            // Still try to build the plan; the registry throws with the same idea.
         }
-        const cwd = resolveCwd(args);
-        const vars = flagVars(args);
         try {
             const plan = buildHelperPlan({ helperId: id, projectRoot: cwd, vars });
-            const savePlanPath = flagString(args, 'save-plan');
             if (savePlanPath) {
                 const saved = helperPlanToSavedPlan(plan, cwd);
                 let toWrite = saved;
@@ -118,27 +213,7 @@ export const helperPlanCommand = {
                 }
                 return 0;
             }
-            const output = flagString(args, 'output');
-            if (flagBool(args, 'json')) {
-                const body = asJson(plan);
-                if (output) {
-                    const abs = writePlanFile(body, output, cwd);
-                    process.stdout.write(`Wrote ${abs}\n`);
-                }
-                else {
-                    process.stdout.write(body + '\n');
-                }
-                return 0;
-            }
-            process.stdout.write(renderHelperPlanText(plan));
-            if (plan.destructive) {
-                process.stdout.write('\n⚠ DESTRUCTIVE — human approval required.\n');
-            }
-            if (output) {
-                const abs = writePlanFile(asJson(plan), output, cwd);
-                process.stdout.write(`\nSaved plan to ${abs}\n`);
-            }
-            return 0;
+            return writePlanOutput(plan, args, cwd);
         }
         catch (e) {
             process.stderr.write(`${e.message}\n`);
@@ -146,25 +221,89 @@ export const helperPlanCommand = {
         }
     },
 };
+export const helperDoctorCommand = {
+    name: 'doctor',
+    description: 'Validate every helper file (local helpers.ts + pack helperFiles[]): load failures, invalid helpers, duplicate ids, unknown operation keys. Exit 0 clean · 1 errors · 2 nothing examined (pass --allow-empty to accept an empty helper set).',
+    usage: 'shrk helper doctor [--allow-empty] [--json]',
+    booleanFlags: new Set([ALLOW_EMPTY_FLAG, 'json']),
+    async run(args) {
+        const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+        const catalog = await listAllHelpers(inspection);
+        const errors = catalog.issues.filter((i) => i.severity === 'error');
+        const warnings = catalog.issues.filter((i) => i.severity === 'warning');
+        const unexamined = catalog.files.filter((f) => f.status !== 'loaded');
+        const coverage = {
+            unit: 'helper files',
+            expected: catalog.files.length,
+            examined: catalog.files.length - unexamined.length,
+            root: inspection.projectRoot,
+            ...(unexamined.length > 0
+                ? {
+                    unexamined: unexamined.slice(0, 20).map((f) => nodePath.relative(inspection.projectRoot, f.file) || f.file),
+                    unexaminedTotal: unexamined.length,
+                    reason: 'failed to load or missing',
+                }
+                : { reason: 'no helpers.ts and no pack helperFiles[] declared' }),
+            ...allowEmptyValve(args, catalog.files.length),
+        };
+        const settled = settleVerdict(errors.length > 0 ? 1 : 0, [coverage]);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                helpers: catalog.entries.length,
+                files: catalog.files,
+                issues: catalog.issues,
+                coverage,
+                exitCode: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
+            }) + '\n');
+            return settled.exit;
+        }
+        process.stdout.write(header('Helper doctor'));
+        process.stdout.write(`  helpers ${catalog.entries.length} · files ${catalog.files.length} (${catalog.files.length - unexamined.length} loaded)\n\n`);
+        for (const i of catalog.issues) {
+            process.stdout.write(`  ${i.severity.toUpperCase().padEnd(8)} ${i.code.padEnd(16)} ${i.helperId ? `${i.helperId} ` : ''}${i.message}${i.source ? `  (${i.source})` : ''}\n`);
+        }
+        if (catalog.issues.length > 0)
+            process.stdout.write('\n');
+        if (settled.exit === 1) {
+            process.stdout.write(`${errors.length} helper error(s), ${warnings.length} warning(s).\n`);
+        }
+        const line = verdictLine(settled, `Helpers OK — ${catalog.entries.length} helper(s) from ${catalog.files.length} file(s)${warnings.length > 0 ? `, ${warnings.length} warning(s) above` : ''}. ✓`, catalog.files.length === 0 ? 'No helper files to examine.' : undefined);
+        if (line)
+            process.stdout.write(line + '\n');
+        if (settled.exit === 2 && catalog.files.length === 0) {
+            process.stdout.write('Pass --allow-empty to accept an empty helper set explicitly.\n');
+        }
+        return settled.exit;
+    },
+};
 export const helperCommand = {
     name: 'helper',
-    description: 'Helper plan generators (list / get / plan). Plan-only, dry-run default.',
-    usage: 'shrk helper list|get <id>|plan <id> --var k=v',
+    positionals: PositionalMode.None,
+    subverbs: [
+        { name: 'list', description: 'List the helpers.', usage: 'shrk helper list [--json]' },
+        { name: 'get', description: 'Show one helper.', usage: 'shrk helper get <id> [--json]', positionals: PositionalMode.Free },
+        { name: 'plan', description: 'Plan one helper (dry-run).', usage: 'shrk helper plan <id> --var k=v', positionals: PositionalMode.Free },
+        { name: 'doctor', description: 'Helper files loaded + validated.', usage: 'shrk helper doctor [--allow-empty] [--json]' },
+    ],
+    description: 'Helper plan generators (list / get / plan / doctor). Plan-only, dry-run default.',
+    usage: 'shrk helper list|get <id>|plan <id> --var k=v|doctor',
     async run(args) {
         const sub = args.positional[0];
-        if (sub === 'list') {
-            args.positional = args.positional.slice(1);
-            return helperListCommand.run(args);
-        }
-        if (sub === 'get') {
-            args.positional = args.positional.slice(1);
-            return helperGetCommand.run(args);
-        }
-        if (sub === 'plan') {
+        const dispatch = {
+            list: helperListCommand,
+            get: helperGetCommand,
+            plan: helperPlanCommand,
+            doctor: helperDoctorCommand,
+        };
+        const handler = sub ? dispatch[sub] : undefined;
+        if (handler) {
             args.positional = args.positional.slice(1);
-            return helperPlanCommand.run(args);
+            return handler.run(args);
         }
-        process.stderr.write('Usage: shrk helper list|get <id>|plan <id>\n');
+        process.stderr.write('Usage: shrk helper list|get <id>|plan <id>|doctor\n');
         return 2;
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2ahC,eAAO,MAAM,aAAa,EAAE,eAsW3B,CAAC"}
+{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAQL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0ehC,eAAO,MAAM,aAAa,EAAE,eAmZ3B,CAAC"}

package/dist/commands/impact.command.js

@@ -1,10 +1,18 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { analyzeImpact, analyzeTestImpact, findSymbolInProject, FuzzyImpactSourceKind, getChangedFiles, ImpactInputKind, inspectSharkcraft, QueryMatchKind, readFeatureBundle, renderImpactGraph, renderImpactHtml, renderImpactMarkdown, renderImpactText, resolveFuzzyImpact, warmConstructCache, } from '@shrkcrft/inspector';
-import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { emptySelectionExit, flagBool, flagNumber, flagString, flagList, requireInputSelector, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { formatCoverage } from '@shrkcrft/core';
 import { asJson, header, kv } from "../output/format-output.js";
 import { fuzzyImpactAmbiguousHints, renderFailureHints } from "../output/failure-hints.js";
 import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
+import { deletedOrphanCoverage } from "../diff/deleted-orphan-coverage.js";
+import { deletedOrphanScopeNotes } from "../diff/deleted-orphan-scope-notes.js";
+import { ExitCode } from "../exit-codes.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 function collectFiles(args, cwd) {
     const diagnostics = [];
     const explicitFiles = flagList(args, 'files');
@@ -286,12 +294,20 @@ async function runViaGraph(args) {
  * default branch) and queries the graph for surviving files that still
  * import them or reference a symbol they declared (alias-resolved, incl.
  * barrel re-exports). Any surviving importer is reported with `file:line`
- * and the command exits non-zero; with none it exits 0 with
- * "no orphaned importers". Mirrors `--via-graph`'s flag/JSON style.
+ * and the command exits 1. Mirrors `--via-graph`'s flag/JSON style.
  *
  * The graph is queried against the CURRENT index snapshot — a not-yet-
  * reindexed delete still carries its inbound edges, which is exactly what
  * lets the check see the broken importers before they hit the build.
+ *
+ * It answers the same question as `shrk check orphans`, from the same scan,
+ * and settles the same way: "no orphaned importers" (exit 0) only when every
+ * deleted source file was checked against an index current for every
+ * surviving importer. A deleted source file the index does not know, an index
+ * that never read files changed since it was built, or nothing deleted at all
+ * is NOT VERIFIED (2). `--allow-empty` accepts an EMPTY scope (nothing the
+ * graph indexes was deleted) explicitly — never a stale one. `--json` carries
+ * `coverage`, `indexDivergence`, `exitCode`, `verdict` and `shortfalls`.
  */
 async function runDeletedOrphans(args) {
     const cwd = resolveCwd(args);
@@ -314,8 +330,17 @@ async function runDeletedOrphans(args) {
         }
         return 2;
     }
+    // What the scan examined — the ONE authority `check orphans` settles on
+    // (`deletedOrphanCoverage`): the deleted source files the index knows, over
+    // an index current for every surviving importer. This verb answers the same
+    // question from the same scan, so it settles the same way (`settleVerdict`;
+    // it has no gate envelope): "no orphaned importers" is printed only through
+    // the settled verdict, never over a stale, unindexed or empty scope.
+    const measured = deletedOrphanCoverage(scan);
+    const coverage = { ...measured, ...allowEmptyValve(args, measured.expected) };
     const deleted = scan.deleted;
     if (deleted.length === 0) {
+        const settled = settleVerdict(ExitCode.VerifiedPass, [coverage]);
         if (wantJson) {
             process.stdout.write(asJson({
                 schema: 'sharkcraft.deleted-orphans/v1',
@@ -323,25 +348,55 @@ async function runDeletedOrphans(args) {
                 unresolvedDeleted: [],
                 orphans: [],
                 diagnostics: [`no deleted files in diff vs ${scan.ref}`],
+                coverage,
+                exitCode: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
             }) + '\n');
-            return 0;
+            return settled.exit;
         }
         process.stdout.write(header('Deleted-symbol orphans'));
         process.stdout.write(`No deleted files in diff vs ${scan.ref}.\n`);
-        return 0;
+        const line = verdictLine(settled, 'Nothing deleted — accepted.');
+        if (line)
+            process.stdout.write(`\n${line}\n`);
+        if (settled.exit === ExitCode.NotVerified) {
+            process.stdout.write(`  Pass --${ALLOW_EMPTY_FLAG} to accept an empty diff explicitly.\n`);
+        }
+        return settled.exit;
     }
     const report = scan.report;
+    const settled = settleVerdict(report.orphans.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass, [coverage]);
+    const exit = settled.exit;
     if (wantJson) {
-        process.stdout.write(asJson(report) + '\n');
-        return report.orphans.length > 0 ? 1 : 0;
+        process.stdout.write(asJson({
+            ...report,
+            ...(scan.indexDivergence ? { indexDivergence: scan.indexDivergence } : {}),
+            coverage,
+            exitCode: exit,
+            verdict: settled.verdict,
+            shortfalls: settled.shortfalls,
+            accepted: settled.accepted,
+        }) + '\n');
+        return exit;
     }
+    const notes = deletedOrphanScopeNotes(scan, coverage, 'shrk impact --deleted');
     process.stdout.write(header('Deleted-symbol orphans'));
     process.stdout.write(`Deleted files (vs ${scan.ref}): ${deleted.length}\n`);
+    process.stdout.write(kv('coverage', formatCoverage(coverage)) + '\n');
+    if (notes.index !== undefined)
+        process.stdout.write(kv('index', notes.index) + '\n');
     if (report.orphans.length === 0) {
-        process.stdout.write('no orphaned importers\n');
         for (const d of report.diagnostics.slice(0, 5))
             process.stdout.write(`! ${d}\n`);
-        return 0;
+        const line = verdictLine(settled, 'no orphaned importers', notes.lead);
+        if (line)
+            process.stdout.write(`${line}\n`);
+        if (exit === ExitCode.NotVerified && coverage.expected === 0) {
+            process.stdout.write(`  Pass --${ALLOW_EMPTY_FLAG} to accept a delete with no indexed source files explicitly.\n`);
+        }
+        return exit;
     }
     process.stdout.write(`\n${report.orphans.length} surviving importer(s) still reference deleted code:\n`);
     for (const o of report.orphans) {
@@ -353,12 +408,42 @@ async function runDeletedOrphans(args) {
     }
     for (const d of report.diagnostics.slice(0, 5))
         process.stdout.write(`! ${d}\n`);
-    return 1;
+    // A surviving importer is real even over a partial scope (1); the line names
+    // what was not examined next to it.
+    const tail = verdictLine(settled, '');
+    if (tail)
+        process.stdout.write(`${tail}\n`);
+    return exit;
 }
 export const impactCommand = {
     name: 'impact',
+    // Free: `impact <fileOrQuery>` resolves a fuzzy query, never refused.
+    positionals: PositionalMode.Free,
+    subverbs: [
+        { name: 'tests', description: 'The tests a change impacts.', usage: 'shrk impact tests ["<task>"] [--files a,b] [--since <ref>] [--json]', positionals: PositionalMode.Free },
+        {
+            name: 'graph',
+            description: 'Render a saved impact report as a graph.',
+            usage: 'shrk impact graph <impact-report.json> [--format mermaid|dot] [--output <path>]',
+            positionals: PositionalMode.Path,
+        },
+        {
+            name: 'baseline',
+            description: 'Write / show / clear the impact baseline (`show` is the default).',
+            usage: 'shrk impact baseline <write|show|clear> [--json]',
+            positionals: PositionalMode.None,
+            subverbs: [
+                { name: 'write', description: 'Write the impact baseline.', usage: 'shrk impact baseline write [--json]' },
+                { name: 'show', description: 'Show the impact baseline.', usage: 'shrk impact baseline show [--json]' },
+                { name: 'clear', description: 'Clear the impact baseline.', usage: 'shrk impact baseline clear [--json]' },
+            ],
+        },
+    ],
     description: 'Architecture impact analysis: direct + transitive dependents, risk + suggested commands. Supports fuzzy <query> resolution. Read-only.',
-    usage: 'shrk impact <fileOrQuery> | --file <path> | --specifier <spec> | --since <ref> | --staged | --files a,b | --plan <plan.json> | --bundle <id> | --deleted [--since <ref>] [--max-depth N] [--limit N] [--format text|markdown|html|json] [--output <path>] [--tree|--no-tree] [--json] [--html] [--resolve|--resolve-only|--explain-resolution|--no-resolve]',
+    usage: 'shrk impact <fileOrQuery> | --file <path> | --specifier <spec> | --since <ref> | --staged | --files a,b | --plan <plan.json> | --bundle <id> | --deleted [--since <ref>] [--allow-empty] [--max-depth N] [--limit N] [--format text|markdown|html|json] [--output <path>] [--tree|--no-tree] [--json] [--html] [--resolve|--resolve-only|--explain-resolution|--no-resolve]',
+    // `--deleted` and `--allow-empty` take no value — they must never swallow a
+    // following positional.
+    booleanFlags: new Set(['deleted', ALLOW_EMPTY_FLAG]),
     async run(args) {
         if (args.positional[0] === 'tests') {
             return runImpactTests({ ...args, positional: args.positional.slice(1) });
@@ -383,6 +468,15 @@ export const impactCommand = {
         if (args.flags.has('deleted')) {
             return runDeletedOrphans(args);
         }
+        // No input at all is a usage error (3) — it used to render as a confident
+        // `Impact (empty) … Risk: low`, a verdict over nothing.
+        const noSelector = requireInputSelector(args, {
+            flags: ['file', 'files', 'specifier', 'since', 'staged', 'plan', 'bundle', 'task', 'symbol'],
+            positional: true,
+            usage: 'shrk impact <fileOrQuery> | --file <path> | --files a,b | --specifier <spec> | --since <ref> | --staged | --plan <plan.json> | --bundle <id> | --task "<text>" | --symbol <Name> | --deleted',
+        });
+        if (noSelector !== null)
+            return noSelector;
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         // Warm construct cache so fuzzy resolution can map plugin keys / events /
@@ -415,7 +509,7 @@ export const impactCommand = {
                     }
                     process.stdout.write('\nNext commands:\n');
                     process.stdout.write(`  shrk trace --symbol ${symbolFlag}\n`);
-                    process.stdout.write(`  shrk find "${symbolFlag}"\n`);
+                    process.stdout.write(`  shrk search "${symbolFlag}"\n`);
                 }
                 return 1;
             }
@@ -464,6 +558,15 @@ export const impactCommand = {
         const collected = collectFiles(args, cwd);
         const positionalRest = args.positional.slice(1).join(' ').trim();
         const task = flagString(args, 'task') ?? (positionalRest.length > 0 ? positionalRest : undefined);
+        // A selector was given but resolved to 0 files (`--since HEAD` on a clean
+        // tree): nothing was analysed — 2, never `Impact (empty) … Risk: low`.
+        if (collected.files.length === 0 &&
+            collected.planTargets.length === 0 &&
+            collected.specifier === undefined &&
+            task === undefined &&
+            args.positional.length === 0) {
+            return emptySelectionExit(flagBool(args, 'json') || flagString(args, 'format') === 'json');
+        }
         const maxDepth = flagNumber(args, 'max-depth');
         const limit = flagNumber(args, 'limit');
         // Fuzzy query resolution.

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

@@ -1 +1 @@
-{"version":3,"file":"infer.command.d.ts","sourceRoot":"","sources":["../../src/commands/infer.command.ts"],"names":[],"mappings":"AAYA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2BhC,eAAO,MAAM,YAAY,EAAE,eAe1B,CAAC"}
+{"version":3,"file":"infer.command.d.ts","sourceRoot":"","sources":["../../src/commands/infer.command.ts"],"names":[],"mappings":"AAYA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,YAAY,EAAE,eAuB1B,CAAC"}

package/dist/commands/infer.command.js

@@ -1,7 +1,7 @@
-import { existsSync, readdirSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { inferTemplateBodyV2, inspectSharkcraft, loadScaffoldPatternsFromInspection, matchScaffoldPattern, extractVariablesForFile, } from '@shrkcrft/inspector';
+import { enumerateScaffoldPatternCandidates, inferTemplateBodyV2, inspectSharkcraft, loadScaffoldPatternsFromInspection, walkScaffoldCandidateFiles, extractVariablesForFile, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header } from "../output/format-output.js";
 const KIND_MAP = {
     service: 'service',
@@ -17,6 +17,14 @@ const KIND_MAP = {
 };
 export const inferCommand = {
     name: 'infer',
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'templates',
+            description: 'Template-body draft candidates (TypeScript compiler API + pack scaffold patterns).',
+            usage: 'shrk infer templates [--ast] [--kind service|utility|test|component] [--include <glob>] [--limit N] [--json]',
+        },
+    ],
     description: 'Inference helpers (templates / boundaries). `shrk infer templates --ast` produces template-body draft candidates using the TypeScript compiler API when available, with scaffold-pattern–driven detection from installed packs.',
     usage: 'shrk [--cwd <dir>] infer templates [--ast] [--kind service|utility|test|component] [--include <glob>] [--limit N] [--json]',
     async run(args) {
@@ -125,22 +133,20 @@ async function runInferTemplates(args) {
 }
 function collectCandidateFiles(input) {
     const seen = new Map();
-    // 1. Scaffold-pattern matches.
+    // 1. Scaffold-pattern matches — THE enumeration the scaffold doctor counts
+    //    with, so a pattern the doctor calls dead is one infer never matches.
     if (input.patterns.length > 0) {
-        walk(input.cwd, (abs, rel) => {
-            for (const p of input.patterns) {
-                if (matchScaffoldPattern(p.pattern, rel)) {
-                    if (!seen.has(abs))
-                        seen.set(abs, { absPath: abs, pattern: p });
-                    return;
-                }
-            }
-        });
+        const byId = new Map(input.patterns.map((p) => [p.pattern.id, p]));
+        for (const m of enumerateScaffoldPatternCandidates(input.cwd, input.patterns).firstMatch) {
+            const abs = nodePath.join(input.cwd, m.file);
+            if (!seen.has(abs))
+                seen.set(abs, { absPath: abs, pattern: byId.get(m.patternId) });
+        }
     }
-    // 2. Generic kind-based scan if there are no matches yet.
+    // 2. Generic kind-based scan if there are no matches yet (the same walker).
     if (seen.size === 0) {
         const dirToken = kindToDir(input.kind);
-        walk(input.cwd, (abs, rel) => {
+        walkScaffoldCandidateFiles(input.cwd, (abs, rel) => {
             if (rel.includes(`/${dirToken}/`) && /\.(tsx?|jsx?)$/.test(abs)) {
                 if (!seen.has(abs))
                     seen.set(abs, { absPath: abs });
@@ -166,37 +172,6 @@ function kindToDir(kind) {
             return 'components';
     }
 }
-function walk(root, onFile) {
-    const visit = (dir) => {
-        let entries;
-        try {
-            entries = readdirSync(dir);
-        }
-        catch {
-            return;
-        }
-        for (const e of entries) {
-            if (e === 'node_modules' || e === '.git' || e === 'dist' || e === '.sharkcraft' || e === '__tests__')
-                continue;
-            const full = nodePath.join(dir, e);
-            let st;
-            try {
-                st = statSync(full);
-            }
-            catch {
-                continue;
-            }
-            if (st.isDirectory())
-                visit(full);
-            else if (st.isFile()) {
-                const rel = nodePath.relative(root, full).split(nodePath.sep).join('/');
-                onFile(full, rel);
-            }
-        }
-    };
-    if (existsSync(root))
-        visit(root);
-}
 function globRe(g) {
     let re = '^';
     for (let i = 0; i < g.length; i += 1) {