@lumenflow/cli 3.1.3 → 3.2.1

package/dist/guard-main-branch.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Guard Main Branch CLI Tool
+ *
+ * Provides branch protection checks for WU workflow:
+ * - Blocks operations on main/master branches
+ * - Blocks operations on lane branches (require worktree)
+ * - Optionally allows agent branches
+ *
+ * Usage:
+ *   node guard-main-branch.js [--allow-agent-branch] [--strict]
+ *
+ * WU-1109: INIT-003 Phase 4b - Migrate git operations
+ */
+import { createGitForPath, getGitForCwd, isAgentBranch, getConfig } from '@lumenflow/core';
+import { isInWorktree } from '@lumenflow/core/core/worktree-guard';
+/**
+ * Parse command line arguments for guard-main-branch
+ */
+export function parseGuardMainBranchArgs(argv) {
+    const args = {};
+    // Skip node and script name
+    const cliArgs = argv.slice(2);
+    for (let i = 0; i < cliArgs.length; i++) {
+        const arg = cliArgs[i];
+        if (arg === '--help' || arg === '-h') {
+            args.help = true;
+        }
+        else if (arg === '--allow-agent-branch') {
+            args.allowAgentBranch = true;
+        }
+        else if (arg === '--strict') {
+            args.strict = true;
+        }
+        else if (arg === '--base-dir') {
+            args.baseDir = cliArgs[++i];
+        }
+    }
+    return args;
+}
+/**
+ * Get lane branch pattern from config
+ */
+function getLaneBranchPattern() {
+    const config = getConfig();
+    const prefix = config?.git?.laneBranchPrefix ?? 'lane/';
+    const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // eslint-disable-next-line security/detect-non-literal-regexp -- prefix from config file, not user input; escaped for safety
+    return new RegExp(`^${escaped}`);
+}
+/**
+ * Get protected branches from config
+ */
+function getProtectedBranches() {
+    const config = getConfig();
+    const mainBranch = config?.git?.mainBranch ?? 'main';
+    // Always include master for legacy compatibility
+    const protectedSet = new Set([mainBranch, 'master']);
+    return Array.from(protectedSet);
+}
+/**
+ * Check if a branch is a lane branch (requires worktree)
+ */
+function isLaneBranch(branch) {
+    return getLaneBranchPattern().test(branch);
+}
+/**
+ * Guard against operations on protected branches
+ */
+export async function guardMainBranch(args) {
+    try {
+        const git = args.baseDir ? createGitForPath(args.baseDir) : getGitForCwd();
+        const currentBranch = await git.getCurrentBranch();
+        // Handle detached HEAD
+        if (currentBranch === 'HEAD' || !currentBranch) {
+            return {
+                success: true,
+                isProtected: true,
+                currentBranch: 'HEAD (detached)',
+                reason: 'Detached HEAD state is protected - checkout a branch',
+            };
+        }
+        const protectedBranches = getProtectedBranches();
+        // Check if on main/master
+        if (protectedBranches.includes(currentBranch)) {
+            return {
+                success: true,
+                isProtected: true,
+                currentBranch,
+                reason: `Branch '${currentBranch}' is protected - use a worktree for WU work`,
+            };
+        }
+        // Check if on a lane branch (requires worktree discipline)
+        if (isLaneBranch(currentBranch)) {
+            // If we're actually in a worktree, allow the operation (WU-1130)
+            const cwd = args.baseDir ?? process.cwd();
+            if (isInWorktree({ cwd })) {
+                return {
+                    success: true,
+                    isProtected: false,
+                    currentBranch,
+                };
+            }
+            // On lane branch but not in worktree - block
+            return {
+                success: true,
+                isProtected: true,
+                currentBranch,
+                reason: `Lane branch '${currentBranch}' requires worktree - use 'pnpm wu:claim' to create worktree`,
+            };
+        }
+        // Check agent branch if not explicitly allowed
+        if (!args.allowAgentBranch) {
+            const isAgent = await isAgentBranch(currentBranch);
+            if (isAgent) {
+                // Agent branches are allowed by default (unless --strict)
+                if (args.strict) {
+                    return {
+                        success: true,
+                        isProtected: true,
+                        currentBranch,
+                        reason: `Agent branch '${currentBranch}' is protected in strict mode`,
+                    };
+                }
+                // Allow agent branch
+                return {
+                    success: true,
+                    isProtected: false,
+                    currentBranch,
+                };
+            }
+        }
+        // Branch is not protected
+        return {
+            success: true,
+            isProtected: false,
+            currentBranch,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            isProtected: true, // Fail-closed
+            error: errorMessage,
+        };
+    }
+}
+/**
+ * Print help message
+ */
+/* istanbul ignore next -- CLI entry point tested via subprocess */
+function printHelp() {
+    console.log(`
+Usage: guard-main-branch [options]
+
+Check if current branch is protected and block operations.
+
+Options:
+  --base-dir <dir>      Base directory for git operations
+  --allow-agent-branch  Allow operations on agent branches
+  --strict              Block all protected branches (including agent)
+  -h, --help            Show this help message
+
+Exit codes:
+  0 - Branch is not protected (safe to proceed)
+  1 - Branch is protected (operation blocked)
+
+Protected branches:
+  - main/master: Always protected
+  - lane/*: Requires worktree (use wu:claim)
+  - Agent branches: Allowed unless --strict
+
+Examples:
+  guard-main-branch
+  guard-main-branch --allow-agent-branch
+  guard-main-branch --strict
+`);
+}
+/**
+ * Main entry point
+ */
+/* istanbul ignore next -- CLI entry point tested via subprocess */
+async function main() {
+    const args = parseGuardMainBranchArgs(process.argv);
+    if (args.help) {
+        printHelp();
+        process.exit(0);
+    }
+    const result = await guardMainBranch(args);
+    if (result.success) {
+        if (result.isProtected) {
+            console.error(`[guard-main-branch] BLOCKED: ${result.reason}`);
+            console.error(`Current branch: ${result.currentBranch}`);
+            process.exit(1);
+        }
+        else {
+            // Silent success in normal mode
+            if (process.env.DEBUG) {
+                console.log(`[guard-main-branch] OK: Branch '${result.currentBranch}' is not protected`);
+            }
+            process.exit(0);
+        }
+    }
+    else {
+        console.error(`Error: ${result.error}`);
+        process.exit(1);
+    }
+}
+// Run main if executed directly
+import { runCLI } from './cli-entry-point.js';
+if (import.meta.main) {
+    void runCLI(main);
+}
+//# sourceMappingURL=guard-main-branch.js.map

