@pikku/cli 0.12.89 → 0.12.91

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

@@ -8,9 +8,9 @@ export const serializeWorkflowMeta = (outputPath, metaDir, workflowNames, packag
     const pkg = packageName ? `'${packageName}'` : 'null';
     if (workflowNames.length === 0) {
         return `import { pikkuState } from '@pikku/core/internal'
-import type { SerializedWorkflowGraphs } from '@pikku/inspector/workflow-graph'
+import type { WorkflowsRuntimeMeta } from '@pikku/core/workflow/types'
 
-const workflowsMeta: SerializedWorkflowGraphs = {}
+const workflowsMeta: WorkflowsRuntimeMeta = {}
 
 pikkuState(${pkg}, 'workflows', 'meta', workflowsMeta)`;
     }
@@ -32,13 +32,13 @@ pikkuState(${pkg}, 'workflows', 'meta', workflowsMeta)`;
     })
         .join('\n');
     return `import { pikkuState } from '@pikku/core/internal'
-import type { SerializedWorkflowGraphs } from '@pikku/inspector/workflow-graph'
+import type { WorkflowsRuntimeMeta } from '@pikku/core/workflow/types'
 
 ${imports}
 
 const workflowsMeta = {
 ${metaEntries}
-} as SerializedWorkflowGraphs
+} as WorkflowsRuntimeMeta
 
 pikkuState(${pkg}, 'workflows', 'meta', workflowsMeta)`;
 };

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

@@ -1 +1 @@
-export declare const serializeWorkflowTypes: (functionTypesImportPath: string, rpcMapImportPath: string, workflowMapImportPath: string, agentMapImportPath: string, scopesImportPath: string) => string;
+export declare const serializeWorkflowTypes: (functionTypesImportPath: string, rpcMapImportPath: string, workflowMapImportPath: string, agentMapImportPath: string, scopesImportPath: string, scenarioStepMapImportPath?: string, scenarioActorsImportPath?: string) => string;

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

@@ -1,4 +1,4 @@
-export const serializeWorkflowTypes = (functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath) => {
+export const serializeWorkflowTypes = (functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath = './pikku-scenario-step-map.gen.js', scenarioActorsImportPath = './pikku-scenario-actors.gen.js') => {
     return `import { WorkflowCancelledException } from '@pikku/core/workflow'
 import { template } from '@pikku/core/workflow'
 import {
@@ -6,13 +6,17 @@ import {
   type PikkuWorkflowGraphConfig,
   type PikkuWorkflowGraphResult,
 } from '@pikku/core/workflow'
-import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowStepOptions } from '@pikku/core/workflow'
+import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowStepOptions, ScenarioStepOptions } from '@pikku/core/workflow'
 
 export { WorkflowCancelledException }
 import type { PikkuFunctionSessionless, PikkuFunctionConfig } from '${functionTypesImportPath}'
 import type { FlattenedRPCMap } from '${rpcMapImportPath}'
 import type { FlattenedWorkflowMap } from '${workflowMapImportPath}'
 import type { AgentMap as FlattenedAgentMap } from '${agentMapImportPath}'
+import type { FlattenedScenarioStepMap } from '${scenarioStepMapImportPath}'
+import type { TypedScenarioActors } from '${scenarioActorsImportPath}'
+
+export type { TypedScenarioActors }
 
 export { template }
 
@@ -38,7 +42,44 @@ export interface TypedWorkflow extends PikkuWorkflowWire {
   ): Promise<T>
 }
 
-export type TypedScenario = TypedWorkflow & Omit<PikkuScenarioWire, keyof PikkuWorkflowWire>
+/**
+ * The typed half of a scenario wire: \`step\` and its \`given\`/\`when\`/\`then\`
+ * sugar, narrowed to the names declared by \`pikkuScenarioStep\` in this project.
+ * The phase only changes the prose the reporter renders.
+ */
+export interface TypedScenarioSteps {
+  step<K extends keyof FlattenedScenarioStepMap>(
+    stepName: string,
+    stepFunc: K,
+    data?: FlattenedScenarioStepMap[K]['input'],
+    options?: ScenarioStepOptions
+  ): Promise<FlattenedScenarioStepMap[K]['output']>
+
+  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']>
+}
+
+export type TypedScenario = TypedWorkflow &
+  Omit<PikkuScenarioWire, keyof PikkuWorkflowWire | keyof TypedScenarioSteps> &
+  TypedScenarioSteps
 
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { InferSchemaOutput, PikkuPermission, PikkuMiddleware, NodeConfig, PikkuApprovalDescription } from '${functionTypesImportPath}'
@@ -129,6 +170,49 @@ export type PikkuScenarioConfigWithSchema<
     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>
