@pikku/cli 0.12.91 → 0.12.93

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/knowledge-index.d.ts

@@ -0,0 +1,30 @@
+import { renderKnowledgeIndex } from '../knowledge/render.js';
+export declare const knowledgeIndex: import("#pikku").PikkuFunctionConfig<{
+    check?: boolean | undefined;
+}, {
+    ok: boolean;
+    check: boolean;
+    files: {
+        path: string;
+        action: "unchanged" | "created" | "updated";
+    }[];
+}, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    check?: boolean | undefined;
+}, {
+    ok: boolean;
+    check: boolean;
+    files: {
+        path: string;
+        action: "unchanged" | "created" | "updated";
+    }[];
+}, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    check?: boolean | undefined;
+}, {
+    ok: boolean;
+    check: boolean;
+    files: {
+        path: string;
+        action: "unchanged" | "created" | "updated";
+    }[];
+}, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export { renderKnowledgeIndex };

package/dist/src/functions/commands/knowledge-index.js

@@ -0,0 +1,11 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { runKnowledgeIndex } from '@pikku/knowledge';
+import { renderKnowledgeIndex } from '../knowledge/render.js';
+import { KnowledgeIndexInputSchema, KnowledgeIndexOutputSchema, } from '../knowledge/schemas.js';
+export const knowledgeIndex = pikkuSessionlessFunc({
+    description: "Refresh every index.md so each section lists the notes actually in it, replacing only the generated block and leaving each index's prose alone.",
+    input: KnowledgeIndexInputSchema,
+    output: KnowledgeIndexOutputSchema,
+    func: async ({ config }, { check }) => runKnowledgeIndex(config.rootDir, check ?? false),
+});
+export { renderKnowledgeIndex };

package/dist/src/functions/commands/knowledge-validate.d.ts

