@pikku/core 0.11.1 → 0.12.0

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

@@ -1,12 +1,47 @@
-import {
-  SerializedError,
-  CoreSingletonServices,
-  CreateWireServices,
-  CoreConfig,
-  CommonWireMeta,
-} from '../../types/core.types.js'
+import { SerializedError, CommonWireMeta } from '../../types/core.types.js'
 import { 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
@@ -18,7 +53,12 @@ export interface WorkflowServiceConfig {
 /**
  * Workflow run status
  */
-export type WorkflowStatus = 'running' | 'completed' | 'failed' | 'cancelled'
+export type WorkflowStatus =
+  | 'running'
+  | 'suspended'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
 
 /**
  * Workflow step status
@@ -29,6 +69,7 @@ export type StepStatus =
   | 'scheduled'
   | 'succeeded'
   | 'failed'
+  | 'suspended'
 
 /**
  * Workflow run representation
@@ -46,6 +87,12 @@ export interface WorkflowRun {
   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 */
@@ -84,6 +131,28 @@ export interface StepState {
   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>
+  deleteRun(id: string): Promise<boolean>
+}
+
 /**
  * Core workflow definition
  */
@@ -106,215 +175,6 @@ export type CoreWorkflow<
   tags?: string[]
 }
 
-/**
- * Workflow step options
- */
-export interface WorkflowStepOptions {
-  /** Display name for logs/UI (optional, doesn't affect execution) */
-  description?: string
-  /** Number of retry attempts for failed steps (only applies to local execution) */
-  retries?: number
-  /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
-  retryDelay?: string | number
-  // Future: timeout, failFast, priority
-}
-
-/**
- * Type signature for workflow.do() RPC form - used by inspector
- */
-export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(
-  stepName: string,
-  rpcName: string,
-  data: TInput,
-  options?: WorkflowStepOptions
-) => Promise<TOutput>
-
-/**
- * Type signature for workflow.do() inline form - used by inspector
- */
-export type WorkflowWireDoInline = <T>(
-  stepName: string,
-  fn: () => Promise<T> | T,
-  options?: WorkflowStepOptions
-) => Promise<T>
-
-/**
- * Type signature for workflow.sleep() - used by inspector
- */
-export type WorkflowWireSleep = (
-  stepName: string,
-  duration: string
-) => Promise<void>
-
-/**
- * Input source for step arguments in simple workflows
- */
-export type InputSource =
-  | { from: 'input'; path: string }
-  | { from: 'outputVar'; name: string; path?: string }
-  | { from: 'item'; path: string }
-  | { from: 'literal'; value: unknown }
-
-/**
- * Output binding for return statements in simple workflows
- */
-export interface OutputBinding {
-  from: 'outputVar' | 'input'
-  name?: string
-  path?: string
-}
-
-/**
- * RPC step metadata (base form)
- */
-export interface RpcStepMeta {
-  /** RPC form - generates queue worker */
-  type: 'rpc'
-  /** Cache key (stepName from workflow.do) */
-  stepName: string
-  /** RPC to invoke */
-  rpcName: string
-  /** Output variable name (if assigned) */
-  outputVar?: string
-  /** Input source mappings */
-  inputs?: Record<string, InputSource>
-  /** Step options */
-  options?: WorkflowStepOptions
-}
-
-/**
- * Branch step metadata (if/else control flow)
- */
-export interface BranchStepMeta {
-  type: 'branch'
-  /** Condition expression (as source string) */
-  condition: string
-  /** Branch paths */
-  branches: {
-    then: WorkflowStepMeta[]
-    else?: WorkflowStepMeta[]
-  }
-}
-
-/**
- * Parallel group step metadata (Promise.all with multiple steps)
- */
-export interface ParallelGroupStepMeta {
-  type: 'parallel'
-  /** Child steps to execute in parallel */
-  children: RpcStepMeta[]
-}
-
-/**
- * Fanout step metadata (parallel or sequential iteration)
- */
-export interface FanoutStepMeta {
-  type: 'fanout'
-  /** Step name for this fanout */
-  stepName: string
-  /** Source array variable name */
-  sourceVar: string
-  /** Iterator variable name */
-  itemVar: string
-  /** Execution mode */
-  mode: 'parallel' | 'sequential'
-  /** Child step to execute per iteration */
-  child: RpcStepMeta
-  /** Time between iterations (sequential mode only) */
-  timeBetween?: string
-}
-
-/**
- * Return step metadata (workflow output)
- */
-export interface ReturnStepMeta {
-  type: 'return'
-  /** Output bindings */
-  outputs: Record<string, OutputBinding>
-}
-
-/**
- * Inline step metadata (legacy support)
- */
-export interface InlineStepMeta {
-  /** Inline form - local execution */
-  type: 'inline'
-  /** Cache key (stepName from workflow.do) */
-  stepName: string
-  /** Display name */
-  description?: string
-  /** Step options */
-  options?: WorkflowStepOptions
-}
-
-/**
- * Sleep step metadata
- */
-export interface SleepStepMeta {
-  /** Sleep step */
-  type: 'sleep'
-  /** Cache key (stepName from workflow.sleep) */
-  stepName: string
-  /** Sleep duration */
-  duration: string | number
-}
-
-/**
- * Cancel step metadata
- */
-export interface CancelStepMeta {
-  /** Cancel step */
-  type: 'cancel'
-}
-
-/**
- * Workflow step metadata (extracted by inspector)
- */
-export type WorkflowStepMeta =
-  | RpcStepMeta
-  | BranchStepMeta
-  | ParallelGroupStepMeta
-  | FanoutStepMeta
-  | ReturnStepMeta
-  | InlineStepMeta
-  | SleepStepMeta
-  | CancelStepMeta
-
-/**
- * Workflow step wire context for RPC functions
- * Provides step-level metadata including retry attempt tracking
- */
-export interface WorkflowStepWire {
-  /** The workflow run ID */
-  runId: string
-  /** The unique step ID */
-  stepId: string
-  /** Current attempt number (1-indexed, increments on retry) */
-  attemptCount: number
-}
-
-/**
- * Workflow wire object for middleware
- * Provides workflow-specific capabilities to function execution
- */
-export interface PikkuWorkflowWire {
-  /** The workflow name */
-  workflowName: string
-  /** The current run ID */
-  runId: string
-  /** Get the current workflow run */
-  getRun: () => Promise<WorkflowRun>
-
-  /** Execute a workflow step (overloaded - RPC or inline form) */
-  do: WorkflowWireDoRPC & WorkflowWireDoInline
-
-  /** Sleep for a duration */
-  sleep: WorkflowWireSleep
-
-  /** Cancel the current workflow run */
-  cancel: (reason?: string) => Promise<void>
-}
-
 /**
  * Workflow client interface
  */
@@ -328,80 +188,64 @@ export interface PikkuWorkflow {
 }
 
 /**
- * Workflows metadata for inspector/CLI
+ * 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 & {
-    workflowName: string
+    name: string
     steps: WorkflowStepMeta[]
-    /** Whether this workflow conforms to simple workflow DSL */
-    simple?: boolean
+    context?: WorkflowContext
+    dsl?: boolean
   }
 >
 
 /**
- * Interface for workflow orchestration
- * Handles workflow execution, replay, orchestration logic, and run-level state
+ * 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 WorkflowService {
-  // Run-level state operations
-  createRun(workflowName: string, input: any): Promise<string>
-  getRun(id: string): Promise<WorkflowRun | null>
-  getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
-  updateRunStatus(
-    id: string,
-    status: WorkflowStatus,
-    output?: any,
-    error?: SerializedError
-  ): Promise<void>
-  withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>
-  close(): Promise<void>
-
-  // Orchestration operations
-  resumeWorkflow(runId: string): Promise<void>
-  setServices(
-    singletonServices: CoreSingletonServices,
-    createWireServices: CreateWireServices,
-    config: CoreConfig
-  ): void
-  startWorkflow<I>(
-    name: string,
-    input: I,
-    rpcService: any
-  ): Promise<{ runId: string }>
-  runWorkflowJob(runId: string, rpcService: any): Promise<void>
-  orchestrateWorkflow(runId: string, rpcService: any): Promise<void>
-  executeWorkflowSleep(runId: string, stepId: string): Promise<void>
-
-  // Step-level state operations
-  insertStepState(
-    runId: string,
-    stepName: string,
-    rpcName: string,
-    data: any,
-    stepOptions?: { retries?: number; retryDelay?: string | number }
-  ): Promise<StepState>
-  getStepState(runId: string, stepName: string): Promise<StepState>
-  setStepRunning(stepId: string): Promise<void>
-  setStepScheduled(stepId: string): Promise<void>
-  setStepResult(stepId: string, result: any): Promise<void>
-  setStepError(stepId: string, error: Error): Promise<void>
-  createRetryAttempt(
-    stepId: string,
-    status: 'pending' | 'running'
-  ): Promise<StepState>
-
-  // Step execution
-  executeWorkflowStep(
-    runId: string,
-    stepName: string,
-    rpcName: string | null,
-    data: any,
-    rpcService: any
-  ): Promise<void>
+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'
+  /** 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
  */