@lumenflow/core 1.0.0 → 1.3.2

package/dist/wu-done-paths.js

@@ -0,0 +1,237 @@
+/**
+ * Path and workspace detection helpers for wu:done.
+ */
+import path from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { getGitForCwd } from './git-adapter.js';
+import { WU_PATHS } from './wu-paths.js';
+import { parseYAML, readWU } from './wu-yaml.js';
+import { CLAIMED_MODES, EMOJI, LOG_PREFIX, STRING_LITERALS, toKebab } from './wu-constants.js';
+import { detectDocsOnlyByPaths } from './wu-done-docs-only.js';
+/**
+ * Read WU YAML preferring worktree version over main version
+ *
+ * WU-1584 Fix #4: Added diagnostic logging to confirm which YAML file is being
+ * read for code_paths validation. This helps debug issues where worktree YAML
+ * differs from main checkout YAML.
+ *
+ * @param {string} id - WU ID
+ * @param {string|null} worktreePath - Worktree path (null if branch-only mode)
+ * @param {string} mainWUPath - Path to WU YAML in main checkout
+ * @returns {object} Parsed WU document
+ */
+export function readWUPreferWorktree(id, worktreePath, mainWUPath) {
+    if (worktreePath) {
+        const wtWUPath = path.join(worktreePath, WU_PATHS.WU(id));
+        if (existsSync(wtWUPath)) {
+            try {
+                const text = readFileSync(wtWUPath, { encoding: 'utf-8' });
+                const doc = parseYAML(text);
+                if (doc && doc.id === id) {
+                    // WU-1584: Log source file for validation debugging
+                    console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Reading WU YAML from worktree: ${wtWUPath}`);
+                    if (doc.code_paths && doc.code_paths.length > 0) {
+                        console.log(`${LOG_PREFIX.DONE}   code_paths source: worktree (${doc.code_paths.length} path(s))`);
+                    }
+                    return doc;
+                }
+                // If ID mismatch, log warning but continue
+                console.warn(`${LOG_PREFIX.DONE} Warning: Worktree YAML ID mismatch (expected ${id}, got ${doc?.id})`);
+            }
+            catch (err) {
+                // Log parse errors for debugging
+                console.warn(`${LOG_PREFIX.DONE} Warning: Failed to read worktree YAML: ${err.message}`);
+            }
+        }
+        else {
+            // Log missing worktree YAML for debugging
+            console.warn(`${LOG_PREFIX.DONE} Warning: Worktree YAML not found at ${wtWUPath}`);
+        }
+    }
+    // WU-1584: Log when falling back to main checkout YAML
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Reading WU YAML from main: ${mainWUPath}`);
+    const doc = readWU(mainWUPath, id);
+    if (doc.code_paths && doc.code_paths.length > 0) {
+        console.log(`${LOG_PREFIX.DONE}   code_paths source: main checkout (${doc.code_paths.length} path(s))`);
+    }
+    return doc;
+}
+/**
+ * Detect if currently running inside a worktree
+ * Checks for .git file (not directory) which indicates a worktree
+ * @returns {string|null} Current directory path if inside worktree, null otherwise
+ */
+export function detectCurrentWorktree() {
+    const cwd = process.cwd();
+    const gitPath = path.join(cwd, '.git');
+    // Check if .git exists and is a file (worktrees have .git file, main has .git directory)
+    if (!existsSync(gitPath))
+        return null;
+    try {
+        const stats = statSync(gitPath);
+        if (stats.isFile()) {
+            // Parse .git file to verify it points to main repo's worktrees
+            const gitContent = readFileSync(gitPath, { encoding: 'utf-8' });
+            const match = gitContent.match(/^gitdir:\s*(.+)$/m);
+            if (match && match[1].includes('.git/worktrees/')) {
+                console.log(`${LOG_PREFIX.DONE} ${EMOJI.TARGET} Auto-detected worktree from process.cwd(): ${cwd}`);
+                return cwd;
+            }
+        }
+    }
+    catch (err) {
+        // Ignore errors, fall back to calculated path
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Failed to detect worktree: ${err.message}`);
+    }
+    return null;
+}
+/**
+ * Resolve worktree path from WU YAML
+ * Originally implemented in WU-1226, extracted to validators module in WU-1215
+ * Priority:
+ * 1. Read worktree_path field (set at claim time, immune to lane field changes)
+ * 2. Fall back to calculating from lane field (for old WUs without worktree_path)
+ * 3. Use git worktree list to find actual path (defensive fallback)
+ * @param {object} doc - WU YAML document
+ * @returns {Promise<string|null>} - Worktree path or null if not found
+ */
+export async function defaultWorktreeFrom(doc) {
+    // Priority 1 - use recorded worktree_path if available
+    if (doc.worktree_path) {
+        return doc.worktree_path;
+    }
+    // Priority 2 - calculate from current lane field (legacy behavior)
+    const lane = (doc.lane || '').toString();
+    const laneK = toKebab(lane);
+    const idK = (doc.id || '').toLowerCase();
+    if (!laneK || !idK)
+        return null;
+    const calculated = `worktrees/${laneK}-${idK}`;
+    // Priority 3 - verify calculated path exists, or find actual path via git worktree list
+    let calculatedExists = true;
+    try {
+        await access(calculated);
+    }
+    catch {
+        calculatedExists = false;
+    }
+    if (!calculatedExists) {
+        try {
+            const worktreeList = await getGitForCwd().worktreeList();
+            const lines = worktreeList.split(STRING_LITERALS.NEWLINE);
+            const branch = `lane/${laneK}/${idK}`;
+            for (let i = 0; i < lines.length; i++) {
+                if (lines[i].startsWith('branch ') && lines[i].includes(branch)) {
+                    // Found the branch, now get the worktree path from previous line
+                    for (let j = i - 1; j >= 0; j--) {
+                        if (lines[j].startsWith('worktree ')) {
+                            const fullPath = lines[j].substring('worktree '.length);
+                            // Convert absolute path to relative path from repo root
+                            const repoRoot = process.cwd();
+                            const relativePath = path.relative(repoRoot, fullPath);
+                            console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Worktree path mismatch detected:\n` +
+                                `  Expected: ${calculated}\n` +
+                                `  Actual:   ${relativePath}\n` +
+                                `  Using actual path from git worktree list`);
+                            return relativePath;
+                        }
+                    }
+                }
+            }
+        }
+        catch (e) {
+            console.warn(`${LOG_PREFIX.DONE} Could not query git worktree list: ${e.message}`);
+        }
+    }
+    return calculated;
+}
+/**
+ * Detect workspace mode from WU YAML
+ * @param {object} doc - WU YAML document
+ * @returns {'worktree' | 'branch-only'}
+ */
+export function detectWorkspaceMode(doc) {
+    // Explicit mode field takes precedence
+    if (doc.claimed_mode === CLAIMED_MODES.BRANCH_ONLY)
+        return CLAIMED_MODES.BRANCH_ONLY;
+    if (doc.claimed_mode === CLAIMED_MODES.WORKTREE)
+        return CLAIMED_MODES.WORKTREE;
+    // Backward compatibility: if claimed_mode is missing, assume worktree mode
+    // (all WUs claimed before WU-510 used worktree mode)
+    return CLAIMED_MODES.WORKTREE;
+}
+/**
+ * Calculate lane branch name from WU YAML
+ * @param {object} doc - WU YAML document
+ * @returns {string|null} Lane branch name (e.g., lane/operations-tooling/wu-1215)
+ */
+export function defaultBranchFrom(doc) {
+    const lane = (doc.lane || '').toString();
+    const laneK = toKebab(lane);
+    const idK = (doc.id || '').toLowerCase();
+    if (!laneK || !idK)
+        return null;
+    return `lane/${laneK}/${idK}`;
+}
+/**
+ * Check if a branch exists
+ * @param {string} branch - Branch name to check
+ * @returns {Promise<boolean>} True if branch exists
+ */
+export async function branchExists(branch) {
+    return await getGitForCwd().branchExists(branch);
+}
+/**
+ * Detect workspace mode and calculate all relevant paths
+ * @param {string} id - WU ID
+ * @param {object} args - Parsed command-line arguments
+ * @returns {Promise<object>} Object containing paths, mode info, and WU document
+ */
+export async function detectModeAndPaths(id, args) {
+    const WU_PATH = WU_PATHS.WU(id);
+    const STATUS_PATH = WU_PATHS.STATUS();
+    const BACKLOG_PATH = WU_PATHS.BACKLOG();
+    const STAMPS_DIR = WU_PATHS.STAMPS_DIR();
+    // Read WU YAML to detect workspace mode
+    const docMain = readWU(WU_PATH, id);
+    const workspaceMode = detectWorkspaceMode(docMain);
+    const isBranchOnly = workspaceMode === CLAIMED_MODES.BRANCH_ONLY;
+    console.log(`\n${LOG_PREFIX.DONE} Detected workspace mode: ${workspaceMode}`);
+    // Determine candidate worktree path early (only relevant for Worktree mode)
+    // Priority: 1) Auto-detect from cwd 2) Explicit --worktree arg 3) Calculate from YAML
+    const detectedWorktree = detectCurrentWorktree();
+    const worktreePathGuess = args.worktree || null;
+    // For Worktree mode: prefer auto-detected worktree, then explicit arg, then calculated path
+    // For Branch-Only mode: use main checkout version (no worktree exists)
+    const derivedWorktree = isBranchOnly
+        ? null
+        : detectedWorktree || worktreePathGuess || (await defaultWorktreeFrom(docMain));
+    if (!isBranchOnly && derivedWorktree && !detectedWorktree) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.FOLDER} Calculated worktree path from YAML: ${derivedWorktree}`);
+    }
+    // Read the actual WU YAML for validation (prefer worktree version over main)
+    const docForValidation = isBranchOnly
+        ? docMain
+        : readWUPreferWorktree(id, derivedWorktree, WU_PATH);
+    // WU-1234: Detect docs-only by type OR by code_paths
+    // Auto-detect if all code_paths are under docs/, ai/, .claude/, or are README/CLAUDE files
+    const isDocsOnlyByType = docForValidation.type === 'documentation';
+    const isDocsOnlyByPaths = detectDocsOnlyByPaths(docForValidation.code_paths);
+    const isDocsOnly = isDocsOnlyByType || isDocsOnlyByPaths;
+    if (isDocsOnlyByPaths && !isDocsOnlyByType) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Auto-detected docs-only WU from code_paths (type: ${docForValidation.type || 'unset'})`);
+    }
+    return {
+        WU_PATH,
+        STATUS_PATH,
+        BACKLOG_PATH,
+        STAMPS_DIR,
+        docMain,
+        workspaceMode,
+        isBranchOnly,
+        derivedWorktree,
+        docForValidation,
+        isDocsOnly,
+    };
+}

