@pikku/inspector 0.12.46 → 0.12.48

package/CHANGELOG.md

@@ -1,3 +1,200 @@
+## 0.12.48
+
+### Patch Changes
+
+- 04b8607: Make the unmodellable-for-of diagnostic tell you what is actually wrong. It always blamed the iterable ("its iterable must be a data array"), which was false whenever the real cause was a `workflow.do` nested inside an `if`/`switch` — a DSL fanout body is a flat list of steps with no branch member, so the diagnostic now says so and points at `.filter` or `pikkuWorkflowComplexFunc`. Also stops the same diagnostic firing on a `for-of` that contains no workflow call at all: a loop that only massages locals has no step to lose, so erroring on it was a false positive.
+- 7c8f015: Hard-error on a for-of a DSL workflow can't model, instead of silently dropping it.
+
+  A `pikkuWorkflowFunc` (DSL) whose body contained a computed/counting loop — e.g. `for (const i of [...Array(n).keys()])` — used to serialize with **zero steps**: the DSL extractor only models a for-of as a sequential fanout over a data-array identifier/field (`data.items`), so a non-path iterable made `extractSequentialFanout` return null and the extractor dropped the loop _and every `workflow.do` inside it_. The invoked functions then never entered `invokedFunctions`, so they got no `addFunction()` registration and threw `Function not found` at runtime — a silent codegen footgun that bricked every prod sandbox create.
+
+  Now the extractor pushes a validation error naming the offending for-of, so `pikkuWorkflowFunc` reports `INVALID_DSL_WORKFLOW` at codegen. A genuine control-flow/counting loop belongs in `pikkuWorkflowComplexFunc`, which falls back to the basic AST walk that _does_ register loop-invoked functions.
+
+- 5962e51: Give the inspector's program the project's tsconfig path mappings.
+
+  The inspector builds its own TypeScript program rather than reusing the project's, which is what keeps a cold run affordable — but it hand-rolled its compiler options and so had no `paths`. An import the project resolves only through a `paths` entry therefore did not resolve inside the inspector, and the factory the inspected function was passed to came back as `any`. A function whose input type comes from that factory's contextual type — rather than an explicit generic or a named `input:` schema — then recorded no input at all, silently, with no diagnostic.
+
+  `inspect` takes a new `tsconfig` option (the CLI passes `config.tsconfig`, including on a setup-only run, where `schemaConfig` is absent). Only resolution keys are copied across — `baseUrl`, `paths`, `rootDirs`, `pathsBasePath`. Type-inference options such as `strict` deliberately stay the inspector's own, because changing those would change the types it records.
+
+  This was latent rather than live: the generic path reads type _nodes_, the schema path reads an identifier, output types come from the handler body, and JSON schemas are generated by a separate tsconfig-aware program — so nothing in the tree reached the contextual-type fallback. Regenerating the e2e project and the `functions` template produces byte-identical output.
+
+- 5962e51: Add `pikkuFeature`, a grouping primitive for scenarios.
+
+  A feature groups scenarios the way gherkin's `Feature:` groups `Scenario:`, and gets `Examples:` for free as an ordinary loop:
+
+  ```ts
+  export const credentialFeature = pikkuFeature({
+    name: 'Credential API',
+    tags: ['credential'],
+    before: startsMockOAuthServer,
+    after: stopsMockOAuthServer,
+    scenarios: [
+      credentialLazyLoadScenario,
+      ...['stripe', 'google', 'hmac-key'].map((name) => ({
+        scenario: credentialRoundTripScenario,
+        data: { name },
+      })),
+    ],
+  })
+  ```
+
+  - Scenarios are referenced by **imported identifier**, not by string name, so a renamed or deleted scenario is a compile error rather than a silent skip. A `{ scenario, data }` entry's `data` is typed against that scenario's own input.
+  - Feature hooks run **once around the whole group** (`before → a → b → c → after`), not per scenario, and `after` runs in a `finally`. Per-scenario setup stays the scenario's own `before`; gherkin's `Background:` is deliberately not expressible.
+  - A scenario's effective tags are its own plus its feature's, so `--tags credential` selects through the feature.
+  - New `--features` selector on `pikku scenario run`, and `pikku scenario list` now prints features with their scenarios indented. Every filter narrows the same plan, so narrowing a feature to two of its five scenarios still runs its hooks exactly once around those two.
+  - The **feature is the run unit**: `--flows` on a scenario whose every feature entry carries `data` errors and names the features containing it, because the feature is what supplies that data. A scenario referenced bare anywhere, or in no feature at all, still runs standalone.
+
+  `pikkuFeature` infers its scenario list with a `const` generic, so `CoreFeature['scenarios']` is `readonly` — otherwise the emitted `addFeature(id, feature)` call does not typecheck.
+
+  Membership is resolved at runtime by object identity — `pikkuScenario` returns its config verbatim, so a feature holds the very object that was registered. That is what lets the scenario list be built by a loop, which no static analysis could enumerate. It also means a scenario constructed inline inside a feature is never registered, and is reported as unresolved rather than silently running as something else.
+
+- 5962e51: Add `before` / `after` hooks to `pikkuScenario`, and make an unextractable scenario a hard error.
+
+  A scenario config now takes `before` and `after`. Both have the same signature as `func` — `(services, data, wire)` — with the return value discarded, so there is no new type to learn and a hook reaches the app the same way the body does, through `wire.actors`:
+
+  ```ts
+  export const credentialScenario = pikkuScenario({
+    title: 'A credential is loaded on first use',
+    tags: ['scenario', 'credential'],
+    before: resetsCredentials,
+    after: removesInstalledAddon,
+    func: async (services, data, { scenario, actors }) => { ... },
+  })
+  ```
+
+  - `before` throwing skips the body and fails the run, but `after` still runs.
+  - `after` always runs, in a `finally`. 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.
+  - Neither runs when the run is suspended or waiting — teardown only fires at a terminal outcome.
+  - Hooks are not ladder rows: the runner records nothing for them, and a failure is labelled by phase via the new `ScenarioHookError`.
+  - Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs — a workflow is durable and resumable, so a callback that reran on every replay would have no honest meaning.
+
+  Two fixes that scenarios needed to be safe to write:
+  - A closure in a complex-workflow or scenario body is no longer held to the DSL statement whitelist. A single `try`/`catch` inside any callback previously failed extraction, and the fallback path understands `do`/`sleep` but not `step`/`given`/`when`/`then` — so the scenario registered with **zero steps** and passed vacuously, with no diagnostic. Plain DSL workflows still descend into callbacks, which is what validates fanout bodies.
+  - New `PKU679`: a scenario that fails DSL extraction is now a critical error and refuses to register, instead of silently registering empty. A scenario that declares no input parameter at all is legitimate and still extracts.
+
+- a436645: Redesign the console's scenarios screen as living documentation of a project's BDD features.
+
+  The inspector now statically extracts `pikkuFeature` declarations — name, description, tags, the scenarios each one groups (including `{ scenario, data }` examples), and whether it declares `before`/`after` — and the CLI writes them to `<outDir>/scenarios/features.gen.json`, which `MetaService.getFeaturesMeta()` reads and the console addon returns from `getAllMeta`.
+
+  The scenarios page reads that back as a document: features on the left, and on the right the selected feature's scenarios, each rendered as the given/when/then ladder of prose its author actually wrote, with repeats shown as `for each x in xs`, `Examples:` tables for parameterised entries, skip reasons stated rather than hidden, and each scenario's cast of personas inline. The Flows/Personas segmented control is gone; tags filter the document the same way `pikku scenario run --tags` filters a run.
+
+- 47478a4: Let a scenario declare why it is held out of a default run.
+
+  `pikkuScenario({ skip: 'why' })` keeps the scenario in the plan and reports it as `SKIP <name> (<reason>)` on the ladder, instead of the alternatives available until now: deleting it, commenting it out, or leaving it red. Naming it directly with `--flows` clears the quarantine and runs it; selecting the feature it belongs to does not, because a feature is a group and running the group should not silently drag a quarantined member in.
+
+  The run report's `skipped` list now carries a reason per scenario rather than assuming `--no-browser`, so a browser scenario held back on a machine with no browser reads differently from one the project quarantined itself.
+
+  `@pikku/console` gains a test id on the addon detail page's Setup tab, which was previously only reachable through its translated label.
+
+- 2434f1b: Fix two silent losses in scenario step extraction.
+
+  Destructuring a scenario step result (`const { threadId } = await scenario.given(...)`) dropped the
+  step from the graph without a diagnostic — the step stayed fully typed and present in the step map,
+  then failed at runtime with `Function not found`. It now reports PKU679, like every other step form
+  the DSL cannot model.
+
+  A constant referenced as step input (`{ resourceId: RESOURCE_ID }`) was serialized as
+  `{ $ref: 'trigger', path: 'RESOURCE_ID' }` — a read of a trigger field that does not exist. A `const`
+  with a literal initializer is now inlined as that literal.
+
+- 5962e51: Add `template` to `pikkuScenarioStep`, so a step's reported prose names the values it was called with.
+
+  `description` documents what a step does, for the console and for whoever reads the source. `template` is what a reader of the report sees, with `{placeholders}` filled from the input the step was actually called with:
+
+  ```ts
+  export const seesAddonCard = pikkuScenarioStep<
+    { packageName: string; state?: 'installed' | 'available' },
+    { visible: true },
+    true
+  >({
+    name: 'seesAddonCard',
+    description: 'sees an addon in the gallery',
+    template: 'sees {state} addon {packageName}',
+    browser: true,
+    func: async (_services, { packageName, state }, { browser }) => { … },
+  })
+  ```
+
+  ```
+  Then  the admin sees at least 10 addons on offer          ✓  3ms
+  When  the admin searches for stripe                       ✓  10ms
+  Then  the admin sees available addon @pikku/addon-stripe  ✓  77ms
+  ```
+
+  Previously the only way to get that was a `description` at every call site, which meant writing the sentence once per call rather than once per step — and a call site that forgot it reported the same sentence three times in a row.
+  - A placeholder with no recorded value renders as nothing and the surrounding whitespace collapses, so an omitted optional input reads as a shorter sentence rather than leaking a literal `{state}` into the report. Type placeholder values so they read as words (`state?: 'installed' | 'available'`, not `installed?: boolean`).
+  - A call-site `description` still wins, the same way it already won over the step's `description`.
+  - `renderStepTemplate` is exported from `@pikku/core/workflow` alongside `composeStepProse`, so the CLI reporter and the console render identically.
+
+  Scenario steps now record their input on the run (`inlineStep` persisted `null` for every inline step, so there was nothing for a reporter to interpolate). This is what `getRunSteps` already exposes as `data` for RPC steps.
+
+  A step called from a loop gets its template too. Its durable name is built at runtime (`sees @pikku/addon-todos`) from a declaration the static meta records verbatim (`sees ${packageName}`), so the two can never match by name — it used to fall back to the bare name, with no keyword, actor or template:
+
+  ```
+          sees @pikku/addon-console                              ✓  85ms
+  Then    the admin sees installed addon @pikku/addon-console    ✓  92ms
+  ```
+
+  The join is by **step function**. A scenario step is dispatched by name exactly as an RPC is, so it now records that name in the run's existing `rpcName` slot — no new field, no schema change in any workflow store. Nothing dispatches off that value anywhere; step identity always comes from the code being replayed.
+
+  To keep the slot honest, a scenario step is now its own **kind of RPC**, alongside public / private / remote: `FunctionMeta.scenarioStep` marks it, and `rpcExposed` refuses it even if something marks it `expose: true`. Steps were already left out of the RPC registry; this makes "never network-callable" a property the runtime enforces rather than one the registration path happens to produce.
+
+  `collectScenarioStepProse` now returns `{ byStepName, byStepFunc }` rather than a bare `Map`, and `buildStepLadder` takes that. The step name still wins; the function index only decides steps recorded under a name no declaration carries, and a function called from several sites that disagree on their prose is left out rather than guessed at.
+
+- 5962e51: Add `pikkuScenarioStep` — named, typed scenario steps whose body is an ordinary pikku function.
+
+  A scenario step is referenced by typed string name, the same way `workflow.do` references an RPC, and is checked against a generated `FlattenedScenarioStepMap`:
+
+  ```ts
+  export const buysAnApple = pikkuScenarioStep({
+    name: 'buysAnApple',
+    description: 'buys an apple',
+    func: async (services, data: { qty: number }) => { ... },
+  })
+
+  await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })
+  // renders: Given the shopper buys an apple
+  ```
+
+  - `given`/`when`/`then` are sugar over `step`, setting only the prose prefix. The runner renders a step ladder from the recorded run.
+  - Steps default to `retries: 0` — a failed assertion is not retried.
+  - Steps are deliberately **not** registered as RPCs, so a browser-driving step is never network-callable.
+  - `browser: true` steps receive a browser handle on the wire. `@pikku/playwright` is a new package providing the Playwright-backed provider, signing each actor's browser context in through the same actor path the HTTP actors use. Without a provider, `pikku scenario run --no-browser` **skips** browser scenarios instead of failing them.
+  - New diagnostics: PKU677 (a `browser: true` step called without an actor) and PKU678 (a step target that is not a static string literal).
+  - Fixes `--no-<flag>` boolean negation in the CLI command parser, which previously parsed as an unknown option.
+  - Fixes PKU673 (a scenario func destructuring services), which never fired because it ran before function meta existed; it now runs in post-processing.
+  - Fixes scenario/workflow steps nested in `for...of` and `Promise.all` being dropped from workflow meta.
+
+- Updated dependencies [539ee0b]
+- Updated dependencies [a1a6816]
+- Updated dependencies [dc3e11e]
+- Updated dependencies [24da616]
+- Updated dependencies [04bfe3f]
+- Updated dependencies [5962e51]
+- Updated dependencies [5962e51]
+- Updated dependencies [cd6453c]
+- Updated dependencies [a436645]
+- Updated dependencies [46cf63e]
+- Updated dependencies [9e666bc]
+- Updated dependencies [1c841d8]
+- Updated dependencies [47478a4]
+- Updated dependencies [9e666bc]
+- Updated dependencies [5962e51]
+- Updated dependencies [5962e51]
+- Updated dependencies [61b9bf8]
+  - @pikku/core@0.12.70
+
+## 0.12.47
+
+### Patch Changes
+
+- 91077ff: The auth factory's services are read from the auth definition, not from the handler generated out of it.
+
+  `pikkuBetterAuth((services) => ...)`'s destructured services are what `authorize` and the session callbacks actually use, and they reach the generated services map by being stamped onto the auth handler's function meta. On the first run in a clean checkout that handler's file has not been written yet — so there is nothing to stamp, nothing to aggregate, and the map comes out marking those services unused. Run it a second time, with the file now on disk, and it says the opposite.
+
+  The consequence is not cosmetic: `RequiredSingletonServices` is built from that map, so a clean build types the services as optional and tree-shakes them out of the deployed auth worker — the exact failure the stamping exists to prevent, reintroduced by the one case where it cannot run. A CI checkout is always the first run.
+
+  The definition is inspected from hand-written source on every pass, so its services are now folded into the required set directly. A clean build and an incremental one give the same answer.
+
 ## 0.12.46
 
 ### Patch Changes

