@deskwork/core 0.9.5

package/dist/ingest.d.ts

@@ -0,0 +1,162 @@
+/**
+ * ingest.ts — discovery primitive for backfilling existing markdown
+ * content into the editorial calendar.
+ *
+ * Turns "files on disk" into "calendar candidates" without touching
+ * the calendar itself. The CLI layer wires this output into a
+ * dry-run plan or an `--apply` write; this module is purely
+ * descriptive.
+ *
+ * Responsibilities split across three files:
+ *
+ *   - `ingest.ts` (this file) — orchestrates discovery, applies
+ *     idempotency filtering against an existing calendar, and shapes
+ *     candidates into `IngestCandidate` records ready for the apply
+ *     layer.
+ *   - `ingest-paths.ts` — walks file / directory / glob inputs and
+ *     produces `(filePath, root)` tuples.
+ *   - `ingest-derive.ts` — slug / state / date / title derivation
+ *     with provenance recording.
+ *
+ * What's intentionally out of scope:
+ *
+ *   - Mutations: `discoverIngestCandidates` never writes to disk,
+ *     never mutates the calendar.
+ *   - Auto-detection of the content tree: the operator passes paths
+ *     explicitly. Walking the entire repo would scoop up
+ *     node_modules / vendored docs / unrelated markdown.
+ *   - Migrations from other calendar formats: source is markdown
+ *     files + their frontmatter. Importing from Notion / Airtable
+ *     is a separate concern (PRD extension).
+ */
+import { type FrontmatterData } from './frontmatter.ts';
+import type { CalendarEntry, EditorialCalendar, Stage } from './types.ts';
+import { type DerivationSource } from './ingest-derive.ts';
+export type { DerivationSource } from './ingest-derive.ts';
+/** A markdown file resolved to a (slug, state, date) triple ready to commit. */
+export interface IngestCandidate {
+    /** Absolute path to the source markdown file. */
+    filePath: string;
+    /** Path relative to the project root, when one was supplied. Display-only. */
+    relativePath: string;
+    /** Parsed YAML frontmatter (empty object when absent). */
+    frontmatter: FrontmatterData;
+    /** Body of the markdown file (everything after the closing `---`). */
+    body: string;
+    /** Derived slug; honours `--slug-from`, `--slug`, frontmatter, then path. */
+    derivedSlug: string;
+    /** Where `derivedSlug` came from. */
+    slugSource: DerivationSource;
+    /**
+     * Derived stage. `null` when the source produced an unrecognized
+     * state value — the operator must pass `--state` to commit.
+     * Surfaces in the plan as `state: ambiguous`.
+     */
+    derivedState: Stage | null;
+    /** Where `derivedState` came from. */
+    stateSource: DerivationSource;
+    /**
+     * Raw state string the source produced (e.g. `'published-elsewhere'`)
+     * when normalization failed. `undefined` when state was derived
+     * unambiguously.
+     */
+    rawState?: string;
+    /** Derived date in ISO YYYY-MM-DD form. */
+    derivedDate: string;
+    /** Where `derivedDate` came from. */
+    dateSource: DerivationSource;
+    /**
+     * Title pulled from frontmatter — falls back to a humanized slug
+     * when absent. The CLI emits this onto the new calendar row.
+     */
+    title: string;
+    /** Description pulled from frontmatter — empty string when absent. */
+    description: string;
+}
+/** A candidate that won't be added; carries a reason the operator can act on. */
+export interface IngestSkip {
+    filePath: string;
+    relativePath: string;
+    /** Slug we would have used; `undefined` when we couldn't derive one. */
+    slug?: string;
+    reason: string;
+}
+/** Result of a discovery pass — successes and skips, never mutations. */
+export interface IngestDiscoveryResult {
+    candidates: IngestCandidate[];
+    skips: IngestSkip[];
+}
+export type SlugFrom = 'frontmatter' | 'path';
+export type StateFrom = 'frontmatter' | 'datePublished';
+export interface IngestOptions {
+    /**
+     * Project root for relative-path display + scrapbook detection.
+     * Required; the discovery surface always runs in the context of a
+     * deskwork-installed project.
+     */
+    projectRoot: string;
+    /** Where to derive slugs from. Default `'path'`. */
+    slugFrom?: SlugFrom;
+    /** Where to derive states from. Default `'frontmatter'`. */
+    stateFrom?: StateFrom;
+    /**
+     * Explicit slug. Only honored when discovery resolves to exactly
+     * one candidate file — the CLI enforces this before calling.
+     */
+    explicitSlug?: string;
+    /** Explicit stage. Wins over derivation when set. */
+    explicitState?: Stage;
+    /** Explicit ISO date (YYYY-MM-DD). Wins over derivation when set. */
+    explicitDate?: string;
+    /** Frontmatter field-name overrides — match the operator's project schema. */
+    fieldNames?: {
+        title?: string;
+        description?: string;
+        slug?: string;
+        state?: string;
+        date?: string;
+    };
+    /**
+     * Existing calendar to filter against for idempotency. When omitted,
+     * no idempotency check runs (every candidate proceeds). The CLI
+     * always supplies this; tests omit it to exercise discovery alone.
+     */
+    calendar?: EditorialCalendar;
+    /**
+     * Bypass the duplicate-slug skip. The CLI exposes this as `--force`
+     * and warns the operator that existing rows will be left as-is —
+     * `discoverIngestCandidates` does not mutate, so "force" simply
+     * means "don't skip; pass through and let the apply layer decide".
+     */
+    force?: boolean;
+    /**
+     * Skip files under any of these absolute paths — host projects use
+     * a scrapbook directory for sketches that aren't on the editorial
+     * calendar. The CLI threads `<contentDir>/scrapbook` (one per site)
+     * into this list. Default `[]` (no skipping).
+     */
+    scrapbookRoots?: string[];
+    /** Today's date for date-derivation fallback. Test seam; defaults to now(). */
+    now?: Date;
+}
+/**
+ * Walk the supplied paths, parse markdown files, and produce a
+ * candidate list ready to feed to the apply layer.
+ *
+ * `paths` accepts:
+ *   - a single markdown file (`.md`, `.mdx`, `.markdown`)
+ *   - a directory walked recursively
+ *   - a glob (any path containing `*` or `?`)
+ *
+ * Errors during parse (bad frontmatter, unreadable file) surface as
+ * `IngestSkip` records with a descriptive reason — discovery never
+ * throws on a per-file problem so a 100-file run isn't aborted by
+ * one corrupt source.
+ */
+export declare function discoverIngestCandidates(paths: string[], options: IngestOptions): IngestDiscoveryResult;
+/**
+ * Build the CalendarEntry that the apply layer will append for a
+ * given candidate. Pure shaping — does not touch the calendar.
+ */
+export declare function candidateToEntry(candidate: IngestCandidate, stage: Stage): Omit<CalendarEntry, 'id'>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../src/ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAM3D,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,EAAE,eAAe,CAAC;IAC7B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;OAIG;IACH,YAAY,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,sCAAsC;IACtC,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAMD,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,eAAe,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,aAAa,CAAC,EAAE,KAAK,CAAC;IACtB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,UAAU,CAAC,EAAE;QACX,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,+EAA+E;IAC/E,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,aAAa,GACrB,qBAAqB,CA+JvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE,KAAK,GACX,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAe3B"}

