@pikku/cli 0.12.21 → 0.12.22

package/dist/src/functions/commands/watch.d.ts

@@ -1,7 +1,7 @@
 export declare const watch: import("#pikku").PikkuFunctionConfig<{
     hmr?: boolean;
-}, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<{
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
     hmr?: boolean;
-}, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<{
+}, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<{
     hmr?: boolean;
-}, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+}, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -43,7 +43,7 @@ export const watch = pikkuSessionlessFunc({
                     if (timeout) {
                         clearTimeout(timeout);
                     }
-                    timeout = setTimeout(handle, 10);
+                    timeout = setTimeout(handle, 1000);
                 };
                 watcher.on('change', deduped);
                 watcher.on('add', deduped);

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

@@ -0,0 +1,48 @@
+import type { Kysely } from 'kysely';
+import { type MigrateResult } from './sql-migrator.js';
+import { type CodegenResult } from './sqlite-codegen.js';
+import { type ZodCodegenResult } from './zod-codegen.js';
+import { type SeedResult } from './seed.js';
+export type DevDbConfig = true | {
+    file?: string;
+};
+export interface ResolvedLocalDb {
+    dbFile: string;
+    runtimeDir: string;
+    migrationsDir: string;
+    seedFile: string;
+    schemaFile: string;
+    coercionFile: string;
+    zodFile: string;
+    camelCase: boolean;
+}
+/**
+ * Resolve a DevDbConfig into absolute paths.
+ * - dbFile lives under runtimeDir (default: <rootDir>/.pikku-runtime)
+ * - schema/coercion/zod are generated into outDir/db
+ * - migrations and seed are authored source under rootDir/db
+ */
+export declare function resolveLocalDb(config: DevDbConfig | undefined, rootDir: string, outDir: string, runtimeDir?: string): ResolvedLocalDb | null;
+export interface MigrateAndCodegenOutcome {
+    migrate: MigrateResult;
+    codegen: CodegenResult;
+    zod: ZodCodegenResult;
+}
+/**
+ * Run the migrate routine (open → tracking-table → drift-check → apply →
+ * codegen → close). Used by both `pikku db migrate` and `pikku dev` boot.
+ */
+export declare function migrateAndCodegen(resolved: ResolvedLocalDb): MigrateAndCodegenOutcome;
+export declare function seed(resolved: ResolvedLocalDb): SeedResult;
+/**
+ * Delete the dev DB file. Refuses if NODE_ENV is 'production' or the
+ * resolved file lives outside the project root (defensive against
+ * misconfigured absolute paths).
+ */
+export declare function reset(resolved: ResolvedLocalDb, rootDir: string): void;
+/**
+ * Construct the user-facing Kysely instance for the dev DB. Used by
+ * `pikku dev` to populate inMemoryServices.kysely.
+ * Wires the coercion plugin when db/coercion.gen.ts exists.
+ */
+export declare function createKysely<DB>(resolved: ResolvedLocalDb): Promise<Kysely<DB>>;

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

@@ -0,0 +1,106 @@
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { resolve, isAbsolute, relative, dirname, join } from 'node:path';
+import { createNodeSqliteKysely, createCoercionPlugin, } from '@pikku/kysely-node-sqlite';
+import { migrate } from './sql-migrator.js';
+import { generateSchemaTypes } from './sqlite-codegen.js';
+import { generateZodTypes } from './zod-codegen.js';
+import { seed as runSeed } from './seed.js';
+/**
+ * Resolve a DevDbConfig into absolute paths.
+ * - dbFile lives under runtimeDir (default: <rootDir>/.pikku-runtime)
+ * - schema/coercion/zod are generated into outDir/db
+ * - migrations and seed are authored source under rootDir/db
+ */
+export function resolveLocalDb(config, rootDir, outDir, runtimeDir) {
+    if (!config)
+        return null;
+    const file = config === true ? undefined : config.file;
+    const resolvedRuntimeDir = runtimeDir ?? join(rootDir, '.pikku-runtime');
+    return {
+        dbFile: file
+            ? resolveAgainst(rootDir, file)
+            : join(resolvedRuntimeDir, 'dev.db'),
+        runtimeDir: resolvedRuntimeDir,
+        migrationsDir: resolveAgainst(rootDir, 'db/migrations'),
+        seedFile: resolveAgainst(rootDir, 'db/seed.sql'),
+        schemaFile: join(outDir, 'db', 'schema.d.ts'),
+        coercionFile: join(outDir, 'db', 'coercion.gen.ts'),
+        zodFile: join(outDir, 'db', 'zod.gen.ts'),
+        camelCase: true,
+    };
+}
+function resolveAgainst(root, p) {
+    return isAbsolute(p) ? p : resolve(root, p);
+}
+/**
+ * Run the migrate routine (open → tracking-table → drift-check → apply →
+ * codegen → close). Used by both `pikku db migrate` and `pikku dev` boot.
+ */
+export function migrateAndCodegen(resolved) {
+    mkdirSync(dirname(resolved.dbFile), { recursive: true });
+    const db = new DatabaseSync(resolved.dbFile);
+    try {
+        const migrateResult = migrate(db, resolved.migrationsDir);
+        const codegenResult = generateSchemaTypes(db, {
+            outFile: resolved.schemaFile,
+            coercionFile: resolved.coercionFile,
+            camelCase: resolved.camelCase,
+            migrationsDir: resolved.migrationsDir,
+        });
+        const zodResult = generateZodTypes({
+            schemaFile: resolved.schemaFile,
+            outFile: resolved.zodFile,
+        });
+        return { migrate: migrateResult, codegen: codegenResult, zod: zodResult };
+    }
+    finally {
+        db.close();
+    }
+}
+export function seed(resolved) {
+    const db = new DatabaseSync(resolved.dbFile);
+    try {
+        return runSeed(db, resolved.seedFile);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Delete the dev DB file. Refuses if NODE_ENV is 'production' or the
+ * resolved file lives outside the project root (defensive against
+ * misconfigured absolute paths).
+ */
+export function reset(resolved, rootDir) {
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error(`pikku db reset refused: NODE_ENV=production. This command only runs in dev.`);
+    }
+    const rel = relative(resolved.runtimeDir, resolved.dbFile);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`pikku db reset refused: resolved DB file (${resolved.dbFile}) is outside the runtime directory (${resolved.runtimeDir}). Override dev.db.file or set runtimeDir correctly.`);
+    }
+    if (existsSync(resolved.dbFile)) {
+        rmSync(resolved.dbFile);
+    }
+}
+/**
+ * Construct the user-facing Kysely instance for the dev DB. Used by
+ * `pikku dev` to populate inMemoryServices.kysely.
+ * Wires the coercion plugin when db/coercion.gen.ts exists.
+ */
+export async function createKysely(resolved) {
+    let coercionMap;
+    try {
+        const mod = await import(resolved.coercionFile);
+        coercionMap = mod.coercionMap;
+    }
+    catch {
+        // coercion.gen.ts not yet generated — run `pikku db migrate` first
+    }
+    return createNodeSqliteKysely({
+        filename: resolved.dbFile,
+        camelCase: resolved.camelCase,
+        plugins: coercionMap ? [createCoercionPlugin({ map: coercionMap })] : [],
+    });
+}

