@pikku/inspector 0.11.1 → 0.12.0

package/src/utils/workflow/graph/finalize-workflow-wires.ts

@@ -0,0 +1,310 @@
+import type { InspectorState } from '../../../types.js'
+import type {
+  SerializedWorkflowGraph,
+  WorkflowWires,
+} from './workflow-graph.types.js'
+import type { CLICommandMeta } from '@pikku/core/cli'
+
+function parseWorkflowFuncId(
+  pikkuFuncId: string
+): { workflowName: string; startNode?: string } | null {
+  for (const prefix of ['workflowStart:', 'workflow:']) {
+    if (pikkuFuncId.startsWith(prefix)) {
+      return { workflowName: pikkuFuncId.slice(prefix.length) }
+    }
+  }
+  if (pikkuFuncId.startsWith('graphStart:')) {
+    const rest = pikkuFuncId.slice('graphStart:'.length)
+    const colonIdx = rest.indexOf(':')
+    if (colonIdx !== -1) {
+      return {
+        workflowName: rest.slice(0, colonIdx),
+        startNode: rest.slice(colonIdx + 1),
+      }
+    }
+  }
+  return null
+}
+
+function resolveStartNode(
+  parsed: { workflowName: string; startNode?: string },
+  graph: SerializedWorkflowGraph
+): string {
+  return parsed.startNode ?? graph.entryNodeIds[0]
+}
+
+function getOrCreateWires(graph: SerializedWorkflowGraph): WorkflowWires {
+  if (!graph.wires) {
+    graph.wires = {}
+  }
+  return graph.wires
+}
+
+export function finalizeWorkflowHelperTypes(state: InspectorState): void {
+  const { functions, workflows } = state
+  const graphMeta = workflows.graphMeta
+
+  for (const meta of Object.values(functions.meta)) {
+    if (meta.functionType !== 'helper') continue
+    if (meta.pikkuFuncId.startsWith('workflowStatus:')) continue
+
+    const parsed = parseWorkflowFuncId(meta.pikkuFuncId)
+    if (!parsed) continue
+
+    const graph = graphMeta[parsed.workflowName]
+    if (!graph) continue
+
+    const startNodeId = resolveStartNode(parsed, graph)
+    const startNode = graph.nodes[startNodeId]
+    if (!startNode || !('rpcName' in startNode)) continue
+
+    const rpcMeta = functions.meta[startNode.rpcName as string]
+    if (!rpcMeta) continue
+
+    if (rpcMeta.inputSchemaName) {
+      meta.inputSchemaName = rpcMeta.inputSchemaName
+    }
+    if (rpcMeta.inputs && rpcMeta.inputs.length > 0) {
+      meta.inputs = rpcMeta.inputs
+    }
+  }
+}
+
+export function finalizeWorkflowWires(state: InspectorState): void {
+  const { workflows } = state
+  const graphMeta = workflows.graphMeta
+
+  scanHTTP(state, graphMeta)
+  scanScheduledTasks(state, graphMeta)
+  scanTriggers(state, graphMeta)
+  scanQueueWorkers(state, graphMeta)
+  scanChannels(state, graphMeta)
+  scanMCPEndpoints(state, graphMeta)
+  scanCLI(state, graphMeta)
+}
+
+function scanHTTP(
+  state: InspectorState,
+  graphMeta: Record<string, SerializedWorkflowGraph>
+): void {
+  for (const [method, routes] of Object.entries(state.http.meta)) {
+    for (const [route, meta] of Object.entries(routes)) {
+      const parsed = parseWorkflowFuncId(meta.pikkuFuncId)
+      if (!parsed) continue
+      const graph = graphMeta[parsed.workflowName]
+      if (!graph) continue
+      const wires = getOrCreateWires(graph)
+      if (!wires.http) wires.http = []
+      wires.http.push({
+        route,
+        method,
+        startNode: resolveStartNode(parsed, graph),
+      })
+    }
+  }
+}
+
+function scanScheduledTasks(
+  state: InspectorState,
+  graphMeta: Record<string, SerializedWorkflowGraph>
+): void {
+  for (const meta of Object.values(state.scheduledTasks.meta)) {
+    const parsed = parseWorkflowFuncId(meta.pikkuFuncId)
+    if (!parsed) continue
+    const graph = graphMeta[parsed.workflowName]
+    if (!graph) continue
+    const wires = getOrCreateWires(graph)
+    if (!wires.schedule) wires.schedule = []
+    wires.schedule.push({
+      cron: meta.schedule,
+      startNode: resolveStartNode(parsed, graph),
+    })
+  }
+}
+
+function scanTriggers(
+  state: InspectorState,
+  graphMeta: Record<string, SerializedWorkflowGraph>
+): void {
+  for (const meta of Object.values(state.triggers.meta)) {
+    const parsed = parseWorkflowFuncId(meta.pikkuFuncId)
+    if (!parsed) continue
+    const graph = graphMeta[parsed.workflowName]
+    if (!graph) continue
+    const wires = getOrCreateWires(graph)
+    if (!wires.trigger) wires.trigger = []
+    wires.trigger.push({
+      name: meta.name,
+      startNode: resolveStartNode(parsed, graph),
+    })
+  }
+}
+
+function scanQueueWorkers(
+  state: InspectorState,
+  graphMeta: Record<string, SerializedWorkflowGraph>
+): void {
+  for (const meta of Object.values(state.queueWorkers.meta)) {
+    const parsed = parseWorkflowFuncId(meta.pikkuFuncId)
+    if (!parsed) continue
+    const graph = graphMeta[parsed.workflowName]
+    if (!graph) continue
+    const wires = getOrCreateWires(graph)
+    if (!wires.queue) wires.queue = []
+    wires.queue.push({
+      name: meta.name,
+      startNode: resolveStartNode(parsed, graph),
+    })
+  }
+}
+
+function scanChannels(
+  state: InspectorState,
+  graphMeta: Record<string, SerializedWorkflowGraph>
+): void {
+  for (const channelMeta of Object.values(state.channels.meta)) {
+    const wire: NonNullable<WorkflowWires['channel']>[number] = {
+      name: channelMeta.name,
+      route: channelMeta.route,
+    }
+    let targetWorkflow: SerializedWorkflowGraph | undefined
+
+    if (channelMeta.connect) {
+      const parsed = parseWorkflowFuncId(channelMeta.connect.pikkuFuncId)
+      if (parsed) {
+        const graph = graphMeta[parsed.workflowName]
+        if (graph) {
+          targetWorkflow = graph
+          wire.onConnect = resolveStartNode(parsed, graph)
+        }
+      }
+    }
+
+    if (channelMeta.disconnect) {
+      const parsed = parseWorkflowFuncId(channelMeta.disconnect.pikkuFuncId)
+      if (parsed) {
+        const graph = graphMeta[parsed.workflowName]
+        if (graph) {
+          targetWorkflow = targetWorkflow ?? graph
+          wire.onDisconnect = resolveStartNode(parsed, graph)
+        }
+      }
+    }
+
+    if (channelMeta.message) {
+      const parsed = parseWorkflowFuncId(channelMeta.message.pikkuFuncId)
+      if (parsed) {
+        const graph = graphMeta[parsed.workflowName]
+        if (graph) {
+          targetWorkflow = targetWorkflow ?? graph
+          wire.onMessage = resolveStartNode(parsed, graph)
+        }
+      }
+    }
+
+    for (const [routingProp, routeMap] of Object.entries(
+      channelMeta.messageWirings
+    )) {
+      for (const [routeValue, messageMeta] of Object.entries(routeMap)) {
+        const parsed = parseWorkflowFuncId(messageMeta.pikkuFuncId)
+        if (!parsed) continue
+        const graph = graphMeta[parsed.workflowName]
+        if (!graph) continue
+        targetWorkflow = targetWorkflow ?? graph
+        if (!wire.onMessageRoute) wire.onMessageRoute = {}
+        wire.onMessageRoute[`${routingProp}:${routeValue}`] = resolveStartNode(
+          parsed,
+          graph
+        )
+      }
+    }
+
+    if (targetWorkflow) {
+      const wires = getOrCreateWires(targetWorkflow)
+      if (!wires.channel) wires.channel = []
+      wires.channel.push(wire)
+    }
+  }
+}
+
+function scanMCPEndpoints(
+  state: InspectorState,
+  graphMeta: Record<string, SerializedWorkflowGraph>
+): void {
+  for (const meta of Object.values(state.mcpEndpoints.toolsMeta)) {
+    const parsed = parseWorkflowFuncId(meta.pikkuFuncId)
+    if (!parsed) continue
+    const graph = graphMeta[parsed.workflowName]
+    if (!graph) continue
+    const wires = getOrCreateWires(graph)
+    if (!wires.mcp) wires.mcp = {}
+    if (!wires.mcp.tool) wires.mcp.tool = []
+    wires.mcp.tool.push({
+      name: meta.name,
+      startNode: resolveStartNode(parsed, graph),
+    })
+  }
+
+  for (const meta of Object.values(state.mcpEndpoints.promptsMeta)) {
+    const parsed = parseWorkflowFuncId(meta.pikkuFuncId)
+    if (!parsed) continue
+    const graph = graphMeta[parsed.workflowName]
+    if (!graph) continue
+    const wires = getOrCreateWires(graph)
+    if (!wires.mcp) wires.mcp = {}
+    if (!wires.mcp.prompt) wires.mcp.prompt = []
+    wires.mcp.prompt.push({
+      name: meta.name,
+      startNode: resolveStartNode(parsed, graph),
+    })
+  }
+
+  for (const meta of Object.values(state.mcpEndpoints.resourcesMeta)) {
+    const parsed = parseWorkflowFuncId(meta.pikkuFuncId)
+    if (!parsed) continue
+    const graph = graphMeta[parsed.workflowName]
+    if (!graph) continue
+    const wires = getOrCreateWires(graph)
+    if (!wires.mcp) wires.mcp = {}
+    if (!wires.mcp.resource) wires.mcp.resource = []
+    wires.mcp.resource.push({
+      uri: meta.uri,
+      startNode: resolveStartNode(parsed, graph),
+    })
+  }
+}
+
+function visitCLICommands(
+  commands: Record<string, CLICommandMeta>,
+  programName: string,
+  path: string[],
+  graphMeta: Record<string, SerializedWorkflowGraph>
+): void {
+  for (const [name, command] of Object.entries(commands)) {
+    const currentPath = [...path, name]
+    const parsed = parseWorkflowFuncId(command.pikkuFuncId)
+    if (parsed) {
+      const graph = graphMeta[parsed.workflowName]
+      if (graph) {
+        const wires = getOrCreateWires(graph)
+        if (!wires.cli) wires.cli = []
+        wires.cli.push({
+          command: `${programName} ${currentPath.join(' ')}`,
+          startNode: resolveStartNode(parsed, graph),
+        })
+      }
+    }
+    if (command.subcommands) {
+      visitCLICommands(command.subcommands, programName, currentPath, graphMeta)
+    }
+  }
+}
+
+function scanCLI(
+  state: InspectorState,
+  graphMeta: Record<string, SerializedWorkflowGraph>
+): void {
+  for (const program of Object.values(state.cli.meta.programs)) {
+    visitCLICommands(program.commands, program.program, [], graphMeta)
+  }
+}

