@pikku/cli 0.12.93 → 0.12.96

package/dist/src/functions/wirings/roles/pikku-command-roles.js

@@ -0,0 +1,33 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeRolesTypes } from './serialize-roles-types.js';
+import { validateAndBuildSystemRoleDefinitionsMeta } from '@pikku/core/role';
+export const pikkuRoles = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }, data) => {
+        const { rolesFile, rolesMetaJsonFile } = config;
+        if (!rolesFile) {
+            return;
+        }
+        // Same cold-start reasoning as Scopes: on a bare .pikku this runs before
+        // pikku-types.gen.ts exists, so it takes the zero state. The file only has
+        // to exist so personas can import SystemRoleName; the real Roles step
+        // regenerates it with the declarations once setup has run.
+        const bootstrap = data?.bootstrap ?? false;
+        const state = await getInspectorState(false, bootstrap, bootstrap);
+        const content = serializeRolesTypes({
+            definitions: state.systemRoles.definitions,
+        });
+        await writeFileInDir(logger, rolesFile, content);
+        if (rolesMetaJsonFile) {
+            const meta = validateAndBuildSystemRoleDefinitionsMeta(state.systemRoles.definitions);
+            await writeFileInDir(logger, rolesMetaJsonFile, JSON.stringify(meta, null, 2));
+        }
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Creating PikkuRoles types',
+            commandEnd: 'Created PikkuRoles types',
+        }),
+    ],
+});

package/dist/src/functions/wirings/roles/serialize-roles-types.d.ts

@@ -0,0 +1,14 @@
+import type { SystemRoleDefinitions } from '@pikku/core/role';
+export interface SerializeRolesOptions {
+    definitions: SystemRoleDefinitions;
+}
+/**
+ * Generates the `SystemRoleName` union and role metadata from
+ * `defineSystemRole` declarations.
+ *
+ * The union is what makes a persona's `roles: ['buyer']` checkable. Custom
+ * roles are deliberately absent: an admin can delete one from the console, so
+ * a persona pinned to it would silently stop testing what it claims to — the
+ * failure would be a scatter of 403s rather than a build error.
+ */
+export declare const serializeRolesTypes: ({ definitions }: SerializeRolesOptions) => string;

package/dist/src/functions/wirings/roles/serialize-roles-types.js

@@ -0,0 +1,55 @@
+const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
+/**
+ * Generates the `SystemRoleName` union and role metadata from
+ * `defineSystemRole` declarations.
+ *
+ * The union is what makes a persona's `roles: ['buyer']` checkable. Custom
+ * roles are deliberately absent: an admin can delete one from the console, so
+ * a persona pinned to it would silently stop testing what it claims to — the
+ * failure would be a scatter of 403s rather than a build error.
+ */
+export const serializeRolesTypes = ({ definitions }) => {
+    const names = [...new Set(definitions.map((d) => d.name))].sort();
+    const union = names.length > 0
+        ? `\n${names.map((name) => `  | ${quote(name)}`).join('\n')}`
+        : ' never';
+    return `/**
+ * This file was generated by the @pikku/cli
+ */
+import type { SystemRole, SystemRoleDefinitionsMeta } from '@pikku/core/role'
+import { flattenSystemRoleDefinitions } from '@pikku/core/role'
+import definitions from './pikku-roles-meta.gen.json' with { type: 'json' }
+
+/**
+ * Every role that ships with this application.
+ *
+ * Roles an admin composes in the console are not here and cannot be: they do
+ * not exist at build time, and can be deleted after it.
+ */
+export type SystemRoleName =${union}
+
+/**
+ * The declared role set, for a ScopeService to sync into its store.
+ *
+ * Derived from the metadata sidecar rather than inlined, so the import above
+ * forces tsc to emit the .json alongside this file — an addon publishes only
+ * its compiled output, and a host reads that .json to merge the addon's roles
+ * into its own union.
+ *
+ * Additive on removal: a deleted declaration leaves an inert row rather than
+ * revoking everyone's grant on deploy. Use \`pikku roles prune\` to remove them.
+ */
+export const SYSTEM_ROLES: SystemRole[] = flattenSystemRoleDefinitions(
+  Object.values(definitions as SystemRoleDefinitionsMeta)
+)
+
+/** Declared roles, keyed by name. Rendered by the console when granting. */
+export const SYSTEM_ROLES_META: Record<string, SystemRole> = Object.fromEntries(
+  SYSTEM_ROLES.map((role) => [role.name, role])
+)
+
+/** Whether a role name is declared in code, and therefore not editable. */
+export const isSystemRole = (name: string): boolean =>
+  Object.prototype.hasOwnProperty.call(SYSTEM_ROLES_META, name)
+`;
+};