package/dist/src/functions/db/seed.d.ts

@@ -0,0 +1,11 @@
+import type { DatabaseSync } from 'node:sqlite';
+export interface SeedResult {
+    applied: boolean;
+    bytes: number;
+}
+/**
+ * Apply db/seed.sql to the open db. Idempotency is the user's responsibility
+ * (e.g. `INSERT OR IGNORE`, upserts). Returns `applied: false` if the file
+ * doesn't exist; throws on SQL errors.
+ */
+export declare function seed(db: DatabaseSync, seedFile: string): SeedResult;

package/dist/src/functions/db/seed.js

@@ -0,0 +1,22 @@
+import { existsSync, readFileSync } from 'node:fs';
+/**
+ * Apply db/seed.sql to the open db. Idempotency is the user's responsibility
+ * (e.g. `INSERT OR IGNORE`, upserts). Returns `applied: false` if the file
+ * doesn't exist; throws on SQL errors.
+ */
+export function seed(db, seedFile) {
+    if (!existsSync(seedFile)) {
+        return { applied: false, bytes: 0 };
+    }
+    const raw = readFileSync(seedFile);
+    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/sql-migrator.d.ts

@@ -0,0 +1,26 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare class MigrationDriftError extends Error {
+    readonly file: string;
+    readonly recordedHash: string;
+    readonly currentHash: string | null;
+    readonly appliedAt: string;
+    constructor(file: string, recordedHash: string, currentHash: string | null, appliedAt: string);
+}
+export interface MigrateResult {
+    applied: string[];
+    skipped: string[];
+}
+/**
+ * Apply pending migrations from <migrationsDir>/*.sql against the open db.
+ * Hashes raw bytes on apply; subsequent runs re-hash and bail with
+ * MigrationDriftError if any applied file has changed on disk.
+ *
+ * The same bytes that get hashed are the bytes passed to db.exec — no
+ * splitting, trimming, or normalization. See docs/dev-builtin-sqlite.md.
+ */
+export declare function migrate(db: DatabaseSync, migrationsDir: string): MigrateResult;
+/**
+ * Wipe the tracking table. Used by `pikku db reset` after the DB file is
+ * removed (calling this on its own does NOT drop user tables).
+ */
+export declare function dropTrackingTable(db: DatabaseSync): void;

package/dist/src/functions/db/sql-migrator.js

@@ -0,0 +1,104 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+const TRACKING_TABLE = 'sql_migrations';
+export class MigrationDriftError extends Error {
+    file;
+    recordedHash;
+    currentHash;
+    appliedAt;
+    constructor(file, recordedHash, currentHash, appliedAt) {
+        const onDisk = currentHash === null
+            ? 'file missing on disk'
+            : `sha256:${currentHash.slice(0, 8)}…`;
+        super(`[PKU-DB-DRIFT] db/migrations/${file}\n\n` +
+            `Migration content has changed since it was applied.\n` +
+            `  recorded:  sha256:${recordedHash.slice(0, 8)}…  applied ${appliedAt}\n` +
+            `  on disk:   ${onDisk}\n\n` +
+            `If this edit was intentional, run \`pikku db reset\` to rebuild the dev\n` +
+            `database from scratch. Production migrations are immutable.`);
+        this.file = file;
+        this.recordedHash = recordedHash;
+        this.currentHash = currentHash;
+        this.appliedAt = appliedAt;
+        this.name = 'MigrationDriftError';
+    }
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function ensureTrackingTable(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
+       name       TEXT PRIMARY KEY,
+       hash       TEXT NOT NULL,
+       applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+     )`);
+}
+function listMigrationFiles(migrationsDir) {
+    return readdirSync(migrationsDir)
+        .filter((f) => f.endsWith('.sql'))
+        .sort();
+}
+function readApplied(db) {
+    return db
+        .prepare(`SELECT name, hash, applied_at FROM ${TRACKING_TABLE} ORDER BY name`)
+        .all();
+}
+function checkDrift(applied, migrationsDir) {
+    for (const row of applied) {
+        let currentHash = null;
+        try {
+            currentHash = sha256(readFileSync(join(migrationsDir, row.name)));
+        }
+        catch {
+            currentHash = null;
+        }
+        if (currentHash !== row.hash) {
+            throw new MigrationDriftError(row.name, row.hash, currentHash, row.applied_at);
+        }
+    }
+}
+/**
+ * Apply pending migrations from <migrationsDir>/*.sql against the open db.
+ * Hashes raw bytes on apply; subsequent runs re-hash and bail with
+ * MigrationDriftError if any applied file has changed on disk.
+ *
+ * The same bytes that get hashed are the bytes passed to db.exec — no
+ * splitting, trimming, or normalization. See docs/dev-builtin-sqlite.md.
+ */
+export function migrate(db, migrationsDir) {
+    ensureTrackingTable(db);
+    const applied = readApplied(db);
+    checkDrift(applied, migrationsDir);
+    const appliedSet = new Set(applied.map((r) => r.name));
+    const files = listMigrationFiles(migrationsDir);
+    const result = { applied: [], skipped: [] };
+    const insertStmt = db.prepare(`INSERT INTO ${TRACKING_TABLE} (name, hash) VALUES (?, ?)`);
+    for (const name of files) {
+        if (appliedSet.has(name)) {
+            result.skipped.push(name);
+            continue;
+        }
+        const raw = readFileSync(join(migrationsDir, name));
+        const hash = sha256(raw);
+        db.exec('BEGIN');
+        try {
+            db.exec(raw.toString('utf8'));
+            insertStmt.run(name, hash);
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            throw err;
+        }
+        result.applied.push(name);
+    }
+    return result;
+}
+/**
+ * Wipe the tracking table. Used by `pikku db reset` after the DB file is
+ * removed (calling this on its own does NOT drop user tables).
+ */
+export function dropTrackingTable(db) {
+    db.exec(`DROP TABLE IF EXISTS ${TRACKING_TABLE}`);
+}

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

@@ -0,0 +1,45 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ColumnKind } from '@pikku/kysely-node-sqlite';
+/** Internal annotation: column kind plus an optional TS type string (for @json). */
+interface ColAnnotation {
+    kind: ColumnKind;
+    /** TypeScript type string, e.g. `string[]` or `Record<string, number>`. Only set for @json. */
+    tsType?: string;
+}
+/** Internal annotation map used during codegen. */
+type AnnotationMap = Record<string, Record<string, ColAnnotation>>;
+/**
+ * Parse `-- @bool | @date | @json [TypescriptType]` inline annotations from
+ * migration SQL files. The TypeScript type is optional and only meaningful for
+ * `@json` — it controls the generated TypeScript type (e.g. `string[]`,
+ * `Record<string, number>`).
+ *
+ * Returns an AnnotationMap: { table_name: { col_name: ColAnnotation } }.
+ */
+export declare function parseAnnotations(migrationsDir: string): AnnotationMap;
+export interface CodegenOptions {
+    outFile: string;
+    coercionFile: string;
+    camelCase?: boolean;
+    migrationsDir?: string;
+}
+export interface CodegenResult {
+    outFile: string;
+    coercionFile: string;
+    written: boolean;
+    coercionWritten: boolean;
+    tables: string[];
+}
+/**
+ * Introspect the open SQLite database and emit a Kysely DB type to outFile
+ * plus a CoercionMap to coercionFile.
+ *
+ * Columns are annotated via:
+ *   1. Naming conventions (_at/_on → date; is_/has_/can_ → bool)
+ *   2. Inline SQL comments: `col_name TYPE ... -- @bool|@date|@json [TsType]`
+ *      For @json, an optional TypeScript type string controls the generated type.
+ *
+ * Returns `written: false` if the on-disk file already matches.
+ */
+export declare function generateSchemaTypes(db: DatabaseSync, options: CodegenOptions): CodegenResult;
+export {};

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

@@ -0,0 +1,294 @@
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const SKIP_TABLES = new Set(['sqlite_sequence', 'sql_migrations']);
+function snakeToPascal(name) {
+    return name
+        .split('_')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join('');
+}
+function snakeToCamel(name) {
+    return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function mapType(sqlType) {
+    const upper = sqlType.toUpperCase();
+    if (upper.includes('INT'))
+        return 'number';
+    if (upper.includes('CHAR') ||
+        upper.includes('CLOB') ||
+        upper.includes('TEXT')) {
+        return 'string';
+    }
+    if (upper.includes('BLOB'))
+        return 'Buffer';
+    if (upper.includes('REAL') ||
+        upper.includes('FLOA') ||
+        upper.includes('DOUB')) {
+        return 'number';
+    }
+    if (upper.includes('NUMERIC') || upper.includes('DECIMAL'))
+        return 'number';
+    if (upper.includes('BOOL'))
+        return 'number';
+    return 'string';
+}
+function listTables(db) {
+    const tableRows = db
+        .prepare(`SELECT name FROM sqlite_master
+         WHERE type = 'table'
+           AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\'
+         ORDER BY name`)
+        .all();
+    return tableRows
+        .filter((t) => !SKIP_TABLES.has(t.name))
+        .map((t) => {
+        const allColumns = db
+            .prepare(`PRAGMA table_xinfo(${escapeIdentifier(t.name)})`)
+            .all();
+        // hidden: 0=regular, 2=virtual generated, 3=stored generated — include all; skip 1 (vtab hidden)
+        const columns = allColumns.filter((c) => c.hidden !== 1);
+        return { name: t.name, columns };
+    });
+}
+function escapeIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+// ─── Annotation parsing ──────────────────────────────────────────────────────
+/**
+ * Determine column kind from naming conventions:
+ *   *_at / *_on            → date
+ *   is_* / has_* / can_*   → bool
+ */
+function annotationFromName(colName) {
+    if (/_at$|_on$/.test(colName))
+        return { kind: 'date' };
+    if (/^is_|^has_|^can_/.test(colName))
+        return { kind: 'bool' };
+    return null;
+}
+/**
+ * Parse `-- @bool | @date | @json [TypescriptType]` inline annotations from
+ * migration SQL files. The TypeScript type is optional and only meaningful for
+ * `@json` — it controls the generated TypeScript type (e.g. `string[]`,
+ * `Record<string, number>`).
+ *
+ * Returns an AnnotationMap: { table_name: { col_name: ColAnnotation } }.
+ */
+export function parseAnnotations(migrationsDir) {
+    let files;
+    try {
+        files = readdirSync(migrationsDir)
+            .filter((f) => f.endsWith('.sql'))
+            .sort();
+    }
+    catch {
+        return {};
+    }
+    const result = {};
+    for (const file of files) {
+        const content = readFileSync(join(migrationsDir, file), 'utf8');
+        const createTablePattern = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(\w+)"?\s*\(([^;]+)\)/gis;
+        let tableMatch;
+        while ((tableMatch = createTablePattern.exec(content)) !== null) {
+            const tableName = tableMatch[1].toLowerCase();
+            const body = tableMatch[2];
+            for (const line of body.split('\n')) {
+                const trimmed = line.trim();
+                if (/^(PRIMARY|UNIQUE|CHECK|FOREIGN|CONSTRAINT)/i.test(trimmed))
+                    continue;
+                // Match: col_name TYPE ... -- @kind [optional ts type]
+                const annotationMatch = trimmed.match(/^(\w+)\s+\w.*?--\s*@(bool|date|json)(?:\s+(.+?))?$/i);
+                if (annotationMatch) {
+                    const colName = annotationMatch[1].toLowerCase();
+                    const kind = annotationMatch[2].toLowerCase();
+                    const tsType = annotationMatch[3]?.trim() || undefined;
+                    if (!result[tableName])
+                        result[tableName] = {};
+                    result[tableName][colName] = {
+                        kind,
+                        tsType: kind === 'json' ? tsType : undefined,
+                    };
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Merge explicit SQL annotations with naming-convention-based ones.
+ * Explicit annotations take precedence.
+ */
+function buildAnnotationMap(tables, explicit) {
+    const merged = {};
+    for (const table of tables) {
+        const explicitCols = explicit[table.name] ?? {};
+        for (const col of table.columns) {
+            const annotation = explicitCols[col.name] ?? annotationFromName(col.name);
+            if (annotation) {
+                if (!merged[table.name])
+                    merged[table.name] = {};
+                merged[table.name][col.name] = annotation;
+            }
+        }
+    }
+    return merged;
+}
+// ─── Type expression ─────────────────────────────────────────────────────────
+function columnTypeExpression(col, annotation) {
+    const nullable = !col.notnull && col.pk === 0;
+    const hasDefault = col.dflt_value !== null && col.dflt_value !== undefined;
+    const isAutoInt = col.pk === 1 && mapType(col.type) === 'number';
+    const isGenerated = col.hidden === 2 || col.hidden === 3;
+    const wrap = (inner) => hasDefault || isAutoInt || isGenerated ? `Generated<${inner}>` : inner;
+    if (annotation?.kind === 'bool') {
+        const base = nullable ? 'boolean | null' : 'boolean';
+        const rw = nullable ? 'boolean | number | null' : 'boolean | number';
+        return wrap(`ColumnType<${base}, ${rw}, ${rw}>`);
+    }
+    if (annotation?.kind === 'date') {
+        const base = nullable ? 'Date | null' : 'Date';
+        const rw = nullable ? 'Date | string | null' : 'Date | string';
+        return wrap(`ColumnType<${base}, ${rw}, ${rw}>`);
+    }
+    if (annotation?.kind === 'json') {
+        const base = annotation.tsType
+            ? nullable
+                ? `${annotation.tsType} | null`
+                : annotation.tsType
+            : nullable
+                ? 'unknown | null'
+                : 'unknown';
+        return wrap(base);
+    }
+    // Default: plain SQL-mapped type
+    const base = mapType(col.type);
+    if (isAutoInt)
+        return `Generated<${base}>`;
+    if (hasDefault || isGenerated)
+        return `Generated<${base}${nullable ? ' | null' : ''}>`;
+    return nullable ? `${base} | null` : base;
+}
+// ─── Interface emitter ───────────────────────────────────────────────────────
+function emitInterface(table, camelCase, annotations) {
+    const ifaceName = snakeToPascal(table.name);
+    const tableCols = annotations[table.name] ?? {};
+    const fields = table.columns
+        .map((col) => {
+        const fieldName = camelCase ? snakeToCamel(col.name) : col.name;
+        const annotation = tableCols[col.name] ?? null;
+        const type = columnTypeExpression(col, annotation);
+        const safeName = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(fieldName)
+            ? fieldName
+            : JSON.stringify(fieldName);
+        return `  ${safeName}: ${type}`;
+    })
+        .join('\n');
+    return `export interface ${ifaceName} {\n${fields}\n}`;
+}
+/**
+ * Introspect the open SQLite database and emit a Kysely DB type to outFile
+ * plus a CoercionMap to coercionFile.
+ *
+ * Columns are annotated via:
+ *   1. Naming conventions (_at/_on → date; is_/has_/can_ → bool)
+ *   2. Inline SQL comments: `col_name TYPE ... -- @bool|@date|@json [TsType]`
+ *      For @json, an optional TypeScript type string controls the generated type.
+ *
+ * Returns `written: false` if the on-disk file already matches.
+ */
+export function generateSchemaTypes(db, options) {
+    const camelCase = options.camelCase ?? true;
+    const tables = listTables(db);
+    const explicitAnnotations = options.migrationsDir
+        ? parseAnnotations(options.migrationsDir)
+        : {};
+    const annotations = buildAnnotationMap(tables, explicitAnnotations);
+    // ── schema.d.ts ──
+    const interfaces = tables
+        .map((t) => emitInterface(t, camelCase, annotations))
+        .join('\n\n');
+    const dbEntries = tables
+        .map((t) => {
+        const tableKey = camelCase ? snakeToCamel(t.name) : t.name;
+        const safe = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableKey)
+            ? tableKey
+            : JSON.stringify(tableKey);
+        return `  ${safe}: ${snakeToPascal(t.name)}`;
+    })
+        .join('\n');
+    const schemaBody = [
+        `// Generated by @pikku/cli — do not edit by hand.`,
+        `// Run \`pikku db migrate\` to refresh.`,
+        ``,
+        `import type { ColumnType } from 'kysely'`,
+        ``,
+        `export type Generated<T> = T extends ColumnType<infer S, infer I, infer U>`,
+        `  ? ColumnType<S, I | undefined, U>`,
+        `  : ColumnType<T, T | undefined, T>`,
+        ``,
+        interfaces,
+        ``,
+        `export interface DB {`,
+        dbEntries,
+        `}`,
+        ``,
+    ].join('\n');
+    // ── coercion.gen.ts (runtime map — only kind, not tsType) ──
+    const runtimeMap = {};
+    for (const [table, cols] of Object.entries(annotations)) {
+        for (const [col, ann] of Object.entries(cols)) {
+            if (!runtimeMap[table])
+                runtimeMap[table] = {};
+            runtimeMap[table][col] = ann.kind;
+        }
+    }
+    const coercionEntries = Object.entries(runtimeMap)
+        .map(([table, cols]) => {
+        const colEntries = Object.entries(cols)
+            .map(([col, kind]) => `    "${col}": "${kind}"`)
+            .join(',\n');
+        return `  "${table}": {\n${colEntries}\n  }`;
+    })
+        .join(',\n');
+    const coercionBody = [
+        `// Generated by @pikku/cli — do not edit by hand.`,
+        `// Run \`pikku db migrate\` to refresh.`,
+        ``,
+        `export const coercionMap = {`,
+        coercionEntries,
+        `} as const`,
+        ``,
+    ].join('\n');
+    // ── write files ──
+    let existingSchema = null;
+    let existingCoercion = null;
+    try {
+        existingSchema = readFileSync(options.outFile, 'utf8');
+    }
+    catch {
+        /* ok */
+    }
+    try {
+        existingCoercion = readFileSync(options.coercionFile, 'utf8');
+    }
+    catch {
+        /* ok */
+    }
+    const schemaChanged = existingSchema !== schemaBody;
+    const coercionChanged = existingCoercion !== coercionBody;
+    if (schemaChanged) {
+        mkdirSync(dirname(options.outFile), { recursive: true });
+        writeFileSync(options.outFile, schemaBody, 'utf8');
+    }
+    if (coercionChanged) {
+        mkdirSync(dirname(options.coercionFile), { recursive: true });
+        writeFileSync(options.coercionFile, coercionBody, 'utf8');
+    }
+    return {
+        outFile: options.outFile,
+        coercionFile: options.coercionFile,
+        written: schemaChanged,
+        coercionWritten: coercionChanged,
+        tables: tables.map((t) => t.name),
+    };
+}