package/README.md

@@ -1,3 +1,29 @@
-# Pikku CLI
+# @pikku/inspector
 
-This package is part of @pikku/mono and is responsible for all the intropsection and file generations.
+The TypeScript inspector behind the Pikku CLI. Walks your source with the
+TypeScript compiler API to discover functions, wirings and their types, and
+produces the state the CLI generates code from.
+
+Most users get this transitively via `@pikku/cli`; install it directly only if
+you are building your own tooling on top of Pikku's introspection.
+
+## Install
+
+```bash
+npm install @pikku/inspector
+```
+
+## Usage
+
+```typescript
+import { inspect, getInitialInspectorState } from '@pikku/inspector'
+
+const state = getInitialInspectorState()
+await inspect(['src'], tsconfigPath, state)
+```
+
+Diagnostics come back as `CodedDiagnostic` values with a stable `ErrorCode`.
+
+## Docs
+
+https://pikku.dev/docs

package/dist/add/add-feature.d.ts

@@ -0,0 +1,19 @@
+import type { AddWiring } from '../types.js';
+/**
+ * Inspector for `pikkuFeature()` calls.
+ *
+ * A feature is the document structure the console renders — its name,
+ * description, tags and the order of its scenarios are what a reader sees — so
+ * everything the config states literally is extracted here.
+ *
+ * What cannot be extracted is a scenarios entry that is not literal:
+ * `...['stripe', 'google'].map((name) => ({ scenario, data: { name } }))` is
+ * ordinary TypeScript, and no AST walk can enumerate it. Those entries are
+ * counted in `unresolvedEntries` rather than dropped, and membership for them
+ * is resolved at runtime by object identity (`resolveFeatureScenarios`), where
+ * the array has actually been evaluated.
+ *
+ * The export location is recorded either way, which is what the CLI needs to
+ * emit its `addFeature(...)` wiring line.
+ */
+export declare const addFeature: AddWiring;

