@synergenius/flow-weaver 0.5.1 → 0.7.0

package/dist/cli/flow-weaver.mjs

@@ -11812,14 +11812,84 @@ var init_signature_parser = __esm({
   }
 });
 
+// src/type-checker.ts
+function isRuntimeCoercible(sourceText, targetText) {
+  const sourceLower = sourceText.toLowerCase();
+  const targetLower = targetText.toLowerCase();
+  for (const [from, to] of SAFE_COERCIONS) {
+    if (sourceLower === from && targetLower === to) {
+      return true;
+    }
+  }
+  return false;
+}
+function checkTypeCompatibilityFromStrings(sourceText, targetText) {
+  if (sourceText === targetText) {
+    return {
+      isCompatible: true,
+      reason: "exact",
+      sourceType: sourceText,
+      targetType: targetText
+    };
+  }
+  if (sourceText === "any" || targetText === "any") {
+    return {
+      isCompatible: true,
+      reason: "assignable",
+      sourceType: sourceText,
+      targetType: targetText
+    };
+  }
+  if (isRuntimeCoercible(sourceText, targetText)) {
+    return {
+      isCompatible: true,
+      reason: "coercible",
+      sourceType: sourceText,
+      targetType: targetText
+    };
+  }
+  return {
+    isCompatible: false,
+    reason: "incompatible",
+    sourceType: sourceText,
+    targetType: targetText,
+    errorMessage: `Type '${sourceText}' is not assignable to type '${targetText}'`
+  };
+}
+var SAFE_COERCIONS;
+var init_type_checker = __esm({
+  "src/type-checker.ts"() {
+    "use strict";
+    SAFE_COERCIONS = [
+      ["number", "string"],
+      // Number.toString()
+      ["boolean", "string"]
+      // Boolean.toString()
+    ];
+  }
+});
+
 // src/validator.ts
