@synergenius/flow-weaver 0.2.0

package/dist/api/templates.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Public Template API
+ *
+ * Provides access to workflow and node templates for creating new flows.
+ * Templates are starters that can be customized for specific use cases.
+ *
+ * @module
+ */
+import { type WorkflowTemplate, type NodeTemplate, type WorkflowTemplateOptions } from "../cli/templates/index.js";
+export type { WorkflowTemplate, NodeTemplate, WorkflowTemplateOptions };
+/**
+ * List all available workflow templates
+ *
+ * @returns Array of workflow template definitions
+ *
+ * @example
+ * ```typescript
+ * const templates = listWorkflowTemplates();
+ * templates.forEach(t => console.log(`${t.id}: ${t.description}`));
+ * ```
+ */
+export declare function listWorkflowTemplates(): WorkflowTemplate[];
+/**
+ * List all available node templates
+ *
+ * @returns Array of node template definitions
+ *
+ * @example
+ * ```typescript
+ * const templates = listNodeTemplates();
+ * templates.forEach(t => console.log(`${t.id}: ${t.description}`));
+ * ```
+ */
+export declare function listNodeTemplates(): NodeTemplate[];
+/**
+ * Get a workflow template by ID
+ *
+ * @param id - Template identifier (e.g., "sequential", "foreach", "ai-agent")
+ * @returns Template definition or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const template = getWorkflowTemplate("sequential");
+ * if (template) {
+ *   console.log(template.description);
+ * }
+ * ```
+ */
+export declare function getWorkflowTemplate(id: string): WorkflowTemplate | undefined;
+/**
+ * Get a node template by ID
+ *
+ * @param id - Template identifier (e.g., "validator", "transformer", "llm-call")
+ * @returns Template definition or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const template = getNodeTemplate("validator");
+ * if (template) {
+ *   console.log(template.description);
+ * }
+ * ```
+ */
+export declare function getNodeTemplate(id: string): NodeTemplate | undefined;
+/**
+ * Generate workflow code from a template
+ *
+ * @param templateId - Template identifier
+ * @param options - Generation options including workflow name
+ * @returns Generated TypeScript code
+ * @throws Error if template not found
+ *
+ * @example
+ * ```typescript
+ * const code = generateWorkflowFromTemplate("sequential", {
+ *   workflowName: "processOrder",
+ *   async: true,
+ * });
+ * fs.writeFileSync("processOrder.ts", code);
+ * ```
+ */
+export declare function generateWorkflowFromTemplate(templateId: string, options: WorkflowTemplateOptions): string;
+/**
+ * Generate node type code from a template
+ *
+ * @param templateId - Template identifier
+ * @param name - Name for the generated node function
+ * @returns Generated TypeScript code
+ * @throws Error if template not found
+ *
+ * @example
+ * ```typescript
+ * const code = generateNodeFromTemplate("validator", "validateInput");
+ * // Insert into existing file or create new one
+ * ```
+ */
+export declare function generateNodeFromTemplate(templateId: string, name: string, config?: Record<string, unknown>): string;
+//# sourceMappingURL=templates.d.ts.map

package/dist/api/templates.js

