@pikku/inspector 0.11.1 → 0.11.2

package/src/utils/workflow/graph/serialize-workflow-graph.ts

@@ -0,0 +1,223 @@
+import type {
+  SerializedWorkflowGraph,
+  SerializedGraphNode,
+  FunctionNode,
+  DataRef,
+  SerializedNext,
+} from './workflow-graph.types.js'
+
+/**
+ * Convert a RefValue (from runtime) to DataRef (serialized)
+ */
+function convertRef(ref: { nodeId: string; path?: string }): DataRef {
+  return {
+    $ref: ref.nodeId,
+    path: ref.path,
+  }
+}
+
+/**
+ * Check if a value is a runtime RefValue
+ */
+function isRefValue(
+  value: unknown
+): value is { __isRef: true; nodeId: string; path?: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '__isRef' in value &&
+    (value as any).__isRef === true
+  )
+}
+
+/**
+ * Convert input mapping from runtime format to serialized format
+ */
+function serializeInputMapping(
+  input: Record<string, unknown>
+): Record<string, unknown | DataRef> {
+  const result: Record<string, unknown | DataRef> = {}
+
+  for (const [key, value] of Object.entries(input)) {
+    if (isRefValue(value)) {
+      result[key] = convertRef(value)
+    } else {
+      result[key] = value
+    }
+  }
+
+  return result
+}
+
+/**
+ * Convert next config from runtime format to serialized format
+ * Runtime uses Record<string, string | string[]> for branching with graph.branch()
+ * Serialized uses { conditions: [...], default: ... } for UI-friendly branching
+ */
+function serializeNext(
+  next: string | string[] | Record<string, string | string[]> | undefined
+): SerializedNext | undefined {
+  if (!next) return undefined
+
+  if (typeof next === 'string') return next
+  if (Array.isArray(next)) return next
+
+  // Record format - convert to conditions format
+  // For now, treat keys as branch identifiers (from graph.branch())
+  // UI can display these as condition labels
+  const conditions = Object.entries(next).map(([key, target]) => ({
+    expression: key, // The branch key becomes the expression
+    target,
+  }))
+
+  return { conditions }
+}
+
+/**
+ * Serialize a workflow graph definition (from runtime) to JSON format
+ *
+ * @param definition - The runtime definition (with callbacks evaluated)
+ * @param rpcNameLookup - Function to get RPC name from a node's func
+ */
+export function serializeWorkflowGraph(
+  definition: {
+    name: string
+    wires: {
+      http?: { route: string; method: string }
+      queue?: string
+    }
+    graph: Record<
+      string,
+      {
+        func: { name?: string }
+        input?: (ref: any) => Record<string, unknown>
+        next?: string | string[] | Record<string, string | string[]>
+        onError?: string | string[]
+      }
+    >
+  },
+  options?: {
+    description?: string
+    tags?: string[]
+  }
+): SerializedWorkflowGraph {
+  const nodes: Record<string, SerializedGraphNode> = {}
+  const entryNodeIds: string[] = []
+
+  // Create a ref function that captures refs
+  const createRef = (nodeId: string, path?: string) => ({
+    __isRef: true as const,
+    nodeId,
+    path,
+  })
+
+  // Track which nodes have incoming edges
+  const hasIncomingEdge = new Set<string>()
+
+  // First pass: identify nodes with incoming edges
+  for (const [_nodeId, node] of Object.entries(definition.graph)) {
+    const next = node.next
+    if (!next) continue
+
+    if (typeof next === 'string') {
+      hasIncomingEdge.add(next)
+    } else if (Array.isArray(next)) {
+      next.forEach((n) => hasIncomingEdge.add(n))
+    } else {
+      for (const targets of Object.values(next)) {
+        if (typeof targets === 'string') {
+          hasIncomingEdge.add(targets)
+        } else {
+          targets.forEach((n) => hasIncomingEdge.add(n))
+        }
+      }
+    }
+  }
+
+  // Second pass: serialize nodes
+  for (const [nodeId, node] of Object.entries(definition.graph)) {
+    // Evaluate input callback to get the mapping
+    let input: Record<string, unknown | DataRef> = {}
+    if (node.input) {
+      const rawInput = node.input(createRef)
+      input = serializeInputMapping(rawInput)
+    }
+
+    // Get RPC name from func
+    const rpcName = node.func?.name || 'unknown'
+
+    const funcNode: FunctionNode = {
+      nodeId,
+      rpcName,
+      input,
+      next: serializeNext(node.next),
+      onError: node.onError,
+    }
+    nodes[nodeId] = funcNode
+
+    // Entry nodes have no incoming edges
+    if (!hasIncomingEdge.has(nodeId)) {
+      entryNodeIds.push(nodeId)
+    }
+  }
+
+  return {
+    name: definition.name,
+    pikkuFuncName: definition.name, // For graph workflows, pikkuFuncName is the workflow name
+    source: 'graph' as const,
+    description: options?.description,
+    tags: options?.tags,
+    wires: definition.wires as SerializedWorkflowGraph['wires'],
+    nodes,
+    entryNodeIds,
+  }
+}
+
+/**
+ * Deserialize a workflow graph from JSON to runtime format
+ * This re-hydrates the JSON so it can be executed
+ */
+export function deserializeWorkflowGraph(serialized: SerializedWorkflowGraph): {
+  name: string
+  wires: SerializedWorkflowGraph['wires']
+  graph: Record<
+    string,
+    {
+      rpcName: string
+      input: Record<string, unknown | DataRef>
+      next?: SerializedNext
+      onError?: string | string[]
+    }
+  >
+  entryNodeIds: string[]
+} {
+  const graph: Record<
+    string,
+    {
+      rpcName: string
+      input: Record<string, unknown | DataRef>
+      next?: SerializedNext
+      onError?: string | string[]
+    }
+  > = {}
+
+  for (const [nodeId, node] of Object.entries(serialized.nodes)) {
+    // Only include FunctionNode properties (nodes with rpcName)
+    if ('rpcName' in node) {
+      const funcNode = node as FunctionNode
+      graph[nodeId] = {
+        rpcName: funcNode.rpcName,
+        input: funcNode.input ?? {},
+        next: funcNode.next,
+        onError: funcNode.onError,
+      }
+    }
+  }
+
+  return {
+    name: serialized.name,
+    wires: serialized.wires,
+    graph,
+    entryNodeIds: serialized.entryNodeIds,
+  }
+}

