@shrkcrft/generator 0.1.0-alpha.1

package/dist/spec/spec-frontmatter.js

@@ -0,0 +1,497 @@
+/**
+ * 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 { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+const FRONTMATTER_DELIMITER = '---';
+export function splitSpecMd(source) {
+    const lines = source.split('\n');
+    if (lines.length === 0 || lines[0].trim() !== FRONTMATTER_DELIMITER) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'spec.md must begin with `---` on its first line'));
+    }
+    let closeIdx = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === FRONTMATTER_DELIMITER) {
+            closeIdx = i;
+            break;
+        }
+    }
+    if (closeIdx === -1) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'spec.md frontmatter not terminated (missing closing `---`)'));
+    }
+    const frontmatterLines = lines.slice(1, closeIdx);
+    const raw = frontmatterLines.join('\n');
+    const parsed = parseFrontmatter(raw);
+    if (!parsed.ok)
+        return err(parsed.error);
+    const body = lines.slice(closeIdx + 1).join('\n');
+    return ok({
+        frontmatter: { fields: parsed.value, raw },
+        body,
+    });
+}
+export function parseFrontmatter(raw) {
+    const lines = raw.split('\n');
+    const fields = {};
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#')) {
+            i++;
+            continue;
+        }
+        if (line.length !== line.trimStart().length) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Top-level key must start at column 0 (line ${i + 1})`));
+        }
+        const colon = line.indexOf(':');
+        if (colon === -1) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Expected "<key>:" at line ${i + 1}`));
+        }
+        const key = line.slice(0, colon).trim();
+        if (!isValidKey(key)) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Invalid key "${key}" at line ${i + 1}`));
+        }
+        const remainder = line.slice(colon + 1);
+        const inline = remainder.trim();
+        if (inline === '|') {
+            const block = readBlockScalar(lines, i + 1);
+            if (!block.ok)
+                return err(block.error);
+            fields[key] = block.value.text;
+            i = block.value.nextIndex;
+            continue;
+        }
+        if (inline.length > 0) {
+            const scalar = parseInlineScalar(inline, i + 1);
+            if (!scalar.ok)
+                return err(scalar.error);
+            fields[key] = scalar.value;
+            i++;
+            continue;
+        }
+        // No inline value — look ahead for nested block.
+        const peek = peekNonBlank(lines, i + 1);
+        if (peek === null) {
+            fields[key] = null;
+            i++;
+            continue;
+        }
+        const indent = peek.line.length - peek.line.trimStart().length;
+        if (indent === 0) {
+            fields[key] = null;
+            i++;
+            continue;
+        }
+        const trimmedPeek = peek.line.trim();
+        if (trimmedPeek.startsWith('- ') || trimmedPeek === '-') {
+            const arr = parseArrayBlock(lines, i + 1, indent);
+            if (!arr.ok)
+                return err(arr.error);
+            fields[key] = arr.value.value;
+            i = arr.value.nextIndex;
+            continue;
+        }
+        // Nested object block.
+        const obj = parseObjectBlock(lines, i + 1, indent);
+        if (!obj.ok)
+            return err(obj.error);
+        fields[key] = obj.value.value;
+        i = obj.value.nextIndex;
+    }
+    return ok(fields);
+}
+function isValidKey(key) {
+    return /^[A-Za-z_][A-Za-z0-9_-]*$/.test(key);
+}
+function readBlockScalar(lines, start) {
+    let i = start;
+    let baseIndent = -1;
+    const collected = [];
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === '') {
+            collected.push('');
+            i++;
+            continue;
+        }
+        const indent = line.length - line.trimStart().length;
+        if (baseIndent === -1) {
+            if (indent === 0)
+                break;
+            baseIndent = indent;
+        }
+        if (indent < baseIndent)
+            break;
+        collected.push(line.slice(baseIndent));
+        i++;
+    }
+    while (collected.length > 0 && collected[collected.length - 1] === '') {
+        collected.pop();
+    }
+    return ok({ text: collected.join('\n'), nextIndex: i });
+}
+function peekNonBlank(lines, start) {
+    for (let i = start; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        return { line: lines[i], index: i };
+    }
+    return null;
+}
+function parseArrayBlock(lines, start, expectedIndent) {
+    let i = start;
+    const scalars = [];
+    const objects = [];
+    let mode = 'unknown';
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#')) {
+            i++;
+            continue;
+        }
+        const indent = line.length - line.trimStart().length;
+        if (indent < expectedIndent)
+            break;
+        if (indent !== expectedIndent) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Inconsistent indent at line ${i + 1} (expected ${expectedIndent}, got ${indent})`));
+        }
+        if (!trimmed.startsWith('-')) {
+            // Sibling at same indent — end of array.
+            break;
+        }
+        const itemBody = trimmed.replace(/^-\s?/, '');
+        if (itemBody.length === 0) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Empty array item at line ${i + 1}`));
+        }
+        // Object item iff it contains an unquoted `:`.
+        const colonIdx = findUnquotedColon(itemBody);
+        if (colonIdx === -1) {
+            if (mode === 'object') {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Mixed array kinds at line ${i + 1}`));
+            }
+            mode = 'scalar';
+            const scalar = parseInlineScalar(itemBody, i + 1);
+            if (!scalar.ok)
+                return err(scalar.error);
+            if (Array.isArray(scalar.value)) {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Nested array values are not supported (line ${i + 1})`));
+            }
+            scalars.push(scalar.value);
+            i++;
+            continue;
+        }
+        if (mode === 'scalar') {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Mixed array kinds at line ${i + 1}`));
+        }
+        mode = 'object';
+        const obj = {};
+        const firstKey = itemBody.slice(0, colonIdx).trim();
+        const firstVal = itemBody.slice(colonIdx + 1).trim();
+        if (!isValidKey(firstKey)) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Invalid object key "${firstKey}" at line ${i + 1}`));
+        }
+        if (firstVal.length > 0) {
+            const scalar = parseInlineScalar(firstVal, i + 1);
+            if (!scalar.ok)
+                return err(scalar.error);
+            obj[firstKey] = scalar.value;
+        }
+        else {
+            obj[firstKey] = null;
+        }
+        i++;
+        // Collect continuation lines: `  - id: x` was just consumed; further
+        // lines for THIS object must be indented at `expectedIndent + 2`.
+        const objIndent = expectedIndent + 2;
+        while (i < lines.length) {
+            const inner = lines[i];
+            const innerTrim = inner.trim();
+            if (innerTrim === '' || innerTrim.startsWith('#')) {
+                i++;
+                continue;
+            }
+            const innerIndent = inner.length - inner.trimStart().length;
+            if (innerIndent < objIndent)
+                break;
+            if (innerIndent > objIndent) {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Object continuation must be indented to column ${objIndent} (line ${i + 1})`));
+            }
+            const innerColon = findUnquotedColon(innerTrim);
+            if (innerColon === -1) {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Expected "<key>: <value>" at line ${i + 1}`));
+            }
+            const k = innerTrim.slice(0, innerColon).trim();
+            const v = innerTrim.slice(innerColon + 1).trim();
+            if (!isValidKey(k)) {
+                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Invalid object key "${k}" at line ${i + 1}`));
+            }
+            if (v.length === 0) {
+                // Could be either a nested scalar array (e.g. `verifiedBy:`)
+                // OR a nested scalar object (e.g. `variables:`). Peek and dispatch.
+                const peek = peekNonBlank(lines, i + 1);
+                if (peek) {
+                    const peekIndent = peek.line.length - peek.line.trimStart().length;
+                    const peekTrim = peek.line.trim();
+                    if (peekIndent > objIndent) {
+                        if (peekTrim.startsWith('- ') || peekTrim === '-') {
+                            const arr = parseArrayBlock(lines, i + 1, peekIndent);
+                            if (!arr.ok)
+                                return err(arr.error);
+                            if (Array.isArray(arr.value.value) && arr.value.value.every(isScalarLike)) {
+                                obj[k] = arr.value.value;
+                            }
+                            else {
+                                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Nested object-arrays are not supported inside array-object items (line ${i + 1})`));
+                            }
+                            i = arr.value.nextIndex;
+                            continue;
+                        }
+                        // Nested object block (e.g. variables: { name: foo }).
+                        const sub = parseObjectBlock(lines, i + 1, peekIndent);
+                        if (!sub.ok)
+                            return err(sub.error);
+                        const flat = {};
+                        for (const [sk, sv] of Object.entries(sub.value.value)) {
+                            if (!isScalarLike(sv)) {
+                                return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Nested objects within array-object items must contain scalar values only (line ${i + 1})`));
+                            }
+                            flat[sk] = sv;
+                        }
+                        obj[k] = flat;
+                        i = sub.value.nextIndex;
+                        continue;
+                    }
+                }
+                obj[k] = null;
+            }
+            else {
+                const scalar = parseInlineScalar(v, i + 1);
+                if (!scalar.ok)
+                    return err(scalar.error);
+                obj[k] = scalar.value;
+            }
+            i++;
+        }
+        objects.push(obj);
+    }
+    if (mode === 'object') {
+        return ok({ value: objects, nextIndex: i });
+    }
+    return ok({ value: scalars, nextIndex: i });
+}
+function parseObjectBlock(lines, start, expectedIndent) {
+    const obj = {};
+    let i = start;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#')) {
+            i++;
+            continue;
+        }
+        const indent = line.length - line.trimStart().length;
+        if (indent < expectedIndent)
+            break;
+        if (indent !== expectedIndent) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Inconsistent indent at line ${i + 1} (expected ${expectedIndent}, got ${indent})`));
+        }
+        const colon = findUnquotedColon(trimmed);
+        if (colon === -1) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Expected "<key>: <value>" at line ${i + 1}`));
+        }
+        const key = trimmed.slice(0, colon).trim();
+        const value = trimmed.slice(colon + 1).trim();
+        if (!isValidKey(key)) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Invalid object key "${key}" at line ${i + 1}`));
+        }
+        if (value.length === 0) {
+            // Look ahead for an indented array (e.g. nested `packages:` with
+            // a `  - foo` sub-list).
+            const peek = peekNonBlank(lines, i + 1);
+            if (peek) {
+                const peekIndent = peek.line.length - peek.line.trimStart().length;
+                const peekTrim = peek.line.trim();
+                if (peekIndent > expectedIndent && (peekTrim.startsWith('- ') || peekTrim === '-')) {
+                    const arr = parseArrayBlock(lines, i + 1, peekIndent);
+                    if (!arr.ok)
+                        return err(arr.error);
+                    if (Array.isArray(arr.value.value) && arr.value.value.every(isScalarLike)) {
+                        obj[key] = arr.value.value;
+                    }
+                    else {
+                        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Nested object-arrays are not supported inside nested objects (line ${i + 1})`));
+                    }
+                    i = arr.value.nextIndex;
+                    continue;
+                }
+            }
+            obj[key] = null;
+        }
+        else {
+            const scalar = parseInlineScalar(value, i + 1);
+            if (!scalar.ok)
+                return err(scalar.error);
+            obj[key] = scalar.value;
+        }
+        i++;
+    }
+    return ok({ value: obj, nextIndex: i });
+}
+function isScalarLike(v) {
+    return (v === null ||
+        typeof v === 'string' ||
+        typeof v === 'number' ||
+        typeof v === 'boolean');
+}
+function findUnquotedColon(s) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (c === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (c === ':' && !inSingle && !inDouble)
+            return i;
+    }
+    return -1;
+}
+export function parseInlineScalar(s, line) {
+    const trimmed = stripTrailingComment(s).trim();
+    if (trimmed.length === 0)
+        return ok(null);
+    if (trimmed === 'null' || trimmed === '~')
+        return ok(null);
+    if (trimmed === 'true')
+        return ok(true);
+    if (trimmed === 'false')
+        return ok(false);
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
+        return ok(unescapeDoubleQuoted(trimmed.slice(1, -1)));
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2) {
+        return ok(trimmed.slice(1, -1));
+    }
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        return parseInlineArray(trimmed, line);
+    }
+    if (/^-?\d+$/.test(trimmed)) {
+        return ok(Number.parseInt(trimmed, 10));
+    }
+    if (/^-?\d+\.\d+$/.test(trimmed)) {
+        return ok(Number.parseFloat(trimmed));
+    }
+    // Bare string (no quotes). Forbid embedded control characters.
+    if (/[\x00-\x08\x0B-\x1F]/.test(trimmed)) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Control character in bare string at line ${line}`));
+    }
+    return ok(trimmed);
+}
+function parseInlineArray(s, line) {
+    const inner = s.slice(1, -1).trim();
+    if (inner.length === 0)
+        return ok([]);
+    const parts = splitTopLevelCommas(inner);
+    const out = [];
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (trimmed.length === 0)
+            continue;
+        const scalar = parseInlineScalar(trimmed, line);
+        if (!scalar.ok)
+            return err(scalar.error);
+        if (Array.isArray(scalar.value)) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Nested inline arrays are not supported (line ${line})`));
+        }
+        out.push(scalar.value);
+    }
+    return ok(out);
+}
+function splitTopLevelCommas(s) {
+    const out = [];
+    let cur = '';
+    let inSingle = false;
+    let inDouble = false;
+    let depth = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (c === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (!inSingle && !inDouble) {
+            if (c === '[' || c === '{')
+                depth++;
+            else if (c === ']' || c === '}')
+                depth--;
+            else if (c === ',' && depth === 0) {
+                out.push(cur);
+                cur = '';
+                continue;
+            }
+        }
+        cur += c;
+    }
+    out.push(cur);
+    return out;
+}
+function stripTrailingComment(s) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (c === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (c === '#' && !inSingle && !inDouble) {
+            const prev = s[i - 1];
+            if (prev === undefined || prev === ' ' || prev === '\t')
+                return s.slice(0, i);
+        }
+    }
+    return s;
+}
+function unescapeDoubleQuoted(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === '\\' && i + 1 < s.length) {
+            const next = s[i + 1];
+            if (next === 'n')
+                out += '\n';
+            else if (next === 't')
+                out += '\t';
+            else if (next === '\\')
+                out += '\\';
+            else if (next === '"')
+                out += '"';
+            else
+                out += next;
+            i++;
+        }
+        else {
+            out += c;
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Spec id construction and conflict resolution.
+ *
+ * Spec ids are `<YYYY-MM-DD>-<slug>` where `<slug>` is kebab-case.
+ * Conflicts (same-day, same-slug) resolve via numeric suffixes `-2`,
+ * `-3`, etc. The id is the directory name under `.sharkcraft/specs/`,
+ * so it must be safe for any filesystem and stable across spec edits.
+ */
+export interface IBuildSpecIdInput {
+    /** Spec title or seed string. */
+    readonly title: string;
+    /** Optional explicit slug override (overrides title-derived slug). */
+    readonly slug?: string;
+    /**
+     * Date string in YYYY-MM-DD form. Defaults to the current UTC date
+     * if omitted.
+     */
+    readonly date?: string;
+    /** Pre-existing spec ids (full ids, not slugs) for collision detection. */
+    readonly existingIds?: readonly string[];
+}
+export interface IBuiltSpecId {
+    readonly id: string;
+    readonly slug: string;
+    readonly date: string;
+}
+export declare function buildSpecId(input: IBuildSpecIdInput): IBuiltSpecId;
+export declare function normalizeSlug(input: string): string;
+export declare function todayIsoDate(now?: Date): string;
+//# sourceMappingURL=spec-id.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spec-id.d.ts","sourceRoot":"","sources":["../../src/spec/spec-id.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CASlE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED,wBAAgB,YAAY,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAK3D"}

