@synergenius/flow-weaver 0.5.1 → 0.7.0

package/README.md

@@ -218,7 +218,7 @@ flow-weaver export workflow.ts --target cloudflare --output deploy/
 flow-weaver serve ./workflows --port 3000 --swagger
 ```
 
-Inngest compilation wraps each node in `step.run()` for individual durability, parallelizes independent nodes with `Promise.all()`, and generates typed Zod event schemas.
+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.
 
 ## Visual Human-in-the-Loop
 
@@ -319,6 +319,7 @@ flow-weaver listen                   # Stream editor events
 |------|---------|
 | `delay` | Sleep for a duration (ms, s, m, h, d). Mockable for fast testing. |
 | `waitForEvent` | Wait for an external event with optional field matching and timeout. Maps to Inngest `step.waitForEvent()` for zero-cost durable pauses. |
+| `waitForAgent` | Pause execution and wait for an external agent to provide a result. Supports multi-step human-in-the-loop and agent delegation patterns. |
 | `invokeWorkflow` | Invoke another workflow by ID with payload and timeout. Maps to Inngest `step.invoke()`. |
 
 ## STEP Port Architecture

package/dist/annotation-generator.js

@@ -20,6 +20,10 @@ export class AnnotationGenerator {
             if (nodeType.variant === 'MAP_ITERATOR') {
                 return;
             }
+            // Skip synthetic COERCION node types — they're generated from @coerce macros
+            if (nodeType.variant === 'COERCION') {
+                return;
+            }
             lines.push(...this.generateNodeTypeAnnotation(nodeType, indent, includeComments, includeMetadata));
             lines.push("");
         });
@@ -36,9 +40,11 @@ export class AnnotationGenerator {
         }
         // Generate JSDoc comment block (only when no functionText)
         lines.push("/**");
-        // Add description if present
+        // Add description if present (handle multi-line descriptions)
         if (includeComments && nodeType.description) {
-            lines.push(` * ${nodeType.description}`);
+            for (const descLine of nodeType.description.split('\n')) {
+                lines.push(` * ${descLine}`);
+            }
             lines.push(` *`);
         }
         // @flowWeaver nodeType marker
@@ -136,10 +142,11 @@ export class AnnotationGenerator {
     }
     generateWorkflowAnnotation(workflow, indent, includeComments, skipParamReturns = false) {
         const lines = [];
-        // Build macro coverage sets for filtering (@map-specific)
+        // Build macro coverage sets for filtering (@map and @coerce)
         const macroInstanceIds = new Set();
         const macroChildIds = new Set();
         const macroScopeNames = new Set();
+        const coerceInstanceIds = new Set();
         if (workflow.macros && workflow.macros.length > 0) {
             for (const macro of workflow.macros) {
                 if (macro.type === 'map') {
@@ -147,6 +154,9 @@ export class AnnotationGenerator {
                     macroChildIds.add(macro.childId);
                     macroScopeNames.add(`${macro.instanceId}.iterate`);
                 }
+                else if (macro.type === 'coerce') {
+                    coerceInstanceIds.add(macro.instanceId);
+                }
             }
         }
         // Generate JSDoc comment block
@@ -211,10 +221,12 @@ export class AnnotationGenerator {
         if (workflow.description && includeComments) {
             lines.push(` * @description ${workflow.description}`);
         }
-        // Add node instances — skip synthetic MAP_ITERATOR instances, strip parent from macro children
+        // Add node instances — skip synthetic MAP_ITERATOR/COERCION instances, strip parent from macro children
         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: undefined };
                 lines.push(generateNodeInstanceTag(stripped));
@@ -257,6 +269,11 @@ export class AnnotationGenerator {
                     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}`);
+                }
             }
         }
         // Add node positions (if they exist)
@@ -492,6 +509,14 @@ function isConnectionCoveredByMacroStatic(conn, macros) {
                 }
             }
         }
+        else if (macro.type === 'coerce') {
+            if (conn.from.scope || conn.to.scope)
+                continue;
+            // Connections to/from the synthetic coercion instance are covered
+            if (conn.to.node === macro.instanceId || conn.from.node === macro.instanceId) {
+                return true;
+            }
+        }
     }
     return false;
 }

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

