@pikku/core 0.11.2 → 0.12.0

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

@@ -1,8 +1,13 @@
 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';
+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,99 +15,14 @@ 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
  */
-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
  */
@@ -121,6 +41,10 @@ export interface WorkflowRun {
     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 */
@@ -157,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
  */
@@ -204,7 +151,7 @@ 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[];
     context?: WorkflowContext;
     dsl?: boolean;
@@ -218,19 +165,19 @@ export interface WorkflowRuntimeMeta {
     /** Workflow name (used as key in registrations) */
     name: string;
     /** Pikku function name (for execution) */
-    pikkuFuncName: string;
+    pikkuFuncId: string;
     /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph' */
-    source?: 'dsl' | 'complex' | '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[];
+    /** Hash of graph topology (nodes, edges, input mappings) */
+    graphHash?: string;
 }
 /**
  * Unified workflow runtime metadata map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -26,35 +26,33 @@
     "./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",
-    "./forge-node": "./dist/wirings/forge-node/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"
   },
-  "peerDependencies": {
-    "zod": "^4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "zod": {
-      "optional": true
-    }
-  },
   "engines": {
     "node": ">=18"
   }

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/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'

package/src/factory-functions.test.ts

@@ -1,6 +1,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert'
 import {
+  pikkuAuth,
   pikkuPermission,
   pikkuMiddleware,
   pikkuPermissionFactory,
@@ -21,8 +22,8 @@ test('pikkuMiddleware returns the same function', async () => {
 
 test('pikkuPermissionFactory creates a factory function', async () => {
   const factory = pikkuPermissionFactory<{ role: string }>(({ role }) => {
-    return pikkuPermission(async ({ logger }, data, { initialSession }) => {
-      return (initialSession as any)?.role === role
+    return pikkuPermission(async ({ logger }, data, { session }) => {
+      return (session as any)?.role === role
     })
   })
 
@@ -67,3 +68,42 @@ test('pikkuMiddlewareFactory returns the same factory', async () => {
   const wrappedFactory = pikkuMiddlewareFactory(originalFactory)
   assert.strictEqual(wrappedFactory, originalFactory)
 })
+
+test('pikkuAuth returns a 3-arg wrapper function', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth(authFn)
+  assert.strictEqual(typeof wrapped, 'function')
+  assert.strictEqual(wrapped.length, 3)
+})
+
+test('pikkuAuth wrapper extracts session from wire and calls auth function', async () => {
+  let receivedSession = null
+  const authFn = async (_services, session) => {
+    receivedSession = session
+    return session.role === 'admin'
+  }
+  const wrapped = pikkuAuth(authFn)
+  const result = await wrapped({}, null, { session: { role: 'admin' } })
+  assert.strictEqual(result, true)
+  assert.deepStrictEqual(receivedSession, { role: 'admin' })
+})
+
+test('pikkuAuth wrapper returns false when no session', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth(authFn)
+  const result = await wrapped({}, null, { session: null })
+  assert.strictEqual(result, false)
+})
+
+test('pikkuAuth config object syntax works', async () => {
+  const authFn = async (_services, session) => !!session
+  const wrapped = pikkuAuth({
+    func: authFn,
+    name: 'Is Authenticated',
+    description: 'Checks if user has a session',
+  })
+  assert.strictEqual(typeof wrapped, 'function')
+  assert.strictEqual(wrapped.length, 3)
+  const result = await wrapped({}, null, { session: { id: '1' } })
+  assert.strictEqual(result, true)
+})

package/src/function/function-runner.test.ts

@@ -22,7 +22,7 @@ const addTestFunction = (funcName: string, funcConfig: any) => {
     ? funcConfig.tags.map((tag: string) => ({ type: 'tag' as const, tag }))
     : undefined
   pikkuState(null, 'function', 'meta')[funcName] = {
-    pikkuFuncName: funcName,
+    pikkuFuncId: funcName,
     inputSchemaName: null,
     outputSchemaName: null,
     middleware,
@@ -152,14 +152,8 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Order: wiringTags → wiringPermissions → funcTags → funcPermissions
-    assert.deepEqual(executionOrder, [
-      'wiringTag',
-      'wiringPermission',
-      'funcTag',
-      'funcPermission',
-      'main',
-    ])
+    // Order: wiringTags → main (short-circuit on first passing group)
+    assert.deepEqual(executionOrder, ['wiringTag', 'main'])
   })
 
   test('should throw specific error for wiring tag permission failures', async () => {
@@ -340,11 +334,10 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Should execute tag permissions first, then function permissions
+    // Should execute tag permissions and short-circuit before function permissions
     assert.deepEqual(executionOrder, [
       'arrayPermission1',
       'arrayPermission2',
-      'objectPermission',
       'main',
     ])
   })