@shrkcrft/inspector 0.1.0-alpha.2

package/dist/codemod-assist.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Codemod-assist (NOT a codemod engine).
+ *
+ * Inventory + plan + checklist for a rule's cleanup work. Source is never
+ * rewritten by default. The output:
+ *   - lists affected files (when a rule has a custom-check that produced
+ *     a parsed report, or when the user passes a target list).
+ *   - groups by risk (low/medium/high) using consumer counts when an
+ *     impact-analysis hint is supplied.
+ *   - emits a project-script template under `.sharkcraft/fixes/` when
+ *     asked.
+ *   - clearly states "this needs manual / ts-morph / jscodeshift work
+ *     for the rewrite step".
+ *
+ * Hard rules:
+ *   - No source mutation.
+ *   - No spawning of external tools.
+ *   - The "checklist" is text — not a workflow runner.
+ */
+import type { IKnowledgeEntry } from '@shrkcrft/knowledge';
+import type { ICustomCheckReport } from './custom-checks.js';
+export declare const CODEMOD_ASSIST_SCHEMA = "sharkcraft.codemod-assist/v1";
+export declare enum CodemodRiskBand {
+    Low = "low",
+    Medium = "medium",
+    High = "high",
+    Unknown = "unknown"
+}
+export interface ICodemodAffectedFile {
+    path: string;
+    /** Unique consumers, from impact-analysis when available. */
+    consumerCount?: number;
+    /** Free-form notes copied from the check report. */
+    note?: string;
+    /** Risk band determined by the planner. */
+    risk: CodemodRiskBand;
+    /** Suggested first action — copy/rewrite/delete/manual. */
+    suggestedAction: 'rewrite' | 'delete' | 'manual' | 'review';
+}
+export interface ICodemodAssistInput {
+    rule: IKnowledgeEntry;
+    /**
+     * Optional list of files that match the rule's check (typically
+     * supplied from a parsed `sharkcraft.custom-check/v1` report).
+     */
+    affectedFiles?: readonly {
+        path: string;
+        note?: string;
+    }[];
+    /** Map of file path → unique consumer count (impact-analysis output). */
+    consumerCounts?: ReadonlyMap<string, number>;
+    /**
+     * Free-form recommended external tool. Defaults derived from rule tags.
+     */
+    recommendedExternalTool?: string;
+}
+export interface ICodemodAssistChecklistItem {
+    id: string;
+    description: string;
+    /** What command should the agent / human run for this item. */
+    suggestedCommand?: string;
+    /** Risk band for this item. */
+    risk: CodemodRiskBand;
+}
+export interface ICodemodAssistReport {
+    schema: typeof CODEMOD_ASSIST_SCHEMA;
+    generatedAt: string;
+    ruleId: string;
+    ruleTitle: string;
+    /** What the engine can validate locally. */
+    enginePromise: readonly string[];
+    /** What it cannot do (clearly stated). */
+    engineLimits: readonly string[];
+    affectedFiles: readonly ICodemodAffectedFile[];
+    riskGroups: {
+        low: readonly string[];
+        medium: readonly string[];
+        high: readonly string[];
+        unknown: readonly string[];
+    };
+    recommendedExternalTool: string;
+    checklist: readonly ICodemodAssistChecklistItem[];
+    /** Optional project-script template the agent can save under .sharkcraft/fixes/. */
+    scriptTemplate: {
+        path: string;
+        body: string;
+    };
+    /** Suggested validation commands after the rewrite is done. */
+    validationCommands: readonly string[];
+}
+export declare function buildCodemodAssistReport(input: ICodemodAssistInput): ICodemodAssistReport;
+export declare function affectedFromCheckReport(report: ICustomCheckReport): readonly {
+    path: string;
+    note?: string;
+}[];
+export declare function renderCodemodAssistMarkdown(report: ICodemodAssistReport): string;
+//# sourceMappingURL=codemod-assist.d.ts.map