@@ -408,6 +408,9 @@ function replaceWorkflowFunctionBody(source, functionName, newBody) {
     }
     // Find the closing brace
     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 = [

package/dist/ast/types.d.ts

@@ -111,7 +111,7 @@ export type TWorkflowAST = {
  * A sugar macro that expands to a full scope pattern or connection set.
  * Stored on the workflow AST for round-trip preservation in generateInPlace.
  */
-export type TWorkflowMacro = TMapMacro | TPathMacro | TFanOutMacro | TFanInMacro;
+export type TWorkflowMacro = TMapMacro | TPathMacro | TFanOutMacro | TFanInMacro | TCoerceMacro;
 export type TMapMacro = {
     type: 'map';
     /** Instance ID for the synthetic iterator node (e.g., "loop") */
@@ -159,6 +159,24 @@ export type TFanInMacro = {
         port: string;
     };
 };
+export type TCoerceTargetType = 'string' | 'number' | 'boolean' | 'json' | 'object';
+export type TCoerceMacro = {
+    type: 'coerce';
+    /** Instance ID for the synthetic coercion node */
+    instanceId: string;
+    /** Source port in "node.port" format */
+    source: {
+        node: string;
+        port: string;
+    };
+    /** Target port in "node.port" format */
+    target: {
+        node: string;
+        port: string;
+    };
+    /** Coercion target type */
+    targetType: TCoerceTargetType;
+};
 /**
  * Default configuration for a node type that can be overridden per instance.
  */
@@ -222,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';
+    variant?: 'FUNCTION' | 'WORKFLOW' | 'IMPORTED_WORKFLOW' | 'MAP_ITERATOR' | 'COERCION';
     /** File path for external node types */
     path?: string;
     /** Function reference for function-based node types */
@@ -619,6 +637,8 @@ export type TValidationError = {
     node?: string;
     connection?: TConnectionAST;
     location?: TSourceLocation;
+    /** Reference to documentation explaining this error and how to fix it. */
+    docUrl?: string;
 };
 export type TAnalysisResult = {
     controlFlowGraph: TControlFlowGraph;

package/dist/built-in-nodes/coercion-types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Synthetic node type definitions for explicit type coercion.
+ *
+ * These are compiler-internal node types created by @coerce macros.
+ * They generate inline JavaScript coercion expressions instead of function calls.
+ */
+import type { TNodeTypeAST, TCoerceTargetType } from '../ast/types.js';
+/** Maps coercion target type keyword to the synthetic node type name */
+export declare const COERCE_TYPE_MAP: Record<TCoerceTargetType, string>;
+/** Maps synthetic node type name to the inline JS expression */
+export declare const COERCE_EXPRESSIONS: Record<string, string>;
+export declare const COERCION_NODE_TYPES: Record<string, TNodeTypeAST>;
+/** Check if a function name is a coercion node type */
+export declare function isCoercionNode(functionName: string): boolean;
+//# sourceMappingURL=coercion-types.d.ts.map

package/dist/built-in-nodes/coercion-types.js

@@ -0,0 +1,61 @@
+/**
+ * Synthetic node type definitions for explicit type coercion.
+ *
+ * These are compiler-internal node types created by @coerce macros.
+ * They generate inline JavaScript coercion expressions instead of function calls.
+ */
+/** Maps coercion target type keyword to the synthetic node type name */
+export const COERCE_TYPE_MAP = {
+    string: '__fw_toString',
+    number: '__fw_toNumber',
+    boolean: '__fw_toBoolean',
+    json: '__fw_toJSON',
+    object: '__fw_parseJSON',
+};
+/** Maps synthetic node type name to the inline JS expression */
+export const COERCE_EXPRESSIONS = {
+    __fw_toString: 'String',
+    __fw_toNumber: 'Number',
+    __fw_toBoolean: 'Boolean',
+    __fw_toJSON: 'JSON.stringify',
+    __fw_parseJSON: 'JSON.parse',
+};
+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' }],
+        },
+    };
+}
+export const 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'),
+};
+/** Check if a function name is a coercion node type */
+export function isCoercionNode(functionName) {
+    return functionName in COERCION_NODE_TYPES;
+}
+//# sourceMappingURL=coercion-types.js.map

