@lumenflow/cli 2.7.0 → 2.8.0

package/dist/hooks/enforcement-generator.js

@@ -0,0 +1,365 @@
+/**
+ * @file enforcement-generator.ts
+ * Generates Claude Code enforcement hooks based on configuration (WU-1367)
+ *
+ * This module generates hook configurations that can be written to
+ * .claude/settings.json to enforce LumenFlow workflow compliance.
+ */
+/**
+ * Generate enforcement hooks based on configuration.
+ *
+ * @param config - Enforcement configuration
+ * @returns Generated hooks structure for settings.json
+ */
+export function generateEnforcementHooks(config) {
+    const hooks = {};
+    const preToolUseHooks = [];
+    // Generate PreToolUse hooks for Write/Edit operations
+    if (config.block_outside_worktree || config.require_wu_for_edits) {
+        const writeEditHooks = [];
+        if (config.block_outside_worktree) {
+            writeEditHooks.push({
+                type: 'command',
+                command: '$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree.sh',
+            });
+        }
+        if (config.require_wu_for_edits) {
+            writeEditHooks.push({
+                type: 'command',
+                command: '$CLAUDE_PROJECT_DIR/.claude/hooks/require-wu.sh',
+            });
+        }
+        if (writeEditHooks.length > 0) {
+            preToolUseHooks.push({
+                matcher: 'Write|Edit',
+                hooks: writeEditHooks,
+            });
+        }
+    }
+    if (preToolUseHooks.length > 0) {
+        hooks.preToolUse = preToolUseHooks;
+    }
+    // Generate Stop hook for session completion warning
+    if (config.warn_on_stop_without_wu_done) {
+        hooks.stop = [
+            {
+                matcher: '.*',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: '$CLAUDE_PROJECT_DIR/.claude/hooks/warn-incomplete.sh',
+                    },
+                ],
+            },
+        ];
+    }
+    return hooks;
+}
+/**
+ * Generate the enforce-worktree.sh hook script content.
+ *
+ * This hook blocks Write/Edit operations when not in a worktree.
+ * Implements graceful degradation: allows operations if LumenFlow
+ * state cannot be determined.
+ */
+export function generateEnforceWorktreeScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# enforce-worktree.sh (WU-1367)
+#
+# PreToolUse hook that blocks Write/Edit when not in a worktree.
+# Graceful degradation: allows operations if state cannot be determined.
+#
+# Exit codes:
+#   0 = Allow operation
+#   2 = Block operation (stderr shown to Claude as guidance)
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+
+# Graceful degradation: if we can't determine state, allow the operation
+graceful_allow() {
+  local reason="\$1"
+  # Optionally log for debugging
+  # echo "[enforce-worktree] Graceful allow: \$reason" >&2
+  exit 0
+}
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -z "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  graceful_allow "CLAUDE_PROJECT_DIR not set"
+fi
+
+MAIN_REPO_PATH="\$CLAUDE_PROJECT_DIR"
+WORKTREES_DIR="\${MAIN_REPO_PATH}/worktrees"
+LUMENFLOW_DIR="\${MAIN_REPO_PATH}/.lumenflow"
+
+# Check if .lumenflow exists (LumenFlow is configured)
+if [[ ! -d "\$LUMENFLOW_DIR" ]]; then
+  graceful_allow "No .lumenflow directory (LumenFlow not configured)"
+fi
+
+# Read JSON input from stdin
+INPUT=\$(cat)
+
+if [[ -z "\$INPUT" ]]; then
+  graceful_allow "No input provided"
+fi
+
+# Parse JSON with Python
+TMPFILE=\$(mktemp)
+echo "\$INPUT" > "\$TMPFILE"
+
+PARSE_RESULT=\$(python3 -c "
+import json
+import sys
+try:
+    with open('\$TMPFILE', 'r') as f:
+        data = json.load(f)
+    tool_name = data.get('tool_name', '')
+    tool_input = data.get('tool_input', {})
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    file_path = tool_input.get('file_path', '')
+    print('OK')
+    print(tool_name if tool_name else '')
+    print(file_path if file_path else '')
+except Exception as e:
+    print('ERROR')
+    print(str(e))
+    print('')
+" 2>&1)
+
+rm -f "\$TMPFILE"
+
+# Parse the result
+PARSE_STATUS=\$(echo "\$PARSE_RESULT" | head -1)
+TOOL_NAME=\$(echo "\$PARSE_RESULT" | sed -n '2p')
+FILE_PATH=\$(echo "\$PARSE_RESULT" | sed -n '3p')
+
+if [[ "\$PARSE_STATUS" != "OK" ]]; then
+  graceful_allow "JSON parse failed"
+fi
+
+# Only process Write and Edit tools
+if [[ "\$TOOL_NAME" != "Write" && "\$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+if [[ -z "\$FILE_PATH" ]]; then
+  graceful_allow "No file_path in input"
+fi
+
+# Check if any worktrees exist
+if [[ ! -d "\$WORKTREES_DIR" ]]; then
+  exit 0  # No worktrees = no enforcement needed
+fi
+
+WORKTREE_COUNT=\$(find "\$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l)
+if [[ "\$WORKTREE_COUNT" -eq 0 ]]; then
+  exit 0  # No active worktrees
+fi
+
+# Resolve the file path
+RESOLVED_PATH=\$(realpath -m "\$FILE_PATH" 2>/dev/null || echo "\$FILE_PATH")
+
+# Allow if path is inside a worktree
+if [[ "\$RESOLVED_PATH" == "\${WORKTREES_DIR}/"* ]]; then
+  exit 0
+fi
+
+# Block if path is in main repo while worktrees exist
+if [[ "\$RESOLVED_PATH" == "\${MAIN_REPO_PATH}/"* || "\$RESOLVED_PATH" == "\${MAIN_REPO_PATH}" ]]; then
+  ACTIVE_WORKTREES=\$(find "\$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d -printf '%f\\n' 2>/dev/null | head -5 | tr '\\n' ', ' | sed 's/,\$//')
+
+  echo "" >&2
+  echo "=== Worktree Enforcement ===" >&2
+  echo "" >&2
+  echo "BLOCKED: \$TOOL_NAME to main repo" >&2
+  echo "" >&2
+  echo "Active worktrees: \${ACTIVE_WORKTREES:-none detected}" >&2
+  echo "" >&2
+  echo "USE INSTEAD:" >&2
+  echo "  1. cd to your worktree: cd worktrees/<lane>-wu-<id>/" >&2
+  echo "  2. Make your edits in the worktree" >&2
+  echo "" >&2
+  echo "See: LUMENFLOW.md for worktree discipline" >&2
+  echo "==============================" >&2
+  exit 2
+fi
+
+# Path is outside repo entirely - allow
+exit 0
+`;
+    /* eslint-enable no-useless-escape */
+}
+/**
+ * Generate the require-wu.sh hook script content.
+ *
+ * This hook blocks Write/Edit operations when no WU is claimed.
+ * Implements graceful degradation: allows operations if LumenFlow
+ * state cannot be determined.
+ */
+export function generateRequireWuScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# require-wu.sh (WU-1367)
+#
+# PreToolUse hook that blocks Write/Edit when no WU is claimed.
+# Graceful degradation: allows operations if state cannot be determined.
+#
+# Exit codes:
+#   0 = Allow operation
+#   2 = Block operation (stderr shown to Claude as guidance)
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+
+# Graceful degradation
+graceful_allow() {
+  local reason="\$1"
+  exit 0
+}
+
+if [[ -z "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  graceful_allow "CLAUDE_PROJECT_DIR not set"
+fi
+
+MAIN_REPO_PATH="\$CLAUDE_PROJECT_DIR"
+WORKTREES_DIR="\${MAIN_REPO_PATH}/worktrees"
+LUMENFLOW_DIR="\${MAIN_REPO_PATH}/.lumenflow"
+STATE_FILE="\${LUMENFLOW_DIR}/state/wu-events.jsonl"
+
+# Check if LumenFlow is configured
+if [[ ! -d "\$LUMENFLOW_DIR" ]]; then
+  graceful_allow "No .lumenflow directory"
+fi
+
+# Read JSON input
+INPUT=\$(cat)
+if [[ -z "\$INPUT" ]]; then
+  graceful_allow "No input"
+fi
+
+# Parse JSON
+TMPFILE=\$(mktemp)
+echo "\$INPUT" > "\$TMPFILE"
+
+TOOL_NAME=\$(python3 -c "
+import json
+try:
+    with open('\$TMPFILE', 'r') as f:
+        data = json.load(f)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+rm -f "\$TMPFILE"
+
+# Only check Write and Edit
+if [[ "\$TOOL_NAME" != "Write" && "\$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+# Check for active worktrees (indicates claimed WU)
+if [[ -d "\$WORKTREES_DIR" ]]; then
+  WORKTREE_COUNT=\$(find "\$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l)
+  if [[ "\$WORKTREE_COUNT" -gt 0 ]]; then
+    exit 0  # Has worktrees = has claimed WU
+  fi
+fi
+
+# Check state file for in_progress WUs
+if [[ -f "\$STATE_FILE" ]]; then
+  # Look for any WU with in_progress status
+  if grep -q '"status":"in_progress"' "\$STATE_FILE" 2>/dev/null; then
+    exit 0  # Has in_progress WU
+  fi
+fi
+
+# No claimed WU found
+echo "" >&2
+echo "=== WU Enforcement ===" >&2
+echo "" >&2
+echo "BLOCKED: \$TOOL_NAME without claimed WU" >&2
+echo "" >&2
+echo "You must claim a WU before making edits:" >&2
+echo "  pnpm wu:claim --id WU-XXXX --lane <Lane>" >&2
+echo "  cd worktrees/<lane>-wu-xxxx" >&2
+echo "" >&2
+echo "Or create a new WU:" >&2
+echo "  pnpm wu:create --lane <Lane> --title \"Description\"" >&2
+echo "" >&2
+echo "See: LUMENFLOW.md for workflow details" >&2
+echo "======================" >&2
+exit 2
+`;
+    /* eslint-enable no-useless-escape */
+}
+/**
+ * Generate the warn-incomplete.sh hook script content.
+ *
+ * This Stop hook warns when session ends without wu:done.
+ * Always exits 0 (warning only, never blocks).
+ */
+export function generateWarnIncompleteScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# warn-incomplete.sh (WU-1367)
+#
+# Stop hook that warns when session ends without wu:done.
+# This is advisory only - never blocks session termination.
+#
+# Exit codes:
+#   0 = Always (warnings only)
+#
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ -z "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  exit 0
+fi
+
+MAIN_REPO_PATH="\$CLAUDE_PROJECT_DIR"
+WORKTREES_DIR="\${MAIN_REPO_PATH}/worktrees"
+
+# Check for active worktrees
+if [[ ! -d "\$WORKTREES_DIR" ]]; then
+  exit 0
+fi
+
+WORKTREE_COUNT=\$(find "\$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l)
+if [[ "\$WORKTREE_COUNT" -eq 0 ]]; then
+  exit 0
+fi
+
+# Get active worktree names
+ACTIVE_WORKTREES=\$(find "\$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d -printf '%f\\n' 2>/dev/null | head -5 | tr '\\n' ', ' | sed 's/,\$//')
+
+echo "" >&2
+echo "=== Session Completion Reminder ===" >&2
+echo "" >&2
+echo "You have active worktrees: \$ACTIVE_WORKTREES" >&2
+echo "" >&2
+echo "If your work is complete, remember to run:" >&2
+echo "  pnpm wu:prep --id WU-XXXX  (from worktree)" >&2
+echo "  pnpm wu:done --id WU-XXXX  (from main)" >&2
+echo "" >&2
+echo "If work is incomplete, it will be preserved in the worktree." >&2
+echo "====================================" >&2
+
+exit 0
+`;
+    /* eslint-enable no-useless-escape */
+}

package/dist/hooks/enforcement-sync.js

@@ -0,0 +1,243 @@
+/**
+ * @file enforcement-sync.ts
+ * Sync enforcement hooks based on LumenFlow configuration (WU-1367)
+ *
+ * This module handles syncing Claude Code hooks during setup when
+ * enforcement.hooks=true in the configuration.
+ */
+// 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 { generateEnforcementHooks, generateEnforceWorktreeScript, generateRequireWuScript, generateWarnIncompleteScript, } from './enforcement-generator.js';
+/**
+ * Read LumenFlow configuration from .lumenflow.config.yaml
+ *
+ * @param projectDir - Project directory
+ * @returns Parsed configuration or null if not found
+ */
+function readLumenFlowConfig(projectDir) {
+    const configPath = path.join(projectDir, '.lumenflow.config.yaml');
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        return yaml.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get enforcement configuration from LumenFlow config
+ *
+ * @param config - LumenFlow configuration
+ * @returns Enforcement config or null if not enabled
+ */
+function getEnforcementConfig(config) {
+    const enforcement = config?.agents?.clients?.['claude-code']?.enforcement;
+    if (!enforcement || !enforcement.hooks) {
+        return null;
+    }
+    return {
+        hooks: enforcement.hooks ?? false,
+        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,
+    };
+}
+/**
+ * Read existing Claude settings.json
+ *
+ * @param projectDir - Project directory
+ * @returns Parsed settings or default structure
+ */
+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'],
+            },
+        };
+    }
+    try {
+        const content = fs.readFileSync(settingsPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return {
+            $schema: 'https://json.schemastore.org/claude-code-settings.json',
+        };
+    }
+}
+/**
+ * Write Claude settings.json
+ *
+ * @param projectDir - Project directory
+ * @param settings - Settings to write
+ */
+function writeClaudeSettings(projectDir, settings) {
+    const claudeDir = path.join(projectDir, '.claude');
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    if (!fs.existsSync(claudeDir)) {
+        fs.mkdirSync(claudeDir, { recursive: true });
+    }
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Write hook script to .claude/hooks/
+ *
+ * @param projectDir - Project directory
+ * @param filename - Script filename
+ * @param content - Script content
+ */
+function writeHookScript(projectDir, filename, content) {
+    const hooksDir = path.join(projectDir, '.claude', 'hooks');
+    if (!fs.existsSync(hooksDir)) {
+        fs.mkdirSync(hooksDir, { recursive: true });
+    }
+    const scriptPath = path.join(hooksDir, filename);
+    fs.writeFileSync(scriptPath, content, { mode: 0o755 });
+}
+/**
+ * Merge generated hooks with existing hooks in settings
+ *
+ * @param existing - Existing settings
+ * @param generated - Generated hooks
+ * @returns Merged 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) {
+            // Find existing entry with same matcher
+            const existingIndex = result.hooks.PreToolUse.findIndex((h) => h.matcher === newHook.matcher);
+            if (existingIndex >= 0) {
+                // Merge hooks into existing entry, avoiding duplicates
+                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;
+}
+/**
+ * Sync enforcement hooks based on LumenFlow configuration.
+ *
+ * This function:
+ * 1. Reads .lumenflow.config.yaml
+ * 2. Checks if enforcement.hooks=true for claude-code
+ * 3. Generates and writes hook scripts
+ * 4. Updates .claude/settings.json with hook configuration
+ *
+ * @param projectDir - Project directory
+ * @returns True if hooks were synced, false if skipped
+ */
+export async function syncEnforcementHooks(projectDir) {
+    // Read LumenFlow config
+    const config = readLumenFlowConfig(projectDir);
+    const enforcement = getEnforcementConfig(config);
+    // Skip if enforcement not enabled
+    if (!enforcement || !enforcement.hooks) {
+        return false;
+    }
+    // Generate hooks based on config
+    const generatedHooks = generateEnforcementHooks({
+        block_outside_worktree: enforcement.block_outside_worktree,
+        require_wu_for_edits: enforcement.require_wu_for_edits,
+        warn_on_stop_without_wu_done: enforcement.warn_on_stop_without_wu_done,
+    });
+    // Write hook scripts
+    if (enforcement.block_outside_worktree) {
+        writeHookScript(projectDir, 'enforce-worktree.sh', generateEnforceWorktreeScript());
+    }
+    if (enforcement.require_wu_for_edits) {
+        writeHookScript(projectDir, 'require-wu.sh', generateRequireWuScript());
+    }
+    if (enforcement.warn_on_stop_without_wu_done) {
+        writeHookScript(projectDir, 'warn-incomplete.sh', generateWarnIncompleteScript());
+    }
+    // Update settings.json
+    const existingSettings = readClaudeSettings(projectDir);
+    const updatedSettings = mergeHooksIntoSettings(existingSettings, generatedHooks);
+    writeClaudeSettings(projectDir, updatedSettings);
+    return true;
+}
+/**
+ * Remove enforcement hooks from settings.json
+ *
+ * @param projectDir - Project directory
+ */
+export async function removeEnforcementHooks(projectDir) {
+    const settings = readClaudeSettings(projectDir);
+    if (!settings.hooks) {
+        return;
+    }
+    // Remove enforcement-related hooks
+    const enforcementCommands = ['enforce-worktree.sh', 'require-wu.sh', 'warn-incomplete.sh'];
+    if (settings.hooks.PreToolUse) {
+        settings.hooks.PreToolUse = settings.hooks.PreToolUse.map((entry) => ({
+            ...entry,
+            hooks: entry.hooks.filter((h) => !enforcementCommands.some((cmd) => h.command.includes(cmd))),
+        })).filter((entry) => entry.hooks.length > 0);
+        if (settings.hooks.PreToolUse.length === 0) {
+            delete settings.hooks.PreToolUse;
+        }
+    }
+    if (settings.hooks.Stop) {
+        settings.hooks.Stop = settings.hooks.Stop.map((entry) => ({
+            ...entry,
+            hooks: entry.hooks.filter((h) => !enforcementCommands.some((cmd) => h.command.includes(cmd))),
+        })).filter((entry) => entry.hooks.length > 0);
+        if (settings.hooks.Stop.length === 0) {
+            delete settings.hooks.Stop;
+        }
+    }
+    // Clean up empty hooks object
+    if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+    writeClaudeSettings(projectDir, settings);
+}

package/dist/hooks/index.js

@@ -0,0 +1,7 @@
+/**
+ * @file hooks/index.ts
+ * Claude Code enforcement hooks module (WU-1367)
+ */
+export * from './enforcement-generator.js';
+export * from './enforcement-checks.js';
+export * from './enforcement-sync.js';