-var WorkflowValidator, validator;
+var DOCS_BASE, ERROR_DOC_URLS, WorkflowValidator, validator;
 var init_validator = __esm({
   "src/validator.ts"() {
     "use strict";
     init_constants();
     init_string_distance();
     init_signature_parser();
+    init_type_checker();
+    DOCS_BASE = "https://docs.flowweaver.dev/reference";
+    ERROR_DOC_URLS = {
+      UNKNOWN_NODE_TYPE: `${DOCS_BASE}/concepts#node-registration`,
+      UNKNOWN_SOURCE_PORT: `${DOCS_BASE}/concepts#port-architecture`,
+      UNKNOWN_TARGET_PORT: `${DOCS_BASE}/concepts#port-architecture`,
+      TYPE_MISMATCH: `${DOCS_BASE}/compilation#type-compatibility`,
+      UNREACHABLE_NODE: `${DOCS_BASE}/concepts#graph-structure`,
+      MISSING_START_CONNECTION: `${DOCS_BASE}/concepts#start-and-exit`,
+      MISSING_EXIT_CONNECTION: `${DOCS_BASE}/concepts#start-and-exit`,
+      INFERRED_NODE_TYPE: `${DOCS_BASE}/node-conversion`,
+      DUPLICATE_CONNECTION: `${DOCS_BASE}/concepts#connections`
+    };
     WorkflowValidator = class {
       errors = [];
       warnings = [];
@@ -11947,6 +12017,11 @@ var init_validator = __esm({
             return true;
           });
         }
+        for (const diag of [...this.errors, ...this.warnings]) {
+          if (!diag.docUrl && ERROR_DOC_URLS[diag.code]) {
+            diag.docUrl = ERROR_DOC_URLS[diag.code];
+          }
+        }
         return {
           valid: this.errors.length === 0,
           errors: this.errors,
@@ -12170,11 +12245,13 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
           }
           const sourceType = sourcePortDef.dataType;
           const targetType = targetPortDef.dataType;
+          const sourceTsType = sourcePortDef.tsType;
+          const targetTsType = targetPortDef.tsType;
           if (sourceType === "STEP" && targetType !== "STEP") {
             this.errors.push({
               type: "error",
               code: "STEP_PORT_TYPE_MISMATCH",
-              message: `STEP port "${fromPort}" on node "${fromNode}" cannot connect to non-STEP port "${toPort}" (${targetType}) on node "${toNode}"`,
+              message: `STEP port "${fromPort}" on node "${fromNode}" cannot connect to non-STEP port "${toPort}" (${this.formatType(targetType, targetTsType)}) on node "${toNode}"`,
               connection: conn,
               location: connLocation
             });
@@ -12184,7 +12261,7 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
             this.errors.push({
               type: "error",
               code: "STEP_PORT_TYPE_MISMATCH",
-              message: `Non-STEP port "${fromPort}" (${sourceType}) on node "${fromNode}" cannot connect to STEP port "${toPort}" on node "${toNode}"`,
+              message: `Non-STEP port "${fromPort}" (${this.formatType(sourceType, sourceTsType)}) on node "${fromNode}" cannot connect to STEP port "${toPort}" on node "${toNode}"`,
               connection: conn,
               location: connLocation
             });
@@ -12195,14 +12272,19 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
           }
           if (sourceType === targetType) {
             if (sourceType === "OBJECT" && sourcePortDef.tsType && targetPortDef.tsType) {
-              if (this.normalizeTypeString(sourcePortDef.tsType) !== this.normalizeTypeString(targetPortDef.tsType)) {
-                this.warnings.push({
-                  type: "warning",
-                  code: "OBJECT_TYPE_MISMATCH",
-                  message: `Structural type mismatch: ${fromNode}.${fromPort} outputs "${sourcePortDef.tsType}" but ${toNode}.${toPort} expects "${targetPortDef.tsType}". Verify the object shapes are compatible.`,
-                  connection: conn,
-                  location: connLocation
-                });
+              const normalizedSource = this.normalizeTypeString(sourcePortDef.tsType);
+              const normalizedTarget = this.normalizeTypeString(targetPortDef.tsType);
+              if (normalizedSource !== normalizedTarget) {
+                const compat = checkTypeCompatibilityFromStrings(sourcePortDef.tsType, targetPortDef.tsType);
+                if (!compat.isCompatible) {
+                  this.warnings.push({
+                    type: "warning",
+                    code: "OBJECT_TYPE_MISMATCH",
+                    message: `Structural type mismatch: ${fromNode}.${fromPort} outputs "${sourcePortDef.tsType}" but ${toNode}.${toPort} expects "${targetPortDef.tsType}". Verify the object shapes are compatible.`,
+                    connection: conn,
+                    location: connLocation
+                  });
+                }
               }
             }
             return;
@@ -12231,7 +12313,7 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
                 {
                   type: "warning",
                   code: "LOSSY_TYPE_COERCION",
-                  message: `Lossy type coercion from ${sourceType} to ${targetType} in connection ${fromNode}.${fromPort} \u2192 ${toNode}.${toPort}. ${reason}. Add @strictTypes to your workflow annotation to enforce type safety.`,
+                  message: `Lossy type coercion from ${this.formatType(sourceType, sourceTsType)} to ${this.formatType(targetType, targetTsType)} in connection ${fromNode}.${fromPort} \u2192 ${toNode}.${toPort}. ${reason}. Add @strictTypes to your workflow annotation to enforce type safety.`,
                   connection: conn,
                   location: connLocation
                 },
@@ -12256,7 +12338,7 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
                 {
                   type: "warning",
                   code: "UNUSUAL_TYPE_COERCION",
-                  message: `Unusual type coercion from ${sourceType} to ${targetType} in connection ${fromNode}.${fromPort} \u2192 ${toNode}.${toPort}. ${reason}.`,
+                  message: `Unusual type coercion from ${this.formatType(sourceType, sourceTsType)} to ${this.formatType(targetType, targetTsType)} in connection ${fromNode}.${fromPort} \u2192 ${toNode}.${toPort}. ${reason}.`,
                   connection: conn,
                   location: connLocation
                 },
@@ -12269,7 +12351,7 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
             {
               type: "warning",
               code: "TYPE_MISMATCH",
-              message: `Type mismatch in connection ${fromNode}.${fromPort} (${sourceType}) \u2192 ${toNode}.${toPort} (${targetType}). Runtime coercion will be attempted.`,
+              message: `Type mismatch in connection ${fromNode}.${fromPort} (${this.formatType(sourceType, sourceTsType)}) \u2192 ${toNode}.${toPort} (${this.formatType(targetType, targetTsType)}). Runtime coercion will be attempted.`,
               connection: conn,
               location: connLocation
             },
@@ -12704,6 +12786,30 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
             if (portDef.scope) scopeNames.add(portDef.scope);
           }
           if (scopeNames.size === 0) continue;
+          for (const conn of workflow.connections) {
+            if (conn.from.scope && conn.from.node === instance.id) {
+              if (!scopeNames.has(conn.from.scope)) {
+                this.errors.push({
+                  type: "error",
+                  code: "SCOPE_WRONG_SCOPE_NAME",
+                  message: `Connection from "${instance.id}.${conn.from.port}" uses scope qualifier ":${conn.from.scope}" but node "${instance.id}" does not define scope "${conn.from.scope}". Available scopes: ${[...scopeNames].join(", ")}.`,
+                  connection: conn,
+                  location: this.getConnectionLocation(conn)
+                });
+              }
+            }
+            if (conn.to.scope && conn.to.node === instance.id) {
+              if (!scopeNames.has(conn.to.scope)) {
+                this.errors.push({
+                  type: "error",
+                  code: "SCOPE_WRONG_SCOPE_NAME",
+                  message: `Connection to "${instance.id}.${conn.to.port}" uses scope qualifier ":${conn.to.scope}" but node "${instance.id}" does not define scope "${conn.to.scope}". Available scopes: ${[...scopeNames].join(", ")}.`,
+                  connection: conn,
+                  location: this.getConnectionLocation(conn)
+                });
+              }
+            }
+          }
           for (const scopeName of scopeNames) {
             const childIds = [];
             for (const child of workflow.instances) {
@@ -12715,6 +12821,108 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
             const scopedConnections = workflow.connections.filter(
               (conn) => conn.from.scope === scopeName && conn.from.node === instance.id || conn.to.scope === scopeName && conn.to.node === instance.id || conn.from.scope === scopeName && childIds.includes(conn.from.node) || conn.to.scope === scopeName && childIds.includes(conn.to.node)
             );
+            for (const conn of scopedConnections) {
+              if (conn.from.node === instance.id && conn.from.scope === scopeName) {
+                const portDef = nodeType.outputs[conn.from.port];
+                if (!portDef) {
+                  const availablePorts = Object.entries(nodeType.outputs).filter(([, p]) => p.scope === scopeName).map(([n]) => n);
+                  this.errors.push({
+                    type: "error",
+                    code: "SCOPE_UNKNOWN_PORT",
+                    message: `Scoped connection references non-existent output port "${conn.from.port}" on "${instance.id}" in scope "${scopeName}". Available scoped outputs: ${availablePorts.join(", ") || "none"}.`,
+                    connection: conn,
+                    location: this.getConnectionLocation(conn)
+                  });
+                } else if (portDef.scope !== scopeName) {
+                  this.errors.push({
+                    type: "error",
+                    code: "SCOPE_UNKNOWN_PORT",
+                    message: `Output port "${conn.from.port}" on "${instance.id}" is not a scoped port of scope "${scopeName}"${portDef.scope ? ` (it belongs to scope "${portDef.scope}")` : " (it is an unscoped port)"}.`,
+                    connection: conn,
+                    location: this.getConnectionLocation(conn)
+                  });
+                }
+              }
+              if (conn.to.node === instance.id && conn.to.scope === scopeName) {
+                const portDef = nodeType.inputs[conn.to.port];
+                if (!portDef) {
+                  const availablePorts = Object.entries(nodeType.inputs).filter(([, p]) => p.scope === scopeName).map(([n]) => n);
+                  this.errors.push({
+                    type: "error",
+                    code: "SCOPE_UNKNOWN_PORT",
+                    message: `Scoped connection references non-existent input port "${conn.to.port}" on "${instance.id}" in scope "${scopeName}". Available scoped inputs: ${availablePorts.join(", ") || "none"}.`,
+                    connection: conn,
+                    location: this.getConnectionLocation(conn)
+                  });
+                } else if (portDef.scope !== scopeName) {
+                  this.errors.push({
+                    type: "error",
+                    code: "SCOPE_UNKNOWN_PORT",
+                    message: `Input port "${conn.to.port}" on "${instance.id}" is not a scoped port of scope "${scopeName}"${portDef.scope ? ` (it belongs to scope "${portDef.scope}")` : " (it is an unscoped port)"}.`,
+                    connection: conn,
+                    location: this.getConnectionLocation(conn)
+                  });
+                }
+              }
+            }
+            for (const conn of scopedConnections) {
+              if (conn.from.scope === scopeName && childIds.includes(conn.from.node)) {
+                if (conn.to.node !== instance.id && !childIds.includes(conn.to.node)) {
+                  this.errors.push({
+                    type: "error",
+                    code: "SCOPE_CONNECTION_OUTSIDE",
+                    message: `Scoped connection from "${conn.from.node}.${conn.from.port}" targets "${conn.to.node}" which is not inside scope "${scopeName}" of "${instance.id}".`,
+                    connection: conn,
+                    location: this.getConnectionLocation(conn)
+                  });
+                }
+              }
+              if (conn.to.scope === scopeName && childIds.includes(conn.to.node)) {
+                if (conn.from.node !== instance.id && !childIds.includes(conn.from.node)) {
+                  this.errors.push({
+                    type: "error",
+                    code: "SCOPE_CONNECTION_OUTSIDE",
+                    message: `Scoped connection to "${conn.to.node}.${conn.to.port}" sources from "${conn.from.node}" which is not inside scope "${scopeName}" of "${instance.id}".`,
+                    connection: conn,
+                    location: this.getConnectionLocation(conn)
+                  });
+                }
+              }
+            }
+            for (const conn of scopedConnections) {
+              if (conn.from.node === instance.id && conn.from.scope === scopeName) {
+                const parentPort = nodeType.outputs[conn.from.port];
+                const childType = instanceMap.get(conn.to.node);
+                const childPort = childType?.inputs[conn.to.port];
+                if (parentPort && childPort && parentPort.dataType !== "STEP" && childPort.dataType !== "STEP") {
+                  if (parentPort.dataType !== childPort.dataType && parentPort.dataType !== "ANY" && childPort.dataType !== "ANY") {
+                    this.warnings.push({
+                      type: "warning",
+                      code: "SCOPE_PORT_TYPE_MISMATCH",
+                      message: `Type mismatch in scope "${scopeName}": "${instance.id}.${conn.from.port}" outputs ${this.formatType(parentPort.dataType, parentPort.tsType)} but "${conn.to.node}.${conn.to.port}" expects ${this.formatType(childPort.dataType, childPort.tsType)}.`,
+                      connection: conn,
+                      location: this.getConnectionLocation(conn)
+                    });
+                  }
+                }
+              }
+              if (conn.to.node === instance.id && conn.to.scope === scopeName) {
+                const parentPort = nodeType.inputs[conn.to.port];
+                const childType = instanceMap.get(conn.from.node);
+                const childPort = childType?.outputs[conn.from.port];
+                if (parentPort && childPort && parentPort.dataType !== "STEP" && childPort.dataType !== "STEP") {
+                  if (parentPort.dataType !== childPort.dataType && parentPort.dataType !== "ANY" && childPort.dataType !== "ANY") {
+                    this.warnings.push({
+                      type: "warning",
+                      code: "SCOPE_PORT_TYPE_MISMATCH",
+                      message: `Type mismatch in scope "${scopeName}": "${conn.from.node}.${conn.from.port}" outputs ${this.formatType(childPort.dataType, childPort.tsType)} but "${instance.id}.${conn.to.port}" expects ${this.formatType(parentPort.dataType, parentPort.tsType)}.`,
+                      connection: conn,
+                      location: this.getConnectionLocation(conn)
+                    });
+                  }
+                }
+              }
+            }
             for (const childId of childIds) {
               const childType = instanceMap.get(childId);
               if (!childType) continue;
@@ -12758,9 +12966,36 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
                 });
               }
             }
+            for (const childId of childIds) {
+              const hasConnectionFromParent = scopedConnections.some(
+                (conn) => conn.from.node === instance.id && conn.from.scope === scopeName && conn.to.node === childId
+              );
+              const hasConnectionToParent = scopedConnections.some(
+                (conn) => conn.to.node === instance.id && conn.to.scope === scopeName && conn.from.node === childId
+              );
+              if (!hasConnectionFromParent && !hasConnectionToParent) {
+                this.warnings.push({
+                  type: "warning",
+                  code: "SCOPE_ORPHANED_CHILD",
+                  message: `Child node "${childId}" is declared inside scope "${scopeName}" of "${instance.id}" but has no scoped connections to or from the parent. It is disconnected from the scope's data flow.`,
+                  node: childId,
+                  location: this.getInstanceLocation(workflow, childId)
+                });
+              }
+            }
           }
         }
       }
