@lumenflow/cli 2.7.0 → 2.9.0

package/dist/commands/integrate.js

@@ -0,0 +1,229 @@
+/**
+ * @file integrate.ts
+ * Integrate LumenFlow with Claude Code (WU-1367)
+ *
+ * This command generates enforcement hooks and updates Claude Code
+ * configuration based on .lumenflow.config.yaml settings.
+ *
+ * Usage:
+ *   pnpm lumenflow:integrate --client claude-code
+ */
+// CLI tool - console output is intentional for user feedback
+// fs operations use runtime-provided paths from LumenFlow configuration
+// Object injection sink warnings are false positives for array indexing
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core';
+import { generateEnforcementHooks, generateEnforceWorktreeScript, generateRequireWuScript, generateWarnIncompleteScript, } from '../hooks/enforcement-generator.js';
+/**
+ * CLI options for integrate command
+ */
+const INTEGRATE_OPTIONS = {
+    client: {
+        name: 'client',
+        flags: '--client <type>',
+        description: 'Client type to integrate (claude-code)',
+    },
+    force: WU_OPTIONS.force,
+};
+/**
+ * Parse command line options
+ */
+export function parseIntegrateOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-integrate',
+        description: 'Integrate LumenFlow enforcement with AI client tools',
+        options: Object.values(INTEGRATE_OPTIONS),
+    });
+    return {
+        client: opts.client ?? 'claude-code',
+        force: opts.force ?? false,
+    };
+}
+/**
+ * Read existing Claude settings.json
+ */
+function readClaudeSettings(projectDir) {
+    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+    if (!fs.existsSync(settingsPath)) {
+        return {
+            $schema: 'https://json.schemastore.org/claude-code-settings.json',
+            permissions: {
+                allow: ['Bash', 'Read', 'Write', 'Edit', 'WebFetch', 'WebSearch', 'Skill'],
+            },
+        };
+    }
+    try {
+        const content = fs.readFileSync(settingsPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return {
+            $schema: 'https://json.schemastore.org/claude-code-settings.json',
+        };
+    }
+}
+/**
+ * Merge generated hooks into existing settings
+ */
+// Complexity is acceptable for hook merging logic - alternative would over-abstract
+// eslint-disable-next-line sonarjs/cognitive-complexity
+function mergeHooksIntoSettings(existing, generated) {
+    const result = { ...existing };
+    if (!result.hooks) {
+        result.hooks = {};
+    }
+    // Merge PreToolUse hooks
+    if (generated.preToolUse) {
+        if (!result.hooks.PreToolUse) {
+            result.hooks.PreToolUse = [];
+        }
+        for (const newHook of generated.preToolUse) {
+            const existingIndex = result.hooks.PreToolUse.findIndex((h) => h.matcher === newHook.matcher);
+            if (existingIndex >= 0) {
+                const existing = result.hooks.PreToolUse[existingIndex];
+                for (const hook of newHook.hooks) {
+                    const isDuplicate = existing.hooks.some((h) => h.command === hook.command);
+                    if (!isDuplicate) {
+                        existing.hooks.push(hook);
+                    }
+                }
+            }
+            else {
+                result.hooks.PreToolUse.push(newHook);
+            }
+        }
+    }
+    // Merge Stop hooks
+    if (generated.stop) {
+        if (!result.hooks.Stop) {
+            result.hooks.Stop = [];
+        }
+        for (const newHook of generated.stop) {
+            const existingIndex = result.hooks.Stop.findIndex((h) => h.matcher === newHook.matcher);
+            if (existingIndex >= 0) {
+                const existing = result.hooks.Stop[existingIndex];
+                for (const hook of newHook.hooks) {
+                    const isDuplicate = existing.hooks.some((h) => h.command === hook.command);
+                    if (!isDuplicate) {
+                        existing.hooks.push(hook);
+                    }
+                }
+            }
+            else {
+                result.hooks.Stop.push(newHook);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Integrate Claude Code with LumenFlow enforcement hooks.
+ *
+ * This function:
+ * 1. Creates .claude/hooks directory if needed
+ * 2. Generates enforcement hook scripts
+ * 3. Updates .claude/settings.json with hook configuration
+ *
+ * @param projectDir - Project directory
+ * @param config - Client configuration with enforcement settings
+ */
+export async function integrateClaudeCode(projectDir, config) {
+    const enforcement = config.enforcement;
+    // Skip if enforcement not enabled
+    if (!enforcement?.hooks) {
+        console.log('[integrate] Enforcement hooks not enabled, skipping');
+        return;
+    }
+    const claudeDir = path.join(projectDir, '.claude');
+    const hooksDir = path.join(claudeDir, 'hooks');
+    // Create directories
+    if (!fs.existsSync(hooksDir)) {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        console.log('[integrate] Created .claude/hooks directory');
+    }
+    // Generate hooks based on config
+    const generatedHooks = generateEnforcementHooks({
+        block_outside_worktree: enforcement.block_outside_worktree ?? false,
+        require_wu_for_edits: enforcement.require_wu_for_edits ?? false,
+        warn_on_stop_without_wu_done: enforcement.warn_on_stop_without_wu_done ?? false,
+    });
+    // Write hook scripts
+    if (enforcement.block_outside_worktree) {
+        const scriptPath = path.join(hooksDir, 'enforce-worktree.sh');
+        fs.writeFileSync(scriptPath, generateEnforceWorktreeScript(), { mode: 0o755 });
+        console.log('[integrate] Generated enforce-worktree.sh');
+    }
+    if (enforcement.require_wu_for_edits) {
+        const scriptPath = path.join(hooksDir, 'require-wu.sh');
+        fs.writeFileSync(scriptPath, generateRequireWuScript(), { mode: 0o755 });
+        console.log('[integrate] Generated require-wu.sh');
+    }
+    if (enforcement.warn_on_stop_without_wu_done) {
+        const scriptPath = path.join(hooksDir, 'warn-incomplete.sh');
+        fs.writeFileSync(scriptPath, generateWarnIncompleteScript(), { mode: 0o755 });
+        console.log('[integrate] Generated warn-incomplete.sh');
+    }
+    // Update settings.json
+    const existingSettings = readClaudeSettings(projectDir);
+    const updatedSettings = mergeHooksIntoSettings(existingSettings, generatedHooks);
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    fs.writeFileSync(settingsPath, JSON.stringify(updatedSettings, null, 2) + '\n', 'utf-8');
+    console.log('[integrate] Updated .claude/settings.json');
+}
+/**
+ * Read enforcement config from .lumenflow.config.yaml
+ */
+function readEnforcementConfig(projectDir) {
+    const configPath = path.join(projectDir, '.lumenflow.config.yaml');
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const config = yaml.parse(content);
+        return config?.agents?.clients?.['claude-code']?.enforcement ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Main entry point for integrate command
+ */
+export async function main() {
+    const opts = parseIntegrateOptions();
+    if (opts.client !== 'claude-code') {
+        console.error(`[integrate] Unsupported client: ${opts.client}`);
+        console.error('[integrate] Currently only "claude-code" is supported');
+        process.exit(1);
+    }
+    const projectDir = process.cwd();
+    // Read enforcement config from .lumenflow.config.yaml
+    const enforcement = readEnforcementConfig(projectDir);
+    if (!enforcement) {
+        console.log('[integrate] No enforcement config found in .lumenflow.config.yaml');
+        console.log('[integrate] Add this to your config to enable enforcement hooks:');
+        console.log(`
+agents:
+  clients:
+    claude-code:
+      enforcement:
+        hooks: true
+        block_outside_worktree: true
+        require_wu_for_edits: true
+        warn_on_stop_without_wu_done: true
+`);
+        return;
+    }
+    await integrateClaudeCode(projectDir, { enforcement });
+    console.log('[integrate] Claude Code integration complete');
+}
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((err) => {
+        console.error('[integrate] Error:', err.message);
+        process.exit(1);
+    });
+}

package/dist/commands.js

@@ -0,0 +1,171 @@
+/**
+ * @file commands.ts
+ * LumenFlow CLI commands discovery feature (WU-1378)
+ *
+ * Provides a way to discover all available CLI commands grouped by category.
+ * This helps agents and users find CLI workflows without reading docs.
+ */
+import { createWUParser } from '@lumenflow/core';
+import { runCLI } from './cli-entry-point.js';
+/**
+ * Command categories organized by function
+ * Based on quick-ref-commands.md structure
+ */
+const COMMAND_CATEGORIES = [
+    {
+        name: 'WU Lifecycle',
+        commands: [
+            { name: 'wu:create', description: 'Create new WU spec' },
+            { name: 'wu:claim', description: 'Claim WU and create worktree' },
+            { name: 'wu:prep', description: 'Run gates in worktree, prep for wu:done' },
+            { name: 'wu:done', description: 'Complete WU (merge, stamp, cleanup) from main' },
+            { name: 'wu:edit', description: 'Edit WU spec fields' },
+            { name: 'wu:block', description: 'Block WU with reason' },
+            { name: 'wu:unblock', description: 'Unblock WU' },
+            { name: 'wu:release', description: 'Release orphaned WU (in_progress to ready)' },
+            { name: 'wu:status', description: 'Show WU status, location, valid commands' },
+            { name: 'wu:spawn', description: 'Generate sub-agent spawn prompt' },
+            { name: 'wu:validate', description: 'Validate WU spec' },
+            { name: 'wu:recover', description: 'Analyze and fix WU state inconsistencies' },
+        ],
+    },
+    {
+        name: 'Gates & Quality',
+        commands: [
+            { name: 'gates', description: 'Run all quality gates' },
+            { name: 'format', description: 'Format all files (Prettier)' },
+            { name: 'lint', description: 'Run ESLint' },
+            { name: 'typecheck', description: 'Run TypeScript type checking' },
+            { name: 'test', description: 'Run all tests (Vitest)' },
+            { name: 'lane:health', description: 'Check lane config health' },
+        ],
+    },
+    {
+        name: 'Memory & Sessions',
+        commands: [
+            { name: 'mem:init', description: 'Initialize memory for WU' },
+            { name: 'mem:checkpoint', description: 'Save progress checkpoint' },
+            { name: 'mem:signal', description: 'Broadcast coordination signal' },
+            { name: 'mem:inbox', description: 'Check coordination signals' },
+            { name: 'mem:create', description: 'Create memory node (bug discovery)' },
+            { name: 'mem:context', description: 'Get context for current lane/WU' },
+        ],
+    },
+    {
+        name: 'Initiatives',
+        commands: [
+            { name: 'initiative:create', description: 'Create new initiative' },
+            { name: 'initiative:edit', description: 'Edit initiative fields' },
+            { name: 'initiative:list', description: 'List all initiatives' },
+            { name: 'initiative:status', description: 'Show initiative status' },
+            { name: 'initiative:add-wu', description: 'Add WU to initiative' },
+        ],
+    },
+    {
+        name: 'Orchestration',
+        commands: [
+            { name: 'orchestrate:initiative', description: 'Orchestrate initiative execution' },
+            { name: 'orchestrate:init-status', description: 'Compact initiative progress view' },
+            { name: 'orchestrate:monitor', description: 'Monitor spawn/agent activity' },
+            { name: 'spawn:list', description: 'List active spawned agents' },
+        ],
+    },
+    {
+        name: 'Setup & Development',
+        commands: [
+            { name: 'setup', description: 'Install deps and build CLI (first time)' },
+            { name: 'lumenflow', description: 'Initialize LumenFlow in a project' },
+            { name: 'lumenflow:doctor', description: 'Diagnose LumenFlow configuration' },
+            { name: 'lumenflow:upgrade', description: 'Upgrade LumenFlow packages' },
+            { name: 'docs:sync', description: 'Sync agent docs (for upgrades)' },
+        ],
+    },
+    {
+        name: 'Metrics & Flow',
+        commands: [
+            { name: 'flow:report', description: 'Generate flow metrics report' },
+            { name: 'flow:bottlenecks', description: 'Identify flow bottlenecks' },
+            { name: 'metrics:snapshot', description: 'Capture metrics snapshot' },
+        ],
+    },
+    {
+        name: 'State Management',
+        commands: [
+            { name: 'state:doctor', description: 'Diagnose state store issues' },
+            { name: 'state:cleanup', description: 'Clean up stale state data' },
+            { name: 'state:bootstrap', description: 'Bootstrap state store' },
+        ],
+    },
+];
+/**
+ * Get the complete commands registry
+ * @returns Array of command categories with their commands
+ */
+export function getCommandsRegistry() {
+    return COMMAND_CATEGORIES;
+}
+/**
+ * Format commands output for terminal display
+ * @returns Formatted string with all commands grouped by category
+ */
+export function formatCommandsOutput() {
+    const lines = [];
+    lines.push('LumenFlow CLI Commands');
+    lines.push('======================');
+    lines.push('');
+    for (const category of COMMAND_CATEGORIES) {
+        lines.push(`## ${category.name}`);
+        lines.push('');
+        // Find the longest command name for alignment
+        const maxNameLength = Math.max(...category.commands.map((cmd) => cmd.name.length));
+        for (const cmd of category.commands) {
+            const padding = ' '.repeat(maxNameLength - cmd.name.length + 2);
+            lines.push(`  ${cmd.name}${padding}${cmd.description}`);
+        }
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push('Tip: Run `pnpm <command> --help` for detailed options.');
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * CLI option definitions for commands command
+ */
+const COMMANDS_OPTIONS = {
+    json: {
+        name: 'json',
+        flags: '--json',
+        description: 'Output commands as JSON',
+    },
+};
+/**
+ * Parse commands command options using createWUParser
+ */
+export function parseCommandsOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-commands',
+        description: 'List all available LumenFlow CLI commands',
+        options: Object.values(COMMANDS_OPTIONS),
+    });
+    return {
+        json: opts.json ?? false,
+    };
+}
+/**
+ * Main function for the commands CLI
+ */
+export async function main() {
+    const opts = parseCommandsOptions();
+    if (opts.json) {
+        console.log(JSON.stringify(getCommandsRegistry(), null, 2));
+    }
+    else {
+        console.log(formatCommandsOutput());
+    }
+}
+// CLI entry point
+// WU-1071: Use import.meta.main for proper CLI detection with pnpm symlinks
+if (import.meta.main) {
+    runCLI(main);
+}

package/dist/docs-sync.js

@@ -3,11 +3,14 @@
  * LumenFlow docs:sync command for syncing agent docs to existing projects (WU-1083)
  * WU-1085: Added createWUParser for proper --help support
  * WU-1124: Refactored to read templates from bundled files (INIT-004 Phase 2)
+ * WU-1362: Added branch guard to check branch before writing tracked files
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core';
+// WU-1362: Import worktree guard utilities for branch checking
+import { isMainBranch, isInWorktree } from '@lumenflow/core/dist/core/worktree-guard.js';
 /**
  * WU-1085: CLI option definitions for docs-sync command
  */
@@ -182,9 +185,45 @@ export async function syncSkills(targetDir, options) {
     }
     return result;
 }
+/**
+ * WU-1362: Check branch guard before writing tracked files
+ *
+ * Warns (but does not block) if:
+ * - On main branch AND
+ * - Not in a worktree directory AND
+ * - Git repository exists (has .git)
+ *
+ * @param targetDir - Directory where files will be written
+ * @returns Array of warning messages
+ */
+async function checkBranchGuard(targetDir) {
+    const warnings = [];
+    // Only check if target is a git repository
+    const gitDir = path.join(targetDir, '.git');
+    if (!fs.existsSync(gitDir)) {
+        return warnings;
+    }
+    // Check if we're in a worktree (always allow)
+    if (isInWorktree({ cwd: targetDir })) {
+        return warnings;
+    }
+    // Check if on main branch
+    try {
+        const onMain = await isMainBranch();
+        if (onMain) {
+            warnings.push('Running docs:sync on main branch in main checkout. ' +
+                'Consider using a worktree for changes to tracked files.');
+        }
+    }
+    catch {
+        // Git error - silently allow
+    }
+    return warnings;
+}
 /**
  * CLI entry point for docs:sync command
  * WU-1085: Updated to use parseDocsSyncOptions for proper --help support
+ * WU-1362: Added branch guard check
  */
 export async function main() {
     const opts = parseDocsSyncOptions();
@@ -192,10 +231,13 @@ export async function main() {
     console.log('[lumenflow docs:sync] Syncing agent documentation...');
     console.log(`  Vendor: ${opts.vendor}`);
     console.log(`  Force: ${opts.force}`);
+    // WU-1362: Check branch guard before writing files
+    const branchWarnings = await checkBranchGuard(targetDir);
     const docsResult = await syncAgentDocs(targetDir, { force: opts.force });
     const skillsResult = await syncSkills(targetDir, { force: opts.force, vendor: opts.vendor });
     const created = [...docsResult.created, ...skillsResult.created];
     const skipped = [...docsResult.skipped, ...skillsResult.skipped];
+    const warnings = [...branchWarnings];
     if (created.length > 0) {
         console.log('\nCreated:');
         created.forEach((f) => console.log(`  + ${f}`));
@@ -204,6 +246,10 @@ export async function main() {
         console.log('\nSkipped (already exists, use --force to overwrite):');
         skipped.forEach((f) => console.log(`  - ${f}`));
     }
+    if (warnings.length > 0) {
+        console.log('\nWarnings:');
+        warnings.forEach((w) => console.log(`  ! ${w}`));
+    }
     console.log('\n[lumenflow docs:sync] Done!');
 }
 // CLI entry point (WU-1071 pattern: import.meta.main)