@synergenius/flow-weaver 0.33.2 → 0.44.0

package/dist/runtime/checkpoint.js

@@ -1,225 +0,0 @@
-/**
- * Checkpoint serialization for crash recovery.
- *
- * Writes workflow state to disk after each node completes. If the process
- * crashes, the checkpoint file persists and can be used to resume execution
- * from the last completed node.
- *
- * Checkpoint files live in .fw-checkpoints/ next to the workflow file and
- * are auto-deleted after successful workflow completion.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as crypto from 'crypto';
-// ---------------------------------------------------------------------------
-// Serialization helpers
-// ---------------------------------------------------------------------------
-function isUnserializableMarker(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        value.__fw_unserializable__ === true);
-}
-/**
- * Try to serialize a value. If it contains functions, invoke them first.
- * If serialization fails, return a marker.
- */
-function serializeValue(key, value, unsafeNodes) {
-    // Resolve function values (pull execution lazy evaluation)
-    if (typeof value === 'function') {
-        try {
-            value = value();
-        }
-        catch {
-            const parts = key.split(':');
-            unsafeNodes.add(parts[0]);
-            return {
-                __fw_unserializable__: true,
-                nodeId: parts[0],
-                portName: parts[1] || 'unknown',
-                reason: 'Function invocation failed',
-            };
-        }
-    }
-    // Handle Promises: can't serialize, mark as unsafe
-    if (value instanceof Promise) {
-        const parts = key.split(':');
-        unsafeNodes.add(parts[0]);
-        return {
-            __fw_unserializable__: true,
-            nodeId: parts[0],
-            portName: parts[1] || 'unknown',
-            reason: 'Promise value',
-        };
-    }
-    // Test serialization
-    try {
-        JSON.stringify(value);
-        return value;
-    }
-    catch {
-        const parts = key.split(':');
-        unsafeNodes.add(parts[0]);
-        return {
-            __fw_unserializable__: true,
-            nodeId: parts[0],
-            portName: parts[1] || 'unknown',
-            reason: 'Not JSON-serializable',
-        };
-    }
-}
-/**
- * Compute SHA-256 hash of a file's contents.
- */
-function hashFile(filePath) {
-    const content = fs.readFileSync(filePath, 'utf8');
-    return crypto.createHash('sha256').update(content).digest('hex');
-}
-// ---------------------------------------------------------------------------
-// CheckpointWriter
-// ---------------------------------------------------------------------------
-export class CheckpointWriter {
-    dir;
-    filePath;
-    workflowName;
-    runId;
-    params;
-    workflowHash;
-    checkpointPath;
-    writeLock = Promise.resolve();
-    constructor(workflowFilePath, workflowName, runId, params = {}) {
-        this.filePath = path.resolve(workflowFilePath);
-        this.workflowName = workflowName;
-        this.runId = runId;
-        this.params = params;
-        this.dir = path.join(path.dirname(this.filePath), '.fw-checkpoints');
-        this.checkpointPath = path.join(this.dir, `${workflowName}-${runId}.json`);
-        this.workflowHash = hashFile(this.filePath);
-    }
-    /**
-     * Write a checkpoint after a node completes. Uses a write lock so
-     * concurrent calls from parallel nodes are serialized.
-     */
-    async write(completedNodes, executionOrder, position, ctx) {
-        // Serialize under a lock to prevent concurrent writes (parallel nodes)
-        this.writeLock = this.writeLock.then(() => this._writeCheckpoint(completedNodes, executionOrder, position, ctx));
-        await this.writeLock;
-    }
-    /** Clean up checkpoint file after successful completion */
-    cleanup() {
-        try {
-            if (fs.existsSync(this.checkpointPath)) {
-                fs.unlinkSync(this.checkpointPath);
-            }
-            // Remove directory if empty
-            if (fs.existsSync(this.dir)) {
-                const remaining = fs.readdirSync(this.dir);
-                if (remaining.length === 0) {
-                    fs.rmdirSync(this.dir);
-                }
-            }
-        }
-        catch {
-            // Best-effort cleanup
-        }
-    }
-    getCheckpointPath() {
-        return this.checkpointPath;
-    }
-    _writeCheckpoint(completedNodes, executionOrder, position, ctx) {
-        const serialized = ctx.serialize();
-        const unsafeNodes = new Set();
-        // Serialize variables, handling unserializable values
-        const variables = {};
-        for (const [key, value] of Object.entries(serialized.variables)) {
-            variables[key] = serializeValue(key, value, unsafeNodes);
-        }
-        const data = {
-            version: 1,
-            workflowHash: this.workflowHash,
-            workflowName: this.workflowName,
-            filePath: this.filePath,
-            params: this.params,
-            timestamp: new Date().toISOString(),
-            completedNodes: [...completedNodes],
-            executionOrder: [...executionOrder],
-            position,
-            variables,
-            executions: serialized.executions,
-            executionCounter: serialized.executionCounter,
-            nodeExecutionCounts: serialized.nodeExecutionCounts,
-            unsafeNodes: [...unsafeNodes],
-        };
-        // Ensure directory exists
-        if (!fs.existsSync(this.dir)) {
-            fs.mkdirSync(this.dir, { recursive: true });
-        }
-        fs.writeFileSync(this.checkpointPath, JSON.stringify(data, null, 2), 'utf8');
-    }
-}
-// ---------------------------------------------------------------------------
-// Checkpoint reading and resume
-// ---------------------------------------------------------------------------
-/**
- * Load a checkpoint file and validate it against the current workflow.
- * Returns the checkpoint data and a list of nodes that need to be re-run
- * (because their outputs weren't serializable).
- */
-export function loadCheckpoint(checkpointPath, workflowFilePath) {
-    const raw = fs.readFileSync(checkpointPath, 'utf8');
-    const data = JSON.parse(raw);
-    if (data.version !== 1) {
-        throw new Error(`Unsupported checkpoint version: ${data.version}`);
-    }
-    // Check if the workflow has changed since the checkpoint was written
-    let stale = false;
-    if (workflowFilePath) {
-        const currentHash = hashFile(path.resolve(workflowFilePath));
-        stale = currentHash !== data.workflowHash;
-    }
-    // Determine which nodes can be skipped (all outputs serialized) vs
-    // which need re-running (any output was unserializable)
-    const unsafeSet = new Set(data.unsafeNodes);
-    const rerunNodes = [];
-    const skipNodes = new Map();
-    // Walk execution order up to the checkpoint position.
-    // Once we hit an unsafe node, everything from that point forward re-runs.
-    let hitUnsafe = false;
-    for (const nodeId of data.completedNodes) {
-        if (hitUnsafe || unsafeSet.has(nodeId)) {
-            hitUnsafe = true;
-            rerunNodes.push(nodeId);
-            continue;
-        }
-        // Collect this node's outputs from the variables map
-        const nodeOutputs = {};
-        const prefix = `${nodeId}:`;
-        for (const [key, value] of Object.entries(data.variables)) {
-            if (key.startsWith(prefix) && !isUnserializableMarker(value)) {
-                // Store with portName:executionIndex as key
-                const rest = key.substring(prefix.length);
-                nodeOutputs[rest] = value;
-            }
-        }
-        skipNodes.set(nodeId, nodeOutputs);
-    }
-    return { data, stale, rerunNodes, skipNodes };
-}
-/**
- * Find the most recent checkpoint file for a workflow.
- */
-export function findLatestCheckpoint(workflowFilePath, workflowName) {
-    const dir = path.join(path.dirname(path.resolve(workflowFilePath)), '.fw-checkpoints');
-    if (!fs.existsSync(dir))
-        return null;
-    const files = fs.readdirSync(dir)
-        .filter((f) => f.endsWith('.json'))
-        .filter((f) => !workflowName || f.startsWith(`${workflowName}-`));
-    if (files.length === 0)
-        return null;
-    // Sort by modification time, newest first
-    const sorted = files
-        .map((f) => ({ name: f, mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
-        .sort((a, b) => b.mtime - a.mtime);
-    return path.join(dir, sorted[0].name);
-}
-//# sourceMappingURL=checkpoint.js.map

package/dist/runtime/debug-controller.js

@@ -1,247 +0,0 @@
-/**
- * DebugController intercepts workflow execution at node boundaries,
- * enabling step-through debugging and checkpoint/resume.
- *
- * Injected via globalThis.__fw_debug_controller__ (same pattern as
- * __fw_debugger__ and __fw_agent_channel__). The generated code calls
- * beforeNode/afterNode at each node boundary; the controller decides
- * whether to skip, pause, checkpoint, or continue.
- */
-// ---------------------------------------------------------------------------
-// DebugController
-// ---------------------------------------------------------------------------
-export class DebugController {
-    mode;
-    breakpoints;
-    completedNodes = [];
-    completedSet = new Set();
-    executionOrder = [];
-    position = 0;
-    lastCompletedNodeId = null;
-    // Checkpoint
-    checkpointEnabled;
-    checkpointWriter;
-    // Skip nodes (for resume from checkpoint)
-    skipNodes;
-    // Pause/resume channel (mirrors AgentChannel pattern)
-    _gateResolve = null;
-    _pauseResolve = null;
-    _pausePromise;
-    // Variable modification buffer: applied before next node runs
-    pendingModifications = new Map();
-    constructor(config = {}) {
-        this.mode = config.debug ? 'step' : 'run';
-        this.breakpoints = new Set(config.breakpoints ?? []);
-        this.checkpointEnabled = config.checkpoint ?? false;
-        this.checkpointWriter = config.checkpointWriter ?? null;
-        this.executionOrder = config.executionOrder ?? [];
-        this.skipNodes = config.skipNodes ?? new Map();
-        this._pausePromise = this._createPausePromise();
-    }
-    /** Set the execution order (called by executor after compilation) */
-    setExecutionOrder(order) {
-        this.executionOrder = order;
-    }
-    // -----------------------------------------------------------------------
-    // Node boundary hooks (called by generated code)
-    // -----------------------------------------------------------------------
-    /**
-     * Called before a node executes.
-     * Returns true if the node should execute, false to skip.
-     */
-    async beforeNode(nodeId, ctx) {
-        // Apply any pending variable modifications
-        this.applyPendingModifications(ctx);
-        // If this node should be skipped (resume from checkpoint), restore its
-        // outputs into the context and return false
-        if (this.skipNodes.has(nodeId)) {
-            const savedOutputs = this.skipNodes.get(nodeId);
-            this.restoreNodeOutputs(nodeId, savedOutputs, ctx);
-            this.completedNodes.push(nodeId);
-            this.completedSet.add(nodeId);
-            this.lastCompletedNodeId = nodeId;
-            this.position++;
-            return false;
-        }
-        // Check if we should pause here
-        const shouldPause = this.mode === 'step' ||
-            (this.mode === 'continueToBreakpoint' && this.breakpoints.has(nodeId));
-        if (shouldPause) {
-            const action = await this.pause(nodeId, 'before', ctx);
-            if (action.type === 'abort') {
-                throw new Error(`Debug session aborted at node "${nodeId}"`);
-            }
-            // Action may change mode for subsequent nodes
-            this.applyAction(action);
-        }
-        return true;
-    }
-    /**
-     * Called after a node completes successfully.
-     */
-    async afterNode(nodeId, ctx) {
-        this.completedNodes.push(nodeId);
-        this.completedSet.add(nodeId);
-        this.lastCompletedNodeId = nodeId;
-        this.position++;
-        // Write checkpoint to disk
-        if (this.checkpointEnabled && this.checkpointWriter) {
-            await this.checkpointWriter.write(this.completedNodes, this.executionOrder, this.position, ctx);
-        }
-        // Pause after node in step mode
-        if (this.mode === 'step') {
-            const action = await this.pause(nodeId, 'after', ctx);
-            if (action.type === 'abort') {
-                throw new Error(`Debug session aborted after node "${nodeId}"`);
-            }
-            this.applyAction(action);
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Pause/resume channel
-    // -----------------------------------------------------------------------
-    /**
-     * Awaited by the executor to detect when the controller pauses.
-     * Resolves with the current debug state.
-     */
-    onPause() {
-        return this._pausePromise;
-    }
-    /**
-     * Called by MCP tools or CLI to resume execution.
-     */
-    resume(action) {
-        if (action.type !== 'abort') {
-            this.applyAction(action);
-        }
-        this._gateResolve?.(action);
-        this._gateResolve = null;
-        this._pausePromise = this._createPausePromise();
-    }
-    // -----------------------------------------------------------------------
-    // Variable modification
-    // -----------------------------------------------------------------------
-    /**
-     * Queue a variable modification. Applied before the next node runs.
-     * Key format: "nodeId:portName:executionIndex"
-     */
-    setVariable(key, value) {
-        this.pendingModifications.set(key, value);
-    }
-    // -----------------------------------------------------------------------
-    // Breakpoints
-    // -----------------------------------------------------------------------
-    addBreakpoint(nodeId) {
-        this.breakpoints.add(nodeId);
-    }
-    removeBreakpoint(nodeId) {
-        this.breakpoints.delete(nodeId);
-    }
-    getBreakpoints() {
-        return [...this.breakpoints];
-    }
-    // -----------------------------------------------------------------------
-    // State inspection
-    // -----------------------------------------------------------------------
-    /** Build the current debug state for external consumers */
-    buildState(nodeId, phase, ctx) {
-        const variables = this.extractVariables(ctx);
-        const currentNodeOutputs = this.lastCompletedNodeId
-            ? this.extractNodeOutputs(this.lastCompletedNodeId, variables)
-            : undefined;
-        return {
-            currentNodeId: nodeId,
-            phase,
-            completedNodes: [...this.completedNodes],
-            executionOrder: [...this.executionOrder],
-            position: this.position,
-            variables,
-            currentNodeOutputs,
-            breakpoints: [...this.breakpoints],
-        };
-    }
-    /** Get completed nodes list */
-    getCompletedNodes() {
-        return [...this.completedNodes];
-    }
-    // -----------------------------------------------------------------------
-    // Internal helpers
-    // -----------------------------------------------------------------------
-    async pause(nodeId, phase, ctx) {
-        const state = this.buildState(nodeId, phase, ctx);
-        // Signal the executor that we're paused
-        this._pauseResolve?.(state);
-        // Suspend on a gate Promise until resume() is called
-        return new Promise((resolve) => {
-            this._gateResolve = (action) => resolve(action);
-        });
-    }
-    applyAction(action) {
-        switch (action.type) {
-            case 'step':
-                this.mode = 'step';
-                break;
-            case 'continue':
-                this.mode = 'continue';
-                break;
-            case 'continueToBreakpoint':
-                this.mode = 'continueToBreakpoint';
-                break;
-            // 'abort' is handled by the caller (throws)
-        }
-    }
-    applyPendingModifications(ctx) {
-        if (this.pendingModifications.size === 0)
-            return;
-        for (const [key, value] of this.pendingModifications) {
-            // Key format: "nodeId:portName:executionIndex"
-            const parts = key.split(':');
-            if (parts.length >= 3) {
-                const address = {
-                    id: parts[0],
-                    portName: parts[1],
-                    executionIndex: parseInt(parts[2], 10),
-                };
-                ctx.setVariable(address, value);
-            }
-        }
-        this.pendingModifications.clear();
-    }
-    restoreNodeOutputs(nodeId, outputs, ctx) {
-        // outputs is keyed by "portName:executionIndex" -> value
-        // Don't call ctx.addExecution here: the generated code's else block handles
-        // execution registration so local variables (e.g. dIdx) are set correctly.
-        for (const [portKey, value] of Object.entries(outputs)) {
-            const colonIdx = portKey.lastIndexOf(':');
-            if (colonIdx === -1)
-                continue;
-            const portName = portKey.substring(0, colonIdx);
-            const executionIndex = parseInt(portKey.substring(colonIdx + 1), 10);
-            ctx.setVariable({ id: nodeId, portName, executionIndex }, value);
-        }
-    }
-    extractVariables(ctx) {
-        const serialized = ctx.serialize();
-        return serialized.variables;
-    }
-    extractNodeOutputs(nodeId, allVariables) {
-        const outputs = {};
-        const prefix = `${nodeId}:`;
-        for (const [key, value] of Object.entries(allVariables)) {
-            if (key.startsWith(prefix)) {
-                // Extract portName from key "nodeId:portName:executionIndex"
-                const rest = key.substring(prefix.length);
-                const colonIdx = rest.lastIndexOf(':');
-                const portName = colonIdx >= 0 ? rest.substring(0, colonIdx) : rest;
-                outputs[portName] = value;
-            }
-        }
-        return outputs;
-    }
-    _createPausePromise() {
-        return new Promise((resolve) => {
-            this._pauseResolve = resolve;
-        });
-    }
-}
-//# sourceMappingURL=debug-controller.js.map

package/dist/runtime/events.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=events.js.map

package/dist/runtime/function-registry.js

@@ -1,66 +0,0 @@
-/**
- * Function Registry for Flow Weaver
- *
- * Provides a global registry of functions that can be referenced by string IDs
- * in external HTTP calls while allowing direct function passing in internal calls.
- */
-export class FunctionRegistry {
-    functions = new Map();
-    /**
-     * Register a function with the registry
-     */
-    register(config) {
-        if (this.functions.has(config.id)) {
-            throw new Error(`Function with ID '${config.id}' is already registered`);
-        }
-        this.functions.set(config.id, config);
-    }
-    /**
-     * Get a function by ID
-     */
-    get(id) {
-        const registered = this.functions.get(id);
-        return registered?.fn;
-    }
-    /**
-     * Get function metadata without the function itself
-     */
-    getMetadata(id) {
-        const registered = this.functions.get(id);
-        if (!registered)
-            return undefined;
-        const { fn: _, ...metadata } = registered;
-        return metadata;
-    }
-    /**
-     * List all registered functions, optionally filtered by category
-     */
-    list(category) {
-        const all = Array.from(this.functions.values());
-        const filtered = category ? all.filter((f) => f.category === category) : all;
-        return filtered.map(({ fn: _, ...metadata }) => metadata);
-    }
-    /**
-     * Check if a function is registered
-     */
-    has(id) {
-        return this.functions.has(id);
-    }
-    /**
-     * Clear all registered functions (useful for testing)
-     */
-    clear() {
-        this.functions.clear();
-    }
-    /**
-     * Get the count of registered functions
-     */
-    get size() {
-        return this.functions.size;
-    }
-}
-/**
- * Global function registry singleton
- */
-export const functionRegistry = new FunctionRegistry();
-//# sourceMappingURL=function-registry.js.map

package/dist/runtime/parameter-resolver.js

@@ -1,113 +0,0 @@
-/**
- * Parameter Resolver for Flow Weaver
- *
- * Resolves function-like parameters to executable functions.
- * Supports:
- * - Direct functions (passed through)
- * - Registry IDs (looked up in function registry)
- * - Partial application (registry ID with pre-bound arguments)
- */
-import { functionRegistry } from './function-registry.js';
-/**
- * Resolve a function-like parameter to an executable function
- *
- * @param param - The function-like parameter to resolve
- * @returns The resolved function with metadata
- * @throws Error if registry ID is not found
- *
- * @example
- * // Direct function
- * const resolved = resolveFunction((x: number) => x * 2);
- * resolved.fn(5); // 10
- *
- * @example
- * // Registry ID
- * const resolved = resolveFunction('string:uppercase');
- * resolved.fn('hello'); // 'HELLO'
- *
- * @example
- * // Partial application
- * const resolved = resolveFunction({
- *   registryId: 'math:clamp',
- *   partialArgs: { min: 0, max: 100 }
- * });
- * resolved.fn({ value: 150 }); // 100
- */
-export function resolveFunction(param) {
-    // Direct function - pass through
-    if (typeof param === 'function') {
-        return {
-            fn: param,
-            source: 'direct',
-        };
-    }
-    // String registry ID
-    if (typeof param === 'string') {
-        const fn = functionRegistry.get(param);
-        if (!fn) {
-            throw new Error(`Function '${param}' not found in registry`);
-        }
-        return {
-            fn,
-            source: 'registry',
-            registryId: param,
-        };
-    }
-    // Object with registry ID and optional partial args
-    if (typeof param === 'object' && param !== null && 'registryId' in param) {
-        const fn = functionRegistry.get(param.registryId);
-        if (!fn) {
-            throw new Error(`Function '${param.registryId}' not found in registry`);
-        }
-        // If partial args provided, create wrapper that merges them
-        if (param.partialArgs) {
-            const partialArgs = param.partialArgs;
-            const wrappedFn = (input) => {
-                // Merge partial args with input (input takes precedence for conflicting keys)
-                const mergedInput = typeof input === 'object' && input !== null
-                    ? { ...partialArgs, ...input }
-                    : input;
-                return fn(mergedInput);
-            };
-            return {
-                fn: wrappedFn,
-                source: 'registry',
-                registryId: param.registryId,
-            };
-        }
-        return {
-            fn,
-            source: 'registry',
-            registryId: param.registryId,
-        };
-    }
-    throw new Error(`Invalid function parameter: ${JSON.stringify(param)}`);
-}
-/**
- * Check if a value is a function-like parameter
- */
-export function isFunctionLike(value) {
-    if (typeof value === 'function')
-        return true;
-    if (typeof value === 'string')
-        return true;
-    if (typeof value === 'object' &&
-        value !== null &&
-        'registryId' in value &&
-        typeof value.registryId === 'string') {
-        return true;
-    }
-    return false;
-}
-/**
- * Try to resolve a function, returning undefined if not found
- */
-export function tryResolveFunction(param) {
-    try {
-        return resolveFunction(param);
-    }
-    catch {
-        return undefined;
-    }
-}
-//# sourceMappingURL=parameter-resolver.js.map

package/dist/server/types.js

@@ -1,5 +0,0 @@
-/**
- * Type definitions for the webhook server
- */
-export {};
-//# sourceMappingURL=types.js.map