@lumenflow/core 1.0.0

package/dist/cleanup-lock.d.ts

@@ -0,0 +1,139 @@
+/**
+ * WU-2241: Cleanup Lock Module
+ *
+ * Provides atomic locking mechanism for wu:done cleanup operations
+ * to prevent race conditions during concurrent worktree/branch cleanup.
+ *
+ * Features:
+ * - File-based lock with PID, timestamp, and worktree path
+ * - Stale lock detection and auto-cleanup (5-minute threshold)
+ * - Zombie lock detection (PID not running)
+ * - Idempotent re-acquisition for same WU
+ * - Guaranteed cleanup via withCleanupLock wrapper
+ *
+ * Lock ordering (WU-2241):
+ *   Lane lock (phase-scoped) -> Merge lock -> Cleanup lock -> State store lock
+ *
+ * Pattern: Follows lane-lock.mjs and merge-lock.mjs internal patterns.
+ *
+ * @module cleanup-lock
+ */
+/**
+ * Default timeout for waiting to acquire lock (ms)
+ * After this time, acquisition fails if lock is held
+ */
+export declare const CLEANUP_LOCK_TIMEOUT_MS = 30000;
+/**
+ * Time after which a cleanup lock is considered stale (ms)
+ * Should be greater than expected cleanup operation duration
+ * Cleanup is slower than merge, so longer timeout
+ */
+export declare const CLEANUP_LOCK_STALE_MS: number;
+/**
+ * @typedef {Object} CleanupLockInfo
+ * @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
+ * @property {string} [worktreePath] - Path to worktree being cleaned up
+ */
+/**
+ * @typedef {Object} CleanupAcquireResult
+ * @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 BaseDirOptions {
+    /** Base directory (defaults to cwd) */
+    baseDir?: string;
+}
+/**
+ * Check if a lock is stale (older than CLEANUP_LOCK_STALE_MS)
+ *
+ * @param {CleanupLockInfo} lockInfo - Lock info to check
+ * @returns {boolean} True if lock is stale
+ */
+export declare function isCleanupLockStale(lockInfo: any): boolean;
+/**
+ * Check if a lock is a zombie (PID not running)
+ *
+ * @param {CleanupLockInfo} lockInfo - Lock info to check
+ * @returns {boolean} True if lock is a zombie (PID not running)
+ */
+export declare function isCleanupLockZombie(lockInfo: any): boolean;
+/**
+ * Check if cleanup lock is currently held
+ *
+ * @param {BaseDirOptions} [options]
+ * @returns {boolean} True if lock is held (and not stale)
+ */
+export declare function isCleanupLocked(options?: BaseDirOptions): boolean;
+/**
+ * Get information about current cleanup lock
+ *
+ * @param {BaseDirOptions} [options]
+ * @returns {CleanupLockInfo|null} Lock info or null if unlocked
+ */
+export declare function getCleanupLockInfo(options?: BaseDirOptions): any;
+/**
+ * Options for acquiring cleanup lock
+ */
+export interface AcquireCleanupLockOptions extends BaseDirOptions {
+    /** Max time to wait for lock (default: CLEANUP_LOCK_TIMEOUT_MS) */
+    waitMs?: number;
+    /** Path to worktree being cleaned up */
+    worktreePath?: string | null;
+}
+/**
+ * Attempt to acquire the cleanup lock
+ *
+ * Will wait up to waitMs for lock to become available.
+ * If the same WU already holds the lock, re-acquisition succeeds (idempotent).
+ * Stale and zombie locks are automatically cleaned up.
+ *
+ * @param {string} wuId - WU ID requesting the lock
+ * @param {AcquireCleanupLockOptions} [options]
+ * @returns {Promise<CleanupAcquireResult>} Acquisition result
+ */
+export declare function acquireCleanupLock(wuId: any, options?: AcquireCleanupLockOptions): Promise<{
+    acquired: boolean;
+    lockId: any;
+    heldBy?: undefined;
+    heldSince?: undefined;
+} | {
+    acquired: boolean;
+    heldBy: any;
+    heldSince: any;
+    lockId?: undefined;
+}>;
+/**
+ * Release the cleanup 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 {BaseDirOptions} [options]
+ * @returns {boolean} True if lock was released
+ */
+export declare function releaseCleanupLock(lockId: any, options?: BaseDirOptions): boolean;
+/**
+ * Execute a function while holding the cleanup 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 {AcquireCleanupLockOptions} [options]
+ * @returns {Promise<T>} Result of function execution
+ * @throws {Error} If lock cannot be acquired or function throws
+ */
+export declare function withCleanupLock<T>(wuId: string, fn: () => Promise<T>, options?: AcquireCleanupLockOptions): Promise<T>;
+export {};