package/dist/spec/spec-id.js

@@ -0,0 +1,38 @@
+/**
+ * Spec id construction and conflict resolution.
+ *
+ * Spec ids are `<YYYY-MM-DD>-<slug>` where `<slug>` is kebab-case.
+ * Conflicts (same-day, same-slug) resolve via numeric suffixes `-2`,
+ * `-3`, etc. The id is the directory name under `.sharkcraft/specs/`,
+ * so it must be safe for any filesystem and stable across spec edits.
+ */
+import { toKebabCase } from '@shrkcrft/core';
+export function buildSpecId(input) {
+    const slug = normalizeSlug(input.slug ?? input.title);
+    const date = input.date ?? todayIsoDate();
+    const baseId = `${date}-${slug}`;
+    const existing = new Set(input.existingIds ?? []);
+    if (!existing.has(baseId))
+        return { id: baseId, slug, date };
+    let n = 2;
+    while (existing.has(`${baseId}-${n}`))
+        n++;
+    return { id: `${baseId}-${n}`, slug, date };
+}
+export function normalizeSlug(input) {
+    const k = toKebabCase(input)
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (k.length === 0)
+        return 'spec';
+    if (!/^[a-z0-9]/.test(k))
+        return `s-${k}`;
+    return k;
+}
+export function todayIsoDate(now = new Date()) {
+    const y = now.getUTCFullYear().toString().padStart(4, '0');
+    const m = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+    const d = now.getUTCDate().toString().padStart(2, '0');
+    return `${y}-${m}-${d}`;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Read/write helpers for spec.md / spec.json / events.jsonl.
+ *
+ * Pure filesystem layer. Validation lives elsewhere; this module only
+ * reads/writes the on-disk artifacts. The directory layout is
+ * `.sharkcraft/specs/<id>/`:
+ *
+ *   spec.md           — frontmatter + body, authoritative
+ *   spec.json         — derived canonical view
+ *   plan.json         — signed combined plan (after `implement --write-plan`)
+ *   verification.json — most recent verify report (after `verify`)
+ *   events.jsonl      — append-only log of `spec` operations
+ */
+import { type AppError, type Result } from '@shrkcrft/core';
+import { SPEC_EVENTS_SCHEMA_V1, type ISpecJson } from './spec-model.js';
+export declare const SPECS_DIR_RELATIVE = ".sharkcraft/specs";
+export declare function specsRoot(projectRoot: string): string;
+export declare function specDir(projectRoot: string, id: string): string;
+export declare function specMdPath(projectRoot: string, id: string): string;
+export declare function specJsonPath(projectRoot: string, id: string): string;
+export declare function specPlanPath(projectRoot: string, id: string): string;
+export declare function specVerificationPath(projectRoot: string, id: string): string;
+export declare function specEventsPath(projectRoot: string, id: string): string;
+export declare function listSpecIds(projectRoot: string): string[];
+export declare function writeSpecMd(projectRoot: string, id: string, body: string): Result<void, AppError>;
+export declare function readSpecMd(projectRoot: string, id: string): Result<string, AppError>;
+export declare function writeSpecJson(projectRoot: string, id: string, json: ISpecJson): Result<void, AppError>;
+export declare function readSpecJson(projectRoot: string, id: string): Result<ISpecJson, AppError>;
+/**
+ * Convenience: parse spec.md, derive spec.json, return both. Does NOT
+ * read or write the cached spec.json on disk — caller decides.
+ */
+export declare function loadSpec(projectRoot: string, id: string): Result<{
+    spec: ISpecJson;
+    body: string;
+}, AppError>;
+export interface ISpecEvent {
+    readonly schema: typeof SPEC_EVENTS_SCHEMA_V1;
+    readonly ts: string;
+    readonly specId: string;
+    readonly operation: string;
+    readonly verdict?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+export declare function appendSpecEvent(projectRoot: string, id: string, event: Omit<ISpecEvent, 'schema' | 'ts' | 'specId'> & {
+    ts?: string;
+}): Result<void, AppError>;
+export declare function readSpecEvents(projectRoot: string, id: string): readonly ISpecEvent[];
+export interface IPersistSpecArtifactsInput {
+    readonly projectRoot: string;
+    readonly id: string;
+    readonly md: string;
+    readonly json: ISpecJson;
+}
+export declare function persistSpecArtifacts(input: IPersistSpecArtifactsInput): Result<void, AppError>;
+//# sourceMappingURL=spec-io.d.ts.map

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

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