@shrkcrft/inspector 0.1.0-alpha.2

package/dist/compliance-profiles.d.ts

@@ -0,0 +1,42 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const COMPLIANCE_SCHEMA = "sharkcraft.compliance/v1";
+export interface IComplianceProfile {
+    id: string;
+    title: string;
+    description: string;
+    tags: readonly string[];
+    requiredDocs: readonly string[];
+    requiredCommands: readonly string[];
+    requiredOwnership: boolean;
+    requiredQualityThresholds: {
+        minDoctorOk?: number;
+        minAiReadiness?: number;
+    };
+    requiredPackSignatures: boolean;
+    requiredMcpReadOnly: boolean;
+}
+export interface IComplianceCheckFinding {
+    profileId: string;
+    ruleId: string;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    evidence?: string;
+}
+export interface IComplianceCheckReport {
+    schema: typeof COMPLIANCE_SCHEMA;
+    generatedAt: string;
+    profileId: string;
+    pass: boolean;
+    findings: readonly IComplianceCheckFinding[];
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+    };
+}
+export declare const BUILTIN_COMPLIANCE_PROFILES: readonly IComplianceProfile[];
+export declare function listComplianceProfiles(): readonly IComplianceProfile[];
+export declare function getComplianceProfile(id: string): IComplianceProfile | undefined;
+export declare function runComplianceCheck(inspection: ISharkcraftInspection, profileId: string): Promise<IComplianceCheckReport>;
+export declare function renderComplianceReportText(report: IComplianceCheckReport): string;
+//# sourceMappingURL=compliance-profiles.d.ts.map

package/dist/compliance-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compliance-profiles.d.ts","sourceRoot":"","sources":["../src/compliance-profiles.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,yBAAyB,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7E,sBAAsB,EAAE,OAAO,CAAC;IAChC,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC7C,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,eAAO,MAAM,2BAA2B,EAAE,SAAS,kBAAkB,EAiDnE,CAAC;AAEH,wBAAgB,sBAAsB,IAAI,SAAS,kBAAkB,EAAE,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE/E;AAED,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,qBAAqB,EACjC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,sBAAsB,CAAC,CAsFjC;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAejF"}

package/dist/compliance-profiles.js

