@shrkcrft/cli 0.1.0-alpha.12 → 0.1.0-alpha.13

package/dist/audit/templates-fix-plan.js

@@ -0,0 +1,174 @@
+const TEMPLATES_FILE = 'sharkcraft/templates.ts';
+export function buildFixPlan(report) {
+    const fixes = [];
+    const skipped = [];
+    for (const entry of report.templates) {
+        for (const f of entry.deterministicFindings) {
+            const out = dispatchDeterministic(entry, f);
+            if (out.kind === 'fix')
+                fixes.push(out.fix);
+            else
+                skipped.push(out.skip);
+        }
+        for (const f of entry.llmFindings) {
+            fixes.push(makeLlmFix(entry, f));
+        }
+    }
+    const summary = {
+        fixCount: fixes.length,
+        highConfidence: fixes.filter((f) => f.confidence === 'high').length,
+        mediumConfidence: fixes.filter((f) => f.confidence === 'medium').length,
+        lowConfidence: fixes.filter((f) => f.confidence === 'low').length,
+        skipped: skipped.length,
+    };
+    const generatedAt = new Date().toISOString();
+    return {
+        fixPlanId: `fix-${generatedAt.replace(/[:.]/g, '-')}`,
+        generatedAt,
+        auditId: report.auditId,
+        sourceFiles: [TEMPLATES_FILE],
+        fixes,
+        skipped,
+        summary,
+    };
+}
+function dispatchDeterministic(entry, f) {
+    switch (f.category) {
+        case 'unsafe-target':
+            return {
+                kind: 'skip',
+                skip: {
+                    templateId: entry.templateId,
+                    findingCategory: f.category,
+                    finding: f.message,
+                    reason: 'security-sensitive — requires human review',
+                },
+            };
+        case 'missing-name':
+            return makeFix(entry, f, 'high', 'Add a `name` field to this template.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `Add a \`name: '<human-readable name>'\` field next to \`id\`.`,
+                `The name should briefly describe what the template scaffolds (e.g. "CLI command (shrk subcommand)").`,
+                `Do not change other fields. Verify the file still parses.`,
+            ].join('\n'));
+        case 'missing-description':
+            return makeFix(entry, f, 'high', 'Add a `description` field to this template.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `Add a \`description: '<one-sentence description>'\` field. The description appears in \`shrk templates list\` and should explain what the template generates.`,
+                `Do not change other fields. Verify the file still parses.`,
+            ].join('\n'));
+        case 'related-id-unresolved': {
+            const id = extractQuoted(f.message);
+            if (!id) {
+                return makeFix(entry, f, 'medium', 'Remove an unresolved related id (id could not be auto-extracted from the message).', [
+                    `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                    `The finding is: "${f.message}"`,
+                    `Remove the unresolved related id from the \`related\` array. Do not invent a replacement; if no real id applies, leave the array empty or omit the field.`,
+                    `Verify the file still parses.`,
+                ].join('\n'));
+            }
+            return makeFix(entry, f, 'high', `Remove "${id}" from the \`related\` array.`, [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `In its \`related\` array, remove the string "${id}". Do not change any other entries.`,
+                `Verify the file still parses and that "${id}" is not referenced elsewhere in the file.`,
+            ].join('\n'));
+        }
+        case 'undocumented-var': {
+            const varName = extractQuoted(f.message);
+            const where = varName ? `the variable named "${varName}"` : 'the variable referenced in the finding';
+            return makeFix(entry, f, 'medium', varName
+                ? `Add a description to variable "${varName}".`
+                : 'Add a description to an undocumented variable.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `Locate ${where} inside the \`variables\` array.`,
+                `Add a \`description: '<short explanation>'\` field. The description should explain what the variable controls and where its value ends up in the generated output.`,
+                `Verify the file still parses.`,
+            ].join('\n'));
+        }
+        case 'required-var-no-example': {
+            const varName = extractQuoted(f.message);
+            const where = varName ? `the variable named "${varName}"` : 'the required variable referenced in the finding';
+            return makeFix(entry, f, 'medium', varName
+                ? `Add an example value to required variable "${varName}".`
+                : 'Add an example value to a required variable that lacks one.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `Locate ${where} inside the \`variables\` array.`,
+                `Add an \`examples: ['<sample value>']\` field. Choose a sample that's representative of real usage — readable by humans, valid against any \`pattern\` that may also be defined.`,
+                `Verify the file still parses.`,
+            ].join('\n'));
+        }
+        case 'undeclared-var': {
+            const varName = extractPlaceholder(f.message);
+            const where = varName ? `\`{{${varName}}}\`` : 'the undeclared placeholder named in the finding';
+            return makeFix(entry, f, 'medium', varName
+                ? `Resolve undeclared placeholder ${where}.`
+                : 'Resolve an undeclared placeholder in the template body.', [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `The template body uses placeholder ${where} that isn't declared in \`variables[]\`.`,
+                `Pick one:`,
+                `  (a) Add a corresponding entry to \`variables[]\` (with \`name\`, \`required\`, and ideally a \`description\` + \`examples\`). This is right if the placeholder represents intended user input.`,
+                `  (b) Remove the placeholder from the template body. This is right if it was a typo or leftover.`,
+                `Choose based on what the surrounding body and template description imply. Verify the file still parses.`,
+            ].join('\n'));
+        }
+        case 'path-no-convention': {
+            const samplePath = extractQuoted(f.message);
+            return makeFix(entry, f, 'low', samplePath
+                ? `Align template targetPath with path conventions (sample: "${samplePath}").`
+                : 'Align template targetPath with path conventions.', [
+                `The sample target path${samplePath ? ` "${samplePath}"` : ''} doesn't match any entry in \`sharkcraft/paths.ts\`.`,
+                `Decide between two fixes:`,
+                `  (a) Update the template's \`targetPath\` so its rendered output matches an existing path convention. Edit ${TEMPLATES_FILE}, find template "${entry.templateId}", and adjust its \`targetPath\` function/string.`,
+                `  (b) Add a matching entry to \`sharkcraft/paths.ts\` if this template's output really does belong in a new location.`,
+                `Prefer (a) unless the template represents a genuinely new file-shape for the project. Verify both files parse.`,
+            ].join('\n'));
+        }
+        default:
+            return makeFix(entry, f, 'low', `Address finding "${f.category}".`, [
+                `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+                `The audit reported: ${f.message}`,
+                f.suggestion ? `Suggested fix from the inspector: ${f.suggestion}` : 'No specific suggestion was supplied — use judgment.',
+                `Apply a minimal change that resolves the finding without touching unrelated fields. Verify the file still parses.`,
+            ].filter(Boolean).join('\n'));
+    }
+}
+function makeFix(entry, f, confidence, intent, agentPrompt) {
+    return {
+        kind: 'fix',
+        fix: {
+            templateId: entry.templateId,
+            findingCategory: f.category,
+            finding: f.message,
+            severity: f.severity,
+            intent,
+            agentPrompt,
+            confidence,
+            source: 'deterministic',
+        },
+    };
+}
+function makeLlmFix(entry, f) {
+    return {
+        templateId: entry.templateId,
+        findingCategory: f.category,
+        finding: f.message,
+        severity: f.severity,
+        intent: `Review the LLM-flagged "${f.category}" finding and decide whether to act.`,
+        agentPrompt: [
+            `Open ${TEMPLATES_FILE}. Find the template literal with id "${entry.templateId}".`,
+            `An LLM critique flagged (confidence ${f.confidence.toFixed(2)}): ${f.message}`,
+            `LLM findings are advisory — verify against the template body and sibling templates before acting.`,
+            `If you choose to act, keep the change minimal and scoped to the finding. If you don't, that's also a valid outcome — record the decision in your response.`,
+        ].join('\n'),
+        confidence: 'low',
+        source: 'llm',
+    };
+}
+function extractQuoted(message) {
+    const m = message.match(/"([^"]+)"/);
+    return m ? m[1] : null;
+}
+function extractPlaceholder(message) {
+    const m = message.match(/\{\{\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*\}\}/);
+    return m ? m[1] : null;
+}

package/dist/commands/ai-status.command.d.ts

@@ -0,0 +1,19 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk ai-status` — one-shot self-check of the LLM wiring.
+ *
+ * Designed for agents (like Claude) that want to know whether shrk's
+ * LLM enrichment is going to do anything useful, without having to
+ * run a full audit. Three pieces of information:
+ *   1. Which provider, if any, the local-first walk would pick.
+ *   2. The structured `ai` block (the same one every audit emits) so
+ *      the agent can act on the hints.
+ *   3. Optional `--ping`: a tiny live request that proves the
+ *      provider really responds (the resolver only checks env vars).
+ *
+ * The deterministic baseline contract: works without LLM. With no
+ * provider reachable, the output is still useful — it carries the
+ * setup hints.
+ */
+export declare const aiStatusCommand: ICommandHandler;
+//# sourceMappingURL=ai-status.command.d.ts.map

package/dist/commands/ai-status.command.d.ts.map

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

package/dist/commands/ai-status.command.js

@@ -0,0 +1,94 @@
+import { AiMessageRole, buildAiBlock, renderAiBlockMarkdown, selectAiProvider, } from '@shrkcrft/ai';
+import { flagBool, flagNumber, flagString, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+/**
+ * `shrk ai-status` — one-shot self-check of the LLM wiring.
+ *
+ * Designed for agents (like Claude) that want to know whether shrk's
+ * LLM enrichment is going to do anything useful, without having to
+ * run a full audit. Three pieces of information:
+ *   1. Which provider, if any, the local-first walk would pick.
+ *   2. The structured `ai` block (the same one every audit emits) so
+ *      the agent can act on the hints.
+ *   3. Optional `--ping`: a tiny live request that proves the
+ *      provider really responds (the resolver only checks env vars).
+ *
+ * The deterministic baseline contract: works without LLM. With no
+ * provider reachable, the output is still useful — it carries the
+ * setup hints.
+ */
+export const aiStatusCommand = {
+    name: 'ai-status',
+    description: 'Report which AI provider shrk would use right now, with setup or upgrade hints. `--ping` verifies the provider actually responds. Read-only.',
+    usage: 'shrk ai-status [--provider auto|ollama|llamacpp|claude|gemini] [--ping] [--ping-timeout <ms>] [--json]',
+    async run(args) {
+        const providerKind = flagString(args, 'provider');
+        const json = flagBool(args, 'json');
+        const wantPing = flagBool(args, 'ping');
+        const pingTimeoutMs = flagNumber(args, 'ping-timeout') ?? 8000;
+        const selection = selectAiProvider(providerKind);
+        const ai = buildAiBlock({ selection, userOptedOut: false });
+        let ping = null;
+        if (wantPing) {
+            ping = selection.provider
+                ? await pingProvider(selection.provider, pingTimeoutMs)
+                : { ok: false, reason: 'no provider reachable — nothing to ping', elapsedMs: 0 };
+        }
+        if (json) {
+            process.stdout.write(asJson({
+                ai,
+                ...(ping ? { ping } : {}),
+            }) + '\n');
+            return ai.reachable && (!ping || ping.ok) ? 0 : 1;
+        }
+        process.stdout.write(header('AI status'));
+        process.stdout.write(kv('reachable', ai.reachable ? 'yes' : 'no') + '\n');
+        process.stdout.write(kv('requested provider', ai.requestedProvider) + '\n');
+        process.stdout.write(kv('resolved provider', ai.providerId ?? '(none)') + '\n');
+        if (ping) {
+            process.stdout.write(kv('ping', ping.ok
+                ? `ok in ${ping.elapsedMs}ms` + (ping.model ? ` (model: ${ping.model})` : '')
+                : `failed: ${ping.reason}`) + '\n');
+        }
+        process.stdout.write('\n');
+        process.stdout.write(renderAiBlockMarkdown(ai));
+        return ai.reachable && (!ping || ping.ok) ? 0 : 1;
+    },
+};
+async function pingProvider(provider, timeoutMs) {
+    const start = Date.now();
+    // Tiny prompt with bounded output — we just want to prove the round-trip works.
+    const requestPromise = provider.send({
+        messages: [
+            { role: AiMessageRole.System, content: 'Respond with the single word: ok' },
+            { role: AiMessageRole.User, content: 'ping' },
+        ],
+        maxTokens: 8,
+    });
+    const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => resolve({ ok: false, error: new Error(`timed out after ${timeoutMs}ms`) }), timeoutMs);
+    });
+    try {
+        const res = (await Promise.race([requestPromise, timeoutPromise]));
+        const elapsedMs = Date.now() - start;
+        if (!('value' in res) || !res.ok) {
+            const reason = 'error' in res
+                ? res.error.message ?? String(res.error)
+                : 'no response';
+            return { ok: false, reason, elapsedMs };
+        }
+        const value = res.value;
+        return {
+            ok: true,
+            elapsedMs,
+            ...(value.model ? { model: value.model } : {}),
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: e.message,
+            elapsedMs: Date.now() - start,
+        };
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"AAAA,oBAAY,WAAW;IACrB,QAAQ,cAAc;IACtB,iBAAiB,mBAAmB;IACpC,gBAAgB,kBAAkB;IAClC,YAAY,kBAAkB;IAC9B,SAAS,eAAe;IACxB,cAAc,oBAAoB;CACnC;AAED;;;;;;GAMG;AACH,oBAAY,cAAc;IACxB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,8BAA8B;AAC9B,oBAAY,eAAe;IACzB,KAAK,UAAU;IACf,KAAK,UAAU;IACf,EAAE,OAAO;IACT,UAAU,gBAAgB;IAC1B,UAAU,eAAe;CAC1B;AAED;;;;;;GAMG;AACH,oBAAY,eAAe;IACzB,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,MAAM,WAAW;CAClB;AAED;;;;;;GAMG;AACH,oBAAY,gBAAgB;IAC1B,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,KAAK,UAAU;IACf,UAAU,eAAe;IACzB,OAAO,YAAY;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,oBAAY,WAAW;IACrB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,YAAY,iBAAiB;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;IACzB,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;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,kCAAkC;IAClC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,oBAAoB,EAo+FzD,CAAC;AAEH,4DAA4D;AAC5D,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAWpD;AA0DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,CAAC;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAgGjE,CAAC;AAEH,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAItE;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,GAAG,SAAS,eAAe,EAAE,CAKnF;AAED,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,GAAG,eAAe,GAAG,SAAS,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAQ1E;AAqFD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAclE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAwC9D;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,wBAAwB,IAAI,SAAS,uBAAuB,EAAE,CAsB7E;AAED,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,SAAS,uBAAuB,EAAE,GACvC,MAAM,CAaR"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}

package/dist/commands/command-catalog.js

@@ -115,6 +115,16 @@ export const COMMAND_CATALOG = Object.freeze([
         intendedAudience: [CommandAudience.Human, CommandAudience.Agent, CommandAudience.Ci],
         taskRole: CommandTaskRole.Diagnose,
     }),
+    entry({
+        command: 'ai-status',
+        description: 'Report which AI provider shrk would use right now, with setup or upgrade hints. `--ping` verifies the provider actually responds.',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: false,
+        surface: CommandSurface.Common,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent],
+        taskRole: CommandTaskRole.Diagnose,
+    }),
     entry({
         command: 'context',
         description: 'Focused context for a task (rules / paths / templates). For "what should I do?" prefer `shrk recommend "<task>"`.',

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.command.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.command.ts"],"names":[],"mappings":"AAqBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyOhC,eAAO,MAAM,aAAa,EAAE,eAW3B,CAAC;AA+bF,eAAO,MAAM,qBAAqB,EAAE,eAmCnC,CAAC;AAuDF,eAAO,MAAM,yBAAyB,EAAE,eAavC,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eA2CtC,CAAC;AAgCF,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC"}
+{"version":3,"file":"doctor.command.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.command.ts"],"names":[],"mappings":"AAqBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8OhC,eAAO,MAAM,aAAa,EAAE,eAW3B,CAAC;AA4eF,eAAO,MAAM,qBAAqB,EAAE,eAmCnC,CAAC;AAuDF,eAAO,MAAM,yBAAyB,EAAE,eAavC,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eA2CtC,CAAC;AAgCF,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC"}

package/dist/commands/doctor.command.js

@@ -10,6 +10,7 @@ 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 ',
@@ -200,8 +201,8 @@ function renderSemanticIndexCheck(report) {
 }
 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)
