@synergenius/flow-weaver 0.27.5 → 0.29.0

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.27.5";
+export declare const VERSION = "0.29.0";
 //# 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.27.5';
+export const VERSION = '0.29.0';
 //# sourceMappingURL=generated-version.js.map

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

@@ -187,18 +187,35 @@ export function generateScopeFunctionClosure(scopeName, parentNodeId, parentNode
             }
             const safeChildId = toValidIdentifier(child.id);
             const awaitPrefix = isAsync ? 'await ' : '';
+            const emitDebugHooks = !production;
+            // Indentation increases when debug hooks wrap the child block
+            let childIndent = '    ';
             lines.push(``);
             lines.push(`    // Execute: ${child.id} (${child.nodeType})`);
-            lines.push(`    scopedCtx.checkAborted('${child.id}');`);
-            lines.push(`    const ${safeChildId}Idx = scopedCtx.addExecution('${child.id}');`);
-            lines.push(`    if (typeof globalThis !== 'undefined') (globalThis as unknown as { __fw_current_node_id__?: string }).__fw_current_node_id__ = '${child.id}';`);
-            lines.push(`    ${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
-            lines.push(`      nodeTypeName: '${child.nodeType}',`);
-            lines.push(`      id: '${child.id}',`);
-            lines.push(`      executionIndex: ${safeChildId}Idx,`);
-            lines.push(`      status: 'RUNNING',`);
-            lines.push(`    });`);
-            lines.push(`    try {`);
+            // Debug controller: beforeNode hook for scoped children
+            // 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.
+                // 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 = '      ';
+            }
+            lines.push(`${childIndent}scopedCtx.checkAborted('${child.id}');`);
+            // Use assignment when debug hooks hoist the declaration, const otherwise
+            const idxDecl = emitDebugHooks ? '' : 'const ';
+            lines.push(`${childIndent}${idxDecl}${safeChildId}Idx = scopedCtx.addExecution('${child.id}');`);
+            lines.push(`${childIndent}if (typeof globalThis !== 'undefined') (globalThis as unknown as { __fw_current_node_id__?: string }).__fw_current_node_id__ = '${child.id}';`);
+            lines.push(`${childIndent}${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
+            lines.push(`${childIndent}  nodeTypeName: '${child.nodeType}',`);
+            lines.push(`${childIndent}  id: '${child.id}',`);
+            lines.push(`${childIndent}  executionIndex: ${safeChildId}Idx,`);
+            lines.push(`${childIndent}  status: 'RUNNING',`);
+            lines.push(`${childIndent}});`);
+            lines.push(`${childIndent}try {`);
+            // Inner indentation: inside try block (childIndent + 2 spaces for try body)
+            const tryIndent = `${childIndent}  `;
             // Pre-handle connections from parent scoped OUTPUT ports with correct index variables
             const argLines = [];
             const getCall = isAsync ? 'await scopedCtx.getVariable' : 'scopedCtx.getVariable';
@@ -218,9 +235,9 @@ export function generateScopeFunctionClosure(scopeName, parentNodeId, parentNode
                     const portType = targetPortDef
                         ? mapToTypeScript(targetPortDef.dataType, targetPortDef.tsType)
                         : 'unknown';
-                    argLines.push(`      const ${varName} = ${getCall}({ id: '${parentNodeId}', portName: '${conn.from.port}', executionIndex: ${scopeParamIdxVar} }) as ${portType};`);
+                    argLines.push(`${tryIndent}const ${varName} = ${getCall}({ id: '${parentNodeId}', portName: '${conn.from.port}', executionIndex: ${scopeParamIdxVar} }) as ${portType};`);
                     // Emit VARIABLE_SET for the child's INPUT port so breakpoints and inspection work
-                    argLines.push(`      ${childSetCall}({ id: '${child.id}', portName: '${targetPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${varName});`);
+                    argLines.push(`${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${targetPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${varName});`);
                     preHandledPorts.add(targetPort);
                 }
             });
@@ -230,7 +247,7 @@ export function generateScopeFunctionClosure(scopeName, parentNodeId, parentNode
                 workflow: scopeWorkflow,
                 id: child.id,
                 lines: argLines,
-                indent: `      `,
+                indent: tryIndent,
                 getCall,
                 isAsync,
                 instanceParent: child.parent ? `${child.parent.id}.${child.parent.scope}` : undefined,
@@ -245,11 +262,11 @@ export function generateScopeFunctionClosure(scopeName, parentNodeId, parentNode
             // Call the child node function
             if (childNodeType.expression) {
                 // Expression nodes use original signature (positional args, no execute)
-                lines.push(`      const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(', ')});`);
+                lines.push(`${tryIndent}const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(', ')});`);
             }
             else {
                 // Regular node call with positional arguments
-                lines.push(`      const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(', ')});`);
+                lines.push(`${tryIndent}const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(', ')});`);
             }
             // Store outputs (including onSuccess/onFailure for debugging)
             // Expression nodes don't return onSuccess/onFailure — hardcode them
@@ -258,48 +275,57 @@ export function generateScopeFunctionClosure(scopeName, parentNodeId, parentNode
                     const portDef = childNodeType.outputs[outPort];
                     if (portDef.failure || isFailurePort(outPort)) {
                         // Failure ports always false on success (expression nodes always succeed)
-                        lines.push(`      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, false);`);
+                        lines.push(`${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, false);`);
                     }
                     else if (portDef.isControlFlow || isSuccessPort(outPort)) {
                         // Success control flow ports always true (expression nodes always succeed)
-                        lines.push(`      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, true);`);
+                        lines.push(`${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, true);`);
                     }
                     else {
                         // Data outputs read from result object
-                        lines.push(`      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`);
+                        lines.push(`${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`);
                     }
                 });
             }
             else {
                 Object.keys(childNodeType.outputs || {}).forEach((outPort) => {
-                    lines.push(`      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`);
+                    lines.push(`${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`);
                 });
             }
             // Add SUCCEEDED status event
