@pikku/cli 0.12.152 → 0.12.154

package/dist/src/functions/db/local-db.d.ts

@@ -1,4 +1,5 @@
 import { Kysely } from 'kysely';
+import type { PGlite } from '@electric-sql/pglite';
 import { type MigrateResult } from '@pikku/migrator-sql';
 import type { ColumnInfo } from './db-introspector.js';
 import { type CodegenResult } from './db-codegen.js';
@@ -74,6 +75,16 @@ export declare function resolveDb(userConfig: UserConfigShape, rootDir: string,
     defaultSchema?: string;
     pgliteExtensions?: string[];
 } | string): ResolvedDb | null;
+export interface PostgresQueryClient {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    connect?(): Promise<unknown>;
+    end(): Promise<void>;
+    exec?(sql: string): Promise<unknown>;
+    __connectionString?: string;
+    __pglite?: PGlite;
+}
 /**
  * What an embedded PGlite instance needs beyond its data directory: where to
  * resolve extension packages from, and which ones to load.
@@ -109,6 +120,7 @@ type PGliteExtension = {
  * also names is not registered twice.
  */
 export declare function loadPGliteExtensions(rootDir: string, specs: string[]): Promise<Record<string, PGliteExtension>>;
+export declare function withPostgresClient<T>(resolved: ResolvedPostgresDb, run: (client: PostgresQueryClient) => Promise<T>): Promise<T>;
 export interface MigrateAndCodegenOutcome {
     migrate: MigrateResult;
     codegen: CodegenResult;

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

@@ -294,7 +294,7 @@ function pgliteAsClient(db) {
         },
     };
 }
