@deskwork/core 0.10.2 → 0.11.1

package/dist/doctor/validate.js

@@ -0,0 +1,405 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { EntrySchema, isLinearPipelineStage, isOffPipelineStage, } from "../schema/entry.js";
+import { extractEntriesForMigration } from "../calendar/parse.js";
+import { readJournalEvents } from "../journal/read.js";
+async function validateSchema(projectRoot) {
+    const failures = [];
+    const dir = join(projectRoot, '.deskwork', 'entries');
+    let names = [];
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return failures;
+    }
+    for (const name of names.filter((n) => n.endsWith('.json'))) {
+        const path = join(dir, name);
+        const raw = await readFile(path, 'utf8');
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            failures.push({ category: 'schema', message: 'JSON parse failed', path });
+            continue;
+        }
+        const result = EntrySchema.safeParse(json);
+        if (!result.success) {
+            failures.push({ category: 'schema', message: result.error.message, path });
+        }
+    }
+    return failures;
+}
+async function readSidecarUuids(projectRoot) {
+    const dir = join(projectRoot, '.deskwork', 'entries');
+    const uuids = new Set();
+    let names = [];
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return uuids;
+    }
+    for (const name of names.filter((n) => n.endsWith('.json'))) {
+        uuids.add(name.replace(/\.json$/, ''));
+    }
+    return uuids;
+}
+async function validateCalendarSidecar(projectRoot) {
+    const failures = [];
+    const calendarPath = join(projectRoot, '.deskwork', 'calendar.md');
+    let md;
+    try {
+        md = await readFile(calendarPath, 'utf8');
+    }
+    catch {
+        return failures;
+    }
+    const calendarEntries = extractEntriesForMigration(md);
+    const calendarUuids = new Set(calendarEntries.map((e) => e.uuid));
+    const sidecarUuids = await readSidecarUuids(projectRoot);
+    for (const uuid of calendarUuids) {
+        if (!sidecarUuids.has(uuid)) {
+            failures.push({
+                category: 'calendar-sidecar',
+                message: `calendar.md lists uuid ${uuid} but no sidecar exists at .deskwork/entries/${uuid}.json`,
+                entryId: uuid,
+                path: calendarPath,
+            });
+        }
+    }
+    for (const uuid of sidecarUuids) {
+        if (!calendarUuids.has(uuid)) {
+            failures.push({
+                category: 'calendar-sidecar',
+                message: `sidecar ${uuid}.json exists but calendar.md does not list this uuid`,
+                entryId: uuid,
+                path: join(projectRoot, '.deskwork', 'entries', `${uuid}.json`),
+            });
+        }
+    }
+    return failures;
+}
+async function loadSidecars(projectRoot) {
+    const dir = join(projectRoot, '.deskwork', 'entries');
+    let names = [];
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.filter((n) => n.endsWith('.json'))) {
+        const path = join(dir, name);
+        const raw = await readFile(path, 'utf8');
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const result = EntrySchema.safeParse(json);
+        if (!result.success)
+            continue;
+        out.push({ filename: name, path, entry: result.data });
+    }
+    return out;
+}
+/**
+ * Stage-conventional artifact path. Returns null when a stage does not have a
+ * primary on-disk artifact (e.g. Blocked / Cancelled).
+ *
+ * Note: Published shares the Drafting/Final path (`docs/<slug>/index.md`).
+ */
+function artifactPathForStage(projectRoot, slug, stage) {
+    switch (stage) {
+        case 'Ideas':
+            return join(projectRoot, 'docs', slug, 'scrapbook', 'idea.md');
+        case 'Planned':
+            return join(projectRoot, 'docs', slug, 'scrapbook', 'plan.md');
+        case 'Outlining':
+            return join(projectRoot, 'docs', slug, 'scrapbook', 'outline.md');
+        case 'Drafting':
+        case 'Final':
+        case 'Published':
+            return join(projectRoot, 'docs', slug, 'index.md');
+        case 'Blocked':
+        case 'Cancelled':
+            return null;
+    }
+}
+/**
+ * Minimal frontmatter `deskwork.stage` extractor.
+ *
+ * The plugin's frontmatter is YAML-ish, but for the validator's narrow purpose
+ * (read `deskwork.stage`) a regex avoids pulling a full YAML parser into the
+ * validator codepath. We match the `deskwork:` block and find a `stage:` line
+ * inside it, accepting any indentation.
+ */
+function extractDeskworkStage(markdown) {
+    const fmMatch = markdown.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch)
+        return undefined;
+    const fm = fmMatch[1];
+    // Find the line `deskwork:` (the block opener) and then any subsequent
+    // indented child line of the form `  stage: <value>` before either the next
+    // unindented line or end-of-frontmatter.
+    const lines = fm.split('\n');
+    let inBlock = false;
+    for (const line of lines) {
+        if (!inBlock) {
+            if (/^deskwork:\s*$/.test(line))
+                inBlock = true;
+            continue;
+        }
+        // Exit the block when we hit a non-indented, non-empty line.
+        if (line.length > 0 && !/^\s/.test(line))
+            break;
+        const m = line.match(/^\s+stage:\s*([^\s#]+)/);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function validateFrontmatterSidecar(projectRoot) {
+    const failures = [];
+    const sidecars = await loadSidecars(projectRoot);
+    for (const { entry, path: sidecarPath } of sidecars) {
+        const artifactPath = artifactPathForStage(projectRoot, entry.slug, entry.currentStage);
+        if (!artifactPath)
+            continue;
+        if (!(await fileExists(artifactPath)))
+            continue; // file-presence handles missing artifacts
+        const md = await readFile(artifactPath, 'utf8');
+        const fmStage = extractDeskworkStage(md);
+        if (fmStage === undefined)
+            continue;
+        if (fmStage !== entry.currentStage) {
+            failures.push({
+                category: 'frontmatter-sidecar',
+                message: `frontmatter deskwork.stage=${fmStage} at ${artifactPath} does not match sidecar currentStage=${entry.currentStage}`,
+                entryId: entry.uuid,
+                path: sidecarPath,
+            });
+        }
+    }
+    return failures;
+}
+async function validateJournalSidecar(projectRoot) {
+    const failures = [];
+    const sidecars = await loadSidecars(projectRoot);
+    for (const { entry, path } of sidecars) {
+        const events = await readJournalEvents(projectRoot, { entryId: entry.uuid });
+        // readJournalEvents sorts ascending by `at`, so the latest is at the end.
+        const stageTransitions = events.filter((e) => e.kind === 'stage-transition');
+        const latestStageTransition = stageTransitions.at(-1);
+        if (latestStageTransition && latestStageTransition.kind === 'stage-transition') {
+            if (latestStageTransition.to !== entry.currentStage) {
+                failures.push({
+                    category: 'journal-sidecar',
+                    message: `latest stage-transition.to=${latestStageTransition.to} does not match sidecar currentStage=${entry.currentStage}`,
+                    entryId: entry.uuid,
+                    path,
+                });
+            }
+        }
+        const reviewChanges = events.filter((e) => e.kind === 'review-state-change');
+        const latestReview = reviewChanges.at(-1);
+        if (latestReview && latestReview.kind === 'review-state-change') {
+            const sidecarReview = entry.reviewState ?? null;
+            if (latestReview.to !== sidecarReview) {
+                failures.push({
+                    category: 'journal-sidecar',
+                    message: `latest review-state-change.to=${String(latestReview.to)} does not match sidecar reviewState=${String(sidecarReview)}`,
+                    entryId: entry.uuid,
+                    path,
+                });
+            }
+        }
+    }
+    return failures;
+}
+async function validateIterationHistory(projectRoot) {
+    const failures = [];
+    const sidecars = await loadSidecars(projectRoot);
+    for (const { entry, path } of sidecars) {
+        const stages = Object.keys(entry.iterationByStage);
+        // Migration tolerance: a sidecar with no recorded iteration counts is
+        // exempt from journal-vs-sidecar checks (legacy history may exist in the
+        // journal that simply hasn't been backfilled into iterationByStage).
+        if (stages.length === 0)
+            continue;
+        const events = await readJournalEvents(projectRoot, {
+            entryId: entry.uuid,
+            kinds: ['iteration'],
+        });
+        // Count iterations per stage in the journal.
+        const journalCount = {};
+        for (const e of events) {
+            if (e.kind !== 'iteration')
+                continue;
+            journalCount[e.stage] = (journalCount[e.stage] ?? 0) + 1;
+        }
+        // Compare sidecar counts to journal counts for every stage we know about
+        // (union of sidecar-recorded stages and journal-witnessed stages).
+        const allStages = new Set([...stages, ...Object.keys(journalCount)]);
+        for (const stage of allStages) {
+            const sidecarN = entry.iterationByStage[stage] ?? 0;
+            const journalN = journalCount[stage] ?? 0;
+            if (sidecarN === 0)
+                continue; // migration tolerance: only flag stages the sidecar tracks
+            if (sidecarN !== journalN) {
+                failures.push({
+                    category: 'iteration-history',
+                    message: `iterationByStage[${stage}]=${sidecarN} but journal has ${journalN} iteration event(s) for that stage`,
+                    entryId: entry.uuid,
+                    path,
+                });
+            }
+        }
+    }
+    return failures;
+}
+async function validateFilePresence(projectRoot) {
+    const failures = [];
+    const sidecars = await loadSidecars(projectRoot);
+    for (const { entry, path } of sidecars) {
+        const artifactPath = artifactPathForStage(projectRoot, entry.slug, entry.currentStage);
+        if (!artifactPath)
+            continue;
+        if (!(await fileExists(artifactPath))) {
+            failures.push({
+                category: 'file-presence',
+                message: `sidecar currentStage=${entry.currentStage} requires artifact at ${artifactPath} but the file is missing`,
+                entryId: entry.uuid,
+                path,
+            });
+        }
+    }
+    return failures;
+}
+async function validateStageInvariants(projectRoot) {
+    const failures = [];
+    const sidecars = await loadSidecars(projectRoot);
+    for (const { entry, path } of sidecars) {
+        // Off-pipeline stages (Blocked, Cancelled) MUST record priorStage so the
+        // editor knows where to send the entry on resume.
+        if (isOffPipelineStage(entry.currentStage)) {
+            if (!entry.priorStage) {
+                failures.push({
+                    category: 'stage-invariants',
+                    message: `currentStage=${entry.currentStage} requires priorStage to be set`,
+                    entryId: entry.uuid,
+                    path,
+                });
+            }
+        }
+        // Pipeline-stage entries MUST NOT carry a priorStage — that field is for
+        // off-pipeline entries to remember where they paused.
+        if (isLinearPipelineStage(entry.currentStage) && entry.priorStage !== undefined) {
+            failures.push({
+                category: 'stage-invariants',
+                message: `pipeline-stage entry (currentStage=${entry.currentStage}) must not have priorStage set (got ${entry.priorStage})`,
+                entryId: entry.uuid,
+                path,
+            });
+        }
+        // Published is frozen — no further iterations are allowed.
+        const publishedIters = entry.iterationByStage.Published ?? 0;
+        if (publishedIters > 1) {
+            failures.push({
+                category: 'stage-invariants',
+                message: `iterationByStage.Published=${publishedIters} but Published is frozen (max 1)`,
+                entryId: entry.uuid,
+                path,
+            });
+        }
+    }
+    return failures;
+}
+async function validateCrossEntry(projectRoot) {
+    const failures = [];
+    const sidecars = await loadSidecars(projectRoot);
+    // UUID-filename mismatch: the canonical name is `<uuid>.json`. If the body's
+    // uuid field doesn't match the filename, downstream lookups break.
+    for (const { filename, path, entry } of sidecars) {
+        const expectedUuid = filename.replace(/\.json$/, '');
+        if (entry.uuid !== expectedUuid) {
+            failures.push({
+                category: 'cross-entry',
+                message: `sidecar filename ${filename} does not match body uuid ${entry.uuid}`,
+                entryId: entry.uuid,
+                path,
+            });
+        }
+    }
+    // Slug uniqueness: each slug should map to at most one entry. Group sidecars
+    // by slug and emit one failure per duplicate cluster.
+    const bySlug = new Map();
+    for (const sc of sidecars) {
+        const list = bySlug.get(sc.entry.slug) ?? [];
+        list.push(sc);
+        bySlug.set(sc.entry.slug, list);
+    }
+    for (const [slug, group] of bySlug) {
+        if (group.length < 2)
+            continue;
+        const uuids = group.map((g) => g.entry.uuid).join(', ');
+        for (const sc of group) {
+            failures.push({
+                category: 'cross-entry',
+                message: `slug "${slug}" is shared by ${group.length} sidecars (uuids: ${uuids})`,
+                entryId: sc.entry.uuid,
+                path: sc.path,
+            });
+        }
+    }
+    // UUID uniqueness across body fields. Same body uuid in two different files
+    // is unusual (the filename naming convention prevents the obvious case) but
+    // worth catching when it happens.
+    const byUuid = new Map();
+    for (const sc of sidecars) {
+        const list = byUuid.get(sc.entry.uuid) ?? [];
+        list.push(sc);
+        byUuid.set(sc.entry.uuid, list);
+    }
+    for (const [uuid, group] of byUuid) {
+        if (group.length < 2)
+            continue;
+        const filenames = group.map((g) => g.filename).join(', ');
+        for (const sc of group) {
+            failures.push({
+                category: 'cross-entry',
+                message: `uuid ${uuid} appears in ${group.length} sidecar bodies (files: ${filenames})`,
+                entryId: uuid,
+                path: sc.path,
+            });
+        }
+    }
+    return failures;
+}
+export async function validateAll(projectRoot) {
+    const failures = [];
+    failures.push(...(await validateSchema(projectRoot)));
+    failures.push(...(await validateCalendarSidecar(projectRoot)));
+    failures.push(...(await validateFrontmatterSidecar(projectRoot)));
+    failures.push(...(await validateJournalSidecar(projectRoot)));
+    failures.push(...(await validateIterationHistory(projectRoot)));
+    failures.push(...(await validateFilePresence(projectRoot)));
+    failures.push(...(await validateStageInvariants(projectRoot)));
+    failures.push(...(await validateCrossEntry(projectRoot)));
+    return { failures };
+}
+//# sourceMappingURL=validate.js.map

package/dist/doctor/validate.js.map

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

package/dist/iterate/iterate.d.ts

@@ -0,0 +1,13 @@
+import type { Stage } from '../schema/entry.ts';
+interface IterateOptions {
+    uuid: string;
+}
+interface IterateResult {
+    entryId: string;
+    stage: Stage;
+    version: number;
+    reviewState: 'in-review';
+}
+export declare function iterateEntry(projectRoot: string, opts: IterateOptions): Promise<IterateResult>;
+export {};
+//# sourceMappingURL=iterate.d.ts.map

package/dist/iterate/iterate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterate.d.ts","sourceRoot":"","sources":["../../src/iterate/iterate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAS,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEvD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;CAEd;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAaD,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA6DpG"}

package/dist/iterate/iterate.js

@@ -0,0 +1,69 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readSidecar } from "../sidecar/read.js";
+import { writeSidecar } from "../sidecar/write.js";
+import { appendJournalEvent } from "../journal/append.js";
+const STAGE_ARTIFACT_PATH = {
+    Ideas: (slug, contentDir) => join(contentDir, slug, 'scrapbook', 'idea.md'),
+    Planned: (slug, contentDir) => join(contentDir, slug, 'scrapbook', 'plan.md'),
+    Outlining: (slug, contentDir) => join(contentDir, slug, 'scrapbook', 'outline.md'),
+    Drafting: (slug, contentDir) => join(contentDir, slug, 'index.md'),
+    Final: (slug, contentDir) => join(contentDir, slug, 'index.md'),
+    Published: null,
+    Blocked: null,
+    Cancelled: null,
+};
+export async function iterateEntry(projectRoot, opts) {
+    const sidecar = await readSidecar(projectRoot, opts.uuid);
+    if (sidecar.currentStage === 'Published') {
+        throw new Error('Cannot iterate: Published entries are frozen.');
+    }
+    if (sidecar.currentStage === 'Blocked' || sidecar.currentStage === 'Cancelled') {
+        throw new Error(`Cannot iterate: entry is ${sidecar.currentStage}; induct it back into the pipeline first.`);
+    }
+    const pathFn = STAGE_ARTIFACT_PATH[sidecar.currentStage];
+    if (!pathFn) {
+        throw new Error(`Cannot iterate at stage ${sidecar.currentStage}: no artifact path defined.`);
+    }
+    const contentDir = join(projectRoot, 'docs'); // FIXME: read from .deskwork/config.json
+    const artifactPath = pathFn(sidecar.slug, contentDir);
+    const markdown = await readFile(artifactPath, 'utf8');
+    const priorVersion = sidecar.iterationByStage[sidecar.currentStage] ?? 0;
+    const newVersion = priorVersion + 1;
+    const at = new Date().toISOString();
+    // Emit journal event first; doctor reconciles drift if we crash mid-operation
+    await appendJournalEvent(projectRoot, {
+        kind: 'iteration',
+        at,
+        entryId: sidecar.uuid,
+        stage: sidecar.currentStage,
+        version: newVersion,
+        markdown,
+    });
+    // Update sidecar
+    const updated = {
+        ...sidecar,
+        iterationByStage: { ...sidecar.iterationByStage, [sidecar.currentStage]: newVersion },
+        reviewState: 'in-review',
+        updatedAt: at,
+    };
+    await writeSidecar(projectRoot, updated);
+    // Emit review-state-change if state actually changed
+    if (sidecar.reviewState !== 'in-review') {
+        await appendJournalEvent(projectRoot, {
+            kind: 'review-state-change',
+            at,
+            entryId: sidecar.uuid,
+            stage: sidecar.currentStage,
+            from: sidecar.reviewState ?? null,
+            to: 'in-review',
+        });
+    }
+    return {
+        entryId: sidecar.uuid,
+        stage: sidecar.currentStage,
+        version: newVersion,
+        reviewState: 'in-review',
+    };
+}
+//# sourceMappingURL=iterate.js.map

package/dist/iterate/iterate.js.map

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

package/dist/journal/append.d.ts

@@ -0,0 +1,3 @@
+import { type JournalEvent } from '../schema/journal-events.ts';
+export declare function appendJournalEvent(projectRoot: string, event: JournalEvent): Promise<string>;
+//# sourceMappingURL=append.d.ts.map

package/dist/journal/append.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../../src/journal/append.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEpF,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAYlG"}

package/dist/journal/append.js

@@ -0,0 +1,18 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { JournalEventSchema } from "../schema/journal-events.js";
+export async function appendJournalEvent(projectRoot, event) {
+    const result = JournalEventSchema.safeParse(event);
+    if (!result.success) {
+        throw new Error(`appendJournalEvent refused: schema invalid: ${result.error.message}`);
+    }
+    const dir = join(projectRoot, '.deskwork', 'review-journal', 'history');
+    await mkdir(dir, { recursive: true });
+    const eventId = randomUUID();
+    const tsKey = event.at.replace(/[:.]/g, '-');
+    const path = join(dir, `${tsKey}-${eventId}.json`);
+    await writeFile(path, JSON.stringify(event, null, 2));
+    return path;
+}
+//# sourceMappingURL=append.js.map

package/dist/journal/append.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"append.js","sourceRoot":"","sources":["../../src/journal/append.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAqB,MAAM,6BAA6B,CAAC;AAEpF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,WAAmB,EAAE,KAAmB;IAC/E,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,+CAA+C,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,CAAC,CAAC;IACxE,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,OAAO,OAAO,CAAC,CAAC;IACnD,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/journal/index.d.ts

@@ -0,0 +1,3 @@
+export * from './append.ts';
+export * from './read.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/journal/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}

package/dist/journal/index.js

@@ -0,0 +1,3 @@
+export * from "./append.js";
+export * from "./read.js";
+//# sourceMappingURL=index.js.map

package/dist/journal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/journal/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}

package/dist/journal/read.d.ts

@@ -0,0 +1,9 @@
+import { type JournalEvent } from '../schema/journal-events.ts';
+interface ReadOptions {
+    entryId?: string;
+    stage?: string;
+    kinds?: string[];
+}
+export declare function readJournalEvents(projectRoot: string, opts?: ReadOptions): Promise<JournalEvent[]>;
+export {};
+//# sourceMappingURL=read.d.ts.map

package/dist/journal/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/journal/read.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEpF,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA0B5G"}

package/dist/journal/read.js

@@ -0,0 +1,41 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { JournalEventSchema } from "../schema/journal-events.js";
+export async function readJournalEvents(projectRoot, opts = {}) {
+    const dir = join(projectRoot, '.deskwork', 'review-journal', 'history');
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const events = [];
+    for (const name of names.filter(n => n.endsWith('.json'))) {
+        const raw = await readFile(join(dir, name), 'utf8');
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const parsed = JournalEventSchema.safeParse(json);
+        if (!parsed.success)
+            continue;
+        const e = parsed.data;
+        if (opts.entryId && e.entryId !== opts.entryId)
+            continue;
+        if (opts.stage && 'stage' in e && e.stage !== opts.stage)
+            continue;
+        if (opts.kinds && !opts.kinds.includes(e.kind))
+            continue;
+        events.push(e);
+    }
+    events.sort((a, b) => a.at.localeCompare(b.at));
+    return events;
+}
+//# sourceMappingURL=read.js.map

package/dist/journal/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../src/journal/read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAqB,MAAM,6BAA6B,CAAC;AAQpF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,WAAmB,EAAE,OAAoB,EAAE;IACjF,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,CAAC,CAAC;IACxE,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,GAA4B,CAAC;QAC3C,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACvC,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QACpD,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QACnD,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,SAAS;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;QACtB,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO;YAAE,SAAS;QACzD,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;YAAE,SAAS;QACnE,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,SAAS;QACzD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC;AAChB,CAAC"}