@pikku/cli 0.12.92 → 0.12.96

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

@@ -0,0 +1,217 @@
+import { resolve, dirname } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { pikkuSessionlessFunc } from '#pikku';
+import { createHttpPersonas, personaEnvironmentRefusal, roleMismatchMessage, verifyPersonaRoles, } from '@pikku/core/persona';
+import { flattenSystemRoleDefinitions } from '@pikku/core/role';
+import { personaVirtualUserTarget, catalogueClassification, deriveCatalogue, deriveIntents, DISPOSITIONS, reachableAgents, runVirtualUser, } from '@pikku/core/virtual-user';
+import { personaScopes, resolvePersonas } from '../../utils/resolve-personas.js';
+import { resolveEnvironment } from './environment.js';
+import { createDevAIAgentRunner } from './dev-ai-runner.js';
+import { formatVirtualUserReport } from './virtual-user-formatter.js';
+const dispositionNames = Object.keys(DISPOSITIONS);
+/**
+ * What a declaration overrode, in the order it was written.
+ *
+ * Listed rather than summarised as "tuned": the whole reason to override a dial
+ * is that the stock profile was wrong for this product, and which one you moved
+ * is the interesting part.
+ */
+const describeTuning = (tuning) => Object.entries(tuning)
+    .map(([dial, value]) => dial === 'moves' && value && typeof value === 'object'
+    ? Object.entries(value)
+        .map(([move, weight]) => `${move} ${weight}`)
+        .join(', ')
+    : `${dial} ${dial === 'instructions' ? '+' : value}`)
+    .join(', ');
+/**
+ * Run one declared persona against a real stage as a virtual user.
+ *
+ * Everything it needs is already in the project: the catalogue is the function
+ * meta, the intents are the scenarios' own prose, the identity is the persona
+ * signing in over the app's real auth, and the scopes come from the roles they
+ * declared. The only new input is which person to be — everything else is a
+ * flag for narrowing or replaying a run.
+ *
+ * This is deliberately not a test runner. It asserts nothing, and a green run
+ * proves nothing — what it produces is findings, and the absence of them is
+ * only ever "not this time, not with this seed".
+ */
+export const personaRun = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState, variables }, { environment, persona: personaId, disposition: dispositionFlag, goals, steps, mutations, duration, seed, model, apiUrl, allowApproval, skipRoleCheck, out, }) => {
+        const state = await getInspectorState(true, false, false, true);
+        const personas = resolvePersonas(state.personas?.definitions ?? [], config.scenarios?.emailDomain);
+        const known = Object.keys(personas);
+        const persona = personas[personaId];
+        if (!persona) {
+            throw new Error(`No persona '${personaId}'.${known.length
+                ? ` Declared: ${known.join(', ')}`
+                : ' None are declared — add a definePersonas({ … }) call.'}`);
+        }
+        // A provider login needs a human at a consent screen, and someone declared
+        // `runnable: false` exists to be acted upon. Refused here rather than
+        // failing partway through a sign-in that was never going to work.
+        if (!persona.runnable) {
+            throw new Error(`Persona '${personaId}' is not runnable — ${persona.account?.provider
+                ? `their login is a '${persona.account.provider}' account, and driving its consent screen needs a person`
+                : 'they are declared `runnable: false`, to be acted upon rather than to act'}.`);
+        }
+        const declared = dispositionFlag ?? persona.disposition ?? 'realistic';
+        if (!dispositionNames.includes(declared)) {
+            throw new Error(`Unknown disposition '${declared}'. One of: ${dispositionNames.join(', ')}`);
+        }
+        // Narrowed by the guard above; `dispositionNames` is the runtime list and
+        // does not carry the union through `includes`.
+        const disposition = declared;
+        const environments = config.environments ?? {};
+        const env = resolveEnvironment({
+            environment,
+            environments,
+            apiUrl,
+        });
+        // Checked against the *effective* disposition, so `--disposition` cannot
+        // turn an accountable persona adversarial and point it at production. The
+        // build check already looked at the declaration; this one exists because
+        // the declaration is not what is running — the deployed artifact is.
+        const refusal = personaEnvironmentRefusal(personaId, { ...persona, disposition }, environment, environments);
+        if (refusal) {
+            throw new Error(refusal);
+        }
+        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
+        if (!secret) {
+            throw new Error('SCENARIO_ACTOR_SECRET is not set — a virtual user cannot sign in. ' +
+                'Export it in the environment running this command (never put it in pikku.config.json).');
+        }
+        const resolvedModel = model ?? config.scenarios?.model;
+        if (!resolvedModel) {
+            throw new Error('No model to think with — pass --model, or set scenarios.model in pikku.config.json.');
+        }
+        const aiAgentRunner = await createDevAIAgentRunner({
+            logger,
+            projectRoot: config.rootDir,
+            variables,
+        });
+        if (!aiAgentRunner) {
+            throw new Error('No AI provider is configured. Set OPENAI_BASE_URL + OPENAI_API_KEY (or LITELLM_PROXY_URL + LITELLM_API_KEY).');
+        }
+        const functionsMeta = state.functions?.meta ?? {};
+        const catalogue = deriveCatalogue(functionsMeta, (state.schemas ?? {}));
+        if (catalogue.length === 0) {
+            throw new Error('This project exposes no RPCs, so there is nothing for a virtual user to do.');
+        }
+        const intents = deriveIntents(state.workflows?.meta ?? {}, functionsMeta);
+        // Roles are what a persona declares; scopes are what a function checks.
+        // Expanded once, here, from the same definitions the seed grants from.
+        const roleScopes = {};
+        for (const role of flattenSystemRoleDefinitions(state.systemRoles?.definitions ?? [])) {
+            roleScopes[role.name] = role.scopes;
+        }
+        const scopes = personaScopes(persona, roleScopes);
+        // Gated by the same scopes as the RPCs, because an agent is reached rather
+        // than declared: `CoreAIAgent.scopes` is checked against the session, so a
+        // persona finds the specialists its roles unlock and no others.
+        const agents = reachableAgents(state.agents?.agentsMeta ?? {}, scopes);
+        const signedIn = createHttpPersonas({
+            apiUrl: env.apiUrl,
+            secret,
+            personas,
+            signInPath: env.signInPath,
+            rpcPath: env.rpcPath,
+            model: resolvedModel,
+        });
+        // Before the first step, not after: findings from a persona whose roles
+        // drifted are about the seed, and reading them as product bugs is how a
+        // whole run gets thrown away. `--skip-role-check` exists for a stage whose
+        // auth reports roles somewhere this cannot read.
+        if (!skipRoleCheck) {
+            const actual = await signedIn[personaId].sessionRoles();
+            if (actual === null) {
+                logger.warn(`Could not read '${personaId}' roles back from ${env.apiUrl} — running unverified. ` +
+                    `A stage that does not report roles cannot tell a permissions finding from seed drift.`);
+            }
+            else {
+                const message = roleMismatchMessage(verifyPersonaRoles(personaId, persona.roles, actual));
+                if (message) {
+                    throw new Error(message);
+                }
+            }
+        }
+        const flagGoals = goals?.split(',').map((goal) => goal.trim());
+        const result = await runVirtualUser({
+            persona,
+            personaId,
+            disposition,
+            // Tuning belongs to the declared person, so `--disposition` drops it: you
+            // asked to run them differently, not to bend their dials to another shape.
+            ...(dispositionFlag ? {} : { tuning: persona.tuning }),
+            catalogue,
+            intents,
+            goals: [...persona.goals, ...(flagGoals ?? [])],
+            scopes,
+            fixtures: persona.fixtures,
+            // Both halves, or `talkTo` is wired up and never advertised: the target
+            // decides whether a name is callable, the instructions are what tell the
+            // persona the assistant exists at all.
+            agents,
+            target: personaVirtualUserTarget(signedIn[personaId], {
+                model: resolvedModel,
+                agents: agents.map((agent) => agent.name),
+            }),
+            llm: (params) => aiAgentRunner.run(params),
+            model: resolvedModel,
+            seed: seed ? Number(seed) : undefined,
+            allowApprovalRequired: allowApproval ?? false,
+            budget: {
+                steps: steps ? Number(steps) : undefined,
+                mutations: mutations ? Number(mutations) : undefined,
+                duration,
+            },
+        });
+        for (const { level, text } of formatVirtualUserReport(result, {
+            persona: `${persona.name} (${personaId})`,
+            disposition,
+            environment,
+            apiUrl: env.apiUrl,
+            catalogue: catalogueClassification(catalogue),
+        })) {
+            logger[level](text);
+        }
+        if (out) {
+            const path = resolve(config.rootDir, out);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, JSON.stringify(result, null, 2));
+            logger.info(`Wrote the full run to ${path}`);
+        }
+        // A finding is the whole reason this ran, so it has to be able to fail a
+        // pipeline. Nothing else here does: giving up on an intent is a user being
+        // a user, not a defect.
+        if (result.findings.length > 0) {
+            process.exitCode = 1;
+        }
+    },
+});
+/** Who this app is for, and what each of them wants, without running anything. */
+export const personaList = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }) => {
+        const state = await getInspectorState(true, false, false, true);
+        const personas = Object.values(resolvePersonas(state.personas?.definitions ?? [], config.scenarios?.emailDomain));
+        if (personas.length === 0) {
+            logger.info('No personas declared. Add a definePersonas({ susan: { name, roles, goals } }) call.');
+            return;
+        }
+        for (const persona of personas) {
+            logger.info(`${persona.id} — ${persona.name}${persona.jobTitle ? `, ${persona.jobTitle}` : ''}`);
+            logger.info(`  ${persona.email}${persona.roles.length
+                ? `, roles: ${persona.roles.join(', ')}`
+                : ', no roles'}${persona.runnable ? '' : ' (not runnable)'}`);
+            if (persona.disposition || persona.tuning) {
+                logger.info(`  ${persona.disposition ?? 'realistic'}${persona.tuning ? ` (tuned: ${describeTuning(persona.tuning)})` : ''}`);
+            }
+            if (persona.description) {
+                logger.info(`  ${persona.description}`);
+            }
+            for (const goal of persona.goals) {
+                logger.info(`  · ${goal}`);
+            }
+        }
+    },
+});

