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

package/dist/audit/templates-audit-llm.js

@@ -0,0 +1,207 @@
+import { AiMessageRole } from '@shrkcrft/ai';
+export async function enrichAuditWithLlm(report, options) {
+    const enrichedEntries = [];
+    for (const entry of report.templates) {
+        const template = options.inspection.templateRegistry.get(entry.templateId);
+        if (!template) {
+            enrichedEntries.push(entry);
+            continue;
+        }
+        const peers = options.inspection.templateRegistry
+            .list()
+            .filter((t) => t.id !== template.id)
+            .slice(0, 4);
+        const messages = buildEnrichmentMessages(template, peers, entry);
+        try {
+            const res = await options.provider.send({
+                messages,
+                maxTokens: options.maxTokensPerTemplate ?? 1024,
+            });
+            if (!res.ok) {
+                options.onPerTemplateError?.(entry.templateId, res.error);
+                enrichedEntries.push(entry);
+                continue;
+            }
+            const parsed = parseLlmFindings(res.value.content);
+            enrichedEntries.push({
+                ...entry,
+                llmFindings: parsed,
+            });
+        }
+        catch (e) {
+            options.onPerTemplateError?.(entry.templateId, e);
+            enrichedEntries.push(entry);
+        }
+    }
+    return {
+        ...report,
+        llmEnriched: true,
+        llmProviderId: options.provider.id,
+        templates: enrichedEntries,
+    };
+}
+function buildEnrichmentMessages(template, peers, entry) {
+    const system = {
+        role: AiMessageRole.System,
+        content: [
+            'You are a critic auditing a SharkCraft scaffold template for staleness, content quality, and silent drift from sibling templates.',
+            'You will receive: the template body, its declared variables, a sample target path, the deterministic findings already produced by `shrk templates lint` and `shrk templates drift`, and short summaries of up to four sibling templates.',
+            '',
+            'CRITICAL DISTINCTION — read carefully before flagging anything:',
+            '- You are auditing the TEMPLATE itself (the scaffold), NOT the domain it scaffolds. A template that generates a CLI command is fine even if "CLI commands" as a concept were deprecated; you would only flag the template if its OUTPUT is broken.',
+            '- "The template imports X" means a literal `import` statement is in the rendered body. Variable names, type-references via {{placeholders}}, and prose mentions in `description` are NOT imports — do not flag them as api-drift.',
+            '- "Naming convention drift" is real only when the template diverges from CONCRETE SIBLINGS. Re-describing a variable name (e.g. "uses `camel` instead of camelCase") is restating the schema, not a finding.',
+            '',
+            'STRICT silence bias: emit a finding only if a senior maintainer would change something on the strength of it. If the deterministic layer already caught it, do not restate. If you are extrapolating from peer summaries without direct evidence, suppress.',
+            '',
+            'Your job: surface issues the deterministic layer CANNOT see. Look explicitly for each of the following, in order:',
+            '  1. **api-drift**           — the template imports symbols, paths, or APIs that look outdated (renamed, removed, or replaced). Flag specific symbol/path names.',
+            '  2. **deprecated-pattern**  — the body uses syntax/idioms a maintainer would call out today (var, == comparisons, removed helpers, old framework APIs).',
+            '  3. **doc-content-mismatch**— the `description` and `postGenerationNotes` describe behavior the rendered `content` does not actually produce.',
+            '  4. **style-drift**         — the body diverges from sibling templates in naming, formatting, error handling, or registration ceremony.',
+            '  5. **missing-variable**    — sibling templates declare a variable this one omits, and the omission looks unintentional.',
+            '  6. **content-bug**         — the body contains a subtle bug (off-by-one, wrong return type, broken template literal, missing await) the deterministic layer would not catch.',
+            '  7. **stale-phrasing**      — `description`, variable descriptions, or `postGenerationNotes` reference a workflow / file / command that no longer exists or has been renamed.',
+            '  8. **other**               — only when none of the above categories fit.',
+            '',
+            'A finding is worth flagging only if it would change a maintainer\'s decision. Skip ceremonial nits.',
+            '',
+            'Return ONLY a JSON object with this exact shape, no preface, no markdown fences:',
+            '{',
+            '  "findings": [',
+            '    {',
+            '      "severity": "info" | "warn" | "error",',
+            '      "category": "api-drift" | "deprecated-pattern" | "doc-content-mismatch" | "style-drift" | "missing-variable" | "content-bug" | "stale-phrasing" | "other",',
+            '      "message": "<one sentence — name specific symbols, lines, or peers when possible>",',
+            '      "confidence": 0.0',
+            '    }',
+            '  ]',
+            '}',
+            'If nothing new is worth flagging, return {"findings": []}. Never invent variable names, file paths, or symbol names not present in the supplied template or peer summaries.',
+        ].join('\n'),
+    };
+    const body = typeof template.content === 'string'
+        ? (template.content)
+        : '(function body — not introspectable as a string)';
+    const sampleTarget = renderSampleTargetPath(template);
+    const user = {
+        role: AiMessageRole.User,
+        content: [
+            `# Template under audit`,
+            `id: ${template.id}`,
+            `name: ${template.name}`,
+            `description: ${template.description}`,
+            `tags: ${template.tags.join(', ') || '(none)'}`,
+            ``,
+            `## Declared variables`,
+            template.variables.length === 0
+                ? '(none)'
+                : template.variables
+                    .map((v) => `- ${v.name}${v.required ? ' (required)' : ''}${v.description ? ` — ${v.description}` : ''}`)
+                    .join('\n'),
+            ``,
+            `## Sample target path`,
+            sampleTarget ?? '(unable to render)',
+            ``,
+            `## Template body (truncated to ~4 KB)`,
+            '```',
+            truncate(body, 4096),
+            '```',
+            ``,
+            `## Deterministic findings already produced`,
+            entry.deterministicFindings.length === 0
+                ? '(none)'
+                : entry.deterministicFindings
+                    .map((f) => `- [${f.severity}] ${f.category}: ${f.message} (sources: ${f.sources.join(', ')})`)
+                    .join('\n'),
+            ``,
+            `## Sibling templates`,
+            peers.length === 0
+                ? '(no peers in this workspace)'
+                : peers
+                    .map((p) => {
+                    const vars = (p.variables ?? [])
+                        .map((v) => `${v.name}${v.required ? '!' : ''}`)
+                        .join(', ');
+                    return `- ${p.id} — ${p.name}\n  vars: ${vars || '(none)'}\n  tags: ${p.tags.join(', ') || '(none)'}`;
+                })
+                    .join('\n\n'),
+        ].join('\n'),
+    };
+    return [system, user];
+}
+function renderSampleTargetPath(template) {
+    const fn = template.targetPath;
+    if (typeof fn === 'string')
+        return fn;
+    if (typeof fn !== 'function')
+        return null;
+    const sample = { name: 'sample-feature' };
+    for (const v of template.variables ?? []) {
+        sample[v.name] = v.examples?.[0] ?? v.default ?? `sample-${v.name}`;
+    }
+    try {
+        const result = fn(sample);
+        return typeof result === 'string' ? result : null;
+    }
+    catch {
+        return null;
+    }
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max)}\n… [truncated ${s.length - max} chars]`;
+}
+function parseLlmFindings(raw) {
+    const trimmed = raw.trim();
+    let jsonText = trimmed;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced)
+        jsonText = fenced[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        const firstBrace = jsonText.indexOf('{');
+        const lastBrace = jsonText.lastIndexOf('}');
+        if (firstBrace < 0 || lastBrace <= firstBrace)
+            return [];
+        try {
+            parsed = JSON.parse(jsonText.slice(firstBrace, lastBrace + 1));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return [];
+    const list = parsed.findings;
+    if (!Array.isArray(list))
+        return [];
+    const out = [];
+    for (const item of list) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const severity = coerceSeverity(obj.severity);
+        const category = typeof obj.category === 'string' && obj.category.trim() ? obj.category : 'other';
+        const message = typeof obj.message === 'string' ? obj.message.trim() : '';
+        const confidence = typeof obj.confidence === 'number' && obj.confidence >= 0 && obj.confidence <= 1
+            ? obj.confidence
+            : 0.5;
+        if (!message)
+            continue;
+        out.push({ severity, category, message, confidence });
+    }
+    return out;
+}
+function coerceSeverity(value) {
+    if (value === 'error' || value === 'warn' || value === 'info')
+        return value;
+    if (value === 'warning')
+        return 'warn';
+    return 'info';
+}
+export const __internals = { parseLlmFindings, buildEnrichmentMessages };

package/dist/audit/templates-audit.d.ts

@@ -0,0 +1,63 @@
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IAiBlock } from '@shrkcrft/ai';
+export type AuditFindingSeverity = 'info' | 'warn' | 'error';
+export interface IAuditFinding {
+    severity: AuditFindingSeverity;
+    category: string;
+    message: string;
+    location?: string;
+    sources: readonly string[];
+    suggestion?: string;
+}
+export interface ILlmAuditFinding {
+    severity: AuditFindingSeverity;
+    category: string;
+    message: string;
+    confidence: number;
+}
+export type AuditVerdict = 'ok' | 'minor' | 'stale' | 'broken';
+export interface IAuditSuggestedAction {
+    kind: 'edit' | 'regenerate' | 'retire' | 'investigate';
+    target: string;
+    note: string;
+}
+export interface ITemplateAuditEntry {
+    templateId: string;
+    templateName: string;
+    verdict: AuditVerdict;
+    usage: 'unknown';
+    deterministicFindings: readonly IAuditFinding[];
+    llmFindings: readonly ILlmAuditFinding[];
+    suggestedActions: readonly IAuditSuggestedAction[];
+}
+export interface IAuditSkipped {
+    templateId: string;
+    reason: string;
+}
+export interface ITemplateAuditReport {
+    auditId: string;
+    generatedAt: string;
+    llmEnriched: boolean;
+    llmProviderId: string | null;
+    templates: readonly ITemplateAuditEntry[];
+    skipped: readonly IAuditSkipped[];
+    summary: {
+        ok: number;
+        minor: number;
+        stale: number;
+        broken: number;
+        total: number;
+    };
+    /**
+     * Configuration-state block populated by the command handler before
+     * the report is emitted. Always present — without LLM the block
+     * carries setup hints; with LLM it carries upgrade hints. Lets
+     * Claude self-configure shrk without external prompting.
+     */
+    ai?: IAiBlock;
+}
+export interface IBuildAuditOptions {
+    templateId?: string;
+}
+export declare function buildTemplateAudit(inspection: ISharkcraftInspection, options?: IBuildAuditOptions): ITemplateAuditReport;
+//# sourceMappingURL=templates-audit.d.ts.map

package/dist/audit/templates-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates-audit.d.ts","sourceRoot":"","sources":["../../src/audit/templates-audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,aAAa,CAAC;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,qBAAqB,EAAE,SAAS,aAAa,EAAE,CAAC;IAChD,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACzC,gBAAgB,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF;;;;;OAKG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,oBAAoB,CAyFtB"}

package/dist/audit/templates-audit.js

@@ -0,0 +1,171 @@
+import { buildTemplateDriftReport, lintTemplates, TemplateDriftStatus, } from '@shrkcrft/inspector';
+export function buildTemplateAudit(inspection, options = {}) {
+    const all = inspection.templateRegistry.list();
+    const userTemplates = all.filter((t) => (inspection.templateSources.get(t.id)?.type ?? 'local') === 'local');
+    const skipped = all
+        .filter((t) => !userTemplates.includes(t))
+        .map((t) => ({
+        templateId: t.id,
+        reason: 'pack-contributed (out of scope for v1 audit)',
+    }));
+    const targets = options.templateId
+        ? userTemplates.filter((t) => t.id === options.templateId)
+        : userTemplates;
+    const lint = lintTemplates(inspection, targets.map((t) => t.id));
+    const drift = buildTemplateDriftReport(inspection, options.templateId ? { templateId: options.templateId } : {});
+    const lintByTemplate = new Map();
+    for (const r of lint.results)
+        lintByTemplate.set(r.templateId, r);
+    const driftByTemplate = new Map();
+    for (const e of drift.entries)
+        driftByTemplate.set(e.templateId, e);
+    const entries = [];
+    for (const t of targets) {
+        const lintEntry = lintByTemplate.get(t.id);
+        const driftEntry = driftByTemplate.get(t.id);
+        const raw = [];
+        for (const i of lintEntry?.issues ?? []) {
+            raw.push({
+                severity: normaliseSeverity(i.severity),
+                category: i.code,
+                message: i.message,
+                sources: ['templates lint'],
+                ...(i.suggestion ? { suggestion: i.suggestion } : {}),
+            });
+        }
+        for (const i of driftEntry?.issues ?? []) {
+            raw.push({
+                severity: normaliseSeverity(i.severity),
+                category: i.code,
+                message: i.message,
+                sources: ['templates drift'],
+                ...(i.suggestedFix ? { suggestion: i.suggestedFix } : {}),
+            });
+        }
+        const deterministicFindings = dedupeFindings(raw);
+        entries.push({
+            templateId: t.id,
+            templateName: t.name,
+            verdict: deriveVerdict(deterministicFindings, driftEntry?.status ?? null),
+            usage: 'unknown',
+            deterministicFindings,
+            llmFindings: [],
+            suggestedActions: deriveSuggestedActions(t.id, deterministicFindings),
+        });
+    }
+    const summary = entries.reduce((acc, e) => {
+        acc[e.verdict] += 1;
+        acc.total += 1;
+        return acc;
+    }, { ok: 0, minor: 0, stale: 0, broken: 0, total: 0 });
+    const generatedAt = new Date().toISOString();
+    return {
+        auditId: `audit-${generatedAt.replace(/[:.]/g, '-')}`,
+        generatedAt,
+        llmEnriched: false,
+        llmProviderId: null,
+        templates: entries,
+        skipped,
+        summary,
+    };
+}
+function normaliseSeverity(s) {
+    if (s === 'error')
+        return 'error';
+    if (s === 'warning')
+        return 'warn';
+    return 'info';
+}
+function dedupeFindings(raw) {
+    const byKey = new Map();
+    for (const f of raw) {
+        const key = `${f.category}::${f.message}`;
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, { ...f, sources: [...f.sources] });
+            continue;
+        }
+        const mergedSources = Array.from(new Set([...existing.sources, ...f.sources]));
+        byKey.set(key, {
+            ...existing,
+            sources: mergedSources,
+            ...(existing.suggestion || f.suggestion
+                ? { suggestion: existing.suggestion ?? f.suggestion }
+                : {}),
+            severity: maxSeverity(existing.severity, f.severity),
+        });
+    }
+    return Array.from(byKey.values()).sort((a, b) => {
+        const order = { error: 0, warn: 1, info: 2 };
+        return order[a.severity] - order[b.severity] || a.category.localeCompare(b.category);
+    });
+}
+function maxSeverity(a, b) {
+    const rank = { info: 0, warn: 1, error: 2 };
+    return rank[a] >= rank[b] ? a : b;
+}
+function deriveVerdict(findings, driftStatus) {
+    if (findings.some((f) => f.severity === 'error'))
+        return 'broken';
+    if (driftStatus === TemplateDriftStatus.Fail)
+        return 'broken';
+    if (findings.some((f) => f.severity === 'warn'))
+        return 'stale';
+    if (driftStatus === TemplateDriftStatus.Warn)
+        return 'stale';
+    if (findings.some((f) => f.severity === 'info'))
+        return 'minor';
+    return 'ok';
+}
+function deriveSuggestedActions(templateId, findings) {
+    const actions = [];
+    const hasError = findings.some((f) => f.severity === 'error');
+    const hasWarn = findings.some((f) => f.severity === 'warn');
+    const undeclared = findings.find((f) => f.category === 'undeclared-var');
+    const unsafe = findings.find((f) => f.category === 'unsafe-target');
+    const noConvention = findings.find((f) => f.category === 'path-no-convention');
+    const missingName = findings.find((f) => f.category === 'missing-name');
+    if (unsafe) {
+        actions.push({
+            kind: 'edit',
+            target: templateId,
+            note: 'targetPath escapes project root — rewrite to a safe relative path under packages/.',
+        });
+    }
+    if (missingName) {
+        actions.push({
+            kind: 'edit',
+            target: templateId,
+            note: 'Template has no name — add a human-readable `name` field.',
+        });
+    }
+    if (undeclared) {
+        actions.push({
+            kind: 'edit',
+            target: templateId,
+            note: 'Placeholder is not declared in variables[] — declare it or remove the reference.',
+        });
+    }
+    if (noConvention) {
+        actions.push({
+            kind: 'investigate',
+            target: templateId,
+            note: 'Sample path does not match any registered path convention — confirm the targetPath fn aligns with paths.ts.',
+        });
+    }
+    if (hasError && actions.length === 0) {
+        actions.push({
+            kind: 'investigate',
+            target: templateId,
+            note: 'Template has error-level findings; review and fix before next generation.',
+        });
+    }
+    if (!hasError && hasWarn && actions.length === 0) {
+        actions.push({
+            kind: 'edit',
+            target: templateId,
+            note: 'Address warning-level findings to keep the template aligned with current conventions.',
+        });
+    }
+    return actions;
+}

package/dist/audit/templates-fix-plan-llm.d.ts

@@ -0,0 +1,19 @@
+import { type IAiMessage, type IAiProvider } from '@shrkcrft/ai';
+import type { ITemplateDefinition } from '@shrkcrft/templates';
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IFixInstruction, ITemplateFixPlan } from './templates-fix-plan.js';
+export interface IEnrichFixPlanOptions {
+    provider: IAiProvider;
+    inspection: ISharkcraftInspection;
+    maxTokensPerTemplate?: number;
+    onPerTemplateError?: (templateId: string, error: Error) => void;
+}
+export declare function enrichFixPlanWithLlm(plan: ITemplateFixPlan, options: IEnrichFixPlanOptions): Promise<ITemplateFixPlan>;
+declare function buildFixSuggestionMessages(template: ITemplateDefinition, fixes: readonly IFixInstruction[]): IAiMessage[];
+declare function parseSuggestionMap(raw: string): Map<string, string>;
+export declare const __internals: {
+    buildFixSuggestionMessages: typeof buildFixSuggestionMessages;
+    parseSuggestionMap: typeof parseSuggestionMap;
+};
+export {};
+//# sourceMappingURL=templates-fix-plan-llm.d.ts.map

package/dist/audit/templates-fix-plan-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates-fix-plan-llm.d.ts","sourceRoot":"","sources":["../../src/audit/templates-fix-plan-llm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEjF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,qBAAqB,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACjE;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CAuC3B;AAMD,iBAAS,0BAA0B,CACjC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,UAAU,EAAE,CAiFd;AAOD,iBAAS,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiC5D;AAED,eAAO,MAAM,WAAW;;;CAAqD,CAAC"}

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

@@ -0,0 +1,162 @@
+import { AiMessageRole } from '@shrkcrft/ai';
+export async function enrichFixPlanWithLlm(plan, options) {
+    const byTemplate = new Map();
+    for (const fix of plan.fixes) {
+        const list = byTemplate.get(fix.templateId) ?? [];
+        list.push(fix);
+        byTemplate.set(fix.templateId, list);
+    }
+    const enrichedFixes = [];
+    for (const [templateId, fixes] of byTemplate.entries()) {
+        const template = options.inspection.templateRegistry.get(templateId);
+        if (!template) {
+            enrichedFixes.push(...fixes);
+            continue;
+        }
+        try {
+            const messages = buildFixSuggestionMessages(template, fixes);
+            const res = await options.provider.send({
+                messages,
+                maxTokens: options.maxTokensPerTemplate ?? 1024,
+            });
+            if (!res.ok) {
+                options.onPerTemplateError?.(templateId, res.error);
+                enrichedFixes.push(...fixes);
+                continue;
+            }
+            const suggestions = parseSuggestionMap(res.value.content);
+            for (const fix of fixes) {
+                const key = suggestionKey(fix.findingCategory, fix.finding);
+                const suggestion = suggestions.get(key) ?? suggestions.get(fix.findingCategory) ?? null;
+                enrichedFixes.push(suggestion ? { ...fix, llmSuggestion: suggestion } : fix);
+            }
+        }
+        catch (e) {
+            options.onPerTemplateError?.(templateId, e);
+            enrichedFixes.push(...fixes);
+        }
+    }
+    return { ...plan, fixes: enrichedFixes };
+}
+function suggestionKey(category, finding) {
+    return `${category}::${finding.slice(0, 80)}`;
+}
+function buildFixSuggestionMessages(template, fixes) {
+    const body = typeof template.content === 'string'
+        ? (template.content)
+        : '(function body — not introspectable as a string)';
+    const targetPathSource = typeof template.targetPath === 'string'
+        ? `string: ${template.targetPath}`
+        : `function (signature only)`;
+    const system = {
+        role: AiMessageRole.System,
+        content: [
+            'You are a senior maintainer sharpening fix recommendations for a SharkCraft scaffold template.',
+            'For each finding listed, the deterministic layer has already produced a sound agent prompt with a generic placeholder (e.g. <sample value>, <TODO>).',
+            'Your job: replace those placeholders with a CONCRETE recommendation grounded in the supplied template body, variables, and target path.',
+            '',
+            'Per finding category, prefer to emit:',
+            '  - required-var-no-example   → a literal example value, in single quotes, matching any declared pattern and the variable\'s role.',
+            '  - undocumented-var          → a one-sentence description anchored in how the variable is used in the body.',
+            '  - undeclared-var            → either "ADD: <variable spec>" or "REMOVE: <placeholder>" with a one-line rationale.',
+            '  - related-id-unresolved     → confirm removal; if a near-match exists in supplied context, name it.',
+            '  - path-no-convention        → either "ADD paths.ts entry: <pattern>" or "CHANGE template targetPath: <pattern>", whichever is less intrusive.',
+            '  - missing-name              → a short, descriptive name.',
+            '  - missing-description       → a one-sentence description of what the template scaffolds.',
+            '  - any other category        → a one-sentence concrete suggestion.',
+            '',
+            'Return ONLY a JSON object with this exact shape, no preface, no fences:',
+            '{',
+            '  "suggestions": [',
+            '    {',
+            '      "findingCategory": "<exact category>",',
+            '      "finding": "<first 80 chars of the original finding message>",',
+            '      "suggestion": "<one to three sentences, concrete>"',
+            '    }',
+            '  ]',
+            '}',
+            'Omit entries you cannot meaningfully sharpen — better silence than ceremony.',
+        ].join('\n'),
+    };
+    const user = {
+        role: AiMessageRole.User,
+        content: [
+            `# Template: ${template.id}`,
+            `name: ${template.name}`,
+            `description: ${template.description}`,
+            `tags: ${template.tags.join(', ') || '(none)'}`,
+            ``,
+            `## Declared variables`,
+            template.variables.length === 0
+                ? '(none)'
+                : template.variables
+                    .map((v) => `- ${v.name}${v.required ? ' (required)' : ''}` +
+                    (v.pattern ? `  pattern=${v.pattern.source}` : '') +
+                    (v.examples?.length ? `  examples=[${v.examples.join(', ')}]` : '') +
+                    (v.description ? `\n    ${v.description}` : ''))
+                    .join('\n'),
+            ``,
+            `## targetPath`,
+            targetPathSource,
+            ``,
+            `## Template body (truncated to ~3 KB)`,
+            '```',
+            truncate(body, 3072),
+            '```',
+            ``,
+            `## Fixes needing sharpening`,
+            fixes
+                .map((f, i) => `### Fix ${i + 1}: ${f.findingCategory}\nfinding: ${f.finding}\ncurrent agent prompt:\n${f.agentPrompt}`)
+                .join('\n\n'),
+        ].join('\n'),
+    };
+    return [system, user];
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max)}\n… [truncated ${s.length - max} chars]`;
+}
+function parseSuggestionMap(raw) {
+    const out = new Map();
+    const trimmed = raw.trim();
+    let jsonText = trimmed;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced)
+        jsonText = fenced[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        const firstBrace = jsonText.indexOf('{');
+        const lastBrace = jsonText.lastIndexOf('}');
+        if (firstBrace < 0 || lastBrace <= firstBrace)
+            return out;
+        try {
+            parsed = JSON.parse(jsonText.slice(firstBrace, lastBrace + 1));
+        }
+        catch {
+            return out;
+        }
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return out;
+    const list = parsed.suggestions;
+    if (!Array.isArray(list))
+        return out;
+    for (const item of list) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const category = typeof obj.findingCategory === 'string' ? obj.findingCategory.trim() : '';
+        const finding = typeof obj.finding === 'string' ? obj.finding.trim() : '';
+        const suggestion = typeof obj.suggestion === 'string' ? obj.suggestion.trim() : '';
+        if (!category || !suggestion)
+            continue;
+        const key = finding ? suggestionKey(category, finding) : category;
+        out.set(key, suggestion);
+    }
+    return out;
+}
+export const __internals = { buildFixSuggestionMessages, parseSuggestionMap };

package/dist/audit/templates-fix-plan.d.ts

@@ -0,0 +1,37 @@
+import type { AuditFindingSeverity, ITemplateAuditReport } from './templates-audit.js';
+export type FixConfidence = 'high' | 'medium' | 'low';
+export interface IFixInstruction {
+    templateId: string;
+    findingCategory: string;
+    finding: string;
+    severity: AuditFindingSeverity;
+    intent: string;
+    agentPrompt: string;
+    confidence: FixConfidence;
+    source: 'deterministic' | 'llm';
+    /** Concrete suggestion attached by the LLM-enrichment pass when reachable. Advisory. */
+    llmSuggestion?: string;
+}
+export interface ISkippedFinding {
+    templateId: string;
+    findingCategory: string;
+    finding: string;
+    reason: string;
+}
+export interface ITemplateFixPlan {
+    fixPlanId: string;
+    generatedAt: string;
+    auditId: string;
+    sourceFiles: readonly string[];
+    fixes: readonly IFixInstruction[];
+    skipped: readonly ISkippedFinding[];
+    summary: {
+        fixCount: number;
+        highConfidence: number;
+        mediumConfidence: number;
+        lowConfidence: number;
+        skipped: number;
+    };
+}
+export declare function buildFixPlan(report: ITemplateAuditReport): ITemplateFixPlan;
+//# sourceMappingURL=templates-fix-plan.d.ts.map

package/dist/audit/templates-fix-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates-fix-plan.d.ts","sourceRoot":"","sources":["../../src/audit/templates-fix-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAIpB,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,aAAa,CAAC;IAC1B,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC;IAChC,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAID,wBAAgB,YAAY,CAAC,MAAM,EAAE,oBAAoB,GAAG,gBAAgB,CAiC3E"}