@synergenius/flow-weaver 0.2.0

package/dist/api/manipulation/scopes.js

@@ -0,0 +1,156 @@
+/**
+ * Scope operations for workflow manipulation
+ */
+import { withoutValidation, assertNodeExists } from "../helpers.js";
+/**
+ * Create a new scope
+ *
+ * @param ast - Workflow to modify
+ * @param scopeName - Name of scope
+ * @param nodeIds - Node IDs in scope
+ * @returns Modified workflow
+ * @throws {Error} If scope already exists
+ */
+export function createScope(ast, scopeName, nodeIds) {
+    // Validate scope doesn't exist
+    if (ast.scopes?.[scopeName]) {
+        throw new Error(`Scope "${scopeName}" already exists`);
+    }
+    // Verify all nodes exist before mutation to avoid type instantiation issues
+    nodeIds.forEach((nodeId) => assertNodeExists(ast, nodeId));
+    return withoutValidation(ast, (draft) => {
+        if (!draft.scopes) {
+            draft.scopes = {};
+        }
+        draft.scopes[scopeName] = nodeIds;
+        // Update node instances to reference scope
+        // scopeName format is "parentNodeId.scopeName"
+        const dotIndex = scopeName.indexOf('.');
+        const parentNodeName = dotIndex > 0 ? scopeName.substring(0, dotIndex) : scopeName;
+        const scope = dotIndex > 0 ? scopeName.substring(dotIndex + 1) : '';
+        nodeIds.forEach((nodeId) => {
+            const node = draft.instances.find((n) => n.id === nodeId);
+            node.parent = { id: parentNodeName, scope };
+        });
+    });
+}
+/**
+ * Remove a scope.
+ * Uses no validation to allow deletion even when workflow has other errors.
+ *
+ * @param ast - Workflow to modify
+ * @param scopeName - Name of scope to remove
+ * @returns Modified workflow
+ */
+export function removeScope(ast, scopeName) {
+    // Verify scope exists
+    if (!ast.scopes?.[scopeName]) {
+        throw new Error(`Scope "${scopeName}" not found`);
+    }
+    return withoutValidation(ast, (draft) => {
+        const nodeIds = draft.scopes[scopeName];
+        // Remove parent from nodes
+        nodeIds.forEach((nodeId) => {
+            const node = draft.instances.find((n) => n.id === nodeId);
+            if (node) {
+                delete node.parent;
+            }
+        });
+        delete draft.scopes[scopeName];
+    });
+}
+/**
+ * Add node to existing scope
+ *
+ * @param ast - Workflow to modify
+ * @param scopeName - Name of scope
+ * @param nodeId - Node ID to add
+ * @returns Modified workflow
+ */
+export function addToScope(ast, scopeName, nodeId) {
+    // Validate before mutation to avoid type instantiation issues
+    if (!ast.scopes?.[scopeName]) {
+        throw new Error(`Scope "${scopeName}" not found`);
+    }
+    assertNodeExists(ast, nodeId);
+    return withoutValidation(ast, (draft) => {
+        if (!draft.scopes[scopeName].includes(nodeId)) {
+            draft.scopes[scopeName].push(nodeId);
+        }
+        const node = draft.instances.find((n) => n.id === nodeId);
+        if (!node)
+            return; // Already validated above
+        // scopeName format is "parentNodeId.scopeName"
+        const dotIndex = scopeName.indexOf('.');
+        const parentNodeName = dotIndex > 0 ? scopeName.substring(0, dotIndex) : scopeName;
+        const scope = dotIndex > 0 ? scopeName.substring(dotIndex + 1) : '';
+        node.parent = { id: parentNodeName, scope };
+    });
+}
+/**
+ * Remove node from scope.
+ * Uses no validation to allow deletion even when workflow has other errors.
+ *
+ * @param ast - Workflow to modify
+ * @param scopeName - Name of scope
+ * @param nodeId - Node ID to remove
+ * @returns Modified workflow
+ */
+export function removeFromScope(ast, scopeName, nodeId) {
+    // Verify scope exists
+    if (!ast.scopes?.[scopeName]) {
+        throw new Error(`Scope "${scopeName}" not found`);
+    }
+    return withoutValidation(ast, (draft) => {
+        draft.scopes[scopeName] = draft.scopes[scopeName].filter((id) => id !== nodeId);
+        const node = draft.instances.find((n) => n.id === nodeId);
+        if (node && node.parent) {
+            // Match by parent id (simple scope) or full qualified path
+            const matchesScope = node.parent.id === scopeName ||
+                (node.parent.scope && `${node.parent.id}.${node.parent.scope}` === scopeName);
+            if (matchesScope) {
+                delete node.parent;
+            }
+        }
+    });
+}
+/**
+ * Move node to different scope
+ *
+ * @param ast - Workflow to modify
+ * @param nodeId - Node ID to move
+ * @param targetScope - Target scope name
+ * @returns Modified workflow
+ */
+export function moveToScope(ast, nodeId, targetScope) {
+    // Validate before mutation to avoid type instantiation issues
+    assertNodeExists(ast, nodeId);
+    if (!ast.scopes?.[targetScope]) {
+        throw new Error(`Target scope "${targetScope}" not found`);
+    }
+    return withoutValidation(ast, (draft) => {
+        const node = draft.instances.find((n) => n.id === nodeId);
+        if (!node || !draft.scopes)
+            return; // Already validated above
+        // Remove from current scope if any
+        if (node.parent) {
+            // Check for simple scope (just id) or full qualified path
+            const simpleScope = node.parent.id;
+            const fullScope = node.parent.scope ? `${node.parent.id}.${node.parent.scope}` : null;
+            const currentScope = draft.scopes[simpleScope] ? simpleScope : (fullScope && draft.scopes[fullScope] ? fullScope : null);
+            if (currentScope && draft.scopes[currentScope]) {
+                draft.scopes[currentScope] = draft.scopes[currentScope].filter((id) => id !== nodeId);
+            }
+        }
+        // Add to target scope
+        if (!draft.scopes[targetScope].includes(nodeId)) {
+            draft.scopes[targetScope].push(nodeId);
+        }
+        // targetScope format is "parentNodeId.scopeName"
+        const dotIndex = targetScope.indexOf('.');
+        const parentNodeName = dotIndex > 0 ? targetScope.substring(0, dotIndex) : targetScope;
+        const scope = dotIndex > 0 ? targetScope.substring(dotIndex + 1) : '';
+        node.parent = { id: parentNodeName, scope };
+    });
+}
+//# sourceMappingURL=scopes.js.map

