@pikku/inspector 0.12.47 → 0.12.49

package/dist/add/add-functions.js

@@ -11,6 +11,7 @@ import { resolvePermissions } from '../utils/permissions.js';
 import { extractWireNames } from '../utils/post-process.js';
 import { ErrorCode } from '../error-codes.js';
 import { findPiiPaths } from '../utils/check-pii-output.js';
+import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js';
 const isValidVariableName = (name) => {
     const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
     return regex.test(name);
@@ -273,12 +274,22 @@ export const addFunctions = (logger, node, checker, state, options) => {
         return;
     }
     // Match identifiers that contain both "pikku" and "func" (case insensitive),
-    // plus pikkuScenario (a workflow wrapper without "func" in its name)
+    // plus pikkuScenario and pikkuScenarioStep (workflow wrappers without "func"
+    // in their names)
     const pikkuFuncPattern = /pikku.*func/i;
     if (!pikkuFuncPattern.test(expression.text) &&
-        expression.text !== 'pikkuScenario') {
+        expression.text !== 'pikkuScenario' &&
+        expression.text !== 'pikkuScenarioStep') {
         return;
     }
+    // A scenario step is bundled like any invoked function, but is deliberately
+    // never RPC-registered: a step may drive a browser, so exposing it over the
+    // network would put a test harness on the public API surface.
+    const isScenarioStep = expression.text === 'pikkuScenarioStep';
+    // A scenario's own body. Marked so the codegen partitions and the deploy
+    // analyzer can tell it apart from an application workflow without having to
+    // reach into the workflow graph.
+    const isScenario = expression.text === 'pikkuScenario';
     // only handle calls like pikkuFunc(...)
     if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku')) {
         return;
@@ -289,6 +300,14 @@ export const addFunctions = (logger, node, checker, state, options) => {
     if (!pikkuFuncId || pikkuFuncId.startsWith('__temp_')) {
         return;
     }
+    // pikku's own scenario instrumentation, which older projects still carry as a
+    // scaffolded file in their source. It is not application code and must not be
+    // registered, metadata'd or deployed as if it were — `pikku dev` registers the
+    // implementations itself, and that is the only server that should have them.
+    if (isScenarioInstrumentationFunction(pikkuFuncId) ||
+        isScenarioInstrumentationFunction(name)) {
+        return;
+    }
     let title;
     let tags;
     let summary;
@@ -304,6 +323,8 @@ export const addFunctions = (logger, node, checker, state, options) => {
     let workflowQueued;
     let workflowRetries;
     let workflowTimeout;
+    let scenarioStepBrowser;
+    let scenarioStepTemplate;
     let scopes;
     let version;
     let objectNode;
@@ -375,6 +396,8 @@ export const addFunctions = (logger, node, checker, state, options) => {
         workflowQueued = getPropertyValue(firstArg, 'workflowQueued');
         workflowRetries = getPropertyValue(firstArg, 'workflowRetries');
         workflowTimeout = getPropertyValue(firstArg, 'workflowTimeout');
+        scenarioStepBrowser = getPropertyValue(firstArg, 'browser');
+        scenarioStepTemplate = getPropertyValue(firstArg, 'template');
         scopes = getArrayPropertyValue(firstArg, 'scopes') ?? undefined;
         // Extract approvalDescription identifier reference
         for (const prop of firstArg.properties) {
@@ -773,6 +796,8 @@ export const addFunctions = (logger, node, checker, state, options) => {
         outputs: outputNames.filter((n) => n !== 'void') ?? null,
         expose: expose || undefined,
         remote: remote || undefined,
+        scenarioStep: isScenarioStep || undefined,
+        scenario: isScenario || undefined,
         mcp: mcpEnabled || undefined,
         readonly: readonly_ || undefined,
         deploy: deploy || undefined,
@@ -781,6 +806,8 @@ export const addFunctions = (logger, node, checker, state, options) => {
         workflowQueued: workflowQueued === true ? true : undefined,
         workflowRetries: workflowRetries ?? undefined,
         workflowTimeout: workflowTimeout ?? undefined,
+        scenarioStepBrowser: scenarioStepBrowser === true ? true : undefined,
+        scenarioStepTemplate: scenarioStepTemplate || undefined,
         scopes: scopes ?? undefined,
         implementationHash,
         version,
@@ -863,7 +890,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
             logger.error(`• Function with explicit name '${name}' is not exported, this is not allowed.`);
             return;
         }
-        if (remote) {
+        if (remote && !isScenarioStep) {
             state.rpc.invokedFunctions.add(pikkuFuncId);
             // The consumer-facing surface a wireRemoteAddon imports (mirrors exposedMeta)
             state.rpc.remoteMeta[name] = pikkuFuncId;
@@ -872,7 +899,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
                 exportedName,
             });
         }
-        if (expose) {
+        if (expose && !isScenarioStep) {
             state.rpc.exposedMeta[name] = pikkuFuncId;
             state.rpc.exposedFiles.set(name, {
                 path: node.getSourceFile().fileName,
@@ -881,11 +908,13 @@ export const addFunctions = (logger, node, checker, state, options) => {
             // Track exposed RPC function for service aggregation
             state.serviceAggregation.usedFunctions.add(pikkuFuncId);
         }
-        // We add it to internal meta to allow autocomplete for everything
-        state.rpc.internalMeta[name] = pikkuFuncId;
-        if (version !== undefined) {
-            state.rpc.internalMeta[pikkuFuncId] = pikkuFuncId;
-            state.rpc.invokedFunctions.add(pikkuFuncId);
+        if (!isScenarioStep) {
+            // We add it to internal meta to allow autocomplete for everything
+            state.rpc.internalMeta[name] = pikkuFuncId;
+            if (version !== undefined) {
+                state.rpc.internalMeta[pikkuFuncId] = pikkuFuncId;
+                state.rpc.invokedFunctions.add(pikkuFuncId);
+            }
         }
         // But we only import the actual function if it's actually invoked to keep
         // bundle size down

package/dist/add/add-workflow.js

@@ -86,6 +86,11 @@ export function collectInvokedRPCs(steps, rpcs) {
                 rpcs.add(step.options.onError);
             }
         }
+        else if (step.type === 'scenarioStep' && step.stepFunc) {
+            // Steps are bundled like RPCs — the runner calls them through
+            // runPikkuFunc — but they are deliberately never RPC-registered.
+            rpcs.add(step.stepFunc);
+        }
         else if (step.type === 'branch') {
             for (const branch of step.branches) {
                 collectInvokedRPCs(branch.steps, rpcs);
@@ -247,6 +252,7 @@ export const addWorkflow = (logger, node, checker, state) => {
     let description;
     let errors;
     let expose;
+    let skip;
     if (ts.isObjectLiteralExpression(firstArg)) {
         const metadata = getCommonWireMetaData(firstArg, 'Workflow', workflowName, logger, checker);
         if (metadata.disabled)
@@ -257,6 +263,7 @@ export const addWorkflow = (logger, node, checker, state) => {
         description = metadata.description;
         errors = metadata.errors;
         expose = getPropertyValue(firstArg, 'expose');
+        skip = getPropertyValue(firstArg, 'skip') ?? undefined;
     }
     // Validate that we got a valid function
     if (ts.isObjectLiteralExpression(firstArg) &&
@@ -324,6 +331,13 @@ export const addWorkflow = (logger, node, checker, state) => {
             logger.critical(ErrorCode.INVALID_DSL_WORKFLOW, `Workflow '${workflowName}' does not conform to DSL workflow rules:\n${result.reason || 'Unknown error'}`);
             return;
         }
+        else if (wrapperType === 'scenario') {
+            // The fallback below understands do/sleep but not step/given/when/then,
+            // so a scenario that lands here registers with zero steps. Silence would
+            // leave the whole scenario passing vacuously.
+            logger.critical(ErrorCode.SCENARIO_NOT_EXTRACTABLE, `Scenario '${workflowName}' could not be extracted, so none of its steps were recorded and it would run as an empty scenario:\n${result.reason || 'Unknown error'}`);
+            return;
+        }
         else {
             // For pikkuWorkflowComplexFunc, fall back to basic extraction
             logger.debug(`Workflow '${workflowName}' could not be extracted as DSL workflow: ${result.reason || 'Unknown error'}. Falling back to basic extraction.`);
@@ -358,36 +372,15 @@ export const addWorkflow = (logger, node, checker, state) => {
         errors,
         tags,
         expose,
+        skip,
         scenario: wrapperType === 'scenario' ? true : undefined,
         actors: actorNames.length > 0 ? actorNames : undefined,
     };
-    // Scenarios are pure stories of remote RPCs (same rule as client-side CLI
-    // renderers): the func may only destructure logger/config — everything else
-    // must go through actor steps so the flow runs against the TARGET
-    // environment, never local services.
-    const funcMeta = state.functions.meta[pikkuFuncId];
-    if (wrapperType === 'scenario' && funcMeta?.services) {
-        const disallowed = funcMeta.services.services.filter((svc) => svc !== 'logger' && svc !== 'config');
-        if (disallowed.length > 0) {
-            logger.critical(ErrorCode.SCENARIO_HAS_SERVICES, `Scenario '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
-                `Scenarios may only use 'logger'/'config' — drive everything else through ` +
-                `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
-                `runs against the target environment.`);
-            return;
-        }
-    }
-    // Workflow functions require platform services that aren't visible
-    // through parameter destructuring (they're accessed via workflow.do/sleep)
-    if (funcMeta?.services) {
-        for (const svc of [
-            'workflowService',
-            'workflowRunService',
-            'schedulerService',
-            'queueService',
-        ]) {
-            if (!funcMeta.services.services.includes(svc)) {
-                funcMeta.services.services.push(svc);
-            }
-        }
-    }
+    // The scenario "logger/config only" rule (PKU673) and the implicit
+    // workflow platform-service injection both used to live here, reading
+    // state.functions.meta[pikkuFuncId]. addWorkflow runs in the visitSetup
+    // pass, which completes before addFunctions populates that meta, so both
+    // were dead. The rule now lives in validateScenarioServices (post-process),
+    // and aggregateRequiredServices already adds the platform services globally
+    // whenever any workflow exists.
 };

package/dist/add/scenario-instrumentation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The instrumentation RPCs `pikku scenario run` calls on the server it is
+ * testing: snapshot/reset live coverage, and reset/read recorded stub calls.
+ *
+ * They are pikku's own, not the application's. They used to be scaffolded into
+ * the project as ordinary `pikkuFunc`s, which made them indistinguishable from
+ * application code — so they were registered in the app bootstrap, listed in the
+ * app's function and RPC meta, and shipped, `expose: true`, in every deployed
+ * bundle. A deployment has no use for them: coverage and stub inspection are
+ * things you do to a development server.
+ *
+ * The inspector therefore ignores these names wherever it finds them, and
+ * `pikku dev` registers the implementations itself. Ignoring by name (rather
+ * than deleting the scaffold and requiring every project to regenerate) is what
+ * keeps an existing project's checked-in `scenarios.gen.ts` from deploying.
+ */
+export declare const SCENARIO_INSTRUMENTATION_FUNCTIONS: readonly ["pikkuScenarioTakeLiveCoverage", "pikkuScenarioResetLiveCoverage", "pikkuScenarioResetStubs", "pikkuScenarioGetStubCalls"];
+export type ScenarioInstrumentationFunction = (typeof SCENARIO_INSTRUMENTATION_FUNCTIONS)[number];
+/**
+ * True for a scenario instrumentation function, by name. Versioned ids
+ * (`name@v2`) are matched on their base so a project that bumps one is still
+ * covered.
+ */
+export declare const isScenarioInstrumentationFunction: (name: string | undefined) => boolean;

package/dist/add/scenario-instrumentation.js

@@ -0,0 +1,29 @@
+/**
+ * The instrumentation RPCs `pikku scenario run` calls on the server it is
+ * testing: snapshot/reset live coverage, and reset/read recorded stub calls.
+ *
+ * They are pikku's own, not the application's. They used to be scaffolded into
+ * the project as ordinary `pikkuFunc`s, which made them indistinguishable from
+ * application code — so they were registered in the app bootstrap, listed in the
+ * app's function and RPC meta, and shipped, `expose: true`, in every deployed
+ * bundle. A deployment has no use for them: coverage and stub inspection are
+ * things you do to a development server.
+ *
+ * The inspector therefore ignores these names wherever it finds them, and
+ * `pikku dev` registers the implementations itself. Ignoring by name (rather
+ * than deleting the scaffold and requiring every project to regenerate) is what
+ * keeps an existing project's checked-in `scenarios.gen.ts` from deploying.
+ */
+export const SCENARIO_INSTRUMENTATION_FUNCTIONS = [
+    'pikkuScenarioTakeLiveCoverage',
+    'pikkuScenarioResetLiveCoverage',
+    'pikkuScenarioResetStubs',
+    'pikkuScenarioGetStubCalls',
+];
+const names = new Set(SCENARIO_INSTRUMENTATION_FUNCTIONS);
+/**
+ * True for a scenario instrumentation function, by name. Versioned ids
+ * (`name@v2`) are matched on their base so a project that bumps one is still
+ * covered.
+ */
+export const isScenarioInstrumentationFunction = (name) => (name ? names.has(name.split('@')[0]) : false);

package/dist/error-codes.d.ts

@@ -20,6 +20,9 @@ export declare enum ErrorCode {
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
     SCENARIO_HAS_SERVICES = "PKU673",
     EXPECT_EVENTUALLY_SCENARIO_ONLY = "PKU675",
+    SCENARIO_BROWSER_STEP_NEEDS_ACTOR = "PKU677",
+    SCENARIO_STEP_TARGET_NOT_STATIC = "PKU678",
+    SCENARIO_NOT_EXTRACTABLE = "PKU679",
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",
     WORKFLOW_GRAPH_ADDON_NOT_WIRED = "PKU642",

package/dist/error-codes.js

@@ -22,6 +22,9 @@ export var ErrorCode;
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
     ErrorCode["SCENARIO_HAS_SERVICES"] = "PKU673";
     ErrorCode["EXPECT_EVENTUALLY_SCENARIO_ONLY"] = "PKU675";
+    ErrorCode["SCENARIO_BROWSER_STEP_NEEDS_ACTOR"] = "PKU677";
+    ErrorCode["SCENARIO_STEP_TARGET_NOT_STATIC"] = "PKU678";
+    ErrorCode["SCENARIO_NOT_EXTRACTABLE"] = "PKU679";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";
     ErrorCode["WORKFLOW_GRAPH_ADDON_NOT_WIRED"] = "PKU642";

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';
 export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
+export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
+export type { ScenarioInstrumentationFunction } from './add/scenario-instrumentation.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
@@ -12,6 +14,7 @@ export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export type { ContractEntry, VersionHashEntry, VersionValidateError, VersionManifest, VersionManifestEntry, } from './utils/contract-hashes.js';
+export type { InspectorFeature, InspectorFeatureEntry } from './types.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { inspect, getInitialInspectorState } from './inspector.js';
 export { ErrorCode } from './error-codes.js';
 export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
+export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { resolveDeployTarget } from './utils/resolve-deploy-target.js';

package/dist/inspector.js

@@ -1,12 +1,12 @@
 import * as ts from 'typescript';
 import { performance } from 'perf_hooks';
-import { resolve } from 'path';
+import { dirname, resolve } from 'path';
 import { visitSetup, visitFunctions, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeDiagnostics, validateSchemaWiringSeparation, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeDiagnostics, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
 import { pikkuState } from '@pikku/core/internal';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
@@ -86,6 +86,7 @@ export function getInitialInspectorState(rootDir) {
             files: new Map(),
             graphMeta: {},
             graphFiles: new Map(),
+            featureFiles: new Map(),
             invokedWorkflows: new Set(),
         },
         rpc: {
@@ -204,9 +205,43 @@ export function getInitialInspectorState(rootDir) {
         program: null,
     };
 }
+/**
+ * The path mappings the inspector's program has to share with the project.
+ *
+ * The inspector builds its own program rather than reusing the project's, which
+ * is what keeps a cold run affordable — but a project that reaches its generated
+ * code through a tsconfig `paths` entry resolves that import through those
+ * mappings and nothing else. Without them the factory an inspected function is
+ * passed to resolves to `any`, so a function whose input type comes from the
+ * factory's contextual type (rather than an explicit generic or a named schema)
+ * silently records no input at all.
+ *
+ * Only resolution keys are copied. Type-inference options such as `strict` stay
+ * the inspector's own, because changing those would change the recorded types.
+ */
+const readProjectPathMappings = (logger, tsconfig) => {
+    if (!tsconfig) {
+        return {};
+    }
+    const configPath = resolve(tsconfig);
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (configFile.error || !configFile.config) {
+        logger.debug(`Could not read ${configPath} for path mappings; imports that rely on them will not resolve`);
+        return {};
+    }
+    const { options: projectOptions } = ts.parseJsonConfigFileContent(configFile.config, ts.sys, dirname(configPath));
+    const { baseUrl, paths, rootDirs, pathsBasePath } = projectOptions;
+    return {
+        ...(baseUrl !== undefined ? { baseUrl } : {}),
+        ...(paths !== undefined ? { paths } : {}),
+        ...(rootDirs !== undefined ? { rootDirs } : {}),
+        ...(pathsBasePath !== undefined ? { pathsBasePath } : {}),
+    };
+};
 export const inspect = async (logger, routeFiles, options = {}) => {
     const normalizedRouteFiles = routeFiles.map((file) => resolve(file));
     const compilerOptions = {
+        ...readProjectPathMappings(logger, options.tsconfig),
         target: ts.ScriptTarget.ESNext,
         module: ts.ModuleKind.Node16,
         skipLibCheck: true,
@@ -310,6 +345,8 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         computeDiagnostics(state);
         validateSchemaWiringSeparation(logger, state);
         validateWorkflowGraphAddons(logger, state);
+        validateScenarioServices(logger, state);
+        validateScenarioSteps(logger, state);
         if (options.openAPI) {
             state.openAPISpec = await generateOpenAPISpec(logger, state.functions.meta, state.http.meta, state.schemas, options.openAPI.additionalInfo, pikkuState(null, 'misc', 'errors'));
         }

package/dist/types.d.ts

@@ -205,6 +205,12 @@ export type InspectorOptions = Partial<{
     rootDir: string;
     isAddon: boolean;
     sourceFile: ts.SourceFile;
+    /**
+     * The project's tsconfig, read for its path mappings only. The inspector's
+     * program needs them to resolve imports the project reaches through `paths`;
+     * unlike `schemaConfig.tsconfig` this is also needed on a setup-only run.
+     */
+    tsconfig: string;
     types: Partial<{
         configFileType: string;
         userSessionType: string;
@@ -346,6 +352,34 @@ export interface AuthDefinition {
      */
     services: FunctionServicesMeta;
 }
+/** One statically resolved entry of a feature's `scenarios` array. */
+export interface InspectorFeatureEntry {
+    /** The scenario's declared export name, with any import alias followed back. */
+    scenario: string;
+    /** A `{ scenario, data }` entry's literal data — gherkin's `Examples:`. */
+    data?: unknown;
+}
+/** A `pikkuFeature` export, as far as it can be read from the source. */
+export interface InspectorFeature {
+    path: string;
+    exportedName: string;
+    name?: string;
+    description?: string;
+    tags?: string[];
+    entries: InspectorFeatureEntry[];
+    /**
+     * Entries that are not literal — a spread, a `.map()`, a call. Counted rather
+     * than dropped so the console can say the listing is partial instead of
+     * quietly showing a short feature.
+     */
+    unresolvedEntries: number;
+    /**
+     * Feature hooks run once around the whole group, never per scenario, and are
+     * runtime-only — so only their presence is recorded.
+     */
+    hasBefore: boolean;
+    hasAfter: boolean;
+}
 export interface InspectorState {
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
@@ -395,6 +429,15 @@ export interface InspectorState {
             path: string;
             exportedName: string;
         }>;
+        /**
+         * `pikkuFeature` exports, keyed by export identifier.
+         *
+         * Everything the config states literally is extracted here, because a
+         * feature is the document structure the console renders. Entries built by
+         * an ordinary loop cannot be enumerated statically — those are counted in
+         * `unresolvedEntries` and resolved at runtime by object identity instead.
+         */
+        featureFiles: Map<string, InspectorFeature>;
         invokedWorkflows: Set<string>;
     };
     rpc: {

package/dist/utils/extract-function-name.js

@@ -28,6 +28,32 @@ export function funcIdToTypeName(id) {
         .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
         .join('');
 }
+/**
+ * `pikkuScenarioStep({ name })` is the one wrapper whose `name` is its identity:
+ * scenarios reference a step by that string, so it must become the pikkuFuncId
+ * (and hence the generated step map's key), not just a cosmetic label the way
+ * `pikkuMiddleware`/`pikkuAgent` use it.
+ */
+function extractScenarioStepName(callExpr, result) {
+    if (!ts.isCallExpression(callExpr) ||
+        !ts.isIdentifier(callExpr.expression) ||
+        callExpr.expression.text !== 'pikkuScenarioStep') {
+        return;
+    }
+    const firstArg = callExpr.arguments[0];
+    if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) {
+        return;
+    }
+    for (const prop of firstArg.properties) {
+        if (ts.isPropertyAssignment(prop) &&
+            ts.isIdentifier(prop.name) &&
+            prop.name.text === 'name' &&
+            ts.isStringLiteral(prop.initializer)) {
+            result.explicitName = prop.initializer.text;
+            return;
+        }
+    }
+}
 export function extractFunctionName(callExpr, checker, rootDir) {
     const parent = callExpr.parent;
     // Initialize the result
@@ -40,6 +66,7 @@ export function extractFunctionName(callExpr, checker, rootDir) {
         isHelper: false,
         version: null,
     };
+    extractScenarioStepName(callExpr, result);
     const workflowHelpers = new Set([
         'workflow',
         'workflowStart',

package/dist/utils/post-process.d.ts

@@ -50,6 +50,32 @@ export declare function computeMiddlewareGroupsMeta(state: InspectorState): void
 export declare function computePermissionsGroupsMeta(state: InspectorState): void;
 export declare function computeRequiredSchemas(state: InspectorState, options: InspectorOptions): void;
 export declare function validateAgentModels(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * Scenarios are pure stories of remote RPCs (same rule as client-side CLI
+ * renderers): the func may only destructure logger/config — everything else
+ * must go through actor steps so the flow runs against the TARGET
+ * environment, never local services.
+ *
+ * This runs in post-processing rather than in `addWorkflow` because
+ * `addWorkflow` runs in the `visitSetup` pass, which completes before
+ * `addFunctions` (`visitFunctions`) has populated `state.functions.meta` — so
+ * the check read `undefined` there and never fired.
+ */
+export declare function validateScenarioServices(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * Walk every scenario step, wherever it is nested, and validate the two things
+ * that can only be known once both the workflow meta and the function meta
+ * exist:
+ *
+ * - the step target must be a static string literal (PKU678) — otherwise it
+ *   can't be bundled, typed or drawn;
+ * - a `browser: true` step must be given an actor (PKU677), since the browser
+ *   context signs in as that persona.
+ *
+ * It also marks the step's function as used, so `scenario run` boots the
+ * singletons the step actually needs.
+ */
+export declare function validateScenarioSteps(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
  * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never

package/dist/utils/post-process.js

@@ -4,6 +4,7 @@ import { extractTypeKeys } from './type-utils.js';
 import { ErrorCode } from '../error-codes.js';
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js';
 import { flattenScopeDefinitions } from '@pikku/core/scope';
+import { DYNAMIC_SCENARIO_STEP_TARGET } from './workflow/dsl/patterns.js';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -211,6 +212,13 @@ export function aggregateRequiredServices(state) {
     for (const [, graph] of Object.entries(state.workflows.graphMeta)) {
         if (!graph.nodes || !graph.name)
             continue;
+        // A scenario is a workflow, but it only ever runs in-process under
+        // `pikku scenario run` — no step of one is dispatched through a queue. The
+        // synthetic entries were pure leakage: they put a
+        // `wf-orchestrator-<scenario>` worker into the app's queue meta, which every
+        // bundle imports and a provider then creates as a real production queue.
+        if (graph.source === 'scenario')
+            continue;
         const toKebab = (s) => s
             .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
             .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
@@ -552,6 +560,90 @@ export function validateAgentModels(logger, state) {
         }
     }
 }
+/**
+ * Scenarios are pure stories of remote RPCs (same rule as client-side CLI
+ * renderers): the func may only destructure logger/config — everything else
+ * must go through actor steps so the flow runs against the TARGET
+ * environment, never local services.
+ *
+ * This runs in post-processing rather than in `addWorkflow` because
+ * `addWorkflow` runs in the `visitSetup` pass, which completes before
+ * `addFunctions` (`visitFunctions`) has populated `state.functions.meta` — so
+ * the check read `undefined` there and never fired.
+ */
+export function validateScenarioServices(logger, state) {
+    for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+        if (!meta.scenario)
+            continue;
+        const funcMeta = state.functions.meta[meta.pikkuFuncId];
+        if (!funcMeta?.services)
+            continue;
+        const disallowed = funcMeta.services.services.filter((svc) => svc !== 'logger' && svc !== 'config');
+        if (disallowed.length > 0) {
+            logger.critical(ErrorCode.SCENARIO_HAS_SERVICES, `Scenario '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
+                `Scenarios may only use 'logger'/'config' — drive everything else through ` +
+                `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
+                `runs against the target environment.`);
+        }
+    }
+}
+/**
+ * Walk every scenario step, wherever it is nested, and validate the two things
+ * that can only be known once both the workflow meta and the function meta
+ * exist:
+ *
+ * - the step target must be a static string literal (PKU678) — otherwise it
+ *   can't be bundled, typed or drawn;
+ * - a `browser: true` step must be given an actor (PKU677), since the browser
+ *   context signs in as that persona.
+ *
+ * It also marks the step's function as used, so `scenario run` boots the
+ * singletons the step actually needs.
+ */
+export function validateScenarioSteps(logger, state) {
+    const visit = (workflowName, steps) => {
+        for (const step of steps) {
+            if (step.type === 'scenarioStep') {
+                if (step.stepFunc === DYNAMIC_SCENARIO_STEP_TARGET) {
+                    logger.critical(ErrorCode.SCENARIO_STEP_TARGET_NOT_STATIC, `Scenario '${workflowName}' calls step '${step.stepName}' with a target that isn't a string literal. ` +
+                        `A step target must be statically resolvable so it can be bundled, typed and drawn — ` +
+                        `loop over data sets instead of computing the step name.`);
+                    continue;
+                }
+                state.serviceAggregation.usedFunctions.add(step.stepFunc);
+                const stepMeta = state.functions.meta[step.stepFunc];
+                if (stepMeta?.scenarioStepBrowser && !step.actor) {
+                    logger.critical(ErrorCode.SCENARIO_BROWSER_STEP_NEEDS_ACTOR, `Scenario '${workflowName}' calls browser step '${step.stepFunc}' without an actor. ` +
+                        `Pass { actor: actors.<name> } so the browser context signs in as that persona.`);
+                }
+                continue;
+            }
+            if (step.type === 'branch') {
+                for (const branch of step.branches)
+                    visit(workflowName, branch.steps);
+                if (step.elseSteps)
+                    visit(workflowName, step.elseSteps);
+            }
+            else if (step.type === 'switch') {
+                for (const c of step.cases ?? []) {
+                    if (c.steps)
+                        visit(workflowName, c.steps);
+                }
+                if (step.defaultSteps)
+                    visit(workflowName, step.defaultSteps);
+            }
+            else if (step.type === 'fanout' && step.body) {
+                visit(workflowName, step.body);
+            }
+            else if (step.type === 'parallel' && step.children) {
+                visit(workflowName, step.children);
+            }
+        }
+    };
+    for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+        visit(workflowName, meta.steps ?? []);
+    }
+}
 /**
  * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
  * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never

package/dist/utils/serialize-inspector-state.d.ts

@@ -1,5 +1,5 @@
 import type { JSONValue } from '@pikku/core';
-import type { InspectorDiagnostic, InspectorState } from '../types.js';
+import type { InspectorDiagnostic, InspectorFeature, InspectorState } from '../types.js';
 /**
  * Serializable version of InspectorState that can be saved to JSON
  * Omits typesLookup (contains non-serializable ts.Type objects) and converts Maps/Sets to arrays
@@ -160,6 +160,7 @@ export interface SerializableInspectorState {
             path: string;
             exportedName: string;
         }]>;
+        featureFiles: Array<[string, InspectorFeature]>;
         invokedWorkflows: string[];
     };
     rpc: {