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

package/dist/commands/generated.command.js

@@ -0,0 +1,544 @@
+/**
+ * `shrk generated {list,check,update,explain}` — the generated-artifact drift +
+ * provenance GATE. It shares the `generated` noun with the classifier verbs
+ * (`report` / `protect`, in `ingest.command.ts`) on purpose: that half FINDS
+ * what is generated, this half proves it has not drifted.
+ *
+ *   shrk generated list                       # every declared artifact set
+ *   shrk generated check [--id X]             # regen → temp dir → diff BOTH ways + headers
+ *       [--headers-only]                      #   header contract only; never spawns
+ *   shrk generated update [--id X]            # run regen in place (the bless step)
+ *   shrk generated explain --id X             # what it will run + what it currently sees
+ *
+ * The build compiles a hand-edited generated file perfectly happily; only
+ * regenerate-into-a-temp-dir-and-diff catches the edit. `regen` therefore
+ * SPAWNS a shell command, which is why the pack-plane merge seam drops any
+ * pack-contributed rule declaring one — a header-only rule (no `regen`) is
+ * fully useful and never spawns, so packs can still ship it.
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import * as nodeOs from 'node:os';
+import * as nodePath from 'node:path';
+import { failsWhenEmpty } from '@shrkcrft/core';
+import { checkProvenanceHeaders, compareGeneratedTrees, scanGeneratedFiles, } from '@shrkcrft/boundaries';
+import { resolveProjectConfig } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ExitCode } from "../exit-codes.js";
+import { asJson, header, kv } from "../output/format-output.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
+const SCHEMA = 'sharkcraft.generated-drift/v1';
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Cap on the temp tree read — a runaway regen must not be read into memory whole. */
+const MAX_REGEN_FILE_BYTES = 2_000_000;
+async function loadRules(cwd) {
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok)
+        return { ok: false, message: loaded.error.message };
+    const rel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
+    return {
+        ok: true,
+        value: {
+            rules: loaded.value.config.generatedArtifacts ?? [],
+            planeDiagnostics: loaded.value.planeDiagnostics,
+            excludeDirs: rel && !rel.startsWith('..') ? [rel] : [],
+        },
+    };
+}
+/** Read a regenerated temp tree into path→content, relative to `root`. */
+function readTree(root) {
+    const out = new Map();
+    const visit = (abs) => {
+        let entries;
+        try {
+            entries = readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const child = nodePath.join(abs, e.name);
+            if (e.isDirectory()) {
+                visit(child);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            try {
+                if (statSync(child).size > MAX_REGEN_FILE_BYTES)
+                    continue;
+                out.set(nodePath.relative(root, child).split(nodePath.sep).join('/'), readFileSync(child, 'utf8'));
+            }
+            catch {
+                // unreadable — skip
+            }
+        }
+    };
+    visit(root);
+    return out;
+}
+/** Number of trailing path SEGMENTS `a` and `b` share (0 when none). */
+function sharedSuffixSegments(a, b) {
+    const x = a.split('/');
+    const y = b.split('/');
+    let n = 0;
+    while (n < x.length && n < y.length && x[x.length - 1 - n] === y[y.length - 1 - n])
+        n += 1;
+    return n;
+}
+/**
+ * Re-key a regenerated tree onto the committed paths.
+ *
+ * A regen writes into `{TMP}` under its own root, which is rarely the repo
+ * root, while committed files are keyed project-relative. The two sets are
+ * matched on the LONGEST shared path suffix — not the first suffix that
+ * happens to match, because `a.json` alone would otherwise bind to whichever
+ * `…/a.json` the iteration reached first and silently compare two unrelated
+ * files. Ties break lexically so the mapping is deterministic, each committed
+ * path is claimed at most once, and anything unmatched keeps its temp-relative
+ * key and surfaces as `only-regenerated` rather than disappearing.
+ */
+function alignToCommitted(temp, committed) {
+    const committedPaths = [...committed.keys()].sort();
+    const claimed = new Set();
+    const out = new Map();
+    // Best-match first: a temp path with a longer shared suffix has the stronger
+    // claim on a committed path, so resolve those before the weaker ones.
+    const scored = [...temp.keys()]
+        .map((tempPath) => {
+        let best;
+        for (const c of committedPaths) {
+            const score = sharedSuffixSegments(tempPath, c);
+            if (score > 0 && (best === undefined || score > best.score))
+                best = { path: c, score };
+        }
+        return { tempPath, best };
+    })
+        .sort((a, b) => (b.best?.score ?? 0) - (a.best?.score ?? 0) || a.tempPath.localeCompare(b.tempPath));
+    for (const { tempPath, best } of scored) {
+        const content = temp.get(tempPath);
+        if (best && !claimed.has(best.path)) {
+            claimed.add(best.path);
+            out.set(best.path, content);
+        }
+        else {
+            out.set(tempPath, content);
+        }
+    }
+    return out;
+}
+/** Run `regen` into a fresh temp dir and read the result back. Always cleans up. */
+function runRegen(cwd, rule, committed) {
+    const tmp = mkdtempSync(nodePath.join(nodeOs.tmpdir(), 'shrk-generated-'));
+    try {
+        const command = rule.regen.split('{TMP}').join(tmp);
+        const child = spawnSync(command, {
+            cwd,
+            shell: true,
+            encoding: 'utf8',
+            timeout: rule.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        if (child.error)
+            return { error: `regen failed to start: ${child.error.message}` };
+        if (child.status !== 0) {
+            const tail = String(child.stderr ?? '').trim().split('\n').slice(-3).join(' | ');
+            return { error: `regen exited ${child.status ?? 'null'}${tail ? ` — ${tail}` : ''}` };
+        }
+        const tree = readTree(tmp);
+        if (tree.size === 0) {
+            return { error: 'regen wrote no files into {TMP} — the command probably ignores the output path' };
+        }
+        return { files: alignToCommitted(tree, committed) };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+function evaluateRule(cwd, rule, excludeDirs, headersOnly) {
+    const scan = scanGeneratedFiles(cwd, rule, excludeDirs);
+    const severity = rule.severity ?? 'error';
+    if (scan.generated.size === 0) {
+        const failed = failsWhenEmpty(rule);
+        return {
+            rule,
+            status: failed ? 'failed' : 'skipped',
+            committedCount: 0,
+            provenance: [],
+            driftChecked: false,
+            skipReason: `0 files matched generatedGlob (${rule.generatedGlob.join(', ')})`,
+        };
+    }
+    const headers = checkProvenanceHeaders(rule, scan.generated, scan.outside);
+    if (headers.error) {
+        return {
+            rule,
+            status: 'error',
+            committedCount: scan.generated.size,
+            provenance: [],
+            driftChecked: false,
+            error: headers.error,
+        };
+    }
+    let treeDiff;
+    let error;
+    const wantDrift = !headersOnly && rule.regen !== undefined;
+    if (wantDrift) {
+        const regen = runRegen(cwd, rule, scan.generated);
+        if (regen.error)
+            error = regen.error;
+        else
+            treeDiff = compareGeneratedTrees(scan.generated, regen.files, rule.compare ?? 'bytes');
+    }
+    const hardFindings = headers.findings.filter((f) => f.severity === 'error');
+    const drifted = (treeDiff?.differences.length ?? 0) > 0;
+    const status = error !== undefined
+        ? 'error'
+        : drifted || (hardFindings.length > 0 && severity === 'error')
+            ? 'failed'
+            : 'passed';
+    return {
+        rule,
+        status,
+        committedCount: scan.generated.size,
+        ...(treeDiff ? { treeDiff } : {}),
+        provenance: headers.findings,
+        ...(error ? { error } : {}),
+        driftChecked: wantDrift && error === undefined,
+    };
+}
+function hintFor(rule) {
+    return (rule.hint ??
+        (rule.regen
+            ? `regenerate with \`shrk generated update --id ${rule.id}\` and commit the result`
+            : 'add the provenance header to the generated file, or move it out of the generated glob'));
+}
+function outcomeJson(o) {
+    return {
+        id: o.rule.id,
+        ...(o.rule.description ? { description: o.rule.description } : {}),
+        status: o.status,
+        severity: o.rule.severity ?? 'error',
+        committedCount: o.committedCount,
+        driftChecked: o.driftChecked,
+        ...(o.treeDiff ? { differences: o.treeDiff.differences, regeneratedCount: o.treeDiff.regeneratedCount } : {}),
+        provenance: o.provenance,
+        ...(o.error ? { error: o.error } : {}),
+        ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+        hint: hintFor(o.rule),
+    };
+}
+async function prepare(args) {
+    const cwd = resolveCwd(args);
+    const json = flagBool(args, 'json');
+    const loaded = await loadRules(cwd);
+    if (!loaded.ok) {
+        if (json)
+            process.stdout.write(asJson({ schema: SCHEMA, error: loaded.message }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.message}\n  Run \`shrk doctor\` for details.\n`);
+        return { ok: false, code: ExitCode.UsageError };
+    }
+    const id = flagString(args, 'id');
+    let rules = loaded.value.rules;
+    if (id) {
+        const wanted = id.split(',').map((s) => s.trim()).filter(Boolean);
+        const known = new Set(rules.map((r) => r.id));
+        const unknown = wanted.filter((w) => !known.has(w));
+        if (unknown.length > 0) {
+            process.stderr.write(`Unknown generated-artifact id(s): ${unknown.join(', ')}. Declared: ${[...known].join(', ') || '(none)'}\n`);
+            return { ok: false, code: ExitCode.UsageError };
+        }
+        rules = rules.filter((r) => wanted.includes(r.id));
+    }
+    return {
+        ok: true,
+        cwd,
+        rules,
+        all: loaded.value.rules,
+        excludeDirs: loaded.value.excludeDirs,
+        planeDiagnostics: loaded.value.planeDiagnostics,
+    };
+}
+function writeNoRules(json) {
+    if (json) {
+        process.stdout.write(asJson({ schema: SCHEMA, results: [], evaluated: 0, verdict: 'not-verified' }) + '\n');
+        return ExitCode.NotVerified;
+    }
+    process.stdout.write(header('Generated artifacts'));
+    process.stdout.write('  No generated-artifact rules declared. Add `generatedArtifacts[]` to\n' +
+        '  sharkcraft.config.ts to catch hand-edited generated files and missing\n' +
+        '  "do not edit" headers (see docs/generated-drift.md).\n');
+    return ExitCode.NotVerified;
+}
+export const generatedListCommand = {
+    name: 'list',
+    description: 'List every declared generated-artifact rule: its globs, regen command, and header contract.',
+    usage: 'shrk generated list [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const prep = await prepare(args);
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        if (prep.all.length === 0)
+            return writeNoRules(json);
+        if (json) {
+            process.stdout.write(asJson({
+                schema: SCHEMA,
+                rules: prep.all.map((r) => ({
+                    id: r.id,
+                    description: r.description ?? null,
+                    generatedGlob: r.generatedGlob,
+                    regen: r.regen ?? null,
+                    compare: r.compare ?? 'bytes',
+                    provenanceHeader: r.provenanceHeader ?? null,
+                    failOnEmpty: r.failOnEmpty === true,
+                })),
+                diagnostics: prep.planeDiagnostics,
+            }) + '\n');
+            return ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header(`Generated artifacts (${prep.all.length})`));
+        for (const r of prep.all) {
+            process.stdout.write(`  • ${r.id}\n`);
+            process.stdout.write(`      glob   ${r.generatedGlob.join(', ')}\n`);
+            process.stdout.write(`      regen  ${r.regen ?? '(header-only — never spawns)'}\n`);
+            if (r.provenanceHeader) {
+                process.stdout.write(`      header /${r.provenanceHeader.mustMatch}/${r.provenanceHeader.forbidOutside ? '  + mislabel check' : ''}\n`);
+            }
+            if (r.description)
+                process.stdout.write(`      ${r.description}\n`);
+        }
+        for (const d of prep.planeDiagnostics)
+            process.stdout.write(`  ! ${d}\n`);
+        return ExitCode.VerifiedPass;
+    },
+};
+export const generatedCheckCommand = {
+    name: 'check',
+    description: 'Regenerate into a temp dir and diff BOTH ways (hand-edited file AND regen-writes-a-subset), plus the "do not edit" header contract.',
+    usage: 'shrk generated check [--id <ids>] [--headers-only] [--json]',
+    booleanFlags: new Set(['json', 'headers-only']),
+    async run(args) {
+        const prep = await prepare(args);
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        const headersOnly = flagBool(args, 'headers-only');
+        if (prep.rules.length === 0)
+            return writeNoRules(json);
+        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, headersOnly));
+        const failed = outcomes.filter((o) => o.status === 'failed' || (o.status === 'error' && (o.rule.severity ?? 'error') === 'error'));
+        const evaluated = outcomes.filter((o) => o.status !== 'skipped').length;
+        const skippedCount = outcomes.length - evaluated;
+        const exit = failed.length > 0
+            ? ExitCode.Failure
+            : evaluated === 0 || skippedCount > 0
+                ? ExitCode.NotVerified
+                : ExitCode.VerifiedPass;
+        if (json) {
+            process.stdout.write(asJson({
+                schema: SCHEMA,
+                headersOnly,
+                results: outcomes.map(outcomeJson),
+                evaluated,
+                skipped: outcomes.filter((o) => o.status === 'skipped').length,
+                verdict: failed.length > 0 ? 'errors' : evaluated === 0 ? 'not-verified' : 'pass',
+                diagnostics: prep.planeDiagnostics,
+                gate: buildGateEnvelope('generated check', exit, outcomes.map((o) => ({
+                    id: o.rule.id,
+                    type: 'generated',
+                    status: o.status,
+                    severity: o.rule.severity ?? 'error',
+                    counts: {
+                        files: o.committedCount,
+                        differences: o.treeDiff?.differences.length ?? 0,
+                        provenance: o.provenance.length,
+                    },
+                    violations: [
+                        ...(o.treeDiff?.differences ?? []).map((d) => ({
+                            id: d.file,
+                            file: d.file,
+                            message: d.kind,
+                            hint: hintFor(o.rule),
+                        })),
+                        ...o.provenance.map((f) => ({
+                            id: f.file,
+                            file: f.file,
+                            message: f.message,
+                            hint: hintFor(o.rule),
+                        })),
+                    ],
+                    ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+                    ...(o.error ? { error: o.error } : {}),
+                }))),
+            }) + '\n');
+            return exit;
+        }
+        process.stdout.write(header('Generated-artifact drift'));
+        process.stdout.write(kv('evaluated', `${evaluated} of ${prep.rules.length}`) + '\n');
+        if (headersOnly)
+            process.stdout.write(kv('scope', 'headers only — no regen was run') + '\n');
+        for (const o of outcomes) {
+            if (o.status === 'skipped') {
+                process.stdout.write(`  – ${o.rule.id}  SKIPPED — ${o.skipReason}\n`);
+                continue;
+            }
+            if (o.status === 'error') {
+                process.stdout.write(`  ! ${o.rule.id}  ${o.error}\n`);
+                continue;
+            }
+            const diffs = o.treeDiff?.differences ?? [];
+            if (o.status === 'passed') {
+                process.stdout.write(`  ✓ ${o.rule.id}  (${o.committedCount} files` +
+                    `${o.driftChecked ? ', byte-identical to a fresh regen' : ', headers only'})\n`);
+            }
+            else {
+                process.stdout.write(`  ✗ ${o.rule.id}  ${diffs.length} file(s) differ from a fresh regen\n`);
+                for (const d of diffs.slice(0, 25)) {
+                    const label = d.kind === 'content'
+                        ? 'hand-edited (or source changed)'
+                        : d.kind === 'only-committed'
+                            ? 'committed but regen no longer produces it'
+                            : 'regen produces it but it is not committed';
+                    process.stdout.write(`      • ${d.file}  — ${label}\n`);
+                }
+                if (diffs.length > 25)
+                    process.stdout.write(`      … (${diffs.length - 25} more)\n`);
+            }
+            for (const f of o.provenance.slice(0, 25)) {
+                process.stdout.write(`      [${f.severity}] ${f.file} — ${f.message}\n`);
+            }
+            if (o.provenance.length > 25) {
+                process.stdout.write(`      … (${o.provenance.length - 25} more header finding(s))\n`);
+            }
+            if (o.status === 'failed')
+                process.stdout.write(`      → ${hintFor(o.rule)}\n`);
+        }
+        for (const d of prep.planeDiagnostics)
+            process.stdout.write(`  ! ${d}\n`);
+        if (exit === ExitCode.NotVerified) {
+            process.stdout.write('\nNothing was checked — this is NOT a pass. Every rule matched 0 files.\n');
+        }
+        else if (exit === ExitCode.VerifiedPass) {
+            process.stdout.write('\nEvery generated artifact matches its source. ✓\n');
+        }
+        return exit;
+    },
+};
+export const generatedUpdateCommand = {
+    name: 'update',
+    description: 'Run the declared regen command in place — the one-command bless step after an intentional source change. Writes files.',
+    usage: 'shrk generated update [--id <ids>] [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const prep = await prepare(args);
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        if (prep.rules.length === 0)
+            return writeNoRules(json);
+        const results = [];
+        for (const rule of prep.rules) {
+            if (!rule.regen) {
+                results.push({ id: rule.id, ran: false, error: 'header-only rule — nothing to regenerate' });
+                continue;
+            }
+            // `{TMP}` is the CHECK contract; `update` writes in place, so it is
+            // substituted with the project root and the regen writes its real output.
+            const command = rule.regen.split('{TMP}').join(prep.cwd);
+            const child = spawnSync(command, {
+                cwd: prep.cwd,
+                shell: true,
+                encoding: 'utf8',
+                timeout: rule.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                maxBuffer: 16 * 1024 * 1024,
+                stdio: json ? 'pipe' : 'inherit',
+            });
+            if (child.error) {
+                results.push({ id: rule.id, ran: false, error: child.error.message });
+            }
+            else if (child.status !== 0) {
+                results.push({ id: rule.id, ran: true, error: `exited ${child.status ?? 'null'}` });
+            }
+            else {
+                results.push({ id: rule.id, ran: true });
+            }
+        }
+        const failed = results.filter((r) => r.error !== undefined);
+        if (json) {
+            process.stdout.write(asJson({ schema: SCHEMA, results }) + '\n');
+            return failed.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header('Generated update'));
+        for (const r of results) {
+            process.stdout.write(`  ${r.error ? '!' : '✓'} ${r.id}${r.error ? ` — ${r.error}` : ''}\n`);
+        }
+        if (failed.length === 0) {
+            process.stdout.write('\nRegenerated. Review `git diff` before committing.\n');
+        }
+        return failed.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+    },
+};
+export const generatedExplainCommand = {
+    name: 'explain',
+    description: 'Show what ONE generated-artifact rule sees right now: files matched, header contract results, mislabel candidates — without running the regen.',
+    usage: 'shrk generated explain --id <id> [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const id = flagString(args, 'id') ?? args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk generated explain --id <id>\n');
+            return ExitCode.UsageError;
+        }
+        const prep = await prepare(args);
+        if (!prep.ok)
+            return prep.code;
+        const rule = prep.all.find((r) => r.id === id);
+        if (!rule) {
+            process.stderr.write(`No generated-artifact rule "${id}". Declared: ${prep.all.map((r) => r.id).join(', ') || '(none)'}\n`);
+            return ExitCode.UsageError;
+        }
+        // explain never spawns — the point is to show what the rule SEES.
+        const scan = scanGeneratedFiles(prep.cwd, rule, prep.excludeDirs);
+        const outcome = evaluateRule(prep.cwd, rule, prep.excludeDirs, true);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.generated-explain/v1',
+                ...outcomeJson(outcome),
+                files: [...scan.generated.keys()],
+                outsideScanned: scan.outside.size,
+                outsideGlobs: scan.outsideGlobs,
+                regen: rule.regen ?? null,
+            }) + '\n');
+            return ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header(`Generated artifact: ${rule.id}`));
+        if (rule.description)
+            process.stdout.write(`  ${rule.description}\n`);
+        process.stdout.write(kv('glob', rule.generatedGlob.join(', ')) + '\n');
+        process.stdout.write(kv('files matched', String(scan.generated.size)) + '\n');
+        process.stdout.write(kv('regen', rule.regen ?? '(header-only)') + '\n');
+        process.stdout.write(kv('compare', rule.compare ?? 'bytes') + '\n');
+        if (rule.provenanceHeader) {
+            process.stdout.write(kv('header', `/${rule.provenanceHeader.mustMatch}/`) + '\n');
+            if (rule.provenanceHeader.forbidOutside) {
+                process.stdout.write(kv('mislabel scan', `${scan.outside.size} file(s) via ${scan.outsideGlobs.join(', ')}`) + '\n');
+            }
+        }
+        process.stdout.write(kv('header findings', String(outcome.provenance.length)) + '\n');
+        for (const f of outcome.provenance.slice(0, 50)) {
+            process.stdout.write(`  [${f.kind}] ${f.file} — ${f.message}\n`);
+        }
+        if (scan.generated.size > 0) {
+            process.stdout.write('\n  files:\n');
+            for (const f of [...scan.generated.keys()].slice(0, 50))
+                process.stdout.write(`    ${f}\n`);
+            if (scan.generated.size > 50)
+                process.stdout.write(`    … (${scan.generated.size - 50} more)\n`);
+        }
+        process.stdout.write(`\n  Run \`shrk generated check --id ${rule.id}\` to regenerate into a temp dir and diff.\n`);
+        return ExitCode.VerifiedPass;
+    },
+};

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

