@pikku/core 0.11.0 → 0.11.1

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

@@ -1,10 +1,9 @@
 import {
-  PikkuDocs,
-  MiddlewareMetadata,
   SerializedError,
   CoreSingletonServices,
-  CreateSessionServices,
+  CreateWireServices,
   CoreConfig,
+  CommonWireMeta,
 } from '../../types/core.types.js'
 import { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 
@@ -97,8 +96,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,8 +104,6 @@ export type CoreWorkflow<
   permissions?: PikkuFunctionConfig['permissions']
   /** Tags for organization and filtering */
   tags?: string[]
-  /** Documentation metadata */
-  docs?: PikkuDocs
 }
 
 /**
@@ -127,7 +122,7 @@ export interface WorkflowStepOptions {
 /**
  * Type signature for workflow.do() RPC form - used by inspector
  */
-export type WorkflowInteractionDoRPC = <TOutput = any, TInput = any>(
+export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(
   stepName: string,
   rpcName: string,
   data: TInput,
@@ -137,7 +132,7 @@ export type WorkflowInteractionDoRPC = <TOutput = any, TInput = any>(
 /**
  * Type signature for workflow.do() inline form - used by inspector
  */
-export type WorkflowInteractionDoInline = <T>(
+export type WorkflowWireDoInline = <T>(
   stepName: string,
   fn: () => Promise<T> | T,
   options?: WorkflowStepOptions
@@ -146,51 +141,150 @@ export type WorkflowInteractionDoInline = <T>(
 /**
  * Type signature for workflow.sleep() - used by inspector
  */
-export type WorkflowInteractionSleep = (
+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 =
-  | {
-      /** 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
-    }
+  | RpcStepMeta
+  | BranchStepMeta
+  | ParallelGroupStepMeta
+  | FanoutStepMeta
+  | ReturnStepMeta
+  | InlineStepMeta
+  | SleepStepMeta
+  | CancelStepMeta
 
 /**
- * Workflow step interaction context for RPC functions
+ * Workflow step wire context for RPC functions
  * Provides step-level metadata including retry attempt tracking
  */
-export interface WorkflowStepInteraction {
+export interface WorkflowStepWire {
   /** The workflow run ID */
   runId: string
   /** The unique step ID */
@@ -200,10 +294,10 @@ export interface WorkflowStepInteraction {
 }
 
 /**
- * Workflow interaction object for middleware
+ * Workflow wire object for middleware
  * Provides workflow-specific capabilities to function execution
  */
-export interface PikkuWorkflowInteraction {
+export interface PikkuWorkflowWire {
   /** The workflow name */
   workflowName: string
   /** The current run ID */
@@ -212,10 +306,10 @@ export interface PikkuWorkflowInteraction {
   getRun: () => Promise<WorkflowRun>
 
   /** Execute a workflow step (overloaded - RPC or inline form) */
-  do: WorkflowInteractionDoRPC & WorkflowInteractionDoInline
+  do: WorkflowWireDoRPC & WorkflowWireDoInline
 
   /** Sleep for a duration */
-  sleep: WorkflowInteractionSleep
+  sleep: WorkflowWireSleep
 
   /** Cancel the current workflow run */
   cancel: (reason?: string) => Promise<void>
@@ -238,15 +332,11 @@ export interface PikkuWorkflow {
  */
 export type WorkflowsMeta = Record<
   string,
-  {
-    pikkuFuncName: string
+  CommonWireMeta & {
     workflowName: string
-    description?: string
-    session?: undefined
-    docs?: PikkuDocs
-    tags?: string[]
-    middleware?: MiddlewareMetadata[]
     steps: WorkflowStepMeta[]
+    /** Whether this workflow conforms to simple workflow DSL */
+    simple?: boolean
   }
 >
 
@@ -272,7 +362,7 @@ export interface WorkflowService {
   resumeWorkflow(runId: string): Promise<void>
   setServices(
     singletonServices: CoreSingletonServices,
-    createSessionServices: CreateSessionServices,
+    createWireServices: CreateWireServices,
     config: CoreConfig
   ): void
   startWorkflow<I>(