package/dist/src/functions/commands/roles-audit.d.ts

@@ -0,0 +1 @@
+export declare const rolesAudit: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/roles-audit.js

@@ -0,0 +1,37 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { loadDeclaredRoles, openScopeServiceForRoles, reportStaleRoles, } from './roles-shared.js';
+export const rolesAudit = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const declared = await loadDeclaredRoles(config.rolesMetaJsonFile, logger);
+        if (!declared) {
+            throw new Error('role metadata not found');
+        }
+        const opened = await openScopeServiceForRoles({ config, logger }, declared, 'pikku roles audit');
+        if (!opened) {
+            return;
+        }
+        try {
+            const stale = await opened.service.findStaleSystemRoles();
+            logger.info(`Role audit: ${declared.length} system role(s) declared in code`);
+            if (stale.length === 0) {
+                logger.info('  every system role in the database is still declared');
+                return;
+            }
+            logger.info('');
+            logger.info(`${stale.length} system role(s) no longer declared in code:`);
+            reportStaleRoles(stale, logger);
+            const held = stale.filter((s) => s.users > 0);
+            logger.info('');
+            if (held.length > 0) {
+                logger.warn(`${held.length} undeclared role(s) are still held by somebody. ` +
+                    `They are inert — nothing offers them for new grants — but the ` +
+                    `existing grants persist, and so do whatever scopes the role still carries.`);
+            }
+            logger.info('Run `pikku roles prune --yes` to remove them.');
+        }
+        finally {
+            await opened.destroy();
+        }
+    },
+});

