@lumenflow/cli 2.1.1 → 2.2.0

package/dist/file-write.d.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * File Write CLI Tool
+ *
+ * Provides audited file write operations with:
+ * - Scope checking against WU code_paths
+ * - PHI scanning (optional)
+ * - Directory creation
+ * - Audit logging
+ *
+ * Usage:
+ *   node file-write.js <path> --content <content> [--encoding utf-8]
+ *
+ * WU-1108: INIT-003 Phase 4a - Migrate file operations
+ */
+/**
+ * Default configuration for file write operations
+ */
+export declare const FILE_WRITE_DEFAULTS: {
+    /** Default encoding */
+    encoding: BufferEncoding;
+    /** Create parent directories if they don't exist */
+    createDirectories: boolean;
+};
+/**
+ * Arguments for file write operation
+ */
+export interface FileWriteArgs {
+    /** Path to file to write */
+    path?: string;
+    /** Content to write */
+    content?: string;
+    /** File encoding */
+    encoding?: BufferEncoding;
+    /** Create parent directories */
+    createDirectories?: boolean;
+    /** Scan content for PHI */
+    scanPHI?: boolean;
+    /** Show help */
+    help?: boolean;
+}
+/**
+ * Metadata returned with file write
+ */
+export interface FileWriteMetadata {
+    /** Bytes written */
+    bytesWritten: number;
+    /** Whether directories were created */
+    directoriesCreated?: boolean;
+}
+/**
+ * Audit log entry for file operations
+ */
+export interface AuditLogEntry {
+    /** Operation type */
+    operation: 'read' | 'write' | 'edit' | 'delete';
+    /** File path */
+    path: string;
+    /** Timestamp */
+    timestamp: string;
+    /** Duration in ms */
+    durationMs?: number;
+    /** Success status */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Result of file write operation
+ */
+export interface FileWriteResult {
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Error message (if failed) */
+    error?: string;
+    /** Warnings (e.g., PHI detected) */
+    warnings?: string[];
+    /** File metadata */
+    metadata?: FileWriteMetadata;
+    /** Audit log entry */
+    auditLog?: AuditLogEntry;
+}
+/**
+ * Parse command line arguments for file-write
+ */
+export declare function parseFileWriteArgs(argv: string[]): FileWriteArgs;
+/**
+ * Write a file with audit logging and safety checks
+ */
+export declare function writeFileWithAudit(args: FileWriteArgs): Promise<FileWriteResult>;

package/dist/flow-bottlenecks.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Flow Bottlenecks Analysis CLI (WU-1018)
+ *
+ * Analyzes WU dependency graph to identify bottlenecks and critical paths.
+ *
+ * Usage:
+ *   pnpm flow:bottlenecks                   # Default: top 10 bottlenecks, JSON output
+ *   pnpm flow:bottlenecks --limit 5         # Top 5 bottlenecks
+ *   pnpm flow:bottlenecks --format table    # Table output
+ *   pnpm flow:bottlenecks --format mermaid  # Mermaid diagram of critical path
+ *
+ * @module flow-bottlenecks
+ * @see {@link @lumenflow/metrics/flow/analyze-bottlenecks}
+ */
+export {};

package/dist/flow-report.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Flow Report Generator CLI (WU-1018)
+ *
+ * Generates DORA/SPACE flow reports from telemetry and WU data.
+ *
+ * Usage:
+ *   pnpm flow:report                         # Default: last 7 days, JSON output
+ *   pnpm flow:report --days 30               # Last 30 days
+ *   pnpm flow:report --format table          # Table output
+ *   pnpm flow:report --start 2026-01-01 --end 2026-01-15
+ *
+ * @module flow-report
+ * @see {@link @lumenflow/metrics/flow/generate-flow-report}
+ */
+export {};

package/dist/gates.d.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Quality Gates Runner
+ *
+ * Runs quality gates with support for docs-only mode and incremental linting.
+ *
+ * WU-1304: Optimise ESLint gates performance
+ * - Uses incremental linting (only files changed since branching from main)
+ * - Full lint coverage maintained via CI workflow
+ *
+ * WU-1433: Coverage gate with mode flag
+ * - Checks coverage thresholds for hex core files (≥90% for application layer)
+ * - Mode: block (default) fails the gate, warn logs warnings only
+ * WU-2334: Changed default from warn to block for TDD enforcement
+ *
+ * WU-1610: Supabase docs linter
+ * - Verifies every table in migrations is documented in schema.md
+ * - Fails if any table is missing documentation
+ *
+ * For type:documentation WUs:
+ * - ✅ Run: format:check, spec:linter, prompts:lint, backlog-sync
+ * - ❌ Skip: lint, typecheck, supabase-docs:linter, tests, coverage (no code changed)
+ *
+ * WU-1920: Incremental test execution
+ * - Uses Vitest's --changed flag to run only tests for changed files
+ * - Full test suite maintained via CI workflow and --full-tests flag
+ *
+ * WU-2062: Tiered test execution for faster wu:done
+ * - Safety-critical tests (PHI, escalation, red-flag) ALWAYS run
+ * - Docs-only WUs: lint/typecheck only (auto-detected or --docs-only flag)
+ * - High-risk WUs (auth, PHI, RLS, migrations): run integration tests
+ * - Standard WUs: changed tests + safety-critical tests
+ *
+ * Usage:
+ *   node tools/gates.mjs                        # Tiered gates (default)
+ *   node tools/gates.mjs --docs-only            # Docs-only gates
+ *   node tools/gates.mjs --full-lint            # Full lint (bypass incremental)
+ *   node tools/gates.mjs --full-tests           # Full tests (bypass incremental)
+ *   node tools/gates.mjs --coverage-mode=block  # Coverage gate in block mode
+ */
+/**
+ * WU-1087: Gates-specific option definitions for createWUParser.
+ * Exported for testing and consistency with other CLI commands.
+ */
+export declare const GATES_OPTIONS: {
+    docsOnly: {
+        name: string;
+        flags: string;
+        description: string;
+    };
+    fullLint: {
+        name: string;
+        flags: string;
+        description: string;
+    };
+    fullTests: {
+        name: string;
+        flags: string;
+        description: string;
+    };
+    fullCoverage: {
+        name: string;
+        flags: string;
+        description: string;
+    };
+    coverageMode: {
+        name: string;
+        flags: string;
+        description: string;
+        default: string;
+    };
+    verbose: {
+        name: string;
+        flags: string;
+        description: string;
+    };
+};
+/**
+ * WU-1087: Parse gates options using createWUParser for consistency.
+ * Handles pnpm's `--` separator and provides automatic --help support.
+ *
+ * @returns Parsed options object
+ */
+export declare function parseGatesOptions(): {
+    docsOnly?: boolean;
+    fullLint?: boolean;
+    fullTests?: boolean;
+    fullCoverage?: boolean;
+    coverageMode: string;
+    verbose?: boolean;
+};
+export declare function parsePrettierListOutput(output: string): string[];
+export declare function buildPrettierWriteCommand(files: string[]): string;
+export declare function formatFormatCheckGuidance(files: string[]): string[];

package/dist/git-branch.d.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Git Branch CLI Tool
+ *
+ * Provides WU-aware git branch with:
+ * - Branch listing (local, remote, all)
+ * - Current branch detection
+ * - Contains filtering
+ *
+ * Usage:
+ *   node git-branch.js [--list] [-a] [-r] [--show-current]
+ *
+ * WU-1109: INIT-003 Phase 4b - Migrate git operations
+ */
+/**
+ * Arguments for git branch operation
+ */
+export interface GitBranchArgs {
+    /** Base directory for git operations */
+    baseDir?: string;
+    /** List branches */
+    list?: boolean;
+    /** Show all branches (local and remote) */
+    all?: boolean;
+    /** Show only remote branches */
+    remotes?: boolean;
+    /** Show current branch only */
+    showCurrent?: boolean;
+    /** Filter branches containing commit */
+    contains?: string;
+    /** Show help */
+    help?: boolean;
+}
+/**
+ * Branch information
+ */
+export interface BranchInfo {
+    /** Branch name */
+    name: string;
+    /** Whether this is the current branch */
+    isCurrent: boolean;
+    /** Whether this is a remote branch */
+    isRemote: boolean;
+}
+/**
+ * Result of git branch operation
+ */
+export interface GitBranchResult {
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Error message (if failed) */
+    error?: string;
+    /** Current branch name */
+    current?: string;
+    /** List of branches */
+    branches?: BranchInfo[];
+}
+/**
+ * Parse command line arguments for git-branch
+ */
+export declare function parseGitBranchArgs(argv: string[]): GitBranchArgs;
+/**
+ * Get git branch information
+ */
+export declare function getGitBranch(args: GitBranchArgs): Promise<GitBranchResult>;

package/dist/git-diff.d.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Git Diff CLI Tool
+ *
+ * Provides WU-aware git diff with:
+ * - Staged/cached diff support
+ * - Name-only and stat output modes
+ * - File filtering
+ *
+ * Usage:
+ *   node git-diff.js [ref] [--staged] [--name-only] [--stat]
+ *
+ * WU-1109: INIT-003 Phase 4b - Migrate git operations
+ */
+/**
+ * Arguments for git diff operation
+ */
+export interface GitDiffArgs {
+    /** Base directory for git operations */
+    baseDir?: string;
+    /** Reference to diff against */
+    ref?: string;
+    /** Show staged changes */
+    staged?: boolean;
+    /** Show only file names */
+    nameOnly?: boolean;
+    /** Show diffstat */
+    stat?: boolean;
+    /** Path to filter diff */
+    path?: string;
+    /** Show help */
+    help?: boolean;
+}
+/**
+ * Result of git diff operation
+ */
+export interface GitDiffResult {
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Error message (if failed) */
+    error?: string;
+    /** Whether there are any differences */
+    hasDiff?: boolean;
+    /** Diff output */
+    diff?: string;
+    /** List of files (for name-only mode) */
+    files?: string[];
+    /** Diffstat output (for stat mode) */
+    stat?: string;
+}
+/**
+ * Parse command line arguments for git-diff
+ */
+export declare function parseGitDiffArgs(argv: string[]): GitDiffArgs;
+/**
+ * Get git diff with audit logging
+ */
+export declare function getGitDiff(args: GitDiffArgs): Promise<GitDiffResult>;

package/dist/git-log.d.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Git Log CLI Tool
+ *
+ * Provides WU-aware git log with:
+ * - Oneline and custom format output
+ * - Max count limiting
+ * - Date and author filtering
+ *
+ * Usage:
+ *   node git-log.js [ref] [--oneline] [-n <count>] [--format <format>]
+ *
+ * WU-1109: INIT-003 Phase 4b - Migrate git operations
+ */
+/**
+ * Arguments for git log operation
+ */
+export interface GitLogArgs {
+    /** Base directory for git operations */
+    baseDir?: string;
+    /** Reference or range (e.g., main..feature) */
+    ref?: string;
+    /** Use oneline format */
+    oneline?: boolean;
+    /** Maximum number of commits */
+    maxCount?: number;
+    /** Custom format string */
+    format?: string;
+    /** Show commits since date */
+    since?: string;
+    /** Filter by author */
+    author?: string;
+    /** Show help */
+    help?: boolean;
+}
+/**
+ * Commit information
+ */
+export interface CommitInfo {
+    /** Commit hash */
+    hash: string;
+    /** Commit message */
+    message: string;
+    /** Author name */
+    author?: string;
+    /** Author date */
+    date?: string;
+}
+/**
+ * Result of git log operation
+ */
+export interface GitLogResult {
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Error message (if failed) */
+    error?: string;
+    /** Parsed commits */
+    commits: CommitInfo[];
+    /** Raw output (for oneline/custom format) */
+    output?: string;
+}
+/**
+ * Parse command line arguments for git-log
+ */
+export declare function parseGitLogArgs(argv: string[]): GitLogArgs;
+/**
+ * Get git log with audit logging
+ */
+export declare function getGitLog(args: GitLogArgs): Promise<GitLogResult>;

package/dist/git-status.d.ts

@@ -0,0 +1,58 @@
+#!/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

@@ -0,0 +1,62 @@
+#!/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

@@ -0,0 +1,50 @@
+#!/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-main-branch.js

@@ -13,6 +13,7 @@
  * WU-1109: INIT-003 Phase 4b - Migrate git operations
  */
 import { createGitForPath, getGitForCwd, isAgentBranch, getConfig } from '@lumenflow/core';
+import { isInWorktree } from '@lumenflow/core/dist/core/worktree-guard.js';
 /**
  * Parse command line arguments for guard-main-branch
  */
@@ -90,6 +91,16 @@ export async function guardMainBranch(args) {
         }
         // 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,

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

@@ -0,0 +1,59 @@
+#!/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

@@ -0,0 +1,10 @@
+/**
+ * @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';