@@ -0,0 +1,117 @@
+/**
+ * Public Template API
+ *
+ * Provides access to workflow and node templates for creating new flows.
+ * Templates are starters that can be customized for specific use cases.
+ *
+ * @module
+ */
+import { workflowTemplates, nodeTemplates, getWorkflowTemplate as getWorkflowTemplateById, getNodeTemplate as getNodeTemplateById, } from "../cli/templates/index.js";
+/**
+ * List all available workflow templates
+ *
+ * @returns Array of workflow template definitions
+ *
+ * @example
+ * ```typescript
+ * const templates = listWorkflowTemplates();
+ * templates.forEach(t => console.log(`${t.id}: ${t.description}`));
+ * ```
+ */
+export function listWorkflowTemplates() {
+    return workflowTemplates;
+}
+/**
+ * List all available node templates
+ *
+ * @returns Array of node template definitions
+ *
+ * @example
+ * ```typescript
+ * const templates = listNodeTemplates();
+ * templates.forEach(t => console.log(`${t.id}: ${t.description}`));
+ * ```
+ */
+export function listNodeTemplates() {
+    return nodeTemplates;
+}
+/**
+ * Get a workflow template by ID
+ *
+ * @param id - Template identifier (e.g., "sequential", "foreach", "ai-agent")
+ * @returns Template definition or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const template = getWorkflowTemplate("sequential");
+ * if (template) {
+ *   console.log(template.description);
+ * }
+ * ```
+ */
+export function getWorkflowTemplate(id) {
+    return getWorkflowTemplateById(id);
+}
+/**
+ * Get a node template by ID
+ *
+ * @param id - Template identifier (e.g., "validator", "transformer", "llm-call")
+ * @returns Template definition or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const template = getNodeTemplate("validator");
+ * if (template) {
+ *   console.log(template.description);
+ * }
+ * ```
+ */
+export function getNodeTemplate(id) {
+    return getNodeTemplateById(id);
+}
+/**
+ * Generate workflow code from a template
+ *
+ * @param templateId - Template identifier
+ * @param options - Generation options including workflow name
+ * @returns Generated TypeScript code
+ * @throws Error if template not found
+ *
+ * @example
+ * ```typescript
+ * const code = generateWorkflowFromTemplate("sequential", {
+ *   workflowName: "processOrder",
+ *   async: true,
+ * });
+ * fs.writeFileSync("processOrder.ts", code);
+ * ```
+ */
+export function generateWorkflowFromTemplate(templateId, options) {
+    const template = getWorkflowTemplateById(templateId);
+    if (!template) {
+        throw new Error(`Workflow template "${templateId}" not found`);
+    }
+    return template.generate(options);
+}
+/**
+ * Generate node type code from a template
+ *
+ * @param templateId - Template identifier
+ * @param name - Name for the generated node function
+ * @returns Generated TypeScript code
+ * @throws Error if template not found
+ *
+ * @example
+ * ```typescript
+ * const code = generateNodeFromTemplate("validator", "validateInput");
+ * // Insert into existing file or create new one
+ * ```
+ */
+export function generateNodeFromTemplate(templateId, name, config) {
+    const template = getNodeTemplateById(templateId);
+    if (!template) {
+        throw new Error(`Node template "${templateId}" not found`);
+    }
+    return template.generate(name, config);
+}
+//# sourceMappingURL=templates.js.map

package/dist/api/transform.d.ts

@@ -0,0 +1,31 @@
+import type { TASTTransformer, TWorkflowAST } from "../ast/types.js";
+/**
+ * Applies a single transformer to a workflow AST.
+ * The AST is deep-cloned before transformation to avoid mutating the original.
+ *
+ * @param ast - The workflow AST to transform.
+ * @param transformer - The transformer to apply.
+ * @returns A new, transformed workflow AST.
+ */
+export declare function transformWorkflow(ast: TWorkflowAST, transformer: TASTTransformer): TWorkflowAST;
+/**
+ * Applies an ordered sequence of transformers to a workflow AST.
+ * Each transformer receives the output of the previous one, and each step
+ * deep-clones its input via {@link transformWorkflow}.
+ *
+ * @param ast - The initial workflow AST.
+ * @param transformers - An ordered array of transformers to apply sequentially.
+ * @returns The final transformed workflow AST.
+ */
+export declare function applyTransformations(ast: TWorkflowAST, transformers: TASTTransformer[]): TWorkflowAST;
+/**
+ * Composes multiple transformers into a single transformer.
+ * The resulting transformer's name is a comma-separated list of the constituent names
+ * wrapped in "composed(...)". When invoked, it applies all transformers in order
+ * via {@link applyTransformations}.
+ *
+ * @param transformers - The transformers to compose.
+ * @returns A single composite transformer.
+ */
+export declare function composeTransformers(transformers: TASTTransformer[]): TASTTransformer;
+//# sourceMappingURL=transform.d.ts.map