package/dist/guard-main-branch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-main-branch.js","sourceRoot":"","sources":["../src/guard-main-branch.ts"],"names":[],"mappings":"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"}

package/dist/guard-worktree-commit.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file guard-worktree-commit.ts
+ * @description Guard that prevents WU commits from main checkout (WU-1111)
+ *
+ * Validates that WU-related commits are only made from worktrees, not main.
+ * Used by git commit-msg hooks to enforce worktree discipline.
+ *
+ * Usage:
+ *   guard-worktree-commit "commit message"
+ *   guard-worktree-commit --message "commit message"
+ *
+ * Exit codes:
+ *   0 - Commit allowed
+ *   1 - Commit blocked (WU commit from main)
+ *
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - Worktree discipline
+ */
+import { isInWorktree, isMainBranch } from '@lumenflow/core/core/worktree-guard';
+import { runCLI } from './cli-entry-point.js';
+const LOG_PREFIX = '[guard-worktree-commit]';
+/**
+ * Patterns that indicate a WU-related commit message
+ */
+const WU_COMMIT_PATTERNS = [
+    /^wu\(/i, // wu(WU-123): message
+    /\(wu-\d+\)/i, // feat(WU-123): message
+    /\(WU-\d+\)/i, // Same with uppercase
+    /^WU-\d+:/i, // WU-123: message
+    /^wu-\d+:/i, // wu-123: message
+];
+/**
+ * Check if a commit should be blocked
+ *
+ * @param options - Check options
+ * @param options.commitMessage - The commit message
+ * @param options.isMainCheckout - Whether in main checkout
+ * @param options.isInWorktree - Whether in a worktree
+ * @returns Whether commit should be blocked and why
+ *
+ * @example
+ * const result = shouldBlockCommit({
+ *   commitMessage: 'wu(WU-123): add feature',
+ *   isMainCheckout: true,
+ *   isInWorktree: false,
+ * });
+ * if (result.blocked) {
+ *   console.error(result.reason);
+ *   process.exit(1);
+ * }
+ */
+export function shouldBlockCommit(options) {
+    const { commitMessage, isMainCheckout, isInWorktree } = options;
+    // Allow all commits from worktrees
+    if (isInWorktree) {
+        return { blocked: false };
+    }
+    // Check if commit message indicates WU work
+    const isWUCommit = WU_COMMIT_PATTERNS.some((pattern) => pattern.test(commitMessage));
+    // Block WU commits from main checkout
+    if (isWUCommit && isMainCheckout) {
+        return {
+            blocked: true,
+            reason: `${LOG_PREFIX} BLOCKED: WU commits must be made from a worktree.
+
+You are attempting to commit WU work from the main checkout.
+
+To fix:
+  1. Navigate to your worktree:
+     cd worktrees/<lane>-wu-xxx/
+
+  2. Make your commit there:
+     git add . && git commit -m "${commitMessage}"
+
+  3. Complete the WU from main:
+     cd ../.. && pnpm wu:done --id WU-XXX
+
+For more information:
+  See docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+  See .claude/skills/worktree-discipline/SKILL.md
+`,
+        };
+    }
+    // Allow non-WU commits from anywhere
+    return { blocked: false };
+}
+/**
+ * Check if a commit message is WU-related
+ *
+ * @param message - Commit message to check
+ * @returns true if message indicates WU work
+ */
+export function isWUCommitMessage(message) {
+    return WU_COMMIT_PATTERNS.some((pattern) => pattern.test(message));
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse arguments
+    let commitMessage;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--message' || arg === '-m') {
+            commitMessage = args[++i];
+        }
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`Usage: guard-worktree-commit [--message] "commit message"
+
+Check if a WU commit should be blocked from main checkout.
+
+Options:
+  --message, -m MSG  Commit message to check
+  -h, --help         Show this help message
+
+Examples:
+  guard-worktree-commit "wu(WU-123): add feature"
+  guard-worktree-commit --message "chore: update deps"
+`);
+            process.exit(0);
+        }
+        else if (!commitMessage) {
+            commitMessage = arg;
+        }
+    }
+    if (!commitMessage) {
+        console.error(`${LOG_PREFIX} Error: Commit message required`);
+        console.error('Usage: guard-worktree-commit [--message] "commit message"');
+        process.exit(1);
+    }
+    // Check context
+    const inWorktree = isInWorktree();
+    let onMain;
+    try {
+        onMain = await isMainBranch();
+    }
+    catch {
+        // If we can't determine branch, be conservative and allow
+        onMain = false;
+    }
+    const result = shouldBlockCommit({
+        commitMessage,
+        isMainCheckout: onMain && !inWorktree,
+        isInWorktree: inWorktree,
+    });
+    if (result.blocked) {
+        console.error(result.reason);
+        process.exit(1);
+    }
+    console.log(`${LOG_PREFIX} Commit allowed`);
+    process.exit(0);
+}
+// WU-1181: Use import.meta.main instead of process.argv[1] comparison
+// 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
+// WU-1537: Use import.meta.main + runCLI for consistent EPIPE and error handling
+if (import.meta.main) {
+    void runCLI(main);
+}
+//# sourceMappingURL=guard-worktree-commit.js.map