+  /**
+   * 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.
+   */
+  after?: PikkuScenarioHook<InputSchema>
+  /**
+   * 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.
+ */
+export type PikkuScenarioHook<
+  InputSchema extends StandardSchemaV1 | undefined = undefined
+> = PikkuFunctionScenario<
+  InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+  void
+>
+
+/**
+ * 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>(
+  hook: PikkuFunctionScenario<In, void>
+): PikkuFunctionScenario<In, void> {
+  return hook
 }
 
 /**
@@ -152,6 +236,151 @@ 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
+
+export 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
+}
+
+export type PikkuFunctionScenarioStep<
+  In = unknown,
+  Out = never,
+  B extends boolean = false
+> = PikkuFunctionSessionless<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>
+
+export type PikkuScenarioStepConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  B extends boolean = false
+> = {
+  /** Registered name — this is the string \`scenario.step()\` references. */
+  name: string
+  /**
+   * 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
+  /**
+   * This step drives a browser. The runner provisions one for the step's actor
+   * before calling it — which also makes an actor mandatory — and \`wire.browser\`
+   * is non-optional inside \`func\`.
+   */
+  browser?: B
+  title?: string
+  tags?: string[]
+  input?: InputSchema
+  output?: OutputSchema
+  errors?: Array<typeof PikkuError>
+  func: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    B
+  >
+}
+
+export type PikkuScenarioStepConfig<In, Out, B extends boolean = false> =
+  Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined, B>, 'func' | 'input' | 'output'> & {
+    func: PikkuFunctionScenarioStep<In, Out, B>
+  }
+
+/**
+ * A named, reusable scenario step. Unlike \`scenario.do\`, which can only name an
+ * RPC, a step's body is an ordinary pikku function — so it may drive a browser,
+ * invoke RPCs as its actor, or run a workflow.
+ *
+ * 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,
+  B extends boolean = false
+>(
+  config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema, B>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>, InputSchema, OutputSchema>
+export function pikkuScenarioStep<In, Out = unknown, B extends boolean = false>(
+  config: PikkuScenarioStepConfig<In, Out, B>
+): PikkuFunctionConfig<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>
+export function pikkuScenarioStep(config: any) {
+  return config
+}
+
 type TypedRef<T> = { $ref: string; path?: string } & { __phantomType?: T }
 
 type TemplateString = {

package/dist/src/server/server-ready.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Printed once the server is listening AND the project's `afterStart`
+ * lifecycle has resolved.
+ *
+ * The runtime's own `listening on …` line is emitted inside `server.start()`,
+ * which runs *before* `afterStart` — so anything a project seeds there (users,
+ * scopes, fixtures) is still pending when it appears, and a parent process
+ * that treats it as readiness races the seed. This marker is the point at
+ * which the server is actually usable, and it is what `--spawn` waits for.
+ */
+export declare const SERVER_READY_MARKER = "pikku: ready";
+export declare const serverReadyLine: (hostname: string, port: number) => string;

package/dist/src/server/server-ready.js

@@ -0,0 +1,12 @@
+/**
+ * Printed once the server is listening AND the project's `afterStart`
+ * lifecycle has resolved.
+ *
+ * The runtime's own `listening on …` line is emitted inside `server.start()`,
+ * which runs *before* `afterStart` — so anything a project seeds there (users,
+ * scopes, fixtures) is still pending when it appears, and a parent process
+ * that treats it as readiness races the seed. This marker is the point at
+ * which the server is actually usable, and it is what `--spawn` waits for.
+ */
+export const SERVER_READY_MARKER = 'pikku: ready';
+export const serverReadyLine = (hostname, port) => `${SERVER_READY_MARKER} on http://${hostname}:${port}`;

