@shrkcrft/inspector 0.1.0-alpha.2

package/dist/adoption-merge-preview.js

@@ -0,0 +1,254 @@
+/**
+ * Merge preview for the adoption patch. Read-only. Produces text/markdown/html/
+ * json renderings showing exactly what the user would need to merge manually.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { AdoptionCategory, } from "./onboarding-adoption.js";
+import { computeAdoptionFreshness, readAdoptionState, } from "./adoption-state.js";
+import { previewThreeWayBatch, ThreeWayVerdict, } from "./adoption-three-way.js";
+export function buildAdoptionMergePreview(input) {
+    const state = readAdoptionState(input.projectRoot);
+    const freshness = computeAdoptionFreshness(input.projectRoot, state);
+    const threeWay = state
+        ? previewThreeWayBatch(input.projectRoot, state.targetFiles, {
+            draftsChanged: freshness.changedDrafts.length > 0,
+        })
+        : { perTarget: [], summary: emptySummary() };
+    const recommended = recommendCommands(freshness, threeWay, state);
+    return {
+        schema: 'sharkcraft.adoption-merge-preview/v1',
+        projectRoot: input.projectRoot,
+        state,
+        freshness,
+        threeWay,
+        safeAppend: input.plan.byCategory[AdoptionCategory.SafeToAdopt],
+        manualReview: input.plan.byCategory[AdoptionCategory.ManualReview],
+        lowConfidence: input.plan.byCategory[AdoptionCategory.LowConfidence],
+        alreadyCovered: input.plan.byCategory[AdoptionCategory.AlreadyCovered],
+        conflicts: input.plan.byCategory[AdoptionCategory.Conflict],
+        recommendedCommands: recommended,
+    };
+}
+function emptySummary() {
+    return {
+        [ThreeWayVerdict.Safe]: 0,
+        [ThreeWayVerdict.ProbablySafe]: 0,
+        [ThreeWayVerdict.StaleTarget]: 0,
+        [ThreeWayVerdict.StaleDraft]: 0,
+        [ThreeWayVerdict.ManualReview]: 0,
+        [ThreeWayVerdict.CreateFileSafe]: 0,
+        [ThreeWayVerdict.Conflict]: 0,
+    };
+}
+function recommendCommands(freshness, threeWay, state) {
+    if (!state) {
+        return [
+            'shrk onboard --write-drafts',
+            'shrk onboard adopt --write-patch --diff-format unified',
+        ];
+    }
+    if (freshness.status !== 'fresh' ||
+        threeWay.summary[ThreeWayVerdict.StaleTarget] > 0 ||
+        threeWay.summary[ThreeWayVerdict.StaleDraft] > 0) {
+        return [
+            'shrk onboard adopt regenerate',
+            'shrk onboard adopt status',
+        ];
+    }
+    return [
+        'shrk onboard adopt review',
+        'shrk onboard adopt check',
+        `git apply ${nodePath.posix.join('sharkcraft', 'onboarding', 'adoption', 'adopt.patch')}`,
+    ];
+}
+// ─── Renderers ────────────────────────────────────────────────────────────────
+export function renderAdoptionMergePreviewText(p) {
+    const out = [];
+    out.push('=== Onboarding adoption — merge preview ===');
+    if (!p.state) {
+        out.push('No adoption-state.json on disk.');
+        out.push('Run: shrk onboard adopt --write-patch');
+        return out.join('\n') + '\n';
+    }
+    out.push(`  patch         ${p.state.patchPath}`);
+    out.push(`  format        ${p.state.diffFormat}`);
+    out.push(`  freshness     ${p.freshness.status}`);
+    if (p.freshness.staleReasons.length > 0) {
+        out.push('  stale reasons:');
+        for (const r of p.freshness.staleReasons)
+            out.push(`    - ${r}`);
+    }
+    out.push('');
+    out.push('Three-way verdicts:');
+    for (const tw of p.threeWay.perTarget) {
+        out.push(`  ${tw.verdict.padEnd(18)} ${tw.relativePath}`);
+        for (const r of tw.reasons)
+            out.push(`      ${r}`);
+    }
+    out.push('');
+    out.push(`Safe append blocks    ${p.safeAppend.length}`);
+    out.push(`Manual review items   ${p.manualReview.length}`);
+    out.push(`Low-confidence items  ${p.lowConfidence.length}`);
+    out.push(`Already covered       ${p.alreadyCovered.length}`);
+    out.push(`Conflicts             ${p.conflicts.length}`);
+    out.push('');
+    out.push('Recommended commands:');
+    for (const c of p.recommendedCommands)
+        out.push(`  $ ${c}`);
+    return out.join('\n') + '\n';
+}
+export function renderAdoptionMergePreviewMarkdown(p) {
+    const out = [];
+    out.push('# SharkCraft onboarding — merge preview');
+    out.push('');
+    if (!p.state) {
+        out.push('_No adoption state on disk._');
+        out.push('');
+        out.push('```');
+        out.push('shrk onboard --write-drafts');
+        out.push('shrk onboard adopt --write-patch');
+        out.push('```');
+        return out.join('\n') + '\n';
+    }
+    out.push(`- **Patch**: \`${p.state.patchPath}\``);
+    out.push(`- **Format**: \`${p.state.diffFormat}\``);
+    out.push(`- **Freshness**: \`${p.freshness.status}\``);
+    if (p.freshness.staleReasons.length > 0) {
+        out.push('  - Stale reasons:');
+        for (const r of p.freshness.staleReasons)
+            out.push(`    - ${r}`);
+    }
+    out.push('');
+    out.push('## Three-way verdicts per target');
+    out.push('');
+    out.push('| Target | Verdict | Notes |');
+    out.push('|---|---|---|');
+    for (const tw of p.threeWay.perTarget) {
+        const notes = tw.reasons.join('; ').replace(/\|/g, '\\|');
+        out.push(`| \`${tw.relativePath}\` | \`${tw.verdict}\` | ${notes} |`);
+    }
+    out.push('');
+    out.push('## Items by category');
+    out.push('');
+    renderCategoryMd(out, 'Safe to append', p.safeAppend);
+    renderCategoryMd(out, 'Manual review', p.manualReview);
+    renderCategoryMd(out, 'Low-confidence', p.lowConfidence);
+    renderCategoryMd(out, 'Already covered', p.alreadyCovered);
+    renderCategoryMd(out, 'Conflicts', p.conflicts);
+    out.push('');
+    out.push('## Recommended commands');
+    out.push('');
+    out.push('```');
+    for (const c of p.recommendedCommands)
+        out.push(c);
+    out.push('```');
+    return out.join('\n') + '\n';
+}
+function renderCategoryMd(out, title, items) {
+    if (items.length === 0)
+        return;
+    out.push(`### ${title} (${items.length})`);
+    for (const it of items) {
+        out.push(`- **${it.kind}** \`${it.id}\` — ${it.title}`);
+        out.push(`  - reason: ${it.reason}`);
+    }
+    out.push('');
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const HTML_BASE_CSS = `
+*{box-sizing:border-box}body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;margin:0;background:#0f1419;color:#e6e1cf;padding:2rem;line-height:1.55}
+h1,h2,h3{margin-top:1.4rem;color:#bae67e}
+table{border-collapse:collapse;width:100%;margin:.8rem 0}
+th,td{text-align:left;padding:.4rem .6rem;border-bottom:1px solid #2a3138}
+th{background:#1c2329;color:#9aa5b0}
+.badge{display:inline-block;padding:.1rem .5rem;border-radius:.25rem;font-size:.75rem;font-weight:600;text-transform:uppercase}
+.b-safe{background:#28432e;color:#bae67e}.b-probably{background:#3a3a2e;color:#ffd580}.b-stale{background:#4a2e2e;color:#ff7f7f}
+.b-manual{background:#2e3a4a;color:#7fd0ff}.b-create{background:#28433f;color:#7fe6cf}.b-conflict{background:#5a1f1f;color:#ff9f9f}
+pre{background:#1c2329;padding:.8rem;border-radius:.4rem;overflow-x:auto}
+code{background:#1c2329;padding:.05rem .3rem;border-radius:.2rem}
+.note{padding:.6rem .8rem;background:#1c2329;border-left:3px solid #bae67e;border-radius:.2rem;margin:.6rem 0}
+@media (prefers-color-scheme: light){body{background:#fafaf7;color:#1f2329}h1,h2,h3{color:#266a2e}th{background:#eee;color:#222}pre,code{background:#eee}.note{background:#eee;border-left-color:#266a2e}}
+`;
+const VERDICT_CSS = {
+    [ThreeWayVerdict.Safe]: 'b-safe',
+    [ThreeWayVerdict.ProbablySafe]: 'b-probably',
+    [ThreeWayVerdict.StaleTarget]: 'b-stale',
+    [ThreeWayVerdict.StaleDraft]: 'b-stale',
+    [ThreeWayVerdict.ManualReview]: 'b-manual',
+    [ThreeWayVerdict.CreateFileSafe]: 'b-create',
+    [ThreeWayVerdict.Conflict]: 'b-conflict',
+};
+export function renderAdoptionMergePreviewHtml(p) {
+    const out = [];
+    out.push('<!doctype html>');
+    out.push('<html lang="en"><head><meta charset="utf-8"><title>SharkCraft adoption — merge preview</title>');
+    out.push(`<style>${HTML_BASE_CSS}</style></head><body>`);
+    out.push('<h1>SharkCraft onboarding — merge preview</h1>');
+    if (!p.state) {
+        out.push('<p class="note">No adoption state on disk.</p>');
+        out.push('<pre><code>shrk onboard --write-drafts\nshrk onboard adopt --write-patch</code></pre>');
+        out.push('</body></html>');
+        return out.join('\n') + '\n';
+    }
+    out.push('<h2>Patch metadata</h2>');
+    out.push('<table>');
+    out.push(`<tr><th>Patch</th><td><code>${escapeHtml(p.state.patchPath)}</code></td></tr>`);
+    out.push(`<tr><th>Format</th><td><code>${escapeHtml(p.state.diffFormat)}</code></td></tr>`);
+    out.push(`<tr><th>Freshness</th><td><span class="badge ${p.freshness.status === 'fresh' ? 'b-safe' : 'b-stale'}">${escapeHtml(p.freshness.status)}</span></td></tr>`);
+    out.push('</table>');
+    if (p.freshness.staleReasons.length > 0) {
+        out.push('<p class="note"><strong>Stale reasons:</strong></p><ul>');
+        for (const r of p.freshness.staleReasons)
+            out.push(`<li>${escapeHtml(r)}</li>`);
+        out.push('</ul>');
+    }
+    out.push('<h2>Three-way verdicts per target</h2>');
+    out.push('<table><thead><tr><th>Target</th><th>Verdict</th><th>Notes</th></tr></thead><tbody>');
+    for (const tw of p.threeWay.perTarget) {
+        const cls = VERDICT_CSS[tw.verdict];
+        out.push(`<tr><td><code>${escapeHtml(tw.relativePath)}</code></td>` +
+            `<td><span class="badge ${cls}">${escapeHtml(tw.verdict)}</span></td>` +
+            `<td>${tw.reasons.map(escapeHtml).join('<br>')}</td></tr>`);
+    }
+    out.push('</tbody></table>');
+    renderCategoryHtml(out, 'Safe to append', p.safeAppend);
+    renderCategoryHtml(out, 'Manual review', p.manualReview);
+    renderCategoryHtml(out, 'Low-confidence', p.lowConfidence);
+    renderCategoryHtml(out, 'Already covered', p.alreadyCovered);
+    renderCategoryHtml(out, 'Conflicts', p.conflicts);
+    out.push('<h2>Recommended commands</h2>');
+    out.push('<pre>');
+    for (const c of p.recommendedCommands)
+        out.push(escapeHtml(c));
+    out.push('</pre>');
+    out.push('</body></html>');
+    return out.join('\n') + '\n';
+}
+function renderCategoryHtml(out, title, items) {
+    if (items.length === 0)
+        return;
+    out.push(`<h2>${escapeHtml(title)} (${items.length})</h2>`);
+    out.push('<table><thead><tr><th>Kind</th><th>Id</th><th>Title</th><th>Reason</th></tr></thead><tbody>');
+    for (const it of items) {
+        out.push(`<tr><td><code>${escapeHtml(it.kind)}</code></td>` +
+            `<td><code>${escapeHtml(it.id)}</code></td>` +
+            `<td>${escapeHtml(it.title)}</td>` +
+            `<td>${escapeHtml(it.reason)}</td></tr>`);
+    }
+    out.push('</tbody></table>');
+}
+/** Reusable: read the unified patch body if it exists. */
+export function loadAdoptPatchBody(projectRoot) {
+    const p = nodePath.join(projectRoot, 'sharkcraft', 'onboarding', 'adoption', 'adopt.patch');
+    if (!existsSync(p))
+        return null;
+    return readFileSync(p, 'utf8');
+}

