@lumenflow/cli 2.8.0 → 2.10.0

package/dist/__tests__/init.test.js

@@ -491,6 +491,172 @@ describe('lumenflow init', () => {
             });
         });
     });
+    // WU-1382: Improved templates for agent clarity
+    describe('WU-1382: improved templates for agent clarity', () => {
+        describe('CLAUDE.md template enhancements', () => {
+            it('should include CLI commands table inline in CLAUDE.md', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const claudeMdPath = path.join(tempDir, 'CLAUDE.md');
+                expect(fs.existsSync(claudeMdPath)).toBe(true);
+                const content = fs.readFileSync(claudeMdPath, 'utf-8');
+                // Should have CLI commands table with common commands
+                expect(content).toContain('| Command');
+                expect(content).toContain('wu:claim');
+                expect(content).toContain('wu:done');
+                expect(content).toContain('wu:status');
+                expect(content).toContain('gates');
+            });
+            it('should include warning about manual YAML editing in CLAUDE.md', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const claudeMdPath = path.join(tempDir, 'CLAUDE.md');
+                const content = fs.readFileSync(claudeMdPath, 'utf-8');
+                // Should warn against manual WU YAML edits
+                expect(content).toMatch(/do\s+not\s+(manually\s+)?edit|never\s+(manually\s+)?edit/i);
+                expect(content).toMatch(/wu.*yaml|yaml.*wu/i);
+            });
+        });
+        describe('config.yaml managed file header', () => {
+            it('should include managed file header in .lumenflow.config.yaml', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                };
+                await scaffoldProject(tempDir, options);
+                const configPath = path.join(tempDir, '.lumenflow.config.yaml');
+                expect(fs.existsSync(configPath)).toBe(true);
+                const content = fs.readFileSync(configPath, 'utf-8');
+                // Should have managed file header
+                expect(content).toMatch(/LUMENFLOW\s+MANAGED\s+FILE/i);
+                expect(content).toMatch(/do\s+not\s+(manually\s+)?edit/i);
+            });
+        });
+        describe('lane-inference.yaml managed file header', () => {
+            it('should include managed file header in .lumenflow.lane-inference.yaml', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                };
+                await scaffoldProject(tempDir, options);
+                const laneInferencePath = path.join(tempDir, '.lumenflow.lane-inference.yaml');
+                expect(fs.existsSync(laneInferencePath)).toBe(true);
+                const content = fs.readFileSync(laneInferencePath, 'utf-8');
+                // Should have managed file header
+                expect(content).toMatch(/LUMENFLOW\s+MANAGED\s+FILE/i);
+                expect(content).toMatch(/do\s+not\s+(manually\s+)?edit/i);
+            });
+        });
+    });
+    // WU-1383: CLI safeguards against manual file editing
+    describe('WU-1383: CLI safeguards for Claude client', () => {
+        const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
+        describe('enforcement hooks enabled by default for --client claude', () => {
+            it('should add enforcement hooks config when --client claude is used', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const configPath = path.join(tempDir, CONFIG_FILE_NAME);
+                expect(fs.existsSync(configPath)).toBe(true);
+                const content = fs.readFileSync(configPath, 'utf-8');
+                // Should have enforcement hooks enabled for claude-code
+                expect(content).toContain('claude-code');
+                expect(content).toContain('enforcement');
+                expect(content).toContain('hooks: true');
+            });
+            it('should set block_outside_worktree to true by default for claude client', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'claude',
+                };
+                await scaffoldProject(tempDir, options);
+                const configPath = path.join(tempDir, CONFIG_FILE_NAME);
+                const content = fs.readFileSync(configPath, 'utf-8');
+                expect(content).toContain('block_outside_worktree: true');
+            });
+            it('should NOT add enforcement hooks for other clients like cursor', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                    client: 'cursor',
+                };
+                await scaffoldProject(tempDir, options);
+                const configPath = path.join(tempDir, CONFIG_FILE_NAME);
+                const content = fs.readFileSync(configPath, 'utf-8');
+                // Should NOT have claude-code enforcement section (check for the nested enforcement block)
+                // Note: The default config has agents.defaultClient: claude-code, but no enforcement section
+                expect(content).not.toContain('block_outside_worktree');
+                expect(content).not.toMatch(/claude-code:\s*\n\s*enforcement/);
+            });
+        });
+        describe('warning when config already exists', () => {
+            it('should add warning to result when config yaml already exists', async () => {
+                // Create existing config file
+                fs.writeFileSync(path.join(tempDir, CONFIG_FILE_NAME), '# Existing config\ndirectories:\n  tasksDir: docs/tasks\n');
+                const options = {
+                    force: false,
+                    full: false,
+                };
+                const result = await scaffoldProject(tempDir, options);
+                // Should have warning about existing config
+                expect(result.warnings).toBeDefined();
+                expect(result.warnings?.some((w) => w.includes('already exists'))).toBe(true);
+                // Warning should suggest CLI commands
+                expect(result.warnings?.some((w) => w.includes('CLI') || w.includes('lumenflow'))).toBe(true);
+            });
+            it('should skip config file when it already exists (not force)', async () => {
+                const existingContent = '# My custom config\n';
+                fs.writeFileSync(path.join(tempDir, CONFIG_FILE_NAME), existingContent);
+                const options = {
+                    force: false,
+                    full: false,
+                };
+                const result = await scaffoldProject(tempDir, options);
+                expect(result.skipped).toContain(CONFIG_FILE_NAME);
+                // Content should not be changed
+                const content = fs.readFileSync(path.join(tempDir, CONFIG_FILE_NAME), 'utf-8');
+                expect(content).toBe(existingContent);
+            });
+        });
+        describe('post-init output shows CLI commands prominently', () => {
+            // Note: These test the ScaffoldResult which contains info for the CLI output
+            // The main() function uses these to print output
+            it('should include CLI usage guidance in warnings when config exists', async () => {
+                fs.writeFileSync(path.join(tempDir, CONFIG_FILE_NAME), '# Existing\n');
+                const options = {
+                    force: false,
+                    full: false,
+                };
+                const result = await scaffoldProject(tempDir, options);
+                // Warning should mention CLI commands for editing config
+                expect(result.warnings?.some((w) => /pnpm|lumenflow|CLI/i.test(w))).toBe(true);
+            });
+        });
+        describe('warning message suggests CLI commands not manual editing', () => {
+            it('should warn users to use CLI commands instead of manual editing', async () => {
+                fs.writeFileSync(path.join(tempDir, CONFIG_FILE_NAME), '# Existing config\n');
+                const options = {
+                    force: false,
+                    full: false,
+                };
+                const result = await scaffoldProject(tempDir, options);
+                // Should have a warning that mentions not to manually edit
+                expect(result.warnings?.some((w) => w.includes('manual') || w.includes('CLI') || w.includes('lumenflow'))).toBe(true);
+            });
+        });
+    });
     // WU-1362: Branch guard tests for init.ts
     describe('WU-1362: branch guard for tracked file writes', () => {
         it('should block scaffold when on main branch and targeting main checkout', async () => {
@@ -518,4 +684,60 @@ describe('lumenflow init', () => {
             expect(result.created.length).toBeGreaterThan(0);
         });
     });
+    // WU-1385: Include wu-sizing-guide.md in lumenflow init onboarding docs
+    describe('WU-1385: wu-sizing-guide.md scaffolding', () => {
+        describe('wu-sizing-guide.md creation with --full', () => {
+            it('should scaffold wu-sizing-guide.md in onboarding docs with --full', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                    docsStructure: 'arc42',
+                };
+                await scaffoldProject(tempDir, options);
+                const onboardingDir = path.join(tempDir, ONBOARDING_DOCS_PATH);
+                const sizingGuidePath = path.join(onboardingDir, 'wu-sizing-guide.md');
+                expect(fs.existsSync(sizingGuidePath)).toBe(true);
+            });
+            it('should include key sizing guide content', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                    docsStructure: 'arc42',
+                };
+                await scaffoldProject(tempDir, options);
+                const onboardingDir = path.join(tempDir, ONBOARDING_DOCS_PATH);
+                const sizingGuidePath = path.join(onboardingDir, 'wu-sizing-guide.md');
+                const content = fs.readFileSync(sizingGuidePath, 'utf-8');
+                // Should have key content from the sizing guide
+                expect(content).toContain('Complexity');
+                expect(content).toContain('Tool Calls');
+                expect(content).toContain('Context');
+            });
+            it('should not scaffold wu-sizing-guide.md with --minimal (full=false)', async () => {
+                const options = {
+                    force: false,
+                    full: false,
+                };
+                await scaffoldProject(tempDir, options);
+                const onboardingDir = path.join(tempDir, ONBOARDING_DOCS_PATH);
+                const sizingGuidePath = path.join(onboardingDir, 'wu-sizing-guide.md');
+                expect(fs.existsSync(sizingGuidePath)).toBe(false);
+            });
+        });
+        describe('starting-prompt.md references sizing guide', () => {
+            it('should reference wu-sizing-guide.md in starting-prompt.md', async () => {
+                const options = {
+                    force: false,
+                    full: true,
+                    docsStructure: 'arc42',
+                };
+                await scaffoldProject(tempDir, options);
+                const onboardingDir = path.join(tempDir, ONBOARDING_DOCS_PATH);
+                const startingPromptPath = path.join(onboardingDir, 'starting-prompt.md');
+                const content = fs.readFileSync(startingPromptPath, 'utf-8');
+                // Should reference the sizing guide
+                expect(content).toContain('wu-sizing-guide.md');
+            });
+        });
+    });
 });