package/dist/add/add-feature.js

@@ -0,0 +1,200 @@
+import * as ts from 'typescript';
+import { extractFunctionName } from '../utils/extract-function-name.js';
+import { ErrorCode } from '../error-codes.js';
+/**
+ * Reads a fully literal expression into a plain value.
+ *
+ * Used for a `{ scenario, data }` entry's `data`, which is gherkin's
+ * `Examples:` row. Anything not literal yields `undefined` — a computed row
+ * belongs to the runtime-resolved portion, not to the extracted meta.
+ */
+const literalValue = (node) => {
+    if (ts.isStringLiteralLike(node)) {
+        return node.text;
+    }
+    if (ts.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    if (node.kind === ts.SyntaxKind.TrueKeyword) {
+        return true;
+    }
+    if (node.kind === ts.SyntaxKind.FalseKeyword) {
+        return false;
+    }
+    if (node.kind === ts.SyntaxKind.NullKeyword) {
+        return null;
+    }
+    if (ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand)) {
+        return -Number(node.operand.text);
+    }
+    if (ts.isArrayLiteralExpression(node)) {
+        const values = [];
+        for (const element of node.elements) {
+            const value = literalValue(element);
+            if (value === undefined) {
+                return undefined;
+            }
+            values.push(value);
+        }
+        return values;
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+        const value = {};
+        for (const property of node.properties) {
+            if (!ts.isPropertyAssignment(property)) {
+                return undefined;
+            }
+            const key = ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)
+                ? property.name.text
+                : undefined;
+            if (key === undefined) {
+                return undefined;
+            }
+            const propertyValue = literalValue(property.initializer);
+            if (propertyValue === undefined) {
+                return undefined;
+            }
+            value[key] = propertyValue;
+        }
+        return value;
+    }
+    return undefined;
+};
+/**
+ * Resolves a scenario reference to the name it is declared under, following an
+ * import alias back to the original export so `{ x as y }` records `x`.
+ */
+const scenarioName = (node, checker) => {
+    if (!ts.isIdentifier(node)) {
+        return undefined;
+    }
+    const symbol = checker.getSymbolAtLocation(node);
+    if (!symbol) {
+        return node.text;
+    }
+    const resolved = symbol.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(symbol)
+        : symbol;
+    return resolved.getName() || node.text;
+};
+const getProperty = (config, name) => {
+    const property = config.properties.find((p) => ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === name);
+    return property && ts.isPropertyAssignment(property)
+        ? property.initializer
+        : undefined;
+};
+const hasProperty = (config, name) => config.properties.some((p) => (ts.isPropertyAssignment(p) ||
+    ts.isMethodDeclaration(p) ||
+    ts.isShorthandPropertyAssignment(p)) &&
+    ts.isIdentifier(p.name) &&
+    p.name.text === name);
+const stringProperty = (config, name) => {
+    const value = getProperty(config, name);
+    return value && ts.isStringLiteralLike(value) ? value.text : undefined;
+};
+const stringArrayProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value || !ts.isArrayLiteralExpression(value)) {
+        return undefined;
+    }
+    const values = value.elements
+        .filter(ts.isStringLiteralLike)
+        .map((e) => e.text);
+    return values.length === value.elements.length ? values : undefined;
+};
+const readEntry = (element, checker) => {
+    if (ts.isIdentifier(element)) {
+        const scenario = scenarioName(element, checker);
+        return scenario ? { scenario } : undefined;
+    }
+    if (ts.isObjectLiteralExpression(element)) {
+        const reference = getProperty(element, 'scenario');
+        if (!reference) {
+            return undefined;
+        }
+        const scenario = scenarioName(reference, checker);
+        if (!scenario) {
+            return undefined;
+        }
+        const dataNode = getProperty(element, 'data');
+        if (!dataNode) {
+            return { scenario };
+        }
+        const data = literalValue(dataNode);
+        return data === undefined ? undefined : { scenario, data };
+    }
+    return undefined;
+};
+/**
+ * Inspector for `pikkuFeature()` calls.
+ *
+ * A feature is the document structure the console renders — its name,
+ * description, tags and the order of its scenarios are what a reader sees — so
+ * everything the config states literally is extracted here.
+ *
+ * What cannot be extracted is a scenarios entry that is not literal:
+ * `...['stripe', 'google'].map((name) => ({ scenario, data: { name } }))` is
+ * ordinary TypeScript, and no AST walk can enumerate it. Those entries are
+ * counted in `unresolvedEntries` rather than dropped, and membership for them
+ * is resolved at runtime by object identity (`resolveFeatureScenarios`), where
+ * the array has actually been evaluated.
+ *
+ * The export location is recorded either way, which is what the CLI needs to
+ * emit its `addFeature(...)` wiring line.
+ */
+export const addFeature = (logger, node, checker, state) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    const expression = node.expression;
+    if (!ts.isIdentifier(expression) || expression.text !== 'pikkuFeature') {
+        return;
+    }
+    const { exportedName } = extractFunctionName(node, checker, state.rootDir);
+    if (!exportedName) {
+        logger.critical(ErrorCode.MISSING_NAME, `A pikkuFeature() must be assigned to an export — the export identifier is the feature's id.`);
+        return;
+    }
+    const feature = {
+        path: node.getSourceFile().fileName,
+        exportedName,
+        entries: [],
+        unresolvedEntries: 0,
+        hasBefore: false,
+        hasAfter: false,
+    };
+    const [config] = node.arguments;
+    if (config && ts.isObjectLiteralExpression(config)) {
+        const name = stringProperty(config, 'name');
+        const description = stringProperty(config, 'description');
+        const tags = stringArrayProperty(config, 'tags');
+        if (name !== undefined) {
+            feature.name = name;
+        }
+        if (description !== undefined) {
+            feature.description = description;
+        }
+        if (tags !== undefined) {
+            feature.tags = tags;
+        }
+        feature.hasBefore = hasProperty(config, 'before');
+        feature.hasAfter = hasProperty(config, 'after');
+        const scenarios = getProperty(config, 'scenarios');
+        if (scenarios && ts.isArrayLiteralExpression(scenarios)) {
+            for (const element of scenarios.elements) {
+                const entry = readEntry(element, checker);
+                if (entry) {
+                    feature.entries.push(entry);
+                }
+                else {
+                    feature.unresolvedEntries += 1;
+                }
+            }
+        }
+    }
+    state.workflows.featureFiles.set(exportedName, feature);
+};

package/dist/add/add-functions.js

@@ -273,12 +273,18 @@ 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';
     // only handle calls like pikkuFunc(...)
     if (!ts.isIdentifier(expression) || !expression.text.startsWith('pikku')) {
         return;
@@ -304,6 +310,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 +383,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 +783,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
         outputs: outputNames.filter((n) => n !== 'void') ?? null,
         expose: expose || undefined,
         remote: remote || undefined,
+        scenarioStep: isScenarioStep || undefined,
         mcp: mcpEnabled || undefined,
         readonly: readonly_ || undefined,
         deploy: deploy || undefined,
@@ -781,6 +792,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 +876,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 +885,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 +894,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/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";