@synergenius/flow-weaver 0.13.0 → 0.13.2

package/README.md

@@ -1,4 +1,4 @@
-# @synergenius/flow-weaver
+# Flow Weaver
 
 [![npm version](https://img.shields.io/npm/v/@synergenius/flow-weaver?style=flat)](https://www.npmjs.com/package/@synergenius/flow-weaver)
 [![npm downloads](https://img.shields.io/npm/dw/@synergenius/flow-weaver?style=flat)](https://www.npmjs.com/package/@synergenius/flow-weaver)
@@ -10,34 +10,43 @@
 
 **Build AI agent workflows visually. Ship them as your own code.**
 
-Design agent workflows in the Studio, in TypeScript, or let AI build them for you. Everything compiles to standalone functions you deploy anywhere, no runtime dependency on Flow Weaver.
+Design agent workflows in the Studio, in TypeScript, or let AI build them for you. The compiler validates everything with 20+ rule categories. The output is standalone TypeScript you deploy anywhere, zero runtime dependency on Flow Weaver.
 
-## Three Ways to Build
-
-**Studio.**
-A unified environment that combines a full code editor with a visual graph builder. You can write and refactor workflows directly in code or compose them visually on the canvas. Both representations stay synchronized at all times. Editing either one updates the other instantly, so you can move between abstraction levels without friction.
+[**flowweaver.ai**](https://flowweaver.ai) · [**Open the Studio**](https://flowweaver.ai/studio) · [**Docs**](https://flowweaver.ai/docs) · [**Discord**](https://discord.gg/6Byh3ur2bk) · [**npm**](https://www.npmjs.com/package/@synergenius/flow-weaver)
 
-**TypeScript.**
-Define workflows in plain TypeScript by annotating functions with JSDoc. The compiler derives an executable workflow graph with static typing and compile-time validation.
-There is no YAML, no JSON configuration, and no runtime layer.
-No lock-in. Remove the annotations and you keep a clean, readable TypeScript file with zero dependencies.
+---
 
-**AI Agents.**
-Connect Claude Code, Cursor, or OpenClaw to design and ship workflows. Agents scaffold implementations, run the compiler, interpret validation errors, apply corrections, and repeat the process until the workflow compiles successfully.
-With more than 30 MCP tools available, the entire build loop can run autonomously.
+## Try It
 
-1. **Agent creates**: scaffolds from templates, builds from a model, or writes from scratch
-2. **Compiler validates**: 15+ validation passes catch missing connections, type mismatches, unreachable paths
-3. **Agent iterates**: validation errors include fix suggestions, the agent corrects and re-validates
-4. **Agent tests**: deterministic mock providers for reproducible testing without real API calls
-5. **Human reviews**: visual editor or SVG diagram for final approval
+**In the browser.** Open the [Cloud Studio](https://flowweaver.ai/studio), sign up, and start building. No install required.
 
-## Quick Start
+**From the terminal.**
 
 ```bash
 npm install @synergenius/flow-weaver
+npx flow-weaver init my-project
+cd my-project
+npx flow-weaver run workflows/example.ts --params '{"input": "value"}'
 ```
 
+## How It Works
+
+**Generate.** AI agents build workflows via 48 MCP tools, or you build visually in the Studio, or you write annotated TypeScript by hand. All three stay in sync.
+
+**Validate.** The compiler catches wiring errors, type mismatches, missing handlers, unreachable paths, and agent-specific mistakes before anything runs. Not at runtime, not in production.
+
+**Own.** Compiled output is plain TypeScript with zero imports from Flow Weaver. Clean git diffs, standard testing, no license obligations on the output. If Flow Weaver disappeared tomorrow, your agents would still run.
+
+## Three Ways to Build
+
+**Studio.** A visual IDE that combines a full code editor with a graph builder. Write and refactor workflows in code or compose them on the canvas. Both representations stay synchronized: editing either one updates the other instantly.
+
+**TypeScript.** Define workflows in plain TypeScript by annotating functions with JSDoc. The compiler derives an executable workflow graph with static typing and compile-time validation. No YAML, no JSON configuration, no runtime layer. Remove the annotations and you keep a clean TypeScript file with zero dependencies.
+
+**AI Agents.** Connect Claude Code, Cursor, or OpenClaw and let agents scaffold implementations, run the compiler, interpret validation errors, apply corrections, and iterate until the workflow compiles. Agents then test with deterministic mock providers and generate diagrams for human review.
+
+## Quick Start
+
 Workflows are plain TypeScript. Annotations declare the graph structure:
 
 ```typescript
@@ -79,7 +88,7 @@ The compiler fills in the function body while preserving your code outside the g
 
 ## AI-Native Development with MCP
 
-Flow Weaver includes an MCP server for Claude Code, Cursor, OpenClaw, or any MCP-compatible agent:
+Flow Weaver includes an MCP server with 48 tools for Claude Code, Cursor, OpenClaw, or any MCP-compatible agent:
 
 ```bash
 npx flow-weaver mcp-server    # auto-registers with Claude Code
@@ -108,27 +117,20 @@ npx flow-weaver status my-workflow.ts      # shows stub vs implemented progress
 npx flow-weaver implement my-workflow.ts processData   # scaffolds a node body
 ```
 
-The graph is valid before any node has a real implementation. Fill in node bodies incrementally, check `status` to track progress. Architecture and implementation stay separate: the architect defines the shape, developers fill in the logic.
+The graph is valid before any node has a real implementation. Fill in node bodies incrementally, check `status` to track progress. The architect defines the shape, developers fill in the logic.
 
 ## Agent Workflow Templates
 
-Built-in templates for AI agent workflows (LLM reasoning, tool calling, looping):
+Built-in templates for AI agent workflows:
 
 ```bash
-# Scaffold a tool-calling agent with memory and error handling
 npx flow-weaver create workflow ai-agent my-agent.ts --provider openai --model gpt-4o
-
-# ReAct pattern (Thought -> Action -> Observation loop)
 npx flow-weaver create workflow ai-react react-agent.ts
-
-# RAG pipeline (Retrieve -> Augment -> Generate)
 npx flow-weaver create workflow ai-rag rag-pipeline.ts
-
-# Durable agent with per-step retries (compiles to Inngest)
 npx flow-weaver create workflow ai-agent-durable durable-agent.ts
 ```
 
-**12 workflow templates** cover common patterns:
+**12 workflow templates:**
 
 | Template | What it builds |
 |----------|---------------|
@@ -145,9 +147,9 @@ npx flow-weaver create workflow ai-agent-durable durable-agent.ts
 | `webhook` | HTTP event handler |
 | `error-handler` | Error recovery pattern |
 
-**12 node templates** for common node types: `llm-call`, `tool-executor`, `conversation-memory`, `prompt-template`, `json-extractor`, `human-approval`, `agent-router`, `rag-retriever`, `validator`, `transformer`, `http`, `aggregator`.
+Plus **12 node templates** for common building blocks: `llm-call`, `tool-executor`, `conversation-memory`, `prompt-template`, `json-extractor`, `human-approval`, `agent-router`, `rag-retriever`, `validator`, `transformer`, `http`, `aggregator`.
 
-## Agent-Aware Validation
+## Compile-Time Validation
 
 The validator understands AI agent patterns and enforces safety rules:
 
@@ -159,7 +161,7 @@ AGENT_LLM_NO_FALLBACK              LLM failure goes directly to Exit, add retry
 AGENT_TOOL_NO_OUTPUT_HANDLING      Tool executor outputs are all unconnected, results are discarded
 ```
 
-These aren't generic lint rules. The validator identifies LLM, tool-executor, human-approval, and memory nodes by port signatures, annotations, and naming patterns, then applies agent-specific checks.
+These are not generic lint rules. The validator identifies LLM, tool-executor, human-approval, and memory nodes by port signatures, annotations, and naming patterns, then applies agent-specific checks.
 
 ## Deterministic Agent Testing
 
@@ -185,9 +187,9 @@ const replay = loadRecording('fixtures/agent-session.json');
 
 Mock human approvals, fast-forward delays, and simulate external events. Configured via `globalThis.__fw_mock_config__`.
 
-## Scoped Ports: Agent Loops Without Cycles
+## Scoped Ports: Agent Loops Without Graph Cycles
 
-Most workflow engines either ban loops (DAG-only) or allow arbitrary cycles (hard to reason about). Flow Weaver uses **scoped ports** to express iteration without graph cycles:
+Most workflow engines either ban loops entirely (DAG-only) or allow arbitrary cycles that are hard to reason about. Flow Weaver takes a third path: **scoped ports** express iteration while keeping the graph acyclic and statically analyzable.
 
 ```typescript
 /**
@@ -202,32 +204,9 @@ Most workflow engines either ban loops (DAG-only) or allow arbitrary cycles (har
  */
 ```
 
-The scope's output ports become callback parameters, and input ports become return values. Agent reasoning loops, ForEach over collections, map/reduce patterns, nested sub-workflows: all work while keeping the graph acyclic and statically analyzable.
-
-## Diagram Generation
-
-Generate SVG or interactive HTML diagrams from any workflow:
-
-```bash
-flow-weaver diagram workflow.ts -o workflow.svg --theme dark
-flow-weaver diagram workflow.ts -o workflow.html --format html
-```
-
-Customize node appearance with annotations:
-
-```typescript
-/**
- * @flowWeaver nodeType
- * @color blue
- * @icon database
- */
-```
-
-Named colors: `blue`, `purple`, `green`, `cyan`, `orange`, `pink`, `red`, `yellow`. Icons include `api`, `database`, `shield`, `brain`, `cloud`, `search`, `code`, and 60+ more from Material Design 3.
-
-The interactive HTML viewer supports zoom/pan, click-to-inspect nodes, port-level hover with connection tracing, and works standalone or embedded in an iframe.
+The scope's output ports become callback parameters, and input ports become return values. Agent reasoning loops, ForEach over collections, map/reduce patterns, and nested sub-workflows all work without introducing graph cycles.
 
-## Multi-Target Compilation
+## Deploy Anywhere
 
 Same workflow source, multiple deployment targets:
 
@@ -249,6 +228,27 @@ flow-weaver serve ./workflows --port 3000 --swagger
 
 Both the default TypeScript target and Inngest target parallelize independent nodes with `Promise.all()`. Inngest additionally wraps each node in `step.run()` for individual durability and generates typed Zod event schemas.
 
+## Diagram Generation
+
+Generate SVG or interactive HTML diagrams from any workflow:
+
+```bash
+flow-weaver diagram workflow.ts -o workflow.svg --theme dark
+flow-weaver diagram workflow.ts -o workflow.html --format html
+```
+
+Customize node appearance with annotations:
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @color blue
+ * @icon database
+ */
+```
+
+Named colors: `blue`, `purple`, `green`, `cyan`, `orange`, `pink`, `red`, `yellow`. Icons include `api`, `database`, `shield`, `brain`, `cloud`, `search`, `code`, and 60+ more from Material Design 3. The interactive HTML viewer supports zoom/pan, click-to-inspect nodes, and port-level hover with connection tracing.
+
 ## API
 
 ```typescript
@@ -370,18 +370,38 @@ function nodeName(
 
 Expression nodes (`@expression`) skip the control flow boilerplate. Inputs and outputs map directly to the TypeScript signature.
 
-## Testing
+## Flow Weaver Cloud
 
-```bash
-npm test              # Run all tests
-npm run test:watch    # Watch mode
-```
+[flowweaver.ai](https://flowweaver.ai) is the hosted platform that adds collaboration, managed deployments, and team features on top of everything the CLI provides.
+
+What the cloud adds:
+
+- **Browser-based Studio** with real-time collaborative editing
+- **One-click deployment** of any workflow as an HTTP endpoint
+- **Execution logs** for every workflow run, with input/output history
+- **Visual debugger** for step-through node inspection (Pro)
+- **Version history** and workflow snapshots (Pro)
+- **AI Chat assistant** for building and debugging workflows (Pro)
+- **Organization workspaces** with team management (Business)
+
+Three tiers: **Free** (3 workflows, 1 deployment, 100 executions/month), **Pro** at 9 EUR/month (25 workflows, 10k executions), and **Business** at 29 EUR/month (unlimited workflows, 100k executions). See [flowweaver.ai/pricing](https://flowweaver.ai/pricing) for details.
+
+The CLI remains fully functional for local development. The cloud adds the parts that are hard to do alone: team collaboration, always-on endpoints, and operational visibility.
+
+## Community
+
+- [Discord](https://discord.gg/6Byh3ur2bk)
+- [GitHub Discussions](https://github.com/synergenius-fw/flow-weaver/discussions)
+- [X / Twitter](https://x.com/flowweaver_ai)
+- [Website](https://flowweaver.ai)
 
 ## Development
 
 ```bash
 npm run build         # Build
 npm run watch         # Watch mode
+npm test              # Run all tests
+npm run test:watch    # Watch mode
 npm run typecheck     # Type check
 npm run docs          # Generate API docs
 ```

package/dist/api/generate-in-place.js

@@ -907,8 +907,12 @@ function generateNodeTypeJSDoc(nodeType) {
 function replaceWorkflowJSDoc(source, ast, options = {}) {
     const sourceFile = ts.createSourceFile('temp.ts', source, ts.ScriptTarget.Latest, true);
     let functionNode;
-    // Find the workflow function (exported or not)
+    // Find the FIRST workflow function with the matching name.
+    // ts.forEachChild visits all children — we break on first match to avoid
+    // targeting a later duplicate (which corrupts the wrong function's JSDoc).
     ts.forEachChild(sourceFile, (node) => {
+        if (functionNode)
+            return; // already found — skip
         if (ts.isFunctionDeclaration(node) && node.name?.text === ast.functionName) {
             functionNode = node;
         }

package/dist/cli/flow-weaver.mjs

@@ -9671,7 +9671,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.13.0";
+    VERSION = "0.13.2";
   }
 });
 
@@ -19539,6 +19539,7 @@ function replaceWorkflowJSDoc(source, ast, options = {}) {
   const sourceFile = ts2.createSourceFile("temp.ts", source, ts2.ScriptTarget.Latest, true);
   let functionNode;
   ts2.forEachChild(sourceFile, (node) => {
+    if (functionNode) return;
     if (ts2.isFunctionDeclaration(node) && node.name?.text === ast.functionName) {
       functionNode = node;
     }
@@ -46773,6 +46774,8 @@ function buildScopeSubGraph(parentNode, parentNt, scopeName, childIds, ast, node
     if (!childInst) continue;
     const childNode = buildInstanceNode(childId, childInst.nodeType, childInst.config, nodeTypeMap, theme);
     computeNodeDimensions(childNode);
+    if (childInst.config?.width != null) childNode.width = childInst.config.width;
+    if (childInst.config?.height != null) childNode.height = childInst.config.height;
     children.push(childNode);
     childNodeMap.set(childId, childNode);
   }
@@ -47086,6 +47089,23 @@ function resolveHorizontalOverlaps(diagramNodes, explicitPositions) {
     }
   }
 }
+function resolvePostLayoutOverlaps(diagramNodes) {
+  const hasScopeParent = [...diagramNodes.values()].some((n) => n.scopeChildren && n.scopeChildren.length > 0);
+  if (!hasScopeParent) return;
+  const nodes = [...diagramNodes.values()].sort((a, b) => a.x - b.x);
+  for (let i = 1; i < nodes.length; i++) {
+    const prev = nodes[i - 1];
+    const curr = nodes[i];
+    if (!prev.scopeChildren || prev.scopeChildren.length === 0) continue;
+    const actualGap = curr.x - (prev.x + prev.width);
+    if (actualGap < MIN_EDGE_GAP) {
+      const shift = MIN_EDGE_GAP - actualGap;
+      for (let j = i; j < nodes.length; j++) {
+        nodes[j].x += shift;
+      }
+    }
+  }
+}
 function buildDiagramGraph(ast, options = {}) {
   const themeName = options.theme ?? "dark";
   const nodeTypeMap = /* @__PURE__ */ new Map();
@@ -47183,6 +47203,13 @@ function buildDiagramGraph(ast, options = {}) {
     if (!parentNt) continue;
     buildScopeSubGraph(parentNode, parentNt, scopeName, childIds, ast, nodeTypeMap, themeName);
   }
+  for (const inst of ast.instances) {
+    if (scopedChildren.has(inst.id)) continue;
+    const node = diagramNodes.get(inst.id);
+    if (!node) continue;
+    if (inst.config?.width != null) node.width = inst.config.width;
+    if (inst.config?.height != null) node.height = inst.config.height;
+  }
   const explicitPositions = extractExplicitPositions(ast);
   const allPositioned = [...diagramNodes.keys()].every((id) => explicitPositions.has(id));
   const nonePositioned = ![...diagramNodes.keys()].some((id) => explicitPositions.has(id));
@@ -47202,6 +47229,7 @@ function buildDiagramGraph(ast, options = {}) {
     assignUnpositionedNodes(layers, diagramNodes, explicitPositions);
     resolveHorizontalOverlaps(diagramNodes, explicitPositions);
   }
+  resolvePostLayoutOverlaps(diagramNodes);
   for (const node of diagramNodes.values()) {
     computePortPositions(node);
   }
@@ -110074,7 +110102,7 @@ async function mcpSetupCommand(options, deps) {
 
 // src/cli/index.ts
 init_error_utils();
-var version2 = true ? "0.13.0" : "0.0.0-dev";
+var version2 = true ? "0.13.2" : "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/diagram/geometry.js

@@ -298,6 +298,10 @@ function buildScopeSubGraph(parentNode, parentNt, scopeName, childIds, ast, node
             continue;
         const childNode = buildInstanceNode(childId, childInst.nodeType, childInst.config, nodeTypeMap, theme);
         computeNodeDimensions(childNode);
+        if (childInst.config?.width != null)
+            childNode.width = childInst.config.width;
+        if (childInst.config?.height != null)
+            childNode.height = childInst.config.height;
         children.push(childNode);
         childNodeMap.set(childId, childNode);
     }
@@ -628,6 +632,32 @@ function resolveHorizontalOverlaps(diagramNodes, explicitPositions) {
         }
     }
 }
+/**
+ * After all positioning, resolve overlaps caused by expanded scope boxes.
+ * Only checks nodes immediately after a scope parent — regular node spacing
+ * is left to the user's explicit positions. When a node falls inside the
+ * expanded scope box, shift it and all further-right nodes to clear.
+ */
+function resolvePostLayoutOverlaps(diagramNodes) {
+    const hasScopeParent = [...diagramNodes.values()].some(n => n.scopeChildren && n.scopeChildren.length > 0);
+    if (!hasScopeParent)
+        return;
+    const nodes = [...diagramNodes.values()].sort((a, b) => a.x - b.x);
+    for (let i = 1; i < nodes.length; i++) {
+        const prev = nodes[i - 1];
+        const curr = nodes[i];
+        // Only resolve overlaps caused by scope parent expansion
+        if (!prev.scopeChildren || prev.scopeChildren.length === 0)
+            continue;
+        const actualGap = curr.x - (prev.x + prev.width);
+        if (actualGap < MIN_EDGE_GAP) {
+            const shift = MIN_EDGE_GAP - actualGap;
+            for (let j = i; j < nodes.length; j++) {
+                nodes[j].x += shift;
+            }
+        }
+    }
+}
 // ---- Main orchestrator ----
 export function buildDiagramGraph(ast, options = {}) {
     const themeName = options.theme ?? 'dark';
@@ -741,6 +771,18 @@ export function buildDiagramGraph(ast, options = {}) {
             continue;
         buildScopeSubGraph(parentNode, parentNt, scopeName, childIds, ast, nodeTypeMap, themeName);
     }
+    // Apply explicit [size: W H] annotation — hard override (not a floor)
+    for (const inst of ast.instances) {
+        if (scopedChildren.has(inst.id))
+            continue;
+        const node = diagramNodes.get(inst.id);
+        if (!node)
+            continue;
+        if (inst.config?.width != null)
+            node.width = inst.config.width;
+        if (inst.config?.height != null)
+            node.height = inst.config.height;
+    }
     // Layout — use explicit positions when available, auto-layout otherwise
     const explicitPositions = extractExplicitPositions(ast);
     const allPositioned = [...diagramNodes.keys()].every(id => explicitPositions.has(id));
@@ -766,6 +808,11 @@ export function buildDiagramGraph(ast, options = {}) {
         assignUnpositionedNodes(layers, diagramNodes, explicitPositions);
         resolveHorizontalOverlaps(diagramNodes, explicitPositions);
     }
+    // Resolve overlaps caused by expanded scope boxes. When all positions are
+    // explicit, resolveHorizontalOverlaps is never called (or skips all nodes).
+    // Scope parents can be far wider than the user anticipates, so we cascade
+    // a rightward shift to all downstream nodes that fall inside the expanded box.
+    resolvePostLayoutOverlaps(diagramNodes);
     // Compute external port positions
     for (const node of diagramNodes.values()) {
         computePortPositions(node);

package/dist/generated-version.d.ts

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

package/package.json

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