@pikku/cli 0.12.118 → 0.12.120

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/virtual-user/serialize-virtual-user-functions.js

@@ -206,6 +206,19 @@ const virtualUserScheduleFields = {
   nextRunAt: z.string(),
   lastRunId: z.string().nullable(),
   lastRunAt: z.string().nullable(),
+  /**
+   * What \`definePersonas()\` says about this persona now, alongside what the
+   * row is actually running.
+   *
+   * A schedule is turned on once and then outlives the declaration it was
+   * written from: someone edits \`personas.ts\`, redeploys, and the row keeps
+   * running last month's goals with nothing anywhere to say so. Both sides
+   * cross the wire so that difference is readable rather than inferred.
+   */
+  declared: z.object({
+    disposition: Disposition,
+    goals: z.array(z.string()),
+  }),
 }
 
 export const SetVirtualUserScheduleOutput = z.object(virtualUserScheduleFields)
@@ -291,6 +304,16 @@ const API_URL_VARIABLE = 'VIRTUAL_USER_API_URL'
 const SECRET_VARIABLE = 'SCENARIO_ACTOR_SECRET'
 const MODEL_VARIABLE = 'VIRTUAL_USER_MODEL'
 
+/**
+ * The same two variables a scenario run reads, because a virtual user signs in
+ * and calls through exactly the doors a scenario does. An app that mounts auth
+ * somewhere other than the root — \`/api/auth\` is the common one — has no other
+ * way to say so, and without them the run signs in against a 404 and spends its
+ * whole budget thinking about why nothing works.
+ */
+const SIGN_IN_PATH_VARIABLE = 'SCENARIO_SIGN_IN_PATH'
+const RPC_PATH_VARIABLE = 'SCENARIO_RPC_PATH'
+
 /**
  * One run on the wire. Findings and intents are free-form by design — the
  * engine records what it noticed, not a fixed row shape — so they cross as the
@@ -340,9 +363,16 @@ const serializeRun = (run: VirtualUserRunRecord) => ({
 const startVirtualUserRun = async (
   services: {
     virtualUserRunStore?: VirtualUserRunStore
-    config: { nodeEnv?: string }
+    // \`unknown\` because an application's Config is its own interface and need
+    // not declare nodeEnv at all. A structural \`{ nodeEnv?: string }\` shares no
+    // property with such a config and TypeScript rejects the whole call.
+    config: unknown
+  },
+  // Named literally rather than as \`string\`: a project's generated rpc.invoke
+  // is generic over its own map's keys, and \`string\` is not one of them.
+  rpc: {
+    invoke: (name: 'executeVirtualUserRun', data: any) => Promise<unknown>
   },
-  rpc: { invoke: (name: string, data: any) => Promise<unknown> },
   input: {
     persona: string
     disposition?: string
@@ -384,7 +414,7 @@ const startVirtualUserRun = async (
   // does wrong, which is not a thing to do to real customers' data. Checked
   // against the effective disposition, so the override cannot smuggle one in.
   if (
-    config.nodeEnv === 'production' &&
+    (config as { nodeEnv?: string } | undefined)?.nodeEnv === 'production' &&
     disposition !== PRODUCTION_DISPOSITION
   ) {
     throw new Error(
@@ -525,27 +555,38 @@ export const getVirtualUserRunSteps = pikkuFunc({
  * what every other call here takes; the engine's own duration also accepts
  * \`'30m'\`, which nothing on this side ever writes.
  */
