@pikku/cli 0.12.92 → 0.12.96

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)

package/dist/src/server/content-signing-jwt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `pikku dev` and `pikku serve` construct the local content service themselves,
+ * so they must supply the key its signed asset URLs are signed and verified
+ * with — a project is not required to wire a JWTService just to serve uploads
+ * in development.
+ *
+ * The key is random and per-process: URLs signed by one dev server mean
+ * nothing to the next. That is the right lifetime for a development secret,
+ * and it lets the runtime reject any signature it cannot verify instead of
+ * waving through requests when no key is configured.
+ */
+import type { JWTService } from '@pikku/core/services';
+export declare const createEphemeralContentSigningJWT: () => JWTService;

package/dist/src/server/content-signing-jwt.js

@@ -0,0 +1,51 @@
+/**
+ * `pikku dev` and `pikku serve` construct the local content service themselves,
+ * so they must supply the key its signed asset URLs are signed and verified
+ * with — a project is not required to wire a JWTService just to serve uploads
+ * in development.
+ *
+ * The key is random and per-process: URLs signed by one dev server mean
+ * nothing to the next. That is the right lifetime for a development secret,
+ * and it lets the runtime reject any signature it cannot verify instead of
+ * waving through requests when no key is configured.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { getRelativeTimeOffsetFromNow } from '@pikku/core';
+export const createEphemeralContentSigningJWT = () => {
+    const key = randomBytes(32);
+    const sign = (body) => createHmac('sha256', key).update(body).digest('base64url');
+    return {
+        encode: async (expiresIn, payload) => {
+            const envelope = {
+                exp: getRelativeTimeOffsetFromNow(expiresIn).getTime(),
+                payload,
+            };
+            const body = Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64url');
+            return `${body}.${sign(body)}`;
+        },
+        decode: async (hash, invalidHashError) => {
+            const invalid = invalidHashError ?? new Error('Invalid content signature');
+            const [body, signature] = hash.split('.');
+            if (!body || !signature) {
+                throw invalid;
+            }
+            const expected = Buffer.from(sign(body), 'utf8');
+            const actual = Buffer.from(signature, 'utf8');
+            if (expected.length !== actual.length ||
+                !timingSafeEqual(expected, actual)) {
+                throw invalid;
+            }
+            let envelope;
+            try {
+                envelope = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+            }
+            catch {
+                throw invalid;
+            }
+            if (typeof envelope.exp !== 'number' || Date.now() > envelope.exp) {
+                throw invalid;
+            }
+            return envelope.payload;
+        },
+    };
+};

package/dist/src/server/dev-server-runner.interface.d.ts

@@ -9,7 +9,7 @@
  * `services.ts` and injected — no `typeof Bun` checks in the dev command.
  */
 import type { EventHubService } from '@pikku/core';