package/dist/commands.js

@@ -0,0 +1,171 @@
+/**
+ * @file commands.ts
+ * LumenFlow CLI commands discovery feature (WU-1378)
+ *
+ * Provides a way to discover all available CLI commands grouped by category.
+ * This helps agents and users find CLI workflows without reading docs.
+ */
+import { createWUParser } from '@lumenflow/core';
+import { runCLI } from './cli-entry-point.js';
+/**
+ * Command categories organized by function
+ * Based on quick-ref-commands.md structure
+ */
+const COMMAND_CATEGORIES = [
+    {
+        name: 'WU Lifecycle',
+        commands: [
+            { name: 'wu:create', description: 'Create new WU spec' },
+            { name: 'wu:claim', description: 'Claim WU and create worktree' },
+            { name: 'wu:prep', description: 'Run gates in worktree, prep for wu:done' },
+            { name: 'wu:done', description: 'Complete WU (merge, stamp, cleanup) from main' },
+            { name: 'wu:edit', description: 'Edit WU spec fields' },
+            { name: 'wu:block', description: 'Block WU with reason' },
+            { name: 'wu:unblock', description: 'Unblock WU' },
+            { name: 'wu:release', description: 'Release orphaned WU (in_progress to ready)' },
+            { name: 'wu:status', description: 'Show WU status, location, valid commands' },
+            { name: 'wu:spawn', description: 'Generate sub-agent spawn prompt' },
+            { name: 'wu:validate', description: 'Validate WU spec' },
+            { name: 'wu:recover', description: 'Analyze and fix WU state inconsistencies' },
+        ],
+    },
+    {
+        name: 'Gates & Quality',
+        commands: [
+            { name: 'gates', description: 'Run all quality gates' },
+            { name: 'format', description: 'Format all files (Prettier)' },
+            { name: 'lint', description: 'Run ESLint' },
+            { name: 'typecheck', description: 'Run TypeScript type checking' },
+            { name: 'test', description: 'Run all tests (Vitest)' },
+            { name: 'lane:health', description: 'Check lane config health' },
+        ],
+    },
+    {
+        name: 'Memory & Sessions',
+        commands: [
+            { name: 'mem:init', description: 'Initialize memory for WU' },
+            { name: 'mem:checkpoint', description: 'Save progress checkpoint' },
+            { name: 'mem:signal', description: 'Broadcast coordination signal' },
+            { name: 'mem:inbox', description: 'Check coordination signals' },
+            { name: 'mem:create', description: 'Create memory node (bug discovery)' },
+            { name: 'mem:context', description: 'Get context for current lane/WU' },
+        ],
+    },
+    {
+        name: 'Initiatives',
+        commands: [
+            { name: 'initiative:create', description: 'Create new initiative' },
+            { name: 'initiative:edit', description: 'Edit initiative fields' },
+            { name: 'initiative:list', description: 'List all initiatives' },
+            { name: 'initiative:status', description: 'Show initiative status' },
+            { name: 'initiative:add-wu', description: 'Add WU to initiative' },
+        ],
+    },
+    {
+        name: 'Orchestration',
+        commands: [
+            { name: 'orchestrate:initiative', description: 'Orchestrate initiative execution' },
+            { name: 'orchestrate:init-status', description: 'Compact initiative progress view' },
+            { name: 'orchestrate:monitor', description: 'Monitor spawn/agent activity' },
+            { name: 'spawn:list', description: 'List active spawned agents' },
+        ],
+    },
+    {
+        name: 'Setup & Development',
+        commands: [
+            { name: 'setup', description: 'Install deps and build CLI (first time)' },
+            { name: 'lumenflow', description: 'Initialize LumenFlow in a project' },
+            { name: 'lumenflow:doctor', description: 'Diagnose LumenFlow configuration' },
+            { name: 'lumenflow:upgrade', description: 'Upgrade LumenFlow packages' },
+            { name: 'docs:sync', description: 'Sync agent docs (for upgrades)' },
+        ],
+    },
+    {
+        name: 'Metrics & Flow',
+        commands: [
+            { name: 'flow:report', description: 'Generate flow metrics report' },
+            { name: 'flow:bottlenecks', description: 'Identify flow bottlenecks' },
+            { name: 'metrics:snapshot', description: 'Capture metrics snapshot' },
+        ],
+    },
+    {
+        name: 'State Management',
+        commands: [
+            { name: 'state:doctor', description: 'Diagnose state store issues' },
+            { name: 'state:cleanup', description: 'Clean up stale state data' },
+            { name: 'state:bootstrap', description: 'Bootstrap state store' },
+        ],
+    },
+];
+/**
+ * Get the complete commands registry
+ * @returns Array of command categories with their commands
+ */
+export function getCommandsRegistry() {
+    return COMMAND_CATEGORIES;
+}
+/**
+ * Format commands output for terminal display
+ * @returns Formatted string with all commands grouped by category
+ */
+export function formatCommandsOutput() {
+    const lines = [];
+    lines.push('LumenFlow CLI Commands');
+    lines.push('======================');
+    lines.push('');
+    for (const category of COMMAND_CATEGORIES) {
+        lines.push(`## ${category.name}`);
+        lines.push('');
+        // Find the longest command name for alignment
+        const maxNameLength = Math.max(...category.commands.map((cmd) => cmd.name.length));
+        for (const cmd of category.commands) {
+            const padding = ' '.repeat(maxNameLength - cmd.name.length + 2);
+            lines.push(`  ${cmd.name}${padding}${cmd.description}`);
+        }
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push('Tip: Run `pnpm <command> --help` for detailed options.');
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * CLI option definitions for commands command
+ */
+const COMMANDS_OPTIONS = {
+    json: {
+        name: 'json',
+        flags: '--json',
+        description: 'Output commands as JSON',
+    },
+};
+/**
+ * Parse commands command options using createWUParser
+ */
+export function parseCommandsOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-commands',
+        description: 'List all available LumenFlow CLI commands',
+        options: Object.values(COMMANDS_OPTIONS),
+    });
+    return {
+        json: opts.json ?? false,
+    };
+}
+/**
+ * Main function for the commands CLI
+ */
+export async function main() {
+    const opts = parseCommandsOptions();
+    if (opts.json) {
+        console.log(JSON.stringify(getCommandsRegistry(), null, 2));
+    }
+    else {
+        console.log(formatCommandsOutput());
+    }
+}
+// CLI entry point
+// WU-1071: Use import.meta.main for proper CLI detection with pnpm symlinks
+if (import.meta.main) {
+    runCLI(main);
+}