@synergenius/flow-weaver 0.27.5 → 0.29.0

package/dist/api/generate-in-place.js

@@ -46,12 +46,66 @@ export function generateInPlace(sourceCode, ast, options = {}) {
             path.resolve(nodeType.sourceLocation.file) !== path.resolve(ast.sourceFile)) {
             continue;
         }
+        // Skip built-in auto-injected nodes — step 1.2 handles their insertion
+        if (!nodeType.sourceLocation && nodeType.helperText != null) {
+            continue;
+        }
         const nodeTypeResult = replaceNodeTypeJSDoc(result, nodeType);
         if (nodeTypeResult.changed) {
             result = nodeTypeResult.code;
             hasChanges = true;
         }
     }
+    // Step 1.2: Insert built-in node functions that are auto-injected (no source in the file)
+    const usedNodeTypes = new Set(ast.instances.map((i) => i.nodeType));
+    const builtInNodes = ast.nodeTypes.filter((nt) => !nt.sourceLocation && nt.functionText && nt.helperText != null && usedNodeTypes.has(nt.name));
+    if (builtInNodes.length > 0) {
+        // Find insertion point: just before the workflow function's JSDoc
+        const workflowFnPattern = new RegExp(`(/\\*\\*[\\s\\S]*?@flowWeaver\\s+workflow[\\s\\S]*?\\*/)\\s*\\n\\s*(?:export\\s+)?(?:async\\s+)?function\\s+${ast.functionName}\\b`);
+        const match = result.match(workflowFnPattern);
+        if (match && match.index !== undefined) {
+            const insertionLines = [];
+            // Emit shared helpers once (deduplicated)
+            const emittedHelpers = new Set();
+            for (const node of builtInNodes) {
+                const helperText = production ? (node.helperTextProduction ?? null) : (node.helperText ?? null);
+                if (helperText && !emittedHelpers.has(helperText)) {
+                    emittedHelpers.add(helperText);
+                    insertionLines.push(helperText);
+                    insertionLines.push('');
+                }
+            }
+            // Emit each built-in function with its JSDoc
+            for (const node of builtInNodes) {
+                const funcText = (production && node.functionTextProduction != null) ? node.functionTextProduction : node.functionText;
+                if (funcText) {
+                    // Add JSDoc annotation so the function is recognized on re-parse
+                    const portAnnotations = [];
+                    portAnnotations.push('/**');
+                    portAnnotations.push(` * @flowWeaver nodeType`);
+                    for (const [name, port] of Object.entries(node.inputs)) {
+                        if (name === 'execute')
+                            continue;
+                        const optPrefix = port.optional ? '[' : '';
+                        const optSuffix = port.optional ? ']' : '';
+                        portAnnotations.push(` * @input ${optPrefix}${name}${optSuffix} - ${port.label || name}`);
+                    }
+                    for (const [name, port] of Object.entries(node.outputs)) {
+                        if (name === 'onSuccess' || name === 'onFailure')
+                            continue;
+                        portAnnotations.push(` * @output ${name} - ${port.label || name}`);
+                    }
+                    portAnnotations.push(' */');
+                    insertionLines.push(portAnnotations.join('\n'));
+                    insertionLines.push(funcText);
+                    insertionLines.push('');
+                }
+            }
+            const insertionCode = insertionLines.join('\n');
+            result = result.slice(0, match.index) + insertionCode + '\n' + result.slice(match.index);
+            hasChanges = true;
+        }
+    }
     // Step 1.5: Remove orphaned nodeType functions (functions that don't match any AST nodeType)
     // When multi-workflow, consider ALL workflows' node types to avoid deleting types used by siblings
     const cleanupResult = removeOrphanedNodeTypeFunctions(result, ast, allWorkflows);

package/dist/api/generate.js

