@lumenflow/cli 2.7.0 → 2.8.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/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)

package/dist/doctor.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-console -- CLI command uses console for status output */
 /**
  * @file doctor.ts
  * LumenFlow health check command (WU-1177)
@@ -167,7 +166,6 @@ function getCommandVersion(command, args) {
  * Parse semver version string to compare
  */
 function parseVersion(versionStr) {
-    // eslint-disable-next-line sonarjs/slow-regex, sonarjs/prefer-regexp-exec -- Simple semver extraction, no backtracking risk
     const match = versionStr.match(/(\d+)\.(\d+)\.?(\d+)?/);
     if (!match) {
         return [0, 0, 0];

package/dist/gates.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-/* eslint-disable no-console -- Gates runner uses console for status output; refactoring to logger is tracked for future work */
 /**
  * Quality Gates Runner
  *
@@ -469,7 +468,6 @@ export function formatFormatCheckGuidance(files) {
 function collectPrettierListDifferent(cwd, files = []) {
     const filesArg = files.length > 0 ? quoteShellArgs(files) : '.';
     const cmd = pnpmCmd(SCRIPTS.PRETTIER, PRETTIER_ARGS.LIST_DIFFERENT, filesArg);
-    // eslint-disable-next-line sonarjs/os-command -- Pre-existing: executes trusted pnpm prettier command
     const result = spawnSync(cmd, [], {
         shell: true,
         cwd,
@@ -534,7 +532,6 @@ function run(cmd, { agentLog } = {}) {
     if (!agentLog) {
         console.log(`\n> ${cmd}\n`);
         try {
-            // eslint-disable-next-line sonarjs/os-command -- Pre-existing: cmd is built from trusted constants
             execSync(cmd, { stdio: 'inherit', encoding: FILE_SYSTEM.ENCODING });
             return { ok: true, duration: Date.now() - start };
         }
@@ -543,7 +540,6 @@ function run(cmd, { agentLog } = {}) {
         }
     }
     writeSync(agentLog.logFd, `\n> ${cmd}\n\n`);
-    // eslint-disable-next-line sonarjs/os-command -- Pre-existing: cmd is built from trusted constants
     const result = spawnSync(cmd, [], {
         shell: true,
         stdio: ['ignore', agentLog.logFd, agentLog.logFd],
@@ -704,13 +700,11 @@ async function runFormatCheckGate({ agentLog, useAgentMode }) {
         return { ok: true, duration: Date.now() - start, fileCount: 0, filesChecked: [] };
     }
     if (plan.mode === 'full') {
-        /* eslint-disable sonarjs/no-nested-conditional -- Pre-existing: simple reason mapping, readable as-is */
         const reason = plan.reason === 'prettier-config'
             ? ' (prettier config changed)'
             : plan.reason === 'file-list-error'
                 ? ' (file list unavailable)'
                 : '';
-        /* eslint-enable sonarjs/no-nested-conditional */
         logLine(`📋 Running full format check${reason}`);
         const result = run(pnpmCmd(SCRIPTS.FORMAT_CHECK), { agentLog });
         return { ...result, duration: Date.now() - start, fileCount: -1 };
@@ -1408,7 +1402,6 @@ async function executeGates(opts) {
 // 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) {
-    // eslint-disable-next-line sonarjs/deprecation -- Pre-existing: parseGatesArgs kept for backwards compatibility
     const opts = parseGatesArgs();
     executeGates({ ...opts, argv: process.argv.slice(2) })
         .then((ok) => {

package/dist/hooks/enforcement-checks.js

@@ -0,0 +1,209 @@
+/**
+ * @file enforcement-checks.ts
+ * Runtime enforcement checks for LumenFlow workflow compliance (WU-1367)
+ *
+ * These functions can be used by hooks to validate operations.
+ * All checks implement graceful degradation: if state cannot be
+ * determined, operations are allowed.
+ */
+// Note: fs operations use runtime-provided paths from LumenFlow configuration
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Check if a Write/Edit operation should be allowed based on worktree enforcement.
+ *
+ * Implements graceful degradation: if LumenFlow state cannot be determined,
+ * the operation is allowed to prevent blocking legitimate work.
+ *
+ * @param input - Tool input with file_path and tool_name
+ * @param projectDir - Project directory (defaults to CLAUDE_PROJECT_DIR)
+ * @returns Check result with allowed status and reason
+ */
+export async function checkWorktreeEnforcement(input, projectDir) {
+    const mainRepoPath = projectDir ?? process.env.CLAUDE_PROJECT_DIR;
+    // Graceful degradation: no project dir
+    if (!mainRepoPath) {
+        return {
+            allowed: true,
+            reason: 'graceful: CLAUDE_PROJECT_DIR not set',
+        };
+    }
+    const lumenflowDir = path.join(mainRepoPath, '.lumenflow');
+    const worktreesDir = path.join(mainRepoPath, 'worktrees');
+    // Graceful degradation: LumenFlow not configured
+    if (!fs.existsSync(lumenflowDir)) {
+        return {
+            allowed: true,
+            reason: 'graceful: LumenFlow not configured',
+        };
+    }
+    // No worktrees = no enforcement needed
+    if (!fs.existsSync(worktreesDir)) {
+        return {
+            allowed: true,
+            reason: 'no worktrees exist',
+        };
+    }
+    // Check for active worktrees
+    let worktreeCount = 0;
+    try {
+        const entries = fs.readdirSync(worktreesDir);
+        worktreeCount = entries.filter((e) => {
+            const stat = fs.statSync(path.join(worktreesDir, e));
+            return stat.isDirectory();
+        }).length;
+    }
+    catch {
+        return {
+            allowed: true,
+            reason: 'graceful: cannot read worktrees directory',
+        };
+    }
+    if (worktreeCount === 0) {
+        return {
+            allowed: true,
+            reason: 'no active worktrees',
+        };
+    }
+    // Resolve the file path
+    let resolvedPath;
+    try {
+        resolvedPath = path.resolve(input.file_path);
+    }
+    catch {
+        return {
+            allowed: true,
+            reason: 'graceful: cannot resolve file path',
+        };
+    }
+    // Allow if path is inside a worktree
+    if (resolvedPath.startsWith(worktreesDir + path.sep)) {
+        return {
+            allowed: true,
+            reason: 'path is inside worktree',
+        };
+    }
+    // Block if path is in main repo while worktrees exist
+    if (resolvedPath.startsWith(mainRepoPath + path.sep) || resolvedPath === mainRepoPath) {
+        const activeWorktrees = fs
+            .readdirSync(worktreesDir)
+            .filter((e) => fs.statSync(path.join(worktreesDir, e)).isDirectory())
+            .slice(0, 5)
+            .join(', ');
+        return {
+            allowed: false,
+            reason: `cannot write to main repo while worktrees exist (${activeWorktrees})`,
+            suggestion: 'cd to your worktree: cd worktrees/<lane>-wu-<id>/',
+        };
+    }
+    // Path is outside repo entirely - allow
+    return {
+        allowed: true,
+        reason: 'path is outside repository',
+    };
+}
+/**
+ * Check if a Write/Edit operation should be allowed based on WU requirement.
+ *
+ * @param input - Tool input with file_path and tool_name
+ * @param projectDir - Project directory
+ * @returns Check result with allowed status and reason
+ */
+export async function checkWuRequirement(input, projectDir) {
+    const mainRepoPath = projectDir ?? process.env.CLAUDE_PROJECT_DIR;
+    if (!mainRepoPath) {
+        return {
+            allowed: true,
+            reason: 'graceful: CLAUDE_PROJECT_DIR not set',
+        };
+    }
+    const lumenflowDir = path.join(mainRepoPath, '.lumenflow');
+    const worktreesDir = path.join(mainRepoPath, 'worktrees');
+    const stateFile = path.join(lumenflowDir, 'state', 'wu-events.jsonl');
+    // Graceful degradation: LumenFlow not configured
+    if (!fs.existsSync(lumenflowDir)) {
+        return {
+            allowed: true,
+            reason: 'graceful: LumenFlow not configured',
+        };
+    }
+    // Check for active worktrees (indicates claimed WU)
+    if (fs.existsSync(worktreesDir)) {
+        try {
+            const entries = fs.readdirSync(worktreesDir);
+            const worktreeCount = entries.filter((e) => {
+                const stat = fs.statSync(path.join(worktreesDir, e));
+                return stat.isDirectory();
+            }).length;
+            if (worktreeCount > 0) {
+                return {
+                    allowed: true,
+                    reason: 'has active worktree (claimed WU)',
+                };
+            }
+        }
+        catch {
+            // Continue to state file check
+        }
+    }
+    // Check state file for in_progress WUs
+    if (fs.existsSync(stateFile)) {
+        try {
+            const content = fs.readFileSync(stateFile, 'utf-8');
+            if (content.includes('"status":"in_progress"')) {
+                return {
+                    allowed: true,
+                    reason: 'has in_progress WU in state',
+                };
+            }
+        }
+        catch {
+            return {
+                allowed: true,
+                reason: 'graceful: cannot read state file',
+            };
+        }
+    }
+    // No claimed WU found
+    return {
+        allowed: false,
+        reason: 'no WU claimed',
+        suggestion: 'pnpm wu:claim --id WU-XXXX --lane <Lane>',
+    };
+}
+/**
+ * Check if the current working directory is inside a worktree.
+ *
+ * @param cwd - Current working directory
+ * @param projectDir - Project directory
+ * @returns True if cwd is inside a worktree
+ */
+export function isInsideWorktree(cwd, projectDir) {
+    const worktreesDir = path.join(projectDir, 'worktrees');
+    if (!fs.existsSync(worktreesDir)) {
+        return false;
+    }
+    const resolvedCwd = path.resolve(cwd);
+    return resolvedCwd.startsWith(worktreesDir + path.sep);
+}
+/**
+ * Get list of active worktrees.
+ *
+ * @param projectDir - Project directory
+ * @returns Array of worktree names
+ */
+export function getActiveWorktrees(projectDir) {
+    const worktreesDir = path.join(projectDir, 'worktrees');
+    if (!fs.existsSync(worktreesDir)) {
+        return [];
+    }
+    try {
+        return fs.readdirSync(worktreesDir).filter((e) => {
+            const stat = fs.statSync(path.join(worktreesDir, e));
+            return stat.isDirectory();
+        });
+    }
+    catch {
+        return [];
+    }
+}