@pikku/cli 0.12.91 → 0.12.92

package/dist/src/fabric/fabric-commands.d.ts

@@ -451,37 +451,65 @@ export declare const fabricCommands: {
                 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>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
             list: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
+            }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
+            rotate: import("@pikku/core/cli").CoreCLICommandConfig<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>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
         };
     };
@@ -622,21 +650,21 @@ export declare const fabricCommands: {
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
             add: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;
                 cnameTarget: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;
                 cnameTarget: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;

package/dist/src/fabric/fabric-commands.js

@@ -31,6 +31,7 @@ import { FabricDbSchema, renderDbSchema, } from './functions/db-schema.function.
 import { FabricRollback } from './functions/rollback.function.js';
 import { FabricSecretsSet } from './functions/secrets-set.function.js';
 import { FabricSecretsList } from './functions/secrets-list.function.js';
+import { FabricSecretsRotate } from './functions/secrets-rotate.function.js';
 import { FabricLogs } from './functions/logs.function.js';
 import { FabricMetrics } from './functions/metrics.function.js';
 import { FabricTrace } from './functions/trace.function.js';
@@ -241,6 +242,17 @@ export const fabricCommands = defineCLICommands({
                     json: { description: 'Machine-readable output', default: false },
                 },
             }),
+            rotate: pikkuCLICommand({
+                func: FabricSecretsRotate,
+                description: "Retire a stage's sealing key (secrets must be set again)",
+                options: {
+                    branch: { description: 'Target branch', short: 'b' },
+                    force: {
+                        description: 'Confirm that existing secrets become unreadable',
+                        default: false,
+                    },
+                },
+            }),
         },
     },
     logs: pikkuCLICommand({

package/dist/src/fabric/functions/domains-add.function.d.ts

@@ -2,8 +2,8 @@ import { z } from 'zod';
 export declare const FabricDomainsAddInput: z.ZodObject<{
     hostname: z.ZodString;
     target: z.ZodOptional<z.ZodEnum<{
-        api: "api";
         app: "app";
+        api: "api";
     }>>;
     apiUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -13,21 +13,21 @@ export declare const FabricDomainsAddOutput: z.ZodObject<{
 }, z.core.$strip>;
 export declare const FabricDomainsAdd: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;
     cnameTarget: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;
     cnameTarget: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;

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

@@ -4,21 +4,33 @@ export declare const FabricSecretsListInput: z.ZodObject<{
     json: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const FabricSecretsListOutput: z.ZodObject<{
-    names: z.ZodArray<z.ZodString>;
+    secrets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const FabricSecretsList: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>;

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

@@ -2,13 +2,16 @@ 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 FabricSecretsListInput = z.object({
     branch: z.string(),
     json: z.boolean().optional(),
 });
-export const FabricSecretsListOutput = z.object({ names: z.array(z.string()) });
+export const FabricSecretsListOutput = z.object({
+    secrets: z.array(z.object({ name: z.string(), updatedAt: z.string() })),
+});
 export const FabricSecretsList = pikkuSessionlessFunc({
-    description: 'List secret names visible to a stage (values never leave the server).',
+    description: 'List the secrets set on a stage, by name. Values are sealed to the stage and never leave it.',
     input: FabricSecretsListInput,
     output: FabricSecretsListOutput,
     func: async (_services, { branch, json }) => {
@@ -18,19 +21,18 @@ export const FabricSecretsList = pikkuSessionlessFunc({
         if (!ctx.projectId)
             throw new Error('No fabric project linked. Run `pikku fabric link` first.');
         const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
-        const result = await rpc.invoke('listStageSecrets', {
-            projectId: ctx.projectId,
-            branch,
-        });
+        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        const result = await rpc.invoke('listStageSecretNames', { stageId });
         if (json) {
-            console.log(JSON.stringify({ branch, names: result.names }, null, 2));
+            console.log(JSON.stringify({ branch, secrets: result.secrets }, null, 2));
         }
-        else if (result.names.length === 0) {
+        else if (result.secrets.length === 0) {
             console.log(`[fabric] no secrets set on ${branch}`);
         }
         else {
-            for (const name of result.names)
-                console.log(name);
+            for (const { name, updatedAt } of result.secrets) {
+                console.log(`${name}\t${updatedAt}`);
+            }
         }
         return result;
     },

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,6 +11,7 @@ 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';
@@ -115,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];

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

@@ -70,6 +70,7 @@ export const pikkuBootstrap = pikkuSessionlessFunc({
         // in place however this module is reached.
         const scenarioBootstrapImports = [
             config.bootstrapFile,
+            join(config.scenarioSchemaDirectory, 'register.gen.ts'),
             config.scenarioStepsMetaFile,
             config.scenarioStepsFile,
             config.scenarioWiringsMetaFile,

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

@@ -29,9 +29,17 @@ 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. */
+    /**
+     * 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;
+        appUrl?: string;
         apiUrl: string;
     }) => unknown;
 }
@@ -55,6 +63,13 @@ export interface ResolveScenarioBrowserProviderOptions {
  * 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>;
 /**

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

@@ -4,12 +4,15 @@ 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), }) => {
-    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'`
@@ -17,15 +20,20 @@ export const resolveScenarioBrowserProvider = async ({ environment, apiUrl, appU
         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: module.browserConfigFromEnv?.({ appUrl, apiUrl }) ?? {
-            appUrl,
-            apiUrl,
-        },
+        config,
     };
     if (module.createScenarioBrowserProvider) {
         return module.createScenarioBrowserProvider(options);

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;