@pikku/core 0.11.1 → 0.11.2

package/dist/wirings/workflow/graph/graph-runner.js

@@ -0,0 +1,452 @@
+import { createRef, isRef } from './workflow-graph.types.js';
+import { pikkuState } from '../../../pikku-state.js';
+/**
+ * Add a workflow graph to the system
+ * This is called by the generated workflow wirings
+ */
+export const addWorkflowGraph = (workflowName, graphResult) => {
+    // Get workflow metadata from inspector
+    const meta = pikkuState(null, 'workflows', 'meta');
+    const workflowMeta = meta[workflowName];
+    if (!workflowMeta) {
+        throw new Error(`Workflow metadata not found for '${workflowName}'. Make sure to run the CLI to generate metadata.`);
+    }
+    // Store workflow graph definition in state
+    const registrations = pikkuState(null, 'workflows', 'graphRegistrations');
+    registrations.set(workflowName, {
+        name: workflowName,
+        wires: graphResult.wires || {},
+        graph: graphResult.graph,
+    });
+};
+/**
+ * Get a registered workflow graph by name
+ */
+export function getWorkflowGraph(name) {
+    const registrations = pikkuState(null, 'workflows', 'graphRegistrations');
+    return registrations.get(name);
+}
+/**
+ * Resolve next config to array of node IDs
+ * For branching (Record), uses the branch key from step
+ */
+function resolveNextFromConfig(next, branchKey) {
+    if (!next)
+        return [];
+    if (typeof next === 'string')
+        return [next];
+    if (Array.isArray(next))
+        return next;
+    // Record (branching) - use branch key set by graph.branch()
+    if (!branchKey || !(branchKey in next))
+        return [];
+    const branchNext = next[branchKey];
+    return Array.isArray(branchNext) ? branchNext : [branchNext];
+}
+/**
+ * Check if a value is a template
+ */
+function isTemplate(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '$template' in value &&
+        typeof value.$template === 'object');
+}
+/**
+ * Create a template function for use in input callbacks
+ */
+function createTemplate(templateStr, refs) {
+    const parts = [];
+    const expressions = [];
+    const regex = /\$(\d+)/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = regex.exec(templateStr)) !== null) {
+        parts.push(templateStr.slice(lastIndex, match.index));
+        const refIndex = parseInt(match[1], 10);
+        const refValue = refs[refIndex];
+        if (refValue) {
+            expressions.push({ $ref: refValue.nodeId, path: refValue.path });
+        }
+        else {
+            expressions.push({ $ref: 'unknown' });
+        }
+        lastIndex = regex.lastIndex;
+    }
+    parts.push(templateStr.slice(lastIndex));
+    return { $template: { parts, expressions } };
+}
+/**
+ * Evaluate a node's input callback to get the input mapping
+ */
+function evaluateInputCallback(node) {
+    if (!node.input)
+        return {};
+    const ref = (targetNodeId, path) => createRef(targetNodeId, path);
+    const template = (templateStr, refs) => createTemplate(templateStr, refs);
+    // Call with both ref and template - input callback may accept 1 or 2 params
+    return node.input(ref, template);
+}
+/**
+ * Extract node IDs referenced in an input mapping (including from templates)
+ */
+function extractReferencedNodeIds(inputMapping) {
+    const nodeIds = [];
+    for (const value of Object.values(inputMapping)) {
+        if (isRef(value)) {
+            nodeIds.push(value.nodeId);
+        }
+        else if (isTemplate(value)) {
+            for (const expr of value.$template.expressions) {
+                nodeIds.push(expr.$ref);
+            }
+        }
+    }
+    return [...new Set(nodeIds)];
+}
+/**
+ * Resolve a template value using node results
+ */
+function resolveTemplate(template, nodeResults) {
+    const { parts, expressions } = template.$template;
+    let result = '';
+    for (let i = 0; i < parts.length; i++) {
+        result += parts[i];
+        if (i < expressions.length) {
+            const expr = expressions[i];
+            const nodeResult = nodeResults[expr.$ref];
+            const value = expr.path
+                ? getValueAtPath(nodeResult, expr.path)
+                : nodeResult;
+            result += String(value ?? '');
+        }
+    }
+    return result;
+}
+/**
+ * Resolve input mapping using node results
+ */
+function resolveInputMapping(inputMapping, nodeResults) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(inputMapping)) {
+        if (isRef(value)) {
+            const nodeResult = nodeResults[value.nodeId];
+            resolved[key] = value.path
+                ? getValueAtPath(nodeResult, value.path)
+                : nodeResult;
+        }
+        else if (isTemplate(value)) {
+            resolved[key] = resolveTemplate(value, nodeResults);
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
+/**
+ * Get value at a dot-notation path from an object
+ */
+function getValueAtPath(obj, path) {
+    if (!path)
+        return obj;
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current == null)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Get the RPC name from a graph node's func
+ * Supports both function references (func.name) and string RPC names
+ */
+function getRpcName(node) {
+    const func = node.func;
+    // If func is a string, use it directly as the RPC name
+    if (typeof func === 'string') {
+        return func;
+    }
+    // Otherwise, it's a function reference - use its name
+    return func?.name || 'unknown';
+}
+/**
+ * Queue a graph node for execution
+ */
+async function queueGraphNode(workflowService, runId, _graphName, nodeId, rpcName, input) {
+    // Step name convention: node:<nodeId>
+    // Graph name is stored as the workflow name on the run
+    await workflowService.insertStepState(runId, `node:${nodeId}`, rpcName, input, { retries: 3 });
+    await workflowService.resumeWorkflow(runId);
+}
+/**
+ * Continue graph execution
+ * Non-blocking - finds pending nodes, resolves inputs, queues them for execution
+ */
+export async function continueGraph(workflowService, runId, graphName) {
+    const definition = getWorkflowGraph(graphName);
+    if (!definition) {
+        throw new Error(`Workflow graph '${graphName}' not found`);
+    }
+    const graph = definition.graph;
+    // Get completed node IDs + branch keys (lightweight, no results)
+    const { completedNodeIds, branchKeys } = await workflowService.getCompletedGraphState(runId);
+    // Find candidate next nodes from completed nodes
+    const candidateNodes = [];
+    for (const nodeId of completedNodeIds) {
+        const node = graph[nodeId];
+        if (!node?.next)
+            continue;
+        const nextNodes = resolveNextFromConfig(node.next, branchKeys[nodeId]);
+        candidateNodes.push(...nextNodes);
+    }
+    if (candidateNodes.length === 0 && completedNodeIds.length > 0) {
+        // No more nodes to run - graph complete
+        await workflowService.updateRunStatus(runId, 'completed');
+        return;
+    }
+    // Filter to only nodes that don't have a step yet
+    const nodesToQueue = await workflowService.getNodesWithoutSteps(runId, candidateNodes);
+    // Queue each node for execution
+    for (const nodeId of nodesToQueue) {
+        const node = graph[nodeId];
+        if (!node)
+            continue;
+        // Evaluate input callback to get the mapping
+        const inputMapping = evaluateInputCallback(node);
+        // Only fetch results for nodes referenced in this node's input
+        const referencedNodeIds = extractReferencedNodeIds(inputMapping);
+        const nodeResults = await workflowService.getNodeResults(runId, referencedNodeIds);
+        const resolvedInput = resolveInputMapping(inputMapping, nodeResults);
+        const rpcName = getRpcName(node);
+        await queueGraphNode(workflowService, runId, graphName, nodeId, rpcName, resolvedInput);
+    }
+}
+/**
+ * Execute a graph step with wire context.
+ * Called by the step worker when executing graph nodes.
+ */
+export async function executeGraphStep(workflowService, rpcService, runId, stepId, stepName, rpcName, data, graphName) {
+    const nodeId = stepName.replace(/^node:/, '');
+    const wireState = {};
+    const graphWire = {
+        runId,
+        graphName,
+        nodeId,
+        branch: (key) => {
+            wireState.branchKey = key;
+        },
+        setState: (name, value) => workflowService.updateRunState(runId, name, value),
+        getState: () => workflowService.getRunState(runId),
+    };
+    try {
+        // Execute the RPC with graph wire context
+        const result = await rpcService.rpcWithWire(rpcName, data, {
+            graph: graphWire,
+        });
+        // If branch was called, store the branch key
+        if (wireState.branchKey) {
+            await workflowService.setBranchTaken(stepId, wireState.branchKey);
+        }
+        return result;
+    }
+    catch (error) {
+        // Check if this node has an onError handler
+        const definition = getWorkflowGraph(graphName);
+        if (definition) {
+            const node = definition.graph[nodeId];
+            if (node?.onError) {
+                // Route to error handler nodes
+                const errorNodes = Array.isArray(node.onError)
+                    ? node.onError
+                    : [node.onError];
+                for (const errorNodeId of errorNodes) {
+                    const errorNode = definition.graph[errorNodeId];
+                    if (errorNode) {
+                        const errorRpcName = getRpcName(errorNode);
+                        // Queue error node with the error as input
+                        await queueGraphNode(workflowService, runId, graphName, errorNodeId, errorRpcName, { error: { message: error.message } });
+                    }
+                }
+                // Don't rethrow - error was handled by routing to error nodes
+                return;
+            }
+        }
+        // No error handler - rethrow
+        throw error;
+    }
+}
+/**
+ * Handle node completion - re-triggers graph continuation
+ */
+export async function onGraphNodeComplete(workflowService, runId, graphName) {
+    await continueGraph(workflowService, runId, graphName);
+}
+/**
+ * Execute a graph node inline (without queue)
+ */
+async function executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, input, graph) {
+    const node = graph[nodeId];
+    if (!node)
+        return;
+    const rpcName = getRpcName(node);
+    const stepName = `node:${nodeId}`;
+    // Insert step state
+    const stepState = await workflowService.insertStepState(runId, stepName, rpcName, input, { retries: 3 });
+    await workflowService.setStepRunning(stepState.stepId);
+    // Execute with graph wire context
+    const wireState = {};
+    const graphWire = {
+        runId,
+        graphName,
+        nodeId,
+        branch: (key) => {
+            wireState.branchKey = key;
+        },
+        setState: (name, value) => workflowService.updateRunState(runId, name, value),
+        getState: () => workflowService.getRunState(runId),
+    };
+    try {
+        const result = await rpcService.rpcWithWire(rpcName, input, {
+            graph: graphWire,
+        });
+        // If branch was called, store the branch key
+        if (wireState.branchKey) {
+            await workflowService.setBranchTaken(stepState.stepId, wireState.branchKey);
+        }
+        await workflowService.setStepResult(stepState.stepId, result);
+    }
+    catch (error) {
+        await workflowService.setStepError(stepState.stepId, error);
+        // Check if this node has an onError handler
+        const definition = getWorkflowGraph(graphName);
+        if (definition) {
+            const node = definition.graph[nodeId];
+            if (node?.onError) {
+                // Route to error handler nodes (inline)
+                const errorNodes = Array.isArray(node.onError)
+                    ? node.onError
+                    : [node.onError];
+                await Promise.all(errorNodes.map((errorNodeId) => executeGraphNodeInline(workflowService, rpcService, runId, graphName, errorNodeId, { error: { message: error.message } }, graph)));
+                return;
+            }
+        }
+        // No error handler - rethrow
+        throw error;
+    }
+}
+/**
+ * Continue graph execution inline (without queue)
+ * Executes nodes in parallel where possible using Promise.all
+ */
+async function continueGraphInline(workflowService, rpcService, runId, graphName, graph, triggerInput) {
+    while (true) {
+        // Get completed node IDs + branch keys (lightweight, no results)
+        const { completedNodeIds, branchKeys } = await workflowService.getCompletedGraphState(runId);
+        // Find candidate next nodes from completed nodes
+        const candidateNodes = [];
+        for (const nodeId of completedNodeIds) {
+            const node = graph[nodeId];
+            if (!node?.next)
+                continue;
+            const nextNodes = resolveNextFromConfig(node.next, branchKeys[nodeId]);
+            candidateNodes.push(...nextNodes);
+        }
+        if (candidateNodes.length === 0 && completedNodeIds.length > 0) {
+            // No more nodes to run - graph complete
+            await workflowService.updateRunStatus(runId, 'completed');
+            return;
+        }
+        // Filter to only nodes that don't have a step yet
+        const nodesToExecute = await workflowService.getNodesWithoutSteps(runId, candidateNodes);
+        if (nodesToExecute.length === 0) {
+            // No more nodes to execute - if we've completed at least one node, we're done
+            // This handles branching where only some paths are taken
+            if (completedNodeIds.length > 0) {
+                await workflowService.updateRunStatus(runId, 'completed');
+            }
+            return;
+        }
+        // Execute all nodes in parallel
+        await Promise.all(nodesToExecute.map(async (nodeId) => {
+            const node = graph[nodeId];
+            if (!node)
+                return;
+            // Evaluate input callback to get the mapping
+            const inputMapping = evaluateInputCallback(node);
+            // Only fetch results for nodes referenced in this node's input (excluding trigger)
+            const referencedNodeIds = extractReferencedNodeIds(inputMapping).filter((id) => id !== 'trigger');
+            const fetchedResults = await workflowService.getNodeResults(runId, referencedNodeIds);
+            // Merge fetched results with trigger input
+            const nodeResults = { trigger: triggerInput, ...fetchedResults };
+            const resolvedInput = resolveInputMapping(inputMapping, nodeResults);
+            await executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, resolvedInput, graph);
+        }));
+    }
+}
+/**
+ * Start a workflow graph execution
+ * @param startNode - Optional starting node ID (from wire config). If not provided, uses wires.api from graph definition.
+ */
+export async function runWorkflowGraph(workflowService, graphName, triggerInput, rpcService, inline, startNode) {
+    const definition = getWorkflowGraph(graphName);
+    if (!definition) {
+        throw new Error(`Workflow graph '${graphName}' not found`);
+    }
+    // Use startNode from caller if provided, otherwise use wires.api from graph definition
+    const apiStartNode = startNode ?? definition.wires?.api;
+    const entryNodes = apiStartNode ? [apiStartNode] : [];
+    if (entryNodes.length === 0) {
+        throw new Error(`Workflow graph '${graphName}' has no wires.api defined and no startNode was provided`);
+    }
+    const graph = definition.graph;
+    const runId = await workflowService.createRun(graphName, triggerInput, inline);
+    // Register as inline for fast lookup
+    if (inline) {
+        workflowService.registerInlineRun(runId);
+    }
+    // Create nodeResults with trigger for resolving entry node inputs
+    const triggerNodeResults = { trigger: triggerInput };
+    try {
+        if (inline && rpcService) {
+            // Inline mode - execute entry nodes in parallel
+            await Promise.all(entryNodes.map(async (nodeId) => {
+                const node = graph[nodeId];
+                if (!node)
+                    return;
+                // Evaluate and resolve entry node input
+                const inputMapping = evaluateInputCallback(node);
+                const resolvedInput = Object.keys(inputMapping).length > 0
+                    ? resolveInputMapping(inputMapping, triggerNodeResults)
+                    : triggerInput;
+                await executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, resolvedInput, graph);
+            }));
+            // Continue executing remaining nodes inline
+            await continueGraphInline(workflowService, rpcService, runId, graphName, graph, triggerInput);
+        }
+        else {
+            // Queue-based mode
+            for (const nodeId of entryNodes) {
+                const node = graph[nodeId];
+                if (!node)
+                    continue;
+                // Evaluate and resolve entry node input
+                const inputMapping = evaluateInputCallback(node);
+                const resolvedInput = Object.keys(inputMapping).length > 0
+                    ? resolveInputMapping(inputMapping, triggerNodeResults)
+                    : triggerInput;
+                const rpcName = getRpcName(node);
+                await queueGraphNode(workflowService, runId, graphName, nodeId, rpcName, resolvedInput);
+            }
+        }
+        return { runId };
+    }
+    finally {
+        // Clean up inline tracking
+        if (inline) {
+            workflowService.unregisterInlineRun(runId);
+        }
+    }
+}