package/dist/src/server/spawn-dev-server.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Rejects if anything is already listening on `port`.
+ *
+ * A readiness check cannot tell "my server" from "someone else's": both answer
+ * on the same address once spawned, so a stale server left on the target port
+ * silently absorbs a whole run and reports failures that belong to code nobody
+ * is looking at. A TCP-level check before spawning is the only point at which
+ * the two are distinguishable.
+ */
+export declare const assertPortFree: (port: number, host?: string, timeoutMs?: number) => Promise<void>;
+export interface ReadyBarrier {
+    /** Feed a chunk of the child's output. */
+    observe: (text: string) => void;
+    /** Record that the child exited, so the wait fails fast instead of timing out. */
+    markExited: (code: number | null) => void;
+    wait: (options?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }) => Promise<void>;
+}
+/**
+ * Watches a spawned server's output for the ready marker. Separated from the
+ * spawn so the three outcomes that matter — ready, the child died, nothing
+ * happened for long enough — are testable without a real process.
+ */
+export declare const createReadyBarrier: (label: string) => ReadyBarrier;
+export interface SpawnedServer {
+    /** Kills the whole process group, so the server's own children go with it. */
+    stop: () => void;
+    /** Resolves on the ready marker; rejects if the server dies or never reports. */
+    waitUntilReady: (options?: {
+        timeoutMs?: number;
+    }) => Promise<void>;
+}
+export interface SpawnDevServerOptions {
+    cwd: string;
+    port: number;
+    hostname?: string;
+    coverage?: boolean;
+    /** Passed through as `--test`, which sets PIKKU_TEST_RUN for isTestRun(). */
+    test?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** Where the server's own output goes. Defaults to this process's streams. */
+    onOutput?: (text: string) => void;
+}
+/**
+ * Start `pikku dev` as its own process group and stream its output under a
+ * `[server]` prefix. Does not wait — call `waitUntilReady`.
+ */
+export declare const spawnDevServer: (options: SpawnDevServerOptions) => Promise<SpawnedServer>;

package/dist/src/server/spawn-dev-server.js