@@ -0,0 +1,33 @@
+import { renderKnowledgeValidate } from '../knowledge/render.js';
+export declare const knowledgeValidate: import("#pikku").PikkuFunctionConfig<Record<string, never>, {
+    ok: boolean;
+    notes: number;
+    findings: {
+        id: string;
+        severity: "warn" | "error" | "info";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<Record<string, never>, {
+    ok: boolean;
+    notes: number;
+    findings: {
+        id: string;
+        severity: "warn" | "error" | "info";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<Record<string, never>, {
+    ok: boolean;
+    notes: number;
+    findings: {
+        id: string;
+        severity: "warn" | "error" | "info";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export { renderKnowledgeValidate };

package/dist/src/functions/commands/knowledge-validate.js

@@ -0,0 +1,11 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { runKnowledgeValidate } from '@pikku/knowledge';
+import { renderKnowledgeValidate } from '../knowledge/render.js';
+import { KnowledgeValidateInputSchema, KnowledgeValidateOutputSchema, } from '../knowledge/schemas.js';
+export const knowledgeValidate = pikkuSessionlessFunc({
+    description: 'Check the knowledge base against the app-project profile: every note typed, every section indexed, every slice gated, and every resource: pointing at something that still exists.',
+    input: KnowledgeValidateInputSchema,
+    output: KnowledgeValidateOutputSchema,
+    func: async ({ config }) => runKnowledgeValidate(config.rootDir, config.outDir),
+});
+export { renderKnowledgeValidate };

package/dist/src/functions/commands/new-addon.d.ts

@@ -9,6 +9,24 @@
  * the only option there.
  */
 export declare function resolveAddonDepProtocol(baseDir: string): string;
+export interface AddonVars {
+    name: string;
+    camelName: string;
+    pascalName: string;
+    screamingName: string;
+    displayName: string;
+    description: string;
+    category: string;
+    addonDepProtocol: string;
+}
+export declare function getAddonFiles(vars: AddonVars, flags: {
+    secret: boolean;
+    variable: boolean;
+    oauth: boolean;
+    credential?: 'apikey' | 'bearer' | 'oauth2';
+    /** Delegated login: credential is the upstream token + expiry, checked per call. */
+    delegated?: boolean;
+}): Record<string, string>;
 export declare const pikkuNewAddon: import("#pikku").PikkuFunctionConfig<{
     name: string;
     displayName?: string;

package/dist/src/functions/commands/new-addon.js

@@ -110,7 +110,23 @@ function sanitizeAddonName(raw) {
         name = `x${name}`;
     return name || raw;
 }
-function getAddonFiles(vars, flags) {
+/**
+ * `--display-name` and `--description` are free-form prose, so an apostrophe in
+ * them is ordinary — "Bob's CRM". `JSON.stringify` emits a valid, escaped
+ * string literal; interpolating the raw text into a quoted one terminates the
+ * string and the scaffolded file no longer parses. Prose composed with other
+ * words is stringified as a whole, not swapped in place.
+ */
+const literal = (value) => JSON.stringify(value);
+/**
+ * The same prose inside a generated template literal, where a backtick or a
+ * `${` opens an interpolation rather than ending the string — so the emitted
+ * message keeps its own `\${response.status}` holes.
+ */
+const inTemplate = (value) => value.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+/** The same prose on a `//` comment line, where a newline ends the comment. */
+const inComment = (value) => value.replace(/\s+/g, ' ').trim();
+export function getAddonFiles(vars, flags) {
     const { name, camelName, pascalName, screamingName, displayName, description, category, } = vars;
     const files = {};
     // package.json
@@ -205,7 +221,7 @@ ${description}
 6. Build: \`yarn install && yarn pikku && yarn build\`
 `;
     // src/index.ts
-    files['src/index.ts'] = `// ${displayName} functions
+    files['src/index.ts'] = `// ${inComment(displayName)} functions
 // export { ${camelName}Operation } from './functions/operation.function.js'
 `;
     // src/services.ts
@@ -224,10 +240,10 @@ export const createWireServices = pikkuAddonWireServices(
     }
     const cred = await wire.getCredential<{ token: string; expiresAt?: number }>('${camelName}')
     if (!cred?.token) {
-      throw new UnauthorizedError('No ${displayName} session — sign in again')
+      throw new UnauthorizedError(${literal(`No ${displayName} session — sign in again`)})
     }
     if (cred.expiresAt && cred.expiresAt * 1000 < Date.now()) {
-      throw new UnauthorizedError('${displayName} session expired — sign in again')
+      throw new UnauthorizedError(${literal(`${displayName} session expired — sign in again`)})
     }
     const ${camelName} = new ${pascalName}Service(cred, variables)
 
@@ -275,7 +291,7 @@ export const createWireServices = pikkuAddonWireServices(
     }
     const cred = await wire.getCredential<{ accessToken: string }>('${camelName}')
     if (!cred?.accessToken) {
-      throw new UnauthorizedError('No ${displayName} connection — connect ${displayName} first')
+      throw new UnauthorizedError(${literal(`No ${displayName} connection — connect ${displayName} first`)})
     }
     const ${camelName} = new ${pascalName}Service(cred, variables)
 
@@ -363,7 +379,7 @@ export class ${pascalName}Service {
 
     if (!response.ok) {
       const errorText = await response.text()
-      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)
+      throw new Error(\`${inTemplate(displayName)} API error (\${response.status}): \${errorText}\`)
     }
 
     return response.json() as Promise<T>
@@ -416,7 +432,7 @@ export class ${pascalName}Service {
 
     if (!response.ok) {
       const errorText = await response.text()
-      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)
+      throw new Error(\`${inTemplate(displayName)} API error (\${response.status}): \${errorText}\`)
     }
 
     return response.json() as Promise<T>
@@ -464,7 +480,7 @@ export class ${pascalName}Service {
 
     if (!response.ok) {
       const errorText = await response.text()
-      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)
+      throw new Error(\`${inTemplate(displayName)} API error (\${response.status}): \${errorText}\`)
     }
 
     return response.json() as Promise<T>
@@ -507,7 +523,7 @@ export class ${pascalName}Service {
 
     if (!response.ok) {
       const errorText = await response.text()
-      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)
+      throw new Error(\`${inTemplate(displayName)} API error (\${response.status}): \${errorText}\`)
     }
 
     return response.json() as Promise<T>
@@ -553,13 +569,13 @@ export interface Services extends CoreServices<SingletonServices> {}
 import { wireCredential } from '@pikku/core/credential'
 
 export const ${camelName}CredentialSchema = z.object({
-  apiKey: z.string().describe('${displayName} API key'),
+  apiKey: z.string().describe(${literal(`${displayName} API key`)}),
 })
 
 wireCredential({
   name: '${camelName}',
-  displayName: '${displayName}',
-  description: '${description}',
+  displayName: ${literal(displayName)},
+  description: ${literal(description)},
   type: 'wire',
   schema: ${camelName}CredentialSchema,
 })
@@ -567,10 +583,10 @@ wireCredential({
     }
     else if (flags.credential === 'bearer') {
         const credentialFields = flags.delegated
-            ? `  token: z.string().describe('${displayName} session token captured at delegated sign-in'),
+            ? `  token: z.string().describe(${literal(`${displayName} session token captured at delegated sign-in`)}),
   expiresAt: z.number().optional().describe('Token expiry (epoch seconds)'),
   tenantId: z.string().optional().describe('Upstream tenant id'),`
-            : `  token: z.string().describe('${displayName} bearer token'),`;
+            : `  token: z.string().describe(${literal(`${displayName} bearer token`)}),`;
         files[`src/${name}.credential.ts`] = `import { z } from 'zod'
 import { wireCredential } from '@pikku/core/credential'
 
@@ -580,8 +596,8 @@ ${credentialFields}
 
 wireCredential({
   name: '${camelName}',
-  displayName: '${displayName}',
-  description: '${description}',
+  displayName: ${literal(displayName)},
+  description: ${literal(description)},
   type: 'wire',
   schema: ${camelName}CredentialSchema,
 })
@@ -599,8 +615,8 @@ export const ${camelName}TokenSchema = z.object({
 
 wireCredential({
   name: '${camelName}',
-  displayName: '${displayName}',
-  description: '${description}',
+  displayName: ${literal(displayName)},
+  description: ${literal(description)},
   type: 'wire',
   schema: ${camelName}TokenSchema,
   oauth2: {
@@ -614,8 +630,8 @@ wireCredential({
 
 wireSecret({
   name: '${camelName}OAuthApp',
-  displayName: '${displayName} OAuth App',
-  description: 'OAuth2 app credentials for ${displayName}',
+  displayName: ${literal(`${displayName} OAuth App`)},
+  description: ${literal(`OAuth2 app credentials for ${displayName}`)},
   secretId: '${screamingName}_OAUTH_APP',
 })
 `;
@@ -625,7 +641,7 @@ wireSecret({
 import { wireSecret } from '@pikku/core/secret'
 
 export const ${camelName}SecretsSchema = z.object({
-  apiKey: z.string().describe('${displayName} API key'),
+  apiKey: z.string().describe(${literal(`${displayName} API key`)}),
   // Add other secret fields as needed
 })
 
@@ -633,8 +649,8 @@ export type ${pascalName}Secrets = z.infer<typeof ${camelName}SecretsSchema>
 
 wireSecret({
   name: '${camelName}',
-  displayName: '${displayName} API',
-  description: '${description}',
+  displayName: ${literal(`${displayName} API`)},
+  description: ${literal(description)},
   secretId: '${screamingName}_CREDENTIALS',
   schema: ${camelName}SecretsSchema,
 })
@@ -649,7 +665,7 @@ export const ${camelName}VariableSchema = z.string().optional().describe('TODO:
 
 wireVariable({
   name: '${camelName}_variable',
-  displayName: '${displayName} Variable',
+  displayName: ${literal(`${displayName} Variable`)},
   description: 'TODO: describe this variable',
   variableId: '${screamingName}_VARIABLE',
   schema: ${camelName}VariableSchema,

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;

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;
+};

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

@@ -10,6 +10,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    apiUrl?: string;
+    appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
     environment: string;
     flows?: string;
@@ -21,6 +23,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    apiUrl?: string;
+    appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
     environment: string;
     flows?: string;
@@ -32,4 +36,6 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
+    apiUrl?: string;
+    appUrl?: string;
 }, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

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

@@ -12,6 +12,7 @@ import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './sce
 import { resolveScenarioActors } from '../../utils/resolve-scenario-actors.js';
 import { spawnDevServer } from '../../server/spawn-dev-server.js';
 import { buildScenarioPlan } from './scenario-plan.js';
+import { resolveScenarioEnvironment } from './scenario-environment.js';
 const isScenario = (wf) => wf?.scenario === true;
 const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     .filter(([, wf]) => isScenario(wf))
@@ -83,16 +84,20 @@ export const scenarioList = pikkuSessionlessFunc({
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, spawn = false, keepAlive = false, trace = false, }) => {
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, spawn = false, keepAlive = false, trace = false, apiUrl, appUrl, }) => {
         const state = await getInspectorState(true, false, false, true);
-        const environments = config.scenarios?.environments ?? {};
-        const env = environments[environment];
-        if (!env) {
-            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" } }`));
+        // Resolved once, so actors, step env, the browser driver and any spawned
+        // server all target the same place — including when the target only exists
+        // at run time and arrives through --api-url/--app-url.
+        const env = resolveScenarioEnvironment({
+            environment,
+            environments: config.scenarios?.environments ?? {},
+            apiUrl,
+            appUrl,
+            spawn,
+        });
+        if (apiUrl || appUrl) {
+            logger.info(`Overriding '${environment}': apiUrl ${env.apiUrl}${env.appUrl ? `, appUrl ${env.appUrl}` : ''}`);
         }
         if (spawn) {
             const { hostname, port } = new URL(env.apiUrl);