@pikku/cli 0.12.90 → 0.12.92

package/dist/src/fabric/functions/secrets-rotate.function.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export declare const FabricSecretsRotateInput: z.ZodObject<{
+    branch: z.ZodString;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const FabricSecretsRotateOutput: z.ZodObject<{
+    retiredKeyId: z.ZodString;
+}, z.core.$strip>;
+export declare const FabricSecretsRotate: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
+    branch: string;
+    force?: boolean | undefined;
+}, {
+    retiredKeyId: string;
+}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
+    branch: string;
+    force?: boolean | undefined;
+}, {
+    retiredKeyId: string;
+}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
+    branch: string;
+    force?: boolean | undefined;
+}, {
+    retiredKeyId: string;
+}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/secrets-rotate.function.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
+import { resolveApiContext } from '../lib/config.js';
+import { getFabricRPC } from '../lib/http.js';
+import { resolveStageId } from '../lib/stage.js';
+export const FabricSecretsRotateInput = z.object({
+    branch: z.string(),
+    force: z.boolean().optional(),
+});
+export const FabricSecretsRotateOutput = z.object({
+    retiredKeyId: z.string(),
+});
+export const FabricSecretsRotate = pikkuSessionlessFunc({
+    description: "Retire a stage's sealing key so the next deploy issues a new one. Secrets sealed to the old key must be set again.",
+    input: FabricSecretsRotateInput,
+    output: FabricSecretsRotateOutput,
+    func: async (_services, { branch, force }) => {
+        const ctx = await resolveApiContext();
+        if (!ctx.token)
+            throw new Error('Not logged in. Run `pikku fabric login` first.');
+        if (!ctx.projectId)
+            throw new Error('No fabric project linked. Run `pikku fabric link` first.');
+        if (!force) {
+            // Not a confirmation for politeness — this is the one operation here
+            // that destroys access to data. Fabric cannot read the sealed values, so
+            // it cannot carry them over, and nobody can undo it afterwards.
+            throw new Error(`Rotating the sealing key on ${branch} makes every secret already set on it unreadable — fabric cannot re-seal values it cannot open, so each one must be set again after the next deploy. Re-run with --force if that is what you want.`);
+        }
+        const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
+        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        const result = await rpc.invoke('rotateStageSealingKey', { stageId });
+        console.log(`[fabric] retired sealing key ${result.retiredKeyId} on ${branch}`);
+        console.log('[fabric] deploy the stage to issue a new key, then set its secrets again');
+        return result;
+    },
+});

package/dist/src/fabric/functions/secrets-set.function.d.ts