-import type { Logger } from '@pikku/core/services';
+import type { JWTService, Logger } from '@pikku/core/services';
 import type { NodeHTTPServerConfig } from '@pikku/node-http-server';
 export interface DevServerInstance {
     init(): Promise<void>;
@@ -19,6 +19,14 @@ export interface DevServerInstance {
 }
 /** Config shape both runtimes accept (Core config + host/port/content). */
 export type DevServerConfig = NodeHTTPServerConfig;
+export type DevServerOptions = {
+    /**
+     * The JWTService the dev server's content service signs asset URLs with.
+     * The transport verifies signed asset reads with it, so it must be the same
+     * instance — otherwise every signed URL is rejected.
+     */
+    contentSigningJWT?: JWTService;
+};
 export interface DevServerRunner {
     /**
      * Create the EventHub for this runtime. Shared into singleton services so
@@ -27,5 +35,5 @@ export interface DevServerRunner {
      */
     createEventHub(): Promise<EventHubService<any>>;
     /** Create the dev HTTP/WS server. Must be called after `createEventHub`. */
-    createServer(config: DevServerConfig, logger: Logger): DevServerInstance;
+    createServer(config: DevServerConfig, logger: Logger, options?: DevServerOptions): DevServerInstance;
 }

package/dist/src/server/node-server-runner.d.ts

@@ -5,8 +5,8 @@
  */
 import type { EventHubService } from '@pikku/core';
 import type { Logger } from '@pikku/core/services';
-import type { DevServerRunner, DevServerInstance, DevServerConfig } from './dev-server-runner.interface.js';
+import type { DevServerRunner, DevServerInstance, DevServerConfig, DevServerOptions } from './dev-server-runner.interface.js';
 export declare class NodeServerRunner implements DevServerRunner {
     createEventHub(): Promise<EventHubService<any>>;
-    createServer(config: DevServerConfig, logger: Logger): DevServerInstance;
+    createServer(config: DevServerConfig, logger: Logger, options?: DevServerOptions): DevServerInstance;
 }

package/dist/src/server/node-server-runner.js

@@ -11,12 +11,13 @@ export class NodeServerRunner {
     async createEventHub() {
         return new LocalEventHubService();
     }
-    createServer(config, logger) {
+    createServer(config, logger, options = {}) {
         const wss = new WebSocketServer({ noServer: true });
         const server = new PikkuNodeHTTPServer(config, logger, {
             configureServer: (httpServer) => {
                 pikkuWebsocketHandler({ server: httpServer, wss, logger });
             },
+            contentSigningJWT: options.contentSigningJWT,
         });
         return {
             init: () => server.init(),

package/dist/src/services.d.ts

@@ -12,7 +12,9 @@ export declare function processDiagnostics(diagnostics: InspectorDiagnostic[], l
  */
 export declare const defaultCLIRenderer: import("@pikku/core/cli").CorePikkuCLIRender<ForwardedLogMessage, import("@pikku/core").CoreSingletonServices<{
     logLevel?: LogLevel;
-    secrets?: {};
+    secrets?: {
+        requireAllowedHosts?: boolean;
+    };
     workflow?: import("@pikku/core/workflow").WorkflowServiceConfig;
     webhook?: import("@pikku/core/services").WebhookServiceConfig;
     postgres?: import("@pikku/core").PostgresConfig;

package/dist/src/services.js

@@ -216,7 +216,7 @@ export const createSingletonServices = async (config) => {
                 config.publicRpcFile,
                 config.publicAgentFile,
                 // The auth scaffold (catch-all routes + session middleware) and its
-                // sibling secrets file (wireSecret per provider) are generated into the
+                // sibling secrets file (defineSecret per provider) are generated into the
                 // scaffold dir, which may live outside srcDirectories (e.g. a project's
                 // `pikku/` dir). Add them explicitly so their wirings are inspected.
                 config.authFile,
@@ -259,6 +259,7 @@ export const createSingletonServices = async (config) => {
                 // data-classification leaks. Off by default — it's the dominant codegen
                 // cost. Never runs during a plain `pikku all`.
                 classificationCheck: !setupOnly && !!config.security,
+                strictMeta: !!config.strictMeta,
                 schemaConfig: !setupOnly
                     ? {
                         tsconfig: config.tsconfig,

package/dist/src/utils/pikku-cli-config.js

@@ -1,5 +1,6 @@
 import { join, dirname, resolve, isAbsolute, parse as parsePath } from 'path';
 import { readdir, readFile } from 'fs/promises';
+import { resolveScaffoldFeature } from './resolve-scaffold-feature.js';
 const CLIENT_FILE_KEYS = [
     'fetchFile',
     'websocketFile',
@@ -231,6 +232,32 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         const resolvedScaffoldDir = isAbsolute(scaffoldDir)
             ? scaffoldDir
             : join(result.rootDir, scaffoldDir);
+        // Read every scaffold feature once, here, so a legacy 'auth'/'no-auth'
+        // fails at load with the migration named, rather than downstream where the
+        // value has already been coerced into something plausible.
+        //
+        // An explicit `path` is written onto the feature's output field before the
+        // derivations below run. Each of those is guarded by `!result.<field>`, so
+        // setting it here wins and the pikkuDir-derived default is skipped.
+        const SCAFFOLD_OUTPUT_FIELDS = {
+            rpc: 'publicRpcFile',
+            agent: 'publicAgentFile',
+            console: 'consoleFunctionsFile',
+            scenarios: 'scenariosFunctionsFile',
+            userAdmin: 'userAdminFunctionsFile',
+            workflow: 'workflowRoutesFile',
+            events: 'eventsChannelFile',
+            remoteRpc: 'remoteRpcWorkersFile',
+        };
+        const scaffoldBlock = result.scaffold;
+        for (const [feature, outputField] of Object.entries(SCAFFOLD_OUTPUT_FIELDS)) {
+            const resolved = resolveScaffoldFeature(feature, scaffoldBlock?.[feature]);
+            if (!resolved.enabled || !resolved.path)
+                continue;
+            result[outputField] = isAbsolute(resolved.path)
+                ? resolved.path
+                : join(result.rootDir, resolved.path);
+        }
         if (result.scaffold?.remoteRpc && !result.remoteRpcWorkersFile) {
             result.remoteRpcWorkersFile = join(resolvedScaffoldDir, 'rpc', 'rpc-remote.gen.ts');
         }
@@ -373,8 +400,8 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.workflowMetaDir) {
             result.workflowMetaDir = join(workflowDir, 'meta');
         }
-        if (!result.scenarioActorsFile) {
-            result.scenarioActorsFile = join(workflowDir, 'pikku-scenario-actors.gen.ts');
+        if (!result.personasWiringFile) {
+            result.personasWiringFile = join(workflowDir, 'pikku-personas.gen.ts');
         }
         // Scenarios
         const scenarioDir = join(result.outDir, 'scenarios');
@@ -527,6 +554,22 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.scopesMetaJsonFile) {
             result.scopesMetaJsonFile = join(scopesDir, 'pikku-scopes-meta.gen.json');
         }
+        // System roles (SystemRoleName union + declared role set). Kept beside the
+        // scopes they are composed from — a role is unreadable without them.
+        if (!result.rolesFile) {
+            result.rolesFile = join(scopesDir, 'pikku-roles.gen.ts');
+        }
+        if (!result.rolesMetaJsonFile) {
+            result.rolesMetaJsonFile = join(scopesDir, 'pikku-roles-meta.gen.json');
+        }
+        // Personas. Beside the roles they are checked against, for the same reason
+        // roles sit beside their scopes.
+        if (!result.personasFile) {
+            result.personasFile = join(scopesDir, 'pikku-personas.gen.ts');
+        }
+        if (!result.personasMetaJsonFile) {
+            result.personasMetaJsonFile = join(scopesDir, 'pikku-personas-meta.gen.json');
+        }
         // Variables (typed wrapper for VariablesService)
         const variablesDir = join(result.outDir, 'variables');
         if (!result.variableTypesFile) {

package/dist/src/utils/resolve-personas.d.ts

@@ -0,0 +1,32 @@
+import type { PersonaDefinitions } from '@pikku/core/persona';
+import type { ResolvedPersona } from '@pikku/core/services';
+/**
+ * Where a persona's mail lands when the project has not said.
+ *
+ * Deliberately a domain nobody can own rather than something plausible: an app
+ * that never sends mail runs fine against it, and one that does fails loudly at
+ * the first send instead of quietly delivering a magic link to a stranger.
+ */
+export declare const DEFAULT_PERSONA_EMAIL_DOMAIN = "personas.invalid";
+/**
+ * The personas a run actually sees: every declaration, with its address filled
+ * in.
+ *
+ * Every consumer resolves through here rather than reading the definitions
+ * directly, because the address is the part nobody declares and everybody
+ * needs — codegen writes it into `personaConfigs`, the seed creates the user
+ * rows from it, and both `scenario run` and `persona run` sign in with it.
+ * Computing it in three places is how two of them end up disagreeing.
+ */
+export declare const resolvePersonas: (definitions: PersonaDefinitions, domain?: string, runId?: string) => Record<string, ResolvedPersona>;
+/**
+ * The scopes a persona holds, resolved through its roles.
+ *
+ * Roles are the only thing a persona declares; scopes are what a function
+ * checks. Narrowing a virtual user's catalogue needs the second, so the
+ * expansion happens once, here, against the same `defineSystemRole` definitions
+ * the seed grants from.
+ */
+export declare const personaScopes: (persona: {
+    roles?: readonly string[];
+}, roleScopes: Record<string, readonly string[]>) => string[];

package/dist/src/utils/resolve-personas.js

@@ -0,0 +1,46 @@
+import { personaEmails, validateAndBuildPersonasMeta, } from '@pikku/core/persona';
+/**
+ * Where a persona's mail lands when the project has not said.
+ *
+ * Deliberately a domain nobody can own rather than something plausible: an app
+ * that never sends mail runs fine against it, and one that does fails loudly at
+ * the first send instead of quietly delivering a magic link to a stranger.
+ */
+export const DEFAULT_PERSONA_EMAIL_DOMAIN = 'personas.invalid';
+/**
+ * The personas a run actually sees: every declaration, with its address filled
+ * in.
+ *
+ * Every consumer resolves through here rather than reading the definitions
+ * directly, because the address is the part nobody declares and everybody
+ * needs — codegen writes it into `personaConfigs`, the seed creates the user
+ * rows from it, and both `scenario run` and `persona run` sign in with it.
+ * Computing it in three places is how two of them end up disagreeing.
+ */
+export const resolvePersonas = (definitions, domain = DEFAULT_PERSONA_EMAIL_DOMAIN, runId) => {
+    const meta = validateAndBuildPersonasMeta(definitions);
+    const ids = Object.keys(meta);
+    const emails = personaEmails(ids, domain, runId);
+    const resolved = {};
+    for (const id of ids) {
+        resolved[id] = { ...meta[id], email: emails[id] };
+    }
+    return resolved;
+};
+/**
+ * The scopes a persona holds, resolved through its roles.
+ *
+ * Roles are the only thing a persona declares; scopes are what a function
+ * checks. Narrowing a virtual user's catalogue needs the second, so the
+ * expansion happens once, here, against the same `defineSystemRole` definitions
+ * the seed grants from.
+ */
+export const personaScopes = (persona, roleScopes) => {
+    const scopes = new Set();
+    for (const role of persona.roles ?? []) {
+        for (const scope of roleScopes[role] ?? []) {
+            scopes.add(scope);
+        }
+    }
+    return [...scopes].sort();
+};

package/dist/src/utils/resolve-scaffold-feature.d.ts

@@ -0,0 +1,19 @@
+import type { PikkuScaffoldFeature } from '../../types/config.js';
+export type ResolvedScaffoldFeature = {
+    /** Whether to generate this surface at all. */
+    enabled: boolean;
+    /** Whether the generated surface requires a session. */
+    auth: boolean;
+    /** An explicit output path, or undefined to derive one from `pikkuDir`. */
+    path?: string;
+};
+/**
+ * Reads one `scaffold.<feature>` value.
+ *
+ * `true` means enabled **and authenticated**. A surface only becomes public by
+ * writing `{ auth: false }`, so omitting the field can never open anything —
+ * the failure mode of a forgotten flag is a locked door, not an open one.
+ *
+ * knowledge: decisions/security/scaffold-features-are-authenticated-unless-opted-out.md
+ */
+export declare const resolveScaffoldFeature: (feature: string, value: PikkuScaffoldFeature | undefined) => ResolvedScaffoldFeature;

package/dist/src/utils/resolve-scaffold-feature.js

@@ -0,0 +1,49 @@
+const LEGACY_VALUES = new Set(['auth', 'no-auth']);
+/**
+ * Reads one `scaffold.<feature>` value.
+ *
+ * `true` means enabled **and authenticated**. A surface only becomes public by
+ * writing `{ auth: false }`, so omitting the field can never open anything —
+ * the failure mode of a forgotten flag is a locked door, not an open one.
+ *
+ * knowledge: decisions/security/scaffold-features-are-authenticated-unless-opted-out.md
+ */
+export const resolveScaffoldFeature = (feature, value) => {
+    if (value === undefined || value === false) {
+        return { enabled: false, auth: true };
+    }
+    if (typeof value === 'string') {
+        throw new Error(legacyValueMessage(feature, value));
+    }
+    if (value === true) {
+        return { enabled: true, auth: true };
+    }
+    if (typeof value !== 'object') {
+        throw new Error(`pikku.config.json: scaffold.${feature} must be true, false, or an object ` +
+            `like { "auth": false } — received ${JSON.stringify(value)}.`);
+    }
+    return {
+        enabled: true,
+        auth: value.auth !== false,
+        path: value.path,
+    };
+};
+/**
+ * A legacy `'auth'`/`'no-auth'` is refused by name rather than coerced. The
+ * value it would coerce to is exactly the one that caused the incident this
+ * change came out of, and under the new shape a bare string is a plausible
+ * path — so guessing would be wrong twice over.
+ */
+const legacyValueMessage = (feature, value) => {
+    const migrated = value === 'no-auth' ? '{ "auth": false }' : LEGACY_VALUES.has(value) ? 'true' : null;
+    if (!migrated) {
+        return (`pikku.config.json: scaffold.${feature} must be true, false, or an object ` +
+            `like { "auth": false } — received the string ${JSON.stringify(value)}.`);
+    }
+    return (`pikku.config.json: scaffold.${feature} is ${JSON.stringify(value)}, which is no longer a ` +
+        `mode. Authentication is declared on the function or on the addon, and the ` +
+        `scaffold flag only says whether the surface exists.\n` +
+        `  Replace it with: "${feature}": ${migrated}\n` +
+        `  \`true\` enables the surface with a session required; ` +
+        `\`{ "auth": false }\` makes it public.`);
+};