@shrkcrft/generator 0.1.0-alpha.1

package/dist/saved-plan.js

@@ -0,0 +1,281 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+/** v1 schema marker — kept for legacy CREATE-only plans. */
+export const SAVED_PLAN_SCHEMA_V1 = 'sharkcraft.plan/v1';
+/** v2 schema marker — emitted when any change carries a v2 operation. */
+export const SAVED_PLAN_SCHEMA_V2 = 'sharkcraft.plan/v2';
+/** Default exported alias — points at v1 for backward-compat with consumers. */
+export const SAVED_PLAN_SCHEMA = SAVED_PLAN_SCHEMA_V1;
+/**
+ * Build a saved plan. If any change in the plan carries a v2 operation, the
+ * resulting plan is tagged `sharkcraft.plan/v2`; otherwise v1.
+ */
+export function buildSavedPlan(input) {
+    const hasV2Op = input.plan.changes.some((c) => c.operation !== undefined);
+    const hasFolderOps = (input.folderOps?.length ?? 0) > 0;
+    const expectedChanges = input.plan.changes.map((c) => {
+        const entry = {
+            type: String(c.type),
+            relativePath: c.relativePath,
+            sizeBytes: c.sizeBytes,
+        };
+        if (c.operation !== undefined)
+            entry.operation = c.operation;
+        return entry;
+    });
+    const out = {
+        schema: hasV2Op || hasFolderOps ? SAVED_PLAN_SCHEMA_V2 : SAVED_PLAN_SCHEMA_V1,
+        templateId: input.templateId,
+        variables: { ...input.variables },
+        projectRoot: input.projectRoot,
+        createdAt: new Date().toISOString(),
+        expectedChanges,
+    };
+    if (input.name !== undefined)
+        out.name = input.name;
+    if (input.note !== undefined)
+        out.note = input.note;
+    if (hasFolderOps)
+        out.folderOps = [...input.folderOps];
+    return out;
+}
+export function savePlanToFile(plan, filePath) {
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, JSON.stringify(plan, null, 2) + '\n', 'utf8');
+        return ok(undefined);
+    }
+    catch (e) {
+        return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, `Failed to save plan: ${filePath}`, {
+            details: { filePath },
+            cause: e,
+        }));
+    }
+}
+export function readPlanFromFile(filePath) {
+    if (!existsSync(filePath)) {
+        return err(new AppErrorImpl(ERROR_CODES.NOT_FOUND, `Plan file not found: ${filePath}`, {
+            details: { filePath },
+        }));
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch (e) {
+        return err(new AppErrorImpl(ERROR_CODES.FILE_READ_ERROR, `Failed to read plan: ${filePath}`, {
+            details: { filePath },
+            cause: e,
+        }));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Plan file is not valid JSON: ${filePath}`, {
+            cause: e,
+        }));
+    }
+    const validation = validateSavedPlanShape(parsed);
+    if (!validation.ok)
+        return err(validation.error);
+    return ok(validation.value);
+}
+function validateSavedPlanShape(value) {
+    if (!value || typeof value !== 'object') {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan must be a JSON object'));
+    }
+    const obj = value;
+    if (obj.schema !== SAVED_PLAN_SCHEMA_V1 && obj.schema !== SAVED_PLAN_SCHEMA_V2) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Unsupported plan schema: ${String(obj.schema)} (expected ${SAVED_PLAN_SCHEMA_V1} or ${SAVED_PLAN_SCHEMA_V2})`));
+    }
+    if (typeof obj.templateId !== 'string' || !obj.templateId) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: templateId must be a non-empty string'));
+    }
+    if (obj.variables === null || typeof obj.variables !== 'object') {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: variables must be an object'));
+    }
+    for (const [k, v] of Object.entries(obj.variables)) {
+        if (typeof v !== 'string') {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Plan: variables.${k} must be a string (got ${typeof v})`));
+        }
+    }
+    if (typeof obj.projectRoot !== 'string' || !obj.projectRoot) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: projectRoot must be a non-empty string'));
+    }
+    if (typeof obj.createdAt !== 'string') {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: createdAt must be a string'));
+    }
+    if (obj.name !== undefined && typeof obj.name !== 'string') {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: name must be a string'));
+    }
+    if (obj.folderOps !== undefined) {
+        if (!Array.isArray(obj.folderOps)) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: folderOps must be an array'));
+        }
+        for (const f of obj.folderOps) {
+            if (!f || typeof f !== 'object') {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: folderOps entries must be objects'));
+            }
+            const fo = f;
+            if (fo.kind !== 'rename-folder' && fo.kind !== 'delete-folder') {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Plan: folderOps.kind must be "rename-folder" or "delete-folder" (got ${String(fo.kind)})`));
+            }
+            if (typeof fo.targetPath !== 'string' || fo.targetPath.length === 0) {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: folderOps.targetPath must be a non-empty string'));
+            }
+            if (fo.newPath !== undefined && typeof fo.newPath !== 'string') {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: folderOps.newPath must be a string'));
+            }
+            if (fo.kind === 'rename-folder' && (fo.newPath === undefined || fo.newPath.length === 0)) {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'Plan: folderOps[rename-folder] requires newPath'));
+            }
+        }
+    }
+    return ok(obj);
+}
+/**
+ * Compare the saved plan's expected changes with a freshly-computed plan's
+ * changes. Returns an empty array when they match. v2 plans additionally
+ * detect operation-intent drift (e.g. signed `append` became `replace` in
+ * the template).
+ */
+export function diffPlanChanges(saved, fresh) {
+    if (!saved.expectedChanges)
+        return [];
+    // Key by `path :: operation-fingerprint` so multiple ops on the
+    // same file are tracked independently. Falls back to path-only keying
+    // for v1 plans where `operation` is absent. Reordered independent ops
+    // still match (the fingerprint is stable and does not depend on order).
+    const out = [];
+    const expectedByKey = new Map();
+    for (const e of saved.expectedChanges) {
+        expectedByKey.set(`${e.relativePath}::${opFingerprint(e.operation, e.type)}`, e);
+    }
+    const freshByKey = new Map();
+    for (const c of fresh.changes) {
+        freshByKey.set(`${c.relativePath}::${opFingerprint(c.operation, c.type)}`, c);
+    }
+    for (const [key, expected] of expectedByKey) {
+        const actual = freshByKey.get(key);
+        if (!actual) {
+            // Try a same-path fallback to give a more useful "type-changed" /
+            // "operation-changed" diagnostic when paths match but fingerprint
+            // differs.
+            const samePath = [...freshByKey.values()].find((c) => c.relativePath === expected.relativePath);
+            if (samePath) {
+                if (String(samePath.type) !== expected.type) {
+                    out.push({
+                        relativePath: expected.relativePath,
+                        kind: 'type-changed',
+                        detail: `${expected.type} → ${String(samePath.type)}`,
+                    });
+                }
+                else if (expected.operation !== undefined &&
+                    samePath.operation !== undefined &&
+                    !operationsEqual(expected.operation, samePath.operation)) {
+                    out.push({
+                        relativePath: expected.relativePath,
+                        kind: 'operation-changed',
+                        detail: `${expected.operation.kind} intent drifted`,
+                    });
+                }
+                else {
+                    out.push({
+                        relativePath: expected.relativePath,
+                        kind: 'removed',
+                        detail: `expected op fingerprint not found on this path`,
+                    });
+                }
+                continue;
+            }
+            out.push({ relativePath: expected.relativePath, kind: 'removed' });
+            continue;
+        }
+        if (actual.sizeBytes !== expected.sizeBytes) {
+            out.push({
+                relativePath: expected.relativePath,
+                kind: 'size-changed',
+                detail: `${expected.sizeBytes}B → ${actual.sizeBytes}B`,
+            });
+        }
+    }
+    for (const [key, actual] of freshByKey) {
+        if (!expectedByKey.has(key)) {
+            // Only surface as `added` if the same-path expected didn't already
+            // produce a type-changed / operation-changed diagnostic above.
+            const samePathExpected = saved.expectedChanges.some((e) => e.relativePath === actual.relativePath);
+            if (!samePathExpected) {
+                out.push({ relativePath: actual.relativePath, kind: 'added' });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Stable, canonical fingerprint for a plan operation. Two semantically
+ * equal operations on the same file produce the same fingerprint; reordering
+ * independent ops keeps each one's fingerprint stable.
+ */
+function opFingerprint(op, fallbackType) {
+    if (!op)
+        return `legacy:${fallbackType}`;
+    // The canonical-JSON encoding sorts keys and ignores undefined values, so
+    // the resulting hash is deterministic.
+    return canonicalOpString(op);
+}
+function canonicalOpString(op) {
+    return JSON.stringify(canon(op));
+}
+/**
+ * Structural equality on operations. JSON round-trip; cheap and deterministic.
+ */
+function operationsEqual(a, b) {
+    return JSON.stringify(canon(a)) === JSON.stringify(canon(b));
+}
+/**
+ * Folder-op divergence. Returns an empty array when saved and live
+ * folder ops match (by kind+targetPath+newPath).
+ */
+export function diffPlanFolderOps(saved, liveFolderOps) {
+    const out = [];
+    const savedOps = saved.folderOps ?? [];
+    const key = (op) => `${op.kind}:${op.targetPath}:${op.newPath ?? ''}`;
+    const savedByKey = new Map();
+    for (const o of savedOps)
+        savedByKey.set(key(o), o);
+    const liveByKey = new Map();
+    for (const o of liveFolderOps)
+        liveByKey.set(key(o), o);
+    for (const [k, savedOp] of savedByKey) {
+        if (!liveByKey.has(k)) {
+            out.push({
+                relativePath: savedOp.targetPath,
+                kind: 'removed',
+                detail: `folder-op ${savedOp.kind}`,
+            });
+        }
+    }
+    for (const [k, liveOp] of liveByKey) {
+        if (!savedByKey.has(k)) {
+            out.push({
+                relativePath: liveOp.targetPath,
+                kind: 'added',
+                detail: `folder-op ${liveOp.kind}`,
+            });
+        }
+    }
+    return out;
+}
+function canon(op) {
+    const out = {};
+    for (const k of Object.keys(op).sort()) {
+        const v = op[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}

package/dist/spec/index.d.ts

@@ -0,0 +1,7 @@
+export * from './spec-frontmatter.js';
+export * from './spec-model.js';
+export * from './spec-id.js';
+export * from './spec-derive.js';
+export * from './spec-scaffold.js';
+export * from './spec-io.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/spec/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/spec/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC"}

package/dist/spec/index.js

@@ -0,0 +1,6 @@
+export * from "./spec-frontmatter.js";
+export * from "./spec-model.js";
+export * from "./spec-id.js";
+export * from "./spec-derive.js";
+export * from "./spec-scaffold.js";
+export * from "./spec-io.js";

package/dist/spec/spec-derive.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Derive the canonical `spec.json` view from a parsed `spec.md`.
+ *
+ * Pure transformation: parsed frontmatter + body → `ISpecJson`. The
+ * frontmatterHash / bodyHash are sha256 hex digests. Frontmatter
+ * canonicalization sorts keys recursively so the hash is stable
+ * across YAML formatting changes that preserve semantics.
+ */
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { IParsedSpecMd } from './spec-frontmatter.js';
+import { type ISpecJson } from './spec-model.js';
+export declare function deriveSpecJson(parsed: IParsedSpecMd): Result<ISpecJson, AppError>;
+export declare function sha256(text: string): string;
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=spec-derive.d.ts.map

package/dist/spec/spec-derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-derive.d.ts","sourceRoot":"","sources":["../../src/spec/spec-derive.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EAQL,KAAK,SAAS,EAKf,MAAM,iBAAiB,CAAC;AAEzB,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAwEjF;AA8LD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcpD"}

package/dist/spec/spec-derive.js

@@ -0,0 +1,294 @@
+/**
+ * Derive the canonical `spec.json` view from a parsed `spec.md`.
+ *
+ * Pure transformation: parsed frontmatter + body → `ISpecJson`. The
+ * frontmatterHash / bodyHash are sha256 hex digests. Frontmatter
+ * canonicalization sorts keys recursively so the hash is stable
+ * across YAML formatting changes that preserve semantics.
+ */
+import { createHash } from 'node:crypto';
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { knownTopLevelKeys, SPEC_SCHEMA_V1, SpecStatus, } from "./spec-model.js";
+export function deriveSpecJson(parsed) {
+    const fm = parsed.frontmatter.fields;
+    const knownKeys = new Set(knownTopLevelKeys());
+    const unknownKeys = [];
+    for (const k of Object.keys(fm)) {
+        if (!knownKeys.has(k))
+            unknownKeys.push(k);
+    }
+    const id = asString(fm['id']);
+    const slug = asString(fm['slug']);
+    const title = asString(fm['title']);
+    const status = asSpecStatus(fm['status']);
+    const createdAt = asString(fm['createdAt']);
+    const updatedAt = asString(fm['updatedAt']);
+    const intent = asString(fm['intent']);
+    const motivation = asString(fm['motivation']);
+    if (!id) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'spec.md frontmatter missing required "id"'));
+    }
+    const acceptanceCriteria = readAcceptanceCriteria(fm['acceptanceCriteria']);
+    const affectedAreas = readAffectedAreas(fm['affectedAreas']);
+    const relevantRules = readScalarArray(fm['relevantRules']);
+    const relevantKnowledge = readScalarArray(fm['relevantKnowledge']);
+    const relevantPaths = readScalarArray(fm['relevantPaths']);
+    const proposedTemplates = readProposedTemplates(fm['proposedTemplates']);
+    const risks = readRisks(fm['risks']);
+    const outOfScope = readScalarArray(fm['outOfScope']);
+    const externalLinks = readExternalLinks(fm['externalLinks']);
+    const boundariesCheck = readBoundariesCheck(fm['boundariesCheck']);
+    const verificationCommands = readVerificationCommandRefs(fm['verificationCommands']);
+    const plan = readPlanRef(fm['plan']);
+    const bodyHash = sha256(parsed.body);
+    // The frontmatter hash includes EVERYTHING in the frontmatter EXCEPT
+    // the `plan` block (which is added after implement). That way the
+    // hash is stable from create → review → implement.
+    const hashableFm = {};
+    for (const [k, v] of Object.entries(fm)) {
+        if (k === 'plan')
+            continue;
+        hashableFm[k] = v;
+    }
+    const frontmatterHash = sha256(canonicalJson(hashableFm));
+    const json = {
+        schema: SPEC_SCHEMA_V1,
+        id,
+        slug: slug || '',
+        title: title || '',
+        status,
+        createdAt: createdAt || '',
+        updatedAt: updatedAt || '',
+        intent: intent || '',
+        motivation: motivation || '',
+        acceptanceCriteria,
+        affectedAreas,
+        relevantRules,
+        relevantKnowledge,
+        relevantPaths,
+        proposedTemplates,
+        risks,
+        outOfScope,
+        externalLinks,
+        boundariesCheck: { predicted: boundariesCheck },
+        verificationCommands,
+        ...(plan ? { plan } : {}),
+        frontmatterHash,
+        bodyHash,
+        unknownKeys,
+    };
+    return ok(json);
+}
+function asString(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return '';
+}
+function asSpecStatus(v) {
+    const s = typeof v === 'string' ? v : '';
+    if (Object.values(SpecStatus).includes(s))
+        return s;
+    return SpecStatus.Draft;
+}
+function readAcceptanceCriteria(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const id = typeof obj['id'] === 'string' ? obj['id'] : '';
+        const text = typeof obj['text'] === 'string' ? obj['text'] : '';
+        const verifiedByRaw = obj['verifiedBy'];
+        const verifiedBy = readVerifiedBy(verifiedByRaw);
+        out.push({ id, text, verifiedBy });
+    }
+    return out;
+}
+function readVerifiedBy(raw) {
+    if (typeof raw === 'string') {
+        // YAML inline arrays aren't supported by our parser; allow a comma-list as a courtesy.
+        return raw
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    if (Array.isArray(raw)) {
+        return raw
+            .map((v) => (typeof v === 'string' ? v : String(v ?? '')))
+            .filter((s) => s.length > 0);
+    }
+    return [];
+}
+function readAffectedAreas(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+        return { files: [], packages: [], layers: [] };
+    }
+    const obj = v;
+    return {
+        files: readScalarArrayLike(obj['files']),
+        packages: readScalarArrayLike(obj['packages']),
+        layers: readScalarArrayLike(obj['layers']),
+    };
+}
+function readScalarArrayLike(v) {
+    if (typeof v === 'string') {
+        return v
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    if (Array.isArray(v)) {
+        return v
+            .map((x) => (typeof x === 'string' ? x : String(x ?? '')))
+            .filter((s) => s.length > 0);
+    }
+    return [];
+}
+function readScalarArray(v) {
+    if (Array.isArray(v)) {
+        return v
+            .map((x) => (typeof x === 'string' ? x : String(x ?? '')))
+            .filter((s) => s.length > 0);
+    }
+    if (typeof v === 'string') {
+        return v
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    return [];
+}
+function readProposedTemplates(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const templateId = typeof obj['templateId'] === 'string' ? obj['templateId'] : '';
+        if (!templateId)
+            continue;
+        const note = typeof obj['note'] === 'string' ? obj['note'] : undefined;
+        const variables = {};
+        const rawVars = obj['variables'];
+        if (rawVars && typeof rawVars === 'object' && !Array.isArray(rawVars)) {
+            for (const [k, val] of Object.entries(rawVars)) {
+                variables[k] = typeof val === 'string' ? val : String(val ?? '');
+            }
+        }
+        out.push(note !== undefined ? { templateId, variables, note } : { templateId, variables });
+    }
+    return out;
+}
+function readRisks(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const id = typeof obj['id'] === 'string' ? obj['id'] : '';
+        const text = typeof obj['text'] === 'string' ? obj['text'] : '';
+        if (!id || !text)
+            continue;
+        const mitigation = typeof obj['mitigation'] === 'string' ? obj['mitigation'] : undefined;
+        out.push(mitigation !== undefined ? { id, text, mitigation } : { id, text });
+    }
+    return out;
+}
+function readExternalLinks(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+        return { issue: null, pr: null };
+    }
+    const obj = v;
+    return {
+        issue: scalarOrNull(obj['issue']),
+        pr: scalarOrNull(obj['pr']),
+    };
+}
+function scalarOrNull(v) {
+    if (typeof v === 'string')
+        return v.length > 0 ? v : null;
+    if (v === null || v === undefined)
+        return null;
+    return String(v);
+}
+function readBoundariesCheck(v) {
+    // Support either `boundariesCheck: { predicted: [...] }` (nested) or
+    // `boundariesCheck:` shorthand with predicted as the direct array.
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return [];
+    const obj = v;
+    const raw = obj['predicted'];
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const o = item;
+        const from = typeof o['from'] === 'string' ? o['from'] : '';
+        const to = typeof o['to'] === 'string' ? o['to'] : '';
+        const reason = typeof o['reason'] === 'string' ? o['reason'] : '';
+        if (!from || !to)
+            continue;
+        out.push({ from, to, reason });
+    }
+    return out;
+}
+function readVerificationCommandRefs(v) {
+    if (Array.isArray(v)) {
+        const out = [];
+        for (const item of v) {
+            if (typeof item === 'string') {
+                if (item.length > 0)
+                    out.push({ id: item });
+            }
+            else if (item && typeof item === 'object') {
+                const id = item['id'];
+                if (typeof id === 'string' && id.length > 0)
+                    out.push({ id });
+            }
+        }
+        return out;
+    }
+    return [];
+}
+function readPlanRef(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return undefined;
+    const obj = v;
+    const planPath = typeof obj['planPath'] === 'string' ? obj['planPath'] : '';
+    const planHash = typeof obj['planHash'] === 'string' ? obj['planHash'] : '';
+    if (!planPath || !planHash)
+        return undefined;
+    const signedAt = typeof obj['signedAt'] === 'string' ? obj['signedAt'] : undefined;
+    return signedAt !== undefined ? { planPath, planHash, signedAt } : { planPath, planHash };
+}
+export function sha256(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+export function canonicalJson(value) {
+    if (value === null || value === undefined)
+        return JSON.stringify(value ?? null);
+    if (typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => canonicalJson(v)).join(',') + ']';
+    }
+    const keys = Object.keys(value).sort();
+    const parts = [];
+    for (const k of keys) {
+        const v = value[k];
+        if (v === undefined)
+            continue;
+        parts.push(JSON.stringify(k) + ':' + canonicalJson(v));
+    }
+    return '{' + parts.join(',') + '}';
+}

