@pikku/cli 0.12.104 → 0.12.107

package/dist/src/functions/wirings/webhook/serialize-webhook.js

@@ -4,7 +4,7 @@
  * The handler is inlined: it is wired exactly once, so a named export would
  * only be indirection.
  */
-export const serializeWebhook = (pathToPikkuTypes) => {
+export const serializeWebhook = (leaf) => {
     const schemas = `/**
  * Auto-generated outgoing webhook delivery schemas
  * Do not edit manually - regenerate with 'npx pikku'
@@ -23,7 +23,8 @@ export const WebhookDelivery = z.object({
  * Auto-generated outgoing webhook delivery queue worker
  * Do not edit manually - regenerate with 'npx pikku'
  */
-import { pikkuSessionlessFunc, wireQueueWorker } from '${pathToPikkuTypes}'
+import { pikkuSessionlessFunc } from '${leaf('function')}'
+import { wireQueueWorker } from '${leaf('queue')}'
 import { pikkuWebhookWorkerFunc } from '@pikku/core/services'
 import { WebhookDelivery } from './webhook.schemas.gen.js'
 

package/dist/src/functions/wirings/workflow/pikku-command-workflow-routes.d.ts

@@ -1 +1 @@
-export declare const pikkuWorkflowRoutes: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuWorkflowRoutes: import("#pikku/function").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;

package/dist/src/functions/wirings/workflow/pikku-command-workflow-routes.js

@@ -1,5 +1,5 @@
-import { pikkuSessionlessFunc } from '#pikku';
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { pikkuSessionlessFunc } from '#pikku/function';
+import { getLeafImportPath } from '../../../utils/leaf-import-path.js';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
@@ -10,8 +10,8 @@ export const pikkuWorkflowRoutes = pikkuSessionlessFunc({
         if (config.scaffold?.workflow &&
             config.workflowRoutesFile &&
             config.workflowRoutesSchemasFile) {
-            const pathToPikkuTypes = getFileImportRelativePath(config.workflowRoutesFile, config.typesDeclarationFile, config.packageMappings);
-            const { schemas, functions } = serializeWorkflowRoutes(pathToPikkuTypes, resolveScaffoldFeature('workflow', config.scaffold?.workflow).auth);
+            const leaf = (name) => getLeafImportPath(config.workflowRoutesFile, name, config);
+            const { schemas, functions } = serializeWorkflowRoutes(leaf, resolveScaffoldFeature('workflow', config.scaffold?.workflow).auth);
             await writeFileInDir(logger, config.workflowRoutesSchemasFile, schemas);
             await writeFileInDir(logger, config.workflowRoutesFile, functions);
             await removeLegacyScaffoldFile(config.workflowRoutesFile);

package/dist/src/functions/wirings/workflow/pikku-command-workflow.d.ts

@@ -1,5 +1,5 @@
 type WorkflowCommandInput = {
     bootstrap?: boolean;
 };
-export declare const pikkuWorkflow: import("#pikku").PikkuFunctionConfig<WorkflowCommandInput, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<WorkflowCommandInput, boolean | undefined, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<WorkflowCommandInput, boolean | undefined, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuWorkflow: import("#pikku/function").PikkuFunctionConfig<WorkflowCommandInput, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<WorkflowCommandInput, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<WorkflowCommandInput, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
 export {};

package/dist/src/functions/wirings/workflow/pikku-command-workflow.js

@@ -1,8 +1,9 @@
-import { pikkuSessionlessFunc } from '#pikku';
+import { pikkuSessionlessFunc } from '#pikku/function';
 import { ErrorCode } from '@pikku/inspector';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeWorkflowTypes } from './serialize-workflow-types.js';
+import { serializeScenarioTypes } from './serialize-scenario-types.js';
 import { serializePersonas } from './serialize-personas.js';
 import { resolvePersonas } from '../../../utils/resolve-personas.js';
 import { serializeWorkflowRegistration } from './serialize-workflow-registration.js';
@@ -16,7 +17,7 @@ import { buildFeaturesMeta } from '../scenarios/serialize-feature-meta.js';
 import { serializeScenarioWorkflowMeta } from '../scenarios/serialize-scenario-meta.js';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { rm } from 'fs/promises';
 export const pikkuWorkflow = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }, input) => {
@@ -88,9 +89,11 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
         const workflowMapImportPath = getFileImportRelativePath(workflowTypesFile, workflowMapDeclarationFile, packageMappings);
         const agentMapImportPath = getFileImportRelativePath(workflowTypesFile, config.agentMapDeclarationFile, packageMappings);
         const scopesImportPath = getFileImportRelativePath(workflowTypesFile, config.scopesFile, packageMappings);
-        const scenarioStepMapImportPath = getFileImportRelativePath(workflowTypesFile, config.scenarioStepMapDeclarationFile, packageMappings);
-        const personasImportPath = getFileImportRelativePath(workflowTypesFile, config.personasWiringFile, packageMappings);
-        await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath, personasImportPath));
+        await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, getFileImportRelativePath(workflowTypesFile, config.middlewareTypesFile, packageMappings), getFileImportRelativePath(workflowTypesFile, config.authGuardsFile, packageMappings), rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath));
+        // Scenarios get their own barrel: a scenario is a testing primitive, and
+        // mixing it into the workflow barrel meant every project that only ships
+        // workflows still imported the whole scenario surface.
+        await writeFileInDir(logger, config.scenarioTypesFile, serializeScenarioTypes(getFileImportRelativePath(config.scenarioTypesFile, functionTypesFile, packageMappings), getFileImportRelativePath(config.scenarioTypesFile, config.middlewareTypesFile, packageMappings), getFileImportRelativePath(config.scenarioTypesFile, workflowTypesFile, packageMappings), getFileImportRelativePath(config.scenarioTypesFile, config.scenarioStepMapDeclarationFile, packageMappings), getFileImportRelativePath(config.scenarioTypesFile, config.personasWiringFile, packageMappings)));
         // Rides the workflow command rather than getting its own codegen node, so
         // it can't drift out of the two hand-maintained ordering lists.
         await writeFileInDir(logger, config.scenarioStepMapDeclarationFile, serializeScenarioStepMap(logger, config.scenarioStepMapDeclarationFile, packageMappings, typesMap, functionState.meta));
@@ -101,6 +104,12 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
             const agentMapImportPath = getFileImportRelativePath(config.personasWiringFile, config.agentMapDeclarationFile, packageMappings);
             const exposedRpcMapImportPath = getFileImportRelativePath(config.personasWiringFile, config.rpcMapDeclarationFile, packageMappings);
             await writeFileInDir(logger, config.personasWiringFile, serializePersonas(personas, agentMapImportPath, exposedRpcMapImportPath));
+            // Same reason as the scenario meta above: a project generated before this
+            // moved to `scenarios/` still has a copy under `workflow/`, and tsc
+            // compiles every file in the output tree whether anything imports it.
+            await rm(join(dirname(workflowTypesFile), 'pikku-personas.gen.ts'), {
+                force: true,
+            });
             // Fixed path getPersonasMeta() reads; kept out of workflow/meta, which
             // getWorkflowMeta() globs as workflows.
             await writeFileInDir(logger, join(config.outDir, 'workflow', 'personas.gen.json'), JSON.stringify(personas, null, 2));

package/dist/src/functions/wirings/workflow/serialize-personas.js

@@ -10,7 +10,8 @@ export const serializePersonas = (personas, agentMapImportPath, rpcMapImportPath
     return `/** Personas declared with definePersonas() */
 import { createHttpPersonas } from '@pikku/core/persona'
 import type { HttpPersonasConfig } from '@pikku/core/persona'
-import type { ScenarioPersona, ResolvedPersona } from '@pikku/core/services'
+import type { ScenarioPersona } from '@pikku/core/services'
+import type { ResolvedPersona } from '@pikku/core/services'
 import type { AgentMap } from '${agentMapImportPath}'
 import type { FlattenedRPCMap } from '${rpcMapImportPath}'
 

package/dist/src/functions/wirings/workflow/serialize-scenario-step-map.d.ts

@@ -1,4 +1,3 @@
 import { type TypesMap } from '@pikku/inspector';
-import type { FunctionsMeta } from '@pikku/core';
-import type { Logger } from '@pikku/core/services';
+import type { FunctionsMeta, Logger } from '@pikku/core/services';
 export declare const serializeScenarioStepMap: (logger: Logger, relativeToPath: string, packageMappings: Record<string, string>, typesMap: TypesMap, functionsMeta: FunctionsMeta) => string;

package/dist/src/functions/wirings/workflow/serialize-scenario-types.d.ts

@@ -0,0 +1,2 @@
+export declare const sharedWorkflowConfigFields = "  title?: string\n  description?: string\n  tags?: string[]\n  expose?: boolean\n  internal?: boolean\n  override?: string\n  version?: number\n  remote?: boolean\n  mcp?: boolean\n  readonly?: boolean\n  approvalRequired?: boolean\n  approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never\n  middleware?: PikkuMiddleware[]\n  input?: InputSchema\n  output?: OutputSchema\n  node?: NodeConfig\n  errors?: Array<typeof PikkuError>\n  inline?: boolean";
+export declare const serializeScenarioTypes: (functionTypesImportPath: string, middlewareTypesImportPath: string, workflowTypesImportPath: string, scenarioStepMapImportPath: string, personasImportPath: string) => string;

package/dist/src/functions/wirings/workflow/serialize-scenario-types.js

@@ -0,0 +1,511 @@
+/**
+ * The config fields a scenario shares with a workflow.
+ *
+ * Emitted into both barrels rather than imported across them: the workflow's
+ * own config type is private, and exporting it just so the scenario barrel can
+ * `Omit` from it would put a name back on the public surface to serve a
+ * generator-internal relationship. One definition here keeps the two emissions
+ * from drifting.
+ */
+const SHARED_CONFIG_FIELDS = `  title?: string
+  description?: string
+  tags?: string[]
+  expose?: boolean
+  internal?: boolean
+  override?: string
+  version?: number
+  remote?: boolean
+  mcp?: boolean
+  readonly?: boolean
+  approvalRequired?: boolean
+  approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never
+  middleware?: PikkuMiddleware[]
+  input?: InputSchema
+  output?: OutputSchema
+  node?: NodeConfig
+  errors?: Array<typeof PikkuError>
+  inline?: boolean`;
+export const sharedWorkflowConfigFields = SHARED_CONFIG_FIELDS;
+export const serializeScenarioTypes = (functionTypesImportPath, middlewareTypesImportPath, workflowTypesImportPath, scenarioStepMapImportPath, personasImportPath) => {
+    return `import type {
+  PikkuScenarioWire,
+  ScenarioStepOptions,
+} from '@pikku/core/scenario'
+import type { PikkuWorkflowWire } from '@pikku/core/workflow'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import { PikkuError } from '@pikku/core/errors'
+import type { PikkuFunctionSessionless, PikkuFunctionConfig, WiredServices, InferSchemaOutput, NodeConfig, PikkuApprovalDescription } from '${functionTypesImportPath}'
+import type { PikkuMiddleware } from '${middlewareTypesImportPath}'
+import type { TypedWorkflow } from '${workflowTypesImportPath}'
+import type { FlattenedScenarioStepMap } from '${scenarioStepMapImportPath}'
+import type { TypedPersonas } from '${personasImportPath}'
+
+export type { TypedPersonas }
+
+/**
+ * The scenario test surface, re-exported so a step file has one specifier to
+ * import from. These names are not generated — they come straight from core —
+ * but routing them through here means a scenario file never has to know
+ * whether the helper it wants is typed against this project or shipped by the
+ * framework.
+ */
+export {
+  createCookieJar,
+  createScenarioRunner,
+  pollUntil,
+  requireScenarioEnv,
+} from '@pikku/core/scenario'
+export type {
+  PikkuBrowserWire,
+  ScenarioSurface,
+  TestIdSelector,
+} from '@pikku/core/scenario'
+export { postScenarioJson, readScenarioHttpResponse } from '@pikku/core/persona'
+export type { ScenarioHttpResponse } from '@pikku/core/scenario'
+
+/**
+ * The typed half of a scenario wire: \`given\`/\`when\`/\`then\`, narrowed to the
+ * names declared by \`pikkuScenarioStep\` in this project. \`given\` and \`when\`
+ * differ only in the prose the reporter renders; \`then\` additionally makes the
+ * step's bindings witnesses rather than alternatives.
+ */
+export interface TypedScenarioSteps {
+  given<K extends keyof FlattenedScenarioStepMap>(
+    stepName: string,
+    stepFunc: K,
+    data?: FlattenedScenarioStepMap[K]['input'],
+    options?: ScenarioStepOptions
+  ): Promise<FlattenedScenarioStepMap[K]['output']>
+
+  when<K extends keyof FlattenedScenarioStepMap>(
+    stepName: string,
+    stepFunc: K,
+    data?: FlattenedScenarioStepMap[K]['input'],
+    options?: ScenarioStepOptions
+  ): Promise<FlattenedScenarioStepMap[K]['output']>
+
+  then<K extends keyof FlattenedScenarioStepMap>(
+    stepName: string,
+    stepFunc: K,
+    data?: FlattenedScenarioStepMap[K]['input'],
+    options?: ScenarioStepOptions
+  ): Promise<FlattenedScenarioStepMap[K]['output']>
+}
+
+/** \`Out\` types \`scenario.context\`. */
+export type TypedScenario<Out = unknown> = TypedWorkflow &
+  Omit<PikkuScenarioWire<Out>, keyof PikkuWorkflowWire | keyof TypedScenarioSteps> &
+  TypedScenarioSteps
+
+/**
+ * \`Ctx\` types \`scenario.context\`, defaulting to the body's own output. A hook
+ * returns void but shares the scenario's context, so it passes that scenario's
+ * output here instead.
+ */
+export type PikkuFunctionScenario<
+  In = unknown,
+  Out = never,
+  Ctx = Out
+> = PikkuFunctionSessionless<In, Out, 'scenario' | 'actors', WiredServices, Ctx>
+
+type PikkuScenarioConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = {
+${SHARED_CONFIG_FIELDS}
+  func: PikkuFunctionScenario<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown
+  >
+  /**
+   * Runs before the scenario body. Same signature as \`func\`, but its return
+   * value is discarded — a hook is setup, not a step, so it is never recorded
+   * on the ladder. Throwing skips the body and fails the run; \`after\` still
+   * runs.
+   */
+  before?: PikkuScenarioHook<InputSchema, OutputSchema>
+  /**
+   * Always runs after the scenario body, in a \`finally\`, whether it passed or
+   * failed. Throwing fails a run that would otherwise have passed; on an
+   * already-failed run it attaches as the \`cause\` and never replaces the
+   * original error. Reads \`scenario.context\` for whatever the body managed to
+   * record before it stopped.
+   */
+  after?: PikkuScenarioHook<InputSchema, OutputSchema>
+  /**
+   * Why this scenario is held out of a default run, stated where the scenario
+   * is. The scenario still appears in the plan and is reported as skipped
+   * rather than quietly omitted; naming it directly with \`--flows\` runs it
+   * anyway.
+   */
+  skip?: string
+}
+
+/**
+ * A scenario lifecycle hook: the scenario's own \`(services, data, wire)\`
+ * signature with its result discarded. \`OutputSchema\` types
+ * \`scenario.context\` while the return type stays \`void\`.
+ */
+export type PikkuScenarioHook<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = PikkuFunctionScenario<
+  InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+  void,
+  OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown
+>
+
+/**
+ * Declares a scenario hook. Returns the function verbatim — a hook is never
+ * registered, so this exists purely to give an inline hook a call site to be
+ * contextually typed from, the way every other pikku primitive is.
+ */
+export function pikkuScenarioHook<In = unknown, Ctx = unknown>(
+  hook: PikkuFunctionScenario<In, void, Ctx>
+): PikkuFunctionScenario<In, void, Ctx> {
+  return hook
+}
+
+/**
+ * A scenario: a complex workflow that drives the app the way users do.
+ * Steps run as actors over the REAL transport — \`scenario.do(step, rpc,
+ * data, { actor: actors.yasser })\` — so flows double as e2e tests and
+ * staged/production health checks (no state reset; scope what you create).
+ */
+export function pikkuScenario<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuScenarioConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenario' | 'actors', PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>, InputSchema, OutputSchema>
+export function pikkuScenario<In, Out = unknown>(
+  func:
+    | PikkuFunctionScenario<In, Out>
+    | PikkuFunctionConfig<In, Out, 'scenario' | 'actors', PikkuFunctionScenario<In, Out>>
+): PikkuFunctionConfig<In, Out, 'scenario' | 'actors'>
+export function pikkuScenario(func: any) {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * A scenario as a feature references it. Any \`pikkuScenario\` export is
+ * assignable; \`In\` is recovered from it so the paired form's \`data\` is
+ * checked against that scenario's own input.
+ */
+export type PikkuScenarioRef<In = any, Out = any> = PikkuFunctionConfig<
+  In,
+  Out,
+  'scenario' | 'actors',
+  PikkuFunctionScenario<In, Out>,
+  any,
+  any
+>
+
+/**
+ * One entry in a feature's \`scenarios\` list, validated against itself: a bare
+ * scenario, or a scenario paired with the input to run it with. The paired form
+ * is gherkin's \`Examples:\` written as an ordinary loop.
+ */
+export type PikkuFeatureEntry<Entry> = Entry extends {
+  scenario: PikkuScenarioRef<infer In>
+}
+  ? { scenario: PikkuScenarioRef<In>; data: In }
+  : Entry extends PikkuScenarioRef
+    ? Entry
+    : never
+
+type PikkuFeatureConfig<Scenarios extends readonly unknown[]> = {
+  /** Human-readable name. The export identifier is the id. */
+  name: string
+  description?: string
+  tags?: string[]
+  scenarios: { [K in keyof Scenarios]: PikkuFeatureEntry<Scenarios[K]> }
+  /**
+   * Runs ONCE before the whole group — not before each scenario. Per-scenario
+   * setup is the scenario's own \`before\`; gherkin's \`Background:\` is
+   * deliberately not expressible here.
+   */
+  before?: PikkuScenarioHook
+  after?: PikkuScenarioHook
+}
+
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * A scenario does not have to belong to a feature — a void-input scenario
+ * still runs standalone.
+ *
+ * \`\`\`ts
+ * export const credentialFeature = pikkuFeature({
+ *   name: 'Credential API',
+ *   tags: ['credential'],
+ *   before: startsMockOAuthServer,
+ *   after: stopsMockOAuthServer,
+ *   scenarios: [
+ *     credentialLazyLoadScenario,
+ *     ...['stripe', 'google'].map((name) => ({
+ *       scenario: credentialRoundTripScenario,
+ *       data: { name },
+ *     })),
+ *   ],
+ * })
+ * \`\`\`
+ */
+export function pikkuFeature<const Scenarios extends readonly unknown[]>(
+  config: PikkuFeatureConfig<Scenarios>
+): PikkuFeatureConfig<Scenarios> {
+  return config
+}
+
+/**
+ * One surface's implementation of a step.
+ *
+ * Each binding is typed independently, so a browser binding gets a non-optional
+ * \`wire.browser\` and a cli binding a non-optional \`wire.cli\` without either
+ * leaking into the other.
+ */
+export type PikkuFunctionScenarioStep<
+  In = unknown,
+  Out = never,
+  Surface extends 'browser' | 'cli' | 'default' = 'default',
+  HasActor extends boolean = false
+> = PikkuFunctionSessionless<
+  In,
+  Out,
+  | 'scenarioStep'
+  | (Surface extends 'default' ? never : Surface)
+  | (HasActor extends true ? 'actor' : never)
+>
+
+type PikkuScenarioStepConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  HasActor extends boolean = false
+> = {
+  /** Registered name — this is the string \`scenario.given()\` references. */
+  name: string
+  /**
+   * This step is driven by a persona, so \`wire.actor\` is injected and
+   * non-optional inside every binding, and the runner refuses to dispatch it
+   * without one.
+   *
+   * A \`browser\` binding implies it — a window is opened as somebody. Declare it
+   * for a server-side step that calls RPCs as its actor. Leave it off for a step
+   * that has no persona to be: an assertion over a value an earlier step
+   * returned, or one that posts credentials precisely because it must not reuse
+   * an actor's session.
+   */
+  actor?: HasActor
+  /**
+   * What this step does, for the console and for whoever reads the source. It
+   * is also the fallback prose when no \`template\` is declared, in which case a
+   * reporter renders "Given the shopper buys an apple". Defaults to the call
+   * site's step name.
+   */
+  description?: string
+  /**
+   * The prose a reporter renders for this step, with \`{placeholders}\` filled
+   * from the input the step was called with — \`'sees {packageName}'\` reports as
+   * "Then the admin sees @pikku/addon-todos". Every input field should appear,
+   * so the report names the values under test rather than repeating one
+   * sentence per call site.
+   */
+  template?: string
+  title?: string
+  tags?: string[]
+  input?: InputSchema
+  output?: OutputSchema
+  errors?: Array<typeof PikkuError>
+  /**
+   * Drive this step through a real browser, as a human would. The runner
+   * provisions a window for the step's actor first — which makes an actor
+   * mandatory — and \`wire.browser\` is non-optional inside it.
+   *
+   * Compose shared utilities here rather than writing raw clicks: the step says
+   * what the actor is doing, the utilities say how.
+   */
+  browser?: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'browser',
+    // A window is opened as somebody, so a browser binding has an actor whether
+    // or not the step declared one.
+    true
+  >
+  /** Drive this step remotely, over the websocket. */
+  cli?: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'cli',
+    HasActor
+  >
+  /**
+   * The server-side path — the fast suite, and the floor every other surface
+   * falls back to.
+   *
+   * On a \`then\`, this is not an alternative to the other bindings but a second
+   * **witness**: the run executes every binding it has and fails if they
+   * disagree, because "the row says paid" and "the page says paid" are different
+   * claims and the gap between them is the bug nobody catches.
+   */
+  default?: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'default',
+    HasActor
+  >
+}
+
+type PikkuScenarioStepConfig<In, Out, HasActor extends boolean = false> =
+  Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined, HasActor>, 'browser' | 'cli' | 'default' | 'input' | 'output'> & {
+    browser?: PikkuFunctionScenarioStep<In, Out, 'browser', true>
+    cli?: PikkuFunctionScenarioStep<In, Out, 'cli', HasActor>
+    default?: PikkuFunctionScenarioStep<In, Out, 'default', HasActor>
+  }
+
+/**
+ * A named, reusable scenario step, declaring one implementation per surface an
+ * actor can drive it through.
+ *
+ * The step's identity is what the actor is trying to do; which surface carries
+ * it out is a binding. That is what lets one ladder run through a real browser,
+ * over the websocket, or entirely server-side — and what makes "how much of this
+ * flow can a human actually reach" a number rather than a guess.
+ *
+ * Steps are deliberately NOT registered as RPCs: a browser-driving step must
+ * never be network-callable.
+ */
+export function pikkuScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema, true> & { actor: true }
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep' | 'browser' | 'cli', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser' | 'cli' | 'default'>, InputSchema, OutputSchema>
+export function pikkuScenarioStep<In, Out = unknown>(
+  config: PikkuScenarioStepConfig<In, Out, true> & { actor: true }
+): PikkuFunctionConfig<In, Out, 'scenarioStep' | 'browser' | 'cli'>
+export function pikkuScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema, true> & { browser: {} }
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep' | 'browser' | 'cli', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser' | 'cli' | 'default'>, InputSchema, OutputSchema>
+export function pikkuScenarioStep<In, Out = unknown>(
+  config: PikkuScenarioStepConfig<In, Out, true> & { browser: {} }
+): PikkuFunctionConfig<In, Out, 'scenarioStep' | 'browser' | 'cli'>
+export function pikkuScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep' | 'browser' | 'cli', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser' | 'cli' | 'default'>, InputSchema, OutputSchema>
+export function pikkuScenarioStep<In, Out = unknown>(
+  config: PikkuScenarioStepConfig<In, Out>
+): PikkuFunctionConfig<In, Out, 'scenarioStep' | 'browser' | 'cli'>
+export function pikkuScenarioStep(config: any) {
+  const surfaces = (['browser', 'cli', 'default'] as const).filter(
+    (surface) => typeof config[surface] === 'function'
+  )
+  if (surfaces.length === 0) {
+    throw new Error(
+      \`[scenario] step '\${config.name}' declares no surface bindings. Add at least a \\\`default\\\` (server-side) implementation.\`
+    )
+  }
+  return {
+    ...config,
+    surfaces,
+    requiresActor: config.actor === true || surfaces.includes('browser'),
+    // The runner sets the surface on the wire and calls this once per binding it
+    // resolved — every witness of a \`then\`, exactly one for an action step.
+    func: (services: any, data: any, wire: any) => {
+      const surface = wire?.scenarioStep?.surface ?? 'default'
+      const binding = config[surface] ?? config.default
+      return binding(services, data, wire)
+    },
+  }
+}
+
+/**
+ * What a step declares when nobody drives it: one implementation, and no
+ * surfaces to choose between.
+ *
+ * \`func\` rather than \`default\` is the point. \`default\` means *the fallback when
+ * no other surface applies*, which implies others could exist; \`func\` says
+ * structurally that there is one way this happens. That also keeps the phase
+ * rule coherent — an assertion runs every witness it has and fails if they
+ * disagree, and this has exactly one by construction.
+ */
+type PikkuSubjectScenarioStepConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = Omit<
+  PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>,
+  'browser' | 'cli' | 'default' | 'actor'
+> & {
+  func: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'default'
+  >
+}
+
+type PikkuSubjectScenarioStepConfig<In, Out> =
+  Omit<PikkuScenarioStepConfig<In, Out>, 'browser' | 'cli' | 'default' | 'actor'> & {
+    func: PikkuFunctionScenarioStep<In, Out, 'default'>
+  }
+
+/**
+ * A step in which the app acts on itself — "Given the platform has expired the
+ * trial".
+ *
+ * The grammatical subject of that sentence is not a user of your app; it **is**
+ * your app, which is why it is its own declaration rather than a persona with an
+ * asterisk. A persona is a person.
+ *
+ * Local-test-only, and never in a virtual user's catalogue: a virtual user that
+ * could expire its own trial is manufacturing the outcome it exists to discover.
+ */
+export function pikkuPlatformScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>
+export function pikkuPlatformScenarioStep<In, Out = unknown>(
+  config: PikkuSubjectScenarioStepConfig<In, Out>
+): PikkuFunctionConfig<In, Out, 'scenarioStep'>
+export function pikkuPlatformScenarioStep(config: any) {
+  return { ...config, surfaces: ['default'] }
+}
+
+/**
+ * A step in which a third-party system acts — "Given Stripe's webhook arrives",
+ * "When Mailgun bounces it".
+ *
+ * \`addon\` names the addon that wraps that service, the same name its
+ * \`wireAddon\` declares. These steps *are* the mock its consumers currently
+ * hand-write: shipped by the addon author, maintained with the addon, and the
+ * same artifact that appears in the prose.
+ *
+ * Note that arranging and asserting are different — "Stripe's webhook arrives"
+ * stubs, "Then Stripe was charged" asserts, and only the first is a stub.
+ *
+ * Local-test-only, and never in a virtual user's catalogue: one that could
+ * invoke this would forge its own payment success.
+ */
+export function pikkuAddonScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema> & { addon: string }
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>
+export function pikkuAddonScenarioStep<In, Out = unknown>(
+  config: PikkuSubjectScenarioStepConfig<In, Out> & { addon: string }
+): PikkuFunctionConfig<In, Out, 'scenarioStep'>
+export function pikkuAddonScenarioStep(config: any) {
+  return { ...config, surfaces: ['default'] }
+}
+`;
+};

package/dist/src/functions/wirings/workflow/serialize-workflow-map.d.ts

@@ -4,8 +4,7 @@
 import type { WorkflowsMeta } from '@pikku/core/workflow';
 import { type TypesMap } from '@pikku/inspector';
 import type { SerializedWorkflowGraphs } from '@pikku/inspector/workflow-graph';
-import type { FunctionsMeta } from '@pikku/core';
-import type { Logger } from '@pikku/core/services';
+import type { FunctionsMeta, Logger } from '@pikku/core/services';
 type WireAddonDeclarations = Map<string, {
     package: string;
     rpcEndpoint?: string;

package/dist/src/functions/wirings/workflow/serialize-workflow-map.js

@@ -1,6 +1,6 @@
 import { serializeImportMap } from '../../../utils/serialize-import-map.js';
 import { generateCustomTypes } from '@pikku/inspector';
-import { parseVersionedId } from '@pikku/core';
+import { parseVersionedId } from '@pikku/core/utils';
 /**
  * A workflow or graph node name is free-form prose written by a human, so an
  * apostrophe or a backslash in it is ordinary. `JSON.stringify` emits a valid,