@lumenflow/cli 2.4.0 → 2.5.1

package/dist/__tests__/init-quick-ref.test.js

@@ -0,0 +1,145 @@
+/**
+ * @file init-quick-ref.test.ts
+ * Tests for quick-ref commands content (WU-1309)
+ * Verifies: correct init command, complete wu:create example
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { scaffoldProject } from '../init.js';
+// Constants to avoid duplicate strings (sonarjs/no-duplicate-string)
+const ARC42_DOCS_STRUCTURE = 'arc42';
+describe('quick-ref commands', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-quickref-test-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    function getQuickRefPath(docsStructure = ARC42_DOCS_STRUCTURE) {
+        if (docsStructure === 'simple') {
+            return path.join(tempDir, 'docs', '_frameworks', 'lumenflow', 'agent', 'onboarding', 'quick-ref-commands.md');
+        }
+        return path.join(tempDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding', 'quick-ref-commands.md');
+    }
+    function getArc42Options() {
+        return {
+            force: false,
+            full: true,
+            docsStructure: ARC42_DOCS_STRUCTURE,
+        };
+    }
+    describe('init command documentation', () => {
+        it('should show correct lumenflow init command', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should document the init command correctly
+            expect(content).toContain('lumenflow init');
+            // Should show the various init flags
+            expect(content).toContain('--full');
+        });
+        it('should document --docs-structure flag in quick-ref', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should document the docs-structure option
+            expect(content).toContain('--docs-structure');
+            expect(content).toMatch(/simple|arc42/);
+        });
+    });
+    describe('wu:create example', () => {
+        it('should include a complete wu:create example with all required fields', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should have a complete wu:create example
+            expect(content).toContain('wu:create');
+            expect(content).toContain('--lane');
+            expect(content).toContain('--title');
+            expect(content).toContain('--description');
+            expect(content).toContain('--acceptance');
+            expect(content).toContain('--code-paths');
+            expect(content).toContain('--exposure');
+        });
+        it('should show test-paths in wu:create example', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should include test paths
+            expect(content).toMatch(/--test-paths-(unit|e2e)/);
+        });
+        it('should show spec-refs in wu:create example for feature WUs', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should include spec-refs for feature WUs
+            expect(content).toContain('--spec-refs');
+        });
+    });
+    describe('AGENTS.md quick-ref link', () => {
+        it('should have correct quick-ref link for arc42 structure', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const agentsContent = fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+            // Should point to arc42 path
+            expect(agentsContent).toContain('docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md');
+        });
+        it('should have correct quick-ref link for simple structure', async () => {
+            const options = {
+                force: false,
+                full: true,
+                docsStructure: 'simple',
+            };
+            await scaffoldProject(tempDir, options);
+            const agentsContent = fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+            // Should point to simple path (without 04-operations)
+            expect(agentsContent).toContain('docs/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md');
+            expect(agentsContent).not.toContain('04-operations');
+        });
+    });
+    describe('quick-ref command tables', () => {
+        it('should have project setup commands including init', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should have a project setup section
+            // eslint-disable-next-line sonarjs/slow-regex -- Simple alternation, no backtracking risk
+            expect(content).toMatch(/##.*?Setup|##.*?Project/i);
+            expect(content).toContain('lumenflow init');
+        });
+        it('should have WU management commands', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should have WU commands
+            expect(content).toContain('wu:create');
+            expect(content).toContain('wu:claim');
+            expect(content).toContain('wu:done');
+            expect(content).toContain('wu:block');
+        });
+        it('should have gates commands', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should have gates commands
+            expect(content).toContain('pnpm gates');
+            expect(content).toContain('--docs-only');
+        });
+    });
+    describe('workflow sequence', () => {
+        it('should have a complete workflow sequence example', async () => {
+            await scaffoldProject(tempDir, getArc42Options());
+            const quickRefPath = getQuickRefPath();
+            const content = fs.readFileSync(quickRefPath, 'utf-8');
+            // Should have workflow sequence
+            expect(content).toMatch(/workflow|sequence/i);
+            // Should show the full flow: create -> claim -> work -> commit -> gates -> done
+            expect(content).toContain('wu:create');
+            expect(content).toContain('wu:claim');
+            expect(content).toContain('pnpm gates');
+            expect(content).toContain('wu:done');
+        });
+    });
+});

package/dist/__tests__/init-scripts.test.js

@@ -0,0 +1,207 @@
+/**
+ * @file init-scripts.test.ts
+ * Test: Generated package.json scripts use correct format (wu-create, wu-claim, wu-done, gates)
+ *
+ * WU-1307: Fix lumenflow-init scaffolding
+ *
+ * The init command should inject standalone binary scripts that work
+ * in consumer projects without requiring the full @lumenflow/cli path.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { scaffoldProject } from '../init.js';
+/** Package.json file name - extracted to avoid duplicate string lint errors */
+const PACKAGE_JSON_FILE_NAME = 'package.json';
+describe('init scripts generation (WU-1307)', () => {
+    let tempDir;
+    beforeEach(() => {
+        // Create a temporary directory for each test
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-init-scripts-'));
+    });
+    afterEach(() => {
+        // Clean up temporary directory
+        if (tempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    /** Helper to read and parse package.json from temp directory */
+    function readPackageJson() {
+        const packageJsonPath = path.join(tempDir, PACKAGE_JSON_FILE_NAME);
+        return JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    }
+    it('should generate package.json scripts using standalone binaries', async () => {
+        // Arrange
+        const packageJsonPath = path.join(tempDir, PACKAGE_JSON_FILE_NAME);
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        expect(fs.existsSync(packageJsonPath)).toBe(true);
+        const packageJson = readPackageJson();
+        expect(packageJson.scripts).toBeDefined();
+        // Scripts should use standalone binary format (wu-create, wu-claim, etc.)
+        // NOT 'pnpm exec lumenflow' format
+        expect(packageJson.scripts?.['wu:claim']).toBe('wu-claim');
+        expect(packageJson.scripts?.['wu:done']).toBe('wu-done');
+        expect(packageJson.scripts?.['wu:create']).toBe('wu-create');
+        expect(packageJson.scripts?.gates).toBe('gates');
+    });
+    it('should NOT use pnpm exec lumenflow format', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        const packageJson = readPackageJson();
+        // Ensure scripts do NOT use the old 'pnpm exec lumenflow' format
+        const scriptValues = Object.values(packageJson.scripts ?? {});
+        const hasOldFormat = scriptValues.some((script) => script.includes('pnpm exec lumenflow'));
+        expect(hasOldFormat).toBe(false);
+    });
+    it('should include all essential WU lifecycle scripts', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        const packageJson = readPackageJson();
+        // Essential scripts that must be present
+        const essentialScripts = ['wu:claim', 'wu:done', 'wu:create', 'wu:status', 'gates'];
+        for (const scriptName of essentialScripts) {
+            expect(packageJson.scripts?.[scriptName]).toBeDefined();
+        }
+    });
+    it('should preserve existing scripts when updating package.json', async () => {
+        // Arrange
+        const packageJsonPath = path.join(tempDir, PACKAGE_JSON_FILE_NAME);
+        const existingPackageJson = {
+            name: 'test-project',
+            version: '1.0.0',
+            scripts: {
+                test: 'vitest',
+                build: 'tsc',
+                custom: 'echo hello',
+            },
+        };
+        fs.writeFileSync(packageJsonPath, JSON.stringify(existingPackageJson, null, 2));
+        // Act
+        await scaffoldProject(tempDir, { force: false, full: true });
+        // Assert
+        const packageJson = readPackageJson();
+        // Existing scripts should be preserved
+        expect(packageJson.scripts?.test).toBe('vitest');
+        expect(packageJson.scripts?.build).toBe('tsc');
+        expect(packageJson.scripts?.custom).toBe('echo hello');
+        // LumenFlow scripts should be added
+        expect(packageJson.scripts?.['wu:claim']).toBeDefined();
+        expect(packageJson.scripts?.gates).toBeDefined();
+    });
+    // WU-1342: Test for all 17 essential commands
+    it('should include all 17 essential commands (WU-1342)', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        const packageJson = readPackageJson();
+        // All 17 essential commands that must be present per WU-1342 acceptance criteria
+        const essentialScripts = [
+            // Core WU lifecycle
+            'wu:claim',
+            'wu:done',
+            'wu:create',
+            'wu:status',
+            'wu:block',
+            'wu:unblock',
+            // Additional critical commands (WU-1342)
+            'wu:prep',
+            'wu:recover',
+            'wu:spawn',
+            'wu:validate',
+            'wu:infer-lane',
+            // Memory commands
+            'mem:init',
+            'mem:checkpoint',
+            'mem:inbox',
+            // Lane commands
+            'lane:suggest',
+            // Gates
+            'gates',
+            'gates:docs',
+        ];
+        for (const scriptName of essentialScripts) {
+            expect(packageJson.scripts?.[scriptName], `Missing essential script: ${scriptName}`).toBeDefined();
+        }
+        // Verify count
+        const lumenflowScripts = Object.keys(packageJson.scripts ?? {}).filter((key) => key.startsWith('wu:') ||
+            key.startsWith('mem:') ||
+            key.startsWith('lane:') ||
+            key === 'gates' ||
+            key === 'gates:docs');
+        expect(lumenflowScripts.length).toBeGreaterThanOrEqual(17);
+    });
+});
+describe('init .gitignore generation (WU-1342)', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-init-gitignore-'));
+    });
+    afterEach(() => {
+        if (tempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    it('should create .gitignore with required exclusions (WU-1342)', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: true });
+        // Assert
+        const gitignorePath = path.join(tempDir, '.gitignore');
+        expect(fs.existsSync(gitignorePath)).toBe(true);
+        const content = fs.readFileSync(gitignorePath, 'utf-8');
+        // Must include node_modules
+        expect(content).toContain('node_modules');
+        // Must include .lumenflow/state
+        expect(content).toContain('.lumenflow/state');
+        // Must include worktrees
+        expect(content).toContain('worktrees');
+    });
+    it('should preserve existing .gitignore content in merge mode (WU-1342)', async () => {
+        // Arrange
+        const gitignorePath = path.join(tempDir, '.gitignore');
+        const existingContent = '# Custom ignores\n.env\n*.log\n';
+        fs.writeFileSync(gitignorePath, existingContent);
+        // Act
+        await scaffoldProject(tempDir, { force: false, full: true, merge: true });
+        // Assert
+        const content = fs.readFileSync(gitignorePath, 'utf-8');
+        // Should preserve existing content
+        expect(content).toContain('.env');
+        expect(content).toContain('*.log');
+        // Should add LumenFlow exclusions
+        expect(content).toContain('node_modules');
+        expect(content).toContain('.lumenflow/state');
+        expect(content).toContain('worktrees');
+    });
+});
+describe('init .claude directory creation (WU-1342)', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-init-claude-'));
+    });
+    afterEach(() => {
+        if (tempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    it('should create .claude directory when --client claude specified (WU-1342)', async () => {
+        // Act
+        await scaffoldProject(tempDir, { force: true, full: false, client: 'claude' });
+        // Assert
+        const claudeDir = path.join(tempDir, '.claude');
+        expect(fs.existsSync(claudeDir)).toBe(true);
+        // Should have agents directory
+        const agentsDir = path.join(claudeDir, 'agents');
+        expect(fs.existsSync(agentsDir)).toBe(true);
+        // Should have settings.json
+        const settingsPath = path.join(claudeDir, 'settings.json');
+        expect(fs.existsSync(settingsPath)).toBe(true);
+        // Should have skills directory
+        const skillsDir = path.join(claudeDir, 'skills');
+        expect(fs.existsSync(skillsDir)).toBe(true);
+    });
+});

package/dist/__tests__/init-template-portability.test.js

@@ -0,0 +1,97 @@
+/**
+ * @file init-template-portability.test.ts
+ * Tests for template portability - no absolute paths (WU-1309)
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { scaffoldProject } from '../init.js';
+// Constants to avoid duplicate strings (sonarjs/no-duplicate-string)
+const ARC42_DOCS_STRUCTURE = 'arc42';
+const PROJECT_ROOT_PLACEHOLDER = '<project-root>';
+describe('template portability', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lumenflow-portability-test-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    describe('no absolute paths in templates', () => {
+        it('should use <project-root> placeholder instead of absolute paths', async () => {
+            const options = {
+                force: false,
+                full: true,
+                client: 'claude',
+            };
+            await scaffoldProject(tempDir, options);
+            // Check LUMENFLOW.md for absolute paths
+            const lumenflowContent = fs.readFileSync(path.join(tempDir, 'LUMENFLOW.md'), 'utf-8');
+            expect(lumenflowContent).not.toMatch(/\/home\//);
+            expect(lumenflowContent).not.toMatch(/\/Users\//);
+            expect(lumenflowContent).not.toMatch(/C:\\/);
+            // Should contain <project-root> placeholder for portable references
+            expect(lumenflowContent).toContain(PROJECT_ROOT_PLACEHOLDER);
+        });
+        it('should not contain hardcoded user paths in AGENTS.md', async () => {
+            const options = {
+                force: false,
+                full: true,
+            };
+            await scaffoldProject(tempDir, options);
+            const agentsContent = fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+            expect(agentsContent).not.toMatch(/\/home\/[a-zA-Z0-9_-]+\//);
+            expect(agentsContent).not.toMatch(/\/Users\/[a-zA-Z0-9_-]+\//);
+            expect(agentsContent).not.toMatch(/C:\\Users\\[a-zA-Z0-9_-]+\\/);
+        });
+        it('should not contain hardcoded paths in quick-ref-commands.md', async () => {
+            const options = {
+                force: false,
+                full: true,
+                docsStructure: ARC42_DOCS_STRUCTURE,
+            };
+            await scaffoldProject(tempDir, options);
+            // Find the quick-ref-commands.md based on docs structure (arc42)
+            const quickRefPath = path.join(tempDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding', 'quick-ref-commands.md');
+            if (fs.existsSync(quickRefPath)) {
+                const quickRefContent = fs.readFileSync(quickRefPath, 'utf-8');
+                expect(quickRefContent).not.toMatch(/\/home\/[a-zA-Z0-9_-]+\//);
+                expect(quickRefContent).not.toMatch(/\/Users\/[a-zA-Z0-9_-]+\//);
+                expect(quickRefContent).toContain(PROJECT_ROOT_PLACEHOLDER);
+            }
+        });
+        it('should use relative paths for docs cross-references', async () => {
+            const options = {
+                force: false,
+                full: true,
+                client: 'claude',
+                docsStructure: ARC42_DOCS_STRUCTURE,
+            };
+            await scaffoldProject(tempDir, options);
+            // Starting prompt should have relative paths to other docs
+            const onboardingDir = path.join(tempDir, 'docs', '04-operations', '_frameworks', 'lumenflow', 'agent', 'onboarding');
+            const startingPromptPath = path.join(onboardingDir, 'starting-prompt.md');
+            if (fs.existsSync(startingPromptPath)) {
+                const content = fs.readFileSync(startingPromptPath, 'utf-8');
+                // Should use relative paths like ../../../../../../LUMENFLOW.md
+                // eslint-disable-next-line sonarjs/slow-regex -- Simple path pattern, no backtracking risk
+                expect(content).toMatch(/\[.*?\]\([./]+.*?\.md\)/);
+            }
+        });
+    });
+    describe('PROJECT_ROOT token replacement', () => {
+        it('should replace {{PROJECT_ROOT}} with <project-root> placeholder', async () => {
+            const options = {
+                force: false,
+                full: true,
+            };
+            await scaffoldProject(tempDir, options);
+            const lumenflowContent = fs.readFileSync(path.join(tempDir, 'LUMENFLOW.md'), 'utf-8');
+            // Should not have unreplaced {{PROJECT_ROOT}} tokens
+            expect(lumenflowContent).not.toContain('{{PROJECT_ROOT}}');
+            // Should have the portable placeholder
+            expect(lumenflowContent).toContain('<project-root>');
+        });
+    });
+});

package/dist/__tests__/init.test.js

@@ -268,6 +268,7 @@ describe('lumenflow init', () => {
             const options = {
                 force: false,
                 full: true, // This is now the default when parsed
+                docsStructure: 'arc42', // WU-1309: Explicitly request arc42 for legacy test
             };
             await scaffoldProject(tempDir, options);
             // Should create agent onboarding docs
@@ -311,8 +312,10 @@ describe('lumenflow init', () => {
                 const laneInferencePath = path.join(tempDir, '.lumenflow.lane-inference.yaml');
                 expect(fs.existsSync(laneInferencePath)).toBe(true);
                 const content = fs.readFileSync(laneInferencePath, 'utf-8');
-                // Should have lane definitions
-                expect(content).toContain('lanes:');
+                // WU-1307: Should have hierarchical lane definitions (not flat lanes: array)
+                expect(content).toContain('Framework:');
+                expect(content).toContain('Content:');
+                expect(content).toContain('Operations:');
             });
             it('should scaffold lane-inference with framework-specific lanes when --framework is provided', async () => {
                 const options = {
@@ -330,6 +333,7 @@ describe('lumenflow init', () => {
                 const options = {
                     force: false,
                     full: true,
+                    docsStructure: 'arc42', // WU-1309: Explicitly request arc42 for legacy test
                 };
                 await scaffoldProject(tempDir, options);
                 const onboardingDir = path.join(tempDir, ONBOARDING_DOCS_PATH);
@@ -381,6 +385,7 @@ describe('lumenflow init', () => {
                 const options = {
                     force: false,
                     full: true,
+                    docsStructure: 'arc42', // WU-1309: Explicitly request arc42 for legacy test
                 };
                 await scaffoldProject(tempDir, options);
                 const agentsContent = fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf-8');