-            lines.push(`      ${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
-            lines.push(`        nodeTypeName: '${child.nodeType}',`);
-            lines.push(`        id: '${child.id}',`);
-            lines.push(`        executionIndex: ${safeChildId}Idx,`);
-            lines.push(`        status: 'SUCCEEDED',`);
-            lines.push(`      });`);
-            lines.push(`    } catch (error: unknown) {`);
-            lines.push(`      const isCancellation = CancellationError.isCancellationError(error);`);
-            lines.push(`      ${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
-            lines.push(`        nodeTypeName: '${child.nodeType}',`);
-            lines.push(`        id: '${child.id}',`);
-            lines.push(`        executionIndex: ${safeChildId}Idx,`);
-            lines.push(`        status: isCancellation ? 'CANCELLED' : 'FAILED',`);
-            lines.push(`      });`);
-            lines.push(`      if (!isCancellation) {`);
-            lines.push(`        scopedCtx.sendLogErrorEvent({`);
-            lines.push(`          nodeTypeName: '${child.nodeType}',`);
-            lines.push(`          id: '${child.id}',`);
-            lines.push(`          executionIndex: ${safeChildId}Idx,`);
-            lines.push(`          error: error instanceof Error ? error.message : String(error),`);
-            lines.push(`        });`);
-            lines.push(`      }`);
-            lines.push(`      throw error;`);
-            lines.push(`    }`);
+            lines.push(`${tryIndent}${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
+            lines.push(`${tryIndent}  nodeTypeName: '${child.nodeType}',`);
+            lines.push(`${tryIndent}  id: '${child.id}',`);
+            lines.push(`${tryIndent}  executionIndex: ${safeChildId}Idx,`);
+            lines.push(`${tryIndent}  status: 'SUCCEEDED',`);
+            lines.push(`${tryIndent}});`);
+            // Debug controller: afterNode hook for scoped children
+            if (emitDebugHooks) {
+                const awaitHook = isAsync ? 'await ' : '';
+                lines.push(`${tryIndent}${awaitHook}__ctrl__.afterNode('${child.id}', scopedCtx);`);
+            }
+            lines.push(`${childIndent}} catch (error: unknown) {`);
+            lines.push(`${tryIndent}const isCancellation = CancellationError.isCancellationError(error);`);
+            lines.push(`${tryIndent}${awaitPrefix}scopedCtx.sendStatusChangedEvent({`);
+            lines.push(`${tryIndent}  nodeTypeName: '${child.nodeType}',`);
+            lines.push(`${tryIndent}  id: '${child.id}',`);
+            lines.push(`${tryIndent}  executionIndex: ${safeChildId}Idx,`);
+            lines.push(`${tryIndent}  status: isCancellation ? 'CANCELLED' : 'FAILED',`);
+            lines.push(`${tryIndent}});`);
+            lines.push(`${tryIndent}if (!isCancellation) {`);
+            lines.push(`${tryIndent}  scopedCtx.sendLogErrorEvent({`);
+            lines.push(`${tryIndent}    nodeTypeName: '${child.nodeType}',`);
+            lines.push(`${tryIndent}    id: '${child.id}',`);
+            lines.push(`${tryIndent}    executionIndex: ${safeChildId}Idx,`);
+            lines.push(`${tryIndent}    error: error instanceof Error ? error.message : String(error),`);
+            lines.push(`${tryIndent}  });`);
+            lines.push(`${tryIndent}}`);
+            lines.push(`${tryIndent}throw error;`);
+            lines.push(`${childIndent}}`);
+            // Close debug controller beforeNode if-block
+            if (emitDebugHooks) {
+                lines.push(`    }`);
+            }
         });
         lines.push(``);
     }

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)
@@ -1653,6 +1693,10 @@ export class AnnotationParser {
                 for (const [inputName] of Object.entries(nextInputs)) {
                     if (isControlFlowPort(inputName))
                         continue;
+                    // Skip auto-wiring if a manual @connect already targets this input port
+                    const alreadyConnected = connections.some(c => c.to.node === nextId && c.to.port === inputName);
+                    if (alreadyConnected)
+                        continue;
                     // Walk backward through path steps to find nearest ancestor with same-name output
                     for (let j = i; j >= 0; j--) {
                         const ancestorId = steps[j].node;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.27.5",
+  "version": "0.29.0",
   "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",