@synergenius/flow-weaver 0.15.2 → 0.17.0

package/dist/cli/index.js

@@ -5,7 +5,9 @@
  * Note: Shebang is added by build script (scripts/build-cli.ts) to the CJS bundle.
  * Do not add #!/usr/bin/env node here - it will cause duplicate shebangs.
  */
-import { Command } from 'commander';
+// Must be imported first: sets up env vars before picocolors reads them
+import './env-setup.js';
+import { Command, Option } from 'commander';
 import { compileCommand } from './commands/compile.js';
 import { createWorkflowCommand, createNodeCommand } from './commands/create.js';
 import { describeCommand } from './commands/describe.js';
@@ -45,9 +47,24 @@ const program = new Command();
 program
     .name('flow-weaver')
     .description('Flow Weaver Annotations - Compile and validate workflow files')
-    .version(version, '-v, --version', 'Output the current version');
+    .option('-v, --version', 'Output the current version')
+    .option('--no-color', 'Disable colors')
+    .option('--color', 'Force colors')
+    .on('option:version', () => {
+    logger.banner(version);
+    process.exit(0);
+})
+    .configureHelp({
+    sortSubcommands: false,
+    subcommandTerm: (cmd) => cmd.name() + (cmd.usage() ? ' ' + cmd.usage() : ''),
+});
+// Track whether our action handler already printed the error,
+// so Commander's own error handling doesn't duplicate it.
+let actionErrorHandled = false;
 program.configureOutput({
     writeErr: (str) => {
+        if (actionErrorHandled)
+            return;
         const trimmed = str.replace(/^error:\s*/i, '').trimEnd();
         if (trimmed) {
             logger.error(trimmed);
@@ -55,6 +72,22 @@ program.configureOutput({
     },
     writeOut: (str) => process.stdout.write(str),
 });
+/**
+ * Wraps a command action with centralized error handling.
+ * Catches errors, prints them once, sets the flag to prevent Commander duplication.
+ */
+function wrapAction(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (error) {
+            actionErrorHandled = true;
+            logger.error(getErrorMessage(error));
+            process.exit(1);
+        }
+    };
+}
 // Compile command
 program
     .command('compile <input>')
@@ -64,8 +97,8 @@ program
     .option('-s, --source-map', 'Generate source maps', false)
     .option('--verbose', 'Verbose output', false)
     .option('--dry-run', 'Preview compilation without writing files', false)
-    .option('-w, --workflow-name <name>', 'Specific workflow name to compile')
-    .option('-f, --format <format>', 'Module format: esm, cjs, or auto (default: auto)', 'auto')
+    .option('-w, --workflow <name>', 'Specific workflow name to compile')
+    .addOption(new Option('-f, --format <format>', 'Module format').choices(['esm', 'cjs', 'auto']).default('auto'))
     .option('--strict', 'Treat type coercion warnings as errors', false)
     .option('--inline-runtime', 'Force inline runtime even when @synergenius/flow-weaver package is installed', false)
     .option('--clean', 'Omit redundant @param/@returns annotations from compiled output', false)
@@ -76,15 +109,11 @@ program
     .option('--typed-events', 'Generate Zod event schemas from workflow @param annotations')
     .option('--retries <n>', 'Number of retries per function (Inngest target only)', parseInt)
     .option('--timeout <duration>', 'Function timeout (e.g. "30m", "1h")')
-    .action(async (input, options) => {
-    try {
-        await compileCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, options) => {
+    if (options.workflow)
+        options.workflowName = options.workflow;
+    await compileCommand(input, options);
+}));
 // Strip command
 program
     .command('strip <input>')
@@ -92,73 +121,55 @@ program
     .option('-o, --output <path>', 'Output directory (default: in-place)')
     .option('--dry-run', 'Preview without writing', false)
     .option('--verbose', 'Verbose output', false)
-    .action(async (input, options) => {
-    try {
-        await stripCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, options) => {
+    await stripCommand(input, options);
+}));
 // Describe command
 program
     .command('describe <input>')
     .description('Output workflow structure in LLM-friendly formats (JSON, text, mermaid)')
-    .option('-f, --format <format>', 'Output format: json (default), text, mermaid, paths, ascii, ascii-compact', 'json')
+    .addOption(new Option('-f, --format <format>', 'Output format').choices(['json', 'text', 'mermaid', 'paths', 'ascii', 'ascii-compact']).default('json'))
     .option('-n, --node <id>', 'Focus on a specific node')
     .option('--compile', 'Also update runtime markers in the source file')
-    .option('-w, --workflow-name <name>', 'Specific workflow name to describe')
-    .action(async (input, options) => {
-    try {
-        await describeCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .option('-w, --workflow <name>', 'Specific workflow name to describe')
+    .action(wrapAction(async (input, options) => {
+    if (options.workflow)
+        options.workflowName = options.workflow;
+    await describeCommand(input, options);
+}));
 // Diagram command
 program
     .command('diagram <input>')
     .description('Generate SVG or interactive HTML diagram of a workflow')
-    .option('-t, --theme <theme>', 'Color theme: dark (default), light', 'dark')
-    .option('-w, --width <pixels>', 'SVG width in pixels')
+    .option('-t, --theme <theme>', 'Color theme: dark, light', 'dark')
+    .option('--width <pixels>', 'SVG width in pixels')
     .option('-p, --padding <pixels>', 'Canvas padding in pixels')
     .option('--no-port-labels', 'Hide data type labels on ports')
-    .option('--workflow-name <name>', 'Specific workflow to render')
-    .option('-f, --format <format>', 'Output format: svg (default), html, ascii, ascii-compact, text', 'svg')
+    .option('-w, --workflow <name>', 'Specific workflow to render')
+    .addOption(new Option('-f, --format <format>', 'Output format').choices(['svg', 'html', 'ascii', 'ascii-compact', 'text']).default('svg'))
     .option('-o, --output <file>', 'Write output to file instead of stdout')
-    .action(async (input, options) => {
-    try {
-        if (options.width)
-            options.width = Number(options.width);
-        if (options.padding)
-            options.padding = Number(options.padding);
-        options.showPortLabels = options.portLabels;
-        await diagramCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, options) => {
+    if (options.width)
+        options.width = Number(options.width);
+    if (options.padding)
+        options.padding = Number(options.padding);
+    options.showPortLabels = options.portLabels;
+    if (options.workflow)
+        options.workflowName = options.workflow;
+    await diagramCommand(input, options);
+}));
 // Diff command
 program
     .command('diff <file1> <file2>')
     .description('Compare two workflow files semantically')
-    .option('-f, --format <format>', 'Output format: text (default), json, compact', 'text')
-    .option('-w, --workflow-name <name>', 'Specific workflow name to compare')
+    .addOption(new Option('-f, --format <format>', 'Output format').choices(['text', 'json', 'compact']).default('text'))
+    .option('-w, --workflow <name>', 'Specific workflow name to compare')
     .option('--exit-zero', 'Exit 0 even when differences are found', false)
-    .action(async (file1, file2, options) => {
-    try {
-        await diffCommand(file1, file2, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (file1, file2, options) => {
+    if (options.workflow)
+        options.workflowName = options.workflow;
+    await diffCommand(file1, file2, options);
+}));
 // Validate command
 program
     .command('validate <input>')
@@ -166,54 +177,43 @@ program
     .option('--verbose', 'Verbose output', false)
     .option('-q, --quiet', 'Suppress warnings', false)
     .option('--json', 'Output results as JSON', false)
-    .option('-w, --workflow-name <name>', 'Specific workflow name to validate')
+    .option('-w, --workflow <name>', 'Specific workflow name to validate')
     .option('--strict', 'Treat type coercion warnings as errors', false)
-    .action(async (input, options) => {
-    try {
-        await validateCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, options) => {
+    if (options.workflow)
+        options.workflowName = options.workflow;
+    await validateCommand(input, options);
+}));
 // Doctor command
 program
     .command('doctor')
     .description('Check project environment and configuration for flow-weaver compatibility')
     .option('--json', 'Output results as JSON', false)
-    .action(async (options) => {
-    try {
-        await doctorCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await doctorCommand(options);
+}));
 // Init command
 program
     .command('init [directory]')
     .description('Create a new flow-weaver project')
     .option('-n, --name <name>', 'Project name (defaults to directory name)')
-    .option('-t, --template <template>', 'Workflow template (default: simple)')
+    .option('-t, --template <template>', 'Workflow template (default: sequential)')
     .option('-f, --format <format>', 'Module format: esm or cjs (default: esm)')
     .option('-y, --yes', 'Skip prompts and use defaults', false)
+    .option('--preset <persona>', 'User preset: nocode, vibecoder, lowcode, expert')
+    .option('--use-case <category>', 'Use case: data, ai, api, automation, cicd, minimal')
+    .option('--mcp', 'Auto-configure MCP for AI editors after scaffolding')
+    .option('--no-mcp', 'Skip MCP setup prompt')
+    .option('--no-agent', 'Skip post-init agent launch prompt')
     .option('--install', 'Run npm install after scaffolding')
     .option('--no-install', 'Skip npm install')
     .option('--git', 'Initialize a git repository')
     .option('--no-git', 'Skip git init')
     .option('--force', 'Overwrite existing files', false)
     .option('--json', 'Output results as JSON', false)
-    .action(async (directory, options) => {
-    try {
-        await initCommand(directory, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (directory, options) => {
+    await initCommand(directory, options);
+}));
 // Watch command
 program
     .command('watch <input>')
@@ -222,17 +222,13 @@ program
     .option('-p, --production', 'Generate production code (no debug events)', false)
     .option('-s, --source-map', 'Generate source maps', false)
     .option('--verbose', 'Verbose output', false)
-    .option('-w, --workflow-name <name>', 'Specific workflow name to compile')
-    .option('-f, --format <format>', 'Module format: esm, cjs, or auto (default: auto)', 'auto')
-    .action(async (input, options) => {
-    try {
-        await watchCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .option('-w, --workflow <name>', 'Specific workflow name to compile')
+    .option('-f, --format <format>', 'Module format: esm, cjs, or auto', 'auto')
+    .action(wrapAction(async (input, options) => {
+    if (options.workflow)
+        options.workflowName = options.workflow;
+    await watchCommand(input, options);
+}));
 // Dev command (watch + compile + run)
 program
     .command('dev <input>')
@@ -241,36 +237,24 @@ program
     .option('--params-file <path>', 'Path to JSON file with input parameters')
     .option('-w, --workflow <name>', 'Specific workflow name to run')
     .option('-p, --production', 'Run in production mode (no trace events)', false)
-    .option('-f, --format <format>', 'Module format: esm, cjs, or auto (default: auto)', 'auto')
+    .option('-f, --format <format>', 'Module format: esm, cjs, or auto', 'auto')
     .option('--clean', 'Omit redundant @param/@returns annotations', false)
     .option('--once', 'Run once then exit', false)
     .option('--json', 'Output result as JSON', false)
     .option('--target <target>', 'Compilation target: typescript or inngest (default: typescript)')
     .option('--framework <framework>', 'Framework for serve handler (inngest target only)', 'express')
     .option('--port <port>', 'Port for dev server (inngest target only)', (v) => parseInt(v, 10), 3000)
-    .action(async (input, options) => {
-    try {
-        await devCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, options) => {
+    await devCommand(input, options);
+}));
 // Listen command
 program
     .command('listen')
     .description('Connect to Studio and stream integration events as JSON lines')
     .option('-s, --server <url>', 'Studio URL', DEFAULT_SERVER_URL)
-    .action(async (options) => {
-    try {
-        await listenCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await listenCommand(options);
+}));
 // Tunnel command
 program
     .command('tunnel')
@@ -278,30 +262,18 @@ program
     .requiredOption('-k, --key <apiKey>', 'API key for cloud authentication (fw_xxxx)')
     .option('-c, --cloud <url>', 'Cloud server URL', 'https://flowweaver.dev')
     .option('-d, --dir <path>', 'Project directory', process.cwd())
-    .action(async (options) => {
-    try {
-        await tunnelCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await tunnelCommand(options);
+}));
 // MCP server command
 program
     .command('mcp-server')
     .description('Start MCP server for Claude Code integration')
     .option('-s, --server <url>', 'Studio URL', DEFAULT_SERVER_URL)
     .option('--stdio', 'Run in MCP stdio mode (skip interactive registration)')
-    .action(async (options) => {
-    try {
-        await mcpServerCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await mcpServerCommand(options);
+}));
 // MCP setup command
 program
     .command('mcp-setup')
@@ -309,82 +281,46 @@ program
     .option('--tool <tools...>', 'Specific tools to configure (claude, cursor, vscode, windsurf, codex, openclaw)')
     .option('--all', 'Configure all detected tools without prompting')
     .option('--list', 'List detected tools without configuring')
-    .action(async (options) => {
-    try {
-        await mcpSetupCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await mcpSetupCommand(options);
+}));
 // UI command group (send commands to Studio)
 const uiCmd = program.command('ui').description('Send commands to Studio');
 uiCmd
     .command('focus-node <nodeId>')
     .description('Select and center a node in Studio')
     .option('-s, --server <url>', 'Studio URL', DEFAULT_SERVER_URL)
-    .action(async (nodeId, options) => {
-    try {
-        await uiFocusNode(nodeId, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (nodeId, options) => {
+    await uiFocusNode(nodeId, options);
+}));
 uiCmd
     .command('add-node <nodeTypeName>')
     .description('Add a node at viewport center')
     .option('-s, --server <url>', 'Studio URL', DEFAULT_SERVER_URL)
-    .action(async (nodeTypeName, options) => {
-    try {
-        await uiAddNode(nodeTypeName, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (nodeTypeName, options) => {
+    await uiAddNode(nodeTypeName, options);
+}));
 uiCmd
     .command('open-workflow <filePath>')
     .description('Open a workflow file in Studio')
     .option('-s, --server <url>', 'Studio URL', DEFAULT_SERVER_URL)
-    .action(async (filePath, options) => {
-    try {
-        await uiOpenWorkflow(filePath, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (filePath, options) => {
+    await uiOpenWorkflow(filePath, options);
+}));
 uiCmd
     .command('get-state')
     .description('Return current workflow state from Studio')
     .option('-s, --server <url>', 'Studio URL', DEFAULT_SERVER_URL)
-    .action(async (options) => {
-    try {
-        await uiGetState(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await uiGetState(options);
+}));
 uiCmd
     .command('batch <json>')
     .description('Execute a batch of commands with auto-snapshot rollback')
     .option('-s, --server <url>', 'Studio URL', DEFAULT_SERVER_URL)
-    .action(async (json, options) => {
-    try {
-        await uiBatch(json, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (json, options) => {
+    await uiBatch(json, options);
+}));
 // Create command (with subcommands)
 const createCmd = program.command('create').description('Create workflows or nodes from templates');
 createCmd
@@ -400,91 +336,55 @@ createCmd
     .option('--nodes <names>', 'Comma-separated node function names (e.g., "fetch,parse,store")')
     .option('--input <name>', 'Custom input port name (default: "data")')
     .option('--output <name>', 'Custom output port name (default: "result")')
-    .action(async (template, file, options) => {
-    try {
-        await createWorkflowCommand(template, file, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (template, file, options) => {
+    await createWorkflowCommand(template, file, options);
+}));
 createCmd
     .command('node <name> <file>')
-    .description('Create a node type (uses processor template by default)')
+    .description('Create a node type from a template')
     .option('-l, --line <number>', 'Insert at specific line number', parseInt)
-    .option('-t, --template <template>', 'Node template to use', 'processor')
+    .option('-t, --template <template>', 'Node template to use', 'transformer')
     .option('-p, --preview', 'Preview generated code without writing', false)
     .option('--strategy <strategy>', 'Template strategy (e.g. mock, callback, webhook)')
     .option('--config <json>', 'Additional configuration (JSON)')
-    .action(async (name, file, options) => {
-    try {
-        await createNodeCommand(name, file, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (name, file, options) => {
+    await createNodeCommand(name, file, options);
+}));
 // Templates command
 program
     .command('templates')
     .description('List available templates')
     .option('--json', 'Output as JSON', false)
-    .action(async (options) => {
-    try {
-        await templatesCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await templatesCommand(options);
+}));
 // Grammar command
 program
     .command('grammar')
     .description('Output JSDoc annotation grammar (@input, @output, @connect, @node, @scope) as HTML railroad diagrams or EBNF text')
-    .option('-f, --format <format>', 'Output format: html (default), ebnf', 'html')
+    .addOption(new Option('-f, --format <format>', 'Output format').choices(['html', 'ebnf']))
     .option('-o, --output <path>', 'Write output to file instead of stdout')
-    .action(async (options) => {
-    try {
-        await grammarCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await grammarCommand(options);
+}));
 // Pattern command (with subcommands)
 const patternCmd = program.command('pattern').description('Work with reusable workflow patterns');
 patternCmd
     .command('list <path>')
     .description('List patterns in a file or directory')
     .option('--json', 'Output as JSON', false)
-    .action(async (inputPath, options) => {
-    try {
-        await patternListCommand(inputPath, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (inputPath, options) => {
+    await patternListCommand(inputPath, options);
+}));
 patternCmd
     .command('apply <pattern-file> <target-file>')
     .description('Apply a pattern to a workflow file')
     .option('-p, --preview', 'Preview changes without writing', false)
     .option('--prefix <prefix>', 'Prefix for node instance IDs')
     .option('-n, --name <name>', 'Specific pattern name to apply')
-    .action(async (patternFile, targetFile, options) => {
-    try {
-        await patternApplyCommand(patternFile, targetFile, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (patternFile, targetFile, options) => {
+    await patternApplyCommand(patternFile, targetFile, options);
+}));
 patternCmd
     .command('extract <source-file>')
     .description('Extract a pattern from workflow nodes')
@@ -492,15 +392,9 @@ patternCmd
     .requiredOption('-o, --output <file>', 'Output pattern file')
     .option('-n, --name <name>', 'Pattern name')
     .option('-p, --preview', 'Preview pattern without writing', false)
-    .action(async (sourceFile, options) => {
-    try {
-        await patternExtractCommand(sourceFile, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (sourceFile, options) => {
+    await patternExtractCommand(sourceFile, options);
+}));
 // Run command
 program
     .command('run <input>')
@@ -519,15 +413,9 @@ program
     .option('--checkpoint', 'Enable checkpointing to disk after each node')
     .option('--resume [file]', 'Resume from a checkpoint file (auto-detects latest if no file)')
     .option('-b, --breakpoint <nodeIds...>', 'Set initial breakpoints (repeatable)')
-    .action(async (input, options) => {
-    try {
-        await runCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, options) => {
+    await runCommand(input, options);
+}));
 // Serve command
 program
     .command('serve [directory]')
@@ -539,28 +427,22 @@ program
     .option('--precompile', 'Precompile all workflows on startup', false)
     .option('--cors <origin>', 'CORS origin', '*')
     .option('--swagger', 'Enable Swagger UI at /docs', false)
-    .action(async (directory, options) => {
-    try {
-        await serveCommand(directory, {
-            port: parseInt(options.port, 10),
-            host: options.host,
-            watch: options.watch,
-            production: options.production,
-            precompile: options.precompile,
-            cors: options.cors,
-            swagger: options.swagger,
-        });
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (directory, options) => {
+    await serveCommand(directory, {
+        port: parseInt(options.port, 10),
+        host: options.host,
+        watch: options.watch,
+        production: options.production,
+        precompile: options.precompile,
+        cors: options.cors,
+        swagger: options.swagger,
+    });
+}));
 // Export command
 program
     .command('export <input>')
     .description('Export workflow as serverless function')
-    .requiredOption('-t, --target <target>', 'Target platform (lambda, vercel, cloudflare)')
+    .requiredOption('-t, --target <target>', 'Target platform (install target packs via marketplace)')
     .requiredOption('-o, --output <path>', 'Output directory')
     .option('-w, --workflow <name>', 'Specific workflow name to export')
     .option('-p, --production', 'Production mode', true)
@@ -569,15 +451,9 @@ program
     .option('--workflows <names>', 'Comma-separated list of workflows to export (used with --multi)')
     .option('--docs', 'Include API documentation routes (/docs and /openapi.json)', false)
     .option('--durable-steps', 'Use deep generator with per-node Inngest steps for durability (inngest target only)', false)
-    .action(async (input, options) => {
-    try {
-        await exportCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, options) => {
+    await exportCommand(input, options);
+}));
 // OpenAPI command
 program
     .command('openapi <directory>')
@@ -586,17 +462,11 @@ program
     .option('--title <title>', 'API title', 'Flow Weaver API')
     .option('--version <version>', 'API version', '1.0.0')
     .option('--description <desc>', 'API description')
-    .option('-f, --format <format>', 'Output format: json (default), yaml', 'json')
+    .option('-f, --format <format>', 'Output format: json, yaml', 'json')
     .option('--server <url>', 'Server URL')
-    .action(async (directory, options) => {
-    try {
-        await openapiCommand(directory, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (directory, options) => {
+    await openapiCommand(directory, options);
+}));
 // Plugin command group
 const pluginCmd = program.command('plugin').description('Scaffold and manage external plugins');
 pluginCmd
@@ -606,60 +476,40 @@ pluginCmd
     .option('--no-system', 'Skip generating a system module')
     .option('-p, --preview', 'Preview generated files without writing', false)
     .option('--force', 'Overwrite existing files', false)
-    .action(async (name, options) => {
-    try {
-        await pluginInitCommand(name, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (name, options) => {
+    await pluginInitCommand(name, options);
+}));
 // Migrate command
 program
     .command('migrate <glob>')
     .description('Migrate workflow files to current syntax via parse → regenerate round-trip')
     .option('--dry-run', 'Preview changes without writing files', false)
     .option('--diff', 'Show semantic diff before/after', false)
-    .action(async (glob, options) => {
-    try {
-        await migrateCommand(glob, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (glob, options) => {
+    await migrateCommand(glob, options);
+}));
 // Status command
 program
     .command('status <input>')
     .description('Report implementation progress for stub workflows')
-    .option('-w, --workflow-name <name>', 'Specific workflow name')
+    .option('-w, --workflow <name>', 'Specific workflow name')
     .option('--json', 'Output as JSON', false)
-    .action(async (input, options) => {
-    try {
-        await statusCommand(input, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, options) => {
+    if (options.workflow)
+        options.workflowName = options.workflow;
+    await statusCommand(input, options);
+}));
 // Implement command
 program
     .command('implement <input> <node>')
     .description('Replace a stub node with a real function skeleton')
-    .option('-w, --workflow-name <name>', 'Specific workflow name')
+    .option('-w, --workflow <name>', 'Specific workflow name')
     .option('-p, --preview', 'Preview the generated code without writing', false)
-    .action(async (input, node, options) => {
-    try {
-        await implementCommand(input, node, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (input, node, options) => {
+    if (options.workflow)
+        options.workflowName = options.workflow;
+    await implementCommand(input, node, options);
+}));
 // Changelog command
 program
     .command('changelog')
@@ -667,43 +517,31 @@ program
     .option('--last-tag', 'From last git tag to HEAD', false)
     .option('--since <date>', 'Date-based range (e.g., "2024-01-01")')
     .option('-r, --range <range>', 'Custom git range (e.g., "v0.1.0..HEAD")')
-    .action(async (options) => {
-    try {
-        await changelogCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (options) => {
+    await changelogCommand(options);
+}));
 // Docs command: flow-weaver docs [topic] | flow-weaver docs search <query>
 program
     .command('docs [args...]')
     .description('Browse reference documentation')
     .option('--json', 'Output as JSON', false)
     .option('--compact', 'Return compact LLM-friendly version', false)
-    .action(async (args, options) => {
-    try {
-        if (args.length === 0) {
-            await docsListCommand(options);
-        }
-        else if (args[0] === 'search') {
-            const query = args.slice(1).join(' ');
-            if (!query) {
-                logger.error('Usage: flow-weaver docs search <query>');
-                process.exit(1);
-            }
-            await docsSearchCommand(query, options);
-        }
-        else {
-            await docsReadCommand(args[0], options);
+    .action(wrapAction(async (args, options) => {
+    if (args.length === 0 || args[0] === 'list') {
+        await docsListCommand(options);
+    }
+    else if (args[0] === 'search') {
+        const query = args.slice(1).join(' ');
+        if (!query) {
+            logger.error('Usage: flow-weaver docs search <query>');
+            process.exit(1);
         }
+        await docsSearchCommand(query, options);
     }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
+    else {
+        await docsReadCommand(args[0], options);
     }
-});
+}));
 // Context command: generate LLM context bundles
 program
     .command('context [preset]')
@@ -714,15 +552,9 @@ program
     .option('--no-grammar', 'Omit EBNF grammar section')
     .option('-o, --output <path>', 'Write to file instead of stdout')
     .option('--list', 'List available presets and exit')
-    .action(async (preset, options) => {
-    try {
-        await contextCommand(preset, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (preset, options) => {
+    await contextCommand(preset, options);
+}));
 // Marketplace command group
 const marketCmd = program.command('market').description('Discover, install, and publish marketplace packages');
 marketCmd
@@ -731,158 +563,77 @@ marketCmd
     .option('-d, --description <desc>', 'Package description')
     .option('-a, --author <author>', 'Author name')
     .option('-y, --yes', 'Skip prompts and use defaults', false)
-    .action(async (name, options) => {
-    try {
-        await marketInitCommand(name, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (name, options) => {
+    await marketInitCommand(name, options);
+}));
 marketCmd
     .command('pack [directory]')
     .description('Validate and generate flowweaver.manifest.json')
     .option('--json', 'Output results as JSON', false)
     .option('--verbose', 'Show parse warnings', false)
-    .action(async (directory, options) => {
-    try {
-        await marketPackCommand(directory, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (directory, options) => {
+    await marketPackCommand(directory, options);
+}));
 marketCmd
     .command('publish [directory]')
     .description('Pack and publish to npm')
     .option('--dry-run', 'Preview without publishing', false)
     .option('--tag <tag>', 'npm dist-tag')
-    .action(async (directory, options) => {
-    try {
-        await marketPublishCommand(directory, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (directory, options) => {
+    await marketPublishCommand(directory, options);
+}));
 marketCmd
     .command('install <package>')
     .description('Install a marketplace package')
     .option('--json', 'Output results as JSON', false)
-    .action(async (packageSpec, options) => {
-    try {
-        await marketInstallCommand(packageSpec, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (packageSpec, options) => {
+    await marketInstallCommand(packageSpec, options);
+}));
 marketCmd
     .command('search [query]')
     .description('Search npm for marketplace packages')
     .option('-l, --limit <number>', 'Max results', '20')
     .option('-r, --registry <url>', 'Custom registry search URL (e.g., private npm registry)')
     .option('--json', 'Output as JSON', false)
-    .action(async (query, options) => {
-    try {
-        await marketSearchCommand(query, { ...options, limit: parseInt(options.limit, 10) });
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
+    .action(wrapAction(async (query, options) => {
+    await marketSearchCommand(query, { ...options, limit: parseInt(options.limit, 10) });
+}));
 marketCmd
     .command('list')
     .description('List installed marketplace packages')
     .option('--json', 'Output as JSON', false)
-    .action(async (options) => {
-    try {
-        await marketListCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
-// Help command (default commander behavior)
-program.on('--help', () => {
-    logger.newline();
-    logger.section('Examples');
-    logger.log('  $ flow-weaver compile my-workflow.ts');
-    logger.log("  $ flow-weaver compile '**/*.ts' -o .output");
-    logger.log('  $ flow-weaver compile my-workflow.ts --format cjs');
-    logger.log('  $ flow-weaver describe workflow.ts');
-    logger.log('  $ flow-weaver describe workflow.ts --format mermaid');
-    logger.log('  $ flow-weaver describe workflow.ts --node validator');
-    logger.log('  $ flow-weaver diagram workflow.ts');
-    logger.log('  $ flow-weaver diagram workflow.ts --theme light -o diagram.svg');
-    logger.log('  $ flow-weaver diagram workflow.ts --format html -o diagram.html');
-    logger.log('  $ flow-weaver diff workflow-v1.ts workflow-v2.ts');
-    logger.log('  $ flow-weaver diff workflow-v1.ts workflow-v2.ts --format json');
-    logger.log("  $ flow-weaver validate '**/*.ts'");
-    logger.log("  $ flow-weaver watch 'src/**/*.ts' -o dist");
-    logger.log('  $ flow-weaver create workflow simple my-workflow.ts');
-    logger.log('  $ flow-weaver create workflow ai-agent agent.ts --provider openai --model gpt-4o');
-    logger.log('  $ flow-weaver create node myProcessor my-workflow.ts');
-    logger.log('  $ flow-weaver templates');
-    logger.log('  $ flow-weaver pattern list ./patterns');
-    logger.log('  $ flow-weaver pattern apply pattern.ts workflow.ts');
-    logger.log('  $ flow-weaver pattern extract workflow.ts --nodes a,b -o extracted.ts');
-    logger.log('  $ flow-weaver init my-project');
-    logger.log('  $ flow-weaver init --template ai-agent -y');
-    logger.log('  $ flow-weaver init my-project --format cjs');
-    logger.log('  $ flow-weaver doctor');
-    logger.log('  $ flow-weaver doctor --json');
-    logger.newline();
-    logger.section('Plugin Commands');
-    logger.log('  $ flow-weaver plugin init my-plugin');
-    logger.log('  $ flow-weaver plugin init my-plugin --area sidebar --no-system');
-    logger.log('  $ flow-weaver plugin init my-plugin --preview');
-    logger.newline();
-    logger.section('Deployment Commands');
-    logger.log('  $ flow-weaver run workflow.ts --params \'{"a": 5}\'');
-    logger.log('  $ flow-weaver serve ./workflows --port 8080');
-    logger.log('  $ flow-weaver export workflow.ts --target vercel --output api/');
-    logger.log('  $ flow-weaver export workflows.ts --target lambda --output dist/ --multi');
-    logger.log('  $ flow-weaver export workflows.ts --target lambda --output dist/ --multi --docs');
-    logger.log('  $ flow-weaver export workflow.ts --target inngest --output dist/ --durable-steps');
-    logger.log('  $ flow-weaver compile workflow.ts --target inngest');
-    logger.log('  $ flow-weaver openapi ./workflows --output api-spec.json');
-    logger.newline();
-    logger.section('Marketplace Commands');
-    logger.log('  $ flow-weaver market init openai');
-    logger.log('  $ flow-weaver market pack');
-    logger.log('  $ flow-weaver market publish');
-    logger.log('  $ flow-weaver market publish --dry-run');
-    logger.log('  $ flow-weaver market install flowweaver-pack-openai');
-    logger.log('  $ flow-weaver market search openai');
-    logger.log('  $ flow-weaver market list');
-    logger.newline();
-    logger.section('Documentation');
-    logger.log('  $ flow-weaver docs');
-    logger.log('  $ flow-weaver docs read error-codes');
-    logger.log('  $ flow-weaver docs read scaffold --compact');
-    logger.log('  $ flow-weaver docs search "missing workflow"');
-    logger.log('  $ flow-weaver docs read error-codes --json');
-    logger.newline();
-    logger.section('Migration & Changelog');
-    logger.log("  $ flow-weaver migrate '**/*.ts'");
-    logger.log("  $ flow-weaver migrate '**/*.ts' --dry-run");
-    logger.log("  $ flow-weaver migrate 'src/**/*.ts' --diff");
-    logger.log('  $ flow-weaver changelog --last-tag');
-    logger.log('  $ flow-weaver changelog --range v0.1.0..HEAD');
-    logger.log('  $ flow-weaver changelog --since 2024-01-01');
-    logger.newline();
-});
-// Parse arguments
-program.parse(process.argv);
-// Show help if no command specified
+    .action(wrapAction(async (options) => {
+    await marketListCommand(options);
+}));
+// Concise examples appended to --help
+program.addHelpText('after', `
+Examples:
+
+  $ flow-weaver compile my-workflow.ts
+  $ flow-weaver validate 'src/**/*.ts'
+  $ flow-weaver run workflow.ts --params '{"a": 5}'
+  $ flow-weaver describe workflow.ts --format ascii-compact
+  $ flow-weaver init my-project
+
+  Run flow-weaver <command> --help for detailed usage.
+`);
+// Show concise welcome when no command specified (before parse to avoid Commander error handling)
 if (!process.argv.slice(2).length) {
-    program.outputHelp();
+    logger.banner(version);
+    console.log();
+    console.log('  Usage: flow-weaver <command> [options]');
+    console.log();
+    console.log('  Get started:');
+    console.log('    init [dir]        Create a new project');
+    console.log('    compile <input>   Compile workflow files');
+    console.log('    validate <input>  Validate without compiling');
+    console.log('    run <input>       Execute a workflow');
+    console.log('    doctor            Check project environment');
+    console.log();
+    console.log('  Run ' + logger.highlight('flow-weaver --help') + ' for all commands.');
+    console.log();
+    process.exit(0);
 }
+// Parse arguments
+program.parse(process.argv);
 //# sourceMappingURL=index.js.map