@@ -0,0 +1,112 @@
+import { spawn } from 'node:child_process';
+import { connect } from 'node:net';
+import { SERVER_READY_MARKER } from './server-ready.js';
+/**
+ * Rejects if anything is already listening on `port`.
+ *
+ * A readiness check cannot tell "my server" from "someone else's": both answer
+ * on the same address once spawned, so a stale server left on the target port
+ * silently absorbs a whole run and reports failures that belong to code nobody
+ * is looking at. A TCP-level check before spawning is the only point at which
+ * the two are distinguishable.
+ */
+export const assertPortFree = (port, host = '127.0.0.1', timeoutMs = 1000) => new Promise((resolve, reject) => {
+    const socket = connect({ port, host });
+    const settle = (error) => {
+        socket.removeAllListeners();
+        socket.destroy();
+        error ? reject(error) : resolve();
+    };
+    socket.setTimeout(timeoutMs);
+    socket.on('connect', () => settle(new Error(`Port ${port} is already in use — something is already listening on ${host}:${port}. ` +
+        `Stop it, or point this environment's apiUrl at a free port.`)));
+    // Nothing listening, or unreachable: either way this process is free to bind.
+    socket.on('error', () => settle());
+    socket.on('timeout', () => settle());
+});
+/**
+ * Watches a spawned server's output for the ready marker. Separated from the
+ * spawn so the three outcomes that matter — ready, the child died, nothing
+ * happened for long enough — are testable without a real process.
+ */
+export const createReadyBarrier = (label) => {
+    let ready = false;
+    let exit;
+    // Stdout arrives in arbitrary chunks, so the marker can straddle two of them.
+    // Keep just enough of the tail to rejoin a split marker.
+    let tail = '';
+    return {
+        observe: (text) => {
+            if (ready)
+                return;
+            const window = tail + text;
+            if (window.includes(SERVER_READY_MARKER)) {
+                ready = true;
+                tail = '';
+                return;
+            }
+            tail = window.slice(-SERVER_READY_MARKER.length);
+        },
+        markExited: (code) => {
+            exit = { code };
+        },
+        wait: async ({ timeoutMs = 120_000, pollMs = 100 } = {}) => {
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                if (ready)
+                    return;
+                if (exit) {
+                    throw new Error(`${label} exited with code ${exit.code} before it was ready`);
+                }
+                await new Promise((r) => setTimeout(r, pollMs));
+            }
+            throw new Error(`${label} did not report ready within ${timeoutMs / 1000} seconds`);
+        },
+    };
+};
+/**
+ * Start `pikku dev` as its own process group and stream its output under a
+ * `[server]` prefix. Does not wait — call `waitUntilReady`.
+ */
+export const spawnDevServer = async (options) => {
+    const { cwd, port, hostname = '127.0.0.1', coverage, test = true, env, onOutput = (text) => process.stdout.write(text), } = options;
+    await assertPortFree(port, hostname);
+    const args = ['pikku', 'dev', '--port', String(port)];
+    if (coverage)
+        args.push('--coverage');
+    if (test)
+        args.push('--test');
+    const child = spawn('npx', args, {
+        cwd,
+        env: { ...process.env, ...env },
+        stdio: 'pipe',
+        detached: true,
+    });
+    const barrier = createReadyBarrier('Server');
+    const forward = (chunk) => {
+        const text = chunk.toString();
+        barrier.observe(text);
+        onOutput(text
+            .split('\n')
+            .map((line) => (line ? `[server] ${line}` : line))
+            .join('\n'));
+    };
+    child.stdout?.on('data', forward);
+    child.stderr?.on('data', forward);
+    child.on('exit', (code) => barrier.markExited(code));
+    return {
+        waitUntilReady: barrier.wait,
+        stop: () => {
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                catch {
+                    // Process group may already be gone
+                }
+            }
+        },
+    };
+};

package/dist/src/services.js