@@ -0,0 +1,171 @@
+/**
+ * Local-first compliance profiles.
+ *
+ * Not legal advice, not external standards certification. Structured
+ * local checks: required policies, boundaries, docs, commands,
+ * ownership, quality thresholds, pack signatures.
+ *
+ * Built-in profiles:
+ * - ai-safe-development
+ * - signed-pack-workflow
+ * - review-gated-codegen
+ * - ci-governed-repository
+ */
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const COMPLIANCE_SCHEMA = 'sharkcraft.compliance/v1';
+export const BUILTIN_COMPLIANCE_PROFILES = Object.freeze([
+    {
+        id: 'ai-safe-development',
+        title: 'AI-safe development',
+        description: 'MCP is read-only, plans are reviewed, demo is non-destructive, dashboard has no write endpoints.',
+        tags: ['safety', 'mcp', 'ai-agent'],
+        requiredDocs: ['docs/safety-model.md'],
+        requiredCommands: ['shrk safety audit', 'shrk doctor'],
+        requiredOwnership: false,
+        requiredQualityThresholds: {},
+        requiredPackSignatures: false,
+        requiredMcpReadOnly: true,
+    },
+    {
+        id: 'signed-pack-workflow',
+        title: 'Signed pack workflow',
+        description: 'Discovered packs all carry verified HMAC signatures.',
+        tags: ['pack', 'signing'],
+        requiredDocs: ['docs/security.md'],
+        requiredCommands: ['shrk packs doctor --release --require-signatures'],
+        requiredOwnership: false,
+        requiredQualityThresholds: {},
+        requiredPackSignatures: true,
+        requiredMcpReadOnly: false,
+    },
+    {
+        id: 'review-gated-codegen',
+        title: 'Review-gated codegen',
+        description: 'Generation is dry-run by default; apply requires signature verification.',
+        tags: ['generation', 'review'],
+        requiredDocs: ['docs/plan-review.md', 'docs/safety-model.md'],
+        requiredCommands: ['shrk plan review', 'shrk apply --verify-signature'],
+        requiredOwnership: false,
+        requiredQualityThresholds: {},
+        requiredPackSignatures: false,
+        requiredMcpReadOnly: true,
+    },
+    {
+        id: 'ci-governed-repository',
+        title: 'CI-governed repository',
+        description: 'CI scaffolds + release readiness + preflight gates are documented and validated.',
+        tags: ['ci', 'release', 'governance'],
+        requiredDocs: ['docs/ci-scaffold.md', 'docs/release-readiness.md'],
+        requiredCommands: ['shrk release readiness --strict', 'bun run release:preflight'],
+        requiredOwnership: false,
+        requiredQualityThresholds: {},
+        requiredPackSignatures: false,
+        requiredMcpReadOnly: false,
+    },
+]);
+export function listComplianceProfiles() {
+    return BUILTIN_COMPLIANCE_PROFILES;
+}
+export function getComplianceProfile(id) {
+    return BUILTIN_COMPLIANCE_PROFILES.find((p) => p.id === id);
+}
+export async function runComplianceCheck(inspection, profileId) {
+    const profile = getComplianceProfile(profileId);
+    if (!profile) {
+        return {
+            schema: COMPLIANCE_SCHEMA,
+            generatedAt: new Date().toISOString(),
+            profileId,
+            pass: false,
+            findings: [
+                {
+                    profileId,
+                    ruleId: 'unknown-profile',
+                    severity: 'error',
+                    message: `Compliance profile "${profileId}" not found. Use \`shrk compliance profiles\`.`,
+                },
+            ],
+            summary: { errors: 1, warnings: 0, info: 0 },
+        };
+    }
+    const findings = [];
+    // Required docs.
+    for (const d of profile.requiredDocs) {
+        const abs = nodePath.join(inspection.projectRoot, d);
+        if (!existsSync(abs)) {
+            findings.push({
+                profileId: profile.id,
+                ruleId: `required-doc:${d}`,
+                severity: 'warning',
+                message: `Required doc missing: ${d}`,
+                evidence: abs,
+            });
+        }
+    }
+    // MCP read-only contract — info only; the canonical check is the
+    // separate `shrk safety audit` command, which has access to the MCP
+    // tool list. We surface a hint here so adopters know to run it.
+    if (profile.requiredMcpReadOnly) {
+        findings.push({
+            profileId: profile.id,
+            ruleId: 'mcp-no-write-hint',
+            severity: 'info',
+            message: 'Run `shrk safety audit` to confirm MCP has zero write tools (this profile requires it).',
+        });
+    }
+    // Pack signatures — only checks discovered packs.
+    if (profile.requiredPackSignatures) {
+        for (const p of inspection.packs.validPacks ?? []) {
+            const status = p.signatureStatus ?? 'not-checked';
+            if (status === 'invalid-signature' || status === 'missing-signature') {
+                findings.push({
+                    profileId: profile.id,
+                    ruleId: `pack-signature:${p.packageName}`,
+                    severity: 'error',
+                    message: `Pack ${p.packageName} signature status: ${status}.`,
+                });
+            }
+            else if (status === 'not-checked') {
+                findings.push({
+                    profileId: profile.id,
+                    ruleId: `pack-signature:${p.packageName}`,
+                    severity: 'warning',
+                    message: `Pack ${p.packageName} signature was not verified — re-run with --require-signatures.`,
+                });
+            }
+        }
+    }
+    // Required-commands check is a docstring check — the commands must
+    // exist in the catalog. We don't run them.
+    // (Catalog parity is exercised separately by `shrk commands doctor`.)
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    const warnings = findings.filter((f) => f.severity === 'warning').length;
+    const info = findings.filter((f) => f.severity === 'info').length;
+    return {
+        schema: COMPLIANCE_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        profileId,
+        pass: errors === 0,
+        findings,
+        summary: { errors, warnings, info },
+    };
+}
+export function renderComplianceReportText(report) {
+    const lines = [];
+    lines.push(`=== Compliance: ${report.profileId} ===`);
+    lines.push(`  pass     ${report.pass ? 'yes' : 'no'}`);
+    lines.push(`  errors   ${report.summary.errors}`);
+    lines.push(`  warnings ${report.summary.warnings}`);
+    if (report.findings.length === 0) {
+        lines.push('No findings.');
+    }
+    else {
+        for (const f of report.findings) {
+            lines.push(`  [${f.severity.padEnd(7)}] ${f.ruleId} — ${f.message}`);
+            if (f.evidence)
+                lines.push(`    evidence: ${f.evidence}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}

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

@@ -0,0 +1,55 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const CONSTRUCT_ADOPTION_DIFF_SCHEMA = "sharkcraft.construct-adoption-diff/v1";
+export type ConstructAdoptionDiffFormat = 'text' | 'markdown' | 'html' | 'json';
+export declare enum ConstructDiffBlockKind {
+    NewConstruct = "new-construct",
+    NewFacet = "new-facet",
+    FieldAdded = "field-added",
+    FieldConflict = "field-conflict",
+    AlreadyCovered = "already-covered",
+    Conflict = "conflict"
+}
+export interface IConstructDiffLine {
+    /** `'+'` add, `'-'` remove, `' '` context, `'~'` conflict marker. */
+    marker: '+' | '-' | ' ' | '~';
+    text: string;
+}
+export interface IConstructDiffBlock {
+    kind: ConstructDiffBlockKind;
+    /** Construct id this block belongs to. */
+    constructId: string;
+    /** Optional facet sub-id (when kind is NewFacet). */
+    facetKind?: string;
+    /** A short title for human readers. */
+    title: string;
+    /** Optional notes / reasons. */
+    notes?: readonly string[];
+    /** Line-level preview. Empty when the block is purely informational. */
+    lines: readonly IConstructDiffLine[];
+}
+export interface IConstructAdoptionDiff {
+    schema: typeof CONSTRUCT_ADOPTION_DIFF_SCHEMA;
+    generatedAt: string;
+    projectRoot: string;
+    constructsFile: string | null;
+    /** Whether the live constructs.ts exists at the moment of generation. */
+    constructsFileExists: boolean;
+    /** Whole-file preview of the proposed constructs.ts (or unchanged when none). */
+    proposedFilePreview: string;
+    blocks: readonly IConstructDiffBlock[];
+    summary: {
+        newConstructs: number;
+        newFacets: number;
+        fieldsAdded: number;
+        fieldConflicts: number;
+        alreadyCovered: number;
+        conflicts: number;
+    };
+    warnings: readonly string[];
+}
+export declare function buildConstructAdoptionDiff(inspection: ISharkcraftInspection): Promise<IConstructAdoptionDiff>;
+export declare function renderConstructAdoptionDiffText(diff: IConstructAdoptionDiff): string;
+export declare function renderConstructAdoptionDiffMarkdown(diff: IConstructAdoptionDiff): string;
+export declare function renderConstructAdoptionDiffHtml(diff: IConstructAdoptionDiff): string;
+export declare function renderConstructAdoptionDiff(diff: IConstructAdoptionDiff, format: ConstructAdoptionDiffFormat): string;
+//# sourceMappingURL=construct-adoption-diff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"construct-adoption-diff.d.ts","sourceRoot":"","sources":["../src/construct-adoption-diff.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,8BAA8B,0CAA0C,CAAC;AAEtF,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhF,oBAAY,sBAAsB;IAChC,YAAY,kBAAkB;IAC9B,QAAQ,cAAc;IACtB,UAAU,gBAAgB;IAC1B,aAAa,mBAAmB;IAChC,cAAc,oBAAoB;IAClC,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,wEAAwE;IACxE,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,8BAA8B,CAAC;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,oBAAoB,EAAE,OAAO,CAAC;IAC9B,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACvC,OAAO,EAAE;QACP,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AA8KD,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,sBAAsB,CAAC,CA2CjC;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAmBpF;AAED,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAuCxF;AAED,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAwCpF;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,sBAAsB,EAC5B,MAAM,EAAE,2BAA2B,GAClC,MAAM,CAKR"}

package/dist/construct-adoption-diff.js

@@ -0,0 +1,331 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildConstructAdoptionPlan, ConstructAdoptionCategory, } from "./construct-adoption.js";
+import { listConstructs } from "./construct-registry.js";
+export const CONSTRUCT_ADOPTION_DIFF_SCHEMA = 'sharkcraft.construct-adoption-diff/v1';
+export var ConstructDiffBlockKind;
+(function (ConstructDiffBlockKind) {
+    ConstructDiffBlockKind["NewConstruct"] = "new-construct";
+    ConstructDiffBlockKind["NewFacet"] = "new-facet";
+    ConstructDiffBlockKind["FieldAdded"] = "field-added";
+    ConstructDiffBlockKind["FieldConflict"] = "field-conflict";
+    ConstructDiffBlockKind["AlreadyCovered"] = "already-covered";
+    ConstructDiffBlockKind["Conflict"] = "conflict";
+})(ConstructDiffBlockKind || (ConstructDiffBlockKind = {}));
+function esc(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/** Render an inferred construct entry as a TypeScript object literal — only
+ *  the fields we know about, never speculative ones. */
+function renderConstructLiteral(entry) {
+    const lines = [];
+    lines.push('{');
+    lines.push(`  id: '${entry.id}',`);
+    lines.push(`  type: '${entry.type}',`);
+    lines.push(`  title: '${entry.title.replace(/'/g, "\\'")}',`);
+    const files = entry.inferred.files ?? [];
+    if (files.length > 0) {
+        lines.push(`  files: [${files.map((f) => "'" + f + "'").join(', ')}],`);
+    }
+    const publicApi = entry.inferred.publicApi ?? [];
+    if (publicApi.length > 0) {
+        lines.push(`  publicApi: [${publicApi.map((a) => "'" + a + "'").join(', ')}],`);
+    }
+    const events = entry.inferred.events ?? [];
+    if (events.length > 0) {
+        lines.push(`  events: [${events.map((e) => "'" + e + "'").join(', ')}],`);
+    }
+    const tokens = entry.inferred.tokens ?? [];
+    if (tokens.length > 0) {
+        lines.push(`  tokens: [${tokens.map((t) => "'" + t + "'").join(', ')}],`);
+    }
+    lines.push('},');
+    return lines;
+}
+function buildBlocks(plan, existingById) {
+    const blocks = [];
+    for (const entry of plan.entries) {
+        if (entry.category === ConstructAdoptionCategory.AlreadyCovered) {
+            blocks.push({
+                kind: ConstructDiffBlockKind.AlreadyCovered,
+                constructId: entry.id,
+                title: `${entry.id} is already covered`,
+                notes: entry.reasons,
+                lines: [],
+            });
+            continue;
+        }
+        if (entry.category === ConstructAdoptionCategory.Conflict) {
+            const existing = existingById.get(entry.id);
+            const lines = [];
+            if (existing) {
+                lines.push({ marker: '-', text: `existing type: ${existing.type}` });
+            }
+            lines.push({ marker: '+', text: `inferred type: ${entry.type}` });
+            lines.push({ marker: '~', text: `id collision — manual review required` });
+            blocks.push({
+                kind: ConstructDiffBlockKind.Conflict,
+                constructId: entry.id,
+                title: `${entry.id} CONFLICT`,
+                notes: entry.reasons,
+                lines,
+            });
+            continue;
+        }
+        const existing = existingById.get(entry.id);
+        if (!existing) {
+            const literal = renderConstructLiteral(entry);
+            const lines = literal.map((l) => ({ marker: '+', text: l }));
+            blocks.push({
+                kind: ConstructDiffBlockKind.NewConstruct,
+                constructId: entry.id,
+                title: `Add construct ${entry.id} (${entry.type})`,
+                notes: entry.reasons,
+                lines,
+            });
+            continue;
+        }
+        // Existing construct, same type → diff additive fields field-by-field.
+        const existingFiles = new Set(existing.files ?? []);
+        const newFiles = (entry.inferred.files ?? []).filter((f) => !existingFiles.has(f));
+        if (newFiles.length > 0) {
+            blocks.push({
+                kind: ConstructDiffBlockKind.FieldAdded,
+                constructId: entry.id,
+                title: `Add files to ${entry.id}`,
+                lines: newFiles.map((f) => ({ marker: '+', text: `  '${f}',` })),
+            });
+        }
+        const existingApi = new Set(existing.publicApi ?? []);
+        const newApi = (entry.inferred.publicApi ?? []).filter((a) => !existingApi.has(a));
+        if (newApi.length > 0) {
+            blocks.push({
+                kind: ConstructDiffBlockKind.FieldAdded,
+                constructId: entry.id,
+                title: `Add publicApi entries to ${entry.id}`,
+                lines: newApi.map((a) => ({ marker: '+', text: `  '${a}',` })),
+            });
+        }
+        const existingEvents = new Set(existing.events ?? []);
+        const newEvents = (entry.inferred.events ?? []).filter((e) => !existingEvents.has(e));
+        if (newEvents.length > 0) {
+            blocks.push({
+                kind: ConstructDiffBlockKind.FieldAdded,
+                constructId: entry.id,
+                title: `Add events to ${entry.id}`,
+                lines: newEvents.map((e) => ({ marker: '+', text: `  '${e}',` })),
+            });
+        }
+        const existingTokens = new Set(existing.tokens ?? []);
+        const newTokens = (entry.inferred.tokens ?? []).filter((t) => !existingTokens.has(t));
+        if (newTokens.length > 0) {
+            blocks.push({
+                kind: ConstructDiffBlockKind.FieldAdded,
+                constructId: entry.id,
+                title: `Add tokens to ${entry.id}`,
+                lines: newTokens.map((t) => ({ marker: '+', text: `  '${t}',` })),
+            });
+        }
+        // Title conflict — flag if the inferred title differs from the live one.
+        if (existing.title && entry.title && existing.title !== entry.title) {
+            blocks.push({
+                kind: ConstructDiffBlockKind.FieldConflict,
+                constructId: entry.id,
+                title: `${entry.id} title differs`,
+                lines: [
+                    { marker: '-', text: `title: '${existing.title}'` },
+                    { marker: '+', text: `title: '${entry.title}'` },
+                    { marker: '~', text: 'manual review — pick one' },
+                ],
+            });
+        }
+    }
+    return blocks;
+}
+function renderProposedFilePreview(existingSource, plan) {
+    // Only render literals for entries that aren't already-covered/conflict so the
+    // preview matches what `--write-patch` would suggest copying in.
+    const additions = plan.entries.filter((e) => e.category !== ConstructAdoptionCategory.AlreadyCovered &&
+        e.category !== ConstructAdoptionCategory.Conflict);
+    if (additions.length === 0) {
+        return existingSource ?? '';
+    }
+    const additionBlock = additions
+        .map((e) => '  ' + renderConstructLiteral(e).join('\n  '))
+        .join('\n');
+    if (!existingSource) {
+        return [
+            "import { defineConstruct } from '@shrkcrft/plugin-api';",
+            '',
+            'export default [',
+            additionBlock,
+            '];',
+            '',
+        ].join('\n');
+    }
+    // Naive: append before the trailing `];` or just at the end.
+    const trimmed = existingSource.replace(/\n+$/, '');
+    return [trimmed, '// Added by `shrk constructs adopt --write-patch`:', additionBlock, ''].join('\n');
+}
+export async function buildConstructAdoptionDiff(inspection) {
+    const plan = await buildConstructAdoptionPlan(inspection);
+    const existing = listConstructs(inspection);
+    const existingById = new Map();
+    for (const c of existing)
+        existingById.set(c.id, c);
+    const constructsFile = inspection.sharkcraftDir
+        ? nodePath.join(inspection.sharkcraftDir, 'constructs.ts')
+        : null;
+    const exists = !!constructsFile && existsSync(constructsFile);
+    let existingSource = null;
+    if (exists && constructsFile) {
+        try {
+            existingSource = readFileSync(constructsFile, 'utf8');
+        }
+        catch {
+            existingSource = null;
+        }
+    }
+    const blocks = buildBlocks(plan, existingById);
+    const summary = {
+        newConstructs: blocks.filter((b) => b.kind === ConstructDiffBlockKind.NewConstruct).length,
+        newFacets: blocks.filter((b) => b.kind === ConstructDiffBlockKind.NewFacet).length,
+        fieldsAdded: blocks.filter((b) => b.kind === ConstructDiffBlockKind.FieldAdded).length,
+        fieldConflicts: blocks.filter((b) => b.kind === ConstructDiffBlockKind.FieldConflict).length,
+        alreadyCovered: blocks.filter((b) => b.kind === ConstructDiffBlockKind.AlreadyCovered).length,
+        conflicts: blocks.filter((b) => b.kind === ConstructDiffBlockKind.Conflict).length,
+    };
+    const warnings = [...plan.warnings];
+    if (!exists && constructsFile) {
+        warnings.push(`No live constructs.ts yet at ${constructsFile} — diff shows a clean creation.`);
+    }
+    return {
+        schema: CONSTRUCT_ADOPTION_DIFF_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        projectRoot: inspection.projectRoot,
+        constructsFile,
+        constructsFileExists: exists,
+        proposedFilePreview: renderProposedFilePreview(existingSource, plan),
+        blocks,
+        summary,
+        warnings,
+    };
+}
+export function renderConstructAdoptionDiffText(diff) {
+    const lines = [];
+    lines.push(`Construct adoption diff — generated ${diff.generatedAt}`);
+    lines.push(`Live constructs.ts: ${diff.constructsFile ?? '(no sharkcraft dir)'}`);
+    lines.push(`Summary: +constructs=${diff.summary.newConstructs}  +fields=${diff.summary.fieldsAdded}  ~conflicts=${diff.summary.conflicts}  covered=${diff.summary.alreadyCovered}`);
+    for (const b of diff.blocks) {
+        lines.push('');
+        lines.push(`-- ${b.title} [${b.kind}]`);
+        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 renderConstructAdoptionDiffMarkdown(diff) {
+    const lines = [];
+    lines.push('# Construct adoption diff');
+    lines.push('');
+    lines.push(`Generated: ${diff.generatedAt}`);
+    lines.push(`Live constructs.ts: \`${diff.constructsFile ?? '(none)'}\``);
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- New constructs: ${diff.summary.newConstructs}`);
+    lines.push(`- Fields added to existing: ${diff.summary.fieldsAdded}`);
+    lines.push(`- Conflicts: ${diff.summary.conflicts}`);
+    lines.push(`- Already covered: ${diff.summary.alreadyCovered}`);
+    lines.push('');
+    for (const b of diff.blocks) {
+        lines.push(`## ${b.title} _[${b.kind}]_`);
+        lines.push('');
+        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 `constructs.ts` automatically.');
+    lines.push('Copy entries from the proposed file preview into your `sharkcraft/constructs.ts`.');
+    return lines.join('\n') + '\n';
+}
+export function renderConstructAdoptionDiffHtml(diff) {
+    const out = [];
+    out.push('<!doctype html><html><head><meta charset="utf-8"><title>Construct 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>Construct adoption diff</h1>');
+    out.push(`<p class="muted">Generated ${esc(diff.generatedAt)} — Live <code>${esc(diff.constructsFile ?? '(none)')}</code></p>`);
+    out.push(`<p>Summary: +constructs=${diff.summary.newConstructs} · +fields=${diff.summary.fieldsAdded} · ~conflicts=${diff.summary.conflicts} · covered=${diff.summary.alreadyCovered}</p>`);
+    for (const b of diff.blocks) {
+        out.push(`<h2>${esc(b.title)} <span class="tag">${esc(b.kind)}</span></h2>`);
+        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 <code>constructs.ts</code> automatically. Copy the highlighted entries into your config when you are ready.</p>');
+    out.push('</body></html>');
+    return out.join('\n') + '\n';
+}
+export function renderConstructAdoptionDiff(diff, format) {
+    if (format === 'markdown')
+        return renderConstructAdoptionDiffMarkdown(diff);
+    if (format === 'html')
+        return renderConstructAdoptionDiffHtml(diff);
+    if (format === 'json')
+        return JSON.stringify(diff, null, 2) + '\n';
+    return renderConstructAdoptionDiffText(diff);
+}