package/dist/codemod-assist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codemod-assist.d.ts","sourceRoot":"","sources":["../src/codemod-assist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,oBAAY,eAAe;IACzB,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,EAAE,eAAe,CAAC;IACtB,2DAA2D;IAC3D,eAAe,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3D,yEAAyE;IACzE,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,0CAA0C;IAC1C,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC/C,UAAU,EAAE;QACV,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;QACvB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;QAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QACxB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;KAC5B,CAAC;IACF,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAClD,oFAAoF;IACpF,cAAc,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,+DAA+D;IAC/D,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAmGD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAiGzF;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAO9G;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA2ChF"}

package/dist/codemod-assist.js

@@ -0,0 +1,261 @@
+export const CODEMOD_ASSIST_SCHEMA = 'sharkcraft.codemod-assist/v1';
+export var CodemodRiskBand;
+(function (CodemodRiskBand) {
+    CodemodRiskBand["Low"] = "low";
+    CodemodRiskBand["Medium"] = "medium";
+    CodemodRiskBand["High"] = "high";
+    CodemodRiskBand["Unknown"] = "unknown";
+})(CodemodRiskBand || (CodemodRiskBand = {}));
+const DELETE_TAGS = new Set(['delete', 'cleanup', 'noreexport', 'no-reexport', 're-export', 'reexport-proxy']);
+const REWRITE_TAGS = new Set(['rewrite', 'refactor', 'imports', 'rename']);
+function defaultExternalTool(rule, fallback) {
+    if (fallback)
+        return fallback;
+    const tagsLower = new Set(rule.tags.map((t) => t.toLowerCase()));
+    if (tagsLower.has('imports') || rule.id.toLowerCase().includes('reexport')) {
+        return 'ts-morph or jscodeshift (manual rewrite of consumers)';
+    }
+    if (tagsLower.has('lint') || tagsLower.has('style')) {
+        return 'eslint custom rule + autofix (when safe)';
+    }
+    if (tagsLower.has('boundaries') || tagsLower.has('architecture')) {
+        return 'manual review + targeted rename via shrk knowledge rename-symbol';
+    }
+    return 'ts-morph (or manual edits when scope is small)';
+}
+function bandForFile(consumerCount) {
+    if (consumerCount === undefined)
+        return CodemodRiskBand.Unknown;
+    if (consumerCount === 0)
+        return CodemodRiskBand.Low;
+    if (consumerCount <= 5)
+        return CodemodRiskBand.Medium;
+    return CodemodRiskBand.High;
+}
+function suggestedActionForRule(rule) {
+    const lower = rule.id.toLowerCase();
+    if (lower.includes('reexport') || lower.includes('proxy'))
+        return 'delete';
+    const tags = new Set(rule.tags.map((t) => t.toLowerCase()));
+    for (const t of tags)
+        if (DELETE_TAGS.has(t))
+            return 'delete';
+    for (const t of tags)
+        if (REWRITE_TAGS.has(t))
+            return 'rewrite';
+    return 'review';
+}
+function fileSafeId(id) {
+    return id.replace(/[^a-zA-Z0-9]+/g, '-');
+}
+function buildScriptTemplate(rule, suggestedAction) {
+    const safeId = fileSafeId(rule.id);
+    const path = `.sharkcraft/fixes/codemod-${safeId}.template.ts`;
+    const body = `/**
+ * Codemod-assist template for "${rule.id}".
+ *
+ * Auto-generated by \`shrk codemod plan --rule ${rule.id}\`. The engine
+ * does NOT rewrite source. This file is a starting point for the
+ * project-script that does. Suggested first action: ${suggestedAction}.
+ *
+ * Convention: the script should write a sharkcraft.custom-check/v1
+ * report to .sharkcraft/reports/custom-check-${safeId}.json so
+ * \`shrk checks run ${safeId}\` can parse it.
+ */
+import { writeFileSync } from 'node:fs';
+
+const REPORT_PATH = '.sharkcraft/reports/custom-check-${safeId}.json';
+
+function findOffenders(): string[] {
+  // TODO: walk the repo and return paths matching the rule shape.
+  return [];
+}
+
+function planRewrite(file: string): { ok: boolean; message: string } {
+  // TODO: open the file with ts-morph / jscodeshift / regex and decide.
+  return { ok: true, message: \`would ${suggestedAction} \${file}\` };
+}
+
+function main(): void {
+  const offenders = findOffenders();
+  const findings = offenders.map((file) => {
+    const plan = planRewrite(file);
+    return {
+      severity: plan.ok ? 'info' : 'error',
+      file,
+      message: plan.message,
+      suggestedAction: '${suggestedAction}',
+      safeToAutoFix: false,
+    };
+  });
+  const report = {
+    schema: 'sharkcraft.custom-check/v1',
+    checkId: '${safeId}',
+    ruleId: '${rule.id}',
+    generatedAt: new Date().toISOString(),
+    status: findings.some((f) => f.severity === 'error') ? 'fail' : findings.length > 0 ? 'warn' : 'pass',
+    findings,
+  };
+  writeFileSync(REPORT_PATH, JSON.stringify(report, null, 2) + '\\n');
+}
+
+main();
+`;
+    return { path, body };
+}
+export function buildCodemodAssistReport(input) {
+    const rule = input.rule;
+    const suggestion = suggestedActionForRule(rule);
+    const externalTool = defaultExternalTool(rule, input.recommendedExternalTool);
+    const counts = input.consumerCounts ?? new Map();
+    const affected = (input.affectedFiles ?? []).map((f) => {
+        const consumerCount = counts.get(f.path);
+        return {
+            path: f.path,
+            note: f.note,
+            consumerCount,
+            risk: bandForFile(consumerCount),
+            suggestedAction: suggestion,
+        };
+    });
+    const groups = {
+        low: affected.filter((a) => a.risk === CodemodRiskBand.Low).map((a) => a.path),
+        medium: affected.filter((a) => a.risk === CodemodRiskBand.Medium).map((a) => a.path),
+        high: affected.filter((a) => a.risk === CodemodRiskBand.High).map((a) => a.path),
+        unknown: affected.filter((a) => a.risk === CodemodRiskBand.Unknown).map((a) => a.path),
+    };
+    const checklist = [];
+    let counter = 1;
+    if (groups.low.length > 0) {
+        checklist.push({
+            id: `codemod-${counter++}`,
+            risk: CodemodRiskBand.Low,
+            description: `Low-risk: ${groups.low.length} file(s) with no consumers — safe to ${suggestion} first.`,
+            suggestedCommand: `shrk codemod inventory --rule ${rule.id} --risk low`,
+        });
+    }
+    if (groups.medium.length > 0) {
+        checklist.push({
+            id: `codemod-${counter++}`,
+            risk: CodemodRiskBand.Medium,
+            description: `Medium-risk: ${groups.medium.length} file(s) with 1–5 consumers — ${suggestion} after re-import sweep.`,
+            suggestedCommand: `shrk impact analyze --files ${groups.medium.slice(0, 3).join(',')}`,
+        });
+    }
+    if (groups.high.length > 0) {
+        checklist.push({
+            id: `codemod-${counter++}`,
+            risk: CodemodRiskBand.High,
+            description: `High-risk: ${groups.high.length} file(s) with >5 consumers — schedule with owners before rewriting.`,
+            suggestedCommand: `shrk impact analyze --files ${groups.high.slice(0, 3).join(',')}`,
+        });
+    }
+    if (groups.unknown.length > 0) {
+        checklist.push({
+            id: `codemod-${counter++}`,
+            risk: CodemodRiskBand.Unknown,
+            description: `Unknown risk: ${groups.unknown.length} file(s) — run impact-analysis to fill in consumer counts.`,
+            suggestedCommand: `shrk impact analyze --files ${groups.unknown.slice(0, 3).join(',')}`,
+        });
+    }
+    checklist.push({
+        id: `codemod-${counter++}`,
+        risk: CodemodRiskBand.Unknown,
+        description: `Use ${externalTool} for the actual rewrite — engine does not touch source.`,
+    });
+    checklist.push({
+        id: `codemod-${counter++}`,
+        risk: CodemodRiskBand.Unknown,
+        description: 'After rewriting, re-run the rule\'s custom check + boundaries + tests.',
+        suggestedCommand: `shrk checks run codemod-${fileSafeId(rule.id)} --execute`,
+    });
+    const validation = [
+        'shrk doctor',
+        'shrk check boundaries',
+        'bun x tsc -p tsconfig.base.json --noEmit',
+        'bun test',
+    ];
+    return {
+        schema: CODEMOD_ASSIST_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        ruleId: rule.id,
+        ruleTitle: rule.title,
+        enginePromise: [
+            'inventory affected files (when a check report or target list is supplied)',
+            'group by risk via consumer count when impact-analysis output is provided',
+            'suggest the rewrite strategy and the external tool',
+            'emit a project-script template under .sharkcraft/fixes/',
+            'list the validation commands to run after rewrite',
+        ],
+        engineLimits: [
+            'no source rewrite — the engine never edits the offending files',
+            'no AST traversal — use ts-morph / jscodeshift for safe rewrites',
+            'no spawn of external tools — the agent runs them after review',
+            'consumer counts are absent when impact-analysis output is not provided',
+        ],
+        affectedFiles: affected,
+        riskGroups: groups,
+        recommendedExternalTool: externalTool,
+        checklist,
+        scriptTemplate: buildScriptTemplate(rule, suggestion),
+        validationCommands: validation,
+    };
+}
+export function affectedFromCheckReport(report) {
+    const out = [];
+    for (const f of report.findings) {
+        if (!f.file)
+            continue;
+        out.push({ path: f.file, note: f.message });
+    }
+    return out;
+}
+export function renderCodemodAssistMarkdown(report) {
+    const lines = [];
+    lines.push(`# Codemod-assist for ${report.ruleId}`);
+    lines.push('');
+    lines.push(`> ${report.ruleTitle}`);
+    lines.push('');
+    lines.push(`Generated: ${report.generatedAt}`);
+    lines.push('');
+    lines.push('## What the engine can do');
+    for (const p of report.enginePromise)
+        lines.push(`- ${p}`);
+    lines.push('');
+    lines.push('## What the engine cannot do');
+    for (const p of report.engineLimits)
+        lines.push(`- ${p}`);
+    lines.push('');
+    lines.push('## Affected files');
+    if (report.affectedFiles.length === 0) {
+        lines.push('_(no files supplied — pass `--from-report <path>` or `--targets a,b,c`)_');
+    }
+    else {
+        lines.push('| Risk | Consumers | File | Note |');
+        lines.push('| --- | --- | --- | --- |');
+        for (const f of report.affectedFiles) {
+            lines.push(`| ${f.risk} | ${f.consumerCount ?? '?'} | \`${f.path}\` | ${f.note ?? ''} |`);
+        }
+    }
+    lines.push('');
+    lines.push(`## Recommended external tool: ${report.recommendedExternalTool}`);
+    lines.push('');
+    lines.push('## Checklist');
+    for (const c of report.checklist) {
+        lines.push(`- [ ] (${c.risk}) ${c.description}`);
+        if (c.suggestedCommand)
+            lines.push(`        $ ${c.suggestedCommand}`);
+    }
+    lines.push('');
+    lines.push('## Validation commands (after rewrite)');
+    for (const v of report.validationCommands)
+        lines.push(`- $ ${v}`);
+    lines.push('');
+    lines.push('## Project-script template (preview)');
+    lines.push('Save this under `' + report.scriptTemplate.path + '` and customise:');
+    lines.push('');
+    lines.push('```typescript');
+    lines.push(report.scriptTemplate.body);
+    lines.push('```');
+    return lines.join('\n') + '\n';
+}

