@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/commands/doctor.command.js

@@ -5,10 +5,12 @@ import { buildSurfaceSummary } from "../surface/surface-summary.js";
 import { renderShapeLine } from "../surface/shape-defaults.js";
 import { existsSync } from 'node:fs';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { SemanticIndex, listIndexableFiles } from '@shrkcrft/embeddings';
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 import { doctorHints, renderFailureHints } from "../output/failure-hints.js";
 import { foldDoctorChecks, renderFoldedSummary, DoctorState, } from "../doctor/doctor-tags.js";
+import { enrichWithLlmRecommendations, renderRecommendationsMarkdown, } from '@shrkcrft/ai';
 const SEVERITY_LABEL = {
     [DoctorSeverity.Ok]: 'OK   ',
     [DoctorSeverity.Info]: 'INFO ',
@@ -38,7 +40,7 @@ function describeStrictMode(mode) {
         case 'all':
             return 'strict=all (every warning fails)';
         case 'warnings':
-            return 'strict=warnings (structural warnings fail, hint-quality excluded)';
+            return 'strict=warnings (structural warnings fail, advisory excluded)';
         case 'errors':
             return 'strict=errors (only errors fail)';
         case 'off':
@@ -59,8 +61,10 @@ function evaluateStrict(mode, checks, errorCount) {
     for (const c of checks) {
         if (c.severity !== DoctorSeverity.Warning)
             continue;
-        const isHintQuality = c.id.startsWith('actionhints-');
-        if (mode === 'warnings' && isHintQuality) {
+        // `--strict=warnings` excludes anything the inspector flagged as
+        // advisory (action-hint quality today, any future advisory category
+        // tomorrow). `--strict=all` counts every warning, advisory or not.
+        if (mode === 'warnings' && c.advisory === true) {
             excludedWarnings += 1;
         }
         else {
@@ -74,7 +78,7 @@ function evaluateStrict(mode, checks, errorCount) {
         excludedWarnings,
         reason: mode === 'all'
             ? 'any warning'
-            : 'structural warnings only (hint-quality excluded)',
+            : 'structural warnings only (advisory excluded)',
     };
 }
 function buildFilterOptions(args, suppressions) {
@@ -137,10 +141,81 @@ function isBlockerCheck(check) {
 async function runDoctorOnce(args) {
     return doctorCommandImpl(args);
 }
+function augmentWithSemanticIndexCheck(result, cwd) {
+    const current = listIndexableFiles(cwd, 5000);
+    const report = SemanticIndex.freshnessReport(cwd, current);
+    const check = renderSemanticIndexCheck(report);
+    const checks = [...result.checks, check];
+    const summary = { ...result.summary };
+    if (check.severity === DoctorSeverity.Ok)
+        summary.ok = (summary.ok ?? 0) + 1;
+    else if (check.severity === DoctorSeverity.Info)
+        summary.info = (summary.info ?? 0) + 1;
+    else if (check.severity === DoctorSeverity.Warning)
+        summary.warnings = (summary.warnings ?? 0) + 1;
+    else if (check.severity === DoctorSeverity.Error)
+        summary.errors = (summary.errors ?? 0) + 1;
+    return { ...result, checks, summary };
+}
+function renderSemanticIndexCheck(report) {
+    if (!report.hasIndex) {
+        return {
+            id: 'semantic-index-missing',
+            title: 'Semantic embedding index',
+            severity: DoctorSeverity.Info,
+            message: `No semantic index found — ${report.untracked} indexable files on disk. ` +
+                'Run `shrk smart-context embeddings-build` to enable embedding-backed retrieval in smart-context.',
+            category: 'semantic-index',
+        };
+    }
+    if (report.corrupt) {
+        return {
+            id: 'semantic-index-corrupt',
+            title: 'Semantic embedding index',
+            severity: DoctorSeverity.Error,
+            message: 'Semantic index meta is corrupt.',
+            fix: 'shrk smart-context embeddings-build --rebuild',
+            category: 'semantic-index',
+        };
+    }
+    const driftCount = report.stale + report.missing + report.untracked;
+    if (driftCount === 0) {
+        return {
+            id: 'semantic-index-fresh',
+            title: 'Semantic embedding index',
+            severity: DoctorSeverity.Ok,
+            message: `Index fresh — ${report.indexed} files (model ${report.model}).`,
+            category: 'semantic-index',
+        };
+    }
+    // Severity is driven only by *rot* — indexed entries that changed (stale)
+    // or were deleted (missing), as a fraction of the indexed set. Newly added
+    // files (`untracked`) are benign growth, not drift: they aren't in the
+    // index yet so they can't return wrong hits, and they don't belong in a
+    // ratio whose denominator is the indexed set. The old fused "% drift"
+    // (stale+missing+untracked over indexed) tripped a yellow WARN purely on
+    // repo growth — exactly the "scary number" noise. The index is a derived
+    // cache, so this is always `advisory` (folds into the calm "N advisory"
+    // line and nudges a refresh) rather than a code-health defect; a deleted
+    // file can no longer reach a caller either, because searchFiles prunes
+    // on-disk-missing paths at query time.
+    const rotPct = report.indexed > 0 ? ((report.stale + report.missing) * 100) / report.indexed : 0;
+    const severity = rotPct >= 10 ? DoctorSeverity.Warning : DoctorSeverity.Info;
+    return {
+        id: 'semantic-index-stale',
+        title: 'Semantic embedding index',
+        severity,
+        advisory: true,
+        message: `Index drifted from disk — ${report.untracked} new, ${report.missing} deleted, ${report.stale} changed ` +
+            `(${report.indexed} indexed; ${Math.round(rotPct)}% stale/deleted).`,
+        fix: 'shrk smart-context embeddings-build',
+        category: 'semantic-index',
+    };
+}
 export const doctorCommand = {
     name: 'doctor',
-    description: 'Validate the local SharkCraft setup (config, knowledge, templates, project). `--focus errors|warnings-new|info`, `--hide <category,...>`, `--quiet-known` filter the headline view using `sharkcraft/doctor.suppressions.json`. `--watch`/`--once`/`--debounce` for live mode. `--explain-quality` shows the per-warning "why this matters" line so warnings stop being permanent yellow noise. `--blockers` shows only must-fix findings (errors + warning-category in {config-invalid, pack-signature-invalid, plan-signature-divergent, asset-load-failed}); exit code is non-zero iff a blocker remains. Subcommands: `suppress`, `suppressions list|check`, `watch`.',
-    usage: 'shrk [--cwd <dir>] doctor [--no-config] [--json] [--strict[=errors|warnings|all]] [--blockers] [--show-advisory] [--min-score <0-100>] [--focus errors,warnings-new,info] [--hide action-hint-quality,...] [--quiet-known] [--explain-quality] [--watch [--once] [--debounce N]]',
+    description: 'Validate the local SharkCraft setup (config, knowledge, templates, project). `--focus errors|warnings-new|info`, `--hide <category,...>`, `--quiet-known` filter the headline view using `sharkcraft/doctor.suppressions.json`. `--watch`/`--once`/`--debounce` for live mode. `--explain-quality` shows the per-warning "why this matters" line so warnings stop being permanent yellow noise. `--blockers` shows only must-fix findings (errors + warning-category in {config-invalid, pack-signature-invalid, plan-signature-divergent, asset-load-failed}); exit code is non-zero iff a blocker remains. `--llm-recommendations` layers a local-LLM-derived list of concrete next-steps onto the deterministic output (no-op when no provider is reachable). Subcommands: `suppress`, `suppressions list|check`, `watch`.',
+    usage: 'shrk [--cwd <dir>] doctor [--no-config] [--json] [--strict[=errors|warnings|all]] [--blockers] [--show-advisory] [--min-score <0-100>] [--focus errors,warnings-new,info] [--hide action-hint-quality,...] [--quiet-known] [--explain-quality] [--llm-recommendations] [--provider auto|ollama|llamacpp] [--watch [--once] [--debounce N]]',
     async run(args) {
         const watchExit = await maybeRunInWatchMode(args, runDoctorOnce);
         if (watchExit !== null)
@@ -161,7 +236,7 @@ async function doctorCommandImpl(args) {
         inspectOpts.loaderTimeoutMs = loaderTimeout;
     }
     const inspection = await inspectSharkcraft(inspectOpts);
-    const result = runDoctor(inspection);
+    const result = augmentWithSemanticIndexCheck(runDoctor(inspection), cwd);
     const report = buildAiReadinessReport(inspection);
     if (debug) {
         process.stderr.write(`[debug] inspection elapsed ${inspection.inspectionElapsedMs}ms cache=${inspection.cacheEnabled ? 'on' : 'off'} loaders=${inspection.loaderDiagnostics.length}\n`);
@@ -235,6 +310,19 @@ async function doctorCommandImpl(args) {
             return !isSharkcraftMissing;
         });
     }
+    // Optional LLM enrichment: never alters the deterministic emission below;
+    // only appended at the end. No-op when the flag is off or no provider is
+    // reachable — keeps the deterministic baseline byte-stable.
+    const wantLlmRecs = flagBool(args, 'llm-recommendations');
+    const llmEnvelope = wantLlmRecs
+        ? await enrichWithLlmRecommendations({
+            surface: 'doctor',
+            deterministicSummary: summariseDoctorChecks(visibleChecks),
+            providerKind: flagString(args, 'provider') ?? undefined,
+            ask: 'For each warning or error, propose ONE concrete next-step the user can execute from a shell — name the `shrk` subcommand, file path, or config key. If a finding has no useful next-step, skip it.',
+            maxTokens: 1024,
+        })
+        : null;
     const ackExpired = ackSummary.expired.length > 0 && failOnExpiredAcknowledgement;
     // Under --no-config + missing sharkcraft, treat the run as advisory: do not
     // red-fail on the inspector's "no sharkcraft" errors / warnings.
@@ -327,6 +415,7 @@ async function doctorCommandImpl(args) {
             })),
             ...result,
             ...(filtered ? { filtered } : {}),
+            ...(llmEnvelope ? { llmRecommendations: llmEnvelope } : {}),
         }) + '\n');
         return overallExitCode;
     }
@@ -402,6 +491,11 @@ async function doctorCommandImpl(args) {
             process.stdout.write('\n' + summary);
     }
     process.stdout.write('\n');
+    // How many of the warnings are routine index/cache maintenance (advisory
+    // staleness) rather than code-health defects. Surfaced as an additive
+    // sub-line so the headline count isn't misread as N real problems —
+    // these fold out under --show-advisory.
+    const maintenanceWarnings = visibleChecks.filter((c) => c.severity === DoctorSeverity.Warning && c.advisory).length;
     if (filtered) {
         const s = filtered.summary;
         process.stdout.write(`Summary: ${s.ok} ok, ${s.info} info, ${s.warnings} active warnings, ${s.errors} errors\n`);
@@ -415,12 +509,15 @@ async function doctorCommandImpl(args) {
     else {
         process.stdout.write(`Summary: ${result.summary.ok} ok, ${result.summary.info} info, ${result.summary.warnings} warnings, ${result.summary.errors} errors\n`);
     }
+    if (maintenanceWarnings > 0) {
+        process.stdout.write(`  (${maintenanceWarnings} ${maintenanceWarnings === 1 ? 'warning is' : 'warnings are'} routine index/cache maintenance, not code-health defects — fold-out via --show-advisory)\n`);
+    }
     void buildSuppressionEntry;
     void doctorSuppressionsFile;
     void saveDoctorSuppressions;
     void existsSync;
     if (strictMode === 'warnings' && strictEval.excludedWarnings > 0) {
-        process.stdout.write(`  (strict=warnings excluded ${strictEval.excludedWarnings} hint-quality warning(s); use --strict=all to include)\n`);
+        process.stdout.write(`  (strict=warnings excluded ${strictEval.excludedWarnings} advisory warning(s); use --strict=all to include)\n`);
     }
     // Surface acknowledgement state. Bare suppressions don't qualify as
     // acknowledgements; expiring/expired ones get a callout so authors don't
@@ -458,10 +555,27 @@ async function doctorCommandImpl(args) {
     if (!inspection.sharkcraftDir) {
         process.stdout.write('\nNothing here yet — try `shrk init --zero-config` to detect your stack and pick a preset.\n');
     }
-    process.stdout.write(`\nAI-readiness: ${report.score} / 100 (${report.grade})\n`);
+    // Honest binary verdicts come first — yes/no on the two questions
+    // users actually want answered (can I let an agent write here? can
+    // I let an agent read here?). The 0..100 score follows, scoped to
+    // the workspace shape so libraries don't get dinged for "no
+    // pipelines" and apps don't get dinged for "no published API".
+    process.stdout.write(`\nShape: ${report.workspaceShape.label}` +
+        ` (score counts ${report.dimensions.filter((d) => d.applies === 'core').length} of ${report.dimensions.length} dimensions)\n`);
+    process.stdout.write(`  ${report.verdicts.readyForAgentReads ? '✓' : '✗'} Ready for agent reads (context / task lookups)\n`);
+    process.stdout.write(`  ${report.verdicts.readyForAgentWrites ? '✓' : '✗'} Ready for agent writes (apply / generate)\n`);
+    if (report.verdicts.blockers.length > 0) {
+        process.stdout.write(`  Blockers:\n`);
+        for (const b of report.verdicts.blockers) {
+            process.stdout.write(`    • ${b}\n`);
+        }
+    }
+    process.stdout.write(`\nAI-readiness: ${report.score} / 100 (${report.grade}, shape-aware)\n`);
     if (report.topRecommendations.length) {
         // Keep the default doctor output short: top 3 recommendations,
-        // pass `--verbose` for the full list.
+        // pass `--verbose` for the full list. Recommendations only fire
+        // from `core` dimensions now — n/a-for-shape dimensions stop
+        // generating the misleading "add a pipeline" advice for libraries.
         const verbose = flagBool(args, 'verbose');
         const visible = verbose ? report.topRecommendations : report.topRecommendations.slice(0, 3);
         process.stdout.write(`Top recommendations${verbose ? '' : ` (top ${visible.length})`}:\n`);
@@ -471,6 +585,21 @@ async function doctorCommandImpl(args) {
             process.stdout.write(`  … (${report.topRecommendations.length - visible.length} more — pass --verbose to see all)\n`);
         }
     }
+    // Surface N/A dimensions when --show-na is passed, so users can see
+    // what was deliberately skipped and disagree if they want to.
+    if (flagBool(args, 'show-na')) {
+        const skipped = report.dimensions.filter((d) => d.applies !== 'core');
+        if (skipped.length > 0) {
+            process.stdout.write(`\nNot counted in score (${skipped.length} dimensions):\n`);
+            for (const d of skipped) {
+                const tag = d.applies === 'n/a-for-shape' ? 'n/a' : 'advisory';
+                process.stdout.write(`  [${tag}] ${d.title}: ${d.note}`);
+                if (d.appliesReason)
+                    process.stdout.write(` — ${d.appliesReason}`);
+                process.stdout.write('\n');
+            }
+        }
+    }
     if (strictEval.failed) {
         process.stdout.write(`\nStrict mode: failing because ${strictEval.countedWarnings} warning(s) + ${result.summary.errors} error(s) exist (${strictEval.reason}).\n`);
     }
@@ -497,8 +626,31 @@ async function doctorCommandImpl(args) {
     if (previewEligible) {
         process.stdout.write('\nDraft patch available — run `shrk fix preview` for a preview-only patch under `.sharkcraft/fixes/`.\n');
     }
+    if (llmEnvelope) {
+        process.stdout.write('\n');
+        process.stdout.write(renderRecommendationsMarkdown(llmEnvelope));
+    }
     return overallExitCode;
 }
+function summariseDoctorChecks(checks) {
+    const lines = [];
+    const order = [DoctorSeverity.Error, DoctorSeverity.Warning, DoctorSeverity.Info, DoctorSeverity.Ok];
+    for (const sev of order) {
+        const grouped = checks.filter((c) => c.severity === sev);
+        if (grouped.length === 0)
+            continue;
+        const label = SEVERITY_LABEL[sev].trim();
+        lines.push(`## ${label} (${grouped.length})`);
+        for (const c of grouped) {
+            const fix = c.recommendedFix ?? c.fix;
+            lines.push(`- **${c.title}**${c.category ? ` (${c.category})` : ''}: ${c.message}${fix ? ` — suggested fix: ${fix}` : ''}`);
+        }
+        lines.push('');
+    }
+    if (lines.length === 0)
+        lines.push('(no findings — all checks passed)');
+    return lines.join('\n');
+}
 export const doctorSuppressCommand = {
     name: 'suppress',
     description: 'Add a doctor finding to sharkcraft/doctor.suppressions.json. Requires --reason.',

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

@@ -1 +1 @@
-{"version":3,"file":"export.command.d.ts","sourceRoot":"","sources":["../../src/commands/export.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,aAAa,EAAE,eAkF3B,CAAC"}
+{"version":3,"file":"export.command.d.ts","sourceRoot":"","sources":["../../src/commands/export.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,aAAa,EAAE,eAuF3B,CAAC"}

package/dist/commands/export.command.js

@@ -2,8 +2,9 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { inspectSharkcraft } from '@shrkcrft/inspector';
 import { ALL_EXPORT_FORMATS, isExportFormat, renderExport, } from "../export/export-formats.js";
+import { buildClaudeCommands } from "../export/claude-commands-export.js";
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
-import { asJson, header } from "../output/format-output.js";
+import { asJson, bullet, header } from "../output/format-output.js";
 import { exportBundleCommand, exportSessionCommand, exportQualityCommand, exportReviewCommand, } from "./export-bundle.command.js";
 const ARCHIVE_SUBCOMMANDS = {
     bundle: exportBundleCommand,
@@ -13,7 +14,7 @@ const ARCHIVE_SUBCOMMANDS = {
 };
 export const exportCommand = {
     name: 'export',
-    description: 'Render SharkCraft knowledge as a flat agent-rule file (AGENTS.md / CLAUDE.md / .cursor/rules / copilot-instructions). Dry-run by default; pass --write to save.',
+    description: 'Inversion — pull SharkCraft rules into the agent\'s prompt instead of the agent calling back to shrk. Single-file outputs: claude-skill (.claude/skills/<name>/SKILL.md, recommended), agents-md (AGENTS.md), claude-md (CLAUDE.md), cursor-rules (.cursor/rules/*.mdc), copilot-instructions. Multi-file output: claude-commands (.claude/commands/*.md — per-project slash commands like /new-service, /check-changes, /follow-shrk). Dry-run by default; pass --write to save.',
     usage: 'shrk [--cwd <dir>] export <format> [--write] [--output <path>] [--task "<task>"] [--max-rules N] [--max-paths N] [--json]',
     async run(args) {
         const format = args.positional[0];
@@ -27,8 +28,13 @@ export const exportCommand = {
             const sub = { ...args, positional: args.positional.slice(1) };
             return archive.run(sub);
         }
+        // Multi-file `claude-commands` dispatches separately — it emits
+        // one .md per slash command, not a single rendered file.
+        if (format === 'claude-commands') {
+            return runClaudeCommandsExport(args);
+        }
         if (!isExportFormat(format)) {
-            process.stderr.write(`Unknown export format "${format}".\nFormats: ${ALL_EXPORT_FORMATS.join(', ')}, bundle, session, quality, review\n`);
+            process.stderr.write(`Unknown export format "${format}".\nFormats: ${ALL_EXPORT_FORMATS.join(', ')}, claude-commands, bundle, session, quality, review\n`);
             return 2;
         }
         const cwd = resolveCwd(args);
@@ -81,3 +87,70 @@ export const exportCommand = {
         return 0;
     },
 };
+/**
+ * `shrk export claude-commands` — multi-file generator for Claude
+ * Code's native `.claude/commands/` slash-command primitive. Produces
+ * one .md per command (static + per-template).
+ *
+ * Unlike single-file exports (claude-skill / claude-md / etc.) this
+ * writes a SET of files. Each file is a complete recipe Claude Code
+ * loads when the user types the matching slash command.
+ */
+async function runClaudeCommandsExport(args) {
+    const cwd = resolveCwd(args);
+    const inspection = await inspectSharkcraft({ cwd });
+    const result = buildClaudeCommands(inspection);
+    const wantJson = flagBool(args, 'json');
+    const doWrite = flagBool(args, 'write');
+    const force = flagBool(args, 'force');
+    if (wantJson) {
+        process.stdout.write(asJson({
+            format: 'claude-commands',
+            write: doWrite,
+            files: result.files.map((f) => ({
+                path: f.path,
+                slash: f.slash,
+                source: f.source,
+            })),
+        }) + '\n');
+        return 0;
+    }
+    if (!doWrite) {
+        process.stdout.write(header('Export (claude-commands) — dry-run'));
+        process.stdout.write(`Would write ${result.files.length} command file(s):\n\n`);
+        for (const f of result.files) {
+            process.stdout.write(`  ${f.path}\n`);
+            process.stdout.write(`    → users type \`/${f.slash}\` in Claude Code (${f.source})\n`);
+        }
+        process.stdout.write('\nRe-run with --write to save.\n');
+        return 0;
+    }
+    const written = [];
+    const skipped = [];
+    for (const file of result.files) {
+        const fullPath = join(cwd, file.path);
+        mkdirSync(dirname(fullPath), { recursive: true });
+        if (existsSync(fullPath) && !force) {
+            skipped.push(file.path);
+            continue;
+        }
+        writeFileSync(fullPath, file.content, 'utf8');
+        written.push(file.path);
+    }
+    process.stdout.write(header('Claude commands exported'));
+    if (written.length) {
+        process.stdout.write(`Wrote ${written.length} command file(s):\n`);
+        for (const p of written) {
+            const f = result.files.find((x) => x.path === p);
+            process.stdout.write(bullet(`${p}  → \`/${f.slash}\``) + '\n');
+        }
+    }
+    if (skipped.length) {
+        process.stdout.write(`\nSkipped ${skipped.length} (already exist; use --force to overwrite):\n`);
+        for (const p of skipped)
+            process.stdout.write(bullet(p) + '\n');
+    }
+    process.stdout.write('\nClaude Code picks up `.claude/commands/*.md` automatically. ' +
+        'Open the project in Claude Code, type `/` — the slash commands are in the palette.\n');
+    return 0;
+}

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

@@ -0,0 +1,12 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk framework` — run / inspect the framework-aware extractors.
+ *
+ * Sub-verbs:
+ *   - shrk framework index           run extractors over the project
+ *   - shrk framework status          report store health
+ *   - shrk framework list [filters]  list entities (--framework, --subtype, --file)
+ *   - shrk framework routes          NestJS route table (method, path, handler, file)
+ */
+export declare const frameworkCommand: ICommandHandler;
+//# sourceMappingURL=framework.command.d.ts.map

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

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

package/dist/commands/framework.command.js

@@ -0,0 +1,180 @@
+import { buildRegistryWithPacks, defaultRegistry, FrameworkQueryApi, runExtractors, } from '@shrkcrft/framework-scanners';
+import { inspectSharkcraft } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk framework` — run / inspect the framework-aware extractors.
+ *
+ * Sub-verbs:
+ *   - shrk framework index           run extractors over the project
+ *   - shrk framework status          report store health
+ *   - shrk framework list [filters]  list entities (--framework, --subtype, --file)
+ *   - shrk framework routes          NestJS route table (method, path, handler, file)
+ */
+export const frameworkCommand = {
+    name: 'framework',
+    description: 'Framework-aware extractors: NestJS (controllers/modules/providers/routes), React (components/hook usages). Output: shrk framework list / routes / status / index.',
+    usage: 'shrk framework index [--only nestjs,react] [--json] | shrk framework status [--json] | shrk framework list [--framework <name>] [--subtype <s>] [--file <path>] [--limit N] [--json] | shrk framework routes [--json]',
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'index')
+            return runIndex(args);
+        if (sub === 'status')
+            return runStatus(args);
+        if (sub === 'list')
+            return runList(args);
+        if (sub === 'routes')
+            return runRoutes(args);
+        process.stderr.write(this.usage + '\n');
+        return 2;
+    },
+};
+async function runIndex(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const only = flagString(args, 'only');
+    const noPacks = flagBool(args, 'no-packs');
+    try {
+        // Build the registry: built-ins + optional pack-contributed extractors.
+        const registry = defaultRegistry();
+        let packPackages = [];
+        let packDiagnostics = [];
+        if (!noPacks) {
+            try {
+                const inspection = await inspectSharkcraft({ cwd });
+                const merged = await buildRegistryWithPacks(registry, inspection.packs);
+                packPackages = merged.packs;
+                packDiagnostics = merged.diagnostics;
+            }
+            catch (e) {
+                // Pack loading is best-effort. Surface the error as a diagnostic
+                // but don't block the index — built-in extractors still run.
+                packDiagnostics = [`pack discovery failed: ${e.message}`];
+            }
+        }
+        const r = runExtractors({
+            projectRoot: cwd,
+            registry,
+            ...(only ? { only: only.split(',').map((s) => s.trim()).filter(Boolean) } : {}),
+        });
+        const diagnostics = [...packDiagnostics, ...r.diagnostics];
+        if (wantJson) {
+            process.stdout.write(asJson({
+                ok: true,
+                manifest: r.manifest,
+                filesScanned: r.filesScanned,
+                durationMs: r.durationMs,
+                diagnostics,
+                packExtractors: packPackages,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Framework index'));
+        process.stdout.write(kv('schema', r.manifest.schema) + '\n');
+        process.stdout.write(kv('frameworks', r.manifest.frameworks.join(', ')) + '\n');
+        process.stdout.write(kv('files scanned', String(r.filesScanned)) + '\n');
+        for (const [framework, count] of Object.entries(r.manifest.countsByFramework)) {
+            process.stdout.write(kv(`entities (${framework})`, String(count)) + '\n');
+        }
+        if (packPackages.length > 0) {
+            process.stdout.write(kv('pack extractors', packPackages.join(', ')) + '\n');
+        }
+        process.stdout.write(kv('duration', `${r.durationMs}ms`) + '\n');
+        for (const d of diagnostics.slice(0, 5))
+            process.stdout.write(`! ${d}\n`);
+        return 0;
+    }
+    catch (e) {
+        const msg = e.message;
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: msg, nextCommand: 'shrk graph index' }) + '\n');
+        }
+        else {
+            process.stderr.write(msg + '\n');
+        }
+        return 1;
+    }
+}
+async function runStatus(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const missing = FrameworkQueryApi.missingDescription(cwd);
+    if (missing) {
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, state: 'missing', message: missing, nextCommand: 'shrk framework index' }) + '\n');
+            return 1;
+        }
+        process.stderr.write(missing + '\n');
+        return 1;
+    }
+    const api = FrameworkQueryApi.fromStore(cwd);
+    const m = api.manifest();
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, manifest: m }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('Framework status'));
+    process.stdout.write(kv('schema', m.schema) + '\n');
+    process.stdout.write(kv('frameworks', m.frameworks.join(', ')) + '\n');
+    for (const [k, v] of Object.entries(m.countsBySubtype)) {
+        process.stdout.write(kv(`  ${k}`, String(v)) + '\n');
+    }
+    process.stdout.write(kv('last built', m.lastBuiltAt) + '\n');
+    return 0;
+}
+async function runList(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const missing = FrameworkQueryApi.missingDescription(cwd);
+    if (missing) {
+        process.stderr.write(missing + '\n');
+        return 1;
+    }
+    const api = FrameworkQueryApi.fromStore(cwd);
+    const framework = flagString(args, 'framework');
+    const subtype = flagString(args, 'subtype');
+    const file = flagString(args, 'file');
+    const limit = Number(flagString(args, 'limit') ?? '50');
+    const entities = api.list({
+        ...(framework ? { framework } : {}),
+        ...(subtype ? { subtype } : {}),
+        ...(file ? { file } : {}),
+        limit,
+    });
+    if (wantJson) {
+        process.stdout.write(asJson({
+            schema: 'sharkcraft.framework-list/v1',
+            filters: { framework, subtype, file },
+            total: entities.length,
+            entities: entities.map((n) => ({ id: n.id, label: n.label, path: n.path, data: n.data })),
+        }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('Framework entities'));
+    process.stdout.write(kv('total', String(entities.length)) + '\n');
+    for (const n of entities) {
+        process.stdout.write(`  ${n.data?.['framework'] ?? '?'}:${n.data?.['subtype'] ?? '?'}  ${n.label}  ${n.path ?? ''}\n`);
+    }
+    return 0;
+}
+async function runRoutes(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const missing = FrameworkQueryApi.missingDescription(cwd);
+    if (missing) {
+        process.stderr.write(missing + '\n');
+        return 1;
+    }
+    const api = FrameworkQueryApi.fromStore(cwd);
+    const routes = api.routes();
+    if (wantJson) {
+        process.stdout.write(asJson({ schema: 'sharkcraft.framework-routes/v1', total: routes.length, routes }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('NestJS routes'));
+    process.stdout.write(kv('total', String(routes.length)) + '\n');
+    for (const r of routes.slice(0, 100)) {
+        process.stdout.write(`  ${r.method.padEnd(6)} ${r.path.padEnd(36)} → ${r.handler}  (${r.file})\n`);
+    }
+    return 0;
+}

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

@@ -0,0 +1,15 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk gate` — run all code-intelligence quality gates and emit one
+ * pass/fail report. Designed as the single command CI should call
+ * before merge.
+ *
+ * Exit codes:
+ *   - 0 if overall status is `pass` (no failures, no warnings)
+ *   - 0 if overall is `warn` (default — opt-in to fail via --strict)
+ *   - 1 if overall is `fail`
+ *
+ * Pass `--strict` to treat `warn` as failure.
+ */
+export declare const gateCommand: ICommandHandler;
+//# sourceMappingURL=gate.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eA+FzB,CAAC"}