@pikku/cli 0.12.24 → 0.12.26

package/dist/src/functions/db/coercion-plugin.js

@@ -0,0 +1,99 @@
+function fromDb(value, kind) {
+    if (value == null)
+        return value;
+    switch (kind) {
+        case 'date':
+            if (typeof value === 'string') {
+                const d = new Date(value);
+                return Number.isNaN(d.getTime()) ? value : d;
+            }
+            return value;
+        case 'bool':
+            if (typeof value === 'number')
+                return value !== 0;
+            if (typeof value === 'bigint')
+                return value !== 0n;
+            return value;
+        case 'json':
+            if (typeof value !== 'string')
+                return value;
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
+    }
+}
+function snakeToCamel(name) {
+    return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function buildGlobalMap(map) {
+    const out = {};
+    for (const [table, tbl] of Object.entries(map)) {
+        for (const [col, kind] of Object.entries(tbl)) {
+            out[`${table}.${col}`] = kind;
+            out[`${table}.${snakeToCamel(col)}`] = kind;
+            out[col] = kind;
+            out[snakeToCamel(col)] = kind;
+        }
+    }
+    return out;
+}
+function collectQueryTables(node, out) {
+    if (!node || typeof node !== 'object')
+        return;
+    const op = node;
+    if (op.kind === 'TableNode') {
+        const tableName = op.table?.identifier?.name;
+        if (typeof tableName === 'string' && tableName.length > 0)
+            out.add(tableName);
+    }
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                collectQueryTables(item, out);
+        }
+        else {
+            collectQueryTables(value, out);
+        }
+    }
+}
+function lookupKind(globalMap, tables, col) {
+    let matchedKind;
+    for (const table of tables) {
+        const kind = globalMap[`${table}.${col}`];
+        if (!kind)
+            continue;
+        if (matchedKind && matchedKind !== kind)
+            return globalMap[col];
+        matchedKind = kind;
+    }
+    return matchedKind ?? globalMap[col];
+}
+export function createCoercionPlugin(options) {
+    const globalMap = buildGlobalMap(options.map);
+    const queryTables = new WeakMap();
+    return {
+        transformQuery(args) {
+            const tables = new Set();
+            collectQueryTables(args.node, tables);
+            queryTables.set(args.queryId, [...tables]);
+            return args.node;
+        },
+        async transformResult(args) {
+            const tables = queryTables.get(args.queryId) ?? [];
+            const out = [];
+            for (const row of args.result.rows) {
+                const next = { ...row };
+                for (const [col, val] of Object.entries(row)) {
+                    const kind = lookupKind(globalMap, tables, col);
+                    if (kind)
+                        next[col] = fromDb(val, kind);
+                }
+                out.push(next);
+            }
+            return { ...args.result, rows: out };
+        },
+    };
+}

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

@@ -0,0 +1,24 @@
+import type { DbIntrospector } from './db-introspector.js';
+export interface CodegenOptions {
+    outFile: string;
+    coercionFile: string;
+    manifestFile?: string;
+    camelCase?: boolean;
+    migrationsDir?: string;
+}
+export interface CodegenResult {
+    outFile: string;
+    coercionFile: string;
+    manifestFile?: string;
+    written: boolean;
+    coercionWritten: boolean;
+    manifestWritten: boolean;
+    tables: string[];
+}
+/**
+ * Introspect `introspector` and emit:
+ *   - `schema.d.ts`            Kysely DB type with classification brands
+ *   - `coercion.gen.ts`        Runtime CoercionMap for date/bool/json coercion
+ *   - `classification.gen.ts`  Data-classification manifest (when manifestFile set)
+ */
+export declare function generateSchemaTypes(introspector: DbIntrospector, options: CodegenOptions): Promise<CodegenResult>;

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