package/dist/cleanup-lock.js

@@ -0,0 +1,313 @@
+/**
+ * WU-2241: Cleanup Lock Module
+ *
+ * Provides atomic locking mechanism for wu:done cleanup operations
+ * to prevent race conditions during concurrent worktree/branch cleanup.
+ *
+ * Features:
+ * - File-based lock with PID, timestamp, and worktree path
+ * - Stale lock detection and auto-cleanup (5-minute threshold)
+ * - Zombie lock detection (PID not running)
+ * - Idempotent re-acquisition for same WU
+ * - Guaranteed cleanup via withCleanupLock wrapper
+ *
+ * Lock ordering (WU-2241):
+ *   Lane lock (phase-scoped) -> Merge lock -> Cleanup lock -> State store lock
+ *
+ * Pattern: Follows lane-lock.mjs and merge-lock.mjs internal patterns.
+ *
+ * @module cleanup-lock
+ */
+/* eslint-disable security/detect-non-literal-fs-filename -- Lock file paths are computed from trusted sources */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync, closeSync, } 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 CLEANUP_LOCK_TIMEOUT_MS = 30000; // 30 seconds
+/**
+ * Time after which a cleanup lock is considered stale (ms)
+ * Should be greater than expected cleanup operation duration
+ * Cleanup is slower than merge, so longer timeout
+ */
+export const CLEANUP_LOCK_STALE_MS = 5 * 60 * 1000; // 5 minutes
+/** Lock file name within .beacon directory */
+const LOCK_FILE_NAME = 'cleanup.lock';
+/**
+ * Polling interval for lock acquisition retries
+ */
+const LOCK_POLL_INTERVAL_MS = 500;
+/**
+ * Get the path to the cleanup lock file
+ *
+ * @param {BaseDirOptions} [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 {BaseDirOptions} [options]
+ * @returns {CleanupLockInfo|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;
+    }
+}
+/**
+ * Delete lock file
+ *
+ * @param {BaseDirOptions} [options]
+ */
+function deleteLockFile(options = {}) {
+    const lockPath = getLockPath(options);
+    if (existsSync(lockPath)) {
+        unlinkSync(lockPath);
+    }
+}
+/**
+ * Check if a lock is stale (older than CLEANUP_LOCK_STALE_MS)
+ *
+ * @param {CleanupLockInfo} lockInfo - Lock info to check
+ * @returns {boolean} True if lock is stale
+ */
+export function isCleanupLockStale(lockInfo) {
+    if (!lockInfo || !lockInfo.createdAt) {
+        return true;
+    }
+    const lockTime = new Date(lockInfo.createdAt).getTime();
+    const age = Date.now() - lockTime;
+    return age > CLEANUP_LOCK_STALE_MS;
+}
+/**
+ * Check if a lock is a zombie (PID not running)
+ *
+ * @param {CleanupLockInfo} lockInfo - Lock info to check
+ * @returns {boolean} True if lock is a zombie (PID not running)
+ */
+export function isCleanupLockZombie(lockInfo) {
+    if (!lockInfo || typeof lockInfo.pid !== 'number') {
+        return true;
+    }
+    try {
+        process.kill(lockInfo.pid, 0); // Signal 0 = check existence
+        return false; // Process exists
+    }
+    catch {
+        return true; // Process doesn't exist
+    }
+}
+/**
+ * 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 cleanup lock is currently held
+ *
+ * @param {BaseDirOptions} [options]
+ * @returns {boolean} True if lock is held (and not stale)
+ */
+export function isCleanupLocked(options = {}) {
+    const lockInfo = readLockFile(options);
+    if (!lockInfo) {
+        return false;
+    }
+    // Stale or zombie locks are treated as unlocked
+    return !isCleanupLockStale(lockInfo) && !isCleanupLockZombie(lockInfo);
+}
+/**
+ * Get information about current cleanup lock
+ *
+ * @param {BaseDirOptions} [options]
+ * @returns {CleanupLockInfo|null} Lock info or null if unlocked
+ */
+export function getCleanupLockInfo(options = {}) {
+    const lockInfo = readLockFile(options);
+    if (!lockInfo || isCleanupLockStale(lockInfo) || isCleanupLockZombie(lockInfo)) {
+        return null;
+    }
+    return lockInfo;
+}
+/**
+ * Attempt atomic lock file creation
+ * Returns 'acquired' | 'race' | throws on other errors
+ *
+ * @param {CleanupLockInfo} lockInfo - Lock info to write
+ * @param {Object} options - Options with baseDir
+ * @returns {'acquired' | 'race'} Result of acquisition attempt
+ */
+function tryAtomicLockCreate(lockInfo, options) {
+    const lockPath = getLockPath(options);
+    const beaconDir = path.dirname(lockPath);
+    if (!existsSync(beaconDir)) {
+        mkdirSync(beaconDir, { recursive: true });
+    }
+    try {
+        // Use 'wx' flag for atomic creation
+        const fd = openSync(lockPath, 'wx');
+        writeFileSync(lockPath, JSON.stringify(lockInfo, null, 2));
+        closeSync(fd);
+        return 'acquired';
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            return 'race';
+        }
+        throw err;
+    }
+}
+/**
+ * Handle stale or zombie lock cleanup
+ * Returns 'retry' if lock was cleaned, null if lock is valid
+ *
+ * @param {CleanupLockInfo} existingLock - Existing lock info
+ * @param {Object} options - Options with baseDir
+ * @returns {'retry' | null} Whether to retry acquisition
+ */
+function handleStaleLock(existingLock, options) {
+    if (isCleanupLockStale(existingLock)) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Cleaning up stale cleanup lock from ${existingLock.wuId}`);
+        deleteLockFile(options);
+        return 'retry';
+    }
+    if (isCleanupLockZombie(existingLock)) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Cleaning up zombie cleanup lock from ${existingLock.wuId} (PID ${existingLock.pid} not running)`);
+        deleteLockFile(options);
+        return 'retry';
+    }
+    return null;
+}
+/**
+ * Attempt to acquire the cleanup lock
+ *
+ * Will wait up to waitMs for lock to become available.
+ * If the same WU already holds the lock, re-acquisition succeeds (idempotent).
+ * Stale and zombie locks are automatically cleaned up.
+ *
+ * @param {string} wuId - WU ID requesting the lock
+ * @param {AcquireCleanupLockOptions} [options]
+ * @returns {Promise<CleanupAcquireResult>} Acquisition result
+ */
+export async function acquireCleanupLock(wuId, options = {}) {
+    const { baseDir, waitMs = CLEANUP_LOCK_TIMEOUT_MS, worktreePath = null } = 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',
+                worktreePath,
+            };
+            const result = tryAtomicLockCreate(lockInfo, { baseDir });
+            if (result === 'race') {
+                continue; // Race condition - retry
+            }
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Acquired cleanup lock for ${wuId}`);
+            return { acquired: true, lockId };
+        }
+        // Check for stale/zombie locks
+        if (handleStaleLock(existingLock, { baseDir }) === 'retry') {
+            continue;
+        }
+        // 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} Cleanup 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 cleanup 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 {BaseDirOptions} [options]
+ * @returns {boolean} True if lock was released
+ */
+export function releaseCleanupLock(lockId, options = {}) {
+    const existingLock = readLockFile(options);
+    if (!existingLock) {
+        return false;
+    }
+    if (existingLock.lockId !== lockId) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Cannot release cleanup lock - lockId mismatch`);
+        return false;
+    }
+    deleteLockFile(options);
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Released cleanup lock for ${existingLock.wuId}`);
+    return true;
+}
+/**
+ * Execute a function while holding the cleanup 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 {AcquireCleanupLockOptions} [options]
+ * @returns {Promise<T>} Result of function execution
+ * @throws {Error} If lock cannot be acquired or function throws
+ */
+export async function withCleanupLock(wuId, fn, options = {}) {
+    const result = await acquireCleanupLock(wuId, options);
+    if (!result.acquired) {
+        throw createError(ErrorCodes.LOCK_ERROR, `Cannot acquire cleanup lock - held by ${result.heldBy} since ${result.heldSince}`, { wuId, heldBy: result.heldBy, heldSince: result.heldSince });
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        releaseCleanupLock(result.lockId, options);
+    }
+}

package/dist/code-path-validator.d.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Unified Code Path Validator (WU-1825)
+ *
+ * Consolidates three separate code path validators into one module:
+ * - validateCodePathsExist (wu-done-validators.mjs) - file existence for wu:done
+ * - validateLaneCodePaths (lane-validator.mjs) - lane pattern matching
+ * - validateWUCodePaths (wu-validator.mjs) - code quality (TODOs, mocks)
+ *
+ * Usage:
+ *   import { validate } from './code-path-validator.js';
+ *
+ *   // Mode: 'exist' - check file existence (wu:done workflow)
+ *   const result = await validate(paths, { mode: 'exist', worktreePath, targetBranch });
+ *
+ *   // Mode: 'lane' - check lane pattern matching (wu:claim workflow)
+ *   const result = validate(paths, { mode: 'lane', lane: 'Operations: Tooling' });
+ *
+ *   // Mode: 'quality' - check code quality (TODOs, mocks)
+ *   const result = validate(paths, { mode: 'quality', worktreePath, allowTodos: false });
+ *
+ * Part of INIT-023: Workflow Integrity initiative.
+ */
+interface ExistValidationResult {
+    valid: boolean;
+    errors: string[];
+    missing: string[];
+}
+interface LaneValidationResult {
+    hasWarnings: boolean;
+    warnings: string[];
+    violations: string[];
+    skipped: boolean;
+}
+interface QualityValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+interface QualityOptions {
+    allowTodos?: boolean;
+    worktreePath?: string | null;
+}
+interface ValidateOptions {
+    mode?: string;
+    worktreePath?: string;
+    targetBranch?: string;
+    lane?: string;
+    allowTodos?: boolean;
+}
+/**
+ * Validation modes for the unified validator
+ * @enum {string}
+ */
+export declare const VALIDATION_MODES: Readonly<{
+    /** Check file existence - used by wu:done */
+    EXIST: "exist";
+    /** Check lane pattern matching - used by wu:claim */
+    LANE: "lane";
+    /** Check code quality (TODOs, mocks) - used by wu:done */
+    QUALITY: "quality";
+}>;
+/**
+ * Check if a file path is a test file
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a test file
+ */
+declare function isTestFile(filePath: string): boolean;
+/**
+ * Check if a file path is a markdown file
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a markdown file
+ */
+declare function isMarkdownFile(filePath: string): boolean;
+/**
+ * Scan a file for TODO/FIXME/HACK/XXX comments
+ * @param {string} filePath - Path to file to scan
+ * @returns {{found: boolean, matches: Array<{line: number, text: string, pattern: string}>}}
+ */
+declare function scanFileForTODOs(filePath: string): {
+    found: boolean;
+    matches: Array<{
+        line: number;
+        text: string;
+        pattern: string | null;
+    }>;
+};
+/**
+ * Scan a file for Mock/Stub/Fake class/function names
+ * @param {string} filePath - Path to file to scan
+ * @returns {{found: boolean, matches: Array<{line: number, text: string, type: string}>}}
+ */
+declare function scanFileForMocks(filePath: string): {
+    found: boolean;
+    matches: Array<{
+        line: number;
+        text: string;
+        type: string;
+    }>;
+};
+/**
+ * Unified code path validation function
+ *
+ * @param {string[]} codePaths - Array of file paths to validate
+ * @param {object} options - Validation options
+ * @param {string} options.mode - Validation mode: 'exist', 'lane', or 'quality'
+ * @param {string} [options.worktreePath] - Worktree path (for 'exist' and 'quality' modes)
+ * @param {string} [options.targetBranch] - Target branch (for 'exist' mode, branch-only)
+ * @param {string} [options.lane] - Lane name (for 'lane' mode)
+ * @param {boolean} [options.allowTodos] - Allow TODO comments (for 'quality' mode)
+ * @returns {Promise<ExistValidationResult|LaneValidationResult|QualityValidationResult>}
+ */
+export declare function validate(codePaths: string[], options?: ValidateOptions): Promise<ExistValidationResult | LaneValidationResult | QualityValidationResult>;
+interface WUDoc {
+    code_paths?: string[];
+}
+interface ExistOptions {
+    targetBranch?: string;
+    worktreePath?: string | null;
+}
+/**
+ * @deprecated Use validate(paths, { mode: 'exist' }) instead
+ * Backward-compatible wrapper for validateCodePathsExist
+ */
+export declare function validateCodePathsExist(doc: WUDoc, _id: string, options?: ExistOptions): Promise<ExistValidationResult>;
+/**
+ * @deprecated Use validate(paths, { mode: 'lane', lane }) instead
+ * Backward-compatible wrapper for validateLaneCodePaths
+ * NOTE: This must remain SYNCHRONOUS for backward compatibility
+ */
+export declare function validateLaneCodePaths(doc: WUDoc, lane: string): LaneValidationResult;
+/**
+ * @deprecated Use validate(paths, { mode: 'quality' }) instead
+ * Backward-compatible wrapper for validateWUCodePaths
+ * NOTE: This must remain SYNCHRONOUS for backward compatibility
+ */
+export declare function validateWUCodePaths(codePaths: string[], options?: QualityOptions): QualityValidationResult;
+/**
+ * Log lane validation warnings to console.
+ * Helper function to format and display warnings consistently.
+ *
+ * @param {LaneValidationResult} result - Result from validateLaneCodePaths
+ * @param {string} logPrefix - Log prefix (e.g., "[wu-claim]")
+ */
+export declare function logLaneValidationWarnings(result: LaneValidationResult, logPrefix?: string): void;
+export { isTestFile, isMarkdownFile, scanFileForTODOs, scanFileForMocks };