package/dist/adoption-report-renderer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Adoption report renderers — text / markdown / html / json.
+ *
+ * Built from the adoption plan + (optionally) adoption state. Self-contained
+ * HTML output (no external assets, no JS, dark-mode aware). Never writes
+ * outside the adoption directory.
+ */
+import { type IAdoptionPlan } from './onboarding-adoption.js';
+import { type IAdoptionState, type IComputeFreshnessResult } from './adoption-state.js';
+import { type IThreeWayPreviewBatchResult } from './adoption-three-way.js';
+export type AdoptionReportFormat = 'text' | 'markdown' | 'html' | 'json';
+export interface IAdoptionReport {
+    schema: 'sharkcraft.adoption-report/v1';
+    projectRoot: string;
+    generatedAt: string;
+    state: IAdoptionState | null;
+    freshness: IComputeFreshnessResult;
+    threeWay: IThreeWayPreviewBatchResult;
+    plan: IAdoptionPlan;
+    recommendedCommands: readonly string[];
+    safetyNotes: readonly string[];
+}
+export interface IBuildAdoptionReportInput {
+    projectRoot: string;
+    plan: IAdoptionPlan;
+    state: IAdoptionState | null;
+}
+export declare function buildAdoptionReport(input: IBuildAdoptionReportInput): IAdoptionReport;
+export declare function renderAdoptionReportText(r: IAdoptionReport): string;
+export declare function renderAdoptionReportMarkdown(r: IAdoptionReport): string;
+export declare function renderAdoptionReportHtml(r: IAdoptionReport): string;
+export declare function renderAdoptionReportJson(r: IAdoptionReport): string;
+//# sourceMappingURL=adoption-report-renderer.d.ts.map

