@pikku/cli 0.12.125 → 0.12.127

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

@@ -1,11 +1,11 @@
 import { resolve, dirname } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku/function';
-import { createHttpPersonas, personaEnvironmentRefusal, roleMismatchMessage, verifyPersonaRoles, } from '@pikku/core/persona';
+import { createHttpPersonas, deriveActorSecret, personaEnvironmentRefusal, roleMismatchMessage, verifyPersonaRoles, } from '@pikku/core/persona';
 import { personaVirtualUserTarget, runVirtualUser, catalogueClassification, DISPOSITIONS, prepareVirtualUserRun, } from '@pikku/core/virtual-user';
 import { getSingletonServices, setSingletonServices } from '@pikku/core/state';
 import { resolvePersonas } from '../../utils/resolve-personas.js';
-import { resolvePersonaCredentials } from '../../utils/persona-credentials.js';
+import { ACTOR_SECRET_VARIABLE, PERSONA_SECRETS_VARIABLE, resolvePersonaCredentials, } from '../../utils/persona-credentials.js';
 import { resolveEnvironment } from './environment.js';
 import { createDevAgentRunner } from './dev-agent-runner.js';
 import { formatVirtualUserReport } from './virtual-user-formatter.js';
@@ -115,6 +115,7 @@ export const personaRun = pikkuSessionlessFunc({
             ...credentials,
             personas,
             signInPath: env.signInPath,
+            sessionPath: env.sessionPath,
             rpcPath: env.rpcPath,
             model: resolvedModel,
         });
@@ -191,6 +192,45 @@ export const personaRun = pikkuSessionlessFunc({
     },
 });
 /** Who this app is for, and what each of them wants, without running anything. */
+/**
+ * Mint the actor credential for one persona, or for every declared persona.
+ *
+ * The root secret is entitled to all of them, so nothing that only needs to be
+ * one person should ever hold it. What comes out is bound to that persona's
+ * address by the target — presenting it for anyone else is refused — so a CI
+ * job, a container or a virtual user can be handed exactly the people it is
+ * meant to be and no more.
+ *
+ * Printed as `id=secret` lines, which is the shape PIKKU_PERSONA_SECRETS reads.
+ */
+export const personaSecret = pikkuSessionlessFunc({
+    func: async ({ logger, config, variables, getInspectorState }, input) => {
+        const root = await variables.get(ACTOR_SECRET_VARIABLE);
+        if (!root) {
+            throw new Error(`${ACTOR_SECRET_VARIABLE} is not set — there is no root to derive from. ` +
+                `It lives in the environment of whoever mints credentials, and never in pikku.config.json.`);
+        }
+        const state = await getInspectorState(true, false, false, true);
+        const declared = resolvePersonas(state.personas?.definitions ?? [], config.scenarios?.emailDomain);
+        const wanted = input.personas?.length
+            ? input.personas
+            : Object.keys(declared);
+        const unknown = wanted.filter((id) => !declared[id]);
+        if (unknown.length > 0) {
+            throw new Error(`No persona ${unknown.map((id) => `'${id}'`).join(', ')} is declared. ` +
+                `Declared: ${Object.keys(declared).sort().join(', ') || 'none'}.`);
+        }
+        const minted = [];
+        for (const id of wanted) {
+            minted.push(`${id}=${await deriveActorSecret(String(root), declared[id].email)}`);
+        }
+        for (const line of minted) {
+            logger.info(line);
+        }
+        logger.info('');
+        logger.info(`Hand these to a run as ${PERSONA_SECRETS_VARIABLE}='${minted.join(',')}'`);
+    },
+});
 export const personaList = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const state = await getInspectorState(true, false, false, true);

package/dist/src/functions/commands/scenario-browser.d.ts

@@ -9,12 +9,16 @@
  */
 import type { ScenarioArtifact, ScenarioBrowserFailure, ScenarioBrowserProvider } from '@pikku/core/scenario';
 import type { ResolvedPersona } from '@pikku/core/services';
