@pikku/cli 0.12.96 → 0.12.99

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

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, readdirSync, } from 'node:fs';
 import { resolve, isAbsolute, relative, dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import { runInNewContext } from 'node:vm';
 import { transformSync } from 'esbuild';
 import { CamelCasePlugin, Kysely, PostgresDialect } from 'kysely';
@@ -15,7 +16,7 @@ import { SqliteMigrationExecutor } from './sqlite/sqlite-migrator.js';
 import { SqliteIntrospector } from './sqlite/sqlite-introspector.js';
 import { createSqliteKysely } from './sqlite/sqlite-kysely.js';
 import { loadSqliteRuntime } from './sqlite/sqlite-runtime.js';
-import { seed as runSeed } from './sqlite/seed.js';
+import { devSeed as runDevSeed } from './sqlite/dev-seed.js';
 import { PostgresMigrationExecutor } from './postgres/postgres-migrator.js';
 import { createPGliteKysely } from './postgres/pglite-kysely.js';
 import { PostgresIntrospector } from './postgres/postgres-introspector.js';
@@ -37,7 +38,11 @@ export function parseDatabaseUrl(url) {
  * Resolve a UserConfigShape into an absolute-path descriptor.
  * Returns null when neither sqliteDb nor postgresUrl is configured.
  */
-export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
+export function resolveDb(userConfig, rootDir, outDir, runtimeDir, dbConfig) {
+    // The parameter took a bare schema string before `defaultSchema` existed;
+    // both forms are accepted so callers outside this repo keep working.
+    const schema = typeof dbConfig === 'string' ? dbConfig : dbConfig?.schema;
+    const defaultSchema = typeof dbConfig === 'string' ? undefined : dbConfig?.defaultSchema;
     const resolvedRuntimeDir = runtimeDir
         ? resolveAgainst(rootDir, runtimeDir)
         : join(rootDir, '.pikku-runtime');
@@ -58,17 +63,21 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
         classificationsGenJsonFile: join(rootDir, 'db', 'annotations.gen.json'),
         zodFile: join(outDir, 'db', 'zod.gen.ts'),
         camelCase: true,
+        defaultSchema,
     });
     if (userConfig.postgresUrl && userConfig.sqliteDb) {
         throw new Error('Both postgresUrl and sqliteDb are set. Configure exactly one database dialect.');
     }
+    const pgliteExtensions = userConfig.pgliteExtensions ?? [];
     if (userConfig.postgresUrl) {
         return {
             dialect: 'postgres',
             mode: 'url',
             connectionString: userConfig.postgresUrl,
             runtimeDir: resolvedRuntimeDir,
-            seedFile: resolveAgainst(rootDir, 'db/postgres-seed.sql'),
+            devSeedFile: resolveAgainst(rootDir, 'db/postgres-dev-seed.sql'),
+            pgliteExtensions,
+            schema,
             ...base('db/postgres'),
         };
     }
@@ -77,11 +86,17 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
             ? '.pikku-runtime/dev.db'
             : undefined);
     if (sqliteDb) {
+        if (schema) {
+            throw new Error(`db.schema is set to '${schema}', but the resolved database is sqlite. ` +
+                'sqlite has one schema to be in, and its REFERENCES clause takes a bare ' +
+                'table name, so qualified DDL does not compile there. Remove db.schema, ' +
+                'or configure postgres.');
+        }
         return {
             dialect: 'sqlite',
             dbFile: resolveAgainst(rootDir, sqliteDb),
             runtimeDir: resolvedRuntimeDir,
-            seedFile: resolveAgainst(rootDir, 'db/sqlite-seed.sql'),
+            devSeedFile: resolveAgainst(rootDir, 'db/sqlite-dev-seed.sql'),
             ...base('db/sqlite'),
         };
     }
@@ -91,7 +106,9 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
             mode: 'pglite',
             pgliteDir: join(resolvedRuntimeDir, 'dev-postgres'),
             runtimeDir: resolvedRuntimeDir,
