@pikku/core 0.11.1 → 0.12.0

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

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

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
+}

package/src/wirings/workflow/index.ts

@@ -1,13 +1,68 @@
 /**
  * Workflow module exports
  */
+export {
+  PikkuWorkflowService,
+  WorkflowCancelledException,
+  WorkflowSuspendedException,
+  WorkflowNotFoundError,
+  WorkflowRunNotFoundError,
+} from './pikku-workflow-service.js'
 
-// Types
+// Internal registration functions (used by generated code)
+export { addWorkflow } from './dsl/workflow-runner.js'
+
+// Graph helpers (template, pikkuWorkflowGraph)
+export { template, type TemplateString } from './graph/template.js'
+export {
+  pikkuWorkflowGraph,
+  type PikkuWorkflowGraphConfig,
+  type PikkuWorkflowGraphResult,
+} from './graph/wire-workflow-graph.js'
+
+// Workflow helpers (runtime factories for HTTP handlers)
+export {
+  workflow,
+  workflowStart,
+  workflowStatus,
+  graphStart,
+} from './workflow-helpers.js'
+
+// Re-export all types from workflow.types
 export type {
+  WorkflowService,
+  WorkflowServiceConfig,
+  WorkflowRunWire,
+  WorkflowStatus,
+  StepStatus,
+  WorkflowRun,
+  StepState,
+  WorkflowRunService,
   CoreWorkflow,
+  PikkuWorkflow,
+  ContextVariable,
+  WorkflowContext,
+  WorkflowsMeta,
+  WorkflowRuntimeMeta,
+  WorkflowsRuntimeMeta,
+  WorkflowStepInput,
+  WorkflowOrchestratorInput,
+  WorkflowSleeperInput,
+} from './workflow.types.js'
+
+// Re-export DSL types
+export type {
   WorkflowStepOptions,
-  WorkflowStepMeta,
+  WorkflowWireDoRPC,
+  WorkflowWireDoInline,
+  WorkflowWireSleep,
+  WorkflowWireSuspend,
+  InputSource,
+  OutputBinding,
   RpcStepMeta,
+  SimpleCondition,
+  Condition,
+  BranchCase,
   BranchStepMeta,
   ParallelGroupStepMeta,
   FanoutStepMeta,
@@ -15,29 +70,12 @@ export type {
   InlineStepMeta,
   SleepStepMeta,
   CancelStepMeta,
-  InputSource,
-  OutputBinding,
+  SetStepMeta,
+  SwitchCaseMeta,
+  SwitchStepMeta,
+  FilterStepMeta,
+  ArrayPredicateStepMeta,
+  WorkflowStepMeta,
+  WorkflowStepWire,
   PikkuWorkflowWire,
-  PikkuWorkflow,
-  WorkflowsMeta,
-  WorkflowRun,
-  StepState,
-  WorkflowStatus,
-  StepStatus,
 } from './workflow.types.js'
-
-export { PikkuWorkflowService } from './pikku-workflow-service.js'
-
-// Internal registration function (used by generated code)
-export { addWorkflow } from './workflow-runner.js'
-
-/**
- * @deprecated This function is no longer used and will be removed in a future release.
- * It exists only for backwards compatibility with generated code.
- * TODO: Remove this export in a future release after updating code generation
- */
-export const wireWorkflow = <T extends { name: string; func: any }>(
-  workflow: T
-): void => {
-  // Empty function - no longer used, kept for backwards compatibility
-}

package/src/wirings/workflow/pikku-workflow-service.test.ts

@@ -0,0 +1,212 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState } from '../../pikku-state.js'
+import { addWorkflow } from './dsl/workflow-runner.js'
+import {
+  WorkflowSuspendedException,
+  type PikkuWorkflowWire,
+} from './pikku-workflow-service.js'
+
+describe('pikku-workflow-service version mismatch fallback', () => {
+  test('should fall back to stored graph for dsl workflow version mismatch', async () => {
+    const ws = new InMemoryWorkflowService()
+    const workflowName = 'testDslVersionMismatch'
+    const oldHash = 'old-hash'
+    const newHash = 'new-hash'
+
+    ws.setServices(
+      {
+        queueService: {
+          add: async () => {},
+        },
+      } as any,
+      (() => ({})) as any,
+      {} as any
+    )
+
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    metaState[workflowName] = {
+      name: workflowName,
+      pikkuFuncId: workflowName,
+      source: 'dsl',
+      graphHash: newHash,
+    }
+
+    await ws.upsertWorkflowVersion(
+      workflowName,
+      oldHash,
+      {
+        name: workflowName,
+        pikkuFuncId: workflowName,
+        source: 'dsl',
+        graphHash: oldHash,
+        nodes: {
+          nodeA: { nodeId: 'nodeA', rpcName: 'doA' },
+        },
+        entryNodeIds: ['nodeA'],
+      },
+      'dsl'
+    )
+    const runId = await ws.createRun(workflowName, {}, false, oldHash, {
+      type: 'test',
+    })
+
+    await ws.runWorkflowJob(runId, {})
+
+    const step = await ws.getStepState(runId, 'nodeA')
+    const run = await ws.getRun(runId)
+    assert.notEqual(step.stepId, '')
+    assert.equal(step.status, 'pending')
+    assert.equal(run?.status, 'running')
+
+    delete metaState[workflowName]
+  })
+
+  test('should continue from stored graph version when hashes mismatch', async () => {
+    const ws = new InMemoryWorkflowService()
+    const workflowName = 'testGraphVersionMismatch'
+    const oldHash = 'old-graph-hash'
+    const newHash = 'new-graph-hash'
+
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    metaState[workflowName] = {
+      name: workflowName,
+      pikkuFuncId: workflowName,
+      source: 'graph',
+      graphHash: newHash,
+      nodes: {
+        changedNode: { nodeId: 'changedNode', rpcName: 'changedRpc' },
+      },
+      entryNodeIds: ['changedNode'],
+    }
+
+    await ws.upsertWorkflowVersion(
+      workflowName,
+      oldHash,
+      {
+        name: workflowName,
+        pikkuFuncId: workflowName,
+        source: 'graph',
+        graphHash: oldHash,
+        nodes: {},
+        entryNodeIds: [],
+      },
+      'graph'
+    )
+
+    const runId = await ws.createRun(workflowName, {}, false, oldHash, {
+      type: 'test',
+    })
+    await ws.runWorkflowJob(runId, {})
+
+    const run = await ws.getRun(runId)
+    assert.equal(run?.status, 'completed')
+
+    delete metaState[workflowName]
+  })
+})
+
+describe('pikku-workflow-service executeWorkflowStep', () => {
+  test('should set pending step to running before succeeding', async () => {
+    const ws = new InMemoryWorkflowService()
+    ws.setServices(
+      {
+        queueService: {
+          add: async () => {},
+        },
+      } as any,
+      (() => ({})) as any,
+      {} as any
+    )
+
+    const runId = await ws.createRun(
+      'pending-step-running',
+      {},
+      false,
+      'hash',
+      { type: 'test' }
+    )
+    await ws.insertStepState(runId, 'stepA', 'doStepA', { a: 1 })
+
+    await ws.executeWorkflowStep(
+      runId,
+      'stepA',
+      'doStepA',
+      { a: 1 },
+      {
+        rpcWithWire: async () => ({ ok: true }),
+      }
+    )
+
+    const step = await ws.getStepState(runId, 'stepA')
+    assert.equal(step.status, 'succeeded')
+    assert.ok(step.runningAt instanceof Date)
+  })
+})
+
+describe('pikku-workflow-service suspend', () => {
+  test('should set run status to suspended when workflow.suspend is called', async () => {
+    const ws = new InMemoryWorkflowService()
+    ws.setServices(
+      {
+        queueService: {
+          add: async () => {},
+        },
+      } as any,
+      (() => ({})) as any,
+      {} as any
+    )
+
+    const workflowName = 'testSuspendWorkflow'
+    const graphHash = 'suspend-hash'
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    metaState[workflowName] = {
+      name: workflowName,
+      pikkuFuncId: workflowName,
+      source: 'dsl',
+      graphHash,
+    }
+    const functionMetaState = pikkuState(null, 'function', 'meta')
+    functionMetaState[workflowName] = {
+      name: workflowName,
+      sessionless: true,
+      permissions: [],
+    } as any
+
+    addWorkflow(workflowName, {
+      func: async (
+        _services: any,
+        _data: any,
+        { workflow }: { workflow: PikkuWorkflowWire }
+      ) => {
+        await workflow.suspend('Needs approval')
+        return { ok: true }
+      },
+    })
+
+    const runId = await ws.createRun(workflowName, {}, false, graphHash, {
+      type: 'test',
+    })
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+
+    const run = await ws.getRun(runId)
+    assert.equal(run?.status, 'suspended')
+    assert.equal(run?.error?.code, 'WORKFLOW_SUSPENDED')
+    assert.equal(run?.error?.message, 'Needs approval')
+
+    await ws.resumeWorkflow(runId)
+    await ws.runWorkflowJob(runId, {})
+    const resumedRun = await ws.getRun(runId)
+    assert.equal(resumedRun?.status, 'completed')
+    assert.deepEqual(resumedRun?.output, { ok: true })
+
+    delete metaState[workflowName]
+    delete functionMetaState[workflowName]
+    pikkuState(null, 'workflows', 'registrations').delete(workflowName)
+  })
+})