@pikku/inspector 0.12.74 → 0.12.81

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

@@ -1,240 +0,0 @@
-import { isRef, template } from '@pikku/core/workflow'
-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,
-  }
-}
-
-/**
- * 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 (isRef(value)) {
-      result[key] = convertRef(value)
-    } else {
-      result[key] = value
-    }
-  }
-
-  return result
-}
-
-/**
- * Convert a `forEach` source — a bare node id, a ref, or a `(ref) => ref(...)`
- * callback — to the serialized DataRef form
- */
-function serializeForEach(
-  forEach: unknown,
-  createRef: (nodeId: string, path?: string) => { nodeId: string; path?: string }
-): DataRef | undefined {
-  if (forEach === undefined) return undefined
-  if (typeof forEach === 'string') return { $ref: forEach }
-  if (typeof forEach === 'function') {
-    return serializeForEach(
-      (forEach as (ref: unknown) => unknown)(createRef),
-      createRef
-    )
-  }
-  if (isRef(forEach)) return convertRef(forEach)
-  return undefined
-}
-
-/**
- * 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, template?: any, $item?: any) => Record<string, unknown>
-        forEach?: string | { nodeId: string; path?: string } | ((ref: any) => unknown)
-        mode?: 'parallel' | 'sequential'
-        next?: string | string[] | Record<string, string | string[]>
-        onError?: string | string[]
-        notes?: string
-      }
-    >
-  },
-  options?: {
-    description?: string
-    tags?: string[]
-    notes?: 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,
-  })
-
-  const createItemRef = (path?: string) => createRef('$item', 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, template, createItemRef)
-      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,
-    }
-    const forEach = serializeForEach(node.forEach, createRef)
-    if (forEach) {
-      funcNode.forEach = forEach
-      if (node.mode !== undefined) {
-        funcNode.mode = node.mode
-      }
-    }
-    if (node.notes !== undefined) {
-      funcNode.notes = node.notes
-    }
-    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,
-    notes: options?.notes,
-    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,
-  }
-}

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

@@ -1,281 +0,0 @@
-/**
- * Serialized types for workflow graphs
- * These are extracted by the inspector and stored as JSON
- * Can be created from code (pikkuWorkflowGraph) 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[]
-    }
-  // Key-based branching: the running node picks a key via `graph.branch(key)`,
-  // routing to `next[key]`. Keys are branch/output identifiers, not predicates.
-  | Record<string, string | string[]>
-
-/**
- * Node execution options
- */
-export interface NodeOptions {
-  /** Number of retry attempts on failure */
-  retries?: number
-  /** Delay between retries (e.g., '1s', '5s', or a number of milliseconds) */
-  retryDelay?: string | number
-  /** Timeout for node execution (e.g., '30s', '5m') */
-  timeout?: string
-}
-
-/**
- * Flow node types for control flow (no RPC call)
- */
-export type FlowType =
-  | 'sleep'
-  | 'suspend'
-  | 'approval'
-  | 'branch'
-  | 'parallel'
-  | 'fanout'
-  | 'inline'
-  | 'switch'
-  | 'filter'
-  | 'arrayPredicate'
-  | 'return'
-  | 'cancel'
-  | 'set'
-
-// Import and re-export context types from core
-import type {
-  ContextVariable,
-  WorkflowContext,
-  WorkflowPlannedStep,
-} from '@pikku/core/workflow'
-import type { ScenarioStepPhase } from '@pikku/core/scenario'
-
-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
-  /** Free-text node documentation. Non-semantic — excluded from graphHash. */
-  notes?: string
-}
-
-/**
- * Function node - calls an RPC
- */
-/** How the per-item instances of a `forEach` node run */
-export type ForEachMode = 'parallel' | 'sequential'
-
-export interface FunctionNode extends BaseNode {
-  /** RPC function name */
-  rpcName: string
-  /** Input mapping - values can be literals or DataRefs */
-  input?: Record<string, unknown | DataRef>
-  /**
-   * Run this node once per element of the referenced array. The node's own
-   * result becomes the ordered array of per-item results.
-   */
-  forEach?: DataRef
-  /** How the per-item instances run. Defaults to 'parallel'. */
-  mode?: ForEachMode
-  /** Output variable name for storing result */
-  outputVar?: string
-  /** Hash of nodeId + RPC input/output schemas for version detection */
-  stepHash?: string
-  /** Scenario actor name this step runs as (workflow.do {actor: actors.x}) */
-  actor?: string
-  /** True for workflow.expectEventually polling steps (scenarios) */
-  expectEventually?: boolean
-  /** Gherkin-style phase for a declared scenario step (scenario.given/when/then) */
-  scenarioStepPhase?: ScenarioStepPhase
-}
-
-/**
- * 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
-
-/**
- * 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)
- * - 'scenario': Scenario (pikkuScenario) - complex workflow whose steps run as actors
- */
-export type WorkflowSourceType = 'dsl' | 'complex' | 'graph' | 'scenario'
-
-/**
- * Serialized workflow graph - the canonical JSON format
- */
-export interface SerializedWorkflowGraph {
-  /** Workflow name */
-  name: string
-  /** Pikku function name (for runtime registration) */
-  pikkuFuncId: string
-  /** Source type: 'dsl' for pikkuWorkflowFunc, 'graph' for pikkuWorkflowGraph */
-  source: WorkflowSourceType
-  /** Optional short display name */
-  title?: string
-  /** Optional description */
-  description?: string
-  /** Tags for organization */
-  tags?: string[]
-  /** Actor names a scenario's steps run as */
-  actors?: string[]
-  /** Why a scenario is held out of a default run, stated where it is declared */
-  skip?: string
-  /** If true, workflow always executes inline without queues */
-  inline?: boolean
-  /** Workflow context/state variables (from Zod schema) */
-  context?: WorkflowContext
-  /** Serialized nodes */
-  nodes: Record<string, SerializedGraphNode>
-  /** Graph-level free-text notes (e.g. imported sticky notes). Non-semantic — excluded from graphHash. */
-  notes?: string[]
-  /** Entry node(s) - first nodes to execute */
-  entryNodeIds: string[]
-  /** Hash of graph topology (nodes, edges, input mappings) */
-  graphHash?: string
-  /**
-   * True when the exact executed step sequence is known up front: a loopless
-   * DSL workflow with no branches/switches. Lets a UI render the run as a fixed
-   * pipeline. Loops (fanout) → omitted; branchy-but-loopless → false.
-   */
-  deterministic?: boolean
-  /**
-   * Every named step the workflow can run, in source order — so a frontend can
-   * render the step skeleton before the run starts. Populated for any loopless
-   * DSL workflow (a branchy one lists all possible steps); omitted when the step
-   * count is runtime-dependent (any fanout).
-   */
-  plannedSteps?: WorkflowPlannedStep[]
-  /** Wire entry points (HTTP, channel, queue, etc.) that trigger this workflow */
-  wires?: WorkflowWires
-}
-
-export interface WorkflowWires {
-  http?: Array<{ route: string; method: string; startNode: string }>
-  channel?: Array<{
-    name: string
-    route: string
-    onConnect?: string
-    onMessage?: string
-    onDisconnect?: string
-    onMessageRoute?: Record<string, string>
-  }>
-  queue?: Array<{ name: string; startNode: string }>
-  cli?: Array<{ command: string; startNode: string }>
-  mcp?: {
-    tool?: Array<{ name: string; startNode: string }>
-    prompt?: Array<{ name: string; startNode: string }>
-    resource?: Array<{ uri: string; startNode: string }>
-  }
-  schedule?: Array<{ cron: string; startNode: string }>
-  trigger?: Array<{ name: string; startNode: string }>
-}
-
-/**
- * All workflow graphs (serialized)
- */
-export type SerializedWorkflowGraphs = Record<string, SerializedWorkflowGraph>

