@pikku/inspector 0.12.75 → 0.12.81

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

@@ -1,310 +0,0 @@
-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.test.ts

@@ -1,50 +0,0 @@
-import { test } from 'node:test'
-import assert from 'node:assert'
-import { computeGraphHash } from './finalize-workflows.js'
-import type {
-  SerializedWorkflowGraph,
-  FunctionNode,
-} from './workflow-graph.types.js'
-
-function graph(
-  overrides: Partial<SerializedWorkflowGraph> = {},
-  nodeOverrides: Partial<FunctionNode> = {}
-): SerializedWorkflowGraph {
-  const node: FunctionNode = {
-    nodeId: 'a',
-    rpcName: 'doThing',
-    input: { x: { $ref: 'trigger', path: 'x' } },
-    next: 'b',
-    ...nodeOverrides,
-  }
-  return {
-    name: 'wf',
-    pikkuFuncId: 'wf',
-    source: 'graph',
-    nodes: { a: node, b: { nodeId: 'b', rpcName: 'finish' } },
-    entryNodeIds: ['a'],
-    ...overrides,
-  }
-}
-
-test('computeGraphHash: node-level notes do not change the hash', () => {
-  const without = computeGraphHash(graph())
-  const withNote = computeGraphHash(
-    graph({}, { notes: 'imported node "Do Thing"' })
-  )
-  assert.strictEqual(withNote, without)
-})
-
-test('computeGraphHash: graph-level notes do not change the hash', () => {
-  const without = computeGraphHash(graph())
-  const withNotes = computeGraphHash(
-    graph({ notes: ['sticky note one', 'sticky note two'] })
-  )
-  assert.strictEqual(withNotes, without)
-})
-
-test('computeGraphHash: a topology change DOES change the hash', () => {
-  const base = computeGraphHash(graph())
-  const changed = computeGraphHash(graph({}, { next: 'c' }))
-  assert.notStrictEqual(changed, base)
-})

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

@@ -1,130 +0,0 @@
-import type { FunctionsMeta } from '@pikku/core/services'
-import {
-  isVersionedId,
-  formatVersionedId,
-  parseVersionedId,
-} from '@pikku/core/utils'
-import type { SerializedWorkflowGraph } from './workflow-graph.types.js'
-import { canonicalJSON, hashString } from '../../hash.js'
-import { convertDslToGraph } from './convert-dsl-to-graph.js'
-import { deriveWorkflowPlan } from '../derive-workflow-plan.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)
-    // Predictable (loopless) DSL workflows carry their full step list so a UI
-    // can render the skeleton up front without executing the run. Only DSL is
-    // gated: a complex workflow's step tree is incomplete (inline JS branches
-    // aren't captured) and flattens loops into plain steps, so its plan would
-    // lie about determinism.
-    if (graph.source === 'dsl') {
-      const { deterministic, plannedSteps } = deriveWorkflowPlan(meta.steps)
-      graph.deterministic = deterministic
-      // Omit an empty list — a deterministic workflow with no plannedSteps is
-      // simply one with no named steps (e.g. a bare return).
-      if (plannedSteps?.length) {
-        graph.plannedSteps = plannedSteps
-      }
-    }
-    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
-    )
-  }
-}
-
-/**
- * Hash of graph topology only. `notes` (node- and graph-level) is deliberately
- * excluded so editing documentation never changes the hash / marks the workflow
- * as a new version.
- */
-export function computeGraphHash(graph: SerializedWorkflowGraph): string {
-  const nodesForHash = Object.fromEntries(
-    Object.entries(graph.nodes).map(([nodeId, node]) => {
-      const { notes: _notes, ...rest } = node as { notes?: string }
-      return [nodeId, rest]
-    })
-  )
-  return hashString(
-    canonicalJSON({
-      source: graph.source,
-      context: graph.context,
-      nodes: nodesForHash,
-      entryNodeIds: graph.entryNodeIds,
-    }),
-    12
-  )
-}

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

@@ -1,28 +0,0 @@
-/**
- * Workflow graph serialization exports
- */
-export {
-  isDataRef,
-  isFunctionNode,
-  ref,
-  state,
-} from './workflow-graph.types.js'
-export type {
-  BranchCondition,
-  ContextVariable,
-  DataRef,
-  FlowNode,
-  ForEachMode,
-  FunctionNode,
-  NodeOptions,
-  SerializedWorkflowGraph,
-  SerializedWorkflowGraphs,
-  WorkflowContext,
-} 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'