package/dist/api/transform.js

@@ -0,0 +1,40 @@
+/**
+ * Applies a single transformer to a workflow AST.
+ * The AST is deep-cloned before transformation to avoid mutating the original.
+ *
+ * @param ast - The workflow AST to transform.
+ * @param transformer - The transformer to apply.
+ * @returns A new, transformed workflow AST.
+ */
+export function transformWorkflow(ast, transformer) {
+    const cloned = JSON.parse(JSON.stringify(ast));
+    return transformer.transform(cloned);
+}
+/**
+ * Applies an ordered sequence of transformers to a workflow AST.
+ * Each transformer receives the output of the previous one, and each step
+ * deep-clones its input via {@link transformWorkflow}.
+ *
+ * @param ast - The initial workflow AST.
+ * @param transformers - An ordered array of transformers to apply sequentially.
+ * @returns The final transformed workflow AST.
+ */
+export function applyTransformations(ast, transformers) {
+    return transformers.reduce((currentAST, transformer) => transformWorkflow(currentAST, transformer), ast);
+}
+/**
+ * Composes multiple transformers into a single transformer.
+ * The resulting transformer's name is a comma-separated list of the constituent names
+ * wrapped in "composed(...)". When invoked, it applies all transformers in order
+ * via {@link applyTransformations}.
+ *
+ * @param transformers - The transformers to compose.
+ * @returns A single composite transformer.
+ */
+export function composeTransformers(transformers) {
+    return {
+        name: `composed(${transformers.map((t) => t.name).join(", ")})`,
+        transform: (ast) => applyTransformations(ast, transformers),
+    };
+}
+//# sourceMappingURL=transform.js.map

package/dist/api/validate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Public API wrapper for workflow validation
+ *
+ * This module provides a simplified validation interface that uses
+ * the consolidated WorkflowValidator internally.
+ */
+import type { TValidationRule, TWorkflowAST } from "../ast/index.js";
+import { type TValidationError } from "../validator.js";
+export interface ValidationResult {
+    valid: boolean;
+    errors: TValidationError[];
+    warnings: TValidationError[];
+}
+/**
+ * Validates a workflow AST
+ *
+ * Runs the built-in validator, then agent-specific rules, then any custom rules.
+ * Agent rules are always applied automatically.
+ *
+ * @param ast - The workflow AST to validate
+ * @param customRules - Optional array of additional custom validation rules
+ * @returns ValidationResult with errors and warnings
+ */
+export declare function validateWorkflow(ast: TWorkflowAST, customRules?: TValidationRule[]): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/api/validate.js

@@ -0,0 +1,39 @@
+/**
+ * Public API wrapper for workflow validation
+ *
+ * This module provides a simplified validation interface that uses
+ * the consolidated WorkflowValidator internally.
+ */
+import { validator } from "../validator.js";
+import { getAgentValidationRules } from "../validation/agent-rules.js";
+/**
+ * Validates a workflow AST
+ *
+ * Runs the built-in validator, then agent-specific rules, then any custom rules.
+ * Agent rules are always applied automatically.
+ *
+ * @param ast - The workflow AST to validate
+ * @param customRules - Optional array of additional custom validation rules
+ * @returns ValidationResult with errors and warnings
+ */
+export function validateWorkflow(ast, customRules) {
+    // Use the consolidated validator
+    const result = validator.validate(ast);
+    // Apply agent-specific rules + any custom rules
+    const allRules = [...getAgentValidationRules(), ...(customRules || [])];
+    for (const rule of allRules) {
+        const ruleResults = rule.validate(ast);
+        for (const err of ruleResults) {
+            if (err.type === 'warning') {
+                result.warnings.push(err);
+            }
+            else {
+                result.errors.push(err);
+            }
+        }
+    }
+    // Re-evaluate validity
+    result.valid = result.errors.length === 0;
+    return result;
+}
+//# sourceMappingURL=validate.js.map