package/dist/built-in-nodes/invoke-workflow.js

@@ -1,4 +1,4 @@
-import { getMockConfig } from './mock-types.js';
+import { getMockConfig, lookupMock } from './mock-types.js';
 /**
  * @flowWeaver nodeType
  * @input functionId - Inngest function ID (e.g. "my-service/sub-workflow")
@@ -11,8 +11,8 @@ export async function invokeWorkflow(execute, functionId, payload, timeout) {
         return { onSuccess: false, onFailure: false, result: {} };
     const mocks = getMockConfig();
     if (mocks) {
-        // Mock mode active — look up result by functionId
-        const mockResult = mocks.invocations?.[functionId];
+        // Mock mode — look up result by functionId (supports instance-qualified keys)
+        const mockResult = lookupMock(mocks.invocations, functionId);
         if (mockResult !== undefined) {
             return { onSuccess: true, onFailure: false, result: mockResult };
         }

package/dist/built-in-nodes/mock-types.d.ts

@@ -17,4 +17,24 @@ export interface FwMockConfig {
  * Read the mock config from globalThis, returning undefined if not set.
  */
 export declare function getMockConfig(): FwMockConfig | undefined;
+/**
+ * Look up a mock value from a section, supporting instance-qualified keys.
+ *
+ * Checks "instanceId:key" first (for per-node targeting), then falls back
+ * to plain "key". The instance ID comes from __fw_current_node_id__ which
+ * the generated code sets before each node invocation.
+ *
+ * @example
+ * ```json
+ * {
+ *   "invocations": {
+ *     "retryCall:api/process": { "status": "ok" },
+ *     "api/process": { "status": "default" }
+ *   }
+ * }
+ * ```
+ * When the node "retryCall" invokes "api/process", it gets `{ status: "ok" }`.
+ * Any other node invoking "api/process" gets `{ status: "default" }`.
+ */
+export declare function lookupMock<T>(section: Record<string, T> | undefined, key: string): T | undefined;
 //# sourceMappingURL=mock-types.d.ts.map

package/dist/built-in-nodes/mock-types.js

@@ -9,4 +9,34 @@
 export function getMockConfig() {
     return globalThis.__fw_mocks__;
 }
