@pikku/core 0.11.1 → 0.12.0

package/dist/wirings/workflow/workflow-helpers.d.ts

@@ -0,0 +1,36 @@
+export declare 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>;
+};
+export declare function workflowStart<TWorkflowMap extends Record<string, {
+    input: any;
+    output: any;
+}>>(workflowName: string & keyof TWorkflowMap): {
+    func: (services: any, data: any, wire: any) => Promise<{
+        runId: string;
+    }>;
+};
+export declare 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;
+        };
+    }>;
+};
+export declare 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;
+    }>;
+};

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

@@ -0,0 +1,38 @@
+import { WorkflowRunNotFoundError } from './pikku-workflow-service.js';
+export function workflow(workflowName, options) {
+    return {
+        func: async (services, data, { rpc }) => {
+            return services.workflowService.runToCompletion(workflowName, data, rpc, options);
+        },
+    };
+}
+export function workflowStart(workflowName) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.startWorkflow(workflowName, data);
+        },
+    };
+}
+export function workflowStatus(_workflowName) {
+    return {
+        func: async (services, data) => {
+            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(graphName, startNode) {
+    return {
+        func: async (_services, data, { rpc }) => {
+            return rpc.startWorkflow(graphName, data, { startNode });
+        },
+    };
+}

package/dist/wirings/workflow/workflow-utils.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/dist/wirings/workflow/workflow.types.d.ts

@@ -1,5 +1,13 @@
-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, 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;
@@ -10,11 +18,11 @@ export interface WorkflowServiceConfig {
 /**
  * Workflow run status
  */
-export type WorkflowStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+export type WorkflowStatus = 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled';
 /**
  * Workflow step status
  */
-export type StepStatus = 'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed';
+export type StepStatus = 'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed' | 'suspended';
 /**
  * Workflow run representation
  */
@@ -31,6 +39,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 */
@@ -67,6 +81,29 @@ export interface StepState {
     /** Timestamp when step failed */
     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
  */
@@ -82,183 +119,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 +133,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;
+    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 {
-    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) */
+    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
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -26,24 +26,31 @@
     "./http": "./dist/wirings/http/index.js",
     "./queue": "./dist/wirings/queue/index.js",
     "./scheduler": "./dist/wirings/scheduler/index.js",
+    "./trigger": "./dist/wirings/trigger/index.js",
     "./rpc": "./dist/wirings/rpc/index.js",
     "./mcp": "./dist/wirings/mcp/index.js",
+    "./ai-agent": "./dist/wirings/ai-agent/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/channel": "./dist/wirings/cli/channel/index.js",
+    "./node": "./dist/wirings/node/index.js",
+    "./secret": "./dist/wirings/secret/index.js",
+    "./variable": "./dist/wirings/variable/index.js",
+    "./oauth2": "./dist/wirings/oauth2/index.js",
     "./errors": "./dist/errors/index.js",
     "./services": "./dist/services/index.js",
     "./services/local-content": "./dist/services/local-content.js",
-    "./schema": "./dist/schema.js",
-    "./types": "./dist/types/index.d.ts"
+    "./services/gopass-secrets": "./dist/services/gopass-secrets.js",
+    "./schema": "./dist/schema.js"
   },
   "dependencies": {
-    "cookie": "^1.0.2",
+    "@standard-schema/spec": "^1.1.0",
+    "cookie": "^1.1.1",
     "path-to-regexp": "^8.3.0",
     "picoquery": "^2.5.0"
   },
   "devDependencies": {
-    "@types/node": "^24.10.1",
-    "tsx": "^4.20.6",
+    "@types/node": "^24.10.12",
+    "tsx": "^4.21.0",
     "typescript": "^5.9"
   },
   "engines": {

package/run-tests.sh

@@ -34,6 +34,9 @@ files=($(find src -type f -name "*.test.ts"))
 # Check if any files matched the pattern
 if [ ${#files[@]} -eq 0 ]; then
   echo "No test files found matching pattern: $pattern"
+  if [ "${STRICT_TEST_DISCOVERY}" = "1" ] || [ "${CI}" = "true" ]; then
+    exit 1
+  fi
   exit 0
 fi
 
@@ -50,4 +53,4 @@ if [ "$coverage_mode" = true ]; then
 fi
 
 # Execute the node command with the expanded list of files
-$node_cmd "${files[@]}"
+$node_cmd "${files[@]}"

package/src/crypto-utils.ts

@@ -0,0 +1,99 @@
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+const getSubtle = () => {
+  const crypto = globalThis.crypto
+  if (!crypto?.subtle) {
+    throw new Error('WebCrypto not available')
+  }
+  return crypto.subtle
+}
+
+const base64Encode = (bytes: Uint8Array): string => {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64')
+  }
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!)
+  }
+  return btoa(binary)
+}
+
+const base64Decode = (input: string): Uint8Array => {
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(input, 'base64'))
+  }
+  const binary = atob(input)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes
+}
+
+const toBase64Url = (bytes: Uint8Array): string => {
+  return base64Encode(bytes)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '')
+}
+
+const fromBase64Url = (input: string): Uint8Array => {
+  let base64 = input.replace(/-/g, '+').replace(/_/g, '/')
+  while (base64.length % 4 !== 0) base64 += '='
+  return base64Decode(base64)
+}
+
+const deriveKey = async (secret: string): Promise<CryptoKey> => {
+  const subtle = getSubtle()
+  const hash = await subtle.digest('SHA-256', encoder.encode(secret))
+  return subtle.importKey('raw', hash, { name: 'AES-GCM' }, false, [
+    'encrypt',
+    'decrypt',
+  ])
+}
+
+export const encryptJSON = async (
+  secret: string,
+  value: unknown
+): Promise<string> => {
+  const crypto = globalThis.crypto
+  if (!crypto?.getRandomValues) {
+    throw new Error('WebCrypto not available')
+  }
+  const subtle = getSubtle()
+  const iv = crypto.getRandomValues(new Uint8Array(12))
+  const key = await deriveKey(secret)
+  const plaintext = encoder.encode(JSON.stringify(value))
+  const encrypted = await subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    plaintext
+  )
+  const cipherBytes = new Uint8Array(encrypted)
+  const out = new Uint8Array(iv.length + cipherBytes.length)
+  out.set(iv, 0)
+  out.set(cipherBytes, iv.length)
+  return toBase64Url(out)
+}
+
+export const decryptJSON = async <T>(
+  secret: string,
+  token: string
+): Promise<T> => {
+  const subtle = getSubtle()
+  const data = fromBase64Url(token)
+  if (data.length < 13) {
+    throw new Error('Invalid encrypted payload')
+  }
+  const iv = data.slice(0, 12)
+  const ciphertext = data.slice(12)
+  const key = await deriveKey(secret)
+  const decrypted = await subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext
+  )
+  return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
+}

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

@@ -9,6 +9,12 @@ addError(InvalidMiddlewareWireError, {
   message: 'The middleware wire is invalid for the current wiring type.',
 })
 
+export class PikkuMissingMetaError extends PikkuError {}
+addError(PikkuMissingMetaError, {
+  status: 500,
+  message: 'Required metadata is missing',
+})
+
 /**
  * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
  * @group Error
@@ -345,3 +351,14 @@ addError(MaxComputeTimeReachedError, {
   message:
     'The server took too long to complete the request, reaching the maximum compute time allowed.',
 })
+
+/**
+ * A required schema was not found during validation.
+ * @group Error
+ */
+export class MissingSchemaError extends PikkuError {}
+addError(MissingSchemaError, {
+  status: 500,
+  message:
+    'A required schema was not found. Ensure schema generation has been run.',
+})

package/src/errors/index.ts

@@ -1,2 +1 @@
-export * from './error-handler.js'
 export * from './errors.js'