@lumenflow/core 1.0.0

package/dist/merge-lock.js

@@ -0,0 +1,251 @@
+/**
+ * WU-1747: Merge Lock Module
+ *
+ * Provides atomic locking mechanism for wu:done merge operations
+ * to prevent race conditions during concurrent completions.
+ *
+ * Features:
+ * - File-based lock with PID and timestamp
+ * - Stale lock detection and auto-cleanup
+ * - Idempotent re-acquisition for same WU
+ * - Guaranteed cleanup via withMergeLock wrapper
+ *
+ * @module merge-lock
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { LOG_PREFIX, EMOJI } from './wu-constants.js';
+import { createError, ErrorCodes } from './error-handler.js';
+/**
+ * Default timeout for waiting to acquire lock (ms)
+ * After this time, acquisition fails if lock is held
+ */
+export const MERGE_LOCK_TIMEOUT_MS = 30000; // 30 seconds
+/**
+ * Time after which a lock is considered stale and can be forcibly released (ms)
+ * Should be greater than expected merge operation duration
+ */
+export const MERGE_LOCK_STALE_MS = 60000; // 60 seconds
+/** Lock file name within .beacon directory */
+const LOCK_FILE_NAME = 'merge.lock';
+/**
+ * Polling interval for lock acquisition retries
+ */
+const LOCK_POLL_INTERVAL_MS = 500;
+/**
+ * Get the path to the merge lock file
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {string} Path to lock file
+ */
+function getLockPath(options = {}) {
+    const baseDir = options.baseDir || process.cwd();
+    return path.join(baseDir, '.beacon', LOCK_FILE_NAME);
+}
+/**
+ * Read lock file contents
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {LockInfo|null} Lock info or null if no lock
+ */
+function readLockFile(options = {}) {
+    const lockPath = getLockPath(options);
+    if (!existsSync(lockPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(lockPath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        // Corrupted lock file - treat as no lock
+        return null;
+    }
+}
+/**
+ * Write lock file
+ *
+ * @param {LockInfo} lockInfo - Lock information to write
+ * @param {MergeLockBaseDirOptions} [options]
+ */
+function writeLockFile(lockInfo, options = {}) {
+    const lockPath = getLockPath(options);
+    const beaconDir = path.dirname(lockPath);
+    // Ensure .beacon directory exists
+    if (!existsSync(beaconDir)) {
+        mkdirSync(beaconDir, { recursive: true });
+    }
+    writeFileSync(lockPath, JSON.stringify(lockInfo, null, 2));
+}
+/**
+ * Delete lock file
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ */
+function deleteLockFile(options = {}) {
+    const lockPath = getLockPath(options);
+    if (existsSync(lockPath)) {
+        unlinkSync(lockPath);
+    }
+}
+/**
+ * Check if a lock is stale (older than MERGE_LOCK_STALE_MS)
+ *
+ * @param {LockInfo} lockInfo - Lock info to check
+ * @returns {boolean} True if lock is stale
+ */
+function isLockStale(lockInfo) {
+    if (!lockInfo || !lockInfo.createdAt) {
+        return true;
+    }
+    const lockTime = new Date(lockInfo.createdAt).getTime();
+    const age = Date.now() - lockTime;
+    return age > MERGE_LOCK_STALE_MS;
+}
+/**
+ * Generate a unique lock ID
+ *
+ * @returns {string} Unique lock ID
+ */
+function generateLockId() {
+    return crypto.randomUUID();
+}
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Check if merge lock is currently held
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {boolean} True if lock is held (and not stale)
+ */
+export function isMergeLocked(options = {}) {
+    const lockInfo = readLockFile(options);
+    if (!lockInfo) {
+        return false;
+    }
+    // Stale locks are treated as unlocked
+    return !isLockStale(lockInfo);
+}
+/**
+ * Get information about current merge lock
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {LockInfo|null} Lock info or null if unlocked
+ */
+export function getMergeLockInfo(options = {}) {
+    const lockInfo = readLockFile(options);
+    if (!lockInfo || isLockStale(lockInfo)) {
+        return null;
+    }
+    return lockInfo;
+}
+/**
+ * Attempt to acquire the merge lock
+ *
+ * Will wait up to waitMs for lock to become available.
+ * If the same WU already holds the lock, re-acquisition succeeds (idempotent).
+ * Stale locks are automatically cleaned up.
+ *
+ * @param {string} wuId - WU ID requesting the lock
+ * @param {AcquireMergeLockOptions} [options]
+ * @returns {Promise<AcquireResult>} Acquisition result
+ */
+export async function acquireMergeLock(wuId, options = {}) {
+    const { baseDir, waitMs = MERGE_LOCK_TIMEOUT_MS } = options;
+    const startTime = Date.now();
+    while (true) {
+        const existingLock = readLockFile({ baseDir });
+        // No lock exists - acquire it
+        if (!existingLock) {
+            const lockId = generateLockId();
+            const lockInfo = {
+                wuId,
+                lockId,
+                createdAt: new Date().toISOString(),
+                pid: process.pid,
+                hostname: process.env.HOSTNAME || 'unknown',
+            };
+            writeLockFile(lockInfo, { baseDir });
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Acquired merge lock for ${wuId}`);
+            return { acquired: true, lockId };
+        }
+        // Lock is stale - clean it up and acquire
+        if (isLockStale(existingLock)) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Cleaning up stale lock from ${existingLock.wuId}`);
+            deleteLockFile({ baseDir });
+            continue; // Retry acquisition
+        }
+        // Same WU already holds lock - return existing lock ID (idempotent)
+        if (existingLock.wuId === wuId) {
+            return { acquired: true, lockId: existingLock.lockId };
+        }
+        // Different WU holds lock - check if we should wait
+        const elapsed = Date.now() - startTime;
+        if (elapsed >= waitMs) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Merge lock held by ${existingLock.wuId} since ${existingLock.createdAt}`);
+            return {
+                acquired: false,
+                heldBy: existingLock.wuId,
+                heldSince: existingLock.createdAt,
+            };
+        }
+        // Wait and retry
+        await sleep(LOCK_POLL_INTERVAL_MS);
+    }
+}
+/**
+ * Release the merge lock
+ *
+ * Only releases if the provided lockId matches the current lock.
+ * This prevents accidentally releasing another WU's lock.
+ *
+ * @param {string} lockId - Lock ID to release
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {boolean} True if lock was released
+ */
+export function releaseMergeLock(lockId, options = {}) {
+    const existingLock = readLockFile(options);
+    if (!existingLock) {
+        return false;
+    }
+    if (existingLock.lockId !== lockId) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Cannot release lock - lockId mismatch`);
+        return false;
+    }
+    deleteLockFile(options);
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Released merge lock for ${existingLock.wuId}`);
+    return true;
+}
+/**
+ * Execute a function while holding the merge lock
+ *
+ * Guarantees the lock is released after function completes,
+ * even if the function throws an error.
+ *
+ * @template T
+ * @param {string} wuId - WU ID requesting the lock
+ * @param {function(): Promise<T>} fn - Async function to execute
+ * @param {AcquireMergeLockOptions} [options]
+ * @returns {Promise<T>} Result of function execution
+ * @throws {Error} If lock cannot be acquired or function throws
+ */
+export async function withMergeLock(wuId, fn, options = {}) {
+    const result = await acquireMergeLock(wuId, options);
+    if (!result.acquired) {
+        throw createError(ErrorCodes.LOCK_ERROR, `Cannot acquire merge lock - held by ${result.heldBy} since ${result.heldSince}`, { wuId, heldBy: result.heldBy, heldSince: result.heldSince });
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        releaseMergeLock(result.lockId, options);
+    }
+}

package/dist/micro-worktree.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Micro-Worktree Operations
+ *
+ * Race-safe micro-worktree isolation pattern extracted from wu-create.mjs (WU-1262).
+ * Provides shared infrastructure for commands that need to modify main branch
+ * atomically without switching checkout.
+ *
+ * Part of WU-1262: Race-safe WU creation using micro-worktrees
+ * Extended in WU-1274: Add wu:edit command for spec-only changes
+ * Extended in WU-1439: Migrate initiative:create and wu:create to shared helper
+ *
+ * Pattern:
+ * 1. Create temp branch without switching main checkout
+ * 2. Create micro-worktree in /tmp pointing to temp branch
+ * 3. Perform operations in micro-worktree
+ * 4. FF-only merge temp branch to main (retry with rebase if main moved)
+ * 5. Push to origin
+ * 6. Cleanup (always, even on failure)
+ *
+ * Benefits:
+ * - Main checkout never switches branches (no impact on other agents)
+ * - Race conditions handled via rebase+retry (up to MAX_MERGE_RETRIES attempts)
+ * - Cleanup guaranteed even on failure
+ *
+ * Consumers:
+ * @see {@link tools/wu-create.mjs} - WU creation (WU-1262, WU-1439)
+ * @see {@link tools/wu-edit.mjs} - Spec edits (WU-1274)
+ * @see {@link tools/initiative-create.mjs} - Initiative creation (WU-1439)
+ */
+/**
+ * Maximum retry attempts for ff-only merge when main moves
+ *
+ * This handles race conditions when multiple agents run wu:create or wu:edit
+ * concurrently. Each retry fetches latest main and rebases.
+ */
+export declare const MAX_MERGE_RETRIES = 3;
+/**
+ * Default log prefix for micro-worktree operations
+ *
+ * Extracted to constant to satisfy sonarjs/no-duplicate-string rule.
+ */
+export declare const DEFAULT_LOG_PREFIX = "[micro-wt]";
+/**
+ * Temp branch prefix for micro-worktree operations
+ *
+ * @param {string} operation - Operation name (e.g., 'wu-create', 'wu-edit')
+ * @param {string} id - WU ID (e.g., 'wu-123')
+ * @returns {string} Temp branch name (e.g., 'tmp/wu-create/wu-123')
+ */
+export declare function getTempBranchName(operation: any, id: any): string;
+/**
+ * Create micro-worktree in /tmp directory
+ *
+ * @param {string} prefix - Directory prefix (e.g., 'wu-create-', 'wu-edit-')
+ * @returns {string} Path to created micro-worktree directory
+ */
+export declare function createMicroWorktreeDir(prefix: any): string;
+/**
+ * Parse git worktree list output to find worktrees by branch
+ *
+ * WU-2237: Helper to parse porcelain format output from `git worktree list --porcelain`
+ *
+ * @param {string} worktreeListOutput - Output from git worktree list --porcelain
+ * @param {string} branchName - Branch name to search for (e.g., 'tmp/wu-create/wu-123')
+ * @returns {string|null} Worktree path if found, null otherwise
+ */
+export declare function findWorktreeByBranch(worktreeListOutput: any, branchName: any): any;
+/**
+ * Clean up orphaned micro-worktree and temp branch from a previous interrupted operation
+ *
+ * WU-2237: Before creating a new micro-worktree, detect and clean any existing temp
+ * branch/worktree for the same operation+WU ID. This handles scenarios where:
+ * - A previous wu:create/wu:edit was interrupted (timeout/crash)
+ * - The temp branch and /tmp worktree were left behind
+ * - A subsequent operation would fail with 'branch already exists'
+ *
+ * This function is idempotent - safe to call even when no orphans exist.
+ *
+ * @param {string} operation - Operation name (e.g., 'wu-create', 'wu-edit')
+ * @param {string} id - WU ID (e.g., 'WU-123')
+ * @param {Object} gitAdapter - GitAdapter instance to use (for testability)
+ * @param {string} logPrefix - Log prefix for console output
+ * @returns {Promise<{cleanedWorktree: boolean, cleanedBranch: boolean}>} Cleanup status
+ */
+export declare function cleanupOrphanedMicroWorktree(operation: any, id: any, gitAdapter: any, logPrefix?: string): Promise<{
+    cleanedWorktree: boolean;
+    cleanedBranch: boolean;
+}>;
+/**
+ * Cleanup micro-worktree and temp branch
+ *
+ * Runs even on failure to prevent orphaned resources.
+ * Safe to call multiple times (idempotent).
+ *
+ * WU-2237: Enhanced to also check git worktree list for registered worktrees
+ * on the temp branch, in case the worktree path differs from what was expected.
+ *
+ * @param {string} worktreePath - Path to micro-worktree
+ * @param {string} branchName - Temp branch name
+ * @param {string} logPrefix - Log prefix for console output
+ */
+export declare function cleanupMicroWorktree(worktreePath: any, branchName: any, logPrefix?: string): Promise<void>;
+/**
+ * Stage changes including deletions in micro-worktree
+ *
+ * WU-1813: Uses addWithDeletions to properly stage tracked file deletions.
+ * This replaces the previous pattern of using gitWorktree.add(files) which
+ * could miss deletions when files were removed.
+ *
+ * @param {Object} gitWorktree - GitAdapter instance for the worktree
+ * @param {string[]|undefined} files - Files to stage (undefined/empty = stage all)
+ * @returns {Promise<void>}
+ */
+export declare function stageChangesWithDeletions(gitWorktree: any, files: any): Promise<void>;
+/**
+ * Format files using prettier before committing
+ *
+ * WU-1435: Ensures committed files pass format gates.
+ * Runs prettier --write on specified files within the micro-worktree.
+ *
+ * @param {string[]} files - Relative file paths to format
+ * @param {string} worktreePath - Path to the micro-worktree
+ * @param {string} logPrefix - Log prefix for console output
+ */
+export declare function formatFiles(files: any, worktreePath: any, logPrefix?: string): Promise<void>;
+/**
+ * Merge temp branch to main with ff-only and retry logic
+ *
+ * Handles race conditions when main branch advances between operation start
+ * and merge attempt. Retries with rebase up to MAX_MERGE_RETRIES times.
+ *
+ * @param {string} tempBranchName - Temp branch to merge
+ * @param {string} microWorktreePath - Path to micro-worktree (for rebase)
+ * @param {string} logPrefix - Log prefix for console output
+ * @throws {Error} If merge fails after all retries
+ */
+export declare function mergeWithRetry(tempBranchName: any, microWorktreePath: any, logPrefix?: string): Promise<void>;
+/**
+ * Execute an operation in a micro-worktree with full isolation
+ *
+ * This is the main entry point for micro-worktree operations.
+ * Handles the full lifecycle: create temp branch, create worktree,
+ * execute operation, merge, push, and cleanup.
+ *
+ * WU-1435: Added pushOnly option to keep local main pristine.
+ * WU-2237: Added pre-creation cleanup of orphaned temp branches/worktrees.
+ *
+ * @param {Object} options - Options for the operation
+ * @param {string} options.operation - Operation name (e.g., 'wu-create', 'wu-edit')
+ * @param {string} options.id - WU ID (e.g., 'WU-123')
+ * @param {string} options.logPrefix - Log prefix for console output
+ * @param {boolean} [options.pushOnly=false] - Skip local main merge, push directly to origin/main
+ * @param {Function} options.execute - Async function to execute in micro-worktree
+ *   Receives: { worktreePath: string, gitWorktree: GitAdapter }
+ *   Should return: { commitMessage: string, files: string[] }
+ * @returns {Promise<Object>} Result with ref property for worktree creation
+ * @throws {Error} If any step fails (cleanup still runs)
+ */
+export declare function withMicroWorktree(options: any): Promise<any>;