@lumenflow/cli 2.9.0 → 2.11.0

package/README.md

@@ -134,7 +134,7 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 | Command           | Description                                                                                |
 | ----------------- | ------------------------------------------------------------------------------------------ |
 | `gates`           | Run quality gates with support for docs-only mode, incremental linting, and tiered testing |
-| `lumenflow-gates` | Alias for `gates` - run quality gates                                                      |
+| `lumenflow-gates` | Alias for `gates` command                                                                  |
 
 ### System & Setup
 
@@ -202,7 +202,7 @@ pnpm wu:done --id WU-123
 
 # Memory operations
 pnpm mem:checkpoint "Completed port definitions" --wu WU-123
-pnpm mem:inbox --unread
+pnpm mem:inbox --since 10m
 
 # Initiative management
 pnpm initiative:status INIT-007
@@ -245,6 +245,27 @@ The CLI integrates with other LumenFlow packages:
 - `@lumenflow/agent` - Agent session management
 - `@lumenflow/initiatives` - Initiative tracking
 
+## MCP Server Setup (Claude Code)
+
+LumenFlow provides an MCP (Model Context Protocol) server for deep integration with Claude Code.
+
+When you run `lumenflow init --client claude`, a `.mcp.json` is automatically created:
+
+```json
+{
+  "mcpServers": {
+    "lumenflow": {
+      "command": "npx",
+      "args": ["@lumenflow/mcp"]
+    }
+  }
+}
+```
+
+The `@lumenflow/mcp` server provides tools for WU lifecycle, memory coordination, and lane management directly within Claude Code.
+
+See [AI Integrations](https://lumenflow.dev/guides/ai-integrations) for full MCP documentation.
+
 ## Documentation
 
 For complete documentation, see [lumenflow.dev](https://lumenflow.dev/reference/cli).

package/dist/__tests__/gates-integration-tests.test.js

@@ -0,0 +1,112 @@
+/**
+ * @file gates-integration-tests.test.ts
+ * @description Tests for gates infrastructure fixes (WU-1415)
+ *
+ * Bug 1: vitest --include is not a valid CLI option
+ * Bug 2: docs-only turbo filter uses directory names instead of package names
+ */
+import { describe, it, expect } from 'vitest';
+import { extractPackagesFromCodePaths, resolveDocsOnlyTestPlan } from '../gates.js';
+describe('WU-1415: Gates infrastructure fixes', () => {
+    describe('Bug 1: vitest integration test command', () => {
+        it('should NOT use --include flag (vitest does not support it)', async () => {
+            // Import the module to inspect the command construction
+            // We need to verify that runIntegrationTests uses valid vitest syntax
+            //
+            // vitest run accepts positional glob patterns, NOT --include flags:
+            //   WRONG: vitest run --include='**/*.integration.*'
+            //   RIGHT: vitest run '**/*.integration.*'
+            //
+            // This test ensures we're using the correct vitest CLI syntax
+            const gatesModule = await import('../gates.js');
+            // The command construction happens in runIntegrationTests
+            // We can't directly test the internal function, but we can verify
+            // via the module's exported constants or by checking the implementation
+            // doesn't contain --include
+            // Read the source to verify no --include in vitest commands
+            const fs = await import('fs');
+            const path = await import('path');
+            const gatesPath = path.join(import.meta.dirname, '..', 'gates.ts');
+            const source = fs.readFileSync(gatesPath, 'utf-8');
+            // Find the runIntegrationTests function and check it doesn't use --include
+            const integrationTestMatch = source.match(/function runIntegrationTests[\s\S]*?^}/m);
+            if (integrationTestMatch) {
+                const functionBody = integrationTestMatch[0];
+                // vitest run should NOT have --include flags
+                expect(functionBody).not.toMatch(/vitest.*--include/);
+                // Instead, glob patterns should be positional args or via proper config
+                // The fix should pass patterns directly: vitest run 'pattern1' 'pattern2'
+            }
+        });
+    });
+    describe('Bug 2: docs-only turbo filter', () => {
+        describe('extractPackagesFromCodePaths', () => {
+            it('should extract scoped package names from packages/ paths', () => {
+                const codePaths = [
+                    'packages/@lumenflow/cli/src/gates.ts',
+                    'packages/@lumenflow/core/src/index.ts',
+                ];
+                const packages = extractPackagesFromCodePaths(codePaths);
+                expect(packages).toContain('@lumenflow/cli');
+                expect(packages).toContain('@lumenflow/core');
+            });
+            it('should return empty array for apps/ paths that are not real turbo packages', () => {
+                // apps/docs/ directory name is 'docs' but the turbo package might be
+                // named differently (e.g., '@lumenflow/docs' or not exist at all)
+                //
+                // The current implementation returns 'docs' which causes turbo to fail:
+                //   "No package found with name 'docs' in workspace"
+                //
+                // Fix: Either lookup actual package.json name or skip apps
+                const codePaths = ['apps/docs/src/content/docs/', 'apps/github-app/'];
+                const packages = extractPackagesFromCodePaths(codePaths);
+                // Current buggy behavior returns ['docs', 'github-app']
+                // Fixed behavior should either:
+                // - Return actual package names from package.json
+                // - Or return empty array (apps don't have turbo test tasks)
+                //
+                // For now, the fix should skip apps that aren't valid turbo packages
+                // because apps/docs has no test script and apps/github-app was deleted
+                expect(packages).not.toContain('docs');
+                expect(packages).not.toContain('github-app');
+            });
+            it('should handle mixed code_paths (packages + apps + docs)', () => {
+                const codePaths = [
+                    'packages/@lumenflow/cli/src/file.ts',
+                    'apps/docs/astro.config.mjs',
+                    'docs/DISTRIBUTION.md',
+                ];
+                const packages = extractPackagesFromCodePaths(codePaths);
+                // Should include the real package
+                expect(packages).toContain('@lumenflow/cli');
+                // Should NOT include apps (no valid turbo package)
+                expect(packages).not.toContain('docs');
+                // Should NOT include docs/ (not a package)
+                expect(packages.length).toBe(1);
+            });
+            it('should return empty array for pure docs paths', () => {
+                const codePaths = ['docs/01-product/product-lines.md', 'docs/DISTRIBUTION.md'];
+                const packages = extractPackagesFromCodePaths(codePaths);
+                expect(packages).toEqual([]);
+            });
+        });
+        describe('resolveDocsOnlyTestPlan', () => {
+            it('should return skip mode for pure documentation WUs', () => {
+                const plan = resolveDocsOnlyTestPlan({
+                    codePaths: ['docs/README.md', 'apps/docs/content/'],
+                });
+                expect(plan.mode).toBe('skip');
+                expect(plan.packages).toEqual([]);
+            });
+            it('should return filtered mode only for valid package paths', () => {
+                const plan = resolveDocsOnlyTestPlan({
+                    codePaths: ['packages/@lumenflow/cli/src/gates.ts', 'apps/docs/content/'],
+                });
+                expect(plan.mode).toBe('filtered');
+                expect(plan.packages).toContain('@lumenflow/cli');
+                // apps/docs should not be included
+                expect(plan.packages).not.toContain('docs');
+            });
+        });
+    });
+});

package/dist/__tests__/init.test.js

@@ -740,4 +740,229 @@ describe('lumenflow init', () => {
             });
         });
     });
