@pikku/cli 0.12.20 → 0.12.22

package/dist/src/functions/commands/versions-update.js

@@ -13,9 +13,11 @@ export const pikkuVersionsUpdate = pikkuSessionlessFunc({
         const immutabilityErrors = visitState.manifest.errors.filter((e) => e.code === ErrorCode.FUNCTION_VERSION_MODIFIED);
         if (immutabilityErrors.length > 0) {
             for (const e of immutabilityErrors) {
-                logger.warn(`[${e.code}] ${e.message}`);
+                logger.critical(ErrorCode.FUNCTION_VERSION_MODIFIED, e.message);
+            }
+            if (logger.hasCriticalErrors()) {
+                process.exit(1);
             }
-            logger.warn(`Contract drift detected — version manifest not updated. Run 'pikku versions check' to inspect, or bump versions via code and re-run.`);
             return;
         }
         await saveManifest(manifestPath, visitState.manifest.current);

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 {};