+/**
+ * Look up a mock value from a section, supporting instance-qualified keys.
+ *
+ * Checks "instanceId:key" first (for per-node targeting), then falls back
+ * to plain "key". The instance ID comes from __fw_current_node_id__ which
+ * the generated code sets before each node invocation.
+ *
+ * @example
+ * ```json
+ * {
+ *   "invocations": {
+ *     "retryCall:api/process": { "status": "ok" },
+ *     "api/process": { "status": "default" }
+ *   }
+ * }
+ * ```
+ * When the node "retryCall" invokes "api/process", it gets `{ status: "ok" }`.
+ * Any other node invoking "api/process" gets `{ status: "default" }`.
+ */
+export function lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[`${nodeId}:${key}`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
 //# sourceMappingURL=mock-types.js.map

package/dist/built-in-nodes/wait-for-agent.js

@@ -1,4 +1,4 @@
-import { getMockConfig } from './mock-types.js';
+import { getMockConfig, lookupMock } from './mock-types.js';
 /**
  * @flowWeaver nodeType
  * @input agentId - Agent/task identifier
@@ -9,10 +9,11 @@ import { getMockConfig } from './mock-types.js';
 export async function waitForAgent(execute, agentId, context, prompt) {
     if (!execute)
         return { onSuccess: false, onFailure: false, agentResult: {} };
-    // 1. Check mocks first
+    // 1. Check mocks first (supports instance-qualified keys)
     const mocks = getMockConfig();
-    if (mocks?.agents?.[agentId]) {
-        return { onSuccess: true, onFailure: false, agentResult: mocks.agents[agentId] };
+    const mockResult = lookupMock(mocks?.agents, agentId);
+    if (mockResult !== undefined) {
+        return { onSuccess: true, onFailure: false, agentResult: mockResult };
     }
     // 2. Check agent channel (set by executor for pause/resume)
     const channel = globalThis.__fw_agent_channel__;

package/dist/built-in-nodes/wait-for-event.js

@@ -1,4 +1,4 @@
-import { getMockConfig } from './mock-types.js';
+import { getMockConfig, lookupMock } from './mock-types.js';
 /**
  * @flowWeaver nodeType
  * @input eventName - Event name to wait for (e.g. "app/approval.received")
@@ -11,8 +11,8 @@ export async function waitForEvent(execute, eventName, match, timeout) {
         return { onSuccess: false, onFailure: false, eventData: {} };
     const mocks = getMockConfig();
     if (mocks) {
-        // Mock mode active — look up event data by name
-        const mockData = mocks.events?.[eventName];
+        // Mock mode — look up event data by name (supports instance-qualified keys)
+        const mockData = lookupMock(mocks.events, eventName);
         if (mockData !== undefined) {
             return { onSuccess: true, onFailure: false, eventData: mockData };
         }

package/dist/chevrotain-parser/coerce-parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module chevrotain-parser/coerce-parser
+ *
+ * Parser for @coerce sugar annotation using Chevrotain.
+ *
+ * Syntax:
+ *   @coerce instanceId sourceNode.port -> targetNode.port as targetType
+ *
+ * Where targetType is one of: string, number, boolean, json, object
+ */
+import type { TCoerceTargetType } from '../ast/types.js';
+export interface CoerceParseResult {
+    instanceId: string;
+    source: {
+        node: string;
+        port: string;
+    };
+    target: {
+        node: string;
+        port: string;
+    };
+    targetType: TCoerceTargetType;
+}
+/**
+ * Parse a @coerce line and return structured result.
+ * Returns null if the line is not a valid @coerce declaration.
+ */
+export declare function parseCoerceLine(input: string, warnings: string[]): CoerceParseResult | null;
+/**
+ * Get serialized grammar for documentation/diagram generation.
+ */
+export declare function getCoerceGrammar(): import("chevrotain").ISerializedGast[];
+//# sourceMappingURL=coerce-parser.d.ts.map

package/dist/chevrotain-parser/coerce-parser.js

@@ -0,0 +1,103 @@
+/**
+ * @module chevrotain-parser/coerce-parser
+ *
+ * Parser for @coerce sugar annotation using Chevrotain.
+ *
+ * Syntax:
+ *   @coerce instanceId sourceNode.port -> targetNode.port as targetType
+ *
+ * Where targetType is one of: string, number, boolean, json, object
+ */
+import { CstParser } from 'chevrotain';
+import { JSDocLexer, CoerceTag, Identifier, Arrow, Dot, AsKeyword, allTokens, } from './tokens.js';
+const VALID_COERCE_TYPES = new Set(['string', 'number', 'boolean', 'json', 'object']);
+// =============================================================================
+// Parser Definition
+// =============================================================================
+class CoerceParser 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' });
+    });
+}
+// =============================================================================
+// Parser Instance (singleton)
+// =============================================================================
+const parserInstance = new CoerceParser();
+// =============================================================================
+// CST Visitor
+// =============================================================================
+const BaseVisitor = parserInstance.getBaseCstVisitorConstructor();
+class CoerceVisitor extends BaseVisitor {
+    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,
+        };
+    }
+}
+const visitorInstance = new CoerceVisitor();
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Parse a @coerce line and return structured result.
+ * Returns null if the line is not a valid @coerce declaration.
+ */
+export 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;
+    parserInstance.input = lexResult.tokens;
+    const cst = parserInstance.coerceLine();
+    if (parserInstance.errors.length > 0) {
+        const truncatedInput = input.length > 80 ? input.substring(0, 80) + '...' : input;
+        warnings.push(`Failed to parse @coerce line: "${truncatedInput}"\n` +
+            `  Error: ${parserInstance.errors[0].message}\n` +
+            `  Expected format: @coerce instanceId source.port -> target.port as type`);
+        return null;
+    }
+    const result = visitorInstance.visit(cst);
+    // Validate the target type
+    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;
+}
+/**
+ * Get serialized grammar for documentation/diagram generation.
+ */
+export function getCoerceGrammar() {
+    return parserInstance.getSerializedGastProductions();
+}
+//# sourceMappingURL=coerce-parser.js.map

package/dist/chevrotain-parser/index.d.ts

