@lumenflow/cli 2.4.0 → 2.5.0

package/dist/git-status.d.ts

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-/**
- * Git Status CLI Tool
- *
- * Provides WU-aware git status with:
- * - Porcelain and short output formats
- * - Parsed file status (staged, modified, untracked)
- * - Clean/dirty state detection
- *
- * Usage:
- *   node git-status.js [path] [--porcelain] [--short]
- *
- * WU-1109: INIT-003 Phase 4b - Migrate git operations
- */
-/**
- * Arguments for git status operation
- */
-export interface GitStatusArgs {
-    /** Base directory for git operations */
-    baseDir?: string;
-    /** Path to filter status */
-    path?: string;
-    /** Use porcelain output format */
-    porcelain?: boolean;
-    /** Use short output format */
-    short?: boolean;
-    /** Show help */
-    help?: boolean;
-}
-/**
- * Result of git status operation
- */
-export interface GitStatusResult {
-    /** Whether operation succeeded */
-    success: boolean;
-    /** Error message (if failed) */
-    error?: string;
-    /** Whether working tree is clean */
-    isClean?: boolean;
-    /** List of staged files */
-    staged?: string[];
-    /** List of modified files (unstaged) */
-    modified?: string[];
-    /** List of untracked files */
-    untracked?: string[];
-    /** List of deleted files */
-    deleted?: string[];
-    /** Raw output (for porcelain mode) */
-    output?: string;
-}
-/**
- * Parse command line arguments for git-status
- */
-export declare function parseGitStatusArgs(argv: string[]): GitStatusArgs;
-/**
- * Get git status with audit logging
- */
-export declare function getGitStatus(args: GitStatusArgs): Promise<GitStatusResult>;

package/dist/guard-locked.d.ts

@@ -1,62 +0,0 @@
-#!/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
- */
-/**
- * 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 declare function isWULocked(wuPath: string): boolean;
-/**
- * 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 declare function assertWUNotLocked(wuPath: string): void;
-/**
- * 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 declare function isWUIdLocked(wuId: string): boolean;
-/**
- * Assert that a WU ID is not locked
- *
- * @param wuId - WU ID (e.g., "WU-123")
- * @throws Error if WU is locked
- */
-export declare function assertWUIdNotLocked(wuId: string): void;

package/dist/guard-main-branch.d.ts

@@ -1,50 +0,0 @@
-#!/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
- */
-/**
- * Arguments for guard-main-branch operation
- */
-export interface GuardMainBranchArgs {
-    /** Base directory for git operations */
-    baseDir?: string;
-    /** Allow agent branches (e.g., claude/session-123) */
-    allowAgentBranch?: boolean;
-    /** Strict mode - fail on any protected branch */
-    strict?: boolean;
-    /** Show help */
-    help?: boolean;
-}
-/**
- * Result of guard-main-branch operation
- */
-export interface GuardMainBranchResult {
-    /** Whether operation succeeded */
-    success: boolean;
-    /** Error message (if failed) */
-    error?: string;
-    /** Whether current branch is protected */
-    isProtected: boolean;
-    /** Current branch name */
-    currentBranch?: string;
-    /** Reason for protection */
-    reason?: string;
-}
-/**
- * Parse command line arguments for guard-main-branch
- */
-export declare function parseGuardMainBranchArgs(argv: string[]): GuardMainBranchArgs;
-/**
- * Guard against operations on protected branches
- */
-export declare function guardMainBranch(args: GuardMainBranchArgs): Promise<GuardMainBranchResult>;

package/dist/guard-worktree-commit.d.ts

@@ -1,59 +0,0 @@
-#!/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
- */
-/**
- * Result of commit block check
- */
-export interface CommitBlockResult {
-    /** Whether the commit should be blocked */
-    blocked: boolean;
-    /** Reason for blocking (if blocked) */
-    reason?: string;
-}
-/**
- * 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 declare function shouldBlockCommit(options: {
-    commitMessage: string;
-    isMainCheckout: boolean;
-    isInWorktree: boolean;
-}): CommitBlockResult;
-/**
- * Check if a commit message is WU-related
- *
- * @param message - Commit message to check
- * @returns true if message indicates WU work
- */
-export declare function isWUCommitMessage(message: string): boolean;

