@lumenflow/core 1.0.0

package/dist/wu-checkpoint.js

@@ -0,0 +1,233 @@
+/**
+ * WU-1747: WU Checkpoint Module
+ *
+ * Provides checkpoint-based gate resumption for wu:done operations.
+ * Allows failed wu:done to resume from checkpoint without re-running gates
+ * if nothing has changed since the checkpoint was created.
+ *
+ * Features:
+ * - Pre-gates checkpoint creation with worktree state
+ * - SHA-based change detection
+ * - Schema versioning for forward compatibility
+ * - Automatic stale checkpoint cleanup
+ *
+ * @module wu-checkpoint
+ */
+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';
+/**
+ * Schema version for checkpoint files
+ * Increment when checkpoint format changes
+ */
+export const CHECKPOINT_SCHEMA_VERSION = 1;
+/**
+ * Checkpoint directory within .beacon
+ */
+const CHECKPOINT_DIR = 'checkpoints';
+/**
+ * Maximum age for a checkpoint before it's considered stale (24 hours)
+ */
+const CHECKPOINT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Get the path to a checkpoint file
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ * @returns {string} Path to checkpoint file
+ */
+function getCheckpointPath(wuId, options = {}) {
+    const baseDir = options.baseDir || process.cwd();
+    return path.join(baseDir, '.beacon', CHECKPOINT_DIR, `${wuId}.checkpoint.json`);
+}
+/**
+ * Ensure checkpoint directory exists
+ *
+ * @param {CheckpointBaseDirOptions} [options]
+ */
+function ensureCheckpointDir(options = {}) {
+    const baseDir = options.baseDir || process.cwd();
+    const checkpointDir = path.join(baseDir, '.beacon', CHECKPOINT_DIR);
+    if (!existsSync(checkpointDir)) {
+        mkdirSync(checkpointDir, { recursive: true });
+    }
+}
+/**
+ * Generate a unique checkpoint ID
+ *
+ * @returns {string} Unique checkpoint ID
+ */
+function generateCheckpointId() {
+    return `ckpt-${crypto.randomUUID().slice(0, 8)}`;
+}
+/**
+ * Get the current HEAD SHA from a git directory
+ * Falls back to placeholder if git operations fail
+ *
+ * @param {string} dir - Directory to get HEAD SHA from
+ * @returns {string} HEAD SHA or placeholder
+ */
+function getHeadSha(dir) {
+    try {
+        // Try to read .git/HEAD directly for speed
+        const gitDir = path.join(dir, '.git');
+        if (existsSync(gitDir)) {
+            const headPath = path.join(gitDir, 'HEAD');
+            if (existsSync(headPath)) {
+                const headContent = readFileSync(headPath, 'utf8').trim();
+                // If it's a ref, read the ref file
+                if (headContent.startsWith('ref: ')) {
+                    const refPath = path.join(gitDir, headContent.slice(5));
+                    if (existsSync(refPath)) {
+                        return readFileSync(refPath, 'utf8').trim();
+                    }
+                }
+                // It's a direct SHA
+                return headContent;
+            }
+        }
+        // For worktrees, .git is a file pointing to the main repo
+        const gitFile = path.join(dir, '.git');
+        if (existsSync(gitFile)) {
+            const gitFileContent = readFileSync(gitFile, 'utf8').trim();
+            if (gitFileContent.startsWith('gitdir: ')) {
+                const worktreeGitDir = gitFileContent.slice(8);
+                const headPath = path.join(worktreeGitDir, 'HEAD');
+                if (existsSync(headPath)) {
+                    const headContent = readFileSync(headPath, 'utf8').trim();
+                    if (headContent.startsWith('ref: ')) {
+                        // Need to resolve from main repo's refs
+                        const mainGitDir = path.resolve(worktreeGitDir, '..', '..');
+                        const refPath = path.join(mainGitDir, headContent.slice(5));
+                        if (existsSync(refPath)) {
+                            return readFileSync(refPath, 'utf8').trim();
+                        }
+                    }
+                    return headContent;
+                }
+            }
+        }
+        return 'unknown-sha';
+    }
+    catch {
+        return 'unknown-sha';
+    }
+}
+/**
+ * Create a checkpoint before running gates
+ *
+ * @param {Object} params - Checkpoint parameters
+ * @param {string} params.wuId - WU ID
+ * @param {string} params.worktreePath - Path to worktree
+ * @param {string} params.branchName - Lane branch name
+ * @param {CreatePreGatesCheckpointOptions} [options]
+ * @returns {Promise<Checkpoint>} Created checkpoint
+ */
+export async function createPreGatesCheckpoint(params, options = {}) {
+    const { wuId, worktreePath, branchName, gatesPassed = false } = params;
+    const { baseDir } = options;
+    ensureCheckpointDir({ baseDir });
+    const checkpoint = {
+        schemaVersion: CHECKPOINT_SCHEMA_VERSION,
+        checkpointId: generateCheckpointId(),
+        wuId,
+        worktreePath,
+        branchName,
+        worktreeHeadSha: getHeadSha(worktreePath),
+        createdAt: new Date().toISOString(),
+        gatesPassed,
+        gatesPassedAt: gatesPassed ? new Date().toISOString() : null,
+    };
+    const checkpointPath = getCheckpointPath(wuId, { baseDir });
+    writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2));
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Created pre-gates checkpoint for ${wuId}`);
+    return checkpoint;
+}
+/**
+ * Mark a checkpoint as having passed gates
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ * @returns {boolean} True if checkpoint was updated
+ */
+export function markGatesPassed(wuId, options = {}) {
+    const checkpoint = getCheckpoint(wuId, options);
+    if (!checkpoint) {
+        return false;
+    }
+    checkpoint.gatesPassed = true;
+    checkpoint.gatesPassedAt = new Date().toISOString();
+    const checkpointPath = getCheckpointPath(wuId, options);
+    writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2));
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Marked gates passed for ${wuId}`);
+    return true;
+}
+/**
+ * Get a checkpoint for a WU
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ * @returns {Checkpoint|null} Checkpoint or null if not found
+ */
+export function getCheckpoint(wuId, options = {}) {
+    const checkpointPath = getCheckpointPath(wuId, options);
+    if (!existsSync(checkpointPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(checkpointPath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        // Corrupted checkpoint - treat as non-existent
+        return null;
+    }
+}
+/**
+ * Clear a checkpoint for a WU
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ */
+export function clearCheckpoint(wuId, options = {}) {
+    const checkpointPath = getCheckpointPath(wuId, options);
+    if (existsSync(checkpointPath)) {
+        unlinkSync(checkpointPath);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Cleared checkpoint for ${wuId}`);
+    }
+}
+export function canSkipGates(wuId, options = {}) {
+    const { baseDir, currentHeadSha } = options;
+    const checkpoint = getCheckpoint(wuId, { baseDir });
+    // No checkpoint exists
+    if (!checkpoint) {
+        return { canSkip: false, reason: 'No checkpoint exists' };
+    }
+    // Schema version mismatch
+    if (checkpoint.schemaVersion !== CHECKPOINT_SCHEMA_VERSION) {
+        return {
+            canSkip: false,
+            reason: `Checkpoint schema version mismatch (got ${checkpoint.schemaVersion}, expected ${CHECKPOINT_SCHEMA_VERSION})`,
+        };
+    }
+    // Gates didn't pass at checkpoint
+    if (!checkpoint.gatesPassed) {
+        return { canSkip: false, reason: 'Gates did not pass at checkpoint' };
+    }
+    // Check if checkpoint is stale
+    const checkpointAge = Date.now() - new Date(checkpoint.createdAt).getTime();
+    if (checkpointAge > CHECKPOINT_MAX_AGE_MS) {
+        return { canSkip: false, reason: 'Checkpoint is stale (older than 24 hours)' };
+    }
+    // SHA has changed since checkpoint
+    if (currentHeadSha && currentHeadSha !== checkpoint.worktreeHeadSha) {
+        return {
+            canSkip: false,
+            reason: 'Worktree has changed since checkpoint (SHA mismatch)',
+        };
+    }
+    // All checks passed - gates can be skipped
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Gates can be skipped - checkpoint valid (${checkpoint.checkpointId})`);
+    return { canSkip: true, checkpoint };
+}

package/dist/wu-claim-helpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file wu-claim-helpers.mjs
+ * Helper functions for wu:claim (WU-1423)
+ *
+ * Extracted email validation logic for testability and SOLID compliance.
+ */
+/**
+ * Validates if a string is a valid email address.
+ *
+ * @param {string} value - The string to validate
+ * @returns {boolean} True if valid email, false otherwise
+ */
+export declare function isValidEmail(value: any): boolean;
+/**
+ * Gets a valid email address for WU assignment.
+ *
+ * Fallback chain (WU-1423):
+ * 1. git config user.email
+ * 2. GIT_AUTHOR_EMAIL environment variable
+ * 3. Error (no silent fallback to username)
+ *
+ * @param {object} gitAdapter - Git adapter with getConfigValue method
+ * @returns {Promise<string>} Valid email address
+ * @throws {Error} If no valid email can be determined
+ */
+export declare function getAssignedEmail(gitAdapter: any): Promise<any>;

package/dist/wu-claim-helpers.js

@@ -0,0 +1,63 @@
+/**
+ * @file wu-claim-helpers.mjs
+ * Helper functions for wu:claim (WU-1423)
+ *
+ * Extracted email validation logic for testability and SOLID compliance.
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for validating email addresses.
+ * Uses Zod's built-in email validation (library-first, no regex).
+ */
+const emailSchema = z.string().email();
+/**
+ * Validates if a string is a valid email address.
+ *
+ * @param {string} value - The string to validate
+ * @returns {boolean} True if valid email, false otherwise
+ */
+export function isValidEmail(value) {
+    if (!value || typeof value !== 'string') {
+        return false;
+    }
+    return emailSchema.safeParse(value).success;
+}
+/**
+ * Gets a valid email address for WU assignment.
+ *
+ * Fallback chain (WU-1423):
+ * 1. git config user.email
+ * 2. GIT_AUTHOR_EMAIL environment variable
+ * 3. Error (no silent fallback to username)
+ *
+ * @param {object} gitAdapter - Git adapter with getConfigValue method
+ * @returns {Promise<string>} Valid email address
+ * @throws {Error} If no valid email can be determined
+ */
+export async function getAssignedEmail(gitAdapter) {
+    // Try git config user.email first (WU-1427: properly await async method)
+    try {
+        const gitEmail = await gitAdapter.getConfigValue('user.email');
+        const trimmed = gitEmail?.trim();
+        if (trimmed && isValidEmail(trimmed)) {
+            return trimmed;
+        }
+    }
+    catch {
+        // Git config not available, continue to fallback
+    }
+    // Fallback to GIT_AUTHOR_EMAIL (commonly set in CI/scripting)
+    const authorEmail = process.env.GIT_AUTHOR_EMAIL?.trim();
+    if (authorEmail && isValidEmail(authorEmail)) {
+        return authorEmail;
+    }
+    // WU-1423: NO silent fallback to username (GIT_USER, USER)
+    // These are usernames, not email addresses, and would cause wu:done validation failures
+    throw new Error('Cannot determine assigned_to email address.\n\n' +
+        'Checked:\n' +
+        '  1. git config user.email - not set or invalid\n' +
+        '  2. GIT_AUTHOR_EMAIL env var - not set or invalid\n\n' +
+        'Fix:\n' +
+        '  git config --global user.email "you@example.com"\n' +
+        '  OR export GIT_AUTHOR_EMAIL="you@example.com"');
+}

package/dist/wu-claim-resume.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @file wu-claim-resume.mjs
+ * Helper functions for wu:claim --resume agent handoff (WU-2411)
+ *
+ * When an agent crashes or is killed, its worktree remains with uncommitted work.
+ * The --resume flag allows a new agent to take over by:
+ * 1. Verifying the old PID is dead (safety check)
+ * 2. Updating the lock file with the new PID
+ * 3. Preserving the existing worktree
+ * 4. Logging the handoff to the memory layer
+ *
+ * NOTE: This is WU-specific workflow tooling. No external library provides
+ * agent handoff/PID management for git worktrees. Library-first search
+ * confirmed no applicable packages exist for this domain-specific logic.
+ */
+/**
+ * @typedef {Object} ResumeResult
+ * @property {boolean} success - Whether the resume operation succeeded
+ * @property {boolean} handoff - Whether this was a handoff (vs normal claim)
+ * @property {number|null} previousPid - PID of the previous lock holder
+ * @property {string|null} previousSession - Session ID of the previous lock holder
+ * @property {string|null} error - Error message if operation failed
+ * @property {string|null} uncommittedSummary - Summary of uncommitted changes in worktree
+ */
+/**
+ * Check if a process is running by sending signal 0.
+ * This doesn't actually send a signal, but checks if the process exists.
+ *
+ * @param {number} pid - Process ID to check
+ * @returns {boolean} True if process is running, false if not
+ */
+export declare function isProcessRunning(pid: any): boolean;
+/**
+ * Resume a WU claim from a crashed/killed agent (handoff).
+ *
+ * This function:
+ * 1. Verifies the worktree exists
+ * 2. Reads the existing lock file
+ * 3. Verifies the old PID is dead (safety check)
+ * 4. Updates the lock file with the new PID
+ *
+ * @param {Object} options - Resume options
+ * @param {string} options.wuId - WU ID (e.g., "WU-2411")
+ * @param {string} options.lane - Lane name (e.g., "Operations: Tooling")
+ * @param {string} options.worktreePath - Path to the existing worktree
+ * @param {string} [options.baseDir] - Base directory for lock files (defaults to project root)
+ * @param {string} [options.agentSession] - New agent session ID
+ * @returns {Promise<ResumeResult>} Result of the resume operation
+ */
+export declare function resumeClaimForHandoff(options: any): Promise<{
+    success: boolean;
+    handoff: boolean;
+    previousPid: number;
+    previousSession: string;
+    error: string;
+    uncommittedSummary: any;
+}>;
+/**
+ * Get a summary of uncommitted changes in a worktree.
+ *
+ * @param {Object} gitAdapter - Git adapter with getStatus method
+ * @returns {Promise<string|null>} Summary of uncommitted changes, or null if clean
+ */
+export declare function getWorktreeUncommittedChanges(gitAdapter: any): Promise<any>;
+/**
+ * Format uncommitted changes for display.
+ *
+ * @param {string} status - Raw git status output
+ * @returns {string} Formatted summary for display
+ */
+export declare function formatUncommittedChanges(status: any): string;
+/**
+ * Create a checkpoint in the memory layer documenting the handoff.
+ *
+ * @param {Object} options - Checkpoint options
+ * @param {string} options.wuId - WU ID
+ * @param {number} options.previousPid - Previous owner's PID
+ * @param {number} options.newPid - New owner's PID
+ * @param {string|null} options.previousSession - Previous owner's session ID
+ * @param {string|null} options.uncommittedSummary - Summary of uncommitted changes
+ * @param {Object} [options.memoryLayer] - Memory layer interface (for testing)
+ * @returns {Promise<{success: boolean, checkpointId?: string, error?: string}>}
+ */
+export declare function createHandoffCheckpoint(options: any): Promise<{
+    success: boolean;
+    checkpointId: any;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+    checkpointId?: undefined;
+}>;
+/**
+ * Check if a worktree exists and is valid for resumption.
+ *
+ * @param {string} worktreePath - Path to check
+ * @param {string} _expectedBranch - Expected branch name (unused, for future validation)
+ * @returns {{valid: boolean, error?: string}}
+ */
+export declare function validateWorktreeForResume(worktreePath: any, _expectedBranch: any): {
+    valid: boolean;
+    error: string;
+} | {
+    valid: boolean;
+    error?: undefined;
+};