package/dist/command-recommender.d.ts

@@ -0,0 +1,25 @@
+import { type IUncertaintyReport } from './uncertainty-report.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const COMMAND_RECOMMENDER_SCHEMA = "sharkcraft.command-recommender/v1";
+export interface ICommandRecommendation {
+    command: string;
+    why: string;
+    safetyLevel: 'read-only' | 'writes-drafts' | 'writes-session' | 'writes-source' | 'runs-shell';
+    docsLink?: string;
+}
+export interface ICommandRecommendationReport {
+    schema: typeof COMMAND_RECOMMENDER_SCHEMA;
+    generatedAt: string;
+    query: string;
+    role?: string;
+    recommendations: readonly ICommandRecommendation[];
+    nextCommand: string;
+    warnings: readonly string[];
+    /** Uncertainty report (confidence + reasons + safe fallback). */
+    uncertainty: IUncertaintyReport;
+}
+export declare function recommendCommands(inspection: ISharkcraftInspection, query: string, options?: {
+    fromError?: string;
+    role?: string;
+}): Promise<ICommandRecommendationReport>;
+//# sourceMappingURL=command-recommender.d.ts.map

package/dist/command-recommender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-recommender.d.ts","sourceRoot":"","sources":["../src/command-recommender.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,WAAW,GAAG,eAAe,GAAG,gBAAgB,GAAG,eAAe,GAAG,YAAY,CAAC;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,iEAAiE;IACjE,WAAW,EAAE,kBAAkB,CAAC;CACjC;AA0DD,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,OAAO,CAAC,4BAA4B,CAAC,CAoFvC"}

