@lumenflow/cli 2.2.2 → 2.3.1

package/README.md

@@ -13,6 +13,25 @@
 npm install @lumenflow/cli
 ```
 
+## Quick Start
+
+```bash
+# Initialize LumenFlow (works with any AI)
+npx lumenflow-init
+
+# Or specify your AI tool for enhanced integration
+npx lumenflow-init --client claude    # Claude Code
+npx lumenflow-init --client cursor    # Cursor
+npx lumenflow-init --client windsurf  # Windsurf
+npx lumenflow-init --client cline     # Cline
+npx lumenflow-init --client aider     # Aider
+npx lumenflow-init --client all       # All integrations
+```
+
+The default `lumenflow-init` creates `AGENTS.md` and `LUMENFLOW.md` which work with **any AI coding assistant**. The `--client` flag adds vendor-specific configuration files for deeper integration.
+
+See [AI Integrations](https://lumenflow.dev/guides/ai-integrations) for details on each tool.
+
 ## Overview
 
 This package provides CLI commands for the LumenFlow workflow framework, including:
@@ -24,63 +43,134 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 
 ## Commands
 
-### Work Unit Commands
-
-| Command         | Description                                          |
-| --------------- | ---------------------------------------------------- |
-| `wu-claim`      | Claim a WU and create a worktree                     |
-| `wu-done`       | Complete a WU (runs gates, merges, creates stamp)    |
-| `wu-block`      | Mark a WU as blocked with reason                     |
-| `wu-unblock`    | Remove blocked status from a WU                      |
-| `wu-create`     | Create a new WU specification                        |
-| `wu-edit`       | Edit an existing WU specification                    |
-| `wu-spawn`      | Generate spawn prompt for delegating WU to sub-agent |
-| `wu-validate`   | Validate WU YAML against schema                      |
-| `wu-preflight`  | Pre-claim validation checks                          |
-| `wu-repair`     | Repair corrupted WU state                            |
-| `wu-prune`      | Clean up stale worktrees                             |
-| `wu-cleanup`    | Post-merge cleanup for a WU                          |
-| `wu-deps`       | Display WU dependency graph                          |
-| `wu-infer-lane` | Infer lane from WU content                           |
-
-### Memory Commands
-
-| Command          | Description                              |
-| ---------------- | ---------------------------------------- |
-| `mem-init`       | Initialize memory directory structure    |
-| `mem-start`      | Start a new memory session               |
-| `mem-checkpoint` | Create a progress checkpoint             |
-| `mem-ready`      | Query pending nodes for a WU             |
-| `mem-signal`     | Send coordination signal to other agents |
-| `mem-inbox`      | Check incoming coordination signals      |
-| `mem-create`     | Create a memory node                     |
-| `mem-summarize`  | Roll up nodes for context compaction     |
-| `mem-triage`     | Triage discovered bugs                   |
-| `mem-cleanup`    | Clean up expired memory nodes            |
-
-### Initiative Commands
-
-| Command             | Description                         |
-| ------------------- | ----------------------------------- |
-| `initiative-create` | Create a new initiative             |
-| `initiative-edit`   | Edit an existing initiative         |
-| `initiative-list`   | List all initiatives                |
-| `initiative-status` | Show initiative status and progress |
-| `initiative-add-wu` | Link a WU to an initiative          |
-
-### Setup Commands
-
-| Command     | Description                                         |
-| ----------- | --------------------------------------------------- |
-| `init`      | Scaffold LumenFlow into a project                   |
-| `docs-sync` | Sync agent onboarding docs (for upgrading projects) |
-
-### Other Commands
-
-| Command      | Description                                        |
-| ------------ | -------------------------------------------------- |
-| `gates`      | Run quality gates (format, lint, typecheck, tests) |
-| `spawn-list` | List active spawned agents                         |
+### Work Unit Management
+
+| Command          | Description                                                                                                 |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `wu-block`       | Block a work unit and move it from in-progress to blocked status                                            |
+| `wu-claim`       | Claim a work unit by creating a worktree/branch and updating status                                         |
+| `wu-cleanup`     | Clean up worktree and branch after PR merge (PR-based completion workflow)                                  |
+| `wu-create`      | Create a new Work Unit with micro-worktree isolation (race-safe). Auto-generates ID if `--id` not provided. |
+| `wu-delete`      | Safely delete WU YAML files with micro-worktree isolation                                                   |
+| `wu-deps`        | Visualize WU dependency graph                                                                               |
+| `wu-done`        | Complete a WU (runs gates, merges, creates stamp)                                                           |
+| `wu-edit`        | Edit WU spec files with micro-worktree isolation                                                            |
+| `wu-infer-lane`  | Suggest sub-lane for a WU based on content                                                                  |
+| `wu-preflight`   | Fast validation of code paths and test paths before gates                                                   |
+| `wu-prune`       | Maintain worktree hygiene (prune stale worktrees, detect orphans)                                           |
+| `wu-recover`     | Analyze and fix WU state inconsistencies                                                                    |
+| `wu-release`     | Release an orphaned WU from in_progress back to ready state                                                 |
+| `wu-repair`      | Unified WU repair tool - detect and fix WU state issues                                                     |
+| `wu-spawn`       | Generate Task tool invocation for sub-agent WU execution                                                    |
+| `wu-status`      | Show WU status, location, and valid commands                                                                |
+| `wu-unblock`     | Unblock a work unit and move it from blocked to in-progress status                                          |
+| `wu-unlock-lane` | Safely unlock a lane lock with audit logging                                                                |
+| `wu-validate`    | Validate WU YAML files against schema                                                                       |
+
+### Memory & Session
+
+| Command               | Description                                                 |
+| --------------------- | ----------------------------------------------------------- |
+| `agent-issues-query`  | Show summary of logged issues                               |
+| `agent-log-issue`     | Log a workflow issue or incident                            |
+| `agent-session`       | Start an agent session                                      |
+| `agent-session-end`   | End the current agent session                               |
+| `mem-checkpoint`      | Create a checkpoint node for context snapshots              |
+| `mem-cleanup`         | Prune closed memory nodes based on lifecycle policy and TTL |
+| `mem-create`          | Create a memory node with optional provenance tracking      |
+| `mem-export`          | Export memory nodes as markdown or JSON                     |
+| `mem-inbox`           | Read coordination signals from other agents                 |
+| `mem-init`            | Initialize memory layer in repository                       |
+| `mem-ready`           | Query ready nodes for a WU (deterministic ordering)         |
+| `mem-signal`          | Send a coordination signal to other agents                  |
+| `mem-start`           | Create a session node linked to a WU                        |
+| `mem-summarize`       | Rollup older memory nodes into summary nodes for compaction |
+| `mem-triage`          | Review discovery nodes and promote to WUs or archive        |
+| `session-coordinator` | Manage agent sessions for WU work coordination              |
+| `signal-cleanup`      | Prune old signals based on TTL policy to prevent growth     |
+
+### Initiative Orchestration
+
+| Command                      | Description                                                   |
+| ---------------------------- | ------------------------------------------------------------- |
+| `init-plan`                  | Link a plan file to an initiative                             |
+| `initiative-add-wu`          | Link a WU to an initiative bidirectionally                    |
+| `initiative-bulk-assign-wus` | Bulk-assign orphaned WUs to initiatives based on lane rules   |
+| `initiative-create`          | Create a new Initiative with micro-worktree isolation         |
+| `initiative-edit`            | Edit Initiative YAML files with micro-worktree isolation      |
+| `initiative-list`            | List all initiatives with progress percentages                |
+| `initiative-status`          | Show detailed initiative view with phases and WUs             |
+| `orchestrate-init-status`    | Show initiative progress status                               |
+| `orchestrate-initiative`     | Orchestrate initiative execution with parallel agent spawning |
+| `orchestrate-monitor`        | Monitor spawned agent progress                                |
+| `rotate-progress`            | Move completed WUs from status.md to Completed section        |
+| `spawn-list`                 | Display spawn trees for WUs or initiatives                    |
+
+### Metrics & Analytics
+
+| Command             | Description                                                    |
+| ------------------- | -------------------------------------------------------------- |
+| `flow-bottlenecks`  | Analyze WU dependency graph for bottlenecks and critical paths |
+| `flow-report`       | Generate DORA/SPACE flow report from telemetry and WU data     |
+| `lumenflow-metrics` | LumenFlow metrics CLI (lanes, dora, flow)                      |
+| `metrics`           | Alias for `lumenflow-metrics`                                  |
+| `metrics-snapshot`  | Capture DORA metrics, lane health, and flow state snapshot     |
+| `trace-gen`         | Generate traceability reports linking WUs to code changes      |
+
+### Lane Tooling
+
+| Command        | Description                                                           |
+| -------------- | --------------------------------------------------------------------- |
+| `lane-health`  | Check lane configuration health (overlaps, coverage gaps)             |
+| `lane-suggest` | LLM-driven lane suggestions based on codebase context and git history |
+
+### Verification & Gates
+
+| Command                 | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| `gates`                 | Run quality gates (format, lint, typecheck, tests)        |
+| `guard-locked`          | Check if a WU is locked (exits 1 if locked)               |
+| `guard-main-branch`     | Check if current branch is protected and block operations |
+| `guard-worktree-commit` | Check if a WU commit should be blocked from main checkout |
+| `lumenflow-gates`       | Alias for `gates`                                         |
+| `lumenflow-validate`    | Validate WU YAML files for schema and quality             |
+| `validate`              | Alias for `lumenflow-validate`                            |
+| `validate-agent-skills` | Validate agent skill definitions                          |
+| `validate-agent-sync`   | Validate agent configuration and sync state               |
+| `validate-backlog-sync` | Validate that backlog.md is in sync with WU YAML files    |
+| `validate-skills-spec`  | Validate skill specification format                       |
+
+### System & Setup
+
+| Command                    | Description                                               |
+| -------------------------- | --------------------------------------------------------- |
+| `backlog-prune`            | Maintain backlog hygiene (archive old WUs)                |
+| `deps-add`                 | Add dependencies with worktree discipline enforcement     |
+| `deps-remove`              | Remove dependencies with worktree discipline enforcement  |
+| `lumenflow`                | CLI entry point (scaffold/init)                           |
+| `lumenflow-docs-sync`      | Sync agent onboarding docs to existing projects           |
+| `lumenflow-init`           | Initialize LumenFlow in a project                         |
+| `lumenflow-release`        | Release @lumenflow/\* packages to npm                     |
+| `lumenflow-sync-templates` | Sync internal docs to CLI templates                       |
+| `lumenflow-upgrade`        | Upgrade all @lumenflow/\* packages to a specified version |
+| `state-bootstrap`          | One-time migration utility for state sourcing             |
+| `state-cleanup`            | Unified cleanup: signals, memory, and event archival      |
+| `state-doctor`             | Check state integrity and detect inconsistencies          |
+| `lumenflow-doctor`         | Alias for `state-doctor`                                  |
+| `sync-templates`           | Alias for `lumenflow-sync-templates`                      |
+
+### File & Git Operations
+
+| Command       | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| `file-delete` | Delete a file or directory with audit logging                  |
+| `file-edit`   | Edit file by replacing exact string matches with audit logging |
+| `file-read`   | Read file content with audit logging                           |
+| `file-write`  | Write content to a file with audit logging                     |
+| `git-branch`  | List, create, or delete branches                               |
+| `git-diff`    | Show changes between commits, commit and working tree          |
+| `git-log`     | Show commit logs                                               |
+| `git-status`  | Show the working tree status                                   |
 
 ## Usage
 

package/dist/__tests__/agent-log-issue.test.js

@@ -0,0 +1,56 @@
+/**
+ * Tests for agent-log-issue CLI
+ *
+ * WU-1182: Validates that agent-log-issue.ts uses Commander.js repeatable
+ * options pattern instead of comma-separated splits for --tags and --files.
+ *
+ * Per Commander.js best practices:
+ * - Repeatable: --tag a --tag b → ['a', 'b'] (explicit, no ambiguity)
+ * - Comma-split: --tags "a,b" → splits on comma (ambiguous if values contain commas)
+ *
+ * The repeatable pattern is preferred for multi-value options.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+describe('WU-1182: agent-log-issue CLI patterns', () => {
+    const srcDir = path.resolve(__dirname, '..');
+    const filePath = path.join(srcDir, 'agent-log-issue.ts');
+    const content = readFileSync(filePath, 'utf-8');
+    describe('--tags option', () => {
+        it('should use repeatable pattern instead of comma-separated', () => {
+            // Should NOT have comma-split pattern for tags
+            const hasCommaSplit = /opts\.tags\s*\?\s*opts\.tags\.split\s*\(\s*['"],['"]/.test(content);
+            expect(hasCommaSplit, 'should not use comma-split for --tags').toBe(false);
+        });
+        it('should define --tag as repeatable option (not --tags with comma)', () => {
+            // Should have repeatable option pattern with collect function
+            // Either using Commander's variadic syntax (...) or custom collect function
+            const hasRepeatableTag = /\.option\s*\(\s*['"]--tag\s+</.test(content) ||
+                /\.option\s*\(\s*['"]--tags?\s+<[^>]+>\.\.\./.test(content) ||
+                /collect(?:Repeatable)?/.test(content);
+            expect(hasRepeatableTag, 'should use repeatable --tag option or collect function').toBe(true);
+        });
+    });
+    describe('--files option', () => {
+        it('should use repeatable pattern instead of comma-separated', () => {
+            // Should NOT have comma-split pattern for files
+            const hasCommaSplit = /opts\.files\s*\?\s*opts\.files\.split\s*\(\s*['"],['"]/.test(content);
+            expect(hasCommaSplit, 'should not use comma-split for --files').toBe(false);
+        });
+        it('should define --file as repeatable option (not --files with comma)', () => {
+            // Should have repeatable option pattern
+            const hasRepeatableFile = /\.option\s*\(\s*['"]--file\s+</.test(content) ||
+                /\.option\s*\(\s*['"]--files?\s+<[^>]+>\.\.\./.test(content) ||
+                /collect(?:Repeatable)?/.test(content);
+            expect(hasRepeatableFile, 'should use repeatable --file option or collect function').toBe(true);
+        });
+    });
+    describe('Commander.js best practices', () => {
+        it('should not import comma-split utility functions', () => {
+            // Should not have custom comma-split helper
+            const hasCommaSplitHelper = /commaSeparatedList|splitComma/.test(content);
+            expect(hasCommaSplitHelper, 'should not use comma-split helpers').toBe(false);
+        });
+    });
+});

package/dist/__tests__/cli-entry-point.test.js

@@ -10,7 +10,7 @@
  * instead of the broken process.argv[1] === fileURLToPath(import.meta.url) pattern.
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { runCLI } from '../cli-entry-point.js';
 import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
@@ -54,7 +54,7 @@ describe('runCLI', () => {
     });
 });
 /**
- * WU-1071: Verify CLI entry points use import.meta.main pattern
+ * WU-1071/WU-1181: Verify CLI entry points use import.meta.main pattern
  *
  * The old pattern `process.argv[1] === fileURLToPath(import.meta.url)` fails with
  * pnpm symlinks because process.argv[1] is the symlink path but import.meta.url
@@ -62,34 +62,80 @@ describe('runCLI', () => {
  *
  * The fix is to use `import.meta.main` (Node.js 22.16.0+ built-in) which correctly
  * handles symlinks.
+ *
+ * WU-1181: Extended to validate ALL CLI files with entry guards, not just a subset.
  */
-describe('WU-1071: CLI entry point patterns', () => {
-    // CLI files that should have the main() entry guard
-    const CLI_FILES_WITH_ENTRY_GUARD = [
-        'gates.ts',
-        'wu-spawn.ts',
-        'wu-create.ts',
-        'wu-claim.ts',
-        'wu-done.ts',
-    ];
+describe('WU-1071/WU-1181: CLI entry point patterns', () => {
+    // Files that should NOT be checked for entry guards
+    // (helper modules, index files, tests, or files without CLI entry points)
+    const EXCLUDED_FILES = new Set([
+        'cli-entry-point.ts', // Helper module, not a CLI entry point itself
+        'index.ts', // Re-exports only
+        'merge-block.ts', // Not a CLI entry point (no main guard needed)
+        'wu-done-check.ts', // Not a CLI entry point (no main guard needed)
+        'wu-spawn-completion.ts', // Not a CLI entry point (helper module)
+        'agent-session.ts', // Not a CLI entry point (helper module)
+        'agent-session-end.ts', // Not a CLI entry point (helper module)
+        'agent-log-issue.ts', // Not a CLI entry point (helper module)
+        'orchestrate-init-status.ts', // Not a CLI entry point (helper module)
+        'orchestrate-initiative.ts', // Not a CLI entry point (helper module)
+        'orchestrate-monitor.ts', // Not a CLI entry point (helper module)
+        'initiative-edit.ts', // Not a CLI entry point (no main guard)
+        'wu-block.ts', // Not a CLI entry point (no main guard)
+        'wu-unblock.ts', // Not a CLI entry point (no main guard)
+        'wu-release.ts', // Not a CLI entry point (no main guard)
+        'wu-delete.ts', // Not a CLI entry point (no main guard)
+        'init.ts', // Not a CLI entry point (no main guard)
+    ]);
     // Old broken pattern that fails with pnpm symlinks
     const OLD_BROKEN_PATTERN = /if\s*\(\s*process\.argv\[1\]\s*===\s*fileURLToPath\(import\.meta\.url\)\s*\)/;
     // New working pattern using import.meta.main
     const NEW_WORKING_PATTERN = /if\s*\(\s*import\.meta\.main\s*\)/;
-    it('should use import.meta.main instead of process.argv[1] comparison', () => {
+    /**
+     * Discovers all CLI files with entry guards by scanning the src directory.
+     * A file is considered to have an entry guard if it contains either:
+     * - The old broken pattern: if (process.argv[1] === fileURLToPath(import.meta.url))
+     * - The new working pattern: if (import.meta.main)
+     */
+    function discoverCLIFilesWithEntryGuards() {
+        const srcDir = path.resolve(__dirname, '..');
+        const files = readdirSync(srcDir).filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts') && !EXCLUDED_FILES.has(f));
+        return files.filter((file) => {
+            const content = readFileSync(path.join(srcDir, file), 'utf-8');
+            return OLD_BROKEN_PATTERN.test(content) || NEW_WORKING_PATTERN.test(content);
+        });
+    }
+    it('should discover all CLI files with entry guards', () => {
+        const cliFiles = discoverCLIFilesWithEntryGuards();
+        // WU-1181: There should be a significant number of CLI files with entry guards
+        // This test ensures we're actually discovering files, not returning an empty list
+        expect(cliFiles.length).toBeGreaterThan(40);
+    });
+    it('should use import.meta.main instead of process.argv[1] comparison in ALL CLI files', () => {
         const srcDir = path.resolve(__dirname, '..');
-        for (const file of CLI_FILES_WITH_ENTRY_GUARD) {
+        const cliFiles = discoverCLIFilesWithEntryGuards();
+        const errors = [];
+        for (const file of cliFiles) {
             const filePath = path.join(srcDir, file);
             const content = readFileSync(filePath, 'utf-8');
             // Should NOT have old broken pattern
-            expect(OLD_BROKEN_PATTERN.test(content), `${file} should not use the old broken pattern (process.argv[1] === fileURLToPath)`).toBe(false);
+            if (OLD_BROKEN_PATTERN.test(content)) {
+                errors.push(`${file} uses the old broken pattern (process.argv[1] === fileURLToPath)`);
+            }
             // Should have new working pattern
-            expect(NEW_WORKING_PATTERN.test(content), `${file} should use import.meta.main pattern`).toBe(true);
+            if (!NEW_WORKING_PATTERN.test(content)) {
+                errors.push(`${file} does not use import.meta.main pattern`);
+            }
+        }
+        if (errors.length > 0) {
+            expect.fail(`Entry point pattern violations:\n${errors.join('\n')}`);
         }
     });
     it('should not have unused fileURLToPath imports in CLI files with entry guards', () => {
         const srcDir = path.resolve(__dirname, '..');
-        for (const file of CLI_FILES_WITH_ENTRY_GUARD) {
+        const cliFiles = discoverCLIFilesWithEntryGuards();
+        const errors = [];
+        for (const file of cliFiles) {
             const filePath = path.join(srcDir, file);
             const content = readFileSync(filePath, 'utf-8');
             // If the file imports fileURLToPath, it should actually use it somewhere
@@ -97,9 +143,12 @@ describe('WU-1071: CLI entry point patterns', () => {
             const hasFileURLToPathImport = /import\s*{[^}]*fileURLToPath[^}]*}\s*from\s*['"]node:url['"]/.test(content);
             const usesFileURLToPath = /fileURLToPath\(/.test(content);
             if (hasFileURLToPathImport && !usesFileURLToPath) {
-                expect.fail(`${file} imports fileURLToPath but does not use it - remove unused import`);
+                errors.push(`${file} imports fileURLToPath but does not use it - remove unused import`);
             }
         }
+        if (errors.length > 0) {
+            expect.fail(`Unused fileURLToPath imports:\n${errors.join('\n')}`);
+        }
     });
     it('cli-entry-point.ts JSDoc should document import.meta.main pattern', () => {
         const srcDir = path.resolve(__dirname, '..');

package/dist/__tests__/cli-subprocess.test.js

@@ -61,4 +61,29 @@ describe('CLI subprocess error handling', () => {
             expect(result.stderr.length + result.stdout.length).toBeGreaterThan(0);
         });
     });
+    describe('wu-preflight (WU-1180)', () => {
+        it('should show proper Commander help when --help is passed', () => {
+            const result = runCLI('wu-preflight', ['--help']);
+            // Help should work
+            expect(result.code).toBe(0);
+            expect(result.stdout).toContain('Usage');
+            expect(result.stdout).toContain('Options');
+            // Should have the standard Commander format with -h, --help
+            expect(result.stdout).toMatch(/-h,\s*--help/);
+        });
+        it('should show proper Commander help format with option descriptions', () => {
+            const result = runCLI('wu-preflight', ['--help']);
+            expect(result.code).toBe(0);
+            // Should include option descriptions in Commander format
+            expect(result.stdout).toContain('--id');
+            expect(result.stdout).toContain('--worktree');
+        });
+        it('should exit with non-zero code when required --id option is missing', () => {
+            const result = runCLI('wu-preflight', []);
+            // Should NOT exit 0 (silent failure)
+            expect(result.code).not.toBe(0);
+            // Should have some error output
+            expect(result.stderr.length + result.stdout.length).toBeGreaterThan(0);
+        });
+    });
 });