package/dist/adoption-report-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adoption-report-renderer.d.ts","sourceRoot":"","sources":["../src/adoption-report-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,+BAA+B,CAAC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,uBAAuB,CAAC;IACnC,QAAQ,EAAE,2BAA2B,CAAC;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,yBAAyB,GAAG,eAAe,CAsBrF;AAqCD,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CA+BnE;AAED,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAgDvE;AA+CD,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAwDnE;AAiBD,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAEnE"}

package/dist/adoption-report-renderer.js

@@ -0,0 +1,257 @@
+/**
+ * Adoption report renderers — text / markdown / html / json.
+ *
+ * Built from the adoption plan + (optionally) adoption state. Self-contained
+ * HTML output (no external assets, no JS, dark-mode aware). Never writes
+ * outside the adoption directory.
+ */
+import { AdoptionCategory, } from "./onboarding-adoption.js";
+import { computeAdoptionFreshness, } from "./adoption-state.js";
+import { previewThreeWayBatch, ThreeWayVerdict, } from "./adoption-three-way.js";
+export function buildAdoptionReport(input) {
+    const freshness = computeAdoptionFreshness(input.projectRoot, input.state);
+    const threeWay = input.state
+        ? previewThreeWayBatch(input.projectRoot, input.state.targetFiles, {
+            draftsChanged: freshness.changedDrafts.length > 0,
+        })
+        : { perTarget: [], summary: emptyVerdictSummary() };
+    return {
+        schema: 'sharkcraft.adoption-report/v1',
+        projectRoot: input.projectRoot,
+        generatedAt: new Date().toISOString(),
+        state: input.state,
+        freshness,
+        threeWay,
+        plan: input.plan,
+        recommendedCommands: buildRecommended(input.state, freshness),
+        safetyNotes: [
+            'MCP never writes — adoption outputs are always written by the CLI.',
+            'The user must review the patch before applying. `git apply --check` is recommended.',
+            'Adoption only appends to existing files. It never overwrites existing entries.',
+        ],
+    };
+}
+function emptyVerdictSummary() {
+    return {
+        [ThreeWayVerdict.Safe]: 0,
+        [ThreeWayVerdict.ProbablySafe]: 0,
+        [ThreeWayVerdict.StaleTarget]: 0,
+        [ThreeWayVerdict.StaleDraft]: 0,
+        [ThreeWayVerdict.ManualReview]: 0,
+        [ThreeWayVerdict.CreateFileSafe]: 0,
+        [ThreeWayVerdict.Conflict]: 0,
+    };
+}
+function buildRecommended(state, freshness) {
+    if (!state) {
+        return [
+            'shrk onboard --write-drafts',
+            'shrk onboard adopt --write-patch --diff-format unified',
+            'shrk onboard adopt report --format html --output /tmp/adoption.html',
+        ];
+    }
+    if (freshness.status !== 'fresh') {
+        return ['shrk onboard adopt regenerate', 'shrk onboard adopt status'];
+    }
+    return [
+        'shrk onboard adopt check',
+        'shrk onboard adopt merge-preview --format markdown',
+        `git apply ${state.patchPath}`,
+    ];
+}
+// ─── Renderers ────────────────────────────────────────────────────────────────
+export function renderAdoptionReportText(r) {
+    const out = [];
+    out.push('=== Onboarding adoption — report ===');
+    out.push(`  generated     ${r.generatedAt}`);
+    if (r.state) {
+        out.push(`  patch         ${r.state.patchPath}`);
+        out.push(`  format        ${r.state.diffFormat}`);
+        out.push(`  freshness     ${r.freshness.status}`);
+    }
+    else {
+        out.push('  state         (none on disk)');
+    }
+    out.push('');
+    out.push('## Categories');
+    for (const cat of Object.values(AdoptionCategory)) {
+        const items = r.plan.byCategory[cat];
+        out.push(`  ${cat.padEnd(18)} ${items.length}`);
+    }
+    out.push('');
+    if (r.state && r.threeWay.perTarget.length > 0) {
+        out.push('## Three-way verdicts');
+        for (const tw of r.threeWay.perTarget) {
+            out.push(`  ${tw.verdict.padEnd(18)} ${tw.relativePath}`);
+        }
+        out.push('');
+    }
+    out.push('## Recommended commands');
+    for (const c of r.recommendedCommands)
+        out.push(`  $ ${c}`);
+    out.push('');
+    out.push('## Safety');
+    for (const s of r.safetyNotes)
+        out.push(`  - ${s}`);
+    return out.join('\n') + '\n';
+}
+export function renderAdoptionReportMarkdown(r) {
+    const out = [];
+    out.push('# SharkCraft onboarding adoption — report');
+    out.push('');
+    out.push(`Generated: \`${r.generatedAt}\``);
+    if (r.state) {
+        out.push(`- Patch: \`${r.state.patchPath}\``);
+        out.push(`- Format: \`${r.state.diffFormat}\``);
+        out.push(`- Freshness: \`${r.freshness.status}\``);
+    }
+    else {
+        out.push('- State: _(no adoption state on disk)_');
+    }
+    out.push('');
+    out.push('## Executive summary');
+    out.push('');
+    out.push('| Category | Count |');
+    out.push('|---|---|');
+    for (const cat of Object.values(AdoptionCategory)) {
+        out.push(`| \`${cat}\` | ${r.plan.byCategory[cat].length} |`);
+    }
+    out.push('');
+    if (r.state && r.threeWay.perTarget.length > 0) {
+        out.push('## Three-way verdicts');
+        out.push('');
+        out.push('| Target | Verdict | Notes |');
+        out.push('|---|---|---|');
+        for (const tw of r.threeWay.perTarget) {
+            out.push(`| \`${tw.relativePath}\` | \`${tw.verdict}\` | ${tw.reasons.join('; ')} |`);
+        }
+        out.push('');
+    }
+    renderItemSectionMd(out, 'Safe to adopt', r.plan.byCategory[AdoptionCategory.SafeToAdopt]);
+    renderItemSectionMd(out, 'Manual review', r.plan.byCategory[AdoptionCategory.ManualReview]);
+    renderItemSectionMd(out, 'Conflicts', r.plan.byCategory[AdoptionCategory.Conflict]);
+    renderItemSectionMd(out, 'Skipped / low-confidence', [
+        ...r.plan.byCategory[AdoptionCategory.LowConfidence],
+        ...r.plan.byCategory[AdoptionCategory.Skipped],
+    ]);
+    out.push('## Recommended commands');
+    out.push('');
+    out.push('```');
+    for (const c of r.recommendedCommands)
+        out.push(c);
+    out.push('```');
+    out.push('');
+    out.push('## Safety');
+    for (const s of r.safetyNotes)
+        out.push(`- ${s}`);
+    out.push('');
+    return out.join('\n') + '\n';
+}
+function renderItemSectionMd(out, title, items) {
+    if (items.length === 0)
+        return;
+    out.push(`### ${title} (${items.length})`);
+    for (const it of items) {
+        out.push(`- **${it.kind}** \`${it.id}\` — ${it.title}`);
+        out.push(`  - reason: ${it.reason}`);
+    }
+    out.push('');
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const HTML_CSS = `
+*{box-sizing:border-box}body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;margin:0;background:#0f1419;color:#e6e1cf;padding:2rem;line-height:1.55}
+h1,h2,h3{margin-top:1.4rem;color:#bae67e}
+table{border-collapse:collapse;width:100%;margin:.8rem 0}
+th,td{text-align:left;padding:.4rem .6rem;border-bottom:1px solid #2a3138}
+th{background:#1c2329;color:#9aa5b0}
+.badge{display:inline-block;padding:.1rem .5rem;border-radius:.25rem;font-size:.75rem;font-weight:600;text-transform:uppercase}
+.b-safe{background:#28432e;color:#bae67e}.b-stale{background:#4a2e2e;color:#ff7f7f}
+.b-manual{background:#2e3a4a;color:#7fd0ff}.b-probably{background:#3a3a2e;color:#ffd580}
+.b-create{background:#28433f;color:#7fe6cf}.b-conflict{background:#5a1f1f;color:#ff9f9f}
+pre{background:#1c2329;padding:.8rem;border-radius:.4rem;overflow-x:auto}
+code{background:#1c2329;padding:.05rem .3rem;border-radius:.2rem}
+.note{padding:.6rem .8rem;background:#1c2329;border-left:3px solid #bae67e;border-radius:.2rem;margin:.6rem 0}
+@media (prefers-color-scheme: light){body{background:#fafaf7;color:#1f2329}h1,h2,h3{color:#266a2e}th{background:#eee;color:#222}pre,code{background:#eee}.note{background:#eee;border-left-color:#266a2e}}
+`;
+const VERDICT_CSS = {
+    [ThreeWayVerdict.Safe]: 'b-safe',
+    [ThreeWayVerdict.ProbablySafe]: 'b-probably',
+    [ThreeWayVerdict.StaleTarget]: 'b-stale',
+    [ThreeWayVerdict.StaleDraft]: 'b-stale',
+    [ThreeWayVerdict.ManualReview]: 'b-manual',
+    [ThreeWayVerdict.CreateFileSafe]: 'b-create',
+    [ThreeWayVerdict.Conflict]: 'b-conflict',
+};
+export function renderAdoptionReportHtml(r) {
+    const out = [];
+    out.push('<!doctype html>');
+    out.push('<html lang="en"><head><meta charset="utf-8"><title>SharkCraft adoption report</title>');
+    out.push(`<style>${HTML_CSS}</style></head><body>`);
+    out.push('<h1>SharkCraft onboarding adoption — report</h1>');
+    out.push('<p class="note"><strong>MCP never writes.</strong> The user must review the patch before applying.</p>');
+    out.push('<h2>Status</h2>');
+    out.push('<table>');
+    out.push(`<tr><th>Generated</th><td><code>${escapeHtml(r.generatedAt)}</code></td></tr>`);
+    if (r.state) {
+        out.push(`<tr><th>Patch</th><td><code>${escapeHtml(r.state.patchPath)}</code></td></tr>`);
+        out.push(`<tr><th>Format</th><td><code>${escapeHtml(r.state.diffFormat)}</code></td></tr>`);
+        out.push(`<tr><th>Freshness</th><td><span class="badge ${r.freshness.status === 'fresh' ? 'b-safe' : 'b-stale'}">${escapeHtml(r.freshness.status)}</span></td></tr>`);
+    }
+    else {
+        out.push('<tr><th>State</th><td><em>no adoption state on disk</em></td></tr>');
+    }
+    out.push('</table>');
+    out.push('<h2>Categories</h2>');
+    out.push('<table><thead><tr><th>Category</th><th>Count</th></tr></thead><tbody>');
+    for (const cat of Object.values(AdoptionCategory)) {
+        out.push(`<tr><td><code>${escapeHtml(cat)}</code></td><td>${r.plan.byCategory[cat].length}</td></tr>`);
+    }
+    out.push('</tbody></table>');
+    if (r.state && r.threeWay.perTarget.length > 0) {
+        out.push('<h2>Three-way verdicts</h2>');
+        out.push('<table><thead><tr><th>Target</th><th>Verdict</th><th>Notes</th></tr></thead><tbody>');
+        for (const tw of r.threeWay.perTarget) {
+            const cls = VERDICT_CSS[tw.verdict];
+            out.push(`<tr><td><code>${escapeHtml(tw.relativePath)}</code></td>` +
+                `<td><span class="badge ${cls}">${escapeHtml(tw.verdict)}</span></td>` +
+                `<td>${tw.reasons.map(escapeHtml).join('<br>')}</td></tr>`);
+        }
+        out.push('</tbody></table>');
+    }
+    renderItemSectionHtml(out, 'Safe to adopt', r.plan.byCategory[AdoptionCategory.SafeToAdopt]);
+    renderItemSectionHtml(out, 'Manual review', r.plan.byCategory[AdoptionCategory.ManualReview]);
+    renderItemSectionHtml(out, 'Conflicts', r.plan.byCategory[AdoptionCategory.Conflict]);
+    renderItemSectionHtml(out, 'Skipped / low-confidence', [...r.plan.byCategory[AdoptionCategory.LowConfidence], ...r.plan.byCategory[AdoptionCategory.Skipped]]);
+    out.push('<h2>Recommended commands</h2><pre>');
+    for (const c of r.recommendedCommands)
+        out.push(escapeHtml(c));
+    out.push('</pre>');
+    out.push('<h2>Safety</h2><ul>');
+    for (const s of r.safetyNotes)
+        out.push(`<li>${escapeHtml(s)}</li>`);
+    out.push('</ul></body></html>');
+    return out.join('\n') + '\n';
+}
+function renderItemSectionHtml(out, title, items) {
+    if (items.length === 0)
+        return;
+    out.push(`<h2>${escapeHtml(title)} (${items.length})</h2>`);
+    out.push('<table><thead><tr><th>Kind</th><th>Id</th><th>Title</th><th>Reason</th></tr></thead><tbody>');
+    for (const it of items) {
+        out.push(`<tr><td><code>${escapeHtml(it.kind)}</code></td>` +
+            `<td><code>${escapeHtml(it.id)}</code></td>` +
+            `<td>${escapeHtml(it.title)}</td>` +
+            `<td>${escapeHtml(it.reason)}</td></tr>`);
+    }
+    out.push('</tbody></table>');
+}
+export function renderAdoptionReportJson(r) {
+    return JSON.stringify(r, null, 2) + '\n';
+}

package/dist/adoption-state.d.ts

@@ -0,0 +1,100 @@
+import { AdoptionCategory } from './onboarding-adoption.js';
+import type { AdoptionKind, IAdoptionItem, IAdoptionPatchTarget, IAdoptionPlan } from './onboarding-adoption.js';
+export declare const ADOPTION_STATE_SCHEMA = "sharkcraft.adoption-state/v1";
+export declare enum AdoptionFreshnessStatus {
+    Fresh = "fresh",
+    Stale = "stale",
+    Unknown = "unknown"
+}
+export interface IAdoptionStateCategorySummary {
+    [AdoptionCategory.SafeToAdopt]: readonly string[];
+    [AdoptionCategory.ManualReview]: readonly string[];
+    [AdoptionCategory.LowConfidence]: readonly string[];
+    [AdoptionCategory.Conflict]: readonly string[];
+    [AdoptionCategory.AlreadyCovered]: readonly string[];
+    [AdoptionCategory.Skipped]: readonly string[];
+}
+export interface IAdoptionStateFile {
+    relativePath: string;
+    hash: string;
+}
+export interface IAdoptionStateFreshness {
+    status: AdoptionFreshnessStatus;
+    staleReasons: readonly string[];
+}
+export interface IAdoptionState {
+    schema: typeof ADOPTION_STATE_SCHEMA;
+    projectRoot: string;
+    createdAt: string;
+    updatedAt: string;
+    sharkcraftVersion: string;
+    command: string;
+    sourceDraftFiles: readonly IAdoptionStateFile[];
+    targetFiles: readonly IAdoptionStateFile[];
+    /** Patch + summary + report files this run produced. Relative to projectRoot. */
+    generatedFiles: readonly string[];
+    patchPath: string;
+    summaryPath: string;
+    reportPath?: string;
+    diffFormat: 'pseudo' | 'unified';
+    confidenceThreshold: 'high' | 'medium' | 'low';
+    includedKinds: readonly AdoptionKind[];
+    excludedKinds: readonly AdoptionKind[];
+    categories: IAdoptionStateCategorySummary;
+    freshness: IAdoptionStateFreshness;
+    warnings: readonly string[];
+    nextCommands: readonly string[];
+}
+export declare function adoptionDir(projectRoot: string): string;
+export declare function adoptionStatePath(projectRoot: string): string;
+export declare function adoptionHistoryDir(projectRoot: string): string;
+export declare function hashFile(absolute: string): string | null;
+export interface IBuildAdoptionStateInput {
+    projectRoot: string;
+    command: string;
+    patchPath: string;
+    summaryPath: string;
+    reportPath?: string;
+    diffFormat: 'pseudo' | 'unified';
+    plan: IAdoptionPlan;
+    targets: readonly IAdoptionPatchTarget[];
+    generatedFiles: readonly string[];
+    warnings?: readonly string[];
+    nextCommands?: readonly string[];
+    sharkcraftVersion?: string;
+    /** When provided, preserve the prior createdAt (so updatedAt reflects regen). */
+    previousCreatedAt?: string;
+}
+export declare function buildAdoptionState(input: IBuildAdoptionStateInput): IAdoptionState;
+export declare function writeAdoptionState(projectRoot: string, state: IAdoptionState): string;
+export declare function readAdoptionState(projectRoot: string): IAdoptionState | null;
+export interface IComputeFreshnessResult extends IAdoptionStateFreshness {
+    changedTargets: readonly IAdoptionStateFile[];
+    changedDrafts: readonly IAdoptionStateFile[];
+    missingTargets: readonly string[];
+    missingDrafts: readonly string[];
+}
+/**
+ * Recompute freshness from disk. Compares stored hashes against current file
+ * content. A patch is stale when any target or draft file changed since the
+ * state was written (or when state files are missing).
+ */
+export declare function computeAdoptionFreshness(projectRoot: string, state: IAdoptionState | null): IComputeFreshnessResult;
+/** Archive the previous adoption-state.json + adopt.patch under history/. */
+export interface IArchiveAdoptionStateResult {
+    archived: readonly string[];
+    historyDir: string;
+}
+export declare function archivePreviousAdoptionOutputs(projectRoot: string, timestamp?: string): IArchiveAdoptionStateResult;
+/** Convenience used by `shrk onboard adopt regenerate`. */
+export interface IUpdateAdoptionStateInput extends Omit<IBuildAdoptionStateInput, 'previousCreatedAt'> {
+    /** When the user passes --force, we still archive previous outputs first. */
+    archivePrevious: boolean;
+}
+export declare function updateAdoptionStateAfterRegenerate(input: IUpdateAdoptionStateInput): {
+    state: IAdoptionState;
+    archived: IArchiveAdoptionStateResult | null;
+    statePath: string;
+};
+export type { IAdoptionItem };
+//# sourceMappingURL=adoption-state.d.ts.map

package/dist/adoption-state.d.ts.map

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