@lumenflow/cli 1.5.0 → 2.0.0

package/dist/guard-locked.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * @file guard-locked.ts
+ * @description Guard that prevents changes to locked WUs (WU-1111)
+ *
+ * Validates that a WU is not locked before allowing modifications.
+ * Used by git hooks and wu: commands to enforce workflow discipline.
+ *
+ * Usage:
+ *   guard-locked WU-123        # Check if WU-123 is locked
+ *   guard-locked --wu WU-123   # Same with explicit flag
+ *
+ * Exit codes:
+ *   0 - WU is not locked (safe to proceed)
+ *   1 - WU is locked (block operation)
+ *
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - WU lifecycle
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { PATTERNS, FILE_SYSTEM } from '@lumenflow/core/dist/wu-constants.js';
+const LOG_PREFIX = '[guard-locked]';
+/**
+ * Check if a WU is locked
+ *
+ * @param wuPath - Path to WU YAML file
+ * @returns true if WU has locked: true, false otherwise
+ * @throws Error if WU file does not exist or cannot be parsed
+ *
+ * @example
+ * if (isWULocked('/path/to/WU-123.yaml')) {
+ *   console.log('WU is locked, cannot modify');
+ * }
+ */
+export function isWULocked(wuPath) {
+    if (!existsSync(wuPath)) {
+        throw new Error(`WU file not found: ${wuPath}`);
+    }
+    const content = readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 });
+    const doc = parseYAML(content);
+    return doc.locked === true;
+}
+/**
+ * Assert that a WU is not locked
+ *
+ * @param wuPath - Path to WU YAML file
+ * @throws Error if WU is locked, with actionable fix instructions
+ *
+ * @example
+ * try {
+ *   assertWUNotLocked('/path/to/WU-123.yaml');
+ *   // Safe to modify
+ * } catch (error) {
+ *   console.error(error.message);
+ *   process.exit(1);
+ * }
+ */
+export function assertWUNotLocked(wuPath) {
+    if (!existsSync(wuPath)) {
+        throw new Error(`WU file not found: ${wuPath}`);
+    }
+    const content = readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 });
+    const doc = parseYAML(content);
+    if (doc.locked === true) {
+        const wuId = doc.id || path.basename(wuPath, '.yaml');
+        throw new Error(`${LOG_PREFIX} WU ${wuId} is locked.
+
+Locked WUs cannot be modified. This prevents accidental changes to completed work.
+
+If you need to modify this WU:
+  1. Check if modification is really necessary (locked WUs are done)
+  2. Use wu:unlock to unlock the WU first:
+     pnpm wu:unlock --id ${wuId} --reason "reason for unlocking"
+
+For more information:
+  See docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+`);
+    }
+}
+/**
+ * Check if a WU ID is locked by looking up the YAML file
+ *
+ * @param wuId - WU ID (e.g., "WU-123")
+ * @returns true if WU has locked: true, false otherwise
+ * @throws Error if WU file does not exist
+ */
+export function isWUIdLocked(wuId) {
+    const wuPath = WU_PATHS.WU(wuId);
+    return isWULocked(wuPath);
+}
+/**
+ * Assert that a WU ID is not locked
+ *
+ * @param wuId - WU ID (e.g., "WU-123")
+ * @throws Error if WU is locked
+ */
+export function assertWUIdNotLocked(wuId) {
+    const wuPath = WU_PATHS.WU(wuId);
+    assertWUNotLocked(wuPath);
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse arguments
+    let wuId;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--wu' || arg === '--id') {
+            wuId = args[++i];
+        }
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`Usage: guard-locked [--wu] WU-XXX
+
+Check if a WU is locked. Exits with code 1 if locked.
+
+Options:
+  --wu, --id WU-XXX  WU ID to check
+  -h, --help         Show this help message
+
+Examples:
+  guard-locked WU-123
+  guard-locked --wu WU-123
+`);
+            process.exit(0);
+        }
+        else if (PATTERNS.WU_ID.test(arg.toUpperCase())) {
+            wuId = arg.toUpperCase();
+        }
+    }
+    if (!wuId) {
+        console.error(`${LOG_PREFIX} Error: WU ID required`);
+        console.error('Usage: guard-locked [--wu] WU-XXX');
+        process.exit(1);
+    }
+    // Normalize WU ID
+    wuId = wuId.toUpperCase();
+    if (!PATTERNS.WU_ID.test(wuId)) {
+        console.error(`${LOG_PREFIX} Invalid WU ID: ${wuId}`);
+        console.error('Expected format: WU-123');
+        process.exit(1);
+    }
+    try {
+        if (isWUIdLocked(wuId)) {
+            console.error(`${LOG_PREFIX} ${wuId} is locked`);
+            console.error('');
+            console.error('Locked WUs cannot be modified.');
+            console.error(`To unlock: pnpm wu:unlock --id ${wuId} --reason "your reason"`);
+            process.exit(1);
+        }
+        console.log(`${LOG_PREFIX} ${wuId} is not locked (OK)`);
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`${LOG_PREFIX} Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+// Guard main() for testability
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(`${LOG_PREFIX} Unexpected error:`, error);
+        process.exit(1);
+    });
+}

package/dist/guard-main-branch.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * 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';
+/**
+ * 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, '\\$&');
+    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)) {
+            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) {
+    runCLI(main);
+}

package/dist/guard-worktree-commit.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * @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 { fileURLToPath } from 'node:url';
+import { isInWorktree, isMainBranch } from '@lumenflow/core/dist/core/worktree-guard.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 = false;
+    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);
+}
+// Guard main() for testability
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(`${LOG_PREFIX} Unexpected error:`, error);
+        process.exit(1);
+    });
+}