-const serializeSchedule = (schedule: VirtualUserScheduleRecord) => ({
-  persona: schedule.persona,
-  enabled: schedule.enabled,
-  disposition: schedule.disposition,
-  goals: schedule.goals,
-  budget: schedule.budget
-    ? {
-        steps: schedule.budget.steps,
-        mutations: schedule.budget.mutations,
-        durationMs:
-          typeof schedule.budget.duration === 'number'
-            ? schedule.budget.duration
-            : undefined,
-      }
-    : null,
-  minIntervalMs: schedule.minIntervalMs,
-  maxIntervalMs: schedule.maxIntervalMs,
-  nextRunAt: schedule.nextRunAt.toISOString(),
-  lastRunId: schedule.lastRunId,
-  lastRunAt: schedule.lastRunAt ? schedule.lastRunAt.toISOString() : null,
-})
+const serializeSchedule = (schedule: VirtualUserScheduleRecord) => {
+  const persona = personaConfigs[
+    schedule.persona as keyof typeof personaConfigs
+  ] as { goals?: string[]; disposition?: string } | undefined
+  const declared = {
+    disposition: (persona?.disposition ??
+      'realistic') as VirtualUserDisposition,
+    goals: persona?.goals ?? [],
+  }
+  return {
+    persona: schedule.persona,
+    enabled: schedule.enabled,
+    disposition: schedule.disposition,
+    goals: schedule.goals,
+    budget: schedule.budget
+      ? {
+          steps: schedule.budget.steps,
+          mutations: schedule.budget.mutations,
+          durationMs:
+            typeof schedule.budget.duration === 'number'
+              ? schedule.budget.duration
+              : undefined,
+        }
+      : null,
+    minIntervalMs: schedule.minIntervalMs,
+    maxIntervalMs: schedule.maxIntervalMs,
+    nextRunAt: schedule.nextRunAt.toISOString(),
+    lastRunId: schedule.lastRunId,
+    lastRunAt: schedule.lastRunAt ? schedule.lastRunAt.toISOString() : null,
+    declared,
+  }
+}
 
 export const setVirtualUserSchedule = pikkuFunc({
   tags: ['pikku'],
@@ -612,7 +653,6 @@ export const listVirtualUserSchedules = pikkuFunc({
     'Which personas are on a clock, how often they run, and when each is next due.',
   expose: true,
   scopes: ['virtualUser:read'],
-  input: null,
   output: ListVirtualUserSchedulesOutput,
   func: async ({ virtualUserScheduleStore }) => {
     if (!virtualUserScheduleStore) {
@@ -759,7 +799,13 @@ export const executeVirtualUserRun = pikkuSessionlessFunc({
         agentsMeta: await metaService.getAgentsMeta(),
       })
 
-      const signedIn = createPersonas({ apiUrl, secret, model })
+      const signedIn = createPersonas({
+        apiUrl,
+        secret,
+        model,
+        signInPath: (await variables.get(SIGN_IN_PATH_VARIABLE)) ?? undefined,
+        rpcPath: (await variables.get(RPC_PATH_VARIABLE)) ?? undefined,
+      })
       const target = signedIn[personaId as keyof typeof signedIn]
       if (!target) {
         throw new Error(\`Persona "\${personaId}" cannot sign in\`)

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;

package/dist/src/server/actor-sign-in.js

@@ -0,0 +1,27 @@
+import { randomBytes } from 'node:crypto';
+import { ACTOR_SIGN_IN_OPT_IN_ENV, DEV_ACTOR_SIGN_IN_ENV, } from '@pikku/better-auth';
+export const ACTOR_SECRET_ENV = 'SCENARIO_ACTOR_SECRET';
+export const VITE_ACTOR_SECRET_ENV = 'VITE_SCENARIO_ACTOR_SECRET';
+const mintEphemeralSecret = () => randomBytes(32).toString('base64url');
+export const enableDevActorSignIn = (logger) => {
+    process.env[DEV_ACTOR_SIGN_IN_ENV] = 'true';
+    const configured = process.env[ACTOR_SECRET_ENV] || undefined;
+    const configuredForFrontend = process.env[VITE_ACTOR_SECRET_ENV] || undefined;
+    if (configured &&
+        configuredForFrontend &&
+        configured !== configuredForFrontend) {
+        logger.warn(`${ACTOR_SECRET_ENV} and ${VITE_ACTOR_SECRET_ENV} are set to different values — using ${ACTOR_SECRET_ENV}, since that is the one the server compares against`);
+    }
+    const secret = configured ?? configuredForFrontend ?? mintEphemeralSecret();
+    process.env[ACTOR_SECRET_ENV] = secret;
+    process.env[VITE_ACTOR_SECRET_ENV] = secret;
+    logger.info((configured ?? configuredForFrontend)
+        ? `Actor quick login enabled, using the ${configured ? ACTOR_SECRET_ENV : VITE_ACTOR_SECRET_ENV} already in this environment`
+        : 'Actor quick login enabled with a secret minted for this run — nothing to configure, and it is gone when the server stops');
+};
+export const disableDevActorSignIn = (logger) => {
+    if (process.env[DEV_ACTOR_SIGN_IN_ENV] !== undefined) {
+        logger.warn(`${DEV_ACTOR_SIGN_IN_ENV} was set in this environment and has been cleared — \`pikku serve\` never enables actor sign-in. Set ${ACTOR_SIGN_IN_OPT_IN_ENV} if this stage is meant to run scenarios.`);
+    }
+    delete process.env[DEV_ACTOR_SIGN_IN_ENV];
+};

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

@@ -2,11 +2,22 @@
  * Node dev server runner — `@pikku/node-http-server` + the `ws` WebSocketServer.
  * Used when the CLI runs under Node. Owns the WebSocketServer so teardown
  * (close ws then the http server) is encapsulated in the returned instance.
+ *
+ * `@pikku/ws` and `ws` are optional peers of the CLI, so they are imported
+ * dynamically and resolved from the *project* rather than from the CLI: both
+ * peer on `@pikku/core`, and a copy loaded out of the CLI's own tree is paired
+ * with the CLI's core instead of the project's. A project without them served
+ * over plain HTTP — `pikku validate` reports the missing packages.
  */
 import type { EventHubService } from '@pikku/core/channel';
 import type { Logger } from '@pikku/core/services';
 import type { DevServerRunner, DevServerInstance, DevServerConfig, DevServerOptions } from './dev-server-runner.interface.js';
+export declare const WEBSOCKET_PACKAGES_MISSING = "WebSocket support is disabled: @pikku/ws and ws are not installed in this project. Install them (npm install @pikku/ws ws) to serve channels over Node.";
 export declare class NodeServerRunner implements DevServerRunner {
+    private readonly rootDir;
+    private pikkuWs?;
+    private ws?;
+    constructor(rootDir: string);
     createEventHub(): Promise<EventHubService<any>>;
     createServer(config: DevServerConfig, logger: Logger, options?: DevServerOptions): DevServerInstance;
 }