@pikku/cli 0.12.89 → 0.12.91

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

@@ -4,19 +4,22 @@ import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-
 import { serializeFunctionImports } from './serialize-function-imports.js';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { stripVerboseFields, hasVerboseFields, reattachFunctionServices, } from '../../../utils/strip-verbose-meta.js';
+import { partitionScenarioFunctions, partitionScenarioFunctionsMeta, } from '../scenarios/scenario-partition.js';
+import { serializeScenarioFunctionMeta } from '../scenarios/serialize-scenario-meta.js';
 export const pikkuFunctions = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const { functions, rpc } = await getInspectorState();
-        const { functionsMetaFile, functionsMetaJsonFile, functionsFile, packageMappings, schema, } = config;
-        let minimalMeta = stripVerboseFields(functions.meta);
+        const { functionsMetaFile, functionsMetaJsonFile, functionsFile, scenarioStepsFile, scenarioStepsMetaFile, scenarioStepsMetaJsonFile, packageMappings, schema, } = config;
+        const { app: appFunctionsMeta, scenario: scenarioFunctionsMeta } = partitionScenarioFunctionsMeta(functions.meta);
+        let minimalMeta = stripVerboseFields(appFunctionsMeta);
         if (config.addonName) {
-            minimalMeta = reattachFunctionServices(minimalMeta, functions.meta);
+            minimalMeta = reattachFunctionServices(minimalMeta, appFunctionsMeta);
         }
         await writeFileInDir(logger, functionsMetaJsonFile, JSON.stringify(minimalMeta, null, 2));
         // Write verbose JSON only if it has additional fields