package/dist/src/functions/commands/roles-prune.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Removes system roles that are no longer declared in code, cascading them out
+ * of every user grant that holds them.
+ *
+ * This revokes access, so it never runs implicitly — not at boot, not as part
+ * of `pikku all`. Without `--yes` it only reports the blast radius. That is the
+ * whole point of the additive sync: deleting a `defineSystemRole` declaration
+ * leaves people holding the role until somebody decides otherwise here.
+ */
+export declare const rolesPrune: import("#pikku").PikkuFunctionConfig<{
+    yes?: boolean;
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    yes?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    yes?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/roles-prune.js

@@ -0,0 +1,52 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { loadDeclaredRoles, openScopeServiceForRoles, reportStaleRoles, } from './roles-shared.js';
+/**
+ * Removes system roles that are no longer declared in code, cascading them out
+ * of every user grant that holds them.
+ *
+ * This revokes access, so it never runs implicitly — not at boot, not as part
+ * of `pikku all`. Without `--yes` it only reports the blast radius. That is the
+ * whole point of the additive sync: deleting a `defineSystemRole` declaration
+ * leaves people holding the role until somebody decides otherwise here.
+ */
+export const rolesPrune = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }, { yes }) => {
+        const declared = await loadDeclaredRoles(config.rolesMetaJsonFile, logger);
+        if (!declared) {
+            throw new Error('role metadata not found');
+        }
+        const opened = await openScopeServiceForRoles({ config, logger }, declared, 'pikku roles prune');
+        if (!opened) {
+            return;
+        }
+        try {
+            const stale = await opened.service.findStaleSystemRoles();
+            if (stale.length === 0) {
+                logger.info('roles prune: nothing to prune');
+                return;
+            }
+            logger.info(`${stale.length} system role(s) no longer declared in code:`);
+            reportStaleRoles(stale, logger);
+            const held = stale.filter((s) => s.users > 0);
+            const affectedUsers = stale.reduce((sum, s) => sum + s.users, 0);
+            if (!yes) {
+                logger.info('');
+                if (held.length > 0) {
+                    logger.warn(`Pruning would revoke ${held.length} role(s) from ${affectedUsers} user grant(s).`);
+                }
+                logger.info('Re-run with --yes to remove them.');
+                return;
+            }
+            const pruned = await opened.service.pruneSystemRoles();
+            logger.info('');
+            logger.info(`roles prune: removed ${pruned.length} system role(s)`);
+            if (held.length > 0) {
+                logger.warn(`Revoked from ${affectedUsers} user grant(s). They lose the role's scopes on their next request.`);
+            }
+        }
+        finally {
+            await opened.destroy();
+        }
+    },
+});