package/dist/guard-worktree-commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-worktree-commit.js","sourceRoot":"","sources":["../src/guard-worktree-commit.ts"],"names":[],"mappings":"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"}

package/dist/hooks/auto-checkpoint-utils.js

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file auto-checkpoint-utils.ts
+ * Utilities for auto-checkpoint enforcement hooks (WU-1471)
+ *
+ * Provides:
+ * - checkAutoCheckpointWarning: Detects config mismatch (policy enabled, hooks disabled)
+ * - cleanupHookCounters: Removes per-WU counter files on wu:done completion
+ */
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { LUMENFLOW_PATHS } from '@lumenflow/core';
+/**
+ * WU-1471 AC5: Check if auto-checkpoint policy is enabled but hooks master switch is disabled.
+ * When this mismatch exists, tooling should emit a warning that enforcement is advisory-only.
+ *
+ * @param params - Configuration state
+ * @param params.hooksEnabled - Whether the hooks master switch is enabled
+ * @param params.autoCheckpointEnabled - Whether auto_checkpoint.enabled is true
+ * @returns Warning result with message if applicable
+ */
+export function checkAutoCheckpointWarning(params) {
+    if (params.autoCheckpointEnabled && !params.hooksEnabled) {
+        return {
+            warning: true,
+            message: 'Auto-checkpoint policy is enabled but hooks master switch is disabled. ' +
+                'Checkpointing remains advisory-only. Enable agents.clients.claude-code.enforcement.hooks ' +
+                'to activate automatic checkpointing.',
+        };
+    }
+    return { warning: false };
+}
+/**
+ * WU-1471 AC4: Remove per-WU hook counter file on wu:done completion.
+ * Called during wu:done cleanup to remove .lumenflow/state/hook-counters/<WU_ID>.json.
+ *
+ * Fail-safe: does not throw if the file or directory does not exist.
+ *
+ * @param projectDir - Project root directory
+ * @param wuId - WU identifier (e.g., 'WU-1471')
+ */
+export function cleanupHookCounters(projectDir, wuId) {
+    try {
+        const counterFile = join(projectDir, LUMENFLOW_PATHS.HOOK_COUNTERS_DIR, `${wuId}.json`);
+        if (existsSync(counterFile)) {
+            unlinkSync(counterFile);
+        }
+    }
+    catch {
+        // Fail-safe: counter cleanup failure should never block wu:done
+    }
+}
+//# sourceMappingURL=auto-checkpoint-utils.js.map

package/dist/hooks/auto-checkpoint-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-checkpoint-utils.js","sourceRoot":"","sources":["../../src/hooks/auto-checkpoint-utils.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAG1C;IACC,IAAI,MAAM,CAAC,qBAAqB,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACzD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EACL,yEAAyE;gBACzE,2FAA2F;gBAC3F,sCAAsC;SACzC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB,EAAE,IAAY;IAClE,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,iBAAiB,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;QACxF,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5B,UAAU,CAAC,WAAW,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;AACH,CAAC"}