@@ -0,0 +1,276 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseAnnotations, annotationFromName, } from './annotation-parser.js';
+// ─── Name helpers ─────────────────────────────────────────────────────────────
+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());
+}
+// ─── Type mapping ─────────────────────────────────────────────────────────────
+function mapType(sqlType) {
+    const upper = sqlType.toUpperCase();
+    if (upper.includes('INT'))
+        return 'number';
+    if (upper.includes('CHAR') ||
+        upper.includes('CLOB') ||
+        upper.includes('TEXT') ||
+        upper === 'UUID')
+        return 'string';
+    if (upper.includes('BLOB') || upper === 'BYTEA')
+        return 'Buffer';
+    if (upper.includes('REAL') || upper.includes('FLOA') || upper.includes('DOUB'))
+        return 'number';
+    if (upper.includes('NUMERIC') || upper.includes('DECIMAL'))
+        return 'number';
+    // Postgres BOOLEAN type → boolean; SQLite BOOL (stores as int) → number
+    if (upper === 'BOOLEAN')
+        return 'boolean';
+    if (upper.includes('BOOL'))
+        return 'number';
+    if (upper.includes('JSON'))
+        return 'unknown';
+    return 'string';
+}
+// ─── Type expression ─────────────────────────────────────────────────────────
+function selectBase(annotation, col) {
+    if (annotation?.kind === 'bool')
+        return 'boolean';
+    if (annotation?.kind === 'date')
+        return 'Date';
+    if (annotation?.kind === 'json')
+        return annotation.tsType ?? 'unknown';
+    return mapType(col.type);
+}
+function insertBase(annotation, col) {
+    if (annotation?.kind === 'bool')
+        return 'boolean | number';
+    if (annotation?.kind === 'date')
+        return 'Date | string';
+    if (annotation?.kind === 'json')
+        return annotation.tsType ?? 'unknown';
+    return mapType(col.type);
+}
+function columnTypeExpression(col, annotation, classification) {
+    const nullable = !col.notNull && !col.pk;
+    const isAutoInt = col.pk && mapType(col.type) === 'number';
+    const isOptionalInsert = col.defaultValue !== null || isAutoInt || Boolean(col.generated);
+    if (classification === 'public') {
+        const wrap = (inner) => isOptionalInsert ? `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);
+        }
+        const base = mapType(col.type);
+        if (isAutoInt)
+            return `Generated<${base}>`;
+        if (col.defaultValue !== null || col.generated)
+            return `Generated<${base}${nullable ? ' | null' : ''}>`;
+        return nullable ? `${base} | null` : base;
+    }
+    const B = classification === 'secret' ? 'Secret' : 'Private';
+    const sBase = selectBase(annotation, col);
+    const iBase = insertBase(annotation, col);
+    const selectT = nullable ? `${B}<${sBase}> | null` : `${B}<${sBase}>`;
+    const insertT = nullable
+        ? `${iBase} | null${isOptionalInsert ? ' | undefined' : ''}`
+        : `${iBase}${isOptionalInsert ? ' | undefined' : ''}`;
+    const updateT = nullable ? `${iBase} | null` : iBase;
+    return `ColumnType<${selectT}, ${insertT}, ${updateT}>`;
+}
+function emitInterface(table, camelCase, explicitAnnotations) {
+    const ifaceName = snakeToPascal(table.name);
+    const tableCols = explicitAnnotations[table.name] ?? {};
+    const fields = table.columns
+        .map((col) => {
+        const fieldName = camelCase ? snakeToCamel(col.name) : col.name;
+        const sqlAnn = tableCols[col.name] ?? null;
+        const kindAnn = sqlAnn?.kind
+            ? { kind: sqlAnn.kind, tsType: sqlAnn.tsType }
+            : annotationFromName(col.name);
+        const classification = sqlAnn?.classification ?? 'private';
+        const type = columnTypeExpression(col, kindAnn, classification);
+        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}`;
+}
+// ─── Manifest emitter ────────────────────────────────────────────────────────
+function emitManifest(tables, explicitAnnotations) {
+    const tableEntries = tables
+        .map((table) => {
+        const tableCols = explicitAnnotations[table.name] ?? {};
+        const colEntries = table.columns
+            .map((col) => {
+            const ann = tableCols[col.name];
+            const classification = ann?.classification ?? 'private';
+            const strategy = ann?.anonymize ?? null;
+            const strategyLiteral = strategy === null ? 'null' : `'${strategy}'`;
+            return (`      ${JSON.stringify(col.name)}: ` +
+                `{ classification: '${classification}', anonymize_strategy: ${strategyLiteral} }`);
+        })
+            .join(',\n');
+        return `    ${JSON.stringify(table.name)}: {\n${colEntries}\n    }`;
+    })
+        .join(',\n');
+    return [
+        `// Generated by @pikku/cli — do not edit by hand.`,
+        `// Run \`pikku db migrate\` to refresh.`,
+        ``,
+        `export const classificationManifest = {`,
+        `  version: 1 as const,`,
+        `  tables: {`,
+        tableEntries,
+        `  },`,
+        `} as const`,
+        ``,
+    ].join('\n');
+}
+/**
+ * Introspect `introspector` and emit:
+ *   - `schema.d.ts`            Kysely DB type with classification brands
+ *   - `coercion.gen.ts`        Runtime CoercionMap for date/bool/json coercion
+ *   - `classification.gen.ts`  Data-classification manifest (when manifestFile set)
+ */
+export async function generateSchemaTypes(introspector, options) {
+    const camelCase = options.camelCase ?? true;
+    const tableNames = await introspector.listTables();
+    const tables = await Promise.all(tableNames.map(async (name) => ({
+        name,
+        columns: await introspector.getColumns(name),
+    })));
+    const explicitAnnotations = options.migrationsDir
+        ? parseAnnotations(options.migrationsDir)
+        : {};
+    // ── schema.d.ts ─────────────────────────────────────────────────────────────
+    const interfaces = tables
+        .map((t) => emitInterface(t, camelCase, explicitAnnotations))
+        .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>`,
+        ``,
+        `export type Private<T> = T & { readonly __pii__: 'private' }`,
+        `export type Secret<T> = T & { readonly __pii__: 'secret' }`,
+        ``,
+        interfaces,
+        ``,
+        `export interface DB {`,
+        dbEntries,
+        `}`,
+        ``,
+    ].join('\n');
+    // ── coercion.gen.ts ──────────────────────────────────────────────────────────
+    const coercionMap = {};
+    for (const table of tables) {
+        const tableCols = explicitAnnotations[table.name] ?? {};
+        for (const col of table.columns) {
+            const sqlAnn = tableCols[col.name];
+            const kind = sqlAnn?.kind ?? annotationFromName(col.name)?.kind;
+            if (kind) {
+                if (!coercionMap[table.name])
+                    coercionMap[table.name] = {};
+                coercionMap[table.name][col.name] = kind;
+            }
+        }
+    }
+    const coercionEntries = Object.entries(coercionMap)
+        .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');
+    // ── classification.gen.ts ───────────────────────────────────────────────────
+    const manifestBody = options.manifestFile ? emitManifest(tables, explicitAnnotations) : null;
+    // ── write files ───────────────────────────────────────────────────────────────
+    let existingSchema = null;
+    let existingCoercion = null;
+    let existingManifest = null;
+    try {
+        existingSchema = readFileSync(options.outFile, 'utf8');
+    }
+    catch { /* ok */ }
+    try {
+        existingCoercion = readFileSync(options.coercionFile, 'utf8');
+    }
+    catch { /* ok */ }
+    if (options.manifestFile) {
+        try {
+            existingManifest = readFileSync(options.manifestFile, 'utf8');
+        }
+        catch { /* ok */ }
+    }
+    const schemaChanged = existingSchema !== schemaBody;
+    const coercionChanged = existingCoercion !== coercionBody;
+    const manifestChanged = manifestBody !== null && existingManifest !== manifestBody;
+    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');
+    }
+    if (manifestChanged && options.manifestFile && manifestBody) {
+        mkdirSync(dirname(options.manifestFile), { recursive: true });
+        writeFileSync(options.manifestFile, manifestBody, 'utf8');
+    }
+    return {
+        outFile: options.outFile,
+        coercionFile: options.coercionFile,
+        manifestFile: options.manifestFile,
+        written: schemaChanged,
+        coercionWritten: coercionChanged,
+        manifestWritten: manifestChanged,
+        tables: tables.map((t) => t.name),
+    };
+}

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

@@ -0,0 +1,15 @@
+export interface ColumnInfo {
+    name: string;
+    /** Raw SQL/DB type string, e.g. 'INTEGER', 'TEXT', 'boolean', 'timestamp without time zone' */
+    type: string;
+    notNull: boolean;
+    pk: boolean;
+    defaultValue: string | null;
+    /** True for virtual or stored generated columns — these are read-only and never inserted. */
+    generated?: boolean;
+}
+export interface DbIntrospector {
+    listTables(): Promise<string[]>;
+    getColumns(table: string): Promise<ColumnInfo[]>;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,32 @@
+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, migrationsDir: string);
+}
+export interface MigrateResult {
+    applied: string[];
+    skipped: string[];
+}
+export interface AppliedMigration {
+    name: string;
+    hash: string;
+    applied_at: string;
+}
+/**
+ * Provider-agnostic migration executor. Implement this for each DB dialect.
+ * Each method maps to a single DB operation; all file I/O and hashing lives
+ * in the shared `migrate()` function above.
+ */
+export interface MigrationExecutor {
+    ensureTrackingTable(): Promise<void>;
+    getApplied(): Promise<AppliedMigration[]>;
+    runMigration(sql: string, name: string, hash: string): Promise<void>;
+}
+/**
+ * Apply pending migrations from `migrationsDir/*.sql` using the supplied
+ * executor. Hashes raw file bytes on apply; subsequent runs re-hash and bail
+ * with `MigrationDriftError` if any applied file has changed on disk.
+ */
+export declare function migrate(executor: MigrationExecutor, migrationsDir: string): Promise<MigrateResult>;

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

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+export class MigrationDriftError extends Error {
+    file;
+    recordedHash;
+    currentHash;
+    appliedAt;
+    constructor(file, recordedHash, currentHash, appliedAt, migrationsDir) {
+        const onDisk = currentHash === null
+            ? 'file missing on disk'
+            : `sha256:${currentHash.slice(0, 8)}…`;
+        super(`[PKU-DB-DRIFT] ${migrationsDir}/${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, write a new forward migration to revert the change.\n` +
+            `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');
+}
+/**
+ * Apply pending migrations from `migrationsDir/*.sql` using the supplied
+ * executor. Hashes raw file bytes on apply; subsequent runs re-hash and bail
+ * with `MigrationDriftError` if any applied file has changed on disk.
+ */
+export async function migrate(executor, migrationsDir) {
+    await executor.ensureTrackingTable();
+    const applied = await executor.getApplied();
+    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, migrationsDir);
+        }
+    }
+    const appliedSet = new Set(applied.map((r) => r.name));
+    const files = readdirSync(migrationsDir)
+        .filter((f) => f.endsWith('.sql'))
+        .sort();
+    const result = { applied: [], skipped: [] };
+    for (const name of files) {
+        if (appliedSet.has(name)) {
+            result.skipped.push(name);
+            continue;
+        }
+        const raw = readFileSync(join(migrationsDir, name));
+        const hash = sha256(raw);
+        await executor.runMigration(raw.toString('utf8'), name, hash);
+        result.applied.push(name);
+    }
+    return result;
+}

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

@@ -1,48 +1,42 @@
 import type { Kysely } from 'kysely';
-import { type MigrateResult } from './sql-migrator.js';
-import { type CodegenResult } from './sqlite-codegen.js';
+import { type MigrateResult } from './db-migrator.js';
+import { type CodegenResult } from './db-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;
+import { type SeedResult } from './sqlite/seed.js';
+import type { UserConfigShape } from '../commands/db-shared.js';
+interface ResolvedDbBase {
     migrationsDir: string;
-    seedFile: string;
     schemaFile: string;
     coercionFile: string;
+    manifestFile: string;
     zodFile: string;
     camelCase: boolean;
 }
+export interface ResolvedSqliteDb extends ResolvedDbBase {
+    dialect: 'sqlite';
+    dbFile: string;
+    runtimeDir: string;
+    seedFile: string;
+}
+export interface ResolvedPostgresDb extends ResolvedDbBase {
+    dialect: 'postgres';
+    connectionString: string;
+}
+export type ResolvedDb = ResolvedSqliteDb | ResolvedPostgresDb;
 /**
- * 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
+ * Resolve a UserConfigShape into an absolute-path descriptor.
+ * Returns null when neither sqliteDb nor postgresUrl is configured.
  */
-export declare function resolveLocalDb(config: DevDbConfig | undefined, rootDir: string, outDir: string, runtimeDir?: string): ResolvedLocalDb | null;
+export declare function resolveDb(userConfig: UserConfigShape, rootDir: string, outDir: string, runtimeDir?: string): ResolvedDb | null;
+/** @deprecated Use resolveDb(userConfig, ...) instead. */
+export declare function resolveLocalDb(sqliteDb: string | undefined, rootDir: string, outDir: string, runtimeDir?: string): ResolvedSqliteDb | 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>>;
+export declare function migrateAndCodegen(resolved: ResolvedDb): Promise<MigrateAndCodegenOutcome>;
+export declare function seed(resolved: ResolvedSqliteDb): Promise<SeedResult>;
+export declare function reset(resolved: ResolvedSqliteDb, rootDir: string): void;
+export declare function createKysely<DB>(resolved: ResolvedSqliteDb): Promise<Kysely<DB>>;
+export {};