@shrkcrft/inspector 0.1.0-alpha.2

package/dist/monorepo-onboarding.js

@@ -0,0 +1,235 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { WorkspaceProfile } from '@shrkcrft/workspace';
+const PACKAGE_LIMIT = 30;
+const GROUPS = [
+    { key: 'apps', dir: 'apps' },
+    { key: 'packages', dir: 'packages' },
+    { key: 'libs', dir: 'libs' },
+];
+const TRACKED_SCRIPTS = new Set([
+    'test',
+    'test:unit',
+    'test:int',
+    'lint',
+    'build',
+    'typecheck',
+]);
+export function buildMonorepoSummary(ws, subDirs) {
+    const isMonorepo = ws.profiles.includes(WorkspaceProfile.IsMonorepo) ||
+        ws.profiles.includes(WorkspaceProfile.HasPackageWorkspaces) ||
+        ws.profiles.includes(WorkspaceProfile.HasNx);
+    if (!isMonorepo)
+        return null;
+    const workspaces = ws.raw.packageJson?.workspaces;
+    const workspacesArr = Array.isArray(workspaces)
+        ? workspaces.filter((w) => typeof w === 'string')
+        : [];
+    const groups = {
+        apps: [],
+        packages: [],
+        libs: [],
+    };
+    let scanned = 0;
+    for (const g of GROUPS) {
+        const children = subDirs.get(g.dir) ?? [];
+        for (const child of children) {
+            if (scanned >= PACKAGE_LIMIT)
+                break;
+            const rel = nodePath.posix.join(g.dir, child);
+            const full = nodePath.join(ws.projectRoot, g.dir, child);
+            if (!statSafeIsDir(full))
+                continue;
+            groups[g.key].push(describePackage(full, rel, g.key));
+            scanned += 1;
+        }
+    }
+    const rootVerificationCommands = buildRootVerificationCommands(ws);
+    const perPackageVerificationHints = [];
+    for (const list of Object.values(groups)) {
+        for (const p of list) {
+            for (const [name, value] of Object.entries(p.scripts)) {
+                if (!TRACKED_SCRIPTS.has(name))
+                    continue;
+                if (typeof value !== 'string' || !value)
+                    continue;
+                perPackageVerificationHints.push({
+                    packagePath: p.path,
+                    script: name,
+                    command: buildPackageRunCommand(ws, p.path, name),
+                });
+            }
+        }
+    }
+    const boundaryCandidates = buildBoundaryCandidates(groups);
+    const presetRecommendations = buildPresetRecommendations(ws);
+    const notes = buildNotes(ws, groups);
+    return {
+        rootPath: ws.projectRoot,
+        workspaces: workspacesArr,
+        apps: groups.apps,
+        packages: groups.packages,
+        libs: groups.libs,
+        rootVerificationCommands,
+        perPackageVerificationHints,
+        boundaryCandidates,
+        presetRecommendations,
+        notes,
+    };
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+function statSafeIsDir(p) {
+    try {
+        return existsSync(p) && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function describePackage(full, rel, group) {
+    const pkgJsonPath = nodePath.join(full, 'package.json');
+    let name;
+    const scripts = {};
+    let hasTsConfig = false;
+    if (existsSync(pkgJsonPath)) {
+        try {
+            const raw = readFileSync(pkgJsonPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.name === 'string')
+                name = parsed.name;
+            if (parsed.scripts) {
+                for (const [k, v] of Object.entries(parsed.scripts)) {
+                    if (typeof v === 'string')
+                        scripts[k] = v;
+                }
+            }
+        }
+        catch {
+            // Ignore unreadable JSON — we still emit the package entry.
+        }
+    }
+    hasTsConfig = existsSync(nodePath.join(full, 'tsconfig.json'));
+    // Optional: probe for a src/ folder marker.
+    try {
+        readdirSync(full);
+    }
+    catch {
+        // ignore
+    }
+    return {
+        path: rel,
+        group,
+        ...(name ? { name } : {}),
+        scripts,
+        hasTsConfig,
+    };
+}
+function buildRootVerificationCommands(ws) {
+    const out = [];
+    const runner = pickRunner(ws);
+    for (const name of ['test', 'typecheck', 'lint', 'build']) {
+        const v = ws.scripts[name];
+        if (typeof v === 'string' && v.length > 0) {
+            out.push(`${runner} ${name}`);
+        }
+    }
+    if (out.length === 0) {
+        // Even with no scripts, suggest the deterministic checks the engine knows
+        // about so the user has *something* to run.
+        out.push('bun x tsc -p tsconfig.base.json --noEmit');
+        out.push('shrk doctor');
+        out.push('shrk check boundaries');
+    }
+    return [...new Set(out)];
+}
+function buildPackageRunCommand(ws, pkgPath, script) {
+    // We do not assume a specific monorepo runner. Emit a `--cwd` invocation
+    // when the manager supports it; otherwise emit a doc-friendly fallback.
+    switch (ws.packageManager.manager) {
+        case 'bun':
+            return `bun --cwd ${pkgPath} run ${script}`;
+        case 'pnpm':
+            return `pnpm --filter ./${pkgPath} run ${script}`;
+        case 'yarn':
+            return `yarn workspace ${pkgPath} ${script}`;
+        case 'npm':
+            return `npm run ${script} --workspace ${pkgPath}`;
+        default:
+            return `(cd ${pkgPath} && npm run ${script})`;
+    }
+}
+function pickRunner(ws) {
+    switch (ws.packageManager.manager) {
+        case 'bun':
+            return 'bun run';
+        case 'pnpm':
+            return 'pnpm';
+        case 'yarn':
+            return 'yarn';
+        case 'npm':
+            return 'npm run';
+        default:
+            return 'npm run';
+    }
+}
+function buildBoundaryCandidates(groups) {
+    const out = [];
+    // Standard rule: packages/* should not import from apps/*.
+    if (groups.packages.length > 0 && groups.apps.length > 0) {
+        out.push({
+            id: 'architecture.packages.no-imports-from-apps',
+            title: 'packages/* must not import from apps/*',
+            from: ['packages/**'],
+            forbiddenImports: ['apps/**'],
+            reason: 'packages/ + apps/ both present; packages depending on apps inverts the layer order',
+        });
+    }
+    // Standard rule: libs/* should not import from apps/*.
+    if (groups.libs.length > 0 && groups.apps.length > 0) {
+        out.push({
+            id: 'architecture.libs.no-imports-from-apps',
+            title: 'libs/* must not import from apps/*',
+            from: ['libs/**'],
+            forbiddenImports: ['apps/**'],
+            reason: 'libs/ + apps/ both present; libs depending on apps inverts the layer order',
+        });
+    }
+    return out;
+}
+function buildPresetRecommendations(ws) {
+    const out = [];
+    // Nothing fancy: hint to use 'nx-style' / 'monorepo' presets when available.
+    // The actual preset picker still runs via `recommendPresets`; this is the
+    // monorepo-flavored recommendation list shown alongside it.
+    if (ws.profiles.includes(WorkspaceProfile.HasNx)) {
+        out.push('nx-monorepo');
+    }
+    else if (ws.profiles.includes(WorkspaceProfile.HasPackageWorkspaces)) {
+        out.push('package-workspaces');
+    }
+    else {
+        out.push('generic-monorepo');
+    }
+    return out;
+}
+function buildNotes(ws, groups) {
+    const out = [];
+    const counts = [
+        groups.apps.length > 0 ? `${groups.apps.length} app(s)` : null,
+        groups.packages.length > 0 ? `${groups.packages.length} package(s)` : null,
+        groups.libs.length > 0 ? `${groups.libs.length} lib(s)` : null,
+    ].filter((s) => s !== null);
+    if (counts.length > 0) {
+        out.push(`Detected monorepo layout: ${counts.join(', ')}.`);
+    }
+    if (ws.profiles.includes(WorkspaceProfile.HasNx)) {
+        out.push('Nx workspace detected — preset suggestions reflect Nx conventions.');
+    }
+    if (ws.profiles.includes(WorkspaceProfile.HasPackageWorkspaces)) {
+        out.push('package.json workspaces detected.');
+    }
+    if (groups.apps.length === 0 && groups.packages.length === 0 && groups.libs.length === 0) {
+        out.push('Monorepo signals detected but no apps/packages/libs directories — keep onboarding bounded.');
+    }
+    return out;
+}

package/dist/onboarding-adoption-diff.d.ts

@@ -0,0 +1,53 @@
+import { AdoptionKind } from './onboarding-adoption.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const ONBOARD_ADOPTION_DIFF_SCHEMA = "sharkcraft.onboard-adoption-diff/v1";
+export type OnboardAdoptionDiffFormat = 'text' | 'markdown' | 'html' | 'json';
+export declare enum OnboardDiffBlockKind {
+    NewBlock = "new-block",
+    AlreadyExists = "already-exists",
+    Conflict = "conflict",
+    ManualReview = "manual-review"
+}
+export interface IOnboardDiffLine {
+    marker: '+' | '-' | ' ' | '~';
+    text: string;
+}
+export interface IOnboardDiffBlock {
+    kind: OnboardDiffBlockKind;
+    /** Target file relative to the project root. */
+    targetFile: string;
+    /** Whether the target file exists on disk. */
+    targetExists: boolean;
+    /** Adoption kind (rule / path / template / boundary / verification / pipeline). */
+    adoptionKind: AdoptionKind;
+    title: string;
+    /** Short notes for the human reviewer. */
+    notes?: readonly string[];
+    /** Line-level preview lines. */
+    lines: readonly IOnboardDiffLine[];
+}
+export interface IOnboardAdoptionDiff {
+    schema: typeof ONBOARD_ADOPTION_DIFF_SCHEMA;
+    generatedAt: string;
+    projectRoot: string;
+    blocks: readonly IOnboardDiffBlock[];
+    summary: {
+        newBlocks: number;
+        alreadyExists: number;
+        conflicts: number;
+        manualReview: number;
+    };
+    warnings: readonly string[];
+}
+export interface IBuildOnboardAdoptionDiffOptions {
+    /** Confidence threshold mirrored from the underlying adoption build. */
+    confidence?: 'high' | 'medium' | 'low';
+    include?: readonly AdoptionKind[];
+    exclude?: readonly AdoptionKind[];
+}
+export declare function buildOnboardAdoptionDiff(inspection: ISharkcraftInspection, options?: IBuildOnboardAdoptionDiffOptions): IOnboardAdoptionDiff;
+export declare function renderOnboardAdoptionDiffText(diff: IOnboardAdoptionDiff): string;
+export declare function renderOnboardAdoptionDiffMarkdown(diff: IOnboardAdoptionDiff): string;
+export declare function renderOnboardAdoptionDiffHtml(diff: IOnboardAdoptionDiff): string;
+export declare function renderOnboardAdoptionDiff(diff: IOnboardAdoptionDiff, format: OnboardAdoptionDiffFormat): string;
+//# sourceMappingURL=onboarding-adoption-diff.d.ts.map

package/dist/onboarding-adoption-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-adoption-diff.d.ts","sourceRoot":"","sources":["../src/onboarding-adoption-diff.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,YAAY,EAIb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAElF,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9E,oBAAY,oBAAoB;IAC9B,QAAQ,cAAc;IACtB,aAAa,mBAAmB;IAChC,QAAQ,aAAa;IACrB,YAAY,kBAAkB;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,YAAY,EAAE,OAAO,CAAC;IACtB,mFAAmF;IACnF,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,gCAAgC;IAChC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,4BAA4B,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrC,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AA4HD,MAAM,WAAW,gCAAgC;IAC/C,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACvC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CACnC;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,gCAAqC,GAC7C,oBAAoB,CAwCtB;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAkBhF;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAuCpF;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAyChF;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,oBAAoB,EAC1B,MAAM,EAAE,yBAAyB,GAChC,MAAM,CAKR"}

package/dist/onboarding-adoption-diff.js

@@ -0,0 +1,285 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { AdoptionCategory, AdoptionKind, buildOnboardingAdoptionPlan, } from "./onboarding-adoption.js";
+import { buildOnboardingPlan } from "./onboarding.js";
+export const ONBOARD_ADOPTION_DIFF_SCHEMA = 'sharkcraft.onboard-adoption-diff/v1';
+export var OnboardDiffBlockKind;
+(function (OnboardDiffBlockKind) {
+    OnboardDiffBlockKind["NewBlock"] = "new-block";
+    OnboardDiffBlockKind["AlreadyExists"] = "already-exists";
+    OnboardDiffBlockKind["Conflict"] = "conflict";
+    OnboardDiffBlockKind["ManualReview"] = "manual-review";
+})(OnboardDiffBlockKind || (OnboardDiffBlockKind = {}));
+function esc(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function targetFor(kind) {
+    switch (kind) {
+        case AdoptionKind.Rule:
+            return 'sharkcraft/rules.ts';
+        case AdoptionKind.Path:
+            return 'sharkcraft/paths.ts';
+        case AdoptionKind.Verification:
+            return 'sharkcraft/sharkcraft.config.ts';
+        case AdoptionKind.Template:
+            return 'sharkcraft/templates.ts';
+        case AdoptionKind.Boundary:
+            return 'sharkcraft/boundaries.ts';
+        case AdoptionKind.Pipeline:
+            return 'sharkcraft/pipelines.ts';
+    }
+}
+function renderItemPreview(item) {
+    switch (item.kind) {
+        case AdoptionKind.Rule:
+            return [`// rule ${item.id} — ${item.title}`];
+        case AdoptionKind.Path:
+            return [`// path ${item.id} — ${item.title}`];
+        case AdoptionKind.Verification:
+            return [`{ id: '${item.id}', label: '${item.title}', command: '<edit>', trusted: true },`];
+        case AdoptionKind.Template:
+            return [`// template ${item.id} — ${item.title}`];
+        case AdoptionKind.Boundary:
+            return [`// boundary ${item.id} — ${item.title}`];
+        case AdoptionKind.Pipeline:
+            return [`// pipeline ${item.id} — ${item.title}`];
+    }
+}
+function buildBlocks(inspection, plan) {
+    const blocks = [];
+    const cwd = inspection.projectRoot;
+    for (const cat of Object.values(AdoptionCategory)) {
+        const items = plan.byCategory[cat];
+        if (items.length === 0)
+            continue;
+        for (const item of items) {
+            const target = targetFor(item.kind);
+            const targetExists = existsSync(nodePath.resolve(cwd, target));
+            if (cat === AdoptionCategory.AlreadyCovered) {
+                blocks.push({
+                    kind: OnboardDiffBlockKind.AlreadyExists,
+                    targetFile: target,
+                    targetExists,
+                    adoptionKind: item.kind,
+                    title: `${item.id} already covered in ${target}`,
+                    notes: [item.reason],
+                    lines: [],
+                });
+                continue;
+            }
+            if (cat === AdoptionCategory.Conflict) {
+                blocks.push({
+                    kind: OnboardDiffBlockKind.Conflict,
+                    targetFile: target,
+                    targetExists,
+                    adoptionKind: item.kind,
+                    title: `${item.id} CONFLICT (${item.kind})`,
+                    notes: [item.reason],
+                    lines: [
+                        { marker: '~', text: 'manual review required — existing entry differs' },
+                    ],
+                });
+                continue;
+            }
+            if (cat === AdoptionCategory.ManualReview) {
+                blocks.push({
+                    kind: OnboardDiffBlockKind.ManualReview,
+                    targetFile: target,
+                    targetExists,
+                    adoptionKind: item.kind,
+                    title: `${item.id} — manual review`,
+                    notes: [item.reason],
+                    lines: renderItemPreview(item).map((text) => ({ marker: '~', text })),
+                });
+                continue;
+            }
+            if (cat === AdoptionCategory.SafeToAdopt) {
+                blocks.push({
+                    kind: OnboardDiffBlockKind.NewBlock,
+                    targetFile: target,
+                    targetExists,
+                    adoptionKind: item.kind,
+                    title: `Append to ${target}: ${item.id}`,
+                    notes: [item.reason],
+                    lines: renderItemPreview(item).map((text) => ({ marker: '+', text })),
+                });
+                continue;
+            }
+            // LowConfidence / Skipped → render with informational marker only.
+            if (cat === AdoptionCategory.LowConfidence || cat === AdoptionCategory.Skipped) {
+                blocks.push({
+                    kind: OnboardDiffBlockKind.ManualReview,
+                    targetFile: target,
+                    targetExists,
+                    adoptionKind: item.kind,
+                    title: `${item.id} (${cat})`,
+                    notes: [item.reason],
+                    lines: [],
+                });
+                continue;
+            }
+        }
+    }
+    return blocks;
+}
+export function buildOnboardAdoptionDiff(inspection, options = {}) {
+    const plan = buildOnboardingPlan(inspection, {});
+    const adoption = buildOnboardingAdoptionPlan({
+        inspection,
+        plan,
+        ...(options.confidence ? { confidence: options.confidence } : {}),
+        ...(options.include ? { include: options.include } : {}),
+        ...(options.exclude ? { exclude: options.exclude } : {}),
+    });
+    const blocks = buildBlocks(inspection, adoption);
+    const summary = {
+        newBlocks: blocks.filter((b) => b.kind === OnboardDiffBlockKind.NewBlock).length,
+        alreadyExists: blocks.filter((b) => b.kind === OnboardDiffBlockKind.AlreadyExists).length,
+        conflicts: blocks.filter((b) => b.kind === OnboardDiffBlockKind.Conflict).length,
+        manualReview: blocks.filter((b) => b.kind === OnboardDiffBlockKind.ManualReview).length,
+    };
+    const warnings = [];
+    for (const k of Object.values(AdoptionKind)) {
+        const target = targetFor(k);
+        const full = nodePath.resolve(inspection.projectRoot, target);
+        if (!existsSync(full)) {
+            warnings.push(`Target file ${target} does not exist — patch would create it.`);
+        }
+        else {
+            // Quick sanity: load and confirm it's a TS file we recognize. Don't fail
+            // hard — onboarding has its own draft loader for the actual semantics.
+            try {
+                readFileSync(full, 'utf8');
+            }
+            catch {
+                warnings.push(`Cannot read ${target}.`);
+            }
+        }
+    }
+    return {
+        schema: ONBOARD_ADOPTION_DIFF_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        projectRoot: inspection.projectRoot,
+        blocks,
+        summary,
+        warnings: [...new Set(warnings)],
+    };
+}
+export function renderOnboardAdoptionDiffText(diff) {
+    const lines = [];
+    lines.push(`Onboard adoption diff — generated ${diff.generatedAt}`);
+    lines.push(`Summary: +blocks=${diff.summary.newBlocks}  ~review=${diff.summary.manualReview}  conflicts=${diff.summary.conflicts}  covered=${diff.summary.alreadyExists}`);
+    for (const b of diff.blocks) {
+        lines.push('');
+        lines.push(`-- ${b.title} [${b.kind} → ${b.targetFile}${b.targetExists ? '' : ' (new)'}]`);
+        for (const n of b.notes ?? [])
+            lines.push(`   note: ${n}`);
+        for (const ln of b.lines)
+            lines.push(`${ln.marker} ${ln.text}`);
+    }
+    if (diff.warnings.length > 0) {
+        lines.push('');
+        lines.push('Warnings:');
+        for (const w of diff.warnings)
+            lines.push(`  ! ${w}`);
+    }
+    return lines.join('\n') + '\n';
+}
+export function renderOnboardAdoptionDiffMarkdown(diff) {
+    const lines = [];
+    lines.push('# Onboard adoption diff');
+    lines.push('');
+    lines.push(`Generated: ${diff.generatedAt}`);
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- Append blocks: ${diff.summary.newBlocks}`);
+    lines.push(`- Manual review: ${diff.summary.manualReview}`);
+    lines.push(`- Conflicts: ${diff.summary.conflicts}`);
+    lines.push(`- Already exists: ${diff.summary.alreadyExists}`);
+    lines.push('');
+    for (const b of diff.blocks) {
+        lines.push(`## ${b.title} _[${b.kind}]_`);
+        lines.push('');
+        lines.push(`Target: \`${b.targetFile}\`${b.targetExists ? '' : ' _(new file)_'}`);
+        if (b.notes && b.notes.length > 0) {
+            for (const n of b.notes)
+                lines.push(`- ${n}`);
+            lines.push('');
+        }
+        if (b.lines.length > 0) {
+            lines.push('```diff');
+            for (const ln of b.lines)
+                lines.push(`${ln.marker} ${ln.text}`);
+            lines.push('```');
+            lines.push('');
+        }
+    }
+    if (diff.warnings.length > 0) {
+        lines.push('## Warnings');
+        lines.push('');
+        for (const w of diff.warnings)
+            lines.push(`- ${w}`);
+        lines.push('');
+    }
+    lines.push('## Next steps');
+    lines.push('');
+    lines.push('SharkCraft never modifies your live `sharkcraft/*.ts` files automatically.');
+    lines.push('Run `shrk onboard adopt --write-patch` and review the patch before applying.');
+    return lines.join('\n') + '\n';
+}
+export function renderOnboardAdoptionDiffHtml(diff) {
+    const out = [];
+    out.push('<!doctype html><html><head><meta charset="utf-8"><title>Onboard adoption diff</title>');
+    out.push('<style>');
+    out.push('body{font:14px/1.5 -apple-system,system-ui,sans-serif;max-width:920px;margin:24px auto;padding:0 16px;color:#1a1a1a;background:#fff}');
+    out.push('h1{font-size:24px;margin-bottom:8px}h2{font-size:18px;margin-top:24px;border-bottom:1px solid #e1e4e8;padding-bottom:4px}');
+    out.push('.diff{background:#f7f7f9;border:1px solid #d0d0d6;border-radius:6px;padding:8px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px;white-space:pre;overflow-x:auto}');
+    out.push('.add{color:#22863a;background:#eaffea;display:block}.del{color:#b31d28;background:#ffeef0;display:block}.ctx{color:#586069;display:block}.cnf{color:#b08800;background:#fff8d6;display:block}');
+    out.push('.muted{color:#586069}.tag{display:inline-block;padding:2px 6px;border-radius:4px;font-size:11px;background:#eef2f6}');
+    out.push('@media (prefers-color-scheme: dark){body{background:#0d1117;color:#c9d1d9}.diff{background:#161b22;border-color:#30363d}.add{background:#0c3a1c}.del{background:#3d1a1e}.cnf{background:#3a2f0c}.muted{color:#8b949e}.tag{background:#21262d}}');
+    out.push('</style></head><body>');
+    out.push('<h1>Onboard adoption diff</h1>');
+    out.push(`<p class="muted">Generated ${esc(diff.generatedAt)}</p>`);
+    out.push(`<p>Summary: +blocks=${diff.summary.newBlocks} · ~review=${diff.summary.manualReview} · conflicts=${diff.summary.conflicts} · covered=${diff.summary.alreadyExists}</p>`);
+    for (const b of diff.blocks) {
+        out.push(`<h2>${esc(b.title)} <span class="tag">${esc(b.kind)}</span></h2>`);
+        out.push(`<p class="muted">Target: <code>${esc(b.targetFile)}</code>${b.targetExists ? '' : ' <em>(new file)</em>'}</p>`);
+        if (b.notes && b.notes.length > 0) {
+            out.push('<ul>');
+            for (const n of b.notes)
+                out.push(`<li>${esc(n)}</li>`);
+            out.push('</ul>');
+        }
+        if (b.lines.length > 0) {
+            out.push('<div class="diff">');
+            for (const ln of b.lines) {
+                const cls = ln.marker === '+' ? 'add' : ln.marker === '-' ? 'del' : ln.marker === '~' ? 'cnf' : 'ctx';
+                out.push(`<span class="${cls}">${esc(ln.marker + ' ' + ln.text)}</span>`);
+            }
+            out.push('</div>');
+        }
+    }
+    if (diff.warnings.length > 0) {
+        out.push('<h2>Warnings</h2><ul>');
+        for (const w of diff.warnings)
+            out.push(`<li>${esc(w)}</li>`);
+        out.push('</ul>');
+    }
+    out.push('<p class="muted">SharkCraft never modifies your live <code>sharkcraft/*.ts</code> files. Run <code>shrk onboard adopt --write-patch</code> to render a patch under <code>sharkcraft/onboarding/adoption/</code>.</p>');
+    out.push('</body></html>');
+    return out.join('\n') + '\n';
+}
+export function renderOnboardAdoptionDiff(diff, format) {
+    if (format === 'markdown')
+        return renderOnboardAdoptionDiffMarkdown(diff);
+    if (format === 'html')
+        return renderOnboardAdoptionDiffHtml(diff);
+    if (format === 'json')
+        return JSON.stringify(diff, null, 2) + '\n';
+    return renderOnboardAdoptionDiffText(diff);
+}