@pikku/core 0.11.0 → 0.11.2

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

@@ -0,0 +1,94 @@
+import { pikkuState } from '../../pikku-state.js'
+import type { WorkflowWires } from './workflow.types.js'
+import type { GraphNodeConfig } from './graph/workflow-graph.types.js'
+
+/**
+ * Workflow definition with DSL function
+ */
+export interface WorkflowDefinitionFunc {
+  wires: WorkflowWires
+  func: { func: (...args: any[]) => any } | ((...args: any[]) => any)
+}
+
+/**
+ * Workflow definition with graph
+ */
+export interface WorkflowDefinitionGraph<
+  T extends Record<string, GraphNodeConfig<string>> = Record<
+    string,
+    GraphNodeConfig<string>
+  >,
+> {
+  wires: WorkflowWires
+  graph: T
+}
+
+/**
+ * Union type for workflow definitions
+ */
+export type WorkflowDefinition<
+  T extends Record<string, GraphNodeConfig<string>> = Record<
+    string,
+    GraphNodeConfig<string>
+  >,
+> = WorkflowDefinitionFunc | WorkflowDefinitionGraph<T>
+
+/**
+ * Type guard for DSL workflow definition
+ */
+function isWorkflowDefinitionFunc(
+  def: WorkflowDefinition
+): def is WorkflowDefinitionFunc {
+  return 'func' in def
+}
+
+/**
+ * Type guard for graph workflow definition
+ */
+function isWorkflowDefinitionGraph(
+  def: WorkflowDefinition
+): def is WorkflowDefinitionGraph {
+  return 'graph' in def
+}
+
+/**
+ * Wire a workflow with triggers.
+ * Accepts either a DSL function (func) or a graph definition (graph).
+ *
+ * @example
+ * ```typescript
+ * // DSL workflow
+ * wireWorkflow({
+ *   wires: { http: { route: '/start', method: 'post' } },
+ *   func: myWorkflowFunc,
+ * })
+ *
+ * // Graph workflow
+ * wireWorkflow({
+ *   wires: { http: { route: '/graph-start', method: 'post' } },
+ *   graph: myGraphWorkflow,
+ * })
+ * ```
+ */
+export function wireWorkflow<T extends Record<string, GraphNodeConfig<string>>>(
+  definition: WorkflowDefinitionFunc | WorkflowDefinitionGraph<T>
+): void {
+  if (isWorkflowDefinitionFunc(definition)) {
+    // DSL workflow - store wiring for later registration by inspector
+    const wirings = pikkuState(null, 'workflows', 'wirings')
+    // The wiring will be matched to the function by the inspector
+    // Store the func reference and wires
+    wirings.set(definition.func, {
+      wires: definition.wires,
+      func: definition.func,
+    })
+  } else if (isWorkflowDefinitionGraph(definition)) {
+    // Graph workflow - store for registration
+    const graphWirings = pikkuState(null, 'workflows', 'graphWirings')
+    // Store the graph reference and wires
+    graphWirings.set(definition.graph, {
+      wires: definition.wires,
+      graph: definition.graph,
+    })
+  }
+}

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

