@shrkcrft/cli 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -2,7 +2,7 @@
 
 SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.
 
-Part of [SharkCraft](https://github.com/sharkcraft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
 
 ## Install
 

package/dist/commands/api-diff.command.d.ts

@@ -0,0 +1,11 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk api-diff` — compare the current code-graph's public-API
+ * surface to a saved baseline (or another snapshot file).
+ *
+ * Sub-verbs:
+ *   - shrk api-diff capture --output <path>     write the current surface to disk
+ *   - shrk api-diff <baseline.json>             diff current vs baseline
+ */
+export declare const apiDiffCommand: ICommandHandler;
+//# sourceMappingURL=api-diff.command.d.ts.map

package/dist/commands/api-diff.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-diff.command.d.ts","sourceRoot":"","sources":["../../src/commands/api-diff.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,eAoB5B,CAAC"}

package/dist/commands/api-diff.command.js

@@ -0,0 +1,116 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { diffApiSurfaces, extractApiSurface, extractApiSurfaceWithProgram, } from '@shrkcrft/api-surface-diff';
+import { GraphStore } from '@shrkcrft/graph';
+import { flagBool, flagList, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk api-diff` — compare the current code-graph's public-API
+ * surface to a saved baseline (or another snapshot file).
+ *
+ * Sub-verbs:
+ *   - shrk api-diff capture --output <path>     write the current surface to disk
+ *   - shrk api-diff <baseline.json>             diff current vs baseline
+ */
+export const apiDiffCommand = {
+    name: 'api-diff',
+    description: 'Compare the current public API surface to a saved baseline. Reports added / removed / kind-changed / moved symbols, with breaking-change severity.',
+    usage: 'shrk api-diff capture --output <path> [--packages a,b] [--with-signatures] | shrk api-diff <baseline.json> [--packages a,b] [--with-signatures] [--json] [--fail-on-breaking]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const sub = args.positional[0];
+        if (!sub) {
+            process.stderr.write(this.usage + '\n');
+            return 2;
+        }
+        if (sub === 'capture') {
+            return runCapture(args, cwd, wantJson);
+        }
+        return runDiff(args, cwd, wantJson, sub);
+    },
+};
+async function runCapture(args, cwd, wantJson) {
+    const outputFlag = flagString(args, 'output');
+    if (!outputFlag) {
+        process.stderr.write('shrk api-diff capture requires --output <path>\n');
+        return 2;
+    }
+    const surface = readSurfaceFromCwd(cwd, args);
+    if (!surface)
+        return 1;
+    const abs = nodePath.isAbsolute(outputFlag) ? outputFlag : nodePath.resolve(cwd, outputFlag);
+    mkdirSync(nodePath.dirname(abs), { recursive: true });
+    writeFileSync(abs, JSON.stringify(surface, null, 2), 'utf8');
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, wrote: abs, total: surface.total }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('API surface capture'));
+    process.stdout.write(kv('wrote', abs) + '\n');
+    process.stdout.write(kv('symbols', String(surface.total)) + '\n');
+    return 0;
+}
+async function runDiff(args, cwd, wantJson, baselinePath) {
+    const baselineAbs = nodePath.isAbsolute(baselinePath)
+        ? baselinePath
+        : nodePath.resolve(cwd, baselinePath);
+    let baseline;
+    try {
+        baseline = JSON.parse(readFileSync(baselineAbs, 'utf8'));
+    }
+    catch (e) {
+        process.stderr.write(`Baseline read error: ${e.message}\n`);
+        return 2;
+    }
+    const current = readSurfaceFromCwd(cwd, args);
+    if (!current)
+        return 1;
+    const diff = diffApiSurfaces(baseline, current);
+    const failOnBreaking = flagBool(args, 'fail-on-breaking');
+    if (wantJson) {
+        process.stdout.write(asJson(diff) + '\n');
+        return failOnBreaking && diff.breakingCount > 0 ? 1 : 0;
+    }
+    process.stdout.write(header('API surface diff'));
+    process.stdout.write(kv('schema', diff.schema) + '\n');
+    process.stdout.write(kv('baseline symbols', String(diff.baselineTotal)) + '\n');
+    process.stdout.write(kv('current symbols', String(diff.currentTotal)) + '\n');
+    process.stdout.write(kv('added', String(diff.added)) + '\n');
+    process.stdout.write(kv('removed', String(diff.removed)) + '\n');
+    process.stdout.write(kv('changed', String(diff.changed)) + '\n');
+    process.stdout.write(kv('breaking', String(diff.breakingCount)) + '\n');
+    if (diff.entries.length === 0) {
+        process.stdout.write('\nNo changes.\n');
+        return 0;
+    }
+    process.stdout.write('\nEntries:\n');
+    for (const e of diff.entries.slice(0, 80)) {
+        process.stdout.write(`  [${e.severity}] [${e.kind}] ${e.message}\n`);
+    }
+    if (diff.entries.length > 80) {
+        process.stdout.write(`  … (${diff.entries.length - 80} more)\n`);
+    }
+    return failOnBreaking && diff.breakingCount > 0 ? 1 : 0;
+}
+function readSurfaceFromCwd(cwd, args) {
+    const packages = flagList(args, 'packages');
+    const withSignatures = flagBool(args, 'with-signatures');
+    if (withSignatures) {
+        const result = extractApiSurfaceWithProgram({
+            projectRoot: cwd,
+            ...(packages.length > 0 ? { packageFilter: packages } : {}),
+        });
+        for (const d of result.diagnostics.slice(0, 5)) {
+            process.stderr.write(`! ${d}\n`);
+        }
+        return result.surface;
+    }
+    const store = new GraphStore(cwd);
+    if (!store.exists()) {
+        process.stderr.write("Code-graph store missing. Run 'shrk graph index' first.\n");
+        return undefined;
+    }
+    const snap = store.loadSnapshot();
+    return extractApiSurface(snap, { ...(packages.length > 0 ? { packageFilter: packages } : {}) });
+}

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

