@lumenflow/cli 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,11 @@
 # @lumenflow/cli
 
-Command-line interface for LumenFlow workflow management.
+[![npm version](https://img.shields.io/npm/v/@lumenflow/cli.svg)](https://www.npmjs.com/package/@lumenflow/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@lumenflow/cli.svg)](https://www.npmjs.com/package/@lumenflow/cli)
+[![license](https://img.shields.io/npm/l/@lumenflow/cli.svg)](https://github.com/hellmai/os/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@lumenflow/cli.svg)](https://nodejs.org)
+
+> Command-line interface for LumenFlow workflow framework
 
 ## Installation
 
@@ -105,6 +110,23 @@ npx wu-claim --id WU-123 --lane operations
 npx gates
 ```
 
+## Global Flags
+
+All commands support these flags:
+
+| Flag              | Description               |
+| ----------------- | ------------------------- |
+| `--help`, `-h`    | Show help for the command |
+| `--version`, `-V` | Show version number       |
+| `--no-color`      | Disable colored output    |
+
+## Environment Variables
+
+| Variable      | Description                                                                            |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `NO_COLOR`    | Disable colored output when set (any value, per [no-color.org](https://no-color.org/)) |
+| `FORCE_COLOR` | Override color level: `0` (disabled), `1` (basic), `2` (256 colors), `3` (16m colors)  |
+
 ## Integration
 
 The CLI integrates with other LumenFlow packages:
@@ -116,7 +138,7 @@ The CLI integrates with other LumenFlow packages:
 
 ## Documentation
 
-For complete documentation, see the [LumenFlow documentation](https://github.com/hellmai/os).
+For complete documentation, see [lumenflow.dev](https://lumenflow.dev/reference/cli).
 
 ## License
 

package/dist/cli-entry-point.js

@@ -10,6 +10,8 @@
  * path but import.meta.url resolves to the real path - they never match
  * so main() is never called.
  *
+ * WU-1085: Initializes color support respecting NO_COLOR/FORCE_COLOR/--no-color
+ *
  * @example
  * ```typescript
  * // At the bottom of each CLI file:
@@ -21,13 +23,17 @@
  * ```
  */
 import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+import { initColorSupport } from '@lumenflow/core';
 /**
  * Wraps an async main function with proper error handling.
+ * WU-1085: Also initializes color support based on NO_COLOR/FORCE_COLOR/--no-color
  *
  * @param main - The async main function to execute
  * @returns Promise that resolves when main completes (or after error handling)
  */
 export async function runCLI(main) {
+    // WU-1085: Initialize color support before running command
+    initColorSupport();
     try {
         await main();
     }

package/dist/docs-sync.js

@@ -1,9 +1,38 @@
 /**
  * @file docs-sync.ts
  * LumenFlow docs:sync command for syncing agent docs to existing projects (WU-1083)
+ * WU-1085: Added createWUParser for proper --help support
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core';
+/**
+ * WU-1085: CLI option definitions for docs-sync command
+ */
+const DOCS_SYNC_OPTIONS = {
+    vendor: {
+        name: 'vendor',
+        flags: '--vendor <type>',
+        description: 'Vendor type (claude, cursor, aider, all, none)',
+        default: 'claude',
+    },
+    force: WU_OPTIONS.force,
+};
+/**
+ * WU-1085: Parse docs-sync command options using createWUParser
+ * Provides proper --help, --version, and option parsing
+ */
+export function parseDocsSyncOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-docs-sync',
+        description: 'Sync agent onboarding docs to existing projects (skips existing files by default)',
+        options: Object.values(DOCS_SYNC_OPTIONS),
+    });
+    return {
+        force: opts.force ?? false,
+        vendor: opts.vendor ?? 'claude',
+    };
+}
 /**
  * Get current date in YYYY-MM-DD format
  */
@@ -407,32 +436,18 @@ export async function syncSkills(targetDir, options) {
     await createFile(path.join(gatesDir, 'SKILL.md'), processTemplate(LUMENFLOW_GATES_SKILL_TEMPLATE, tokens), options.force, result, targetDir);
     return result;
 }
-/**
- * Parse vendor flag from arguments
- */
-function parseVendorArg(args) {
-    const vendorIndex = args.findIndex((arg) => arg === '--vendor');
-    if (vendorIndex !== -1 && args[vendorIndex + 1]) {
-        const vendor = args[vendorIndex + 1].toLowerCase();
-        if (['claude', 'cursor', 'aider', 'all', 'none'].includes(vendor)) {
-            return vendor;
-        }
-    }
-    return undefined;
-}
 /**
  * CLI entry point for docs:sync command
+ * WU-1085: Updated to use parseDocsSyncOptions for proper --help support
  */
 export async function main() {
-    const args = process.argv.slice(2);
-    const force = args.includes('--force') || args.includes('-f');
-    const vendor = parseVendorArg(args) ?? 'claude'; // Default to claude
+    const opts = parseDocsSyncOptions();
     const targetDir = process.cwd();
     console.log('[lumenflow docs:sync] Syncing agent documentation...');
-    console.log(`  Vendor: ${vendor}`);
-    console.log(`  Force: ${force}`);
-    const docsResult = await syncAgentDocs(targetDir, { force });
-    const skillsResult = await syncSkills(targetDir, { force, vendor });
+    console.log(`  Vendor: ${opts.vendor}`);
+    console.log(`  Force: ${opts.force}`);
+    const docsResult = await syncAgentDocs(targetDir, { force: opts.force });
+    const skillsResult = await syncSkills(targetDir, { force: opts.force, vendor: opts.vendor });
     const created = [...docsResult.created, ...skillsResult.created];
     const skipped = [...docsResult.skipped, ...skillsResult.skipped];
     if (created.length > 0) {

package/dist/gates.js

@@ -54,35 +54,92 @@ import { buildGatesLogPath, shouldUseGatesAgentMode, updateGatesLatestSymlink, }
 import { detectRiskTier, RISK_TIERS, } from '@lumenflow/core/dist/risk-detector.js';
 // WU-2252: Import invariants runner for first-check validation
 import { runInvariants } from '@lumenflow/core/dist/invariants-runner.js';
-import { Command } from 'commander';
+import { createWUParser } from '@lumenflow/core/dist/arg-parser.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
-function parseGatesArgs(argv = process.argv) {
+/**
+ * WU-1087: Gates-specific option definitions for createWUParser.
+ * Exported for testing and consistency with other CLI commands.
+ */
+export const GATES_OPTIONS = {
+    docsOnly: {
+        name: 'docsOnly',
+        flags: '--docs-only',
+        description: 'Run docs-only gates (format, spec-linter, prompts-lint, backlog-sync)',
+    },
+    fullLint: {
+        name: 'fullLint',
+        flags: '--full-lint',
+        description: 'Run full lint instead of incremental',
+    },
+    fullTests: {
+        name: 'fullTests',
+        flags: '--full-tests',
+        description: 'Run full test suite instead of incremental',
+    },
+    fullCoverage: {
+        name: 'fullCoverage',
+        flags: '--full-coverage',
+        description: 'Force full test suite and coverage gate (implies --full-tests)',
+    },
+    coverageMode: {
+        name: 'coverageMode',
+        flags: '--coverage-mode <mode>',
+        description: 'Coverage gate mode: "warn" logs warnings, "block" fails gate',
+        default: 'block',
+    },
+    verbose: {
+        name: 'verbose',
+        flags: '--verbose',
+        description: 'Stream output in agent mode instead of logging to file',
+    },
+};
+/**
+ * WU-1087: Parse gates options using createWUParser for consistency.
+ * Handles pnpm's `--` separator and provides automatic --help support.
+ *
+ * @returns Parsed options object
+ */
+export function parseGatesOptions() {
     // 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 -)
+    // createWUParser's default filtering removes all `--`, but we need smarter handling:
+    // Remove `--` only if it's followed by an option (starts with -)
+    const originalArgv = process.argv;
+    const filteredArgv = originalArgv.filter((arg, index, arr) => {
         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();
+    // Temporarily replace process.argv for createWUParser
+    process.argv = filteredArgv;
+    try {
+        const opts = createWUParser({
+            name: 'gates',
+            description: 'Run quality gates with support for docs-only mode, incremental linting, and tiered testing',
+            options: Object.values(GATES_OPTIONS),
+        });
+        return {
+            docsOnly: opts.docsOnly,
+            fullLint: opts.fullLint,
+            fullTests: opts.fullTests,
+            fullCoverage: opts.fullCoverage,
+            coverageMode: opts.coverageMode ?? 'block',
+            verbose: opts.verbose,
+        };
+    }
+    finally {
+        // Restore original process.argv
+        process.argv = originalArgv;
+    }
+}
+/**
+ * @deprecated Use parseGatesOptions() instead (WU-1087)
+ * Kept for backward compatibility during migration.
+ */
+function parseGatesArgs(argv = process.argv) {
+    return parseGatesOptions();
 }
 /**
  * Build a pnpm command string

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @lumenflow/cli - Command-line interface for LumenFlow workflow framework
+ *
+ * This package provides CLI commands for the LumenFlow workflow framework.
+ * Most functionality is exposed via bin commands, but the cli-entry-point
+ * helper is exported for use in custom CLI wrappers.
+ *
+ * @see https://lumenflow.dev/reference/cli
+ */
+export { runCLI } from './cli-entry-point.js';

package/dist/init.js

@@ -3,13 +3,58 @@
  * LumenFlow project scaffolding command (WU-1045)
  * WU-1006: Library-First - use core defaults for config generation
  * WU-1028: Vendor-agnostic core + vendor overlays
+ * WU-1085: Added createWUParser for proper --help support
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { getDefaultConfig } from '@lumenflow/core';
+import { getDefaultConfig, createWUParser, WU_OPTIONS } from '@lumenflow/core';
 // WU-1067: Import GATE_PRESETS for --preset support
 import { GATE_PRESETS } from '@lumenflow/core/dist/gates-config.js';
+/**
+ * WU-1085: CLI option definitions for init command
+ */
+const INIT_OPTIONS = {
+    full: {
+        name: 'full',
+        flags: '--full',
+        description: 'Add docs + agent onboarding + task scaffolding',
+    },
+    framework: {
+        name: 'framework',
+        flags: '--framework <name>',
+        description: 'Add framework hint + overlay docs',
+    },
+    vendor: {
+        name: 'vendor',
+        flags: '--vendor <type>',
+        description: 'Vendor type (claude, cursor, aider, all, none)',
+    },
+    preset: {
+        name: 'preset',
+        flags: '--preset <preset>',
+        description: 'Gate preset for config (node, python, go, rust, dotnet)',
+    },
+    force: WU_OPTIONS.force,
+};
+/**
+ * WU-1085: Parse init command options using createWUParser
+ * Provides proper --help, --version, and option parsing
+ */
+export function parseInitOptions() {
+    const opts = createWUParser({
+        name: 'lumenflow-init',
+        description: 'Initialize LumenFlow in a project',
+        options: Object.values(INIT_OPTIONS),
+    });
+    return {
+        force: opts.force ?? false,
+        full: opts.full ?? false,
+        framework: opts.framework,
+        vendor: opts.vendor,
+        preset: opts.preset,
+    };
+}
 const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
 const FRAMEWORK_HINT_FILE = '.lumenflow.framework.yaml';
 const LUMENFLOW_DIR = '.lumenflow';
@@ -1100,26 +1145,22 @@ async function createFile(filePath, content, force, result, targetDir) {
 }
 /**
  * CLI entry point
+ * WU-1085: Updated to use parseInitOptions for proper --help support
  */
 export async function main() {
-    const args = process.argv.slice(2);
-    const force = args.includes('--force') || args.includes('-f');
-    const full = args.includes('--full');
-    const vendor = parseVendorArg(args);
-    const framework = parseFrameworkArg(args);
-    const gatePreset = parsePresetArg(args); // WU-1067
+    const opts = parseInitOptions();
     const targetDir = process.cwd();
     console.log('[lumenflow init] Scaffolding LumenFlow project...');
-    console.log(`  Mode: ${full ? 'full' : 'minimal'}`);
-    console.log(`  Framework: ${framework ?? 'none'}`);
-    console.log(`  Vendor overlays: ${vendor ?? 'auto'}`);
-    console.log(`  Gate preset: ${gatePreset ?? 'none (manual config)'}`);
+    console.log(`  Mode: ${opts.full ? 'full' : 'minimal'}`);
+    console.log(`  Framework: ${opts.framework ?? 'none'}`);
+    console.log(`  Vendor overlays: ${opts.vendor ?? 'auto'}`);
+    console.log(`  Gate preset: ${opts.preset ?? 'none (manual config)'}`);
     const result = await scaffoldProject(targetDir, {
-        force,
-        full,
-        vendor,
-        framework,
-        gatePreset,
+        force: opts.force,
+        full: opts.full,
+        vendor: opts.vendor,
+        framework: opts.framework,
+        gatePreset: opts.preset,
     });
     if (result.created.length > 0) {
         console.log('\nCreated:');

package/dist/release.js

@@ -13,9 +13,12 @@
  * - Creates git tag vX.Y.Z
  *
  * Usage:
- *   pnpm release --version 1.3.0
- *   pnpm release --version 1.3.0 --dry-run     # Preview without making changes
- *   pnpm release --version 1.3.0 --skip-publish # Bump and tag only (no npm publish)
+ *   pnpm release --release-version 1.3.0
+ *   pnpm release --release-version 1.3.0 --dry-run     # Preview without making changes
+ *   pnpm release --release-version 1.3.0 --skip-publish # Bump and tag only (no npm publish)
+ *
+ * WU-1085: The --release-version flag was renamed from --version to avoid conflict
+ * with the standard CLI --version flag that shows the CLI version.
  *
  * WU-1074: Add release command for npm publishing
  */
@@ -262,19 +265,22 @@ export async function pushTagWithForce(git, tagName, reason = 'release: tag push
 }
 /**
  * Main release function
+ * WU-1085: Renamed --version to --release-version to avoid conflict with CLI --version flag
  */
 async function main() {
     const program = new Command()
-        .name('release')
+        .name('lumenflow-release')
         .description('Release @lumenflow/* packages to npm with version bump, tag, and publish')
-        .requiredOption('-v, --version <version>', 'Semver version to release (e.g., 1.3.0)')
+        .version('1.0.0', '-V, --version', 'Output the CLI version')
+        .requiredOption('-v, --release-version <version>', 'Semver version to release (e.g., 1.3.0)')
         .option('--dry-run', 'Preview changes without making them', false)
         .option('--skip-publish', 'Skip npm publish (only bump and tag)', false)
         .option('--skip-build', 'Skip build step (use existing dist)', false)
         .helpOption('-h, --help', 'Display help for command');
     program.parse();
     const opts = program.opts();
-    const { version, dryRun, skipPublish, skipBuild } = opts;
+    // WU-1085: Use releaseVersion instead of version (renamed to avoid CLI --version conflict)
+    const { releaseVersion: version, dryRun, skipPublish, skipBuild } = opts;
     console.log(`${LOG_PREFIX} Starting release process for v${version}`);
     if (dryRun) {
         console.log(`${LOG_PREFIX} DRY RUN MODE - no changes will be made`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -21,6 +21,18 @@
     "url": "https://hellm.ai"
   },
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli-entry-point": {
+      "types": "./dist/cli-entry-point.d.ts",
+      "import": "./dist/cli-entry-point.js"
+    }
+  },
   "bin": {
     "wu-claim": "./dist/wu-claim.js",
     "wu-done": "./dist/wu-done.js",
@@ -88,11 +100,11 @@
     "pretty-ms": "^9.2.0",
     "simple-git": "^3.30.0",
     "yaml": "^2.8.2",
-    "@lumenflow/core": "1.4.0",
-    "@lumenflow/metrics": "1.4.0",
-    "@lumenflow/memory": "1.4.0",
-    "@lumenflow/initiatives": "1.4.0",
-    "@lumenflow/agent": "1.4.0"
+    "@lumenflow/core": "1.5.0",
+    "@lumenflow/initiatives": "1.5.0",
+    "@lumenflow/memory": "1.5.0",
+    "@lumenflow/agent": "1.5.0",
+    "@lumenflow/metrics": "1.5.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",