@lumenflow/core 3.2.0 → 3.2.2

package/dist/wu-done-worktree.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Worktree mode completion orchestrator for wu:done (WU-1369 atomic pattern).
+ * Decomposed in WU-2014: pre-flight checks, merge/rebase, error handling,
+ * zombie recovery, and main-sync validation extracted into focused modules.
+ *
+ * Key guarantee: If validation fails, NO files are modified.
+ */
+import path from 'node:path';
+import { generateCommitMessage, collectMetadataToTransaction, stageAndFormatMetadata, defaultBranchFrom, validatePostMutation, } from './wu-done-validators.js';
+import { createGitForPath } from './git-adapter.js';
+import { readWU, writeWU } from './wu-yaml.js';
+import { WU_PATHS } from './wu-paths.js';
+import { BRANCHES, LOG_PREFIX, EMOJI, WU_STATUS, LUMENFLOW_PATHS } from './wu-constants.js';
+import { createError, ErrorCodes } from './error-handler.js';
+import { createValidationError } from './wu-done-errors.js';
+import { validateDoneWU, validateAndNormalizeWUYAML } from './wu-schema.js';
+import { validateCodePathsCommittedBeforeDone } from './wu-done-validation.js';
+import { assertTransition } from './state-machine.js';
+import { emitLaneSignalForCompletion } from './wu-done-branch-only.js';
+import { WU_DONE_COMPLETION_MODES } from './wu-done-pr.js';
+import { clearRecoveryAttempts } from './wu-recovery.js';
+import { WUTransaction, createTransactionSnapshot } from './wu-transaction.js';
+import { countPreviousCompletionAttempts, squashPreviousCompletionAttempts, } from './wu-done-retry-helpers.js';
+import { WU_EVENTS_FILE_NAME } from './wu-state-store.js';
+import { maybeRegenerateAndStageDocs } from './wu-done-docs-generate.js';
+// WU-2014: Import from extracted modules
+import { assertNoConflictArtifactsInIndex } from './wu-done-rebase.js';
+import { handleZombieRecovery } from './wu-done-zombie-recovery.js';
+import { handleCompletionError } from './wu-done-error-handling.js';
+import { ensureMainNotBehindOrigin } from './wu-done-main-sync.js';
+import { executeMergePhase } from './wu-done-merge-phase.js';
+// Re-exports for backwards compatibility (WU-2014)
+// Consumers import these symbols from '@lumenflow/core/wu-done-worktree'
+export { checkBranchDrift, checkBranchDivergence, checkMergeCommits, checkMergeConflicts, checkEmptyMerge, } from './wu-done-preflight-checks.js';
+export { autoRebaseBranch, assertNoConflictArtifactsInIndex, autoResolveAppendOnlyConflicts, } from './wu-done-rebase.js';
+export { mergeLaneBranch, isMainAncestorOfBranch } from './wu-done-merge.js';
+export { hasSessionCheckpoints, rollbackBranchOnMergeFailure } from './wu-done-utils.js';
+export { handleZombieRecovery } from './wu-done-zombie-recovery.js';
+export { handleCompletionError } from './wu-done-error-handling.js';
+export { validateMainNotBehindOrigin } from './wu-done-main-sync.js';
+export { executeMergePhase } from './wu-done-merge-phase.js';
+// Path resolution
+/**
+ * Resolve all metadata/state paths as absolute worktree-local paths.
+ *
+ * WU-1563: Prevents wu:done from writing lifecycle metadata into main checkout
+ * when worktree mode is active.
+ */
+export function resolveWorktreeMetadataPaths(worktreePath, id) {
+    return {
+        wuPath: path.join(worktreePath, WU_PATHS.WU(id)),
+        statusPath: path.join(worktreePath, WU_PATHS.STATUS()),
+        backlogPath: path.join(worktreePath, WU_PATHS.BACKLOG()),
+        stampsDir: path.join(worktreePath, WU_PATHS.STAMPS_DIR()),
+        stampPath: path.join(worktreePath, WU_PATHS.STAMP(id)),
+        eventsPath: path.join(worktreePath, LUMENFLOW_PATHS.STATE_DIR, WU_EVENTS_FILE_NAME),
+    };
+}
+// Main orchestrator
+/**
+ * Execute worktree mode completion
+ *
+ * @param context - Worktree mode context
+ * @returns Completion result
+ * @throws On validation or git operation failure
+ */
+export async function executeWorktreeCompletion(context) {
+    // Save original cwd for returning after worktree operations.
+    // This must be captured BEFORE zombie recovery, which temporarily chdirs into the worktree.
+    const originalCwd = process.cwd();
+    const { id, args, docMain, title, isDocsOnly, worktreePath, maxCommitLength, validateStagedFiles, } = context;
+    const worktreeMetadataPaths = resolveWorktreeMetadataPaths(worktreePath, id);
+    // Read WU YAML and validate current state
+    const docForUpdate = readWU(worktreeMetadataPaths.wuPath, id);
+    // WU-2014: Zombie recovery delegated to wu-done-zombie-recovery.ts
+    await handleZombieRecovery(docForUpdate, worktreePath, id);
+    // Capture status AFTER potential zombie recovery reset
+    const currentStatus = docForUpdate.status || WU_STATUS.IN_PROGRESS;
+    assertTransition(currentStatus, WU_STATUS.DONE, id);
+    // WU-1577: Abort early if local main is behind origin/main.
+    await ensureMainNotBehindOrigin(originalCwd, id);
+    // WU-1369: Create atomic transaction for metadata updates
+    const transaction = new WUTransaction(id);
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Transaction BEGIN - atomic pattern (WU-1369)`);
+    let preCommitSha = null;
+    let gitCommitMade = false;
+    let transactionSnapshot = null;
+    let stagedMetadataAllowlist;
+    let initiativeMetadataPath;
+    try {
+        console.log(`\n${LOG_PREFIX.DONE} Updating metadata in worktree: ${worktreePath}`);
+        const worktreeGit = createGitForPath(worktreePath);
+        const workingWUPath = worktreeMetadataPaths.wuPath;
+        const workingStatusPath = worktreeMetadataPaths.statusPath;
+        const workingBacklogPath = worktreeMetadataPaths.backlogPath;
+        const workingStampsDir = worktreeMetadataPaths.stampsDir;
+        const workingStampPath = worktreeMetadataPaths.stampPath;
+        // PHASE 1: RUN ALL VALIDATIONS FIRST (before file writes)
+        console.log(`${LOG_PREFIX.DONE} Running validations (no writes until all pass)...`);
+        const normalizeResult = validateAndNormalizeWUYAML(docForUpdate);
+        if (!normalizeResult.valid) {
+            throw createValidationError(`WU YAML validation failed:\n  - ${normalizeResult.errors.join('\n  - ')}\n\nNext step: Fix the validation errors in ${workingWUPath} and rerun wu:done`, { wuId: id });
+        }
+        if (normalizeResult.wasNormalized) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} WU-1811: Applying auto-normalisations to WU YAML...`);
+            writeWU(workingWUPath, normalizeResult.normalized);
+            Object.assign(docForUpdate, normalizeResult.normalized);
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} WU YAML normalised and saved`);
+        }
+        const normalizedWU = normalizeResult.normalized ?? docForUpdate;
+        const completenessResult = validateDoneWU(normalizedWU);
+        if (!completenessResult.valid) {
+            throw createValidationError(`Cannot mark WU as done - spec incomplete:\n  ${completenessResult.errors.join('\n  ')}\n\nNext step: Update ${workingWUPath} to meet completion requirements and rerun wu:done`, { wuId: id });
+        }
+        console.log(`${LOG_PREFIX.DONE} Checking code_paths commit status (WU-1153)...`);
+        const codePathsResult = await validateCodePathsCommittedBeforeDone(normalizedWU, worktreeGit, {
+            abortOnFailure: false,
+        });
+        if (!codePathsResult.valid) {
+            const errorMessage = await import('./wu-done-validation.js').then((m) => m.buildCodePathsCommittedErrorMessage(id, codePathsResult.uncommittedPaths));
+            throw createValidationError(errorMessage, { wuId: id });
+        }
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All validations passed`);
+        // PHASE 2: COLLECT ALL CHANGES TO TRANSACTION
+        await collectMetadataToTransaction({
+            id,
+            title,
+            doc: docForUpdate,
+            wuPath: workingWUPath,
+            statusPath: workingStatusPath,
+            backlogPath: workingBacklogPath,
+            stampPath: workingStampPath,
+            transaction,
+            projectRoot: worktreePath,
+        });
+        const pendingWrites = transaction.getPendingWrites();
+        stagedMetadataAllowlist = pendingWrites
+            .map((write) => path.relative(worktreePath, write.path).split(path.sep).join('/'))
+            .filter((relativePath) => Boolean(relativePath) && !relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+        const initiativeMetadataWrite = pendingWrites.find((write) => write.description === 'initiative YAML');
+        initiativeMetadataPath = initiativeMetadataWrite?.path ?? null;
+        const txValidation = transaction.validate();
+        if (!txValidation.valid) {
+            throw createError(ErrorCodes.TRANSACTION_ERROR, `Transaction validation failed:\n  ${txValidation.errors.join('\n  ')}`, { wuId: id });
+        }
+        // PHASE 3: ATOMIC COMMIT (write all files at once)
+        const workingEventsPath = worktreeMetadataPaths.eventsPath;
+        const pathsToSnapshot = Array.from(new Set(transaction.getPendingWrites().map((write) => write.path)));
+        transactionSnapshot = createTransactionSnapshot(pathsToSnapshot);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} WU-2310: Snapshot captured for rollback`);
+        const commitResult = transaction.commit();
+        if (!commitResult.success) {
+            throw createError(ErrorCodes.TRANSACTION_ERROR, `Transaction commit failed - some files not written:\n  ${commitResult.failed.map((f) => f.path).join('\n  ')}`, { wuId: id, written: commitResult.written, failed: commitResult.failed });
+        }
+        // WU-1617: POST-MUTATION VALIDATION
+        const postMutationResult = validatePostMutation({
+            id,
+            wuPath: workingWUPath,
+            stampPath: workingStampPath,
+            eventsPath: workingEventsPath,
+        });
+        if (!postMutationResult.valid) {
+            throw createValidationError(`Post-mutation validation failed:\n  ${postMutationResult.errors.join('\n  ')}`, { wuId: id, errors: postMutationResult.errors });
+        }
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Post-mutation validation passed (WU-1617)`);
+        // PHASE 4: GIT OPERATIONS (stage, format, commit)
+        await maybeRegenerateAndStageDocs({
+            baseBranch: BRANCHES.MAIN,
+            repoRoot: worktreePath,
+        });
+        await stageAndFormatMetadata({
+            id,
+            wuPath: workingWUPath,
+            statusPath: workingStatusPath,
+            backlogPath: workingBacklogPath,
+            stampsDir: workingStampsDir,
+            initiativePath: initiativeMetadataPath,
+            gitAdapter: worktreeGit,
+            repoRoot: worktreePath,
+        });
+        await validateStagedFiles(id, isDocsOnly, { metadataAllowlist: stagedMetadataAllowlist });
+        // WU-1584: Squash previous completion attempts
+        const previousAttempts = await countPreviousCompletionAttempts(id, worktreeGit);
+        if (previousAttempts > 0) {
+            const squashResult = await squashPreviousCompletionAttempts(id, previousAttempts, worktreeGit);
+            if (squashResult.squashed) {
+                console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} WU-1584: Squashed ${squashResult.count} previous attempt(s) - single commit will be created`);
+            }
+        }
+        const laneBranch = await defaultBranchFrom(docForUpdate);
+        const msg = generateCommitMessage(id, title, maxCommitLength, {
+            branch: laneBranch ?? undefined,
+            worktreePath,
+        });
+        await assertNoConflictArtifactsInIndex(worktreeGit);
+        preCommitSha = await worktreeGit.getCommitHash('HEAD');
+        await worktreeGit.commit(msg);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Metadata committed in worktree`);
+        gitCommitMade = true;
+        // WU-2014: Merge/PR phase delegated to wu-done-merge-phase.ts
+        const mergeResult = await executeMergePhase({
+            id,
+            title,
+            laneBranch,
+            docMain,
+            docForUpdate,
+            args,
+            worktreePath,
+        });
+        clearRecoveryAttempts(id); // WU-1335: Clear recovery attempts on success
+        await emitLaneSignalForCompletion({
+            wuId: id,
+            lane: docForUpdate.lane,
+            laneBranch,
+            completionMode: WU_DONE_COMPLETION_MODES.WORKTREE,
+        });
+        return {
+            success: true,
+            committed: true,
+            pushed: !mergeResult.prModeEnabled,
+            merged: mergeResult.merged,
+            prUrl: mergeResult.prUrl,
+            cleanupSafe: true,
+        };
+    }
+    catch (err) {
+        // WU-2014: Error handling extracted to wu-done-error-handling.ts
+        // handleCompletionError always throws (Promise<never>); return satisfies TS control-flow
+        return await handleCompletionError({
+            error: err,
+            id,
+            worktreePath,
+            transaction,
+            gitCommitMade,
+            preCommitSha,
+            transactionSnapshot,
+        });
+    }
+}
+//# sourceMappingURL=wu-done-worktree.js.map

