@lumenflow/cli 2.1.1 → 2.2.0

package/dist/__tests__/guard-main-branch.test.js

@@ -0,0 +1,79 @@
+/**
+ * @file guard-main-branch.test.ts
+ * @description Tests for guard-main-branch worktree context detection (WU-1130)
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { guardMainBranch } from '../guard-main-branch.js';
+// Mock the core module
+vi.mock('@lumenflow/core', () => ({
+    createGitForPath: vi.fn(),
+    getGitForCwd: vi.fn(),
+    isAgentBranch: vi.fn().mockResolvedValue(false),
+    getConfig: vi.fn().mockReturnValue({
+        git: {
+            mainBranch: 'main',
+            laneBranchPrefix: 'lane/',
+        },
+    }),
+}));
+// Mock the worktree-guard module
+vi.mock('@lumenflow/core/dist/core/worktree-guard.js', () => ({
+    isInWorktree: vi.fn(),
+}));
+import { getGitForCwd, createGitForPath } from '@lumenflow/core';
+import { isInWorktree } from '@lumenflow/core/dist/core/worktree-guard.js';
+describe('guard-main-branch (WU-1130)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('lane branch worktree detection', () => {
+        it('should allow operations when on lane branch AND in worktree', async () => {
+            // Setup: On lane branch, in worktree
+            const mockGit = {
+                getCurrentBranch: vi.fn().mockResolvedValue('lane/framework-cli/wu-1130'),
+            };
+            vi.mocked(getGitForCwd).mockReturnValue(mockGit);
+            vi.mocked(isInWorktree).mockReturnValue(true);
+            const result = await guardMainBranch({});
+            expect(result.success).toBe(true);
+            expect(result.isProtected).toBe(false);
+            expect(result.currentBranch).toBe('lane/framework-cli/wu-1130');
+        });
+        it('should block operations when on lane branch but NOT in worktree', async () => {
+            // Setup: On lane branch, but not in worktree (e.g., checked out directly)
+            const mockGit = {
+                getCurrentBranch: vi.fn().mockResolvedValue('lane/framework-cli/wu-1130'),
+            };
+            vi.mocked(getGitForCwd).mockReturnValue(mockGit);
+            vi.mocked(isInWorktree).mockReturnValue(false);
+            const result = await guardMainBranch({});
+            expect(result.success).toBe(true);
+            expect(result.isProtected).toBe(true);
+            expect(result.reason).toContain('requires worktree');
+        });
+        it('should use baseDir for worktree detection when provided', async () => {
+            const mockGit = {
+                getCurrentBranch: vi.fn().mockResolvedValue('lane/ops-tooling/wu-2725'),
+            };
+            vi.mocked(createGitForPath).mockReturnValue(mockGit);
+            vi.mocked(isInWorktree).mockReturnValue(true);
+            const result = await guardMainBranch({ baseDir: '/path/to/worktrees/ops-tooling-wu-2725' });
+            expect(isInWorktree).toHaveBeenCalledWith({ cwd: '/path/to/worktrees/ops-tooling-wu-2725' });
+            expect(result.isProtected).toBe(false);
+        });
+    });
+    describe('main branch protection', () => {
+        it('should block operations on main branch', async () => {
+            const mockGit = {
+                getCurrentBranch: vi.fn().mockResolvedValue('main'),
+            };
+            vi.mocked(getGitForCwd).mockReturnValue(mockGit);
+            const result = await guardMainBranch({});
+            expect(result.isProtected).toBe(true);
+            expect(result.reason).toContain("'main' is protected");
+        });
+    });
+});

package/dist/agent-issues-query.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Agent Issues Query CLI (WU-1018)
+ *
+ * Query and display logged agent incidents/issues.
+ *
+ * Usage:
+ *   pnpm agent:issues-query summary                 # Summary of last 7 days
+ *   pnpm agent:issues-query summary --since 30     # Summary of last 30 days
+ *   pnpm agent:issues-query summary --category tooling
+ *   pnpm agent:issues-query summary --severity blocker
+ *
+ * @module agent-issues-query
+ * @see {@link @lumenflow/agent}
+ */
+export {};

package/dist/agent-log-issue.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Agent Log Issue CLI
+ *
+ * Logs a workflow issue or incident during agent execution.
+ *
+ * Usage:
+ *   pnpm agent:log-issue --category workflow --severity minor --title "..." --description "..."
+ */
+export {};

package/dist/agent-session-end.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Agent Session End CLI
+ *
+ * Ends the current agent session and returns summary.
+ *
+ * Usage:
+ *   pnpm agent:session:end
+ */
+export {};

package/dist/agent-session.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Agent Session Start CLI
+ *
+ * Starts an agent session for tracking WU execution.
+ *
+ * Usage:
+ *   pnpm agent:session --wu WU-1234 --tier 2
+ */
+export {};

