@lumenflow/cli 2.2.1 → 2.3.1

package/dist/wu-prep.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * WU Prep Helper (WU-1223)
+ *
+ * Prepares a WU for completion by running gates and generating docs in the worktree.
+ * After successful prep, prints copy-paste instruction to run wu:done from main.
+ *
+ * Workflow:
+ * 1. Verify we're in a worktree (error if in main checkout)
+ * 2. Run gates in the worktree
+ * 3. Generate docs (if applicable)
+ * 4. Print copy-paste instruction for wu:done from main
+ *
+ * Usage:
+ *   pnpm wu:prep --id WU-XXX [--docs-only]
+ *
+ * @module
+ */
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { resolveLocation } from '@lumenflow/core/dist/context/location-resolver.js';
+import { readWU } from '@lumenflow/core/dist/wu-yaml.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { CONTEXT_VALIDATION, PATTERNS, EXIT_CODES, WU_STATUS, EMOJI, } from '@lumenflow/core/dist/wu-constants.js';
+import { runGates } from './gates.js';
+const { LOCATION_TYPES } = CONTEXT_VALIDATION;
+/**
+ * Log prefix for wu:prep command output.
+ */
+const PREP_PREFIX = '[wu-prep]';
+/**
+ * GATES_OPTIONS for wu:prep command.
+ * Subset of gates options relevant for prep.
+ */
+const PREP_OPTIONS = {
+    docsOnly: {
+        name: 'docsOnly',
+        flags: '--docs-only',
+        description: 'Run docs-only gates (format, spec-linter)',
+    },
+};
+/**
+ * Print success message with copy-paste instruction.
+ */
+function printSuccessMessage(wuId, mainCheckout) {
+    console.log('');
+    console.log(`${PREP_PREFIX} ${EMOJI.SUCCESS} ${wuId}: Prep completed successfully!`);
+    console.log('');
+    console.log(`${PREP_PREFIX} Gates passed in worktree.`);
+    console.log('');
+    console.log(`${PREP_PREFIX} Next step - copy and paste this command:`);
+    console.log('');
+    console.log(`    cd ${mainCheckout} && pnpm wu:done --id ${wuId}`);
+    console.log('');
+}
+/**
+ * Main entry point.
+ */
+async function main() {
+    // Parse arguments
+    const args = createWUParser({
+        name: 'wu-prep',
+        description: 'Prepare WU for completion (run gates in worktree)',
+        options: [WU_OPTIONS.id, PREP_OPTIONS.docsOnly],
+        required: ['id'],
+        allowPositionalId: true,
+    });
+    const id = args.id.toUpperCase();
+    if (!PATTERNS.WU_ID.test(id)) {
+        die(`Invalid WU id '${args.id}'. Expected format WU-123`);
+    }
+    // Detect location
+    const location = await resolveLocation();
+    // WU-1223: wu:prep MUST be run from worktree, not main
+    if (location.type !== LOCATION_TYPES.WORKTREE) {
+        die(`${EMOJI.FAILURE} wu:prep must be run from a worktree, not ${location.type}.\n\n` +
+            `Current location: ${location.cwd}\n\n` +
+            `If you have a worktree for ${id}, navigate to it first:\n` +
+            `  cd worktrees/<lane>-${id.toLowerCase()}\n\n` +
+            `If you don't have a worktree yet, claim the WU first:\n` +
+            `  pnpm wu:claim --id ${id} --lane "<lane>"`);
+    }
+    // Verify the worktree is for the correct WU
+    if (location.worktreeWuId && location.worktreeWuId !== id) {
+        console.warn(`${PREP_PREFIX} ${EMOJI.WARNING} Worktree is for ${location.worktreeWuId}, but you specified ${id}.`);
+        console.warn(`${PREP_PREFIX} Proceeding with ${id} as specified.`);
+    }
+    // Read WU YAML to validate it exists and check status
+    const wuPath = WU_PATHS.WU(id);
+    let doc;
+    try {
+        doc = readWU(wuPath, id);
+    }
+    catch (error) {
+        die(`Failed to read WU ${id}: ${error.message}\n\n` +
+            `Options:\n` +
+            `  1. Check if WU file exists: ls -la ${wuPath}\n` +
+            `  2. Validate YAML syntax: pnpm wu:validate --id ${id}`);
+    }
+    // Validate WU status is in_progress
+    if (doc.status !== WU_STATUS.IN_PROGRESS) {
+        die(`${EMOJI.FAILURE} WU ${id} status is '${doc.status}', expected '${WU_STATUS.IN_PROGRESS}'.\n\n` +
+            `wu:prep can only be run on WUs that are in progress.`);
+    }
+    console.log(`${PREP_PREFIX} Preparing ${id} for completion...`);
+    console.log(`${PREP_PREFIX} Location: ${location.cwd}`);
+    console.log(`${PREP_PREFIX} Main checkout: ${location.mainCheckout}`);
+    console.log('');
+    // Run gates in the worktree
+    console.log(`${PREP_PREFIX} Running gates in worktree...`);
+    const gatesResult = await runGates({
+        cwd: location.cwd,
+        docsOnly: args.docsOnly,
+    });
+    if (!gatesResult) {
+        die(`${EMOJI.FAILURE} Gates failed in worktree.\n\n` +
+            `Fix the gate failures and run wu:prep again.`);
+    }
+    // Success - print copy-paste instruction
+    printSuccessMessage(id, location.mainCheckout);
+}
+main().catch((e) => {
+    console.error(e.message);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/wu-prune.js

@@ -260,9 +260,10 @@ This tool:
     }
     process.exit(totalErrors > 0 ? EXIT_CODES.ERROR : EXIT_CODES.SUCCESS);
 }