package/dist/wu-done-worktree.js.map

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

package/dist/wu-done-zombie-recovery.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Handle zombie state detection and recovery.
+ *
+ * A "zombie" WU has status=done in the worktree YAML but was never
+ * successfully merged to main. This function:
+ * 1. Detects the zombie state
+ * 2. Checks recovery attempt count to prevent infinite loops
+ * 3. Squashes previous completion attempts
+ * 4. Resets worktree YAML to in_progress for a fresh attempt
+ *
+ * @param doc - WU document (mutated in-place if recovery resets status)
+ * @param worktreePath - Absolute path to the worktree
+ * @param id - WU ID (e.g. 'WU-1234')
+ * @returns true if zombie was detected and recovery initiated, false if no zombie
+ * @throws When recovery loop detected (too many attempts)
+ */
+export declare function handleZombieRecovery(doc: Record<string, unknown>, worktreePath: string, id: string): Promise<boolean>;
+//# sourceMappingURL=wu-done-zombie-recovery.d.ts.map

package/dist/wu-done-zombie-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-done-zombie-recovery.d.ts","sourceRoot":"","sources":["../src/wu-done-zombie-recovery.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,OAAO,CAAC,CAqElB"}

package/dist/wu-done-zombie-recovery.js

@@ -0,0 +1,84 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-2014: Zombie state detection and recovery for wu:done
+ *
+ * Extracted from wu-done-worktree.ts to isolate recovery orchestration.
+ * Handles detection of "zombie" WUs (status=done in worktree but not merged)
+ * and coordinates recovery: squash previous attempts, reset YAML, continue.
+ *
+ * Functions:
+ *   handleZombieRecovery - Detect and recover from zombie WU state
+ */
+import { createGitForPath } from './git-adapter.js';
+import { LOG_PREFIX, EMOJI, BOX } from './wu-constants.js';
+import { RECOVERY } from './wu-done-messages.js';
+import { createRecoveryError } from './wu-done-errors.js';
+import { detectZombieState, resetWorktreeYAMLForRecovery, getRecoveryAttemptCount, incrementRecoveryAttempt, shouldEscalateToManualIntervention, MAX_RECOVERY_ATTEMPTS, } from './wu-recovery.js';
+import { prepareRecoveryWithSquash } from './wu-done-retry-helpers.js';
+import { getErrorMessage } from './error-handler.js';
+/**
+ * Handle zombie state detection and recovery.
+ *
+ * A "zombie" WU has status=done in the worktree YAML but was never
+ * successfully merged to main. This function:
+ * 1. Detects the zombie state
+ * 2. Checks recovery attempt count to prevent infinite loops
+ * 3. Squashes previous completion attempts
+ * 4. Resets worktree YAML to in_progress for a fresh attempt
+ *
+ * @param doc - WU document (mutated in-place if recovery resets status)
+ * @param worktreePath - Absolute path to the worktree
+ * @param id - WU ID (e.g. 'WU-1234')
+ * @returns true if zombie was detected and recovery initiated, false if no zombie
+ * @throws When recovery loop detected (too many attempts)
+ */
+export async function handleZombieRecovery(doc, worktreePath, id) {
+    if (!detectZombieState(doc, worktreePath)) {
+        return false;
+    }
+    console.log(`\n${RECOVERY.DETECTED}`);
+    // WU-1335: Check recovery attempt count to prevent infinite loops
+    const attemptCount = getRecoveryAttemptCount(id);
+    if (shouldEscalateToManualIntervention(attemptCount)) {
+        console.log(`\n${BOX.TOP}`);
+        console.log(`${BOX.SIDE}  RECOVERY LOOP DETECTED - MANUAL INTERVENTION REQUIRED`);
+        console.log(BOX.MID);
+        console.log(`${BOX.SIDE}  WU: ${id}`);
+        console.log(`${BOX.SIDE}  Recovery attempts: ${attemptCount} (max: ${MAX_RECOVERY_ATTEMPTS})`);
+        console.log(BOX.SIDE);
+        console.log(`${BOX.SIDE}  Automatic recovery has failed multiple times.`);
+        console.log(`${BOX.SIDE}  Manual steps required:`);
+        console.log(BOX.SIDE);
+        console.log(`${BOX.SIDE}  1. cd ${worktreePath}`);
+        console.log(`${BOX.SIDE}  2. Reset WU YAML status to in_progress manually`);
+        console.log(`${BOX.SIDE}  3. git add && git commit`);
+        console.log(`${BOX.SIDE}  4. Return to main and retry wu:done`);
+        console.log(BOX.SIDE);
+        console.log(`${BOX.SIDE}  Or reset the recovery counter:`);
+        console.log(`${BOX.SIDE}  rm .lumenflow/recovery/${id}.recovery`);
+        console.log(BOX.BOT);
+        throw createRecoveryError(`Recovery loop detected for ${id} after ${attemptCount} attempts. Manual intervention required.`, { wuId: id, attemptCount, maxAttempts: MAX_RECOVERY_ATTEMPTS });
+    }
+    // Increment attempt counter before trying recovery
+    const newAttemptCount = incrementRecoveryAttempt(id);
+    console.log(`${LOG_PREFIX.DONE} Recovery attempt ${newAttemptCount}/${MAX_RECOVERY_ATTEMPTS} (WU-1335)`);
+    console.log(RECOVERY.RESUMING);
+    // WU-1749: Squash previous completion attempts before recovery
+    try {
+        const gitWorktree = createGitForPath(worktreePath);
+        const squashResult = await prepareRecoveryWithSquash(id, gitWorktree);
+        if (squashResult.squashedCount > 0) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Squashed ${squashResult.squashedCount} previous completion attempt(s)`);
+        }
+    }
+    catch (squashError) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not squash previous attempts: ${getErrorMessage(squashError)}`);
+    }
+    console.log(`${LOG_PREFIX.DONE} WU-1440: Resetting worktree YAML to in_progress for recovery flow...`);
+    // Reset the worktree YAML to in_progress (mutates doc)
+    resetWorktreeYAMLForRecovery({ worktreePath, id, doc });
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Recovery reset complete - continuing normal flow`);
+    return true;
+}
+//# sourceMappingURL=wu-done-zombie-recovery.js.map

package/dist/wu-done-zombie-recovery.js.map

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

package/dist/wu-event-sourcer.d.ts

@@ -0,0 +1,44 @@
+import { type WUEvent } from './wu-state-schema.js';
+import type { WUStateIndexer } from './wu-state-indexer.js';
+/**
+ * WU events file name constant
+ */
+export declare const WU_EVENTS_FILE_NAME = "wu-events.jsonl";
+/**
+ * WU Event Sourcer
+ *
+ * Manages event file I/O: loading events from JSONL, replaying them
+ * into a WUStateIndexer, appending new validated events, and running
+ * the delegation cutover migration on first load.
+ */
+export declare class WUEventSourcer {
+    private readonly baseDir;
+    private readonly eventsFilePath;
+    private readonly indexer;
+    constructor(baseDir: string, indexer: WUStateIndexer);
+    /** Get the events file path (used by facade for external consumers). */
+    getEventsFilePath(): string;
+    /**
+     * Load and replay events from JSONL file into the indexer.
+     *
+     * Handles:
+     * - Missing file: returns empty state
+     * - Empty file: returns empty state
+     * - Empty lines: skipped gracefully
+     * - Malformed JSON: throws error with line info
+     * - Invalid events: throws validation error
+     *
+     * @throws Error If file contains malformed JSON or invalid events
+     */
+    load(): Promise<void>;
+    /**
+     * Append an event to the events file.
+     * Validates event before appending. Creates directories if needed.
+     *
+     * @throws Error If event fails validation
+     */
+    appendEvent(event: WUEvent): Promise<void>;
+    /** Append an event to disk and apply it to the indexer. */
+    appendAndApply(event: WUEvent): Promise<void>;
+}
+//# sourceMappingURL=wu-event-sourcer.d.ts.map

package/dist/wu-event-sourcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-event-sourcer.d.ts","sourceRoot":"","sources":["../src/wu-event-sourcer.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI5D;;GAEG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAiBrD;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;gBAE7B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;IAMpD,wEAAwE;IACxE,iBAAiB,IAAI,MAAM;IAI3B;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgD3B;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAchD,2DAA2D;IACrD,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAIpD"}

package/dist/wu-event-sourcer.js

@@ -0,0 +1,135 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU Event Sourcer (WU-2013)
+ *
+ * Handles event sourcing operations for WU lifecycle:
+ * - Loading and replaying events from JSONL file
+ * - Appending new events with validation
+ * - Delegation cutover migration (delegated to wu-delegation-cutover.ts)
+ *
+ * Single responsibility: event file I/O and replay.
+ *
+ * @see {@link ./wu-state-store.ts} - Facade that delegates to this service
+ * @see {@link ./wu-state-indexer.ts} - Applies events to in-memory state
+ * @see {@link ./wu-delegation-cutover.ts} - Legacy migration logic
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { validateWUEvent } from './wu-state-schema.js';
+import { runDelegationCutoverIfNeeded } from './wu-delegation-cutover.js';
+import { getErrorMessage } from './error-handler.js';
+/**
+ * WU events file name constant
+ */
+export const WU_EVENTS_FILE_NAME = 'wu-events.jsonl';
+const FILE_NOT_FOUND_ERROR_CODE = 'ENOENT';
+function getErrorCode(error) {
+    if (typeof error !== 'object' || error === null) {
+        return null;
+    }
+    if (!('code' in error)) {
+        return null;
+    }
+    const { code } = error;
+    return typeof code === 'string' ? code : null;
+}
+/**
+ * WU Event Sourcer
+ *
+ * Manages event file I/O: loading events from JSONL, replaying them
+ * into a WUStateIndexer, appending new validated events, and running
+ * the delegation cutover migration on first load.
+ */
+export class WUEventSourcer {
+    baseDir;
+    eventsFilePath;
+    indexer;
+    constructor(baseDir, indexer) {
+        this.baseDir = baseDir;
+        this.eventsFilePath = path.join(baseDir, WU_EVENTS_FILE_NAME);
+        this.indexer = indexer;
+    }
+    /** Get the events file path (used by facade for external consumers). */
+    getEventsFilePath() {
+        return this.eventsFilePath;
+    }
+    /**
+     * Load and replay events from JSONL file into the indexer.
+     *
+     * Handles:
+     * - Missing file: returns empty state
+     * - Empty file: returns empty state
+     * - Empty lines: skipped gracefully
+     * - Malformed JSON: throws error with line info
+     * - Invalid events: throws validation error
+     *
+     * @throws Error If file contains malformed JSON or invalid events
+     */
+    async load() {
+        this.indexer.clear();
+        await runDelegationCutoverIfNeeded(this.baseDir, this.eventsFilePath);
+        let content;
+        try {
+            content = await fs.readFile(this.eventsFilePath, 'utf-8');
+        }
+        catch (error) {
+            if (getErrorCode(error) === FILE_NOT_FOUND_ERROR_CODE) {
+                return;
+            }
+            throw error;
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const rawLine = lines[i];
+            if (typeof rawLine !== 'string') {
+                continue;
+            }
+            const line = rawLine.trim();
+            if (!line) {
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch (error) {
+                throw new Error(`Malformed JSON on line ${i + 1}: ${getErrorMessage(error)}`, {
+                    cause: error,
+                });
+            }
+            const validation = validateWUEvent(parsed);
+            if (!validation.success) {
+                const issues = validation.error.issues
+                    .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                    .join(', ');
+                throw new Error(`Validation error on line ${i + 1}: ${issues}`);
+            }
+            this.indexer.applyEvent(validation.data);
+        }
+    }
+    /**
+     * Append an event to the events file.
+     * Validates event before appending. Creates directories if needed.
+     *
+     * @throws Error If event fails validation
+     */
+    async appendEvent(event) {
+        const validation = validateWUEvent(event);
+        if (!validation.success) {
+            const issues = validation.error.issues
+                .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                .join(', ');
+            throw new Error(`Validation error: ${issues}`);
+        }
+        const line = `${JSON.stringify(event)}\n`;
+        await fs.mkdir(this.baseDir, { recursive: true });
+        await fs.appendFile(this.eventsFilePath, line, 'utf-8');
+    }
+    /** Append an event to disk and apply it to the indexer. */
+    async appendAndApply(event) {
+        await this.appendEvent(event);
+        this.indexer.applyEvent(event);
+    }
+}
+//# sourceMappingURL=wu-event-sourcer.js.map

package/dist/wu-event-sourcer.js.map

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