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

package/dist/commands/check.command.js

@@ -9,7 +9,8 @@ import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
 import { renderWiringExplain } from "./wiring.command.js";
 import { validateTemplateVariables } from '@shrkcrft/templates';
 import { FileChangeType, planGeneration } from '@shrkcrft/generator';
-import { evaluateBoundaries, explainWiring, loadTsconfigPaths, runWiring, scanImports, summarizeImports, } from '@shrkcrft/boundaries';
+import { evaluateBoundaries, explainWiring, loadTsconfigPaths, runWiring, scanImports, summarizeImports, planWiringFix, readMatchingFiles, wiringGlobsOf, } from '@shrkcrft/boundaries';
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
 function knowledgeGroup(inspection) {
     const dup = inspection.validationIssues.filter((i) => i.code === 'duplicate-id');
     const missing = inspection.validationIssues.filter((i) => i.code !== 'duplicate-id');
@@ -532,6 +533,93 @@ const WIRING_CHECK_USAGE = 'shrk check wiring [--changed-only] [--since <ref>] [
     '    --only <ids>     run only these rule ids (comma-separated)\n' +
     '    --explain <id>   dry-run ONE rule and print the declared/registered sets it extracts\n' +
     '  Exit: 0 verified pass · 1 violations · 2 not-verified (0 rules evaluated in scope).';
+/**
+ * The honest exit code for a wiring run.
+ *
+ * The banner already said "Not a full green" when some rules were skipped, but
+ * the code an agent chains on returned `0` — a rule that enforced NOTHING was
+ * masked by its passing siblings. The verdict must match the sentence:
+ *
+ *   `1` violations (or a `failOnEmpty` skip, which the engine folds into the verdict)
+ *   `2` nothing evaluated, OR anything skipped — partially verified is not verified
+ *   `0` only when every configured rule actually ran and passed
+ */
+function wiringExitCode(report, evaluated) {
+    if (report.verdict === 'errors')
+        return ExitCode.Failure;
+    if (evaluated === 0)
+        return ExitCode.NotVerified;
+    if (report.skipped.length > 0)
+        return ExitCode.NotVerified;
+    return ExitCode.VerifiedPass;
+}
+/**
+ * `check wiring --fix` — append a declared-but-unregistered token to its sink
+ * array, but ONLY where the edit is mechanically unambiguous.
+ *
+ * Dry-run by default: it prints the exact diff it would make and writes
+ * nothing. `--write` applies it. Anything the planner will not touch is listed
+ * with the reason, because a gate that silently half-fixes is worse than one
+ * that does nothing — the user must be able to see what was left.
+ */
+function runWiringFix(cwd, rules, report, write, wantJson) {
+    const allEdits = [];
+    const allSkips = [];
+    // Read every file a sink could live in, once.
+    const globs = [...new Set(rules.flatMap((r) => wiringGlobsOf(r)))];
+    const cache = readMatchingFiles(cwd, globs, new Set());
+    const files = [...cache.entries()].map(([path, content]) => ({ path, content }));
+    for (const rule of rules) {
+        const violations = report.violations.filter((v) => v.ruleId === rule.id);
+        if (violations.length === 0)
+            continue;
+        const plan = planWiringFix(rule, violations, files);
+        allEdits.push(...plan.edits);
+        allSkips.push(...plan.skipped);
+    }
+    // One write per file: the planner threads each file's content forward, so the
+    // LAST edit for a path carries every earlier insertion.
+    const finalByFile = new Map();
+    for (const e of allEdits)
+        finalByFile.set(e.file, e.nextContent);
+    let written = 0;
+    if (write) {
+        for (const [rel, content] of finalByFile) {
+            writeFileSync(nodePath.resolve(cwd, rel), content, 'utf8');
+            written += 1;
+        }
+    }
+    if (wantJson) {
+        process.stdout.write(asJson({
+            schema: 'sharkcraft.wiring-fix/v1',
+            applied: write,
+            filesWritten: written,
+            edits: allEdits.map(({ nextContent: _drop, ...rest }) => rest),
+            skipped: allSkips,
+        }) + '\n');
+        return allEdits.length === 0 && allSkips.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+    }
+    process.stdout.write(header(write ? 'Wiring fix (applied)' : 'Wiring fix (dry run)'));
+    if (allEdits.length === 0 && allSkips.length === 0) {
+        process.stdout.write('  Nothing to fix — no declared-but-unregistered tokens.\n');
+        return ExitCode.VerifiedPass;
+    }
+    for (const e of allEdits) {
+        process.stdout.write(`  ${write ? 'wrote  ' : 'would add'} ${e.token} → ${e.file}:${e.line}\n`);
+        process.stdout.write(`      + ${e.insert}\n`);
+    }
+    if (allSkips.length > 0) {
+        process.stdout.write(`\n  Left untouched (${allSkips.length}) — not mechanically unambiguous:\n`);
+        for (const sk of allSkips) {
+            process.stdout.write(`    • ${sk.token}  [${sk.reason}] ${sk.detail}\n`);
+        }
+    }
+    process.stdout.write(write
+        ? `\n${written} file(s) written. Re-run \`shrk check wiring\` to confirm, and review the diff.\n`
+        : '\nDry run — nothing written. Re-run with `--write` to apply.\n');
+    // An unfixable violation still means the gate is red.
+    return allSkips.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+}
 async function checkWiring(args) {
     const cwd = resolveCwd(args);
     // `--help`/`-h` on the subverb documents its own scoping flags instead of
@@ -570,7 +658,7 @@ async function checkWiring(args) {
         const explainId = flagString(args, 'explain');
         if (!explainId) {
             process.stderr.write('Usage: shrk check wiring --explain <ruleId> [--json]\n');
-            return 2;
+            return ExitCode.UsageError;
         }
         const rule = rules.find((r) => r.id === explainId);
         if (!rule) {
@@ -580,7 +668,7 @@ async function checkWiring(args) {
                 return 2;
             }
             process.stderr.write(`No wiring rule "${explainId}". Configured rules: ${ids.length > 0 ? ids.join(', ') : '(none)'}\n`);
-            return 2;
+            return ExitCode.UsageError;
         }
         return renderWiringExplain(explainWiring(cwd, rule), wantJson);
     }
@@ -637,6 +725,10 @@ async function checkWiring(args) {
     // blast radius, not just the rules whose literal files were edited (a25 §3.2).
     const selectedRuleIds = report.rules.map((r) => r.ruleId);
     const scoped = changedOnly || since !== undefined;
+    // ── --fix: deterministic, heavily-guarded autofix ─────────────────────
+    if (flagBool(args, 'fix')) {
+        return runWiringFix(cwd, rules, report, flagBool(args, 'write'), wantJson);
+    }
     if (wantJson) {
         // Carry the honest counts so a machine consumer can tell "0 evaluated" from
         // a real green, and see how many rules the scope skipped + which fired.
@@ -650,15 +742,31 @@ async function checkWiring(args) {
             notVerified,
             selectedRuleIds,
             // Distinguish verified-pass / failure / not-verified for a chained gate.
-            exitCode: evaluated === 0 ? ExitCode.NotVerified : report.verdict === 'errors' ? ExitCode.Failure : ExitCode.VerifiedPass,
+            exitCode: wiringExitCode(report, evaluated),
+            // One shape across every plane — see docs/gate-json.md.
+            gate: buildGateEnvelope('check wiring', wiringExitCode(report, evaluated), report.rules.map((r) => {
+                const skip = report.skipped.find((s) => s.ruleId === r.ruleId);
+                return {
+                    id: r.ruleId,
+                    type: 'wiring',
+                    status: r.status,
+                    severity: r.severity,
+                    counts: { declared: r.declaredCount, registered: r.registeredCount },
+                    violations: r.violations.map((v) => ({
+                        id: v.token,
+                        file: v.file,
+                        line: v.line,
+                        ...(v.message ? { message: v.message } : {}),
+                        ...(v.hint ? { hint: v.hint } : {}),
+                    })),
+                    ...(skip ? { skipReason: skip.reason } : {}),
+                    ...(r.error ? { error: r.error } : {}),
+                };
+            })),
         }) + '\n');
         // `evaluated === 0` = nothing checked in scope → NOT verified (`2`), never a
         // silent `0` an agent's `&& next` would march past (a25 §1.1).
-        return evaluated === 0
-            ? ExitCode.NotVerified
-            : report.verdict === 'errors'
-                ? ExitCode.Failure
-                : ExitCode.VerifiedPass;
+        return wiringExitCode(report, evaluated);
     }
     process.stdout.write(header('Wiring check'));
     // `evaluated` counts rules that actually ran a comparison (globs matched >0
@@ -686,7 +794,32 @@ async function checkWiring(args) {
         for (const d of report.diagnostics)
             process.stdout.write(`  ! ${d}\n`);
     }
+    // Rules that checked NOTHING, reported per-rule. `matchedNothing` gives the
+    // count; this names them, because "which rule went stale" is the actionable
+    // half. A `failOnEmpty` rule turns its own skip into a hard failure.
+    if (report.skipped.length > 0) {
+        process.stdout.write('\nRules that checked nothing:\n');
+        for (const sk of report.skipped) {
+            process.stdout.write(`  ${sk.failed ? '✗' : '–'} ${sk.ruleId} ${sk.failed ? 'FAILED' : 'SKIPPED'} — ${sk.reason}\n`);
+        }
+        if (report.skipped.some((sk) => !sk.failed)) {
+            process.stdout.write('  Fix the selector, or set `failOnEmpty: true` once the rule is known to have\n' +
+                '  real subjects. Run `shrk gates coverage` to audit every plane at once.\n');
+        }
+    }
+    // A sink that extracted 0 ids while the source had some is a real failure, but
+    // almost always a stale SINK glob — say so instead of listing N "unwired"
+    // tokens with no explanation.
+    for (const r of report.rules) {
+        if (!r.emptySink)
+            continue;
+        process.stdout.write(`\n  ! ${r.ruleId}: the registered side extracted 0 ids while ${r.declaredCount} were declared —\n` +
+            `    every declared token "fails". Check the registered glob before chasing the tokens.\n`);
+    }
     if (report.violations.length === 0 && report.diagnostics.length === 0) {
+        // A failOnEmpty skip produces no violation object but IS a failure.
+        if (report.verdict === 'errors')
+            return ExitCode.Failure;
         if (allEvaluated) {
             // Every configured rule ran — the earned full green.
             process.stdout.write('\nNo wiring violations — every declared token is registered. ✓\n');
@@ -697,10 +830,10 @@ async function checkWiring(args) {
             process.stdout.write(`\nNo wiring violations among the ${evaluated} rule(s) evaluated — ` +
                 `${notVerified} of ${configured} NOT verified${breakdown}. Not a full green.\n`);
         }
-        return 0;
+        return wiringExitCode(report, evaluated);
     }
     if (report.violations.length === 0) {
-        return report.verdict === 'errors' ? 1 : 0;
+        return wiringExitCode(report, evaluated);
     }
     // Group by rule for a readable report.
     for (const r of report.rules) {
@@ -709,7 +842,9 @@ async function checkWiring(args) {
         process.stdout.write(`\n[${r.severity}] ${r.ruleId}${r.description ? ' — ' + r.description : ''}\n`);
         process.stdout.write(`  declared ${r.declaredCount} / registered ${r.registeredCount} — ${r.violations.length} not wired:\n`);
         for (const v of r.violations.slice(0, 50)) {
-            process.stdout.write(`    • ${v.token}  (${v.file}:${v.line})\n`);
+            const where = `(${v.file}:${v.line})`;
+            const hop = v.hop !== undefined ? ` [hop ${v.hop}]` : '';
+            process.stdout.write(v.message ? `    • ${v.message}  ${where}${hop}\n` : `    • ${v.token}  ${where}${hop}\n`);
         }
         if (r.violations.length > 50) {
             process.stdout.write(`    … (${r.violations.length - 50} more)\n`);

package/dist/commands/command-catalog.d.ts.map

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

package/dist/commands/command-catalog.js

@@ -406,6 +406,126 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'check wiring --fix',
+        description: 'Deterministic autofix for `declared-but-not-registered`: append the missing id to its sink array. Dry-run by default; `--write` applies. Refuses anything ambiguous (N sinks, non-array sink, non-unique file/array) and lists what it left alone with the reason — it never guesses. [--write] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSource,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Apply,
+    }),
+    entry({
+        command: 'policy-lint explain',
+        description: 'Dry-run ONE policyRule and print every hit with file:line — INCLUDING the hits an exemption (exemptFiles / exemptLines) or the lexical scan zone dropped, each labelled with which one applied. The author-loop view of what the gate sees. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'registry duplicates',
+        description: 'Ids declared more than once across roots in a config-defined registry — a latent bug the compiler cannot see (whichever registration wins at runtime is an accident of load order). Every declaration site is reported. Exit 1 on duplicates, 2 when the registry matched 0 ids. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'gates list',
+        description: 'Every data-defined rule across every plane (wiring / policy / registry / registration / baseline / generated) with its severity and empty-match policy. [--plane <p>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'gates coverage',
+        description: 'The stale-selector detector: what every data-defined rule actually MATCHED against the live tree, flagging each rule that matched 0 files/ids (a rule matching nothing is a bug in the rule, never a pass) and running each rule\'s declared selfTest expectations. Run it in CI so a rule quietly dying is itself a failure. Exit 2 when a rule matched nothing, 1 when it set failOnEmpty. [--plane <p>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'gates explain',
+        description: 'Universal rule introspection: for a rule of ANY plane, print the concrete inputs it resolved — files matched, ids extracted with file:line, and the computed diff. Dispatches to the plane-specific explainer. [--plane <p>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'baseline list',
+        description: 'Every declared baseline: what it pins, how it recomputes, and which direction of drift fails. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'baseline check',
+        description: 'Recompute every committed baseline (adoption ledger / API digest / coverage ratchet / allow-list) and fail on drift. TWO-WAY by default: a silently LOST entry fails exactly like a gained one. Rules from sharkcraft.config.ts baselines[]. Runs the declared compute command for `kind: "command"` rules. [--id X] [--changed-only] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.RunsShell,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'baseline diff',
+        description: 'Human-readable +added / −removed for each baseline, without a verdict — the inspection verb. [--id X] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.RunsShell,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'baseline update',
+        description: 'Rewrite a committed baseline from the current value — the explicit, reviewable bless step (deliberately a separate verb from `check` so a drift can never be blessed by accident). Writes files. [--id X] [--dry-run] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSource,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Apply,
+    }),
+    entry({
+        command: 'baseline explain',
+        description: 'What ONE baseline computes and compares — the command or extractor, the canonical form, both entry counts, and the diff — without turning it into a verdict. [--id X] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.RunsShell,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'generated list',
+        description: 'Every declared generated-artifact rule: its globs, regen command, and "do not edit" header contract. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'generated check',
+        description: 'Regenerate into a temp dir and diff BOTH ways — catching a hand-edited generated file AND a regen that writes a subset — plus the provenance-header contract (missing header on a generated file, header on a hand-written one). `--headers-only` never spawns. Rules from sharkcraft.config.ts generatedArtifacts[]. [--id X] [--headers-only] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.RunsShell,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'generated update',
+        description: 'Run the declared regen command in place — the one-command bless step after an intentional source change. Writes files. [--id X] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSource,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Apply,
+    }),
+    entry({
+        command: 'generated explain',
+        description: 'What ONE generated-artifact rule sees right now: files matched, header-contract results, mislabel candidates — without running the regen. [--id X] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
     entry({
         command: 'wiring explain',
         description: 'Dry-run ONE configured wiringRule and print the declared set + registered set it extracts (token + file:line), the alias-resolved set-difference, and the verdict — the author-loop view of what `check wiring` sees, without re-running the gate. [--json]',

package/dist/commands/daily.commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eAyG5B,CAAC"}
+{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eAmH5B,CAAC"}

package/dist/commands/daily.commands.js

@@ -2,6 +2,7 @@ import { buildAiReadinessReport, buildTaskPacket, inspectSharkcraft, runDoctor,
 import { recommendPresets } from '@shrkcrft/presets';
 import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { tryExplainGateRule } from "./gates.command.js";
 // ────────────────────────────────────────────────────────────────────────
 // shrk next — "what should I do right now in this repo?"
 // ────────────────────────────────────────────────────────────────────────
@@ -177,9 +178,18 @@ export const explainCommand = {
     async run(args) {
         const topic = args.positional.join(' ').trim();
         if (!topic) {
-            process.stderr.write('Usage: shrk explain "<topic>"\n');
+            process.stderr.write('Usage: shrk explain "<topic>"   (a topic, or the id of any data-defined rule)\n');
             return 2;
         }
+        // A single token that exactly names a declared rule on ANY plane is
+        // explained as that rule — the one entrypoint the trust layer promises.
+        // Anything else keeps the original topic search, so no existing call
+        // changes meaning.
+        if (args.positional.length === 1) {
+            const asRule = await tryExplainGateRule(args, topic);
+            if (asRule !== undefined)
+                return asRule;
+        }
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const maxEntries = flagNumber(args, 'max-entries') ?? 6;
         const packet = buildTaskPacket(inspection, topic, { maxTokens: 2500 });

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

@@ -0,0 +1,16 @@
+import { type ICommandHandler, type ParsedArgs } from '../command-registry.js';
+export declare const gatesListCommand: ICommandHandler;
+export declare const gatesCoverageCommand: ICommandHandler;
+export declare const gatesExplainCommand: ICommandHandler;
+/**
+ * Try to explain `id` as a data-defined rule on ANY plane.
+ *
+ * Returns the exit code when the id resolves to exactly one declared rule, or
+ * `undefined` when it is not a rule id at all — which lets `shrk explain` keep
+ * its original topic-search behaviour for everything else. This is the D2
+ * unification: a user holding a rule id no longer has to know which plane owns
+ * it, and no existing invocation changes meaning.
+ */
+export declare function tryExplainGateRule(args: ParsedArgs, id: string): Promise<number | undefined>;
+export declare const gatesCommand: ICommandHandler;
+//# sourceMappingURL=gates.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gates.command.d.ts","sourceRoot":"","sources":["../../src/commands/gates.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,wBAAwB,CAAC;AAgFhC,eAAO,MAAM,gBAAgB,EAAE,eAsD9B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAuGlC,CAAC;AAuCF,eAAO,MAAM,mBAAmB,EAAE,eA4FjC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B;AAED,eAAO,MAAM,YAAY,EAAE,eAe1B,CAAC"}