-// Guard main() for testability (WU-1366)
-import { fileURLToPath } from 'node:url';
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }

package/dist/wu-recover.js

@@ -24,9 +24,11 @@ import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 import { readWU, writeWU } from '@lumenflow/core/dist/wu-yaml.js';
 import { CONTEXT_VALIDATION, EMOJI, WU_STATUS, DEFAULTS, toKebab, } from '@lumenflow/core/dist/wu-constants.js';
 import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
-import { join } from 'node:path';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+import { join, relative } from 'node:path';
 const { RECOVERY_ACTIONS } = CONTEXT_VALIDATION;
 const LOG_PREFIX = '[wu:recover]';
+const OPERATION_NAME = 'wu-recover';
 /**
  * Valid recovery action types
  */
@@ -107,6 +109,9 @@ function getWorktreePath(wuId, lane) {
 }
 /**
  * Execute resume action - reconcile state and continue
+ *
+ * WU-1226: Uses micro-worktree isolation for all state changes.
+ * Changes are pushed via merge, not direct file modification on main.
  */
 async function executeResume(wuId) {
     console.log(`${LOG_PREFIX} Executing resume action for ${wuId}...`);
@@ -116,17 +121,46 @@ async function executeResume(wuId) {
         return false;
     }
     const doc = readWU(wuPath, wuId);
-    // Update status to in_progress if it was ready
-    if (doc.status === WU_STATUS.READY) {
-        doc.status = WU_STATUS.IN_PROGRESS;
-        writeWU(wuPath, doc);
+    // If status is already in_progress, nothing to do
+    if (doc.status !== WU_STATUS.READY) {
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Resume completed - WU already has status '${doc.status}'`);
+        return true;
+    }
+    // WU-1226: Use micro-worktree isolation for state changes
+    try {
+        await withMicroWorktree({
+            operation: OPERATION_NAME,
+            id: wuId,
+            logPrefix: LOG_PREFIX,
+            pushOnly: true, // Don't modify local main
+            execute: async ({ worktreePath }) => {
+                // Read WU in micro-worktree context
+                const microWuPath = join(worktreePath, relative(process.cwd(), wuPath));
+                const microDoc = readWU(microWuPath, wuId);
+                // Update status to in_progress
+                microDoc.status = WU_STATUS.IN_PROGRESS;
+                writeWU(microWuPath, microDoc);
+                return {
+                    commitMessage: `fix(wu-recover): resume ${wuId} - set status to in_progress`,
+                    files: [relative(process.cwd(), wuPath)],
+                };
+            },
+        });
         console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Updated ${wuId} status to in_progress`);
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Resume completed - you can continue working in the worktree`);
+        return true;
+    }
+    catch (err) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Micro-worktree operation failed: ${err.message}`);
+        return false;
     }