-        if (hasVerboseFields(functions.meta)) {
+        if (hasVerboseFields(appFunctionsMeta)) {
             const verbosePath = functionsMetaJsonFile.replace(/\.gen\.json$/, '-verbose.gen.json');
-            await writeFileInDir(logger, verbosePath, JSON.stringify(functions.meta, null, 2));
+            await writeFileInDir(logger, verbosePath, JSON.stringify(appFunctionsMeta, null, 2));
         }
         const jsonImportPath = getFileImportRelativePath(functionsMetaFile, functionsMetaJsonFile, packageMappings);
         const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
@@ -31,11 +34,26 @@ export const pikkuFunctions = pikkuSessionlessFunc({
         const hasRPCs = rpc.exposedFiles.size > 0 || rpc.internalFiles.size > 0;
         const hasFunctions = functions.files.size > 0;
         const shouldGenerateFunctionsFile = isAddon ? hasFunctions : hasRPCs;
+        // For addon packages, use all function files; for main packages, use internal RPC files
+        const filesToRegister = isAddon ? functions.files : rpc.internalFiles;
+        const { app: appFiles, scenario: scenarioFiles } = partitionScenarioFunctions(filesToRegister, functions.meta);
         if (shouldGenerateFunctionsFile) {
-            // For addon packages, use all function files; for main packages, use internal RPC files
-            const filesToRegister = isAddon ? functions.files : rpc.internalFiles;
-            await writeFileInDir(logger, functionsFile, serializeFunctionImports(functionsFile, filesToRegister, functions.meta, packageMappings, config.addonName));
+            await writeFileInDir(logger, functionsFile, serializeFunctionImports(functionsFile, appFiles, appFunctionsMeta, packageMappings, config.addonName));
         }
+        // Always written, even when empty: a project that deletes its last scenario
+        // must stop registering the one it had, and the scenario bootstrap imports
+        // these unconditionally.
+        await writeFileInDir(logger, scenarioStepsMetaJsonFile, JSON.stringify(stripVerboseFields(scenarioFunctionsMeta), null, 2));
+        // The bootstrap imports the stripped copy; the verbose one is read off disk
+        // by whatever documents a scenario — the console needs `sourceFile` and
+        // `exportedName` to show the code a step runs.
+        if (hasVerboseFields(scenarioFunctionsMeta)) {
+            await writeFileInDir(logger, scenarioStepsMetaJsonFile.replace(/\.gen\.json$/, '-verbose.gen.json'), JSON.stringify(scenarioFunctionsMeta, null, 2));
+        }
+        await writeFileInDir(logger, scenarioStepsMetaFile, serializeScenarioFunctionMeta(getFileImportRelativePath(scenarioStepsMetaFile, scenarioStepsMetaJsonFile, packageMappings), getFileImportRelativePath(scenarioStepsMetaFile, functionsMetaFile, packageMappings), supportsImportAttributes, config.addonName));
+        await writeFileInDir(logger, scenarioStepsFile, scenarioFiles.size === 0
+            ? 'export {}'
+            : serializeFunctionImports(scenarioStepsFile, scenarioFiles, scenarioFunctionsMeta, packageMappings, config.addonName));
         return shouldGenerateFunctionsFile;
     },
     middleware: [

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

@@ -7,7 +7,7 @@ export const serializeFunctionTypes = (userSessionTypeImport, userSessionTypeNam
         ? nodeCategories.map((c) => `'${c}'`).join(' | ')
         : 'string';
     const workflowImport = workflowTypesImport ||
-        `import type { TypedWorkflow, TypedScenario } from '../workflow/pikku-workflow-types.gen.js'`;
+        `import type { TypedWorkflow, TypedScenario, TypedScenarioActors } from '../workflow/pikku-workflow-types.gen.js'`;
     // Falls back to `string` when a project has no scopes codegen, so that
     // `scopes` stays usable rather than resolving to an unbound type name.
     const scopesImport = scopesTypeImport || `type ScopeId = string`;
@@ -299,7 +299,7 @@ export type PikkuFunctionSessionless<
     Out,
     RequiredServices,
     Session,
-    PickRequired<PikkuWire<In, Out, false, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario>, RequiredWires>
+    PickRequired<PikkuWire<In, Out, false, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario, TypedScenarioActors>, RequiredWires>
   >
 
 /**
@@ -320,7 +320,7 @@ export type PikkuFunction<
     Out,
     RequiredServices,
     Session,
-    PickRequired<PikkuWire<In, Out, true, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario>, RequiredWires>
+    PickRequired<PikkuWire<In, Out, true, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario, TypedScenarioActors>, RequiredWires>
   >
 
 /**

package/dist/src/functions/wirings/scenarios/scenario-partition.d.ts

@@ -0,0 +1,29 @@
+import type { FunctionsMeta } from '@pikku/core';
+import type { SerializedWorkflowGraphs } from '@pikku/inspector/workflow-graph';
+export type WiringFileMap = Map<string, {
+    path: string;
+    exportedName: string;
+}>;
+/**
+ * Scenario steps and scenarios are ordinary pikku functions and workflows, so
+ * without a split they register into the same bootstrap a deployed server
+ * imports — dragging every step body (and whatever it imports: Playwright, test
+ * fixtures, assertion helpers) into production. These partitions are what keep
+ * them in `.pikku/scenarios/`, reachable only from `pikku scenario run`.
+ */
+export declare const isScenarioStep: (meta: FunctionsMeta[string] | undefined) => boolean;
+export declare const partitionScenarioFunctions: (files: WiringFileMap, functionsMeta: FunctionsMeta) => {
+    app: WiringFileMap;
+    scenario: WiringFileMap;
+};
+export declare const partitionScenarioFunctionsMeta: (functionsMeta: FunctionsMeta) => {
+    app: FunctionsMeta;
+    scenario: FunctionsMeta;
+};
+export declare const isScenarioWorkflow: (graphMeta: SerializedWorkflowGraphs, name: string) => boolean;
+export declare const partitionScenarioWorkflows: (workflowNames: string[], workflowFiles: WiringFileMap, graphMeta: SerializedWorkflowGraphs) => {
+    appNames: string[];
+    scenarioNames: string[];
+    appFiles: WiringFileMap;
+    scenarioFiles: WiringFileMap;
+};

package/dist/src/functions/wirings/scenarios/scenario-partition.js

@@ -0,0 +1,58 @@
+/**
+ * Scenario steps and scenarios are ordinary pikku functions and workflows, so
+ * without a split they register into the same bootstrap a deployed server
+ * imports — dragging every step body (and whatever it imports: Playwright, test
+ * fixtures, assertion helpers) into production. These partitions are what keep
+ * them in `.pikku/scenarios/`, reachable only from `pikku scenario run`.
+ */
+export const isScenarioStep = (meta) => meta?.scenarioStep === true;
+export const partitionScenarioFunctions = (files, functionsMeta) => {
+    const app = new Map();
+    const scenario = new Map();
+    for (const [name, entry] of files) {
+        if (isScenarioStep(functionsMeta[name])) {
+            scenario.set(name, entry);
+        }
+        else {
+            app.set(name, entry);
+        }
+    }
+    return { app, scenario };
+};
+export const partitionScenarioFunctionsMeta = (functionsMeta) => {
+    const app = {};
+    const scenario = {};
+    for (const [name, meta] of Object.entries(functionsMeta)) {
+        if (isScenarioStep(meta)) {
+            scenario[name] = meta;
+        }
+        else {
+            app[name] = meta;
+        }
+    }
+    return { app, scenario };
+};
+export const isScenarioWorkflow = (graphMeta, name) => graphMeta[name]?.source === 'scenario';
+export const partitionScenarioWorkflows = (workflowNames, workflowFiles, graphMeta) => {
+    const appNames = [];
+    const scenarioNames = [];
+    for (const name of workflowNames) {
+        if (isScenarioWorkflow(graphMeta, name)) {
+            scenarioNames.push(name);
+        }
+        else {
+            appNames.push(name);
+        }
+    }
+    const appFiles = new Map();
+    const scenarioFiles = new Map();
+    for (const [name, entry] of workflowFiles) {
+        if (isScenarioWorkflow(graphMeta, name)) {
+            scenarioFiles.set(name, entry);
+        }
+        else {
+            appFiles.set(name, entry);
+        }
+    }
+    return { appNames, scenarioNames, appFiles, scenarioFiles };
+};

package/dist/src/functions/wirings/scenarios/serialize-feature-meta.d.ts

@@ -0,0 +1,14 @@
+import type { FeaturesMeta } from '@pikku/core/workflow/types';
+import type { InspectorFeature } from '@pikku/inspector';
+/**
+ * The feature meta the console reads, built from what the inspector could read
+ * off the source.
+ *
+ * Entry order is the declared order and is deliberately not sorted — a
+ * feature's scenarios read top to bottom the way they were written, the same
+ * way a gherkin Feature file does.
+ *
+ * The source path is dropped: it is absolute to the machine that generated the
+ * meta, and nothing rendering a feature needs it.
+ */
+export declare const buildFeaturesMeta: (featureFiles: Map<string, InspectorFeature>) => FeaturesMeta;

package/dist/src/functions/wirings/scenarios/serialize-feature-meta.js

@@ -0,0 +1,29 @@
+/**
+ * The feature meta the console reads, built from what the inspector could read
+ * off the source.
+ *
+ * Entry order is the declared order and is deliberately not sorted — a
+ * feature's scenarios read top to bottom the way they were written, the same
+ * way a gherkin Feature file does.
+ *
+ * The source path is dropped: it is absolute to the machine that generated the
+ * meta, and nothing rendering a feature needs it.
+ */
+export const buildFeaturesMeta = (featureFiles) => {
+    const meta = {};
+    for (const [id, feature] of featureFiles) {
+        meta[id] = {
+            id,
+            name: feature.name ?? id,
+            ...(feature.description ? { description: feature.description } : {}),
+            tags: feature.tags ?? [],
+            entries: feature.entries.map((entry) => entry.data === undefined
+                ? { scenario: entry.scenario }
+                : { scenario: entry.scenario, data: entry.data }),
+            unresolvedEntries: feature.unresolvedEntries,
+            hasBefore: feature.hasBefore,
+            hasAfter: feature.hasAfter,
+        };
+    }
+    return meta;
+};

package/dist/src/functions/wirings/scenarios/serialize-scenario-meta.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Scenario workflow meta, merged onto whatever the app registered rather than
+ * replacing it — `pikkuState(…, 'workflows', 'meta', value)` is a wholesale
+ * setter, and the app's own meta file is one. The app file is imported here so
+ * the ordering holds however this module is reached, not only through the
+ * generated scenario bootstrap.
+ */
+export declare const serializeScenarioWorkflowMeta: (outputPath: string, metaDir: string, appMetaImportPath: string, scenarioNames: string[], packageMappings: Record<string, string>, supportsImportAttributes: boolean, packageName?: string) => string;
+/**
+ * Scenario step meta, merged onto the app's function meta for the same reason.
+ */
+export declare const serializeScenarioFunctionMeta: (jsonImportPath: string, appMetaImportPath: string, supportsImportAttributes: boolean, packageName?: string) => string;

package/dist/src/functions/wirings/scenarios/serialize-scenario-meta.js

@@ -0,0 +1,56 @@
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { sanitizeTypeName } from '@pikku/inspector';
+/**
+ * Scenario workflow meta, merged onto whatever the app registered rather than
+ * replacing it — `pikkuState(…, 'workflows', 'meta', value)` is a wholesale
+ * setter, and the app's own meta file is one. The app file is imported here so
+ * the ordering holds however this module is reached, not only through the
+ * generated scenario bootstrap.
+ */
+export const serializeScenarioWorkflowMeta = (outputPath, metaDir, appMetaImportPath, scenarioNames, packageMappings, supportsImportAttributes, packageName) => {
+    const pkg = packageName ? `'${packageName}'` : 'null';
+    const sortedNames = [...scenarioNames].sort();
+    const imports = sortedNames
+        .map((name) => {
+        const sanitizedIdentifier = sanitizeTypeName(name);
+        const jsonPath = `${metaDir}/${name}.gen.json`;
+        const importPath = getFileImportRelativePath(outputPath, jsonPath, packageMappings);
+        return supportsImportAttributes
+            ? `import ${sanitizedIdentifier}Meta from '${importPath}' with { type: 'json' }`
+            : `import ${sanitizedIdentifier}Meta from '${importPath}'`;
+    })
+        .join('\n');
+    const metaEntries = sortedNames
+        .map((name) => `  '${name}': ${sanitizeTypeName(name)}Meta,`)
+        .join('\n');
+    return `import { pikkuState } from '@pikku/core/internal'
+import type { WorkflowsRuntimeMeta } from '@pikku/core/workflow/types'
+import '${appMetaImportPath}'
+${imports ? `\n${imports}\n` : ''}
+const scenariosMeta = {
+${metaEntries}
+} as WorkflowsRuntimeMeta
+
+pikkuState(${pkg}, 'workflows', 'meta', {
+  ...pikkuState(${pkg}, 'workflows', 'meta'),
+  ...scenariosMeta,
+})`;
+};
+/**
+ * Scenario step meta, merged onto the app's function meta for the same reason.
+ */
+export const serializeScenarioFunctionMeta = (jsonImportPath, appMetaImportPath, supportsImportAttributes, packageName) => {
+    const pkg = packageName ? `'${packageName}'` : 'null';
+    const importStatement = supportsImportAttributes
+        ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
+        : `import metaData from '${jsonImportPath}'`;
+    return `import { pikkuState } from '@pikku/core/internal'
+import type { FunctionsMeta } from '@pikku/core'
+import '${appMetaImportPath}'
+${importStatement}
+
+pikkuState(${pkg}, 'function', 'meta', {
+  ...pikkuState(${pkg}, 'function', 'meta'),
+  ...(metaData as FunctionsMeta),
+})`;
+};

package/dist/src/functions/wirings/scenarios/serialize-scenario-registration.d.ts

@@ -0,0 +1,7 @@
+import type { WiringFileMap } from './scenario-partition.js';
+/**
+ * The scenario counterpart of `serializeWorkflowRegistration`: registers the
+ * scenarios and features that were held back from the app wirings, so they
+ * exist only in the module graph `pikku scenario run` loads.
+ */
+export declare const serializeScenarioRegistration: (outputPath: string, metaImportPath: string, scenarioFiles: WiringFileMap, featureFiles: WiringFileMap, packageMappings: Record<string, string>, packageName?: string) => string;

package/dist/src/functions/wirings/scenarios/serialize-scenario-registration.js

@@ -0,0 +1,40 @@
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+/**
+ * The scenario counterpart of `serializeWorkflowRegistration`: registers the
+ * scenarios and features that were held back from the app wirings, so they
+ * exist only in the module graph `pikku scenario run` loads.
+ */
+export const serializeScenarioRegistration = (outputPath, metaImportPath, scenarioFiles, featureFiles, packageMappings, packageName) => {
+    const hasScenarios = scenarioFiles.size > 0;
+    const hasFeatures = featureFiles.size > 0;
+    if (!hasScenarios && !hasFeatures) {
+        return 'export {}';
+    }
+    const lines = [];
+    const registrars = [
+        ...(hasScenarios ? ['addWorkflow'] : []),
+        ...(hasFeatures ? ['addFeature'] : []),
+    ];
+    lines.push(`import { ${registrars.join(', ')} } from '@pikku/core/workflow'`);
+    lines.push(`import '${metaImportPath}'`);
+    const sortedScenarios = Array.from(scenarioFiles.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+    // A feature holds the very objects its scenarios were registered with, so it
+    // has to be imported for its membership to be resolvable at all.
+    const sortedFeatures = Array.from(featureFiles.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [, { path, exportedName }] of [
+        ...sortedScenarios,
+        ...sortedFeatures,
+    ]) {
+        const importPath = getFileImportRelativePath(outputPath, path, packageMappings);
+        lines.push(`import { ${exportedName} } from '${importPath}'`);
+    }
+    lines.push('');
+    const packageArg = packageName ? `, '${packageName}'` : '';
+    for (const [pikkuFuncId, { exportedName }] of sortedScenarios) {
+        lines.push(`addWorkflow('${pikkuFuncId}', ${exportedName}${packageArg})`);
+    }
+    for (const [featureId, { exportedName }] of sortedFeatures) {
+        lines.push(`addFeature('${featureId}', ${exportedName}${packageArg})`);
+    }
+    return lines.join('\n');
+};

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

@@ -4,13 +4,20 @@ 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 { serializeScenarioActors } from './serialize-scenario-actors.js';
+import { resolveScenarioActors } from '../../../utils/resolve-scenario-actors.js';
 import { serializeWorkflowRegistration } from './serialize-workflow-registration.js';
 import { serializeWorkflowMap } from './serialize-workflow-map.js';
+import { serializeScenarioStepMap } from './serialize-scenario-step-map.js';
 import { serializeWorkflowBootstrapMap } from './serialize-workflow-bootstrap-map.js';
 import { serializeWorkflowMeta } from './serialize-workflow-meta.js';
+import { partitionScenarioWorkflows } from '../scenarios/scenario-partition.js';
+import { serializeScenarioRegistration } from '../scenarios/serialize-scenario-registration.js';
+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 { rm } from 'fs/promises';
 export const pikkuWorkflow = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }, input) => {
         const bootstrap = input?.bootstrap === true;
@@ -28,6 +35,11 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
         ];
         const hasRelevantWorkflows = allWorkflowNames.length > 0;
         const hasWorkflows = hasRelevantWorkflows;
+        // Scenarios and features are held back from every app-facing artifact: they
+        // are only ever run by `pikku scenario run`, and registering them in the app
+        // bootstrap drags each scenario's steps — and whatever those import — into a
+        // deployed server.
+        const { appNames, scenarioNames, appFiles, scenarioFiles } = partitionScenarioWorkflows(allWorkflowNames, workflows.files, workflows.graphMeta);
         if (hasWorkflows) {
             const singletonServices = visitState.serviceAggregation.allSingletonServices.length > 0
                 ? visitState.serviceAggregation.allSingletonServices
@@ -44,35 +56,58 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
             }
         }
         if (hasWorkflows && workflowMetaDir) {
+            const scenarioNameSet = new Set(scenarioNames);
             for (const [name, graphMeta] of Object.entries(workflows.graphMeta)) {
+                const metaDir = scenarioNameSet.has(name)
+                    ? config.scenarioMetaDir
+                    : workflowMetaDir;
                 const minimalMeta = stripVerboseFields(graphMeta);
-                const minimalPath = join(workflowMetaDir, `${name}.gen.json`);
+                const minimalPath = join(metaDir, `${name}.gen.json`);
                 await writeFileInDir(logger, minimalPath, JSON.stringify(minimalMeta, null, 2), { ignoreModifyComment: true });
                 if (hasVerboseFields(graphMeta)) {
-                    const verbosePath = join(workflowMetaDir, `${name}-verbose.gen.json`);
+                    const verbosePath = join(metaDir, `${name}-verbose.gen.json`);
                     await writeFileInDir(logger, verbosePath, JSON.stringify(graphMeta, null, 2), { ignoreModifyComment: true });
                 }
             }
         }
+        // A project generated before scenarios moved out has their meta sitting in
+        // workflow/meta, and getWorkflowMeta() reads both directories — leaving it
+        // there would serve a stale copy of every scenario forever.
+        if (workflowMetaDir) {
+            await Promise.all(scenarioNames.flatMap((name) => [`${name}.gen.json`, `${name}-verbose.gen.json`].map((file) => rm(join(workflowMetaDir, file), { force: true }))));
+        }
         if (workflowsWiringMetaFile && workflowMetaDir) {
-            await writeFileInDir(logger, workflowsWiringMetaFile, serializeWorkflowMeta(workflowsWiringMetaFile, workflowMetaDir, allWorkflowNames, packageMappings, schema?.supportsImportAttributes ?? false, config.addonName));
+            await writeFileInDir(logger, workflowsWiringMetaFile, serializeWorkflowMeta(workflowsWiringMetaFile, workflowMetaDir, appNames, packageMappings, schema?.supportsImportAttributes ?? false, config.addonName));
         }
+        await writeFileInDir(logger, config.scenarioWiringsMetaFile, serializeScenarioWorkflowMeta(config.scenarioWiringsMetaFile, config.scenarioMetaDir, getFileImportRelativePath(config.scenarioWiringsMetaFile, workflowsWiringMetaFile, packageMappings), scenarioNames, packageMappings, schema?.supportsImportAttributes ?? false, config.addonName));
+        await writeFileInDir(logger, config.scenarioWiringsFile, serializeScenarioRegistration(config.scenarioWiringsFile, getFileImportRelativePath(config.scenarioWiringsFile, config.scenarioWiringsMetaFile, packageMappings), scenarioFiles, workflows.featureFiles, packageMappings, config.addonName));
         const metaImportPath = getFileImportRelativePath(workflowsWiringFile, workflowsWiringMetaFile, packageMappings);
-        await writeFileInDir(logger, workflowsWiringFile, serializeWorkflowRegistration(workflowsWiringFile, metaImportPath, allWorkflowNames, workflows.files, workflows.graphFiles, packageMappings, config.addonName));
+        await writeFileInDir(logger, workflowsWiringFile, serializeWorkflowRegistration(workflowsWiringFile, metaImportPath, appNames, appFiles, workflows.graphFiles, packageMappings, config.addonName));
         const functionTypesImportPath = getFileImportRelativePath(workflowTypesFile, functionTypesFile, packageMappings);
         const rpcMapImportPath = getFileImportRelativePath(workflowTypesFile, config.rpcInternalMapDeclarationFile, packageMappings);
         const workflowMapImportPath = getFileImportRelativePath(workflowTypesFile, workflowMapDeclarationFile, packageMappings);
         const agentMapImportPath = getFileImportRelativePath(workflowTypesFile, config.agentMapDeclarationFile, packageMappings);
         const scopesImportPath = getFileImportRelativePath(workflowTypesFile, config.scopesFile, packageMappings);
-        await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath));
-        const scenarioActors = config.scenarios?.actors;
-        if (scenarioActors && Object.keys(scenarioActors).length > 0) {
+        const scenarioStepMapImportPath = getFileImportRelativePath(workflowTypesFile, config.scenarioStepMapDeclarationFile, packageMappings);
+        const scenarioActorsImportPath = getFileImportRelativePath(workflowTypesFile, config.scenarioActorsFile, packageMappings);
+        await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath, scenarioActorsImportPath));
+        // 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));
+        // Written even for an empty registry, so `TypedScenarioActors` is always a
+        // resolvable import for the generated function types.
+        const scenarioActors = resolveScenarioActors(config.scenarios);
+        {
             const agentMapImportPath = getFileImportRelativePath(config.scenarioActorsFile, config.agentMapDeclarationFile, packageMappings);
-            await writeFileInDir(logger, config.scenarioActorsFile, serializeScenarioActors(scenarioActors, agentMapImportPath));
+            const exposedRpcMapImportPath = getFileImportRelativePath(config.scenarioActorsFile, config.rpcMapDeclarationFile, packageMappings);
+            await writeFileInDir(logger, config.scenarioActorsFile, serializeScenarioActors(scenarioActors, agentMapImportPath, exposedRpcMapImportPath));
             // Fixed path getScenarioActorsMeta() reads; kept out of workflow/meta,
             // which getWorkflowMeta() globs as workflows.
             await writeFileInDir(logger, join(config.outDir, 'workflow', 'scenario-actors.gen.json'), JSON.stringify(scenarioActors, null, 2));
         }