@@ -4,7 +4,7 @@
  * Chevrotain-based parsers for JSDoc annotations.
  * Provides structured parsing for @input, @output, @node, @connect, and @position.
  */
-export { JSDocLexer, allTokens, InputTag, OutputTag, NodeTag, ConnectTag, PositionTag, ScopeTag, MapTag, PathTag, FanOutTag, FanInTag, TriggerTag, CancelOnTag, RetriesTag, TimeoutTag, ThrottleTag, } from './tokens.js';
+export { JSDocLexer, allTokens, InputTag, OutputTag, NodeTag, ConnectTag, PositionTag, ScopeTag, MapTag, PathTag, FanOutTag, FanInTag, CoerceTag, TriggerTag, CancelOnTag, RetriesTag, TimeoutTag, ThrottleTag, } from './tokens.js';
 export { parsePortLine, getPortGrammar } from './port-parser.js';
 export type { PortParseResult } from './port-parser.js';
 export { parseNodeLine, getNodeGrammar } from './node-parser.js';
@@ -21,6 +21,8 @@ export { parsePathLine, getPathGrammar } from './path-parser.js';
 export type { PathParseResult, PathStep } from './path-parser.js';
 export { parseFanOutLine, parseFanInLine } from './fan-parser.js';
 export type { FanOutParseResult, FanInParseResult, PortRef } from './fan-parser.js';
+export { parseCoerceLine } from './coerce-parser.js';
+export type { CoerceParseResult } from './coerce-parser.js';
 export { parseTriggerLine, parseCancelOnLine, parseRetriesLine, parseTimeoutLine, parseThrottleLine } from './trigger-cancel-parser.js';
 export type { TriggerParseResult, CancelOnParseResult, ThrottleParseResult } from './trigger-cancel-parser.js';
 export { generateGrammarDiagrams, getAllGrammars, serializedToEBNF } from './grammar-diagrams.js';

package/dist/chevrotain-parser/index.js

@@ -5,7 +5,7 @@
  * Provides structured parsing for @input, @output, @node, @connect, and @position.
  */
 // Token exports (for advanced use cases)
-export { JSDocLexer, allTokens, InputTag, OutputTag, NodeTag, ConnectTag, PositionTag, ScopeTag, MapTag, PathTag, FanOutTag, FanInTag, TriggerTag, CancelOnTag, RetriesTag, TimeoutTag, ThrottleTag, } from './tokens.js';
+export { JSDocLexer, allTokens, InputTag, OutputTag, NodeTag, ConnectTag, PositionTag, ScopeTag, MapTag, PathTag, FanOutTag, FanInTag, CoerceTag, TriggerTag, CancelOnTag, RetriesTag, TimeoutTag, ThrottleTag, } from './tokens.js';
 // Port parser
 export { parsePortLine, getPortGrammar } from './port-parser.js';
 // Node parser
@@ -22,6 +22,8 @@ export { parseMapLine, getMapGrammar } from './map-parser.js';
 export { parsePathLine, getPathGrammar } from './path-parser.js';
 // Fan-out / Fan-in parser
 export { parseFanOutLine, parseFanInLine } from './fan-parser.js';
+// Coerce parser
+export { parseCoerceLine } from './coerce-parser.js';
 // Trigger/cancel/retries/timeout/throttle parser
 export { parseTriggerLine, parseCancelOnLine, parseRetriesLine, parseTimeoutLine, parseThrottleLine } from './trigger-cancel-parser.js';
 // Grammar diagram generation

package/dist/chevrotain-parser/port-parser.js

@@ -4,7 +4,7 @@
  * Parser for @input/@output/@step port declarations using Chevrotain.
  */
 import { CstParser } from 'chevrotain';
