@pikku/core 0.12.51 → 0.12.53

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -11,6 +11,7 @@ import {
   pikkuState,
 } from '../../pikku-state.js'
 import { getDurationInMilliseconds } from '../../time-utils.js'
+import { createHttpScenarioActors } from '../../services/http-scenario-actors.js'
 
 const resolveWorkflowMeta = (
   name: string
@@ -59,6 +60,8 @@ import type {
   WorkflowServiceConfig,
   WorkflowStepOptions,
   WorkflowExpectEventuallyOptions,
+  WorkflowExpectErrorOptions,
+  WorkflowExpectServiceOptions,
 } from './workflow.types.js'
 import {
   continueGraph,
@@ -67,7 +70,7 @@ import {
   runFromMeta,
 } from './graph/graph-runner.js'
 import type { WorkflowService } from '../../services/workflow-service.js'
-import type { UserFlowActors } from '../../services/user-flow-actors-service.js'
+import type { ScenarioActors } from '../../services/scenario-actors-service.js'
 import {
   PikkuError,
   addError,
@@ -222,7 +225,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
   private inlineRuns = new Set<string>()
   // User-flow actors per run: live authenticated clients (cookie jars) are
   // process-local by nature, so they ride this map, never the persisted wire.
-  private runActors = new Map<string, UserFlowActors>()
+  private runActors = new Map<string, ScenarioActors>()
 
   protected get logger() {
     return getSingletonServices()?.logger
@@ -1065,6 +1068,39 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     return true
   }
 
+  /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
+  private async resolveScenarioActors(): Promise<ScenarioActors | undefined> {
+    const services = getSingletonServices()
+    const variables = services?.variables
+    const metaService = services?.metaService
+    if (!variables || !metaService) {
+      return undefined
+    }
+    const secret = await variables.get('SCENARIO_ACTOR_SECRET')
+    const apiUrl = await variables.get('API_URL')
+    if (!secret || !apiUrl) {
+      services?.logger?.warn(
+        'A scenario was started without actors but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without actors.'
+      )
+      return undefined
+    }
+    const actorsConfig = await metaService.getScenarioActorsMeta()
+    if (!actorsConfig || Object.keys(actorsConfig).length === 0) {
+      return undefined
+    }
+    const signInPath =
+      (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
+      '/api/auth/sign-in/actor'
+    const rpcPath = (await variables.get('SCENARIO_RPC_PATH')) ?? '/rpc'
+    return createHttpScenarioActors({
+      apiUrl,
+      secret,
+      actors: actorsConfig,
+      signInPath,
+      rpcPath,
+    })
+  }
+
   /**
    * Start a new workflow run
    * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -1076,7 +1112,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     input: I,
     wire: WorkflowRunWire,
     rpcService: any,
-    options?: { inline?: boolean; startNode?: string; actors?: UserFlowActors }
+    options?: { inline?: boolean; startNode?: string; actors?: ScenarioActors }
   ): Promise<{ runId: string }> {
     // Resolve workflow from static meta (root or addon namespace), then dynamic DB
     const resolved = resolveWorkflowMeta(name)
@@ -1140,8 +1176,13 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       }
     )
 
-    if (options?.actors) {
-      this.runActors.set(runId, options.actors)
+    const actors =
+      options?.actors ??
+      (workflowMeta.source === 'scenario'
+        ? await this.resolveScenarioActors()
+        : undefined)
+    if (actors) {
+      this.runActors.set(runId, actors)
     }
 
     if (shouldInline) {
@@ -2184,6 +2225,104 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         )
       },
 
+      expectError: async (
+        stepName: string,
+        rpcName: string,
+        data: any,
+        options?: WorkflowExpectErrorOptions
+      ) => {
+        this.verifyStepName(stepName)
+        const resolvedRpcName =
+          addonNamespace && !rpcName.includes(':')
+            ? `${addonNamespace}:${rpcName}`
+            : rpcName
+        return await this.inlineStep(
+          runId,
+          stepName,
+          async () => {
+            let result: any
+            try {
+              result = options?.actor
+                ? await options.actor.invoke(resolvedRpcName, data)
+                : await rpcService.rpcWithWire(resolvedRpcName, data, {})
+            } catch (e: any) {
+              const message = e?.message ?? String(e)
+              if (options?.matches) {
+                const matched =
+                  typeof options.matches === 'string'
+                    ? message.includes(options.matches)
+                    : options.matches.test(message)
+                if (!matched) {
+                  throw new Error(
+                    `[workflow] expectError '${stepName}' ('${resolvedRpcName}') threw, but the message did not match ${options.matches}: ${message}`
+                  )
+                }
+              }
+              return message
+            }
+            throw new Error(
+              `[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`
+            )
+          },
+          options
+        )
+      },
+
+      expectService: async (
+        stepName: string,
+        serviceMethod: string,
+        options?: WorkflowExpectServiceOptions
+      ) => {
+        this.verifyStepName(stepName)
+        const [service, method] = serviceMethod.split('.')
+        if (!service || !method) {
+          throw new Error(
+            `[workflow] expectService '${stepName}' needs 'service.method', got '${serviceMethod}'`
+          )
+        }
+        await this.inlineStep(
+          runId,
+          stepName,
+          async () => {
+            const rpcName = 'console:getStubCalls'
+            const calls: Array<{
+              service: string
+              method: string
+              args: unknown[]
+            }> = options?.actor
+              ? await options.actor.invoke(rpcName, { service })
+              : await rpcService.rpcWithWire(rpcName, { service }, {})
+            const matching = (calls ?? []).filter(
+              (c) =>
+                c.service === service &&
+                c.method === method &&
+                (options?.calledWith === undefined ||
+                  JSON.stringify(c.args?.[0]) ===
+                    JSON.stringify(options.calledWith))
+            )
+            const expected = options?.times
+            const ok =
+              expected === undefined
+                ? matching.length > 0
+                : matching.length === expected
+            if (!ok) {
+              const seen =
+                (calls ?? [])
+                  .map(
+                    (c) =>
+                      `${c.service}.${c.method}(${JSON.stringify(c.args?.[0])?.slice(0, 120) ?? ''})`
+                  )
+                  .join('\n  ') || '(none)'
+              throw new Error(
+                `[workflow] expectService '${stepName}' expected ${expected ?? 'at least one'} call(s) to '${serviceMethod}'` +
+                  `${options?.calledWith !== undefined ? ` with ${JSON.stringify(options.calledWith)}` : ''}, found ${matching.length}. Recorded:\n  ${seen}`
+              )
+            }
+          },
+          options
+        )
+      },
+
       // Implement workflow.sleep()
       sleep: async (stepName: string, duration: string | number) => {
         this.verifyStepName(stepName)

package/src/wirings/workflow/{user-flow-step.test.ts → scenario-step.test.ts}

@@ -3,14 +3,14 @@ import assert from 'node:assert/strict'
 
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
-import type { UserFlowActor } from '../../services/user-flow-actors-service.js'
+import type { ScenarioActor } from '../../services/scenario-actors-service.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
 const fakeActor = (
   name: string,
   handler: (rpcName: string, data: unknown) => Promise<unknown>
-): UserFlowActor & { calls: Array<{ rpcName: string; data: unknown }> } => {
+): ScenarioActor & { calls: Array<{ rpcName: string; data: unknown }> } => {
   const calls: Array<{ rpcName: string; data: unknown }> = []
   return {
     name,
@@ -31,14 +31,14 @@ const setup = async (
     logger: noopLogger,
     ...services,
   } as any)
-  const runId = await ws.createRun('userFlowTest', {}, true, 'hash', {
+  const runId = await ws.createRun('scenarioTest', {}, true, 'hash', {
     type: 'test',
   } as any)
   ws.registerInlineRun(runId)
   return runId
 }
 
-describe('user-flow actor steps (workflow.do with `actor`)', () => {
+describe('scenario actor steps (workflow.do with `actor`)', () => {
   beforeEach(() => resetPikkuState())
 
   test('routes through the actor over the real transport, never internal rpc', async () => {
@@ -54,7 +54,7 @@ describe('user-flow actor steps (workflow.do with `actor`)', () => {
       },
     }
 
-    const wire = ws.createWorkflowWire('userFlowTest', runId, rpc)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, rpc)
     const result = await wire.do(
       'customer creates todo',
       'createTodo',
@@ -74,7 +74,7 @@ describe('user-flow actor steps (workflow.do with `actor`)', () => {
     let invocations = 0
     const yasser = fakeActor('yasser', async () => ({ n: ++invocations }))
     const runId = await setup(ws)
-    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
 
     const first = await wire.do('step', 'someRpc', {}, { actor: yasser })
     assert.deepEqual(first, { n: 1 })
@@ -82,8 +82,13 @@ describe('user-flow actor steps (workflow.do with `actor`)', () => {
     // Simulate replay: reset per-run ordinals so the same logical step name
     // resolves to the same durable step key.
     ;(ws as any).resetStepOrdinals(runId)
-    const replayWire = ws.createWorkflowWire('userFlowTest', runId, {})
-    const replayed = await replayWire.do('step', 'someRpc', {}, { actor: yasser })
+    const replayWire = ws.createWorkflowWire('scenarioTest', runId, {})
+    const replayed = await replayWire.do(
+      'step',
+      'someRpc',
+      {},
+      { actor: yasser }
+    )
 
     assert.deepEqual(replayed, { n: 1 }, 'replay must return the cached result')
     assert.equal(invocations, 1, 'the actor must not be re-invoked on replay')
@@ -106,7 +111,7 @@ describe('user-flow actor steps (workflow.do with `actor`)', () => {
       workflowQueued: true,
     } as any
 
-    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
     await wire.do('step', 'queuedRpc', {}, { actor: customer })
 
     assert.equal(queued, 0, 'actor steps are outbound HTTP — never queued')
@@ -116,10 +121,10 @@ describe('user-flow actor steps (workflow.do with `actor`)', () => {
   test('actor step failure surfaces the actor error and fails after retries', async () => {
     const ws = new InMemoryWorkflowService()
     const broken = fakeActor('broken', async () => {
-      throw new Error("[user-flow] 'createTodo' as 'broken' returned 403: nope")
+      throw new Error("[scenario] 'createTodo' as 'broken' returned 403: nope")
     })
     const runId = await setup(ws)
-    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
 
     await assert.rejects(
       wire.do('step', 'createTodo', {}, { actor: broken, retries: 2 }),
@@ -139,7 +144,7 @@ describe('workflow.expectEventually', () => {
       notifications: ++polls >= 3 ? ['ping'] : [],
     }))
     const runId = await setup(ws)
-    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
 
     const result = await wire.expectEventually(
       'sarah sees the notification',
@@ -157,7 +162,7 @@ describe('workflow.expectEventually', () => {
     const ws = new InMemoryWorkflowService()
     const sarah = fakeActor('sarah', async () => ({ notifications: [] }))
     const runId = await setup(ws)
-    const wire = ws.createWorkflowWire('userFlowTest', runId, {})
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
 
     await assert.rejects(
       wire.expectEventually(
@@ -178,7 +183,7 @@ describe('workflow.expectEventually', () => {
     const rpc = {
       rpcWithWire: async () => ({ ready: ++polls >= 2 }),
     }
-    const wire = ws.createWorkflowWire('userFlowTest', runId, rpc)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, rpc)
 
     const result = await wire.expectEventually(
       'job finishes',

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

@@ -8,6 +8,8 @@ export type { WorkflowService } from '../../services/workflow-service.js'
 export type {
   WorkflowStepOptions,
   WorkflowExpectEventuallyOptions,
+  WorkflowExpectErrorOptions,
+  WorkflowExpectServiceOptions,
   WorkflowWireDoRPC,
   WorkflowWireDoInline,
   WorkflowWireSleep,
@@ -325,9 +327,9 @@ export type WorkflowsMeta = Record<
     context?: WorkflowContext
     dsl?: boolean
     expose?: boolean
-    /** True for pikkuUserFlow workflows (complex + actor steps). */
-    userFlow?: boolean
-    /** Actor names a user flow declares (personas it runs steps as). */
+    /** True for pikkuScenario workflows (complex + actor steps). */
+    scenario?: boolean
+    /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[]
   }
 >
@@ -342,13 +344,13 @@ export interface WorkflowRuntimeMeta {
   name: string
   /** Pikku function name (for execution) */
   pikkuFuncId: string
-  /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph', 'user-flow' (complex + actor steps) */
-  source: 'dsl' | 'complex' | 'graph' | 'dynamic-workflow' | 'user-flow'
+  /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph', 'scenario' (complex + actor steps) */
+  source: 'dsl' | 'complex' | 'graph' | 'dynamic-workflow' | 'scenario'
   /** Optional description */
   description?: string
   /** Tags for organization */
   tags?: string[]
-  /** Actor names a user flow declares (personas it runs steps as). */
+  /** Actor names a scenario declares (personas it runs steps as). */
   actors?: string[]
   /** Serialized nodes */
   nodes?: Record<string, any>