@lumenflow/cli 1.6.0 → 2.0.0

package/dist/session-coordinator.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * Session Coordinator CLI Command
+ *
+ * Manages agent sessions - starting, stopping, status, and handoffs.
+ * Sessions track which agent is working on which WU and facilitate
+ * coordination between multiple agents.
+ *
+ * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ *
+ * Usage:
+ *   pnpm session:start --wu WU-1112 --agent claude-code
+ *   pnpm session:stop --reason "Completed work"
+ *   pnpm session:status
+ *   pnpm session:handoff --wu WU-1112 --agent cursor
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { EXIT_CODES, LUMENFLOW_PATHS, FILE_SYSTEM } from '@lumenflow/core/dist/wu-constants.js';
+import { runCLI } from './cli-entry-point.js';
+/** Log prefix for console output */
+const LOG_PREFIX = '[session]';
+/**
+ * Session subcommands
+ */
+export var SessionCommand;
+(function (SessionCommand) {
+    SessionCommand["START"] = "start";
+    SessionCommand["STOP"] = "stop";
+    SessionCommand["STATUS"] = "status";
+    SessionCommand["HANDOFF"] = "handoff";
+})(SessionCommand || (SessionCommand = {}));
+/**
+ * Parse command line arguments for session-coordinator
+ *
+ * @param argv - Process argv array
+ * @returns Parsed arguments
+ */
+export function parseSessionArgs(argv) {
+    const args = {};
+    // 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 === '--wu' || arg === '-w') {
+            args.wuId = cliArgs[++i];
+        }
+        else if (arg === '--agent' || arg === '-a') {
+            args.agent = cliArgs[++i];
+        }
+        else if (arg === '--reason' || arg === '-r') {
+            args.reason = cliArgs[++i];
+        }
+        else if (!arg.startsWith('-')) {
+            // Subcommand
+            if (Object.values(SessionCommand).includes(arg)) {
+                args.command = arg;
+            }
+        }
+    }
+    // Default to status if no command given
+    if (!args.command && !args.help) {
+        args.command = SessionCommand.STATUS;
+    }
+    return args;
+}
+/**
+ * Validate session command arguments
+ *
+ * @param args - Parsed session arguments
+ * @returns Validation result
+ */
+export function validateSessionCommand(args) {
+    const { command, wuId } = args;
+    switch (command) {
+        case SessionCommand.START:
+            if (!wuId) {
+                return {
+                    valid: false,
+                    error: 'session start requires --wu <id> to specify which WU to work on',
+                };
+            }
+            break;
+        case SessionCommand.HANDOFF:
+            if (!wuId) {
+                return {
+                    valid: false,
+                    error: 'session handoff requires --wu <id> to specify which WU to hand off',
+                };
+            }
+            break;
+        case SessionCommand.STOP:
+        case SessionCommand.STATUS:
+            // No required arguments
+            break;
+        default:
+            return {
+                valid: false,
+                error: `Unknown command: ${command}`,
+            };
+    }
+    return { valid: true };
+}
+/**
+ * Get path to current session file
+ */
+function getSessionPath() {
+    return join(process.cwd(), LUMENFLOW_PATHS.SESSION_CURRENT);
+}
+/**
+ * Read current session state
+ */
+function readCurrentSession() {
+    const path = getSessionPath();
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(path, { encoding: FILE_SYSTEM.ENCODING });
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write session state
+ */
+function writeSession(session) {
+    const path = getSessionPath();
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    if (session === null) {
+        // Remove session file if clearing
+        if (existsSync(path)) {
+            const { unlinkSync } = require('node:fs');
+            unlinkSync(path);
+        }
+    }
+    else {
+        writeFileSync(path, JSON.stringify(session, null, 2), {
+            encoding: FILE_SYSTEM.ENCODING,
+        });
+    }
+}
+/**
+ * Print help message for session-coordinator
+ */
+/* istanbul ignore next -- CLI entry point */
+function printHelp() {
+    console.log(`
+Usage: session <command> [options]
+
+Manage agent sessions for WU work coordination.
+
+Commands:
+  start     Start a new session
+  stop      Stop current session
+  status    Show current session status
+  handoff   Hand off session to another agent
+
+Options:
+  -w, --wu <id>       WU ID to work on (required for start/handoff)
+  -a, --agent <type>  Agent type (e.g., claude-code, cursor, aider)
+  -r, --reason <msg>  Reason for stopping session
+  -h, --help          Show this help message
+
+Examples:
+  session start --wu WU-1112 --agent claude-code
+  session stop --reason "Completed acceptance criteria"
+  session status
+  session handoff --wu WU-1112 --agent cursor
+
+Session files are stored in: ${LUMENFLOW_PATHS.SESSION_CURRENT}
+`);
+}
+/**
+ * Handle start command
+ */
+/* istanbul ignore next -- CLI entry point */
+function handleStart(args) {
+    const current = readCurrentSession();
+    if (current) {
+        console.log(`${LOG_PREFIX} Active session already exists:`);
+        console.log(`  WU: ${current.wuId}`);
+        console.log(`  Agent: ${current.agent}`);
+        console.log(`  Started: ${current.startedAt}`);
+        console.log(`\n${LOG_PREFIX} Stop current session first with: session stop`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const session = {
+        wuId: args.wuId,
+        agent: args.agent || 'unknown',
+        startedAt: new Date().toISOString(),
+        lastActivity: new Date().toISOString(),
+    };
+    writeSession(session);
+    console.log(`${LOG_PREFIX} ✅ Session started`);
+    console.log(`  WU: ${session.wuId}`);
+    console.log(`  Agent: ${session.agent}`);
+    console.log(`  Started: ${session.startedAt}`);
+}
+/**
+ * Handle stop command
+ */
+/* istanbul ignore next -- CLI entry point */
+function handleStop(args) {
+    const current = readCurrentSession();
+    if (!current) {
+        console.log(`${LOG_PREFIX} No active session to stop.`);
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    const duration = Date.now() - new Date(current.startedAt).getTime();
+    const durationMin = Math.round(duration / 60000);
+    console.log(`${LOG_PREFIX} ✅ Session stopped`);
+    console.log(`  WU: ${current.wuId}`);
+    console.log(`  Agent: ${current.agent}`);
+    console.log(`  Duration: ${durationMin} minutes`);
+    if (args.reason) {
+        console.log(`  Reason: ${args.reason}`);
+    }
+    writeSession(null);
+}
+/**
+ * Handle status command
+ */
+/* istanbul ignore next -- CLI entry point */
+function handleStatus() {
+    const current = readCurrentSession();
+    if (!current) {
+        console.log(`${LOG_PREFIX} No active session.`);
+        console.log(`\n${LOG_PREFIX} Start a session with: session start --wu WU-XXXX`);
+        return;
+    }
+    const duration = Date.now() - new Date(current.startedAt).getTime();
+    const durationMin = Math.round(duration / 60000);
+    console.log(`${LOG_PREFIX} Active session:`);
+    console.log(`  WU: ${current.wuId}`);
+    console.log(`  Agent: ${current.agent}`);
+    console.log(`  Started: ${current.startedAt}`);
+    console.log(`  Duration: ${durationMin} minutes`);
+    console.log(`  Last activity: ${current.lastActivity}`);
+}
+/**
+ * Handle handoff command
+ */
+/* istanbul ignore next -- CLI entry point */
+function handleHandoff(args) {
+    const current = readCurrentSession();
+    if (current) {
+        console.log(`${LOG_PREFIX} Stopping current session...`);
+        handleStop({ reason: `Handoff to ${args.agent || 'another agent'}` });
+    }
+    console.log(`\n${LOG_PREFIX} Starting new session for handoff...`);
+    handleStart(args);
+}
+/**
+ * Main entry point for session-coordinator command
+ */
+/* istanbul ignore next -- CLI entry point */
+async function main() {
+    const args = parseSessionArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    const validation = validateSessionCommand(args);
+    if (!validation.valid) {
+        console.error(`${LOG_PREFIX} Error: ${validation.error}`);
+        printHelp();
+        process.exit(EXIT_CODES.ERROR);
+    }
+    switch (args.command) {
+        case SessionCommand.START:
+            handleStart(args);
+            break;
+        case SessionCommand.STOP:
+            handleStop(args);
+            break;
+        case SessionCommand.STATUS:
+            handleStatus();
+            break;
+        case SessionCommand.HANDOFF:
+            handleHandoff(args);
+            break;
+        default:
+            console.error(`${LOG_PREFIX} Unknown command: ${args.command}`);
+            printHelp();
+            process.exit(EXIT_CODES.ERROR);
+    }
+}
+// Run main if executed directly
+if (import.meta.main) {
+    runCLI(main);
+}

package/dist/state-bootstrap.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+/**
+ * State Bootstrap Command
+ *
+ * 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
+ *
+ * Usage:
+ *   pnpm state:bootstrap           # Dry-run mode (shows what would be done)
+ *   pnpm state:bootstrap --execute # Apply changes
+ */
+import { readdirSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { readFileSync } from 'node:fs';
+import { CLI_FLAGS, EXIT_CODES, EMOJI, 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 = '[state-bootstrap]';
+/**
+ * Default configuration for state bootstrap
+ */
+export const STATE_BOOTSTRAP_DEFAULTS = {
+    /** Default WU directory path */
+    wuDir: 'docs/04-operations/tasks/wu',
+    /** Default state directory path */
+    stateDir: '.lumenflow/state',
+};
+/**
+ * Parse command line arguments for state-bootstrap
+ */
+export function parseStateBootstrapArgs(argv) {
+    const args = {
+        dryRun: true,
+        wuDir: STATE_BOOTSTRAP_DEFAULTS.wuDir,
+        stateDir: STATE_BOOTSTRAP_DEFAULTS.stateDir,
+        force: false,
+        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 === '--force') {
+            args.force = true;
+        }
+        else if (arg === '--wu-dir' && argv[i + 1]) {
+            args.wuDir = argv[++i];
+        }
+        else if (arg === '--state-dir' && argv[i + 1]) {
+            args.stateDir = argv[++i];
+        }
+    }
+    return args;
+}
+/**
+ * Convert a date string to ISO timestamp
+ * Falls back to start of day if only date is provided
+ */
+function toTimestamp(dateStr, fallback) {
+    if (!dateStr) {
+        if (fallback) {
+            return toTimestamp(fallback);
+        }
+        return new Date().toISOString();
+    }
+    // If already ISO format, return as-is
+    if (dateStr.includes('T')) {
+        return dateStr;
+    }
+    // Convert date-only to ISO timestamp at midnight UTC
+    const date = new Date(dateStr);
+    if (isNaN(date.getTime())) {
+        return new Date().toISOString();
+    }
+    return date.toISOString();
+}
+/**
+ * Infer events from a WU based on its current status
+ *
+ * Event generation rules:
+ * - ready: No events (WU not yet claimed)
+ * - in_progress: Generate claim event
+ * - blocked: Generate claim + block events
+ * - done/completed: Generate claim + complete events
+ */
+export function inferEventsFromWu(wu) {
+    const events = [];
+    // Ready WUs have no events (not yet in the lifecycle)
+    if (wu.status === 'ready' || wu.status === 'backlog' || wu.status === 'todo') {
+        return events;
+    }
+    // All other states start with a claim event
+    const claimTimestamp = toTimestamp(wu.claimed_at, wu.created);
+    events.push({
+        type: 'claim',
+        wuId: wu.id,
+        lane: wu.lane,
+        title: wu.title,
+        timestamp: claimTimestamp,
+    });
+    // Handle completed/done status
+    if (wu.status === 'done' || wu.status === 'completed') {
+        const completeTimestamp = toTimestamp(wu.completed_at, wu.created);
+        events.push({
+            type: 'complete',
+            wuId: wu.id,
+            timestamp: completeTimestamp,
+        });
+        return events;
+    }
+    // Handle blocked status
+    if (wu.status === 'blocked') {
+        // Block event timestamp should be after claim
+        // We don't have exact block time, so use claim time + 1 second
+        const claimDate = new Date(claimTimestamp);
+        claimDate.setSeconds(claimDate.getSeconds() + 1);
+        events.push({
+            type: 'block',
+            wuId: wu.id,
+            timestamp: claimDate.toISOString(),
+            reason: 'Bootstrapped from WU YAML (original reason unknown)',
+        });
+        return events;
+    }
+    // in_progress status already has claim event
+    return events;
+}
+/**
+ * Generate all bootstrap events from a list of WUs, ordered chronologically
+ */
+export function generateBootstrapEvents(wus) {
+    const allEvents = [];
+    for (const wu of wus) {
+        const events = inferEventsFromWu(wu);
+        allEvents.push(...events);
+    }
+    // Sort events chronologically
+    allEvents.sort((a, b) => {
+        const dateA = new Date(a.timestamp).getTime();
+        const dateB = new Date(b.timestamp).getTime();
+        return dateA - dateB;
+    });
+    return allEvents;
+}
+/**
+ * Load a WU YAML file and extract bootstrap info
+ */
+function loadWuYaml(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const doc = parseYaml(content);
+        if (!doc || typeof doc !== 'object' || !doc.id) {
+            return null;
+        }
+        return {
+            id: String(doc.id),
+            status: String(doc.status || 'ready'),
+            lane: String(doc.lane || 'Unknown'),
+            title: String(doc.title || 'Untitled'),
+            created: doc.created ? String(doc.created) : undefined,
+            claimed_at: doc.claimed_at ? String(doc.claimed_at) : undefined,
+            completed_at: doc.completed_at ? String(doc.completed_at) : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the state bootstrap migration
+ */
+export async function runStateBootstrap(args) {
+    const result = {
+        success: true,
+        eventsGenerated: 0,
+        eventsWritten: 0,
+        skipped: 0,
+        warnings: [],
+    };
+    // Check if WU directory exists
+    if (!existsSync(args.wuDir)) {
+        result.warnings.push('WU directory not found');
+        return result;
+    }
+    // Check if state file already exists
+    const stateFilePath = path.join(args.stateDir, 'wu-events.jsonl');
+    if (existsSync(stateFilePath) && !args.force && !args.dryRun) {
+        result.success = false;
+        result.error = `State file already exists: ${stateFilePath}. Use --force to overwrite.`;
+        return result;
+    }
+    // Load all WU YAML files
+    const wus = [];
+    const files = readdirSync(args.wuDir).filter((f) => f.endsWith('.yaml'));
+    for (const file of files) {
+        const filePath = path.join(args.wuDir, file);
+        const wu = loadWuYaml(filePath);
+        if (wu) {
+            wus.push(wu);
+        }
+        else {
+            result.skipped++;
+        }
+    }
+    // Generate events
+    const events = generateBootstrapEvents(wus);
+    result.eventsGenerated = events.length;
+    // In dry-run mode, don't write anything
+    if (args.dryRun) {
+        return result;
+    }
+    // Ensure state directory exists
+    mkdirSync(args.stateDir, { recursive: true });
+    // Write events to state file
+    const lines = events.map((event) => JSON.stringify(event));
+    const content = lines.length > 0 ? `${lines.join('\n')}\n` : '';
+    writeFileSync(stateFilePath, content, 'utf-8');
+    result.eventsWritten = events.length;
+    return result;
+}
+/**
+ * Print help text
+ */
+export function printHelp() {
+    console.log(`
+${LOG_PREFIX} State Bootstrap - One-time migration utility
+
+Usage:
+  pnpm state:bootstrap           # Dry-run mode (default, shows what would be done)
+  pnpm state:bootstrap --execute # Apply changes
+
+Options:
+  --execute                      Execute migration (default is dry-run)
+  --dry-run                      Show what would be done without making changes
+  --wu-dir <path>                WU YAML directory (default: ${STATE_BOOTSTRAP_DEFAULTS.wuDir})
+  --state-dir <path>             State store directory (default: ${STATE_BOOTSTRAP_DEFAULTS.stateDir})
+  --force                        Overwrite existing state file
+  --help, -h                     Show this help message
+
+This tool:
+  ${EMOJI.SUCCESS} Reads all WU YAML files from the WU directory
+  ${EMOJI.SUCCESS} Generates events based on WU status (claim, complete, block)
+  ${EMOJI.SUCCESS} Writes events to .lumenflow/state/wu-events.jsonl
+  ${EMOJI.WARNING} One-time migration - run only when setting up event-sourced state
+
+Supported WU statuses:
+  ready     -> No events (WU not yet claimed)
+  in_progress -> claim event
+  blocked   -> claim + block events
+  done      -> claim + complete events
+`);
+}
+/**
+ * Main function
+ */
+async function main() {
+    const args = parseStateBootstrapArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    console.log(`${LOG_PREFIX} State Bootstrap Migration`);
+    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}`);
+    }
+    console.log(`${LOG_PREFIX} WU directory: ${args.wuDir}`);
+    console.log(`${LOG_PREFIX} State directory: ${args.stateDir}${STRING_LITERALS.NEWLINE}`);
+    const result = await runStateBootstrap(args);
+    if (!result.success) {
+        console.error(`${LOG_PREFIX} ${EMOJI.FAILURE} ${result.error}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // Report warnings
+    for (const warning of result.warnings) {
+        console.log(`${LOG_PREFIX} ${EMOJI.WARNING} ${warning}`);
+    }
+    // Summary
+    console.log(`${STRING_LITERALS.NEWLINE}${LOG_PREFIX} Summary`);
+    console.log(`${LOG_PREFIX} ========`);
+    console.log(`${LOG_PREFIX} Events generated: ${result.eventsGenerated}`);
+    console.log(`${LOG_PREFIX} Events written: ${result.eventsWritten}`);
+    console.log(`${LOG_PREFIX} Files skipped: ${result.skipped}`);
+    if (args.dryRun && result.eventsGenerated > 0) {
+        console.log(`${STRING_LITERALS.NEWLINE}${LOG_PREFIX} ${EMOJI.INFO} This was a dry-run. Use --execute to apply changes.`);
+    }
+    else if (result.eventsWritten > 0) {
+        console.log(`${STRING_LITERALS.NEWLINE}${LOG_PREFIX} ${EMOJI.SUCCESS} State bootstrap complete!`);
+    }
+    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);
+}