package/dist/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * @lumenflow/cli - Command-line interface for LumenFlow workflow framework
- *
- * This package provides CLI commands for the LumenFlow workflow framework.
- * Most functionality is exposed via bin commands, but the cli-entry-point
- * helper is exported for use in custom CLI wrappers.
- *
- * @see https://lumenflow.dev/reference/cli
- */
-export { runCLI } from './cli-entry-point.js';

package/dist/init-plan.d.ts

@@ -1,80 +0,0 @@
-#!/usr/bin/env node
-/**
- * Init Plan Command (WU-1105)
- *
- * Links plan files to initiatives by setting the `related_plan` field
- * in the initiative YAML.
- *
- * Usage:
- *   pnpm init:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md
- *   pnpm init:plan --initiative INIT-001 --create  # Create new plan template
- *
- * Features:
- * - Validates initiative exists before modifying
- * - Formats plan path as lumenflow:// URI
- * - Idempotent: no error if same plan already linked
- * - Warns if replacing existing plan link
- * - Can create plan templates with --create
- *
- * Context: WU-1105 (INIT-003 Phase 3a: Migrate init:plan command)
- */
-import { readInitiative } from '@lumenflow/initiatives/dist/initiative-yaml.js';
-/** Log prefix for console output */
-export declare const LOG_PREFIX: string;
-/**
- * Validate Initiative ID format
- * @param id - Initiative ID to validate
- * @throws Error if format is invalid
- */
-export declare function validateInitIdFormat(id: string): void;
-/**
- * Validate plan file path
- * @param planPath - Path to plan file
- * @throws Error if path is invalid or file doesn't exist
- */
-export declare function validatePlanPath(planPath: string): void;
-/**
- * Format plan path as lumenflow:// URI
- *
- * Extracts the filename (and any subdirectory within plans/) and creates
- * a standardized URI for the plan reference.
- *
- * @param planPath - Path to plan file (can be relative or absolute)
- * @returns lumenflow://plans/<filename> URI
- */
-export declare function formatPlanUri(planPath: string): string;
-/**
- * Check if initiative exists and return the document
- * @param initId - Initiative ID to check
- * @returns Initiative document
- * @throws Error if initiative not found
- */
-export declare function checkInitiativeExists(initId: string): ReturnType<typeof readInitiative>;
-/**
- * Update initiative with plan reference in micro-worktree
- *
- * Uses raw YAML parsing to preserve unknown fields like related_plan
- * that are not in the strict initiative schema.
- *
- * @param worktreePath - Path to micro-worktree
- * @param initId - Initiative ID
- * @param planUri - Plan URI to set
- * @returns True if changes were made, false if already linked
- */
-export declare function updateInitiativeWithPlan(worktreePath: string, initId: string, planUri: string): boolean;
-/**
- * Create a plan template file
- *
- * @param worktreePath - Path to repo root or worktree
- * @param initId - Initiative ID
- * @param title - Initiative title
- * @returns Path to created file
- * @throws Error if file already exists
- */
-export declare function createPlanTemplate(worktreePath: string, initId: string, title: string): string;
-/**
- * Generate commit message for plan link operation
- */
-export declare function getCommitMessage(initId: string, planUri: string): string;
-declare function main(): Promise<void>;
-export { main };

package/dist/init-plan.js