@@ -296,6 +297,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.
@@ -388,6 +402,7 @@ async function doctorCommandImpl(args) {
             })),
             ...result,
             ...(filtered ? { filtered } : {}),
+            ...(llmEnvelope ? { llmRecommendations: llmEnvelope } : {}),
         }) + '\n');
         return overallExitCode;
     }
@@ -590,8 +605,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/smart-context.command.d.ts

@@ -23,6 +23,34 @@ export declare const smartContextPlanAheadCommand: ICommandHandler;
 export declare const smartContextListCommand: ICommandHandler;
 /** `shrk smart-context show <slug>` — print a saved entry. */
 export declare const smartContextShowCommand: ICommandHandler;
+/**
+ * `shrk smart-context audit-templates` — local-LLM template audit.
+ *
+ * Orchestrates the existing deterministic template inspectors
+ * (`templates lint` + `templates drift`), dedupes their overlap by
+ * (category + message), and — when a local provider is reachable —
+ * runs an LLM critique pass per template. Always report-only: no edits
+ * to template sources, no plan emission. See
+ * docs/smart-context-audit-templates.md for the report contract.
+ */
+export declare const smartContextAuditTemplatesCommand: ICommandHandler;
+/**
+ * `shrk smart-context audit-knowledge` — local-LLM knowledge audit.
+ *
+ * Wraps `lintKnowledge` + `buildKnowledgeStaleReport` from `@shrkcrft/inspector`,
+ * then layers LLM critique (when a provider is reachable) and emits a
+ * Claude-targetable fix plan. Report-only — no writes to knowledge sources.
+ * See docs/smart-context-audit-templates.md for the shared report contract.
+ */
+export declare const smartContextAuditKnowledgeCommand: ICommandHandler;
+/**
+ * `shrk smart-context audit-pipelines` — local-LLM pipeline audit.
+ *
+ * Wraps `lintPipelines` from `@shrkcrft/inspector`, optionally layers
+ * LLM critique, and emits a Claude-targetable fix plan. Same report-only
+ * contract as audit-templates / audit-knowledge.
+ */
+export declare const smartContextAuditPipelinesCommand: ICommandHandler;
 /** `shrk smart-context embeddings build` — (re)build the semantic index. */
 export declare const smartContextEmbeddingsBuildCommand: ICommandHandler;
 /** `shrk smart-context embeddings-status` — freshness report (no model load). */

package/dist/commands/smart-context.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6BhC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA+JjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAmF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAgHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC"}
+{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyDhC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA+JjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAmF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAiMF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC"}