@pikku/inspector 0.11.0 → 0.11.2

package/src/utils/workflow/graph/convert-dsl-to-graph.ts

@@ -0,0 +1,415 @@
+/**
+ * Converts DSL (Domain Specific Language) step-based format to graph node format
+ */
+import type { WorkflowStepMeta, WorkflowsMeta } from '@pikku/core/workflow'
+import type {
+  SerializedGraphNode,
+  SerializedWorkflowGraph,
+  FunctionNode,
+  FlowNode,
+  DataRef,
+} from './workflow-graph.types.js'
+
+/**
+ * Check if a node is a terminal flow (no next step should follow)
+ */
+function isTerminalFlow(node: SerializedGraphNode): boolean {
+  if ('flow' in node) {
+    // Cancel and return are terminal flows - they end execution
+    return node.flow === 'cancel' || node.flow === 'return'
+  }
+  return false
+}
+
+/**
+ * Convert InputSource to DataRef
+ */
+function convertInputSource(source: {
+  from: string
+  path?: string
+  name?: string
+  value?: unknown
+  parts?: string[]
+  expressions?: unknown[]
+}): unknown | DataRef {
+  if (source.from === 'literal') {
+    return source.value
+  }
+  if (source.from === 'input') {
+    return { $ref: 'trigger', path: source.path }
+  }
+  if (source.from === 'outputVar') {
+    return { $ref: source.name!, path: source.path }
+  }
+  if (source.from === 'item') {
+    return { $ref: '$item', path: source.path }
+  }
+  if (source.from === 'stateVar') {
+    return { $state: source.name!, path: source.path }
+  }
+  if (source.from === 'template') {
+    return {
+      $template: {
+        parts: source.parts,
+        expressions: source.expressions?.map((expr) =>
+          convertInputSource(expr as any)
+        ),
+      },
+    }
+  }
+  return source.value
+}
+
+/**
+ * Convert a single DSL step to graph node(s)
+ */
+function convertStepToNode(
+  step: WorkflowStepMeta,
+  index: number,
+  steps: WorkflowStepMeta[],
+  nodeIdPrefix: string = 'step'
+): SerializedGraphNode[] {
+  const nodeId = `${nodeIdPrefix}_${index}`
+  const nextNodeId =
+    index < steps.length - 1 ? `${nodeIdPrefix}_${index + 1}` : undefined
+
+  switch (step.type) {
+    case 'rpc': {
+      const node: FunctionNode = {
+        nodeId,
+        rpcName: step.rpcName,
+        stepName: step.stepName,
+        next: nextNodeId,
+      }
+      if (step.inputs) {
+        if (step.inputs === 'passthrough') {
+          // Entire data is passed through - store as reference to trigger
+          node.input = { $passthrough: { $ref: 'trigger' } }
+        } else {
+          node.input = {}
+          for (const [key, source] of Object.entries(step.inputs)) {
+            node.input[key] = convertInputSource(source as any)
+          }
+        }
+      }
+      if (step.outputVar) {
+        node.outputVar = step.outputVar
+      }
+      if (step.options) {
+        node.options = {
+          retries: step.options.retries,
+          retryDelay: step.options.retryDelay?.toString(),
+        }
+      }
+      return [node]
+    }
+
+    case 'sleep': {
+      const node: FlowNode = {
+        nodeId,
+        flow: 'sleep',
+        stepName: step.stepName,
+        duration: step.duration,
+        next: nextNodeId,
+      }
+      return [node]
+    }
+
+    case 'inline': {
+      const node: FlowNode = {
+        nodeId,
+        flow: 'inline',
+        stepName: step.stepName,
+        description: step.description,
+        next: nextNodeId,
+      }
+      return [node]
+    }
+
+    case 'branch': {
+      // Convert all branch conditions (if/else-if chain)
+      const branchNodes: SerializedGraphNode[] = []
+      const branches: Array<{
+        condition: unknown
+        entry: string
+      }> = []
+
+      for (let i = 0; i < step.branches.length; i++) {
+        const branchSteps = convertStepsToNodes(
+          step.branches[i].steps,
+          `${nodeId}_branch${i}`
+        )
+        if (branchSteps.length > 0) {
+          branches.push({
+            condition: step.branches[i].condition,
+            entry: branchSteps[0].nodeId,
+          })
+          // Link last branch node back to next (unless terminal flow)
+          if (nextNodeId) {
+            const lastBranch = branchSteps[branchSteps.length - 1]
+            if (!lastBranch.next && !isTerminalFlow(lastBranch))
+              lastBranch.next = nextNodeId
+          }
+          branchNodes.push(...branchSteps)
+        }
+      }
+
+      // Convert else branch
+      const elseNodes = step.elseSteps
+        ? convertStepsToNodes(step.elseSteps, `${nodeId}_else`)
+        : []
+      if (elseNodes.length > 0 && nextNodeId) {
+        const lastElse = elseNodes[elseNodes.length - 1]
+        if (!lastElse.next && !isTerminalFlow(lastElse))
+          lastElse.next = nextNodeId
+      }
+
+      const node: FlowNode = {
+        nodeId,
+        flow: 'branch',
+        branches,
+        elseEntry: elseNodes.length > 0 ? elseNodes[0].nodeId : undefined,
+        next: nextNodeId,
+      }
+
+      return [node, ...branchNodes, ...elseNodes]
+    }
+
+    case 'switch': {
+      const caseNodes: SerializedGraphNode[] = []
+      const cases: Array<{
+        value?: unknown
+        expression?: string
+        entry: string
+      }> = []
+
+      for (let i = 0; i < step.cases.length; i++) {
+        const caseSteps = convertStepsToNodes(
+          step.cases[i].steps,
+          `${nodeId}_case${i}`
+        )
+        if (caseSteps.length > 0) {
+          cases.push({
+            value: step.cases[i].value,
+            expression: step.cases[i].expression,
+            entry: caseSteps[0].nodeId,
+          })
+          // Link last case node to next (unless terminal flow)
+          if (nextNodeId) {
+            const lastCase = caseSteps[caseSteps.length - 1]
+            if (!lastCase.next && !isTerminalFlow(lastCase))
+              lastCase.next = nextNodeId
+          }
+          caseNodes.push(...caseSteps)
+        }
+      }
+
+      let defaultEntry: string | undefined
+      if (step.defaultSteps) {
+        const defaultNodes = convertStepsToNodes(
+          step.defaultSteps,
+          `${nodeId}_default`
+        )
+        if (defaultNodes.length > 0) {
+          defaultEntry = defaultNodes[0].nodeId
+          // Link last default node to next (unless terminal flow)
+          if (nextNodeId) {
+            const lastDefault = defaultNodes[defaultNodes.length - 1]
+            if (!lastDefault.next && !isTerminalFlow(lastDefault))
+              lastDefault.next = nextNodeId
+          }
+          caseNodes.push(...defaultNodes)
+        }
+      }
+
+      const node: FlowNode = {
+        nodeId,
+        flow: 'switch',
+        expression: step.expression,
+        cases,
+        defaultEntry,
+        next: nextNodeId,
+      }
+
+      return [node, ...caseNodes]
+    }
+
+    case 'parallel': {
+      // Convert children to nodes
+      const childNodes: SerializedGraphNode[] = []
+      const childEntries: string[] = []
+
+      for (let i = 0; i < step.children.length; i++) {
+        const childSteps = convertStepToNode(
+          step.children[i],
+          i,
+          step.children,
+          `${nodeId}_child`
+        )
+        if (childSteps.length > 0) {
+          childEntries.push(childSteps[0].nodeId)
+          childNodes.push(...childSteps)
+        }
+      }
+
+      const node: FlowNode = {
+        nodeId,
+        flow: 'parallel',
+        children: childEntries,
+        next: nextNodeId,
+      }
+
+      return [node, ...childNodes]
+    }
+
+    case 'fanout': {
+      // Convert child step
+      const childNodes = convertStepToNode(
+        step.child,
+        0,
+        [step.child],
+        `${nodeId}_item`
+      )
+
+      const node: FlowNode = {
+        nodeId,
+        flow: 'fanout',
+        stepName: step.stepName,
+        sourceVar: step.sourceVar,
+        itemVar: step.itemVar,
+        mode: step.mode,
+        childEntry: childNodes.length > 0 ? childNodes[0].nodeId : undefined,
+        timeBetween: step.timeBetween,
+        next: nextNodeId,
+      }
+
+      return [node, ...childNodes]
+    }
+
+    case 'filter': {
+      const node: FlowNode = {
+        nodeId,
+        flow: 'filter',
+        sourceVar: step.sourceVar,
+        itemVar: step.itemVar,
+        condition: step.condition,
+        outputVar: step.outputVar,
+        next: nextNodeId,
+      }
+      return [node]
+    }
+
+    case 'arrayPredicate': {
+      const node: FlowNode = {
+        nodeId,
+        flow: 'arrayPredicate',
+        mode: step.mode,
+        sourceVar: step.sourceVar,
+        itemVar: step.itemVar,
+        condition: step.condition,
+        outputVar: step.outputVar,
+        next: nextNodeId,
+      }
+      return [node]
+    }
+
+    case 'return': {
+      const node: FlowNode = {
+        nodeId,
+        flow: 'return',
+        outputs: step.outputs,
+      }
+      return [node]
+    }
+
+    case 'cancel': {
+      const node: FlowNode = {
+        nodeId,
+        flow: 'cancel',
+        reason: step.reason,
+      }
+      return [node]
+    }
+
+    case 'set': {
+      const node: FlowNode = {
+        nodeId,
+        flow: 'set',
+        variable: step.variable,
+        value: step.value,
+        next: nextNodeId,
+      }
+      return [node]
+    }
+
+    default:
+      return []
+  }
+}
+
+/**
+ * Convert array of steps to graph nodes
+ */
+function convertStepsToNodes(
+  steps: WorkflowStepMeta[],
+  nodeIdPrefix: string = 'step'
+): SerializedGraphNode[] {
+  const allNodes: SerializedGraphNode[] = []
+
+  for (let i = 0; i < steps.length; i++) {
+    const nodes = convertStepToNode(steps[i], i, steps, nodeIdPrefix)
+    allNodes.push(...nodes)
+  }
+
+  return allNodes
+}
+
+/**
+ * Convert a DSL workflow to graph format
+ */
+export function convertDslToGraph(
+  workflowName: string,
+  meta: WorkflowsMeta[string]
+): SerializedWorkflowGraph {
+  const nodes = convertStepsToNodes(meta.steps)
+  const nodesRecord: Record<string, SerializedGraphNode> = {}
+
+  for (const node of nodes) {
+    nodesRecord[node.nodeId] = node
+  }
+
+  // Find entry nodes (step_0 is always entry for sequential workflows)
+  const entryNodeIds = nodes.length > 0 ? ['step_0'] : []
+
+  // Determine source type based on dsl flag:
+  // - dsl === true: pure DSL workflow, can be serialized
+  // - dsl === false: complex workflow with inline steps, not serializable
+  const source = meta.dsl === false ? 'complex' : 'dsl'
+
+  return {
+    name: workflowName,
+    pikkuFuncName: meta.pikkuFuncName,
+    source,
+    description: meta.description,
+    tags: meta.tags,
+    context: meta.context,
+    wires: {}, // DSL workflows don't have explicit wires in meta
+    nodes: nodesRecord,
+    entryNodeIds,
+  }
+}
+
+/**
+ * Convert all DSL workflows to graph format
+ */
+export function convertAllDslToGraphs(
+  workflowsMeta: WorkflowsMeta
+): Record<string, SerializedWorkflowGraph> {
+  const result: Record<string, SerializedWorkflowGraph> = {}
+
+  for (const [name, meta] of Object.entries(workflowsMeta)) {
+    result[name] = convertDslToGraph(name, meta)
+  }
+
+  return result
+}

package/src/utils/workflow/graph/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Workflow graph serialization exports
+ */
+export * from './workflow-graph.types.js'
+export { serializeWorkflowGraph } from './serialize-workflow-graph.js'
+export { convertDslToGraph } from './convert-dsl-to-graph.js'

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,
+  }
+}