@pikku/cli 0.12.90 → 0.12.91

package/dist/src/cli.wiring.js

@@ -397,14 +397,36 @@ wireCLI({
                             description: 'Comma-separated flow names to run (default: all)',
                             short: 'f',
                         },
+                        features: {
+                            description: 'Comma-separated feature names to run (pikkuFeature exports) — the feature is the run unit, so its hooks run once around the group',
+                        },
                         tags: {
                             description: 'Comma-separated tags — run flows matching any',
                             short: 't',
                         },
+                        excludeTags: {
+                            description: 'Comma-separated tags to hold back — flows matching any are not run, unless named directly with --flows',
+                        },
                         coverage: {
                             description: 'Reset/snapshot server coverage per scenario (target must run with --coverage); writes coverage/scenario-coverage.json',
                             default: false,
                         },
+                        browser: {
+                            description: 'Run scenarios with browser steps. --no-browser skips them (they are reported as skipped, not failed)',
+                            default: true,
+                        },
+                        spawn: {
+                            description: "Start `pikku dev` on the environment's apiUrl for the run and stop it afterwards. Without it, the environment must already be serving",
+                            default: false,
+                        },
+                        keepAlive: {
+                            description: 'With --spawn, leave the server running after the run (dev loop)',
+                            default: false,
+                        },
+                        trace: {
+                            description: 'Keep every stack frame on a failure. Without it, only the project’s own frames are shown',
+                            default: false,
+                        },
                     },
                 }),
                 list: pikkuCLICommand({

package/dist/src/functions/commands/dev.js

@@ -14,6 +14,7 @@ import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 import { startCoverageService } from './start-coverage.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
+import { serverReadyLine } from '../../server/server-ready.js';
 export const dev = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config, getInspectorState, invalidateInspectorState, variables, devServerRunner, }, { port, watch, hmr, coverage, test }, { rpc }) => {
@@ -238,6 +239,7 @@ export const dev = pikkuSessionlessFunc({
         if (consoleMount) {
             logger.info(`Pikku Console available at http://${hostname}:${resolvedPort}${consoleMount.urlPrefix}`);
         }
+        logger.info(serverReadyLine(hostname, resolvedPort));
         let configWatcher;
         let watcher;
         process.once('SIGINT', async () => {

package/dist/src/functions/commands/load-user-project.d.ts

@@ -4,6 +4,13 @@
  * `pikkuState`.
  */
 export declare function loadUserBootstrap(pikkuDir: string): Promise<void>;
+/**
+ * Load the generated `pikku-bootstrap-scenarios.gen.{ts,js}`, which imports the
+ * app bootstrap and then registers the scenarios, features and steps that are
+ * deliberately kept out of it. Falls back to the app bootstrap for a project
+ * generated before the split existed.
+ */
+export declare function loadScenarioBootstrap(pikkuDir: string): Promise<void>;
 /**
  * Import a user-source TypeScript file (e.g. their config or services
  * factory) so it can be loaded from inside @pikku/cli's compiled JS.

package/dist/src/functions/commands/load-user-project.js

@@ -39,6 +39,27 @@ export async function loadUserBootstrap(pikkuDir) {
     ensureTsxRegistered();
     await importUserPath(bootstrapPath);
 }
+/**
+ * Load the generated `pikku-bootstrap-scenarios.gen.{ts,js}`, which imports the
+ * app bootstrap and then registers the scenarios, features and steps that are
+ * deliberately kept out of it. Falls back to the app bootstrap for a project
+ * generated before the split existed.
+ */
+export async function loadScenarioBootstrap(pikkuDir) {
+    const scenarioTs = join(pikkuDir, 'pikku-bootstrap-scenarios.gen.ts');
+    const scenarioJs = join(pikkuDir, 'pikku-bootstrap-scenarios.gen.js');
+    const scenarioPath = existsSync(scenarioTs)
+        ? scenarioTs
+        : existsSync(scenarioJs)
+            ? scenarioJs
+            : null;
+    if (!scenarioPath) {
+        await loadUserBootstrap(pikkuDir);
+        return;
+    }
+    ensureTsxRegistered();
+    await importUserPath(scenarioPath);
+}
 /**
  * Import a user-source TypeScript file (e.g. their config or services
  * factory) so it can be loaded from inside @pikku/cli's compiled JS.

package/dist/src/functions/commands/pikku-command-bootstrap.js

@@ -64,5 +64,17 @@ export const pikkuBootstrap = pikkuSessionlessFunc({
         })
             .join('\n');
         await writeFileInDir(logger, config.bootstrapFile, allBootstrapImports);
+        // The scenario bootstrap is the only entry point that registers scenarios,
+        // features and their steps. It pulls in the app bootstrap first so a runner
+        // needs to load one file, and so the meta files it merges onto are already
+        // in place however this module is reached.
+        const scenarioBootstrapImports = [
+            config.bootstrapFile,
+            config.scenarioStepsMetaFile,
+            config.scenarioStepsFile,
+            config.scenarioWiringsMetaFile,
+            config.scenarioWiringsFile,
+        ].map((to) => `import '${getFileImportRelativePath(config.scenarioBootstrapFile, to, config.packageMappings, config.forceRelativeImports)}'`);
+        await writeFileInDir(logger, config.scenarioBootstrapFile, scenarioBootstrapImports.join('\n'));
     },
 });

package/dist/src/functions/commands/scenario-browser.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The scenario runner's browser lifecycle.
+ *
+ * Two jobs, both kept out of the run loop so they are testable without
+ * launching a browser: deciding whether a run needs a driver at all (and
+ * failing early, with instructions, when it does and cannot have one), and
+ * making the driver's optional isolation and diagnostics safe to call
+ * unconditionally.
+ */
+import type { ScenarioBrowserFailure, ScenarioBrowserProvider } from '@pikku/core/workflow';
+import type { ScenarioActorConfig } from '@pikku/core/services';
+/** The default driver, used when a project names no other. */
+export declare const DEFAULT_BROWSER_DRIVER = "@pikku/playwright";
+export interface ScenarioBrowserDriverOptions {
+    secret: string;
+    actors: Record<string, ScenarioActorConfig>;
+    signInPath?: string;
+    failureDir?: string;
+    config: unknown;
+}
+/**
+ * What a browser driver package exports.
+ *
+ * Nothing here is playwright-specific: a driver is anything that can hand a
+ * scenario step a `ScenarioBrowserProvider`. `@pikku/playwright` is the one
+ * pikku ships, named by `scenarios.browserDriver` only as a default.
+ */
+export interface ScenarioBrowserDriver {
+    createScenarioBrowserProvider?: (options: ScenarioBrowserDriverOptions) => ScenarioBrowserProvider;
+    /** The class form the bundled driver exports. */
+    PlaywrightScenarioBrowserProvider?: new (options: ScenarioBrowserDriverOptions) => ScenarioBrowserProvider;
+    /** Driver-specific config (headed, slowMo, timeouts) resolved from the env. */
+    browserConfigFromEnv?: (overrides: {
+        appUrl: string;
+        apiUrl: string;
+    }) => unknown;
+}
+export interface ResolveScenarioBrowserProviderOptions {
+    /** The environment name, for error messages that tell the user what to edit. */
+    environment: string;
+    apiUrl: string;
+    appUrl?: string;
+    secret: string;
+    actors: Record<string, ScenarioActorConfig>;
+    signInPath?: string;
+    /** Where failure screenshots are written. */
+    failureDir: string;
+    /** The scenarios that declared browser steps, named in the missing-driver error. */
+    browserScenarios: string[];
+    /** Package to drive the browser. Defaults to `@pikku/playwright`. */
+    driver?: string;
+    importDriver?: (specifier: string) => Promise<ScenarioBrowserDriver>;
+}
+/**
+ * Both failure modes here are discovered before the first scenario starts. A
+ * missing `appUrl` or an uninstalled driver found mid-run costs a whole run to
+ * learn about.
+ */
+export declare const resolveScenarioBrowserProvider: ({ environment, apiUrl, appUrl, secret, actors, signInPath, failureDir, browserScenarios, driver, importDriver, }: ResolveScenarioBrowserProviderOptions) => Promise<ScenarioBrowserProvider>;
+/**
+ * The three calls the run loop makes, safe against a run with no browser and
+ * against a driver that implements neither optional member.
+ */
+export interface ScenarioBrowserLifecycle {
+    reset(): Promise<void>;
+    captureFailure(label: string): Promise<ScenarioBrowserFailure[]>;
+    close(): Promise<void>;
+}
+export declare const scenarioBrowserLifecycle: (provider: ScenarioBrowserProvider | undefined) => ScenarioBrowserLifecycle;

package/dist/src/functions/commands/scenario-browser.js

@@ -0,0 +1,60 @@
+/** The default driver, used when a project names no other. */
+export const DEFAULT_BROWSER_DRIVER = '@pikku/playwright';
+/**
+ * Both failure modes here are discovered before the first scenario starts. A
+ * missing `appUrl` or an uninstalled driver found mid-run costs a whole run to
+ * learn about.
+ */
+export const resolveScenarioBrowserProvider = async ({ environment, apiUrl, appUrl, secret, actors, signInPath, failureDir, browserScenarios, driver = DEFAULT_BROWSER_DRIVER, importDriver = (specifier) => import(specifier), }) => {
+    if (!appUrl) {
+        throw new Error(`Scenario environment '${environment}' has browser steps but no 'appUrl'. ` +
+            `Add it to scenarios.environments.${environment} in pikku.config.json, or run with --no-browser to skip them.`);
+    }
+    const module = await importDriver(driver).catch(() => {
+        const install = driver === DEFAULT_BROWSER_DRIVER
+            ? `Run 'yarn add -D ${driver} @playwright/test'`
+            : `Install '${driver}', or point scenarios.browserDriver at a package that is`;
+        throw new Error(`Scenarios ${browserScenarios.join(', ')} declare browser steps but '${driver}' could not be loaded. ` +
+            `${install}, or run with --no-browser to skip them.`);
+    });
+    const options = {
+        secret,
+        actors,
+        signInPath,
+        failureDir,
+        config: module.browserConfigFromEnv?.({ appUrl, apiUrl }) ?? {
+            appUrl,
+            apiUrl,
+        },
+    };
+    if (module.createScenarioBrowserProvider) {
+        return module.createScenarioBrowserProvider(options);
+    }
+    if (module.PlaywrightScenarioBrowserProvider) {
+        return new module.PlaywrightScenarioBrowserProvider(options);
+    }
+    throw new Error(`'${driver}' is not a scenario browser driver: it exports neither ` +
+        `'createScenarioBrowserProvider' nor a provider class. A driver returns an object with ` +
+        `sessionFor() and close(), and optionally reset() and captureFailure().`);
+};
+export const scenarioBrowserLifecycle = (provider) => ({
+    // Deliberately NOT swallowed: a browser that cannot be reset would run the
+    // next scenario against the last one's session, and a scenario failing on
+    // its reset is far easier to diagnose than one failing on stale state.
+    reset: async () => {
+        await provider?.reset?.();
+    },
+    captureFailure: async (label) => {
+        try {
+            return (await provider?.captureFailure?.(label)) ?? [];
+        }
+        catch {
+            // This runs while a scenario is already failing. Whatever went wrong
+            // here matters less than the error we were called to describe.
+            return [];
+        }
+    },
+    close: async () => {
+        await provider?.close();
+    },
+});

package/dist/src/functions/commands/scenario-formatter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The scenario run report, and how it is rendered.
+ *
+ * Everything a run prints goes through here, so the shape of the output is one
+ * file rather than log calls scattered through the command. The report itself
+ * is plain serialisable data — no Maps, no meta handles — which is what makes a
+ * second formatter (JSON, JUnit) a matter of writing one function rather than
+ * unpicking the runner.
+ */
+import type { ScenarioBrowserFailure } from '@pikku/core/workflow';
+/** The longest gherkin keyword ("Given"), so sentences line up under each other. */
+declare const KEYWORD_WIDTH = 5;
+/** One step of a run, already joined to the prose that declared it. */
+export interface ScenarioStepRow {
+    sentence: string;
+    status: string;
+    durationMs?: number;
+    error?: string;
+}
+/** Everything known about why one scenario failed. */
+export interface ScenarioFailureDetail {
+    /** The rendered sentence of the failing step; absent if no step failed. */
+    sentence?: string;
+    message: string;
+    stack?: string;
+    /**
+     * True when the failure was a deliberate one (a PikkuError). Its message is
+     * the whole story, so the stack is noise.
+     */
+    expected?: boolean;
+    browser?: ScenarioBrowserFailure[];
+}
+export interface ScenarioResult {
+    name: string;
+    status: 'passed' | 'failed';
+    durationMs: number;
+    output?: unknown;
+    error?: string;
+    steps?: ScenarioStepRow[];
+    failure?: ScenarioFailureDetail;
+}
+/** One scenario that was not run, and why. */
+export interface ScenarioSkip {
+    name: string;
+    reason: string;
+}
+export interface ScenarioRunReport {
+    environment: string;
+    results: ScenarioResult[];
+    /**
+     * Scenarios not run at all, each carrying why. A skip is only useful if the
+     * reader can tell a browser scenario held back by `--no-browser` from one the
+     * project itself quarantined, so the reason travels with the name rather than
+     * being assumed by the formatter.
+     */
+    skipped: ScenarioSkip[];
+    /** Feature-level hook failures, which belong to no single scenario. */
+    hookFailures: string[];
+}
+export interface ScenarioReportLine {
+    level: 'info' | 'error';
+    text: string;
+}
+export interface FormatScenarioReportOptions {
+    /** Keep every stack frame, including the framework's own. */
+    trace?: boolean;
+    /** Frames under this directory are the project's own. */
+    projectRoot?: string;
+}
+export declare const formatScenarioReport: (report: ScenarioRunReport, options?: FormatScenarioReportOptions) => ScenarioReportLine[];
+export declare const buildStepLadder: (steps: ScenarioStepRow[]) => string[];
+/**
+ * The indented block printed under a failed scenario's ladder.
+ *
+ * One line of `run.error.message` is what a browser step's "Timed out waiting
+ * for selector" looks like with all of its context removed. The page's own
+ * console errors and failed API calls almost always say why the selector never
+ * appeared, and the driver has been collecting them all along.
+ */
+export declare const formatScenarioFailure: (failure: ScenarioFailureDetail, { trace, projectRoot }?: FormatScenarioReportOptions) => string[];
+export { KEYWORD_WIDTH };

package/dist/src/functions/commands/scenario-formatter.js

@@ -0,0 +1,120 @@
+/** The longest gherkin keyword ("Given"), so sentences line up under each other. */
+const KEYWORD_WIDTH = 5;
+export const formatScenarioReport = (report, options = {}) => {
+    const lines = [];
+    const info = (text) => lines.push({ level: 'info', text });
+    const error = (text) => lines.push({ level: 'error', text });
+    for (const { name, reason } of report.skipped) {
+        info(`SKIP ${name} (${reason})`);
+    }
+    for (const result of report.results) {
+        if (result.status === 'passed') {
+            const output = result.output !== undefined ? ` → ${JSON.stringify(result.output)}` : '';
+            info(`PASS ${result.name} (${result.durationMs}ms)${output}`);
+        }
+        else {
+            error(`FAIL ${result.name} (${result.durationMs}ms): ${firstLine(result.error)}`);
+        }
+        for (const line of buildStepLadder(result.steps ?? [])) {
+            info(line);
+        }
+        if (result.failure) {
+            for (const line of formatScenarioFailure(result.failure, options)) {
+                error(line);
+            }
+        }
+    }
+    for (const hookFailure of report.hookFailures) {
+        error(hookFailure);
+    }
+    const failed = report.results.filter((r) => r.status === 'failed').length;
+    const skippedSuffix = report.skipped.length
+        ? `, ${report.skipped.length} skipped`
+        : '';
+    const hookSuffix = report.hookFailures.length
+        ? `, ${report.hookFailures.length} feature hook failure(s)`
+        : '';
+    info(`${report.results.length - failed}/${report.results.length} scenarios passed against '${report.environment}'${skippedSuffix}${hookSuffix}`);
+    return lines;
+};
+export const buildStepLadder = (steps) => {
+    const width = Math.max(0, ...steps.map(({ sentence }) => sentence.length));
+    return steps.map((step) => {
+        const glyph = step.status === 'succeeded' ? '✓' : '✗';
+        const detail = step.status === 'succeeded' || !step.error
+            ? formatDuration(step.durationMs)
+            : firstLine(step.error);
+        return `  ${step.sentence.padEnd(width)}  ${glyph}  ${detail}`;
+    });
+};
+/**
+ * The one line a summary gets. A browser timeout's message carries its whole
+ * call log; the failure block below prints all of it, so the row above only
+ * needs enough to recognise it by.
+ */
+const firstLine = (message) => (message ?? '').split('\n')[0] ?? '';
+/**
+ * The indented block printed under a failed scenario's ladder.
+ *
+ * One line of `run.error.message` is what a browser step's "Timed out waiting
+ * for selector" looks like with all of its context removed. The page's own
+ * console errors and failed API calls almost always say why the selector never
+ * appeared, and the driver has been collecting them all along.
+ */
+export const formatScenarioFailure = (failure, { trace = false, projectRoot } = {}) => {
+    const lines = [];
+    if (failure.sentence) {
+        lines.push(`  ✗ failed at: ${failure.sentence}`);
+    }
+    for (const line of failure.message.split('\n')) {
+        lines.push(`    ${line}`);
+    }
+    for (const browser of failure.browser ?? []) {
+        lines.push(`    browser (${browser.actor})${browser.url ? `: ${browser.url}` : ''}`);
+        const detail = (label, values) => {
+            for (const value of values) {
+                lines.push(`      ${`${label}:`.padEnd(11)} ${value}`);
+            }
+        };
+        detail('console', browser.consoleErrors);
+        detail('page', browser.pageErrors);
+        detail('request', browser.failedRequests);
+        detail('api', browser.apiErrors);
+        if (browser.screenshot) {
+            lines.push(`      screenshot: ${browser.screenshot}`);
+        }
+    }
+    // An expected failure is a deliberate one — where it was thrown from adds
+    // nothing the message and the ladder do not already say.
+    if (failure.stack && !failure.expected) {
+        for (const frame of stackFrames(failure.stack, trace, projectRoot)) {
+            lines.push(`    ${frame}`);
+        }
+    }
+    return lines;
+};
+/**
+ * The project's own frames — the ones a reader can act on. Framework and node
+ * internals are dropped unless `trace`, or unless dropping them would leave
+ * nothing at all: some stack always beats no stack.
+ */
+const stackFrames = (stack, trace, projectRoot) => {
+    const frames = stack
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('at '));
+    if (trace || !projectRoot) {
+        return frames;
+    }
+    const own = frames.filter((frame) => frame.includes(projectRoot) && !frame.includes('node_modules'));
+    return own.length > 0 ? own : frames;
+};
+const formatDuration = (durationMs) => {
+    if (durationMs === undefined) {
+        return '';
+    }
+    return durationMs < 1000
+        ? `${durationMs}ms`
+        : `${(durationMs / 1000).toFixed(1)}s`;
+};
+export { KEYWORD_WIDTH };

package/dist/src/functions/commands/scenario-ladder.d.ts

@@ -0,0 +1,66 @@
+import type { ScenarioStepPhase } from '@pikku/core/workflow';
+import type { WorkflowStepMeta } from '@pikku/core/workflow/types';
+import type { FunctionsMeta } from '@pikku/core';
+import type { ScenarioFailureDetail, ScenarioStepRow } from './scenario-formatter.js';
+export interface ScenarioStepProse {
+    phase: ScenarioStepPhase;
+    description: string;
+    template?: string;
+    actor?: string;
+}
+export interface ScenarioStepOutcome {
+    stepName: string;
+    status: string;
+    durationMs?: number;
+    error?: string;
+    /** The failing error's stack, as recorded on the run. */
+    stack?: string;
+    /**
+     * True when the failure was a deliberate one (a PikkuError). Its message is
+     * the whole story, so the stack is noise.
+     */
+    expected?: boolean;
+    /** The input this step was called with, as recorded on the run. */
+    input?: unknown;
+    /** The step function that ran it, as recorded on the run. */
+    stepFunc?: string;
+}
+/**
+ * One scenario's prose, indexed the two ways a run step can be joined back to
+ * its declaration.
+ */
+export interface ScenarioProse {
+    byStepName: Map<string, ScenarioStepProse>;
+    /**
+     * The same prose keyed by step function, for steps whose durable name the
+     * static meta cannot predict: a step called in a loop is declared as
+     * `sees ${packageName}` and reaches the run as `sees @pikku/addon-todos`.
+     *
+     * A function called from several sites that do not agree on their prose is
+     * left out rather than guessed at — such a step falls back to its bare name,
+     * which is what it did before this index existed.
+     */
+    byStepFunc: Map<string, ScenarioStepProse>;
+}
+/**
+ * Build `durable step name → prose parts` for one scenario.
+ *
+ * Description precedence matches the runtime: the call site's `description`
+ * wins, then the step's own declared `description`, then the positional step
+ * name. A step's `template` is carried alongside and, when it exists, is what
+ * actually gets rendered — filled from the input recorded on the run.
+ */
+export declare const collectScenarioStepProse: (workflowMeta: {
+    steps?: WorkflowStepMeta[];
+} | undefined, functionsMeta: FunctionsMeta) => ScenarioProse;
+/** The step functions in this scenario that declare `browser: true`. */
+export declare const scenarioBrowserSteps: (workflowMeta: {
+    steps?: WorkflowStepMeta[];
+} | undefined, functionsMeta: FunctionsMeta) => string[];
+/** The run's steps as renderable rows, in the order they were recorded. */
+export declare const scenarioStepRows: (steps: ScenarioStepOutcome[], prose: ScenarioProse) => ScenarioStepRow[];
+/**
+ * Find the step a run died on and join it back to its declared prose, so a
+ * failure names the sentence a reader recognises rather than a durable key.
+ */
+export declare const scenarioFailureFromSteps: (steps: ScenarioStepOutcome[], prose: ScenarioProse) => ScenarioFailureDetail | undefined;

package/dist/src/functions/commands/scenario-ladder.js

@@ -0,0 +1,132 @@
+/**
+ * The scenario step ladder — joining a recorded run back to the English that
+ * declared it.
+ *
+ * Cucumber parsed English into calls; this recovers English out of the typed
+ * calls the inspector already recorded, joined against the run the engine
+ * already persisted. No engine change, no step-event bus. Layout of the result
+ * belongs to `scenario-formatter.ts`; this module only decides what each step
+ * is called.
+ */
+import { composeStepProse } from '@pikku/core/workflow';
+import { KEYWORD_WIDTH } from './scenario-formatter.js';
+/**
+ * Walk a workflow's steps — including the ones nested inside branches, fanouts
+ * and parallel groups — and yield every scenario step it declares.
+ */
+function* walkScenarioSteps(steps) {
+    if (!Array.isArray(steps)) {
+        return;
+    }
+    for (const step of steps) {
+        const node = step;
+        if (node?.type === 'scenarioStep') {
+            yield node;
+            continue;
+        }
+        yield* walkScenarioSteps(node?.children);
+        yield* walkScenarioSteps(node?.body);
+        yield* walkScenarioSteps(node?.steps);
+        yield* walkScenarioSteps(node?.then);
+        yield* walkScenarioSteps(node?.else);
+        for (const branch of Object.values(node?.cases ?? {})) {
+            yield* walkScenarioSteps(branch);
+        }
+    }
+}
+/**
+ * Build `durable step name → prose parts` for one scenario.
+ *
+ * Description precedence matches the runtime: the call site's `description`
+ * wins, then the step's own declared `description`, then the positional step
+ * name. A step's `template` is carried alongside and, when it exists, is what
+ * actually gets rendered — filled from the input recorded on the run.
+ */
+export const collectScenarioStepProse = (workflowMeta, functionsMeta) => {
+    const byStepName = new Map();
+    const byStepFunc = new Map();
+    const ambiguous = new Set();
+    for (const step of walkScenarioSteps(workflowMeta?.steps)) {
+        const stepMeta = functionsMeta[step.stepFunc];
+        const parts = {
+            phase: step.phase ?? 'step',
+            description: step.options?.description ?? stepMeta?.description ?? step.stepName,
+            // A call-site description is an explicit override, so it wins over the
+            // step's template the same way it wins over its description.
+            template: step.options?.description
+                ? undefined
+                : stepMeta?.scenarioStepTemplate,
+            actor: step.actor,
+        };
+        byStepName.set(step.stepName, parts);
+        const declared = byStepFunc.get(step.stepFunc);
+        if (declared && !sameProse(declared, parts)) {
+            ambiguous.add(step.stepFunc);
+        }
+        else {
+            byStepFunc.set(step.stepFunc, parts);
+        }
+    }
+    for (const stepFunc of ambiguous) {
+        byStepFunc.delete(stepFunc);
+    }
+    return { byStepName, byStepFunc };
+};
+const sameProse = (a, b) => a.phase === b.phase &&
+    a.description === b.description &&
+    a.template === b.template &&
+    a.actor === b.actor;
+/** The step functions in this scenario that declare `browser: true`. */
+export const scenarioBrowserSteps = (workflowMeta, functionsMeta) => {
+    const names = new Set();
+    for (const step of walkScenarioSteps(workflowMeta?.steps)) {
+        if (functionsMeta[step.stepFunc]?.scenarioStepBrowser === true) {
+            names.add(step.stepFunc);
+        }
+    }
+    return [...names];
+};
+/**
+ * Render one step's gherkin sentence.
+ *
+ * A repeated step is stored as `name#1`; its prose lives under the bare name.
+ * Only once neither name matches does the step function decide it, so a step
+ * recorded under the name it was declared with is never re-resolved by a
+ * function shared with another call site.
+ */
+const stepSentence = (step, prose) => {
+    const parts = prose.byStepName.get(step.stepName) ??
+        prose.byStepName.get(baseName(step.stepName)) ??
+        (step.stepFunc ? prose.byStepFunc.get(step.stepFunc) : undefined);
+    return parts
+        ? composeStepProse({
+            ...parts,
+            input: step.input,
+            keywordWidth: KEYWORD_WIDTH,
+        })
+        : `${''.padEnd(KEYWORD_WIDTH)} ${step.stepName}`;
+};
+/** The run's steps as renderable rows, in the order they were recorded. */
+export const scenarioStepRows = (steps, prose) => steps.map((step) => ({
+    sentence: stepSentence(step, prose),
+    status: step.status,
+    durationMs: step.durationMs,
+    error: step.error,
+}));
+const baseName = (stepName) => stepName.replace(/#\d+$/, '');
+/**
+ * Find the step a run died on and join it back to its declared prose, so a
+ * failure names the sentence a reader recognises rather than a durable key.
+ */
+export const scenarioFailureFromSteps = (steps, prose) => {
+    const failed = steps.find((step) => step.status !== 'succeeded');
+    if (!failed) {
+        return undefined;
+    }
+    return {
+        sentence: stepSentence(failed, prose).trimEnd(),
+        message: failed.error ?? `step status: ${failed.status}`,
+        stack: failed.stack,
+        expected: failed.expected,
+    };
+};