@@ -1 +1 @@
-{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAqF9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EAqJpF"}
+{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA4H9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EA2KpF"}

package/dist/commands/help.command.js

@@ -1,5 +1,45 @@
 import { header } from "../output/format-output.js";
 import { COMMAND_CATALOG, defaultShowInHelp, listExplainFamily } from "./command-catalog.js";
+/**
+ * Every multi-token command path the catalog documents. These are real,
+ * callable verbs that the command trie never sees, because their parent
+ * dispatches them from a positional argument rather than registering them.
+ */
+function catalogHelpPaths() {
+    const paths = new Set();
+    for (const entry of COMMAND_CATALOG) {
+        // Strip the flag/argument tail a few catalog entries carry in `command`.
+        const clean = entry.command.split(/\s+--/)[0].trim();
+        if (clean.length > 0)
+            paths.add(clean);
+    }
+    return paths;
+}
+/**
+ * Render help for a command path the trie could not resolve but the catalog
+ * documents, plus its sibling verbs under the same parent so the family is
+ * discoverable from any one member.
+ */
+function renderCatalogHelp(tokens) {
+    const want = tokens.join(' ');
+    const entry = COMMAND_CATALOG.find((e) => e.command.split(/\s+--/)[0].trim() === want);
+    if (!entry)
+        return undefined;
+    let out = `${want} — ${entry.description}\n`;
+    const extra = EXTRA_HELP_LINES[want];
+    if (extra)
+        out += extra.join('\n') + '\n';
+    const parent = tokens.slice(0, -1).join(' ');
+    if (parent.length > 0) {
+        const siblings = [...catalogHelpPaths()]
+            .filter((p) => p !== want && p.startsWith(parent + ' ') && !p.slice(parent.length + 1).includes(' '))
+            .sort();
+        if (siblings.length > 0) {
+            out += `\nSiblings: ${siblings.join(', ')}\n`;
+        }
+    }
+    return out;
+}
 /** First sentence of a catalog description, for the compact explain-family list. */
 function firstSentence(description) {
     const dot = description.indexOf('. ');
@@ -156,8 +196,17 @@ export function makeHelpCommand(registry) {
                     // that exits 0. Error out honestly instead, with a did-you-mean when
                     // a real topic is a near-typo of the request.
                     const attempt = tokens.join(' ');
+                    // The trie matched nothing, but the CATALOG may still document this
+                    // path — a documented verb whose parent isn't a registered command
+                    // is still real and callable.
+                    const viaCatalog = renderCatalogHelp(tokens);
+                    if (viaCatalog !== undefined) {
+                        process.stdout.write(viaCatalog);
+                        return 0;
+                    }
                     process.stderr.write(`no such help topic: '${attempt}'\n`);
-                    const suggestion = nearestHelpTopic(attempt, realHelpTopics(registry));
+                    const suggestion = nearestHelpTopic(attempt, realHelpTopics(registry)) ??
+                        nearestHelpTopic(attempt, catalogHelpPaths());
                     if (suggestion)
                         process.stderr.write(`Did you mean: ${suggestion}?\n`);
                     return 1;
@@ -199,7 +248,20 @@ export function makeHelpCommand(registry) {
                     }
                     return 0;
                 }
-                process.stderr.write(`Unknown command: ${tokens.join(' ')}\n`);
+                // The trie could not resolve the full path, but the CATALOG may still
+                // document it. Verbs like `check wiring` are dispatched from inside
+                // their parent's handler on a positional, so they are real, callable
+                // and documented — yet never trie nodes. Falling through to "Unknown
+                // command" made an entire documented surface look non-existent.
+                const catalogHelp = renderCatalogHelp(tokens);
+                if (catalogHelp !== undefined) {
+                    process.stdout.write(catalogHelp);
+                    return 0;
+                }
+                process.stderr.write(`no such help topic: '${tokens.join(' ')}'\n`);
+                const near = nearestHelpTopic(tokens.join(' '), catalogHelpPaths());
+                if (near)
+                    process.stderr.write(`Did you mean: shrk help ${near}?\n`);
                 return 1;
             }
             if (!wantsFull) {

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

@@ -1,6 +1,17 @@
 import { type ICommandHandler } from '../command-registry.js';
 export declare const ingestCommand: ICommandHandler;
 export declare const contradictionsCommand: ICommandHandler;
+/** Classify the tree's generated code (the `report` half of `shrk generated`). */
+export declare const generatedReportCommand: ICommandHandler;
+/** Recommend protect rules for the classified generated roots. */
+export declare const generatedProtectCommand: ICommandHandler;
+/**
+ * The `generated` group. The bare verb keeps its historical behaviour (the
+ * classifier report); `report` / `protect` are the classifier subverbs, and
+ * `list` / `check` / `update` / `explain` are the drift GATE (registered from
+ * `generated.command.ts`). One noun: that half FINDS what is generated, this
+ * half proves it has not drifted.
+ */
 export declare const generatedCommand: ICommandHandler;
 export declare const stabilityCommand: ICommandHandler;
 //# sourceMappingURL=ingest.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ingest.command.d.ts","sourceRoot":"","sources":["../../src/commands/ingest.command.ts"],"names":[],"mappings":"AA0CA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC;AAmZF,eAAO,MAAM,qBAAqB,EAAE,eAkBnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eA8B9B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAkC9B,CAAC"}
+{"version":3,"file":"ingest.command.d.ts","sourceRoot":"","sources":["../../src/commands/ingest.command.ts"],"names":[],"mappings":"AA0CA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC;AAmZF,eAAO,MAAM,qBAAqB,EAAE,eAkBnC,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,EAAE,eAcpC,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,EAAE,eAsBrC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAY9B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAkC9B,CAAC"}