@lumenflow/core 3.1.3 → 3.2.1

package/dist/wu-transaction-collectors.js

@@ -0,0 +1,273 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU Transaction Collectors - Compute file content for atomic writes
+ *
+ * WU-1369: These functions compute the new file content WITHOUT writing.
+ * This allows collection of all changes in memory before atomic commit.
+ *
+ * Each function returns:
+ * - The new file content (string)
+ * - Does NOT write to disk
+ *
+ * Usage:
+ * ```js
+ * const tx = new WUTransaction(id);
+ *
+ * // Collect all content
+ * tx.addWrite(wuPath, computeWUYAMLContent(doc), 'WU YAML');
+ * tx.addWrite(statusPath, computeStatusContent(statusPath, id, title), 'status.md');
+ * tx.addWrite(backlogPath, computeBacklogContent(backlogPath, id, title), 'backlog.md');
+ * tx.addWrite(stampPath, computeStampContent(id, title), 'stamp');
+ *
+ * // Validate and commit
+ * tx.commit();
+ * ```
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { stringifyYAML } from './wu-yaml.js';
+import { parseBacklogFrontmatter } from './backlog-parser.js';
+import { getSectionHeadingsWithDefaults } from './section-headings.js';
+import { todayISO, normalizeToDateString } from './date-utils.js';
+import { createError, ErrorCodes } from './error-handler.js';
+import { STRING_LITERALS, WU_STATUS } from './wu-constants.js';
+// WU-1145, WU-1319: Import concurrent merge utilities
+import { computeBacklogContentWithMainMerge, computeStatusContentWithMainMerge, computeWUEventsContentWithMainMerge, } from './wu-done-concurrent-merge.js';
+/**
+ * Compute WU YAML content for done state
+ *
+ * Updates the document in-place and returns the YAML string.
+ * Does NOT write to disk.
+ *
+ * @param {object} doc - WU YAML document (will be mutated)
+ * @returns {string} YAML content string
+ */
+export function computeWUYAMLContent(doc) {
+    // Apply done state updates
+    doc.status = WU_STATUS.DONE;
+    doc.locked = true;
+    doc.completed_at = new Date().toISOString();
+    // Keep legacy completion date in sync for tooling that still reads `completed`.
+    doc.completed =
+        normalizeToDateString(doc.completed ?? doc.completed_at) ?? doc.completed_at.slice(0, 10);
+    // Serialize to YAML
+    return stringifyYAML(doc);
+}
+/**
+ * Find section in lines array
+ * @param {string[]} lines - Array of lines
+ * @param {string} heading - Section heading to find
+ * @returns {number} Index of section, or -1 if not found
+ */
+function findSection(lines, heading) {
+    return lines.findIndex((l) => l.trim() === heading);
+}
+/**
+ * Find end of section (next ## heading or end of file)
+ * @param {string[]} lines - Array of lines
+ * @param {number} startIdx - Start index of section
+ * @returns {number} End index of section
+ */
+function findSectionEnd(lines, startIdx) {
+    const nextHeadingIdx = lines.slice(startIdx + 1).findIndex((l) => l.startsWith('## '));
+    return nextHeadingIdx === -1 ? lines.length : startIdx + 1 + nextHeadingIdx;
+}
+/**
+ * Remove WU entry from a section
+ * @param {string[]} lines - Array of lines (mutated)
+ * @param {number} startIdx - Start index of section
+ * @param {number} endIdx - End index of section
+ * @param {string} rel - Relative path to WU file
+ * @param {string} id - WU ID
+ * @returns {{ removed: boolean, newEndIdx: number }}
+ */
+function removeWUFromSection(lines, startIdx, endIdx, rel, id) {
+    let removed = false;
+    let newEndIdx = endIdx;
+    for (let i = startIdx + 1; i < newEndIdx; i++) {
+        const line = lines[i];
+        if (line && (line.includes(rel) || line.includes(`[${id}`))) {
+            lines.splice(i, 1);
+            removed = true;
+            newEndIdx--;
+            i--;
+        }
+    }
+    return { removed, newEndIdx };
+}
+/**
+ * Insert completed entry into Completed section
+ * @param {string[]} lines - Array of lines (mutated)
+ * @param {number} completedIdx - Index of Completed section
+ * @param {string} entry - Entry to insert
+ * @param {string} id - WU ID
+ * @param {number} sectionEndIdx - End index of Completed section
+ */
+function insertIntoCompleted(lines, completedIdx, entry, id, sectionEndIdx) {
+    const completedSection = lines.slice(completedIdx, sectionEndIdx).join(STRING_LITERALS.NEWLINE);
+    if (completedSection.includes(`[${id}`)) {
+        return; // Already present (idempotent)
+    }
+    let insertIdx = completedIdx + 1;
+    while (insertIdx < lines.length) {
+        const line = lines[insertIdx];
+        if (typeof line !== 'string' || line.trim() !== '') {
+            break;
+        }
+        insertIdx++;
+    }
+    lines.splice(insertIdx, 0, entry);
+}
+/**
+ * Compute updated status.md content
+ *
+ * Removes WU from In Progress section and adds to Completed section.
+ * Returns the new file content without writing.
+ *
+ * @param {string} statusPath - Path to status.md
+ * @param {string} id - WU ID
+ * @param {string} title - WU title
+ * @returns {string} New status.md content
+ * @throws {Error} If file not found or section not found
+ */
+export function computeStatusContent(statusPath, id, title) {
+    if (!existsSync(statusPath)) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Status file not found: ${statusPath}`, {
+            path: statusPath,
+            function: 'computeStatusContent',
+        });
+    }
+    const { frontmatter, markdown } = parseBacklogFrontmatter(statusPath);
+    const headings = getSectionHeadingsWithDefaults(frontmatter, 'status');
+    const rel = `wu/${id}.yaml`;
+    const completedEntry = `- [${id} — ${title}](${rel}) — ${todayISO()}`;
+    const lines = markdown.split(/\r?\n/);
+    // Find and process In Progress section
+    const inProgressIdx = findSection(lines, headings.in_progress);
+    if (inProgressIdx === -1) {
+        throw createError(ErrorCodes.SECTION_NOT_FOUND, `Could not find "${headings.in_progress}" section in ${statusPath}`, { path: statusPath, section: headings.in_progress, function: 'computeStatusContent' });
+    }
+    let inProgressEndIdx = findSectionEnd(lines, inProgressIdx);
+    const { removed, newEndIdx } = removeWUFromSection(lines, inProgressIdx, inProgressEndIdx, rel, id);
+    inProgressEndIdx = newEndIdx;
+    // Add placeholder if section is now empty after removal
+    if (removed) {
+        const sectionContent = lines
+            .slice(inProgressIdx + 1, inProgressEndIdx)
+            .filter((l) => l.trim() !== '');
+        if (sectionContent.length === 0) {
+            lines.splice(inProgressEndIdx, 0, '', '(No items currently in progress)', '');
+        }
+    }
+    // Find and process Completed section
+    const completedIdx = findSection(lines, headings.completed);
+    if (completedIdx === -1) {
+        throw createError(ErrorCodes.SECTION_NOT_FOUND, `Could not find "${headings.completed}" section in ${statusPath}`, { path: statusPath, section: headings.completed, function: 'computeStatusContent' });
+    }
+    const completedEndIdx = findSectionEnd(lines, completedIdx);
+    insertIntoCompleted(lines, completedIdx, completedEntry, id, completedEndIdx);
+    // Reconstruct with frontmatter
+    const raw = readFileSync(statusPath, { encoding: 'utf-8' });
+    const frontmatterMatch = raw.match(/^---\n[\s\S]*?\n---\n/);
+    const frontmatterText = frontmatterMatch ? frontmatterMatch[0] : '';
+    return frontmatterText + lines.join(STRING_LITERALS.NEWLINE);
+}
+/**
+ * Compute wu-events.jsonl content after completing a WU.
+ *
+ * WU-1145: Now merges with origin/main to preserve concurrent changes.
+ * This prevents loss of WU entries when multiple WUs are completed concurrently.
+ *
+ * @param {string} backlogPath - Path to backlog.md
+ * @param {string} wuId - WU ID being completed
+ * @returns {Promise<{eventsPath: string, content: string} | null>}
+ */
+export async function computeWUEventsContentAfterComplete(backlogPath, wuId) {
+    // WU-1145: Use merged state to preserve concurrent changes
+    return computeWUEventsContentWithMainMerge(backlogPath, wuId);
+}
+/**
+ * Compute updated backlog.md content
+ *
+ * WU-1574: Simplified to generate from state store
+ * WU-1145: Now merges with origin/main to preserve concurrent changes
+ *
+ * @param {string} backlogPath - Path to backlog.md
+ * @param {string} id - WU ID to mark complete
+ * @param {string} _title - WU title (unused - state store has it)
+ * @returns {Promise<string>} New backlog.md content
+ */
+export async function computeBacklogContent(backlogPath, id, _title) {
+    // WU-1145: Use merged state to preserve concurrent changes
+    return computeBacklogContentWithMainMerge(backlogPath, id);
+}
+/**
+ * Compute updated status.md content from merged state store
+ *
+ * WU-1319: Generates status.md from merged state (origin/main + worktree events)
+ * instead of editing the local file snapshot. This prevents reintroducing
+ * stale "In Progress" entries when concurrent WUs complete on main.
+ *
+ * @param {string} backlogPath - Path to backlog.md (used to find state dir)
+ * @param {string} id - WU ID to mark complete
+ * @returns {Promise<string>} New status.md content
+ */
+export async function computeStatusContentFromMergedState(backlogPath, id) {
+    // WU-1319: Use merged state to preserve concurrent changes
+    return computeStatusContentWithMainMerge(backlogPath, id);
+}
+/**
+ * Compute stamp file content
+ *
+ * @param {string} id - WU ID
+ * @param {string} title - WU title
+ * @returns {string} Stamp content
+ */
+export function computeStampContent(id, title) {
+    const timestamp = todayISO();
+    return `WU ${id} — ${title}\nCompleted: ${timestamp}\n`;
+}
+/**
+ * Collect all metadata updates for a transaction
+ * WU-1574: Made async for computeBacklogContent
+ * WU-1319: Made status.md generation use merged state
+ *
+ * Convenience function that computes all file contents at once.
+ * Returns an object with all computed content.
+ *
+ * @param {object} params - Parameters
+ * @param {object} params.doc - WU YAML document (will be mutated)
+ * @param {string} params.id - WU ID
+ * @param {string} params.title - WU title
+ * @param {string} params.wuPath - Path to WU YAML
+ * @param {string} params.statusPath - Path to status.md
+ * @param {string} params.backlogPath - Path to backlog.md
+ * @param {string} params.stampPath - Path to stamp file
+ * @returns {Promise<object>} Object with content for each file
+ */
+export async function collectMetadataUpdates({ doc, id, title, wuPath, statusPath, backlogPath, stampPath, }) {
+    return {
+        wuYAML: {
+            path: wuPath,
+            content: computeWUYAMLContent(doc),
+            description: 'WU YAML',
+        },
+        status: {
+            path: statusPath,
+            // WU-1319: Use merged state to preserve concurrent changes
+            content: await computeStatusContentFromMergedState(backlogPath, id),
+            description: 'status.md',
+        },
+        backlog: {
+            path: backlogPath,
+            content: await computeBacklogContent(backlogPath, id, title),
+            description: 'backlog.md',
+        },
+        stamp: {
+            path: stampPath,
+            content: computeStampContent(id, title),
+            description: 'completion stamp',
+        },
+    };
+}
+//# sourceMappingURL=wu-transaction-collectors.js.map

package/dist/wu-transaction-collectors.js.map

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

package/dist/wu-transaction.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Represents a pending file write operation
+ */
+interface PendingWrite {
+    /** Absolute or relative file path */
+    path: string;
+    /** File content to write */
+    content: string;
+    /** Human-readable description (e.g., "WU YAML", "status.md") */
+    description: string;
+}
+/**
+ * Transaction for atomic metadata updates
+ *
+ * Usage:
+ * ```js
+ * const tx = new WUTransaction(id);
+ *
+ * // Collect pending changes
+ * tx.addWrite(wuPath, yamlContent, 'WU YAML');
+ * tx.addWrite(statusPath, statusContent, 'status.md');
+ *
+ * // Validate (no writes happen yet)
+ * const validation = tx.validate();
+ * if (!validation.valid) {
+ *   tx.abort();
+ *   return;
+ * }
+ *
+ * // Commit all changes atomically
+ * const result = tx.commit();
+ * ```
+ */
+export declare class WUTransaction {
+    private readonly wuId;
+    private readonly pendingWrites;
+    private committed;
+    private aborted;
+    private readonly createdAt;
+    /**
+     * Create a new transaction
+     * @param {string} wuId - WU ID for logging context
+     */
+    constructor(wuId: string);
+    /**
+     * Add a pending file write operation
+     *
+     * @param {string} filePath - File path to write
+     * @param {string} content - Content to write
+     * @param {string} description - Human-readable description
+     * @throws {Error} If transaction already committed or aborted
+     */
+    addWrite(filePath: string, content: string, description: string): void;
+    /**
+     * Get pending writes for inspection
+     * @returns {PendingWrite[]}
+     */
+    getPendingWrites(): PendingWrite[];
+    /**
+     * Get count of pending writes
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Check if transaction has been committed
+     * @returns {boolean}
+     */
+    get isCommitted(): boolean;
+    /**
+     * Check if transaction has been aborted
+     * @returns {boolean}
+     */
+    get isAborted(): boolean;
+    /**
+     * Validate pending writes (pre-commit checks)
+     *
+     * Checks:
+     * - All parent directories can be created
+     * - No duplicate paths with different content
+     * - Content is valid (non-empty for critical files)
+     *
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Commit all pending writes atomically
+     *
+     * Writes all files in a single batch. If UnsafeAny write fails,
+     * reports which files were written vs failed.
+     *
+     * @returns {{ success: boolean, written: string[], failed: { path: string, error: string }[] }}
+     * @throws {Error} If transaction already committed or aborted
+     */
+    commit(): {
+        success: boolean;
+        written: string[];
+        failed: {
+            path: string;
+            error: string;
+        }[];
+    };
+    /**
+     * Abort transaction (discard pending writes)
+     *
+     * Since no writes have been made, this just clears pending changes.
+     * This is the key benefit of the transactional pattern.
+     */
+    abort(): void;
+    /**
+     * Get transaction state for debugging
+     */
+    getState(): {
+        wuId: string;
+        committed: boolean;
+        aborted: boolean;
+        pendingCount: number;
+        files: string[];
+        createdAt: string;
+    };
+}
+/**
+ * Read file content for transaction (pre-compute backup)
+ *
+ * @param {string} filePath - File to read
+ * @returns {string|null} - File content or null if doesn't exist
+ */
+export declare function readFileForTransaction(filePath: string): string | null;
+/**
+ * Create a transaction state snapshot for rollback
+ *
+ * Captures current file contents before UnsafeAny modifications.
+ * Used if git operations fail after transaction commit.
+ *
+ * @param {string[]} filePaths - Paths to snapshot
+ * @returns {Map<string, string|null>} - Map of path to content (null = didn't exist)
+ */
+export declare function createTransactionSnapshot(filePaths: string[]): Map<string, string | null>;
+/**
+ * Restore files from snapshot (for rollback after commit)
+ *
+ * @param {Map<string, string|null>} snapshot - Snapshot from createTransactionSnapshot
+ * @returns {{ restored: string[], errors: { path: string, error: string }[] }}
+ */
+export declare function restoreFromSnapshot(snapshot: Map<string, string | null>): {
+    restored: string[];
+    errors: {
+        path: string;
+        error: string;
+    }[];
+};
+/**
+ * WU-1665: Execute snapshot restore for state-machine-driven recovery.
+ *
+ * This is the high-level entry point for snapshot-based rollback, used by the
+ * centralized rollbackFromPipelineState function in rollback-utils.ts.
+ * It delegates to restoreFromSnapshot but accepts a serializable Map format.
+ *
+ * @param {Map<string, string|null>} snapshot - Map of file paths to original content
+ * @returns {{ restored: string[], errors: { path: string, error: string }[] }}
+ */
+export declare function executeSnapshotRestore(snapshot: Map<string, string | null>): {
+    restored: string[];
+    errors: {
+        path: string;
+        error: string;
+    }[];
+};
+export {};
+//# sourceMappingURL=wu-transaction.d.ts.map

package/dist/wu-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-transaction.d.ts","sourceRoot":"","sources":["../src/wu-transaction.ts"],"names":[],"mappings":"AA6BA;;GAEG;AACH,UAAU,YAAY;IACpB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAO;IAEjC;;;OAGG;gBACS,IAAI,EAAE,MAAM;IAQxB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAuBtE;;;OAGG;IACH,gBAAgB,IAAI,YAAY,EAAE;IAIlC;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;OAGG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;;;;;;OASG;IACH,QAAQ,IAAI;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;IAoBhD;;;;;;;;OAQG;IACH,MAAM,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE;IAwD5F;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAeb;;OAEG;IACH,QAAQ,IAAI;QACV,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,OAAO,CAAC;QACnB,OAAO,EAAE,OAAO,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB;CAUF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAQzF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG;IACzE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C,CAwBA;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C,CAEA"}