package/dist/wirings/workflow/graph/index.d.ts

@@ -0,0 +1,3 @@
+export * from './workflow-graph.types.js';
+export * from './graph-node.js';
+export * from './graph-runner.js';

package/dist/wirings/workflow/graph/index.js

@@ -0,0 +1,3 @@
+export * from './workflow-graph.types.js';
+export * from './graph-node.js';
+export * from './graph-runner.js';

package/dist/wirings/workflow/graph/workflow-graph.types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Ref value - internal representation after input callback is evaluated
+ */
+export interface RefValue {
+    __isRef: true;
+    nodeId: string;
+    path?: string;
+}
+/**
+ * Helper to create a ref value
+ */
+export declare const createRef: (nodeId: string, path?: string) => RefValue;
+/**
+ * Check if a value is a ref
+ */
+export declare const isRef: (value: unknown) => value is RefValue;
+/**
+ * Input reference for fetching step results
+ */
+export interface InputRef {
+    nodeId: string;
+    path?: string;
+}
+/**
+ * Ref function type - provides type-safe references to other nodes' outputs
+ * The actual typing is done at the pikkuWorkflowGraph level
+ */
+export type RefFn<NodeIds extends string = string> = (nodeId: NodeIds, path?: string) => RefValue;
+/**
+ * Next node configuration - fully serializable
+ * - string: single next node
+ * - string[]: parallel execution (all run concurrently)
+ * - Record<string, string | string[]>: branching (function calls graph.branch('key'))
+ */
+export type NextConfig<NodeIds extends string = string> = NodeIds | NodeIds[] | Record<string, NodeIds | NodeIds[]>;
+/**
+ * Graph node configuration - references functions by RPC name
+ */
+export interface GraphNodeConfig<NodeIds extends string = string> {
+    /** RPC function name */
+    func: string;
+    /** Input mapping callback - receives ref function, returns input object */
+    input?: (ref: RefFn<NodeIds>) => Record<string, unknown>;
+    /** Next nodes - string, array, or record for branching */
+    next?: NextConfig<NodeIds>;
+    /** Error routing - node(s) to execute on error */
+    onError?: NodeIds | NodeIds[];
+}
+import type { WorkflowWires } from '../workflow.types.js';
+export type { WorkflowWires };
+/**
+ * Workflow graph definition (internal use)
+ */
+export interface WorkflowGraphDefinition<Nodes extends Record<string, GraphNodeConfig<string>> = Record<string, GraphNodeConfig>> {
+    /** Unique workflow name */
+    name: string;
+    /** Wire configuration */
+    wires: WorkflowWires;
+    /** Graph nodes */
+    graph: Nodes;
+}
+/**
+ * Graph wire context - available to functions running in a workflow graph
+ */
+export interface PikkuGraphWire {
+    /** Workflow run ID */
+    runId: string;
+    /** Graph name */
+    graphName: string;
+    /** Current node ID */
+    nodeId: string;
+    /**
+     * Select which branch to take for Record-based next config.
+     * Must be called if the node has a Record `next` configuration.
+     * @param key - The branch key to take (must match a key in the next Record)
+     */
+    branch: (key: string) => void;
+    /**
+     * Set a state variable value.
+     * @param name - Variable name
+     * @param value - Value to store
+     */
+    setState: (name: string, value: unknown) => Promise<void>;
+    /**
+     * Get the entire state object.
+     * @returns The state object with all variables
+     */
+    getState: () => Promise<Record<string, unknown>>;
+}
+/**
+ * Internal mutable state for graph wire (used by runner to capture branch)
+ */
+export interface GraphWireState {
+    branchKey?: string;
+}

