@pikku/cli 0.12.117 → 0.12.119

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

@@ -1,51 +1,26 @@
 import { pikkuSessionlessFunc } from '#pikku/function';
-import { createHttpPersonas } from '@pikku/core/persona';
 import { personaEnvironmentRefusal } from '@pikku/core/persona';
 import { resolvePersonas } from '../../utils/resolve-personas.js';
-import { resolvePersonaCredentials } from '../../utils/persona-credentials.js';
-import { resolveEnvironment } from './environment.js';
-import { loadDeclaredRoles, openScopeServiceForRoles } from './roles-shared.js';
 /**
- * The user id behind a persona's address.
+ * Report which personas an environment will provision, and which it will not.
  *
- * 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 reset` 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 reports rather than writes, because the writing happens somewhere this
+ * command cannot reach. Provisioning a persona means creating a user row and
+ * granting it roles, and both of those live in the deployment's database — one
+ * the CLI has no connection to for any environment that is not the developer's
+ * own. This command used to open a Kysely connection from the local project
+ * config and write through it, which provisioned a local stage correctly and
+ * silently provisioned the wrong database for every other environment.
  *
- * 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.
+ * So the deployment provisions itself: an app calls `provisionPersonas` from
+ * `@pikku/better-auth` in its server lifecycle, where the database connection
+ * and better-auth's own adapter are both already open, and a deploy carries its
+ * personas with it. What is left here is the half that needs no database — the
+ * declaration, and the environment rule applied to it — which is what tells you
+ * before a deploy whether the accounts you expect will appear.
  */
 export const personaSync = pikkuSessionlessFunc({
-    remote: true,
-    func: async ({ logger, config, getInspectorState, variables }, { environment, apiUrl, dryRun }) => {
+    func: async ({ logger, config, getInspectorState }, { environment }) => {
         const state = await getInspectorState(true, false, false, true);
         const personas = resolvePersonas(state.personas?.definitions ?? [], config.scenarios?.emailDomain);
         if (Object.keys(personas).length === 0) {
@@ -53,9 +28,11 @@ export const personaSync = pikkuSessionlessFunc({
             return;
         }
         const environments = config.environments ?? {};
-        const env = resolveEnvironment({ environment, environments, apiUrl });
+        if (!environments[environment]) {
+            throw new Error(`Unknown environment '${environment}'. Configured environments: ${Object.keys(environments).join(', ') || 'none'}.`);
+        }
         // 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
+        // who is 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.
         //
@@ -73,76 +50,21 @@ export const personaSync = pikkuSessionlessFunc({
         }
         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(`  ${refusal}`);
             }
-            logger.info('Re-run without --dry-run to apply.');
-            return;
-        }
-        const credentials = await resolvePersonaCredentials(variables, 'a persona account');
-        const declaredRoles = await loadDeclaredRoles(config.rolesMetaJsonFile, logger);
-        if (!declaredRoles) {
-            throw new Error('role metadata not found');
-        }
-        const signedIn = createHttpPersonas({
-            apiUrl: env.apiUrl,
-            ...credentials,
-            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) {
+            logger.info('  Give the persona this environment, and disposition `accountable` if it is production.');
             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.`);
-            }
+        logger.info(`persona sync: ${eligible.length} persona(s) will be provisioned when a deployment of '${environment}' starts:`);
+        for (const [id, persona] of eligible) {
+            logger.info(`  ${id.padEnd(20)} ${persona.email}${persona.roles.length
+                ? ` -> ${persona.roles.join(' + ')}`
+                : ' (no roles)'}`);
         }
-        finally {
-            await opened.destroy();
+        for (const refusal of skipped) {
+            logger.info(`  skipped: ${refusal}`);
         }
+        logger.info("  Provisioning runs in the deployment: call `provisionPersonas` from '@pikku/better-auth' in your server lifecycle, passing `personaConfigs` and `personaEnvironments` from the generated personas file.");
     },
 });

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

@@ -18,11 +18,13 @@ import { createDevAgentRunner } from './dev-agent-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
 import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
+import { disableDevActorSignIn } from '../../server/actor-sign-in.js';
 import { applyModelAliasOverride } from '../../utils/model-alias-override.js';
 export const serve = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole, model }) => {
         process.env.PIKKU_DEV_QUICK_LOGIN ??= 'true';
+        disableDevActorSignIn(logger);
         applyModelAliasOverride(logger, model, config.models);
         const resolvedPort = parseInt(port || '3000', 10);
         const hostname = 'localhost';

package/dist/src/functions/validate/auth-plugin-checks.d.ts

@@ -0,0 +1,16 @@
+import type { ValidateFinding } from './persona-checks.js';
+export type AuthPluginCheckConfig = {
+    srcDirectories?: unknown;
+};
+/**
+ * Whether better-auth is configured the way pikku supports.
+ *
+ * Pikku authorizes on scopes, so better-auth's `admin()` — which authorizes its
+ * endpoints against a `user.role` column — is unsupported: wiring it means
+ * running two authorization models and projecting one onto the other. The
+ * inspector refuses it outright at prebuild; this reports the same thing
+ * without one, and additionally catches the quieter half of the migration, an
+ * app that dropped `admin()` and never wired `ban()`, which keeps its ban
+ * columns and its ban UI while silently enforcing nothing.
+ */
+export declare const runAuthPluginChecks: (root: string, config: AuthPluginCheckConfig | null) => Promise<ValidateFinding[]>;

package/dist/src/functions/validate/auth-plugin-checks.js

@@ -0,0 +1,165 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const lines = (...parts) => parts.join('\n');
+/** Local rather than imported from shared-checks, which imports this module. */
+const readTextSafe = async (path) => {
+    if (!existsSync(path))
+        return null;
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const stringArray = (value) => Array.isArray(value)
+    ? value.filter((v) => typeof v === 'string')
+    : [];
+/**
+ * Source files under one directory, generated files included — better-auth is
+ * routinely configured in a file the auth scaffold wrote.
+ */
+const listSourceFiles = async (dir) => {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return (await readdir(dir, { recursive: true }))
+            .filter((f) => typeof f === 'string' &&
+            (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+            !f.includes('node_modules'))
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * The text inside every `plugins: [...]` array in the file.
+ *
+ * Bracket-counted rather than parsed: `pikku validate` runs without a TypeScript
+ * program, and a `]` inside a string literal in a plugin's options is the only
+ * way this misreads an array — at which point the check under-reports rather
+ * than inventing a finding.
+ */
+const pluginArrays = (text) => {
+    const arrays = [];
+    const opener = /plugins\s*:\s*\[/g;
+    let match;
+    while ((match = opener.exec(text))) {
+        const start = match.index + match[0].length;
+        let depth = 1;
+        let i = start;
+        while (i < text.length && depth > 0) {
+            if (text[i] === '[')
+                depth++;
+            else if (text[i] === ']')
+                depth--;
+            i++;
+        }
+        if (depth === 0)
+            arrays.push(text.slice(start, i - 1));
+    }
+    return arrays;
+};
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * How `exported` from `module` can be called in this file: the local name a
+ * named import bound it to, or `<namespace>.<exported>` for a namespace import.
+ * Empty when the file never imports it, so a local helper of the same name is
+ * not mistaken for the package's.
+ */
+const importedCallees = (text, module, exported) => {
+    const callees = [];
+    const imports = /import\s+([\s\S]*?)\s+from\s*['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = imports.exec(text))) {
+        if (match[2] !== module)
+            continue;
+        const clause = match[1];
+        const namespace = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/);
+        if (namespace) {
+            callees.push(`${namespace[1]}.${exported}`);
+            continue;
+        }
+        const named = clause.match(/\{([\s\S]*?)\}/);
+        if (!named)
+            continue;
+        for (const entry of named[1].split(',')) {
+            const [imported, alias] = entry.split(/\s+as\s+/).map((v) => v.trim());
+            if (imported === exported)
+                callees.push(alias || imported);
+        }
+    }
+    return callees;
+};
+/**
+ * Whether `exported` from `module` is wired as a plugin — imported from that
+ * package *and* called inside a `plugins: [...]` array. An import left behind
+ * after the call was removed configures nothing, and a call somewhere else in
+ * the file is not a plugin.
+ */
+const configuresPlugin = (text, module, exported) => {
+    const callees = importedCallees(text, module, exported);
+    if (callees.length === 0)
+        return false;
+    return pluginArrays(text).some((array) => callees.some((callee) => new RegExp(`(^|[^\\w$.])${escapeRegExp(callee)}\\s*\\(`).test(array)));
+};
+/**
+ * Whether better-auth is configured the way pikku supports.
+ *
+ * Pikku authorizes on scopes, so better-auth's `admin()` — which authorizes its
+ * endpoints against a `user.role` column — is unsupported: wiring it means
+ * running two authorization models and projecting one onto the other. The
+ * inspector refuses it outright at prebuild; this reports the same thing
+ * without one, and additionally catches the quieter half of the migration, an
+ * app that dropped `admin()` and never wired `ban()`, which keeps its ban
+ * columns and its ban UI while silently enforcing nothing.
+ */
+export const runAuthPluginChecks = async (root, config) => {
+    const findings = [];
+    const srcDirectories = stringArray(config?.srcDirectories);
+    const searchDirs = srcDirectories.length
+        ? srcDirectories
+        : [join('packages', 'functions', 'src')];
+    const sourceFiles = (await Promise.all(searchDirs.map((dir) => listSourceFiles(join(root, dir))))).flat();
+    let bansAnywhere = false;
+    const adminFiles = [];
+    for (const file of sourceFiles) {
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        if (configuresPlugin(text, 'better-auth/plugins', 'admin'))
+            adminFiles.push(file);
+        if (configuresPlugin(text, '@pikku/better-auth', 'ban'))
+            bansAnywhere = true;
+    }
+    for (const file of adminFiles) {
+        findings.push({
+            id: 'better-auth-admin-plugin',
+            severity: 'error',
+            message: "better-auth's admin() plugin is not supported — it authorizes against a user.role column while pikku authorizes on scopes, so one has to be projected onto the other",
+            path: file,
+            fixHint: lines('Replace it with ban(), which keeps the one capability admin() had that', 'pikku cannot supply from outside better-auth — refusing a banned user a', 'session:', "  import { ban } from '@pikku/better-auth'", '  betterAuth({ plugins: [ban()] })', 'User management is already scoped RPCs in @pikku/addon-admin: list,', 'create, ban, remove, revoke sessions and set password.'),
+        });
+    }
+    if (!bansAnywhere && adminFiles.length === 0) {
+        const configuresAuth = sourceFiles.length > 0;
+        if (configuresAuth) {
+            for (const file of sourceFiles) {
+                const text = await readTextSafe(file);
+                if (!text || !/\bpikkuBetterAuth\s*\(/.test(text))
+                    continue;
+                findings.push({
+                    id: 'better-auth-no-ban-plugin',
+                    severity: 'warn',
+                    message: 'better-auth is configured without ban() — the banned/banReason/banExpires columns do not exist, so banning a user through @pikku/addon-admin has nothing to write and nothing refuses their next sign-in',
+                    path: file,
+                    fixHint: lines("  import { ban } from '@pikku/better-auth'", '  betterAuth({ plugins: [ban()] })', 'Wire it wherever the rest of your plugins are, then run', '`pikku db migrate` to add the columns.'),
+                });
+                break;
+            }
+        }
+    }
+    return findings;
+};

package/dist/src/functions/validate/persona-checks.js

@@ -123,7 +123,7 @@ export const runPersonaChecks = async (root, config) => {
         return findings;
     }
     if (!(await hasActorSignIn(sourceFiles))) {
-        w('personas-no-actor-sign-in', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but nothing wires actor sign-in — a scenario run signs in over POST /auth/sign-in/actor, so every persona fails to acquire a session`, pikkuConfigPath, lines('Wire the actor plugin where better-auth is configured:', "  import { actor } from '@pikku/better-auth'", '  plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]', 'The plugin refuses every sign-in while the secret is unset, so a stage', 'that must not run scenarios simply leaves SCENARIO_ACTOR_SECRET out.'));
+        w('personas-no-actor-sign-in', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but nothing wires actor sign-in — a scenario run signs in over POST /auth/sign-in/actor, so every persona fails to acquire a session`, pikkuConfigPath, lines('Wire the actor plugin where better-auth is configured:', "  import { actor } from '@pikku/better-auth'", '  plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]', '`pikku dev` turns the endpoint on and mints the secret itself, so there', 'is nothing to configure locally. A deployed stage that must run', 'scenarios opts in with', 'PIKKU_ALLOW_ACTOR_SIGN_IN=passwordless-actor-sign-in; everywhere else', 'the endpoint stays off whatever the environment happens to contain.'));
     }
     const environments = config?.environments;
     const hasEnvironment = typeof environments === 'object' &&

package/dist/src/functions/validate/shared-checks.js

@@ -4,7 +4,10 @@ import { join } from 'node:path';
 import { runKnowledgeValidate } from '@pikku/knowledge';
 import { runBootstrapChecks } from './bootstrap-checks.js';
 import { runPersonaChecks } from './persona-checks.js';
+import { runAuthPluginChecks } from './auth-plugin-checks.js';
 import { runScenarioFileChecks } from './scenario-file-checks.js';
+import { projectWiresChannels, runWebsocketDepsChecks, } from './websocket-deps-checks.js';
+import { resolveFromProject } from '../../utils/resolve-from-project.js';
 /**
  * A malformed config is named, never reported as absent.
  *
@@ -311,8 +314,17 @@ export async function runSharedProjectChecks(root) {
     }
     // ── server bootstrap ───────────────────────────────────────────────────
     findings.push(...(await runBootstrapChecks(root, rootPkg, pikkuConfig)));
+    findings.push(...runWebsocketDepsChecks({
+        root,
+        runtime: typeof globalThis.Bun !== 'undefined'
+            ? 'bun'
+            : 'node',
+        hasChannels: await projectWiresChannels(root, typeof pikkuConfig?.outDir === 'string' ? pikkuConfig.outDir : '.pikku'),
+        resolve: (specifier) => resolveFromProject(root, specifier),
+    }));
     // ── personas, scenario files and the knowledge base ────────────────────
     findings.push(...(await runPersonaChecks(root, pikkuConfig)));
+    findings.push(...(await runAuthPluginChecks(root, pikkuConfig)));
     const srcDirectories = Array.isArray(pikkuConfig?.srcDirectories)
         ? pikkuConfig.srcDirectories.filter((d) => typeof d === 'string')
         : [];

package/dist/src/functions/validate/websocket-deps-checks.d.ts

@@ -0,0 +1,30 @@
+import type { ValidateFinding } from './persona-checks.js';
+/**
+ * The packages the Node dev/serve path needs to speak WebSocket. Both are
+ * optional peers of `@pikku/cli`, because Bun serves WebSockets natively
+ * through `@pikku/bun-server` and a Bun project has no use for either.
+ */
+export declare const NODE_WEBSOCKET_PACKAGES: readonly ["@pikku/ws", "ws"];
+export type WebsocketDepsInput = {
+    root: string;
+    /** The runtime the CLI is running on. Bun needs neither package. */
+    runtime: 'node' | 'bun';
+    /** Whether the project wires any channels. Nothing is reported when not. */
+    hasChannels: boolean;
+    /** Resolves a specifier from the project. `undefined` when not installed. */
+    resolve: (specifier: string) => string | undefined;
+};
+/**
+ * Reports the optional WebSocket peers when a Node-hosted project that wires
+ * channels is missing them.
+ *
+ * `pikku dev` / `pikku serve` under Node start over plain HTTP when the
+ * packages are absent, rather than failing: a project with no channels does not
+ * need them, and making them hard dependencies of the CLI is what put a second
+ * `@pikku/core` in the tree. That leaves a project that *does* wire channels
+ * with sockets that never connect and nothing pointing at the cause — which is
+ * this check.
+ */
+export declare function runWebsocketDepsChecks(input: WebsocketDepsInput): ValidateFinding[];
+/** True when codegen produced at least one channel for this project. */
+export declare function projectWiresChannels(root: string, outDir: string): Promise<boolean>;

package/dist/src/functions/validate/websocket-deps-checks.js

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+import { readJsonSafe } from './shared-checks.js';
+/**
+ * The packages the Node dev/serve path needs to speak WebSocket. Both are
+ * optional peers of `@pikku/cli`, because Bun serves WebSockets natively
+ * through `@pikku/bun-server` and a Bun project has no use for either.
+ */
+export const NODE_WEBSOCKET_PACKAGES = ['@pikku/ws', 'ws'];
+/**
+ * Reports the optional WebSocket peers when a Node-hosted project that wires
+ * channels is missing them.
+ *
+ * `pikku dev` / `pikku serve` under Node start over plain HTTP when the
+ * packages are absent, rather than failing: a project with no channels does not
+ * need them, and making them hard dependencies of the CLI is what put a second
+ * `@pikku/core` in the tree. That leaves a project that *does* wire channels
+ * with sockets that never connect and nothing pointing at the cause — which is
+ * this check.
+ */
+export function runWebsocketDepsChecks(input) {
+    const { root, runtime, hasChannels, resolve } = input;
+    if (runtime === 'bun' || !hasChannels)
+        return [];
+    const missing = NODE_WEBSOCKET_PACKAGES.filter((name) => !resolve(name));
+    if (missing.length === 0)
+        return [];
+    const named = missing.join(' and ');
+    return [
+        {
+            id: 'websocket-deps-missing',
+            severity: 'error',
+            message: `${named} ${missing.length > 1 ? 'are' : 'is'} not installed, but this project wires channels — \`pikku dev\` and \`pikku serve\` will start without WebSocket support and every channel connection will fail`,
+            path: join(root, 'package.json'),
+            fixHint: `Install ${NODE_WEBSOCKET_PACKAGES.join(' ')} in this project. They are optional peer dependencies of @pikku/cli so that Bun projects, which serve WebSockets natively, do not pull them in`,
+        },
+    ];
+}
+/** True when codegen produced at least one channel for this project. */
+export async function projectWiresChannels(root, outDir) {
+    const meta = await readJsonSafe(join(root, outDir, 'channel', 'pikku-channels-meta.gen.json'));
+    return !!meta && Object.keys(meta).length > 0;
+}

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

@@ -3,7 +3,7 @@
  *
  * `SCENARIO_ACTOR_SECRET` is the platform's, not the application's: nothing in
  * app code reads it. It is consumed by the scenario service when it signs an
- * actor in, by `pikku scenario` / `pikku persona` / `pikku persona sync`, and by
+ * actor in, by `pikku scenario` / `pikku persona`, and by
  * the Playwright provider. Declaring it here — rather than leaving every project
  * to hand-write the same `defineSecret` — is the same reasoning that puts
  * `BETTER_AUTH_SECRET` in the auth scaffold: a value the framework requires

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

@@ -3,7 +3,7 @@
  *
  * `SCENARIO_ACTOR_SECRET` is the platform's, not the application's: nothing in
  * app code reads it. It is consumed by the scenario service when it signs an
- * actor in, by `pikku scenario` / `pikku persona` / `pikku persona sync`, and by
+ * actor in, by `pikku scenario` / `pikku persona`, and by
  * the Playwright provider. Declaring it here — rather than leaving every project
  * to hand-write the same `defineSecret` — is the same reasoning that puts
  * `BETTER_AUTH_SECRET` in the auth scaffold: a value the framework requires

package/dist/src/functions/wirings/scopes/pikku-command-scopes.d.ts

@@ -1,3 +1,13 @@
+import type { PersonaDefinitions } from '@pikku/core/persona';
+import type { ScopeDefinitions } from '@pikku/core/scope';
+/**
+ * The declared scopes, plus the `app` tree derived from the personas.
+ *
+ * Appended here rather than in the inspector because it is not a declaration
+ * the AST can find: it is the personas' `app` field read as a scope, and this
+ * is the one place the two states are both in hand.
+ */
+export declare const withAppScopes: (scopes: ScopeDefinitions, personas: PersonaDefinitions) => ScopeDefinitions;
 export declare const pikkuScopes: import("#pikku/function").PikkuFunctionConfig<{
     bootstrap?: boolean;
 }, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{

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

@@ -4,6 +4,22 @@ import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-
 import { serializeScopesTypes } from './serialize-scopes-types.js';
 import { serializeScopesClient } from './serialize-scopes-client.js';
 import { validateAndBuildScopeDefinitionsMeta } from '@pikku/core/scope';
+import { APP_SCOPE_ROOT, buildAppScopeDefinition } from '@pikku/core/persona';
+/**
+ * The declared scopes, plus the `app` tree derived from the personas.
+ *
+ * Appended here rather than in the inspector because it is not a declaration
+ * the AST can find: it is the personas' `app` field read as a scope, and this
+ * is the one place the two states are both in hand.
+ */
+export const withAppScopes = (scopes, personas) => {
+    const declared = scopes.find((scope) => scope.name === APP_SCOPE_ROOT);
+    if (declared) {
+        throw new Error(`'${APP_SCOPE_ROOT}' is reserved: it is derived from the apps your personas name, and ${declared.sourceFile ?? 'a defineScope call'} declares it too. Rename that scope root — two trees answering to one name make a grant ambiguous.`);
+    }
+    const appScopes = buildAppScopeDefinition(personas);
+    return appScopes ? [...scopes, appScopes] : scopes;
+};
 export const pikkuScopes = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }, data) => {
         const { scopesFile, scopesMetaJsonFile } = config;
@@ -19,15 +35,16 @@ export const pikkuScopes = pikkuSessionlessFunc({
         // Scopes step regenerates it with the declarations once setup has run.
         const bootstrap = data?.bootstrap ?? false;
         const state = await getInspectorState(false, bootstrap, bootstrap);
+        const definitions = withAppScopes(state.scopes.definitions, state.personas.definitions);
         const content = serializeScopesTypes({
-            definitions: state.scopes.definitions,
+            definitions,
         });
         await writeFileInDir(logger, scopesFile, content);
         if (scopesClientFile) {
-            await writeFileInDir(logger, scopesClientFile, serializeScopesClient({ definitions: state.scopes.definitions }));
+            await writeFileInDir(logger, scopesClientFile, serializeScopesClient({ definitions }));
         }
         if (scopesMetaJsonFile) {
-            const meta = validateAndBuildScopeDefinitionsMeta(state.scopes.definitions);
+            const meta = validateAndBuildScopeDefinitionsMeta(definitions);
             await writeFileInDir(logger, scopesMetaJsonFile, JSON.stringify(meta, null, 2));
         }
     },

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

@@ -103,7 +103,7 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
         {
             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));
+            await writeFileInDir(logger, config.personasWiringFile, serializePersonas(personas, agentMapImportPath, exposedRpcMapImportPath, config.environments ?? {}));
             // Same reason as the scenario meta above: a project generated before this
             // moved to `scenarios/` still has a copy under `workflow/`, and tsc
             // compiles every file in the output tree whether anything imports it.

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

@@ -1,3 +1,4 @@
+import type { PersonaEnvironment } from '@pikku/core/persona';
 import type { ResolvedPersona } from '@pikku/core/services';
 /**
  * The runtime half of `definePersonas()`.
@@ -7,4 +8,4 @@ import type { ResolvedPersona } from '@pikku/core/services';
  * 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;
+export declare const serializePersonas: (personas: Record<string, ResolvedPersona>, agentMapImportPath: string, rpcMapImportPath: string, environments?: Readonly<Record<string, PersonaEnvironment>>) => string;

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

@@ -6,7 +6,14 @@
  * 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) => {
+export const serializePersonas = (personas, agentMapImportPath, rpcMapImportPath, environments = {}) => {
+    // Only the flag the rule reads. The rest of an environment entry is its
+    // apiUrl and paths, which belong to the machine running `pikku scenario` and
+    // have no business inside the deployed bundle.
+    const projected = Object.fromEntries(Object.entries(environments).map(([name, environment]) => [
+        name,
+        environment.production ? { production: true } : {},
+    ]));
     return `/** Personas declared with definePersonas() */
 import { createHttpPersonas } from '@pikku/core/persona'
 import type { HttpPersonasConfig } from '@pikku/core/persona'
@@ -27,6 +34,18 @@ export type PersonaName = keyof typeof personaConfigs
  */
 export const personaList: ResolvedPersona[] = Object.values(personaConfigs)
 
+/**
+ * The \`environments\` block of pikku.config.json, carried into the runtime.
+ *
+ * A persona's environments are checked twice: at build time against the config,
+ * and again wherever a persona is signed in or provisioned, against the
+ * environment the running process says it is (\`PIKKU_ENV\`). The second check
+ * is not the first one repeated — the build check trusts the file, and the run
+ * check does not trust which artifact got deployed — so the rule needs the
+ * config on both sides of the build.
+ */
+export const personaEnvironments = ${JSON.stringify(projected, null, 2)} as const satisfies Record<string, { production?: boolean }>
+
 export type AgentName = keyof AgentMap & string
 /**
  * The personas this project declares, keyed by name — the \`actors\` a scenario

package/dist/src/server/actor-sign-in.d.ts

@@ -0,0 +1,5 @@
+import type { Logger } from '@pikku/core/services';
+export declare const ACTOR_SECRET_ENV = "SCENARIO_ACTOR_SECRET";
+export declare const VITE_ACTOR_SECRET_ENV = "VITE_SCENARIO_ACTOR_SECRET";
+export declare const enableDevActorSignIn: (logger: Logger) => void;
+export declare const disableDevActorSignIn: (logger: Logger) => void;