@@ -6,7 +6,8 @@ export declare const FabricSecretsSetInput: z.ZodObject<{
     force: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const FabricSecretsSetOutput: z.ZodObject<{
-    ok: z.ZodBoolean;
+    name: z.ZodString;
+    keyId: z.ZodString;
 }, z.core.$strip>;
 export declare const FabricSecretsSet: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
     name: string;
@@ -14,19 +15,22 @@ export declare const FabricSecretsSet: import("../../../.pikku/pikku-types.gen.j
     value?: string | undefined;
     force?: boolean | undefined;
 }, {
-    ok: boolean;
+    name: string;
+    keyId: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
     name: string;
     branch: string;
     value?: string | undefined;
     force?: boolean | undefined;
 }, {
-    ok: boolean;
+    name: string;
+    keyId: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
     name: string;
     branch: string;
     value?: string | undefined;
     force?: boolean | undefined;
 }, {
-    ok: boolean;
+    name: string;
+    keyId: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/secrets-set.function.js

@@ -3,15 +3,20 @@ import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
 import { resolveApiContext } from '../lib/config.js';
 import { getFabricRPC } from '../lib/http.js';
 import { promptSecret } from '../lib/prompt.js';
+import { resolveStageId } from '../lib/stage.js';
+import { seal, serializeSealedValue } from '../lib/sealed-box.js';
 export const FabricSecretsSetInput = z.object({
     name: z.string(),
     branch: z.string(),
     value: z.string().optional(),
     force: z.boolean().optional(),
 });
-export const FabricSecretsSetOutput = z.object({ ok: z.boolean() });
+export const FabricSecretsSetOutput = z.object({
+    name: z.string(),
+    keyId: z.string(),
+});
 export const FabricSecretsSet = pikkuSessionlessFunc({
-    description: 'Set a stage-scoped secret. Encrypted with the stage KEK and stored in the project D1.',
+    description: 'Set a stage-scoped secret. Sealed here to the stage public key — the plaintext never leaves this machine.',
     input: FabricSecretsSetInput,
     output: FabricSecretsSetOutput,
     func: async (_services, { name, branch, value }) => {
@@ -24,13 +29,19 @@ export const FabricSecretsSet = pikkuSessionlessFunc({
         if (!plaintext)
             throw new Error('Empty secret value — aborting.');
         const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
-        const result = await rpc.invoke('setStageSecret', {
-            projectId: ctx.projectId,
-            branch,
+        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        // Fabric holds only the public half of this keypair. The private half went
+        // to the stage's worker at deploy time and was dropped there, so the value
+        // sealed below can be opened by that worker and by nothing else — including
+        // by the fabric process that stores it.
+        const key = await rpc.invoke('getStageSealingKey', { stageId });
+        const sealed = seal(key.publicKey, key.keyId, plaintext);
+        const result = await rpc.invoke('setStageSealedSecret', {
+            stageId,
             name,
-            value: plaintext,
+            sealedValue: serializeSealedValue(sealed),
         });
-        console.log(`[fabric] ${name} set on ${branch}.`);
+        console.log(`[fabric] ${name} sealed to ${result.keyId} and set on ${branch}.`);
         return result;
     },
 });

package/dist/src/fabric/lib/http.d.ts

@@ -1,4 +1,10 @@
+/**
+ * Type-safe RPC client backed by the snapshot SDK in `../sdk/`. The map is
+ * a copy of fabric's generated rpc-map at the time of the addon's last
+ * release — versioning bumps are taken by republishing this package.
+ */
+import { PikkuRPC } from '../sdk/pikku-rpc.gen.js';
 export declare function getFabricRPC(opts: {
     apiUrl: string;
     token: string | null;
-}): any;
+}): PikkuRPC;

package/dist/src/fabric/lib/sealed-box.d.ts

@@ -0,0 +1,16 @@
+/** Algorithm tag carried by every sealed value. Must match fabric's. */
+export declare const SEALED_BOX_ALGORITHM = "sealed-x25519-v1";
+export interface SealedValue {
+    alg: typeof SEALED_BOX_ALGORITHM;
+    /** The `encryption_key` row whose public key sealed this. */
+    kid: string;
+    /** Ephemeral public key, SPKI DER as base64. */
+    epk: string;
+    iv: string;
+    ct: string;
+    tag: string;
+}
+/** Seal a value to a stage's public key. */
+export declare function seal(publicKey: string, keyId: string, plaintext: string): SealedValue;
+/** Wire form. Fabric stores exactly this string. */
+export declare function serializeSealedValue(sealed: SealedValue): string;

package/dist/src/fabric/lib/sealed-box.js

@@ -0,0 +1,72 @@
+/**
+ * Sealing a value to a stage's public key, here on the client.
+ *
+ * `pikku fabric secrets set` seals before it sends, so the plaintext never
+ * reaches fabric — not the ingress in front of it, not a request log, not the
+ * process handling the write. Fabric stores the sealed blob and hands it to the
+ * worker, which holds the only private key that opens it.
+ *
+ * This is the seal half of fabric's `sealed-x25519-v1`, and the two must stay
+ * byte-compatible: an ephemeral X25519 keypair, ECDH against the recipient,
+ * HKDF-SHA256 to a content key, AES-256-GCM to seal. Everything below is
+ * `node:crypto` on purpose — a sealing primitive that pulled in a dependency
+ * would be a supply-chain question sitting directly on the plaintext.
+ *
+ * There is deliberately no `unseal` here. The CLI has no private key and no
+ * business having one; opening a value happens in the worker.
+ */
+import { createCipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from 'node:crypto';
+/** Algorithm tag carried by every sealed value. Must match fabric's. */
+export const SEALED_BOX_ALGORITHM = 'sealed-x25519-v1';
+/** HKDF domain separator. Must match fabric's byte for byte. */
+const SEAL_SALT = 'pikkufabric/sealed-box/v1';
+/** Seal a value to a stage's public key. */
+export function seal(publicKey, keyId, plaintext) {
+    const recipient = importPublicKey(publicKey);
+    const ephemeral = generateKeyPairSync('x25519');
+    const epk = ephemeral.publicKey.export({ type: 'spki', format: 'der' });
+    const contentKey = deriveContentKey(diffieHellman({ privateKey: ephemeral.privateKey, publicKey: recipient }), epk, recipient.export({ type: 'spki', format: 'der' }));
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', contentKey, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    return {
+        alg: SEALED_BOX_ALGORITHM,
+        kid: keyId,
+        epk: epk.toString('base64'),
+        iv: iv.toString('base64'),
+        ct: ct.toString('base64'),
+        tag: cipher.getAuthTag().toString('base64'),
+    };
+}
+/** Wire form. Fabric stores exactly this string. */
+export function serializeSealedValue(sealed) {
+    return JSON.stringify(sealed);
+}
+/**
+ * Both public keys go into the HKDF `info`, which is what stops a sealed value
+ * being redirected: change either the ephemeral key or the recipient and the
+ * derived content key changes with it.
+ */
+function deriveContentKey(shared, epk, recipientPublic) {
+    return Buffer.from(hkdfSync('sha256', shared, Buffer.from(SEAL_SALT), Buffer.concat([epk, recipientPublic]), 32));
+}
+function importPublicKey(publicKey) {
+    let key;
+    try {
+        key = createPublicKey({
+            key: Buffer.from(publicKey, 'base64'),
+            type: 'spki',
+            format: 'der',
+        });
+    }
+    catch (error) {
+        throw new Error(`Not a valid X25519 public key (${error instanceof Error ? error.message : String(error)})`);
+    }
+    // A public key of the wrong curve would still ECDH, just against a key the
+    // stage's worker cannot match — the failure would surface as an unopenable
+    // secret much later, so refuse it at the point the type is still knowable.
+    if (key.asymmetricKeyType !== 'x25519') {
+        throw new Error(`Stage sealing key is ${key.asymmetricKeyType}, expected x25519 — this CLI is too old for it, run \`npm i -g @pikku/cli\``);
+    }
+    return key;
+}

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

@@ -11,9 +11,11 @@ import { LocalContent, } from '@pikku/core/services/local-content';
 import { InMemorySchedulerService } from '@pikku/schedule';
 import { resolveDb, createKysely, parseDatabaseUrl, } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
+import { registerScenarioInstrumentation } from '../wirings/scenarios/register-scenario-instrumentation.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 }) => {
@@ -114,6 +116,14 @@ export const dev = pikkuSessionlessFunc({
             return;
         }
         await loadUserBootstrap(pikkuDir);
+        // Scenario instrumentation exists only on a development server: the runner
+        // calls it over RPC to reset and snapshot coverage and stub calls. It is
+        // registered here, after the app bootstrap, rather than generated into the
+        // project — an app bootstrap is what a deployed bundle imports, and coverage
+        // endpoints have no business in one.
+        if (config.scaffold?.scenarios) {
+            registerScenarioInstrumentation(config.scaffold.scenarios === 'auth');
+        }
         const configModule = await loadUserModule(pikkuConfigFactory.file);
         const servicesModule = await loadUserModule(singletonServicesFactory.file);
         const userCreateConfig = configModule[pikkuConfigFactory.variable];
@@ -238,6 +248,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,18 @@ 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,
+            join(config.scenarioSchemaDirectory, 'register.gen.ts'),
+            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,84 @@
+/**
+ * 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.
+     *
+     * A driver may resolve `appUrl` itself when the caller passes none — that is
+     * how a target known only at run time (a sandbox hostname in the env) is
+     * reached without a config file per deployment. A driver that answers with a
+     * placeholder rather than a real target must say so with
+     * `appUrlSource: 'default'`, which the runner reports as a missing appUrl.
+     */
+    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.
+ *
+ * `appUrl` is checked after the driver has resolved its config rather than
+ * before, so a driver that knows the target from its own environment (a
+ * sandbox hostname) is allowed to supply it. The check is not dropped: a driver
+ * reporting `appUrlSource: 'default'` resolved nothing and fails the same way,
+ * because a run against a placeholder URL is worse than one that refuses to
+ * start.
+ */
+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,68 @@
+/** 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.
+ *
+ * `appUrl` is checked after the driver has resolved its config rather than
+ * before, so a driver that knows the target from its own environment (a
+ * sandbox hostname) is allowed to supply it. The check is not dropped: a driver
+ * reporting `appUrlSource: 'default'` resolved nothing and fails the same way,
+ * because a run against a placeholder URL is worse than one that refuses to
+ * start.
+ */
+export const resolveScenarioBrowserProvider = async ({ environment, apiUrl, appUrl, secret, actors, signInPath, failureDir, browserScenarios, driver = DEFAULT_BROWSER_DRIVER, importDriver = (specifier) => import(specifier), }) => {
+    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 config = (module.browserConfigFromEnv?.({ appUrl, apiUrl }) ?? {
+        appUrl,
+        apiUrl,
+    });
+    if (!config.appUrl || config.appUrlSource === 'default') {
+        throw new Error(`Scenario environment '${environment}' has browser steps but no 'appUrl', and '${driver}' resolved none from the environment. ` +
+            `Add it to scenarios.environments.${environment} in pikku.config.json, pass --app-url for a target that only exists at run time, or run with --no-browser to skip them.`);
+    }
+    const options = {
+        secret,
+        actors,
+        signInPath,
+        failureDir,
+        config,
+    };
+    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-environment.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Resolving `pikku scenario run <environment>` to the URLs the run targets.
+ *
+ * The configured environment is the base; `--api-url`/`--app-url` override it
+ * for one invocation, which is what makes a suite runnable against a target
+ * that only exists at run time (a freshly provisioned sandbox) without writing
+ * a pikku.config.json per deployment.
+ */
+/** One entry of `scenarios.environments` in pikku.config.json. */
+export interface ScenarioEnvironment {
+    apiUrl: string;
+    signInPath?: string;
+    rpcPath?: string;
+    appUrl?: string;
+}
+export interface ResolveScenarioEnvironmentOptions {
+    /** The name given on the command line. Must exist in config. */
+    environment: string;
+    environments: Record<string, ScenarioEnvironment>;
+    /** `--api-url`, overriding the configured `apiUrl`. */
+    apiUrl?: string;
+    /** `--app-url`, overriding the configured `appUrl`. */
+    appUrl?: string;
+    /** `--spawn`, which is only coherent against a local `apiUrl`. */
+    spawn?: boolean;
+}
+/**
+ * Applied once, so actors, step env, the browser driver and the spawned server
+ * all see the same target. The environment is still looked up by name: the
+ * flags override fields on a configured environment, they do not invent one.
+ */
+export declare const resolveScenarioEnvironment: ({ environment, environments, apiUrl, appUrl, spawn, }: ResolveScenarioEnvironmentOptions) => ScenarioEnvironment;

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

@@ -0,0 +1,61 @@
+/**
+ * Resolving `pikku scenario run <environment>` to the URLs the run targets.
+ *
+ * The configured environment is the base; `--api-url`/`--app-url` override it
+ * for one invocation, which is what makes a suite runnable against a target
+ * that only exists at run time (a freshly provisioned sandbox) without writing
+ * a pikku.config.json per deployment.
+ */
+const LOCAL_HOSTNAMES = new Set([
+    'localhost',
+    '127.0.0.1',
+    '0.0.0.0',
+    '::1',
+    '[::1]',
+]);
+/**
+ * Absolute URLs only: the value is concatenated with paths (`${apiUrl}/rpc`)
+ * and parsed by the spawn path, so a relative one fails far from its cause.
+ */
+const assertAbsoluteUrl = (flag, value) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${flag} '${value}' is not a valid absolute URL — pass one including the scheme, e.g. ${flag} https://sandbox-a1b2.example.com/api`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`${flag} '${value}' must be an http(s) URL, not '${url.protocol.replace(':', '')}'.`);
+    }
+    return url;
+};
+/**
+ * Applied once, so actors, step env, the browser driver and the spawned server
+ * all see the same target. The environment is still looked up by name: the
+ * flags override fields on a configured environment, they do not invent one.
+ */
+export const resolveScenarioEnvironment = ({ environment, environments, apiUrl, appUrl, spawn = false, }) => {
+    const configured = environments[environment];
+    if (!configured) {
+        const known = Object.keys(environments);
+        throw new Error(`Unknown scenario environment '${environment}'. ` +
+            (known.length
+                ? `Configured environments: ${known.join(', ')}`
+                : `Add scenarios.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
+    }
+    const resolved = { ...configured };
+    if (apiUrl !== undefined) {
+        const url = assertAbsoluteUrl('--api-url', apiUrl);
+        if (spawn && !LOCAL_HOSTNAMES.has(url.hostname)) {
+            throw new Error(`--spawn starts a server on this machine, but --api-url points at '${url.hostname}'. ` +
+                `Drop --spawn to run against an already-serving target, or point --api-url at localhost.`);
+        }
+        resolved.apiUrl = apiUrl;
+    }
+    if (appUrl !== undefined) {
+        assertAbsoluteUrl('--app-url', appUrl);
+        resolved.appUrl = appUrl;
+    }
+    return resolved;
+};