-async function withPostgresClient(resolved, run) {
+export async function withPostgresClient(resolved, run) {
     const client = await createPostgresClient(resolved);
     try {
         return await run(client);

package/dist/src/functions/db/postgres/scenario-baseline.d.ts

@@ -0,0 +1,3 @@
+import { type ResolvedPostgresDb } from '../local-db.js';
+import { type ScenarioBaseline, type ScenarioBaselineOptions } from '../scenario-baseline.js';
+export declare function capturePostgresScenarioBaseline(resolved: ResolvedPostgresDb, { keep }: ScenarioBaselineOptions): Promise<ScenarioBaseline>;

package/dist/src/functions/db/postgres/scenario-baseline.js

@@ -0,0 +1,112 @@
+import { MIGRATION_TRACKING_TABLE } from '@pikku/migrator-sql';
+import { withPostgresClient } from '../local-db.js';
+import { BASELINE_SCHEMA, FEATURE_LAYER, SEED_LAYER, copyName, keepMatcher, quoteIdentifier, } from '../scenario-baseline.js';
+export async function capturePostgresScenarioBaseline(resolved, { keep = [] }) {
+    const shouldKeep = keepMatcher(keep);
+    const sequencesByLayer = new Map();
+    const copy = (layer, schema, table) => `${quoteIdentifier(BASELINE_SCHEMA)}.${quoteIdentifier(copyName([layer, schema, table]))}`;
+    const tables = await withPostgresClient(resolved, async (client) => {
+        const { rows } = await client.query(`
+      SELECT table_schema, table_name
+      FROM information_schema.tables
+      WHERE table_type = 'BASE TABLE'
+        AND table_schema NOT IN ('information_schema', '${BASELINE_SCHEMA}')
+        AND table_schema NOT LIKE 'pg_%'
+      ORDER BY table_schema, table_name
+    `);
+        await client.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(BASELINE_SCHEMA)}`);
+        return rows.filter(({ table_schema, table_name }) => table_name !== MIGRATION_TRACKING_TABLE &&
+            !shouldKeep(table_schema, table_name));
+    });
+    const captureLayer = (layer) => withPostgresClient(resolved, async (client) => {
+        for (const { table_schema, table_name } of tables) {
+            const target = copy(layer, table_schema, table_name);
+            await client.query(`DROP TABLE IF EXISTS ${target}`);
+            await client.query(`CREATE TABLE ${target} AS TABLE ${quoteIdentifier(table_schema)}.${quoteIdentifier(table_name)}`);
+        }
+        // Sequences are state the row copies do not carry: restoring the rows
+        // without them leaves the next insert claiming an id that already exists.
+        const { rows } = await client.query(`
+        SELECT s.schemaname, s.sequencename, s.last_value, s.start_value,
+               owner_ns.nspname AS owner_schema,
+               owner_cls.relname AS owner_table
+        FROM pg_sequences s
+        JOIN pg_namespace seq_ns ON seq_ns.nspname = s.schemaname
+        JOIN pg_class seq_cls
+          ON seq_cls.relname = s.sequencename
+         AND seq_cls.relnamespace = seq_ns.oid
+        LEFT JOIN pg_depend dep
+          ON dep.classid = 'pg_class'::regclass
+         AND dep.objid = seq_cls.oid
+         AND dep.refclassid = 'pg_class'::regclass
+         AND dep.deptype IN ('a', 'i')
+        LEFT JOIN pg_class owner_cls ON owner_cls.oid = dep.refobjid
+        LEFT JOIN pg_namespace owner_ns ON owner_ns.oid = owner_cls.relnamespace
+        WHERE s.schemaname NOT IN ('information_schema', '${BASELINE_SCHEMA}')
+          AND s.schemaname NOT LIKE 'pg_%'
+      `);
+        sequencesByLayer.set(layer, rows
+            // A sequence owned by a kept table is left alone with the table: its
+            // rows survive the restore, so winding its counter back hands the
+            // next insert an id that is already taken.
+            .filter((sequence) => !(sequence.owner_table !== null &&
+            shouldKeep(sequence.owner_schema, sequence.owner_table)))
+            .map((sequence) => ({
+            qualified: `${quoteIdentifier(sequence.schemaname)}.${quoteIdentifier(sequence.sequencename)}`,
+            lastValue: sequence.last_value,
+            startValue: sequence.start_value,
+        })));
+    });
+    const restoreLayer = (layer) => withPostgresClient(resolved, async (client) => {
+        // Foreign keys are switched off for the duration rather than the tables
+        // sorted into dependency order: `keep` can hold the parent of a table
+        // being replaced, which no ordering makes legal.
+        try {
+            await client.query(`SET session_replication_role = 'replica'`);
+        }
+        catch (error) {
+            throw new Error(`Scenario database reset needs 'SET session_replication_role' to suspend foreign keys, and this role may not: ${error?.message ?? error}. Connect as a superuser, or run the suite against sqlite.`);
+        }
+        try {
+            await client.query('BEGIN');
+            try {
+                for (const { table_schema, table_name } of tables) {
+                    const target = `${quoteIdentifier(table_schema)}.${quoteIdentifier(table_name)}`;
+                    await client.query(`DELETE FROM ${target}`);
+                    await client.query(`INSERT INTO ${target} SELECT * FROM ${copy(layer, table_schema, table_name)}`);
+                }
+                await client.query('COMMIT');
+            }
+            catch (error) {
+                await client.query('ROLLBACK');
+                throw error;
+            }
+            for (const { qualified, lastValue, startValue } of sequencesByLayer.get(layer) ?? []) {
+                await client.query(lastValue === null
+                    ? `SELECT setval('${qualified}', ${startValue}, false)`
+                    : `SELECT setval('${qualified}', ${lastValue}, true)`);
+            }
+        }
+        finally {
+            await client.query(`SET session_replication_role = 'origin'`);
+        }
+    });
+    await captureLayer(SEED_LAYER);
+    let active = SEED_LAYER;
+    return {
+        tables: tables.map(({ table_schema, table_name }) => `${table_schema}.${table_name}`),
+        restore: () => restoreLayer(active),
+        async pushFeatureLayer() {
+            await captureLayer(FEATURE_LAYER);
+            active = FEATURE_LAYER;
+        },
+        async popFeatureLayer() {
+            active = SEED_LAYER;
+        },
+        async drop() {
+            await withPostgresClient(resolved, async (client) => {
+                await client.query(`DROP SCHEMA IF EXISTS ${quoteIdentifier(BASELINE_SCHEMA)} CASCADE`);
+            });
+        },
+    };
+}

package/dist/src/functions/db/scenario-baseline.d.ts

@@ -0,0 +1,51 @@
+import type { ResolvedDb } from './local-db.js';
+/**
+ * Where the captured copies live: a schema of its own in Postgres, a name
+ * prefix in sqlite, which has no schemas to hide them in.
+ */
+export declare const BASELINE_SCHEMA = "pikku_scenario_baseline";
+export declare const BASELINE_PREFIX = "pikku_scenario_baseline__";
+/**
+ * The seed layer is the database as the suite found it. The feature layer is
+ * that plus whatever a feature's `before` hook built, and it exists so a
+ * scenario can be rolled back without losing its feature's fixtures.
+ */
+export declare const SEED_LAYER = "seed";
+export declare const FEATURE_LAYER = "feature";
+export declare const LAYERS: string[];
+export interface ScenarioBaselineOptions {
+    /**
+     * Tables left alone by both the capture and the restore.
+     *
+     * The session tables belong here: an actor signs in once for the whole run,
+     * and rolling its session back to a baseline taken before the sign-in logs
+     * every actor out mid-suite.
+     */
+    keep?: string[];
+}
+export interface ScenarioBaseline {
+    /** The tables this baseline holds a copy of, qualified as the dialect names them. */
+    tables: string[];
+    /** Put every captured table back as the active layer holds it. */
+    restore(): Promise<void>;
+    /**
+     * Capture the database as it stands now and make that the active layer, so
+     * later restores come back to here rather than to the seed.
+     */
+    pushFeatureLayer(): Promise<void>;
+    /** Make the seed the active layer again. */
+    popFeatureLayer(): Promise<void>;
+    /** Drop the captured copies. A database left with them reads as schema drift. */
+    drop(): Promise<void>;
+}
+/** An identifier, quoted so its casing and any punctuation survive the parser. */
+export declare const quoteIdentifier: (name: string) => string;
+/**
+ * A copy's name, stable for a given layer and source table and short enough for
+ * Postgres. Long names keep a readable prefix and earn a hash suffix, because a
+ * blind truncation maps two different tables onto one copy.
+ */
+export declare const copyName: (parts: string[]) => string;
+/** Matches a `keep` entry against a table, bare or schema-qualified. */
+export declare const keepMatcher: (keep: string[]) => (schema: string | null, table: string) => boolean;
+export declare function captureScenarioBaseline(resolved: ResolvedDb, options?: ScenarioBaselineOptions): Promise<ScenarioBaseline>;

package/dist/src/functions/db/scenario-baseline.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+/**
+ * Where the captured copies live: a schema of its own in Postgres, a name
+ * prefix in sqlite, which has no schemas to hide them in.
+ */
+export const BASELINE_SCHEMA = 'pikku_scenario_baseline';
+export const BASELINE_PREFIX = `${BASELINE_SCHEMA}__`;
+/**
+ * The seed layer is the database as the suite found it. The feature layer is
+ * that plus whatever a feature's `before` hook built, and it exists so a
+ * scenario can be rolled back without losing its feature's fixtures.
+ */
+export const SEED_LAYER = 'seed';
+export const FEATURE_LAYER = 'feature';
+export const LAYERS = [SEED_LAYER, FEATURE_LAYER];
+/** Postgres truncates identifiers at 63 bytes, silently colliding two tables. */
+const MAX_IDENTIFIER_LENGTH = 63;
+/** An identifier, quoted so its casing and any punctuation survive the parser. */
+export const quoteIdentifier = (name) => `"${name.replace(/"/g, '""')}"`;
+/**
+ * A copy's name, stable for a given layer and source table and short enough for
+ * Postgres. Long names keep a readable prefix and earn a hash suffix, because a
+ * blind truncation maps two different tables onto one copy.
+ */
+export const copyName = (parts) => {
+    const raw = parts.join('__');
+    if (raw.length <= MAX_IDENTIFIER_LENGTH)
+        return raw;
+    const hash = createHash('sha1').update(raw).digest('hex').slice(0, 8);
+    return `${raw.slice(0, MAX_IDENTIFIER_LENGTH - 9)}_${hash}`;
+};
+/** Matches a `keep` entry against a table, bare or schema-qualified. */
+export const keepMatcher = (keep) => {
+    const names = new Set(keep.map((name) => name.toLowerCase()));
+    return (schema, table) => names.has(table.toLowerCase()) ||
+        (schema !== null && names.has(`${schema}.${table}`.toLowerCase()));
+};
+export async function captureScenarioBaseline(resolved, options = {}) {
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error(`Scenario database reset refused: NODE_ENV=production. It replaces live rows with seed data — it only runs in dev.`);
+    }
+    // `isLocalUrl` on the environment's apiUrl says nothing about where the
+    // database is: a local server can be configured against a remote postgres,
+    // and this replaces every row it finds.
+    if (resolved.dialect === 'postgres' && resolved.mode === 'url') {
+        const { isLocalUrl } = await import('../commands/environment.js');
+        if (!isLocalUrl(resolved.connectionString ?? '')) {
+            throw new Error(`Scenario database reset refused: postgresUrl points at a host other than this machine. It rolls every table back to a copy taken at the start of the run, so it only runs against a database on this machine.`);
+        }
+    }
+    // Imported here rather than at the top because both dialects import the
+    // shared helpers back out of this module, and a static edge each way is a
+    // cycle.
+    if (resolved.dialect === 'sqlite') {
+        const { captureSqliteScenarioBaseline } = await import('./sqlite/scenario-baseline.js');
+        return captureSqliteScenarioBaseline(resolved, options);
+    }
+    const { capturePostgresScenarioBaseline } = await import('./postgres/scenario-baseline.js');
+    return capturePostgresScenarioBaseline(resolved, options);
+}

package/dist/src/functions/db/sqlite/scenario-baseline.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedSqliteDb } from '../local-db.js';
+import { type ScenarioBaseline, type ScenarioBaselineOptions } from '../scenario-baseline.js';
+export declare function captureSqliteScenarioBaseline(resolved: ResolvedSqliteDb, { keep }: ScenarioBaselineOptions): Promise<ScenarioBaseline>;

package/dist/src/functions/db/sqlite/scenario-baseline.js

@@ -0,0 +1,82 @@
+import { MIGRATION_TRACKING_TABLE } from '@pikku/migrator-sql';
+import { loadSqliteRuntime } from '@pikku/migrator-sql/sqlite';
+import { BASELINE_PREFIX, FEATURE_LAYER, LAYERS, SEED_LAYER, copyName, keepMatcher, quoteIdentifier, } from '../scenario-baseline.js';
+export async function captureSqliteScenarioBaseline(resolved, { keep = [] }) {
+    const runtime = await loadSqliteRuntime();
+    const shouldKeep = keepMatcher(keep);
+    const withDb = (run) => {
+        const db = runtime.open(resolved.dbFile);
+        // The app under test is still connected to this file. A rollback-journal
+        // database gives a writer an exclusive lock, so without a timeout the first
+        // statement that overlaps one of the app's reads fails outright with
+        // SQLITE_BUSY and takes the scenario with it.
+        db.exec('PRAGMA busy_timeout = 10000');
+        try {
+            return run(db);
+        }
+        finally {
+            db.close();
+        }
+    };
+    const copy = (layer, table) => quoteIdentifier(BASELINE_PREFIX + copyName([layer, table]));
+    const tables = withDb((db) => db
+        .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'`)
+        .all()
+        .map(({ name }) => name)
+        .filter((name) => name !== MIGRATION_TRACKING_TABLE &&
+        !name.startsWith(BASELINE_PREFIX) &&
+        !shouldKeep(null, name))
+        .sort());
+    const captureLayer = (layer) => withDb((db) => {
+        for (const table of tables) {
+            db.exec(`DROP TABLE IF EXISTS ${copy(layer, table)}`);
+            db.exec(`CREATE TABLE ${copy(layer, table)} AS SELECT * FROM ${quoteIdentifier(table)}`);
+        }
+    });
+    const restoreLayer = (layer) => withDb((db) => {
+        // Foreign keys are switched off for the duration rather than the tables
+        // sorted into dependency order: `keep` can hold the parent of a table
+        // being replaced, which no ordering makes legal. The pragma is a no-op
+        // inside a transaction, so it goes before BEGIN.
+        db.exec('PRAGMA foreign_keys = OFF');
+        db.exec('BEGIN');
+        try {
+            for (const table of tables) {
+                db.exec(`DELETE FROM ${quoteIdentifier(table)}`);
+                db.exec(`INSERT INTO ${quoteIdentifier(table)} SELECT * FROM ${copy(layer, table)}`);
+            }
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+        finally {
+            db.exec('PRAGMA foreign_keys = ON');
+        }
+    });
+    captureLayer(SEED_LAYER);
+    let active = SEED_LAYER;
+    return {
+        tables,
+        async restore() {
+            restoreLayer(active);
+        },
+        async pushFeatureLayer() {
+            captureLayer(FEATURE_LAYER);
+            active = FEATURE_LAYER;
+        },
+        async popFeatureLayer() {
+            active = SEED_LAYER;
+        },
+        async drop() {
+            withDb((db) => {
+                for (const layer of LAYERS) {
+                    for (const table of tables) {
+                        db.exec(`DROP TABLE IF EXISTS ${copy(layer, table)}`);
+                    }
+                }
+            });
+        },
+    };
+}

package/dist/src/functions/examples/command-schemas.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The schemas the wired commands bind to.
+ *
+ * Re-bound here for the reason the knowledge commands re-bind theirs: the inspector that
+ * reads a command's schema is the PUBLISHED one during the bootstrap build, and a command
+ * file imports `#pikku`, which points at output that does not exist yet at that point. A
+ * schema the inspector has to import therefore cannot live beside a wired function.
+ */
+export declare const ExamplesListInputSchema: import("zod").ZodObject<{
+    group: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export declare const ExamplesListOutputSchema: import("zod").ZodObject<{
+    examples: import("zod").ZodArray<import("zod").ZodObject<{
+        name: import("zod").ZodString;
+        title: import("zod").ZodString;
+        when: import("zod").ZodString;
+        lang: import("zod").ZodString;
+        entity: import("zod").ZodString;
+        deferUntil: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;
+export declare const ExamplesShowInputSchema: import("zod").ZodObject<{
+    name: import("zod").ZodString;
+    entity: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export declare const ExamplesShowOutputSchema: import("zod").ZodObject<{
+    found: import("zod").ZodBoolean;
+    name: import("zod").ZodString;
+    title: import("zod").ZodString;
+    when: import("zod").ZodString;
+    source: import("zod").ZodString;
+    steps: import("zod").ZodString;
+    code: import("zod").ZodString;
+    notes: import("zod").ZodArray<import("zod").ZodObject<{
+        anchor: import("zod").ZodNullable<import("zod").ZodString>;
+        lines: import("zod").ZodArray<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    available: import("zod").ZodArray<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export declare const ExamplesAddInputSchema: import("zod").ZodObject<{
+    name: import("zod").ZodString;
+    entity: import("zod").ZodOptional<import("zod").ZodString>;
+    app: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export declare const ExamplesAddOutputSchema: import("zod").ZodObject<{
+    ok: import("zod").ZodBoolean;
+    name: import("zod").ZodString;
+    entity: import("zod").ZodString;
+    refusal: import("zod").ZodString;
+    written: import("zod").ZodArray<import("zod").ZodString>;
+    kept: import("zod").ZodArray<import("zod").ZodString>;
+    failed: import("zod").ZodArray<import("zod").ZodString>;
+    deferred: import("zod").ZodArray<import("zod").ZodObject<{
+        path: import("zod").ZodString;
+        tables: import("zod").ZodArray<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    manual: import("zod").ZodArray<import("zod").ZodString>;
+    api: import("zod").ZodArray<import("zod").ZodObject<{
+        path: import("zod").ZodString;
+        exports: import("zod").ZodArray<import("zod").ZodString>;
+        declarations: import("zod").ZodArray<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    when: import("zod").ZodString;
+    steps: import("zod").ZodString;
+    notes: import("zod").ZodArray<import("zod").ZodObject<{
+        anchor: import("zod").ZodNullable<import("zod").ZodString>;
+        lines: import("zod").ZodArray<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;

package/dist/src/functions/examples/command-schemas.js

@@ -0,0 +1,15 @@
+import { ExamplesAddInput, ExamplesAddOutput, ExamplesListInput, ExamplesListOutput, ExamplesShowInput, ExamplesShowOutput, } from './schemas.js';
+/**
+ * The schemas the wired commands bind to.
+ *
+ * Re-bound here for the reason the knowledge commands re-bind theirs: the inspector that
+ * reads a command's schema is the PUBLISHED one during the bootstrap build, and a command
+ * file imports `#pikku`, which points at output that does not exist yet at that point. A
+ * schema the inspector has to import therefore cannot live beside a wired function.
+ */
+export const ExamplesListInputSchema = ExamplesListInput;
+export const ExamplesListOutputSchema = ExamplesListOutput;
+export const ExamplesShowInputSchema = ExamplesShowInput;
+export const ExamplesShowOutputSchema = ExamplesShowOutput;
+export const ExamplesAddInputSchema = ExamplesAddInput;
+export const ExamplesAddOutputSchema = ExamplesAddOutput;

package/dist/src/functions/examples/corpus.d.ts

@@ -0,0 +1,115 @@
+import type { PikkuExample } from '../../examples.gen.js';
+/**
+ * Strip the `//~` teaching comments so what lands on disk is clean code.
+ *
+ * Keeps a code line that carries a trailing `//~` by removing just the comment; drops a
+ * line that is entirely one. This is what lets a recipe be heavily annotated for whoever
+ * reads it while the file it writes has no comments in it at all.
+ */
+export declare function stripTeaching(content: string): string;
+/** A run of `//~` teaching, and the code line it was written against. */
+export interface ExampleNote {
+    /** The line the prose annotates, trimmed; null for prose that opens a file. */
+    anchor: string | null;
+    lines: string[];
+}
+/**
+ * Every `//~` teaching line in a recipe, paired with the code it annotates.
+ *
+ * The anchor is what makes a flat dump readable: prose like "swap this for your own list
+ * RPC" means nothing on its own and everything beside the line it points at. The leading
+ * header block is skipped by the same rule the header parser uses, so `name`, `when` and
+ * `steps:` are never repeated here.
+ */
+export declare function extractTeaching(content: string): ExampleNote[];
+export interface ExampleFile {
+    path: string;
+    body: string;
+    /**
+     * `(overwrite)` on the marker line. The default is never-clobber, which is right for a
+     * file the caller may have customised; a recipe that REPLACES a shipped file says so.
+     */
+    overwrite: boolean;
+}
+export declare function splitExampleFiles(content: string): ExampleFile[];
+/**
+ * Where a recipe's file lands, relative to the project root.
+ *
+ * A marker path beginning `src/` is FRONTEND-relative; one beginning
+ * `packages/functions/src/` is backend, and is rebased onto whatever this project calls
+ * its source directory — the starter template keeps functions in a workspace package and
+ * a single-package project keeps them at `src/`, and a recipe should not have to know
+ * which. Anything else is taken from the project root as written.
+ */
+export declare function resolveExamplePath(path: string, appBase: string, functionsDir: string): string;
+/** The three spellings a recipe spells its domain symbol in. */
+export interface EntityNames {
+    /** `sessionNote` — identifiers, RPC names. */
+    camel: string;
+    /** `SessionNote` — types, generated zod (`SessionNoteZ`), components. */
+    pascal: string;
+    /** `session-note` — file names and route paths. */
+    kebab: string;
+}
+export declare function entityNames(raw: string): EntityNames;
+/**
+ * Entity names the stack already owns, with what each one would collide with.
+ *
+ * The rename lands a `CREATE TABLE <entity>` in a migration, so `--entity session` does
+ * not produce a second table — it collides with Better Auth's session store and breaks
+ * login. Deliberately a refusal rather than an auto-prefix: the caller has to pick the
+ * domain word they actually mean, and a silent rewrite would hand back files named for
+ * something they never asked for.
+ */
+export declare const RESERVED_ENTITY_NAMES: Map<string, string>;
+/** What `--entity <raw>` would collide with, or null when the name is free to use. */
+export declare function reservedEntityCollision(raw: string): string | null;
+export declare function renameEntityInCode(content: string, from: EntityNames, to: EntityNames): string;
+export declare function renameEntityInPath(path: string, from: EntityNames, to: EntityNames): string;
+/**
+ * Point an example's `actors.<id>` at somebody this project actually declares.
+ *
+ * A browser step's actor has to be a literal `actors.<name>`, so every scenario recipe
+ * names one — and a persona that does not exist fails codegen, which stops everything
+ * written afterwards from registering. Distinct unknown ids map to distinct personas in
+ * declaration order, so a two-colleague example keeps its two colleagues, and saturate
+ * on the last one when the cast is smaller.
+ */
+export declare function renameActorsInCode(content: string, cast: string[]): string;
+/**
+ * Every RPC a scenario recipe's steps call BY NAME, after the entity rename.
+ *
+ * A scenario is the one family that is a FORWARD REFERENCE: codegen auto-discovers every
+ * `*.scenario.ts` and types `scenario.do`'s second argument as the union of registered
+ * RPCs, so a step naming one that does not exist yet is a type error the moment the file
+ * lands — and while codegen is red nothing written after it registers.
+ */
+export declare function scenarioRpcNames(body: string): string[];
+/** What a written file offers whatever imports it. */
+export interface ExampleApi {
+    exports: string[];
+    /** The `Props` (and transitively referenced) type declarations, verbatim. */
+    declarations: string[];
+}
+/**
+ * The API of a written file, taken from its source rather than described by hand.
+ *
+ * A recipe that WRITES its files leaves the caller holding filenames and nothing else —
+ * they have not seen a single prop, and buy them back one file read at a time.
+ * Declarations come back verbatim, teaching comments included, because the comment is
+ * routinely the part a type cannot express.
+ */
+export declare function extractExampleApi(body: string): ExampleApi;
+/**
+ * The recipes that must be written before this one, dependencies first.
+ *
+ * A recipe that declares an example entity is NOT installed unattended — the rename is
+ * the whole point of it, and guessing the caller's domain word would write the example
+ * one into their app. Those come back as `manual` so the caller can be told to run each
+ * with the entity it is for.
+ */
+export declare function requiredChain(name: string, entries: readonly PikkuExample[]): {
+    install: string[];
+    manual: string[];
+    missing: string[];
+};