@lumenflow/cli 1.5.0 → 2.0.0

package/dist/wu-recover.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+/**
+ * WU Recovery Command
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Analyzes WU state inconsistencies and offers recovery actions:
+ * - resume: Reconcile state and continue working (preserves work)
+ * - reset: Discard worktree and reset WU to ready
+ * - nuke: Remove all artifacts completely (requires --force)
+ * - cleanup: Remove leftover worktree for done WUs
+ *
+ * Usage:
+ *   pnpm wu:recover --id WU-123             # Analyze issues
+ *   pnpm wu:recover --id WU-123 --action resume  # Apply fix
+ *   pnpm wu:recover --id WU-123 --action nuke --force  # Destructive
+ */
+import { existsSync, rmSync } from 'node:fs';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { computeContext } from '@lumenflow/core/dist/context/index.js';
+import { analyzeRecovery, } from '@lumenflow/core/dist/recovery/recovery-analyzer.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+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';
+const { RECOVERY_ACTIONS } = CONTEXT_VALIDATION;
+const LOG_PREFIX = '[wu:recover]';
+/**
+ * Valid recovery action types
+ */
+const VALID_ACTIONS = [
+    RECOVERY_ACTIONS.RESUME,
+    RECOVERY_ACTIONS.RESET,
+    RECOVERY_ACTIONS.NUKE,
+    RECOVERY_ACTIONS.CLEANUP,
+];
+/**
+ * Check if action requires --force flag
+ */
+export function requiresForceFlag(action) {
+    return action === RECOVERY_ACTIONS.NUKE;
+}
+/**
+ * Validate recovery action
+ */
+export function validateRecoveryAction(action) {
+    if (VALID_ACTIONS.includes(action)) {
+        return { valid: true };
+    }
+    return {
+        valid: false,
+        error: `Invalid action '${action}'. Valid actions: ${VALID_ACTIONS.join(', ')}`,
+    };
+}
+/**
+ * Format recovery analysis output
+ */
+export function formatRecoveryOutput(analysis) {
+    const lines = [];
+    lines.push(`## Recovery Analysis for ${analysis.wuId || 'unknown'}`);
+    lines.push('');
+    if (!analysis.hasIssues) {
+        lines.push(`${EMOJI.SUCCESS} No issues found - WU state is healthy`);
+        return lines.join('\n');
+    }
+    // Issues section
+    lines.push('### Issues Detected');
+    for (const issue of analysis.issues) {
+        lines.push(`  ${EMOJI.FAILURE} ${issue.code}: ${issue.description}`);
+    }
+    lines.push('');
+    // Actions section
+    if (analysis.actions.length > 0) {
+        lines.push('### Available Recovery Actions');
+        for (const action of analysis.actions) {
+            lines.push(`  **${action.type}**: ${action.description}`);
+            lines.push(`    Command: ${action.command}`);
+            if (action.warning) {
+                lines.push(`    ${EMOJI.WARNING} Warning: ${action.warning}`);
+            }
+            if (action.requiresForce) {
+                lines.push(`    Requires: --force flag`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Get exit code for recovery command
+ */
+export function getRecoveryExitCode(analysis, actionFailed) {
+    if (actionFailed) {
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Get expected worktree path for a WU
+ */
+function getWorktreePath(wuId, lane) {
+    const laneKebab = toKebab(lane);
+    const wuIdLower = wuId.toLowerCase();
+    return join(process.cwd(), DEFAULTS.WORKTREES_DIR, `${laneKebab}-${wuIdLower}`);
+}
+/**
+ * Execute resume action - reconcile state and continue
+ */
+async function executeResume(wuId) {
+    console.log(`${LOG_PREFIX} Executing resume action for ${wuId}...`);
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} WU file not found: ${wuPath}`);
+        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);
+        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;
+}
+/**
+ * Execute reset action - discard worktree and reset to ready
+ */
+async function executeReset(wuId) {
+    console.log(`${LOG_PREFIX} Executing reset action for ${wuId}...`);
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} WU file not found: ${wuPath}`);
+        return false;
+    }
+    const doc = readWU(wuPath, wuId);
+    const worktreePath = getWorktreePath(wuId, doc.lane || '');
+    // Remove worktree if exists
+    // WU-1097: Use worktreeRemove() instead of deprecated run() with shell strings
+    // This properly handles paths with spaces and special characters
+    if (existsSync(worktreePath)) {
+        try {
+            const git = getGitForCwd();
+            await git.worktreeRemove(worktreePath, { force: true });
+            console.log(`${LOG_PREFIX} Removed worktree: ${worktreePath}`);
+        }
+        catch (e) {
+            // Try manual removal if git command fails
+            try {
+                rmSync(worktreePath, { recursive: true, force: true });
+                console.log(`${LOG_PREFIX} Manually removed worktree directory: ${worktreePath}`);
+            }
+            catch (rmError) {
+                console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Failed to remove worktree: ${rmError.message}`);
+                return false;
+            }
+        }
+    }
+    // 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;
+}
+/**
+ * Execute nuke action - remove all artifacts completely
+ */
+async function executeNuke(wuId) {
+    console.log(`${LOG_PREFIX} Executing nuke action for ${wuId}...`);
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        console.log(`${LOG_PREFIX} WU file does not exist: ${wuPath}`);
+    }
+    else {
+        const doc = readWU(wuPath, wuId);
+        const worktreePath = getWorktreePath(wuId, doc.lane || '');
+        // Remove worktree if exists
+        // WU-1097: Use worktreeRemove() instead of deprecated run() with shell strings
+        if (existsSync(worktreePath)) {
+            try {
+                const git = getGitForCwd();
+                await git.worktreeRemove(worktreePath, { force: true });
+            }
+            catch {
+                rmSync(worktreePath, { recursive: true, force: true });
+            }
+            console.log(`${LOG_PREFIX} Removed worktree: ${worktreePath}`);
+        }
+        // Try to delete branch
+        // WU-1097: Use deleteBranch() instead of deprecated run() with shell strings
+        try {
+            const git = getGitForCwd();
+            const laneKebab = toKebab(doc.lane || '');
+            const branchName = `lane/${laneKebab}/${wuId.toLowerCase()}`;
+            await git.deleteBranch(branchName, { force: true });
+            console.log(`${LOG_PREFIX} Deleted branch: ${branchName}`);
+        }
+        catch {
+            // Branch may not exist, that's fine
+        }
+    }
+    console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Nuke completed - all artifacts removed for ${wuId}`);
+    return true;
+}
+/**
+ * Execute cleanup action - remove leftover worktree for done WUs
+ */
+async function executeCleanup(wuId) {
+    console.log(`${LOG_PREFIX} Executing cleanup action for ${wuId}...`);
+    const wuPath = WU_PATHS.WU(wuId);
+    if (!existsSync(wuPath)) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} WU file not found: ${wuPath}`);
+        return false;
+    }
+    const doc = readWU(wuPath, wuId);
+    if (doc.status !== WU_STATUS.DONE) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Cannot cleanup: WU status is '${doc.status}', expected 'done'`);
+        return false;
+    }
+    const worktreePath = getWorktreePath(wuId, doc.lane || '');
+    if (!existsSync(worktreePath)) {
+        console.log(`${LOG_PREFIX} Worktree does not exist, nothing to cleanup`);
+        return true;
+    }
+    // WU-1097: Use worktreeRemove() instead of deprecated run() with shell strings
+    try {
+        const git = getGitForCwd();
+        await git.worktreeRemove(worktreePath, { force: true });
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Removed leftover worktree: ${worktreePath}`);
+    }
+    catch (e) {
+        rmSync(worktreePath, { recursive: true, force: true });
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Manually removed leftover worktree: ${worktreePath}`);
+    }
+    return true;
+}
+/**
+ * Execute recovery action
+ */
+async function executeAction(action, wuId) {
+    switch (action) {
+        case RECOVERY_ACTIONS.RESUME:
+            return executeResume(wuId);
+        case RECOVERY_ACTIONS.RESET:
+            return executeReset(wuId);
+        case RECOVERY_ACTIONS.NUKE:
+            return executeNuke(wuId);
+        case RECOVERY_ACTIONS.CLEANUP:
+            return executeCleanup(wuId);
+        default:
+            console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Unknown action: ${action}`);
+            return false;
+    }
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    const args = createWUParser({
+        name: 'wu-recover',
+        description: 'Analyze and fix WU state inconsistencies (WU-1090)',
+        options: [
+            WU_OPTIONS.id,
+            {
+                name: 'action',
+                flags: '-a, --action <action>',
+                type: 'string',
+                description: 'Recovery action: resume, reset, nuke, cleanup',
+            },
+            {
+                name: 'force',
+                flags: '-f, --force',
+                type: 'boolean',
+                description: 'Required for destructive actions (nuke)',
+            },
+            {
+                name: 'json',
+                flags: '-j, --json',
+                type: 'boolean',
+                description: 'Output as JSON',
+            },
+        ],
+        required: ['id'],
+        allowPositionalId: true,
+    });
+    const { id, action, force, json } = args;
+    // Compute context for the WU
+    const { context } = await computeContext({ wuId: id });
+    // Analyze recovery issues
+    const analysis = await analyzeRecovery(context);
+    // If no action specified, just show analysis
+    if (!action) {
+        if (json) {
+            console.log(JSON.stringify(analysis, null, 2));
+        }
+        else {
+            console.log(formatRecoveryOutput(analysis));
+        }
+        process.exit(getRecoveryExitCode(analysis, false));
+        return;
+    }
+    // Validate action
+    const validation = validateRecoveryAction(action);
+    if (!validation.valid) {
+        die(validation.error);
+    }
+    // Check force flag for destructive actions
+    if (requiresForceFlag(action) && !force) {
+        die(`Action '${action}' requires --force flag`);
+    }
+    // Execute action
+    const success = await executeAction(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';
+import { runCLI } from './cli-entry-point.js';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    runCLI(main);
+}

package/dist/wu-status.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * WU Status Command
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Shows:
+ * - Current location (main checkout vs worktree)
+ * - WU state if in worktree or --id provided
+ * - Git state (branch, dirty, ahead/behind)
+ * - Valid commands for current context
+ *
+ * Usage:
+ *   pnpm wu:status              # Auto-detect from current directory
+ *   pnpm wu:status --id WU-123  # Show status for specific WU
+ */
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { computeContext } from '@lumenflow/core/dist/context/index.js';
+import { getValidCommandsForContext } from '@lumenflow/core/dist/validation/command-registry.js';
+import { CONTEXT_VALIDATION, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
+const { LOCATION_TYPES } = CONTEXT_VALIDATION;
+const LOG_PREFIX = '[wu:status]';
+/**
+ * Format location type for display
+ */
+function formatLocationType(type) {
+    switch (type) {
+        case LOCATION_TYPES.MAIN:
+            return 'main checkout';
+        case LOCATION_TYPES.WORKTREE:
+            return 'worktree';
+        case LOCATION_TYPES.DETACHED:
+            return 'detached HEAD';
+        default:
+            return 'unknown location';
+    }
+}
+/**
+ * Format git state for display
+ */
+function formatGitState(context) {
+    const lines = [];
+    const { git } = context;
+    if (git.hasError) {
+        lines.push(`  ${EMOJI.FAILURE} Git error: ${git.errorMessage}`);
+        return lines;
+    }
+    const branchInfo = git.branch || '(detached)';
+    lines.push(`  Branch: ${branchInfo}`);
+    if (git.isDirty) {
+        lines.push(`  ${EMOJI.WARNING} Working tree: dirty (${git.modifiedFiles.length} files)`);
+    }
+    else {
+        lines.push(`  ${EMOJI.SUCCESS} Working tree: clean`);
+    }
+    if (git.hasStaged) {
+        lines.push(`  Staged: yes`);
+    }
+    if (git.ahead > 0 || git.behind > 0) {
+        const parts = [];
+        if (git.ahead > 0)
+            parts.push(`${git.ahead} ahead`);
+        if (git.behind > 0)
+            parts.push(`${git.behind} behind`);
+        lines.push(`  Tracking: ${parts.join(', ')}`);
+    }
+    return lines;
+}
+/**
+ * Format WU state for display
+ */
+function formatWuState(context) {
+    const lines = [];
+    const { wu } = context;
+    if (!wu) {
+        lines.push(`  No WU context`);
+        return lines;
+    }
+    lines.push(`  ID: ${wu.id}`);
+    lines.push(`  Title: ${wu.title}`);
+    lines.push(`  Lane: ${wu.lane}`);
+    lines.push(`  Status: ${wu.status}`);
+    if (!wu.isConsistent) {
+        lines.push(`  ${EMOJI.WARNING} State inconsistency: ${wu.inconsistencyReason}`);
+    }
+    return lines;
+}
+/**
+ * Format valid commands for display
+ */
+function formatValidCommands(context) {
+    const lines = [];
+    const validCommands = getValidCommandsForContext(context);
+    if (validCommands.length === 0) {
+        lines.push(`  No commands available for current context`);
+        return lines;
+    }
+    for (const cmd of validCommands) {
+        lines.push(`  ${cmd.name} - ${cmd.description}`);
+    }
+    return lines;
+}
+/**
+ * Format complete status output
+ */
+export function formatStatusOutput(context) {
+    const lines = [];
+    // Location section
+    lines.push('## Location');
+    lines.push(`  Type: ${formatLocationType(context.location.type)}`);
+    lines.push(`  Path: ${context.location.cwd}`);
+    if (context.location.worktreeName) {
+        lines.push(`  Worktree: ${context.location.worktreeName}`);
+    }
+    if (context.location.worktreeWuId) {
+        lines.push(`  WU ID: ${context.location.worktreeWuId}`);
+    }
+    lines.push('');
+    // Git section
+    lines.push('## Git State');
+    lines.push(...formatGitState(context));
+    lines.push('');
+    // WU section
+    lines.push('## WU State');
+    lines.push(...formatWuState(context));
+    lines.push('');
+    // Valid commands section
+    lines.push('## Valid Commands');
+    lines.push(...formatValidCommands(context));
+    return lines.join('\n');
+}
+/**
+ * Get exit code based on context state
+ */
+export function getStatusExitCode(context) {
+    // Error if git has errors
+    if (context.git.hasError) {
+        return 1;
+    }
+    // Error if location is unknown
+    if (context.location.type === LOCATION_TYPES.UNKNOWN) {
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    const args = createWUParser({
+        name: 'wu-status',
+        description: 'Show WU status, location, and valid commands (WU-1090)',
+        options: [
+            { ...WU_OPTIONS.id, required: false },
+            {
+                name: 'json',
+                flags: '-j, --json',
+                type: 'boolean',
+                description: 'Output as JSON',
+            },
+        ],
+        required: [],
+        allowPositionalId: true,
+    });
+    const { id, json } = args;
+    // Compute context
+    const { context, computationMs, exceededBudget } = await computeContext({
+        wuId: id,
+    });
+    if (exceededBudget) {
+        console.warn(`${LOG_PREFIX} ${EMOJI.WARNING} Context computation took ${computationMs.toFixed(0)}ms (exceeded 100ms budget)`);
+    }
+    // Output
+    if (json) {
+        console.log(JSON.stringify(context, null, 2));
+    }
+    else {
+        console.log(formatStatusOutput(context));
+    }
+    // Exit with appropriate code
+    process.exit(getStatusExitCode(context));
+}
+// Guard main() for testability
+import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    runCLI(main);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -51,6 +51,8 @@
     "wu-delete": "./dist/wu-delete.js",
     "wu-unlock-lane": "./dist/wu-unlock-lane.js",
     "wu-release": "./dist/wu-release.js",
+    "wu-status": "./dist/wu-status.js",
+    "wu-recover": "./dist/wu-recover.js",
     "mem-init": "./dist/mem-init.js",
     "mem-checkpoint": "./dist/mem-checkpoint.js",
     "mem-start": "./dist/mem-start.js",
@@ -66,6 +68,7 @@
     "initiative-list": "./dist/initiative-list.js",
     "initiative-status": "./dist/initiative-status.js",
     "initiative-add-wu": "./dist/initiative-add-wu.js",
+    "init-plan": "./dist/init-plan.js",
     "agent-session": "./dist/agent-session.js",
     "agent-session-end": "./dist/agent-session-end.js",
     "agent-log-issue": "./dist/agent-log-issue.js",
@@ -76,6 +79,8 @@
     "flow-report": "./dist/flow-report.js",
     "flow-bottlenecks": "./dist/flow-bottlenecks.js",
     "metrics-snapshot": "./dist/metrics-snapshot.js",
+    "metrics": "./dist/metrics-cli.js",
+    "lumenflow-metrics": "./dist/metrics-cli.js",
     "initiative-bulk-assign-wus": "./dist/initiative-bulk-assign-wus.js",
     "agent-issues-query": "./dist/agent-issues-query.js",
     "gates": "./dist/gates.js",
@@ -83,7 +88,32 @@
     "lumenflow-init": "./dist/init.js",
     "lumenflow": "./dist/init.js",
     "lumenflow-release": "./dist/release.js",
-    "lumenflow-docs-sync": "./dist/docs-sync.js"
+    "lumenflow-docs-sync": "./dist/docs-sync.js",
+    "backlog-prune": "./dist/backlog-prune.js",
+    "file-read": "./dist/file-read.js",
+    "file-write": "./dist/file-write.js",
+    "file-edit": "./dist/file-edit.js",
+    "file-delete": "./dist/file-delete.js",
+    "guard-worktree-commit": "./dist/guard-worktree-commit.js",
+    "guard-locked": "./dist/guard-locked.js",
+    "validate": "./dist/validate.js",
+    "lumenflow-validate": "./dist/validate.js",
+    "validate-agent-skills": "./dist/validate-agent-skills.js",
+    "validate-agent-sync": "./dist/validate-agent-sync.js",
+    "validate-backlog-sync": "./dist/validate-backlog-sync.js",
+    "validate-skills-spec": "./dist/validate-skills-spec.js",
+    "deps-add": "./dist/deps-add.js",
+    "deps-remove": "./dist/deps-remove.js",
+    "session-coordinator": "./dist/session-coordinator.js",
+    "rotate-progress": "./dist/rotate-progress.js",
+    "lumenflow-upgrade": "./dist/lumenflow-upgrade.js",
+    "trace-gen": "./dist/trace-gen.js",
+    "git-status": "./dist/git-status.js",
+    "git-diff": "./dist/git-diff.js",
+    "git-log": "./dist/git-log.js",
+    "git-branch": "./dist/git-branch.js",
+    "guard-main-branch": "./dist/guard-main-branch.js",
+    "state-bootstrap": "./dist/state-bootstrap.js"
   },
   "files": [
     "dist",
@@ -100,11 +130,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "1.5.0",
-    "@lumenflow/initiatives": "1.5.0",
-    "@lumenflow/memory": "1.5.0",
-    "@lumenflow/agent": "1.5.0",
-    "@lumenflow/metrics": "1.5.0"
+    "@lumenflow/memory": "2.0.0",
+    "@lumenflow/metrics": "1.6.0",
+    "@lumenflow/core": "2.0.0",
+    "@lumenflow/initiatives": "2.0.0",
+    "@lumenflow/agent": "2.0.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",