@synergenius/flow-weaver 0.28.0 → 0.29.1

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/parse.js

@@ -32,6 +32,7 @@ export async function parseWorkflow(filePath, options) {
         // Parse the file to extract nodes and workflows
         const parsed = parser.parse(filePath);
         warnings.push(...parsed.warnings);
+        errors.push(...parsed.errors);
         // Get available workflow names
         availableWorkflows = parsed.workflows.map((w) => w.functionName);
         // Determine which workflow to use
@@ -82,7 +83,7 @@ export async function parseWorkflow(filePath, options) {
         }
         return {
             ast: workflow,
-            errors: [],
+            errors,
             warnings,
             availableWorkflows,
             allWorkflows: parsed.workflows,

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/chevrotain-parser/node-parser.js

@@ -65,14 +65,13 @@ class NodeParser extends CstParser {
         this.CONSUME(LabelPrefix);
         this.CONSUME(StringLiteral, { LABEL: 'labelValue' });
     });
-    // expr: port="value", port2="value2"
+    // expr: port="value", port2="value2"  (comma optional between assignments)
     exprAttr = this.RULE('exprAttr', () => {
         this.CONSUME(ExprPrefix);
-        this.AT_LEAST_ONE_SEP({
-            SEP: Comma,
-            DEF: () => {
-                this.SUBRULE(this.exprAssignment);
-            },
+        this.SUBRULE(this.exprAssignment);
+        this.MANY(() => {
+            this.OPTION(() => this.CONSUME(Comma));
+            this.SUBRULE2(this.exprAssignment);
         });
     });
     // port="value"
@@ -524,6 +523,10 @@ const visitorInstance = new NodeVisitor();
 export function parseNodeLine(input, warnings) {
     const lexResult = JSDocLexer.tokenize(input);
     if (lexResult.errors.length > 0) {
+        const truncatedInput = input.length > 60 ? input.substring(0, 60) + '...' : input;
+        warnings.push(`Failed to tokenize node line: "${truncatedInput}"\n` +
+            `  Error: ${lexResult.errors[0].message}\n` +
+            `  Expected format: @node instanceId NodeType`);
         return null;
     }
     // Check if starts with @node

package/dist/cli/flow-weaver.mjs

@@ -5987,7 +5987,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.28.0";
+    VERSION = "0.29.1";
   }
 });
 
@@ -6651,7 +6651,7 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
       lines.push(`    // Execute: ${child.id} (${child.nodeType})`);
       if (emitDebugHooks) {
         const awaitHook = isAsync2 ? "await " : "";
-        lines.push(`    let ${safeChildId}Idx: number;`);
+        lines.push(`    let ${safeChildId}Idx: number = -1;`);
         lines.push(`    if (${awaitHook}__ctrl__.beforeNode('${child.id}', scopedCtx)) {`);
         childIndent = "      ";
       }
@@ -14039,8 +14039,9 @@ function generateCode(ast, options) {
     }
   }
   const npmPackageNodes = ast.nodeTypes.filter((n7) => n7.importSource);
