@lumenflow/cli 1.6.0 → 2.1.0

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);
+}

package/dist/sync-templates.js

@@ -0,0 +1,212 @@
+/**
+ * @file sync-templates.ts
+ * Sync internal docs to CLI templates for release-cycle maintenance (WU-1123)
+ *
+ * This script syncs source docs from the hellmai/os repo to the templates
+ * directory, applying template variable substitutions:
+ * - Onboarding docs -> templates/core/ai/onboarding/
+ * - Claude skills -> templates/vendors/claude/.claude/skills/
+ * - Core docs (LUMENFLOW.md, constraints.md) -> templates/core/
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createWUParser } from '@lumenflow/core';
+// Template variable patterns
+const DATE_PATTERN = /\d{4}-\d{2}-\d{2}/g;
+/**
+ * CLI option definitions for sync-templates command
+ */
+const SYNC_TEMPLATES_OPTIONS = {
+    dryRun: {
+        name: 'dry-run',
+        flags: '--dry-run',
+        description: 'Show what would be synced without writing files',
+        default: false,
+    },
+    verbose: {
+        name: 'verbose',
+        flags: '--verbose',
+        description: 'Show detailed output',
+        default: false,
+    },
+};
+/**
+ * Parse sync-templates command options
+ */
+export function parseSyncTemplatesOptions() {
+    const opts = createWUParser({
+        name: 'sync-templates',
+        description: 'Sync internal docs to CLI templates for release-cycle maintenance',
+        options: Object.values(SYNC_TEMPLATES_OPTIONS),
+    });
+    return {
+        dryRun: opts['dry-run'] ?? false,
+        verbose: opts.verbose ?? false,
+    };
+}
+/**
+ * Convert source content to template format by replacing:
+ * - YYYY-MM-DD dates with {{DATE}}
+ * - Absolute project paths with {{PROJECT_ROOT}}
+ */
+export function convertToTemplate(content, projectRoot) {
+    let output = content;
+    // Replace dates with {{DATE}}
+    output = output.replace(DATE_PATTERN, '{{DATE}}');
+    // Replace absolute project paths with {{PROJECT_ROOT}}
+    // Escape special regex characters in the path
+    const escapedPath = projectRoot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pathPattern = new RegExp(escapedPath, 'g');
+    output = output.replace(pathPattern, '{{PROJECT_ROOT}}');
+    return output;
+}
+/**
+ * Get the templates directory path
+ */
+function getTemplatesDir(projectRoot) {
+    return path.join(projectRoot, 'packages', '@lumenflow', 'cli', 'templates');
+}
+/**
+ * Ensure directory exists
+ */
+function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Sync a single file to templates
+ */
+function syncFile(sourcePath, targetPath, projectRoot, result, dryRun = false) {
+    try {
+        if (!fs.existsSync(sourcePath)) {
+            result.errors.push(`Source not found: ${sourcePath}`);
+            return;
+        }
+        const content = fs.readFileSync(sourcePath, 'utf-8');
+        const templateContent = convertToTemplate(content, projectRoot);
+        if (!dryRun) {
+            ensureDir(path.dirname(targetPath));
+            fs.writeFileSync(targetPath, templateContent);
+        }
+        result.synced.push(path.relative(projectRoot, targetPath));
+    }
+    catch (error) {
+        result.errors.push(`Error syncing ${sourcePath}: ${error.message}`);
+    }
+}
+/**
+ * Sync onboarding docs to templates/core/ai/onboarding/
+ */
+export async function syncOnboardingDocs(projectRoot, dryRun = false) {
+    const result = { synced: [], errors: [] };
+    const sourceDir = path.join(projectRoot, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+    const targetDir = path.join(getTemplatesDir(projectRoot), 'core', 'ai', 'onboarding');
+    if (!fs.existsSync(sourceDir)) {
+        result.errors.push(`Onboarding source directory not found: ${sourceDir}`);
+        return result;
+    }
+    const files = fs.readdirSync(sourceDir).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+        const sourcePath = path.join(sourceDir, file);
+        const targetPath = path.join(targetDir, `${file}.template`);
+        syncFile(sourcePath, targetPath, projectRoot, result, dryRun);
+    }
+    return result;
+}
+/**
+ * Sync Claude skills to templates/vendors/claude/.claude/skills/
+ */
+export async function syncSkillsToTemplates(projectRoot, dryRun = false) {
+    const result = { synced: [], errors: [] };
+    const sourceDir = path.join(projectRoot, '.claude', 'skills');
+    const targetDir = path.join(getTemplatesDir(projectRoot), 'vendors', 'claude', '.claude', 'skills');
+    if (!fs.existsSync(sourceDir)) {
+        result.errors.push(`Skills source directory not found: ${sourceDir}`);
+        return result;
+    }
+    // Get all skill directories
+    const skillDirs = fs
+        .readdirSync(sourceDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    for (const skillName of skillDirs) {
+        const skillSourceDir = path.join(sourceDir, skillName);
+        const skillTargetDir = path.join(targetDir, skillName);
+        // Look for SKILL.md file
+        const skillFile = path.join(skillSourceDir, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+            const targetPath = path.join(skillTargetDir, 'SKILL.md.template');
+            syncFile(skillFile, targetPath, projectRoot, result, dryRun);
+        }
+    }
+    return result;
+}
+/**
+ * Sync core docs (LUMENFLOW.md, constraints.md) to templates/core/
+ */
+export async function syncCoreDocs(projectRoot, dryRun = false) {
+    const result = { synced: [], errors: [] };
+    const templatesDir = getTemplatesDir(projectRoot);
+    // Sync LUMENFLOW.md
+    const lumenflowSource = path.join(projectRoot, 'LUMENFLOW.md');
+    const lumenflowTarget = path.join(templatesDir, 'core', 'LUMENFLOW.md.template');
+    syncFile(lumenflowSource, lumenflowTarget, projectRoot, result, dryRun);
+    // Sync constraints.md
+    const constraintsSource = path.join(projectRoot, '.lumenflow', 'constraints.md');
+    const constraintsTarget = path.join(templatesDir, 'core', '.lumenflow', 'constraints.md.template');
+    syncFile(constraintsSource, constraintsTarget, projectRoot, result, dryRun);
+    return result;
+}
+/**
+ * Sync all templates
+ */
+export async function syncTemplates(projectRoot, dryRun = false) {
+    const onboarding = await syncOnboardingDocs(projectRoot, dryRun);
+    const skills = await syncSkillsToTemplates(projectRoot, dryRun);
+    const core = await syncCoreDocs(projectRoot, dryRun);
+    return { onboarding, skills, core };
+}
+/**
+ * CLI entry point
+ */
+export async function main() {
+    const opts = parseSyncTemplatesOptions();
+    const projectRoot = process.cwd();
+    console.log('[sync-templates] Syncing internal docs to CLI templates...');
+    if (opts.dryRun) {
+        console.log('  (dry-run mode - no files will be written)');
+    }
+    const result = await syncTemplates(projectRoot, opts.dryRun);
+    // Print results
+    const sections = [
+        { name: 'Onboarding docs', data: result.onboarding },
+        { name: 'Claude skills', data: result.skills },
+        { name: 'Core docs', data: result.core },
+    ];
+    let totalSynced = 0;
+    let totalErrors = 0;
+    for (const section of sections) {
+        if (section.data.synced.length > 0 || section.data.errors.length > 0) {
+            console.log(`\n${section.name}:`);
+            if (section.data.synced.length > 0) {
+                section.data.synced.forEach((f) => console.log(`  + ${f}`));
+                totalSynced += section.data.synced.length;
+            }
+            if (section.data.errors.length > 0) {
+                section.data.errors.forEach((e) => console.log(`  ! ${e}`));
+                totalErrors += section.data.errors.length;
+            }
+        }
+    }
+    console.log(`\n[sync-templates] Done! Synced ${totalSynced} files.`);
+    if (totalErrors > 0) {
+        console.log(`  ${totalErrors} error(s) occurred.`);
+        process.exitCode = 1;
+    }
+}
+// CLI entry point
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    runCLI(main);
+}