package/dist/api/manipulation/validation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validation wrappers for workflow manipulation operations
+ * Re-exports from helpers.ts for backward compatibility
+ */
+export { withoutValidation, type RemoveOptions, type NodeFilter, type OperationResult, validatePortReference, portReferencesEqual, formatPortReference, generateUniqueNodeId, assertNodeExists, assertNodeNotExists, } from "../helpers.js";
+//# sourceMappingURL=validation.d.ts.map

package/dist/api/manipulation/validation.js

@@ -0,0 +1,6 @@
+/**
+ * Validation wrappers for workflow manipulation operations
+ * Re-exports from helpers.ts for backward compatibility
+ */
+export { withoutValidation, validatePortReference, portReferencesEqual, formatPortReference, generateUniqueNodeId, assertNodeExists, assertNodeNotExists, } from "../helpers.js";
+//# sourceMappingURL=validation.js.map

package/dist/api/manipulation/workflow.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Workflow-level operations for manipulation
+ */
+import type { TWorkflowAST, TWorkflowMetadata, TNodeTypePort } from "../../ast/types.js";
+/**
+ * Clone a workflow (creates deep copy via Immer)
+ *
+ * @param ast - Workflow to clone
+ * @returns New workflow instance
+ *
+ * @example
+ * ```typescript
+ * const copy = cloneWorkflow(original);
+ * // copy !== original
+ * ```
+ */
+export declare function cloneWorkflow(ast: TWorkflowAST): TWorkflowAST;
+/**
+ * Set workflow description
+ *
+ * @param ast - Workflow to modify
+ * @param description - New description
+ * @returns Modified workflow
+ */
+export declare function setWorkflowDescription(ast: TWorkflowAST, description: string): TWorkflowAST;
+/**
+ * Set workflow metadata (forceAsync, etc.)
+ *
+ * @param ast - Workflow to modify
+ * @param metadata - Partial metadata to merge
+ * @returns Modified workflow
+ *
+ * @example
+ * ```typescript
+ * const updated = setWorkflowMetadata(workflow, { forceAsync: true });
+ * ```
+ */
+export declare function setWorkflowMetadata(ast: TWorkflowAST, metadata: Partial<TWorkflowMetadata>): TWorkflowAST;
+/**
+ * Set workflow output file type
+ *
+ * @param ast - Workflow to modify
+ * @param fileType - Target file extension
+ * @returns Modified workflow
+ *
+ * @example
+ * ```typescript
+ * const updated = setOutputFileType(workflow, "tsx");
+ * ```
+ */
+export declare function setOutputFileType(ast: TWorkflowAST, fileType: "js" | "ts" | "jsx" | "tsx"): TWorkflowAST;
+/**
+ * Rename workflow export
+ *
+ * @param ast - Workflow to modify
+ * @param newName - New workflow export name
+ * @returns Modified workflow
+ *
+ * @example
+ * ```typescript
+ * const updated = renameWorkflow(workflow, "myNewWorkflow");
+ * ```
+ */
+export declare function renameWorkflow(ast: TWorkflowAST, newName: string): TWorkflowAST;
+/**
+ * Set workflow export interface ports
+ *
+ * @param ast - Workflow to modify
+ * @param ports - New ports configuration
+ * @returns Modified workflow
+ *
+ * @example
+ * ```typescript
+ * const updated = setWorkflowPorts(workflow, [
+ *   { name: "input", type: "String", direction: "input" },
+ *   { name: "result", type: "Number", direction: "output" }
+ * ]);
+ * ```
+ */
+export declare function setWorkflowPorts(ast: TWorkflowAST, ports: TNodeTypePort[]): TWorkflowAST;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/api/manipulation/workflow.js

