@pikku/core 0.12.4 → 0.12.6

package/src/wirings/workflow/workflow-helpers.test.ts

@@ -0,0 +1,129 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import {
+  workflow,
+  workflowStart,
+  workflowStatus,
+  graphStart,
+} from './workflow-helpers.js'
+
+describe('workflow helpers', () => {
+  describe('workflow', () => {
+    test('should return an object with func', () => {
+      const wf = workflow('myWorkflow')
+      assert.strictEqual(typeof wf.func, 'function')
+    })
+
+    test('func should call workflowService.runToCompletion', async () => {
+      const wf = workflow('myWorkflow', { pollIntervalMs: 500 })
+      let calledWith: any
+      const services = {
+        workflowService: {
+          runToCompletion: async (...args: any[]) => {
+            calledWith = args
+            return { result: 'done' }
+          },
+        },
+      }
+      const result = await wf.func(services, { input: 1 }, { rpc: {} })
+      assert.strictEqual(calledWith[0], 'myWorkflow')
+      assert.deepStrictEqual(calledWith[1], { input: 1 })
+      assert.deepStrictEqual(result, { result: 'done' })
+    })
+  })
+
+  describe('workflowStart', () => {
+    test('should return an object with func', () => {
+      const wfs = workflowStart('myWorkflow')
+      assert.strictEqual(typeof wfs.func, 'function')
+    })
+
+    test('func should call rpc.startWorkflow', async () => {
+      const wfs = workflowStart('myWorkflow')
+      let calledWith: any
+      const rpc = {
+        startWorkflow: async (...args: any[]) => {
+          calledWith = args
+          return { runId: 'run-1' }
+        },
+      }
+      const result = await wfs.func({}, { input: 1 }, { rpc })
+      assert.strictEqual(calledWith[0], 'myWorkflow')
+      assert.deepStrictEqual(calledWith[1], { input: 1 })
+      assert.deepStrictEqual(result, { runId: 'run-1' })
+    })
+  })
+
+  describe('workflowStatus', () => {
+    test('should return an object with func', () => {
+      const wfst = workflowStatus('myWorkflow')
+      assert.strictEqual(typeof wfst.func, 'function')
+    })
+
+    test('func should return run status', async () => {
+      const wfst = workflowStatus('myWorkflow')
+      const services = {
+        workflowService: {
+          getRun: async (runId: string) => ({
+            id: runId,
+            status: 'completed',
+            output: { data: 'ok' },
+          }),
+        },
+      }
+      const result = await wfst.func(services, { runId: 'run-1' })
+      assert.strictEqual(result.id, 'run-1')
+      assert.strictEqual(result.status, 'completed')
+      assert.deepStrictEqual(result.output, { data: 'ok' })
+    })
+
+    test('func should throw WorkflowRunNotFoundError for missing run', async () => {
+      const wfst = workflowStatus('myWorkflow')
+      const services = {
+        workflowService: { getRun: async () => null },
+      }
+      await assert.rejects(
+        () => wfst.func(services, { runId: 'non-existent' }),
+        (err: any) => err.message.includes('non-existent')
+      )
+    })
+
+    test('func should include error message when run has error', async () => {
+      const wfst = workflowStatus('myWorkflow')
+      const services = {
+        workflowService: {
+          getRun: async () => ({
+            id: 'run-2',
+            status: 'failed',
+            error: { message: 'step failed', name: 'Error' },
+          }),
+        },
+      }
+      const result = await wfst.func(services, { runId: 'run-2' })
+      assert.strictEqual(result.status, 'failed')
+      assert.deepStrictEqual(result.error, { message: 'step failed' })
+    })
+  })
+
+  describe('graphStart', () => {
+    test('should return an object with func', () => {
+      const gs = graphStart('myGraph', 'startNode')
+      assert.strictEqual(typeof gs.func, 'function')
+    })
+
+    test('func should call rpc.startWorkflow with startNode', async () => {
+      const gs = graphStart('myGraph', 'nodeA')
+      let calledWith: any
+      const rpc = {
+        startWorkflow: async (...args: any[]) => {
+          calledWith = args
+          return { runId: 'run-3' }
+        },
+      }
+      const result = await gs.func({}, { input: 1 }, { rpc })
+      assert.strictEqual(calledWith[0], 'myGraph')
+      assert.deepStrictEqual(calledWith[2], { startNode: 'nodeA' })
+      assert.deepStrictEqual(result, { runId: 'run-3' })
+    })
+  })
+})

package/src/wirings/workflow/workflow-helpers.ts

