@synergenius/flow-weaver 0.27.4 → 0.28.0

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/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();

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.27.4";
+    VERSION = "0.28.0";
   }
 });
 
@@ -6645,18 +6645,28 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
       }
       const safeChildId = toValidIdentifier(child.id);
       const awaitPrefix = isAsync2 ? "await " : "";
+      const emitDebugHooks = !production;
+      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 {`);
+      if (emitDebugHooks) {
+        const awaitHook = isAsync2 ? "await " : "";
+        lines.push(`    let ${safeChildId}Idx: number;`);
+        lines.push(`    if (${awaitHook}__ctrl__.beforeNode('${child.id}', scopedCtx)) {`);
+        childIndent = "      ";
+      }
+      lines.push(`${childIndent}scopedCtx.checkAborted('${child.id}');`);
+      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 {`);
+      const tryIndent = `${childIndent}  `;
       const argLines = [];
       const getCall = isAsync2 ? "await scopedCtx.getVariable" : "scopedCtx.getVariable";
       const childSetCall = isAsync2 ? `await scopedCtx.setVariable` : `scopedCtx.setVariable`;
@@ -6673,10 +6683,10 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
           const targetPortDef = childNodeType.inputs[targetPort];
           const portType = targetPortDef ? mapToTypeScript(targetPortDef.dataType, targetPortDef.tsType) : "unknown";
           argLines.push(
-            `      const ${varName} = ${getCall}({ id: '${parentNodeId}', portName: '${conn.from.port}', executionIndex: ${scopeParamIdxVar} }) as ${portType};`
+            `${tryIndent}const ${varName} = ${getCall}({ id: '${parentNodeId}', portName: '${conn.from.port}', executionIndex: ${scopeParamIdxVar} }) as ${portType};`
           );
           argLines.push(
-            `      ${childSetCall}({ id: '${child.id}', portName: '${targetPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${varName});`
+            `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${targetPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${varName});`
           );
           preHandledPorts.add(targetPort);
         }
@@ -6686,7 +6696,7 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
         workflow: scopeWorkflow,
         id: child.id,
         lines: argLines,
-        indent: `      `,
+        indent: tryIndent,
         getCall,
         isAsync: isAsync2,
         instanceParent: child.parent ? `${child.parent.id}.${child.parent.scope}` : void 0,
@@ -6699,11 +6709,11 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
       argLines.forEach((line) => lines.push(line));
       if (childNodeType.expression) {
         lines.push(
-          `      const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(", ")});`
+          `${tryIndent}const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(", ")});`
         );
       } else {
         lines.push(
-          `      const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(", ")});`
+          `${tryIndent}const ${safeChildId}Result = ${awaitPrefix}${child.nodeType}(${args.join(", ")});`
         );
       }
       if (childNodeType.expression) {
@@ -6711,49 +6721,56 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
           const portDef = childNodeType.outputs[outPort];
           if (portDef.failure || isFailurePort(outPort)) {
             lines.push(
-              `      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, false);`
+              `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, false);`
             );
           } else if (portDef.isControlFlow || isSuccessPort(outPort)) {
             lines.push(
-              `      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, true);`
+              `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, true);`
             );
           } else {
             lines.push(
-              `      ${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`
+              `${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});`
+            `${tryIndent}${childSetCall}({ id: '${child.id}', portName: '${outPort}', executionIndex: ${safeChildId}Idx, nodeTypeName: '${child.nodeType}' }, ${safeChildId}Result.${outPort});`
           );
         });
       }
-      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}});`);
+      if (emitDebugHooks) {
+        const awaitHook = isAsync2 ? "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}}`);
+      if (emitDebugHooks) {
+        lines.push(`    }`);
+      }
     });
     lines.push(``);
   }
@@ -29005,6 +29022,10 @@ ${fn.getText()}` : fn.getText();
             const nextInputs = getInputPorts(nextId);
             for (const [inputName] of Object.entries(nextInputs)) {
               if (isControlFlowPort(inputName)) continue;
+              const alreadyConnected = connections.some(
+                (c) => c.to.node === nextId && c.to.port === inputName
+              );
+              if (alreadyConnected) continue;
               for (let j2 = i; j2 >= 0; j2--) {
                 const ancestorId = steps[j2].node;
                 const ancestorOutputs = getOutputPorts(ancestorId);
@@ -37919,7 +37940,7 @@ function getDependents(ast, nodeId) {
   });
   return Array.from(dependents);
 }
-function getTopologicalOrder(ast) {
+function getTopologicalOrder(ast, options) {
   const mainInstances = getMainFlowInstances(ast);
   const mainConnections = getMainFlowConnections(ast);
   const inDegree = /* @__PURE__ */ new Map();
@@ -37958,6 +37979,30 @@ function getTopologicalOrder(ast) {
   if (result.length !== mainInstances.length) {
     throw new Error("Cannot compute topological order: workflow contains cycles");
   }
+  if (options?.includeScopedChildren) {
+    const scopedChildren = ast.instances.filter(
+      (inst) => isPerPortScopedChild(inst, ast, ast.nodeTypes)
+    );
+    const expanded = [];
+    const scopedByParent = /* @__PURE__ */ 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;
 }
 function findIsolatedNodes(ast) {
@@ -58608,9 +58653,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();
@@ -58628,17 +58673,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")}`);
 }
 function pad(displayName, width) {
   const padding = Math.max(1, width - displayName.length);
@@ -59588,16 +59633,19 @@ ${workflowCode}`;
       "",
       `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");
   } else {
@@ -59613,16 +59661,19 @@ ${workflowCode}`;
       "",
       `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");
   }
@@ -84560,6 +84611,13 @@ async function runCommandInner(input, options) {
       logger.newline();
       logger.section("Result");
       logger.log(JSON.stringify(result.result, null, 2));
+      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."
+        );
+      }
       if (options.trace && !options.stream && result.trace && result.trace.length > 0) {
         logger.newline();
         logger.section("Trace");
@@ -88468,7 +88526,7 @@ function parseIntStrict(value) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.27.4" : "0.0.0-dev";
+var version2 = true ? "0.28.0" : "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.27.4";
+export declare const VERSION = "0.28.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.4';
+export const VERSION = '0.28.0';
 //# sourceMappingURL=generated-version.js.map

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

@@ -187,18 +187,34 @@ 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
+                lines.push(`    let ${safeChildId}Idx: number;`);
+                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 +234,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 +246,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 +261,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 +274,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

@@ -1653,6 +1653,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,7 +1,7 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.27.4",
-  "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
+  "version": "0.28.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",
   "main": "./dist/index.js",
@@ -138,12 +138,18 @@
   "keywords": [
     "flow-weaver",
     "workflow",
+    "workflow-engine",
+    "workflow-automation",
+    "orchestration",
     "ai-agent",
     "llm",
     "mcp",
-    "deterministic",
     "typescript",
     "compiler",
+    "code-generation",
+    "visual-programming",
+    "node-graph",
+    "durable-execution",
     "inngest",
     "serverless"
   ],