@@ -0,0 +1,116 @@
+/**
+ * Workflow-level operations for manipulation
+ */
+import { produce } from "immer";
+import { withoutValidation } from "../helpers.js";
+/**
+ * Clone a workflow (creates deep copy via Immer)
+ *
+ * @param ast - Workflow to clone
+ * @returns New workflow instance
+ *
+ * @example
+ * ```typescript
+ * const copy = cloneWorkflow(original);
+ * // copy !== original
+ * ```
+ */
+export function cloneWorkflow(ast) {
+    // Force Immer to create a new object by making changes to nested structures
+    // Without this, Immer returns the same object (structural sharing)
+    return withoutValidation(ast, (draft) => {
+        // Touch nested arrays to force deep cloning
+        draft.nodeTypes = [...draft.nodeTypes];
+        draft.instances = [...draft.instances];
+        draft.connections = [...draft.connections];
+    });
+}
+/**
+ * Set workflow description
+ *
+ * @param ast - Workflow to modify
+ * @param description - New description
+ * @returns Modified workflow
+ */
+export function setWorkflowDescription(ast, description) {
+    return withoutValidation(ast, (draft) => {
+        draft.description = description;
+    });
+}
+/**
+ * Set workflow metadata (forceAsync, etc.)
+ *
+ * @param ast - Workflow to modify
+ * @param metadata - Partial metadata to merge
+ * @returns Modified workflow
+ *
+ * @example
+ * ```typescript
+ * const updated = setWorkflowMetadata(workflow, { forceAsync: true });
+ * ```
+ */
+export function setWorkflowMetadata(ast, metadata) {
+    return withoutValidation(ast, (draft) => {
+        draft.metadata = { ...draft.metadata, ...metadata };
+    });
+}
+/**
+ * Set workflow output file type
+ *
+ * @param ast - Workflow to modify
+ * @param fileType - Target file extension
+ * @returns Modified workflow
+ *
+ * @example
+ * ```typescript
+ * const updated = setOutputFileType(workflow, "tsx");
+ * ```
+ */
+export function setOutputFileType(ast, fileType) {
+    return withoutValidation(ast, (draft) => {
+        const baseName = draft.sourceFile.replace(/\.(ts|js|tsx|jsx)$/, "");
+        draft.sourceFile = `${baseName}.${fileType}`;
+    });
+}
+/**
+ * Rename workflow export
+ *
+ * @param ast - Workflow to modify
+ * @param newName - New workflow export name
+ * @returns Modified workflow
+ *
+ * @example
+ * ```typescript
+ * const updated = renameWorkflow(workflow, "myNewWorkflow");
+ * ```
+ */
+export function renameWorkflow(ast, newName) {
+    if (!newName || !/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(newName)) {
+        throw new Error(`Invalid workflow name: ${newName}`);
+    }
+    return withoutValidation(ast, (draft) => {
+        draft.functionName = newName;
+    });
+}
+/**
+ * Set workflow export interface ports
+ *
+ * @param ast - Workflow to modify
+ * @param ports - New ports configuration
+ * @returns Modified workflow
+ *
+ * @example
+ * ```typescript
+ * const updated = setWorkflowPorts(workflow, [
+ *   { name: "input", type: "String", direction: "input" },
+ *   { name: "result", type: "Number", direction: "output" }
+ * ]);
+ * ```
+ */
+export function setWorkflowPorts(ast, ports) {
+    // Use produce directly with non-generic approach to avoid excessive type instantiation
+    return produce(ast, (draft) => {
+        draft.ports = ports;
+    });
+}
+//# sourceMappingURL=workflow.js.map