package/dist/command-recommender.js

@@ -0,0 +1,145 @@
+/**
+ * Deterministic command recommender.
+ *
+ * Given an input ("what I want to do" or stderr blob), surface the
+ * most relevant commands from the catalog + diagnostics + start-here
+ * flow + intent classification. No AI, no embeddings.
+ */
+import { classifyChangeIntent, ChangeIntentKind } from "./change-intent.js";
+import { buildDiagnosticByCode, listDiagnostics } from "./failure-diagnostics.js";
+import { buildUncertaintyReport, } from "./uncertainty-report.js";
+export const COMMAND_RECOMMENDER_SCHEMA = 'sharkcraft.command-recommender/v1';
+const RECIPES = [
+    {
+        match: /review|pr|pull[-\s]?request/i,
+        recommendations: [
+            { command: 'shrk review packet --v3 --since main', why: 'Generate an agent-ready PR review packet.' },
+            { command: 'shrk impact --since main', why: 'See what changed and what depends on it.' },
+            { command: 'shrk report site --output .sharkcraft/reports/site', why: 'Render the local read-only review site.' },
+        ],
+    },
+    {
+        match: /start|begin|new task|feature/i,
+        recommendations: [
+            { command: 'shrk brief "<task>"', why: 'Pre-work brief for the agent.' },
+            { command: 'shrk dev start "<task>"', why: 'Start a tracked dev session.' },
+            { command: 'shrk intent "<task>"', why: 'Classify the change intent first.' },
+        ],
+    },
+    {
+        match: /publish|release|tag|alpha|beta/i,
+        recommendations: [
+            { command: 'shrk release readiness --strict', why: 'Confirm release gates.' },
+            { command: 'shrk release smoke --scenario all', why: 'Validate the release smoke matrix.' },
+            { command: 'bun run release:preflight', why: 'Run the full preflight.' },
+        ],
+    },
+    {
+        match: /pack/i,
+        recommendations: [
+            { command: 'shrk packs doctor --release --require-signatures', why: 'Validate discovered packs.' },
+            { command: 'shrk packs compat <pack> --consumer-root .', why: 'Detect helper/symbol-missing issues.' },
+            { command: 'shrk packs quality <path>', why: 'Score pack maturity.' },
+        ],
+    },
+    {
+        match: /boundary|architecture|layer/i,
+        recommendations: [
+            { command: 'shrk architecture map', why: 'Layered architecture summary.' },
+            { command: 'shrk check boundaries', why: 'Boundary scan.' },
+            { command: 'shrk drift', why: 'Drift report.' },
+        ],
+    },
+];
+function safetyLevelFor(command) {
+    if (/^shrk (gen|init|apply|import|presets apply --write|packs (sign|new))/i.test(command))
+        return 'writes-source';
+    if (/^shrk (onboard|brief|dev start|handoff|export|report site|impact|ci scaffold|simulate|orchestrate)/i.test(command))
+        return 'writes-drafts';
+    if (/^shrk (session|dev report)/i.test(command))
+        return 'writes-session';
+    if (/^bun |^npm |^node |^git /i.test(command))
+        return 'runs-shell';
+    return 'read-only';
+}
+export async function recommendCommands(inspection, query, options = {}) {
+    const warnings = [];
+    const trimmed = query.trim();
+    let recommendations = [];
+    // Recipe matching by query.
+    for (const r of RECIPES) {
+        if (r.match.test(trimmed)) {
+            for (const rec of r.recommendations)
+                recommendations.push({ ...rec, safetyLevel: safetyLevelFor(rec.command) });
+        }
+    }
+    // If a stderr-like input was provided, do a diagnostic-suggest pass.
+    if (options.fromError && options.fromError.length > 0) {
+        for (const e of listDiagnostics()) {
+            const built = buildDiagnosticByCode(e.code, {});
+            if (new RegExp(e.code, 'i').test(options.fromError) || new RegExp(built.problem.slice(0, 20), 'i').test(options.fromError)) {
+                recommendations.push({
+                    command: built.nextCommand,
+                    why: `Diagnostic match: ${e.code}.`,
+                    safetyLevel: safetyLevelFor(built.nextCommand),
+                    ...(built.docsLink ? { docsLink: built.docsLink } : {}),
+                });
+            }
+        }
+    }
+    // Intent-driven fallback.
+    if (recommendations.length === 0) {
+        const intent = await classifyChangeIntent(trimmed, inspection);
+        recommendations.push({
+            command: intent.suggestedFirstCommand,
+            why: `Intent fallback (${intent.kind}, confidence ${intent.confidence}).`,
+            safetyLevel: safetyLevelFor(intent.suggestedFirstCommand),
+        });
+        if (intent.kind === ChangeIntentKind.Unknown) {
+            recommendations.push({ command: 'shrk start-here', why: 'No clear intent — start here.', safetyLevel: 'read-only' });
+        }
+    }
+    // Dedup by command (keep first).
+    const seen = new Set();
+    recommendations = recommendations.filter((r) => (seen.has(r.command) ? false : (seen.add(r.command), true)));
+    // Top of list = first recommendation.
+    const nextCommand = recommendations[0]?.command ?? 'shrk start-here';
+    // Build an uncertainty report from the recommendation signals.
+    const usedRecipe = RECIPES.some((r) => r.match.test(trimmed));
+    let confidence = 'medium';
+    const reasons = [];
+    const missing = [];
+    const increase = [];
+    if (usedRecipe) {
+        confidence = 'high';
+        reasons.push(`Recipe matched the query "${trimmed}".`);
+    }
+    else if (recommendations.length > 0 && recommendations[0]?.why.startsWith('Intent fallback')) {
+        confidence = 'low';
+        reasons.push('No recipe matched — fell back to intent classification.');
+        missing.push({ id: 'no-recipe-match', message: 'No recommender recipe matched the query.' });
+        increase.push('Add a routing hint or recommender recipe for this task class.');
+    }
+    else if (recommendations.length === 0) {
+        confidence = 'unknown';
+        reasons.push('No recommendations could be produced.');
+    }
+    const uncertainty = buildUncertaintyReport({
+        confidence,
+        reasons,
+        missingSignals: missing,
+        suggestedCommands: recommendations.slice(0, 3).map((r) => r.command),
+        safeFallbackCommand: 'shrk start-here',
+        whatWouldIncreaseConfidence: increase,
+    });
+    return {
+        schema: COMMAND_RECOMMENDER_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        query: trimmed,
+        ...(options.role ? { role: options.role } : {}),
+        recommendations,
+        nextCommand,
+        warnings,
+        uncertainty,
+    };
+}