package/dist/api/workflow-file-operations.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Workflow File Operations
+ * Functions for adding, removing, and managing workflows in source files
+ */
+export interface WorkflowInfo {
+    name: string;
+    functionName: string;
+    isExported: boolean;
+}
+export interface AddWorkflowOptions {
+    exported?: boolean;
+}
+/**
+ * Add a new workflow function to the source code
+ */
+export declare function addWorkflowToSource(source: string, workflowName: string, options?: AddWorkflowOptions): string;
+/**
+ * Remove a workflow function from the source code
+ */
+export declare function removeWorkflowFromSource(source: string, workflowName: string): string;
+/**
+ * Toggle the export status of a workflow
+ */
+export declare function toggleWorkflowExport(source: string, workflowName: string): string;
+/**
+ * Get all available workflows from source code
+ */
+export declare function getAvailableWorkflows(source: string): WorkflowInfo[];
+//# sourceMappingURL=workflow-file-operations.d.ts.map

package/dist/api/workflow-file-operations.js

@@ -0,0 +1,180 @@
+/**
+ * Workflow File Operations
+ * Functions for adding, removing, and managing workflows in source files
+ */
+import * as ts from "typescript";
+// Marker for runtime section
+const RUNTIME_END_MARKER = "// @flow-weaver-runtime-end";
+/**
+ * Parse source and find all workflow functions
+ */
+function findWorkflowFunctions(source) {
+    const sourceFile = ts.createSourceFile("temp.ts", source, ts.ScriptTarget.Latest, true);
+    const workflows = [];
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            const functionName = node.name.text;
+            const functionStart = node.getFullStart();
+            const leadingComments = ts.getLeadingCommentRanges(source, functionStart);
+            if (!leadingComments)
+                return;
+            // Check for @flowWeaver workflow JSDoc
+            for (const comment of leadingComments) {
+                if (comment.kind === ts.SyntaxKind.MultiLineCommentTrivia) {
+                    const commentText = source.slice(comment.pos, comment.end);
+                    if (commentText.includes("@flowWeaver workflow")) {
+                        // Check for @name tag
+                        const nameMatch = commentText.match(/@name\s+(\S+)/);
+                        const name = nameMatch ? nameMatch[1] : functionName;
+                        const isExported = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+                        workflows.push({
+                            node,
+                            name,
+                            functionName,
+                            isExported,
+                            jsdocStart: comment.pos,
+                            jsdocEnd: comment.end,
+                        });
+                        break;
+                    }
+                }
+            }
+        }
+    });
+    return workflows;
+}
+/**
+ * Generate a new workflow function scaffold
+ */
+function generateWorkflowScaffold(workflowName, exported) {
+    const exportKeyword = exported ? "export " : "";
+    return `/**
+ * @flowWeaver workflow
+ */
+${exportKeyword}function ${workflowName}(execute: boolean, data: {}): { onSuccess: boolean; onFailure: boolean } {
+  throw new Error("Not implemented");
+}`;
+}
+/**
+ * Add a new workflow function to the source code
+ */
+export function addWorkflowToSource(source, workflowName, options = {}) {
+    const { exported = true } = options;
+    // Check if workflow already exists
+    const existingWorkflows = findWorkflowFunctions(source);
+    const exists = existingWorkflows.some((w) => w.name === workflowName || w.functionName === workflowName);
+    if (exists) {
+        throw new Error(`Workflow "${workflowName}" already exists`);
+    }
+    // Generate the new workflow
+    const newWorkflow = generateWorkflowScaffold(workflowName, exported);
+    // Find insertion point
+    let insertPosition;
+    // Try to insert after runtime section
+    const runtimeEndPos = source.indexOf(RUNTIME_END_MARKER);
+    if (runtimeEndPos !== -1) {
+        const afterMarker = source.indexOf("\n", runtimeEndPos);
+        insertPosition = afterMarker !== -1 ? afterMarker + 1 : runtimeEndPos + RUNTIME_END_MARKER.length;
+    }
+    else if (existingWorkflows.length > 0) {
+        // Insert before the first existing workflow
+        insertPosition = existingWorkflows[0].jsdocStart;
+    }
+    else {
+        // Insert at the end
+        insertPosition = source.length;
+    }
+    // Insert the new workflow
+    const before = source.slice(0, insertPosition);
+    const after = source.slice(insertPosition);
+    // Add proper spacing
+    const needsLeadingNewline = before.length > 0 && !before.endsWith("\n\n");
+    const needsTrailingNewline = after.length > 0 && !after.startsWith("\n");
+    return (before +
+        (needsLeadingNewline ? "\n\n" : "") +
+        newWorkflow +
+        (needsTrailingNewline ? "\n\n" : "") +
+        after);
+}
+/**
+ * Remove a workflow function from the source code
+ */
+export function removeWorkflowFromSource(source, workflowName) {
+    const workflows = findWorkflowFunctions(source);
+    // Find the workflow to remove
+    const workflowToRemove = workflows.find((w) => w.name === workflowName || w.functionName === workflowName);
+    if (!workflowToRemove) {
+        throw new Error(`Workflow "${workflowName}" not found`);
+    }
+    // Check if it's the last workflow
+    if (workflows.length === 1) {
+        throw new Error(`Cannot remove the last workflow from file`);
+    }
+    // Calculate the range to remove (including JSDoc and trailing newlines)
+    const startPos = workflowToRemove.jsdocStart;
+    let endPos = workflowToRemove.node.end;
+    // Include trailing newlines
+    while (endPos < source.length && (source[endPos] === '\n' || source[endPos] === '\r')) {
+        endPos++;
+    }
+    // Remove the workflow
+    const before = source.slice(0, startPos);
+    const after = source.slice(endPos);
+    return before + after;
+}
+/**
+ * Toggle the export status of a workflow
+ */
+export function toggleWorkflowExport(source, workflowName) {
+    const workflows = findWorkflowFunctions(source);
+    // Find the workflow to toggle
+    const workflow = workflows.find((w) => w.name === workflowName || w.functionName === workflowName);
+    if (!workflow) {
+        throw new Error(`Workflow "${workflowName}" not found`);
+    }
+    // Find the function keyword position
+    let functionKeywordPos = -1;
+    // Find the 'function' keyword
+    for (let i = workflow.jsdocEnd; i < source.length - 7; i++) {
+        if (source.slice(i, i + 8) === "function") {
+            functionKeywordPos = i;
+            break;
+        }
+        if (source.slice(i, i + 15) === "export function") {
+            functionKeywordPos = i;
+            break;
+        }
+    }
+    if (functionKeywordPos === -1) {
+        throw new Error(`Could not find function declaration for "${workflowName}"`);
+    }
+    if (workflow.isExported) {
+        // Remove 'export ' keyword
+        const exportPos = source.lastIndexOf("export", functionKeywordPos);
+        if (exportPos !== -1 && exportPos >= workflow.jsdocEnd) {
+            // Find the space after export
+            let spaceEnd = exportPos + 6;
+            while (spaceEnd < source.length && (source[spaceEnd] === ' ' || source[spaceEnd] === '\t')) {
+                spaceEnd++;
+            }
+            return source.slice(0, exportPos) + source.slice(spaceEnd);
+        }
+    }
+    else {
+        // Add 'export ' keyword before 'function'
+        return source.slice(0, functionKeywordPos) + "export " + source.slice(functionKeywordPos);
+    }
+    return source;
+}
+/**
+ * Get all available workflows from source code
+ */
+export function getAvailableWorkflows(source) {
+    const workflows = findWorkflowFunctions(source);
+    return workflows.map((w) => ({
+        name: w.name,
+        functionName: w.functionName,
+        isExported: w.isExported,
+    }));
+}
+//# sourceMappingURL=workflow-file-operations.js.map