@lumenflow/core 3.1.3 → 3.2.1

package/dist/merge-lock.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Default timeout for waiting to acquire lock (ms)
+ * After this time, acquisition fails if lock is held
+ */
+export declare const MERGE_LOCK_TIMEOUT_MS = 30000;
+/**
+ * Time after which a lock is considered stale and can be forcibly released (ms)
+ * Should be greater than expected merge operation duration
+ */
+export declare const MERGE_LOCK_STALE_MS = 60000;
+/**
+ * @typedef {Object} LockInfo
+ * @property {string} wuId - WU ID that holds the lock
+ * @property {string} lockId - Unique lock identifier
+ * @property {string} createdAt - ISO timestamp when lock was created
+ * @property {number} pid - Process ID of lock holder
+ * @property {string} hostname - Hostname of lock holder
+ */
+/**
+ * @typedef {Object} AcquireResult
+ * @property {boolean} acquired - Whether lock was acquired
+ * @property {string} [lockId] - Lock ID if acquired
+ * @property {string} [heldBy] - WU ID holding the lock if not acquired
+ * @property {string} [heldSince] - ISO timestamp if not acquired
+ */
+/**
+ * Options for lock file operations
+ */
+interface MergeLockBaseDirOptions {
+    /**
+     * Base directory override (for testing only)
+     *
+     * WU-1174: In production, locks are always stored in LUMENFLOW_PATHS.LOCK_DIR
+     * (a temp directory). This option allows tests to use isolated directories.
+     */
+    baseDir?: string;
+}
+/**
+ * Check if merge lock is currently held
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {boolean} True if lock is held (and not stale)
+ */
+export declare function isMergeLocked(options?: MergeLockBaseDirOptions): boolean;
+/**
+ * Get information about current merge lock
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {LockInfo|null} Lock info or null if unlocked
+ */
+export declare function getMergeLockInfo(options?: MergeLockBaseDirOptions): any;
+/**
+ * Options for acquiring merge lock
+ */
+export interface AcquireMergeLockOptions extends MergeLockBaseDirOptions {
+    /** Max time to wait for lock (default: MERGE_LOCK_TIMEOUT_MS) */
+    waitMs?: number;
+}
+/**
+ * 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 declare function acquireMergeLock(wuId: UnsafeAny, options?: AcquireMergeLockOptions): Promise<{
+    acquired: boolean;
+    lockId: any;
+    heldBy?: undefined;
+    heldSince?: undefined;
+} | {
+    acquired: boolean;
+    heldBy: any;
+    heldSince: any;
+    lockId?: undefined;
+}>;
+/**
+ * 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 declare function releaseMergeLock(lockId: UnsafeAny, options?: MergeLockBaseDirOptions): boolean;
+/**
+ * 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 declare function withMergeLock<T>(wuId: string, fn: () => Promise<T>, options?: AcquireMergeLockOptions): Promise<T>;
+export {};
+//# sourceMappingURL=merge-lock.d.ts.map

package/dist/merge-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-lock.d.ts","sourceRoot":"","sources":["../src/merge-lock.ts"],"names":[],"mappings":"AA+BA;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAkB,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAKlD;;;;;;;GAOG;AAEH;;;;;;GAMG;AAEH;;GAEG;AACH,UAAU,uBAAuB;IAC/B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwGD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,uBAA4B,WAOlE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,OAMrE;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,uBAAuB;IACtE,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,uBAA4B;;;;;;;;;;GAuD5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,uBAA4B,WAgBxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,CAAC,CAAC,CAgBZ"}

package/dist/merge-lock.js

@@ -0,0 +1,260 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-1747: Merge Lock Module
+ * WU-1174: Lock files moved to temp directory to avoid polluting main checkout
+ *
+ * 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
+ * - Lock files stored in temp directory (not main checkout)
+ *
+ * @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, LUMENFLOW_PATHS, LOCK_DIR_NAME } from './wu-constants.js';
+import { createError, ErrorCodes } from './error-handler.js';
+import { LOCK_TIMEOUT_MS, MERGE_LOCK_STALE_MS as MERGE_STALE_MS, LOCK_POLL_INTERVAL_MS, } from './constants/lock-constants.js';
+/**
+ * Default timeout for waiting to acquire lock (ms)
+ * After this time, acquisition fails if lock is held
+ */
+export const MERGE_LOCK_TIMEOUT_MS = LOCK_TIMEOUT_MS;
+/**
+ * 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 = MERGE_STALE_MS;
+/** Lock file name within .lumenflow directory */
+const LOCK_FILE_NAME = 'merge.lock';
+/**
+ * Get the path to the merge lock file
+ *
+ * WU-1174: Lock files are stored in a temp directory to avoid polluting
+ * the main checkout. The baseDir option is only for testing isolation.
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {string} Path to lock file
+ */
+function getLockPath(options = {}) {
+    // WU-1174: Use temp directory for locks (not main checkout's .lumenflow/)
+    // baseDir is only used for test isolation
+    const lockDir = options.baseDir
+        ? path.join(options.baseDir, LOCK_DIR_NAME)
+        : LUMENFLOW_PATHS.LOCK_DIR;
+    return path.join(lockDir, 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 lockDir = path.dirname(lockPath);
+    // WU-1174: Ensure lock directory exists (temp directory, not .lumenflow/)
+    if (!existsSync(lockDir)) {
+        mkdirSync(lockDir, { 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);
+    }
+}
+//# sourceMappingURL=merge-lock.js.map

package/dist/merge-lock.js.map

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

package/dist/micro-worktree-shared.d.ts

@@ -0,0 +1,128 @@
+import type { GitAdapter } from './git-adapter.js';
+import type { PushRetryConfig } from './lumenflow-config-schema.js';
+/**
+ * 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;
+/**
+ * Maximum retry attempts for push when origin/main advances
+ *
+ * WU-1179: When push fails due to race condition (origin advanced while we
+ * were working), rollback local main to origin/main and retry.
+ * Each retry: fetch -> rebase temp branch -> re-merge -> push.
+ *
+ * @deprecated Use DEFAULT_PUSH_RETRY_CONFIG.retries instead (WU-1332)
+ */
+export declare const MAX_PUSH_RETRIES = 3;
+/**
+ * WU-1332: Default push retry configuration
+ *
+ * Provides sensible defaults for micro-worktree push operations.
+ * Can be overridden via workspace.yaml software_delivery.git.push_retry.
+ */
+export declare const DEFAULT_PUSH_RETRY_CONFIG: PushRetryConfig;
+/**
+ * Resolve effective push retry config from defaults + global config + operation override.
+ *
+ * Priority (lowest to highest):
+ * 1. DEFAULT_PUSH_RETRY_CONFIG
+ * 2. Global config from workspace.yaml software_delivery (`git.push_retry`)
+ * 3. Operation-specific override from caller
+ */
+export declare function resolvePushRetryConfig(globalConfig?: Partial<PushRetryConfig>, operationOverride?: Partial<PushRetryConfig>): PushRetryConfig;
+/**
+ * Environment variable name for LUMENFLOW_FORCE bypass
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export declare const LUMENFLOW_FORCE_ENV = "LUMENFLOW_FORCE";
+/**
+ * Environment variable name for LUMENFLOW_FORCE_REASON audit trail
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export declare const LUMENFLOW_FORCE_REASON_ENV = "LUMENFLOW_FORCE_REASON";
+/**
+ * Environment variable name for LUMENFLOW_WU_TOOL
+ *
+ * WU-1365: Exported for use by CLI commands that use micro-worktree operations.
+ * The pre-push hook checks this env var to allow micro-worktree pushes to main.
+ * Valid values are: wu-create, wu-edit, wu-done, wu-delete, wu-claim, wu-block,
+ * wu-unblock, initiative-create, initiative-edit, release, lumenflow-upgrade
+ */
+export declare const LUMENFLOW_WU_TOOL_ENV = "LUMENFLOW_WU_TOOL";
+/**
+ * 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]";
+/**
+ * WU-1336: Typed error for retry exhaustion in micro-worktree operations
+ *
+ * Thrown when push retries are exhausted due to race conditions with parallel agents.
+ * CLI commands should use `isRetryExhaustionError` to detect this error type and
+ * `formatRetryExhaustionError` to generate actionable user-facing messages.
+ */
+export declare class RetryExhaustionError extends Error {
+    readonly name = "RetryExhaustionError";
+    readonly operation: string;
+    readonly retries: number;
+    constructor(operation: string, retries: number);
+}
+/**
+ * WU-1336: Options for formatting retry exhaustion error messages
+ */
+export interface FormatRetryExhaustionOptions {
+    command: string;
+}
+/**
+ * WU-1336: Type guard to check if an error is a retry exhaustion error
+ *
+ * Detects both the typed `RetryExhaustionError` class and legacy error messages
+ * that match the "Push failed after N attempts" pattern.
+ */
+export declare function isRetryExhaustionError(error: unknown): error is Error;
+/**
+ * WU-1336: Format retry exhaustion error with actionable next steps
+ */
+export declare function formatRetryExhaustionError(error: Error, options: FormatRetryExhaustionOptions): string;
+/**
+ * WU-1308: Check if remote operations should be skipped based on git.requireRemote config
+ */
+export declare function shouldSkipRemoteOperations(): boolean;
+/**
+ * Temp branch prefix for micro-worktree operations
+ */
+export declare function getTempBranchName(operation: string, id: string): string;
+/**
+ * Create micro-worktree in /tmp directory
+ */
+export declare function createMicroWorktreeDir(prefix: string): string;
+/**
+ * Parse git worktree list output to find worktrees by branch
+ */
+export declare function findWorktreeByBranch(worktreeListOutput: string, branchName: string): string | null;
+/**
+ * Clean up orphaned micro-worktree and temp branch from a previous interrupted operation
+ */
+export declare function cleanupOrphanedMicroWorktree(operation: string, id: string, gitAdapter: GitAdapter, logPrefix?: string): Promise<{
+    cleanedWorktree: boolean;
+    cleanedBranch: boolean;
+}>;
+/**
+ * Cleanup micro-worktree and temp branch
+ */
+export declare function cleanupMicroWorktree(worktreePath: string, branchName: string, logPrefix?: string): Promise<void>;
+/**
+ * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
+ */
+export declare function pushRefspecWithForce(gitAdapter: GitAdapter, remote: string, localRef: string, remoteRef: string, reason: string): Promise<void>;
+/**
+ * WU-1337: Push using refspec with LUMENFLOW_FORCE and retry logic
+ */
+export declare function pushRefspecWithRetry(gitWorktree: GitAdapter, mainGit: GitAdapter, remote: string, localRef: string, remoteRef: string, reason: string, logPrefix?: string, config?: PushRetryConfig): Promise<void>;
+//# sourceMappingURL=micro-worktree-shared.d.ts.map

package/dist/micro-worktree-shared.d.ts.map

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