package/dist/src/functions/wirings/rpc/pikku-command-public-rpc.js

@@ -4,6 +4,7 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializePublicRPC } from './serialize-public-rpc.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuPublicRPC = pikkuSessionlessFunc({
     func: async ({ logger, config, variables }) => {
         const deployCodegenFlag = await variables.get('PIKKU_DEPLOY_CODEGEN');
@@ -12,7 +13,7 @@ export const pikkuPublicRPC = pikkuSessionlessFunc({
         }
         if (config.scaffold?.rpc && config.publicRpcSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.publicRpcFile, config.typesDeclarationFile, config.packageMappings);
-            const { schemas, functions } = serializePublicRPC(pathToPikkuTypes, config.scaffold.rpc === 'auth', config.globalHTTPPrefix || '');
+            const { schemas, functions } = serializePublicRPC(pathToPikkuTypes, resolveScaffoldFeature('rpc', config.scaffold.rpc).auth, config.globalHTTPPrefix || '');
             await writeFileInDir(logger, config.publicRpcSchemasFile, schemas);
             await writeFileInDir(logger, config.publicRpcFile, functions);
             await removeLegacyScaffoldFile(config.publicRpcFile);

package/dist/src/functions/wirings/scenarios/register-scenario-instrumentation.d.ts

@@ -3,8 +3,8 @@
  * scenario runner can reach it over `/rpc/<name>` exactly as before.
  *
  * They are registered sessionless: `auth` decides whether a session is
- * *required*, and a sessioned function would demand one regardless of the flag —
- * which is what made `scaffold.scenarios: true` (as opposed to `'auth'`) refuse
- * every call and log a warning about it.
+ * *required*, and a sessioned function would demand one regardless of the flag.
+ * `scaffold.scenarios: true` therefore requires a session; `{ auth: false }` is
+ * what opens them.
  */
 export declare const registerScenarioInstrumentation: (requireAuth: boolean) => void;

package/dist/src/functions/wirings/scenarios/register-scenario-instrumentation.js

@@ -79,9 +79,9 @@ const instrumentation = {
  * scenario runner can reach it over `/rpc/<name>` exactly as before.
  *
  * They are registered sessionless: `auth` decides whether a session is
- * *required*, and a sessioned function would demand one regardless of the flag —
- * which is what made `scaffold.scenarios: true` (as opposed to `'auth'`) refuse
- * every call and log a warning about it.
+ * *required*, and a sessioned function would demand one regardless of the flag.
+ * `scaffold.scenarios: true` therefore requires a session; `{ auth: false }` is
+ * what opens them.
  */
 export const registerScenarioInstrumentation = (requireAuth) => {
     const meta = pikkuState(null, 'function', 'meta');

package/dist/src/functions/wirings/scopes/serialize-scopes-types.d.ts

@@ -3,7 +3,7 @@ export interface SerializeScopesOptions {
     definitions: ScopeDefinitions;
 }
 /**
- * Generates the `ScopeId` union and scope metadata from `wireScope`
+ * Generates the `ScopeId` union and scope metadata from `defineScope`
  * declarations.
  *
  * The union carries every declared node plus a wildcard form for each node that

package/dist/src/functions/wirings/scopes/serialize-scopes-types.js

@@ -1,7 +1,7 @@
 import { flattenScopeDefinitions } from '@pikku/core/scope';
 const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
 /**
- * Generates the `ScopeId` union and scope metadata from `wireScope`
+ * Generates the `ScopeId` union and scope metadata from `defineScope`
  * declarations.
  *
  * The union carries every declared node plus a wildcard form for each node that

package/dist/src/functions/wirings/user-admin/pikku-command-user-admin-functions.js

@@ -3,6 +3,7 @@ import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeUserAdminFunctions } from './serialize-user-admin-functions.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         if (!config.scaffold?.userAdmin ||
@@ -35,7 +36,7 @@ export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
                 `Then re-run codegen. Or remove "scaffold.userAdmin" from pikku.config.json.`);
         }
         const pathToPikkuTypes = getFileImportRelativePath(config.userAdminFunctionsFile, config.typesDeclarationFile, config.packageMappings);
-        const { schemas, functions } = serializeUserAdminFunctions(pathToPikkuTypes, config.scaffold.userAdmin === 'auth');
+        const { schemas, functions } = serializeUserAdminFunctions(pathToPikkuTypes, resolveScaffoldFeature('userAdmin', config.scaffold.userAdmin).auth);
         await writeFileInDir(logger, config.userAdminSchemasFile, schemas);
         await writeFileInDir(logger, config.userAdminFunctionsFile, functions);
         return true;

package/dist/src/functions/wirings/user-admin/serialize-user-admin-functions.js

@@ -86,7 +86,7 @@ export const Success = z.object({
  * Auto-generated user management functions
  * Do not edit manually - regenerate with 'npx pikku'
  */
-import { pikkuFunc, wireScope } from '${pathToPikkuTypes}'
+import { pikkuFunc, defineScope } from '${pathToPikkuTypes}'
 import { callAdminApi } from '@pikku/better-auth'
 import {
   CreateUserInput,
@@ -103,7 +103,7 @@ import {
 // this is the whole \`admin\` tree — not just the leaves gated below. It must stay
 // byte-identical to ADMIN_SCOPE_TREE in @pikku/better-auth and to the copy in
 // @pikku/addon-console, or codegen fails with conflicting declarations.
-wireScope({
+defineScope({
   admin: {
     displayName: 'Administration',
     description: 'Capabilities that act on the application as a whole',

package/dist/src/functions/wirings/workflow/pikku-command-workflow-routes.js

@@ -4,13 +4,14 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializeWorkflowRoutes } from './serialize-workflow-routes.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuWorkflowRoutes = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
         if (config.scaffold?.workflow &&
             config.workflowRoutesFile &&
             config.workflowRoutesSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.workflowRoutesFile, config.typesDeclarationFile, config.packageMappings);
-            const { schemas, functions } = serializeWorkflowRoutes(pathToPikkuTypes, config.scaffold?.workflow === 'auth');
+            const { schemas, functions } = serializeWorkflowRoutes(pathToPikkuTypes, resolveScaffoldFeature('workflow', config.scaffold?.workflow).auth);
             await writeFileInDir(logger, config.workflowRoutesSchemasFile, schemas);
             await writeFileInDir(logger, config.workflowRoutesFile, functions);
             await removeLegacyScaffoldFile(config.workflowRoutesFile);

package/dist/src/functions/wirings/workflow/pikku-command-workflow.js

@@ -3,8 +3,8 @@ import { ErrorCode } from '@pikku/inspector';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeWorkflowTypes } from './serialize-workflow-types.js';
-import { serializeScenarioActors } from './serialize-scenario-actors.js';
-import { resolveScenarioActors } from '../../../utils/resolve-scenario-actors.js';
+import { serializePersonas } from './serialize-personas.js';
+import { resolvePersonas } from '../../../utils/resolve-personas.js';
 import { serializeWorkflowRegistration } from './serialize-workflow-registration.js';
 import { serializeWorkflowMap } from './serialize-workflow-map.js';
 import { serializeScenarioStepMap } from './serialize-scenario-step-map.js';
@@ -89,21 +89,21 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
         const agentMapImportPath = getFileImportRelativePath(workflowTypesFile, config.agentMapDeclarationFile, packageMappings);
         const scopesImportPath = getFileImportRelativePath(workflowTypesFile, config.scopesFile, packageMappings);
         const scenarioStepMapImportPath = getFileImportRelativePath(workflowTypesFile, config.scenarioStepMapDeclarationFile, packageMappings);
-        const scenarioActorsImportPath = getFileImportRelativePath(workflowTypesFile, config.scenarioActorsFile, packageMappings);
-        await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath, scenarioActorsImportPath));
+        const personasImportPath = getFileImportRelativePath(workflowTypesFile, config.personasWiringFile, packageMappings);
+        await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath, personasImportPath));
         // Rides the workflow command rather than getting its own codegen node, so
         // it can't drift out of the two hand-maintained ordering lists.
         await writeFileInDir(logger, config.scenarioStepMapDeclarationFile, serializeScenarioStepMap(logger, config.scenarioStepMapDeclarationFile, packageMappings, typesMap, functionState.meta));
-        // Written even for an empty registry, so `TypedScenarioActors` is always a
-        // resolvable import for the generated function types.
-        const scenarioActors = resolveScenarioActors(config.scenarios);
+        // Written even when nobody declared a persona, so `TypedPersonas` is always
+        // a resolvable import for the generated function types.
+        const personas = resolvePersonas(visitState.personas.definitions, config.scenarios?.emailDomain);
         {
-            const agentMapImportPath = getFileImportRelativePath(config.scenarioActorsFile, config.agentMapDeclarationFile, packageMappings);
-            const exposedRpcMapImportPath = getFileImportRelativePath(config.scenarioActorsFile, config.rpcMapDeclarationFile, packageMappings);
-            await writeFileInDir(logger, config.scenarioActorsFile, serializeScenarioActors(scenarioActors, agentMapImportPath, exposedRpcMapImportPath));
-            // Fixed path getScenarioActorsMeta() reads; kept out of workflow/meta,
-            // which getWorkflowMeta() globs as workflows.
-            await writeFileInDir(logger, join(config.outDir, 'workflow', 'scenario-actors.gen.json'), JSON.stringify(scenarioActors, null, 2));
+            const agentMapImportPath = getFileImportRelativePath(config.personasWiringFile, config.agentMapDeclarationFile, packageMappings);
+            const exposedRpcMapImportPath = getFileImportRelativePath(config.personasWiringFile, config.rpcMapDeclarationFile, packageMappings);
+            await writeFileInDir(logger, config.personasWiringFile, serializePersonas(personas, agentMapImportPath, exposedRpcMapImportPath));
+            // Fixed path getPersonasMeta() reads; kept out of workflow/meta, which
+            // getWorkflowMeta() globs as workflows.
+            await writeFileInDir(logger, join(config.outDir, 'workflow', 'personas.gen.json'), JSON.stringify(personas, null, 2));
         }
         // Fixed path getFeaturesMeta() reads. Written even when empty so the
         // console can tell "no features declared" from "meta not generated yet".

package/dist/src/functions/wirings/workflow/serialize-personas.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedPersona } from '@pikku/core/services';
+/**
+ * The runtime half of `definePersonas()`.
+ *
+ * Generated rather than re-exported because the addresses are computed: nobody
+ * writes one down, and a seed, a scenario run and a virtual-user run all have
+ * to arrive at the same one. Baking them here is what makes that a single fact
+ * rather than three implementations of the same rule.
+ */
+export declare const serializePersonas: (personas: Record<string, ResolvedPersona>, agentMapImportPath: string, rpcMapImportPath: string) => string;

package/dist/src/functions/wirings/workflow/serialize-personas.js

@@ -0,0 +1,46 @@
+/**
+ * The runtime half of `definePersonas()`.
+ *
+ * Generated rather than re-exported because the addresses are computed: nobody
+ * writes one down, and a seed, a scenario run and a virtual-user run all have
+ * to arrive at the same one. Baking them here is what makes that a single fact
+ * rather than three implementations of the same rule.
+ */
+export const serializePersonas = (personas, agentMapImportPath, rpcMapImportPath) => {
+    return `/** Personas declared with definePersonas() */
+import { createHttpPersonas } from '@pikku/core/persona'
+import type {
+  HttpPersonasConfig,
+  ScenarioPersona,
+  ResolvedPersona,
+} from '@pikku/core/services'
+import type { AgentMap } from '${agentMapImportPath}'
+import type { FlattenedRPCMap } from '${rpcMapImportPath}'
+
+export const personaConfigs = ${JSON.stringify(personas, null, 2)} as const satisfies Record<string, ResolvedPersona>
+
+export type PersonaName = keyof typeof personaConfigs
+
+/**
+ * The same personas as a list, widened to \`ResolvedPersona\`. Iterating
+ * \`personaConfigs\` directly yields the literal type of each entry, on which an
+ * optional field a persona did not declare does not exist — so a seed reading
+ * \`roles\` off every persona needs this instead.
+ */
+export const personaList: ResolvedPersona[] = Object.values(personaConfigs)
+
+export type AgentName = keyof AgentMap & string
+export type TypedPersonas = Record<
+  PersonaName,
+  ScenarioPersona<AgentName, FlattenedRPCMap>
+>
+
+export const createPersonas = (
+  options: Omit<HttpPersonasConfig, 'personas'>
+): TypedPersonas =>
+  createHttpPersonas({
+    ...options,
+    personas: personaConfigs,
+  }) as TypedPersonas
+`;
+};

package/dist/src/functions/wirings/workflow/serialize-scenario-step-map.js

@@ -9,10 +9,19 @@
  */
 import { serializeImportMap } from '../../../utils/serialize-import-map.js';
 import { generateCustomTypes } from '@pikku/inspector';
-const SCENARIO_STEP_WRAPPER = 'pikkuScenarioStep';
+/**
+ * All three step wrappers. A scenario calls a platform or addon step by name
+ * exactly as it calls a persona one — who acts changes what the step may do, not
+ * how it is referenced — so all three belong in the map.
+ */
+const SCENARIO_STEP_WRAPPERS = new Set([
+    'pikkuScenarioStep',
+    'pikkuPlatformScenarioStep',
+    'pikkuAddonScenarioStep',
+]);
 export const serializeScenarioStepMap = (logger, relativeToPath, packageMappings, typesMap, functionsMeta) => {
     const requiredTypes = new Set();
-    const steps = Object.entries(functionsMeta).filter(([, meta]) => meta.funcWrapper === SCENARIO_STEP_WRAPPER);
+    const steps = Object.entries(functionsMeta).filter(([, meta]) => !!meta.funcWrapper && SCENARIO_STEP_WRAPPERS.has(meta.funcWrapper));
     const resolveType = (name) => {
         if (!name) {
             return 'void';

package/dist/src/functions/wirings/workflow/serialize-workflow-types.js

@@ -1,4 +1,4 @@
-export const serializeWorkflowTypes = (functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath = './pikku-scenario-step-map.gen.js', scenarioActorsImportPath = './pikku-scenario-actors.gen.js') => {
+export const serializeWorkflowTypes = (functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath = './pikku-scenario-step-map.gen.js', scenarioActorsImportPath = './pikku-personas.gen.js') => {
     return `import { WorkflowCancelledException } from '@pikku/core/workflow'
 import { template } from '@pikku/core/workflow'
 import {
@@ -14,9 +14,9 @@ import type { FlattenedRPCMap } from '${rpcMapImportPath}'
 import type { FlattenedWorkflowMap } from '${workflowMapImportPath}'
 import type { AgentMap as FlattenedAgentMap } from '${agentMapImportPath}'
 import type { FlattenedScenarioStepMap } from '${scenarioStepMapImportPath}'
-import type { TypedScenarioActors } from '${scenarioActorsImportPath}'
+import type { TypedPersonas } from '${scenarioActorsImportPath}'
 
-export type { TypedScenarioActors }
+export type { TypedPersonas }
 
 export { template }
 
@@ -308,16 +308,26 @@ export function pikkuFeature<const Scenarios extends readonly unknown[]>(
   return config
 }
 
+/**
+ * One surface's implementation of a step.
+ *
+ * Each binding is typed independently, so a browser binding gets a non-optional
+ * \`wire.browser\` and a cli binding a non-optional \`wire.cli\` without either
+ * leaking into the other.
+ */
 export type PikkuFunctionScenarioStep<
   In = unknown,
   Out = never,
-  B extends boolean = false
-> = PikkuFunctionSessionless<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>
+  Surface extends 'browser' | 'cli' | 'default' = 'default'
+> = PikkuFunctionSessionless<
+  In,
+  Out,
+  Surface extends 'default' ? 'scenarioStep' : 'scenarioStep' | Surface
+>
 
 export type PikkuScenarioStepConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined,
-  B extends boolean = false
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
 > = {
   /** Registered name — this is the string \`scenario.step()\` references. */
   name: string
@@ -336,49 +346,175 @@ export type PikkuScenarioStepConfigWithSchema<
    * sentence per call site.
    */
   template?: string
-  /**
-   * This step drives a browser. The runner provisions one for the step's actor
-   * before calling it — which also makes an actor mandatory — and \`wire.browser\`
-   * is non-optional inside \`func\`.
-   */
-  browser?: B
   title?: string
   tags?: string[]
   input?: InputSchema
   output?: OutputSchema
   errors?: Array<typeof PikkuError>
-  func: PikkuFunctionScenarioStep<
+  /**
+   * Drive this step through a real browser, as a human would. The runner
+   * provisions a window for the step's actor first — which makes an actor
+   * mandatory — and \`wire.browser\` is non-optional inside it.
+   *
+   * Compose shared utilities here rather than writing raw clicks: the step says
+   * what the actor is doing, the utilities say how.
+   */
+  browser?: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'browser'
+  >
+  /** Drive this step remotely, over the websocket. */
+  cli?: PikkuFunctionScenarioStep<
     InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
     OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
-    B
+    'cli'
+  >
+  /**
+   * The server-side path — the fast suite, and the floor every other surface
+   * falls back to.
+   *
+   * On a \`then\`, this is not an alternative to the other bindings but a second
+   * **witness**: the run executes every binding it has and fails if they
+   * disagree, because "the row says paid" and "the page says paid" are different
+   * claims and the gap between them is the bug nobody catches.
+   */
+  default?: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'default'
   >
 }
 
-export type PikkuScenarioStepConfig<In, Out, B extends boolean = false> =
-  Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined, B>, 'func' | 'input' | 'output'> & {
-    func: PikkuFunctionScenarioStep<In, Out, B>
+export type PikkuScenarioStepConfig<In, Out> =
+  Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined>, 'browser' | 'cli' | 'default' | 'input' | 'output'> & {
+    browser?: PikkuFunctionScenarioStep<In, Out, 'browser'>
+    cli?: PikkuFunctionScenarioStep<In, Out, 'cli'>
+    default?: PikkuFunctionScenarioStep<In, Out, 'default'>
   }
 
 /**
- * A named, reusable scenario step. Unlike \`scenario.do\`, which can only name an
- * RPC, a step's body is an ordinary pikku function — so it may drive a browser,
- * invoke RPCs as its actor, or run a workflow.
+ * A named, reusable scenario step, declaring one implementation per surface an
+ * actor can drive it through.
+ *
+ * The step's identity is what the actor is trying to do; which surface carries
+ * it out is a binding. That is what lets one ladder run through a real browser,
+ * over the websocket, or entirely server-side — and what makes "how much of this
+ * flow can a human actually reach" a number rather than a guess.
  *
  * Steps are deliberately NOT registered as RPCs: a browser-driving step must
  * never be network-callable.
  */
 export function pikkuScenarioStep<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined,
-  B extends boolean = false
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
 >(
-  config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema, B>
-): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>, InputSchema, OutputSchema>
-export function pikkuScenarioStep<In, Out = unknown, B extends boolean = false>(
-  config: PikkuScenarioStepConfig<In, Out, B>
-): PikkuFunctionConfig<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>
+  config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep' | 'browser' | 'cli', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser' | 'cli' | 'default'>, InputSchema, OutputSchema>
+export function pikkuScenarioStep<In, Out = unknown>(
+  config: PikkuScenarioStepConfig<In, Out>
+): PikkuFunctionConfig<In, Out, 'scenarioStep' | 'browser' | 'cli'>
 export function pikkuScenarioStep(config: any) {
-  return config
+  const surfaces = (['browser', 'cli', 'default'] as const).filter(
+    (surface) => typeof config[surface] === 'function'
+  )
+  if (surfaces.length === 0) {
+    throw new Error(
+      \`[scenario] step '\${config.name}' declares no surface bindings. Add at least a \\\`default\\\` (server-side) implementation.\`
+    )
+  }
+  return {
+    ...config,
+    surfaces,
+    // The runner sets the surface on the wire and calls this once per binding it
+    // resolved — every witness of a \`then\`, exactly one for an action step.
+    func: (services: any, data: any, wire: any) => {
+      const surface = wire?.scenarioStep?.surface ?? 'default'
+      const binding = config[surface] ?? config.default
+      return binding(services, data, wire)
+    },
+  }
+}
+
+/**
+ * What a step declares when nobody drives it: one implementation, and no
+ * surfaces to choose between.
+ *
+ * \`func\` rather than \`default\` is the point. \`default\` means *the fallback when
+ * no other surface applies*, which implies others could exist; \`func\` says
+ * structurally that there is one way this happens. That also keeps the phase
+ * rule coherent — an assertion runs every witness it has and fails if they
+ * disagree, and this has exactly one by construction.
+ */
+export type PikkuSubjectScenarioStepConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = Omit<
+  PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>,
+  'browser' | 'cli' | 'default'
+> & {
+  func: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'default'
+  >
+}
+
+export type PikkuSubjectScenarioStepConfig<In, Out> =
+  Omit<PikkuScenarioStepConfig<In, Out>, 'browser' | 'cli' | 'default'> & {
+    func: PikkuFunctionScenarioStep<In, Out, 'default'>
+  }
+
+/**
+ * A step in which the app acts on itself — "Given the platform has expired the
+ * trial".
+ *
+ * The grammatical subject of that sentence is not a user of your app; it **is**
+ * your app, which is why it is its own declaration rather than a persona with an
+ * asterisk. A persona is a person.
+ *
+ * Local-test-only, and never in a virtual user's catalogue: a virtual user that
+ * could expire its own trial is manufacturing the outcome it exists to discover.
+ */
+export function pikkuPlatformScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>
+export function pikkuPlatformScenarioStep<In, Out = unknown>(
+  config: PikkuSubjectScenarioStepConfig<In, Out>
+): PikkuFunctionConfig<In, Out, 'scenarioStep'>
+export function pikkuPlatformScenarioStep(config: any) {
+  return { ...config, surfaces: ['default'] }
+}
+
+/**
+ * A step in which a third-party system acts — "Given Stripe's webhook arrives",
+ * "When Mailgun bounces it".
+ *
+ * \`addon\` names the addon that wraps that service, the same name its
+ * \`wireAddon\` declares. These steps *are* the mock its consumers currently
+ * hand-write: shipped by the addon author, maintained with the addon, and the
+ * same artifact that appears in the prose.
+ *
+ * Note that arranging and asserting are different — "Stripe's webhook arrives"
+ * stubs, "Then Stripe was charged" asserts, and only the first is a stub.
+ *
+ * Local-test-only, and never in a virtual user's catalogue: one that could
+ * invoke this would forge its own payment success.
+ */
+export function pikkuAddonScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema> & { addon: string }
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>
+export function pikkuAddonScenarioStep<In, Out = unknown>(
+  config: PikkuSubjectScenarioStepConfig<In, Out> & { addon: string }
+): PikkuFunctionConfig<In, Out, 'scenarioStep'>
+export function pikkuAddonScenarioStep(config: any) {
+  return { ...config, surfaces: ['default'] }
 }
 
 type TypedRef<T> = { $ref: string; path?: string } & { __phantomType?: T }

package/dist/src/functions/workflows/all.workflow.js

@@ -53,6 +53,10 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             // schemas, for one — fails until these two files exist.
             await workflow.do('Bootstrap scope definition types', 'pikkuScopeDefinitionTypes', null);
             await workflow.do('Bootstrap scopes', 'pikkuScopes', { bootstrap: true });
+            await workflow.do('Bootstrap roles', 'pikkuRoles', { bootstrap: true });
+            await workflow.do('Bootstrap personas', 'pikkuPersonas', {
+                bootstrap: true,
+            });
             await workflow.do('Bootstrap function types split', 'pikkuFunctionTypesSplit', { bootstrap: true });
             // Pre-write a stub auth.types.ts (if the project uses better-auth) so the
             // pikkuBetterAuth re-export resolves before any user file is imported.
@@ -155,6 +159,8 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             workflow.do('Credentials', 'pikkuCredentials', null),
             workflow.do('Scope definition types', 'pikkuScopeDefinitionTypes', null),
             workflow.do('Scopes', 'pikkuScopes', {}),
+            workflow.do('Roles', 'pikkuRoles', {}),
+            workflow.do('Personas', 'pikkuPersonas', {}),
             workflow.do('Variable definition types', 'pikkuVariableDefinitionTypes', null),
             workflow.do('Variables', 'pikkuVariables', null),
             workflow.do('Addon types', 'pikkuAddonTypes', null),
@@ -165,7 +171,7 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         if (agents || !config.addon) {
             await workflow.do('Re-inspect after agents', async () => getInspectorState(true));
         }
-        // pikkuAuth generates auth-secrets.gen.ts (with wireSecret calls) inside the
+        // pikkuAuth generates auth-secrets.gen.ts (with defineSecret calls) inside the
         // Promise.all above, but pikkuSecrets runs concurrently from the pre-auth
         // inspector state. Re-run secret/credential/variable codegen now so that the
         // freshly-generated auth-secrets.gen.ts (just picked up by Re-inspect above)