@pikku/core 0.11.0 → 0.11.2

package/dist/wirings/workflow/wire-workflow.js

@@ -0,0 +1,53 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Type guard for DSL workflow definition
+ */
+function isWorkflowDefinitionFunc(def) {
+    return 'func' in def;
+}
+/**
+ * Type guard for graph workflow definition
+ */
+function isWorkflowDefinitionGraph(def) {
+    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(definition) {
+    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/dist/wirings/workflow/workflow-utils.d.ts

@@ -0,0 +1,23 @@
+import { PikkuWire, CreateWireServices, CoreSingletonServices, CoreServices, CoreUserSession } from '../../types/core.types.js';
+import { HTTPWiringMeta } from '../http/http.types.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 declare const findWorkflowByHttpWire: (route: string, method: string) => WorkflowHttpMatch | undefined;
+/**
+ * Start a workflow triggered by an HTTP wire
+ * The workflow is responsible for handling the HTTP response
+ */
+export declare const startWorkflowByHttpWire: (singletonServices: CoreSingletonServices, createWireServices: CreateWireServices<CoreSingletonServices, CoreServices<CoreSingletonServices>, CoreUserSession> | undefined, matchedRoute: {
+    matchedPath: any;
+    params: any;
+    route: any;
+    meta: HTTPWiringMeta;
+}, wire: PikkuWire) => Promise<void>;

package/dist/wirings/workflow/workflow-utils.js

@@ -0,0 +1,66 @@
+import { pikkuState } from '../../pikku-state.js';
+import { NotFoundError } from '../../errors/errors.js';
+import { ContextAwareRPCService } from '../rpc/rpc-runner.js';
+/**
+ * Find workflow name by matching route and method against workflow wires
+ */
+export const findWorkflowByHttpWire = (route, method) => {
+    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, createWireServices, matchedRoute, wire) => {
+    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/dist/wirings/workflow/workflow.types.d.ts

@@ -1,5 +1,8 @@
-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';
+export type { WorkflowService } from '../../services/workflow-service.js';
+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;
@@ -7,6 +10,91 @@ export interface WorkflowServiceConfig {
     stepWorkerQueueName: string;
     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
  */
@@ -31,6 +119,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 */
@@ -73,8 +163,6 @@ export interface StepState {
 export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
     /** Unique workflow name */
     name: string;
-    /** Description of the workflow */
-    description?: string;
     /** The workflow function */
     func: PikkuFunctionConfig;
     /** Middleware chain for this workflow */
@@ -83,93 +171,7 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     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;
-}
-/**
- * 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>;
-}
 /**
  * Workflow client interface
  */
@@ -184,51 +186,56 @@ export interface PikkuWorkflow {
     cancelRun: (runId: string) => Promise<void>;
 }
 /**
- * Workflows metadata for inspector/CLI
+ * Context variable definition (serialized from Zod schema or type inference)
  */
-export type WorkflowsMeta = Record<string, {
-    pikkuFuncName: string;
-    workflowName: string;
+export interface ContextVariable {
+    /** Variable type */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** Default value */
+    default?: unknown;
+    /** Description for UI/docs */
     description?: string;
-    session?: undefined;
-    docs?: PikkuDocs;
-    tags?: string[];
-    middleware?: MiddlewareMetadata[];
+}
+/**
+ * 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;
     steps: WorkflowStepMeta[];
+    context?: WorkflowContext;
+    dsl?: boolean;
 }>;
 /**
- * Interface for workflow orchestration
- * Handles workflow execution, replay, orchestration logic, and run-level state
- */
-export interface WorkflowService {
-    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>;
-    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>;
-    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>;
-    executeWorkflowStep(runId: string, stepName: string, rpcName: string | null, data: any, rpcService: any): Promise<void>;
+ * 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) */
+    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
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -30,6 +30,7 @@
     "./mcp": "./dist/wirings/mcp/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/channel": "./dist/wirings/cli/channel/index.js",
+    "./forge-node": "./dist/wirings/forge-node/index.js",
     "./errors": "./dist/errors/index.js",
     "./services": "./dist/services/index.js",
     "./services/local-content": "./dist/services/local-content.js",
@@ -42,10 +43,18 @@
     "picoquery": "^2.5.0"
   },
   "devDependencies": {
-    "@types/node": "^24.9.1",
+    "@types/node": "^24.10.1",
     "tsx": "^4.20.6",
     "typescript": "^5.9"
   },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18"
   }

package/src/errors/error-handler.ts

@@ -30,7 +30,7 @@ export interface ErrorDetails {
  * @param details - The details of the error.
  */
 export const addError = (error: any, { status, message }: ErrorDetails) => {
-  pikkuState('misc', 'errors').set(error, { status, message })
+  pikkuState(null, 'misc', 'errors').set(error, { status, message })
 }
 
 /**
@@ -53,10 +53,10 @@ export const addErrors = (
 export const getErrorResponse = (
   error: Error
 ): { status: number; message: string; mcpCode?: number } | undefined => {
-  const errors = Array.from(pikkuState('misc', 'errors').entries())
+  const errors = Array.from(pikkuState(null, 'misc', 'errors').entries())
   const foundError = errors.find(([e]) => e.name === error.constructor.name)
   if (foundError) {
     return foundError[1]
   }
-  return pikkuState('misc', 'errors').get(error)
+  return pikkuState(null, 'misc', 'errors').get(error)
 }

package/src/errors/errors.ts

@@ -3,10 +3,10 @@
  */
 import { addError, PikkuError } from './error-handler.js'
 
-export class InvalidMiddlewareInteractionError extends PikkuError {}
-addError(InvalidMiddlewareInteractionError, {
+export class InvalidMiddlewareWireError extends PikkuError {}
+addError(InvalidMiddlewareWireError, {
   status: 500,
-  message: 'The middleware interaction is invalid for the current wiring type.',
+  message: 'The middleware wire is invalid for the current wiring type.',
 })
 
 /**

package/src/factory-functions.test.ts

@@ -7,44 +7,22 @@ import {
   pikkuMiddlewareFactory,
 } from './index.js'
 
-test('pikkuPermission factory function', async () => {
-  const permission = pikkuPermission(async ({ logger }, data, session) => {
-    return true
-  })
-
-  assert.strictEqual(typeof permission, 'function')
-  assert.strictEqual(permission.length, 3) // services, data, session
-})
-
-test('pikkuMiddleware factory function', async () => {
-  const middleware = pikkuMiddleware(async ({ logger }, interactions, next) => {
-    await next()
-  })
-
-  assert.strictEqual(typeof middleware, 'function')
-  assert.strictEqual(middleware.length, 3) // services, interactions, next
-})
-
 test('pikkuPermission returns the same function', async () => {
-  const originalFn = async ({ logger }, data, session) => true
+  const originalFn = async () => true
   const wrappedFn = pikkuPermission(originalFn)
-
   assert.strictEqual(wrappedFn, originalFn)
 })
 
 test('pikkuMiddleware returns the same function', async () => {
-  const originalFn = async ({ logger }, interactions, next) => {
-    await next()
-  }
+  const originalFn = async ({ logger }, wires, next) => next
   const wrappedFn = pikkuMiddleware(originalFn)
-
   assert.strictEqual(wrappedFn, originalFn)
 })
 
 test('pikkuPermissionFactory creates a factory function', async () => {
   const factory = pikkuPermissionFactory<{ role: string }>(({ role }) => {
-    return pikkuPermission(async ({ logger }, data, session) => {
-      return session?.role === role
+    return pikkuPermission(async ({ logger }, data, { initialSession }) => {
+      return (initialSession as any)?.role === role
     })
   })
 
@@ -59,7 +37,7 @@ test('pikkuPermissionFactory creates a factory function', async () => {
 
 test('pikkuMiddlewareFactory creates a factory function', async () => {
   const factory = pikkuMiddlewareFactory<{ message: string }>(({ message }) => {
-    return pikkuMiddleware(async ({ logger }, interactions, next) => {
+    return pikkuMiddleware(async ({ logger }, wires, next) => {
       logger.info(message)
       await next()
     })
@@ -71,26 +49,21 @@ test('pikkuMiddlewareFactory creates a factory function', async () => {
   // Call the factory to get middleware
   const middleware = factory({ message: 'test' })
   assert.strictEqual(typeof middleware, 'function')
-  assert.strictEqual(middleware.length, 3) // services, interactions, next
+  assert.strictEqual(middleware.length, 3) // services, wires, next
 })
 
 test('pikkuPermissionFactory returns the same factory', async () => {
-  const originalFactory = ({ role }) =>
-    pikkuPermission(async ({ logger }, data, session) => {
-      return session?.role === role
-    })
-  const wrappedFactory = pikkuPermissionFactory(originalFactory)
-
+  const originalFactory = () => pikkuPermission(async () => true)
+  const wrappedFactory = pikkuPermissionFactory(originalFactory as any)
   assert.strictEqual(wrappedFactory, originalFactory)
 })
 
 test('pikkuMiddlewareFactory returns the same factory', async () => {
   const originalFactory = ({ message }) =>
-    pikkuMiddleware(async ({ logger }, interactions, next) => {
+    pikkuMiddleware(async ({ logger }, _wires, next) => {
       logger.info(message)
       await next()
     })
   const wrappedFactory = pikkuMiddlewareFactory(originalFactory)
-
   assert.strictEqual(wrappedFactory, originalFactory)
 })