package/dist/backlog-prune.d.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Backlog Prune Command
+ *
+ * Maintains backlog hygiene by:
+ * - Auto-tagging stale WUs (in_progress/ready too long without activity)
+ * - Archiving old completed WUs (done for > N days)
+ *
+ * WU-1106: INIT-003 Phase 3b - Migrate from PatientPath tools/backlog-prune.mjs
+ *
+ * Usage:
+ *   pnpm backlog:prune           # Dry-run mode (shows what would be done)
+ *   pnpm backlog:prune --execute # Apply changes
+ */
+/**
+ * Default configuration for backlog pruning
+ */
+export declare const BACKLOG_PRUNE_DEFAULTS: {
+    /** Days without activity before in_progress WU is considered stale */
+    staleDaysInProgress: number;
+    /** Days without activity before ready WU is considered stale */
+    staleDaysReady: number;
+    /** Days after completion before done WU can be archived */
+    archiveDaysDone: number;
+};
+/**
+ * Arguments for backlog-prune command
+ */
+export interface BacklogPruneArgs {
+    dryRun: boolean;
+    staleDaysInProgress: number;
+    staleDaysReady: number;
+    archiveDaysDone: number;
+    help?: boolean;
+}
+/**
+ * Minimal WU information needed for prune analysis
+ */
+export interface WuPruneInfo {
+    id: string;
+    status: string;
+    title?: string;
+    created?: string;
+    updated?: string;
+    completed?: string;
+}
+/**
+ * Result of WU categorization
+ */
+export interface PruneCategorization {
+    stale: WuPruneInfo[];
+    archivable: WuPruneInfo[];
+    healthy: WuPruneInfo[];
+}
+/**
+ * Parse command line arguments for backlog-prune
+ */
+export declare function parseBacklogPruneArgs(argv: string[]): BacklogPruneArgs;
+/**
+ * Calculate days since a date string
+ * @returns Number of days since date, or null if invalid
+ */
+export declare function calculateStaleDays(dateStr: string | undefined | null): number | null;
+/**
+ * Check if a WU is stale based on its status and last activity date
+ */
+export declare function isWuStale(wu: WuPruneInfo, options: {
+    staleDaysInProgress?: number;
+    staleDaysReady?: number;
+}): boolean;
+/**
+ * Check if a WU is archivable (done for more than N days)
+ */
+export declare function isWuArchivable(wu: WuPruneInfo, options: {
+    archiveDaysDone?: number;
+}): boolean;
+/**
+ * Categorize WUs into stale, archivable, and healthy
+ */
+export declare function categorizeWus(wus: WuPruneInfo[], options: {
+    staleDaysInProgress: number;
+    staleDaysReady: number;
+    archiveDaysDone: number;
+}): PruneCategorization;

package/dist/cli-entry-point.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wraps an async main function with proper error handling.
+ * WU-1085: Also initializes color support based on NO_COLOR/FORCE_COLOR/--no-color
+ *
+ * @param main - The async main function to execute
+ * @returns Promise that resolves when main completes (or after error handling)
+ */
+export declare function runCLI(main: () => Promise<void>): Promise<void>;

package/dist/deps-add.d.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Deps Add CLI Command
+ *
+ * Safe wrapper for `pnpm add` that enforces worktree discipline.
+ * Dependencies can only be added from within a worktree, not from main checkout.
+ *
+ * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ *
+ * Usage:
+ *   pnpm deps:add react
+ *   pnpm deps:add --dev vitest
+ *   pnpm deps:add --filter @lumenflow/cli chalk
+ *
+ * @see dependency-guard.ts for blocking logic
+ */
+/**
+ * Arguments for deps-add command
+ */
+export interface DepsAddArgs {
+    /** Package names to add */
+    packages?: string[];
+    /** Add as dev dependency */
+    dev?: boolean;
+    /** Filter to specific workspace package */
+    filter?: string;
+    /** Use exact version */
+    exact?: boolean;
+    /** Show help */
+    help?: boolean;
+}
+/**
+ * Arguments for deps-remove command (also exported from here for convenience)
+ */
+export interface DepsRemoveArgs {
+    /** Package names to remove */
+    packages?: string[];
+    /** Filter to specific workspace package */
+    filter?: string;
+    /** Show help */
+    help?: boolean;
+}
+/**
+ * Result of worktree context validation
+ */
+export interface WorktreeValidationResult {
+    /** Whether the context is valid (inside worktree) */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Fix command suggestion */
+    fixCommand?: string;
+}
+/**
+ * Parse command line arguments for deps-add
+ *
+ * @param argv - Process argv array
+ * @returns Parsed arguments
+ */
+export declare function parseDepsAddArgs(argv: string[]): DepsAddArgs;
+/**
+ * Parse command line arguments for deps-remove
+ *
+ * @param argv - Process argv array
+ * @returns Parsed arguments
+ */
+export declare function parseDepsRemoveArgs(argv: string[]): DepsRemoveArgs;
+/**
+ * Validate that the current directory is within a worktree
+ *
+ * Dependencies should only be modified in worktrees to maintain
+ * isolation and prevent lockfile conflicts on main checkout.
+ *
+ * @param cwd - Current working directory to validate
+ * @returns Validation result with error and fix command if invalid
+ */
+export declare function validateWorktreeContext(cwd: string): WorktreeValidationResult;
+/**
+ * Build pnpm add command string from arguments
+ *
+ * @param args - Parsed deps-add arguments
+ * @returns Command string ready for execution
+ */
+export declare function buildPnpmAddCommand(args: DepsAddArgs): string;
+/**
+ * Build pnpm remove command string from arguments
+ *
+ * @param args - Parsed deps-remove arguments
+ * @returns Command string ready for execution
+ */
+export declare function buildPnpmRemoveCommand(args: DepsRemoveArgs): string;