@@ -0,0 +1,79 @@
+import { WorkflowRunNotFoundError } from './pikku-workflow-service.js'
+
+export function workflow<
+  TWorkflowMap extends Record<string, { input: any; output: any }>,
+>(
+  workflowName: string & keyof TWorkflowMap,
+  options?: { pollIntervalMs?: number }
+): { func: (services: any, data: any, wire: any) => Promise<any> } {
+  return {
+    func: async (services: any, data: any, { rpc }: any) => {
+      return services.workflowService.runToCompletion(
+        workflowName,
+        data,
+        rpc,
+        options
+      )
+    },
+  }
+}
+
+export function workflowStart<
+  TWorkflowMap extends Record<string, { input: any; output: any }>,
+>(
+  workflowName: string & keyof TWorkflowMap
+): {
+  func: (services: any, data: any, wire: any) => Promise<{ runId: string }>
+} {
+  return {
+    func: async (_services: any, data: any, { rpc }: any) => {
+      return rpc.startWorkflow(workflowName, data)
+    },
+  }
+}
+
+export function workflowStatus<
+  TWorkflowMap extends Record<string, { input: any; output: any }>,
+>(
+  _workflowName: string & keyof TWorkflowMap
+): {
+  func: (
+    services: any,
+    data: { runId: string }
+  ) => Promise<{
+    id: string
+    status: 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled'
+    output?: any
+    error?: { message?: string }
+  }>
+} {
+  return {
+    func: async (services: any, data: { runId: string }) => {
+      const run = await services.workflowService.getRun(data.runId)
+      if (!run) {
+        throw new WorkflowRunNotFoundError(data.runId)
+      }
+      return {
+        id: run.id,
+        status: run.status,
+        output: run.output,
+        error: run.error ? { message: run.error.message } : undefined,
+      }
+    },
+  }
+}
+
+export function graphStart<
+  TGraphsMap extends Record<string, Record<string, any>>,
+>(
+  graphName: string & keyof TGraphsMap,
+  startNode: string
+): {
+  func: (services: any, data: any, wire: any) => Promise<{ runId: string }>
+} {
+  return {
+    func: async (_services: any, data: any, { rpc }: any) => {
+      return rpc.startWorkflow(graphName, data, { startNode })
+    },
+  }
+}

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

