@lumenflow/cli 1.6.0 → 2.1.0

package/dist/__tests__/trace-gen.test.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Tests for trace-gen CLI command
+ *
+ * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ *
+ * Trace generator creates traceability reports linking WUs to code changes,
+ * useful for audit trails and compliance documentation.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// Import functions under test
+import { parseTraceArgs, TraceFormat, buildTraceEntry, } from '../trace-gen.js';
+describe('trace-gen', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('parseTraceArgs', () => {
+        it('should parse --wu flag', () => {
+            const args = parseTraceArgs(['node', 'trace-gen.js', '--wu', 'WU-1112']);
+            expect(args.wuId).toBe('WU-1112');
+        });
+        it('should parse --format json', () => {
+            const args = parseTraceArgs(['node', 'trace-gen.js', '--format', 'json']);
+            expect(args.format).toBe('json');
+        });
+        it('should parse --format markdown', () => {
+            const args = parseTraceArgs(['node', 'trace-gen.js', '--format', 'markdown']);
+            expect(args.format).toBe('markdown');
+        });
+        it('should parse --output flag', () => {
+            const args = parseTraceArgs(['node', 'trace-gen.js', '--output', 'trace.json']);
+            expect(args.output).toBe('trace.json');
+        });
+        it('should parse --since flag', () => {
+            const args = parseTraceArgs(['node', 'trace-gen.js', '--since', '2024-01-01']);
+            expect(args.since).toBe('2024-01-01');
+        });
+        it('should parse --help flag', () => {
+            const args = parseTraceArgs(['node', 'trace-gen.js', '--help']);
+            expect(args.help).toBe(true);
+        });
+        it('should default format to json', () => {
+            const args = parseTraceArgs(['node', 'trace-gen.js']);
+            expect(args.format).toBeUndefined();
+        });
+    });
+    describe('TraceFormat enum', () => {
+        it('should have JSON format', () => {
+            expect(TraceFormat.JSON).toBe('json');
+        });
+        it('should have markdown format', () => {
+            expect(TraceFormat.MARKDOWN).toBe('markdown');
+        });
+        it('should have CSV format', () => {
+            expect(TraceFormat.CSV).toBe('csv');
+        });
+    });
+    describe('buildTraceEntry', () => {
+        it('should build trace entry from WU and commit data', () => {
+            const entry = buildTraceEntry({
+                wuId: 'WU-1112',
+                title: 'Migrate tools',
+                status: 'done',
+                commits: [{ sha: 'abc1234', message: 'feat: add deps-add', date: '2024-01-15T10:00:00Z' }],
+                files: ['src/deps-add.ts'],
+            });
+            expect(entry.wuId).toBe('WU-1112');
+            expect(entry.title).toBe('Migrate tools');
+            expect(entry.status).toBe('done');
+            expect(entry.commitCount).toBe(1);
+            expect(entry.fileCount).toBe(1);
+        });
+        it('should calculate commit count correctly', () => {
+            const entry = buildTraceEntry({
+                wuId: 'WU-1112',
+                title: 'Test',
+                status: 'done',
+                commits: [
+                    { sha: 'abc1234', message: 'feat: first', date: '2024-01-15T10:00:00Z' },
+                    { sha: 'def5678', message: 'feat: second', date: '2024-01-16T10:00:00Z' },
+                    { sha: 'ghi9012', message: 'fix: third', date: '2024-01-17T10:00:00Z' },
+                ],
+                files: ['a.ts', 'b.ts'],
+            });
+            expect(entry.commitCount).toBe(3);
+            expect(entry.fileCount).toBe(2);
+        });
+        it('should include first and last commit dates', () => {
+            const entry = buildTraceEntry({
+                wuId: 'WU-1112',
+                title: 'Test',
+                status: 'done',
+                commits: [
+                    { sha: 'abc1234', message: 'feat: first', date: '2024-01-15T10:00:00Z' },
+                    { sha: 'def5678', message: 'feat: last', date: '2024-01-20T10:00:00Z' },
+                ],
+                files: [],
+            });
+            expect(entry.firstCommit).toBe('2024-01-15T10:00:00Z');
+            expect(entry.lastCommit).toBe('2024-01-20T10:00:00Z');
+        });
+        it('should handle empty commits array', () => {
+            const entry = buildTraceEntry({
+                wuId: 'WU-1112',
+                title: 'Test',
+                status: 'done',
+                commits: [],
+                files: [],
+            });
+            expect(entry.commitCount).toBe(0);
+            expect(entry.firstCommit).toBeUndefined();
+            expect(entry.lastCommit).toBeUndefined();
+        });
+    });
+});