+    // WU-1408: safe-git and pre-commit hook scaffolding
+    describe('WU-1408: safe-git and pre-commit scaffolding', () => {
+        describe('safe-git wrapper', () => {
+            it('should scaffold scripts/safe-git', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const safeGitPath = path.join(tempDir, 'scripts', 'safe-git');
+                expect(fs.existsSync(safeGitPath)).toBe(true);
+            });
+            it('should make safe-git executable', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const safeGitPath = path.join(tempDir, 'scripts', 'safe-git');
+                const stats = fs.statSync(safeGitPath);
+                // Check for executable bit (owner, group, or other)
+                // eslint-disable-next-line no-bitwise
+                const isExecutable = (stats.mode & 0o111) !== 0;
+                expect(isExecutable).toBe(true);
+            });
+            it('should include worktree remove block in safe-git', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const safeGitPath = path.join(tempDir, 'scripts', 'safe-git');
+                const content = fs.readFileSync(safeGitPath, 'utf-8');
+                expect(content).toContain('worktree');
+                expect(content).toContain('remove');
+                expect(content).toContain('BLOCKED');
+            });
+            it('should scaffold safe-git even in minimal mode', async () => {
+                const options = {
+                    force: false,
+                    full: false, // minimal mode
+                };
+                await scaffoldProject(tempDir, options);
+                const safeGitPath = path.join(tempDir, 'scripts', 'safe-git');
+                expect(fs.existsSync(safeGitPath)).toBe(true);
+            });
+        });
+        describe('pre-commit hook', () => {
+            it('should scaffold .husky/pre-commit', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                expect(fs.existsSync(preCommitPath)).toBe(true);
+            });
+            it('should make pre-commit executable', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                const stats = fs.statSync(preCommitPath);
+                // eslint-disable-next-line no-bitwise
+                const isExecutable = (stats.mode & 0o111) !== 0;
+                expect(isExecutable).toBe(true);
+            });
+            it('should NOT run pnpm test in pre-commit hook', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                const content = fs.readFileSync(preCommitPath, 'utf-8');
+                // The pre-commit hook should NOT assume pnpm test exists
+                expect(content).not.toContain('pnpm test');
+                expect(content).not.toContain('npm test');
+            });
+            it('should block commits to main/master in pre-commit', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                const content = fs.readFileSync(preCommitPath, 'utf-8');
+                // Should protect main branch
+                expect(content).toContain('main');
+                expect(content).toContain('BLOCK');
+            });
+            it('should scaffold pre-commit even in minimal mode', async () => {
+                const options = {
+                    force: false,
+                    full: false, // minimal mode
+                };
+                await scaffoldProject(tempDir, options);
+                const preCommitPath = path.join(tempDir, '.husky', 'pre-commit');
+                expect(fs.existsSync(preCommitPath)).toBe(true);
+            });
+        });
+    });
+    // WU-1413: MCP server configuration scaffolding
+    describe('WU-1413: .mcp.json scaffolding', () => {
+        const MCP_JSON_FILE = '.mcp.json';
+        describe('.mcp.json creation with --client claude', () => {
+            it('should scaffold .mcp.json when --client claude is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(true);
+            });
+            it('should include lumenflow MCP server configuration', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                const content = fs.readFileSync(mcpJsonPath, 'utf-8');
+                const mcpConfig = JSON.parse(content);
+                // Should have mcpServers key
+                expect(mcpConfig.mcpServers).toBeDefined();
+                // Should have lumenflow server entry
+                expect(mcpConfig.mcpServers.lumenflow).toBeDefined();
+                // Should use npx command
+                expect(mcpConfig.mcpServers.lumenflow.command).toBe('npx');
+                // Should reference @lumenflow/mcp package
+                expect(mcpConfig.mcpServers.lumenflow.args).toContain('@lumenflow/mcp');
+            });
+            it('should be valid JSON', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                const content = fs.readFileSync(mcpJsonPath, 'utf-8');
+                // Should parse without error
+                expect(() => JSON.parse(content)).not.toThrow();
+            });
+        });
+        describe('.mcp.json creation with --client all', () => {
+            it('should scaffold .mcp.json when --client all is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'all',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(true);
+            });
+        });
+        describe('.mcp.json NOT created with other clients', () => {
+            it('should NOT scaffold .mcp.json when --client none is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'none',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(false);
+            });
+            it('should NOT scaffold .mcp.json when --client cursor is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'cursor',
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(false);
+            });
+            it('should NOT scaffold .mcp.json when no client is specified', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                };
+                await scaffoldProject(tempDir, options);
+                const mcpJsonPath = path.join(tempDir, MCP_JSON_FILE);
+                expect(fs.existsSync(mcpJsonPath)).toBe(false);
+            });
+        });
+        describe('.mcp.json file modes', () => {
+            it('should skip .mcp.json if it already exists (skip mode)', async () => {
+                // Create existing .mcp.json
+                const existingContent = '{"mcpServers":{"custom":{}}}';
+                fs.writeFileSync(path.join(tempDir, MCP_JSON_FILE), existingContent);
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                const result = await scaffoldProject(tempDir, options);
+                expect(result.skipped).toContain(MCP_JSON_FILE);
+                // Content should not be changed
+                const content = fs.readFileSync(path.join(tempDir, MCP_JSON_FILE), 'utf-8');
+                expect(content).toBe(existingContent);
+            });
+            it('should overwrite .mcp.json in force mode', async () => {
+                // Create existing .mcp.json
+                fs.writeFileSync(path.join(tempDir, MCP_JSON_FILE), '{"custom":true}');
+                const options = {
+                    force: true,
+                    full: false,
+                    client: 'claude',
+                };
+                const result = await scaffoldProject(tempDir, options);
+                expect(result.created).toContain(MCP_JSON_FILE);
+                const content = fs.readFileSync(path.join(tempDir, MCP_JSON_FILE), 'utf-8');
+                const mcpConfig = JSON.parse(content);
+                expect(mcpConfig.mcpServers.lumenflow).toBeDefined();
+            });
+        });
+    });
 });

