@synergenius/flow-weaver 0.8.2 → 0.8.3

package/dist/ast/types.d.ts

@@ -240,7 +240,7 @@ export type TNodeTypeAST = {
     /** Multiple scopes this node creates */
     scopes?: string[];
     /** Variant identifier (set by app layer) */
-    variant?: 'FUNCTION' | 'WORKFLOW' | 'IMPORTED_WORKFLOW' | 'MAP_ITERATOR' | 'COERCION';
+    variant?: 'FUNCTION' | 'WORKFLOW' | 'IMPORTED_WORKFLOW' | 'MAP_ITERATOR' | 'COERCION' | 'STUB';
     /** File path for external node types */
     path?: string;
     /** Function reference for function-based node types */

package/dist/cli/flow-weaver.mjs

@@ -32298,7 +32298,8 @@ function wrapFunctionDeclaration(fn) {
     getStartLineNumber: (inc) => fn.getStartLineNumber(inc),
     getText: (inc) => fn.getText(inc),
     getSourceFile: () => fn.getSourceFile(),
-    getTypeResolutionNode: () => fn
+    getTypeResolutionNode: () => fn,
+    isAmbient: () => !fn.hasBody()
   };
 }
 function extractFunctionLikes(sourceFile) {
@@ -43872,14 +43873,20 @@ var JSDocParser = class {
     if (jsdocs.length === 0) return null;
     let jsdoc = null;
     let flowWeaverTag = null;
+    let isNodeShorthand = false;
     for (const doc of jsdocs) {
       const tags2 = doc.getTags();
       const tag = tags2.find(
-        (t) => t.getTagName() === "flowWeaver" && t.getCommentText()?.trim() === "nodeType"
+        (t) => {
+          if (t.getTagName() !== "flowWeaver") return false;
+          const comment = t.getCommentText()?.trim();
+          return comment === "nodeType" || comment === "node";
+        }
       );
       if (tag) {
         jsdoc = doc;
         flowWeaverTag = tag;
+        isNodeShorthand = flowWeaverTag.getCommentText()?.trim() === "node";
         break;
       }
     }
@@ -43889,6 +43896,9 @@ var JSDocParser = class {
       inputs: {},
       outputs: {}
     };
+    if (isNodeShorthand) {
+      config2.expression = true;
+    }
     const descriptionText = jsdoc.getDescription();
     if (descriptionText && descriptionText.trim()) {
       config2.description = descriptionText.trim();
@@ -45475,6 +45485,10 @@ var AnnotationParser = class {
           };
         }
       }
+      const isStub = fn.isAmbient?.() ?? false;
+      if (isStub) {
+        config2.expression = true;
+      }
       if (config2.expression) {
         const hasExplicitDataInputs = Object.keys(inputs).some((k) => k !== "execute");
         const hasExplicitDataOutputs = Object.keys(outputs).some(
@@ -45534,7 +45548,7 @@ var AnnotationParser = class {
       assignImplicitPortOrders(outputs);
       const jsDocs = fn.getJsDocs();
       const jsDocText = jsDocs.map((doc) => doc.getText()).join("\n");
-      const functionText = jsDocText ? `${jsDocText}
+      const functionText = isStub ? void 0 : jsDocText ? `${jsDocText}
 ${fn.getText()}` : fn.getText();
       const isAsync2 = fn.isAsync();
       let defaultConfig = void 0;
@@ -45557,7 +45571,7 @@ ${fn.getText()}` : fn.getText();
         type: "NodeType",
         name: nodeTypeName,
         functionName,
-        variant: "FUNCTION",
+        variant: isStub ? "STUB" : "FUNCTION",
         inputs,
         outputs,
         hasSuccessPort: RESERVED_PORT_NAMES.ON_SUCCESS in outputs,
@@ -48562,7 +48576,7 @@ var configSchema = {
 };
 function generateDefaultTemplate(workflowName, asyncKeyword, returnType) {
   return `
-// Use @expression for pure functions, normal mode for branching
+// Use @expression for most functions, normal mode only for error-with-data or void side-effects
 
 /**
  * Validates input data
@@ -50298,7 +50312,7 @@ var aggregatorTemplate = {
     const asyncKeyword = isAsync2 ? "async " : "";
     const returnType = isAsync2 ? "Promise<{ onSuccess: boolean; onFailure: boolean; aggregated: any }>" : "{ onSuccess: boolean; onFailure: boolean; aggregated: any }";
     return `
-// Use @expression for pure functions, normal mode for branching
+// Use @expression for most functions, normal mode only for error-with-data or void side-effects
 
 /**
  * Fetches data from source A
@@ -95182,7 +95196,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.8.2" : "0.0.0-dev";
+var version2 = true ? "0.8.3" : "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({

package/dist/cli/templates/workflows/aggregator.js

@@ -14,7 +14,7 @@ export const aggregatorTemplate = {
             ? "Promise<{ onSuccess: boolean; onFailure: boolean; aggregated: any }>"
             : "{ onSuccess: boolean; onFailure: boolean; aggregated: any }";
         return `
-// Use @expression for pure functions, normal mode for branching
+// Use @expression for most functions, normal mode only for error-with-data or void side-effects
 
 /**
  * Fetches data from source A

package/dist/cli/templates/workflows/sequential.js

@@ -26,7 +26,7 @@ const configSchema = {
 };
 function generateDefaultTemplate(workflowName, asyncKeyword, returnType) {
     return `
-// Use @expression for pure functions, normal mode for branching
+// Use @expression for most functions, normal mode only for error-with-data or void side-effects
 
 /**
  * Validates input data

package/dist/function-like.d.ts

@@ -23,6 +23,8 @@ export interface FunctionLike {
     getDeclarationKind?(): 'const' | 'let' | 'var' | undefined;
     /** Returns the underlying ts-morph Node for type resolution (e.g., Symbol.getTypeAtLocation). */
     getTypeResolutionNode(): Node;
+    /** Whether this is an ambient declaration (declare function) with no implementation body. */
+    isAmbient?(): boolean;
 }
 /**
  * Scan a source file and return every function-like declaration that could

package/dist/function-like.js

@@ -17,6 +17,7 @@ function wrapFunctionDeclaration(fn) {
         getText: (inc) => fn.getText(inc),
         getSourceFile: () => fn.getSourceFile(),
         getTypeResolutionNode: () => fn,
+        isAmbient: () => !fn.hasBody(),
     };
 }
 /**

package/dist/jsdoc-parser.js

@@ -104,15 +104,22 @@ export class JSDocParser {
         const jsdocs = func.getJsDocs();
         if (jsdocs.length === 0)
             return null;
-        // Find the JSDoc block that contains @flowWeaver nodeType
+        // Find the JSDoc block that contains @flowWeaver nodeType (or @flowWeaver node shorthand)
         let jsdoc = null;
         let flowWeaverTag = null;
+        let isNodeShorthand = false;
         for (const doc of jsdocs) {
             const tags = doc.getTags();
-            const tag = tags.find((t) => t.getTagName() === 'flowWeaver' && t.getCommentText()?.trim() === 'nodeType');
+            const tag = tags.find((t) => {
+                if (t.getTagName() !== 'flowWeaver')
+                    return false;
+                const comment = t.getCommentText()?.trim();
+                return comment === 'nodeType' || comment === 'node';
+            });
             if (tag) {
                 jsdoc = doc;
                 flowWeaverTag = tag;
+                isNodeShorthand = flowWeaverTag.getCommentText()?.trim() === 'node';
                 break;
             }
         }
@@ -123,6 +130,10 @@ export class JSDocParser {
             inputs: {},
             outputs: {},
         };
+        // @flowWeaver node implies expression mode (auto-detect from signature)
+        if (isNodeShorthand) {
+            config.expression = true;
+        }
         // Extract description from JSDoc comment text (before tags)
         const descriptionText = jsdoc.getDescription();
         if (descriptionText && descriptionText.trim()) {

package/dist/parser.js

@@ -629,6 +629,12 @@ export class AnnotationParser {
                     };
                 }
             }
+            // Ambient declarations (declare function) are stub nodes — interface only, no implementation.
+            // Force expression mode so ports are inferred from the TypeScript signature.
+            const isStub = fn.isAmbient?.() ?? false;
+            if (isStub) {
+                config.expression = true;
+            }
             // Auto-infer ports for @expression nodes when @input/@output are missing.
             // If the function has @expression but no explicit port annotations, infer
             // data ports from the TypeScript function signature (same logic as unannotated functions).
@@ -679,11 +685,10 @@ export class AnnotationParser {
             // Assign implicit port orders with mandatory port precedence
             assignImplicitPortOrders(inputs);
             assignImplicitPortOrders(outputs);
-            // Get function text (JSDoc comment + function)
-            // getText() returns just the function, so we need to prepend the JSDoc
+            // Get function text (JSDoc comment + function). Stubs have no body to capture.
             const jsDocs = fn.getJsDocs();
             const jsDocText = jsDocs.map((doc) => doc.getText()).join('\n');
-            const functionText = jsDocText ? `${jsDocText}\n${fn.getText()}` : fn.getText();
+            const functionText = isStub ? undefined : (jsDocText ? `${jsDocText}\n${fn.getText()}` : fn.getText());
             // Detect async keyword on function declaration
             const isAsync = fn.isAsync();
             // Convert defaultConfig
@@ -718,7 +723,7 @@ export class AnnotationParser {
                 type: 'NodeType',
                 name: nodeTypeName,
                 functionName,
-                variant: 'FUNCTION',
+                variant: isStub ? 'STUB' : 'FUNCTION',
                 inputs,
                 outputs,
                 hasSuccessPort: RESERVED_PORT_NAMES.ON_SUCCESS in outputs,

package/docs/reference/concepts.md

@@ -137,7 +137,7 @@ Expression nodes are pure functions where:
   - Object return `{ a, b }` -> one port per property
 - Best for: transformers, math, utilities, data mapping, async fetchers, API calls
 
-> **Start with expression mode.** Only switch to normal mode when you need explicit branching (`onSuccess`/`onFailure` routing), custom error-with-data patterns, or void returns with side effects.
+> **Start with expression mode.** Only switch to normal mode when you need to return data alongside a failure (error-with-data patterns) or for void side-effect functions. Expression nodes handle success/failure branching automatically — throw to trigger the `onFailure` path.
 
 #### Async Expression Example
 
@@ -157,7 +157,7 @@ async function fetchUser(userId: string): Promise<User> {
 
 ### Node Type (Normal Mode)
 
-Use normal mode when you need explicit `try/catch -> onFailure` error handling or `void` returns.
+Use normal mode when you need to return error data alongside the failure signal, or for `void` side-effect functions.
 
 ```typescript
 /**
@@ -196,7 +196,7 @@ export function workflowName(
 }
 ```
 
-> STEP connections (`execute`, `onSuccess`, `onFailure`) are auto-wired for expression nodes in linear data flows. Add them explicitly only for branching or normal mode nodes.
+> STEP connections (`execute`, `onSuccess`, `onFailure`) are auto-wired for expression nodes. Add explicit STEP connections only for normal mode nodes or to override the automatic wiring.
 
 ### Importing External Functions
 

package/docs/reference/iterative-development.md

@@ -55,16 +55,15 @@ flow-weaver validate <file>
 
 ### Phase 3: Create the Nodes
 
-**Start with `@expression` mode for all nodes.** Only switch to normal mode when you need explicit branching (quality gates, conditional routing, error-with-data patterns).
+**Start with `@expression` mode for all nodes.** Only switch to normal mode when you need to return error data alongside the failure signal, or for void side-effects.
 
 Create nodes by adding `@flowWeaver nodeType` annotated functions.
 
 Create at most 3 nodes at a time, test each.
 
 Default to expression mode. Use normal mode only for:
-- **Quality gates** -- routing to different paths based on success/failure
-- **Conditional routing** -- explicit `onSuccess`/`onFailure` branching
-- **Error-with-data patterns** -- returning error details alongside the failure signal
+- **Error-with-data patterns** -- returning structured error details alongside the failure signal
+- **Void side-effects** -- functions with no return value that need explicit control flow
 
 **Expression mode (recommended for most nodes):**
 
@@ -82,7 +81,7 @@ function addNumbers(a: number, b: number): number {
 }
 ```
 
-> Use `@expression` for most nodes. Only use normal mode when you need custom failure handling or void returns.
+> Use `@expression` for most nodes. Expression nodes support failure branching via throw. Only use normal mode for error-with-data patterns or void returns.
 
 **Normal mode (for custom error handling):**
 
@@ -147,7 +146,7 @@ flow-weaver describe <file>  # Get workflow structure as JSON
 
 ### 1. Missing STEP Connections (Normal Mode) or Adding Unnecessary Ones (Expression Mode)
 
-**Normal mode nodes** need explicit STEP wiring: `@connect Start.execute -> firstNode.execute`. Without this, no node will run. **Expression mode** nodes auto-wire STEP connections from data flow -- you only need data connections for linear pipelines. Add explicit STEP connections only for branching (e.g., routing `onFailure` to a different node).
+**Normal mode nodes** need explicit STEP wiring: `@connect Start.execute -> firstNode.execute`. Without this, no node will run. **Expression mode** nodes auto-wire STEP connections from data flow -- you only need data connections for linear pipelines. Add explicit STEP connections when you need to route `onFailure` to a specific node (both expression and normal mode nodes support this).
 
 ### 2. Wrapping Node Inputs in Object
 
@@ -173,13 +172,13 @@ Always run `flow-weaver validate` after adding nodes/connections. Don't batch 10
 
 ### 6. Using Normal Mode When Expression Mode Works
 
-If the function returns a value and doesn't need custom error handling, use `@expression`. It's simpler and less error-prone. Expression mode eliminates the `execute` parameter, the `if (!execute)` guard, and the `onSuccess`/`onFailure` boilerplate. The compiler handles all of it.
+If the function returns a value, use `@expression`. It's simpler and less error-prone. Expression mode eliminates the `execute` parameter, the `if (!execute)` guard, and the `onSuccess`/`onFailure` boilerplate. The compiler wraps the call in try/catch, so throwing triggers the `onFailure` path automatically.
 
 **Rule of thumb:** If you are writing `if (!execute) return ...` and a `try/catch` that just returns `{ onSuccess: false, onFailure: true }`, you should be using expression mode instead.
 
 ### 7. Defaulting to Normal Mode
 
 Normal mode adds boilerplate that expression mode handles automatically. Default to `@expression` for every node. Only reach for normal mode when the function needs to:
-- Route to different downstream nodes on success vs. failure
-- Return error data (not just signal failure)
+- Return error data alongside the failure signal (not just signal failure)
+- Perform void side-effects with no return value
 - Perform void side-effects with explicit control flow

package/docs/reference/node-conversion.md

@@ -10,15 +10,12 @@ keywords: [conversion, expression mode, normal mode, function, transform, nodeTy
 Is it a pure function that returns a value?
   YES -> expression mode (@expression)
   NO  |
-Does it need to route onSuccess/onFailure to different nodes?
-  YES -> normal mode
-  NO  |
 Does it need to return error data alongside the failure signal?
   YES -> normal mode
   NO  -> expression mode (@expression)
 ```
 
-**Default to expression mode** unless the function has explicit success/failure branching logic.
+**Default to expression mode.** Expression nodes handle success/failure branching via throw. Only use normal mode when you need to return data on the failure path, or for void side-effects.
 
 ---
 
@@ -280,7 +277,7 @@ When no `--mode` is specified:
 - **Expression** (default): function returns a value (non-void), whether sync or async
 - **Normal**: void return, or user explicitly requests normal mode
 
-**Default to expression mode** unless the function has explicit success/failure branching logic. If the function simply takes inputs and returns outputs -- even async ones with `await` -- expression mode is the right choice.
+**Default to expression mode.** Expression nodes support failure branching via throw. Only switch to normal mode for error-with-data patterns or void side-effects.
 
 The compiler fully supports async expression nodes -- `await`, async detection, try/catch wrapping, and onSuccess/onFailure are all handled automatically.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",