@lumenflow/cli 2.2.2 → 2.3.1

package/dist/signal-cleanup.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI tool requires console output */
+/**
+ * Signal Cleanup CLI (WU-1204)
+ *
+ * Prune old signals based on TTL policy to prevent unbounded growth.
+ * Implements configurable retention:
+ * - Read signals: 7 days default TTL
+ * - Unread signals: 30 days default TTL
+ * - Max entries: 500 default
+ * - Active WU protection: signals linked to in_progress/blocked WUs are never removed
+ *
+ * Usage:
+ *   pnpm signal:cleanup                      # Cleanup based on TTL policy
+ *   pnpm signal:cleanup --dry-run            # Preview without changes
+ *   pnpm signal:cleanup --ttl 3d             # Override read signal TTL
+ *   pnpm signal:cleanup --max-entries 100    # Override max entries
+ *   pnpm signal:cleanup --json               # Output as JSON
+ *
+ * @see {@link packages/@lumenflow/memory/src/signal-cleanup-core.ts} - Core logic
+ * @see {@link packages/@lumenflow/memory/__tests__/signal-cleanup-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 { cleanupSignals } from '@lumenflow/memory/dist/signal-cleanup-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';
+/**
+ * Log prefix for signal:cleanup output
+ */
+const LOG_PREFIX = '[signal:cleanup]';
+/**
+ * Tool name for audit logging
+ */
+const TOOL_NAME = 'signal:cleanup';
+/**
+ * Bytes per KB for formatting
+ */
+const BYTES_PER_KB = 1024;
+/**
+ * Active WU statuses that should protect signals
+ */
+const ACTIVE_WU_STATUSES = ['in_progress', 'blocked'];
+/**
+ * CLI argument options specific to signal:cleanup
+ */
+const CLI_OPTIONS = {
+    dryRun: {
+        name: 'dryRun',
+        flags: '--dry-run',
+        description: 'Preview cleanup without making changes',
+    },
+    ttl: {
+        name: 'ttl',
+        flags: '--ttl <duration>',
+        description: 'TTL for read signals (e.g., 7d, 24h). Default: 7d',
+    },
+    unreadTtl: {
+        name: 'unreadTtl',
+        flags: '--unread-ttl <duration>',
+        description: 'TTL for unread signals (e.g., 30d). Default: 30d',
+    },
+    maxEntries: {
+        name: 'maxEntries',
+        flags: '--max-entries <count>',
+        description: 'Maximum signals to retain. Default: 500',
+    },
+    json: {
+        name: 'json',
+        flags: '--json',
+        description: 'Output as JSON',
+    },
+    quiet: {
+        name: 'quiet',
+        flags: '-q, --quiet',
+        description: 'Suppress output except errors',
+    },
+    baseDir: {
+        name: 'baseDir',
+        flags: '-b, --base-dir <path>',
+        description: 'Base directory (defaults to current directory)',
+    },
+};
+/**
+ * Write audit log entry for tool execution
+ *
+ * @param baseDir - Base directory
+ * @param entry - Audit log entry
+ */
+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
+    }
+}
+/**
+ * Format bytes as human-readable string
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 KB")
+ */
+function formatBytes(bytes) {
+    if (bytes < BYTES_PER_KB) {
+        return `${bytes} B`;
+    }
+    const kb = (bytes / BYTES_PER_KB).toFixed(1);
+    return `${kb} KB`;
+}
+/**
+ * Format compaction ratio as percentage
+ *
+ * @param ratio - Compaction ratio (0-1)
+ * @returns Formatted percentage
+ */
+function formatRatio(ratio) {
+    return `${(ratio * 100).toFixed(1)}%`;
+}
+/**
+ * Get active WU IDs (in_progress or blocked) by scanning WU YAML files.
+ *
+ * @param baseDir - Base directory
+ * @returns Set of active WU IDs
+ */
+async function getActiveWuIds(baseDir) {
+    const activeIds = new Set();
+    try {
+        const config = getConfig({ projectRoot: baseDir });
+        const wuDir = path.join(baseDir, config.directories.wuDir);
+        // Find all WU YAML files
+        const wuFiles = await fg('WU-*.yaml', { cwd: wuDir });
+        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 && ACTIVE_WU_STATUSES.includes(wu.status)) {
+                    activeIds.add(wu.id);
+                }
+            }
+            catch {
+                // Skip files that fail to parse
+                continue;
+            }
+        }
+    }
+    catch {
+        // If we can't read WU files, return empty set (safer to remove nothing)
+    }
+    return activeIds;
+}
+/**
+ * Parse CLI arguments
+ *
+ * @returns Parsed arguments
+ */
+function parseArguments() {
+    return createWUParser({
+        name: 'signal-cleanup',
+        description: 'Prune old signals based on TTL policy to prevent unbounded growth',
+        options: [
+            CLI_OPTIONS.dryRun,
+            CLI_OPTIONS.ttl,
+            CLI_OPTIONS.unreadTtl,
+            CLI_OPTIONS.maxEntries,
+            CLI_OPTIONS.json,
+            CLI_OPTIONS.quiet,
+            CLI_OPTIONS.baseDir,
+        ],
+        required: [],
+        allowPositionalId: false,
+    });
+}
+/**
+ * Print cleanup result to console
+ *
+ * @param result - Cleanup result
+ * @param quiet - Suppress verbose output
+ */
+function printResult(result, quiet) {
+    if (result.dryRun) {
+        console.log(`${LOG_PREFIX} Dry-run: Would remove ${result.removedIds.length} signal(s)`);
+    }
+    else {
+        console.log(`${LOG_PREFIX} Cleanup complete`);
+    }
+    if (quiet) {
+        console.log(`${result.removedIds.length} removed, ${result.retainedIds.length} retained`);
+        return;
+    }
+    console.log('');
+    console.log('Summary:');
+    console.log(`  Removed:          ${result.removedIds.length} signal(s)`);
+    console.log(`  Retained:         ${result.retainedIds.length} signal(s)`);
+    console.log(`  Bytes Freed:      ${formatBytes(result.bytesFreed)}`);
+    console.log(`  Compaction Ratio: ${formatRatio(result.compactionRatio)}`);
+    console.log('');
+    console.log('Breakdown:');
+    console.log(`  TTL Expired (read):    ${result.breakdown.ttlExpired} removed`);
+    console.log(`  TTL Expired (unread):  ${result.breakdown.unreadTtlExpired} removed`);
+    console.log(`  Count Limit Exceeded:  ${result.breakdown.countLimitExceeded} removed`);
+    console.log(`  Active WU Protected:   ${result.breakdown.activeWuProtected} retained`);
+    if (result.removedIds.length > 0 && !result.dryRun) {
+        console.log('');
+        console.log('Removed Signal IDs:');
+        // Show first 10, then "and X more" if needed
+        const displayLimit = 10;
+        const displayIds = result.removedIds.slice(0, displayLimit);
+        for (const id of displayIds) {
+            console.log(`  - ${id}`);
+        }
+        if (result.removedIds.length > displayLimit) {
+            console.log(`  ... and ${result.removedIds.length - displayLimit} more`);
+        }
+    }
+    if (result.dryRun) {
+        console.log('');
+        console.log('To execute, run without --dry-run');
+    }
+}
+/**
+ * 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 {
+        result = await cleanupSignals(baseDir, {
+            dryRun: args.dryRun,
+            ttl: args.ttl,
+            unreadTtl: args.unreadTtl,
+            maxEntries: args.maxEntries ? parseInt(args.maxEntries, 10) : undefined,
+            getActiveWuIds: () => getActiveWuIds(baseDir),
+        });
+    }
+    catch (err) {
+        error = err.message;
+    }
+    const durationMs = Date.now() - startTime;
+    await writeAuditLog(baseDir, {
+        tool: TOOL_NAME,
+        status: error ? 'failed' : 'success',
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs,
+        input: {
+            baseDir,
+            dryRun: args.dryRun,
+            ttl: args.ttl,
+            unreadTtl: args.unreadTtl,
+            maxEntries: args.maxEntries,
+        },
+        output: result
+            ? {
+                success: result.success,
+                removedCount: result.removedIds.length,
+                retainedCount: result.retainedIds.length,
+                bytesFreed: result.bytesFreed,
+                compactionRatio: result.compactionRatio,
+                breakdown: result.breakdown,
+                dryRun: result.dryRun,
+            }
+            : null,
+        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(EXIT_CODES.SUCCESS);
+    }
+    if (result) {
+        printResult(result, args.quiet ?? false);
+    }
+}
+main().catch((e) => {
+    console.error(`${LOG_PREFIX} ${e.message}`);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/spawn-list.js

@@ -10,8 +10,8 @@
  *   pnpm spawn:list --initiative INIT-XXX # All spawns in an initiative
  *   pnpm spawn:list --json               # JSON output
  *
- * @see {@link tools/lib/spawn-tree.mjs} - Tree builder
- * @see {@link tools/__tests__/spawn-list.test.mjs} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/spawn-tree.ts} - Tree builder
+ * @see {@link packages/@lumenflow/cli/src/__tests__/spawn-list.test.ts} - Tests
  */
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
@@ -130,9 +130,10 @@ async function main() {
         console.log(`\nTotal: ${spawns.length} spawn(s) across ${rootWuIds.length} root WU(s)`);
     }
 }
-// Guard main() for testability
-import { fileURLToPath } from 'node:url';
-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((err) => {
         console.error(`${LOG_PREFIX} ${EMOJI.ERROR} ${err.message}`);
         process.exit(1);

package/dist/state-bootstrap.js

@@ -5,7 +5,7 @@
  * One-time migration utility from WU YAMLs to event-sourced state store.
  * Reads all WU YAML files and generates corresponding events in the state store.
  *
- * WU-1107: INIT-003 Phase 3c - Migrate state-bootstrap.mjs from PatientPath
+ * WU-1107: INIT-003 Phase 3c - Migrate state-bootstrap.ts from PatientPath
  *
  * Usage:
  *   pnpm state:bootstrap           # Dry-run mode (shows what would be done)
@@ -299,9 +299,10 @@ async function main() {
     }
     process.exit(EXIT_CODES.SUCCESS);
 }
-// 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);
 }