package/dist/__tests__/safe-git.test.js

@@ -13,7 +13,7 @@ const USER_NAME_CONFIG = 'user.name';
 const TEST_EMAIL = 'test@test.com';
 const TEST_USERNAME = 'Test';
 const FORCE_BYPASSES_LOG = 'force-bypasses.log';
-// Create a temporary directory for testing to avoid polluting the real .beacon directory
+// Create a temporary directory for testing to avoid polluting the real .lumenflow directory
 const createTempDir = () => {
     return fs.mkdtempSync(path.join(os.tmpdir(), 'safe-git-test-'));
 };
@@ -128,7 +128,7 @@ describe('safe-git', () => {
                 env: { ...process.env, LUMENFLOW_FORCE: '1' },
             });
             // Check that the force bypass log exists and contains the entry
-            const bypassLog = path.join(testRepo, '.beacon', FORCE_BYPASSES_LOG);
+            const bypassLog = path.join(testRepo, '.lumenflow', FORCE_BYPASSES_LOG);
             expect(fs.existsSync(bypassLog)).toBe(true);
             const logContent = fs.readFileSync(bypassLog, 'utf-8');
             expect(logContent).toContain('reset --hard');
@@ -155,7 +155,7 @@ describe('safe-git', () => {
                 encoding: 'utf-8',
                 env: { ...process.env, LUMENFLOW_FORCE: '1', LUMENFLOW_FORCE_REASON: testReason },
             });
