@lumenflow/cli 2.6.0 → 2.8.0

package/dist/__tests__/wu-proto.test.js

@@ -0,0 +1,97 @@
+/**
+ * @file wu-proto.test.ts
+ * Test suite for wu:proto command (WU-1359)
+ *
+ * WU-1359: Add wu:proto convenience command for rapid prototyping
+ *
+ * Tests:
+ * - wu:proto creates WU with type: prototype
+ * - wu:proto has relaxed validation (no --acceptance required)
+ * - wu:proto immediately claims the WU
+ * - wu:proto prints cd command to worktree
+ */
+import { describe, it, expect } from 'vitest';
+// WU-1359: Import wu:proto validation and helpers
+import { validateProtoSpec } from '../wu-proto.js';
+/** Test constants to avoid duplicate string literals (sonarjs/no-duplicate-string) */
+const TEST_WU_ID = 'WU-9999';
+const TEST_LANE = 'Framework: CLI';
+const TEST_TITLE = 'Quick prototype';
+const TEST_DESCRIPTION = 'Context: testing.\nProblem: need to test.\nSolution: add tests.';
+describe('wu:proto command (WU-1359)', () => {
+    describe('validateProtoSpec relaxed validation', () => {
+        it('should pass validation without --acceptance', () => {
+            const result = validateProtoSpec({
+                id: TEST_WU_ID,
+                lane: TEST_LANE,
+                title: TEST_TITLE,
+                opts: {
+                    description: TEST_DESCRIPTION,
+                    codePaths: ['packages/@lumenflow/cli/src/wu-proto.ts'],
+                },
+            });
+            expect(result.valid).toBe(true);
+            expect(result.errors).toHaveLength(0);
+        });
+        it('should pass validation without --exposure', () => {
+            const result = validateProtoSpec({
+                id: TEST_WU_ID,
+                lane: TEST_LANE,
+                title: TEST_TITLE,
+                opts: {
+                    description: TEST_DESCRIPTION,
+                },
+            });
+            expect(result.valid).toBe(true);
+            expect(result.errors).toHaveLength(0);
+        });
+        it('should pass validation without --code-paths', () => {
+            const result = validateProtoSpec({
+                id: TEST_WU_ID,
+                lane: TEST_LANE,
+                title: TEST_TITLE,
+                opts: {
+                    description: TEST_DESCRIPTION,
+                },
+            });
+            expect(result.valid).toBe(true);
+            expect(result.errors).toHaveLength(0);
+        });
+        it('should require lane', () => {
+            const result = validateProtoSpec({
+                id: TEST_WU_ID,
+                lane: '',
+                title: TEST_TITLE,
+                opts: {},
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.toLowerCase().includes('lane'))).toBe(true);
+        });
+        it('should require title', () => {
+            const result = validateProtoSpec({
+                id: TEST_WU_ID,
+                lane: TEST_LANE,
+                title: '',
+                opts: {},
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.toLowerCase().includes('title'))).toBe(true);
+        });
+    });
+    describe('prototype WU type', () => {
+        it('should set type to prototype', () => {
+            // The buildProtoWUContent function should return type: prototype
+            // We test this indirectly through the validateProtoSpec which checks content
+            const result = validateProtoSpec({
+                id: TEST_WU_ID,
+                lane: TEST_LANE,
+                title: TEST_TITLE,
+                opts: {
+                    description: TEST_DESCRIPTION,
+                },
+            });
+            // Prototype WUs should always be valid with minimal input
+            expect(result.valid).toBe(true);
+        });
+    });
+});

package/dist/backlog-prune.js

@@ -17,7 +17,6 @@ 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]';
 /**

package/dist/cli-entry-point.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-console -- CLI entry point uses console for error output */
 /**
  * Shared CLI entry point wrapper
  *

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) => {