-    console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Resume completed - you can continue working in the worktree`);
-    return true;
 }
 /**
  * Execute reset action - discard worktree and reset to ready
+ *
+ * WU-1226: Uses micro-worktree isolation for WU YAML state changes.
+ * Worktree removal still happens directly (git operation, not file write).
+ * Changes are pushed via merge, not direct file modification on main.
  */
 async function executeReset(wuId) {
     console.log(`${LOG_PREFIX} Executing reset action for ${wuId}...`);
@@ -137,7 +171,7 @@ async function executeReset(wuId) {
     }
     const doc = readWU(wuPath, wuId);
     const worktreePath = getWorktreePath(wuId, doc.lane || '');
-    // Remove worktree if exists
+    // Remove worktree if exists (git operation, safe to do directly)
     // WU-1097: Use worktreeRemove() instead of deprecated run() with shell strings
     // This properly handles paths with spaces and special characters
     if (existsSync(worktreePath)) {
@@ -146,7 +180,7 @@ async function executeReset(wuId) {
             await git.worktreeRemove(worktreePath, { force: true });
             console.log(`${LOG_PREFIX} Removed worktree: ${worktreePath}`);
         }
-        catch (e) {
+        catch {
             // Try manual removal if git command fails
             try {
                 rmSync(worktreePath, { recursive: true, force: true });
@@ -158,14 +192,38 @@ async function executeReset(wuId) {
             }
         }
     }
-    // Reset WU status to ready
-    doc.status = WU_STATUS.READY;
-    delete doc.worktree_path;
-    delete doc.claimed_at;
-    delete doc.session_id;
-    writeWU(wuPath, doc);
-    console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Reset completed - ${wuId} is now ready for re-claiming`);
-    return true;
+    // WU-1226: Use micro-worktree isolation for WU YAML state changes
+    try {
+        await withMicroWorktree({
+            operation: OPERATION_NAME,
+            id: wuId,
+            logPrefix: LOG_PREFIX,
+            pushOnly: true, // Don't modify local main
+            execute: async ({ worktreePath: microPath }) => {
+                // Read WU in micro-worktree context
+                const microWuPath = join(microPath, relative(process.cwd(), wuPath));
+                const microDoc = readWU(microWuPath, wuId);
+                // Reset WU status to ready and clear claim fields
+                microDoc.status = WU_STATUS.READY;
+                // Use Reflect.deleteProperty to satisfy sonarjs/no-delete rule
+                Reflect.deleteProperty(microDoc, 'worktree_path');
+                Reflect.deleteProperty(microDoc, 'claimed_at');
+                Reflect.deleteProperty(microDoc, 'session_id');
+                Reflect.deleteProperty(microDoc, 'baseline_main_sha');
+                writeWU(microWuPath, microDoc);
+                return {
+                    commitMessage: `fix(wu-recover): reset ${wuId} - clear claim and set status to ready`,
+                    files: [relative(process.cwd(), wuPath)],
+                };
+            },
+        });
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Reset completed - ${wuId} is now ready for re-claiming`);
+        return true;
+    }
+    catch (err) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Micro-worktree operation failed: ${err.message}`);
+        return false;
+    }
 }
 /**
  * Execute nuke action - remove all artifacts completely
@@ -241,8 +299,15 @@ async function executeCleanup(wuId) {
 }
 /**
  * Execute recovery action
+ *
+ * WU-1226: All state-modifying actions (resume, reset) now use micro-worktree
+ * isolation. Changes are pushed via merge, not direct file modification on main.
+ *
+ * @param action - Recovery action type
+ * @param wuId - WU ID to recover
+ * @returns Promise<boolean> - true if action succeeded
  */
-async function executeAction(action, wuId) {
+export async function executeRecoveryAction(action, wuId) {
     switch (action) {
         case RECOVERY_ACTIONS.RESUME:
             return executeResume(wuId);
@@ -314,16 +379,17 @@ async function main() {
         die(`Action '${action}' requires --force flag`);
     }
     // Execute action
-    const success = await executeAction(action, id);
+    const success = await executeRecoveryAction(action, id);
     if (!success) {
         console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Recovery action failed`);
         process.exit(1);
     }
     process.exit(0);
 }
-// Guard main() for testability
-import { fileURLToPath } from 'node:url';
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }

package/dist/wu-repair.js

@@ -41,9 +41,9 @@
  *   - pnpm wu:repair-claim is deprecated. Use: pnpm wu:repair --claim
  *   - pnpm wu:admin-repair is deprecated. Use: pnpm wu:repair --admin
  *
- * @see {@link tools/lib/wu-repair-core.mjs} - Core repair logic
- * @see {@link tools/lib/wu-consistency-checker.mjs} - Consistency detection/repair
- * @see {@link tools/lib/wu-state-store.mjs} - State file repair (repairStateFile)
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-repair-core.ts} - Core repair logic
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-consistency-checker.ts} - Consistency detection/repair
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-state-store.ts} - State file repair (repairStateFile)
  */
 import { Command } from 'commander';
 import path from 'node:path';
@@ -217,10 +217,11 @@ async function main() {
     const result = await routeToRepairMode(options);
     process.exit(result.exitCode);
 }
-// Guard main() for testability (WU-1366)
-import { fileURLToPath } from 'node:url';
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// The old pattern fails with pnpm symlinks because process.argv[1] is the symlink
+// path but import.meta.url resolves to the real path - they never match
 import { runCLI } from './cli-entry-point.js';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (import.meta.main) {
     runCLI(main);
 }
 // Export for testing