package/dist/src/functions/commands/roles-shared.d.ts

@@ -0,0 +1,40 @@
+import type { SystemRole } from '@pikku/core/role';
+import { openScopeService } from './scopes-shared.js';
+import type { OpenedScopeService } from './scopes-shared.js';
+type Logger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+/**
+ * Reads the generated role metadata and flattens it to the declared role set.
+ *
+ * Returns `null` — never an empty array — when the file cannot be read, for the
+ * same reason `loadDeclaredScopes` does: `prune` removes everything not in this
+ * set, so "nothing is declared" and "we failed to find out" have to stay
+ * distinguishable or a missing file wipes every system role in the database.
+ */
+export declare const loadDeclaredRoles: (rolesMetaJsonFile: string | undefined, logger: Logger) => Promise<SystemRole[] | null>;
+/**
+ * Opens a ScopeService and brings both the scope and the role `declared` marks
+ * up to date with the code.
+ *
+ * Scopes are synced first and not as a courtesy: `pikku_role_scopes` has a
+ * foreign key onto `pikku_scopes`, so a role granting a freshly-declared scope
+ * cannot be written until that scope's row exists. Both syncs are additive, so
+ * doing them inside a read-only command is safe.
+ */
+export declare const openScopeServiceForRoles: (args: Parameters<typeof openScopeService>[0] & {
+    config: {
+        scopesMetaJsonFile: string;
+    };
+}, roles: SystemRole[], command: string) => Promise<OpenedScopeService | null>;
+/**
+ * Renders undeclared system roles and how many people still hold each — the
+ * blast radius, shown before anything is deleted.
+ */
+export declare const reportStaleRoles: (stale: Array<{
+    role: string;
+    users: number;
+}>, logger: Logger) => void;
+export {};

package/dist/src/functions/commands/roles-shared.js

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises';
+import { flattenSystemRoleDefinitions } from '@pikku/core/role';
+import { loadDeclaredScopes, openScopeService } from './scopes-shared.js';
+const isRoleDefinitionsMeta = (value) => typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value).every((def) => typeof def === 'object' &&
+        def !== null &&
+        !Array.isArray(def) &&
+        typeof def.name === 'string' &&
+        Array.isArray(def.scopes));
+/**
+ * Reads the generated role metadata and flattens it to the declared role set.
+ *
+ * Returns `null` — never an empty array — when the file cannot be read, for the
+ * same reason `loadDeclaredScopes` does: `prune` removes everything not in this
+ * set, so "nothing is declared" and "we failed to find out" have to stay
+ * distinguishable or a missing file wipes every system role in the database.
+ */
+export const loadDeclaredRoles = async (rolesMetaJsonFile, logger) => {
+    if (!rolesMetaJsonFile) {
+        logger.error('pikku roles: no role metadata path is configured.\n' +
+            '  Run `pikku all` to generate it.');
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(rolesMetaJsonFile, 'utf8'));
+    }
+    catch {
+        logger.error(`pikku roles: no role metadata at ${rolesMetaJsonFile}.\n` +
+            `  Run \`pikku all\` to generate it.`);
+        return null;
+    }
+    if (!isRoleDefinitionsMeta(parsed)) {
+        logger.error(`pikku roles: the role metadata at ${rolesMetaJsonFile} is malformed.\n` +
+            `  Run \`pikku all\` to regenerate it.`);
+        return null;
+    }
+    return flattenSystemRoleDefinitions(Object.values(parsed));
+};
+/**
+ * Opens a ScopeService and brings both the scope and the role `declared` marks
+ * up to date with the code.
+ *
+ * Scopes are synced first and not as a courtesy: `pikku_role_scopes` has a
+ * foreign key onto `pikku_scopes`, so a role granting a freshly-declared scope
+ * cannot be written until that scope's row exists. Both syncs are additive, so
+ * doing them inside a read-only command is safe.
+ */
+export const openScopeServiceForRoles = async (args, roles, command) => {
+    const declaredScopes = await loadDeclaredScopes(args.config.scopesMetaJsonFile, args.logger);
+    if (!declaredScopes) {
+        throw new Error('scope metadata not found');
+    }
+    const opened = await openScopeService(args, declaredScopes, command);
+    if (!opened) {
+        return null;
+    }
+    try {
+        await opened.service.syncSystemRoles(roles);
+    }
+    catch (e) {
+        await opened.destroy();
+        throw e;
+    }
+    return opened;
+};
+/**
+ * Renders undeclared system roles and how many people still hold each — the
+ * blast radius, shown before anything is deleted.
+ */
+export const reportStaleRoles = (stale, logger) => {
+    for (const { role, users } of stale) {
+        logger.info(`  ${role.padEnd(40)} held by ${users} user(s)`);
+    }
+};

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

