@pikku/core 0.11.1 → 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 { 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';
+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 */
@@ -82,183 +172,6 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     /** Tags for organization and filtering */
     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;
-}
-/**
- * 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
  */
@@ -273,47 +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 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;
     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 {
-    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, 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>;
-    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>;
+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.1",
+  "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",
@@ -46,6 +47,14 @@
     "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/function/function-runner.test.ts

@@ -21,7 +21,7 @@ const addTestFunction = (funcName: string, funcConfig: any) => {
   const permissions = funcConfig.tags
     ? funcConfig.tags.map((tag: string) => ({ type: 'tag' as const, tag }))
     : undefined
-  pikkuState('function', 'meta')[funcName] = {
+  pikkuState(null, 'function', 'meta')[funcName] = {
     pikkuFuncName: funcName,
     inputSchemaName: null,
     outputSchemaName: null,