@@ -0,0 +1,9 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk arch` — semantic architecture checks on top of the code graph.
+ * Sub-verbs:
+ *   - shrk arch check               run all enabled checks (auto-loads sharkcraft/arch.ts)
+ *   - shrk arch check --contract X  point at an explicit contract file
+ */
+export declare const archCommand: ICommandHandler;
+//# sourceMappingURL=arch.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arch.command.d.ts","sourceRoot":"","sources":["../../src/commands/arch.command.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,eAoBzB,CAAC"}

package/dist/commands/arch.command.js

@@ -0,0 +1,186 @@
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { ArchReportStore, diffSnapshots, runArchCheck, } from '@shrkcrft/architecture-guard';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { safeImport } from '@shrkcrft/core';
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk arch` — semantic architecture checks on top of the code graph.
+ * Sub-verbs:
+ *   - shrk arch check               run all enabled checks (auto-loads sharkcraft/arch.ts)
+ *   - shrk arch check --contract X  point at an explicit contract file
+ */
+export const archCommand = {
+    name: 'arch',
+    description: 'Architecture-guard checks: public-API misuse, barrel risks, cycle severity, project-specific contracts (sharkcraft/arch.ts auto-loaded). `shrk arch baseline <write|show|clear>` to gate doctor on a frozen baseline.',
+    usage: 'shrk arch check [--contract <path>] [--no-cycles] [--no-barrels] [--no-public-api] [--no-persist] [--json]\n         shrk arch baseline <write|show|clear> [--contract <path>] [--json]',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'baseline') {
+            return runArchBaseline({
+                ...args,
+                positional: args.positional.slice(1),
+            });
+        }
+        if (sub !== 'check') {
+            process.stderr.write(this.usage + '\n');
+            return 2;
+        }
+        return runArchCheckCommand(args);
+    },
+};
+async function runArchCheckCommand(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const noCycles = flagBool(args, 'no-cycles');
+    const noBarrels = flagBool(args, 'no-barrels');
+    const noPublicApi = flagBool(args, 'no-public-api');
+    const noPersist = flagBool(args, 'no-persist');
+    const contractPath = flagString(args, 'contract');
+    const contract = await loadContract(cwd, contractPath);
+    const report = runArchCheck({
+        projectRoot: cwd,
+        ...(contract ? { contract } : {}),
+        enable: {
+            publicApi: !noPublicApi,
+            barrels: !noBarrels,
+            cycles: !noCycles,
+            contract: !!contract,
+        },
+    });
+    // Persist a compact snapshot so `shrk doctor` can compare against
+    // baseline without re-running the full check. `--no-persist` opts out
+    // (useful when scripting against many trees).
+    if (!noPersist) {
+        try {
+            new ArchReportStore(cwd).writeLast(report);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    if (wantJson) {
+        process.stdout.write(asJson(report) + '\n');
+        return report.countsBySeverity.error > 0 ? 1 : 0;
+    }
+    printArchReport(report);
+    return report.countsBySeverity.error > 0 ? 1 : 0;
+}
+async function runArchBaseline(args) {
+    const cwd = resolveCwd(args);
+    const verb = args.positional[0] ?? 'show';
+    const store = new ArchReportStore(cwd);
+    const wantJson = flagBool(args, 'json');
+    if (verb === 'write') {
+        const contractPath = flagString(args, 'contract');
+        const contract = await loadContract(cwd, contractPath);
+        const report = runArchCheck({
+            projectRoot: cwd,
+            ...(contract ? { contract } : {}),
+        });
+        const snap = store.writeBaseline(report);
+        // Update last.json too so doctor's first delta read is meaningful.
+        store.writeLast(report);
+        if (wantJson) {
+            process.stdout.write(asJson({ wrote: store.baselinePath, baseline: snap }) + '\n');
+            return 0;
+        }
+        process.stdout.write(`Architecture baseline written → ${store.baselinePath}\n`);
+        process.stdout.write(`  ${snap.violationIds.length} violations (` +
+            `${snap.countsBySeverity.error} error, ` +
+            `${snap.countsBySeverity.warning} warning, ` +
+            `${snap.countsBySeverity.info} info) ` +
+            `across ${snap.filesAnalyzed} files.\n`);
+        return 0;
+    }
+    if (verb === 'show') {
+        const baseline = store.readBaseline();
+        if (!baseline) {
+            const msg = `No baseline at ${store.baselinePath}. Run \`shrk arch baseline write\` to freeze one.\n`;
+            if (wantJson) {
+                process.stdout.write(asJson({ baseline: null, path: store.baselinePath }) + '\n');
+                return 1;
+            }
+            process.stdout.write(msg);
+            return 1;
+        }
+        if (wantJson) {
+            process.stdout.write(asJson({ path: store.baselinePath, baseline }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Architecture baseline'));
+        process.stdout.write(kv('path', store.baselinePath) + '\n');
+        process.stdout.write(kv('generated at', baseline.generatedAt) + '\n');
+        process.stdout.write(kv('files analyzed', String(baseline.filesAnalyzed)) + '\n');
+        process.stdout.write(kv('counts', `${baseline.countsBySeverity.error} error, ${baseline.countsBySeverity.warning} warning, ${baseline.countsBySeverity.info} info`) + '\n');
+        const last = store.readLast();
+        if (last) {
+            const delta = diffSnapshots(baseline, last);
+            process.stdout.write('\nDelta (last − baseline): ' +
+                `${delta.newViolationIds.length} new, ${delta.fixedViolationIds.length} fixed ` +
+                `(error ${delta.errorDelta >= 0 ? '+' : ''}${delta.errorDelta}, warning ${delta.warningDelta >= 0 ? '+' : ''}${delta.warningDelta})\n`);
+        }
+        else {
+            process.stdout.write('\n(no `last.json` yet — run `shrk arch check`.)\n');
+        }
+        return 0;
+    }
+    if (verb === 'clear') {
+        const removed = store.clearBaseline();
+        if (wantJson) {
+            process.stdout.write(asJson({ removed, path: store.baselinePath }) + '\n');
+            return 0;
+        }
+        process.stdout.write(removed ? `Baseline removed: ${store.baselinePath}\n` : 'No baseline to remove.\n');
+        return 0;
+    }
+    process.stderr.write('Usage: shrk arch baseline <write|show|clear> [--json]\n');
+    return 2;
+}
+function printArchReport(report) {
+    process.stdout.write(header('Architecture guard'));
+    process.stdout.write(kv('schema', report.schema) + '\n');
+    process.stdout.write(kv('files analyzed', String(report.filesAnalyzed)) + '\n');
+    process.stdout.write(kv('errors', String(report.countsBySeverity.error)) + '\n');
+    process.stdout.write(kv('warnings', String(report.countsBySeverity.warning)) + '\n');
+    if (report.violations.length === 0) {
+        process.stdout.write('\nNo violations.\n');
+    }
+    else {
+        process.stdout.write('\nViolations:\n');
+        for (const v of report.violations.slice(0, 80)) {
+            const lineSuffix = v.line ? `:${v.line}` : '';
+            process.stdout.write(`  [${v.severity}] [${v.kind}] ${v.file}${lineSuffix}\n    ${v.message}\n`);
+            if (v.suggestedFix)
+                process.stdout.write(`    → ${v.suggestedFix}\n`);
+        }
+        if (report.violations.length > 80) {
+            process.stdout.write(`  … (${report.violations.length - 80} more)\n`);
+        }
+    }
+    for (const d of report.diagnostics.slice(0, 5))
+        process.stdout.write(`! ${d}\n`);
+}
+async function loadContract(cwd, explicit) {
+    const candidate = explicit
+        ? nodePath.isAbsolute(explicit) ? explicit : nodePath.resolve(cwd, explicit)
+        : nodePath.join(cwd, 'sharkcraft', 'arch.ts');
+    if (!existsSync(candidate)) {
+        if (explicit)
+            process.stderr.write(`! contract file not found: ${candidate}\n`);
+        return undefined;
+    }
+    const result = await safeImport(candidate);
+    if (!result.ok) {
+        process.stderr.write(`! failed to load arch contract: ${result.error.message}\n`);
+        return undefined;
+    }
+    const mod = result.module;
+    const exported = mod.default ??
+        mod.contract;
+    if (!exported) {
+        process.stderr.write(`! arch contract module ${candidate} does not export a contract\n`);
+        return undefined;
+    }
+    return exported;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"boundaries.command.d.ts","sourceRoot":"","sources":["../../src/commands/boundaries.command.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAwB,KAAK,eAAe,EAA+B,MAAM,wBAAwB,CAAC;AAGjH,eAAO,MAAM,qBAAqB,EAAE,eAuBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAqClC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmDtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyEpC,CAAC;AAsCF,uCAAuC;AACvC,eAAO,MAAM,wBAAwB,EAAE,eAmFtC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC"}
+{"version":3,"file":"boundaries.command.d.ts","sourceRoot":"","sources":["../../src/commands/boundaries.command.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAwB,KAAK,eAAe,EAA+B,MAAM,wBAAwB,CAAC;AAGjH,eAAO,MAAM,qBAAqB,EAAE,eAuBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAqClC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmDtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyEpC,CAAC;AAsCF,uCAAuC;AACvC,eAAO,MAAM,wBAAwB,EAAE,eAqEtC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC"}

package/dist/commands/boundaries.command.js

@@ -218,18 +218,6 @@ export const boundariesEnforceCommand = {
         const fileList = filesRaw
             ? filesRaw.split(',').map((s) => s.trim()).filter(Boolean)
             : [];
-        if (since) {
-            const { verifyGitRef } = await import('@shrkcrft/inspector');
-            const verify = verifyGitRef(cwd, since);
-            if (!verify.valid) {
-                process.stderr.write(`error: --since ref "${since}" does not resolve to a commit in this repository.\n` +
-                    (verify.suggestions && verify.suggestions.length > 0
-                        ? `\nDid you mean:\n${verify.suggestions.map((s) => `  --since ${s}`).join('\n')}\n`
-                        : '') +
-                    '\nUse `git branch -a` to list available refs.\n');
-                return 2;
-            }
-        }
         const wantChangedScope = changedOnly || staged || Boolean(since) || fileList.length > 0;
         const { filterViolationsToChangedScope } = await import('@shrkcrft/inspector');
         const filtered = wantChangedScope

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

@@ -1 +1 @@
-{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0kBhC,eAAO,MAAM,YAAY,EAAE,eAmD1B,CAAC"}
+{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAikBhC,eAAO,MAAM,YAAY,EAAE,eAmD1B,CAAC"}

package/dist/commands/check.command.js

@@ -1,8 +1,9 @@
-import { buildAiReadinessReport, buildImportHygieneReport, buildPackDoctorReport, ChangedScopeMode, diagnoseActionHints, emitImportHygieneAllowlistDraft, filterViolationsToChangedScope, ImportHygieneFindingKind, inspectSharkcraft, isTodoReason, renderImportHygieneText, resolveChangedFiles, runDoctor, suggestBoundaryFixes, verifyGitRef, } from '@shrkcrft/inspector';
+import { buildAiReadinessReport, buildImportHygieneReport, buildPackDoctorReport, ChangedScopeMode, diagnoseActionHints, emitImportHygieneAllowlistDraft, filterViolationsToChangedScope, ImportHygieneFindingKind, inspectSharkcraft, isTodoReason, renderImportHygieneText, resolveChangedFiles, runDoctor, suggestBoundaryFixes, } from '@shrkcrft/inspector';
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { flagBool, flagNumber, flagString, flagVars, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { maybeRunInWatchMode } from "../output/watch-loop.js";
 import { validateTemplateVariables } from '@shrkcrft/templates';
 import { FileChangeType, planGeneration } from '@shrkcrft/generator';
 import { evaluateBoundaries, loadTsconfigPaths, scanImports, summarizeImports, } from '@shrkcrft/boundaries';
@@ -152,13 +153,6 @@ async function checkImports(args) {
     const cwd = resolveCwd(args);
     const changedOnly = flagBool(args, 'changed-only');
     const since = flagString(args, 'since');
-    if (since) {
-        const verify = verifyGitRef(cwd, since);
-        if (!verify.valid) {
-            process.stderr.write(renderSinceRefError(since, verify.suggestions ?? []));
-            return 2;
-        }
-    }
     let files;
     if (changedOnly || since) {
         const changed = resolveChangedFiles({
@@ -300,13 +294,6 @@ function readChangedScopeOptions(args, cwd) {
         : [];
     if (!changedOnly && !staged && !since && files.length === 0)
         return null;
-    if (since) {
-        const verify = verifyGitRef(cwd, since);
-        if (!verify.valid) {
-            process.stderr.write(renderSinceRefError(since, verify.suggestions ?? []));
-            process.exit(2);
-        }
-    }
     const out = { projectRoot: cwd };
     if (files.length > 0)
         out.files = files;
@@ -318,20 +305,23 @@ function readChangedScopeOptions(args, cwd) {
         out.includeWorktree = true;
     return out;
 }
-function renderSinceRefError(ref, suggestions) {
-    const lines = [];
-    lines.push(`error: --since ref "${ref}" does not resolve to a commit in this repository.`);
-    if (suggestions.length > 0) {
-        lines.push('');
-        lines.push('Did you mean:');
-        for (const s of suggestions)
-            lines.push(`  --since ${s}`);
-    }
-    lines.push('');
-    lines.push('Use `git branch -a` to list available refs, or skip --since to use the working tree.');
-    return lines.join('\n') + '\n';
-}
 async function checkBoundaries(args) {
+    const watchExit = await maybeRunInWatchMode(args, checkBoundariesOnce, {
+        defaultPaths: BOUNDARIES_DEFAULT_WATCH_PATHS,
+    });
+    if (watchExit !== null)
+        return watchExit;
+    return checkBoundariesOnce(args);
+}
+const BOUNDARIES_DEFAULT_WATCH_PATHS = [
+    'sharkcraft',
+    'packages',
+    'apps',
+    'libs',
+    'src',
+    'tools',
+];
+async function checkBoundariesOnce(args) {
     const cwd = resolveCwd(args);
     const inspection = await inspectSharkcraft({ cwd });
     const rules = inspection.boundaryRegistry.list();
@@ -531,8 +521,8 @@ async function checkBoundaries(args) {
 // ────────────────────────────────────────────────────────────────────────
 export const checkCommand = {
     name: 'check',
-    description: 'Run SharkCraft-level validation across knowledge / rules / templates / pipelines / packs / action hints / doctor.',
-    usage: 'shrk [--cwd <dir>] check [packs|pipelines|knowledge|generation] [--strict] [--min-score <0-100>] [--json]',
+    description: 'Run SharkCraft-level validation across knowledge / rules / templates / pipelines / packs / action hints / doctor. `check boundaries [--watch [--paths a,b] [--debounce N] [--once]]` re-runs the boundary scan on file changes.',
+    usage: 'shrk [--cwd <dir>] check [packs|pipelines|knowledge|generation|boundaries|imports] [--strict] [--min-score <0-100>] [--json] [--watch [--paths <list>] [--debounce N] [--once]]',
     async run(args) {
         const sub = args.positional[0];
         if (sub === 'generation')

package/dist/commands/code-intel.command.d.ts

@@ -0,0 +1,18 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk code-intel` — one-shot view of the 14 code-intelligence
+ * doctor checks. Independent of `shrk doctor` so callers (agents,
+ * inner-loop scripts, the dashboard) can pull just this section
+ * without parsing through unrelated config / knowledge findings.
+ *
+ * Output modes:
+ *   - text (default): grouped by severity, one line per finding.
+ *   - --json: machine-readable, including the full check list.
+ *   - --markdown: PR-comment-ready rendering.
+ *
+ * Filters:
+ *   - --only ok,warning,error,info — restrict severities.
+ *   - --check <id>                 — show only one check id.
+ */
+export declare const codeIntelCommand: ICommandHandler;
+//# sourceMappingURL=code-intel.command.d.ts.map

package/dist/commands/code-intel.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-intel.command.d.ts","sourceRoot":"","sources":["../../src/commands/code-intel.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAuE9B,CAAC"}

package/dist/commands/code-intel.command.js

@@ -0,0 +1,146 @@
+import { buildCodeIntelligenceChecks, DoctorSeverity, } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk code-intel` — one-shot view of the 14 code-intelligence
+ * doctor checks. Independent of `shrk doctor` so callers (agents,
+ * inner-loop scripts, the dashboard) can pull just this section
+ * without parsing through unrelated config / knowledge findings.
+ *
+ * Output modes:
+ *   - text (default): grouped by severity, one line per finding.
+ *   - --json: machine-readable, including the full check list.
+ *   - --markdown: PR-comment-ready rendering.
+ *
+ * Filters:
+ *   - --only ok,warning,error,info — restrict severities.
+ *   - --check <id>                 — show only one check id.
+ */
+export const codeIntelCommand = {
+    name: 'code-intel',
+    description: 'One-shot view of code-intelligence doctor checks (graph, rule-graph, api-surface, quality-gate, migrations, architecture, impact, framework, structural-search, context-planner). Read-only.',
+    usage: 'shrk [--cwd <dir>] code-intel [--json] [--markdown] [--only ok,warning,error,info] [--check <id>] [--stale-days N]',
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const wantMarkdown = flagBool(args, 'markdown');
+        const onlyRaw = flagString(args, 'only');
+        const checkId = flagString(args, 'check');
+        const staleDaysRaw = flagString(args, 'stale-days');
+        const staleDays = staleDaysRaw ? Number.parseInt(staleDaysRaw, 10) : undefined;
+        const options = {};
+        if (typeof staleDays === 'number' && Number.isFinite(staleDays) && staleDays > 0) {
+            options.staleThresholdDays = staleDays;
+        }
+        let checks = buildCodeIntelligenceChecks(cwd, options);
+        if (checkId) {
+            checks = checks.filter((c) => c.id === checkId);
+        }
+        if (onlyRaw) {
+            const allowed = new Set(onlyRaw
+                .split(',')
+                .map((s) => s.trim().toLowerCase())
+                .filter((s) => s.length > 0));
+            checks = checks.filter((c) => allowed.has(severityKey(c.severity)));
+        }
+        const summary = summarize(checks);
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.code-intelligence-state/v1',
+                totalChecks: checks.length,
+                summary,
+                checks,
+            }) + '\n');
+            return exitCode(summary);
+        }
+        if (wantMarkdown) {
+            process.stdout.write(renderMarkdown(checks, summary));
+            return exitCode(summary);
+        }
+        process.stdout.write(header('Code-intelligence state'));
+        process.stdout.write(kv('summary', `ok=${summary.ok} info=${summary.info} warnings=${summary.warnings} errors=${summary.errors}`) + '\n');
+        if (checks.length === 0) {
+            process.stdout.write('\nNo code-intelligence state on disk yet — opt in by running `shrk graph index`.\n');
+            return 0;
+        }
+        process.stdout.write('\n');
+        for (const c of checks) {
+            const icon = severityIcon(c.severity);
+            const advisory = c.advisory ? ' (advisory)' : '';
+            process.stdout.write(`${icon} ${c.id}${advisory}\n`);
+            process.stdout.write(`   ${c.title}\n`);
+            process.stdout.write(`   ${c.message}\n`);
+            if (c.fix)
+                process.stdout.write(`   → ${c.fix}\n`);
+            if (c.whyThisMatters)
+                process.stdout.write(`   why: ${c.whyThisMatters}\n`);
+            process.stdout.write('\n');
+        }
+        return exitCode(summary);
+    },
+};
+function severityKey(severity) {
+    return severity;
+}
+function severityIcon(severity) {
+    switch (severity) {
+        case DoctorSeverity.Ok:
+            return '✓';
+        case DoctorSeverity.Info:
+            return 'ℹ';
+        case DoctorSeverity.Warning:
+            return '⚠';
+        case DoctorSeverity.Error:
+            return '✗';
+    }
+}
+function summarize(checks) {
+    const s = { ok: 0, info: 0, warnings: 0, errors: 0 };
+    for (const c of checks) {
+        if (c.severity === DoctorSeverity.Ok)
+            s.ok += 1;
+        else if (c.severity === DoctorSeverity.Info)
+            s.info += 1;
+        else if (c.severity === DoctorSeverity.Warning)
+            s.warnings += 1;
+        else if (c.severity === DoctorSeverity.Error)
+            s.errors += 1;
+    }
+    return s;
+}
+function exitCode(summary) {
+    // Exit 1 if any non-advisory warning or error remains. Advisory
+    // warnings are reported but never fail the command — they're hints,
+    // not blockers (same contract as `shrk doctor`).
+    return summary.errors > 0 ? 1 : 0;
+}
+function renderMarkdown(checks, summary) {
+    const lines = [];
+    lines.push('# SharkCraft code-intelligence state');
+    lines.push('');
+    lines.push('| ok | info | warnings | errors |');
+    lines.push('|---|---|---|---|');
+    lines.push(`| ${summary.ok} | ${summary.info} | ${summary.warnings} | ${summary.errors} |`);
+    lines.push('');
+    if (checks.length === 0) {
+        lines.push('_(no code-intelligence state on disk yet)_');
+        return lines.join('\n') + '\n';
+    }
+    for (const c of checks) {
+        const icon = severityIcon(c.severity);
+        const advisory = c.advisory ? ' _(advisory)_' : '';
+        lines.push(`### ${icon} \`${c.id}\` — ${c.title}${advisory}`);
+        lines.push('');
+        lines.push(c.message);
+        if (c.fix) {
+            lines.push('');
+            lines.push(`**Fix:** ${c.fix}`);
+        }
+        if (c.whyThisMatters) {
+            lines.push('');
+            lines.push(`**Why:** ${c.whyThisMatters}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n') + '\n';
+}

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

@@ -236,9 +236,13 @@ export declare function commandLifecycle(e: ICommandCatalogEntry): CommandLifecy
 /**
  * Default-help visibility rule. Honors an explicit
  * {@link ICommandCatalogEntry.showInDefaultHelp} when set; otherwise
- * primary + common are visible and advanced / machine / internal / legacy
- * are hidden. Deprecated and retired commands are always hidden by
- * default regardless of surface.
+ * the {@link PRIMARY_VERBS_ALLOWLIST} gates membership in the visible
+ * surface (primary + common entries whose top-level verb pays rent
+ * make the cut; everything else is hidden from `--full-help`).
+ *
+ * Deprecated, retired, aliased commands and anything in the
+ * {@link R46_OVERLAY} are always hidden regardless of allowlist
+ * membership.
  */
 export declare function defaultShowInHelp(e: ICommandCatalogEntry): boolean;
 /**