@@ -1,337 +0,0 @@
-#!/usr/bin/env node
-/* eslint-disable security/detect-non-literal-fs-filename */
-/**
- * Init Plan Command (WU-1105)
- *
- * Links plan files to initiatives by setting the `related_plan` field
- * in the initiative YAML.
- *
- * Usage:
- *   pnpm init:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md
- *   pnpm init:plan --initiative INIT-001 --create  # Create new plan template
- *
- * Features:
- * - Validates initiative exists before modifying
- * - Formats plan path as lumenflow:// URI
- * - Idempotent: no error if same plan already linked
- * - Warns if replacing existing plan link
- * - Can create plan templates with --create
- *
- * Context: WU-1105 (INIT-003 Phase 3a: Migrate init:plan command)
- */
-import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
-import { die } from '@lumenflow/core/dist/error-handler.js';
-import { existsSync, writeFileSync, mkdirSync, readFileSync } from 'node:fs';
-import { join, basename } from 'node:path';
-import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
-import { INIT_PATHS } from '@lumenflow/initiatives/dist/initiative-paths.js';
-import { INIT_PATTERNS } from '@lumenflow/initiatives/dist/initiative-constants.js';
-import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
-import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
-import { readInitiative } from '@lumenflow/initiatives/dist/initiative-yaml.js';
-import { parseYAML, stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
-import { LOG_PREFIX as CORE_LOG_PREFIX } from '@lumenflow/core/dist/wu-constants.js';
-/** Log prefix for console output */
-export const LOG_PREFIX = CORE_LOG_PREFIX.INIT_PLAN;
-/** Micro-worktree operation name */
-const OPERATION_NAME = 'init-plan';
-/** Standard plans directory relative to repo root */
-const PLANS_DIR = 'docs/04-operations/plans';
-/** LumenFlow URI scheme for plan references */
-const PLAN_URI_SCHEME = 'lumenflow://plans/';
-/**
- * Custom option for plan file path
- */
-const PLAN_OPTION = {
-    name: 'plan',
-    flags: '--plan <path>',
-    description: 'Path to plan file (markdown)',
-};
-/**
- * Custom option for creating new plan template
- */
-const CREATE_OPTION = {
-    name: 'create',
-    flags: '--create',
-    description: 'Create a new plan template instead of linking existing file',
-};
-/**
- * Validate Initiative ID format
- * @param id - Initiative ID to validate
- * @throws Error if format is invalid
- */
-export function validateInitIdFormat(id) {
-    if (!INIT_PATTERNS.INIT_ID.test(id)) {
-        die(`Invalid Initiative ID format: "${id}"\n\n` +
-            `Expected format: INIT-<number> or INIT-NAME (e.g., INIT-001, INIT-TOOLING)`);
-    }
-}
-/**
- * Validate plan file path
- * @param planPath - Path to plan file
- * @throws Error if path is invalid or file doesn't exist
- */
-export function validatePlanPath(planPath) {
-    if (!planPath.endsWith('.md')) {
-        die(`Invalid plan file format: "${planPath}"\n\nPlan files must be markdown (.md)`);
-    }
-    if (!existsSync(planPath)) {
-        die(`Plan file not found: "${planPath}"\n\nUse --create to create a new plan template`);
-    }
-}
-/**
- * Format plan path as lumenflow:// URI
- *
- * Extracts the filename (and any subdirectory within plans/) and creates
- * a standardized URI for the plan reference.
- *
- * @param planPath - Path to plan file (can be relative or absolute)
- * @returns lumenflow://plans/<filename> URI
- */
-export function formatPlanUri(planPath) {
-    // Try to extract path relative to plans directory
-    const plansMarker = '/plans/';
-    const plansIndex = planPath.indexOf(plansMarker);
-    if (plansIndex !== -1) {
-        // Extract everything after /plans/
-        const relativePath = planPath.substring(plansIndex + plansMarker.length);
-        return `${PLAN_URI_SCHEME}${relativePath}`;
-    }
-    // Fallback: just use the filename
-    const filename = basename(planPath);
-    return `${PLAN_URI_SCHEME}${filename}`;
-}
-/**
- * Check if initiative exists and return the document
- * @param initId - Initiative ID to check
- * @returns Initiative document
- * @throws Error if initiative not found
- */
-export function checkInitiativeExists(initId) {
-    const initPath = INIT_PATHS.INITIATIVE(initId);
-    if (!existsSync(initPath)) {
-        die(`Initiative not found: ${initId}\n\nFile does not exist: ${initPath}`);
-    }
-    return readInitiative(initPath, initId);
-}
-/**
- * Update initiative with plan reference in micro-worktree
- *
- * Uses raw YAML parsing to preserve unknown fields like related_plan
- * that are not in the strict initiative schema.
- *
- * @param worktreePath - Path to micro-worktree
- * @param initId - Initiative ID
- * @param planUri - Plan URI to set
- * @returns True if changes were made, false if already linked
- */
-export function updateInitiativeWithPlan(worktreePath, initId, planUri) {
-    const initRelPath = INIT_PATHS.INITIATIVE(initId);
-    const initAbsPath = join(worktreePath, initRelPath);
-    // Read raw YAML to preserve unknown fields like related_plan
-    // (readInitiative strips them via zod schema validation)
-    const rawText = readFileSync(initAbsPath, { encoding: 'utf-8' });
-    const doc = parseYAML(rawText);
-    // Validate ID matches
-    if (doc.id !== initId) {
-        die(`Initiative YAML id mismatch. Expected ${initId}, found ${doc.id}`);
-    }
-    // Check for existing plan link
-    const existingPlan = doc.related_plan;
-    if (existingPlan === planUri) {
-        // Already linked to same plan - idempotent
-        return false;
-    }
-    if (existingPlan && existingPlan !== planUri) {
-        // Different plan already linked - warn but proceed
-        console.warn(`${LOG_PREFIX} Replacing existing related_plan: ${existingPlan} -> ${planUri}`);
-    }
-    // Update related_plan field
-    doc.related_plan = planUri;
-    const out = stringifyYAML(doc);
-    writeFileSync(initAbsPath, out, { encoding: 'utf-8' });
-    console.log(`${LOG_PREFIX} Updated ${initId} with related_plan: ${planUri}`);
-    return true;
-}
-/**
- * Create a plan template file
- *
- * @param worktreePath - Path to repo root or worktree
- * @param initId - Initiative ID
- * @param title - Initiative title
- * @returns Path to created file
- * @throws Error if file already exists
- */
-export function createPlanTemplate(worktreePath, initId, title) {
-    const slug = title
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-|-$/g, '')
-        .substring(0, 30);
-    const filename = `${initId}-${slug}.md`;
-    const plansDir = join(worktreePath, PLANS_DIR);
-    const planPath = join(plansDir, filename);
-    if (existsSync(planPath)) {
-        die(`Plan file already exists: ${planPath}\n\nUse --plan to link an existing file`);
-    }
-    // Ensure plans directory exists
-    if (!existsSync(plansDir)) {
-        mkdirSync(plansDir, { recursive: true });
-    }
-    const template = `# ${initId} Plan - ${title}
-
-## Goal
-
-<!-- What is the primary objective of this initiative? -->
-
-## Scope
-
-<!-- What is in scope and out of scope? -->
-
-## Approach
-
-<!-- How will you achieve the goal? Key phases or milestones? -->
-
-## Success Criteria
-
-<!-- How will you know when this is complete? Measurable outcomes? -->
-
-## Risks
-
-<!-- What could go wrong? How will you mitigate? -->
-
-## References
-
-- Initiative: ${initId}
-- Created: ${new Date().toISOString().split('T')[0]}
-`;
-    writeFileSync(planPath, template, { encoding: 'utf-8' });
-    console.log(`${LOG_PREFIX} Created plan template: ${planPath}`);
-    return planPath;
-}
-/**
- * Generate commit message for plan link operation
- */
-export function getCommitMessage(initId, planUri) {
-    const filename = planUri.replace(PLAN_URI_SCHEME, '');
-    return `docs: link plan ${filename} to ${initId.toLowerCase()}`;
-}
-async function main() {
-    const args = createWUParser({
-        name: 'init-plan',
-        description: 'Link a plan file to an initiative',
-        options: [WU_OPTIONS.initiative, PLAN_OPTION, CREATE_OPTION],
-        required: ['initiative'],
-        allowPositionalId: false,
-    });
-    const initId = args.initiative;
-    const planPath = args.plan;
-    const shouldCreate = args.create;
-    // Validate inputs
-    validateInitIdFormat(initId);
-    // Check initiative exists first (before any mutations)
-    const initDoc = checkInitiativeExists(initId);
-    const initTitle = initDoc.title;
-    // Determine plan path and URI
-    let targetPlanPath;
-    let planUri;
-    if (shouldCreate) {
-        // Create mode - will create template and link it
-        console.log(`${LOG_PREFIX} Creating plan template for ${initId}...`);
-        // Ensure on main for micro-worktree operations
-        await ensureOnMain(getGitForCwd());
-        try {
-            await withMicroWorktree({
-                operation: OPERATION_NAME,
-                id: initId,
-                logPrefix: LOG_PREFIX,
-                pushOnly: true,
-                execute: async ({ worktreePath }) => {
-                    // Create plan template
-                    targetPlanPath = createPlanTemplate(worktreePath, initId, initTitle);
-                    planUri = formatPlanUri(targetPlanPath);
-                    // Update initiative with plan link
-                    updateInitiativeWithPlan(worktreePath, initId, planUri);
-                    // Return files to commit
-                    const planRelPath = targetPlanPath.replace(worktreePath + '/', '');
-                    return {
-                        commitMessage: getCommitMessage(initId, planUri),
-                        files: [planRelPath, INIT_PATHS.INITIATIVE(initId)],
-                    };
-                },
-            });
-            console.log(`\n${LOG_PREFIX} Transaction complete!`);
-            console.log(`\nPlan Linked:`);
-            console.log(`  Initiative: ${initId}`);
-            console.log(`  Plan URI:   ${planUri}`);
-            console.log(`  File:       ${targetPlanPath}`);
-            console.log(`\nNext steps:`);
-            console.log(`  1. Edit the plan file with your goals and approach`);
-            console.log(`  2. View initiative: pnpm initiative:status ${initId}`);
-        }
-        catch (error) {
-            die(`Transaction failed: ${error.message}\n\n` +
-                `Micro-worktree cleanup was attempted automatically.\n` +
-                `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
-        }
-    }
-    else if (planPath) {
-        // Link existing file mode
-        validatePlanPath(planPath);
-        planUri = formatPlanUri(planPath);
-        console.log(`${LOG_PREFIX} Linking plan to ${initId}...`);
-        // Check for idempotent case before micro-worktree
-        const existingPlan = initDoc.related_plan;
-        if (existingPlan === planUri) {
-            console.log(`${LOG_PREFIX} Plan already linked (idempotent - no changes needed)`);
-            console.log(`\n${LOG_PREFIX} ${initId} already has related_plan: ${planUri}`);
-            return;
-        }
-        // Ensure on main for micro-worktree operations
-        await ensureOnMain(getGitForCwd());
-        try {
-            await withMicroWorktree({
-                operation: OPERATION_NAME,
-                id: initId,
-                logPrefix: LOG_PREFIX,
-                pushOnly: true,
-                execute: async ({ worktreePath }) => {
-                    // Update initiative with plan link
-                    const changed = updateInitiativeWithPlan(worktreePath, initId, planUri);
-                    if (!changed) {
-                        console.log(`${LOG_PREFIX} No changes detected (concurrent link operation)`);
-                    }
-                    return {
-                        commitMessage: getCommitMessage(initId, planUri),
-                        files: [INIT_PATHS.INITIATIVE(initId)],
-                    };
-                },
-            });
-            console.log(`\n${LOG_PREFIX} Transaction complete!`);
-            console.log(`\nPlan Linked:`);
-            console.log(`  Initiative: ${initId}`);
-            console.log(`  Plan URI:   ${planUri}`);
-            console.log(`  File:       ${planPath}`);
-            console.log(`\nNext steps:`);
-            console.log(`  - View initiative: pnpm initiative:status ${initId}`);
-        }
-        catch (error) {
-            die(`Transaction failed: ${error.message}\n\n` +
-                `Micro-worktree cleanup was attempted automatically.\n` +
-                `If issue persists, check for orphaned branches: git branch | grep tmp/${OPERATION_NAME}`);
-        }
-    }
-    else {
-        die('Either --plan or --create is required\n\n' +
-            'Usage:\n' +
-            '  pnpm init:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md\n' +
-            '  pnpm init:plan --initiative INIT-001 --create');
-    }
-}
-// Guard main() for testability - use import.meta.main (WU-1071)
-import { runCLI } from './cli-entry-point.js';
-if (import.meta.main) {
-    runCLI(main);
-}
-// Export for testing
-export { main };