@@ -149,7 +149,14 @@ export const createSingletonServices = async (config) => {
     let unfilteredStateIsSetupOnly = false;
     let inspectedTsGeneration;
     let inspectorInvalidated = false;
-    const getInspectorState = async (refresh = false, setupOnly = false, bootstrapMode = false) => {
+    /**
+     * `unfiltered` is for commands that RUN the project rather than generate from
+     * it. The CLI filters narrow what gets written out, which is meaningless to a
+     * runner and actively wrong for one: `--tags` on `pikku scenario run` selects
+     * which scenarios to run, and if it also narrowed the state the runner would
+     * lose the very step functions it is about to call.
+     */
+    const getInspectorState = async (refresh = false, setupOnly = false, bootstrapMode = false, unfiltered = false) => {
         // In bootstrap mode, return a minimal "zero state" with core types
         // This allows bootstrap to run immediately without inspecting the codebase
         if (bootstrapMode) {
@@ -240,6 +247,7 @@ export const createSingletonServices = async (config) => {
                 rootDir,
                 isAddon: !!config.addon,
                 oldProgram,
+                tsconfig: config.tsconfig,
                 types: {
                     configFileType: config.configFile,
                     userSessionType: config.userSessionType,
@@ -287,6 +295,9 @@ export const createSingletonServices = async (config) => {
                 }
             }
         }
+        if (unfiltered) {
+            return unfilteredState;
+        }
         // Apply filters as a post-processing step
         const filteredState = filterInspectorState(unfilteredState, filters, logger);
         return filteredState;

package/dist/src/utils/meta-diff.js

@@ -19,7 +19,7 @@ const UNWRAP = {
     email: 'templates',
     agent: 'agentsMeta',
 };
-// Workflows (incl. userflows/scenarios) are written one file per workflow under
+// Workflows (incl. scenarios) are written one file per workflow under
 // this dir; the file basename (sans `.gen.json`) is the id, `-verbose` excluded.
 const WORKFLOW_META_DIR = 'workflow/meta';
 function readJson(path) {
@@ -40,7 +40,10 @@ function readSingle(outDir, category, relPath) {
     const unwrapKey = UNWRAP[category];
     if (unwrapKey) {
         const inner = raw[unwrapKey];
-        raw = inner && typeof inner === 'object' && !Array.isArray(inner) ? inner : {};
+        raw =
+            inner && typeof inner === 'object' && !Array.isArray(inner)
+                ? inner
+                : {};
     }
     if (category !== 'http')
         return raw;

package/dist/src/utils/pikku-cli-config.js

@@ -341,6 +341,9 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.workflowMapDeclarationFile) {
             result.workflowMapDeclarationFile = join(workflowDir, 'pikku-workflow-map.gen.d.ts');
         }
+        if (!result.scenarioStepMapDeclarationFile) {
+            result.scenarioStepMapDeclarationFile = join(workflowDir, 'pikku-scenario-step-map.gen.d.ts');
+        }
         if (!result.workflowTypesFile) {
             result.workflowTypesFile = join(workflowDir, 'pikku-workflow-types.gen.ts');
         }
@@ -351,6 +354,29 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.scenarioActorsFile) {
             result.scenarioActorsFile = join(workflowDir, 'pikku-scenario-actors.gen.ts');
         }
+        // Scenarios
+        const scenarioDir = join(result.outDir, 'scenarios');
+        if (!result.scenarioStepsFile) {
+            result.scenarioStepsFile = join(scenarioDir, 'pikku-scenario-functions.gen.ts');
+        }
+        if (!result.scenarioStepsMetaFile) {
+            result.scenarioStepsMetaFile = join(scenarioDir, 'pikku-scenario-functions-meta.gen.ts');
+        }
+        if (!result.scenarioStepsMetaJsonFile) {
+            result.scenarioStepsMetaJsonFile = join(scenarioDir, 'pikku-scenario-functions-meta.gen.json');
+        }
+        if (!result.scenarioWiringsFile) {
+            result.scenarioWiringsFile = join(scenarioDir, 'pikku-scenario-wirings.gen.ts');
+        }
+        if (!result.scenarioWiringsMetaFile) {
+            result.scenarioWiringsMetaFile = join(scenarioDir, 'pikku-scenario-wirings-meta.gen.ts');
+        }
+        if (!result.scenarioMetaDir) {
+            result.scenarioMetaDir = join(scenarioDir, 'meta');
+        }
+        if (!result.scenarioBootstrapFile) {
+            result.scenarioBootstrapFile = join(result.outDir, 'pikku-bootstrap-scenarios.gen.ts');
+        }
         // Services
         if (!result.servicesFile) {
             result.servicesFile = join(result.outDir, 'pikku-services.gen.ts');

package/dist/src/utils/resolve-scenario-actors.d.ts

@@ -0,0 +1,23 @@
+import type { PikkuCLIConfig } from '../../types/config.js';
+type ScenariosConfig = NonNullable<PikkuCLIConfig['scenarios']>;
+type ActorsConfig = NonNullable<ScenariosConfig['actors']>;
+type ActorConfig = ActorsConfig[string];
+/**
+ * The actor registry a run actually sees: every declared actor, plus one
+ * materialised actor for each persona nobody declared an actor for.
+ *
+ * A persona is the KIND of person (its `description`); an actor is one BODY
+ * that signs in, with an email of its own. Most apps want exactly one body per
+ * kind, so declaring the persona is enough — this fills in the actor. You only
+ * write an actor by hand when a scenario needs TWO of the same kind, which is
+ * what tenant-isolation and peer-sharing scenarios are made of.
+ *
+ * Every consumer must resolve through here rather than reading
+ * `config.scenarios.actors` directly: codegen emits `scenarioActorConfigs` from
+ * it (and `ScenarioActorName` is a `keyof` over that literal, so an actor missing
+ * at codegen time can never be referenced in a typed step), while `scenario run`
+ * builds the HTTP and Playwright actor maps from it. Those were already three
+ * separate reads of the same field before personas existed.
+ */
+export declare const resolveScenarioActors: (scenarios: ScenariosConfig | undefined) => ActorsConfig;
+export type { ActorConfig as ResolvedScenarioActorConfig };