package/dist/wu-done-preflight.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Preflight validation helpers for wu:done.
+ */
+import { execSync as execSyncImport } from 'node:child_process';
+import { validatePreflight } from './wu-preflight-validators.js';
+/**
+ * WU-1781: Build preflight error message with actionable guidance
+ */
+export declare function buildPreflightErrorMessage(id: any, errors: any): string;
+/**
+ * WU-1805: Execute preflight code_paths and test_paths validation
+ */
+export interface ExecutePreflightCodePathValidationOptions {
+    /** Override validatePreflight for testing */
+    validatePreflightFn?: typeof validatePreflight;
+}
+export declare function executePreflightCodePathValidation(id: any, paths: any, options?: ExecutePreflightCodePathValidationOptions): Promise<{
+    valid: boolean;
+    errors: any[];
+    missingCodePaths: any[];
+    missingTestPaths: any[];
+    abortedBeforeGates: boolean;
+}>;
+/**
+ * WU-1805: Build preflight code_paths error message with actionable guidance
+ */
+export declare function buildPreflightCodePathErrorMessage(id: any, result: any): string;
+/**
+ * WU-1781: Run tasks:validate as preflight check before any git operations
+ */
+export interface ExecSyncOverrideOptions {
+    /** Override execSync for testing (default: child_process.execSync) */
+    execSyncFn?: typeof execSyncImport;
+}
+export declare function runPreflightTasksValidation(id: any, options?: ExecSyncOverrideOptions): {
+    valid: boolean;
+    errors: any;
+    abortedBeforeMerge: boolean;
+    localMainModified: boolean;
+    hasStampStatusError: any;
+};
+/**
+ * WU-2308: Validate all pre-commit hooks with worktree context
+ */
+export declare function validateAllPreCommitHooks(id: any, worktreePath?: any, options?: ExecSyncOverrideOptions): {
+    valid: boolean;
+    errors: any[];
+};

