@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/plans/plan-artifact.js

@@ -0,0 +1,721 @@
+/**
+ * Plan-as-FILE artifact store (Pugi backlog).
+ *
+ * Pattern absorbed from the the upstream tool `ExitPlanMode` leak intel
+ * (clean-room TypeScript reimplementation — no source was copied; only
+ * the file-as-artifact concept). When Pugi enters plan-mode the engine
+ * routes the plan body to `.pugi/plans/<plan-id>.md` instead of the
+ * message stream so it survives `/compact`, becomes diffable across
+ * sessions, and stays queryable / chainable across multi-version
+ * iterations.
+ *
+ * Public surface (lifecycle):
+ *
+ *  writePlan(taskId, body, metadata?)      — create + return {planId, path}
+ *  readPlan(planId)                        — load frontmatter + body
+ *  listPlans({ taskId? })                  — list, newest first
+ *  diffPlans(planA, planB?)                — unified diff (planB = latest)
+ *  markSuperseded(planId, supersededBy)    — add chain pointer
+ *  prunePlans({ maxAgeDays })              — GC ancient plans
+ *
+ * Plan-id format (sortable + filename-safe):
+ *
+ *  `pln_<base32-timestamp>_<short-hash>`
+ *
+ *  - `pln_`          — fixed prefix; gates listPlans + parser.
+ *  - base32-timestamp — Crockford base32 encoding of `Date.now()`. 10
+ *                       chars at the millisecond range, monotonically
+ *                       sortable, no '_' / '-' collision with the
+ *                       separator.
+ *  - short-hash      — 8 chars from `crypto.randomBytes(5)` rendered as
+ *                       Crockford base32. Disambiguates same-ms writes
+ *                       (plan races during agent ensemble fan-out).
+ *
+ *  Example: `pln_01HEZ7C2QM_X3R8WK9P`.
+ *
+ * Frontmatter schema (minimal YAML-ish, parsed without `js-yaml`):
+ *
+ *  ---
+ *  planId: pln_<base32>_<hash>
+ *  taskId: <task-slug>         # opaque caller-provided string
+ *  createdAt: <ISO-8601 UTC>
+ *  ttlDays: 30                 # GC budget; default 30
+ *  supersededBy: pln_…         # absent unless markSuperseded() ran
+ *  title: <one-line summary>   # optional, caller-provided
+ *  ---
+ *
+ *  - One `key: value` pair per line, no quoting, no nested maps.
+ *  - Keys validated against an allowlist (`KNOWN_FRONTMATTER_KEYS`);
+ *    unknown keys are dropped to avoid silent typos becoming chain
+ *    poison.
+ *  - Body follows the closing `---\n` literally — no body escaping.
+ *
+ * Storage layout:
+ *
+ *  <root>/.pugi/plans/<plan-id>.md         — file mode 0o600.
+ *  <root>/.pugi/plans/                     — dir mode 0o700.
+ *
+ * Atomic write: tmp file (`<id>.md.pugi-tmp-<epoch>`) + `renameSync`.
+ * Mirrors `apps/pugi-cli/src/tools/file-tools.ts` `editTool` so the
+ * plan store inherits the same crash-tolerant write contract.
+ */
+import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { basename, join, resolve } from 'node:path';
+/**
+ * Crockford base32 alphabet — sortable in the same order as decoded
+ * numeric value (lowercased here so plan-ids match the `pln_` prefix
+ * casing). Excludes I, L, O, U intentionally; we never include them
+ * in encoded output so the parser doesn't need a normalisation pass.
+ */
+const CROCKFORD = '0123456789abcdefghjkmnpqrstvwxyz';
+const PLAN_ID_RE = /^pln_[0-9a-z]{10}_[0-9a-z]{8}$/;
+const DEFAULT_TTL_DAYS = 30;
+const MS_PER_DAY = 86_400_000;
+const KNOWN_FRONTMATTER_KEYS = new Set([
+    'planId',
+    'taskId',
+    'createdAt',
+    'ttlDays',
+    'supersededBy',
+    'title',
+]);
+export class PlanNotFoundError extends Error {
+    planId;
+    constructor(planId) {
+        super(`plan not found: ${planId}`);
+        this.planId = planId;
+        this.name = 'PlanNotFoundError';
+    }
+}
+export class InvalidPlanIdError extends Error {
+    planId;
+    constructor(planId) {
+        super(`invalid plan id: ${planId} (expected pln_<base32-timestamp>_<short-hash>)`);
+        this.planId = planId;
+        this.name = 'InvalidPlanIdError';
+    }
+}
+/**
+ * Resolve the `.pugi/plans` directory under a root, creating it (and
+ * the parent `.pugi/`) if missing. Dir mode is 0o700 — only the owner
+ * should be able to enumerate plans. File mode 0o600 is enforced
+ * separately at write-time.
+ */
+function plansDir(root) {
+    const dir = resolve(root, '.pugi', 'plans');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+/** Encode a non-negative integer in Crockford base32 (lowercased). */
+function encodeBase32(input, length) {
+    if (!Number.isFinite(input) || input < 0) {
+        throw new Error(`encodeBase32: non-negative finite required, got ${input}`);
+    }
+    let value = Math.floor(input);
+    const out = [];
+    while (value > 0) {
+        const idx = value % 32;
+        const ch = CROCKFORD[idx];
+        if (ch === undefined) {
+            throw new Error('encodeBase32: alphabet lookup failed');
+        }
+        out.unshift(ch);
+        value = Math.floor(value / 32);
+    }
+    while (out.length < length) {
+        out.unshift('0');
+    }
+    return out.join('').slice(-length);
+}
+/** Encode a byte buffer as Crockford base32 (lowercased), no padding. */
+function bytesToBase32(buf, length) {
+    let bits = 0;
+    let bitCount = 0;
+    const out = [];
+    for (let i = 0; i < buf.length; i += 1) {
+        const byte = buf[i];
+        if (byte === undefined)
+            continue;
+        bits = (bits << 8) | byte;
+        bitCount += 8;
+        while (bitCount >= 5 && out.length < length) {
+            const shift = bitCount - 5;
+            const idx = (bits >> shift) & 0x1f;
+            const ch = CROCKFORD[idx];
+            if (ch === undefined) {
+                throw new Error('bytesToBase32: alphabet lookup failed');
+            }
+            out.push(ch);
+            bits &= (1 << shift) - 1;
+            bitCount -= 5;
+        }
+    }
+    while (out.length < length) {
+        out.push('0');
+    }
+    return out.join('').slice(0, length);
+}
+/**
+ * Generate a new plan-id. Caller can override the timestamp + RNG for
+ * deterministic tests; production code calls with no args.
+ */
+export function generatePlanId(now = Date.now(), rng) {
+    const ts = encodeBase32(now, 10);
+    const buf = rng ? rng() : randomBytes(5);
+    const hash = bytesToBase32(buf, 8);
+    return `pln_${ts}_${hash}`;
+}
+/**
+ * Validate a plan-id at the shape level. Returns the id unchanged on
+ * pass; throws `InvalidPlanIdError` on fail. Keeps the parser tight so
+ * stray `../../.ssh/id_rsa` injection attempts cannot reach disk.
+ */
+export function assertValidPlanId(planId) {
+    if (typeof planId !== 'string' || !PLAN_ID_RE.test(planId)) {
+        throw new InvalidPlanIdError(planId);
+    }
+    return planId;
+}
+/**
+ * Triple-review P1-4 — escape YAML-ambiguous string values so an
+ * adversarial `title` containing `:`, `#`, leading `-`/`*`, leading
+ * whitespace, control chars, newlines, or quotes cannot break the
+ * frontmatter parse OR inject a second key.
+ *
+ * Strategy: if the raw value contains ANY ambiguous character, fall
+ * back to JSON.stringify which gives us a valid YAML-double-quoted
+ * scalar (YAML accepts JSON's quoting + escape rules as a strict
+ * superset for double-quoted flow scalars). For "boring" values we
+ * keep the bareword form so the round-trip stays human-readable.
+ *
+ * `planId`, `taskId`, `createdAt`, `ttlDays`, `supersededBy` are not
+ * routed through this escaper because they are validated upstream to a
+ * conservative grapheme set (regex / Number) and the bareword form is
+ * the only legitimate shape. Title is the one operator-supplied free
+ * field.
+ */
+function yamlScalar(value) {
+    // Ambiguous chars from the YAML 1.2 spec + practical Pugi history:
+    //  ':' '#' newline tab '"' "'" leading whitespace leading '-' leading '*'
+    //  leading '?' leading '|' leading '>' leading '&' leading '!' leading '@'
+    //  leading '`' leading '%' leading '[' leading '{' or any control char.
+    // Empty string is also disambiguated by quoting.
+    if (value.length === 0)
+        return '""';
+    if (/[-"]/.test(value)) {
+        return JSON.stringify(value);
+    }
+    if (/[:#\n\t]/.test(value)) {
+        return JSON.stringify(value);
+    }
+    if (/^[\s\-*?|>&!@`%[{]/.test(value)) {
+        return JSON.stringify(value);
+    }
+    return value;
+}
+/** Serialize frontmatter + body into the on-disk envelope. */
+function serializePlan(frontmatter, body) {
+    const lines = ['---'];
+    // Stable key order — keeps round-trip deterministic for tests.
+    // planId / taskId / createdAt / supersededBy are validated upstream
+    // to safe shapes; ttlDays is a number. Title is operator-supplied
+    // free text → route through `yamlScalar`.
+    lines.push(`planId: ${frontmatter.planId}`);
+    lines.push(`taskId: ${yamlScalar(frontmatter.taskId)}`);
+    lines.push(`createdAt: ${frontmatter.createdAt}`);
+    lines.push(`ttlDays: ${frontmatter.ttlDays}`);
+    if (frontmatter.supersededBy !== undefined) {
+        lines.push(`supersededBy: ${frontmatter.supersededBy}`);
+    }
+    if (frontmatter.title !== undefined) {
+        lines.push(`title: ${yamlScalar(frontmatter.title)}`);
+    }
+    lines.push('---');
+    lines.push('');
+    return `${lines.join('\n')}${body.endsWith('\n') ? body : `${body}\n`}`;
+}
+/**
+ * Triple-review P1-4 (parse side) — decode the scalar form
+ * `serializePlan` produces. Bareword inputs pass through; a JSON-quoted
+ * scalar is unquoted via JSON.parse so the value matches what the
+ * writer recorded. Invalid quoted scalars surface as a clear parse
+ * error so a corrupt plan never silently returns half-decoded data.
+ */
+function parseYamlScalar(raw, path, key) {
+    if (raw.length === 0)
+        return raw;
+    if (raw.startsWith('"')) {
+        try {
+            const decoded = JSON.parse(raw);
+            if (typeof decoded !== 'string') {
+                throw new Error(`expected string scalar`);
+            }
+            return decoded;
+        }
+        catch (err) {
+            throw new Error(`plan file ${path}: invalid quoted scalar for '${key}': ${err.message}`);
+        }
+    }
+    return raw;
+}
+/**
+ * Parse the on-disk envelope. Tolerant of trailing whitespace on
+ * frontmatter values and missing `title` / `supersededBy`. Throws if
+ * a required key is missing OR the frontmatter delimiter is absent —
+ * a corrupt plan file should never silently return a half-state record.
+ *
+ * Triple-review P1-2 — also asserts that the on-disk filename
+ * basename matches the `planId` in the frontmatter. Defends against
+ * rename-then-edit drift where someone (an editor, an agent, a CI
+ * step) renamed `<a>.md` к `<b>.md` without rewriting the body.
+ */
+function parsePlan(text, path) {
+    const lines = text.split('\n');
+    if (lines[0] !== '---') {
+        throw new Error(`plan file missing opening '---': ${path}`);
+    }
+    const closingIdx = lines.indexOf('---', 1);
+    if (closingIdx === -1) {
+        throw new Error(`plan file missing closing '---': ${path}`);
+    }
+    const fm = {};
+    for (let i = 1; i < closingIdx; i += 1) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const sepIdx = line.indexOf(':');
+        if (sepIdx === -1)
+            continue;
+        const rawKey = line.slice(0, sepIdx).trim();
+        const rawVal = line.slice(sepIdx + 1).trim();
+        if (!KNOWN_FRONTMATTER_KEYS.has(rawKey))
+            continue;
+        if (rawKey === 'ttlDays') {
+            const n = Number(rawVal);
+            if (!Number.isFinite(n) || n <= 0) {
+                throw new Error(`plan file ${path}: invalid ttlDays '${rawVal}'`);
+            }
+            fm.ttlDays = n;
+        }
+        else if (rawKey === 'title' || rawKey === 'taskId') {
+            // Operator / caller free-text fields — decode through the
+            // YAML-scalar parser к round-trip the writer's quoting.
+            fm[rawKey] = parseYamlScalar(rawVal, path, rawKey);
+        }
+        else {
+            // planId / createdAt / supersededBy — validated upstream к safe
+            // shapes; bareword.
+            fm[rawKey] = rawVal;
+        }
+    }
+    if (!fm.planId || !fm.taskId || !fm.createdAt || fm.ttlDays === undefined) {
+        throw new Error(`plan file ${path}: frontmatter missing required keys (planId/taskId/createdAt/ttlDays)`);
+    }
+    // Re-validate the on-disk planId — defends against rename-tampering
+    // where the filename was renamed but the body planId was not (or
+    // vice-versa). The caller will trust frontmatter, not the basename.
+    assertValidPlanId(fm.planId);
+    // Triple-review P1-2 — assert filename ↔ frontmatter coherence.
+    // The on-disk basename MUST equal `<planId>.md`; mismatch indicates
+    // tampering and we refuse loud rather than returning a record whose
+    // `path` and `planId` point at different artifacts.
+    const expectedBasename = `${fm.planId}.md`;
+    const actualBasename = basename(path);
+    if (actualBasename !== expectedBasename) {
+        throw new Error(`plan file ${path}: filename '${actualBasename}' does not match frontmatter planId '${fm.planId}'`);
+    }
+    const body = lines.slice(closingIdx + 1).join('\n').replace(/^\n/, '');
+    return {
+        frontmatter: fm,
+        body,
+        path,
+    };
+}
+/**
+ * Triple-review P1-1 — reject any pre-existing symlink at the
+ * target plan path. `existsSync` follows symlinks, so a hostile
+ * symlink at `.pugi/plans/<id>.md` pointing к an arbitrary location
+ * would let a write escape the plan dir. `lstatSync` inspects the link
+ * itself; we refuse loud rather than silently following it.
+ *
+ * Returns true when the path is safe (does not exist OR exists as a
+ * regular file); throws when the path exists as a symlink. Other entry
+ * types (directory, socket, fifo, ...) also throw because they are
+ * never legitimate plan targets.
+ */
+function assertPlanPathSafe(targetPath) {
+    let stats;
+    try {
+        stats = lstatSync(targetPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return;
+        throw err;
+    }
+    if (stats.isSymbolicLink()) {
+        throw new Error(`plan path '${targetPath}' is a symlink — refusing к follow (security)`);
+    }
+    if (!stats.isFile()) {
+        throw new Error(`plan path '${targetPath}' exists but is not a regular file (type=${stats.mode & 0o170000})`);
+    }
+}
+/**
+ * Atomically write a new plan to disk. Returns the generated `planId`
+ * and absolute `path`. Plan-id collisions are statistically
+ * negligible (40-bit hash + ms timestamp); on the freak collision we
+ * regenerate up to 3 times before bubbling an error.
+ *
+ * Triple-review P1-1 +-3 — write path is now TOCTOU-free:
+ *
+ *  1. `assertPlanPathSafe` rejects а pre-existing symlink before we
+ *     touch the filesystem (defends against `.pugi/plans/<id>.md`
+ *     being a planted alias к `.ssh/id_rsa`).
+ *  2. The tmp + `linkSync` + `unlinkSync(tmp)` sequence is the
+ *     POSIX atomic-claim idiom: linkSync fails with EEXIST when the
+ *     target is already present, so two racing writers cannot both
+ *     `existsSync = false`-then-`writeFile` over each other. This
+ *     replaces the previous `existsSync` check that opened а
+ *     check-then-write window.
+ */
+export function writePlan(taskId, planText, metadata = {}, options = {}) {
+    if (typeof taskId !== 'string' || taskId.length === 0) {
+        throw new Error('writePlan: taskId must be a non-empty string');
+    }
+    if (typeof planText !== 'string') {
+        throw new Error('writePlan: planText must be a string');
+    }
+    const root = options.root ?? process.cwd();
+    const dir = plansDir(root);
+    const ttlDays = clampTtl(metadata.ttlDays ?? DEFAULT_TTL_DAYS);
+    let planId = '';
+    let target = '';
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        planId = generatePlanId(options.now ?? Date.now());
+        target = join(dir, `${planId}.md`);
+        // lstat-based safety — refuses symlinks AND surfaces dir / socket
+        // / fifo as errors. existsSync would have silently followed а
+        // hostile symlink.
+        assertPlanPathSafe(target);
+        if (!existsSync(target))
+            break;
+        if (attempt === 2) {
+            throw new Error(`writePlan: failed to allocate unique plan id after 3 attempts`);
+        }
+    }
+    const frontmatter = {
+        planId,
+        taskId,
+        createdAt: new Date(options.now ?? Date.now()).toISOString(),
+        ttlDays,
+        ...(metadata.title !== undefined ? { title: metadata.title } : {}),
+    };
+    const envelope = serializePlan(frontmatter, planText);
+    const tmp = `${target}.pugi-tmp-${Date.now()}-${process.pid}`;
+    writeFileSync(tmp, envelope, { encoding: 'utf8', mode: 0o600 });
+    // Atomic claim: linkSync(tmp, target) succeeds iff `target` does not
+    // exist (errno EEXIST otherwise — surfaced as а clear error). The
+    // tmp is then unlinked. Cross-filesystem links are not а concern
+    // because tmp + target live in the same dir.
+    try {
+        linkSync(tmp, target);
+    }
+    catch (err) {
+        // Best-effort cleanup of the orphan tmp before rethrowing.
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* ignore */
+        }
+        const code = err.code;
+        if (code === 'EEXIST') {
+            throw new Error(`writePlan: plan ${planId}.md already exists; use а different planId or remove the existing file`);
+        }
+        throw err;
+    }
+    // Drop the tmp — the inode is now linked at `target` so the data is
+    // safe even if the unlink fails (we then leak а tmp file, recoverable
+    // by а future GC). Wrapped in а best-effort so the unlink failure
+    // does not surface as а write failure.
+    try {
+        unlinkSync(tmp);
+    }
+    catch {
+        /* ignore — tmp leak is recoverable */
+    }
+    return { planId, path: target };
+}
+function clampTtl(raw) {
+    if (!Number.isFinite(raw))
+        return DEFAULT_TTL_DAYS;
+    if (raw < 1)
+        return 1;
+    if (raw > 365)
+        return 365;
+    return Math.floor(raw);
+}
+/** Load a plan record by id. Throws `PlanNotFoundError` if missing. */
+export function readPlan(planId, options = {}) {
+    assertValidPlanId(planId);
+    const root = options.root ?? process.cwd();
+    const target = join(plansDir(root), `${planId}.md`);
+    if (!existsSync(target)) {
+        throw new PlanNotFoundError(planId);
+    }
+    const text = readFileSync(target, 'utf8');
+    return parsePlan(text, target);
+}
+/**
+ * Enumerate plans newest-first, optionally filtered by taskId. Files
+ * with malformed frontmatter are silently skipped — they will surface
+ * in the next `/plan diff` attempt against them.
+ */
+export function listPlans(options = {}) {
+    const root = options.root ?? process.cwd();
+    const dir = plansDir(root);
+    const entries = readdirSync(dir).filter((name) => name.endsWith('.md'));
+    const records = [];
+    for (const name of entries) {
+        const planId = name.slice(0, -'.md'.length);
+        if (!PLAN_ID_RE.test(planId))
+            continue;
+        try {
+            const record = readPlan(planId, { root });
+            if (options.taskId && record.frontmatter.taskId !== options.taskId) {
+                continue;
+            }
+            records.push(record);
+        }
+        catch {
+            // Malformed plan files are skipped; the maintainer can run
+            // `/plan show <id>` to surface the parse error explicitly.
+            continue;
+        }
+    }
+    // Sort newest first by createdAt (ISO-8601 sorts lexicographically).
+    records.sort((a, b) => (a.frontmatter.createdAt < b.frontmatter.createdAt ? 1 : -1));
+    return records;
+}
+/**
+ * Compute a unified diff between two plans. When `planB` is omitted,
+ * diffs `planA` against the most recent plan that is NOT `planA`. A
+ * small in-process diff implementation avoids pulling in a `diff` dep —
+ * the algorithm is the well-known Hunt-Szymanski-lite LCS adequate for
+ * line-oriented prose under ~10k lines.
+ */
+export function diffPlans(planA, planB, options = {}) {
+    const root = options.root ?? process.cwd();
+    const recordA = readPlan(planA, { root });
+    let recordB;
+    if (planB) {
+        recordB = readPlan(planB, { root });
+    }
+    else {
+        const all = listPlans({ root });
+        const other = all.find((rec) => rec.frontmatter.planId !== planA);
+        if (!other) {
+            throw new PlanNotFoundError('<latest-other>');
+        }
+        recordB = other;
+    }
+    return unifiedDiff(`${recordB.frontmatter.planId}.md`, `${recordA.frontmatter.planId}.md`, recordB.body, recordA.body);
+}
+/**
+ * Update an existing plan to record that it has been superseded by
+ * another plan-id. Both ids must exist on disk — we refuse to write a
+ * dangling pointer. Re-writes the file atomically.
+ */
+export function markSuperseded(planId, supersededBy, options = {}) {
+    assertValidPlanId(planId);
+    assertValidPlanId(supersededBy);
+    if (planId === supersededBy) {
+        throw new Error(`markSuperseded: plan cannot supersede itself (${planId})`);
+    }
+    const root = options.root ?? process.cwd();
+    const current = readPlan(planId, { root });
+    // Confirm the successor exists too — refuse dangling pointers so
+    // chain-walks in the runtime can trust the graph.
+    readPlan(supersededBy, { root });
+    const next = {
+        ...current.frontmatter,
+        supersededBy,
+    };
+    const target = join(plansDir(root), `${planId}.md`);
+    // Triple-review P1-1 — symlink check before the rewrite. The
+    // existing target MUST be а regular file; а symlink swapped в
+    // between `readPlan` and this point would otherwise let an attacker
+    // redirect the atomic rename к а protected basename.
+    assertPlanPathSafe(target);
+    const tmp = `${target}.pugi-tmp-${Date.now()}-${process.pid}`;
+    const envelope = serializePlan(next, current.body);
+    writeFileSync(tmp, envelope, { encoding: 'utf8', mode: 0o600 });
+    try {
+        // renameSync is the right primitive HERE (in markSuperseded) — we
+        // are intentionally overwriting an existing plan. writePlan uses
+        // linkSync because it MUST refuse pre-existing targets; the two
+        // semantics are intentionally different.
+        renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* ignore */
+        }
+        throw err;
+    }
+    return { frontmatter: next, body: current.body, path: target };
+}
+/**
+ * Garbage-collect plans older than `maxAgeDays`. Default budget is 30
+ * days, matching the default `ttlDays` on `writePlan`. Plans flagged
+ * with their own larger `ttlDays` are preserved beyond the sweep
+ * window — the per-plan TTL wins over the sweep floor.
+ */
+export function prunePlans(options = {}) {
+    const root = options.root ?? process.cwd();
+    const dir = plansDir(root);
+    const floorDays = options.maxAgeDays ?? DEFAULT_TTL_DAYS;
+    const now = Date.now();
+    const removed = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.md'))
+            continue;
+        const planId = name.slice(0, -'.md'.length);
+        if (!PLAN_ID_RE.test(planId))
+            continue;
+        const target = join(dir, name);
+        let record;
+        try {
+            record = readPlan(planId, { root });
+        }
+        catch {
+            // Malformed plan files are removed too — they cannot be
+            // recovered and they shadow the listing. Belt-and-braces with
+            // mtime fallback so a brand-new corrupt file is not wiped if
+            // its mtime is below the floor.
+            const stat = statSync(target);
+            const ageDays = (now - stat.mtimeMs) / MS_PER_DAY;
+            if (ageDays > floorDays) {
+                try {
+                    unlinkSync(target);
+                    removed.push(planId);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            continue;
+        }
+        const createdMs = Date.parse(record.frontmatter.createdAt);
+        if (!Number.isFinite(createdMs))
+            continue;
+        const ageDays = (now - createdMs) / MS_PER_DAY;
+        const ttl = Math.max(record.frontmatter.ttlDays, floorDays);
+        if (ageDays > ttl) {
+            try {
+                unlinkSync(target);
+                removed.push(planId);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    return { cleaned: removed.length, removedIds: removed };
+}
+/**
+ * Minimal unified-diff renderer. Uses an O(n*m) DP table; adequate for
+ * the plan body sizes we expect (sub-kB to mid-kB Markdown). Output
+ * matches the GNU `diff -u` envelope so existing CLI tooling (`less
+ * -R`, `delta`, etc.) can colourise it without translation.
+ */
+function unifiedDiff(fromName, toName, fromText, toText) {
+    const a = fromText.split('\n');
+    const b = toText.split('\n');
+    const n = a.length;
+    const m = b.length;
+    // LCS DP table.
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            const rowI = dp[i];
+            const rowI1 = dp[i + 1];
+            if (!rowI || !rowI1)
+                continue;
+            const ai = a[i];
+            const bj = b[j];
+            const next = rowI1[j + 1] ?? 0;
+            const down = rowI1[j] ?? 0;
+            const right = rowI[j + 1] ?? 0;
+            if (ai === bj) {
+                rowI[j] = next + 1;
+            }
+            else {
+                rowI[j] = Math.max(down, right);
+            }
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        const ai = a[i];
+        const bj = b[j];
+        const rowI1 = dp[i + 1];
+        const rowI = dp[i];
+        const down = rowI1?.[j] ?? 0;
+        const right = rowI?.[j + 1] ?? 0;
+        if (ai === bj) {
+            ops.push({ kind: 'eq', line: ai ?? '' });
+            i += 1;
+            j += 1;
+        }
+        else if (down >= right) {
+            ops.push({ kind: 'del', line: ai ?? '' });
+            i += 1;
+        }
+        else {
+            ops.push({ kind: 'add', line: bj ?? '' });
+            j += 1;
+        }
+    }
+    while (i < n) {
+        ops.push({ kind: 'del', line: a[i] ?? '' });
+        i += 1;
+    }
+    while (j < m) {
+        ops.push({ kind: 'add', line: b[j] ?? '' });
+        j += 1;
+    }
+    // Render. We emit one big hunk that spans the whole document — fine
+    // for plan-sized prose and keeps the renderer simple. Header counts
+    // are the full file lengths because hunk == file.
+    const out = [];
+    out.push(`--- a/${fromName}`);
+    out.push(`+++ b/${toName}`);
+    out.push(`@@ -1,${n} +1,${m} @@`);
+    for (const op of ops) {
+        if (op.kind === 'eq')
+            out.push(` ${op.line}`);
+        else if (op.kind === 'del')
+            out.push(`-${op.line}`);
+        else
+            out.push(`+${op.line}`);
+    }
+    return out.join('\n');
+}
+/** Test-only accessor — kept for future tooling that needs to peek. */
+export const __test__ = {
+    PLAN_ID_RE,
+    CROCKFORD,
+    KNOWN_FRONTMATTER_KEYS,
+    DEFAULT_TTL_DAYS,
+};
+//# sourceMappingURL=plan-artifact.js.map