@lumenflow/cli 2.2.1 → 2.3.1

package/dist/state-doctor.js

@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/**
+ * State Doctor CLI (WU-1209)
+ *
+ * Integrity checker for LumenFlow state that detects:
+ * - Orphaned WUs (done status but no stamp)
+ * - Dangling signals (reference non-existent WUs)
+ * - Broken memory relationships (events for missing WU specs)
+ *
+ * Inspired by Beads bd doctor command.
+ *
+ * Features:
+ * - Human-readable output with actionable suggestions
+ * - --fix flag for safe auto-repair of resolvable issues
+ * - --dry-run to preview what would be fixed
+ * - --json for machine-readable output
+ *
+ * Usage:
+ *   pnpm state:doctor                 # Run integrity checks
+ *   pnpm state:doctor --fix           # Auto-repair safe issues
+ *   pnpm state:doctor --fix --dry-run # Preview repairs
+ *   pnpm state:doctor --json          # Output as JSON
+ *
+ * @see {@link packages/@lumenflow/core/src/state-doctor-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/core/src/__tests__/state-doctor-core.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { parse as parseYaml } from 'yaml';
+import { diagnoseState, ISSUE_TYPES, ISSUE_SEVERITY, } from '@lumenflow/core/dist/state-doctor-core.js';
+import { createWUParser } from '@lumenflow/core/dist/arg-parser.js';
+import { EXIT_CODES, LUMENFLOW_PATHS } from '@lumenflow/core/dist/wu-constants.js';
+import { getConfig } from '@lumenflow/core/dist/lumenflow-config.js';
+import { createStamp } from '@lumenflow/core/dist/stamp-utils.js';
+import { createStateDoctorFixDeps } from './state-doctor-fix.js';
+/**
+ * Log prefix for state:doctor output
+ */
+const LOG_PREFIX = '[state:doctor]';
+/**
+ * Signals file path (relative to project root)
+ * Located in memory subdirectory: .lumenflow/memory/signals.jsonl
+ */
+const SIGNALS_FILE = '.lumenflow/memory/signals.jsonl';
+/**
+ * WU events file path (relative to project root)
+ * Located in state directory: .lumenflow/state/wu-events.jsonl
+ */
+const WU_EVENTS_FILE = '.lumenflow/state/wu-events.jsonl';
+/**
+ * Tool name for audit logging
+ */
+const TOOL_NAME = 'state:doctor';
+/**
+ * Emoji constants for output formatting
+ */
+const EMOJI = {
+    SUCCESS: '\u2705',
+    FAILURE: '\u274C',
+    WARNING: '\u26A0\uFE0F',
+    FIX: '\u{1F527}',
+    INFO: '\u2139\uFE0F',
+};
+/**
+ * CLI argument options for state:doctor
+ */
+const CLI_OPTIONS = {
+    fix: {
+        name: 'fix',
+        flags: '--fix',
+        description: 'Auto-repair safe issues',
+    },
+    dryRun: {
+        name: 'dryRun',
+        flags: '--dry-run',
+        description: 'Preview repairs without making changes',
+    },
+    json: {
+        name: 'json',
+        flags: '--json',
+        description: 'Output as JSON',
+    },
+    quiet: {
+        name: 'quiet',
+        flags: '-q, --quiet',
+        description: 'Suppress output except errors and summary',
+    },
+    baseDir: {
+        name: 'baseDir',
+        flags: '-b, --base-dir <path>',
+        description: 'Base directory (defaults to current directory)',
+    },
+};
+/**
+ * Write audit log entry for tool execution
+ */
+async function writeAuditLog(baseDir, entry) {
+    try {
+        const logPath = path.join(baseDir, LUMENFLOW_PATHS.AUDIT_LOG);
+        const logDir = path.dirname(logPath);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates known directory
+        await fs.mkdir(logDir, { recursive: true });
+        const line = `${JSON.stringify(entry)}\n`;
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes audit log
+        await fs.appendFile(logPath, line, 'utf-8');
+    }
+    catch {
+        // Audit logging is non-fatal - silently ignore errors
+    }
+}
+/**
+ * Parse CLI arguments
+ */
+function parseArguments() {
+    return createWUParser({
+        name: 'state-doctor',
+        description: 'Check state integrity and optionally repair issues',
+        options: [
+            CLI_OPTIONS.fix,
+            CLI_OPTIONS.dryRun,
+            CLI_OPTIONS.json,
+            CLI_OPTIONS.quiet,
+            CLI_OPTIONS.baseDir,
+        ],
+        required: [],
+        allowPositionalId: false,
+    });
+}
+/**
+ * Create dependencies for state doctor from filesystem
+ */
+async function createDeps(baseDir) {
+    const config = getConfig({ projectRoot: baseDir });
+    return {
+        /**
+         * List all WU YAML files
+         */
+        listWUs: async () => {
+            try {
+                const wuDir = path.join(baseDir, config.directories.wuDir);
+                const wuFiles = await fg('WU-*.yaml', { cwd: wuDir });
+                const wus = [];
+                for (const file of wuFiles) {
+                    try {
+                        const filePath = path.join(wuDir, file);
+                        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known path
+                        const content = await fs.readFile(filePath, 'utf-8');
+                        const wu = parseYaml(content);
+                        if (wu.id && wu.status) {
+                            wus.push({
+                                id: wu.id,
+                                status: wu.status,
+                                lane: wu.lane,
+                                title: wu.title,
+                            });
+                        }
+                    }
+                    catch {
+                        // Skip files that fail to parse
+                        continue;
+                    }
+                }
+                return wus;
+            }
+            catch {
+                return [];
+            }
+        },
+        /**
+         * List all stamp file IDs
+         */
+        listStamps: async () => {
+            try {
+                const stampsDir = path.join(baseDir, LUMENFLOW_PATHS.STAMPS_DIR);
+                const stampFiles = await fg('WU-*.done', { cwd: stampsDir });
+                return stampFiles.map((file) => file.replace('.done', ''));
+            }
+            catch {
+                return [];
+            }
+        },
+        /**
+         * List all signals from NDJSON file
+         */
+        listSignals: async () => {
+            try {
+                const signalsPath = path.join(baseDir, SIGNALS_FILE);
+                // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known path
+                const content = await fs.readFile(signalsPath, 'utf-8');
+                const signals = [];
+                for (const line of content.split('\n')) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const signal = JSON.parse(line);
+                        if (signal.id) {
+                            signals.push({
+                                id: signal.id,
+                                wuId: signal.wuId,
+                                timestamp: signal.timestamp,
+                                message: signal.message,
+                            });
+                        }
+                    }
+                    catch {
+                        // Skip malformed lines
+                        continue;
+                    }
+                }
+                return signals;
+            }
+            catch {
+                return [];
+            }
+        },
+        /**
+         * List all events from NDJSON file
+         */
+        listEvents: async () => {
+            try {
+                const eventsPath = path.join(baseDir, WU_EVENTS_FILE);
+                // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known path
+                const content = await fs.readFile(eventsPath, 'utf-8');
+                const events = [];
+                for (const line of content.split('\n')) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const event = JSON.parse(line);
+                        if (event.wuId && event.type) {
+                            events.push({
+                                wuId: event.wuId,
+                                type: event.type,
+                                timestamp: event.timestamp,
+                            });
+                        }
+                    }
+                    catch {
+                        // Skip malformed lines
+                        continue;
+                    }
+                }
+                return events;
+            }
+            catch {
+                return [];
+            }
+        },
+        /**
+         * Remove a signal by ID (rewrite signals file without the target)
+         */
+        removeSignal: async (id) => {
+            const signalsPath = path.join(baseDir, SIGNALS_FILE);
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known path
+            const content = await fs.readFile(signalsPath, 'utf-8');
+            const lines = content.split('\n').filter((line) => {
+                if (!line.trim())
+                    return false;
+                try {
+                    const signal = JSON.parse(line);
+                    return signal.id !== id;
+                }
+                catch {
+                    return true; // Keep malformed lines
+                }
+            });
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes known path
+            await fs.writeFile(signalsPath, lines.join('\n') + '\n', 'utf-8');
+        },
+        /**
+         * Remove events for a WU (rewrite events file without the target WU)
+         */
+        removeEvent: async (wuId) => {
+            const eventsPath = path.join(baseDir, WU_EVENTS_FILE);
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known path
+            const content = await fs.readFile(eventsPath, 'utf-8');
+            const lines = content.split('\n').filter((line) => {
+                if (!line.trim())
+                    return false;
+                try {
+                    const event = JSON.parse(line);
+                    return event.wuId !== wuId;
+                }
+                catch {
+                    return true; // Keep malformed lines
+                }
+            });
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes known path
+            await fs.writeFile(eventsPath, lines.join('\n') + '\n', 'utf-8');
+        },
+        /**
+         * Create a stamp for a WU
+         */
+        createStamp: async (wuId, title) => {
+            const stampsDir = path.join(baseDir, LUMENFLOW_PATHS.STAMPS_DIR);
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates known directory
+            await fs.mkdir(stampsDir, { recursive: true });
+            await createStamp({
+                id: wuId,
+                title,
+            });
+        },
+    };
+}
+/**
+ * Get emoji for issue severity
+ */
+function getSeverityEmoji(severity) {
+    switch (severity) {
+        case ISSUE_SEVERITY.ERROR:
+            return EMOJI.FAILURE;
+        case ISSUE_SEVERITY.WARNING:
+            return EMOJI.WARNING;
+        case ISSUE_SEVERITY.INFO:
+            return EMOJI.INFO;
+        default:
+            return EMOJI.WARNING;
+    }
+}
+/**
+ * Get human-readable issue type label
+ */
+function getIssueTypeLabel(type) {
+    switch (type) {
+        case ISSUE_TYPES.ORPHANED_WU:
+            return 'Orphaned WU';
+        case ISSUE_TYPES.DANGLING_SIGNAL:
+            return 'Dangling Signal';
+        case ISSUE_TYPES.BROKEN_EVENT:
+            return 'Broken Event';
+        default:
+            return type;
+    }
+}
+/**
+ * Print summary section
+ */
+function printSummary(result) {
+    console.log('=== Summary ===');
+    console.log(`  Orphaned WUs:     ${result.summary.orphanedWUs}`);
+    console.log(`  Dangling Signals: ${result.summary.danglingSignals}`);
+    console.log(`  Broken Events:    ${result.summary.brokenEvents}`);
+    console.log(`  Total Issues:     ${result.summary.totalIssues}`);
+}
+/**
+ * Print fixed issues section
+ */
+function printFixedSection(result) {
+    if (result.fixed.length > 0) {
+        console.log('\n=== Fixed ===');
+        for (const issue of result.fixed) {
+            const id = issue.wuId || issue.signalId;
+            console.log(`  ${EMOJI.SUCCESS} Fixed: ${getIssueTypeLabel(issue.type)} - ${id}`);
+        }
+    }
+    if (result.fixErrors.length > 0) {
+        console.log('\n=== Fix Errors ===');
+        for (const err of result.fixErrors) {
+            const id = err.wuId || err.signalId;
+            console.log(`  ${EMOJI.FAILURE} Failed to fix: ${id} - ${err.error}`);
+        }
+    }
+}
+/**
+ * Print dry-run section
+ */
+function printDryRunSection(result) {
+    if (!result.dryRun || !result.wouldFix || result.wouldFix.length === 0) {
+        return;
+    }
+    console.log('\n=== Would Fix (dry-run) ===');
+    for (const issue of result.wouldFix) {
+        const id = issue.wuId || issue.signalId;
+        console.log(`  ${EMOJI.FIX} Would fix: ${getIssueTypeLabel(issue.type)} - ${id}`);
+    }
+    console.log('\n  To apply fixes, run without --dry-run');
+}
+/**
+ * Print issues list
+ */
+function printIssues(result) {
+    console.log(`${LOG_PREFIX} ${EMOJI.WARNING} Found ${result.summary.totalIssues} issue(s)\n`);
+    console.log('=== Issues ===');
+    for (const issue of result.issues) {
+        const emoji = getSeverityEmoji(issue.severity);
+        const label = getIssueTypeLabel(issue.type);
+        console.log(`  ${emoji} [${label}] ${issue.description}`);
+        console.log(`     ${EMOJI.FIX} ${issue.suggestion}`);
+        if (issue.canAutoFix) {
+            console.log(`     ${EMOJI.INFO} Can be auto-fixed with --fix`);
+        }
+        console.log('');
+    }
+}
+/**
+ * Print diagnosis result to console
+ */
+function printResult(result, quiet) {
+    if (result.healthy) {
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} State is healthy - no issues found`);
+        return;
+    }
+    if (!quiet) {
+        printIssues(result);
+    }
+    printSummary(result);
+    printFixedSection(result);
+    printDryRunSection(result);
+    if (result.issues.length > 0 && result.fixed.length === 0 && !result.dryRun) {
+        console.log(`\n  ${EMOJI.INFO} Run with --fix to auto-repair fixable issues`);
+    }
+}
+/**
+ * Determine audit log status from result
+ */
+function getAuditStatus(error, result) {
+    if (error)
+        return 'failed';
+    if (result?.healthy)
+        return 'success';
+    if (result?.fixErrors.length === 0 && result?.fixed.length > 0)
+        return 'success';
+    return 'partial';
+}
+/**
+ * Build audit log output entry
+ */
+function buildAuditOutput(result) {
+    if (!result)
+        return null;
+    return {
+        healthy: result.healthy,
+        totalIssues: result.summary.totalIssues,
+        fixedCount: result.fixed.length,
+        fixErrorCount: result.fixErrors.length,
+        dryRun: result.dryRun,
+    };
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = parseArguments();
+    const baseDir = args.baseDir || process.cwd();
+    const startedAt = new Date().toISOString();
+    const startTime = Date.now();
+    let result = null;
+    let error = null;
+    try {
+        // Create base deps for read operations
+        const baseDeps = await createDeps(baseDir);
+        // WU-1230: When --fix is enabled, use micro-worktree isolation for all
+        // tracked file modifications. This prevents direct modifications to main
+        // and ensures changes are pushed via merge.
+        const deps = args.fix && !args.dryRun
+            ? {
+                ...baseDeps,
+                ...createStateDoctorFixDeps(baseDir),
+            }
+            : baseDeps;
+        result = await diagnoseState(baseDir, deps, {
+            fix: args.fix,
+            dryRun: args.dryRun,
+        });
+    }
+    catch (err) {
+        error = err.message;
+    }
+    const durationMs = Date.now() - startTime;
+    const auditStatus = getAuditStatus(error, result);
+    await writeAuditLog(baseDir, {
+        tool: TOOL_NAME,
+        status: auditStatus,
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs,
+        input: { baseDir, fix: args.fix, dryRun: args.dryRun },
+        output: buildAuditOutput(result),
+        error: error ? { message: error } : null,
+    });
+    if (error) {
+        console.error(`${LOG_PREFIX} Error: ${error}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result?.healthy ? EXIT_CODES.SUCCESS : EXIT_CODES.ERROR);
+    }
+    if (result) {
+        printResult(result, args.quiet ?? false);
+        const shouldError = !result.healthy && result.fixed.length === 0;
+        if (shouldError)
+            process.exit(EXIT_CODES.ERROR);
+    }
+}
+main().catch((e) => {
+    console.error(`${LOG_PREFIX} ${e.message}`);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/validate-agent-skills.js

@@ -18,7 +18,6 @@
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { FILE_SYSTEM, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
 const LOG_PREFIX = '[validate-agent-skills]';
 /**
@@ -209,8 +208,10 @@ Examples:
         }
     }
 }
-// Guard main() for testability
-if (process.argv[1] === fileURLToPath(import.meta.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
+if (import.meta.main) {
     main().catch((error) => {
         console.error(`${LOG_PREFIX} Unexpected error:`, error);
         process.exit(1);

package/dist/validate-agent-sync.js

@@ -17,7 +17,6 @@
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { FILE_SYSTEM, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
 const LOG_PREFIX = '[validate-agent-sync]';
 /**
@@ -139,8 +138,10 @@ Examples:
         process.exit(1);
     }
 }
-// Guard main() for testability
-if (process.argv[1] === fileURLToPath(import.meta.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
+if (import.meta.main) {
     main().catch((error) => {
         console.error(`${LOG_PREFIX} Unexpected error:`, error);
         process.exit(1);

package/dist/validate-backlog-sync.js

@@ -15,89 +15,10 @@
  *
  * @see {@link docs/04-operations/tasks/backlog.md} - Backlog file
  */
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { FILE_SYSTEM, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
+import { validateBacklogSync, } from '@lumenflow/core/dist/validators/backlog-sync.js';
+import { EMOJI } from '@lumenflow/core/dist/wu-constants.js';
 const LOG_PREFIX = '[validate-backlog-sync]';
-/**
- * Extract WU IDs from backlog.md content
- *
- * @param content - backlog.md content
- * @returns Array of WU IDs found
- */
-function extractWUIDsFromBacklog(content) {
-    const wuIds = [];
-    const pattern = /WU-\d+/gi;
-    let match;
-    while ((match = pattern.exec(content)) !== null) {
-        const wuId = match[0].toUpperCase();
-        if (!wuIds.includes(wuId)) {
-            wuIds.push(wuId);
-        }
-    }
-    return wuIds;
-}
-/**
- * Get all WU IDs from YAML files
- *
- * @param wuDir - Path to WU directory
- * @returns Array of WU IDs
- */
-function getWUIDsFromFiles(wuDir) {
-    if (!existsSync(wuDir)) {
-        return [];
-    }
-    return readdirSync(wuDir)
-        .filter((f) => f.endsWith('.yaml'))
-        .map((f) => f.replace('.yaml', '').toUpperCase());
-}
-/**
- * Validate that backlog.md is in sync with WU YAML files
- *
- * @param options - Validation options
- * @param options.cwd - Working directory (default: process.cwd())
- * @returns Validation result
- */
-export async function validateBacklogSync(options = {}) {
-    const { cwd = process.cwd() } = options;
-    const errors = [];
-    const warnings = [];
-    // Paths
-    const backlogPath = path.join(cwd, 'docs', '04-operations', 'tasks', 'backlog.md');
-    const wuDir = path.join(cwd, 'docs', '04-operations', 'tasks', 'wu');
-    // Check backlog.md exists
-    if (!existsSync(backlogPath)) {
-        errors.push(`Backlog file not found: ${backlogPath}`);
-        return { valid: false, errors, warnings, wuCount: 0, backlogCount: 0 };
-    }
-    // Get WU IDs from files
-    const wuIdsFromFiles = getWUIDsFromFiles(wuDir);
-    // Get WU IDs from backlog
-    const backlogContent = readFileSync(backlogPath, {
-        encoding: FILE_SYSTEM.UTF8,
-    });
-    const wuIdsFromBacklog = extractWUIDsFromBacklog(backlogContent);
-    // Check for WUs in files but not in backlog
-    for (const wuId of wuIdsFromFiles) {
-        if (!wuIdsFromBacklog.includes(wuId)) {
-            errors.push(`${wuId} not found in backlog.md (exists as ${wuId}.yaml)`);
-        }
-    }
-    // Check for WUs in backlog but not as files (warning only)
-    for (const wuId of wuIdsFromBacklog) {
-        if (!wuIdsFromFiles.includes(wuId)) {
-            warnings.push(`${wuId} referenced in backlog.md but ${wuId}.yaml not found`);
-        }
-    }
-    return {
-        valid: errors.length === 0,
-        errors,
-        warnings,
-        wuCount: wuIdsFromFiles.length,
-        backlogCount: wuIdsFromBacklog.length,
-    };
-}
+export { validateBacklogSync };
 /**
  * Main CLI entry point
  */
@@ -143,8 +64,10 @@ Examples:
         process.exit(1);
     }
 }
-// Guard main() for testability
-if (process.argv[1] === fileURLToPath(import.meta.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
+if (import.meta.main) {
     main().catch((error) => {
         console.error(`${LOG_PREFIX} Unexpected error:`, error);
         process.exit(1);

package/dist/validate-skills-spec.js

@@ -18,7 +18,6 @@
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { FILE_SYSTEM, EMOJI } from '@lumenflow/core/dist/wu-constants.js';
 const LOG_PREFIX = '[validate-skills-spec]';
 /**
@@ -197,8 +196,10 @@ Examples:
         }
     }
 }
-// Guard main() for testability
-if (process.argv[1] === fileURLToPath(import.meta.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
+if (import.meta.main) {
     main().catch((error) => {
         console.error(`${LOG_PREFIX} Unexpected error:`, error);
         process.exit(1);