@lumenflow/cli 2.10.0 → 2.12.0

package/README.md

@@ -101,7 +101,7 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 
 | Command                      | Description                                                        |
 | ---------------------------- | ------------------------------------------------------------------ |
-| `initiative-add-wu`          | Link a WU to an initiative bidirectionally                         |
+| `initiative-add-wu`          | Link one or more WUs to an initiative bidirectionally              |
 | `initiative-bulk-assign-wus` | Bulk-assign orphaned WUs to initiatives based on lane prefix rules |
 | `initiative-create`          | Create a new Initiative with micro-worktree isolation (race-safe)  |
 | `initiative-edit`            | Edit Initiative YAML files with micro-worktree isolation           |
@@ -131,21 +131,15 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 
 ### Verification & Gates
 
-| 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 with support for docs-only mode and tiered testing   |
+| Command | Description                                                                                |
+| ------- | ------------------------------------------------------------------------------------------ |
+| `gates` | Run quality gates with support for docs-only mode, incremental linting, and tiered testing |
 
 ### System & Setup
 
 | Command                    | Description                                                                       |
 | -------------------------- | --------------------------------------------------------------------------------- |
 | `backlog-prune`            | Backlog Prune Command                                                             |
-| `deps-add`                 | Deps Add CLI Command                                                              |
-| `deps-remove`              | Deps Remove CLI Command                                                           |
-| `guard-locked`             |                                                                                   |
-| `guard-main-branch`        | Guard Main Branch CLI Tool                                                        |
-| `guard-worktree-commit`    |                                                                                   |
 | `init-plan`                | Link a plan file to an initiative                                                 |
 | `lumenflow`                | Initialize LumenFlow in a project\n\n                                             |
 | `lumenflow-commands`       | List all available LumenFlow CLI commands                                         |
@@ -162,19 +156,12 @@ This package provides CLI commands for the LumenFlow workflow framework, includi
 | `plan-edit`                | Edit a section in a plan file                                                     |
 | `plan-link`                | Link a plan file to a WU or initiative                                            |
 | `plan-promote`             | Promote a plan to approved status                                                 |
-| `rotate-progress`          | Rotate Progress CLI Command                                                       |
-| `session-coordinator`      | Session Coordinator CLI Command                                                   |
 | `signal-cleanup`           | Prune old signals based on TTL policy to prevent unbounded growth                 |
 | `state-bootstrap`          | State Bootstrap Command                                                           |
 | `state-cleanup`            | Orchestrate all state cleanup: signals, memory, events                            |
 | `state-doctor`             | Check state integrity and optionally repair issues                                |
 | `sync-templates`           | Sync internal docs to CLI templates for release-cycle maintenance                 |
-| `trace-gen`                | Trace Generator CLI Command                                                       |
 | `validate`                 |                                                                                   |
-| `validate-agent-skills`    |                                                                                   |
-| `validate-agent-sync`      |                                                                                   |
-| `validate-backlog-sync`    |                                                                                   |
-| `validate-skills-spec`     |                                                                                   |
 
 ### File & Git Operations
 