package/dist/deps-remove.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Deps Remove CLI Command
+ *
+ * Safe wrapper for `pnpm remove` that enforces worktree discipline.
+ * Dependencies can only be removed from within a worktree, not from main checkout.
+ *
+ * WU-1112: INIT-003 Phase 6 - Migrate remaining Tier 1 tools
+ *
+ * Usage:
+ *   pnpm deps:remove lodash
+ *   pnpm deps:remove --filter @lumenflow/cli chalk
+ *
+ * @see dependency-guard.ts for blocking logic
+ */
+import { type DepsRemoveArgs } from './deps-add.js';
+export type { DepsRemoveArgs };

package/dist/docs-sync.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file docs-sync.ts
+ * LumenFlow docs:sync command for syncing agent docs to existing projects (WU-1083)
+ * WU-1085: Added createWUParser for proper --help support
+ * WU-1124: Refactored to read templates from bundled files (INIT-004 Phase 2)
+ */
+export type VendorType = 'claude' | 'cursor' | 'aider' | 'all' | 'none';
+/**
+ * WU-1085: Parse docs-sync command options using createWUParser
+ * Provides proper --help, --version, and option parsing
+ */
+export declare function parseDocsSyncOptions(): {
+    force: boolean;
+    vendor: VendorType;
+};
+export interface SyncOptions {
+    force: boolean;
+    vendor?: VendorType;
+}
+export interface SyncResult {
+    created: string[];
+    skipped: string[];
+}
+/**
+ * WU-1124: Get the templates directory path
+ * Templates are bundled with the CLI package at dist/templates/
+ * Falls back to src/templates/ for development
+ */
+export declare function getTemplatesDir(): string;
+/**
+ * WU-1124: Load a template file from the bundled templates directory
+ * @param templatePath - Relative path from templates directory (e.g., 'core/ai/onboarding/quick-ref-commands.md.template')
+ * @returns Template content as string
+ */
+export declare function loadTemplate(templatePath: string): string;
+/**
+ * Sync agent onboarding docs to an existing project
+ * WU-1124: Now reads templates from bundled files instead of hardcoded strings
+ */
+export declare function syncAgentDocs(targetDir: string, options: SyncOptions): Promise<SyncResult>;
+/**
+ * Sync Claude skills to an existing project
+ * WU-1124: Now reads templates from bundled files instead of hardcoded strings
+ */
+export declare function syncSkills(targetDir: string, options: SyncOptions): Promise<SyncResult>;
+/**
+ * CLI entry point for docs:sync command
+ * WU-1085: Updated to use parseDocsSyncOptions for proper --help support
+ */
+export declare function main(): Promise<void>;