+      /**
+       * Format a type for display in error messages.
+       * Prefers the structural TypeScript type when available, falling back to the enum name.
+       */
+      formatType(dataType, tsType) {
+        if (tsType) {
+          return `${tsType} (${dataType})`;
+        }
+        return dataType;
+      }
       normalizeTypeString(type2) {
         let n = type2;
         n = n.replace(/\s+/g, "");
@@ -28985,7 +29220,29 @@ function generateNodeCallWithContext(instance, nodeType, workflow, _availableVar
   });
   const resultVar = `${safeId}Result`;
   const awaitKeyword = nodeType.isAsync ? "await " : "";
-  if (nodeType.expression) {
+  if (nodeType.variant === "COERCION") {
+    const coerceExprMap = {
+      __fw_toString: "String",
+      __fw_toNumber: "Number",
+      __fw_toBoolean: "Boolean",
+      __fw_toJSON: "JSON.stringify",
+      __fw_parseJSON: "JSON.parse"
+    };
+    const coerceExpr = coerceExprMap[functionName] || "String";
+    const valueArg = args[0] || "undefined";
+    lines.push(
+      `${indent}  const ${resultVar} = ${coerceExpr}(${valueArg});`
+    );
+    lines.push(
+      `${indent}  ${setCall}({ id: '${instanceId}', portName: 'result', executionIndex: ${safeId}Idx, nodeTypeName: '${functionName}' }, ${resultVar});`
+    );
+    lines.push(
+      `${indent}  ${setCall}({ id: '${instanceId}', portName: 'onSuccess', executionIndex: ${safeId}Idx, nodeTypeName: '${functionName}' }, true);`
+    );
+    lines.push(
+      `${indent}  ${setCall}({ id: '${instanceId}', portName: 'onFailure', executionIndex: ${safeId}Idx, nodeTypeName: '${functionName}' }, false);`
+    );
+  } else if (nodeType.expression) {
     lines.push(
       `${indent}  const ${resultVar} = ${awaitKeyword}${functionName}(${args.join(", ")});`
     );
@@ -30510,6 +30767,9 @@ var AnnotationGenerator = class {
       if (nodeType.variant === "MAP_ITERATOR") {
         return;
       }
+      if (nodeType.variant === "COERCION") {
+        return;
+      }
       lines.push(
         ...this.generateNodeTypeAnnotation(
           nodeType,
@@ -30534,7 +30794,9 @@ var AnnotationGenerator = class {
     }
     lines.push("/**");
     if (includeComments && nodeType.description) {
-      lines.push(` * ${nodeType.description}`);
+      for (const descLine of nodeType.description.split("\n")) {
+        lines.push(` * ${descLine}`);
+      }
       lines.push(` *`);
     }
     lines.push(" * @flowWeaver nodeType");
@@ -30618,12 +30880,15 @@ var AnnotationGenerator = class {
     const macroInstanceIds = /* @__PURE__ */ new Set();
     const macroChildIds = /* @__PURE__ */ new Set();
     const macroScopeNames = /* @__PURE__ */ new Set();
+    const coerceInstanceIds = /* @__PURE__ */ new Set();
     if (workflow.macros && workflow.macros.length > 0) {
       for (const macro of workflow.macros) {
         if (macro.type === "map") {
           macroInstanceIds.add(macro.instanceId);
           macroChildIds.add(macro.childId);
           macroScopeNames.add(`${macro.instanceId}.iterate`);
+        } else if (macro.type === "coerce") {
+          coerceInstanceIds.add(macro.instanceId);
         }
       }
     }
@@ -30673,6 +30938,7 @@ var AnnotationGenerator = class {
     }
     workflow.instances.forEach((instance) => {
       if (macroInstanceIds.has(instance.id)) return;
+      if (coerceInstanceIds.has(instance.id)) return;
       if (macroChildIds.has(instance.id) && instance.parent) {
         const stripped = { ...instance, parent: void 0 };
         lines.push(generateNodeInstanceTag(stripped));
@@ -30717,6 +30983,10 @@ var AnnotationGenerator = class {
           const srcs = macro.sources.map((s) => s.port ? `${s.node}.${s.port}` : s.node).join(", ");
           const tgt = `${macro.target.node}.${macro.target.port}`;
           lines.push(` * @fanIn ${srcs} -> ${tgt}`);
+        } else if (macro.type === "coerce") {
+          const src = `${macro.source.node}.${macro.source.port}`;
+          const tgt = `${macro.target.node}.${macro.target.port}`;
+          lines.push(` * @coerce ${macro.instanceId} ${src} -> ${tgt} as ${macro.targetType}`);
         }
       }
     }
@@ -30872,6 +31142,11 @@ function isConnectionCoveredByMacroStatic(conn, macros) {
           }
         }
       }
+    } else if (macro.type === "coerce") {
+      if (conn.from.scope || conn.to.scope) continue;
+      if (conn.to.node === macro.instanceId || conn.from.node === macro.instanceId) {
+        return true;
+      }
     }
   }
   return false;
@@ -31254,6 +31529,9 @@ function replaceWorkflowFunctionBody(source, functionName, newBody) {
     return { code: source, changed: false };
   }
   const closeBraceIdx = functionNode.body.end - 1;
+  if (closeBraceIdx <= openBraceIdx) {
+    return { code: source, changed: false };
+  }
   const before = source.slice(0, openBraceIdx + 1);
   const after = source.slice(closeBraceIdx);
   const newBodyWithMarkers = [
@@ -39792,17 +40070,17 @@ var CstVisitorDefinitionError;
   CstVisitorDefinitionError2[CstVisitorDefinitionError2["REDUNDANT_METHOD"] = 0] = "REDUNDANT_METHOD";
   CstVisitorDefinitionError2[CstVisitorDefinitionError2["MISSING_METHOD"] = 1] = "MISSING_METHOD";
 })(CstVisitorDefinitionError || (CstVisitorDefinitionError = {}));
-function validateVisitor(visitorInstance10, ruleNames) {
-  const missingErrors = validateMissingCstMethods(visitorInstance10, ruleNames);
+function validateVisitor(visitorInstance11, ruleNames) {
+  const missingErrors = validateMissingCstMethods(visitorInstance11, ruleNames);
   return missingErrors;
 }
-function validateMissingCstMethods(visitorInstance10, ruleNames) {
+function validateMissingCstMethods(visitorInstance11, ruleNames) {
   const missingRuleNames = filter_default(ruleNames, (currRuleName) => {
-    return isFunction_default(visitorInstance10[currRuleName]) === false;
+    return isFunction_default(visitorInstance11[currRuleName]) === false;
   });
   const errors2 = map_default(missingRuleNames, (currRuleName) => {
     return {
-      msg: `Missing visitor method: <${currRuleName}> on ${visitorInstance10.constructor.name} CST Visitor.`,
+      msg: `Missing visitor method: <${currRuleName}> on ${visitorInstance11.constructor.name} CST Visitor.`,
       type: CstVisitorDefinitionError.MISSING_METHOD,
       methodName: currRuleName
     };
@@ -41207,7 +41485,7 @@ var Parser = class _Parser {
   /**
    *  @deprecated use the **instance** method with the same name instead
    */
-  static performSelfAnalysis(parserInstance10) {
+  static performSelfAnalysis(parserInstance11) {
     throw Error("The **static** `performSelfAnalysis` method has been deprecated.	\nUse the **instance** method with the same name instead.");
   }
   performSelfAnalysis() {
@@ -41418,6 +41696,10 @@ var FanInTag = createToken({
   name: "FanInTag",
   pattern: /@fanIn\b/
 });
+var CoerceTag = createToken({
+  name: "CoerceTag",
+  pattern: /@coerce\b/
+});
 var TriggerTag = createToken({
   name: "TriggerTag",
   pattern: /@trigger\b/
@@ -41442,6 +41724,10 @@ var OverKeyword = createToken({
   name: "OverKeyword",
   pattern: /over\b/
 });
+var AsKeyword = createToken({
+  name: "AsKeyword",
+  pattern: /as\b/
+});
 var ParamTag = createToken({
   name: "ParamTag",
   pattern: /@param\b/
@@ -41661,6 +41947,7 @@ var allTokens = [
   PathTag,
   FanOutTag,
   FanInTag,
+  CoerceTag,
   TriggerTag,
   CancelOnTag,
   RetriesTag,
@@ -41694,6 +41981,7 @@ var allTokens = [
   PeriodEq,
   // Keywords (before Identifier)
   OverKeyword,
+  AsKeyword,
   MinimizedKeyword,
   TopKeyword,
   BottomKeyword,
@@ -41870,6 +42158,7 @@ var PortParser = class extends CstParser {
         { ALT: () => this.CONSUME(Asterisk) },
         // Keywords that can appear in description text
         { ALT: () => this.CONSUME(OverKeyword) },
+        { ALT: () => this.CONSUME(AsKeyword) },
         { ALT: () => this.CONSUME(TopKeyword) },
         { ALT: () => this.CONSUME(BottomKeyword) },
         { ALT: () => this.CONSUME(TrueKeyword) },
@@ -43021,6 +43310,77 @@ function getFanGrammar() {
   return parserInstance8.getSerializedGastProductions();
 }
 
+// src/chevrotain-parser/coerce-parser.ts
+var VALID_COERCE_TYPES = /* @__PURE__ */ new Set(["string", "number", "boolean", "json", "object"]);
+var CoerceParser = class extends CstParser {
+  constructor() {
+    super(allTokens);
+    this.performSelfAnalysis();
+  }
+  // @coerce Identifier portRef Arrow portRef AsKeyword Identifier
+  coerceLine = this.RULE("coerceLine", () => {
+    this.CONSUME(CoerceTag);
+    this.CONSUME(Identifier, { LABEL: "instanceId" });
+    this.SUBRULE(this.portRef, { LABEL: "source" });
+    this.CONSUME(Arrow);
+    this.SUBRULE2(this.portRef, { LABEL: "target" });
+    this.CONSUME(AsKeyword);
+    this.CONSUME2(Identifier, { LABEL: "typeName" });
+  });
+  // portRef: Identifier Dot Identifier
+  portRef = this.RULE("portRef", () => {
+    this.CONSUME(Identifier, { LABEL: "nodeName" });
+    this.CONSUME(Dot);
+    this.CONSUME2(Identifier, { LABEL: "portName" });
+  });
+};
+var parserInstance9 = new CoerceParser();
+var BaseVisitor9 = parserInstance9.getBaseCstVisitorConstructor();
+var CoerceVisitor = class extends BaseVisitor9 {
+  constructor() {
+    super();
+    this.validateVisitor();
+  }
+  coerceLine(ctx) {
+    const instanceId = ctx.instanceId[0].image;
+    const source = this.portRef(ctx.source[0].children);
+    const target = this.portRef(ctx.target[0].children);
+    const targetType = ctx.typeName[0].image;
+    return { instanceId, source, target, targetType };
+  }
+  portRef(ctx) {
+    return {
+      node: ctx.nodeName[0].image,
+      port: ctx.portName[0].image
+    };
+  }
+};
+var visitorInstance9 = new CoerceVisitor();
+function parseCoerceLine(input, warnings) {
+  const lexResult = JSDocLexer.tokenize(input);
+  if (lexResult.errors.length > 0 || lexResult.tokens.length === 0) return null;
+  if (lexResult.tokens[0].tokenType !== CoerceTag) return null;
+  parserInstance9.input = lexResult.tokens;
+  const cst = parserInstance9.coerceLine();
+  if (parserInstance9.errors.length > 0) {
+    const truncatedInput = input.length > 80 ? input.substring(0, 80) + "..." : input;
+    warnings.push(
+      `Failed to parse @coerce line: "${truncatedInput}"
+  Error: ${parserInstance9.errors[0].message}
+  Expected format: @coerce instanceId source.port -> target.port as type`
+    );
+    return null;
+  }
+  const result = visitorInstance9.visit(cst);
+  if (!VALID_COERCE_TYPES.has(result.targetType)) {
+    warnings.push(
+      `@coerce: invalid target type "${result.targetType}". Valid types: ${[...VALID_COERCE_TYPES].join(", ")}`
+    );
+    return null;
+  }
+  return result;
+}
+
 // src/chevrotain-parser/trigger-cancel-parser.ts
 function stripQuotes(s) {
   if (s.startsWith('"') && s.endsWith('"')) {
@@ -43085,9 +43445,9 @@ var TriggerCancelParser = class extends CstParser {
     });
   });
 };
-var parserInstance9 = new TriggerCancelParser();
-var BaseVisitor9 = parserInstance9.getBaseCstVisitorConstructor();
-var TriggerCancelVisitor = class extends BaseVisitor9 {
+var parserInstance10 = new TriggerCancelParser();
+var BaseVisitor10 = parserInstance10.getBaseCstVisitorConstructor();
+var TriggerCancelVisitor = class extends BaseVisitor10 {
   constructor() {
     super();
     this.validateVisitor();
@@ -43130,7 +43490,7 @@ var TriggerCancelVisitor = class extends BaseVisitor9 {
     return result;
   }
 };
-var visitorInstance9 = new TriggerCancelVisitor();
+var visitorInstance10 = new TriggerCancelVisitor();
 function parseTriggerLine(input, warnings) {
   const lexResult = JSDocLexer.tokenize(input);
   if (lexResult.errors.length > 0) {
@@ -43143,10 +43503,10 @@ function parseTriggerLine(input, warnings) {
   if (firstToken.tokenType !== TriggerTag) {
     return null;
   }
-  parserInstance9.input = lexResult.tokens;
-  const cst = parserInstance9.triggerLine();
-  if (parserInstance9.errors.length > 0) {
-    const firstError = parserInstance9.errors[0];
+  parserInstance10.input = lexResult.tokens;
+  const cst = parserInstance10.triggerLine();
+  if (parserInstance10.errors.length > 0) {
+    const firstError = parserInstance10.errors[0];
     const truncatedInput = input.length > 60 ? input.substring(0, 60) + "..." : input;
     warnings.push(
       `Failed to parse trigger line: "${truncatedInput}"
@@ -43155,7 +43515,7 @@ function parseTriggerLine(input, warnings) {
     );
     return null;
   }
-  const result = visitorInstance9.visit(cst);
+  const result = visitorInstance10.visit(cst);
   if (result.cron && !CRON_REGEX.test(result.cron)) {
     warnings.push(`Invalid cron expression: "${result.cron}". Expected 5 fields (minute hour day month weekday).`);
   }
@@ -43173,10 +43533,10 @@ function parseCancelOnLine(input, warnings) {
   if (firstToken.tokenType !== CancelOnTag) {
     return null;
   }
-  parserInstance9.input = lexResult.tokens;
-  const cst = parserInstance9.cancelOnLine();
-  if (parserInstance9.errors.length > 0) {
-    const firstError = parserInstance9.errors[0];
+  parserInstance10.input = lexResult.tokens;
+  const cst = parserInstance10.cancelOnLine();
+  if (parserInstance10.errors.length > 0) {
+    const firstError = parserInstance10.errors[0];
     const truncatedInput = input.length > 60 ? input.substring(0, 60) + "..." : input;
     warnings.push(
       `Failed to parse cancelOn line: "${truncatedInput}"
@@ -43185,10 +43545,10 @@ function parseCancelOnLine(input, warnings) {
     );
     return null;
   }
-  return visitorInstance9.visit(cst);
+  return visitorInstance10.visit(cst);
 }
 function getTriggerCancelGrammar() {
-  return parserInstance9.getSerializedGastProductions();
+  return parserInstance10.getSerializedGastProductions();
 }
 function parseThrottleLine(input, warnings) {
   const lexResult = JSDocLexer.tokenize(input);
@@ -43202,10 +43562,10 @@ function parseThrottleLine(input, warnings) {
   if (firstToken.tokenType !== ThrottleTag) {
     return null;
   }
-  parserInstance9.input = lexResult.tokens;
-  const cst = parserInstance9.throttleLine();
-  if (parserInstance9.errors.length > 0) {
-    const firstError = parserInstance9.errors[0];
+  parserInstance10.input = lexResult.tokens;
+  const cst = parserInstance10.throttleLine();
+  if (parserInstance10.errors.length > 0) {
+    const firstError = parserInstance10.errors[0];
     const truncatedInput = input.length > 60 ? input.substring(0, 60) + "..." : input;
     warnings.push(
       `Failed to parse throttle line: "${truncatedInput}"
@@ -43214,7 +43574,7 @@ function parseThrottleLine(input, warnings) {
     );
     return null;
   }
-  return visitorInstance9.visit(cst);
+  return visitorInstance10.visit(cst);
 }
 
 // src/chevrotain-parser/grammar-diagrams.ts
@@ -43632,6 +43992,9 @@ var JSDocParser = class {
         case "fanIn":
           this.parseFanInTag(tag, config2, warnings);
           break;
+        case "coerce":
+          this.parseCoerceTag(tag, config2, warnings);
+          break;
         case "trigger":
           this.parseTriggerTag(tag, config2, warnings);
           break;
@@ -44229,6 +44592,21 @@ var JSDocParser = class {
       target: { node: result.target.node, port: result.target.port }
     });
   }
+  parseCoerceTag(tag, config2, warnings) {
+    const comment = tag.getCommentText() || "";
+    const result = parseCoerceLine(`@coerce ${comment}`, warnings);
+    if (!result) {
+      warnings.push(`Invalid @coerce tag format: ${comment}`);
+      return;
+    }
+    config2.coercions = config2.coercions || [];
+    config2.coercions.push({
+      instanceId: result.instanceId,
+      source: result.source,
+      target: result.target,
+      targetType: result.targetType
+    });
+  }
   /**
    * Parse @trigger tag using Chevrotain parser.
    */
@@ -44484,6 +44862,49 @@ var LRUCache2 = class {
   }
 };
 
+// src/built-in-nodes/coercion-types.ts
+var COERCE_TYPE_MAP = {
+  string: "__fw_toString",
+  number: "__fw_toNumber",
+  boolean: "__fw_toBoolean",
+  json: "__fw_toJSON",
+  object: "__fw_parseJSON"
+};
+function makeCoercionNodeType(name, outputType, outputTsType) {
+  return {
+    type: "NodeType",
+    name,
+    functionName: name,
+    expression: true,
+    isAsync: false,
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    executeWhen: "CONJUNCTION",
+    variant: "COERCION",
+    inputs: {
+      execute: { dataType: "STEP", label: "Execute" },
+      value: { dataType: "ANY", label: "Value", tsType: "unknown" }
+    },
+    outputs: {
+      onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+      onFailure: { dataType: "STEP", label: "On Failure", failure: true, isControlFlow: true },
+      result: { dataType: outputType, label: "Result", tsType: outputTsType }
+    },
+    visuals: {
+      color: "#0d9488",
+      icon: "transform",
+      tags: [{ label: "coerce" }]
+    }
+  };
+}
+var COERCION_NODE_TYPES = {
+  __fw_toString: makeCoercionNodeType("__fw_toString", "STRING", "string"),
+  __fw_toNumber: makeCoercionNodeType("__fw_toNumber", "NUMBER", "number"),
+  __fw_toBoolean: makeCoercionNodeType("__fw_toBoolean", "BOOLEAN", "boolean"),
+  __fw_toJSON: makeCoercionNodeType("__fw_toJSON", "STRING", "string"),
+  __fw_parseJSON: makeCoercionNodeType("__fw_parseJSON", "OBJECT", "object")
+};
+
 // src/parser.ts
 function externalToAST(ext2) {
   const inputs = {};
@@ -45314,9 +45735,19 @@ ${fn.getText()}` : fn.getText();
       if (config2.fanIns && config2.fanIns.length > 0) {
         this.expandFanInMacros(config2.fanIns, instances, connections, startPorts, exitPorts, macros, errors2);
       }
+      if (config2.coercions && config2.coercions.length > 0) {
+        this.expandCoerceMacros(config2.coercions, instances, connections, startPorts, exitPorts, macros, errors2);
+      }
       const importedNames = new Set(importedNpmNodeTypes.map((nt) => nt.name));
       const dedupedAvailableTypes = allAvailableNodeTypes.filter((nt) => !importedNames.has(nt.name));
       const workflowNodeTypes = [...dedupedAvailableTypes, ...importedNpmNodeTypes];
+      for (const inst of instances) {
+        if (inst.nodeType.startsWith("__fw_") && COERCION_NODE_TYPES[inst.nodeType]) {
+          if (!workflowNodeTypes.some((nt) => nt.functionName === inst.nodeType)) {
+            workflowNodeTypes.push(COERCION_NODE_TYPES[inst.nodeType]);
+          }
+        }
+      }
       const ui = {};
       const startPosition = config2.positions?.["Start"];
       if (startPosition) {
@@ -45922,6 +46353,57 @@ ${fn.getText()}` : fn.getText();
       });
     }
   }
+  /**
+   * Expand @coerce macros into synthetic coercion node instances + connections.
+   */
+  expandCoerceMacros(coerceConfigs, instances, connections, startPorts, exitPorts, macros, errors2) {
+    const instanceIds = new Set(instances.map((i) => i.id));
+    instanceIds.add("Start");
+    instanceIds.add("Exit");
+    for (const config2 of coerceConfigs) {
+      const { instanceId, source, target, targetType } = config2;
+      if (!instanceIds.has(source.node)) {
+        errors2.push(`@coerce: source node "${source.node}" does not exist`);
+        continue;
+      }
+      if (!instanceIds.has(target.node)) {
+        errors2.push(`@coerce: target node "${target.node}" does not exist`);
+        continue;
+      }
+      if (instanceIds.has(instanceId)) {
+        errors2.push(`@coerce: instance ID "${instanceId}" already exists`);
+        continue;
+      }
+      const nodeTypeName = COERCE_TYPE_MAP[targetType];
+      if (!nodeTypeName) {
+        errors2.push(`@coerce: unknown target type "${targetType}"`);
+        continue;
+      }
+      instances.push({
+        type: "NodeInstance",
+        id: instanceId,
+        nodeType: nodeTypeName
+      });
+      instanceIds.add(instanceId);
+      connections.push({
+        type: "Connection",
+        from: { node: source.node, port: source.port },
+        to: { node: instanceId, port: "value" }
+      });
+      connections.push({
+        type: "Connection",
+        from: { node: instanceId, port: "result" },
+        to: { node: target.node, port: target.port }
+      });
+      macros.push({
+        type: "coerce",
+        instanceId,
+        source: { node: source.node, port: source.port },
+        target: { node: target.node, port: target.port },
+        targetType
+      });
+    }
+  }
   /**
    * Generate automatic connections for @autoConnect workflows.
    * Wires nodes in declaration order as a linear pipeline:
@@ -52545,12 +53027,31 @@ function extractQuoted(message) {
   return matches ? matches.map((m) => m.replace(/"/g, "")) : [];
 }
 function extractTypes(message) {
+  const structuralMatch = message.match(/from (.+?) \(\w+\) to (.+?) \(\w+\)/);
+  if (structuralMatch) return { source: structuralMatch[1], target: structuralMatch[2] };
   const fromToMatch = message.match(/from (\w+) to (\w+)/i);
   if (fromToMatch) return { source: fromToMatch[1], target: fromToMatch[2] };
+  const structuralParenMatch = message.match(/\((.+?) \(\w+\)\) .* \((.+?) \(\w+\)\)/);
+  if (structuralParenMatch) return { source: structuralParenMatch[1], target: structuralParenMatch[2] };
   const parenMatch = message.match(/\((\w+)\) .* \((\w+)\)/);
   if (parenMatch) return { source: parenMatch[1], target: parenMatch[2] };
   return null;
 }
+var COERCE_TARGET_TYPES = {
+  STRING: "string",
+  NUMBER: "number",
+  BOOLEAN: "boolean",
+  OBJECT: "object"
+};
+function buildCoerceSuggestion(quoted, targetType) {
+  if (quoted.length < 2) return null;
+  const portRefPattern = /^[\w]+\.[\w]+$/;
+  const portRefs = quoted.filter((q) => portRefPattern.test(q));
+  if (portRefs.length < 2) return null;
+  const coerceType = COERCE_TARGET_TYPES[targetType.toUpperCase()] || targetType.toLowerCase();
+  if (!["string", "number", "boolean", "json", "object"].includes(coerceType)) return null;
+  return `@coerce c1 ${portRefs[0]} -> ${portRefs[1]} as ${coerceType}`;
+}
 function extractCyclePath(message) {
   const match2 = message.match(/:\s*(.+ -> .+)/);
   return match2 ? match2[1] : null;
@@ -52653,10 +53154,12 @@ var errorMappers = {
     const types2 = extractTypes(error2.message);
     const source = types2?.source || "unknown";
     const target = types2?.target || "unknown";
+    const quoted = extractQuoted(error2.message);
+    const coerceSuggestion = buildCoerceSuggestion(quoted, target);
     return {
       title: "Type Mismatch",
       explanation: `Type mismatch: you're connecting a ${source} to a ${target}. The value will be automatically converted, but this might cause unexpected behavior.`,
-      fix: `Add a conversion node between the two ports, or change one of the port types to match. You can also use @strictTypes to turn this into an error.`,
+      fix: coerceSuggestion ? `Add an explicit coercion: \`${coerceSuggestion}\`, change one of the port types, or use @strictTypes to turn this into an error.` : `Add a @coerce annotation between the two ports, change one of the port types, or use @strictTypes to turn this into an error.`,
       code: error2.code
     };
   },
@@ -52750,10 +53253,12 @@ var errorMappers = {
     const types2 = extractTypes(error2.message);
     const source = types2?.source || "unknown";
     const target = types2?.target || "unknown";
+    const quoted = extractQuoted(error2.message);
+    const coerceSuggestion = buildCoerceSuggestion(quoted, target);
     return {
       title: "Type Incompatible",
       explanation: `Type mismatch: ${source} to ${target}. With @strictTypes enabled, this is an error instead of a warning.`,
-      fix: `Add a conversion node between the ports, change one of the port types, or remove @strictTypes to allow implicit coercions.`,
+      fix: coerceSuggestion ? `Add an explicit coercion: \`${coerceSuggestion}\`, change one of the port types, or remove @strictTypes to allow implicit coercions.` : `Add a @coerce annotation between the ports, change one of the port types, or remove @strictTypes to allow implicit coercions.`,
       code: error2.code
     };
   },
@@ -52761,10 +53266,12 @@ var errorMappers = {
     const types2 = extractTypes(error2.message);
     const source = types2?.source || "unknown";
     const target = types2?.target || "unknown";
+    const quoted = extractQuoted(error2.message);
+    const coerceSuggestion = buildCoerceSuggestion(quoted, target);
     return {
       title: "Unusual Type Coercion",
       explanation: `Converting ${source} to ${target} is technically valid but semantically unusual and may produce unexpected behavior.`,
-      fix: `Add an explicit conversion node if this is intentional, or use @strictTypes to enforce type safety.`,
+      fix: coerceSuggestion ? `If intentional, add an explicit coercion: \`${coerceSuggestion}\`, or use @strictTypes to enforce type safety.` : `If intentional, add an explicit @coerce annotation, or use @strictTypes to enforce type safety.`,
       code: error2.code
     };
   },
@@ -52789,6 +53296,82 @@ var errorMappers = {
       code: error2.code
     };
   },
+  SCOPE_MISSING_REQUIRED_INPUT(error2) {
+    const quoted = extractQuoted(error2.message);
+    const childId = quoted[0] || error2.node || "unknown";
+    const portName = quoted[1] || "unknown";
+    const scopeName = quoted[2] || "unknown";
+    const parentId = quoted[3] || "unknown";
+    return {
+      title: "Scope Child Missing Input",
+      explanation: `Child node '${childId}' inside scope '${scopeName}' of '${parentId}' has a required input '${portName}' with no connection.`,
+      fix: `Connect the parent's scoped output to '${childId}.${portName}' within the scope, or mark the port as optional.`,
+      code: error2.code
+    };
+  },
+  SCOPE_UNUSED_INPUT(error2) {
+    const quoted = extractQuoted(error2.message);
+    const portName = quoted[0] || "unknown";
+    const parentId = quoted[1] || error2.node || "unknown";
+    const scopeName = quoted[2] || "unknown";
+    return {
+      title: "Scope Input Unused",
+      explanation: `Scoped input '${portName}' on '${parentId}' expects data back from inner nodes, but nothing connects to it within scope '${scopeName}'.`,
+      fix: `Connect an inner node's output to '${parentId}.${portName}:${scopeName}' to return data from the scope.`,
+      code: error2.code
+    };
+  },
+  SCOPE_WRONG_SCOPE_NAME(error2) {
+    const quoted = extractQuoted(error2.message);
+    const portRef = quoted[0] || "unknown";
+    const nodeName = quoted[2] || "unknown";
+    return {
+      title: "Invalid Scope Qualifier",
+      explanation: `A connection at '${portRef}' uses an invalid scope name. Node '${nodeName}' doesn't define that scope.`,
+      fix: `Check the scope names defined on the node type. Fix the :scopeName qualifier in the @connect annotation to match an existing scope.`,
+      code: error2.code
+    };
+  },
+  SCOPE_CONNECTION_OUTSIDE(error2) {
+    const quoted = extractQuoted(error2.message);
+    return {
+      title: "Scope Connection Leak",
+      explanation: `A scoped connection references a node that is outside the scope boundary. Scoped connections must stay within the scope.`,
+      fix: `Move the target node inside the scope (declare it with the scope parent in @node), or remove the scope qualifier from the connection.`,
+      code: error2.code
+    };
+  },
+  SCOPE_PORT_TYPE_MISMATCH(error2) {
+    const quoted = extractQuoted(error2.message);
+    return {
+      title: "Scope Port Type Mismatch",
+      explanation: `Type mismatch within scope '${quoted[0] || "unknown"}'. The parent's scoped port and the child's port have incompatible types.`,
+      fix: `Change one of the port types to match, or add a transformation node inside the scope.`,
+      code: error2.code
+    };
+  },
+  SCOPE_UNKNOWN_PORT(error2) {
+    const quoted = extractQuoted(error2.message);
+    const portName = quoted[0] || "unknown";
+    return {
+      title: "Unknown Scoped Port",
+      explanation: `Port '${portName}' is referenced in a scoped connection but doesn't exist as a scoped port on that node, or belongs to a different scope.`,
+      fix: `Add the port as a scoped port with @output ${portName} scope:scopeName, or fix the port name in the @connect annotation.`,
+      code: error2.code
+    };
+  },
+  SCOPE_ORPHANED_CHILD(error2) {
+    const quoted = extractQuoted(error2.message);
+    const childId = quoted[0] || error2.node || "unknown";
+    const scopeName = quoted[1] || "unknown";
+    const parentId = quoted[2] || "unknown";
+    return {
+      title: "Orphaned Scope Child",
+      explanation: `Node '${childId}' is declared inside scope '${scopeName}' of '${parentId}' but has no scoped connections. It won't receive data from or return data to the scope.`,
+      fix: `Connect the parent's scoped output ports to '${childId}' inputs, and connect '${childId}' outputs back to the parent's scoped input ports.`,
+      code: error2.code
+    };
+  },
   OBJECT_TYPE_MISMATCH(error2) {
     const quoted = extractQuoted(error2.message);
     const sourceType = quoted[0] || "unknown";
@@ -52917,10 +53500,12 @@ var errorMappers = {
     const types2 = extractTypes(error2.message);
     const source = types2?.source || "unknown";
     const target = types2?.target || "unknown";
+    const quoted = extractQuoted(error2.message);
+    const coerceSuggestion = buildCoerceSuggestion(quoted, target);
     return {
       title: "Lossy Type Conversion",
       explanation: `Converting ${source} to ${target} may lose data or produce unexpected results (e.g., NaN, truncation).`,
-      fix: `Add an explicit conversion node, or use @strictTypes on the workflow to enforce type safety and catch these at validation time.`,
+      fix: coerceSuggestion ? `Add an explicit coercion: \`${coerceSuggestion}\`, or use @strictTypes to enforce type safety.` : `Add an explicit conversion with @coerce, or use @strictTypes to enforce type safety.`,
       code: error2.code
     };
   },
@@ -56397,6 +56982,18 @@ ${indent}});`;
 function generateExpressionCall(instanceId, nodeType, workflow, nodeTypes, indent) {
   const args = buildNodeArgs(instanceId, nodeType, workflow, nodeTypes);
   const safeId = toValidIdentifier(instanceId);
+  if (nodeType.variant === "COERCION") {
+    const coerceExprMap = {
+      __fw_toString: "String",
+      __fw_toNumber: "Number",
+      __fw_toBoolean: "Boolean",
+      __fw_toJSON: "JSON.stringify",
+      __fw_parseJSON: "JSON.parse"
+    };
+    const coerceExpr = coerceExprMap[nodeType.functionName] || "String";
+    const valueArg = args[0] || "undefined";
+    return `${indent}${safeId}_result = ${coerceExpr}(${valueArg});`;
+  }
   const fnCall = `${nodeType.functionName}(${args.join(", ")})`;
   const awaitPrefix = nodeType.isAsync ? "await " : "";
   return `${indent}${safeId}_result = ${awaitPrefix}${fnCall};`;
@@ -56605,6 +57202,18 @@ function emitPromiseAll(nodeIds, workflow, nodeTypes, indent, lines, generatedNo
       if (timeoutArg && timeoutArg !== "undefined") invokeCall += `, timeout: ${timeoutArg}`;
       invokeCall += ` })`;
       stepCalls.push(invokeCall);
+    } else if (nt.variant === "COERCION") {
+      const coerceExprMap = {
+        __fw_toString: "String",
+        __fw_toNumber: "Number",
+        __fw_toBoolean: "Boolean",
+        __fw_toJSON: "JSON.stringify",
+        __fw_parseJSON: "JSON.parse"
+      };
+      const coerceExpr = coerceExprMap[nt.functionName] || "String";
+      const args = buildNodeArgs(nodeId, nt, workflow, nodeTypes);
+      const valueArg = args[0] || "undefined";
+      stepCalls.push(`${indent}  Promise.resolve(${coerceExpr}(${valueArg}))`);
     } else if (nt.expression) {
       const args = buildNodeArgs(nodeId, nt, workflow, nodeTypes);
       const fnCall = `${nt.functionName}(${args.join(", ")})`;
@@ -57352,12 +57961,18 @@ async function compileCommand(input, options = {}) {
                 const loc = err.location ? `[line ${err.location.line}] ` : "";
                 logger.error(`  ${loc}${friendly.title}: ${friendly.explanation}`);
                 logger.info(`    How to fix: ${friendly.fix}`);
+                if (err.docUrl) {
+                  logger.info(`    See: ${err.docUrl}`);
+                }
               } else {
                 let msg = `  - ${err.message}`;
                 if (err.node) {
                   msg += ` (node: ${err.node})`;
                 }
                 logger.error(msg);
+                if (err.docUrl) {
+                  logger.info(`    See: ${err.docUrl}`);
+                }
               }
             });
             errorCount++;
@@ -61443,6 +62058,9 @@ async function validateCommand(input, options = {}) {
                 const loc = err.location ? `[line ${err.location.line}] ` : "";
                 logger.error(`  ${loc}${friendly.title}: ${friendly.explanation}`);
                 logger.info(`    How to fix: ${friendly.fix}`);
+                if (err.docUrl) {
+                  logger.info(`    See: ${err.docUrl}`);
+                }
               } else {
                 let msg = `  - ${err.message}`;
                 if (err.location) {
@@ -61455,6 +62073,9 @@ async function validateCommand(input, options = {}) {
                   msg += ` (connection: ${err.connection.from.node}:${err.connection.from.port} -> ${err.connection.to.node}:${err.connection.to.port})`;
                 }
                 logger.error(msg);
+                if (err.docUrl) {
+                  logger.info(`    See: ${err.docUrl}`);
+                }
               }
             });
           }
@@ -61469,6 +62090,9 @@ async function validateCommand(input, options = {}) {
                 const loc = warn.location ? `[line ${warn.location.line}] ` : "";
                 logger.warn(`  ${loc}${friendly.title}: ${friendly.explanation}`);
                 logger.info(`    How to fix: ${friendly.fix}`);
+                if (warn.docUrl) {
+                  logger.info(`    See: ${warn.docUrl}`);
+                }
               } else {
                 let msg = `  - ${warn.message}`;
                 if (warn.location) {
@@ -61478,6 +62102,9 @@ async function validateCommand(input, options = {}) {
                   msg += ` (node: ${warn.node})`;
                 }
                 logger.warn(msg);
+                if (warn.docUrl) {
+                  logger.info(`    See: ${warn.docUrl}`);
+                }
               }
             });
           }
@@ -64783,13 +65410,16 @@ function generateProjectFiles(projectName, template, format = "esm") {
   const gitignore = `node_modules/
 dist/
 .tsbuildinfo
+`;
+  const configYaml = `defaultFileType: ts
 `;
   return {
     "package.json": packageJson,
     "tsconfig.json": tsconfigJson,
     [`src/${workflowFile}`]: workflowCode,
     "src/main.ts": mainTs,
-    ".gitignore": gitignore
+    ".gitignore": gitignore,
+    ".flowweaver/config.yaml": configYaml
   };
 }
 function scaffoldProject(targetDir, files, options) {
@@ -64989,22 +65619,19 @@ async function watchCommand(input, options = {}) {
 init_esm5();
 import * as path19 from "path";
 import * as fs18 from "fs";
-import * as os2 from "os";
+import * as os from "os";
 import { spawn } from "child_process";
 
 // src/mcp/workflow-executor.ts
 import * as path18 from "path";
 import * as fs17 from "fs";
-import * as os from "os";
 import { pathToFileURL } from "url";
 import ts4 from "typescript";
 async function executeWorkflowFromFile(filePath, params, options) {
   const resolvedPath = path18.resolve(filePath);
   const includeTrace = options?.includeTrace !== false;
-  const tmpBase = path18.join(
-    os.tmpdir(),
-    `fw-exec-${Date.now()}-${Math.random().toString(36).slice(2)}`
-  );
+  const tmpId = `fw-exec-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const tmpBase = path18.join(path18.dirname(resolvedPath), tmpId);
   const tmpTsFile = `${tmpBase}.ts`;
   const tmpFile = `${tmpBase}.mjs`;
   try {
@@ -65035,11 +65662,13 @@ async function executeWorkflowFromFile(filePath, params, options) {
     const trace = [];
     const debugger_ = includeTrace ? {
       sendEvent: (event) => {
-        trace.push({
+        const traceEvent = {
           type: event.type || "UNKNOWN",
           timestamp: Date.now(),
           data: event
-        });
+        };
+        trace.push(traceEvent);
+        options?.onEvent?.(traceEvent);
       },
       innerFlowInvocation: false
     } : void 0;
@@ -65298,7 +65927,7 @@ async function runInngestDevMode(filePath, options) {
   if (missingDeps.length > 0) {
     throw new Error(`Missing dependencies: ${missingDeps.join(", ")}. Install them with: npm install ${missingDeps.join(" ")}`);
   }
-  const tmpDir = fs18.mkdtempSync(path19.join(os2.tmpdir(), "fw-inngest-dev-"));
+  const tmpDir = fs18.mkdtempSync(path19.join(os.tmpdir(), "fw-inngest-dev-"));
   const inngestOutputPath = path19.join(tmpDir, path19.basename(filePath).replace(/\.ts$/, ".inngest.ts"));
   let serverProcess = null;
   const compileInngest = async () => {
@@ -83673,15 +84302,30 @@ function registerEditorTools(mcp, connection, buffer) {
       params: external_exports.record(external_exports.unknown()).optional().describe("Optional execution parameters"),
       includeTrace: external_exports.boolean().optional().describe("Include execution trace events (default: true)")
     },
-    async (args) => {
+    async (args, extra) => {
       if (args.filePath) {
         try {
           const channel = new AgentChannel();
           const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+          const progressToken = extra._meta?.progressToken;
+          let eventCount = 0;
+          const onEvent = progressToken ? (event) => {
+            eventCount++;
+            extra.sendNotification({
+              method: "notifications/progress",
+              params: {
+                progressToken,
+                progress: eventCount,
+                message: event.type === "STATUS_CHANGED" ? `${event.data?.id ?? ""}: ${event.data?.status ?? ""}` : event.type
+              }
+            }).catch(() => {
+            });
+          } : void 0;
           const execPromise = executeWorkflowFromFile(args.filePath, args.params, {
             workflowName: args.workflowName,
             includeTrace: args.includeTrace,
-            agentChannel: channel
+            agentChannel: channel,
+            onEvent
           });
           const raceResult = await Promise.race([
             execPromise.then((r) => ({ type: "completed", result: r })),
@@ -91637,6 +92281,9 @@ async function runCommand(input, options) {
       throw new Error(`Failed to parse mocks file: ${options.mocksFile}`);
     }
   }
+  if (mocks && !options.json) {
+    await validateMockConfig(mocks, filePath, options.workflow);
+  }
   let timeoutId;
   let timedOut = false;
   if (options.timeout) {
@@ -91649,17 +92296,40 @@ async function runCommand(input, options) {
     }, options.timeout);
   }
   try {
-    const includeTrace = options.trace ?? !options.production;
+    const includeTrace = options.stream || options.trace || !options.production;
     if (!options.json && mocks) {
       logger.info("Running with mock data");
     }
+    const nodeStartTimes = /* @__PURE__ */ new Map();
+    const onEvent = options.stream && !options.json ? (event) => {
+      if (event.type === "STATUS_CHANGED" && event.data) {
+        const nodeId = event.data.id;
+        const status = event.data.status;
+        if (!nodeId || !status) return;
+        if (status === "RUNNING") {
+          nodeStartTimes.set(nodeId, event.timestamp);
+          logger.log(`  [STATUS_CHANGED] ${nodeId}: \u2192 RUNNING`);
+        } else {
+          const startTime = nodeStartTimes.get(nodeId);
+          const duration3 = startTime ? ` (${event.timestamp - startTime}ms)` : "";
+          logger.log(`  [STATUS_CHANGED] ${nodeId}: \u2192 ${status}${duration3}`);
+        }
+      } else if (event.type === "VARIABLE_SET" && event.data) {
+        const nodeId = event.data.nodeId;
+        const varName = event.data.name;
+        if (nodeId && varName) {
+          logger.log(`  [VARIABLE_SET] ${nodeId}.${varName}`);
+        }
+      }
+    } : void 0;
     const channel = new AgentChannel();
     const execPromise = executeWorkflowFromFile(filePath, params, {
       workflowName: options.workflow,
       production: options.production ?? false,
       includeTrace,
       mocks,
-      agentChannel: channel
+      agentChannel: channel,
+      onEvent
     });
     let result;
     let execDone = false;
@@ -91768,6 +92438,35 @@ async function runCommand(input, options) {
     }
   }
 }
+var VALID_MOCK_KEYS = /* @__PURE__ */ new Set(["events", "invocations", "agents", "fast"]);
+var MOCK_SECTION_TO_NODE = {
+  events: "waitForEvent",
+  invocations: "invokeWorkflow",
+  agents: "waitForAgent"
+};
+async function validateMockConfig(mocks, filePath, workflowName) {
+  for (const key of Object.keys(mocks)) {
+    if (!VALID_MOCK_KEYS.has(key)) {
+      logger.warn(`Mock config has unknown key "${key}". Valid keys: ${[...VALID_MOCK_KEYS].join(", ")}`);
+    }
+  }
+  try {
+    const result = await parseWorkflow(filePath, { workflowName });
+    if (result.errors.length > 0 || !result.ast?.instances) return;
+    const usedNodeTypes = new Set(result.ast.instances.map((i) => i.nodeType));
+    for (const [section, nodeType] of Object.entries(MOCK_SECTION_TO_NODE)) {
+      const mockSection = mocks[section];
+      if (mockSection && typeof mockSection === "object" && Object.keys(mockSection).length > 0) {
+        if (!usedNodeTypes.has(nodeType)) {
+          logger.warn(
+            `Mock config has "${section}" entries but workflow has no ${nodeType} nodes`
+          );
+        }
+      }
+    }
+  } catch {
+  }
+}
 function promptForInput(question) {
   return new Promise((resolve27) => {
     const rl = readline9.createInterface({
@@ -92264,7 +92963,7 @@ async function serveCommand(dir, options) {
 // src/export/index.ts
 import * as path33 from "path";
 import * as fs32 from "fs";
-import * as os3 from "os";
+import * as os2 from "os";
 import { fileURLToPath as fileURLToPath5 } from "url";
 
 // src/export/templates.ts
@@ -92461,7 +93160,7 @@ async function exportMultiWorkflow(options) {
       throw new Error(`None of the requested workflows found. Available: ${available}`);
     }
   }
-  const workDir = isDryRun ? path33.join(os3.tmpdir(), `fw-export-multi-dryrun-${Date.now()}`) : outputDir;
+  const workDir = isDryRun ? path33.join(os2.tmpdir(), `fw-export-multi-dryrun-${Date.now()}`) : outputDir;
   fs32.mkdirSync(workDir, { recursive: true });
   fs32.mkdirSync(path33.join(workDir, "workflows"), { recursive: true });
   fs32.mkdirSync(path33.join(workDir, "runtime"), { recursive: true });
@@ -93185,7 +93884,7 @@ async function exportWorkflow(options) {
     const available = parseResult.workflows.map((w) => w.name).join(", ");
     throw new Error(`Workflow "${options.workflow}" not found. Available: ${available}`);
   }
-  const workDir = isDryRun ? path33.join(os3.tmpdir(), `fw-export-dryrun-${Date.now()}`) : outputDir;
+  const workDir = isDryRun ? path33.join(os2.tmpdir(), `fw-export-dryrun-${Date.now()}`) : outputDir;
   fs32.mkdirSync(workDir, { recursive: true });
   let compiledContent;
   let compiledPath;
@@ -94429,7 +95128,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.5.1" : "0.0.0-dev";
+var version2 = true ? "0.7.0" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").version(version2, "-v, --version", "Output the current version");
 program2.configureOutput({
@@ -94633,7 +95332,7 @@ patternCmd.command("extract <source-file>").description("Extract a pattern from
     process.exit(1);
   }
 });
-program2.command("run <input>").description("Execute a workflow file directly").option("-w, --workflow <name>", "Specific workflow name to run").option("--params <json>", "Input parameters as JSON string").option("--params-file <path>", "Path to JSON file with input parameters").option("-p, --production", "Production mode (no trace events)", false).option("-t, --trace", "Include execution trace events").option("--json", "Output result as JSON", false).option("--timeout <ms>", "Execution timeout in milliseconds", parseInt).option("--mocks <json>", "Mock config for built-in nodes (events, invocations, fast) as JSON").option("--mocks-file <path>", "Path to JSON file with mock config for built-in nodes").action(async (input, options) => {
+program2.command("run <input>").description("Execute a workflow file directly").option("-w, --workflow <name>", "Specific workflow name to run").option("--params <json>", "Input parameters as JSON string").option("--params-file <path>", "Path to JSON file with input parameters").option("-p, --production", "Production mode (no trace events)", false).option("-t, --trace", "Include execution trace events").option("-s, --stream", "Stream trace events in real-time").option("--json", "Output result as JSON", false).option("--timeout <ms>", "Execution timeout in milliseconds", parseInt).option("--mocks <json>", "Mock config for built-in nodes (events, invocations, fast) as JSON").option("--mocks-file <path>", "Path to JSON file with mock config for built-in nodes").action(async (input, options) => {
   try {
     await runCommand(input, options);
   } catch (error2) {