package/src/utils/workflow/graph/workflow-graph.types.ts

@@ -0,0 +1,280 @@
+/**
+ * Serialized types for workflow graphs
+ * These are extracted by the inspector and stored as JSON
+ * Can be created from code (wireWorkflow) or UI
+ */
+
+/**
+ * Reference to data from another node or trigger
+ */
+export interface DataRef {
+  /** Source: 'trigger' for trigger input, or node ID for node output */
+  $ref: string
+  /** Optional path into the data (dot notation: 'body.orderId') */
+  path?: string
+}
+
+/**
+ * Check if value is a DataRef
+ */
+export const isDataRef = (value: unknown): value is DataRef =>
+  typeof value === 'object' &&
+  value !== null &&
+  '$ref' in value &&
+  typeof (value as DataRef).$ref === 'string'
+
+/**
+ * Reference to a context/state variable
+ */
+export interface StateRef {
+  /** Context variable name */
+  $state: string
+  /** Optional path into the value (dot notation for nested objects) */
+  path?: string
+}
+
+/**
+ * Check if value is a StateRef
+ */
+export const isStateRef = (value: unknown): value is StateRef =>
+  typeof value === 'object' &&
+  value !== null &&
+  '$state' in value &&
+  typeof (value as StateRef).$state === 'string'
+
+/**
+ * Helper functions for building input mappings
+ */
+export const ref = (nodeId: string, path?: string): DataRef => ({
+  $ref: nodeId,
+  path,
+})
+export const state = (name: string, path?: string): StateRef => ({
+  $state: name,
+  path,
+})
+
+/**
+ * Condition for branching
+ */
+export interface BranchCondition {
+  /** Expression to evaluate (uses node output references) */
+  expression: string
+  /** Target node(s) if condition is true */
+  target: string | string[]
+}
+
+/**
+ * Next node configuration
+ */
+export type SerializedNext =
+  | string // Single next node
+  | string[] // Parallel execution
+  | {
+      /** Conditions evaluated in order, first match wins */
+      conditions: BranchCondition[]
+      /** Default target if no conditions match */
+      default?: string | string[]
+    }
+
+/**
+ * Node execution options
+ */
+export interface NodeOptions {
+  /** Number of retry attempts on failure */
+  retries?: number
+  /** Delay between retries (e.g., '1s', '5s') */
+  retryDelay?: string
+  /** Timeout for node execution (e.g., '30s', '5m') */
+  timeout?: string
+  /** If true, execute via queue (async). Default: false (inline) */
+  async?: boolean
+}
+
+/**
+ * Flow node types for control flow (no RPC call)
+ */
+export type FlowType =
+  | 'sleep'
+  | 'branch'
+  | 'parallel'
+  | 'fanout'
+  | 'inline'
+  | 'switch'
+  | 'filter'
+  | 'arrayPredicate'
+  | 'return'
+  | 'cancel'
+  | 'set'
+
+// Import and re-export context types from core
+import type { ContextVariable, WorkflowContext } from '@pikku/core/workflow'
+
+export type { ContextVariable, WorkflowContext }
+
+/**
+ * Base node properties shared by all node types
+ */
+interface BaseNode {
+  /** Node ID */
+  nodeId: string
+  /** Step name/description */
+  stepName?: string
+  /** Next node(s) - simple, parallel, or conditional */
+  next?: SerializedNext
+  /** Error routing - node(s) to execute on error */
+  onError?: string | string[]
+  /** Execution options */
+  options?: NodeOptions
+}
+
+/**
+ * Function node - calls an RPC
+ */
+export interface FunctionNode extends BaseNode {
+  /** RPC function name */
+  rpcName: string
+  /** Input mapping - values can be literals or DataRefs */
+  input?: Record<string, unknown | DataRef>
+  /** Output variable name for storing result */
+  outputVar?: string
+}
+
+/**
+ * Flow node - control flow only, no RPC call
+ */
+export interface FlowNode extends BaseNode {
+  /** Flow type */
+  flow: FlowType
+  /** Flow-specific properties */
+  [key: string]: unknown
+}
+
+/**
+ * Serialized graph node - either a function node or flow node
+ */
+export type SerializedGraphNode = FunctionNode | FlowNode
+
+/**
+ * Type guard for function nodes
+ */
+export const isFunctionNode = (
+  node: SerializedGraphNode
+): node is FunctionNode => 'rpcName' in node
+
+/**
+ * Type guard for flow nodes
+ */
+export const isFlowNode = (node: SerializedGraphNode): node is FlowNode =>
+  'flow' in node
+
+/**
+ * HTTP wire configuration with startNode
+ */
+export interface HttpWire {
+  route: string
+  method: 'get' | 'post' | 'put' | 'patch' | 'delete'
+  startNode: string
+}
+
+/**
+ * Channel wire configuration
+ */
+export interface ChannelWire {
+  name: string
+  onConnect?: string
+  onDisconnect?: string
+  onMessage?: string
+}
+
+/**
+ * Queue wire configuration
+ */
+export interface QueueWire {
+  name: string
+  startNode: string
+}
+
+/**
+ * CLI wire configuration
+ */
+export interface CliWire {
+  command: string
+  startNode: string
+}
+
+/**
+ * MCP wire configurations
+ */
+export interface McpWires {
+  tool?: Array<{ name: string; startNode: string }>
+  prompt?: Array<{ name: string; startNode: string }>
+  resource?: Array<{ uri: string; startNode: string }>
+}
+
+/**
+ * Schedule wire configuration
+ */
+export interface ScheduleWire {
+  cron?: string
+  interval?: string
+  startNode: string
+}
+
+/**
+ * Trigger wire configuration
+ */
+export interface TriggerWire {
+  name: string
+  startNode: string
+}
+
+/**
+ * All wire configurations for workflows
+ */
+export interface WorkflowWiresConfig {
+  http?: HttpWire[]
+  channel?: ChannelWire[]
+  queue?: QueueWire[]
+  cli?: CliWire[]
+  mcp?: McpWires
+  schedule?: ScheduleWire[]
+  trigger?: TriggerWire[]
+}
+
+/**
+ * Workflow source type
+ * - 'dsl': Pure DSL workflow (pikkuWorkflowFunc) - can be round-tripped to code
+ * - 'complex': Complex workflow (pikkuWorkflowComplexFunc) - contains inline steps, not serializable
+ * - 'graph': Graph-based workflow (pikkuWorkflowGraph)
+ */
+export type WorkflowSourceType = 'dsl' | 'complex' | 'graph'
+
+/**
+ * Serialized workflow graph - the canonical JSON format
+ */
+export interface SerializedWorkflowGraph {
+  /** Workflow name */
+  name: string
+  /** Pikku function name (for runtime registration) */
+  pikkuFuncName: string
+  /** Source type: 'dsl' for pikkuWorkflowFunc, 'graph' for pikkuWorkflowGraph */
+  source: WorkflowSourceType
+  /** Optional description */
+  description?: string
+  /** Tags for organization */
+  tags?: string[]
+  /** Workflow context/state variables (from Zod schema) */
+  context?: WorkflowContext
+  /** Wires - how the workflow is triggered */
+  wires: WorkflowWiresConfig
+  /** Serialized nodes */
+  nodes: Record<string, SerializedGraphNode>
+  /** Entry node(s) - first nodes to execute */
+  entryNodeIds: string[]
+}
+
+/**
+ * All workflow graphs (serialized)
+ */
+export type SerializedWorkflowGraphs = Record<string, SerializedWorkflowGraph>

package/src/visit.ts

@@ -15,6 +15,9 @@ import { addRPCInvocations } from './add/add-rpc-invocations.js'
 import { addMiddleware } from './add/add-middleware.js'
 import { addPermission } from './add/add-permission.js'
 import { addCLI, addCLIRenderers } from './add/add-cli.js'
+import { addForgeNode } from './add/add-forge-node.js'
+import { addForgeCredential } from './add/add-forge-credential.js'
+import { addWorkflowGraph } from './add/add-workflow-graph.js'
 
 export const visitSetup = (
   logger: InspectorLogger,
@@ -99,6 +102,9 @@ export const visitRoutes = (
   addMCPResource(logger, node, checker, state, options)
   addMCPTool(logger, node, checker, state, options)
   addMCPPrompt(logger, node, checker, state, options)
+  addForgeNode(logger, node, checker, state, options)
+  addForgeCredential(logger, node, checker, state, options)
+  addWorkflowGraph(logger, node, checker, state, options)
 
   ts.forEachChild(node, (child) =>
     visitRoutes(logger, checker, child, state, options)