package/dist/ingest.js

@@ -0,0 +1,269 @@
+/**
+ * ingest.ts — discovery primitive for backfilling existing markdown
+ * content into the editorial calendar.
+ *
+ * Turns "files on disk" into "calendar candidates" without touching
+ * the calendar itself. The CLI layer wires this output into a
+ * dry-run plan or an `--apply` write; this module is purely
+ * descriptive.
+ *
+ * Responsibilities split across three files:
+ *
+ *   - `ingest.ts` (this file) — orchestrates discovery, applies
+ *     idempotency filtering against an existing calendar, and shapes
+ *     candidates into `IngestCandidate` records ready for the apply
+ *     layer.
+ *   - `ingest-paths.ts` — walks file / directory / glob inputs and
+ *     produces `(filePath, root)` tuples.
+ *   - `ingest-derive.ts` — slug / state / date / title derivation
+ *     with provenance recording.
+ *
+ * What's intentionally out of scope:
+ *
+ *   - Mutations: `discoverIngestCandidates` never writes to disk,
+ *     never mutates the calendar.
+ *   - Auto-detection of the content tree: the operator passes paths
+ *     explicitly. Walking the entire repo would scoop up
+ *     node_modules / vendored docs / unrelated markdown.
+ *   - Migrations from other calendar formats: source is markdown
+ *     files + their frontmatter. Importing from Notion / Airtable
+ *     is a separate concern (PRD extension).
+ */
+import { basename, isAbsolute, relative, sep } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { parseFrontmatter } from "./frontmatter.js";
+import { collectMarkdownFiles } from "./ingest-paths.js";
+import { deriveDate, deriveDescription, deriveSlug, deriveState, deriveTitle, } from "./ingest-derive.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)*$/;
+const DEFAULT_FIELDS = {
+    title: 'title',
+    description: 'description',
+    slug: 'slug',
+    state: 'state',
+    date: 'datePublished',
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Walk the supplied paths, parse markdown files, and produce a
+ * candidate list ready to feed to the apply layer.
+ *
+ * `paths` accepts:
+ *   - a single markdown file (`.md`, `.mdx`, `.markdown`)
+ *   - a directory walked recursively
+ *   - a glob (any path containing `*` or `?`)
+ *
+ * Errors during parse (bad frontmatter, unreadable file) surface as
+ * `IngestSkip` records with a descriptive reason — discovery never
+ * throws on a per-file problem so a 100-file run isn't aborted by
+ * one corrupt source.
+ */
+export function discoverIngestCandidates(paths, options) {
+    if (paths.length === 0) {
+        throw new Error('discoverIngestCandidates: at least one path is required');
+    }
+    if (!options.projectRoot || !isAbsolute(options.projectRoot)) {
+        throw new Error(`discoverIngestCandidates: projectRoot must be an absolute path (got "${options.projectRoot ?? ''}")`);
+    }
+    const collected = collectMarkdownFiles(paths);
+    if (options.explicitSlug !== undefined && collected.length !== 1) {
+        throw new Error(`--slug requires exactly one matched file; ${collected.length} matched`);
+    }
+    const candidates = [];
+    const skips = [];
+    const fields = { ...DEFAULT_FIELDS, ...(options.fieldNames ?? {}) };
+    for (const { filePath, root } of collected) {
+        const relPath = relativeTo(options.projectRoot, filePath);
+        if (isUnderScrapbook(filePath, options.scrapbookRoots)) {
+            skips.push({
+                filePath,
+                relativePath: relPath,
+                reason: 'file is under scrapbook/ (skipped by default)',
+            });
+            continue;
+        }
+        let raw;
+        try {
+            raw = readFileSync(filePath, 'utf-8');
+        }
+        catch (err) {
+            skips.push({
+                filePath,
+                relativePath: relPath,
+                reason: `unreadable: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseFrontmatter(raw);
+        }
+        catch (err) {
+            skips.push({
+                filePath,
+                relativePath: relPath,
+                reason: `frontmatter parse failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            continue;
+        }
+        // README.md (case-insensitive) without frontmatter is treated as
+        // organizational content describing a folder's purpose — NOT a
+        // calendar entry. See #23. README.md WITH frontmatter is still
+        // ingested (Phase 13's `--layout readme` produces these).
+        if (isReadmeBasename(filePath) &&
+            Object.keys(parsed.data).length === 0) {
+            skips.push({
+                filePath,
+                relativePath: relPath,
+                reason: 'README.md without frontmatter (organizational, not pipeline)',
+            });
+            continue;
+        }
+        const slug = deriveSlug({
+            filePath,
+            root,
+            frontmatter: parsed.data,
+            fieldName: fields.slug,
+            slugFrom: options.slugFrom ?? 'path',
+            ...(options.explicitSlug !== undefined
+                ? { explicitSlug: options.explicitSlug }
+                : {}),
+        });
+        if (!slug.value) {
+            skips.push({
+                filePath,
+                relativePath: relPath,
+                reason: slug.reason ?? 'could not derive slug',
+            });
+            continue;
+        }
+        if (!SLUG_RE.test(slug.value)) {
+            skips.push({
+                filePath,
+                relativePath: relPath,
+                slug: slug.value,
+                reason: `derived slug "${slug.value}" is not valid kebab-case ` +
+                    `(must match [a-z0-9][a-z0-9-]* segments separated by '/')`,
+            });
+            continue;
+        }
+        if (options.calendar &&
+            !options.force &&
+            options.calendar.entries.some((e) => e.slug === slug.value)) {
+            skips.push({
+                filePath,
+                relativePath: relPath,
+                slug: slug.value,
+                reason: `calendar already has an entry with slug "${slug.value}" (use --force to override)`,
+            });
+            continue;
+        }
+        const state = deriveState({
+            frontmatter: parsed.data,
+            stateField: fields.state,
+            dateField: fields.date,
+            stateFrom: options.stateFrom ?? 'frontmatter',
+            ...(options.explicitState !== undefined
+                ? { explicitState: options.explicitState }
+                : {}),
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+        const date = deriveDate({
+            filePath,
+            frontmatter: parsed.data,
+            dateField: fields.date,
+            ...(options.explicitDate !== undefined
+                ? { explicitDate: options.explicitDate }
+                : {}),
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+        const title = deriveTitle(parsed.data, fields.title, slug.value);
+        const description = deriveDescription(parsed.data, fields.description);
+        candidates.push({
+            filePath,
+            relativePath: relPath,
+            frontmatter: parsed.data,
+            body: parsed.body,
+            derivedSlug: slug.value,
+            slugSource: slug.source,
+            derivedState: state.value,
+            stateSource: state.source,
+            ...(state.rawValue !== undefined ? { rawState: state.rawValue } : {}),
+            derivedDate: date.value,
+            dateSource: date.source,
+            title,
+            description,
+        });
+    }
+    return { candidates, skips };
+}
+/**
+ * Build the CalendarEntry that the apply layer will append for a
+ * given candidate. Pure shaping — does not touch the calendar.
+ */
+export function candidateToEntry(candidate, stage) {
+    const entry = {
+        slug: candidate.derivedSlug,
+        title: candidate.title,
+        description: candidate.description,
+        stage,
+        targetKeywords: [],
+        source: 'manual',
+    };
+    // Published entries carry datePublished; other lanes don't (the
+    // calendar renderer only emits the column for Published).
+    if (stage === 'Published') {
+        entry.datePublished = candidate.derivedDate;
+    }
+    return entry;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * True when the file's basename is `README.<ext>` (case-insensitive)
+ * for any of our supported markdown extensions. The frontmatter check
+ * lives at the call site — this helper is purely about the filename.
+ */
+function isReadmeBasename(filePath) {
+    const lower = basename(filePath).toLowerCase();
+    return (lower === 'readme.md' ||
+        lower === 'readme.mdx' ||
+        lower === 'readme.markdown');
+}
+function relativeTo(projectRoot, filePath) {
+    const rel = relative(projectRoot, filePath);
+    return rel.length > 0 ? rel : filePath;
+}
+function isUnderScrapbook(filePath, roots) {
+    // Path-segment match: any `scrapbook` directory segment anywhere in
+    // the path counts. The configured `roots` list still works (its
+    // entries are absolute prefixes) but is no longer required — a
+    // hierarchical content tree can have `scrapbook/` dirs at any depth
+    // (e.g. `the-outbound/scrapbook/` AND `the-outbound/characters/scrapbook/`)
+    // and every one of them must be skipped to avoid duplicate calendar
+    // rows from same-named files at different depths (issue #20).
+    //
+    // We split on the platform separator and test for an exact `scrapbook`
+    // segment so a directory literally named `scrapbookery/` does NOT
+    // false-positive.
+    const segments = filePath.split(sep);
+    if (segments.includes('scrapbook'))
+        return true;
+    // Honor any explicit roots passed in too — preserves the original
+    // contract for callers that pass absolute paths (the CLI threads the
+    // configured `<contentDir>/scrapbook` per site here).
+    if (!roots || roots.length === 0)
+        return false;
+    for (const root of roots) {
+        const r = root.endsWith(sep) ? root : root + sep;
+        if (filePath.startsWith(r))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=ingest.js.map

package/dist/ingest.js.map

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

package/dist/journal.d.ts

@@ -0,0 +1,49 @@
+/**
+ * journal.ts — directory-backed append-only record store.
+ *
+ * Each record lives in its own file under `dir/` named
+ * `<normalized-timestamp>-<id>.json`. Timestamp normalization strips
+ * filesystem-hostile characters (`:` and `.`) from ISO 8601 so the name
+ * sorts chronologically by simple string comparison and stays portable.
+ *
+ * Why not a single JSONL? Monolithic append logs produce merge conflicts
+ * when two branches each add entries to the tail — git sees overlapping
+ * line ranges. One file per entry means writes never collide by
+ * construction. Ported from audiocontrol.org's scripts/lib/journal/.
+ */
+/**
+ * Normalize an ISO 8601 timestamp for use in a filename. Colons and dots
+ * become dashes so the result is portable across filesystems and still
+ * sorts chronologically by string comparison.
+ */
+export declare function normalizeTimestamp(iso: string): string;
+export interface ReadJournalOptions {
+    /**
+     * Field on each record that carries the chronological key. Records are
+     * sorted ascending by this field's value. Defaults to `timestamp`;
+     * workflow items use `createdAt`.
+     */
+    timestampField?: string;
+}
+/** Read every record in a journal directory, oldest first. */
+export declare function readJournal<T>(dir: string, options?: ReadJournalOptions): T[];
+export interface AppendJournalOptions {
+    /** Field that holds the unique id on each record. Defaults to `id`. */
+    idField?: string;
+    /** Field that holds the timestamp on each record. Defaults to `timestamp`. */
+    timestampField?: string;
+}
+/**
+ * Write a record to its own file under `dir`. The filename is derived from
+ * the record's timestamp + id. If a file for this id already exists, it's
+ * overwritten (so a caller that regenerates an entry stays idempotent).
+ */
+export declare function appendJournal<T>(dir: string, record: T, options?: AppendJournalOptions): void;
+/**
+ * Merge `patch` into the record identified by `id`. Returns the updated
+ * record, or `null` if no record matches. Touches exactly one file.
+ */
+export declare function updateJournal<T>(dir: string, id: string, patch: Partial<T>): T | null;
+/** Remove the file for a given id. Returns true if a file was deleted. */
+export declare function deleteJournal(dir: string, id: string): boolean;
+//# sourceMappingURL=journal.d.ts.map

package/dist/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AA4BD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,CAAC,EAC3B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,kBAAuB,GAC/B,CAAC,EAAE,CAgBL;AAED,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAWN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAChB,CAAC,GAAG,IAAI,CAQV;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAK9D"}

package/dist/journal.js

@@ -0,0 +1,113 @@
+/**
+ * journal.ts — directory-backed append-only record store.
+ *
+ * Each record lives in its own file under `dir/` named
+ * `<normalized-timestamp>-<id>.json`. Timestamp normalization strips
+ * filesystem-hostile characters (`:` and `.`) from ISO 8601 so the name
+ * sorts chronologically by simple string comparison and stays portable.
+ *
+ * Why not a single JSONL? Monolithic append logs produce merge conflicts
+ * when two branches each add entries to the tail — git sees overlapping
+ * line ranges. One file per entry means writes never collide by
+ * construction. Ported from audiocontrol.org's scripts/lib/journal/.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Normalize an ISO 8601 timestamp for use in a filename. Colons and dots
+ * become dashes so the result is portable across filesystems and still
+ * sorts chronologically by string comparison.
+ */
+export function normalizeTimestamp(iso) {
+    return iso.replace(/[:.]/g, '-');
+}
+function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+function recordFilename(timestamp, id) {
+    return `${normalizeTimestamp(timestamp)}-${id}.json`;
+}
+function findFileById(dir, id) {
+    if (!existsSync(dir))
+        return null;
+    const suffix = `-${id}.json`;
+    for (const name of readdirSync(dir)) {
+        if (name.endsWith(suffix))
+            return join(dir, name);
+    }
+    return null;
+}
+function readFile(path) {
+    try {
+        const text = readFileSync(path, 'utf-8');
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Read every record in a journal directory, oldest first. */
+export function readJournal(dir, options = {}) {
+    if (!existsSync(dir))
+        return [];
+    const timestampField = options.timestampField ?? 'timestamp';
+    const records = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.json'))
+            continue;
+        const record = readFile(join(dir, name));
+        if (record === null)
+            continue;
+        records.push(record);
+    }
+    records.sort((a, b) => {
+        const aKey = String(a[timestampField] ?? '');
+        const bKey = String(b[timestampField] ?? '');
+        return aKey.localeCompare(bKey);
+    });
+    return records;
+}
+/**
+ * Write a record to its own file under `dir`. The filename is derived from
+ * the record's timestamp + id. If a file for this id already exists, it's
+ * overwritten (so a caller that regenerates an entry stays idempotent).
+ */
+export function appendJournal(dir, record, options = {}) {
+    ensureDir(dir);
+    const idField = options.idField ?? 'id';
+    const timestampField = options.timestampField ?? 'timestamp';
+    const id = String(record[idField] ?? '');
+    const timestamp = String(record[timestampField] ?? '');
+    if (!id)
+        throw new Error(`appendJournal: record has no \`${idField}\` field`);
+    if (!timestamp)
+        throw new Error(`appendJournal: record has no \`${timestampField}\` field`);
+    const existing = findFileById(dir, id);
+    const target = existing ?? join(dir, recordFilename(timestamp, id));
+    writeFileSync(target, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Merge `patch` into the record identified by `id`. Returns the updated
+ * record, or `null` if no record matches. Touches exactly one file.
+ */
+export function updateJournal(dir, id, patch) {
+    const path = findFileById(dir, id);
+    if (!path)
+        return null;
+    const current = readFile(path);
+    if (current === null)
+        return null;
+    const merged = { ...current, ...patch };
+    writeFileSync(path, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+    return merged;
+}
+/** Remove the file for a given id. Returns true if a file was deleted. */
+export function deleteJournal(dir, id) {
+    const path = findFileById(dir, id);
+    if (!path)
+        return false;
+    unlinkSync(path);
+    return true;
+}
+//# sourceMappingURL=journal.js.map

package/dist/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,cAAc,CAAC,SAAiB,EAAE,EAAU;IACnD,OAAO,GAAG,kBAAkB,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC;AACvD,CAAC;AAED,SAAS,YAAY,CAAC,GAAW,EAAE,EAAU;IAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAI,IAAY;IAC/B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAWD,8DAA8D;AAC9D,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,UAA8B,EAAE;IAEhC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,WAAW,CAAC;IAC7D,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,MAAM,MAAM,GAAG,QAAQ,CAAI,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5C,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QAC9B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,MAAM,IAAI,GAAG,MAAM,CAAE,CAA6B,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1E,MAAM,IAAI,GAAG,MAAM,CAAE,CAA6B,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AASD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,MAAS,EACT,UAAgC,EAAE;IAElC,SAAS,CAAC,GAAG,CAAC,CAAC;IACf,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC;IACxC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,WAAW,CAAC;IAC7D,MAAM,EAAE,GAAG,MAAM,CAAE,MAAkC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,MAAM,CAAE,MAAkC,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;IACpF,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,OAAO,UAAU,CAAC,CAAC;IAC9E,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,cAAc,UAAU,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IACpE,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,EAAU,EACV,KAAiB;IAEjB,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,OAAO,GAAG,QAAQ,CAAI,IAAI,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,MAAM,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,EAAO,CAAC;IAC7C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,EAAU;IACnD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,UAAU,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/outline-split.d.ts

@@ -0,0 +1,38 @@
+export interface SplitOutline {
+    /** The full outline section including the heading, or empty. */
+    outline: string;
+    /** Everything else in the document (frontmatter + title + body). */
+    body: string;
+    /** True if the document has an outline section to split. */
+    present: boolean;
+    /** Line index where the outline started (for structural rejoin). */
+    startLine: number;
+    /** Line index where the outline ended (exclusive). */
+    endLine: number;
+}
+/**
+ * Detect and separate the `## Outline` section. The section runs
+ * from its `## Outline` heading through the next `## ` heading
+ * (non-inclusive) or end of file. Anything before the outline is
+ * prepended to `body`; anything after is appended. Rejoin via
+ * `joinOutline`.
+ *
+ * This mirrors the line-wise logic in `scripts/lib/editorial/
+ * body-state.ts` (kept separate so the browser-side bundle
+ * doesn't have to drag in the server's fs/path imports).
+ */
+export declare function splitOutline(md: string): SplitOutline;
+/**
+ * Rejoin an outline section with body content. If `outline` is
+ * empty, returns `body` unchanged. Otherwise splices the outline
+ * back at the same structural position it was extracted from —
+ * which for the scaffold shape (frontmatter + H1 + outline + body
+ * sections) is right after the H1.
+ *
+ * Strategy: find the first `## ` heading in `body` and insert the
+ * outline immediately before it, separated by a blank line on each
+ * side. If the body has no H2 (e.g., pre-drafting, still just
+ * frontmatter + H1), append outline at the end.
+ */
+export declare function joinOutline(outline: string, body: string): string;
+//# sourceMappingURL=outline-split.d.ts.map

package/dist/outline-split.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-split.d.ts","sourceRoot":"","sources":["../src/outline-split.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAgBrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBjE"}