@@ -202,7 +189,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 +232,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).
@@ -271,3 +279,5 @@ For detailed upgrade instructions, migration guides, and troubleshooting, see [U
 ## License
 
 Apache-2.0
+
+<!-- MODIFIED -->

package/dist/__tests__/commands.test.js

@@ -1,12 +1,23 @@
 /**
  * @file commands.test.ts
  * Tests for lumenflow commands discovery feature (WU-1378)
+ * Extended for public CLI manifest alignment (WU-1432)
  *
- * Tests the new commands subcommand that lists all available CLI commands
- * grouped by category with brief descriptions.
+ * Tests the commands subcommand that lists all available CLI commands
+ * grouped by category with brief descriptions. Also verifies alignment
+ * between public-manifest.ts, commands.ts, and package.json bin entries.
  */
 import { describe, it, expect } from 'vitest';
 import { getCommandsRegistry, formatCommandsOutput } from '../commands.js';
+import { getPublicManifest, getPublicCommandNames, getPublicBinNames, isPublicCommand, } from '../public-manifest.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '../../package.json');
+// Script commands that are NOT CLI binaries (pnpm scripts only)
+// These appear in the registry but should NOT be in the manifest
+const SCRIPT_COMMANDS = new Set(['format', 'lint', 'typecheck', 'test', 'setup']);
 describe('lumenflow commands', () => {
     describe('getCommandsRegistry', () => {
         it('should return command categories', () => {
@@ -73,3 +84,188 @@ describe('lumenflow commands', () => {
         });
     });
 });
+// ============================================================================
+// WU-1432: Public CLI Manifest Tests
+// ============================================================================
+describe('public CLI manifest (WU-1432)', () => {
+    describe('getPublicManifest', () => {
+        it('should return an array of public commands', () => {
+            const manifest = getPublicManifest();
+            expect(manifest).toBeDefined();
+            expect(Array.isArray(manifest)).toBe(true);
+            expect(manifest.length).toBeGreaterThan(0);
+        });
+        it('should have required fields for each command', () => {
+            const manifest = getPublicManifest();
+            for (const cmd of manifest) {
+                expect(cmd.name).toBeDefined();
+                expect(typeof cmd.name).toBe('string');
+                expect(cmd.name.length).toBeGreaterThan(0);
+                expect(cmd.binName).toBeDefined();
+                expect(typeof cmd.binName).toBe('string');
+                expect(cmd.binName.length).toBeGreaterThan(0);
+                expect(cmd.description).toBeDefined();
+                expect(typeof cmd.description).toBe('string');
+                expect(cmd.description.length).toBeGreaterThan(0);
+                expect(cmd.category).toBeDefined();
+                expect(typeof cmd.category).toBe('string');
+                expect(cmd.category.length).toBeGreaterThan(0);
+            }
+        });
+        it('should include core public commands', () => {
+            const names = getPublicCommandNames();
+            // WU lifecycle - must be public
+            expect(names).toContain('wu:create');
+            expect(names).toContain('wu:claim');
+            expect(names).toContain('wu:done');
+            expect(names).toContain('wu:prep');
+            expect(names).toContain('wu:status');
+            // Gates - must be public
+            expect(names).toContain('gates');
+            expect(names).toContain('lumenflow');
+            // Memory - must be public
+            expect(names).toContain('mem:checkpoint');
+            expect(names).toContain('mem:inbox');
+            // Initiatives - must be public
+            expect(names).toContain('initiative:create');
+            expect(names).toContain('initiative:status');
+        });
+        it('should NOT include internal/maintainer commands', () => {
+            const names = getPublicCommandNames();
+            // Guards are internal
+            expect(names).not.toContain('guard-worktree-commit');
+            expect(names).not.toContain('guard-locked');
+            expect(names).not.toContain('guard-main-branch');
+            // Validation internals
+            expect(names).not.toContain('validate-agent-skills');
+            expect(names).not.toContain('validate-agent-sync');
+            expect(names).not.toContain('validate-backlog-sync');
+            expect(names).not.toContain('validate-skills-spec');
+            // Session internals
+            expect(names).not.toContain('session-coordinator');
+            expect(names).not.toContain('rotate-progress');
+            // Trace/debug internals
+            expect(names).not.toContain('trace-gen');
+        });
+    });
+    describe('isPublicCommand', () => {
+        it('should return true for public commands', () => {
+            expect(isPublicCommand('wu:create')).toBe(true);
+            expect(isPublicCommand('wu:claim')).toBe(true);
+            expect(isPublicCommand('gates')).toBe(true);
+            expect(isPublicCommand('lumenflow')).toBe(true);
+        });
+        it('should return false for internal commands', () => {
+            expect(isPublicCommand('guard-worktree-commit')).toBe(false);
+            expect(isPublicCommand('validate-agent-skills')).toBe(false);
+            expect(isPublicCommand('session-coordinator')).toBe(false);
+        });
+    });
+});
+describe('manifest alignment (WU-1432)', () => {
+    describe('commands.ts derives from manifest', () => {
+        it('should have all CLI registry commands in the public manifest (excluding script commands)', () => {
+            const registry = getCommandsRegistry();
+            const publicNames = new Set(getPublicCommandNames());
+            const registryNames = [];
+            for (const category of registry) {
+                for (const cmd of category.commands) {
+                    // Skip script commands - they're not CLI binaries
+                    if (!SCRIPT_COMMANDS.has(cmd.name)) {
+                        registryNames.push(cmd.name);
+                    }
+                }
+            }
+            // Every CLI command in the registry must be a public command
+            for (const name of registryNames) {
+                expect(publicNames.has(name), `Command "${name}" in registry but not in public manifest`).toBe(true);
+            }
+        });
+        it('should have matching descriptions between manifest and registry', () => {
+            const manifest = getPublicManifest();
+            const registry = getCommandsRegistry();
+            // Build a map of registry descriptions
+            const registryDescriptions = new Map();
+            for (const category of registry) {
+                for (const cmd of category.commands) {
+                    registryDescriptions.set(cmd.name, cmd.description);
+                }
+            }
+            // For commands that appear in both, descriptions should match
+            for (const cmd of manifest) {
+                const registryDesc = registryDescriptions.get(cmd.name);
+                if (registryDesc) {
+                    expect(cmd.description, `Description mismatch for "${cmd.name}"`).toBe(registryDesc);
+                }
+            }
+        });
+        it('should have matching categories between manifest and registry', () => {
+            const manifest = getPublicManifest();
+            const registry = getCommandsRegistry();
+            // Build a map of registry categories
+            const registryCategories = new Map();
+            for (const category of registry) {
+                for (const cmd of category.commands) {
+                    registryCategories.set(cmd.name, category.name);
+                }
+            }
+            // For commands that appear in both, categories should match
+            for (const cmd of manifest) {
+                const registryCategory = registryCategories.get(cmd.name);
+                if (registryCategory) {
+                    expect(cmd.category, `Category mismatch for "${cmd.name}"`).toBe(registryCategory);
+                }
+            }
+        });
+    });
+    describe('package.json bin alignment', () => {
+        it('should only include public commands in bin', () => {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const binEntries = Object.keys(packageJson.bin || {});
+            const publicBinNames = new Set(getPublicBinNames());
+            // Every bin entry should be in the public manifest
+            for (const binName of binEntries) {
+                expect(publicBinNames.has(binName), `Bin "${binName}" is in package.json but not in public manifest - should it be internal?`).toBe(true);
+            }
+        });
+        it('should have all public commands in bin', () => {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const binEntries = new Set(Object.keys(packageJson.bin || {}));
+            const publicManifest = getPublicManifest();
+            // Every public manifest command should have a bin entry
+            for (const cmd of publicManifest) {
+                expect(binEntries.has(cmd.binName), `Public command "${cmd.name}" (bin: ${cmd.binName}) missing from package.json bin`).toBe(true);
+            }
+        });
+        it('should have correct file paths in bin', () => {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const publicManifest = getPublicManifest();
+            for (const cmd of publicManifest) {
+                const binPath = packageJson.bin?.[cmd.binName];
+                expect(binPath, `Missing bin path for ${cmd.binName}`).toBeDefined();
+                expect(binPath, `Bin path for ${cmd.binName} should start with ./dist/`).toMatch(/^\.\/dist\//);
+                expect(binPath, `Bin path for ${cmd.binName} should end with .js`).toMatch(/\.js$/);
+            }
+        });
+        it('should not include internal commands in bin', () => {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const binEntries = Object.keys(packageJson.bin || {});
+            // These internal commands should NOT be in bin
+            const internalCommands = [
+                'guard-worktree-commit',
+                'guard-locked',
+                'guard-main-branch',
+                'validate-agent-skills',
+                'validate-agent-sync',
+                'validate-backlog-sync',
+                'validate-skills-spec',
+                'session-coordinator',
+                'rotate-progress',
+                'trace-gen',
+            ];
+            for (const internalCmd of internalCommands) {
+                expect(binEntries.includes(internalCmd), `Internal command "${internalCmd}" should NOT be in package.json bin`).toBe(false);
+            }
+        });
+    });
+});

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-docs-structure.test.js

@@ -67,6 +67,24 @@ describe('docs-structure', () => {
             expect(fs.existsSync(path.join(tempDir, 'docs', 'tasks'))).toBe(true);
             expect(fs.existsSync(path.join(tempDir, 'docs', DOCS_04_OPERATIONS))).toBe(false);
         });
+        it('should scaffold WU template with resilient defaults (simple)', async () => {
+            const options = {
+                force: false,
+                full: true,
+                docsStructure: SIMPLE_DOCS_STRUCTURE,
+            };
+            await scaffoldProject(tempDir, options);
+            const templatePath = path.join(tempDir, 'docs', 'tasks', 'templates', 'wu-template.yaml');
+            expect(fs.existsSync(templatePath)).toBe(true);
+            const content = fs.readFileSync(templatePath, 'utf-8');
+            // Feature WUs should reference plan protocol by default (plan-less friendly).
+            expect(content).toContain('lumenflow://plans/WU-XXX-plan.md');
+            // Ensure non-empty notes to avoid strict spec-linter failures out of the box.
+            expect(content).not.toContain("notes: ''");
+            expect(content).toContain('notes:');
+            // Ensure manual test stub exists to prevent empty tests failures.
+            expect(content).toContain('Manual check:');
+        });
         it('should scaffold arc42 structure with --docs-structure arc42', async () => {
             const options = {
                 force: false,
@@ -77,6 +95,21 @@ describe('docs-structure', () => {
             // Arc42 structure: docs/04-operations/tasks
             expect(fs.existsSync(path.join(tempDir, 'docs', DOCS_04_OPERATIONS, 'tasks'))).toBe(true);
         });
+        it('should scaffold WU template with resilient defaults (arc42)', async () => {
+            const options = {
+                force: false,
+                full: true,
+                docsStructure: ARC42_DOCS_STRUCTURE,
+            };
+            await scaffoldProject(tempDir, options);
+            const templatePath = path.join(tempDir, 'docs', DOCS_04_OPERATIONS, 'tasks', 'templates', 'wu-template.yaml');
+            expect(fs.existsSync(templatePath)).toBe(true);
+            const content = fs.readFileSync(templatePath, 'utf-8');
+            expect(content).toContain('lumenflow://plans/WU-XXX-plan.md');
+            expect(content).not.toContain("notes: ''");
+            expect(content).toContain('notes:');
+            expect(content).toContain('Manual check:');
+        });
         it('should auto-detect arc42 when docs/04-operations exists', async () => {
             // Create existing arc42 structure
             fs.mkdirSync(path.join(tempDir, 'docs', DOCS_04_OPERATIONS), { recursive: true });