@pikku/core 0.12.4 → 0.12.6

package/src/wirings/workflow/graph/graph-validation.test.ts

@@ -0,0 +1,170 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  computeEntryNodeIds,
+  validateWorkflowWiring,
+  generateMermaidDiagram,
+} from './graph-validation.js'
+
+describe('computeEntryNodeIds', () => {
+  it('returns nodes not referenced by any other node', () => {
+    const nodes = {
+      start: { rpcName: 'a', next: 'middle' },
+      middle: { rpcName: 'b', next: 'end' },
+      end: { rpcName: 'c' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
+  })
+
+  it('returns multiple entry nodes for parallel starts', () => {
+    const nodes = {
+      a: { rpcName: 'x' },
+      b: { rpcName: 'y' },
+      c: { rpcName: 'z', next: 'a' },
+    }
+    const entries = computeEntryNodeIds(nodes)
+    assert.ok(entries.includes('b'))
+    assert.ok(entries.includes('c'))
+    assert.ok(!entries.includes('a'))
+  })
+
+  it('returns empty for fully circular graph', () => {
+    const nodes = {
+      a: { rpcName: 'x', next: 'b' },
+      b: { rpcName: 'y', next: 'a' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), [])
+  })
+
+  it('handles onError references', () => {
+    const nodes = {
+      start: { rpcName: 'a', next: 'ok', onError: 'err' },
+      ok: { rpcName: 'b' },
+      err: { rpcName: 'c' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
+  })
+
+  it('handles branching next as object', () => {
+    const nodes = {
+      start: { rpcName: 'a', next: { yes: 'b', no: 'c' } },
+      b: { rpcName: 'x' },
+      c: { rpcName: 'y' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
+  })
+
+  it('handles parallel next as array', () => {
+    const nodes = {
+      start: { rpcName: 'a', next: ['b', 'c'] },
+      b: { rpcName: 'x' },
+      c: { rpcName: 'y' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
+  })
+})
+
+describe('validateWorkflowWiring', () => {
+  const tools = ['toolA', 'toolB', 'toolC']
+
+  it('returns no errors for a valid workflow', () => {
+    const nodes = {
+      step1: { rpcName: 'toolA', input: {}, next: 'step2' },
+      step2: { rpcName: 'toolB', input: {} },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.deepEqual(errors, [])
+  })
+
+  it('errors on missing rpcName', () => {
+    const nodes = {
+      step1: { input: {} },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes("missing 'rpcName'")))
+  })
+
+  it('errors on unknown tool', () => {
+    const nodes = {
+      step1: { rpcName: 'unknownTool', input: {} },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes('unknown tool')))
+  })
+
+  it('errors on next referencing unknown node', () => {
+    const nodes = {
+      step1: { rpcName: 'toolA', next: 'nonexistent' },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes("unknown node 'nonexistent'")))
+  })
+
+  it('errors on onError referencing unknown node', () => {
+    const nodes = {
+      step1: { rpcName: 'toolA', onError: 'missing' },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes("unknown node 'missing'")))
+  })
+
+  it('errors on input referencing unknown node', () => {
+    const nodes = {
+      step1: {
+        rpcName: 'toolA',
+        input: { field: { $ref: 'missing', path: 'x' } },
+      },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes("unknown node 'missing'")))
+  })
+
+  it('allows trigger refs without errors', () => {
+    const nodes = {
+      step1: {
+        rpcName: 'toolA',
+        input: { field: { $ref: 'trigger', path: 'title' } },
+        next: 'step2',
+      },
+      step2: { rpcName: 'toolB', input: {} },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.deepEqual(errors, [])
+  })
+
+  it('allows valid node-to-node refs', () => {
+    const nodes = {
+      step1: { rpcName: 'toolA', input: {}, next: 'step2' },
+      step2: {
+        rpcName: 'toolB',
+        input: { data: { $ref: 'step1', path: 'result' } },
+      },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.deepEqual(errors, [])
+  })
+})
+
+describe('generateMermaidDiagram', () => {
+  it('generates valid mermaid output', () => {
+    const nodes = {
+      start: { rpcName: 'toolA', next: 'end' },
+      end: { rpcName: 'toolB' },
+    }
+    const result = generateMermaidDiagram('test-wf', nodes, ['start'])
+    assert.ok(result.includes('graph TD'))
+    assert.ok(result.includes('start([toolA])'))
+    assert.ok(result.includes('end[toolB]'))
+    assert.ok(result.includes('start --> end'))
+  })
+
+  it('shows error edges with dotted lines', () => {
+    const nodes = {
+      start: { rpcName: 'toolA', onError: 'handler' },
+      handler: { rpcName: 'toolB' },
+    }
+    const result = generateMermaidDiagram('test-wf', nodes, ['start'])
+    assert.ok(result.includes('start -.->|error| handler'))
+  })
+})

package/src/wirings/workflow/graph/graph-validation.ts

@@ -0,0 +1,237 @@
+import { pikkuState } from '../../../pikku-state.js'
+import { resolveNamespace } from '../../rpc/rpc-runner.js'
+
+function normalizeTargets(value: unknown): string[] {
+  if (!value) return []
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.filter((v) => typeof v === 'string')
+  if (typeof value === 'object') {
+    const targets: string[] = []
+    for (const v of Object.values(value as Record<string, unknown>)) {
+      targets.push(...normalizeTargets(v))
+    }
+    return targets
+  }
+  return []
+}
+
+function collectRefs(value: unknown, refs: Set<string>): void {
+  if (
+    typeof value === 'object' &&
+    value !== null &&
+    '$ref' in value &&
+    typeof (value as any).$ref === 'string'
+  ) {
+    refs.add((value as any).$ref)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectRefs(item, refs)
+    return
+  }
+  if (typeof value === 'object' && value !== null) {
+    for (const v of Object.values(value)) collectRefs(v, refs)
+  }
+}
+
+function resolveToolMeta(toolName: string): {
+  fnMeta: any
+  schemas: Map<string, any>
+} | null {
+  const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null
+
+  if (resolved) {
+    const fnMeta = pikkuState(resolved.package, 'function', 'meta')[
+      resolved.function
+    ]
+    const schemas = pikkuState(resolved.package, 'misc', 'schemas')
+    return fnMeta ? { fnMeta, schemas } : null
+  }
+
+  const rpcMeta = pikkuState(null, 'rpc', 'meta')
+  const pikkuFuncId = rpcMeta[toolName]
+  if (!pikkuFuncId) return null
+
+  const fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId]
+  const schemas = pikkuState(null, 'misc', 'schemas')
+  return fnMeta ? { fnMeta, schemas } : null
+}
+
+export function computeEntryNodeIds(nodes: Record<string, any>): string[] {
+  const referenced = new Set<string>()
+  for (const node of Object.values(nodes)) {
+    if (node.next) {
+      for (const target of normalizeTargets(node.next)) {
+        referenced.add(target)
+      }
+    }
+    if (node.onError) {
+      for (const target of normalizeTargets(node.onError)) {
+        referenced.add(target)
+      }
+    }
+  }
+  return Object.keys(nodes).filter((id) => !referenced.has(id))
+}
+
+export function validateWorkflowWiring(
+  nodes: Record<string, any>,
+  toolNames: string[]
+): string[] {
+  const errors: string[] = []
+  const nodeIds = new Set(Object.keys(nodes))
+  const toolSet = new Set(toolNames)
+
+  for (const [nodeId, node] of Object.entries(nodes)) {
+    if (!node.rpcName) {
+      errors.push(`Node '${nodeId}' is missing 'rpcName'`)
+      continue
+    }
+
+    if (!toolSet.has(node.rpcName)) {
+      errors.push(
+        `Node '${nodeId}' references unknown tool '${node.rpcName}'. Available tools: ${toolNames.join(', ')}`
+      )
+      continue
+    }
+
+    const nextTargets = normalizeTargets(node.next)
+    for (const target of nextTargets) {
+      if (!nodeIds.has(target)) {
+        errors.push(
+          `Node '${nodeId}' routes to unknown node '${target}' in 'next'`
+        )
+      }
+    }
+
+    const errorTargets = normalizeTargets(node.onError)
+    for (const target of errorTargets) {
+      if (!nodeIds.has(target)) {
+        errors.push(
+          `Node '${nodeId}' routes to unknown node '${target}' in 'onError'`
+        )
+      }
+    }
+
+    if (!node.input) continue
+
+    const refs = new Set<string>()
+    collectRefs(node.input, refs)
+
+    for (const ref of refs) {
+      if (ref === 'trigger' || ref === '$item') {
+        const targetMeta = resolveToolMeta(node.rpcName)
+        if (targetMeta?.fnMeta?.inputSchemaName) {
+          const targetSchema = targetMeta.schemas.get(
+            targetMeta.fnMeta.inputSchemaName
+          )
+          if (targetSchema?.properties) {
+            for (const [field, fieldValue] of Object.entries(
+              node.input as Record<string, any>
+            )) {
+              if (
+                typeof fieldValue === 'object' &&
+                fieldValue !== null &&
+                fieldValue.$ref === ref &&
+                !fieldValue.path
+              ) {
+                const targetType = targetSchema.properties[field]?.type
+                if (targetType && targetType !== 'object') {
+                  errors.push(
+                    `Node '${nodeId}' input field '${field}' expects type '${targetType}', but references the whole ${ref} object without a path. Use { $ref: "${ref}", path: "${field}" } to extract the field.`
+                  )
+                }
+              }
+            }
+          }
+        }
+        continue
+      }
+
+      if (!nodeIds.has(ref)) {
+        errors.push(
+          `Node '${nodeId}' references unknown node '${ref}' in input`
+        )
+        continue
+      }
+
+      const sourceNode = nodes[ref]
+      if (!sourceNode?.rpcName) continue
+
+      const sourceMeta = resolveToolMeta(sourceNode.rpcName)
+      if (!sourceMeta?.fnMeta?.outputSchemaName) continue
+
+      const sourceSchema = sourceMeta.schemas.get(
+        sourceMeta.fnMeta.outputSchemaName
+      )
+      if (!sourceSchema?.properties) continue
+
+      for (const [field, fieldValue] of Object.entries(
+        node.input as Record<string, any>
+      )) {
+        if (
+          typeof fieldValue === 'object' &&
+          fieldValue !== null &&
+          fieldValue.$ref === ref &&
+          fieldValue.path
+        ) {
+          const pathRoot = fieldValue.path.split('.')[0]
+          if (
+            sourceSchema.properties &&
+            !(pathRoot in sourceSchema.properties)
+          ) {
+            errors.push(
+              `Node '${nodeId}' input field '${field}' references path '${fieldValue.path}' but node '${ref}' (${sourceNode.rpcName}) output has no property '${pathRoot}'`
+            )
+            continue
+          }
+
+          const targetMeta = resolveToolMeta(node.rpcName)
+          if (!targetMeta?.fnMeta?.inputSchemaName) continue
+          const targetSchema = targetMeta.schemas.get(
+            targetMeta.fnMeta.inputSchemaName
+          )
+          if (!targetSchema?.properties?.[field]) continue
+
+          const sourceType = sourceSchema.properties[pathRoot]?.type
+          const targetType = targetSchema.properties[field].type
+          if (sourceType && targetType && sourceType !== targetType) {
+            errors.push(
+              `Node '${nodeId}' input field '${field}' expects type '${targetType}', but node '${ref}' output field '${pathRoot}' is type '${sourceType}'`
+            )
+          }
+        }
+      }
+    }
+  }
+
+  return errors
+}
+
+export function generateMermaidDiagram(
+  workflowName: string,
+  nodes: Record<string, any>,
+  entryNodeIds: string[]
+): string {
+  const lines: string[] = ['graph TD']
+
+  for (const [nodeId, node] of Object.entries(nodes)) {
+    const label = node.rpcName || nodeId
+    const isEntry = entryNodeIds.includes(nodeId)
+    lines.push(
+      `  ${nodeId}${isEntry ? '([' : '['}${label}${isEntry ? '])' : ']'}`
+    )
+
+    const nextTargets = normalizeTargets(node.next)
+    for (const target of nextTargets) {
+      lines.push(`  ${nodeId} --> ${target}`)
+    }
+
+    const errorTargets = normalizeTargets(node.onError)
+    for (const target of errorTargets) {
+      lines.push(`  ${nodeId} -.->|error| ${target}`)
+    }
+  }
+
+  return lines.join('\n')
+}

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

@@ -0,0 +1,19 @@
+export {
+  continueGraph,
+  executeGraphStep,
+  onGraphNodeComplete,
+  runFromMeta,
+  runWorkflowGraph,
+} from './graph-runner.js'
+export { template } from './template.js'
+export type { TemplateString } from './template.js'
+export {
+  pikkuWorkflowGraph,
+  type PikkuWorkflowGraphConfig,
+  type PikkuWorkflowGraphResult,
+} from './wire-workflow-graph.js'
+export {
+  validateWorkflowWiring,
+  computeEntryNodeIds,
+  generateMermaidDiagram,
+} from './graph-validation.js'

package/src/wirings/workflow/graph/template.test.ts

@@ -0,0 +1,49 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { template } from './template.js'
+
+describe('template', () => {
+  test('should parse a simple template with one placeholder', () => {
+    const result = template('Hello $0!', [{ $ref: 'greeting' }])
+    assert.deepStrictEqual(result.$template.parts, ['Hello ', '!'])
+    assert.deepStrictEqual(result.$template.expressions, [{ $ref: 'greeting' }])
+  })
+
+  test('should parse template with multiple placeholders', () => {
+    const result = template('$0 and $1', [{ $ref: 'a' }, { $ref: 'b' }])
+    assert.deepStrictEqual(result.$template.parts, ['', ' and ', ''])
+    assert.strictEqual(result.$template.expressions.length, 2)
+    assert.strictEqual(result.$template.expressions[0].$ref, 'a')
+    assert.strictEqual(result.$template.expressions[1].$ref, 'b')
+  })
+
+  test('should preserve path in references', () => {
+    const result = template('Value: $0', [{ $ref: 'node1', path: 'data.name' }])
+    assert.deepStrictEqual(result.$template.expressions[0], {
+      $ref: 'node1',
+      path: 'data.name',
+    })
+  })
+
+  test('should handle template with no placeholders', () => {
+    const result = template('No placeholders here', [])
+    assert.deepStrictEqual(result.$template.parts, ['No placeholders here'])
+    assert.deepStrictEqual(result.$template.expressions, [])
+  })
+
+  test('should handle out-of-range ref index as unknown', () => {
+    const result = template('$5', [{ $ref: 'a' }])
+    assert.deepStrictEqual(result.$template.expressions[0], { $ref: 'unknown' })
+  })
+
+  test('should handle adjacent placeholders', () => {
+    const result = template('$0$1', [{ $ref: 'a' }, { $ref: 'b' }])
+    assert.deepStrictEqual(result.$template.parts, ['', '', ''])
+    assert.strictEqual(result.$template.expressions.length, 2)
+  })
+
+  test('should omit path when not provided', () => {
+    const result = template('$0', [{ $ref: 'node' }])
+    assert.strictEqual(result.$template.expressions[0].path, undefined)
+  })
+})

package/src/wirings/workflow/graph/template.ts

@@ -0,0 +1,42 @@
+export type TemplateString = {
+  $template: {
+    parts: string[]
+    expressions: Array<{ $ref: string; path?: string }>
+  }
+} & { __brand: 'TemplateString' }
+
+export function template(
+  templateStr: string,
+  refs: Array<{ $ref: string; path?: string }>
+): TemplateString {
+  const parts: string[] = []
+  const expressions: Array<{ $ref: string; path?: string }> = []
+
+  const regex = /\$(\d+)/g
+  let lastIndex = 0
+  let match
+
+  while ((match = regex.exec(templateStr)) !== null) {
+    parts.push(templateStr.slice(lastIndex, match.index))
+
+    const refIndex = parseInt(match[1]!, 10)
+    const refValue = refs[refIndex]
+    if (refValue) {
+      const expr: { $ref: string; path?: string } = { $ref: refValue.$ref }
+      if (refValue.path) {
+        expr.path = refValue.path
+      }
+      expressions.push(expr)
+    } else {
+      expressions.push({ $ref: 'unknown' })
+    }
+
+    lastIndex = regex.lastIndex
+  }
+
+  parts.push(templateStr.slice(lastIndex))
+
+  return {
+    $template: { parts, expressions },
+  } as TemplateString
+}

package/src/wirings/workflow/graph/wire-workflow-graph.ts

@@ -0,0 +1,29 @@
+export interface PikkuWorkflowGraphConfig<
+  FuncMap extends Record<string, string>,
+  T,
+> {
+  disabled?: true
+  name?: string
+  description?: string
+  tags?: string[]
+  nodes: FuncMap
+  config?: T
+}
+
+export interface PikkuWorkflowGraphResult {
+  __type: 'pikkuWorkflowGraph'
+  name?: string
+  description?: string
+  tags?: string[]
+}
+
+export function pikkuWorkflowGraph<
+  const FuncMap extends Record<string, string>,
+>(config: PikkuWorkflowGraphConfig<FuncMap, any>): PikkuWorkflowGraphResult {
+  return {
+    __type: 'pikkuWorkflowGraph',
+    name: config.name,
+    description: config.description,
+    tags: config.tags,
+  }
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Ref value - internal representation after input callback is evaluated
+ */
+export interface RefValue {
+  __isRef: true
+  nodeId: string
+  path?: string
+}
+
+/**
+ * Helper to create a ref value
+ */
+export const createRef = (nodeId: string, path?: string): RefValue => ({
+  __isRef: true,
+  nodeId,
+  path,
+})
+
+/**
+ * Check if a value is a ref
+ */
+export const isRef = (value: unknown): value is RefValue =>
+  typeof value === 'object' &&
+  value !== null &&
+  '__isRef' in value &&
+  (value as RefValue).__isRef === true
+
+/**
+ * Input reference for fetching step results
+ */
+export interface InputRef {
+  nodeId: string
+  path?: string
+}
+
+/**
+ * Ref function type - provides type-safe references to other nodes' outputs
+ * The actual typing is done at the pikkuWorkflowGraph level
+ */
+export type RefFn<NodeIds extends string = string> = (
+  nodeId: NodeIds,
+  path?: string
+) => RefValue
+
+/**
+ * Next node configuration - fully serializable
+ * - string: single next node
+ * - string[]: parallel execution (all run concurrently)
+ * - Record<string, string | string[]>: branching (function calls graph.branch('key'))
+ */
+export type NextConfig<NodeIds extends string = string> =
+  | NodeIds
+  | NodeIds[]
+  | Record<string, NodeIds | NodeIds[]>
+
+/**
+ * Graph node configuration - references functions by RPC name
+ */
+export interface GraphNodeConfig<NodeIds extends string = string> {
+  /** RPC function name */
+  func: string
+  /** Input mapping callback - receives ref function, returns input object */
+  input?: (ref: RefFn<NodeIds>) => Record<string, unknown>
+  /** Next nodes - string, array, or record for branching */
+  next?: NextConfig<NodeIds>
+  /** Error routing - node(s) to execute on error */
+  onError?: NodeIds | NodeIds[]
+}
+
+/**
+ * Graph wire context - available to functions running in a workflow graph
+ */
+export interface PikkuGraphWire {
+  /** Workflow run ID */
+  runId: string
+  /** Graph name */
+  graphName: string
+  /** Current node ID */
+  nodeId: string
+  /**
+   * Select which branch to take for Record-based next config.
+   * Must be called if the node has a Record `next` configuration.
+   * @param key - The branch key to take (must match a key in the next Record)
+   */
+  branch: (key: string) => void
+  /**
+   * Set a state variable value.
+   * @param name - Variable name
+   * @param value - Value to store
+   */
+  setState: (name: string, value: unknown) => Promise<void>
+  /**
+   * Get the entire state object.
+   * @returns The state object with all variables
+   */
+  getState: () => Promise<Record<string, unknown>>
+}
+
+/**
+ * Internal mutable state for graph wire (used by runner to capture branch)
+ */
+export interface GraphWireState {
+  branchKey?: string
+}