package/dist/spec/spec-frontmatter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimal YAML-frontmatter parser for spec.md.
+ *
+ * Supports the subset used by `sharkcraft.spec/v1` frontmatter:
+ *   - `key: scalar` (string / number / boolean / null)
+ *   - `key:` followed by a block-scalar `|` body
+ *   - `key:` followed by `  - item` (array of scalars)
+ *   - `key:` followed by `  - id: x` blocks (array of objects with scalar fields)
+ *   - `key:` followed by `  subkey: value` (one-level nested objects)
+ *
+ * Quoted strings: `'...'` and `"..."` (no escape sequences beyond
+ * `\n`, `\\`, `\"`).
+ * Comments: `# ...` on their own line are stripped.
+ * Out-of-grammar input throws with a 1-based line number.
+ *
+ * Pure parser. No IO. Lives in `@shrkcrft/generator` so the spec
+ * model + parser can be reused from the CLI without pulling in the
+ * inspector.
+ */
+import { type AppError, type Result } from '@shrkcrft/core';
+export type FrontmatterScalar = string | number | boolean | null;
+export type FrontmatterFieldValue = FrontmatterScalar | readonly FrontmatterScalar[] | Readonly<Record<string, FrontmatterScalar>>;
+export type FrontmatterValue = FrontmatterScalar | readonly FrontmatterScalar[] | ReadonlyArray<Readonly<Record<string, FrontmatterFieldValue>>> | Readonly<Record<string, FrontmatterFieldValue>>;
+export interface IFrontmatterDocument {
+    readonly fields: Readonly<Record<string, FrontmatterValue>>;
+    /** Original frontmatter text (between the `---` delimiters), for hashing. */
+    readonly raw: string;
+}
+export interface IParsedSpecMd {
+    readonly frontmatter: IFrontmatterDocument;
+    /** Markdown body (everything after the closing `---`). */
+    readonly body: string;
+}
+export declare function splitSpecMd(source: string): Result<IParsedSpecMd, AppError>;
+export declare function parseFrontmatter(raw: string): Result<Readonly<Record<string, FrontmatterValue>>, AppError>;
+export declare function parseInlineScalar(s: string, line: number): Result<FrontmatterScalar | readonly FrontmatterScalar[], AppError>;
+//# sourceMappingURL=spec-frontmatter.d.ts.map

package/dist/spec/spec-frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-frontmatter.d.ts","sourceRoot":"","sources":["../../src/spec/spec-frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEhG,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AACjE,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,SAAS,iBAAiB,EAAE,GAC5B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAChD,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,SAAS,iBAAiB,EAAE,GAC5B,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC9D,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC5D,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAkC3E;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,EAAE,QAAQ,CAAC,CAoF9D;AAiWD,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,iBAAiB,GAAG,SAAS,iBAAiB,EAAE,EAAE,QAAQ,CAAC,CA+BpE"}