-import type { OperatorSignInOptions } from '@pikku/core/persona';
+import type { ActorSecretResolver, OperatorSignInOptions } from '@pikku/core/persona';
 /** The default driver, used when a project names no other. */
 export declare const DEFAULT_BROWSER_DRIVER = "@pikku/playwright";
 export interface ScenarioBrowserDriverOptions {
-    /** The actor secret, for a local `pikku dev` target. */
-    secret?: string;
+    /**
+     * The root actor secret, for a local `pikku dev` target — each persona's
+     * credential is derived from it. A resolver instead when this run was handed
+     * credentials for only some personas.
+     */
+    secret?: string | ActorSecretResolver;
     /** Fabric operator credentials, for a deployed target. */
     operator?: OperatorSignInOptions;
     actors: Record<string, ResolvedPersona>;
@@ -72,8 +76,12 @@ export interface ResolveScenarioBrowserProviderOptions {
     appUrl?: string;
     /** Base url per app, for a product whose personas sign into more than one. */
     appUrls?: Record<string, string>;
-    /** The actor secret, for a local `pikku dev` target. */
-    secret?: string;
+    /**
+     * The root actor secret, for a local `pikku dev` target — each persona's
+     * credential is derived from it. A resolver instead when this run was handed
+     * credentials for only some personas.
+     */
+    secret?: string | ActorSecretResolver;
     /** Fabric operator credentials, for a deployed target. */
     operator?: OperatorSignInOptions;
     actors: Record<string, ResolvedPersona>;

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

@@ -176,6 +176,7 @@ export const scenarioRun = pikkuSessionlessFunc({
             ...credentials,
             personas: scenarioActors,
             signInPath: env.signInPath,
+            sessionPath: env.sessionPath,
             rpcPath: env.rpcPath,
             model: config.scenarios?.model,
         });

package/dist/src/functions/db/check-enums.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A `CHECK (col IN ('a','b',…))` constraint is an enum by another name, and
+ * both introspectors read one back as SQL text: SQLite stores the `CREATE
+ * TABLE` verbatim, Postgres hands back a normalised `pg_get_constraintdef`.
+ * The parsing they need differs, but the quoting rules do not, so both go
+ * through here.
+ */
+/**
+ * Blank out `--` line comments and `/* … *\/` block comments, leaving a string
+ * of the same shape so offsets and line breaks still line up.
+ *
+ * Quoted text is skipped rather than scanned: `'a--b'` is a value, not a
+ * comment. The reverse — reading a comment as SQL — is what makes this
+ * necessary at all: an apostrophe in `-- the clinician's copy` opens a string
+ * that runs to the next quote in the real list, and a bracket in `-- (see
+ * below)` closes the list early. Either way the CHECK survives as a union that
+ * is wrong, which is worse than no union.
+ */
+export declare function stripSqlComments(sql: string): string;
+/** The single-quoted literals in `text`, with doubled quotes unescaped. */
+export declare function quotedValues(text: string): string[];
+/**
+ * Map each column constrained by a `CHECK (col IN (…))` in a `CREATE TABLE`
+ * statement to its allowed values. Only the positive `col IN (…)` form is
+ * recognised (the convention); `NOT IN`, ranges and boolean expressions are
+ * left for the column to stay a plain string.
+ */
+export declare function parseCheckEnumsFromDdl(ddl: string): Map<string, string[]>;
+/**
+ * The allowed values in a Postgres check constraint, or `undefined` when the
+ * constraint is not an enumeration.
+ *
+ * Postgres does not store the `IN (…)` you wrote — `pg_get_constraintdef`
+ * rewrites it as `= ANY (ARRAY[…])`, with each element cast to the column's
+ * type. Matching that shape is deliberate: `NOT IN` normalises to `<> ALL
+ * (ARRAY[…])` and a range to `>`/`<`, and neither is an enum.
+ */
+export declare function parseCheckEnumValues(constraintDef: string): string[] | undefined;

package/dist/src/functions/db/check-enums.js

@@ -0,0 +1,103 @@
+/**
+ * A `CHECK (col IN ('a','b',…))` constraint is an enum by another name, and
+ * both introspectors read one back as SQL text: SQLite stores the `CREATE
+ * TABLE` verbatim, Postgres hands back a normalised `pg_get_constraintdef`.
+ * The parsing they need differs, but the quoting rules do not, so both go
+ * through here.
+ */
+/**
+ * Blank out `--` line comments and `/* … *\/` block comments, leaving a string
+ * of the same shape so offsets and line breaks still line up.
+ *
+ * Quoted text is skipped rather than scanned: `'a--b'` is a value, not a
+ * comment. The reverse — reading a comment as SQL — is what makes this
+ * necessary at all: an apostrophe in `-- the clinician's copy` opens a string
+ * that runs to the next quote in the real list, and a bracket in `-- (see
+ * below)` closes the list early. Either way the CHECK survives as a union that
+ * is wrong, which is worse than no union.
+ */
+export function stripSqlComments(sql) {
+    let out = '';
+    let i = 0;
+    while (i < sql.length) {
+        const c = sql[i];
+        if (c === "'" || c === '"') {
+            const end = closingQuote(sql, i);
+            out += sql.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (c === '-' && sql[i + 1] === '-') {
+            while (i < sql.length && sql[i] !== '\n') {
+                out += ' ';
+                i++;
+            }
+            continue;
+        }
+        if (c === '/' && sql[i + 1] === '*') {
+            const close = sql.indexOf('*/', i + 2);
+            const end = close === -1 ? sql.length : close + 2;
+            for (let k = i; k < end; k++)
+                out += sql[k] === '\n' ? '\n' : ' ';
+            i = end;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}
+/** Index just past the quoted run starting at `start`, doubled quotes included. */
+function closingQuote(sql, start) {
+    const quote = sql[start];
+    let i = start + 1;
+    while (i < sql.length) {
+        if (sql[i] === quote) {
+            if (sql[i + 1] === quote) {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i++;
+    }
+    return sql.length;
+}
+/** The single-quoted literals in `text`, with doubled quotes unescaped. */
+export function quotedValues(text) {
+    return [...text.matchAll(/'((?:[^']|'')*)'/g)].map((m) => m[1].replace(/''/g, "'"));
+}
+/**
+ * Map each column constrained by a `CHECK (col IN (…))` in a `CREATE TABLE`
+ * statement to its allowed values. Only the positive `col IN (…)` form is
+ * recognised (the convention); `NOT IN`, ranges and boolean expressions are
+ * left for the column to stay a plain string.
+ */
+export function parseCheckEnumsFromDdl(ddl) {
+    const out = new Map();
+    const sql = stripSqlComments(ddl);
+    const checkIn = /CHECK\s*\(\s*"?(\w+)"?\s+IN\s*\(([^)]*)\)/gi;
+    let m;
+    while ((m = checkIn.exec(sql))) {
+        const values = quotedValues(m[2]);
+        if (values.length > 0)
+            out.set(m[1], values);
+    }
+    return out;
+}
+/**
+ * The allowed values in a Postgres check constraint, or `undefined` when the
+ * constraint is not an enumeration.
+ *
+ * Postgres does not store the `IN (…)` you wrote — `pg_get_constraintdef`
+ * rewrites it as `= ANY (ARRAY[…])`, with each element cast to the column's
+ * type. Matching that shape is deliberate: `NOT IN` normalises to `<> ALL
+ * (ARRAY[…])` and a range to `>`/`<`, and neither is an enum.
+ */
+export function parseCheckEnumValues(constraintDef) {
+    const any = /=\s*ANY\s*\(\s*\(?\s*ARRAY\s*\[([^\]]*)\]/i.exec(constraintDef);
+    if (!any)
+        return undefined;
+    const values = quotedValues(any[1]);
+    return values.length > 0 ? values : undefined;
+}

package/dist/src/functions/db/db-codegen.js

@@ -641,6 +641,21 @@ export async function generateSchemaTypes(introspector, options) {
     const coercionBody = [
         `// Generated by @pikku/cli — do not edit by hand.`,
         `// Run \`pikku db migrate\` to refresh.`,
+        `//`,
+        `// Nothing applies this for you. Attach it where the kysely singleton is`,
+        `// created, in createSingletonServices:`,
+        `//`,
+        `//   import { createCoercionPlugin } from '@pikku/kysely'`,
+        `//   import { coercionMap } from '#pikku/db/coercion.gen.js'`,
+        `//`,
+        `//   kysely: existingServices.kysely.withPlugin(`,
+        `//     createCoercionPlugin({ map: coercionMap }),`,
+        `//   )`,
+        `//`,
+        `// Unwired, this file is invisible locally and fatal deployed: the dev`,
+        `// driver hydrates a TEXT date into a Date by itself, a deployed one`,
+        `// returns the raw string, and the generated schema types the column`,
+        `// \`Date\` either way — so tsc flags nothing and no local test can fail.`,
         ``,
         `export const coercionMap = {`,
         coercionEntries,

package/dist/src/functions/db/postgres/postgres-introspector.d.ts

@@ -12,6 +12,20 @@ export declare class PostgresIntrospector implements DbIntrospector {
     connect(): Promise<void>;
     listTables(): Promise<string[]>;
     getColumns(table: string): Promise<ColumnInfo[]>;
+    /**
+     * Columns constrained to a value list by a `CHECK (col IN (…))`, keyed like
+     * {@link getAllColumns} then by column name. Postgres has native enums, but
+     * a CHECK is the other half of how a schema says "one of these" — and the
+     * one an app written against SQLite as well ends up using, since SQLite has
+     * no enums at all. Left as plain `string`, every caller narrows it by hand.
+     *
+     * Only single-column constraints are read: `conkey` naming two columns means
+     * neither is restricted to the list on its own.
+     *
+     * `table` limits the sweep to one table; omitted, it covers the schema. Both
+     * are one round-trip — see {@link getAllColumns}.
+     */
+    private getCheckEnums;
     getForeignKeys(table: string): Promise<ForeignKeyInfo[]>;
     getAllColumns(): Promise<Map<string, ColumnInfo[]>>;
     getAllForeignKeys(): Promise<Map<string, ForeignKeyInfo[]>>;

package/dist/src/functions/db/postgres/postgres-introspector.js

@@ -1,5 +1,6 @@
 import { Pool } from 'pg';
 import { MIGRATION_TRACKING_TABLE } from '../db-migrator.js';
+import { parseCheckEnumValues } from '../check-enums.js';
 /** Table display name matching `listTables` (schema-qualified unless `public`). */
 function tableKey(schema, table) {
     return schema === 'public' ? table : `${schema}.${table}`;
@@ -85,6 +86,8 @@ export class PostgresIntrospector {
        FROM information_schema.columns c
        WHERE c.table_schema = $2 AND c.table_name = $1
        ORDER BY c.ordinal_position`, [tableName, schema]);
+        const checkEnums = (await this.getCheckEnums({ schema, name: tableName })).get(table) ??
+            new Map();
         return result.rows.map((r) => ({
             name: r.column_name,
             type: resolveColumnType(r.data_type, r.udt_name),
@@ -93,8 +96,51 @@ export class PostgresIntrospector {
             pk: Boolean(r.is_pk),
             defaultValue: r.column_default,
             generated: r.is_generated === 'ALWAYS',
+            enumValues: checkEnums.get(r.column_name),
         }));
     }
+    /**
+     * Columns constrained to a value list by a `CHECK (col IN (…))`, keyed like
+     * {@link getAllColumns} then by column name. Postgres has native enums, but
+     * a CHECK is the other half of how a schema says "one of these" — and the
+     * one an app written against SQLite as well ends up using, since SQLite has
+     * no enums at all. Left as plain `string`, every caller narrows it by hand.
+     *
+     * Only single-column constraints are read: `conkey` naming two columns means
+     * neither is restricted to the list on its own.
+     *
+     * `table` limits the sweep to one table; omitted, it covers the schema. Both
+     * are one round-trip — see {@link getAllColumns}.
+     */
+    async getCheckEnums(table) {
+        const result = await this.client.query(`SELECT n.nspname   AS table_schema,
+              cl.relname  AS table_name,
+              a.attname   AS column_name,
+              pg_get_constraintdef(co.oid) AS def
+       FROM pg_constraint co
+       JOIN pg_class cl     ON cl.oid = co.conrelid
+       JOIN pg_namespace n  ON n.oid = cl.relnamespace
+       JOIN pg_attribute a  ON a.attrelid = co.conrelid AND a.attnum = co.conkey[1]
+       WHERE co.contype = 'c'
+         AND array_length(co.conkey, 1) = 1
+         AND n.nspname NOT IN ('information_schema', 'pg_catalog', 'pg_toast')
+         AND n.nspname NOT LIKE 'pg_temp_%'
+         AND ($1::text IS NULL OR (n.nspname = $1 AND cl.relname = $2))`, [table?.schema ?? null, table?.name ?? null]);
+        const byTable = new Map();
+        for (const r of result.rows) {
+            const values = parseCheckEnumValues(r.def);
+            if (!values)
+                continue;
+            const key = tableKey(r.table_schema, r.table_name);
+            let cols = byTable.get(key);
+            if (!cols) {
+                cols = new Map();
+                byTable.set(key, cols);
+            }
+            cols.set(r.column_name, values);
+        }
+        return byTable;
+    }
     async getForeignKeys(table) {
         const dotIdx = table.indexOf('.');
         const schema = dotIdx >= 0 ? table.slice(0, dotIdx) : 'public';
@@ -153,6 +199,7 @@ export class PostgresIntrospector {
        WHERE c.table_schema NOT IN ('information_schema', 'pg_catalog', 'pg_toast')
          AND c.table_schema NOT LIKE 'pg_temp_%'
        ORDER BY c.table_schema, c.table_name, c.ordinal_position`);
+        const checkEnums = await this.getCheckEnums();
         const byTable = new Map();
         for (const r of result.rows) {
             if (isMigrationTracking(r.table_name))
@@ -171,6 +218,7 @@ export class PostgresIntrospector {
                 pk: Boolean(r.is_pk),
                 defaultValue: r.column_default,
                 generated: r.is_generated === 'ALWAYS',
+                enumValues: checkEnums.get(key)?.get(r.column_name),
             });
         }
         return byTable;

package/dist/src/functions/db/sqlite/sqlite-introspector.d.ts

@@ -7,10 +7,9 @@ export declare class SqliteIntrospector implements DbIntrospector {
     getColumns(table: string): Promise<ColumnInfo[]>;
     /**
      * SQLite has no native enums, but a `CHECK (col IN ('a','b',…))` constraint is
-     * an enum by another name. Parse the table's stored `CREATE TABLE` DDL and map
-     * each constrained column to its allowed values so codegen can type it as a
-     * union. Only the positive `col IN (…)` form is recognised (the convention);
-     * `NOT IN`, ranges, and boolean expressions are left as plain `string`.
+     * an enum by another name. Read back the table's stored `CREATE TABLE` DDL —
+     * which SQLite keeps verbatim, comments included — and map each constrained
+     * column to its allowed values so codegen can type it as a union.
      */
     private parseCheckEnums;
     getForeignKeys(table: string): Promise<ForeignKeyInfo[]>;

package/dist/src/functions/db/sqlite/sqlite-introspector.js

@@ -1,4 +1,5 @@
 import { MIGRATION_TRACKING_TABLE } from '../db-migrator.js';
+import { parseCheckEnumsFromDdl } from '../check-enums.js';
 const SKIP_TABLES = new Set(['sqlite_sequence', MIGRATION_TRACKING_TABLE]);
 export class SqliteIntrospector {
     db;
@@ -34,28 +35,15 @@ export class SqliteIntrospector {
     }
     /**
      * SQLite has no native enums, but a `CHECK (col IN ('a','b',…))` constraint is
-     * an enum by another name. Parse the table's stored `CREATE TABLE` DDL and map
-     * each constrained column to its allowed values so codegen can type it as a
-     * union. Only the positive `col IN (…)` form is recognised (the convention);
-     * `NOT IN`, ranges, and boolean expressions are left as plain `string`.
+     * an enum by another name. Read back the table's stored `CREATE TABLE` DDL —
+     * which SQLite keeps verbatim, comments included — and map each constrained
+     * column to its allowed values so codegen can type it as a union.
      */
     parseCheckEnums(table) {
-        const out = new Map();
         const row = this.db
             .prepare(`SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?`)
             .get(table);
-        const ddl = row?.sql;
-        if (!ddl)
-            return out;
-        const checkIn = /CHECK\s*\(\s*"?(\w+)"?\s+IN\s*\(([^)]*)\)/gi;
-        let m;
-        while ((m = checkIn.exec(ddl))) {
-            const column = m[1];
-            const values = [...m[2].matchAll(/'((?:[^']|'')*)'/g)].map((q) => q[1].replace(/''/g, "'"));
-            if (values.length > 0)
-                out.set(column, values);
-        }
-        return out;
+        return row?.sql ? parseCheckEnumsFromDdl(row.sql) : new Map();
     }
     async getForeignKeys(table) {
         const escaped = `"${table.replace(/"/g, '""')}"`;

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

@@ -10,7 +10,7 @@ export type AuthPluginCheckConfig = {
  * 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
+ * app that dropped `admin()` and never wired `pikkuBan()`, 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

@@ -113,7 +113,7 @@ const configuresPlugin = (text, module, exported) => {
  * 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
+ * app that dropped `admin()` and never wired `pikkuBan()`, which keeps its ban
  * columns and its ban UI while silently enforcing nothing.
  */
 export const runAuthPluginChecks = async (root, config) => {
@@ -131,7 +131,10 @@ export const runAuthPluginChecks = async (root, config) => {
             continue;
         if (configuresPlugin(text, 'better-auth/plugins', 'admin'))
             adminFiles.push(file);
-        if (configuresPlugin(text, '@pikku/better-auth', 'ban'))
+        // `pikkuBan` is the current export; `ban` is the deprecated alias, which
+        // configures exactly the same plugin and so must satisfy the check too.
+        if (configuresPlugin(text, '@pikku/better-auth', 'pikkuBan') ||
+            configuresPlugin(text, '@pikku/better-auth', 'ban'))
             bansAnywhere = true;
     }
     for (const file of adminFiles) {
@@ -140,7 +143,7 @@ export const runAuthPluginChecks = async (root, config) => {
             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.'),
+            fixHint: lines('Replace it with pikkuBan(), which keeps the one capability admin() had', 'that pikku cannot supply from outside better-auth — refusing a banned', 'user a session:', "  import { pikkuBan } from '@pikku/better-auth'", '  betterAuth({ plugins: [pikkuBan()] })', 'User management is already scoped RPCs in @pikku/addon-admin: list,', 'create, ban, remove, revoke sessions and set password.'),
         });
     }
     if (!bansAnywhere && adminFiles.length === 0) {
@@ -153,9 +156,9 @@ export const runAuthPluginChecks = async (root, config) => {
                 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',
+                    message: 'better-auth is configured without pikkuBan() — 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.'),
+                    fixHint: lines("  import { pikkuBan } from '@pikku/better-auth'", '  betterAuth({ plugins: [pikkuBan()] })', 'Wire it wherever the rest of your plugins are, then run', '`pikku db migrate` to add the columns.'),
                 });
                 break;
             }

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

@@ -81,17 +81,19 @@ const countPersonas = async (root, config, sourceFiles) => {
 /**
  * Whether a persona can actually sign in.
  *
- * Two shapes count. `actor()` from `@pikku/better-auth` is the one the scaffold
- * wires, and a hand-rolled `/sign-in/actor` route is the one a project that does
- * not use better-auth ends up with. Both terminate at the same endpoint, so
- * either satisfies the check.
+ * Two shapes count. `pikkuActor()` from `@pikku/better-auth` is the one the
+ * scaffold wires, and a hand-rolled `/sign-in/actor` route is the one a project
+ * that does not use better-auth ends up with. Both terminate at the same
+ * endpoint, so either satisfies the check. The deprecated `actor()` alias is
+ * matched too — it is the same plugin under its old name.
  */
 const hasActorSignIn = async (sourceFiles) => {
     for (const file of sourceFiles) {
         const text = await readTextSafe(file);
         if (!text)
             continue;
-        const wiresPlugin = /@pikku\/better-auth/.test(text) && /\bactor\s*\(/.test(text);
+        const wiresPlugin = /@pikku\/better-auth/.test(text) &&
+            /(^|[^\w$.])(pikkuActor|actor)\s*\(/.test(text);
         if (wiresPlugin || /sign-in\/actor/.test(text))
             return true;
     }
@@ -123,7 +125,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 })]', '`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.'));
+        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 { pikkuActor } from '@pikku/better-auth'", '  plugins: [pikkuActor({ 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/wirings/user-admin/pikku-command-user-admin-functions.js

@@ -28,12 +28,17 @@ export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
         // Ban is the one capability with a schema requirement of its own, and it is
         // only one of the six — a warning rather than a failure, so an app that
         // never bans anyone is not forced to carry the columns.
-        if (!definition.plugins.includes('ban')) {
-            logger.warn(`"scaffold.userAdmin" is enabled but better-auth is configured without the ban() plugin, ` +
+        // The plugin ids here are the callee names read off the `plugins: [...]`
+        // array, so both the current `pikkuBan()` and the deprecated `ban()` alias
+        // have to count as wired.
+        const bansUsers = definition.plugins.includes('pikkuBan') ||
+            definition.plugins.includes('ban');
+        if (!bansUsers) {
+            logger.warn(`"scaffold.userAdmin" is enabled but better-auth is configured without the pikkuBan() plugin, ` +
                 `so the banned/banReason/banExpires columns do not exist and setUserBanned will fail.\n` +
-                `Fix: add ban() to the plugins array in ${definition.sourceFile}:\n` +
-                `  import { ban } from '@pikku/better-auth'\n` +
-                `  betterAuth({ plugins: [ban()] })`);
+                `Fix: add pikkuBan() to the plugins array in ${definition.sourceFile}:\n` +
+                `  import { pikkuBan } from '@pikku/better-auth'\n` +
+                `  betterAuth({ plugins: [pikkuBan()] })`);
         }
         const leaf = (name) => getLeafImportPath(config.userAdminFunctionsFile, name, config);
         const { schemas, functions } = serializeUserAdminFunctions(leaf);

package/dist/src/functions/wirings/user-admin/serialize-user-admin-functions.d.ts

@@ -13,7 +13,7 @@ export interface UserAdminGenOutput {
  * codegen on conflicting declarations.
  *
  * Each function is gated on its own `admin:users:*` scope, and works through
- * better-auth's internal adapter. Banning additionally needs the `ban()` plugin
+ * better-auth's internal adapter. Banning additionally needs the `pikkuBan()` plugin
  * from `@pikku/better-auth` for the columns it writes to exist.
  *
  * Emitted as two files. The schemas are zod, and the inspector reads a zod

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

@@ -9,7 +9,7 @@
  * codegen on conflicting declarations.
  *
  * Each function is gated on its own `admin:users:*` scope, and works through
- * better-auth's internal adapter. Banning additionally needs the `ban()` plugin
+ * better-auth's internal adapter. Banning additionally needs the `pikkuBan()` plugin
  * from `@pikku/better-auth` for the columns it writes to exist.
  *
  * Emitted as two files. The schemas are zod, and the inspector reads a zod
@@ -27,7 +27,7 @@ import { z } from 'zod'
 
 /**
  * A user, as the directory sees one. Ban state is optional because those
- * columns belong to the \`ban()\` plugin: a host without it reports no ban state
+ * columns belong to the \`pikkuBan()\` plugin: a host without it reports no ban state
  * at all, which a client can render as "unknown" rather than as a misleading
  * "not banned".
  */
@@ -224,7 +224,7 @@ export const pikkuAdminSetUserBanned = pikkuFunc({
   tags: ['pikku'],
   title: 'Ban or Unban User',
   description:
-    'Bans a user — revoking their sessions and blocking sign-in — or lifts an existing ban. An expiry lets the ban lapse on its own; without one it holds until it is lifted. Requires better-auth wired with the \`ban()\` plugin.',
+    'Bans a user — revoking their sessions and blocking sign-in — or lifts an existing ban. An expiry lets the ban lapse on its own; without one it holds until it is lifted. Requires better-auth wired with the \`pikkuBan()\` plugin.',
   expose: true,
   scopes: ['admin:users:ban'],
   input: SetUserBannedInput,

package/dist/src/functions/wirings/virtual-user/serialize-virtual-user-functions.d.ts

@@ -12,12 +12,15 @@ export interface VirtualUserGenOutput {
  * `pikku persona run` does the same thing from a terminal; this is the same run
  * started over RPC, from CI or from a console, with the result kept.
  *
- * A virtual user is NOT a workflow and NOT a queued job. It explores, so no two
- * attempts take the same steps and there is nothing to replay; and the run
- * record already carries the progress a queue would only be holding on the way
- * here. So `runVirtualUser` writes the record, kicks the run off without
- * awaiting it, and returns the id. The one cost is stated on the record: a
- * restart mid-run strands it at `running`.
+ * A virtual user is still NOT a workflow: it explores, so no two attempts take
+ * the same steps and there is nothing to replay. What it does need is a
+ * trigger. `runVirtualUser` writes the record and returns the id; the run
+ * itself is dispatched onto `pikku-virtual-user-runs`, at one attempt, because
+ * a queue is the only dispatch that survives a deployment which puts each
+ * function in its own unit — there is no in-process promise to leave running
+ * there, and an RPC to a function nothing triggers has nowhere to land. A
+ * project with no queue service keeps the in-process dispatch, which is
+ * correct for the single process it runs in.
  *
  * Emitted as two files. The schemas are zod, and the inspector reads a zod
  * schema by importing the module that declares it — which it cannot do for the