@pikku/cli 0.12.93 → 0.12.96

package/dist/src/functions/commands/dev-ai-runner.d.ts

@@ -7,10 +7,22 @@ import type { AIAgentRunnerService } from '@pikku/core/services';
  * has no equivalent, so agents 503 with AIProviderNotConfiguredError unless we
  * construct one here. When an OpenAI-compatible base URL + key are present
  * (fabric injects LITELLM_PROXY_URL/LITELLM_API_KEY; the standard OPENAI_*
- * vars are also honored) we point a single openai-compatible provider at it and
- * register it under every common provider prefix. Returns undefined when no AI
- * env is configured (agents stay disabled, with the clear downstream error) or
- * when the AI SDK packages aren't installed in the project.
+ * vars are also honored) we point one provider at it and register it under
+ * `'*'`, so every provider prefix resolves to it. The CLI ships the SDK rather
+ * than asking the project for it — behind a proxy one openai-compatible
+ * provider answers for `openai/…`, `anthropic/…` and `google/…` alike, so there
+ * was never a per-vendor package worth making somebody install. The project's
+ * own copies still win when it has them. Returns undefined when no AI env is
+ * configured (agents stay disabled, with the clear downstream error) or when
+ * the SDK packages cannot be loaded from either place.
+ *
+ * Audio does not work here: `@ai-sdk/openai-compatible` exposes only
+ * language/embedding/image models, so a voice agent under `pikku dev` throws
+ * `Provider does not support transcription models`. Fixing that means the full
+ * `@ai-sdk/openai` provider, which assumes OpenAI's own request specifics — a
+ * bad default for a path whose entire purpose is fronting arbitrary gateways.
+ * If it becomes worth it, delegate just `transcription`/`speech` to the full
+ * provider and leave everything else on this one.
  */
 export declare function createDevAIAgentRunner({ logger, projectRoot, variables, }: {
     logger: Logger;

package/dist/src/functions/commands/dev-ai-runner.js

@@ -1,19 +1,6 @@
 import { createRequire } from 'module';
 import { join } from 'path';
 import { pathToFileURL } from 'url';
-// Provider prefixes a fabric/proxy baseURL fronts. Models are written as
-// `openai/gpt-4o-mini`, `openai/deepseek-v4-flash`, etc. — the runner splits on
-// the first `/`, so the prefix only selects the provider entry and the bare
-// model name is forwarded to the OpenAI-compatible proxy, which routes it.
-const PROXY_PROVIDER_NAMES = [
-    'openai',
-    'anthropic',
-    'google',
-    'gemini',
-    'deepseek',
-    'xai',
-    'litellm',
-];
 /**
  * Build the AI agent runner for `pikku dev` from env.
  *
@@ -21,10 +8,22 @@ const PROXY_PROVIDER_NAMES = [
  * has no equivalent, so agents 503 with AIProviderNotConfiguredError unless we
  * construct one here. When an OpenAI-compatible base URL + key are present
  * (fabric injects LITELLM_PROXY_URL/LITELLM_API_KEY; the standard OPENAI_*
- * vars are also honored) we point a single openai-compatible provider at it and
- * register it under every common provider prefix. Returns undefined when no AI
- * env is configured (agents stay disabled, with the clear downstream error) or
- * when the AI SDK packages aren't installed in the project.
+ * vars are also honored) we point one provider at it and register it under
+ * `'*'`, so every provider prefix resolves to it. The CLI ships the SDK rather
+ * than asking the project for it — behind a proxy one openai-compatible
+ * provider answers for `openai/…`, `anthropic/…` and `google/…` alike, so there
+ * was never a per-vendor package worth making somebody install. The project's
+ * own copies still win when it has them. Returns undefined when no AI env is
+ * configured (agents stay disabled, with the clear downstream error) or when
+ * the SDK packages cannot be loaded from either place.
+ *
+ * Audio does not work here: `@ai-sdk/openai-compatible` exposes only
+ * language/embedding/image models, so a voice agent under `pikku dev` throws
+ * `Provider does not support transcription models`. Fixing that means the full
+ * `@ai-sdk/openai` provider, which assumes OpenAI's own request specifics — a
+ * bad default for a path whose entire purpose is fronting arbitrary gateways.
+ * If it becomes worth it, delegate just `transcription`/`speech` to the full
+ * provider and leave everything else on this one.
  */
 export async function createDevAIAgentRunner({ logger, projectRoot, variables, }) {
     // Pair the URL with its matching key — coalescing each var independently could
@@ -43,28 +42,63 @@ export async function createDevAIAgentRunner({ logger, projectRoot, variables, }
         logger.debug('pikku dev: no AI provider env (OPENAI_BASE_URL/OPENAI_API_KEY or LITELLM_PROXY_URL/LITELLM_API_KEY) — AI agents disabled');
         return undefined;
     }
-    // Resolve from the project's node_modules — the AI SDK packages are the
-    // project's deps, not the CLI's, so they share the project's `ai` version.
-    const require = createRequire(pathToFileURL(join(projectRoot, 'package.json')).href);
+    // The project's own copies win, so an app that pins an `ai` version gets a
+    // runner built from that one rather than a second copy alongside it. The
+    // CLI's are the fallback: this function exists for projects that have not
+    // installed an AI SDK at all, and behind a proxy a single openai-compatible
+    // provider reaches every model, so making someone add three packages before
+    // agents work in dev buys nothing.
+    const fromProject = createRequire(pathToFileURL(join(projectRoot, 'package.json')).href);
+    //
+    // Both come from the same place or neither does. A provider built against one
+    // copy of `@ai-sdk/provider` handed to a runner built against another is the
+    // one combination that fails at call time rather than at load time, with an
+    // error about the model spec that names neither package.
+    const loadPair = async () => {
+        const project = ['@pikku/ai-vercel', '@ai-sdk/openai-compatible'].map((name) => {
+            try {
+                return pathToFileURL(fromProject.resolve(name)).href;
+            }
+            catch {
+                return undefined;
+            }
+        });
+        const [runner, provider] = project.every(Boolean)
+            ? project
+            : ['@pikku/ai-vercel', '@ai-sdk/openai-compatible'];
+        return Promise.all([import(runner), import(provider)]);
+    };
     let VercelAIAgentRunner;
     let createOpenAICompatible;
     try {
-        ;
-        ({ VercelAIAgentRunner } = await import(pathToFileURL(require.resolve('@pikku/ai-vercel')).href));
-        ({ createOpenAICompatible } = await import(pathToFileURL(require.resolve('@ai-sdk/openai-compatible')).href));
+        const [runnerModule, providerModule] = await loadPair();
+        ({ VercelAIAgentRunner } = runnerModule);
+        ({ createOpenAICompatible } = providerModule);
     }
     catch (error) {
-        logger.warn(`pikku dev: AI provider env is set but the AI SDK packages could not be loaded (install @pikku/ai-vercel, @ai-sdk/openai-compatible, and ai) — AI agents disabled: ${error instanceof Error ? error.message : String(error)}`);
+        logger.warn(`pikku dev: AI provider env is set but the AI SDK packages could not be loaded — AI agents disabled: ${error instanceof Error ? error.message : String(error)}`);
         return undefined;
     }
-    const buildProviders = (key) => {
-        const provider = createOpenAICompatible({
+    // One provider under '*', so every prefix a model might name resolves to the
+    // proxy — including ones nobody thought to list. This was a hardcoded array
+    // of seven names, which silently excluded everything else.
+    //
+    // `supportsStructuredOutputs` defaults to false, and the default fails in the
+    // worst available way: an `outputSchema` is dropped, the call degrades to
+    // bare `json_object`, and the model returns well-formed JSON with whatever
+    // keys it felt like. Nothing errors — the caller reads `undefined` off every
+    // field it asked for and behaves as though the model said nothing. Anything
+    // fronting this URL that is worth calling speaks `json_schema`; the ones that
+    // do not now fail loudly on the first schema'd call, which is the outcome we
+    // want over silently ignoring the schema.
+    const buildProviders = (key) => ({
+        '*': createOpenAICompatible({
             name: 'pikku-dev',
             baseURL,
             apiKey: key,
-        });
-        return Object.fromEntries(PROXY_PROVIDER_NAMES.map((name) => [name, provider]));
-    };
+            supportsStructuredOutputs: true,
+        }),
+    });
     logger.info(`pikku dev: AI agent runner wired to ${baseURL}`);
     return new VercelAIAgentRunner(buildProviders(apiKey), buildProviders);
 }

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

@@ -16,6 +16,8 @@ import { startCoverageService } from './start-coverage.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
+import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
+import { resolveScaffoldFeature } from '../../utils/resolve-scaffold-feature.js';
 export const dev = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config, getInspectorState, invalidateInspectorState, variables, devServerRunner, }, { port, watch, hmr, coverage, test }, { rpc }) => {
@@ -122,7 +124,7 @@ export const dev = pikkuSessionlessFunc({
         // project — an app bootstrap is what a deployed bundle imports, and coverage
         // endpoints have no business in one.
         if (config.scaffold?.scenarios) {
-            registerScenarioInstrumentation(config.scaffold.scenarios === 'auth');
+            registerScenarioInstrumentation(resolveScaffoldFeature('scenarios', config.scaffold.scenarios).auth);
         }
         const configModule = await loadUserModule(pikkuConfigFactory.file);
         const servicesModule = await loadUserModule(singletonServicesFactory.file);
@@ -150,8 +152,11 @@ export const dev = pikkuSessionlessFunc({
                 sizeLimit: userConfig.content.sizeLimit,
             }
             : undefined;
-        const localContent = localContentConfig
-            ? new LocalContent(localContentConfig, logger)
+        const contentSigningJWT = localContentConfig
+            ? createEphemeralContentSigningJWT()
+            : undefined;
+        const localContent = localContentConfig && contentSigningJWT
+            ? new LocalContent(localContentConfig, logger, contentSigningJWT)
             : undefined;
         const schedulerService = new InMemorySchedulerService();
         const aiStorage = kysely
@@ -239,7 +244,7 @@ export const dev = pikkuSessionlessFunc({
             port: resolvedPort,
             content: localContentConfig,
             ...(consoleMount ? { staticMounts: [consoleMount] } : {}),
-        }, logger);
+        }, logger, { contentSigningJWT });
         const lifecycle = await loadLifecycle();
         await pikkuServer.init();
         await lifecycle?.beforeStart?.(resolvedServices);

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

@@ -1,15 +1,12 @@
 import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { pikkuVoidFunc } from '#pikku';
-const FEATURE_DEFAULTS = {
-    rpc: 'auth',
-    agent: 'auth',
-    console: 'auth',
-    scenarios: 'auth',
-    workflow: 'auth',
-    events: 'auth',
-    remoteRpc: 'no-auth',
-};
+/**
+ * Remote RPC workers carry no auth dimension — `serialize-remote-rpc.ts`
+ * hardcodes `auth: false` on what it generates — so enabling it writes a bare
+ * `true` and there is nothing to opt out of.
+ */
+const NO_AUTH_DIMENSION = new Set(['remoteRpc']);
 async function enableFeature(feature, logger, config, data) {
     const noAuth = data?.noAuth ?? false;
     const configPath = join(config.configDir, 'pikku.config.json');
@@ -21,18 +18,17 @@ async function enableFeature(feature, logger, config, data) {
     if (!json.scaffold.pikkuDir) {
         json.scaffold.pikkuDir = 'pikku';
     }
-    // The console is an admin surface — every RPC requires a session, so it can
-    // never be scaffolded no-auth (the --no-auth flag is ignored for it).
-    const value = feature === 'webhook'
-        ? true
-        : feature === 'console'
-            ? 'auth'
-            : noAuth
-                ? 'no-auth'
-                : FEATURE_DEFAULTS[feature];
+    // `true` is enabled AND authenticated. Only an explicit --no-auth writes the
+    // object form, so a feature can never be turned on public by accident.
+    //
+    // The console is an admin surface — every RPC requires a session, so
+    // --no-auth is ignored for it.
+    const wantsPublic = noAuth && feature !== 'console' && !NO_AUTH_DIMENSION.has(feature);
+    const value = feature === 'webhook' ? true : wantsPublic ? { auth: false } : true;
     json.scaffold[feature] = value;
     await writeFile(configPath, JSON.stringify(json, null, 2) + '\n', 'utf-8');
-    logger.info(`Enabled scaffold.${feature} = '${value}' in ${configPath}`);
+    logger.info(`Enabled scaffold.${feature} = ${JSON.stringify(value)} in ${configPath}` +
+        (wantsPublic ? ' (public — no session required)' : ''));
 }
 export const enableRpc = pikkuVoidFunc({
     func: async ({ logger, config }, data) => enableFeature('rpc', logger, config, data),

package/dist/src/functions/commands/{scenario-environment.d.ts → environment.d.ts}

@@ -1,22 +1,25 @@
 /**
- * Resolving `pikku scenario run <environment>` to the URLs the run targets.
+ * Resolving `pikku scenario run <environment>` and `pikku persona run
+ * <environment>` to the URLs the run targets.
  *
  * The configured environment is the base; `--api-url`/`--app-url` override it
  * for one invocation, which is what makes a suite runnable against a target
  * that only exists at run time (a freshly provisioned sandbox) without writing
  * a pikku.config.json per deployment.
  */
-/** One entry of `scenarios.environments` in pikku.config.json. */
-export interface ScenarioEnvironment {
+/** One entry of `environments` in pikku.config.json. */
+export interface PikkuEnvironment {
     apiUrl: string;
     signInPath?: string;
     rpcPath?: string;
     appUrl?: string;
+    /** Real consequences: only an `accountable` persona may run against it. */
+    production?: boolean;
 }
-export interface ResolveScenarioEnvironmentOptions {
+export interface ResolveEnvironmentOptions {
     /** The name given on the command line. Must exist in config. */
     environment: string;
-    environments: Record<string, ScenarioEnvironment>;
+    environments: Record<string, PikkuEnvironment>;
     /** `--api-url`, overriding the configured `apiUrl`. */
     apiUrl?: string;
     /** `--app-url`, overriding the configured `appUrl`. */
@@ -29,4 +32,4 @@ export interface ResolveScenarioEnvironmentOptions {
  * all see the same target. The environment is still looked up by name: the
  * flags override fields on a configured environment, they do not invent one.
  */
-export declare const resolveScenarioEnvironment: ({ environment, environments, apiUrl, appUrl, spawn, }: ResolveScenarioEnvironmentOptions) => ScenarioEnvironment;
+export declare const resolveEnvironment: ({ environment, environments, apiUrl, appUrl, spawn, }: ResolveEnvironmentOptions) => PikkuEnvironment;

package/dist/src/functions/commands/{scenario-environment.js → environment.js}

@@ -1,5 +1,6 @@
 /**
- * Resolving `pikku scenario run <environment>` to the URLs the run targets.
+ * Resolving `pikku scenario run <environment>` and `pikku persona run
+ * <environment>` to the URLs the run targets.
  *
  * The configured environment is the base; `--api-url`/`--app-url` override it
  * for one invocation, which is what makes a suite runnable against a target
@@ -35,14 +36,14 @@ const assertAbsoluteUrl = (flag, value) => {
  * all see the same target. The environment is still looked up by name: the
  * flags override fields on a configured environment, they do not invent one.
  */
-export const resolveScenarioEnvironment = ({ environment, environments, apiUrl, appUrl, spawn = false, }) => {
+export const resolveEnvironment = ({ environment, environments, apiUrl, appUrl, spawn = false, }) => {
     const configured = environments[environment];
     if (!configured) {
         const known = Object.keys(environments);
-        throw new Error(`Unknown scenario environment '${environment}'. ` +
+        throw new Error(`Unknown environment '${environment}'. ` +
             (known.length
                 ? `Configured environments: ${known.join(', ')}`
-                : `Add scenarios.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
+                : `Add environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
     }
     const resolved = { ...configured };
     if (apiUrl !== undefined) {

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

@@ -566,13 +566,13 @@ export interface Services extends CoreServices<SingletonServices> {}
     // Conditional: credential / secret file
     if (flags.credential === 'apikey') {
         files[`src/${name}.credential.ts`] = `import { z } from 'zod'
-import { wireCredential } from '@pikku/core/credential'
+import { defineCredential } from '@pikku/core/credential'
 
 export const ${camelName}CredentialSchema = z.object({
   apiKey: z.string().describe(${literal(`${displayName} API key`)}),
 })
 
-wireCredential({
+defineCredential({
   name: '${camelName}',
   displayName: ${literal(displayName)},
   description: ${literal(description)},
@@ -588,13 +588,13 @@ wireCredential({
   tenantId: z.string().optional().describe('Upstream tenant id'),`
             : `  token: z.string().describe(${literal(`${displayName} bearer token`)}),`;
         files[`src/${name}.credential.ts`] = `import { z } from 'zod'
-import { wireCredential } from '@pikku/core/credential'
+import { defineCredential } from '@pikku/core/credential'
 
 export const ${camelName}CredentialSchema = z.object({
 ${credentialFields}
 })
 
-wireCredential({
+defineCredential({
   name: '${camelName}',
   displayName: ${literal(displayName)},
   description: ${literal(description)},
@@ -605,15 +605,15 @@ wireCredential({
     }
     else if (flags.oauth || flags.credential === 'oauth2') {
         files[`src/${name}.credential.ts`] = `import { z } from 'zod'
-import { wireCredential } from '@pikku/core/credential'
-import { wireSecret } from '@pikku/core/secret'
+import { defineCredential } from '@pikku/core/credential'
+import { defineSecret } from '@pikku/core/secret'
 
 export const ${camelName}TokenSchema = z.object({
   accessToken: z.string(),
   refreshToken: z.string().optional(),
 })
 
-wireCredential({
+defineCredential({
   name: '${camelName}',
   displayName: ${literal(displayName)},
   description: ${literal(description)},
@@ -628,7 +628,7 @@ wireCredential({
   },
 })
 
-wireSecret({
+defineSecret({
   name: '${camelName}OAuthApp',
   displayName: ${literal(`${displayName} OAuth App`)},
   description: ${literal(`OAuth2 app credentials for ${displayName}`)},
@@ -638,7 +638,7 @@ wireSecret({
     }
     else if (flags.secret) {
         files[`src/${name}.secret.ts`] = `import { z } from 'zod'
-import { wireSecret } from '@pikku/core/secret'
+import { defineSecret } from '@pikku/core/secret'
 
 export const ${camelName}SecretsSchema = z.object({
   apiKey: z.string().describe(${literal(`${displayName} API key`)}),
@@ -647,7 +647,7 @@ export const ${camelName}SecretsSchema = z.object({
 
 export type ${pascalName}Secrets = z.infer<typeof ${camelName}SecretsSchema>
 
-wireSecret({
+defineSecret({
   name: '${camelName}',
   displayName: ${literal(`${displayName} API`)},
   description: ${literal(description)},
@@ -659,11 +659,11 @@ wireSecret({
     // Conditional: variable file
     if (flags.variable) {
         files[`src/${name}.variable.ts`] = `import { z } from 'zod'
-import { wireVariable } from '@pikku/core/variable'
+import { defineVariable } from '@pikku/core/variable'
 
 export const ${camelName}VariableSchema = z.string().optional().describe('TODO: describe this variable')
 
-wireVariable({
+defineVariable({
   name: '${camelName}_variable',
   displayName: ${literal(`${displayName} Variable`)},
   description: 'TODO: describe this variable',

package/dist/src/functions/commands/persona-sync.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Provision the declared personas into an environment: their accounts, and the
+ * roles they declare.
+ *
+ * This is deployment, not seeding. `pikku db seed` applies a project's test
+ * fixtures and does not run in production; an accountable persona doing a real
+ * job in production still needs an account and its grants, and this is where
+ * they come from.
+ *
+ * Additive in the same way `syncSystemRoles` is: it creates and grants, and
+ * never deletes or revokes. Removing a persona from the code leaves their
+ * account and their grants standing until somebody decides otherwise — which is
+ * the point, because the alternative is a rolling deploy quietly locking out the
+ * teammate that the older replica is still running.
+ *
+ * It needs both halves of an environment: its API, to sign the persona in, and
+ * its database, to write the grants. They must be the same deployment — the
+ * command has no way to check that, so pointing it at a stage's API and a local
+ * database provisions nobody usefully.
+ */
+export declare const personaSync: import("#pikku").PikkuFunctionConfig<{
+    environment: string;
+    apiUrl?: string;
+    dryRun?: boolean;
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    environment: string;
+    apiUrl?: string;
+    dryRun?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    environment: string;
+    apiUrl?: string;
+    dryRun?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

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

@@ -0,0 +1,151 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { createHttpPersonas } from '@pikku/core/persona';
+import { personaEnvironmentRefusal } from '@pikku/core/persona';
+import { resolvePersonas } from '../../utils/resolve-personas.js';
+import { resolveEnvironment } from './environment.js';
+import { loadDeclaredRoles, openScopeServiceForRoles } from './roles-shared.js';
+/**
+ * The user id behind a persona's address.
+ *
+ * Read straight off better-auth's own `user` table rather than through the
+ * ScopeService, because the ScopeService has no notion of an address — its
+ * grants are keyed by user id, and `pikku_user_role.user_id` already FKs into
+ * this exact table. Looking it up anywhere else would mean inventing a second
+ * account concept for personas, which is the one thing this command exists to
+ * avoid: a persona is a user, provisioned the way users are.
+ */
+const userIdByEmail = async (db, email) => {
+    const row = await db
+        .selectFrom('user')
+        .select('id')
+        .where('email', '=', email)
+        .executeTakeFirst();
+    return row ? String(row.id) : null;
+};
+/**
+ * Provision the declared personas into an environment: their accounts, and the
+ * roles they declare.
+ *
+ * This is deployment, not seeding. `pikku db seed` applies a project's test
+ * fixtures and does not run in production; an accountable persona doing a real
+ * job in production still needs an account and its grants, and this is where
+ * they come from.
+ *
+ * Additive in the same way `syncSystemRoles` is: it creates and grants, and
+ * never deletes or revokes. Removing a persona from the code leaves their
+ * account and their grants standing until somebody decides otherwise — which is
+ * the point, because the alternative is a rolling deploy quietly locking out the
+ * teammate that the older replica is still running.
+ *
+ * It needs both halves of an environment: its API, to sign the persona in, and
+ * its database, to write the grants. They must be the same deployment — the
+ * command has no way to check that, so pointing it at a stage's API and a local
+ * database provisions nobody usefully.
+ */
+export const personaSync = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config, getInspectorState, variables }, { environment, apiUrl, dryRun }) => {
+        const state = await getInspectorState(true, false, false, true);
+        const personas = resolvePersonas(state.personas?.definitions ?? [], config.scenarios?.emailDomain);
+        if (Object.keys(personas).length === 0) {
+            logger.info('persona sync: no personas are declared — add a definePersonas({ … }) call.');
+            return;
+        }
+        const environments = config.environments ?? {};
+        const env = resolveEnvironment({ environment, environments, apiUrl });
+        // The same rule that decides who may *run* against an environment decides
+        // who may be provisioned into it. Two rules would drift, and the one that
+        // drifted would leave an account standing in production for a persona the
+        // engine then refuses to sign in.
+        //
+        // A `runnable: false` persona is still provisioned: their account is the
+        // whole reason they were declared, because other people act on it.
+        const eligible = [];
+        const skipped = [];
+        for (const [id, persona] of Object.entries(personas)) {
+            const refusal = personaEnvironmentRefusal(id, persona, environment, environments);
+            if (refusal) {
+                skipped.push(refusal);
+                continue;
+            }
+            eligible.push([id, persona]);
+        }
+        if (eligible.length === 0) {
+            logger.info(`persona sync: no persona may act in '${environment}' — ${skipped.length} declared persona(s) were all skipped.`);
+            logger.info('  Run with --dry-run for the reasons, or give the persona this environment and disposition `accountable` if it is production.');
+            return;
+        }
+        if (dryRun) {
+            logger.info(`persona sync (dry run): ${eligible.length} persona(s) would be provisioned into '${environment}' at ${env.apiUrl}:`);
+            for (const [id, persona] of eligible) {
+                logger.info(`  ${id.padEnd(20)} ${persona.email}${persona.roles.length
+                    ? ` -> ${persona.roles.join(' + ')}`
+                    : ' (no roles)'}`);
+            }
+            for (const refusal of skipped) {
+                logger.info(`  skipped: ${refusal}`);
+            }
+            logger.info('Re-run without --dry-run to apply.');
+            return;
+        }
+        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
+        if (!secret) {
+            throw new Error('SCENARIO_ACTOR_SECRET is not set — a persona account cannot be created. ' +
+                'Export it in the environment running this command (never put it in pikku.config.json).');
+        }
+        const declaredRoles = await loadDeclaredRoles(config.rolesMetaJsonFile, logger);
+        if (!declaredRoles) {
+            throw new Error('role metadata not found');
+        }
+        const signedIn = createHttpPersonas({
+            apiUrl: env.apiUrl,
+            secret,
+            personas: Object.fromEntries(eligible),
+            signInPath: env.signInPath,
+            rpcPath: env.rpcPath,
+        });
+        // Roles are synced on the way in, so a grant can name a role this deploy
+        // introduced. Both that sync and everything below are additive.
+        const opened = await openScopeServiceForRoles({ config, logger }, declaredRoles, 'pikku persona sync');
+        if (!opened) {
+            return;
+        }
+        try {
+            let accounts = 0;
+            let granted = 0;
+            let held = 0;
+            for (const [id, persona] of eligible) {
+                // Signing in is what creates the account: the actor plugin upserts an
+                // `actor: true` user row on first sign-in, and nothing else does.
+                // `sessionRoles()` is the public call that forces it — its answer is a
+                // by-product here, not the reason for the call.
+                await signedIn[id].sessionRoles();
+                accounts++;
+                if (persona.roles.length === 0) {
+                    logger.info(`  ${id.padEnd(20)} ${persona.email} (no roles)`);
+                    continue;
+                }
+                const userId = await userIdByEmail(opened.db, persona.email);
+                if (!userId) {
+                    throw new Error(`persona sync: signed '${id}' in at ${env.apiUrl}, but no user row for ${persona.email} exists in the database this command opened. ` +
+                        `That database is not the one '${environment}' runs on, so its grants would land nowhere.`);
+                }
+                const already = new Set(await opened.service.listUserRoles(userId));
+                const missing = persona.roles.filter((role) => !already.has(role));
+                for (const role of missing) {
+                    await opened.service.addUserToRole(userId, role);
+                }
+                granted += missing.length;
+                held += persona.roles.length - missing.length;
+                logger.info(`  ${id.padEnd(20)} ${persona.email} -> ${persona.roles.join(' + ')}${missing.length === 0 ? ' (already held)' : ''}`);
+            }
+            logger.info(`persona sync: ${accounts} account(s) in '${environment}', ${granted} role grant(s) applied, ${held} already held`);
+            if (skipped.length > 0) {
+                logger.info(`  ${skipped.length} persona(s) skipped — they do not act in '${environment}'. Run with --dry-run for the reasons.`);
+            }
+        }
+        finally {
+            await opened.destroy();
+        }
+    },
+});

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

@@ -0,0 +1,58 @@
+/**
+ * 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 declare const personaRun: import("#pikku").PikkuFunctionConfig<{
+    environment: string;
+    persona: string;
+    disposition?: string;
+    goals?: string;
+    steps?: string;
+    mutations?: string;
+    duration?: string;
+    seed?: string;
+    model?: string;
+    apiUrl?: string;
+    allowApproval?: boolean;
+    skipRoleCheck?: boolean;
+    out?: string;
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    environment: string;
+    persona: string;
+    disposition?: string;
+    goals?: string;
+    steps?: string;
+    mutations?: string;
+    duration?: string;
+    seed?: string;
+    model?: string;
+    apiUrl?: string;
+    allowApproval?: boolean;
+    skipRoleCheck?: boolean;
+    out?: string;
+}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    environment: string;
+    persona: string;
+    disposition?: string;
+    goals?: string;
+    steps?: string;
+    mutations?: string;
+    duration?: string;
+    seed?: string;
+    model?: string;
+    apiUrl?: string;
+    allowApproval?: boolean;
+    skipRoleCheck?: boolean;
+    out?: string;
+}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+/** Who this app is for, and what each of them wants, without running anything. */
+export declare const personaList: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;