package/dist/api/manipulation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Manipulation API for programmatic workflow creation and modification
+ * All operations are immutable (return new AST) and validated
+ *
+ * This file re-exports all functions from the manipulation module for backward compatibility.
+ */
+export * from "./manipulation/index.js";
+//# sourceMappingURL=manipulation.d.ts.map

package/dist/api/manipulation.js

@@ -0,0 +1,8 @@
+/**
+ * Manipulation API for programmatic workflow creation and modification
+ * All operations are immutable (return new AST) and validated
+ *
+ * This file re-exports all functions from the manipulation module for backward compatibility.
+ */
+export * from "./manipulation/index.js";
+//# sourceMappingURL=manipulation.js.map

package/dist/api/parse.d.ts

@@ -0,0 +1,48 @@
+import type { TParseOptions as ASTParseOptions, TWorkflowAST } from '../ast/types.js';
+export interface ParseOptions extends Partial<ASTParseOptions> {
+    /**
+     * Name of the workflow to parse from the file.
+     * Required if the file contains multiple workflows.
+     */
+    workflowName?: string;
+    /**
+     * When true, returns node types even if no workflows are found.
+     * Useful for files that only contain node type definitions.
+     */
+    nodeTypesOnly?: boolean;
+}
+export interface ParseResult {
+    ast: TWorkflowAST;
+    errors: string[];
+    warnings: string[];
+    /**
+     * All workflows found in the file (names only)
+     */
+    availableWorkflows: string[];
+    /**
+     * All workflow ASTs found in the file (for local dependency generation)
+     */
+    allWorkflows: TWorkflowAST[];
+}
+/**
+ * Parse a workflow file and convert it to AST
+ *
+ * @param filePath - Path to the workflow file
+ * @param options - Parse options including workflow name
+ * @returns ParseResult with AST, errors, and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await parseWorkflow('./my-workflow.ts', {
+ *   workflowName: 'myWorkflow'
+ * });
+ *
+ * if (result.errors.length > 0) {
+ *   console.error('Parse errors:', result.errors);
+ * } else {
+ *   console.log('Parsed workflow:', result.ast.functionName);
+ * }
+ * ```
+ */
+export declare function parseWorkflow(filePath: string, options?: ParseOptions): Promise<ParseResult>;
+//# sourceMappingURL=parse.d.ts.map