package/dist/command-suggester.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Command discovery + did-you-mean.
+ *
+ * Provides typo-tolerant ranking over a SharkCraft command catalog. Used by
+ * `shrk commands suggest <partial>`, `shrk commands explain <cmd>`, and the
+ * "Unknown subcommand → did you mean …" path in `runCli`.
+ *
+ * Pure, deterministic, fixture-friendly.
+ *
+ * Schema: sharkcraft.command-suggestions/v1
+ */
+export declare const COMMAND_SUGGESTIONS_SCHEMA = "sharkcraft.command-suggestions/v1";
+export interface ICommandEntryLike {
+    command: string;
+    description: string;
+    category: string;
+    safetyLevel: string;
+    writesFiles: boolean;
+    writesSource: boolean;
+    runsShell: boolean;
+    requiresReview: boolean;
+    mcpAvailable: boolean;
+    aliases: readonly string[];
+}
+export interface ICommandSuggestion {
+    command: string;
+    category: string;
+    description: string;
+    safetyLevel: string;
+    score: number;
+    reasons: readonly string[];
+    /** When true, the suggestion writes to source — useful for --safe-only filtering. */
+    writesSource: boolean;
+    /** When false, the suggestion can't be invoked via MCP. */
+    mcpAvailable: boolean;
+}
+export interface ICommandSuggestionsOptions {
+    /** Cap returned suggestions. Default 10. */
+    limit?: number;
+    /** Exclude suggestions that write source. */
+    safeOnly?: boolean;
+    /** Only show MCP-callable commands. */
+    mcpSafeOnly?: boolean;
+    /** Filter by category. */
+    category?: string;
+}
+export declare function suggestCommands(catalog: readonly ICommandEntryLike[], partial: string, options?: ICommandSuggestionsOptions): {
+    schema: typeof COMMAND_SUGGESTIONS_SCHEMA;
+    query: string;
+    suggestions: readonly ICommandSuggestion[];
+};
+/** Suggests at most `limit` did-you-mean candidates for an unknown command path. */
+export declare function suggestDidYouMean(catalog: readonly ICommandEntryLike[], attempted: readonly string[], limit?: number): readonly ICommandSuggestion[];
+export interface ICommandExplanation {
+    schema: 'sharkcraft.command-explain/v1';
+    query: string;
+    exact?: ICommandEntryLike;
+    candidates: readonly ICommandSuggestion[];
+}
+export declare function explainCommand(catalog: readonly ICommandEntryLike[], query: string): ICommandExplanation;
+//# sourceMappingURL=command-suggester.d.ts.map

package/dist/command-suggester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-suggester.d.ts","sourceRoot":"","sources":["../src/command-suggester.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,qFAAqF;IACrF,YAAY,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,0BAA0B;IACzC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAuGD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,0BAA+B,GACvC;IACD,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC5C,CA4BA;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,KAAK,SAAI,GACR,SAAS,kBAAkB,EAAE,CAK/B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,+BAA+B,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC3C;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAUrB"}