@lumenflow/cli 2.8.0 → 2.10.0

package/dist/doctor.js

@@ -2,6 +2,7 @@
  * @file doctor.ts
  * LumenFlow health check command (WU-1177)
  * WU-1191: Lane health check integration
+ * WU-1386: Agent-friction checks (managed-file dirty, WU validity, worktree sanity)
  * Verifies all safety components are installed and configured correctly
  */
 import * as fs from 'node:fs';
@@ -9,8 +10,20 @@ import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { createWUParser } from '@lumenflow/core';
 import { loadLaneDefinitions, detectLaneOverlaps } from './lane-health.js';
+/**
+ * WU-1386: Managed files that should not have uncommitted changes
+ */
+const MANAGED_FILE_PATTERNS = [
+    '.lumenflow.config.yaml',
+    '.lumenflow.lane-inference.yaml',
+    'AGENTS.md',
+    'CLAUDE.md',
+];
+/** WU-1386: Managed directories with glob patterns */
+const MANAGED_DIR_PATTERNS = ['docs/04-operations/tasks/'];
 /**
  * CLI option definitions for doctor command
+ * WU-1386: Added --deep flag
  */
 const DOCTOR_OPTIONS = {
     verbose: {
@@ -23,9 +36,15 @@ const DOCTOR_OPTIONS = {
         flags: '--json',
         description: 'Output results as JSON',
     },
+    deep: {
+        name: 'deep',
+        flags: '--deep',
+        description: 'Run heavier checks including WU validation (slower)',
+    },
 };
 /**
  * Parse doctor command options
+ * WU-1386: Added deep flag
  */
 export function parseDoctorOptions() {
     const opts = createWUParser({
@@ -36,6 +55,7 @@ export function parseDoctorOptions() {
     return {
         verbose: opts.verbose ?? false,
         json: opts.json ?? false,
+        deep: opts.deep ?? false,
     };
 }
 /**
@@ -252,10 +272,314 @@ function checkPrerequisites() {
         },
     };
 }
+/**
+ * WU-1387: Get git repository root directory
+ * This ensures managed-file detection works from subdirectories
+ */
+function getGitRepoRoot(projectDir) {
+    try {
+        const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: projectDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return repoRoot;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * WU-1386: Check for uncommitted changes to managed files
+ * WU-1387: Uses git repo root for path resolution (works from subdirectories)
+ */
+async function checkManagedFilesDirty(projectDir) {
+    try {
+        // WU-1387: Get git repo root to handle subdirectory execution
+        const repoRoot = getGitRepoRoot(projectDir);
+        if (!repoRoot) {
+            return {
+                passed: true,
+                files: [],
+                message: 'Git status check skipped (not a git repository)',
+            };
+        }
+        // Run git status from repo root, not the passed projectDir
+        const statusOutput = execFileSync('git', ['status', '--porcelain'], {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const dirtyFiles = [];
+        // Parse status output and check each line
+        const lines = statusOutput.split('\n').filter((line) => line.trim());
+        for (const line of lines) {
+            // Status format: XY filename (where XY is 2-char status)
+            const filePath = line.slice(3).trim();
+            if (!filePath)
+                continue;
+            // Check if file matches managed patterns
+            const isManaged = MANAGED_FILE_PATTERNS.some((pattern) => filePath === pattern) ||
+                MANAGED_DIR_PATTERNS.some((dir) => filePath.startsWith(dir));
+            if (isManaged) {
+                dirtyFiles.push(filePath);
+            }
+        }
+        if (dirtyFiles.length > 0) {
+            return {
+                passed: false,
+                files: dirtyFiles,
+                message: `${dirtyFiles.length} managed file(s) have uncommitted changes`,
+            };
+        }
+        return {
+            passed: true,
+            files: [],
+            message: 'No uncommitted changes to managed files',
+        };
+    }
+    catch {
+        // Not a git repo or git not available - graceful degradation
+        return {
+            passed: true,
+            files: [],
+            message: 'Git status check skipped (not a git repository)',
+        };
+    }
+}
+function parseWorktreePruneOutput(output) {
+    // Parse summary line for orphan directories: "Orphan directories: N"
+    const orphanSummaryMatch = output.match(/Orphan directories:\s*(\d+)/);
+    const orphansFromSummary = orphanSummaryMatch ? parseInt(orphanSummaryMatch[1], 10) : 0;
+    // Also count "orphan director" mentions (the detailed output)
+    const orphanDetailMatches = output.match(/orphan director/gi) || [];
+    const orphansFromDetail = orphanDetailMatches.length;
+    // Use the higher count (summary is authoritative, but detail catches other mentions)
+    const orphans = Math.max(orphansFromSummary, orphansFromDetail > 0 ? 1 : 0);
+    // Parse specific worktree warnings from wu:prune output
+    // These appear as "Stale worktree:", "Blocked worktree:", "Unclaimed worktree:"
+    const staleCount = (output.match(/Stale worktree:/gi) || []).length;
+    const blockedCount = (output.match(/Blocked worktree:/gi) || []).length;
+    const unclaimedCount = (output.match(/Unclaimed worktree:/gi) || []).length;
+    // Parse missing tracked worktrees: "Missing tracked worktree" header
+    const missingMatch = output.match(/Missing tracked worktree/gi) || [];
+    const missingCount = missingMatch.length > 0 ? 1 : 0; // At least one if header present
+    // Also count specific missing path lines
+    const missingPathMatches = output.match(/worktrees \(tracked by git but directory missing\)/gi);
+    const missingFromDetail = missingPathMatches ? missingPathMatches.length : 0;
+    // Parse summary warnings and errors
+    const warningSummaryMatch = output.match(/Warnings:\s*(\d+)/);
+    const warnings = warningSummaryMatch ? parseInt(warningSummaryMatch[1], 10) : 0;
+    const errorSummaryMatch = output.match(/Errors:\s*(\d+)/);
+    const errors = errorSummaryMatch ? parseInt(errorSummaryMatch[1], 10) : 0;
+    return {
+        orphans,
+        stale: staleCount,
+        blocked: blockedCount,
+        unclaimed: unclaimedCount,
+        missing: Math.max(missingCount, missingFromDetail),
+        warnings,
+        errors,
+    };
+}
+/**
+ * WU-1386: Check worktree sanity by calling wu:prune in dry-run mode
+ * WU-1387: Enhanced parsing for orphan, missing, stale, blocked, and unclaimed worktrees
+ */
+async function checkWorktreeSanity(projectDir) {
+    try {
+        // First check if this is a git repo
+        execFileSync('git', ['rev-parse', '--git-dir'], {
+            cwd: projectDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Call wu:prune in dry-run mode (default) via pnpm
+        // Capture both stdout and stderr to parse the output
+        let pruneOutput;
+        let commandFailed = false;
+        try {
+            pruneOutput = execFileSync('pnpm', ['wu:prune'], {
+                cwd: projectDir,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 30000, // 30 second timeout
+            });
+        }
+        catch (e) {
+            const execError = e;
+            pruneOutput = (execError.stdout || '') + (execError.stderr || '');
+            // Check if this is a "command not found" type error vs wu:prune finding issues
+            // If pnpm can't run the script (no package.json, script not defined, etc.), gracefully skip
+            const errorMsg = execError.message || pruneOutput || '';
+            if (errorMsg.includes('ERR_PNPM') ||
+                errorMsg.includes('ENOENT') ||
+                errorMsg.includes('Missing script') ||
+                errorMsg.includes('command not found') ||
+                !pruneOutput.includes('[wu-prune]')) {
+                // Command couldn't run - gracefully skip
+                return {
+                    passed: true,
+                    orphans: 0,
+                    stale: 0,
+                    message: 'Worktree check skipped (wu:prune not available)',
+                };
+            }
+            // Otherwise, wu:prune ran but found issues (non-zero exit)
+            commandFailed = true;
+        }
+        // WU-1387: Enhanced parsing for all worktree issue types
+        const parsed = parseWorktreePruneOutput(pruneOutput);
+        // Calculate total issues (orphans count as issues, plus stale, blocked, unclaimed, missing)
+        const totalIssues = parsed.orphans + parsed.stale + parsed.blocked + parsed.unclaimed + parsed.missing;
+        const hasIssues = totalIssues > 0 || parsed.warnings > 0 || parsed.errors > 0;
+        const passed = !hasIssues && !commandFailed;
+        // Build descriptive message
+        let message = 'All worktrees are valid';
+        if (!passed) {
+            const parts = [];
+            if (parsed.orphans > 0)
+                parts.push(`${parsed.orphans} orphan(s)`);
+            if (parsed.missing > 0)
+                parts.push(`${parsed.missing} missing`);
+            if (parsed.stale > 0)
+                parts.push(`${parsed.stale} stale`);
+            if (parsed.blocked > 0)
+                parts.push(`${parsed.blocked} blocked`);
+            if (parsed.unclaimed > 0)
+                parts.push(`${parsed.unclaimed} unclaimed`);
+            if (parts.length === 0 && (parsed.warnings > 0 || parsed.errors > 0)) {
+                parts.push(`${parsed.warnings} warning(s), ${parsed.errors} error(s)`);
+            }
+            message = parts.length > 0 ? `Worktree issues: ${parts.join(', ')}` : 'Worktree issues found';
+        }
+        return {
+            passed,
+            orphans: parsed.orphans,
+            stale: parsed.stale + parsed.blocked + parsed.unclaimed + parsed.missing, // Combined for API compat
+            message,
+        };
+    }
+    catch {
+        // Not a git repo or git not available
+        return {
+            passed: true,
+            orphans: 0,
+            stale: 0,
+            message: 'Worktree check skipped (not a git repository)',
+        };
+    }
+}
+/**
+ * WU-1386: Run WU validation (--deep mode only)
+ * WU-1387: Sets passed=false with clear message when CLI fails to run
+ * Calls wu:validate --all --no-strict for full schema/lint validation in warn-only mode
+ */
+async function checkWUValidity(projectDir) {
+    const wuDir = path.join(projectDir, 'docs', '04-operations', 'tasks', 'wu');
+    if (!fs.existsSync(wuDir)) {
+        return {
+            passed: true,
+            total: 0,
+            valid: 0,
+            invalid: 0,
+            warnings: 0,
+            message: 'No WU directory found',
+        };
+    }
+    try {
+        // Call wu:validate --all --no-strict to get warn-only validation
+        // This runs the full schema + lint validation, treating warnings as advisory
+        let validateOutput;
+        let cliError = false;
+        let cliErrorMessage = '';
+        try {
+            validateOutput = execFileSync('pnpm', ['wu:validate', '--all', '--no-strict'], {
+                cwd: projectDir,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 60000, // 60 second timeout for full validation
+            });
+        }
+        catch (e) {
+            // wu:validate exits non-zero if validation fails
+            const execError = e;
+            validateOutput = (execError.stdout || '') + (execError.stderr || '');
+            const errorMsg = execError.message || '';
+            // WU-1387: Distinguish between CLI execution failure and validation failure
+            // CLI failure = script missing, command not found, ENOENT
+            // Validation failure = script ran but found invalid WUs
+            if (errorMsg.includes('ERR_PNPM') ||
+                errorMsg.includes('ENOENT') ||
+                errorMsg.includes('Missing script') ||
+                errorMsg.includes('command not found') ||
+                execError.code === 'ENOENT' ||
+                // If no recognizable wu:validate output, assume CLI failed
+                (!validateOutput.includes('[wu:validate]') && !validateOutput.includes('Valid:'))) {
+                cliError = true;
+                cliErrorMessage = errorMsg.includes('Missing script')
+                    ? 'wu:validate script not found'
+                    : errorMsg.includes('ENOENT')
+                        ? 'pnpm command not available'
+                        : 'wu:validate could not run';
+            }
+        }
+        // WU-1387: If CLI failed to run, report as failure with clear message
+        if (cliError) {
+            return {
+                passed: false,
+                total: 0,
+                valid: 0,
+                invalid: 0,
+                warnings: 0,
+                message: `WU validation failed: ${cliErrorMessage}`,
+            };
+        }
+        // Parse output for counts
+        // wu:validate outputs summary like:
+        //   ✓ Valid: N
+        //   ✗ Invalid: N
+        //   ⚠ Warnings: N
+        const validMatch = validateOutput.match(/Valid:\s*(\d+)/);
+        const invalidMatch = validateOutput.match(/Invalid:\s*(\d+)/);
+        const warningMatch = validateOutput.match(/Warnings:\s*(\d+)/);
+        const validCount = validMatch ? parseInt(validMatch[1], 10) : 0;
+        const invalidCount = invalidMatch ? parseInt(invalidMatch[1], 10) : 0;
+        const warningCount = warningMatch ? parseInt(warningMatch[1], 10) : 0;
+        const total = validCount + invalidCount;
+        // In warn-only mode (--no-strict), we only fail on actual invalid WUs
+        const passed = invalidCount === 0;
+        return {
+            passed,
+            total,
+            valid: validCount,
+            invalid: invalidCount,
+            warnings: warningCount,
+            message: passed
+                ? total > 0
+                    ? `All ${total} WU(s) valid${warningCount > 0 ? ` (${warningCount} warning(s))` : ''}`
+                    : 'No WUs to validate'
+                : `${invalidCount}/${total} WU(s) have issues`,
+        };
+    }
+    catch (e) {
+        // WU-1387: Unexpected errors should report failure, not silently pass
+        const error = e;
+        return {
+            passed: false,
+            total: 0,
+            valid: 0,
+            invalid: 0,
+            warnings: 0,
+            message: `WU validation failed: ${error.message || 'unknown error'}`,
+        };
+    }
+}
 /**
  * Run all doctor checks
+ * WU-1386: Added options parameter for --deep flag
  */
-export async function runDoctor(projectDir) {
+export async function runDoctor(projectDir, options = {}) {
     const checks = {
         husky: checkHusky(projectDir),
         safeGit: checkSafeGit(projectDir),
@@ -266,19 +590,137 @@ export async function runDoctor(projectDir) {
     };
     const vendorConfigs = checkVendorConfigs(projectDir);
     const prerequisites = checkPrerequisites();
+    // WU-1386: Workflow health checks
+    const managedFilesDirty = await checkManagedFilesDirty(projectDir);
+    const worktreeSanity = await checkWorktreeSanity(projectDir);
+    const workflowHealth = {
+        managedFilesDirty,
+        worktreeSanity,
+    };
+    // WU-1386: WU validity check only in --deep mode
+    if (options.deep) {
+        workflowHealth.wuValidity = await checkWUValidity(projectDir);
+    }
     // Determine overall status
     // Note: laneHealth is advisory (not included in critical checks)
     const criticalChecks = [checks.husky, checks.safeGit, checks.agentsMd];
     const allCriticalPassed = criticalChecks.every((check) => check.passed);
+    // WU-1386: Calculate exit code
+    // 0 = healthy (all checks pass, no warnings)
+    // 1 = warnings (non-critical issues)
+    // 2 = errors (critical safety checks failed)
+    let exitCode = 0;
+    if (!allCriticalPassed) {
+        exitCode = 2;
+    }
+    else if (!managedFilesDirty.passed ||
+        !worktreeSanity.passed ||
+        (workflowHealth.wuValidity && !workflowHealth.wuValidity.passed)) {
+        exitCode = 1;
+    }
     return {
         status: allCriticalPassed ? 'ACTIVE' : 'INCOMPLETE',
+        exitCode,
         checks,
         vendorConfigs,
         prerequisites,
+        workflowHealth,
+    };
+}
+/**
+ * WU-1386: Run doctor for init (non-blocking, warnings only)
+ * WU-1387: Shows accurate status including lane health and prerequisite failures
+ * This is used after lumenflow init to provide feedback without blocking
+ */
+export async function runDoctorForInit(projectDir) {
+    const result = await runDoctor(projectDir, { deep: false });
+    // Count warnings and errors using check keys, not messages
+    let warnings = 0;
+    let errors = 0;
+    // Critical checks that count as errors (if they fail, safety is compromised)
+    const criticalCheckKeys = ['husky', 'safeGit', 'agentsMd'];
+    for (const [key, check] of Object.entries(result.checks)) {
+        if (!check.passed) {
+            if (criticalCheckKeys.includes(key)) {
+                errors++;
+            }
+            else {
+                warnings++;
+            }
+        }
+    }
+    // WU-1387: Count prerequisite failures as warnings
+    for (const [, prereq] of Object.entries(result.prerequisites)) {
+        if (!prereq.passed) {
+            warnings++;
+        }
+    }
+    // Count workflow health issues as warnings (not errors)
+    if (result.workflowHealth) {
+        if (!result.workflowHealth.managedFilesDirty.passed)
+            warnings++;
+        if (!result.workflowHealth.worktreeSanity.passed)
+            warnings++;
+    }
+    // Format concise output
+    const lines = [];
+    lines.push('[lumenflow doctor] Quick health check...');
+    if (result.exitCode === 0 && warnings === 0) {
+        lines.push('  All checks passed');
+    }
+    else {
+        // Show critical errors first
+        if (!result.checks.husky.passed) {
+            lines.push('  Error: Husky hooks not installed');
+        }
+        if (!result.checks.safeGit.passed) {
+            lines.push('  Error: safe-git script not found');
+        }
+        if (!result.checks.agentsMd.passed) {
+            lines.push('  Error: AGENTS.md not found');
+        }
+        // WU-1387: Show lane health issues
+        if (!result.checks.laneHealth.passed) {
+            lines.push(`  Warning: Lane overlap detected - ${result.checks.laneHealth.message}`);
+        }
+        // WU-1387: Show prerequisite failures
+        if (!result.prerequisites.node.passed) {
+            lines.push(`  Warning: Node.js version ${result.prerequisites.node.version} (required: ${result.prerequisites.node.required})`);
+        }
+        if (!result.prerequisites.pnpm.passed) {
+            lines.push(`  Warning: pnpm version ${result.prerequisites.pnpm.version} (required: ${result.prerequisites.pnpm.required})`);
+        }
+        if (!result.prerequisites.git.passed) {
+            lines.push(`  Warning: Git version ${result.prerequisites.git.version} (required: ${result.prerequisites.git.required})`);
+        }
+        // Workflow health warnings
+        if (result.workflowHealth?.managedFilesDirty.files.length) {
+            lines.push(`  Warning: ${result.workflowHealth.managedFilesDirty.files.length} managed file(s) have uncommitted changes`);
+            for (const file of result.workflowHealth.managedFilesDirty.files.slice(0, 3)) {
+                lines.push(`    -> ${file}`);
+            }
+        }
+        if (result.workflowHealth?.worktreeSanity.orphans) {
+            lines.push(`  Warning: ${result.workflowHealth.worktreeSanity.orphans} orphan worktree(s) found`);
+        }
+        if (result.workflowHealth && !result.workflowHealth.worktreeSanity.passed) {
+            // WU-1387: Show worktree sanity message if there are issues beyond orphans
+            const wsSanity = result.workflowHealth.worktreeSanity;
+            if (wsSanity.stale > 0 && wsSanity.orphans === 0) {
+                lines.push(`  Warning: ${wsSanity.message}`);
+            }
+        }
+    }
+    return {
+        blocked: false, // Never blocks init
+        warnings,
+        errors,
+        output: lines.join('\n'),
     };
 }
 /**
  * Format doctor output for terminal display
+ * WU-1386: Added workflow health section
  */
 export function formatDoctorOutput(result) {
     const lines = [];
@@ -300,6 +742,31 @@ export function formatDoctorOutput(result) {
     lines.push('');
     lines.push('Lane Health:');
     lines.push(formatCheck(result.checks.laneHealth));
+    // WU-1386: Workflow Health section
+    if (result.workflowHealth) {
+        lines.push('');
+        lines.push('Workflow Health:');
+        const mfd = result.workflowHealth.managedFilesDirty;
+        const mfdSymbol = mfd.passed ? '✓' : '⚠';
+        lines.push(`  ${mfdSymbol} ${mfd.message}`);
+        if (!mfd.passed && mfd.files.length > 0) {
+            for (const file of mfd.files.slice(0, 5)) {
+                lines.push(`     → ${file}`);
+            }
+            if (mfd.files.length > 5) {
+                lines.push(`     → ... and ${mfd.files.length - 5} more`);
+            }
+        }
+        const ws = result.workflowHealth.worktreeSanity;
+        const wsSymbol = ws.passed ? '✓' : '⚠';
+        lines.push(`  ${wsSymbol} ${ws.message}`);
+        // WU validity (only in --deep mode)
+        if (result.workflowHealth.wuValidity) {
+            const wv = result.workflowHealth.wuValidity;
+            const wvSymbol = wv.passed ? '✓' : '⚠';
+            lines.push(`  ${wvSymbol} ${wv.message}`);
+        }
+    }
     // Vendor configs
     lines.push('');
     lines.push('Vendor Configs:');
@@ -324,7 +791,12 @@ export function formatDoctorOutput(result) {
     lines.push('');
     lines.push('─'.repeat(45));
     lines.push(`LumenFlow safety: ${result.status}`);
-    if (result.status === 'INCOMPLETE') {
+    // WU-1386: Show exit code meaning
+    if (result.exitCode === 1) {
+        lines.push('');
+        lines.push('Warnings detected (exit code 1). Use --deep for full WU validation.');
+    }
+    else if (result.exitCode === 2) {
         lines.push('');
         lines.push('To fix missing components:');
         lines.push('  pnpm install && pnpm prepare  # Install Husky hooks');
@@ -341,26 +813,25 @@ export function formatDoctorJson(result) {
 }
 /**
  * CLI entry point
+ * WU-1386: Updated to use new exit codes
  */
 export async function main() {
     const opts = parseDoctorOptions();
     const projectDir = process.cwd();
-    const result = await runDoctor(projectDir);
+    const result = await runDoctor(projectDir, { deep: opts.deep });
     if (opts.json) {
         console.log(formatDoctorJson(result));
     }
     else {
         console.log(formatDoctorOutput(result));
     }
-    // Exit with error code if incomplete
-    if (result.status === 'INCOMPLETE') {
-        process.exit(1);
-    }
+    // WU-1386: Use new exit code system
+    process.exit(result.exitCode);
 }
 // CLI invocation when run directly
 if (import.meta.main) {
     main().catch((error) => {
         console.error('Doctor failed:', error);
-        process.exit(1);
+        process.exit(2);
     });
 }