package/dist/api/parse.js

@@ -0,0 +1,110 @@
+import { parser } from '../parser.js';
+import { getErrorMessage } from '../utils/error-utils.js';
+/**
+ * Parse a workflow file and convert it to AST
+ *
+ * @param filePath - Path to the workflow file
+ * @param options - Parse options including workflow name
+ * @returns ParseResult with AST, errors, and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await parseWorkflow('./my-workflow.ts', {
+ *   workflowName: 'myWorkflow'
+ * });
+ *
+ * if (result.errors.length > 0) {
+ *   console.error('Parse errors:', result.errors);
+ * } else {
+ *   console.log('Parsed workflow:', result.ast.functionName);
+ * }
+ * ```
+ */
+export async function parseWorkflow(filePath, options) {
+    const errors = [];
+    const warnings = [];
+    let availableWorkflows = [];
+    try {
+        // Parse the file to extract nodes and workflows
+        const parsed = parser.parse(filePath);
+        warnings.push(...parsed.warnings);
+        // Get available workflow names
+        availableWorkflows = parsed.workflows.map((w) => w.functionName);
+        // Determine which workflow to use
+        let workflowName = options?.workflowName;
+        if (!workflowName) {
+            if (parsed.workflows.length === 0) {
+                // If nodeTypesOnly mode is enabled and we have node types, return them
+                if (options?.nodeTypesOnly && parsed.nodeTypes.length > 0) {
+                    return {
+                        ast: {
+                            type: 'Workflow',
+                            functionName: '',
+                            name: '',
+                            sourceFile: filePath,
+                            nodeTypes: parsed.nodeTypes,
+                            instances: [],
+                            connections: [],
+                            scopes: {},
+                            startPorts: {},
+                            exitPorts: {},
+                            imports: [],
+                        },
+                        errors: [],
+                        warnings,
+                        availableWorkflows: [],
+                        allWorkflows: [],
+                    };
+                }
+                const nodeTypeCount = parsed.nodeTypes.length;
+                const nodeTypeHint = nodeTypeCount > 0
+                    ? ` (found ${nodeTypeCount} node type${nodeTypeCount === 1 ? '' : 's'}, but no workflow function)`
+                    : '';
+                errors.push(`No workflows found in file${nodeTypeHint}. Add a /** @flowWeaver workflow */ annotation above an exported function to define a workflow. Ensure node type functions are annotated with /** @flowWeaver nodeType */ first.`);
+                throw new Error('No workflows found in file');
+            }
+            if (parsed.workflows.length > 1) {
+                errors.push(`[MULTIPLE_WORKFLOWS_FOUND] Multiple workflows found: ${availableWorkflows.join(', ')}. Please specify workflowName in options.`);
+                throw new Error('Multiple workflows found, workflowName required');
+            }
+            // Single workflow found, use it
+            workflowName = parsed.workflows[0].functionName;
+        }
+        // Find the workflow
+        const workflow = parsed.workflows.find((w) => w.functionName === workflowName);
+        if (!workflow) {
+            errors.push(`Workflow "${workflowName}" not found. Available: ${availableWorkflows.join(', ')}`);
+            throw new Error(`Workflow "${workflowName}" not found`);
+        }
+        return {
+            ast: workflow,
+            errors: [],
+            warnings,
+            availableWorkflows,
+            allWorkflows: parsed.workflows,
+        };
+    }
+    catch (error) {
+        // If we already added errors, return with availableWorkflows
+        if (errors.length > 0) {
+            return {
+                ast: {}, // Return empty AST on error
+                errors,
+                warnings,
+                availableWorkflows, // Include available workflows even on error
+                allWorkflows: [],
+            };
+        }
+        // Handle unexpected errors
+        const errorMessage = getErrorMessage(error);
+        errors.push(`Failed to parse workflow: ${errorMessage}`);
+        return {
+            ast: {},
+            errors,
+            warnings,
+            availableWorkflows,
+            allWorkflows: [],
+        };
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/api/patterns.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Pure pattern API — no I/O, no console, no filesystem writes.
+ *
+ * Provides business logic for listing patterns, applying patterns to workflows,
+ * and generating node type code. CLI and MCP layers call these functions
+ * and handle their own I/O.
+ */
+import type { TPatternAST, TNodeTypeAST, TWorkflowAST } from '../ast/types.js';
+export interface PatternInfo {
+    name: string;
+    description?: string;
+    inputPorts: Array<{
+        name: string;
+        description?: string;
+    }>;
+    outputPorts: Array<{
+        name: string;
+        description?: string;
+    }>;
+    nodes: string[];
+}
+export interface WorkflowFileInfo {
+    filePath: string;
+    workflows: Array<{
+        name: string;
+        functionName: string;
+        nodeCount: number;
+        connectionCount: number;
+    }>;
+}
+export interface ExtractPatternOptions {
+    workflowAST: TWorkflowAST;
+    nodeTypes: TNodeTypeAST[];
+    nodeIds: string[];
+    name?: string;
+}
+export interface ExtractPatternResult {
+    patternCode: string;
+    patternName: string;
+    nodes: string[];
+    inputPorts: string[];
+    outputPorts: string[];
+    internalConnectionCount: number;
+}
+export interface ApplyPatternOptions {
+    /** The pattern AST to apply */
+    patternAST: TPatternAST;
+    /** Raw text content of the target workflow file */
+    targetContent: string;
+    /** Node type names already present in the target workflow */
+    targetNodeTypes: Set<string>;
+    /** Optional prefix for node IDs to avoid conflicts */
+    prefix?: string;
+}
+export interface ApplyPatternResult {
+    /** Modified file content with the pattern applied */
+    modifiedContent: string;
+    /** Number of node instances added */
+    nodesAdded: number;
+    /** Number of connections added */
+    connectionsAdded: number;
+    /** Names of node types added (those not already in the target) */
+    nodeTypesAdded: string[];
+    /** Node type names that conflict (exist in both pattern and target) */
+    conflicts: string[];
+    /** Human-readable instructions for wiring IN/OUT ports */
+    wiringInstructions: string[];
+    /** Structured fw_modify_batch operations for wiring IN/OUT ports */
+    wiringOperations: Array<{
+        operation: 'addConnection';
+        params: {
+            from: string;
+            to: string;
+        };
+    }>;
+}
+/**
+ * Parse a file and return metadata for all patterns found.
+ *
+ * Pure: reads file via AnnotationParser, returns structured data.
+ */
+export declare function listPatterns(filePath: string): PatternInfo[];
+/**
+ * Compute the result of applying a pattern to a workflow.
+ *
+ * Pure: takes AST + content + options, returns the modified content
+ * and structured metadata (conflicts, wiring instructions, etc.).
+ * Does **not** write to disk.
+ */
+export declare function applyPattern(options: ApplyPatternOptions): ApplyPatternResult;
+/**
+ * Generate a TypeScript stub for a node type.
+ *
+ * Produces a JSDoc-annotated function with the correct ports.
+ */
+export declare function generateNodeTypeCode(nodeType: TNodeTypeAST): string;
+/**
+ * Scan a directory for files containing @flowWeaver workflow annotations
+ * and return structured metadata for each.
+ *
+ * Pure: reads files via AnnotationParser, returns structured data.
+ * Skips files that fail to parse.
+ */
+export declare function findWorkflows(directory: string, pattern?: string): Promise<WorkflowFileInfo[]>;
+/**
+ * Extract a reusable pattern from selected nodes in a workflow.
+ *
+ * Pure: takes AST + node IDs, returns pattern code and metadata.
+ * Does **not** write to disk.
+ */
+export declare function extractPattern(options: ExtractPatternOptions): ExtractPatternResult;
+//# sourceMappingURL=patterns.d.ts.map