@shrkcrft/inspector 0.1.0-alpha.2

package/dist/execution-graph.js

@@ -0,0 +1,484 @@
+/**
+ * Task execution graph.
+ *
+ * Combine intent, risk, memory (when present), contract, constructs,
+ * policies, boundaries, playbooks, templates, plans, gates, validations,
+ * and reports into a structured graph (nodes + edges). Pure data — no
+ * execution, no writes.
+ */
+import { buildAgentContract, } from "./agent-contract.js";
+import { loadRepositoryMemory, memoryRiskForTask } from "./repo-memory.js";
+import { classifyChangeIntent } from "./change-intent.js";
+import { buildTaskRiskReport } from "./task-risk.js";
+export const EXECUTION_GRAPH_SCHEMA = 'sharkcraft.execution-graph/v1';
+export var ExecutionNodeKind;
+(function (ExecutionNodeKind) {
+    ExecutionNodeKind["Task"] = "task";
+    ExecutionNodeKind["Intent"] = "intent";
+    ExecutionNodeKind["Risk"] = "risk";
+    ExecutionNodeKind["Memory"] = "memory";
+    ExecutionNodeKind["Contract"] = "contract";
+    ExecutionNodeKind["Construct"] = "construct";
+    ExecutionNodeKind["Policy"] = "policy";
+    ExecutionNodeKind["Boundary"] = "boundary";
+    ExecutionNodeKind["Playbook"] = "playbook";
+    ExecutionNodeKind["Template"] = "template";
+    ExecutionNodeKind["Plan"] = "plan";
+    ExecutionNodeKind["ReviewGate"] = "review-gate";
+    ExecutionNodeKind["HumanApproval"] = "human-approval";
+    ExecutionNodeKind["Validation"] = "validation";
+    ExecutionNodeKind["ReportArtifact"] = "report-artifact";
+    ExecutionNodeKind["Done"] = "done";
+})(ExecutionNodeKind || (ExecutionNodeKind = {}));
+export var ExecutionEdgeKind;
+(function (ExecutionEdgeKind) {
+    ExecutionEdgeKind["Requires"] = "requires";
+    ExecutionEdgeKind["Informs"] = "informs";
+    ExecutionEdgeKind["Blocks"] = "blocks";
+    ExecutionEdgeKind["Validates"] = "validates";
+    ExecutionEdgeKind["Produces"] = "produces";
+    ExecutionEdgeKind["Reviews"] = "reviews";
+    ExecutionEdgeKind["Forbids"] = "forbids";
+    ExecutionEdgeKind["Recommends"] = "recommends";
+})(ExecutionEdgeKind || (ExecutionEdgeKind = {}));
+function n(id, kind, label, detail) {
+    return detail === undefined ? { id, kind, label } : { id, kind, label, detail };
+}
+function e(from, to, kind, detail) {
+    return detail === undefined ? { from, to, kind } : { from, to, kind, detail };
+}
+export async function buildTaskExecutionGraph(task, inspection, options = {}) {
+    const trimmed = (task || '').trim();
+    const intent = await classifyChangeIntent(trimmed, inspection);
+    const risk = await buildTaskRiskReport(trimmed, inspection, {
+        ...(options.files ? { files: options.files } : {}),
+        ...(options.since ? { since: options.since } : {}),
+        ...(options.staged ? { staged: true } : {}),
+        includeMemory: true,
+    });
+    const contract = await buildAgentContract(trimmed, inspection, {
+        ...(options.role ? { role: options.role } : {}),
+        ...(options.mode ? { mode: options.mode } : {}),
+        ...(options.files ? { files: options.files } : {}),
+        ...(options.since ? { since: options.since } : {}),
+        ...(options.staged ? { staged: true } : {}),
+    });
+    const memoryIndex = loadRepositoryMemory(inspection.projectRoot);
+    const memoryRisk = memoryIndex ? memoryRiskForTask(memoryIndex, trimmed) : undefined;
+    const nodes = [];
+    const edges = [];
+    nodes.push(n('task', ExecutionNodeKind.Task, `Task: ${trimmed || '(empty)'}`));
+    nodes.push(n('intent', ExecutionNodeKind.Intent, `Intent: ${intent.kind}`, intent.suggestedFirstCommand));
+    nodes.push(n('risk', ExecutionNodeKind.Risk, `Risk: ${risk.riskLevel} (score ${risk.score})`));
+    if (memoryRisk) {
+        nodes.push(n('memory', ExecutionNodeKind.Memory, `Memory: ${memoryRisk.recommendation}`));
+    }
+    nodes.push(n('contract', ExecutionNodeKind.Contract, `Contract: ${contract.role}/${contract.mode}`));
+    edges.push(e('task', 'intent', ExecutionEdgeKind.Informs));
+    edges.push(e('task', 'risk', ExecutionEdgeKind.Informs));
+    if (memoryRisk)
+        edges.push(e('task', 'memory', ExecutionEdgeKind.Informs));
+    edges.push(e('intent', 'contract', ExecutionEdgeKind.Informs));
+    edges.push(e('risk', 'contract', ExecutionEdgeKind.Informs));
+    if (memoryRisk)
+        edges.push(e('memory', 'contract', ExecutionEdgeKind.Informs));
+    // Constructs
+    for (const c of contract.relevantConstructs.slice(0, 8)) {
+        const id = `construct:${c}`;
+        nodes.push(n(id, ExecutionNodeKind.Construct, c));
+        edges.push(e('contract', id, ExecutionEdgeKind.Informs));
+    }
+    // Policies / boundaries
+    for (const p of contract.relevantPolicies.slice(0, 5)) {
+        const id = `policy:${p.slice(0, 60)}`;
+        nodes.push(n(id, ExecutionNodeKind.Policy, p));
+        edges.push(e('contract', id, ExecutionEdgeKind.Reviews));
+    }
+    for (const b of contract.relevantBoundaries.slice(0, 5)) {
+        const id = `boundary:${b.slice(0, 60)}`;
+        nodes.push(n(id, ExecutionNodeKind.Boundary, b));
+        edges.push(e('contract', id, ExecutionEdgeKind.Reviews));
+    }
+    // Playbooks
+    for (const p of contract.relevantPlaybooks.slice(0, 5)) {
+        const id = `playbook:${p}`;
+        nodes.push(n(id, ExecutionNodeKind.Playbook, p));
+        edges.push(e('contract', id, ExecutionEdgeKind.Recommends));
+    }
+    // Templates
+    for (const t of contract.relevantTemplates.slice(0, 5)) {
+        const id = `template:${t}`;
+        nodes.push(n(id, ExecutionNodeKind.Template, t));
+        edges.push(e('contract', id, ExecutionEdgeKind.Produces));
+    }
+    // Plans
+    for (const planReview of contract.requiredPlanReviews) {
+        const id = `plan:${planReview.slice(0, 60)}`;
+        nodes.push(n(id, ExecutionNodeKind.Plan, planReview));
+        edges.push(e('contract', id, ExecutionEdgeKind.Requires));
+    }
+    // Review gates
+    for (const r of contract.requiredReviews) {
+        const id = `review:${r.slice(0, 60)}`;
+        nodes.push(n(id, ExecutionNodeKind.ReviewGate, r));
+        edges.push(e('contract', id, ExecutionEdgeKind.Requires));
+    }
+    // Human approval
+    if (contract.humanApprovalGates.length > 0) {
+        nodes.push(n('human-approval', ExecutionNodeKind.HumanApproval, 'Human approval gate', contract.humanApprovalGates.join(' / ')));
+        edges.push(e('contract', 'human-approval', ExecutionEdgeKind.Requires));
+    }
+    // Validations
+    for (const v of contract.requiredValidations) {
+        const id = `validation:${v.slice(0, 60)}`;
+        nodes.push(n(id, ExecutionNodeKind.Validation, v));
+        edges.push(e('contract', id, ExecutionEdgeKind.Validates));
+    }
+    // Report artefacts
+    const artefacts = [];
+    artefacts.push('brief');
+    artefacts.push('risk');
+    if (contract.requiredPlanReviews.length)
+        artefacts.push('plan simulation');
+    artefacts.push('validation report');
+    for (const a of artefacts) {
+        const id = `report:${a}`;
+        nodes.push(n(id, ExecutionNodeKind.ReportArtifact, a));
+        edges.push(e('contract', id, ExecutionEdgeKind.Produces));
+    }
+    // Done
+    nodes.push(n('done', ExecutionNodeKind.Done, 'Definition of done', contract.definitionOfDone.join(' / ')));
+    // Edges from each validation/approval to done.
+    for (const v of contract.requiredValidations)
+        edges.push(e(`validation:${v.slice(0, 60)}`, 'done', ExecutionEdgeKind.Validates));
+    if (contract.humanApprovalGates.length > 0)
+        edges.push(e('human-approval', 'done', ExecutionEdgeKind.Validates));
+    // Forbids edges from contract to each forbidden command.
+    for (const f of contract.forbiddenCommands.slice(0, 5)) {
+        const id = `forbid:${f.slice(0, 60)}`;
+        nodes.push(n(id, ExecutionNodeKind.Validation, f));
+        edges.push(e('contract', id, ExecutionEdgeKind.Forbids));
+    }
+    // Blocks: if risk requires approval, contract blocks done until approval.
+    if (contract.taskRisk.humanApprovalRequired) {
+        edges.push(e('human-approval', 'done', ExecutionEdgeKind.Requires));
+    }
+    return {
+        schema: EXECUTION_GRAPH_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        task: trimmed,
+        role: contract.role,
+        mode: contract.mode,
+        intent,
+        taskRisk: risk,
+        contract,
+        ...(memoryRisk ? { memoryRisk } : {}),
+        nodes,
+        edges,
+        notes: [
+            'Read-only. No execution, no writes.',
+            'Nodes are derived from the agent contract; edges are deterministic.',
+        ],
+    };
+}
+export function renderExecutionGraphText(g) {
+    let out = `=== Task execution graph ===\n`;
+    out += `  task    ${g.task || '(empty)'}\n`;
+    out += `  role    ${g.role}\n`;
+    out += `  mode    ${g.mode}\n`;
+    out += `  intent  ${g.intent.kind}\n`;
+    out += `  risk    ${g.taskRisk.riskLevel}\n`;
+    out += `  nodes   ${g.nodes.length}\n`;
+    out += `  edges   ${g.edges.length}\n\n`;
+    out += `Nodes:\n`;
+    for (const n0 of g.nodes)
+        out += `  [${n0.kind}] ${n0.id}  ${n0.label}\n`;
+    out += `\nEdges:\n`;
+    for (const e0 of g.edges)
+        out += `  ${e0.from} --${e0.kind}--> ${e0.to}\n`;
+    return out;
+}
+export function renderExecutionGraphMarkdown(g) {
+    let out = `# Task execution graph\n\n`;
+    out += `- **task**: ${g.task || '(empty)'}\n`;
+    out += `- **role**: ${g.role}\n`;
+    out += `- **mode**: ${g.mode}\n`;
+    out += `- **intent**: ${g.intent.kind}\n`;
+    out += `- **risk**: ${g.taskRisk.riskLevel}\n`;
+    out += `- **nodes**: ${g.nodes.length} / **edges**: ${g.edges.length}\n\n`;
+    out += `## Nodes\n\n`;
+    for (const n0 of g.nodes)
+        out += `- \`${n0.id}\` (${n0.kind}) — ${n0.label}\n`;
+    out += `\n## Edges\n\n`;
+    for (const e0 of g.edges)
+        out += `- \`${e0.from}\` —${e0.kind}→ \`${e0.to}\`\n`;
+    return out + '\n';
+}
+function mermaidLabel(label) {
+    // Escape pipe and quotes; keep things one-line.
+    return label.replace(/"/g, '\\"').replace(/\|/g, '/').replace(/[\r\n]+/g, ' ');
+}
+function mermaidId(id) {
+    return id.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+export function renderExecutionGraphMermaid(g) {
+    let out = `flowchart TD\n`;
+    for (const node of g.nodes) {
+        out += `  ${mermaidId(node.id)}["${mermaidLabel(`${node.label} [${node.kind}]`)}"]\n`;
+    }
+    for (const edge of g.edges) {
+        out += `  ${mermaidId(edge.from)} -->|${mermaidLabel(edge.kind)}| ${mermaidId(edge.to)}\n`;
+    }
+    return out;
+}
+function dotEscape(s) {
+    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/[\r\n]+/g, ' ');
+}
+function dotId(id) {
+    return id.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+export function renderExecutionGraphDot(g) {
+    let out = `digraph TaskExecutionGraph {\n`;
+    out += `  rankdir=TB;\n`;
+    out += `  node [shape=box, fontname="Helvetica"];\n`;
+    for (const node of g.nodes) {
+        out += `  ${dotId(node.id)} [label="${dotEscape(node.label)}\\n[${node.kind}]"];\n`;
+    }
+    for (const edge of g.edges) {
+        out += `  ${dotId(edge.from)} -> ${dotId(edge.to)} [label="${dotEscape(edge.kind)}"];\n`;
+    }
+    out += `}\n`;
+    return out;
+}
+const CLUSTER_INTENT_RISK = [
+    ExecutionNodeKind.Task,
+    ExecutionNodeKind.Intent,
+    ExecutionNodeKind.Risk,
+    ExecutionNodeKind.Memory,
+];
+const CLUSTER_CONTRACT_GATES = [
+    ExecutionNodeKind.Contract,
+    ExecutionNodeKind.ReviewGate,
+    ExecutionNodeKind.HumanApproval,
+];
+const CLUSTER_CONSTRUCTS_POLICIES = [
+    ExecutionNodeKind.Construct,
+    ExecutionNodeKind.Policy,
+    ExecutionNodeKind.Boundary,
+    ExecutionNodeKind.Playbook,
+    ExecutionNodeKind.Template,
+];
+const CLUSTER_PLANS = [ExecutionNodeKind.Plan];
+const CLUSTER_VALIDATION = [
+    ExecutionNodeKind.Validation,
+    ExecutionNodeKind.ReportArtifact,
+];
+const CLUSTER_DONE = [ExecutionNodeKind.Done];
+const CLUSTERS = [
+    {
+        id: 'cluster_intent_risk',
+        kinds: CLUSTER_INTENT_RISK,
+        style: { label: 'Intent · Risk · Memory', color: '#1f77b4', fillColor: '#dbeafe', shape: 'box' },
+    },
+    {
+        id: 'cluster_contract_gates',
+        kinds: CLUSTER_CONTRACT_GATES,
+        style: { label: 'Contract · Gates', color: '#9467bd', fillColor: '#ede9fe', shape: 'hexagon' },
+    },
+    {
+        id: 'cluster_constructs_policies',
+        kinds: CLUSTER_CONSTRUCTS_POLICIES,
+        style: { label: 'Constructs · Policies · Boundaries', color: '#2ca02c', fillColor: '#dcfce7', shape: 'box' },
+    },
+    {
+        id: 'cluster_plans',
+        kinds: CLUSTER_PLANS,
+        style: { label: 'Plans · Simulation', color: '#ff7f0e', fillColor: '#ffedd5', shape: 'note' },
+    },
+    {
+        id: 'cluster_validation',
+        kinds: CLUSTER_VALIDATION,
+        style: { label: 'Validation · Reports', color: '#17becf', fillColor: '#cffafe', shape: 'oval' },
+    },
+    {
+        id: 'cluster_done',
+        kinds: CLUSTER_DONE,
+        style: { label: 'Done', color: '#d62728', fillColor: '#fee2e2', shape: 'doublecircle' },
+    },
+];
+function clusterFor(kind) {
+    return CLUSTERS.find((c) => c.kinds.includes(kind)) ?? null;
+}
+export function renderExecutionGraphClusteredDot(g) {
+    let out = `digraph TaskExecutionGraph {\n`;
+    out += `  rankdir=TB;\n`;
+    out += `  compound=true;\n`;
+    out += `  node [fontname="Helvetica"];\n`;
+    out += `  edge [fontname="Helvetica"];\n\n`;
+    // Index nodes by cluster.
+    const byCluster = new Map();
+    const unclustered = [];
+    for (const node of g.nodes) {
+        const c = clusterFor(node.kind);
+        if (!c) {
+            unclustered.push(node);
+            continue;
+        }
+        if (!byCluster.has(c.id))
+            byCluster.set(c.id, []);
+        byCluster.get(c.id).push(node);
+    }
+    for (const cluster of CLUSTERS) {
+        const nodes = byCluster.get(cluster.id);
+        if (!nodes || nodes.length === 0)
+            continue;
+        out += `  subgraph ${cluster.id} {\n`;
+        out += `    label="${dotEscape(cluster.style.label)}";\n`;
+        out += `    style="rounded,filled";\n`;
+        out += `    fillcolor="${cluster.style.fillColor}";\n`;
+        out += `    color="${cluster.style.color}";\n`;
+        out += `    node [shape=${cluster.style.shape}, color="${cluster.style.color}", style=filled, fillcolor="white"];\n`;
+        for (const node of nodes) {
+            out += `    ${dotId(node.id)} [label="${dotEscape(node.label)}\\n[${node.kind}]"];\n`;
+        }
+        out += `  }\n\n`;
+    }
+    if (unclustered.length > 0) {
+        out += `  subgraph cluster_other {\n`;
+        out += `    label="Other";\n`;
+        out += `    style="rounded,dashed";\n`;
+        for (const node of unclustered) {
+            out += `    ${dotId(node.id)} [label="${dotEscape(node.label)}\\n[${node.kind}]", shape=box];\n`;
+        }
+        out += `  }\n\n`;
+    }
+    for (const edge of g.edges) {
+        out += `  ${dotId(edge.from)} -> ${dotId(edge.to)} [label="${dotEscape(edge.kind)}"];\n`;
+    }
+    out += `}\n`;
+    return out;
+}
+/**
+ * Query syntax (lowercased token before ':'):
+ *  - blocks:<nodeId>       → nodes/edges blocking the named node
+ *  - kind:<kind>           → nodes of that kind
+ *  - edge:<kind>           → edges of that kind
+ *  - text:<substring>      → nodes whose id/label/detail contains substring
+ */
+export function queryExecutionGraph(graph, query) {
+    const q = (query ?? '').trim();
+    const notes = [];
+    if (!q) {
+        return {
+            schema: EXECUTION_GRAPH_SCHEMA,
+            query: q,
+            matchedNodes: [],
+            matchedEdges: [],
+            notes: ['Empty query.'],
+        };
+    }
+    const colon = q.indexOf(':');
+    if (colon < 0) {
+        return {
+            schema: EXECUTION_GRAPH_SCHEMA,
+            query: q,
+            matchedNodes: [],
+            matchedEdges: [],
+            notes: ['Query must use the form `<filter>:<value>` (e.g. `blocks:done`, `kind:human-approval`).'],
+        };
+    }
+    const filter = q.slice(0, colon).toLowerCase();
+    const value = q.slice(colon + 1).trim();
+    const matchedNodes = [];
+    const matchedEdges = [];
+    switch (filter) {
+        case 'blocks': {
+            const targetId = value;
+            // Edges whose `to` is the target with kind requires/blocks (or whose
+            // `from` is the target with kind blocks). We surface all reachable
+            // upstream gating nodes.
+            const upstream = new Set();
+            const queue = [targetId];
+            while (queue.length > 0) {
+                const cur = queue.shift();
+                for (const e of graph.edges) {
+                    if (e.to !== cur)
+                        continue;
+                    if (e.kind === ExecutionEdgeKind.Requires ||
+                        e.kind === ExecutionEdgeKind.Blocks ||
+                        e.kind === ExecutionEdgeKind.Validates) {
+                        matchedEdges.push(e);
+                        if (!upstream.has(e.from)) {
+                            upstream.add(e.from);
+                            queue.push(e.from);
+                        }
+                    }
+                }
+            }
+            for (const id of upstream) {
+                const node = graph.nodes.find((n) => n.id === id);
+                if (node)
+                    matchedNodes.push(node);
+            }
+            if (matchedNodes.length === 0)
+                notes.push(`No nodes block ${targetId}.`);
+            break;
+        }
+        case 'kind': {
+            for (const n of graph.nodes)
+                if (n.kind.toLowerCase() === value.toLowerCase())
+                    matchedNodes.push(n);
+            if (matchedNodes.length === 0)
+                notes.push(`No nodes of kind ${value}.`);
+            break;
+        }
+        case 'edge': {
+            for (const e of graph.edges)
+                if (e.kind.toLowerCase() === value.toLowerCase())
+                    matchedEdges.push(e);
+            if (matchedEdges.length === 0)
+                notes.push(`No edges of kind ${value}.`);
+            break;
+        }
+        case 'text': {
+            const lv = value.toLowerCase();
+            for (const n of graph.nodes) {
+                const blob = `${n.id} ${n.label} ${n.detail ?? ''}`.toLowerCase();
+                if (blob.includes(lv))
+                    matchedNodes.push(n);
+            }
+            if (matchedNodes.length === 0)
+                notes.push(`No node text matches "${value}".`);
+            break;
+        }
+        default: {
+            notes.push(`Unknown filter "${filter}". Try: blocks, kind, edge, text.`);
+            break;
+        }
+    }
+    return {
+        schema: EXECUTION_GRAPH_SCHEMA,
+        query: q,
+        matchedNodes,
+        matchedEdges,
+        notes,
+    };
+}
+function htmlEscape(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+export function renderExecutionGraphHtml(g) {
+    const mermaid = renderExecutionGraphMermaid(g);
+    // No JS — just pre-formatted mermaid source. Render with any local renderer
+    // that supports this. This file is safe to open in a browser.
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Task execution graph</title></head><body>
+<h1>Task execution graph</h1>
+<pre><code class="language-mermaid">${htmlEscape(mermaid)}</code></pre>
+</body></html>
+`;
+}

package/dist/export-bundle.d.ts

@@ -0,0 +1,10 @@
+export interface IExportResult {
+    outputDir: string;
+    files: readonly string[];
+    format: 'folder';
+}
+export declare function exportFeatureBundle(cwd: string, bundleId: string, outputDir: string): IExportResult | null;
+export declare function exportDevSession(cwd: string, sessionId: string, outputDir: string): IExportResult | null;
+export declare function exportQuality(cwd: string, outputDir: string, report: unknown): IExportResult;
+export declare function exportReview(cwd: string, packetFile: string, outputDir: string): IExportResult | null;
+//# sourceMappingURL=export-bundle.d.ts.map

package/dist/export-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-bundle.d.ts","sourceRoot":"","sources":["../src/export-bundle.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,QAAQ,CAAC;CAClB;AA8BD,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,aAAa,GAAG,IAAI,CAetB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,aAAa,GAAG,IAAI,CAetB;AAED,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,GACd,aAAa,CAMf;AAED,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,aAAa,GAAG,IAAI,CActB"}

package/dist/export-bundle.js

@@ -0,0 +1,90 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+import { getBundleDir, readFeatureBundle } from "./feature-bundle.js";
+import { getDevSessionDir, readDevSessionState } from "./dev-session.js";
+function copyDir(src, dest) {
+    const out = [];
+    if (!existsSync(src))
+        return out;
+    mkdirSync(dest, { recursive: true });
+    for (const e of readdirSync(src)) {
+        const s = nodePath.join(src, e);
+        const d = nodePath.join(dest, e);
+        let st;
+        try {
+            st = statSync(s);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            out.push(...copyDir(s, d));
+        else if (st.isFile()) {
+            copyFileSync(s, d);
+            out.push(d);
+        }
+    }
+    return out;
+}
+function writeSummary(dir, title, body) {
+    const file = nodePath.join(dir, 'summary.md');
+    writeFileSync(file, `# ${title}\n\n${body}\n`, 'utf8');
+    return file;
+}
+export function exportFeatureBundle(cwd, bundleId, outputDir) {
+    const bundle = readFeatureBundle(cwd, bundleId);
+    if (!bundle)
+        return null;
+    mkdirSync(outputDir, { recursive: true });
+    const files = [];
+    const src = getBundleDir(cwd, bundleId);
+    files.push(...copyDir(src, outputDir));
+    files.push(writeSummary(outputDir, `Feature bundle: ${bundle.task}`, buildBundleSummary(bundle)));
+    return { outputDir, files, format: 'folder' };
+}
+export function exportDevSession(cwd, sessionId, outputDir) {
+    const session = readDevSessionState(cwd, sessionId);
+    if (!session)
+        return null;
+    mkdirSync(outputDir, { recursive: true });
+    const files = [];
+    const src = getDevSessionDir(cwd, sessionId);
+    files.push(...copyDir(src, outputDir));
+    files.push(writeSummary(outputDir, `Dev session: ${session.task}`, `Phase: ${session.phase}\n\nPlans: ${session.plans.length}\nValidations: ${session.validations.length}\n`));
+    return { outputDir, files, format: 'folder' };
+}
+export function exportQuality(cwd, outputDir, report) {
+    mkdirSync(outputDir, { recursive: true });
+    const file = nodePath.join(outputDir, 'quality.json');
+    writeFileSync(file, JSON.stringify(report, null, 2) + '\n', 'utf8');
+    const sum = writeSummary(outputDir, 'Quality export', 'See quality.json');
+    return { outputDir, files: [file, sum], format: 'folder' };
+}
+export function exportReview(cwd, packetFile, outputDir) {
+    if (!existsSync(packetFile))
+        return null;
+    mkdirSync(outputDir, { recursive: true });
+    const destPacket = nodePath.join(outputDir, 'review-packet.json');
+    copyFileSync(packetFile, destPacket);
+    let body = 'See review-packet.json';
+    try {
+        const parsed = JSON.parse(readFileSync(packetFile, 'utf8'));
+        body = `Changed files: ${parsed.changedFiles?.length ?? 0}\n`;
+    }
+    catch {
+        /* ignore */
+    }
+    const sum = writeSummary(outputDir, 'Review packet export', body);
+    return { outputDir, files: [destPacket, sum], format: 'folder' };
+}
+function buildBundleSummary(bundle) {
+    return [
+        `Status: ${bundle.status}`,
+        `Plans: ${bundle.plans.length}`,
+        `Risk: ${bundle.riskLevel}`,
+        `Next: ${bundle.nextAction ?? '(none)'}`,
+        '',
+        `Affected areas:`,
+        ...(bundle.affectedAreas.map((a) => `- ${a}`)),
+    ].join('\n');
+}

package/dist/failure-diagnostics.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Failure diagnostics.
+ *
+ * Common error surfaces should not just say "X failed" — they should say
+ * "X failed, probable cause is Y, try Z next". This module is a curated set
+ * of diagnostic helpers callers can use to enrich the human-facing message
+ * without re-implementing the dispatch in every command.
+ *
+ * Pure data — no I/O, no shell calls, no writes. Safe to call from MCP.
+ */
+export declare const FAILURE_DIAGNOSTIC_SCHEMA = "sharkcraft.failure-diagnostic/v1";
+export type FailureDiagnosticCode = 'missing-sharkcraft-config' | 'missing-node-modules' | 'pack-helper-missing' | 'mcp-cache-miss' | 'adoption-checkpoint-stale' | 'unknown-command' | 'missing-template-variables' | 'unsafe-path-refused' | 'failed-verification' | 'release-readiness-blocker' | 'plan-signature-mismatch' | 'workflow-file-not-found' | 'java-cannot-find-symbol' | 'java-package-does-not-exist' | 'csharp-cs0246' | 'csharp-nu1101' | 'python-module-not-found' | 'python-pytest-collection-error' | 'go-cannot-find-module' | 'go-import-cycle' | 'rust-e0432' | 'rust-e0308';
+export interface IFailureDiagnostic {
+    schema: typeof FAILURE_DIAGNOSTIC_SCHEMA;
+    code: FailureDiagnosticCode;
+    problem: string;
+    likelyCause: string;
+    nextCommand: string;
+    docsLink?: string;
+    extra?: Record<string, unknown>;
+}
+export declare function diagnoseMissingSharkcraftConfig(projectRoot: string): IFailureDiagnostic;
+export declare function diagnoseMissingNodeModules(): IFailureDiagnostic;
+export declare function diagnosePackHelperMissing(symbol: string, packName: string): IFailureDiagnostic;
+export declare function diagnoseMcpCacheMiss(briefId: string): IFailureDiagnostic;
+export declare function diagnoseAdoptionCheckpointStale(reason: string): IFailureDiagnostic;
+export declare function diagnoseUnknownCommand(command: string, suggestions: readonly string[]): IFailureDiagnostic;
+export declare function diagnoseMissingTemplateVariables(templateId: string, missing: readonly string[]): IFailureDiagnostic;
+export declare function diagnoseUnsafePathRefused(target: string): IFailureDiagnostic;
+export declare function diagnoseFailedVerification(verificationId: string, exitCode: number): IFailureDiagnostic;
+export declare function diagnoseReleaseReadinessBlocker(blockerId: string, message: string): IFailureDiagnostic;
+export declare function diagnosePlanSignatureMismatch(planFile: string): IFailureDiagnostic;
+export declare function diagnoseWorkflowFileNotFound(file: string): IFailureDiagnostic;
+export declare function diagnoseJavaCannotFindSymbol(symbol: string): IFailureDiagnostic;
+export declare function diagnoseJavaPackageDoesNotExist(pkg: string): IFailureDiagnostic;
+export declare function diagnoseCSharpCs0246(typeName: string): IFailureDiagnostic;
+export declare function diagnoseCSharpNu1101(packageName: string): IFailureDiagnostic;
+export declare function diagnosePythonModuleNotFound(moduleName: string): IFailureDiagnostic;
+export declare function diagnosePythonPytestCollectionError(detail: string): IFailureDiagnostic;
+export declare function diagnoseGoCannotFindModule(moduleName: string): IFailureDiagnostic;
+export declare function diagnoseGoImportCycle(detail: string): IFailureDiagnostic;
+export declare function diagnoseRustE0432(detail: string): IFailureDiagnostic;
+export declare function diagnoseRustE0308(detail: string): IFailureDiagnostic;
+export declare function renderDiagnosticText(d: IFailureDiagnostic): string;
+/**
+ * Registry of named diagnostics so the CLI / MCP can list them and
+ * fetch by code. Each entry is a placeholder constructor — callers supply
+ * the per-call data via `context`.
+ */
+export interface IDiagnosticRegistryEntry {
+    code: FailureDiagnosticCode;
+    description: string;
+    /** Required keys in `context` for the constructor to produce a useful message. */
+    contextKeys: readonly string[];
+}
+export declare function listDiagnostics(): readonly IDiagnosticRegistryEntry[];
+export declare function getDiagnosticEntry(code: string): IDiagnosticRegistryEntry | null;
+/**
+ * Produce a diagnostic by code using a context bag. Missing context fields
+ * fall back to `(unknown)` so the diagnostic remains useful as documentation.
+ */
+export declare function buildDiagnosticByCode(code: FailureDiagnosticCode, context?: Record<string, unknown>): IFailureDiagnostic;
+//# sourceMappingURL=failure-diagnostics.d.ts.map

package/dist/failure-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-diagnostics.d.ts","sourceRoot":"","sources":["../src/failure-diagnostics.ts"],"names":[],"mappings":"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"}