package/dist/backlog-prune.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * Backlog Prune Command
+ *
+ * Maintains backlog hygiene by:
+ * - Auto-tagging stale WUs (in_progress/ready too long without activity)
+ * - Archiving old completed WUs (done for > N days)
+ *
+ * WU-1106: INIT-003 Phase 3b - Migrate from PatientPath tools/backlog-prune.mjs
+ *
+ * Usage:
+ *   pnpm backlog:prune           # Dry-run mode (shows what would be done)
+ *   pnpm backlog:prune --execute # Apply changes
+ */
+import { readdirSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { readWURaw, writeWU, appendNote } from '@lumenflow/core/dist/wu-yaml.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { CLI_FLAGS, EXIT_CODES, EMOJI, WU_STATUS, STRING_LITERALS, } from '@lumenflow/core/dist/wu-constants.js';
+/* eslint-disable security/detect-non-literal-fs-filename */
+/** Log prefix for consistent output */
+const LOG_PREFIX = '[backlog-prune]';
+/**
+ * Default configuration for backlog pruning
+ */
+export const BACKLOG_PRUNE_DEFAULTS = {
+    /** Days without activity before in_progress WU is considered stale */
+    staleDaysInProgress: 7,
+    /** Days without activity before ready WU is considered stale */
+    staleDaysReady: 30,
+    /** Days after completion before done WU can be archived */
+    archiveDaysDone: 90,
+};
+/**
+ * Parse command line arguments for backlog-prune
+ */
+export function parseBacklogPruneArgs(argv) {
+    const args = {
+        dryRun: true,
+        staleDaysInProgress: BACKLOG_PRUNE_DEFAULTS.staleDaysInProgress,
+        staleDaysReady: BACKLOG_PRUNE_DEFAULTS.staleDaysReady,
+        archiveDaysDone: BACKLOG_PRUNE_DEFAULTS.archiveDaysDone,
+        help: false,
+    };
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === CLI_FLAGS.EXECUTE) {
+            args.dryRun = false;
+        }
+        else if (arg === CLI_FLAGS.DRY_RUN) {
+            args.dryRun = true;
+        }
+        else if (arg === CLI_FLAGS.HELP || arg === CLI_FLAGS.HELP_SHORT) {
+            args.help = true;
+        }
+        else if (arg === '--stale-days-in-progress' && argv[i + 1]) {
+            args.staleDaysInProgress = parseInt(argv[++i], 10);
+        }
+        else if (arg === '--stale-days-ready' && argv[i + 1]) {
+            args.staleDaysReady = parseInt(argv[++i], 10);
+        }
+        else if (arg === '--archive-days' && argv[i + 1]) {
+            args.archiveDaysDone = parseInt(argv[++i], 10);
+        }
+    }
+    return args;
+}
+/**
+ * Calculate days since a date string
+ * @returns Number of days since date, or null if invalid
+ */
+export function calculateStaleDays(dateStr) {
+    if (!dateStr)
+        return null;
+    const date = new Date(dateStr);
+    if (isNaN(date.getTime()))
+        return null;
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    return diffDays;
+}
+/**
+ * Check if a WU is stale based on its status and last activity date
+ */
+export function isWuStale(wu, options) {
+    const { staleDaysInProgress = BACKLOG_PRUNE_DEFAULTS.staleDaysInProgress } = options;
+    const { staleDaysReady = BACKLOG_PRUNE_DEFAULTS.staleDaysReady } = options;
+    // Done/blocked WUs are not considered stale
+    if (wu.status === WU_STATUS.DONE ||
+        wu.status === WU_STATUS.COMPLETED ||
+        wu.status === WU_STATUS.BLOCKED) {
+        return false;
+    }
+    // Get the relevant date for staleness check
+    // Use updated date if available, otherwise fall back to created date
+    const lastActivityDate = wu.updated || wu.created;
+    const daysSinceActivity = calculateStaleDays(lastActivityDate);
+    if (daysSinceActivity === null)
+        return false;
+    // Check against threshold based on status
+    if (wu.status === WU_STATUS.IN_PROGRESS) {
+        return daysSinceActivity > staleDaysInProgress;
+    }
+    if (wu.status === WU_STATUS.READY ||
+        wu.status === WU_STATUS.BACKLOG ||
+        wu.status === WU_STATUS.TODO) {
+        return daysSinceActivity > staleDaysReady;
+    }
+    return false;
+}
+/**
+ * Check if a WU is archivable (done for more than N days)
+ */
+export function isWuArchivable(wu, options) {
+    const { archiveDaysDone = BACKLOG_PRUNE_DEFAULTS.archiveDaysDone } = options;
+    // Only done WUs can be archived
+    if (wu.status !== WU_STATUS.DONE && wu.status !== WU_STATUS.COMPLETED) {
+        return false;
+    }
+    // Must have a completed date
+    if (!wu.completed) {
+        return false;
+    }
+    const daysSinceCompletion = calculateStaleDays(wu.completed);
+    if (daysSinceCompletion === null)
+        return false;
+    return daysSinceCompletion > archiveDaysDone;
+}
+/**
+ * Categorize WUs into stale, archivable, and healthy
+ */
+export function categorizeWus(wus, options) {
+    const stale = [];
+    const archivable = [];
+    const healthy = [];
+    for (const wu of wus) {
+        if (isWuStale(wu, options)) {
+            stale.push(wu);
+        }
+        else if (isWuArchivable(wu, options)) {
+            archivable.push(wu);
+        }
+        else {
+            healthy.push(wu);
+        }
+    }
+    return { stale, archivable, healthy };
+}
+/**
+ * Load all WU YAML files from the WU directory
+ * @internal Exported for testing
+ */
+export function loadAllWus() {
+    const wuDir = WU_PATHS.WU_DIR();
+    if (!existsSync(wuDir)) {
+        return [];
+    }
+    const files = readdirSync(wuDir).filter((f) => f.endsWith('.yaml'));
+    const wus = [];
+    for (const file of files) {
+        const filePath = path.join(wuDir, file);
+        try {
+            const doc = readWURaw(filePath);
+            if (doc && doc.id) {
+                wus.push({
+                    id: doc.id,
+                    status: doc.status || 'unknown',
+                    title: doc.title,
+                    created: doc.created,
+                    updated: doc.updated,
+                    completed: doc.completed,
+                });
+            }
+        }
+        catch {
+            // Skip invalid YAML files
+        }
+    }
+    return wus;
+}
+/**
+ * Tag a stale WU by appending a note
+ * @internal Exported for testing
+ */
+export function tagStaleWu(wu, dryRun) {
+    const wuPath = WU_PATHS.WU(wu.id);
+    const today = new Date().toISOString().split('T')[0];
+    const note = `[${today}] Auto-tagged as stale by backlog:prune`;
+    if (dryRun) {
+        console.log(`${LOG_PREFIX} ${EMOJI.INFO} Would tag ${wu.id} as stale`);
+        return;
+    }
+    try {
+        const doc = readWURaw(wuPath);
+        appendNote(doc, note);
+        writeWU(wuPath, doc);
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} Tagged ${wu.id} as stale`);
+    }
+    catch (err) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} Failed to tag ${wu.id}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Print help text
+ * @internal Exported for testing
+ */
+export function printHelp() {
+    console.log(`
+${LOG_PREFIX} Backlog Prune - Maintain backlog hygiene
+
+Usage:
+  pnpm backlog:prune           # Dry-run mode (default, shows what would be done)
+  pnpm backlog:prune --execute # Apply changes
+
+Options:
+  --execute                    Execute changes (default is dry-run)
+  --dry-run                    Show what would be done without making changes
+  --stale-days-in-progress N   Days before in_progress WU is stale (default: ${BACKLOG_PRUNE_DEFAULTS.staleDaysInProgress})
+  --stale-days-ready N         Days before ready WU is stale (default: ${BACKLOG_PRUNE_DEFAULTS.staleDaysReady})
+  --archive-days N             Days after completion before archiving (default: ${BACKLOG_PRUNE_DEFAULTS.archiveDaysDone})
+  --help, -h                   Show this help message
+
+This tool:
+  ${EMOJI.SUCCESS} Identifies stale WUs (in_progress/ready too long without activity)
+  ${EMOJI.SUCCESS} Identifies archivable WUs (completed > N days ago)
+  ${EMOJI.SUCCESS} Auto-tags stale WUs with timestamped notes
+  ${EMOJI.SUCCESS} Safe to run regularly (dry-run by default)
+`);
+}
+/**
+ * Main function
+ */
+async function main() {
+    const args = parseBacklogPruneArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    console.log(`${LOG_PREFIX} Backlog Hygiene Check`);
+    console.log(`${LOG_PREFIX} =====================${STRING_LITERALS.NEWLINE}`);
+    if (args.dryRun) {
+        console.log(`${LOG_PREFIX} ${EMOJI.INFO} DRY-RUN MODE (use --execute to apply changes)${STRING_LITERALS.NEWLINE}`);
+    }
+    // Load all WUs
+    const wus = loadAllWus();
+    console.log(`${LOG_PREFIX} Found ${wus.length} WU(s)${STRING_LITERALS.NEWLINE}`);
+    if (wus.length === 0) {
+        console.log(`${LOG_PREFIX} ${EMOJI.SUCCESS} No WUs to analyze`);
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // Categorize WUs
+    const categorization = categorizeWus(wus, {
+        staleDaysInProgress: args.staleDaysInProgress,
+        staleDaysReady: args.staleDaysReady,
+        archiveDaysDone: args.archiveDaysDone,
+    });
+    // Report stale WUs
+    if (categorization.stale.length > 0) {
+        console.log(`${LOG_PREFIX} ${EMOJI.WARNING} Stale WUs (${categorization.stale.length}):`);
+        for (const wu of categorization.stale) {
+            const lastActivity = wu.updated || wu.created;
+            const days = calculateStaleDays(lastActivity);
+            console.log(`    - ${wu.id}: ${wu.title || 'Untitled'} (${wu.status}, ${days} days since activity)`);
+            tagStaleWu(wu, args.dryRun);
+        }
+        console.log('');
+    }
+    // Report archivable WUs
+    if (categorization.archivable.length > 0) {
+        console.log(`${LOG_PREFIX} ${EMOJI.INFO} Archivable WUs (${categorization.archivable.length}):`);
+        for (const wu of categorization.archivable) {
+            const days = calculateStaleDays(wu.completed);
+            console.log(`    - ${wu.id}: ${wu.title || 'Untitled'} (completed ${days} days ago)`);
+        }
+        console.log(`${LOG_PREFIX} ${EMOJI.INFO} Archive functionality not yet implemented. Consider manual cleanup.`);
+        console.log('');
+    }
+    // Summary
+    console.log(`${LOG_PREFIX} Summary`);
+    console.log(`${LOG_PREFIX} ========`);
+    console.log(`${LOG_PREFIX} Total WUs: ${wus.length}`);
+    console.log(`${LOG_PREFIX} Stale: ${categorization.stale.length}`);
+    console.log(`${LOG_PREFIX} Archivable: ${categorization.archivable.length}`);
+    console.log(`${LOG_PREFIX} Healthy: ${categorization.healthy.length}`);
+    if (categorization.stale.length === 0 && categorization.archivable.length === 0) {
+        console.log(`${STRING_LITERALS.NEWLINE}${LOG_PREFIX} ${EMOJI.SUCCESS} Backlog is healthy!`);
+    }
+    else if (args.dryRun) {
+        console.log(`${STRING_LITERALS.NEWLINE}${LOG_PREFIX} ${EMOJI.INFO} This was a dry-run. Use --execute to apply changes.`);
+    }
+    process.exit(EXIT_CODES.SUCCESS);
+}
+// 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/deps-add.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Deps Add CLI Command
+ *
+ * Safe wrapper for `pnpm add` that enforces worktree discipline.
+ * Dependencies can only be added from within a worktree, not from main checkout.
+ *
+ * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ *
+ * Usage:
+ *   pnpm deps:add react
+ *   pnpm deps:add --dev vitest
+ *   pnpm deps:add --filter @lumenflow/cli chalk
+ *
+ * @see dependency-guard.ts for blocking logic
+ */
+import { execSync } from 'node:child_process';
+import { STDIO_MODES, EXIT_CODES, PKG_MANAGER, DEFAULTS, } from '@lumenflow/core/dist/wu-constants.js';
+import { runCLI } from './cli-entry-point.js';
+/** Log prefix for console output */
+const LOG_PREFIX = '[deps:add]';
+/**
+ * Parse command line arguments for deps-add
+ *
+ * @param argv - Process argv array
+ * @returns Parsed arguments
+ */
+export function parseDepsAddArgs(argv) {
+    const args = {
+        packages: [],
+    };
+    // Skip node and script name
+    const cliArgs = argv.slice(2);
+    for (let i = 0; i < cliArgs.length; i++) {
+        const arg = cliArgs[i];
+        if (arg === '--help' || arg === '-h') {
+            args.help = true;
+        }
+        else if (arg === '--dev' || arg === '-D') {
+            args.dev = true;
+        }
+        else if (arg === '--exact' || arg === '-E') {
+            args.exact = true;
+        }
+        else if (arg === '--filter' || arg === '-F') {
+            args.filter = cliArgs[++i];
+        }
+        else if (!arg.startsWith('-')) {
+            // Positional argument - package name
+            args.packages.push(arg);
+        }
+    }
+    return args;
+}
+/**
+ * Parse command line arguments for deps-remove
+ *
+ * @param argv - Process argv array
+ * @returns Parsed arguments
+ */
+export function parseDepsRemoveArgs(argv) {
+    const args = {
+        packages: [],
+    };
+    // Skip node and script name
+    const cliArgs = argv.slice(2);
+    for (let i = 0; i < cliArgs.length; i++) {
+        const arg = cliArgs[i];
+        if (arg === '--help' || arg === '-h') {
+            args.help = true;
+        }
+        else if (arg === '--filter' || arg === '-F') {
+            args.filter = cliArgs[++i];
+        }
+        else if (!arg.startsWith('-')) {
+            // Positional argument - package name
+            args.packages.push(arg);
+        }
+    }
+    return args;
+}
+/**
+ * Validate that the current directory is within a worktree
+ *
+ * Dependencies should only be modified in worktrees to maintain
+ * isolation and prevent lockfile conflicts on main checkout.
+ *
+ * @param cwd - Current working directory to validate
+ * @returns Validation result with error and fix command if invalid
+ */
+export function validateWorktreeContext(cwd) {
+    const worktreesDir = `/${DEFAULTS.WORKTREES_DIR}/`;
+    if (cwd.includes(worktreesDir)) {
+        return { valid: true };
+    }
+    return {
+        valid: false,
+        error: `Cannot modify dependencies on main checkout.\n\nReason: Running pnpm add/remove on main bypasses worktree isolation.\nThis can cause lockfile conflicts and block other agents.`,
+        fixCommand: `1. Claim a WU: pnpm wu:claim --id WU-XXXX --lane "Your Lane"\n2. cd worktrees/<lane>-wu-<id>/\n3. Run deps:add from the worktree`,
+    };
+}
+/**
+ * Build pnpm add command string from arguments
+ *
+ * @param args - Parsed deps-add arguments
+ * @returns Command string ready for execution
+ */
+export function buildPnpmAddCommand(args) {
+    const parts = [PKG_MANAGER, 'add'];
+    if (args.filter) {
+        parts.push('--filter', args.filter);
+    }
+    if (args.dev) {
+        parts.push('--save-dev');
+    }
+    if (args.exact) {
+        parts.push('--save-exact');
+    }
+    if (args.packages && args.packages.length > 0) {
+        parts.push(...args.packages);
+    }
+    return parts.join(' ');
+}
+/**
+ * Build pnpm remove command string from arguments
+ *
+ * @param args - Parsed deps-remove arguments
+ * @returns Command string ready for execution
+ */
+export function buildPnpmRemoveCommand(args) {
+    const parts = [PKG_MANAGER, 'remove'];
+    if (args.filter) {
+        parts.push('--filter', args.filter);
+    }
+    if (args.packages && args.packages.length > 0) {
+        parts.push(...args.packages);
+    }
+    return parts.join(' ');
+}
+/**
+ * Print help message for deps-add
+ */
+/* istanbul ignore next -- CLI entry point */
+function printHelp() {
+    console.log(`
+Usage: deps-add <packages...> [options]
+
+Add dependencies with worktree discipline enforcement.
+Must be run from inside a worktree (not main checkout).
+
+Arguments:
+  packages              Package names to add (e.g., react react-dom)
+
+Options:
+  -D, --dev             Add as dev dependency
+  -F, --filter <pkg>    Filter to specific workspace package
+  -E, --exact           Use exact version (--save-exact)
+  -h, --help            Show this help message
+
+Examples:
+  deps-add react                    # Add react to root
+  deps-add --dev vitest             # Add vitest as dev dependency
+  deps-add -F @lumenflow/cli chalk  # Add chalk to @lumenflow/cli
+  deps-add --exact react@18.2.0     # Add exact version
+
+Worktree Discipline:
+  This command only works inside a worktree to prevent lockfile
+  conflicts on main checkout. Claim a WU first:
+
+    pnpm wu:claim --id WU-XXXX --lane "Your Lane"
+    cd worktrees/<lane>-wu-<id>/
+    deps-add <package>
+`);
+}
+/**
+ * Main entry point for deps-add command
+ */
+/* istanbul ignore next -- CLI entry point */
+async function main() {
+    const args = parseDepsAddArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    if (!args.packages || args.packages.length === 0) {
+        console.error(`${LOG_PREFIX} Error: No packages specified`);
+        printHelp();
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // Validate worktree context
+    const validation = validateWorktreeContext(process.cwd());
+    if (!validation.valid) {
+        console.error(`${LOG_PREFIX} ${validation.error}`);
+        console.error(`\nTo fix:\n${validation.fixCommand}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // Build and execute pnpm add command
+    const command = buildPnpmAddCommand(args);
+    console.log(`${LOG_PREFIX} Running: ${command}`);
+    try {
+        execSync(command, {
+            stdio: STDIO_MODES.INHERIT,
+            cwd: process.cwd(),
+        });
+        console.log(`${LOG_PREFIX} ✅ Dependencies added successfully`);
+    }
+    catch (error) {
+        console.error(`${LOG_PREFIX} ❌ Failed to add dependencies`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+}
+// Run main if executed directly
+if (import.meta.main) {
+    runCLI(main);
+}