@lumenflow/cli 1.1.0 → 1.3.2

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

@@ -0,0 +1,50 @@
+/**
+ * Tests for CLI entry point error handling
+ *
+ * Verifies that runCLI wrapper properly:
+ * - Catches async errors from main()
+ * - Logs error messages to stderr
+ * - Exits with EXIT_CODES.ERROR on failure
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { runCLI } from '../cli-entry-point.js';
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+describe('runCLI', () => {
+    let mockExit;
+    let mockConsoleError;
+    beforeEach(() => {
+        mockExit = vi.spyOn(process, 'exit').mockImplementation(() => undefined);
+        mockConsoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        mockExit.mockRestore();
+        mockConsoleError.mockRestore();
+    });
+    it('should call main() and do nothing on success', async () => {
+        const main = vi.fn().mockResolvedValue(undefined);
+        await runCLI(main);
+        expect(main).toHaveBeenCalledOnce();
+        expect(mockExit).not.toHaveBeenCalled();
+        expect(mockConsoleError).not.toHaveBeenCalled();
+    });
+    it('should catch errors and exit with ERROR code', async () => {
+        const error = new Error('Test error message');
+        const main = vi.fn().mockRejectedValue(error);
+        await runCLI(main);
+        expect(main).toHaveBeenCalledOnce();
+        expect(mockConsoleError).toHaveBeenCalledWith('Test error message');
+        expect(mockExit).toHaveBeenCalledWith(EXIT_CODES.ERROR);
+    });
+    it('should handle errors without message property', async () => {
+        const main = vi.fn().mockRejectedValue('string error');
+        await runCLI(main);
+        expect(mockConsoleError).toHaveBeenCalledWith('string error');
+        expect(mockExit).toHaveBeenCalledWith(EXIT_CODES.ERROR);
+    });
+    it('should handle null/undefined errors', async () => {
+        const main = vi.fn().mockRejectedValue(null);
+        await runCLI(main);
+        expect(mockConsoleError).toHaveBeenCalledWith('Unknown error');
+        expect(mockExit).toHaveBeenCalledWith(EXIT_CODES.ERROR);
+    });
+});

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

@@ -0,0 +1,64 @@
+/**
+ * Integration tests for CLI subprocess execution
+ *
+ * Tests that CLI commands properly:
+ * - Exit with non-zero code on errors
+ * - Output error messages to stderr
+ * - Don't silently fail
+ *
+ * These tests run CLI commands as subprocesses to verify
+ * the entry point error handling works end-to-end.
+ */
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+const CLI_DIR = resolve(__dirname, '../../dist');
+/**
+ * Helper to run a CLI command as subprocess
+ */
+function runCLI(command, args = []) {
+    const result = spawnSync('node', [resolve(CLI_DIR, `${command}.js`), ...args], {
+        encoding: 'utf-8',
+        timeout: 10000,
+    });
+    return {
+        code: result.status ?? -1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+describe('CLI subprocess error handling', () => {
+    describe('wu-claim', () => {
+        it('should exit with non-zero code when required options are missing', () => {
+            const result = runCLI('wu-claim', ['--id', 'WU-TEST']);
+            // Should NOT exit 0 (silent failure)
+            expect(result.code).not.toBe(0);
+            // Should have some error output
+            expect(result.stderr.length + result.stdout.length).toBeGreaterThan(0);
+        });
+        it('should output help when --help is passed', () => {
+            const result = runCLI('wu-claim', ['--help']);
+            // Help should work
+            expect(result.code).toBe(0);
+            expect(result.stdout).toContain('Usage');
+        });
+    });
+    describe('wu-done', () => {
+        it('should exit with non-zero code for non-existent WU', () => {
+            const result = runCLI('wu-done', ['--id', 'WU-NONEXISTENT-99999']);
+            // Should NOT exit 0 (silent failure)
+            expect(result.code).not.toBe(0);
+            // Should have some error output
+            expect(result.stderr.length + result.stdout.length).toBeGreaterThan(0);
+        });
+    });
+    describe('wu-create', () => {
+        it('should exit with non-zero code when validation fails', () => {
+            const result = runCLI('wu-create', ['--id', 'WU-TEST', '--lane', 'Invalid Lane']);
+            // Should NOT exit 0 (silent failure)
+            expect(result.code).not.toBe(0);
+            // Should have some error output
+            expect(result.stderr.length + result.stdout.length).toBeGreaterThan(0);
+        });
+    });
+});

package/dist/cli-entry-point.js

@@ -0,0 +1,46 @@
+/**
+ * Shared CLI entry point wrapper
+ *
+ * Provides consistent error handling for all CLI commands.
+ * Catches async errors, logs them, and exits with proper code.
+ *
+ * @example
+ * ```typescript
+ * // At the bottom of each CLI file:
+ * import { runCLI } from './cli-entry-point.js';
+ * import { fileURLToPath } from 'node:url';
+ *
+ * if (process.argv[1] === fileURLToPath(import.meta.url)) {
+ *   runCLI(main);
+ * }
+ * ```
+ */
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+/**
+ * Wraps an async main function with proper error handling.
+ *
+ * @param main - The async main function to execute
+ * @returns Promise that resolves when main completes (or after error handling)
+ */
+export async function runCLI(main) {
+    try {
+        await main();
+    }
+    catch (err) {
+        const message = getErrorMessage(err);
+        console.error(message);
+        process.exit(EXIT_CODES.ERROR);
+    }
+}
+/**
+ * Extracts error message from unknown error type.
+ */
+function getErrorMessage(err) {
+    if (err === null || err === undefined) {
+        return 'Unknown error';
+    }
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}

package/dist/gates.js

@@ -42,6 +42,7 @@ import { execSync, spawnSync } from 'node:child_process';
 import { closeSync, mkdirSync, openSync, readSync, statSync, writeSync } from 'node:fs';
 import { access } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { emitGateEvent, getCurrentWU, getCurrentLane } from '@lumenflow/core/dist/telemetry.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { getChangedLintableFiles, convertToPackageRelativePaths, } from '@lumenflow/core/dist/incremental-lint.js';
@@ -55,42 +56,35 @@ import { detectRiskTier, RISK_TIERS, } from '@lumenflow/core/dist/risk-detector.
 // WU-2252: Import invariants runner for first-check validation
 import { runInvariants } from '@lumenflow/core/dist/invariants-runner.js';
 import { Command } from 'commander';
-import { BRANCHES, PACKAGES, PKG_MANAGER, PKG_FLAGS, ESLINT_FLAGS, ESLINT_COMMANDS, ESLINT_DEFAULTS, SCRIPTS, CACHE_STRATEGIES, DIRECTORIES, GATE_NAMES, GATE_COMMANDS, TOOL_PATHS, CLI_MODES, EXIT_CODES, FILE_SYSTEM, } from '@lumenflow/core/dist/wu-constants.js';
+import { BRANCHES, PACKAGES, PKG_MANAGER, PKG_FLAGS, ESLINT_FLAGS, ESLINT_COMMANDS, ESLINT_DEFAULTS, SCRIPTS, CACHE_STRATEGIES, DIRECTORIES, GATE_NAMES, GATE_COMMANDS, TOOL_PATHS, CLI_MODES, EXIT_CODES, FILE_SYSTEM, PRETTIER_ARGS, PRETTIER_FLAGS, } from '@lumenflow/core/dist/wu-constants.js';
 // WU-2457: Add Commander.js for --help support
-// WU-2465: Pre-filter argv to handle pnpm's `--` separator
-// When invoked via `pnpm gates -- --docs-only`, pnpm passes ["--", "--docs-only"]
-// Commander treats `--` as "everything after is positional", causing errors.
-// Solution: Remove standalone `--` from argv before parsing.
-const filteredArgv = process.argv.filter((arg, index, arr) => {
-    // Keep `--` only if it's followed by a non-option (actual positional arg)
-    // Remove it if it's followed by an option (starts with -)
-    if (arg === '--') {
-        const nextArg = arr[index + 1];
-        return nextArg && !nextArg.startsWith('-');
-    }
-    return true;
-});
-const program = new Command()
-    .name('gates')
-    .description('Run quality gates with support for docs-only mode, incremental linting, and tiered testing')
-    .option('--docs-only', 'Run docs-only gates (format, spec-linter, prompts-lint, backlog-sync)')
-    .option('--full-lint', 'Run full lint instead of incremental')
-    .option('--full-tests', 'Run full test suite instead of incremental')
-    .option('--full-coverage', 'Force full test suite and coverage gate (implies --full-tests)')
-    .option('--coverage-mode <mode>', 'Coverage gate mode: "warn" logs warnings, "block" fails gate (default)', 'block')
-    .option('--verbose', 'Stream output in agent mode instead of logging to file')
-    .helpOption('-h, --help', 'Display help for command');
-program.parse(filteredArgv);
-const opts = program.opts();
-// Parse command line arguments (now via Commander)
-const isDocsOnly = opts.docsOnly || false;
-const isFullLint = opts.fullLint || false;
-const isFullTests = opts.fullTests || false;
-// WU-2244: Full coverage flag forces full test suite and coverage gate (deterministic)
-const isFullCoverage = opts.fullCoverage || false;
-// WU-1433: Coverage gate mode (warn or block)
-// WU-2334: Default changed from WARN to BLOCK for TDD enforcement
-const coverageMode = opts.coverageMode || COVERAGE_GATE_MODES.BLOCK;
+function parseGatesArgs(argv = process.argv) {
+    // WU-2465: Pre-filter argv to handle pnpm's `--` separator
+    // When invoked via `pnpm gates -- --docs-only`, pnpm passes ["--", "--docs-only"]
+    // Commander treats `--` as "everything after is positional", causing errors.
+    // Solution: Remove standalone `--` from argv before parsing.
+    const filteredArgv = argv.filter((arg, index, arr) => {
+        // Keep `--` only if it's followed by a non-option (actual positional arg)
+        // Remove it if it's followed by an option (starts with -)
+        if (arg === '--') {
+            const nextArg = arr[index + 1];
+            return nextArg && !nextArg.startsWith('-');
+        }
+        return true;
+    });
+    const program = new Command()
+        .name('gates')
+        .description('Run quality gates with support for docs-only mode, incremental linting, and tiered testing')
+        .option('--docs-only', 'Run docs-only gates (format, spec-linter, prompts-lint, backlog-sync)')
+        .option('--full-lint', 'Run full lint instead of incremental')
+        .option('--full-tests', 'Run full test suite instead of incremental')
+        .option('--full-coverage', 'Force full test suite and coverage gate (implies --full-tests)')
+        .option('--coverage-mode <mode>', 'Coverage gate mode: "warn" logs warnings, "block" fails gate (default)', 'block')
+        .option('--verbose', 'Stream output in agent mode instead of logging to file')
+        .helpOption('-h, --help', 'Display help for command');
+    program.parse(filteredArgv);
+    return program.opts();
+}
 /**
  * Build a pnpm command string
  */
@@ -104,6 +98,60 @@ function pnpmRun(script, ...args) {
     const argsStr = args.length > 0 ? ` ${args.join(' ')}` : '';
     return `${PKG_MANAGER} ${SCRIPTS.RUN} ${script}${argsStr}`;
 }
+export function parsePrettierListOutput(output) {
+    if (!output)
+        return [];
+    return output
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.replace(/^\[error\]\s*/i, '').trim())
+        .filter((line) => !line.toLowerCase().includes('code style issues found') &&
+        !line.toLowerCase().includes('all matched files use prettier') &&
+        !line.toLowerCase().includes('checking formatting'));
+}
+export function buildPrettierWriteCommand(files) {
+    const quotedFiles = files.map((file) => `"${file}"`).join(' ');
+    const base = pnpmCmd(SCRIPTS.PRETTIER, PRETTIER_FLAGS.WRITE);
+    return quotedFiles ? `${base} ${quotedFiles}` : base;
+}
+export function formatFormatCheckGuidance(files) {
+    if (!files.length)
+        return [];
+    const command = buildPrettierWriteCommand(files);
+    return [
+        '',
+        '❌ format:check failed',
+        'Fix with:',
+        `  ${command}`,
+        '',
+        'Affected files:',
+        ...files.map((file) => `  - ${file}`),
+        '',
+    ];
+}
+function collectPrettierListDifferent(cwd) {
+    const cmd = pnpmCmd(SCRIPTS.PRETTIER, PRETTIER_ARGS.LIST_DIFFERENT, '.');
+    const result = spawnSync(cmd, [], {
+        shell: true,
+        cwd,
+        encoding: FILE_SYSTEM.ENCODING,
+    });
+    const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+    return parsePrettierListOutput(output);
+}
+function emitFormatCheckGuidance({ agentLog, useAgentMode, }) {
+    const files = collectPrettierListDifferent(process.cwd());
+    if (!files.length)
+        return;
+    const lines = formatFormatCheckGuidance(files);
+    const logLine = useAgentMode && agentLog
+        ? (line) => writeSync(agentLog.logFd, `${line}\n`)
+        : (line) => console.log(line);
+    for (const line of lines) {
+        logLine(line);
+    }
+}
 /**
  * Build a pnpm --filter command string
  */
@@ -480,6 +528,16 @@ const agentLog = useAgentMode ? createAgentLogContext({ wuId: wu_id, lane }) : n
 // Main execution
 // eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing: main() orchestrates multi-step gate workflow
 async function main() {
+    const opts = parseGatesArgs();
+    // Parse command line arguments (now via Commander)
+    const isDocsOnly = opts.docsOnly || false;
+    const isFullLint = opts.fullLint || false;
+    const isFullTests = opts.fullTests || false;
+    // WU-2244: Full coverage flag forces full test suite and coverage gate (deterministic)
+    const isFullCoverage = opts.fullCoverage || false;
+    // WU-1433: Coverage gate mode (warn or block)
+    // WU-2334: Default changed from WARN to BLOCK for TDD enforcement
+    const coverageMode = opts.coverageMode || COVERAGE_GATE_MODES.BLOCK;
     if (useAgentMode) {
         console.log(`🧾 gates (agent mode): output -> ${agentLog.logPath} (use --verbose for streaming)\n`);
     }
@@ -670,6 +728,9 @@ async function main() {
                 }
                 continue;
             }
+            if (gate.name === GATE_NAMES.FORMAT_CHECK) {
+                emitFormatCheckGuidance({ agentLog, useAgentMode });
+            }
             if (useAgentMode) {
                 const tail = readLogTail(agentLog.logPath);
                 console.error(`\n❌ ${gate.name} failed (agent mode). Log: ${agentLog.logPath}\n`);
@@ -692,7 +753,9 @@ async function main() {
     }
     process.exit(EXIT_CODES.SUCCESS);
 }
-main().catch((error) => {
-    console.error('Gates failed:', error);
-    process.exit(EXIT_CODES.ERROR);
-});
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error('Gates failed:', error);
+        process.exit(EXIT_CODES.ERROR);
+    });
+}