@@ -8,12 +8,12 @@
  * unconditionally.
  */
 import type { ScenarioBrowserFailure, ScenarioBrowserProvider } from '@pikku/core/workflow';
-import type { ScenarioActorConfig } from '@pikku/core/services';
+import type { ResolvedPersona } 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>;
+    actors: Record<string, ResolvedPersona>;
     signInPath?: string;
     failureDir?: string;
     config: unknown;
@@ -49,7 +49,7 @@ export interface ResolveScenarioBrowserProviderOptions {
     apiUrl: string;
     appUrl?: string;
     secret: string;
-    actors: Record<string, ScenarioActorConfig>;
+    actors: Record<string, ResolvedPersona>;
     signInPath?: string;
     /** Where failure screenshots are written. */
     failureDir: string;

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

@@ -26,7 +26,7 @@ export const resolveScenarioBrowserProvider = async ({ environment, apiUrl, appU
     });
     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.`);
+            `Add it to 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,

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

@@ -1,4 +1,4 @@
-import type { ScenarioStepPhase } from '@pikku/core/workflow';
+import type { ScenarioStepPhase, ScenarioSurface } 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';
@@ -53,10 +53,52 @@ export interface ScenarioProse {
 export declare const collectScenarioStepProse: (workflowMeta: {
     steps?: WorkflowStepMeta[];
 } | undefined, functionsMeta: FunctionsMeta) => ScenarioProse;
-/** The step functions in this scenario that declare `browser: true`. */
+/** The step functions in this scenario that declare a `browser` binding. */
 export declare const scenarioBrowserSteps: (workflowMeta: {
     steps?: WorkflowStepMeta[];
 } | undefined, functionsMeta: FunctionsMeta) => string[];
+/**
+ * Steps this scenario cannot run on `surface` at all — they declare neither a
+ * binding for it nor a `default` to fall back to.
+ *
+ * Every phase counts. An action with nothing to run is a broken ladder; an
+ * assertion with nothing to run would report a pass having checked nothing,
+ * which the engine now refuses outright. Both are better caught here, so the
+ * flow is held back with a reason than failed halfway through.
+ *
+ * A step that *can* run, just not on the run surface, is the different case — a
+ * coverage gap, counted by {@link scenarioSurfaceCoverage} rather than a reason
+ * to skip.
+ */
+export declare const scenarioStepsWithoutBinding: (workflowMeta: {
+    steps?: WorkflowStepMeta[];
+} | undefined, functionsMeta: FunctionsMeta, surface: ScenarioSurface) => string[];
+/**
+ * How much of this scenario actually ran on the surface the run targeted.
+ *
+ * Every step counts, not just the assertions. A ladder of
+ * `browser/browser/default/browser` is 3/4 — the step that fell back to the
+ * server shows up by lowering the ratio, which is a truer signal than a green
+ * assertion count with a footnote. It also makes surfaces comparable: the same
+ * scenario is 4/4 on a default run and 3/4 on a browser one, over one
+ * denominator.
+ *
+ * Assertions still get named separately. A `given` or `when` driven server-side
+ * took a shortcut; a `then` driven server-side is a sentence claiming the actor
+ * saw something nobody looked at. Same effect on the ratio, different kind of
+ * problem, so `--strict` gates on the latter only.
+ */
+export interface ScenarioSurfaceCoverage {
+    /** Steps that ran on the run surface. */
+    onSurface: number;
+    /** Steps that ran at all. */
+    total: number;
+    /** The `then` steps that ran, but somewhere other than the run surface. */
+    unwitnessed: string[];
+}
+export declare const scenarioSurfaceCoverage: (workflowMeta: {
+    steps?: WorkflowStepMeta[];
+} | undefined, functionsMeta: FunctionsMeta, runSurface: ScenarioSurface) => ScenarioSurfaceCoverage;
 /** The run's steps as renderable rows, in the order they were recorded. */
 export declare const scenarioStepRows: (steps: ScenarioStepOutcome[], prose: ScenarioProse) => ScenarioStepRow[];
 /**

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

@@ -76,16 +76,65 @@ 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`. */
+/** The step functions in this scenario that declare a `browser` binding. */
 export const scenarioBrowserSteps = (workflowMeta, functionsMeta) => {
     const names = new Set();
     for (const step of walkScenarioSteps(workflowMeta?.steps)) {
-        if (functionsMeta[step.stepFunc]?.scenarioStepBrowser === true) {
+        if (functionsMeta[step.stepFunc]?.scenarioStepSurfaces?.includes('browser')) {
             names.add(step.stepFunc);
         }
     }
     return [...names];
 };
+/**
+ * Steps this scenario cannot run on `surface` at all — they declare neither a
+ * binding for it nor a `default` to fall back to.
+ *
+ * Every phase counts. An action with nothing to run is a broken ladder; an
+ * assertion with nothing to run would report a pass having checked nothing,
+ * which the engine now refuses outright. Both are better caught here, so the
+ * flow is held back with a reason than failed halfway through.
+ *
+ * A step that *can* run, just not on the run surface, is the different case — a
+ * coverage gap, counted by {@link scenarioSurfaceCoverage} rather than a reason
+ * to skip.
+ */
+export const scenarioStepsWithoutBinding = (workflowMeta, functionsMeta, surface) => {
+    const names = new Set();
+    for (const step of walkScenarioSteps(workflowMeta?.steps)) {
+        const surfaces = functionsMeta[step.stepFunc]?.scenarioStepSurfaces ?? [
+            'default',
+        ];
+        if (!surfaces.includes(surface) && !surfaces.includes('default')) {
+            names.add(step.stepFunc);
+        }
+    }
+    return [...names];
+};
+export const scenarioSurfaceCoverage = (workflowMeta, functionsMeta, runSurface) => {
+    let onSurface = 0;
+    let total = 0;
+    const unwitnessed = new Set();
+    for (const step of walkScenarioSteps(workflowMeta?.steps)) {
+        const surfaces = functionsMeta[step.stepFunc]?.scenarioStepSurfaces ?? [
+            'default',
+        ];
+        // A step with no binding this run can execute never runs, so it is not a
+        // statistic about this run — `scenarioStepsWithoutBinding` holds the flow
+        // back for it. Counting it here would score a run on work it refuses to do.
+        if (!surfaces.includes(runSurface) && !surfaces.includes('default')) {
+            continue;
+        }
+        total += 1;
+        if (runSurface === 'default' || surfaces.includes(runSurface)) {
+            onSurface += 1;
+        }
+        else if (step.phase === 'then') {
+            unwitnessed.add(step.stepFunc);
+        }
+    }
+    return { onSurface, total, unwitnessed: [...unwitnessed] };
+};
 /**
  * Render one step's gherkin sentence.
  *

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

@@ -1,3 +1,4 @@
+import type { ScenarioSurface } from '@pikku/core/workflow';
 export declare const scenarioList: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
 export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     environment: string;
@@ -7,6 +8,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     excludeTags?: string;
     coverage?: boolean;
     browser?: boolean;
+    run?: ScenarioSurface;
+    strict?: boolean;
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
@@ -20,6 +23,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     excludeTags?: string;
     coverage?: boolean;
     browser?: boolean;
+    run?: ScenarioSurface;
+    strict?: boolean;
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
@@ -33,6 +38,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     excludeTags?: string;
     coverage?: boolean;
     browser?: boolean;
+    run?: ScenarioSurface;
+    strict?: boolean;
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;