package/src/visit.ts

@@ -1,181 +0,0 @@
-import * as ts from 'typescript'
-import { addFileWithFactory } from './add/add-file-with-factory.js'
-import { addFileExtendsCoreType } from './add/add-file-extends-core-type.js'
-import { addHTTPRoute } from './add/add-http-route.js'
-import { addHTTPRoutes } from './add/add-http-routes.js'
-import { checkAddonBans } from './add/add-addon-bans.js'
-import { addSchedule } from './add/add-schedule.js'
-import { addTrigger } from './add/add-trigger.js'
-import { addQueueWorker } from './add/add-queue-worker.js'
-import { addWorkflow } from './add/add-workflow.js'
-import { addMCPResource } from './add/add-mcp-resource.js'
-import { addMCPPrompt } from './add/add-mcp-prompt.js'
-import type {
-  InspectorState,
-  InspectorLogger,
-  InspectorOptions,
-} from './types.js'
-import { addFunctions } from './add/add-functions.js'
-import { addChannel } from './add/add-channel.js'
-import { addGateway } from './add/add-gateway.js'
-import { addRPCInvocations } from './add/add-rpc-invocations.js'
-import { addWireAddon } from './add/add-wire-addon.js'
-import { addWireRemoteAddon } from './add/add-wire-remote-addon.js'
-import { addMiddleware } from './add/add-middleware.js'
-import { addPermission } from './add/add-permission.js'
-import { addCLI, addCLIRenderers } from './add/add-cli.js'
-import { addAuth } from './add/add-auth.js'
-import { addSecret } from './add/add-secret.js'
-import { addCredential } from './add/add-credential.js'
-import { addScope } from './add/add-scope.js'
-import { addSystemRole } from './add/add-system-role.js'
-import { addPersonas } from './add/add-personas.js'
-import { addVariable } from './add/add-variable.js'
-import { addWorkflowGraph } from './add/add-workflow-graph.js'
-import { addFeature } from './add/add-feature.js'
-import { addAgent } from './add/add-agent.js'
-import { addAgentScorer } from './add/add-agent-scorer.js'
-import { addApprovalDescription } from './add/add-approval-description.js'
-
-export const visitSetup = (
-  logger: InspectorLogger,
-  checker: ts.TypeChecker,
-  node: ts.Node,
-  state: InspectorState,
-  options: InspectorOptions
-) => {
-  addFileExtendsCoreType(
-    node,
-    checker,
-    state.singletonServicesTypeImportMap,
-    'CoreSingletonServices',
-    state
-  )
-
-  addFileExtendsCoreType(
-    node,
-    checker,
-    state.wireServicesTypeImportMap,
-    'CoreServices',
-    state
-  )
-
-  addFileExtendsCoreType(
-    node,
-    checker,
-    state.userSessionTypeImportMap,
-    'CoreUserSession',
-    state
-  )
-
-  addFileExtendsCoreType(
-    node,
-    checker,
-    state.configTypeImportMap,
-    'CoreConfig',
-    state
-  )
-
-  addFileWithFactory(
-    node,
-    checker,
-    state.singletonServicesFactories,
-    'CreateSingletonServices',
-    state
-  )
-
-  addFileWithFactory(
-    node,
-    checker,
-    state.wireServicesFactories,
-    'CreateWireServices',
-    state
-  )
-
-  addFileWithFactory(node, checker, state.configFactories, 'CreateConfig')
-  addFileWithFactory(
-    node,
-    checker,
-    state.serverLifecycleFactories,
-    'ServerLifecycle'
-  )
-
-  addRPCInvocations(node, state, logger)
-  addWireAddon(node, state, logger)
-  addWireRemoteAddon(node, state, logger)
-  addMiddleware(logger, node, checker, state, options)
-  addPermission(logger, node, checker, state, options)
-  addApprovalDescription(logger, node, checker, state, options)
-  addWorkflow(logger, node, checker, state, options)
-
-  ts.forEachChild(node, (child) =>
-    visitSetup(logger, checker, child, state, options)
-  )
-}
-
-// Register every pikku function before transports/wirings are resolved, so that
-// resolution (e.g. a channel handler referencing a function defined in another
-// file) is independent of source-file traversal order. Runs between visitSetup
-// and visitRoutes.
-export const visitFunctions = (
-  logger: InspectorLogger,
-  checker: ts.TypeChecker,
-  node: ts.Node,
-  state: InspectorState,
-  options: InspectorOptions
-) => {
-  const nextOptions = ts.isSourceFile(node)
-    ? { ...options, sourceFile: node }
-    : options
-
-  addFunctions(logger, node, checker, state, nextOptions)
-
-  ts.forEachChild(node, (child) =>
-    visitFunctions(logger, checker, child, state, nextOptions)
-  )
-}
-
-export const visitRoutes = (
-  logger: InspectorLogger,
-  checker: ts.TypeChecker,
-  node: ts.Node,
-  state: InspectorState,
-  options: InspectorOptions
-) => {
-  const nextOptions = ts.isSourceFile(node)
-    ? { ...options, sourceFile: node }
-    : options
-
-  checkAddonBans(logger, node, checker, state, nextOptions)
-
-  // NOTE: addFunctions runs in its own earlier pass (visitFunctions) so that
-  // every function is registered before any wiring (channels, CLI, etc.)
-  // resolves it — wiring resolution must not depend on source-file order.
-  addAuth(logger, node, checker, state, nextOptions)
-  addSecret(logger, node, checker, state, nextOptions)
-  addCredential(logger, node, checker, state, nextOptions)
-  addScope(logger, node, checker, state, nextOptions)
-  addSystemRole(logger, node, checker, state, nextOptions)
-  addPersonas(logger, node, checker, state, nextOptions)
-  addVariable(logger, node, checker, state, nextOptions)
-
-  addHTTPRoute(logger, node, checker, state, nextOptions)
-  addHTTPRoutes(logger, node, checker, state, nextOptions)
-  addSchedule(logger, node, checker, state, nextOptions)
-  addTrigger(logger, node, checker, state, nextOptions)
-  addQueueWorker(logger, node, checker, state, nextOptions)
-  addChannel(logger, node, checker, state, nextOptions)
-  addGateway(logger, node, checker, state, nextOptions)
-  addCLI(logger, node, checker, state, nextOptions)
-  addCLIRenderers(logger, node, checker, state, nextOptions)
-  addMCPResource(logger, node, checker, state, nextOptions)
-  addMCPPrompt(logger, node, checker, state, nextOptions)
-  addWorkflowGraph(logger, node, checker, state, nextOptions)
-  addFeature(logger, node, checker, state, nextOptions)
-  addAgent(logger, node, checker, state, nextOptions)
-  addAgentScorer(logger, node, checker, state, nextOptions)
-
-  ts.forEachChild(node, (child) =>
-    visitRoutes(logger, checker, child, state, nextOptions)
-  )
-}