package/dist/wirings/workflow/graph/workflow-graph.types.js

@@ -0,0 +1,15 @@
+/**
+ * Helper to create a ref value
+ */
+export const createRef = (nodeId, path) => ({
+    __isRef: true,
+    nodeId,
+    path,
+});
+/**
+ * Check if a value is a ref
+ */
+export const isRef = (value) => typeof value === 'object' &&
+    value !== null &&
+    '__isRef' in value &&
+    value.__isRef === true;

package/dist/wirings/workflow/index.d.ts

@@ -1,15 +1,10 @@
 /**
  * Workflow module exports
  */
-export type { CoreWorkflow, WorkflowStepOptions, WorkflowStepMeta, RpcStepMeta, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, InputSource, OutputBinding, PikkuWorkflowWire, PikkuWorkflow, WorkflowsMeta, WorkflowRun, StepState, WorkflowStatus, StepStatus, } from './workflow.types.js';
-export { PikkuWorkflowService } from './pikku-workflow-service.js';
-export { addWorkflow } from './workflow-runner.js';
-/**
- * @deprecated This function is no longer used and will be removed in a future release.
- * It exists only for backwards compatibility with generated code.
- * TODO: Remove this export in a future release after updating code generation
- */
-export declare const wireWorkflow: <T extends {
-    name: string;
-    func: any;
-}>(workflow: T) => void;
+export { PikkuWorkflowService, WorkflowCancelledException, } from './pikku-workflow-service.js';
+export { addWorkflow } from './dsl/workflow-runner.js';
+export { addWorkflowGraph } from './graph/graph-runner.js';
+export { wireWorkflow } from './wire-workflow.js';
+export type { WorkflowDefinition, WorkflowDefinitionFunc, WorkflowDefinitionGraph, } from './wire-workflow.js';
+export type { WorkflowService, WorkflowServiceConfig, WorkflowHTTPWire, WorkflowWires, WorkflowStatus, StepStatus, WorkflowRun, StepState, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';

package/dist/wirings/workflow/index.js

@@ -1,14 +1,9 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService } from './pikku-workflow-service.js';
-// Internal registration function (used by generated code)
-export { addWorkflow } from './workflow-runner.js';
-/**
- * @deprecated This function is no longer used and will be removed in a future release.
- * It exists only for backwards compatibility with generated code.
- * TODO: Remove this export in a future release after updating code generation
- */
-export const wireWorkflow = (workflow) => {
-    // Empty function - no longer used, kept for backwards compatibility
-};
+export { PikkuWorkflowService, WorkflowCancelledException, } from './pikku-workflow-service.js';
+// Internal registration functions (used by generated code)
+export { addWorkflow } from './dsl/workflow-runner.js';
+export { addWorkflowGraph } from './graph/graph-runner.js';
+// Unified wireWorkflow function
+export { wireWorkflow } from './wire-workflow.js';