package/src/utils/workflow/graph/finalize-workflows.ts

@@ -0,0 +1,100 @@
+import type { FunctionsMeta } from '@pikku/core'
+import { isVersionedId, formatVersionedId, parseVersionedId } from '@pikku/core'
+import type { SerializedWorkflowGraph } from './workflow-graph.types.js'
+import { canonicalJSON, hashString } from '../../hash.js'
+import { convertDslToGraph } from './convert-dsl-to-graph.js'
+import type { InspectorState } from '../../../types.js'
+
+export function finalizeWorkflows(state: InspectorState): void {
+  const { workflows, functions } = state
+  const functionsMeta = functions.meta
+
+  for (const [name, meta] of Object.entries(workflows.meta)) {
+    const graph = convertDslToGraph(name, meta)
+    stampVersionsOnGraph(graph, functionsMeta)
+    computeStepHashes(graph, functionsMeta)
+    graph.graphHash = computeGraphHash(graph)
+    workflows.graphMeta[name] = graph
+  }
+
+  for (const graph of Object.values(workflows.graphMeta)) {
+    if (graph.graphHash) {
+      continue
+    }
+    stampVersionsOnGraph(graph, functionsMeta)
+    computeStepHashes(graph, functionsMeta)
+    graph.graphHash = computeGraphHash(graph)
+  }
+}
+
+function stampVersionsOnGraph(
+  graph: SerializedWorkflowGraph,
+  functionsMeta: FunctionsMeta
+): void {
+  for (const node of Object.values(graph.nodes)) {
+    if (!('rpcName' in node) || typeof node.rpcName !== 'string') {
+      continue
+    }
+
+    if (isVersionedId(node.rpcName)) {
+      continue
+    }
+
+    const meta = functionsMeta[node.rpcName]
+    if (meta?.version !== undefined) {
+      node.rpcName = formatVersionedId(node.rpcName, meta.version)
+    } else {
+      const latestVersion = findLatestVersion(node.rpcName, functionsMeta)
+      if (latestVersion > 0) {
+        node.rpcName = formatVersionedId(node.rpcName, latestVersion)
+      }
+    }
+  }
+}
+
+function findLatestVersion(
+  baseName: string,
+  functionsMeta: FunctionsMeta
+): number {
+  let max = 0
+  for (const id of Object.keys(functionsMeta)) {
+    const parsed = parseVersionedId(id)
+    if (parsed.baseName === baseName && parsed.version !== null) {
+      max = Math.max(max, parsed.version)
+    }
+  }
+  return max
+}
+
+function computeStepHashes(
+  graph: SerializedWorkflowGraph,
+  functionsMeta: FunctionsMeta
+): void {
+  for (const node of Object.values(graph.nodes)) {
+    if (!('rpcName' in node) || typeof node.rpcName !== 'string') {
+      continue
+    }
+    const rpcName: string = node.rpcName
+    let meta = functionsMeta[rpcName]
+    if (!meta) {
+      const { baseName } = parseVersionedId(rpcName)
+      meta = functionsMeta[baseName]
+    }
+    ;(node as Record<string, unknown>).stepHash = hashString(
+      `${node.nodeId}:${meta?.contractHash ?? ''}`,
+      12
+    )
+  }
+}
+
+function computeGraphHash(graph: SerializedWorkflowGraph): string {
+  return hashString(
+    canonicalJSON({
+      source: graph.source,
+      context: graph.context,
+      nodes: graph.nodes,
+      entryNodeIds: graph.entryNodeIds,
+    }),
+    12
+  )
+}

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

@@ -0,0 +1,11 @@
+/**
+ * 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'
+export { finalizeWorkflows } from './finalize-workflows.js'
+export {
+  finalizeWorkflowHelperTypes,
+  finalizeWorkflowWires,
+} from './finalize-workflow-wires.js'

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

@@ -0,0 +1,216 @@
+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
+    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,
+    pikkuFuncId: definition.name, // For graph workflows, pikkuFuncId is the workflow name
+    source: 'graph' as const,
+    description: options?.description,
+    tags: options?.tags,
+    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
+  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,
+    graph,
+    entryNodeIds: serialized.entryNodeIds,
+  }
+}