-            seedFile: resolveAgainst(rootDir, 'db/postgres-seed.sql'),
+            devSeedFile: resolveAgainst(rootDir, 'db/postgres-dev-seed.sql'),
+            pgliteExtensions,
+            schema,
             ...base('db/postgres'),
         };
     }
@@ -120,7 +137,7 @@ async function createPostgresClient(resolved) {
         throw new Error('PGlite Postgres resolution is missing pgliteDir.');
     }
     mkdirSync(dirname(resolved.pgliteDir), { recursive: true });
-    const db = await createEmbeddedPostgres(resolved.pgliteDir);
+    const db = await createEmbeddedPostgres(resolved, resolved.pgliteDir);
     return pgliteAsClient(db);
 }
 let embeddedPostgresWasm;
@@ -157,21 +174,107 @@ async function loadEmbeddedPostgresWasm() {
         return undefined;
     }
 }
-async function createEmbeddedPostgres(dataDir) {
+const isPGliteExtension = (value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.setup === 'function';
+/**
+ * Turn a declared extension specifier into the module that publishes it.
+ *
+ * A bare name is one of PGlite's own contrib extensions (`hstore`, `citext`,
+ * `uuid_ossp`), which ship with the CLI's copy of PGlite and need nothing
+ * installed. Anything else is a package the project depends on — pgvector, say,
+ * as `@electric-sql/pglite-pgvector` — so it is resolved from the project first
+ * and only then from the CLI, since the project is where a user installs it.
+ */
+async function importPGliteExtensionModule(spec, rootDir) {
+    const id = spec.includes('/') || spec.startsWith('@')
+        ? spec
+        : `@electric-sql/pglite/contrib/${spec}`;
+    for (const from of [join(rootDir, 'package.json'), import.meta.url]) {
+        let resolvedPath;
+        try {
+            resolvedPath = createRequire(from).resolve(id);
+        }
+        catch {
+            continue;
+        }
+        return (await import(pathToFileURL(resolvedPath).href));
+    }
+    throw new Error(`The PGlite extension '${spec}' could not be resolved as '${id}', ` +
+        `from either the project (${rootDir}) or the pikku CLI. ` +
+        `Install it in your project, or name one of PGlite's bundled contrib ` +
+        `extensions (hstore, citext, uuid_ossp, …), which need no install.`);
+}
+/**
+ * Load every extension the project declares, keyed the way PGlite wants them.
+ *
+ * The key is the export name (`vector`, `hstore`), which is also the name the
+ * SQL uses, so `CREATE EXTENSION vector` finds what a declaration of
+ * `@electric-sql/pglite-pgvector` loaded. A module exporting several is fine —
+ * all of them are taken — and a `default` export is used only when it is the
+ * only extension there, so a package that default-exports the same object it
+ * also names is not registered twice.
+ */
+export async function loadPGliteExtensions(rootDir, specs) {
+    const extensions = {};
+    for (const spec of specs) {
+        const module = await importPGliteExtensionModule(spec, rootDir);
+        const found = Object.entries(module).filter(([, value]) => isPGliteExtension(value));
+        const named = found.filter(([name]) => name !== 'default');
+        const chosen = named.length > 0 ? named : found;
+        if (chosen.length === 0) {
+            throw new Error(`'${spec}' exports no PGlite extension. A PGlite extension is an ` +
+                `object with a 'setup' function — check that the package is one, ` +
+                `and that its version matches the PGlite the CLI runs.`);
+        }
+        for (const [name, extension] of chosen) {
+            extensions[name === 'default' ? (extension.name ?? spec) : name] =
+                extension;
+        }
+    }
+    return extensions;
+}
+async function createEmbeddedPostgres(context, dataDir) {
     embeddedPostgresWasm ??= loadEmbeddedPostgresWasm();
-    const [{ PGlite }, { pgcrypto }, wasm] = await Promise.all([
+    const [{ PGlite }, { pgcrypto }, wasm, declared] = await Promise.all([
         import('@electric-sql/pglite'),
         import('@electric-sql/pglite/contrib/pgcrypto'),
         embeddedPostgresWasm,
+        loadPGliteExtensions(context.rootDir, context.pgliteExtensions),
     ]);
     return new PGlite({
         ...(dataDir ? { dataDir } : {}),
         ...wasm,
         extensions: {
             pgcrypto,
+            ...declared,
         },
     });
 }
+/**
+ * PGlite reports an extension it was never given as a plain
+ * `extension "x" is not available`, which reads as though the SQL is at fault.
+ * It is not: the database is real Postgres, the migration is fine, and the one
+ * thing missing is the declaration that would have loaded the extension into
+ * this particular instance. Say so, since nothing else in the message points
+ * anywhere near the fix.
+ */
+function explainMissingExtension(error, declared) {
+    const message = error instanceof Error ? error.message : '';
+    const match = /extension "([^"]+)" is not available/.exec(message);
+    if (!match)
+        return error;
+    const name = match[1];
+    return new Error(`The embedded PGlite database has no '${name}' extension. ` +
+        `The CLI migrates a PGlite shadow database to type and diff your schema, ` +
+        `so every extension your migrations use has to be declared as ` +
+        `pgliteExtensions in createConfig — e.g. pgliteExtensions: ['${name}'] ` +
+        `for a PGlite contrib extension, or the package that publishes it ` +
+        `('@electric-sql/pglite-pgvector' for pgvector).` +
+        (declared.length > 0
+            ? ` Currently declared: ${declared.join(', ')}.`
+            : ''), { cause: error });
+}
 function pgliteAsClient(db) {
     return {
         query: (sql, params) => db.query(sql, params),
@@ -189,6 +292,14 @@ async function withPostgresClient(resolved, run) {
     try {
         return await run(client);
     }
+    catch (error) {
+        // Only the embedded database's missing extensions are the declaration's
+        // doing. On a real server it is the server that lacks the extension, and
+        // pointing at the CLI's config would send the reader the wrong way.
+        throw resolved.mode === 'pglite'
+            ? explainMissingExtension(error, resolved.pgliteExtensions)
+            : error;
+    }
     finally {
         await client.end();
     }
@@ -226,6 +337,7 @@ export async function migrateAndCodegen(resolved, options = {}) {
                 schemaJsonFile: resolved.schemaJsonFile,
                 enumsFile: resolved.enumsFile,
                 camelCase: resolved.camelCase,
+                defaultSchema: resolved.defaultSchema,
                 rootDir: resolved.rootDir,
                 dialect: 'sqlite',
                 migrationsDir: resolved.migrationsDir,
@@ -237,7 +349,7 @@ export async function migrateAndCodegen(resolved, options = {}) {
     }
     else {
         const withClient = options.scratch
-            ? (_r, run) => withScratchPostgresDatabase(run)
+            ? (r, run) => withScratchPostgresDatabase(r, run)
             : withPostgresClient;
         await withClient(resolved, async (client) => {
             const introspector = new PostgresIntrospector(client);
@@ -253,6 +365,7 @@ export async function migrateAndCodegen(resolved, options = {}) {
                     schemaJsonFile: resolved.schemaJsonFile,
                     enumsFile: resolved.enumsFile,
                     camelCase: resolved.camelCase,
+                    defaultSchema: resolved.defaultSchema,
                     rootDir: resolved.rootDir,
                     dialect: 'postgres',
                     migrationsDir: resolved.migrationsDir,
@@ -282,21 +395,32 @@ export async function migrateAndCodegen(resolved, options = {}) {
     };
 }
 // ─── SQLite-only operations ───────────────────────────────────────────────────
-export async function seed(resolved) {
+/**
+ * Apply the dev seed file. Only {@link reset} calls this, immediately after
+ * migrating a database it has just wiped, which is what lets a seed file be
+ * plain `INSERT`s rather than idempotent ones.
+ *
+ * `reset` refuses production before it gets here, so this guard is unreachable
+ * through the CLI. It stays because the export is reachable without it.
+ */
+export async function devSeed(resolved) {
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error(`pikku dev seed refused: NODE_ENV=production. Seed data is test data — it only runs in dev.`);
+    }
     if (resolved.dialect === 'sqlite') {
         const runtime = await loadSqliteRuntime();
         const db = runtime.open(resolved.dbFile);
         try {
-            return runSeed(db, resolved.seedFile);
+            return runDevSeed(db, resolved.devSeedFile);
         }
         finally {
             db.close();
         }
     }
-    if (!existsSync(resolved.seedFile)) {
+    if (!existsSync(resolved.devSeedFile)) {
         return { applied: false, bytes: 0 };
     }
-    const sql = readFileSync(resolved.seedFile, 'utf8');
+    const sql = readFileSync(resolved.devSeedFile, 'utf8');
     if (sql.trim().length === 0) {
         return { applied: false, bytes: 0 };
     }
@@ -346,8 +470,7 @@ export async function reset(resolved, rootDir) {
         AND schema_name NOT LIKE 'pg_temp_%'
     `);
         for (const { schema_name: schemaName } of result.rows) {
-            const quoted = `"${schemaName.replace(/"/g, '""')}"`;
-            await client.query(`DROP SCHEMA IF EXISTS ${quoted} CASCADE`);
+            await client.query(`DROP SCHEMA IF EXISTS ${quoteIdentifier(schemaName)} CASCADE`);
         }
         await client.query('CREATE SCHEMA IF NOT EXISTS public');
     });
@@ -474,7 +597,7 @@ export async function createKysely(resolved) {
     }
     mkdirSync(dirname(resolved.pgliteDir), { recursive: true });
     return createPGliteKysely({
-        db: await createEmbeddedPostgres(resolved.pgliteDir),
+        db: await createEmbeddedPostgres(resolved, resolved.pgliteDir),
         camelCase: resolved.camelCase,
         plugins,
     });
@@ -486,11 +609,22 @@ async function introspectorToMap(intro) {
     }
     return map;
 }
-function diffSchemas(desired, actual) {
+/**
+ * The tables and columns `desired` has that `actual` does not.
+ *
+ * `schema` is the one the desired bare names belong in, when the caller knows.
+ * Given it, only that schema's copy of a table counts: a `workflow_step` in
+ * `public` is a different table from the `app.workflow_step` a source with
+ * `db.schema: "app"` wants, and letting it match would report the source
+ * satisfied by a table its SQL never creates.
+ */
+function diffSchemas(desired, actual, schema) {
     const missingTables = [];
     const missingColumns = [];
     for (const [table, cols] of desired) {
-        const actualCols = actual.get(table) ?? schemaQualifiedMatch(actual, table);
+        const actualCols = schema
+            ? actual.get(qualifiedTableKey(schema, table))
+            : (actual.get(table) ?? schemaQualifiedMatch(actual, table));
         if (!actualCols) {
             missingTables.push(table);
             continue;
@@ -501,6 +635,19 @@ function diffSchemas(desired, actual) {
     }
     return { missingTables, missingColumns };
 }
+/**
+ * How an introspected schema map keys a table in a given schema.
+ *
+ * Introspection elides `public`, so the key for a table there is the bare name.
+ * Anything else carries its qualifier.
+ */
+function qualifiedTableKey(schema, table) {
+    return schema === 'public' ? table : `${schema}.${table}`;
+}
+/** A PostgreSQL identifier, quoted so its casing survives the parser. */
+function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
 /**
  * The one table in `actual` whose name matches `table` once its schema is
  * dropped, if there is exactly one.
@@ -530,11 +677,14 @@ function isPostgresAuthDatabase(options) {
 // target server. Creating a real database via `CREATE DATABASE` would require
 // elevated privileges that application roles (correctly) don't have, which made
 // `pikku db migrate` fail against managed/locked-down Postgres (error 42501).
-async function withScratchPostgresDatabase(run) {
-    const scratchDb = await createEmbeddedPostgres();
+async function withScratchPostgresDatabase(context, run) {
+    const scratchDb = await createEmbeddedPostgres(context);
     try {
         return await run(pgliteAsClient(scratchDb));
     }
+    catch (error) {
+        throw explainMissingExtension(error, context.pgliteExtensions);
+    }
     finally {
         if (!scratchDb.closed) {
             await scratchDb.close();
@@ -551,8 +701,8 @@ async function postgresDatabaseToMap(client) {
         await intro.close();
     }
 }
-async function desiredPostgresAuthSchema(rootDir, srcDirectories, logger) {
-    return withScratchPostgresDatabase(async (scratchDb) => {
+async function desiredPostgresAuthSchema(context, rootDir, srcDirectories, logger) {
+    return withScratchPostgresDatabase(context, async (scratchDb) => {
         // The scratch DB is always an embedded PGlite instance (see
         // withScratchPostgresDatabase), so drive Better Auth's migration codegen
         // through the PGlite-backed Kysely regardless of how the app DB is
@@ -598,7 +748,7 @@ export async function desiredAuthSchema(resolved, rootDir, srcDirectories, logge
             if (resolved.dialect !== 'postgres') {
                 throw new Error('Better Auth database.type is postgres, but the resolved app database is not postgres.');
             }
-            return desiredPostgresAuthSchema(rootDir, srcDirectories, logger);
+            return desiredPostgresAuthSchema(resolved, rootDir, srcDirectories, logger);
         }
         const { runMigrations, compileMigrations } = await getAuthMigrations(options);
         await runMigrations();
@@ -685,7 +835,7 @@ export async function desiredRuntimeSchema(resolved, rootDir, srcDirectories, lo
             db.close();
         }
     }
-    return withScratchPostgresDatabase(async (db) => {
+    return withScratchPostgresDatabase(resolved, async (db) => {
         const kysely = createPGliteKysely({
             db: db.__pglite,
             camelCase: true,
@@ -694,7 +844,7 @@ export async function desiredRuntimeSchema(resolved, rootDir, srcDirectories, lo
             const { tables, schemas, types } = await collect(kysely, () => postgresDatabaseToMap(db));
             return {
                 tables,
-                sql: compilePikkuSchemas(kysely, schemas, types),
+                sql: compilePikkuSchemas(kysely, schemas, types, resolved.schema),
                 skipped,
             };
         }
@@ -736,8 +886,8 @@ async function coveredSqliteSchema(migrationsDir) {
         db.close();
     }
 }
-async function coveredPostgresSchema(migrationsDir) {
-    return withScratchPostgresDatabase(async (client) => {
+async function coveredPostgresSchema(migrationsDir, context) {
+    return withScratchPostgresDatabase(context, async (client) => {
         await migrate(new PostgresMigrationExecutor(client), migrationsDir);
         return postgresDatabaseToMap(client);
     });
@@ -764,7 +914,7 @@ async function coveredPostgresSchema(migrationsDir) {
 export async function computeSchemaDrift(resolved, rootDir, srcDirectories, logger) {
     const covered = resolved.dialect === 'sqlite'
         ? await coveredSqliteSchema(resolved.migrationsDir)
-        : await coveredPostgresSchema(resolved.migrationsDir);
+        : await coveredPostgresSchema(resolved.migrationsDir, resolved);
     const actual = await introspectSchema(resolved);
     const { missingTables, missingColumns } = diffSchemas(covered, actual);
     // Compare on the full name. A migration that names no schema lands in
@@ -889,7 +1039,7 @@ const concatMigrations = (migrationsDir) => readdirSync(migrationsDir)
  * happens to be configured against — an addon is published once and consumed by
  * projects on either engine.
  */
-export async function exportSchema(rootDir) {
+export async function exportSchema(rootDir, pgliteExtensions = []) {
     const artifact = {};
     const sqliteDir = join(rootDir, 'db', 'sqlite');
     if (existsSync(sqliteDir)) {
@@ -902,7 +1052,7 @@ export async function exportSchema(rootDir) {
     if (existsSync(postgresDir)) {
         artifact.postgres = {
             sql: concatMigrations(postgresDir),
-            tables: serializeSchemaMap(await coveredPostgresSchema(postgresDir)),
+            tables: serializeSchemaMap(await coveredPostgresSchema(postgresDir, { rootDir, pgliteExtensions })),
         };
     }
     return artifact;
@@ -975,6 +1125,7 @@ export async function schemaSources(resolved, rootDir, srcDirectories, logger, a
             name: 'pikku-runtime',
             desired: runtime,
             origin: "@pikku/kysely's runtime services",
+            schema: resolved.dialect === 'postgres' ? resolved.schema : undefined,
         });
     }
     sources.push(...(await addonSchemaSources(rootDir, resolved.dialect, addons, logger)));
@@ -1042,15 +1193,31 @@ export async function generateMigrations(resolved, rootDir, srcDirectories, logg
         // is part of what the next one is compared against.
         const covered = resolved.dialect === 'sqlite'
             ? await coveredSqliteSchema(resolved.migrationsDir)
-            : await coveredPostgresSchema(resolved.migrationsDir);
-        const { missingTables, missingColumns } = diffSchemas(source.desired.tables, covered);
+            : await coveredPostgresSchema(resolved.migrationsDir, resolved);
+        const { missingTables, missingColumns } = diffSchemas(source.desired.tables, covered, source.schema);
         if (missingTables.length === 0 && missingColumns.length === 0) {
             result.upToDate.push(source.name);
             continue;
         }
-        const partial = [...source.desired.tables.keys()].some((t) => covered.has(t));
+        // Matched the same way `diffSchemas` matches, qualifier and all. A project
+        // that keeps its tables in a schema has them covered as `app.workflow_step`
+        // while the declaration names them bare, so a strict `covered.has(t)` reads
+        // "nothing is covered" and re-emits the whole schema over tables that are
+        // already there — and a copy in some other schema is not that table, so it
+        // must not count either.
+        const partial = [...source.desired.tables.keys()].some((t) => source.schema
+            ? covered.has(qualifiedTableKey(source.schema, t))
+            : covered.has(t) || schemaQualifiedMatch(covered, t) !== undefined);
         let body;
         let needsBackfill = [];
+        // The source's own SQL is already qualified when it can be; the delta below
+        // is written here from bare introspected names, so it has to be qualified
+        // to match, or it alters a table in whichever schema `search_path` finds.
+        // Quoted, because the compiled SQL this delta has to line up with goes
+        // through the schema builder and is quoted there. `db.schema: "App"` left
+        // raw folds to `app`, so the delta would alter a table in a schema the
+        // runtime never uses.
+        const qualify = (table) => source.schema ? `${quoteIdentifier(source.schema)}.${table}` : table;
         if (!partial) {
             body = source.desired.sql;
         }
@@ -1071,7 +1238,7 @@ export async function generateMigrations(resolved, rootDir, srcDirectories, logg
                 statements.push(`-- REVIEW: ${table} is new, and its CREATE TABLE could not be found in the\n` +
                     `-- source's own SQL. The column list below carries no indexes, constraints\n` +
                     `-- or foreign keys — copy the real statement over it before applying.\n` +
-                    `CREATE TABLE ${table} (\n` +
+                    `CREATE TABLE ${qualify(table)} (\n` +
                     [...(columns?.values() ?? [])]
                         .map((c) => `  ${c.name} ${c.type}${c.notNull ? ' NOT NULL' : ''}`)
                         .join(',\n') +
@@ -1081,7 +1248,7 @@ export async function generateMigrations(resolved, rootDir, srcDirectories, logg
                 const infos = columns
                     .map((name) => source.desired.tables.get(table)?.get(name))
                     .filter((c) => c !== undefined);
-                const added = addColumnStatements(table, infos);
+                const added = addColumnStatements(qualify(table), infos);
                 statements.push(...added.sql);
                 needsBackfill.push(...added.needsBackfill);
             }

package/dist/src/functions/db/sqlite/dev-seed.d.ts

@@ -0,0 +1,12 @@
+import type { SyncSqliteDatabase } from './sqlite-runtime.js';
+export interface DevSeedResult {
+    applied: boolean;
+    bytes: number;
+}
+/**
+ * Apply db/<engine>-dev-seed.sql to the open db. Only `pikku db reset` reaches
+ * here, against a database it has just wiped and migrated, so the file may be
+ * plain `INSERT`s — it is never applied twice. Returns `applied: false` if the
+ * file doesn't exist; throws on SQL errors.
+ */
+export declare function devSeed(db: SyncSqliteDatabase, devSeedFile: string): DevSeedResult;

package/dist/src/functions/db/sqlite/dev-seed.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync } from 'node:fs';
+/**
+ * Apply db/<engine>-dev-seed.sql to the open db. Only `pikku db reset` reaches
+ * here, against a database it has just wiped and migrated, so the file may be
+ * plain `INSERT`s — it is never applied twice. Returns `applied: false` if the
+ * file doesn't exist; throws on SQL errors.
+ */
+export function devSeed(db, devSeedFile) {
+    if (!existsSync(devSeedFile)) {
+        return { applied: false, bytes: 0 };
+    }
+    const raw = readFileSync(devSeedFile);
+    db.exec('BEGIN');
+    try {
+        db.exec(raw.toString('utf8'));
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+    return { applied: true, bytes: raw.length };
+}

package/dist/src/functions/db/sqlite/sqlite-runtime-bun.js

@@ -30,7 +30,7 @@ class BunSqliteDatabase {
     }
     exec(sql) {
         // bun:sqlite throws "no valid SQL statement" on comment-only/empty input
-        // (e.g. a placeholder seed.sql); node:sqlite silently no-ops. Match node's
+        // (e.g. a placeholder dev-seed.sql); node:sqlite silently no-ops. Match node's
         // tolerance by skipping when nothing executable remains after stripping
         // comments. The original `sql` is still exec'd verbatim when non-empty.
         const executable = sql

package/dist/src/functions/validate/bootstrap-checks.d.ts

@@ -0,0 +1,19 @@
+import type { ValidateFinding } from './persona-checks.js';
+type PackageManifest = {
+    scripts?: Record<string, string>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+};
+/**
+ * Reports a root `start`/`dev` script that boots a server Pikku does not own.
+ *
+ * Services built in a hand-rolled entrypoint never reach the
+ * `pikkuServerLifecycle` hooks, so startup and shutdown work silently does not
+ * run. A project depending on a runtime adapter has opted into owning its own
+ * server, and a script that delegates to another runner cannot be followed, so
+ * neither is reported.
+ */
+export declare function runBootstrapChecks(root: string, rootPkg: PackageManifest | null, pikkuConfig: {
+    lint?: unknown;
+} | null): Promise<ValidateFinding[]>;
+export {};

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

@@ -0,0 +1,90 @@
+import { join } from 'node:path';
+import { readJsonSafe } from './shared-checks.js';
+/**
+ * `pikku dev` / `pikku serve` own the server lifecycle, so a project that boots
+ * through them can hang setup off `pikkuServerLifecycle` instead of constructing
+ * its own services. These patterns cover the runner prefixes people put in front
+ * of the binary (npx/yarn/pnpm/bun), leading env assignments, and `&&` chains.
+ */
+const PIKKU_SERVER_SCRIPT = /(?:^|[\s;&|])pikku(?:\.js)?\s+(?:-[^\s]*\s+)*(?:dev|serve)(?:\s|$)/;
+/**
+ * Scripts that hand off to another script rather than starting a process
+ * themselves. We cannot follow the indirection, so they are treated as unknown
+ * rather than reported.
+ */
+const DELEGATING_SCRIPT = /(?:^|[\s;&|])(?:turbo|nx|lerna|npm-run-all|run-p|run-s)(?:\s|$)|(?:^|[\s;&|])(?:npm|yarn|pnpm|bun)\s+(?:run|workspace|workspaces|--filter)(?:\s|$)/;
+/**
+ * Runtime adapters that embed Pikku in a server the project owns. Depending on
+ * one is a deliberate choice to bootstrap by hand — `pikku dev` / `pikku serve`
+ * cannot host these, so their entrypoints are not reported.
+ */
+const RUNTIME_ADAPTER_PACKAGES = new Set([
+    '@pikku/azure-functions',
+    '@pikku/bun-server',
+    '@pikku/cloudflare',
+    '@pikku/express',
+    '@pikku/express-middleware',
+    '@pikku/fastify',
+    '@pikku/fastify-plugin',
+    '@pikku/lambda',
+    '@pikku/modelcontextprotocol',
+    '@pikku/next',
+    '@pikku/node-http-server',
+    '@pikku/tanstack-start',
+    '@pikku/uws',
+    '@pikku/uws-handler',
+    '@pikku/ws',
+]);
+async function hasRuntimeAdapter(root, rootPkg) {
+    const fnPkg = await readJsonSafe(join(root, 'packages', 'functions', 'package.json'));
+    const names = [
+        ...Object.keys(rootPkg.dependencies ?? {}),
+        ...Object.keys(rootPkg.devDependencies ?? {}),
+        ...Object.keys(fnPkg?.dependencies ?? {}),
+        ...Object.keys(fnPkg?.devDependencies ?? {}),
+    ];
+    return names.some((name) => RUNTIME_ADAPTER_PACKAGES.has(name));
+}
+function bootstrapLintSeverity(pikkuConfig) {
+    const lint = pikkuConfig?.lint;
+    const configured = lint?.customServerBootstrap;
+    return configured === 'off' || configured === 'error' || configured === 'warn'
+        ? configured
+        : 'warn';
+}
+/**
+ * Reports a root `start`/`dev` script that boots a server Pikku does not own.
+ *
+ * Services built in a hand-rolled entrypoint never reach the
+ * `pikkuServerLifecycle` hooks, so startup and shutdown work silently does not
+ * run. A project depending on a runtime adapter has opted into owning its own
+ * server, and a script that delegates to another runner cannot be followed, so
+ * neither is reported.
+ */
+export async function runBootstrapChecks(root, rootPkg, pikkuConfig) {
+    if (!rootPkg)
+        return [];
+    const severity = bootstrapLintSeverity(pikkuConfig);
+    if (severity === 'off')
+        return [];
+    if (await hasRuntimeAdapter(root, rootPkg))
+        return [];
+    const customScripts = ['start', 'dev'].filter((name) => {
+        const script = rootPkg.scripts?.[name];
+        if (!script)
+            return false;
+        return !PIKKU_SERVER_SCRIPT.test(script) && !DELEGATING_SCRIPT.test(script);
+    });
+    if (customScripts.length === 0)
+        return [];
+    const named = customScripts.map((n) => `"${n}"`).join(', ');
+    return [
+        {
+            id: 'custom-server-bootstrap',
+            severity,
+            message: `package.json ${named} ${customScripts.length > 1 ? 'scripts start a server' : 'script starts a server'} without \`pikku dev\` or \`pikku serve\`, and no Pikku runtime adapter is installed — services created in a hand-rolled entrypoint bypass the server lifecycle hooks`,
+            path: join(root, 'package.json'),
+            fixHint: 'Start the server with `pikku serve` (or `pikku dev` locally) and move startup and shutdown work into a `pikkuServerLifecycle({ beforeStart, afterStart, beforeStop, afterStop })` export, which receives the already-created singleton services. To keep a custom entrypoint, set "lint": { "customServerBootstrap": "off" } in pikku.config.json',
+        },
+    ];
+}

package/dist/src/functions/validate/persona-checks.d.ts

@@ -0,0 +1,24 @@
+export type ValidateSeverity = 'error' | 'warn' | 'info';
+export type ValidateFinding = {
+    id: string;
+    severity: ValidateSeverity;
+    message: string;
+    path: string;
+    fixHint: string;
+};
+export type PersonaCheckConfig = {
+    srcDirectories?: unknown;
+    outDir?: unknown;
+    personasMetaJsonFile?: unknown;
+    environments?: unknown;
+};
+/**
+ * The people this project can run as, and whether it can run as them.
+ *
+ * Shared by `pikku workspace validate` and `pikku fabric validate` — the two
+ * validators are separate implementations, and a check that only one of them
+ * makes is a check half the projects never see.
+ *
+ * knowledge: decisions/internals/validate-checks-personas-through-a-shared-module.md
+ */
+export declare const runPersonaChecks: (root: string, config: PersonaCheckConfig | null) => Promise<ValidateFinding[]>;