package/dist/file-delete.d.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * File Delete CLI Tool
+ *
+ * Provides audited file delete operations with:
+ * - Scope checking against WU code_paths
+ * - Recursive directory deletion
+ * - Force option for missing files
+ * - Audit logging
+ *
+ * Usage:
+ *   node file-delete.js <path> [--recursive] [--force]
+ *
+ * WU-1108: INIT-003 Phase 4a - Migrate file operations
+ */
+/**
+ * Default configuration for file delete operations
+ */
+export declare const FILE_DELETE_DEFAULTS: {
+    /** Delete directories recursively */
+    recursive: boolean;
+    /** Don't error on missing files */
+    force: boolean;
+};
+/**
+ * Arguments for file delete operation
+ */
+export interface FileDeleteArgs {
+    /** Path to file or directory to delete */
+    path?: string;
+    /** Delete directories recursively */
+    recursive?: boolean;
+    /** Don't error on missing files */
+    force?: boolean;
+    /** Show help */
+    help?: boolean;
+}
+/**
+ * Metadata returned with file delete
+ */
+export interface FileDeleteMetadata {
+    /** Number of items deleted (files + directories) */
+    deletedCount: number;
+    /** Whether target was a directory */
+    wasDirectory: 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 delete operation
+ */
+export interface FileDeleteResult {
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Error message (if failed) */
+    error?: string;
+    /** Delete metadata */
+    metadata?: FileDeleteMetadata;
+    /** Audit log entry */
+    auditLog?: AuditLogEntry;
+}
+/**
+ * Parse command line arguments for file-delete
+ */
+export declare function parseFileDeleteArgs(argv: string[]): FileDeleteArgs;
+/**
+ * Delete a file or directory with audit logging and safety checks
+ */
+export declare function deleteFileWithAudit(args: FileDeleteArgs): Promise<FileDeleteResult>;

package/dist/file-edit.d.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * File Edit CLI Tool
+ *
+ * Provides audited file edit operations with:
+ * - Scope checking against WU code_paths
+ * - Exact string replacement
+ * - Uniqueness validation
+ * - Replace-all support
+ * - Audit logging
+ *
+ * Usage:
+ *   node file-edit.js <path> --old-string <old> --new-string <new> [--replace-all]
+ *
+ * WU-1108: INIT-003 Phase 4a - Migrate file operations
+ */
+/**
+ * Default configuration for file edit operations
+ */
+export declare const FILE_EDIT_DEFAULTS: {
+    /** Default encoding */
+    encoding: BufferEncoding;
+    /** Replace all occurrences (default: false - requires unique match) */
+    replaceAll: boolean;
+};
+/**
+ * Arguments for file edit operation
+ */
+export interface FileEditArgs {
+    /** Path to file to edit */
+    path?: string;
+    /** String to find */
+    oldString?: string;
+    /** String to replace with */
+    newString?: string;
+    /** File encoding */
+    encoding?: BufferEncoding;
+    /** Replace all occurrences */
+    replaceAll?: boolean;
+    /** Show help */
+    help?: 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 edit operation
+ */
+export interface FileEditResult {
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Error message (if failed) */
+    error?: string;
+    /** Number of replacements made */
+    replacements?: number;
+    /** Diff preview */
+    diff?: string;
+    /** Audit log entry */
+    auditLog?: AuditLogEntry;
+}
+/**
+ * Parse command line arguments for file-edit
+ */
+export declare function parseFileEditArgs(argv: string[]): FileEditArgs;
+/**
+ * Edit a file with audit logging and safety checks
+ */
+export declare function editFileWithAudit(args: FileEditArgs): Promise<FileEditResult>;

package/dist/file-read.d.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * File Read CLI Tool
+ *
+ * Provides audited file read operations with:
+ * - Scope checking against WU code_paths
+ * - File size limits
+ * - Line range support
+ * - Audit logging
+ *
+ * Usage:
+ *   node file-read.js <path> [--encoding utf-8] [--start-line N] [--end-line M]
+ *
+ * WU-1108: INIT-003 Phase 4a - Migrate file operations
+ */
+/**
+ * Default configuration for file read operations
+ */
+export declare const FILE_READ_DEFAULTS: {
+    /** Maximum file size in bytes (10MB) */
+    maxFileSizeBytes: number;
+    /** Default encoding */
+    encoding: BufferEncoding;
+};
+/**
+ * Arguments for file read operation
+ */
+export interface FileReadArgs {
+    /** Path to file to read */
+    path?: string;
+    /** File encoding */
+    encoding?: BufferEncoding;
+    /** Start line (1-based, inclusive) */
+    startLine?: number;
+    /** End line (1-based, inclusive) */
+    endLine?: number;
+    /** Maximum file size in bytes */
+    maxFileSizeBytes?: number;
+    /** Show help */
+    help?: boolean;
+}
+/**
+ * Metadata returned with file read
+ */
+export interface FileReadMetadata {
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Total line count */
+    lineCount: number;
+    /** Lines returned (if subset) */
+    linesReturned?: number;
+}
+/**
+ * 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 read operation
+ */
+export interface FileReadResult {
+    /** Whether operation succeeded */
+    success: boolean;
+    /** File content (if successful) */
+    content?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** File metadata */
+    metadata?: FileReadMetadata;
+    /** Audit log entry */
+    auditLog?: AuditLogEntry;
+}
+/**
+ * Parse command line arguments for file-read
+ */
+export declare function parseFileReadArgs(argv: string[]): FileReadArgs;
+/**
+ * Read a file with audit logging and safety checks
+ */
+export declare function readFileWithAudit(args: FileReadArgs): Promise<FileReadResult>;