@@ -126,7 +126,9 @@ export function generateCode(ast, options) {
     // 2. relative file imports (sourceLocation file differs from workflow source)
     // 3. local nodes (same source file)
     const npmPackageNodes = ast.nodeTypes.filter((n) => n.importSource);
-    const localNodes = ast.nodeTypes.filter((n) => !n.importSource && n.sourceLocation?.file === ast.sourceFile);
+    // Only include built-in nodes (no sourceLocation) that are actually used by this workflow
+    const referencedNodeTypes = new Set(ast.instances.map((i) => i.nodeType));
+    const localNodes = ast.nodeTypes.filter((n) => !n.importSource && (n.sourceLocation?.file === ast.sourceFile || (!n.sourceLocation && n.functionText && n.helperText != null && referencedNodeTypes.has(n.name))));
     const importedNodes = ast.nodeTypes.filter((n) => !n.importSource && n.sourceLocation?.file !== ast.sourceFile);
     if (importedNodes.length > 0 || npmPackageNodes.length > 0) {
         // Separate FUNCTION imports (from source) vs IMPORTED_WORKFLOW imports (from generated)
@@ -264,10 +266,26 @@ export function generateCode(ast, options) {
         if (inlineFunctions.length > 0) {
             lines.push('');
             addLine();
+            // Emit shared helper functions once (deduplicated across built-in nodes)
+            // In production mode, use helperTextProduction if set; if undefined, skip helpers entirely
+            // (production built-in nodes don't need mock helpers)
+            const emittedHelpers = new Set();
+            inlineFunctions.forEach((node) => {
+                if (node.importSource)
+                    return;
+                const helperText = production ? (node.helperTextProduction ?? null) : (node.helperText ?? null);
+                if (helperText && !emittedHelpers.has(helperText)) {
+                    emittedHelpers.add(helperText);
+                    lines.push(helperText);
+                    helperText.split('\n').forEach(() => addLine());
+                    lines.push('');
+                    addLine();
+                }
+            });
             inlineFunctions.forEach((node) => {
                 if (node.importSource)
                     return; // Never inline npm package functions
-                const functionText = node.functionText;
+                const functionText = (production && node.functionTextProduction != null) ? node.functionTextProduction : node.functionText;
                 if (functionText) {
                     const functionWithoutDecorators = removeDecorators(functionText);
                     // Add source mapping for the node function

package/dist/api/query.d.ts

@@ -299,7 +299,9 @@ export declare function findPath(ast: TWorkflowAST, fromNodeId: string, toNodeId
  * }
  * ```
  */
-export declare function getTopologicalOrder(ast: TWorkflowAST): string[];
+export declare function getTopologicalOrder(ast: TWorkflowAST, options?: {
+    includeScopedChildren?: boolean;
+}): string[];
 /**
  * Group nodes by execution level (nodes at same level can execute in parallel)
  *

package/dist/api/query.js

@@ -521,7 +521,7 @@ export function findPath(ast, fromNodeId, toNodeId) {
  * }
  * ```
  */
-export function getTopologicalOrder(ast) {
+export function getTopologicalOrder(ast, options) {
     const mainInstances = getMainFlowInstances(ast);
     const mainConnections = getMainFlowConnections(ast);
     const inDegree = new Map();
@@ -565,6 +565,30 @@ export function getTopologicalOrder(ast) {
     if (result.length !== mainInstances.length) {
         throw new Error('Cannot compute topological order: workflow contains cycles');
     }
+    // Optionally append scoped children (for debug: breakpoints need to know about them)
+    if (options?.includeScopedChildren) {
+        const scopedChildren = ast.instances.filter((inst) => isPerPortScopedChild(inst, ast, ast.nodeTypes));
+        // Append scoped children after their parent node in the result
+        const expanded = [];
+        const scopedByParent = new Map();
+        for (const child of scopedChildren) {
+            if (child.parent) {
+                const parentId = child.parent.id;
+                if (!scopedByParent.has(parentId)) {
+                    scopedByParent.set(parentId, []);
+                }
+                scopedByParent.get(parentId).push(child.id);
+            }
+        }
+        for (const nodeId of result) {
+            expanded.push(nodeId);
+            const children = scopedByParent.get(nodeId);
+            if (children) {
+                expanded.push(...children);
+            }
+        }
+        return expanded;
+    }
     return result;
 }
 /**

package/dist/ast/types.d.ts

@@ -259,8 +259,14 @@ export type TNodeTypeAST = {
     y?: number;
     /** Source code location */
     sourceLocation?: TSourceLocation;
-    /** Original function source text */
+    /** Original function source text (main function only) */
     functionText?: string;
+    /** Production-optimized function source text (mock code stripped) */
+    functionTextProduction?: string;
+    /** Shared helper functions (mock helpers, utility functions) emitted once before main functions */
+    helperText?: string;
+    /** Production-optimized helper text */
+    helperTextProduction?: string;
     /** How success/failure branching works */
     branchingStrategy?: TBranchingStrategy;
     /** Field name for value-based branching */

package/dist/built-in-nodes/generated-registry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DO NOT EDIT - generated by scripts/generate-built-in-registry.ts
+ *
+ * Registry of built-in node types for auto-injection into the parser.
+ * Generated from the actual source files in src/built-in-nodes/.
+ */
+import type { TNodeTypeAST } from '../ast/types.js';
+export declare const BUILT_IN_NODE_TYPES: TNodeTypeAST[];
+//# sourceMappingURL=generated-registry.d.ts.map

package/dist/built-in-nodes/generated-registry.js

@@ -0,0 +1,299 @@
+/**
+ * DO NOT EDIT - generated by scripts/generate-built-in-registry.ts
+ *
+ * Registry of built-in node types for auto-injection into the parser.
+ * Generated from the actual source files in src/built-in-nodes/.
+ */
+export const BUILT_IN_NODE_TYPES = [
+    {
+        type: 'NodeType',
+        name: 'delay',
+        functionName: 'delay',
+        isAsync: true,
+        hasSuccessPort: true,
+        hasFailurePort: true,
+        executeWhen: 'CONJUNCTION',
+        variant: 'FUNCTION',
+        inputs: {
+            execute: { dataType: 'STEP', label: 'Execute' },
+            duration: { dataType: 'STRING', label: 'Duration to sleep (e.g. "30s", "5m", "1h", "2d")', tsType: 'string' },
+        },
+        outputs: {
+            onSuccess: { dataType: 'STEP', label: 'On Success', isControlFlow: true },
+            onFailure: { dataType: 'STEP', label: 'On Failure', isControlFlow: true, failure: true },
+            elapsed: { dataType: 'BOOLEAN', label: 'Always true after sleep completes', tsType: 'boolean' },
+        },
+        helperText: `
+function __fw_getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+
+function __fw_lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[\`\${nodeId}:\${key}\`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
+`.trim(),
+        helperTextProduction: undefined,
+        functionText: `
+async function delay(execute, duration) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, elapsed: false };
+    const mocks = __fw_getMockConfig();
+    if (mocks?.fast) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+    else {
+        const ms = __fw_parseDuration(duration);
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    return { onSuccess: true, onFailure: false, elapsed: true };
+}
+function __fw_parseDuration(duration) {
+    const match = duration.match(/^(\\d+)(ms|s|m|h|d)$/);
+    if (!match)
+        return 0;
+    const [, value, unit] = match;
+    const multipliers = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    return parseInt(value) * (multipliers[unit] || 0);
+}
+`.trim(),
+        functionTextProduction: `
+async function delay(execute, duration) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, elapsed: false };
+    const ms = __fw_parseDuration(duration);
+    await new Promise((resolve) => setTimeout(resolve, ms));
+    return { onSuccess: true, onFailure: false, elapsed: true };
+}
+function __fw_parseDuration(duration) {
+    const match = duration.match(/^(\\d+)(ms|s|m|h|d)$/);
+    if (!match)
+        return 0;
+    const [, value, unit] = match;
+    const multipliers = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    return parseInt(value) * (multipliers[unit] || 0);
+}
+`.trim(),
+    },
+    {
+        type: 'NodeType',
+        name: 'waitForEvent',
+        functionName: 'waitForEvent',
+        isAsync: true,
+        hasSuccessPort: true,
+        hasFailurePort: true,
+        executeWhen: 'CONJUNCTION',
+        variant: 'FUNCTION',
+        inputs: {
+            execute: { dataType: 'STEP', label: 'Execute' },
+            eventName: { dataType: 'STRING', label: 'Event name to wait for (e.g. "app/approval.received")', tsType: 'string' },
+            match: { dataType: 'STRING', label: 'Field to match between trigger and waited event (e.g. "data.requestId")', tsType: 'string', optional: true },
+            timeout: { dataType: 'STRING', label: 'Max wait time (e.g. "24h", "7d"). Empty = no timeout', tsType: 'string', optional: true },
+        },
+        outputs: {
+            onSuccess: { dataType: 'STEP', label: 'On Success', isControlFlow: true },
+            onFailure: { dataType: 'STEP', label: 'On Failure', isControlFlow: true, failure: true },
+            eventData: { dataType: 'OBJECT', label: 'The received event\'s data payload', tsType: 'object' },
+        },
+        helperText: `
+function __fw_getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+
+function __fw_lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[\`\${nodeId}:\${key}\`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
+`.trim(),
+        helperTextProduction: undefined,
+        functionText: `
+async function waitForEvent(execute, eventName, match, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, eventData: {} };
+    const mocks = __fw_getMockConfig();
+    if (mocks) {
+        const mockData = __fw_lookupMock(mocks.events, eventName);
+        if (mockData !== undefined) {
+            return { onSuccess: true, onFailure: false, eventData: mockData };
+        }
+        return { onSuccess: false, onFailure: true, eventData: {} };
+    }
+    return { onSuccess: true, onFailure: false, eventData: {} };
+}
+`.trim(),
+        functionTextProduction: `
+async function waitForEvent(execute, eventName, match, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, eventData: {} };
+    return { onSuccess: true, onFailure: false, eventData: {} };
+}
+`.trim(),
+    },
+    {
+        type: 'NodeType',
+        name: 'invokeWorkflow',
+        functionName: 'invokeWorkflow',
+        isAsync: true,
+        hasSuccessPort: true,
+        hasFailurePort: true,
+        executeWhen: 'CONJUNCTION',
+        variant: 'FUNCTION',
+        inputs: {
+            execute: { dataType: 'STEP', label: 'Execute' },
+            functionId: { dataType: 'STRING', label: 'Function ID of the workflow to invoke (e.g. "my-service/sub-workflow")', tsType: 'string' },
+            payload: { dataType: 'OBJECT', label: 'Data to pass as event.data to the invoked function', tsType: 'object' },
+            timeout: { dataType: 'STRING', label: 'Max wait time (e.g. "1h")', tsType: 'string', optional: true },
+        },
+        outputs: {
+            onSuccess: { dataType: 'STEP', label: 'On Success', isControlFlow: true },
+            onFailure: { dataType: 'STEP', label: 'On Failure', isControlFlow: true, failure: true },
+            result: { dataType: 'OBJECT', label: 'Return value from the invoked function', tsType: 'object' },
+        },
+        helperText: `
+function __fw_getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+
+function __fw_lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[\`\${nodeId}:\${key}\`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
+`.trim(),
+        helperTextProduction: undefined,
+        functionText: `
+async function invokeWorkflow(execute, functionId, payload, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, result: {} };
+    const mocks = __fw_getMockConfig();
+    if (mocks) {
+        const mockResult = __fw_lookupMock(mocks.invocations, functionId);
+        if (mockResult !== undefined) {
+            return { onSuccess: true, onFailure: false, result: mockResult };
+        }
+        return { onSuccess: false, onFailure: true, result: {} };
+    }
+    const registry = globalThis.__fw_workflow_registry__;
+    if (registry?.[functionId]) {
+        try {
+            const result = await registry[functionId](true, payload);
+            return { onSuccess: true, onFailure: false, result: result ?? {} };
+        }
+        catch {
+            return { onSuccess: false, onFailure: true, result: {} };
+        }
+    }
+    return { onSuccess: true, onFailure: false, result: {} };
+}
+`.trim(),
+        functionTextProduction: `
+async function invokeWorkflow(execute, functionId, payload, timeout) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, result: {} };
+    const registry = globalThis.__fw_workflow_registry__;
+    if (registry?.[functionId]) {
+        try {
+            const result = await registry[functionId](true, payload);
+            return { onSuccess: true, onFailure: false, result: result ?? {} };
+        }
+        catch {
+            return { onSuccess: false, onFailure: true, result: {} };
+        }
+    }
+    return { onSuccess: true, onFailure: false, result: {} };
+}
+`.trim(),
+    },
+    {
+        type: 'NodeType',
+        name: 'waitForAgent',
+        functionName: 'waitForAgent',
+        isAsync: true,
+        hasSuccessPort: true,
+        hasFailurePort: true,
+        executeWhen: 'CONJUNCTION',
+        variant: 'FUNCTION',
+        inputs: {
+            execute: { dataType: 'STEP', label: 'Execute' },
+            agentId: { dataType: 'STRING', label: 'Agent/task identifier', tsType: 'string' },
+            context: { dataType: 'OBJECT', label: 'Context data to send to the agent', tsType: 'object' },
+            prompt: { dataType: 'STRING', label: 'Message to display when requesting input', tsType: 'string', optional: true },
+        },
+        outputs: {
+            onSuccess: { dataType: 'STEP', label: 'On Success', isControlFlow: true },
+            onFailure: { dataType: 'STEP', label: 'On Failure', isControlFlow: true, failure: true },
+            agentResult: { dataType: 'OBJECT', label: 'Result returned by the agent', tsType: 'object' },
+        },
+        helperText: `
+function __fw_getMockConfig() {
+    return globalThis.__fw_mocks__;
+}
+
+function __fw_lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[\`\${nodeId}:\${key}\`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
+`.trim(),
+        helperTextProduction: undefined,
+        functionText: `
+async function waitForAgent(execute, agentId, context, prompt) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, agentResult: {} };
+    const mocks = __fw_getMockConfig();
+    const mockResult = __fw_lookupMock(mocks?.agents, agentId);
+    if (mockResult !== undefined) {
+        return { onSuccess: true, onFailure: false, agentResult: mockResult };
+    }
+    if (mocks?.agents) {
+        return { onSuccess: false, onFailure: true, agentResult: {} };
+    }
+    const channel = globalThis.__fw_agent_channel__;
+    if (channel) {
+        const result = await channel.request({ agentId, context, prompt });
+        return { onSuccess: true, onFailure: false, agentResult: result };
+    }
+    return { onSuccess: true, onFailure: false, agentResult: {} };
+}
+`.trim(),
+        functionTextProduction: `
+async function waitForAgent(execute, agentId, context, prompt) {
+    if (!execute)
+        return { onSuccess: false, onFailure: false, agentResult: {} };
+    const channel = globalThis.__fw_agent_channel__;
+    if (channel) {
+        const result = await channel.request({ agentId, context, prompt });
+        return { onSuccess: true, onFailure: false, agentResult: result };
+    }
+    return { onSuccess: true, onFailure: false, agentResult: {} };
+}
+`.trim(),
+    },
+];
+//# sourceMappingURL=generated-registry.js.map

package/dist/cli/commands/init-personas.js

@@ -306,9 +306,9 @@ function printNocodeGuidance(_projectName) {
     logger.newline();
     logger.log(`  ${logger.bold('Useful commands')}`);
     logger.newline();
-    logger.log(`    fw run src/*.ts         ${logger.dim('Run your workflow')}`);
-    logger.log(`    fw diagram src/*.ts     ${logger.dim('See a visual diagram')}`);
-    logger.log(`    fw mcp-setup            ${logger.dim('Connect more AI editors')}`);
+    logger.log(`    npx fw run src/*.ts         ${logger.dim('Run your workflow')}`);
+    logger.log(`    npx fw diagram src/*.ts     ${logger.dim('See a visual diagram')}`);
+    logger.log(`    npx fw mcp-setup            ${logger.dim('Connect more AI editors')}`);
 }
 function printVibecoderGuidance() {
     logger.newline();
@@ -326,17 +326,17 @@ function printLowcodeGuidance() {
     logger.newline();
     logger.log(`  ${logger.bold('Explore and customize')}`);
     logger.newline();
-    logger.log(`    fw templates            ${logger.dim('List all 16 workflow templates')}`);
-    logger.log(`    fw describe src/*.ts     ${logger.dim('See the workflow structure')}`);
-    logger.log(`    fw docs annotations     ${logger.dim('Annotation reference')}`);
+    logger.log(`    npx fw templates            ${logger.dim('List all 16 workflow templates')}`);
+    logger.log(`    npx fw describe src/*.ts     ${logger.dim('See the workflow structure')}`);
+    logger.log(`    npx fw docs annotations     ${logger.dim('Annotation reference')}`);
     logger.newline();
     logger.log(`  Your project includes an example in ${logger.highlight('examples/')} to study.`);
     logger.log(`  With MCP connected, AI can help modify nodes and connections.`);
 }
 function printExpertGuidance() {
     logger.newline();
-    logger.log(`    fw mcp-setup            ${logger.dim('Connect AI editors (Claude, Cursor, VS Code)')}`);
-    logger.log(`    fw docs                 ${logger.dim('Browse reference docs')}`);
+    logger.log(`    npx fw mcp-setup            ${logger.dim('Connect AI editors (Claude, Cursor, VS Code)')}`);
+    logger.log(`    npx fw docs                 ${logger.dim('Browse reference docs')}`);
 }
 /** Pad a filename to align descriptions */
 function pad(displayName, width) {

package/dist/cli/commands/init.js

@@ -350,16 +350,19 @@ export function generateProjectFiles(projectName, template, format = 'esm', pers
             '',
             `import { ${workflowName} } from './${workflowJsFile}';`,
             '',
-            'try {',
-            `  const result = ${workflowName}(true, { data: { message: 'hello world' } });`,
-            '  console.log(result);',
-            '} catch (e) {',
+            'async function main() {',
+            `  const result = await ${workflowName}(true, { data: { message: 'hello world' } });`,
+            '  console.log(JSON.stringify(result, null, 2));',
+            '}',
+            '',
+            'main().catch((e) => {',
             "  if (e instanceof Error && e.message.startsWith('Compile with:')) {",
             "    console.error('Workflow not compiled yet. Run: npm run dev');",
             '    process.exit(1);',
             '  }',
-            '  throw e;',
-            '}',
+            '  console.error(e);',
+            '  process.exit(1);',
+            '});',
             '',
         ].join('\n');
     }
@@ -376,16 +379,19 @@ export function generateProjectFiles(projectName, template, format = 'esm', pers
             '',
             `const { ${workflowName} } = require('./${workflowJsFile}');`,
             '',
-            'try {',
-            `  const result = ${workflowName}(true, { data: { message: 'hello world' } });`,
-            '  console.log(result);',
-            '} catch (e) {',
+            'async function main() {',
+            `  const result = await ${workflowName}(true, { data: { message: 'hello world' } });`,
+            '  console.log(JSON.stringify(result, null, 2));',
+            '}',
+            '',
+            'main().catch((e) => {',
             "  if (e instanceof Error && e.message.startsWith('Compile with:')) {",
             "    console.error('Workflow not compiled yet. Run: npm run dev');",
             '    process.exit(1);',
             '  }',
-            '  throw e;',
-            '}',
+            '  console.error(e);',
+            '  process.exit(1);',
+            '});',
             '',
         ].join('\n');
     }

package/dist/cli/commands/run.js

@@ -339,6 +339,12 @@ async function runCommandInner(input, options) {
             logger.newline();
             logger.section('Result');
             logger.log(JSON.stringify(result.result, null, 2));
+            // Hint when the workflow failed and no params were provided
+            const resultObj = result.result;
+            if (resultObj?.onFailure === true && !options.params && !options.paramsFile) {
+                logger.newline();
+                logger.warn('Tip: use --params to provide input. Run `fw describe <file>` to see expected inputs.');
+            }
             // Show trace summary only when --trace is explicitly set (not on --stream, which already printed live)
             if (options.trace && !options.stream && result.trace && result.trace.length > 0) {
                 logger.newline();