package/dist/wu-done-preflight.js

@@ -0,0 +1,185 @@
+/**
+ * Preflight validation helpers for wu:done.
+ */
+import { execSync as execSyncImport } from 'node:child_process';
+import { validatePreflight } from './wu-preflight-validators.js';
+import { LOG_PREFIX, EMOJI, STDIO } from './wu-constants.js';
+/**
+ * WU-1781: Build preflight error message with actionable guidance
+ */
+export function buildPreflightErrorMessage(id, errors) {
+    const hasStampStatusError = errors.some((e) => e.includes('stamp but status is not done'));
+    let message = `
+❌ PREFLIGHT VALIDATION FAILED
+
+tasks:validate found errors that would block pre-push hooks.
+Aborting wu:done BEFORE any merge operations to prevent deadlocks.
+
+Errors:
+${errors.map((e) => `  - ${e}`).join('\n')}
+
+Fix options:
+`;
+    if (hasStampStatusError) {
+        message += `
+  For stamp-status mismatch errors:
+  1. Fix the WU status to match the stamp (set status: done, locked: true)
+  2. Or add the WU ID to .lumenflow.config.yaml > exemptions > stamp_status_mismatch
+
+`;
+    }
+    message += `
+  General fixes:
+  1. Run: pnpm tasks:validate to see full errors
+  2. Fix the validation errors
+  3. Retry: pnpm wu:done --id ${id}
+
+This preflight check prevents wu:done from leaving main in a stuck state
+where husky pre-push would block all further operations.
+`;
+    return message;
+}
+export async function executePreflightCodePathValidation(id, paths, options = {}) {
+    // Use injected validator for testability, default to actual implementation
+    const validatePreflightFn = options.validatePreflightFn || validatePreflight;
+    console.log(`\n${LOG_PREFIX.DONE} 🔍 Preflight: validating code_paths and test paths...`);
+    const result = await validatePreflightFn(id, {
+        rootDir: paths.rootDir,
+        worktreePath: paths.worktreePath,
+    });
+    if (result.valid) {
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Preflight code_paths validation passed`);
+        return {
+            valid: true,
+            errors: [],
+            missingCodePaths: [],
+            missingTestPaths: [],
+            abortedBeforeGates: false,
+        };
+    }
+    console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Preflight code_paths validation failed`);
+    return {
+        valid: false,
+        errors: result.errors,
+        missingCodePaths: result.missingCodePaths || [],
+        missingTestPaths: result.missingTestPaths || [],
+        abortedBeforeGates: true,
+    };
+}
+/**
+ * WU-1805: Build preflight code_paths error message with actionable guidance
+ */
+export function buildPreflightCodePathErrorMessage(id, result) {
+    const { errors, missingCodePaths = [], missingTestPaths = [] } = result;
+    let message = `
+❌ PREFLIGHT CODE_PATHS VALIDATION FAILED
+
+code_paths/test_paths validation found errors that would cause gates to fail.
+Aborting wu:done BEFORE running gates to save time.
+
+Errors:
+${errors.map((e) => `  ${e}`).join('\n')}
+
+`;
+    if (missingCodePaths.length > 0) {
+        message += `
+Fix options for missing code_paths:
+  1. Create the missing files in your worktree
+  2. Update code_paths in ${id}.yaml using: pnpm wu:edit --id ${id} --code-paths "<corrected-paths>"
+  3. Remove paths that were intentionally not created
+
+`;
+    }
+    if (missingTestPaths.length > 0) {
+        message += `
+Fix options for missing test_paths:
+  1. Create the missing test files
+  2. Update test paths in ${id}.yaml using wu:edit
+  3. Use tests.manual for descriptions instead of file paths
+
+`;
+    }
+    message += `
+After fixing, retry:
+  pnpm wu:done --id ${id}
+
+This preflight check runs BEFORE gates to catch YAML mismatches early.
+See: docs/04-operations/_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md for more recovery options.
+`;
+    return message;
+}
+export function runPreflightTasksValidation(id, options = {}) {
+    // Use injected execSync for testability, default to node's child_process
+    const execSyncFn = options.execSyncFn || execSyncImport;
+    console.log(`\n${LOG_PREFIX.DONE} 🔍 Preflight: running tasks:validate...`);
+    try {
+        // Run tasks:validate with WU_ID context (single-WU validation mode)
+        execSyncFn('node tools/validate.js', {
+            stdio: STDIO.PIPE,
+            encoding: 'utf-8',
+            env: { ...process.env, WU_ID: id },
+        });
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Preflight tasks:validate passed`);
+        return {
+            valid: true,
+            errors: [],
+            abortedBeforeMerge: false,
+            localMainModified: false,
+            hasStampStatusError: false,
+        };
+    }
+    catch (err) {
+        // Validation failed - extract errors from output
+        const output = err.stdout || err.message || 'Unknown validation error';
+        const errors = output
+            .split('\n')
+            .filter((line) => line.includes('[') && line.includes(']'))
+            .map((line) => line.trim());
+        const hasStampStatusError = errors.some((e) => e.includes('stamp but status is not done'));
+        console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Preflight tasks:validate failed`);
+        return {
+            valid: false,
+            errors: errors.length > 0 ? errors : [output],
+            abortedBeforeMerge: true,
+            localMainModified: false,
+            hasStampStatusError,
+        };
+    }
+}
+/**
+ * WU-2308: Validate all pre-commit hooks with worktree context
+ */
+export function validateAllPreCommitHooks(id, worktreePath = null, options = {}) {
+    const execSyncFn = options.execSyncFn || execSyncImport;
+    console.log(`\n${LOG_PREFIX.DONE} 🔍 Pre-flight: validating all pre-commit hooks...`);
+    const errors = [];
+    try {
+        // WU-2308: Run from worktree context when provided to ensure audit checks
+        // the worktree's dependencies (with fixes) not main's stale dependencies
+        const execOptions = {
+            stdio: STDIO.INHERIT,
+            encoding: 'utf-8',
+        };
+        // Only set cwd when worktreePath is provided
+        if (worktreePath) {
+            execOptions.cwd = worktreePath;
+        }
+        // Run the gates-pre-commit script that contains all validation gates
+        execSyncFn('node tools/gates-pre-commit.js', execOptions);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All pre-commit hooks passed`);
+        return { valid: true, errors: [] };
+    }
+    catch {
+        // Pre-commit hooks failed
+        errors.push('Pre-commit hook validation failed. Fix these issues before wu:done:');
+        errors.push('');
+        errors.push('Common fixes:');
+        errors.push('  • Formatting issues: Run pnpm format');
+        errors.push('  • Lint errors: Run pnpm lint:fix');
+        errors.push('  • Type errors: Check pnpm typecheck output');
+        errors.push('  • Audit issues: Check pnpm audit output');
+        errors.push('');
+        errors.push(`After fixing, re-run: pnpm wu:done --id ${id}`);
+        return { valid: false, errors };
+    }
+}

package/dist/wu-done-validation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Core validation helpers for wu:done.
+ */
+interface ExposureDefaultResult {
+    applied: boolean;
+    exposure?: string;
+}
+export declare function applyExposureDefaults(doc: any): ExposureDefaultResult;
+/**
+ * WU-1351: Validate code_paths files exist on main branch
+ *
+ * Prevents false completions by ensuring all code_paths entries
+ * actually exist on the target branch (main or lane branch).
+ *
+ * This guards against:
+ * - Stamps being created for WUs where code never merged
+ * - Metadata becoming desynchronized from actual code
+ */
+export interface ValidateCodePathsExistOptions {
+    /** Branch to check files against (default: 'main') */
+    targetBranch?: string;
+    /** Worktree path for worktree mode */
+    worktreePath?: string | null;
+}
+export declare function validateCodePathsExist(doc: any, id: any, options?: ValidateCodePathsExistOptions): Promise<{
+    valid: boolean;
+    errors: any[];
+    missing: any[];
+}>;
+/**
+ * Validate WU spec completeness (WU-1162, WU-1280)
+ *
+ * Ensures WU specifications are complete before allowing wu:done to proceed.
+ * Prevents placeholder WUs from being marked as done.
+ */
+export declare function validateSpecCompleteness(doc: any, _id: any): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * WU-1617: Post-mutation validation for wu:done
+ *
+ * Validates that metadata files written by tx.commit() are valid:
+ * 1. WU YAML has completed_at field with valid ISO datetime
+ * 2. WU YAML has locked: true
+ * 3. Stamp file exists
+ */
+export declare function validatePostMutation({ id, wuPath, stampPath }: {
+    id: any;
+    wuPath: any;
+    stampPath: any;
+}): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * WU-2242: Validate that test_paths is required for non-doc WUs
+ *
+ * Enforces that WUs with code changes (non-documentation types with code_paths
+ * that contain actual code) have at least one test path specified.
+ */
+export declare function validateTestPathsRequired(wu: any): {
+    valid: boolean;
+    error?: undefined;
+} | {
+    valid: boolean;
+    error: string;
+};
+/**
+ * WU-2310: Validate type vs code_paths at preflight (before transaction starts).
+ */
+export declare function validateTypeVsCodePathsPreflight(wu: any): {
+    valid: boolean;
+    errors: any[];
+    blockedPaths: any[];
+    abortedBeforeTransaction: boolean;
+};
+/**
+ * WU-2310: Build error message for type vs code_paths preflight failure.
+ */
+export declare function buildTypeVsCodePathsErrorMessage(id: any, blockedPaths: any): string;
+export {};