@@ -0,0 +1,276 @@
+import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
+
+// Re-export WorkflowService from services module
+export type { WorkflowService } from '../../services/workflow-service.js'
+
+// Re-export DSL types from dsl module
+export type {
+  WorkflowStepOptions,
+  WorkflowWireDoRPC,
+  WorkflowWireDoInline,
+  WorkflowWireSleep,
+  WorkflowWireSuspend,
+  InputSource,
+  OutputBinding,
+  RpcStepMeta,
+  SimpleCondition,
+  Condition,
+  BranchCase,
+  BranchStepMeta,
+  ParallelGroupStepMeta,
+  FanoutStepMeta,
+  ReturnStepMeta,
+  InlineStepMeta,
+  SleepStepMeta,
+  CancelStepMeta,
+  SetStepMeta,
+  SwitchCaseMeta,
+  SwitchStepMeta,
+  FilterStepMeta,
+  ArrayPredicateStepMeta,
+  WorkflowStepMeta,
+  WorkflowStepWire,
+  PikkuWorkflowWire,
+} from './dsl/workflow-dsl.types.js'
+
+import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js'
+
+export interface WorkflowRunWire {
+  type: string
+  id?: string
+  parentRunId?: string
+}
+
+export interface WorkflowServiceConfig {
+  retries: number
+  retryDelay: number
+  orchestratorQueueName: string
+  stepWorkerQueueName: string
+  sleeperRPCName: string
+}
+
+/**
+ * Workflow run status
+ */
+export type WorkflowStatus =
+  | 'running'
+  | 'suspended'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+/**
+ * Workflow version status (for AI-generated workflows)
+ */
+export type WorkflowVersionStatus = 'draft' | 'active' | 'declined'
+
+/**
+ * Workflow step status
+ */
+export type StepStatus =
+  | 'pending'
+  | 'running'
+  | 'scheduled'
+  | 'succeeded'
+  | 'failed'
+  | 'suspended'
+
+/**
+ * Workflow run representation
+ */
+export interface WorkflowRun {
+  /** Unique run ID */
+  id: string
+  /** Workflow name */
+  workflow: string
+  /** Current status */
+  status: WorkflowStatus
+  /** Input data */
+  input: any
+  /** Output data (if completed) */
+  output?: any
+  /** Error (if failed) */
+  error?: SerializedError
+  /** If true, workflow executes inline without queues */
+  inline?: boolean
+  /** Graph hash of the workflow definition at run creation time */
+  graphHash?: string
+  /** Wire origin info (how this run was started) */
+  wire: WorkflowRunWire
+  /** Creation timestamp */
+  createdAt: Date
+  /** Last update timestamp */
+  updatedAt: Date
+}
+
+/**
+ * Step state representation
+ */
+export interface StepState {
+  /** Unique step ID */
+  stepId: string
+  /** Step status */
+  status: StepStatus
+  /** Step result (if done) */
+  result?: any
+  /** Step error (if error) */
+  error?: SerializedError
+  /** Number of attempts made (starts at 1) */
+  attemptCount: number
+  /** Maximum retry attempts allowed */
+  retries?: number
+  /** Delay between retries */
+  retryDelay?: string | number
+  /** Creation timestamp */
+  createdAt: Date
+  /** Last update timestamp */
+  updatedAt: Date
+  /** Child workflow run ID (if this step spawned a sub-workflow) */
+  childRunId?: string
+  /** Timestamp when step started running */
+  runningAt?: Date
+  /** Timestamp when step was scheduled */
+  scheduledAt?: Date
+  /** Timestamp when step succeeded */
+  succeededAt?: Date
+  /** Timestamp when step failed */
+  failedAt?: Date
+}
+
+export interface WorkflowRunService {
+  listRuns(options?: {
+    workflowName?: string
+    status?: string
+    limit?: number
+    offset?: number
+  }): Promise<WorkflowRun[]>
+  getRun(id: string): Promise<WorkflowRun | null>
+  getRunSteps(
+    runId: string
+  ): Promise<
+    Array<StepState & { stepName: string; rpcName?: string; data?: any }>
+  >
+  getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
+  getDistinctWorkflowNames(): Promise<string[]>
+  getWorkflowVersion(
+    name: string,
+    graphHash: string
+  ): Promise<{ graph: any; source: string } | null>
+  getAIGeneratedWorkflows(
+    agentName?: string
+  ): Promise<Array<{ workflowName: string; graphHash: string; graph: any }>>
+  deleteRun(id: string): Promise<boolean>
+}
+
+/**
+ * Core workflow definition
+ */
+export type CoreWorkflow<
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
+    any,
+    any,
+    any
+  > = CorePikkuFunctionConfig<any, any, any>,
+> = {
+  /** Unique workflow name */
+  name: string
+  /** The workflow function */
+  func: PikkuFunctionConfig
+  /** Middleware chain for this workflow */
+  middleware?: PikkuFunctionConfig['middleware']
+  /** Permission requirements */
+  permissions?: PikkuFunctionConfig['permissions']
+  /** Tags for organization and filtering */
+  tags?: string[]
+}
+
+/**
+ * Workflow client interface
+ */
+export interface PikkuWorkflow {
+  /** Start a new workflow run */
+  start: <I>(input: I) => Promise<{ runId: string }>
+  /** Get a workflow run by ID */
+  getRun: (runId: string) => Promise<WorkflowRun>
+  /** Cancel a running workflow */
+  cancelRun: (runId: string) => Promise<void>
+}
+
+/**
+ * Context variable definition (serialized from Zod schema or type inference)
+ */
+export interface ContextVariable {
+  /** Variable type */
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array'
+  /** Default value */
+  default?: unknown
+  /** Description for UI/docs */
+  description?: string
+}
+
+/**
+ * Workflow context - state variables with defaults and types
+ */
+export type WorkflowContext = Record<string, ContextVariable>
+
+/**
+ * Workflows metadata for inspector/CLI (DSL step-based format)
+ */
+export type WorkflowsMeta = Record<
+  string,
+  CommonWireMeta & {
+    name: string
+    steps: WorkflowStepMeta[]
+    context?: WorkflowContext
+    dsl?: boolean
+  }
+>
+
+/**
+ * Unified workflow runtime meta (used by runtime to execute workflows)
+ * This is the format stored in pikkuState('workflows', 'meta')
+ * Both DSL and graph-based workflows are converted to this format
+ */
+export interface WorkflowRuntimeMeta {
+  /** Workflow name (used as key in registrations) */
+  name: string
+  /** Pikku function name (for execution) */
+  pikkuFuncId: string
+  /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph' */
+  source: 'dsl' | 'complex' | 'graph' | 'ai-agent'
+  /** Optional description */
+  description?: string
+  /** Tags for organization */
+  tags?: string[]
+  /** Serialized nodes */
+  nodes?: Record<string, any>
+  /** Entry node IDs for graph workflows (computed at build time) */
+  entryNodeIds?: string[]
+  /** Hash of graph topology (nodes, edges, input mappings) */
+  graphHash?: string
+}
+
+/**
+ * Unified workflow runtime metadata map
+ */
+export type WorkflowsRuntimeMeta = Record<string, WorkflowRuntimeMeta>
+
+/**
+ * Worker input types for generated queue workers
+ */
+export type WorkflowStepInput = {
+  runId: string
+  stepName: string
+  rpcName: string
+  data: any
+}
+
+export type WorkflowOrchestratorInput = {
+  runId: string
+}
+
+export type WorkflowSleeperInput = {
+  runId: string
+  stepId: string
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "composite": true,
+    "module": "Node18",
+    "outDir": "dist",
+    "target": "esnext",
+    "moduleResolution": "node16",
+    "tsBuildInfoFile": null
+  },
+  "exclude": ["**/*.test.ts", "node_modules", "dist"],
+  "references": []
+}