@@ -0,0 +1,120 @@
+import { pikkuState } from '../../pikku-state.js'
+import { NotFoundError } from '../../errors/errors.js'
+import {
+  PikkuWire,
+  CreateWireServices,
+  CoreSingletonServices,
+  CoreServices,
+  CoreUserSession,
+} from '../../types/core.types.js'
+import { HTTPWiringMeta } from '../http/http.types.js'
+import { ContextAwareRPCService } from '../rpc/rpc-runner.js'
+
+/**
+ * Result of finding a workflow by HTTP wire
+ */
+export interface WorkflowHttpMatch {
+  workflowName: string
+  startNode?: string
+}
+
+/**
+ * Find workflow name by matching route and method against workflow wires
+ */
+export const findWorkflowByHttpWire = (
+  route: string,
+  method: string
+): WorkflowHttpMatch | undefined => {
+  const wirings = pikkuState(null, 'workflows', 'wirings')
+  const graphWirings = pikkuState(null, 'workflows', 'graphWirings')
+
+  // Check DSL workflow wirings
+  for (const [, wiring] of wirings) {
+    const httpWires = wiring.wires?.http
+    if (httpWires) {
+      const matchedWire = httpWires.find(
+        (w) => w.route === route && w.method === method
+      )
+      if (matchedWire) {
+        const meta = pikkuState(null, 'workflows', 'meta')
+        for (const [name, workflowMeta] of Object.entries(meta)) {
+          if (workflowMeta.source !== 'graph') {
+            const registrations = pikkuState(null, 'workflows', 'registrations')
+            if (registrations.has(name)) {
+              return { workflowName: name, startNode: matchedWire.startNode }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Check graph workflow wirings
+  for (const [, wiring] of graphWirings) {
+    const httpWires = wiring.wires?.http
+    if (httpWires) {
+      const matchedWire = httpWires.find(
+        (w) => w.route === route && w.method === method
+      )
+      if (matchedWire) {
+        const meta = pikkuState(null, 'workflows', 'meta')
+        for (const [name, workflowMeta] of Object.entries(meta)) {
+          if (workflowMeta.source === 'graph') {
+            return { workflowName: name, startNode: matchedWire.startNode }
+          }
+        }
+      }
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Start a workflow triggered by an HTTP wire
+ * The workflow is responsible for handling the HTTP response
+ */
+export const startWorkflowByHttpWire = async (
+  singletonServices: CoreSingletonServices,
+  createWireServices:
+    | CreateWireServices<
+        CoreSingletonServices,
+        CoreServices<CoreSingletonServices>,
+        CoreUserSession
+      >
+    | undefined,
+  matchedRoute: {
+    matchedPath: any
+    params: any
+    route: any
+    meta: HTTPWiringMeta
+  },
+  wire: PikkuWire
+): Promise<void> => {
+  const { meta } = matchedRoute
+
+  const match = findWorkflowByHttpWire(meta.route, meta.method)
+  if (!match) {
+    throw new NotFoundError(
+      `No workflow found for route ${meta.method.toUpperCase()} ${meta.route}`
+    )
+  }
+
+  const workflowService = singletonServices.workflowService
+  if (!workflowService) {
+    throw new Error('WorkflowService not available')
+  }
+
+  const data = await wire.http!.request!.data()
+
+  const wireServices = createWireServices?.(singletonServices, wire)
+  const rpcService = new ContextAwareRPCService(
+    { ...singletonServices, ...wireServices },
+    wire,
+    {}
+  )
+  await workflowService.startWorkflow(match.workflowName, data, rpcService, {
+    inline: true,
+    startNode: match.startNode,
+  })
+}

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

@@ -1,13 +1,40 @@
-import {
-  PikkuDocs,
-  MiddlewareMetadata,
-  SerializedError,
-  CoreSingletonServices,
-  CreateSessionServices,
-  CoreConfig,
-} 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,
+  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 WorkflowServiceConfig {
   retries: number
   retryDelay: number
@@ -16,6 +43,90 @@ export interface WorkflowServiceConfig {
   sleeperRPCName: string
 }
 
+/**
+ * HTTP wire configuration for workflows
+ */
+export interface WorkflowHTTPWire {
+  route: string
+  method: 'get' | 'post' | 'put' | 'patch' | 'delete'
+  startNode: string
+}
+
+/**
+ * Channel wire configuration for workflows
+ */
+export interface WorkflowChannelWire {
+  name: string
+  onConnect?: string
+  onDisconnect?: string
+  onMessage?: string
+}
+
+/**
+ * Queue wire configuration for workflows
+ */
+export interface WorkflowQueueWire {
+  name: string
+  startNode: string
+}
+
+/**
+ * CLI wire configuration for workflows
+ */
+export interface WorkflowCliWire {
+  command: string
+  startNode: string
+}
+
+/**
+ * MCP wire configurations for workflows
+ */
+export interface WorkflowMcpWires {
+  tool?: Array<{ name: string; startNode: string }>
+  prompt?: Array<{ name: string; startNode: string }>
+  resource?: Array<{ uri: string; startNode: string }>
+}
+
+/**
+ * Schedule wire configuration for workflows
+ */
+export interface WorkflowScheduleWire {
+  cron?: string
+  interval?: string
+  startNode: string
+}
+
+/**
+ * Trigger wire configuration for workflows
+ */
+export interface WorkflowTriggerWire {
+  name: string
+  startNode: string
+}
+
+/**
+ * Wire configuration for workflows
+ * Defines how a workflow can be triggered
+ */
+export interface WorkflowWires {
+  /** API entry point - node ID for startWorkflow() calls */
+  api?: string
+  /** HTTP triggers */
+  http?: WorkflowHTTPWire[]
+  /** Channel triggers */
+  channel?: WorkflowChannelWire[]
+  /** Queue triggers */
+  queue?: WorkflowQueueWire[]
+  /** CLI triggers */
+  cli?: WorkflowCliWire[]
+  /** MCP triggers (tool, prompt, resource) */
+  mcp?: WorkflowMcpWires
+  /** Schedule triggers */
+  schedule?: WorkflowScheduleWire[]
+  /** Named trigger wires */
+  trigger?: WorkflowTriggerWire[]
+}
+
 /**
  * Workflow run status
  */
@@ -47,6 +158,8 @@ export interface WorkflowRun {
   output?: any
   /** Error (if failed) */
   error?: SerializedError
+  /** If true, workflow executes inline without queues */
+  inline?: boolean
   /** Creation timestamp */
   createdAt: Date
   /** Last update timestamp */
@@ -97,8 +210,6 @@ export type CoreWorkflow<
 > = {
   /** Unique workflow name */
   name: string
-  /** Description of the workflow */
-  description?: string
   /** The workflow function */
   func: PikkuFunctionConfig
   /** Middleware chain for this workflow */
@@ -107,118 +218,6 @@ export type CoreWorkflow<
   permissions?: PikkuFunctionConfig['permissions']
   /** Tags for organization and filtering */
   tags?: string[]
-  /** Documentation metadata */
-  docs?: PikkuDocs
-}
-
-/**
- * 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 WorkflowInteractionDoRPC = <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 WorkflowInteractionDoInline = <T>(
-  stepName: string,
-  fn: () => Promise<T> | T,
-  options?: WorkflowStepOptions
-) => Promise<T>
-
-/**
- * Type signature for workflow.sleep() - used by inspector
- */
-export type WorkflowInteractionSleep = (
-  stepName: string,
-  duration: string
-) => Promise<void>
-
-/**
- * Workflow step metadata (extracted by inspector)
- */
-export type WorkflowStepMeta =
-  | {
-      /** RPC form - generates queue worker */
-      type: 'rpc'
-      /** Cache key (stepName from workflow.do) */
-      stepName: string
-      /** RPC to invoke */
-      rpcName: string
-      /** Display name */
-      description?: string
-      /** Step options */
-      options?: WorkflowStepOptions
-    }
-  | {
-      /** Inline form - local execution */
-      type: 'inline'
-      /** Cache key (stepName from workflow.do) */
-      stepName: string
-      /** Display name */
-      description?: string
-      /** Step options */
-      options?: WorkflowStepOptions
-    }
-  | {
-      /** Sleep step */
-      type: 'sleep'
-      /** Cache key (stepName from workflow.sleep) */
-      stepName: string
-      /** Sleep duration */
-      duration: string | number
-    }
-
-/**
- * Workflow step interaction context for RPC functions
- * Provides step-level metadata including retry attempt tracking
- */
-export interface WorkflowStepInteraction {
-  /** The workflow run ID */
-  runId: string
-  /** The unique step ID */
-  stepId: string
-  /** Current attempt number (1-indexed, increments on retry) */
-  attemptCount: number
-}
-
-/**
- * Workflow interaction object for middleware
- * Provides workflow-specific capabilities to function execution
- */
-export interface PikkuWorkflowInteraction {
-  /** 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: WorkflowInteractionDoRPC & WorkflowInteractionDoInline
-
-  /** Sleep for a duration */
-  sleep: WorkflowInteractionSleep
-
-  /** Cancel the current workflow run */
-  cancel: (reason?: string) => Promise<void>
 }
 
 /**
@@ -234,84 +233,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,
-  {
-    pikkuFuncName: string
+  CommonWireMeta & {
     workflowName: string
-    description?: string
-    session?: undefined
-    docs?: PikkuDocs
-    tags?: string[]
-    middleware?: MiddlewareMetadata[]
     steps: WorkflowStepMeta[]
+    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,
-    createSessionServices: CreateSessionServices,
-    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) */
+  pikkuFuncName: string
+  /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph' */
+  source?: 'dsl' | 'complex' | 'graph'
+  /** Optional description */
+  description?: string
+  /** Tags for organization */
+  tags?: string[]
+  /** Wires - how the workflow is triggered */
+  wires?: WorkflowWires
+  /** Serialized nodes */
+  nodes?: Record<string, any>
+  /** Entry node IDs for graph workflows (computed at build time) */
+  entryNodeIds?: string[]
 }
 
+/**
+ * Unified workflow runtime metadata map
+ */
+export type WorkflowsRuntimeMeta = Record<string, WorkflowRuntimeMeta>
+
 /**
  * Worker input types for generated queue workers
  */