@shrkcrft/inspector 0.1.0-alpha.1

package/dist/ingest-adoption.js

@@ -0,0 +1,183 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const INGEST_ADOPTION_SCHEMA = 'sharkcraft.ingest-adoption/v1';
+export var IngestAdoptionStatus;
+(function (IngestAdoptionStatus) {
+    IngestAdoptionStatus["SafeAppend"] = "safe-append";
+    IngestAdoptionStatus["ManualReview"] = "manual-review";
+    IngestAdoptionStatus["LowConfidence"] = "low-confidence";
+    IngestAdoptionStatus["AlreadyCovered"] = "already-covered";
+    IngestAdoptionStatus["GeneratedProtected"] = "generated-protected";
+})(IngestAdoptionStatus || (IngestAdoptionStatus = {}));
+const LIVE_FILES = [
+    'sharkcraft/rules.ts',
+    'sharkcraft/paths.ts',
+    'sharkcraft/templates.ts',
+    'sharkcraft/pipelines.ts',
+    'sharkcraft/boundaries.ts',
+    'sharkcraft/knowledge.ts',
+    'sharkcraft/constructs.ts',
+    'sharkcraft/policies.ts',
+    'sharkcraft/playbooks.ts',
+    'sharkcraft/presets.ts',
+];
+export function buildIngestAdoptionPlan(options) {
+    const model = options.model;
+    const excluded = new Set(options.excludeTargets ?? []);
+    const entries = [];
+    const counts = {
+        [IngestAdoptionStatus.SafeAppend]: 0,
+        [IngestAdoptionStatus.ManualReview]: 0,
+        [IngestAdoptionStatus.LowConfidence]: 0,
+        [IngestAdoptionStatus.AlreadyCovered]: 0,
+        [IngestAdoptionStatus.GeneratedProtected]: 0,
+    };
+    const liveContent = readLiveFiles(model.projectRoot);
+    const generatedPathSet = new Set();
+    for (const root of model.generatedVsHandwritten.generatedRoots)
+        generatedPathSet.add(root.path);
+    for (const file of model.recommendedSharkCraftFiles) {
+        if (excluded.has(file.target))
+            continue;
+        const liveBody = liveContent.get(file.target) ?? '';
+        for (const entry of file.entries) {
+            const isGenerated = isUnderGenerated(entry.id, generatedPathSet);
+            let status;
+            if (isGenerated) {
+                status = IngestAdoptionStatus.GeneratedProtected;
+            }
+            else if (liveBody.includes(`'${entry.id}'`) || liveBody.includes(`"${entry.id}"`)) {
+                status = IngestAdoptionStatus.AlreadyCovered;
+            }
+            else if ((entry.reason ?? '').toLowerCase().includes('low confidence')) {
+                status = IngestAdoptionStatus.LowConfidence;
+            }
+            else if (options.strict !== false && needsManualReview(file.target, entry.kind)) {
+                status = IngestAdoptionStatus.ManualReview;
+            }
+            else {
+                status = IngestAdoptionStatus.SafeAppend;
+            }
+            entries.push({
+                target: file.target,
+                kind: entry.kind,
+                id: entry.id,
+                status,
+                reason: entry.reason,
+            });
+            counts[status] += 1;
+        }
+    }
+    const reviewRequired = counts[IngestAdoptionStatus.ManualReview] > 0 || counts[IngestAdoptionStatus.LowConfidence] > 0;
+    return {
+        schema: INGEST_ADOPTION_SCHEMA,
+        projectRoot: model.projectRoot,
+        entries,
+        counts,
+        reviewRequired,
+    };
+}
+export function writeIngestAdoption(opts) {
+    const outDir = nodePath.resolve(opts.outDir ?? nodePath.join(opts.plan.projectRoot, 'sharkcraft', 'ingestion', 'adoption'));
+    if (!existsSync(outDir))
+        mkdirSync(outDir, { recursive: true });
+    const files = [];
+    const write = (rel, body) => {
+        const full = nodePath.join(outDir, rel);
+        if (!full.startsWith(outDir + nodePath.sep))
+            throw new Error(`escapes outDir: ${rel}`);
+        writeFileSync(full, body, 'utf8');
+        files.push({ path: full, bytes: Buffer.byteLength(body, 'utf8') });
+    };
+    write('ingest-adoption-state.json', JSON.stringify(opts.plan, null, 2));
+    write('ingest-adopt-summary.json', JSON.stringify({
+        schema: 'sharkcraft.ingest-adopt-summary/v1',
+        counts: opts.plan.counts,
+        reviewRequired: opts.plan.reviewRequired,
+    }, null, 2));
+    write('ingest-adoption-plan.md', renderIngestAdoptionPlanMarkdown(opts.plan));
+    write('ingest-adopt.patch', renderIngestAdoptionPatch(opts.plan));
+    return { outDir, files };
+}
+function readLiveFiles(projectRoot) {
+    const out = new Map();
+    for (const rel of LIVE_FILES) {
+        const abs = nodePath.join(projectRoot, rel);
+        if (existsSync(abs)) {
+            try {
+                out.set(rel, readFileSync(abs, 'utf8'));
+            }
+            catch {
+                out.set(rel, '');
+            }
+        }
+        else {
+            out.set(rel, '');
+        }
+    }
+    return out;
+}
+function isUnderGenerated(id, generatedPaths) {
+    for (const p of generatedPaths) {
+        if (id.includes(p))
+            return true;
+    }
+    return false;
+}
+function needsManualReview(target, kind) {
+    if (target === 'sharkcraft/templates.ts')
+        return true; // Always manual.
+    if (target === 'sharkcraft/policies.ts' && kind === 'policy')
+        return false; // Safe append.
+    if (target === 'sharkcraft/boundaries.ts')
+        return false; // Safe append.
+    if (target === 'sharkcraft/constructs.ts')
+        return false; // Safe append.
+    return false;
+}
+export function renderIngestAdoptionPlanMarkdown(plan) {
+    const lines = [];
+    lines.push('# Ingest adoption plan');
+    lines.push('');
+    lines.push(`Review required: **${plan.reviewRequired ? 'yes' : 'no'}**`);
+    lines.push('');
+    lines.push('| Status | Count |');
+    lines.push('|---|---|');
+    for (const [k, v] of Object.entries(plan.counts))
+        lines.push(`| ${k} | ${v} |`);
+    lines.push('');
+    lines.push('## Entries');
+    lines.push('');
+    lines.push('| Target | Kind | Id | Status | Reason |');
+    lines.push('|---|---|---|---|---|');
+    for (const e of plan.entries) {
+        lines.push(`| \`${e.target}\` | ${e.kind} | \`${e.id}\` | ${e.status} | ${e.reason} |`);
+    }
+    return lines.join('\n');
+}
+export function renderIngestAdoptionPatch(plan) {
+    const lines = [];
+    lines.push('# Generated by `shrk ingest adopt --write-patch`. Apply manually:');
+    lines.push('# 1) Review each block.');
+    lines.push('# 2) Copy the safe-append blocks into the corresponding sharkcraft/*.ts file.');
+    lines.push('# 3) Resolve manual-review entries by hand.');
+    lines.push('');
+    const grouped = new Map();
+    for (const e of plan.entries) {
+        if (e.status === IngestAdoptionStatus.GeneratedProtected || e.status === IngestAdoptionStatus.AlreadyCovered)
+            continue;
+        const list = grouped.get(e.target) ?? [];
+        list.push(e);
+        grouped.set(e.target, list);
+    }
+    for (const [target, list] of grouped) {
+        lines.push(`## ${target}`);
+        lines.push('');
+        for (const e of list) {
+            lines.push(`### ${e.status} — \`${e.id}\` (${e.kind})`);
+            lines.push(`> ${e.reason}`);
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}

package/dist/ingest-apply.d.ts

@@ -0,0 +1,80 @@
+import { IngestAdoptionStatus, type IIngestAdoptionPlan } from './ingest-adoption.js';
+export declare const INGEST_APPLY_PLAN_SCHEMA = "sharkcraft.plan/v1";
+export type IngestApplyChangeType = 'create' | 'append';
+export interface IIngestApplyExpectedChange {
+    type: IngestApplyChangeType;
+    relativePath: string;
+    sizeBytes: number;
+}
+export interface IIngestApplyPlan {
+    schema: typeof INGEST_APPLY_PLAN_SCHEMA;
+    templateId: 'ingest.adopt';
+    variables: Readonly<Record<string, string>>;
+    projectRoot: string;
+    createdAt: string;
+    expectedChanges: readonly IIngestApplyExpectedChange[];
+    note?: string;
+    signature?: {
+        algo: 'sha256';
+        hmac: string;
+        signedAt: string;
+    };
+}
+export interface IBuildIngestApplyPlanOptions {
+    plan: IIngestAdoptionPlan;
+    /** Statuses that are eligible — default ['safe-append']. */
+    include?: readonly IngestAdoptionStatus[];
+    /** Optional: include manual-review entries (will appear in the plan but with operation note). */
+    includeManualReview?: boolean;
+    /** Note that lands inside the plan file. */
+    note?: string;
+    /**
+     * When true, attempt to extract the real entry body from the
+     * originating draft TS file (sharkcraft/ingestion/generated/<X>.draft.ts).
+     * Falls back to the comment stub if extraction is unsafe.
+     */
+    includeBody?: boolean;
+}
+export interface IIngestBodyStatus {
+    entryId: string;
+    target: string;
+    status: 'materialised' | 'stubbed' | 'skipped' | 'conflict';
+    reason?: string;
+}
+export interface IBuildIngestApplyPlanResult {
+    plan: IIngestApplyPlan;
+    /** Bodies the apply step should write, keyed by relative path. */
+    files: Readonly<Record<string, string>>;
+    /** Entries that were skipped, with a reason. */
+    skipped: readonly {
+        entryId: string;
+        target: string;
+        reason: string;
+    }[];
+    /** Per-entry body extraction status. */
+    bodyStatuses?: readonly IIngestBodyStatus[];
+}
+export declare function buildIngestApplyPlan(options: IBuildIngestApplyPlanOptions): IBuildIngestApplyPlanResult;
+export declare function signIngestApplyPlan(plan: IIngestApplyPlan, secret: string): IIngestApplyPlan;
+export declare function verifyIngestApplyPlan(plan: IIngestApplyPlan, secret: string): boolean;
+export declare function saveIngestApplyPlan(plan: IIngestApplyPlan, file: string): void;
+export declare function loadIngestApplyPlan(file: string): IIngestApplyPlan | null;
+export declare function renderIngestApplyReviewMarkdown(plan: IIngestApplyPlan): string;
+export interface IApplyIngestPlanOptions {
+    plan: IIngestApplyPlan;
+    files: Readonly<Record<string, string>>;
+    requireSignature?: boolean;
+    secret?: string;
+}
+export interface IApplyIngestPlanResult {
+    applied: readonly {
+        path: string;
+        bytesWritten: number;
+    }[];
+    skipped: readonly {
+        path: string;
+        reason: string;
+    }[];
+}
+export declare function applyIngestPlan(opts: IApplyIngestPlanOptions): IApplyIngestPlanResult;
+//# sourceMappingURL=ingest-apply.d.ts.map

package/dist/ingest-apply.d.ts.map

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

package/dist/ingest-apply.js

@@ -0,0 +1,227 @@
+/**
+ * Ingest adoption apply plan.
+ *
+ * Builds a `sharkcraft.plan/v1` plan (compatible with the existing
+ * generator + apply pipeline) that materialises selected entries from an
+ * `IIngestAdoptionPlan`. The plan only targets `sharkcraft/**` and
+ * `sharkcraft/docs/tasks/**` — nothing else.
+ *
+ * Default is dry-run. `shrk ingest adopt apply <plan>` is the explicit
+ * write step and goes through `shrk apply --verify-signature`, inheriting
+ * every existing plan-safety guarantee.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { createHmac } from 'node:crypto';
+import { IngestAdoptionStatus, } from "./ingest-adoption.js";
+import { extractIngestBody } from "./ingest-body-extractor.js";
+export const INGEST_APPLY_PLAN_SCHEMA = 'sharkcraft.plan/v1';
+const ALLOWED_TARGET_DIRS = [
+    'sharkcraft/',
+    'sharkcraft/docs/tasks/',
+];
+function ensureSafeTarget(target) {
+    const normalized = target.replace(/\\/g, '/');
+    if (normalized.includes('..'))
+        return false;
+    if (nodePath.isAbsolute(normalized))
+        return false;
+    for (const prefix of ALLOWED_TARGET_DIRS) {
+        if (normalized.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+function bodyFor(entry) {
+    if (entry.bodyExcerpt && entry.bodyExcerpt.length > 0)
+        return entry.bodyExcerpt + '\n';
+    // Conservative inline snippet: record the entry id + reason as a comment so
+    // append is always safe to read by humans.
+    const safeReason = entry.reason.replace(/\*\//g, '*\\/');
+    return [
+        `// ingest-adopt — ${entry.id} (${entry.kind})`,
+        `// reason: ${safeReason}`,
+        '',
+    ].join('\n');
+}
+export function buildIngestApplyPlan(options) {
+    const include = new Set(options.include ?? [IngestAdoptionStatus.SafeAppend]);
+    if (options.includeManualReview)
+        include.add(IngestAdoptionStatus.ManualReview);
+    const files = {};
+    const skipped = [];
+    const bodyStatuses = [];
+    const grouped = new Map();
+    for (const entry of options.plan.entries) {
+        if (!include.has(entry.status)) {
+            skipped.push({ entryId: entry.id, target: entry.target, reason: `status ${entry.status} not in include set` });
+            continue;
+        }
+        if (!ensureSafeTarget(entry.target)) {
+            skipped.push({ entryId: entry.id, target: entry.target, reason: 'target outside sharkcraft/ — refused' });
+            continue;
+        }
+        // When --include-body is requested, attempt to materialise the
+        // real entry body from the draft TS file.
+        let resolved = entry;
+        if (options.includeBody) {
+            const ext = extractIngestBody({
+                projectRoot: options.plan.projectRoot,
+                target: entry.target,
+                entryId: entry.id,
+            });
+            if (ext.status === 'materialised' && ext.body) {
+                resolved = { ...entry, bodyExcerpt: ext.body };
+                bodyStatuses.push({ entryId: entry.id, target: entry.target, status: 'materialised' });
+            }
+            else {
+                bodyStatuses.push({
+                    entryId: entry.id,
+                    target: entry.target,
+                    status: ext.status === 'materialised' ? 'stubbed' : ext.status,
+                    ...(ext.reason ? { reason: ext.reason } : {}),
+                });
+            }
+        }
+        const cur = grouped.get(entry.target) ?? [];
+        cur.push(bodyFor(resolved));
+        grouped.set(entry.target, cur);
+    }
+    const expectedChanges = [];
+    for (const [target, chunks] of grouped) {
+        const body = chunks.join('\n');
+        files[target] = body;
+        expectedChanges.push({
+            type: 'append',
+            relativePath: target,
+            sizeBytes: Buffer.byteLength(body, 'utf8'),
+        });
+    }
+    const plan = {
+        schema: INGEST_APPLY_PLAN_SCHEMA,
+        templateId: 'ingest.adopt',
+        variables: { source: 'ingest-adopt' },
+        projectRoot: options.plan.projectRoot,
+        createdAt: new Date().toISOString(),
+        expectedChanges,
+        ...(options.note ? { note: options.note } : {}),
+    };
+    return {
+        plan,
+        files,
+        skipped,
+        ...(bodyStatuses.length > 0 ? { bodyStatuses } : {}),
+    };
+}
+function canonicalJson(plan) {
+    // Strip signature; sort keys for deterministic HMAC.
+    const { signature: _sig, ...rest } = plan;
+    void _sig;
+    const sortKeys = (v) => {
+        if (Array.isArray(v))
+            return v.map(sortKeys);
+        if (v !== null && typeof v === 'object') {
+            const out = {};
+            for (const k of Object.keys(v).sort()) {
+                out[k] = sortKeys(v[k]);
+            }
+            return out;
+        }
+        return v;
+    };
+    return JSON.stringify(sortKeys(rest));
+}
+export function signIngestApplyPlan(plan, secret) {
+    const body = canonicalJson(plan);
+    const hmac = createHmac('sha256', secret).update(body).digest('hex');
+    return {
+        ...plan,
+        signature: { algo: 'sha256', hmac, signedAt: new Date().toISOString() },
+    };
+}
+export function verifyIngestApplyPlan(plan, secret) {
+    if (!plan.signature)
+        return false;
+    const body = canonicalJson(plan);
+    const expected = createHmac('sha256', secret).update(body).digest('hex');
+    return expected === plan.signature.hmac;
+}
+export function saveIngestApplyPlan(plan, file) {
+    const dir = nodePath.dirname(file);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(file, JSON.stringify(plan, null, 2) + '\n', 'utf8');
+}
+export function loadIngestApplyPlan(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const raw = readFileSync(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (parsed.schema !== INGEST_APPLY_PLAN_SCHEMA)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function renderIngestApplyReviewMarkdown(plan) {
+    const lines = [];
+    lines.push('# Ingest adopt — review');
+    lines.push('');
+    lines.push(`- Project root: \`${plan.projectRoot}\``);
+    lines.push(`- Template: \`${plan.templateId}\``);
+    lines.push(`- Files touched: **${plan.expectedChanges.length}**`);
+    if (plan.signature)
+        lines.push(`- Signature: \`${plan.signature.algo}\` (signed at ${plan.signature.signedAt})`);
+    else
+        lines.push(`- Signature: _none — set SHARKCRAFT_PLAN_SECRET to sign_`);
+    lines.push('');
+    lines.push('| Target | Op | Bytes |');
+    lines.push('|---|---|---|');
+    for (const c of plan.expectedChanges) {
+        lines.push(`| \`${c.relativePath}\` | ${c.type} | ${c.sizeBytes} |`);
+    }
+    lines.push('');
+    lines.push('Apply with:');
+    lines.push('');
+    lines.push('```');
+    lines.push('shrk ingest adopt apply <plan.json> --verify-signature');
+    lines.push('```');
+    return lines.join('\n');
+}
+export function applyIngestPlan(opts) {
+    if (opts.requireSignature) {
+        if (!opts.secret)
+            throw new Error('signature required but SHARKCRAFT_PLAN_SECRET is not set');
+        if (!verifyIngestApplyPlan(opts.plan, opts.secret))
+            throw new Error('plan signature invalid');
+    }
+    const applied = [];
+    const skipped = [];
+    for (const change of opts.plan.expectedChanges) {
+        if (!ensureSafeTarget(change.relativePath)) {
+            skipped.push({ path: change.relativePath, reason: 'unsafe target — refused' });
+            continue;
+        }
+        const abs = nodePath.join(opts.plan.projectRoot, change.relativePath);
+        const dir = nodePath.dirname(abs);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const body = opts.files[change.relativePath] ?? '';
+        if (change.type === 'append' && existsSync(abs)) {
+            const current = readFileSync(abs, 'utf8');
+            const next = current.endsWith('\n') ? current + body : current + '\n' + body;
+            writeFileSync(abs, next, 'utf8');
+            applied.push({ path: abs, bytesWritten: Buffer.byteLength(body, 'utf8') });
+        }
+        else {
+            writeFileSync(abs, body, 'utf8');
+            applied.push({ path: abs, bytesWritten: Buffer.byteLength(body, 'utf8') });
+        }
+    }
+    return { applied, skipped };
+}

package/dist/ingest-body-extractor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Extract a draft entry body from a `sharkcraft/ingestion/generated/<X>.draft.ts`
+ * file for a given entry id.
+ *
+ * Extraction strategy:
+ *   1. Find the line containing `id: '<id>'`.
+ *   2. Walk outwards to find the enclosing `{ ... }` object literal.
+ *   3. Return the object literal text (without the leading whitespace) plus a
+ *      trailing comma. The caller appends it to the live sharkcraft/<file>.ts.
+ *   4. If multiple `id: '<id>'` matches exist, or the enclosing block cannot
+ *      be unambiguously identified, return `null` and let the caller fall back
+ *      to the comment-stub body.
+ *
+ * Imports are NOT preserved by this extractor — the caller decides whether
+ * to surface a manual checklist for missing imports. Most draft entries are
+ * plain object literals with no extra imports.
+ */
+export interface IIngestBodyExtractionResult {
+    status: 'materialised' | 'stubbed' | 'skipped' | 'conflict';
+    body: string | null;
+    reason?: string;
+}
+export declare function extractIngestBody(input: {
+    projectRoot: string;
+    target: string;
+    entryId: string;
+}): IIngestBodyExtractionResult;
+//# sourceMappingURL=ingest-body-extractor.d.ts.map

package/dist/ingest-body-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-body-extractor.d.ts","sourceRoot":"","sources":["../src/ingest-body-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IAC5D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyFD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,2BAA2B,CAoB9B"}

package/dist/ingest-body-extractor.js

@@ -0,0 +1,129 @@
+/**
+ * Extract a draft entry body from a `sharkcraft/ingestion/generated/<X>.draft.ts`
+ * file for a given entry id.
+ *
+ * Extraction strategy:
+ *   1. Find the line containing `id: '<id>'`.
+ *   2. Walk outwards to find the enclosing `{ ... }` object literal.
+ *   3. Return the object literal text (without the leading whitespace) plus a
+ *      trailing comma. The caller appends it to the live sharkcraft/<file>.ts.
+ *   4. If multiple `id: '<id>'` matches exist, or the enclosing block cannot
+ *      be unambiguously identified, return `null` and let the caller fall back
+ *      to the comment-stub body.
+ *
+ * Imports are NOT preserved by this extractor — the caller decides whether
+ * to surface a manual checklist for missing imports. Most draft entries are
+ * plain object literals with no extra imports.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const DRAFT_FILE_CANDIDATES = (target) => {
+    // target is `sharkcraft/<file>.ts`; the draft is typically at
+    // `sharkcraft/ingestion/generated/<file>.draft.ts`. We try both.
+    const base = target.replace(/^sharkcraft\//, '').replace(/\.ts$/, '');
+    return [
+        `sharkcraft/ingestion/generated/${base}.draft.ts`,
+        `sharkcraft/ingestion/drafts/${base}.draft.ts`,
+        `sharkcraft/${base}.draft.ts`,
+    ];
+};
+function findDraftFile(projectRoot, target) {
+    for (const rel of DRAFT_FILE_CANDIDATES(target)) {
+        const abs = join(projectRoot, rel);
+        if (existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+function extractObjectBlock(content, entryId) {
+    // Find every occurrence of `id: '<entryId>'` (allow double quotes too).
+    const idRe = new RegExp(`id:\\s*['"]${entryId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`, 'g');
+    const matches = [];
+    let m;
+    while ((m = idRe.exec(content)) !== null)
+        matches.push(m.index);
+    if (matches.length === 0) {
+        return { status: 'skipped', body: null, reason: `id "${entryId}" not found in draft file` };
+    }
+    if (matches.length > 1) {
+        return {
+            status: 'conflict',
+            body: null,
+            reason: `id "${entryId}" matched ${matches.length} times in draft file — ambiguous, falling back to stub`,
+        };
+    }
+    // Walk backwards to find the enclosing `{`.
+    const idx = matches[0];
+    let openIdx = -1;
+    let depth = 0;
+    for (let i = idx - 1; i >= 0; i--) {
+        const ch = content[i];
+        if (ch === '}')
+            depth += 1;
+        else if (ch === '{') {
+            if (depth === 0) {
+                openIdx = i;
+                break;
+            }
+            depth -= 1;
+        }
+    }
+    if (openIdx === -1) {
+        return {
+            status: 'conflict',
+            body: null,
+            reason: `Could not find opening brace before "id: ${entryId}".`,
+        };
+    }
+    // Walk forwards from openIdx to find matching `}`.
+    let closeIdx = -1;
+    depth = 0;
+    for (let i = openIdx; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === '{')
+            depth += 1;
+        else if (ch === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                closeIdx = i;
+                break;
+            }
+        }
+    }
+    if (closeIdx === -1) {
+        return {
+            status: 'conflict',
+            body: null,
+            reason: `Could not find closing brace for entry "${entryId}".`,
+        };
+    }
+    const block = content.slice(openIdx, closeIdx + 1);
+    // Append a trailing comma if the block does not already have one in context.
+    // The live file is an array; entries are object literals separated by commas.
+    return {
+        status: 'materialised',
+        body: block + ',',
+    };
+}
+export function extractIngestBody(input) {
+    const draftFile = findDraftFile(input.projectRoot, input.target);
+    if (!draftFile) {
+        return {
+            status: 'skipped',
+            body: null,
+            reason: `No draft file found for target "${input.target}". Use comment stub.`,
+        };
+    }
+    let content;
+    try {
+        content = readFileSync(draftFile, 'utf8');
+    }
+    catch (e) {
+        return {
+            status: 'skipped',
+            body: null,
+            reason: `Failed to read draft file: ${e.message}`,
+        };
+    }
+    return extractObjectBlock(content, input.entryId);
+}

package/dist/ingest-drafts.d.ts

@@ -0,0 +1,16 @@
+import { type IRepositoryKnowledgeModel } from './repository-knowledge-model.js';
+export interface IWrittenIngestFile {
+    path: string;
+    bytes: number;
+}
+export interface IWriteIngestDraftsOptions {
+    projectRoot: string;
+    /** Override the output directory. Default: `<projectRoot>/sharkcraft/ingestion`. */
+    outDir?: string;
+}
+export interface IWriteIngestDraftsResult {
+    outDir: string;
+    files: readonly IWrittenIngestFile[];
+}
+export declare function writeIngestDrafts(model: IRepositoryKnowledgeModel, options: IWriteIngestDraftsOptions): IWriteIngestDraftsResult;
+//# sourceMappingURL=ingest-drafts.d.ts.map

package/dist/ingest-drafts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-drafts.d.ts","sourceRoot":"","sources":["../src/ingest-drafts.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,iCAAiC,CAAC;AAKzC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACtC;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,yBAAyB,EAChC,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CAiD1B"}