-import { JSDocLexer, InputTag, OutputTag, StepTag, Identifier, ScopePrefix, OrderPrefix, PlacementPrefix, TypePrefix, MergeStrategyPrefix, TopKeyword, BottomKeyword, TrueKeyword, FalseKeyword, OverKeyword, MinimizedKeyword, Integer, StringLiteral, DescriptionText, LBracket, RBracket, LParen, RParen, Comma, Colon, Dot, Dash, Equals, GreaterThan, LessThan, Pipe, Ampersand, LBrace, RBrace, Asterisk, allTokens, } from './tokens.js';
+import { JSDocLexer, InputTag, OutputTag, StepTag, Identifier, ScopePrefix, OrderPrefix, PlacementPrefix, TypePrefix, MergeStrategyPrefix, TopKeyword, BottomKeyword, TrueKeyword, FalseKeyword, OverKeyword, AsKeyword, MinimizedKeyword, Integer, StringLiteral, DescriptionText, LBracket, RBracket, LParen, RParen, Comma, Colon, Dot, Dash, Equals, GreaterThan, LessThan, Pipe, Ampersand, LBrace, RBrace, Asterisk, allTokens, } from './tokens.js';
 // =============================================================================
 // Parser Definition
 // =============================================================================
@@ -160,6 +160,7 @@ class PortParser 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) },

package/dist/chevrotain-parser/tokens.d.ts

@@ -19,12 +19,14 @@ export declare const MapTag: import("chevrotain").TokenType;
 export declare const PathTag: import("chevrotain").TokenType;
 export declare const FanOutTag: import("chevrotain").TokenType;
 export declare const FanInTag: import("chevrotain").TokenType;
+export declare const CoerceTag: import("chevrotain").TokenType;
 export declare const TriggerTag: import("chevrotain").TokenType;
 export declare const CancelOnTag: import("chevrotain").TokenType;
 export declare const RetriesTag: import("chevrotain").TokenType;
 export declare const TimeoutTag: import("chevrotain").TokenType;
 export declare const ThrottleTag: import("chevrotain").TokenType;
 export declare const OverKeyword: import("chevrotain").TokenType;
+export declare const AsKeyword: import("chevrotain").TokenType;
 export declare const ParamTag: import("chevrotain").TokenType;
 export declare const ReturnsTag: import("chevrotain").TokenType;
 export declare const FlowWeaverTag: import("chevrotain").TokenType;

package/dist/chevrotain-parser/tokens.js

@@ -69,6 +69,10 @@ export const FanInTag = createToken({
     name: 'FanInTag',
     pattern: /@fanIn\b/,
 });
+export const CoerceTag = createToken({
+    name: 'CoerceTag',
+    pattern: /@coerce\b/,
+});
 export const TriggerTag = createToken({
     name: 'TriggerTag',
     pattern: /@trigger\b/,
@@ -93,6 +97,10 @@ export const OverKeyword = createToken({
     name: 'OverKeyword',
     pattern: /over\b/,
 });
+export const AsKeyword = createToken({
+    name: 'AsKeyword',
+    pattern: /as\b/,
+});
 export const ParamTag = createToken({
     name: 'ParamTag',
     pattern: /@param\b/,
@@ -325,6 +333,7 @@ export const allTokens = [
     PathTag,
     FanOutTag,
     FanInTag,
+    CoerceTag,
     TriggerTag,
     CancelOnTag,
     RetriesTag,
@@ -358,6 +367,7 @@ export const allTokens = [
     PeriodEq,
     // Keywords (before Identifier)
     OverKeyword,
+    AsKeyword,
     MinimizedKeyword,
     TopKeyword,
     BottomKeyword,

package/dist/cli/commands/compile.js

@@ -116,6 +116,9 @@ export 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}`;
@@ -123,6 +126,9 @@ export async function compileCommand(input, options = {}) {
                                     msg += ` (node: ${err.node})`;
                                 }
                                 logger.error(msg);
+                                if (err.docUrl) {
+                                    logger.info(`    See: ${err.docUrl}`);
+                                }
                             }
                         });
                         errorCount++;

package/dist/cli/commands/init.js

@@ -273,12 +273,14 @@ export function generateProjectFiles(projectName, template, format = 'esm') {
         ].join('\n');
     }
     const gitignore = `node_modules/\ndist/\n.tsbuildinfo\n`;
+    const configYaml = `defaultFileType: ts\n`;
     return {
         'package.json': packageJson,
         'tsconfig.json': tsconfigJson,
         [`src/${workflowFile}`]: workflowCode,
         'src/main.ts': mainTs,
         '.gitignore': gitignore,
+        '.flowweaver/config.yaml': configYaml,
     };
 }
 // ── Filesystem writer ────────────────────────────────────────────────────────