+        // Fixed path getFeaturesMeta() reads. Written even when empty so the
+        // console can tell "no features declared" from "meta not generated yet".
+        await writeFileInDir(logger, join(config.outDir, 'scenarios', 'features.gen.json'), JSON.stringify(buildFeaturesMeta(workflows.featureFiles), null, 2));
         await writeFileInDir(logger, workflowMapDeclarationFile, bootstrap
             ? serializeWorkflowBootstrapMap(workflows.meta, workflows.graphMeta)
             : serializeWorkflowMap(logger, workflowMapDeclarationFile, packageMappings, typesMap, functionState.meta, workflows.meta, workflows.graphMeta, visitState.rpc?.wireAddonDeclarations));

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

@@ -1,2 +1,2 @@
 import type { PikkuCLIConfig } from '../../../../types/config.js';
-export declare const serializeScenarioActors: (actors: NonNullable<NonNullable<PikkuCLIConfig["scenarios"]>["actors"]>, agentMapImportPath: string) => string;
+export declare const serializeScenarioActors: (actors: NonNullable<NonNullable<PikkuCLIConfig["scenarios"]>["actors"]>, agentMapImportPath: string, rpcMapImportPath: string) => string;

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

@@ -1,4 +1,4 @@
-export const serializeScenarioActors = (actors, agentMapImportPath) => {
+export const serializeScenarioActors = (actors, agentMapImportPath, rpcMapImportPath) => {
     return `/** Scenario actors declared in pikku.config.json (\`scenarios.actors\`) */
 import {
   createHttpScenarioActors,
@@ -7,15 +7,26 @@ import {
   type ScenarioActorConfig,
 } from '@pikku/core/services'
 import type { AgentMap } from '${agentMapImportPath}'
+import type { FlattenedRPCMap } from '${rpcMapImportPath}'
 
 export const scenarioActorConfigs = ${JSON.stringify(actors, null, 2)} as const satisfies Record<string, ScenarioActorConfig>
 
 export type ScenarioActorName = keyof typeof scenarioActorConfigs
 
+/**
+ * The same registry as a list, widened to \`ScenarioActorConfig\`. Iterating
+ * \`scenarioActorConfigs\` directly yields the literal type of each entry, on
+ * which an optional field an actor did not declare does not exist — so a seed
+ * reading \`scopes\`/\`roles\` off every actor needs this instead.
+ */
+export const scenarioActorList: ScenarioActorConfig[] = Object.values(
+  scenarioActorConfigs
+)
+
 export type AgentName = keyof AgentMap & string
 export type TypedScenarioActors = Record<
   ScenarioActorName,
-  ScenarioActor<AgentName>
+  ScenarioActor<AgentName, FlattenedRPCMap>
 >
 
 export const createScenarioActors = (

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

@@ -0,0 +1,4 @@
+import { type TypesMap } from '@pikku/inspector';
+import type { FunctionsMeta } from '@pikku/core';
+import type { 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-step-map.js

@@ -0,0 +1,62 @@
+/**
+ * Generate the scenario step map: the typed set of names a scenario may pass to
+ * `scenario.step/given/when/then`.
+ *
+ * Steps are referenced by string, exactly like `workflow.do` references an RPC,
+ * so type safety has to come from a generated map rather than from importing
+ * the step's const. This is what makes `scenario.given('…', 'buysAnApple', …)`
+ * autocomplete and type-check its data.
+ */
+import { serializeImportMap } from '../../../utils/serialize-import-map.js';
+import { generateCustomTypes } from '@pikku/inspector';
+const SCENARIO_STEP_WRAPPER = 'pikkuScenarioStep';
+export const serializeScenarioStepMap = (logger, relativeToPath, packageMappings, typesMap, functionsMeta) => {
+    const requiredTypes = new Set();
+    const steps = Object.entries(functionsMeta).filter(([, meta]) => meta.funcWrapper === SCENARIO_STEP_WRAPPER);
+    const resolveType = (name) => {
+        if (!name) {
+            return 'void';
+        }
+        try {
+            return typesMap.getTypeMeta(name).uniqueName;
+        }
+        catch {
+            return name;
+        }
+    };
+    let stepsStr = 'export type FlattenedScenarioStepMap = {\n';
+    for (const [stepName, meta] of steps) {
+        const inputType = resolveType(meta.inputs?.[0]);
+        const outputType = resolveType(meta.outputs?.[0]);
+        requiredTypes.add(inputType);
+        requiredTypes.add(outputType);
+        stepsStr += `  readonly '${stepName}': ScenarioStepHandler<${inputType}, ${outputType}>,\n`;
+    }
+    stepsStr += '};';
+    const hasAny = steps.length > 0;
+    const serializedCustomTypes = hasAny
+        ? generateCustomTypes(typesMap, requiredTypes)
+        : '';
+    const serializedImportMap = hasAny
+        ? serializeImportMap(logger, relativeToPath, packageMappings, typesMap, requiredTypes)
+        : '';
+    const serializedCustomTypesDeclarationsOnly = serializedCustomTypes
+        .split('\n')
+        .filter((line) => !line.startsWith('import '))
+        .join('\n');
+    return `/**
+ * Scenario step map: the names \`scenario.step/given/when/then\` accepts, with
+ * the input and output types of each step.
+ */
+
+${serializedImportMap}
+${serializedCustomTypesDeclarationsOnly}
+
+interface ScenarioStepHandler<I, O> {
+    input: I;
+    output: O;
+}
+
+${stepsStr}
+`;
+};

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

@@ -1,16 +1,23 @@
+/**
+ * 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,
+ * escaped TypeScript string literal; interpolating the raw name into a quoted
+ * key terminates the string and the whole `.d.ts` stops parsing.
+ */
+const key = (name) => JSON.stringify(name);
 export const serializeWorkflowBootstrapMap = (workflowsMeta, graphMeta) => {
     const workflowEntries = Object.keys(workflowsMeta)
         .sort()
-        .map((workflowName) => `  readonly '${workflowName}': WorkflowHandler<unknown, unknown>,`)
+        .map((workflowName) => `  readonly ${key(workflowName)}: WorkflowHandler<unknown, unknown>,`)
         .join('\n');
     const graphEntries = Object.entries(graphMeta)
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([graphName, graph]) => {
         const nodeEntries = Object.keys(graph.nodes)
             .sort()
-            .map((nodeId) => `    readonly '${nodeId}': GraphNodeHandler<unknown>,`)
+            .map((nodeId) => `    readonly ${key(nodeId)}: GraphNodeHandler<unknown>,`)
             .join('\n');
-        return `  readonly '${graphName}': {\n${nodeEntries}\n  },`;
+        return `  readonly ${key(graphName)}: {\n${nodeEntries}\n  },`;
     })
         .join('\n');
     return `/**

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

@@ -1,6 +1,13 @@
 import { serializeImportMap } from '../../../utils/serialize-import-map.js';
 import { generateCustomTypes } from '@pikku/inspector';
 import { parseVersionedId } from '@pikku/core';
+/**
+ * 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,
+ * escaped TypeScript string literal; interpolating the raw name into a quoted
+ * key terminates the string and the whole `.d.ts` stops parsing.
+ */
+const key = (name) => JSON.stringify(name);
 export const serializeWorkflowMap = (logger, relativeToPath, packageMappings, typesMap, functionsMeta, workflowsMeta, graphMeta, wireAddonDeclarations) => {
     const requiredTypes = new Set();
     const serializedWorkflows = generateWorkflows(workflowsMeta, functionsMeta, typesMap, requiredTypes);
@@ -84,7 +91,7 @@ function generateWorkflows(workflowsMeta, functionsMeta, typesMap, requiredTypes
     }
     let workflowsStr = 'export type WorkflowMap = {\n';
     for (const [workflowName, handler] of Object.entries(workflowsObj)) {
-        workflowsStr += `  readonly '${workflowName}': WorkflowHandler<${handler.inputType}, ${handler.outputType}>,\n`;
+        workflowsStr += `  readonly ${key(workflowName)}: WorkflowHandler<${handler.inputType}, ${handler.outputType}>,\n`;
     }
     workflowsStr += '};';
     return workflowsStr;
@@ -121,9 +128,9 @@ function generateGraphs(graphMeta, functionsMeta, typesMap, requiredTypes) {
     }
     let graphsStr = 'export type GraphsMap = {\n';
     for (const [graphName, nodes] of Object.entries(graphsObj)) {
-        graphsStr += `  readonly '${graphName}': {\n`;
+        graphsStr += `  readonly ${key(graphName)}: {\n`;
         for (const [nodeId, handler] of Object.entries(nodes)) {
-            graphsStr += `    readonly '${nodeId}': GraphNodeHandler<${handler.inputType}>,\n`;
+            graphsStr += `    readonly ${key(nodeId)}: GraphNodeHandler<${handler.inputType}>,\n`;
         }
         graphsStr += '  },\n';
     }