@pikku/core 0.12.3 → 0.12.4

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

@@ -1,170 +0,0 @@
-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

@@ -1,237 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

@@ -1,104 +0,0 @@
-/**
- * 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
-}