-            const bypassLog = path.join(testRepo, '.beacon', FORCE_BYPASSES_LOG);
+            const bypassLog = path.join(testRepo, '.lumenflow', FORCE_BYPASSES_LOG);
             const logContent = fs.readFileSync(bypassLog, 'utf-8');
             expect(logContent).toContain(testReason);
         });
@@ -182,7 +182,7 @@ describe('safe-git', () => {
                 stdio: ['pipe', 'pipe', 'pipe'],
             });
             // Check the bypasslog for the NO_REASON marker
-            const bypassLog = path.join(testRepo, '.beacon', FORCE_BYPASSES_LOG);
+            const bypassLog = path.join(testRepo, '.lumenflow', FORCE_BYPASSES_LOG);
             const logContent = fs.readFileSync(bypassLog, 'utf-8');
             expect(logContent).toContain('NO_REASON');
         });

package/dist/__tests__/wu-create-required-fields.test.js

@@ -82,6 +82,28 @@ describe('wu:create required field aggregation (WU-1366)', () => {
             expect(result.valid).toBe(false);
             expect(result.errors.some((e) => e.includes('--spec-refs'))).toBe(true);
         });
+        it('should treat empty spec-refs array as missing for feature WUs', () => {
+            const result = validateCreateSpec({
+                id: TEST_WU_ID,
+                lane: TEST_LANE,
+                title: 'Test WU',
+                priority: 'P2',
+                type: 'feature',
+                opts: {
+                    description: VALID_DESCRIPTION,
+                    acceptance: TEST_ACCEPTANCE,
+                    exposure: 'backend-only',
+                    codePaths: ['packages/@lumenflow/cli/src/wu-create.ts'],
+                    testPathsUnit: [
+                        'packages/@lumenflow/cli/src/__tests__/wu-create-required-fields.test.ts',
+                    ],
+                    specRefs: [],
+                    strict: false,
+                },
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes('--spec-refs'))).toBe(true);
+        });
         it('should return all errors at once, not fail on first error', () => {
             const result = validateCreateSpec({
                 id: TEST_WU_ID,

package/dist/__tests__/wu-create.test.js

@@ -0,0 +1,72 @@
+/**
+ * @file wu-create.test.ts
+ * Tests for wu:create helpers and warnings (WU-1429)
+ */
+import { describe, it, expect } from 'vitest';
+import { buildWUContent, collectInitiativeWarnings } from '../wu-create.js';
+const BASE_WU = {
+    id: 'WU-1429',
+    lane: 'Framework: CLI',
+    title: 'Test WU',
+    priority: 'P2',
+    type: 'feature',
+    created: '2026-02-04',
+    opts: {
+        description: 'Context: test context.\nProblem: test problem.\nSolution: test solution that exceeds minimum.',
+        acceptance: ['Acceptance criterion'],
+        exposure: 'backend-only',
+        codePaths: ['packages/@lumenflow/cli/src/wu-create.ts'],
+        testPathsUnit: ['packages/@lumenflow/cli/src/__tests__/wu-create.test.ts'],
+        specRefs: ['lumenflow://plans/WU-1429-plan.md'],
+    },
+};
+describe('wu:create helpers (WU-1429)', () => {
+    it('should persist notes when provided', () => {
+        const wu = buildWUContent({
+            ...BASE_WU,
+            opts: {
+                ...BASE_WU.opts,
+                notes: 'Implementation notes for test',
+            },
+        });
+        expect(wu.notes).toBe('Implementation notes for test');
+    });
+    it('should warn when initiative has phases but no --phase is provided', () => {
+        const warnings = collectInitiativeWarnings({
+            initiativeId: 'INIT-TEST',
+            initiativeDoc: {
+                phases: [{ id: 1, title: 'Phase 1' }],
+            },
+            phase: undefined,
+            specRefs: ['lumenflow://plans/WU-1429-plan.md'],
+        });
+        expect(warnings).toEqual(expect.arrayContaining([
+            'Initiative INIT-TEST has phases defined. Consider adding --phase to link this WU to a phase.',
+        ]));
+    });
+    it('should warn when initiative has related_plan but no spec_refs', () => {
+        const warnings = collectInitiativeWarnings({
+            initiativeId: 'INIT-TEST',
+            initiativeDoc: {
+                related_plan: 'lumenflow://plans/INIT-TEST-plan.md',
+            },
+            phase: '1',
+            specRefs: [],
+        });
+        expect(warnings).toEqual(expect.arrayContaining([
+            'Initiative INIT-TEST has related_plan (lumenflow://plans/INIT-TEST-plan.md). Consider adding --spec-refs to link this WU to the plan.',
+        ]));
+    });
+    it('should not warn when phase and spec_refs are provided', () => {
+        const warnings = collectInitiativeWarnings({
+            initiativeId: 'INIT-TEST',
+            initiativeDoc: {
+                phases: [{ id: 1, title: 'Phase 1' }],
+                related_plan: 'lumenflow://plans/INIT-TEST-plan.md',
+            },
+            phase: '1',
+            specRefs: ['lumenflow://plans/WU-1429-plan.md'],
+        });
+        expect(warnings).toEqual([]);
+    });
+});

package/dist/gates.js

@@ -294,13 +294,9 @@ function extractPackageFromPath(codePath) {
             return parts[0];
         }
     }
-    // Handle apps/name/...
-    if (normalized.startsWith('apps/')) {
-        const parts = normalized.slice('apps/'.length).split('/');
-        if (parts[0]) {
-            return parts[0];
-        }
-    }
+    // WU-1415: Skip apps/ paths - they aren't valid turbo packages for test filtering
+    // apps/ directories (e.g., apps/docs, apps/github-app) don't have turbo test tasks
+    // and using directory names as --filter args causes "No package found" errors
     return null;
 }
 /**
@@ -1004,7 +1000,9 @@ async function runIntegrationTests({ agentLog, } = {}) {
     };
     try {
         logLine('\n> Integration tests (high-risk changes detected)\n');
-        const result = run(`RUN_INTEGRATION_TESTS=1 ${pnpmCmd('vitest', 'run', "--include='**/*.integration.*'", "--include='**/golden-*.test.*'")}`, { agentLog });
+        // WU-1415: vitest doesn't support --include flag
+        // Pass glob patterns as positional arguments instead
+        const result = run(`RUN_INTEGRATION_TESTS=1 ${pnpmCmd('vitest', 'run', "'**/*.integration.*'", "'**/golden-*.test.*'")}`, { agentLog });
         const duration = Date.now() - start;
         return {
             ok: result.ok,