+  const referencedNodeTypes = new Set(ast.instances.map((i) => i.nodeType));
   const localNodes = ast.nodeTypes.filter(
-    (n7) => !n7.importSource && n7.sourceLocation?.file === ast.sourceFile
+    (n7) => !n7.importSource && (n7.sourceLocation?.file === ast.sourceFile || !n7.sourceLocation && n7.functionText && n7.helperText != null && referencedNodeTypes.has(n7.name))
   );
   const importedNodes = ast.nodeTypes.filter(
     (n7) => !n7.importSource && n7.sourceLocation?.file !== ast.sourceFile
@@ -14151,9 +14152,21 @@ function generateCode(ast, options) {
     if (inlineFunctions.length > 0) {
       lines.push("");
       addLine();
+      const emittedHelpers = /* @__PURE__ */ new Set();
       inlineFunctions.forEach((node) => {
         if (node.importSource) return;
-        const functionText = node.functionText;
+        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;
+        const functionText = production && node.functionTextProduction != null ? node.functionTextProduction : node.functionText;
         if (functionText) {
           const functionWithoutDecorators = removeDecorators(functionText);
           if (node.sourceLocation) {
@@ -15275,12 +15288,62 @@ function generateInPlace(sourceCode, ast, options = {}) {
     if (nodeType.sourceLocation?.file && path2.resolve(nodeType.sourceLocation.file) !== path2.resolve(ast.sourceFile)) {
       continue;
     }
+    if (!nodeType.sourceLocation && nodeType.helperText != null) {
+      continue;
+    }
     const nodeTypeResult = replaceNodeTypeJSDoc(result, nodeType);
     if (nodeTypeResult.changed) {
       result = nodeTypeResult.code;
       hasChanges = true;
     }
   }
+  const usedNodeTypes = new Set(ast.instances.map((i) => i.nodeType));
+  const builtInNodes = ast.nodeTypes.filter(
+    (nt2) => !nt2.sourceLocation && nt2.functionText && nt2.helperText != null && usedNodeTypes.has(nt2.name)
+  );
+  if (builtInNodes.length > 0) {
+    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 !== void 0) {
+      const insertionLines = [];
+      const emittedHelpers = /* @__PURE__ */ 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("");
+        }
+      }
+      for (const node of builtInNodes) {
+        const funcText = production && node.functionTextProduction != null ? node.functionTextProduction : node.functionText;
+        if (funcText) {
+          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;
+    }
+  }
   const cleanupResult = removeOrphanedNodeTypeFunctions(result, ast, allWorkflows);
   if (cleanupResult.changed) {
     result = cleanupResult.code;
@@ -24302,6 +24365,12 @@ var init_port_parser = __esm({
 function parseNodeLine(input, warnings) {
   const lexResult = JSDocLexer.tokenize(input);
   if (lexResult.errors.length > 0) {
+    const truncatedInput = input.length > 60 ? input.substring(0, 60) + "..." : input;
+    warnings.push(
+      `Failed to tokenize node line: "${truncatedInput}"
+  Error: ${lexResult.errors[0].message}
+  Expected format: @node instanceId NodeType`
+    );
     return null;
   }
   if (lexResult.tokens.length === 0) {
@@ -24389,14 +24458,13 @@ var init_node_parser = __esm({
         this.CONSUME(LabelPrefix);
         this.CONSUME(StringLiteral, { LABEL: "labelValue" });
       });
-      // expr: port="value", port2="value2"
+      // expr: port="value", port2="value2"  (comma optional between assignments)
       exprAttr = this.RULE("exprAttr", () => {
         this.CONSUME(ExprPrefix);
-        this.AT_LEAST_ONE_SEP({
-          SEP: Comma,
-          DEF: () => {
-            this.SUBRULE(this.exprAssignment);
-          }
+        this.SUBRULE(this.exprAssignment);
+        this.MANY(() => {
+          this.OPTION(() => this.CONSUME(Comma));
+          this.SUBRULE2(this.exprAssignment);
         });
       });
       // port="value"
@@ -27260,6 +27328,306 @@ var init_coercion_types = __esm({
   }
 });
 
+// src/built-in-nodes/generated-registry.ts
+var BUILT_IN_NODE_TYPES;
+var init_generated_registry = __esm({
+  "src/built-in-nodes/generated-registry.ts"() {
+    "use strict";
+    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: void 0,
+        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: void 0,
+        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: void 0,
+        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: void 0,
+        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()
+      }
+    ];
+  }
+});
+
 // src/parser/tag-registry.ts
 var TagHandlerRegistry, tagHandlerRegistry;
 var init_tag_registry = __esm({
@@ -27588,6 +27956,7 @@ var init_parser2 = __esm({
     init_shared_project();
     init_lru_cache();
     init_coercion_types();
+    init_generated_registry();
     init_tag_registry();
     AnnotationParser = class {
       project;
@@ -27731,7 +28100,7 @@ var init_parser2 = __esm({
             }
           }
         }
-        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes);
+        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes, localNodeTypes, warnings);
         nodeTypes.push(...inferredNodeTypes);
         const workflows = this.extractWorkflows(sourceFile, nodeTypes, filePath, errors2, warnings);
         const patterns = this.extractPatterns(sourceFile, nodeTypes, filePath, errors2, warnings);
@@ -27771,7 +28140,7 @@ var init_parser2 = __esm({
         const workflowSignatures = this.extractWorkflowSignatures(sourceFile, virtualPath, warnings);
         const sameFileWorkflowNodeTypes = workflowSignatures.map((wf) => this.workflowToNodeType(wf));
         const nodeTypes = [...localNodeTypes, ...sameFileWorkflowNodeTypes];
-        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes);
+        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes, localNodeTypes, warnings);
         nodeTypes.push(...inferredNodeTypes);
         const workflows = this.extractWorkflows(sourceFile, nodeTypes, virtualPath, errors2, warnings);
         const patterns = this.extractPatterns(sourceFile, nodeTypes, virtualPath, errors2, warnings);
@@ -28003,7 +28372,7 @@ var init_parser2 = __esm({
         if (imp.importSource.startsWith(".")) {
           return this.resolveLocalImportAnnotation(imp, currentDir, warnings);
         } else {
-          return this.resolveNpmImportAnnotation(imp, currentDir);
+          return this.resolveNpmImportAnnotation(imp, currentDir, warnings);
         }
       }
       /**
@@ -28048,7 +28417,7 @@ var init_parser2 = __esm({
       /**
        * Resolve an npm package @fwImport to a node type by reading .d.ts declarations.
        */
-      resolveNpmImportAnnotation(imp, currentDir) {
+      resolveNpmImportAnnotation(imp, currentDir, warnings) {
         const cacheKey = `npm:${imp.importSource}`;
         if (this.importCache.has(cacheKey)) {
           const cached2 = this.importCache.get(cacheKey);
@@ -28072,6 +28441,9 @@ var init_parser2 = __esm({
         }
         const dtsPath = resolvePackageTypesPath(imp.importSource, currentDir);
         if (!dtsPath) {
+          warnings.push(
+            `@fwImport: Package "${imp.importSource}" has no type declarations (.d.ts). Install @types/${imp.importSource} or add a local wrapper with @flowWeaver nodeType annotations.`
+          );
           return this.createImportStub(imp);
         }
         try {
@@ -28101,7 +28473,13 @@ var init_parser2 = __esm({
           if (found) {
             return { ...found, name: imp.name, importSource: imp.importSource };
           }
-        } catch {
+          warnings.push(
+            `@fwImport: Function "${imp.functionName}" not found in type declarations for "${imp.importSource}". Available exports: ${allNodeTypes.map((nt2) => nt2.functionName).join(", ") || "(none)"}.`
+          );
+        } catch (err) {
+          warnings.push(
+            `@fwImport: Failed to parse type declarations for "${imp.importSource}": ${err.message}. Node "${imp.name}" will use a generic stub.`
+          );
         }
         return this.createImportStub(imp);
       }
@@ -28400,6 +28778,18 @@ ${fn.getText()}` : fn.getText();
           const importedNpmNodeTypes = (config2.imports || []).map(
             (imp) => this.resolveImportAnnotation(imp, filePath, warnings)
           );
+          for (const nt2 of importedNpmNodeTypes) {
+            const dataInputs = Object.keys(nt2.inputs).filter((p) => p !== "execute");
+            const nonControlOutputs = Object.keys(nt2.outputs).filter(
+              (p) => p !== "onSuccess" && p !== "onFailure"
+            );
+            const isStubOnly = nonControlOutputs.length === 1 && nonControlOutputs[0] === "result" && nt2.outputs.result?.dataType === "ANY";
+            if (dataInputs.length === 0 && isStubOnly) {
+              warnings.push(
+                `Could not infer ports for "${nt2.functionName}" from "${nt2.importSource}". Wrap it in a local function with @flowWeaver nodeType annotations instead.`
+              );
+            }
+          }
           const allAvailableNodeTypes = [...availableNodeTypes, ...importedNpmNodeTypes];
           const instances = (config2.instances || []).map((inst) => {
             const nodeTypeExists = allAvailableNodeTypes.some(
@@ -28750,7 +29140,7 @@ ${fn.getText()}` : fn.getText();
        * nodeType annotation, we infer an expression node type from its TypeScript
        * signature. Phase 1: same-file functions only.
        */
-      inferNodeTypesFromUnannotated(sourceFile, existingNodeTypes) {
+      inferNodeTypesFromUnannotated(sourceFile, existingNodeTypes, localNodeTypes, warnings) {
         const allFunctions = extractFunctionLikes(sourceFile);
         const referencedTypes = /* @__PURE__ */ new Set();
         for (const fn of allFunctions) {
@@ -28774,8 +29164,24 @@ ${fn.getText()}` : fn.getText();
         if (unresolvedTypes.size === 0) return [];
         const inferredNodeTypes = [];
         const alreadyInferred = /* @__PURE__ */ new Set();
+        const builtInByName = new Map(BUILT_IN_NODE_TYPES.map((nt2) => [nt2.name, nt2]));
+        const annotatedNames = new Set(localNodeTypes.map((nt2) => nt2.functionName));
         for (const unresolvedType of unresolvedTypes) {
           if (alreadyInferred.has(unresolvedType)) continue;
+          const builtIn = builtInByName.get(unresolvedType);
+          if (builtIn) {
+            inferredNodeTypes.push(builtIn);
+            alreadyInferred.add(unresolvedType);
+            if (!annotatedNames.has(unresolvedType)) {
+              const shadowFn = allFunctions.find((fn) => fn.getName() === unresolvedType && !this.hasFlowWeaverAnnotation(fn));
+              if (shadowFn) {
+                warnings.push(
+                  `Function '${unresolvedType}' exists in this file but is not annotated with @flowWeaver nodeType. The built-in '${unresolvedType}' will be used instead. Add @flowWeaver nodeType to use your version.`
+                );
+              }
+            }
+            continue;
+          }
           const matchedFn = allFunctions.find((fn) => {
             if (fn.getName() !== unresolvedType) return false;
             return !this.hasFlowWeaverAnnotation(fn);
@@ -29674,6 +30080,7 @@ async function parseWorkflow(filePath, options) {
     }
     const parsed = parser.parse(filePath);
     warnings.push(...parsed.warnings);
+    errors2.push(...parsed.errors);
     availableWorkflows = parsed.workflows.map((w) => w.functionName);
     let workflowName = options?.workflowName;
     if (!workflowName) {
@@ -29723,7 +30130,7 @@ async function parseWorkflow(filePath, options) {
     }
     return {
       ast: workflow,
-      errors: [],
+      errors: errors2,
       warnings,
       availableWorkflows,
       allWorkflows: parsed.workflows
@@ -88526,7 +88933,7 @@ function parseIntStrict(value) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.28.0" : "0.0.0-dev";
+var version2 = true ? "0.29.1" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("fw").description("Flow Weaver Annotations - Compile and validate workflow files").option("-v, --version", "Output the current version").option("--no-color", "Disable colors").option("--color", "Force colors").on("option:version", () => {
   logger.banner(version2);

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.28.0";
+export declare const VERSION = "0.29.1";
 //# sourceMappingURL=generated-version.d.ts.map

package/dist/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.ts — do not edit manually
-export const VERSION = '0.28.0';
+export const VERSION = '0.29.1';
 //# sourceMappingURL=generated-version.js.map

package/dist/generator/scope-function-generator.js

@@ -196,8 +196,9 @@ export function generateScopeFunctionClosure(scopeName, parentNodeId, parentNode
             // When enabled, wraps the child execution so breakpoints can pause on scoped nodes.
             if (emitDebugHooks) {
                 const awaitHook = isAsync ? 'await ' : '';
-                // Hoist Idx declaration before the if block so it stays in scope after
-                lines.push(`    let ${safeChildId}Idx: number;`);
+                // Hoist Idx declaration before the if block so it stays in scope after.
+                // Initialize to -1 so getVariable can still read checkpointed values when beforeNode skips.
+                lines.push(`    let ${safeChildId}Idx: number = -1;`);
                 lines.push(`    if (${awaitHook}__ctrl__.beforeNode('${child.id}', scopedCtx)) {`);
                 childIndent = '      ';
             }

package/dist/parser.js

@@ -14,6 +14,7 @@ import { getPackageExports } from './npm-packages.js';
 import { getSharedProject } from './shared-project.js';
 import { LRUCache } from './utils/lru-cache.js';
 import { COERCION_NODE_TYPES, COERCE_TYPE_MAP } from './built-in-nodes/coercion-types.js';
+import { BUILT_IN_NODE_TYPES } from './built-in-nodes/generated-registry.js';
 import { tagHandlerRegistry } from './parser/tag-registry.js';
 /**
  * Convert a TExternalNodeType to a TNodeTypeAST with sensible defaults.
@@ -233,8 +234,9 @@ export class AnnotationParser {
                 }
             }
         }
-        // Auto-infer node types from unannotated functions referenced by @node
-        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes);
+        // Auto-infer node types from unannotated functions referenced by @node,
+        // and lazily inject built-in nodes (delay, waitForEvent, etc.) when referenced
+        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes, localNodeTypes, warnings);
         nodeTypes.push(...inferredNodeTypes);
         const workflows = this.extractWorkflows(sourceFile, nodeTypes, filePath, errors, warnings);
         const patterns = this.extractPatterns(sourceFile, nodeTypes, filePath, errors, warnings);
@@ -282,8 +284,9 @@ export class AnnotationParser {
         const workflowSignatures = this.extractWorkflowSignatures(sourceFile, virtualPath, warnings);
         const sameFileWorkflowNodeTypes = workflowSignatures.map((wf) => this.workflowToNodeType(wf));
         const nodeTypes = [...localNodeTypes, ...sameFileWorkflowNodeTypes];
-        // Auto-infer node types from unannotated functions referenced by @node
-        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes);
+        // Auto-infer node types from unannotated functions referenced by @node,
+        // and lazily inject built-in nodes (delay, waitForEvent, etc.) when referenced
+        const inferredNodeTypes = this.inferNodeTypesFromUnannotated(sourceFile, nodeTypes, localNodeTypes, warnings);
         nodeTypes.push(...inferredNodeTypes);
         // Note: imports not supported for virtual files - would need filesystem access
         const workflows = this.extractWorkflows(sourceFile, nodeTypes, virtualPath, errors, warnings);
@@ -555,7 +558,7 @@ export class AnnotationParser {
         }
         else {
             // npm package import - use .d.ts inference
-            return this.resolveNpmImportAnnotation(imp, currentDir);
+            return this.resolveNpmImportAnnotation(imp, currentDir, warnings);
         }
     }
     /**
@@ -609,7 +612,7 @@ export class AnnotationParser {
     /**
      * Resolve an npm package @fwImport to a node type by reading .d.ts declarations.
      */
-    resolveNpmImportAnnotation(imp, currentDir) {
+    resolveNpmImportAnnotation(imp, currentDir, warnings) {
         // Check cache (with mtime validation — same pattern as resolveNpmImports)
         const cacheKey = `npm:${imp.importSource}`;
         if (this.importCache.has(cacheKey)) {
@@ -637,6 +640,8 @@ export class AnnotationParser {
         // Resolve .d.ts path
         const dtsPath = resolvePackageTypesPath(imp.importSource, currentDir);
         if (!dtsPath) {
+            warnings.push(`@fwImport: Package "${imp.importSource}" has no type declarations (.d.ts). ` +
+                `Install @types/${imp.importSource} or add a local wrapper with @flowWeaver nodeType annotations.`);
             return this.createImportStub(imp);
         }
         try {
@@ -667,9 +672,12 @@ export class AnnotationParser {
             if (found) {
                 return { ...found, name: imp.name, importSource: imp.importSource };
             }
+            // Function not found in .d.ts
+            warnings.push(`@fwImport: Function "${imp.functionName}" not found in type declarations for "${imp.importSource}". ` +
+                `Available exports: ${allNodeTypes.map((nt) => nt.functionName).join(', ') || '(none)'}.`);
         }
-        catch {
-            // Silently skip packages whose .d.ts can't be parsed
+        catch (err) {
+            warnings.push(`@fwImport: Failed to parse type declarations for "${imp.importSource}": ${err.message}. Node "${imp.name}" will use a generic stub.`);
         }
         return this.createImportStub(imp);
     }
@@ -982,6 +990,22 @@ export class AnnotationParser {
             // These are persisted in JSDoc so they survive file re-parsing
             // Uses the same inference logic as TS imports for consistency
             const importedNpmNodeTypes = (config.imports || []).map((imp) => this.resolveImportAnnotation(imp, filePath, warnings));
+            // Post-resolution check: warn when inferred node type has zero data ports
+            // (excluding control-flow ports). This usually means the .d.ts inference
+            // couldn't extract meaningful port info and a local wrapper is needed.
+            for (const nt of importedNpmNodeTypes) {
+                const dataInputs = Object.keys(nt.inputs).filter((p) => p !== 'execute');
+                const nonControlOutputs = Object.keys(nt.outputs).filter((p) => p !== 'onSuccess' && p !== 'onFailure');
+                // Stub fallback has only result: ANY — if that's all we have with zero
+                // data inputs, inference likely failed
+                const isStubOnly = nonControlOutputs.length === 1 &&
+                    nonControlOutputs[0] === 'result' &&
+                    nt.outputs.result?.dataType === 'ANY';
+                if (dataInputs.length === 0 && isStubOnly) {
+                    warnings.push(`Could not infer ports for "${nt.functionName}" from "${nt.importSource}". ` +
+                        `Wrap it in a local function with @flowWeaver nodeType annotations instead.`);
+                }
+            }
             // Combine available node types with imported npm types for validation
             const allAvailableNodeTypes = [...availableNodeTypes, ...importedNpmNodeTypes];
             // Convert instances to NodeInstanceAST
@@ -1350,7 +1374,7 @@ export class AnnotationParser {
      * nodeType annotation, we infer an expression node type from its TypeScript
      * signature. Phase 1: same-file functions only.
      */
-    inferNodeTypesFromUnannotated(sourceFile, existingNodeTypes) {
+    inferNodeTypesFromUnannotated(sourceFile, existingNodeTypes, localNodeTypes, warnings) {
         const allFunctions = extractFunctionLikes(sourceFile);
         // 1. Pre-scan workflows for @node references to collect referenced type names
         const referencedTypes = new Set();
@@ -1376,17 +1400,33 @@ export class AnnotationParser {
         }
         if (unresolvedTypes.size === 0)
             return [];
-        // 3. Match unresolved types to unannotated functions in the same file
+        // 3. Match unresolved types to unannotated functions OR built-in nodes
         const inferredNodeTypes = [];
         const alreadyInferred = new Set();
+        const builtInByName = new Map(BUILT_IN_NODE_TYPES.map((nt) => [nt.name, nt]));
+        const annotatedNames = new Set(localNodeTypes.map((nt) => nt.functionName));
         for (const unresolvedType of unresolvedTypes) {
             if (alreadyInferred.has(unresolvedType))
                 continue;
-            // Find matching function
+            // 3a. Check built-in nodes first
+            const builtIn = builtInByName.get(unresolvedType);
+            if (builtIn) {
+                inferredNodeTypes.push(builtIn);
+                alreadyInferred.add(unresolvedType);
+                // Warn if a local unannotated function has the same name (it will be shadowed)
+                if (!annotatedNames.has(unresolvedType)) {
+                    const shadowFn = allFunctions.find((fn) => fn.getName() === unresolvedType && !this.hasFlowWeaverAnnotation(fn));
+                    if (shadowFn) {
+                        warnings.push(`Function '${unresolvedType}' exists in this file but is not annotated with @flowWeaver nodeType. ` +
+                            `The built-in '${unresolvedType}' will be used instead. Add @flowWeaver nodeType to use your version.`);
+                    }
+                }
+                continue;
+            }
+            // 3b. Match unannotated local function
             const matchedFn = allFunctions.find((fn) => {
                 if (fn.getName() !== unresolvedType)
                     return false;
-                // Must NOT have a valid @flowWeaver annotation
                 return !this.hasFlowWeaverAnnotation(fn);
             });
             if (!matchedFn)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "Flow Weaver: deterministic TypeScript workflow compiler. Define workflows with JSDoc annotations, compile to standalone functions with zero runtime dependencies.",
   "private": false,
   "type": "module",
@@ -113,7 +113,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "prebuild": "tsx scripts/generate-version.ts",
+    "prebuild": "tsx scripts/generate-version.ts && tsx scripts/generate-built-in-registry.ts",
+    "generate:registry": "tsx scripts/generate-built-in-registry.ts",
+    "generate:registry:check": "tsx scripts/generate-built-in-registry.ts --check",
     "build": "rimraf dist .tsbuildinfo && tsc -p tsconfig.build.json && npm run build:cli",
     "postbuild": "npx tsx scripts/postbuild.ts && npm run generate:docs",
     "generate:docs": "tsx scripts/generate-docs.ts",