@pikku/cli 0.12.25 → 0.12.27

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

@@ -14,7 +14,7 @@ import { pikkuWebsocketHandler } from '@pikku/ws';
 import { PikkuNodeHTTPServer } from '@pikku/node-http-server';
 import { WebSocketServer } from 'ws';
 import { InMemorySchedulerService } from '@pikku/schedule';
-import { resolveLocalDb, createKysely } from '../db/local-db.js';
+import { resolveDb, createKysely } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 export const dev = pikkuSessionlessFunc({
     remote: true,
@@ -116,19 +116,25 @@ export const dev = pikkuSessionlessFunc({
         const userCreateConfig = configModule[pikkuConfigFactory.variable];
         const userCreateSingletonServices = servicesModule[singletonServicesFactory.variable];
         const userConfig = await userCreateConfig();
-        const resolvedLocalDb = resolveLocalDb(userConfig.dev?.db ?? true, config.rootDir, config.outDir, config.runtimeDir);
+        const resolvedDb = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+        const resolvedLocalDb = resolvedDb?.dialect === 'sqlite'
+            ? resolvedDb
+            : userConfig.sqliteDb
+                ? resolveDb({ sqliteDb: userConfig.sqliteDb }, config.rootDir, config.outDir, config.runtimeDir)
+                : undefined;
         const kysely = resolvedLocalDb
             ? await createKysely(resolvedLocalDb)
             : undefined;
         const resolvedRuntimeDir = config.runtimeDir ?? join(config.rootDir, '.pikku-runtime');
-        const localContentConfig = userConfig.dev
-            ?.content
+        const localContentConfig = userConfig.content
             ? {
-                localFileUploadPath: join(resolvedRuntimeDir, 'content'),
-                uploadUrlPrefix: '/upload',
-                assetUrlPrefix: '/assets',
+                localFileUploadPath: userConfig.content.contentPath
+                    ? resolve(config.rootDir, userConfig.content.contentPath)
+                    : join(resolvedRuntimeDir, 'content'),
+                uploadUrlPrefix: userConfig.content.uploadUrlPrefix ?? '/upload',
+                assetUrlPrefix: userConfig.content.assetUrlPrefix ?? '/assets',
                 server: `http://${hostname}:${resolvedPort}`,
-                ...(userConfig.dev.content !== true ? userConfig.dev.content : {}),
+                sizeLimit: userConfig.content.sizeLimit,
             }
             : undefined;
         const localContent = localContentConfig

package/dist/src/functions/commands/new-addon.js

@@ -219,7 +219,7 @@ export const createSingletonServices = pikkuAddonServices(async (
   config,
   { secrets, variables }
 ) => {
-  const creds = await secrets.getSecretJSON<${pascalName}Secrets>('${screamingName}_CREDENTIALS')
+  const creds = await secrets.getSecret<${pascalName}Secrets>('${screamingName}_CREDENTIALS')
   const ${camelName} = new ${pascalName}Service(creds, variables)
 
   return { ${camelName} }
@@ -717,7 +717,7 @@ import { createSingletonServices } from './services.js'
 test('${name} addon', async () => {
   const secrets = new LocalSecretService()
   // Set up secrets for the service
-  // await secrets.setSecretJSON('${screamingName}_CREDENTIALS', { ... })
+  // await secrets.setSecret('${screamingName}_CREDENTIALS', { ... })
 
   const singletonServices = await createSingletonServices({}, { secrets })
   const rpc = rpcService.getContextRPCService(singletonServices as any, {})

package/dist/src/functions/commands/tests-coverage.d.ts

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

package/dist/src/functions/commands/tests-coverage.js

@@ -92,6 +92,7 @@ function lineCoverage(fileCov, span) {
 export const pikkuTestsCoverage = pikkuSessionlessFunc({
     func: async ({ logger, config }, input) => {
         const noRun = input?.noRun ?? false;
+        const aiOut = input?.aiOut ?? null;
         const packageMappings = config.packageMappings ?? {};
         const srcDirs = config.srcDirectories ?? [];
         const functionsRelDir = Object.keys(packageMappings).find((key) => srcDirs.some((src) => src === key || src.startsWith(key + '/'))) ?? Object.keys(packageMappings)[0];
@@ -227,5 +228,38 @@ export const pikkuTestsCoverage = pikkuSessionlessFunc({
         console.log(`  ${summary.covered} covered · ${summary.partial} partial · ${summary.uncovered} uncovered · ${summary.unknown} unknown (overall ${(overallRatio * 100).toFixed(1)}%)`);
         if (uncovered.length)
             console.log(`  uncovered: ${uncovered.map((f) => f.name).join(', ')}`);
+        if (aiOut !== null) {
+            const generatedAt = new Date().toISOString();
+            const pct = Math.round(overallRatio * 100);
+            const needWork = functions.filter((f) => f.status !== 'covered');
+            const lines = [
+                `Coverage report — generated ${generatedAt}.`,
+                `Overall: ${pct}% (${summary.covered}/${summary.total} functions fully covered)`,
+                '',
+                needWork.length === 0
+                    ? 'All functions are fully covered — nothing to do!'
+                    : `Functions needing coverage (${needWork.length}):`,
+                ...needWork.flatMap((fn) => {
+                    const ratio = Math.round(fn.ratio * 100);
+                    const missed = fn.missedLines.length > 0 ? fn.missedLines.join(', ') : 'none';
+                    return [
+                        `- ${fn.name} [${fn.status}, ${ratio}% covered, ${fn.coveredLines}/${fn.totalLines} lines]`,
+                        `  file: ${fn.sourceFile}`,
+                        `  missed lines: ${missed}`,
+                    ];
+                }),
+            ];
+            if (needWork.length > 0) {
+                lines.push('', 'Write @pikku/cucumber Gherkin scenarios (no custom steps) in tests/tests/features/ to cover the missed lines above.', 'Use pikku meta to get versioned RPC names and function schemas before writing.', 'Run pikku tests coverage after writing to verify coverage improved.');
+            }
+            const prompt = lines.join('\n') + '\n';
+            if (aiOut === '-') {
+                process.stdout.write(prompt);
+            }
+            else {
+                writeFileSync(aiOut, prompt, 'utf-8');
+                console.log(`AI prompt → ${relative(config.rootDir, aiOut)}`);
+            }
+        }
     },
 });

package/dist/src/functions/db/annotation-parser.d.ts

@@ -0,0 +1,31 @@
+import type { ColumnKind } from './coercion-plugin.js';
+type Classification = 'public' | 'private' | 'secret';
+type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null;
+export interface ColAnnotation {
+    kind?: ColumnKind;
+    /** TypeScript type string for @json columns, e.g. `string[]`. */
+    tsType?: string;
+    classification?: Classification;
+    anonymize?: AnonymizeStrategy;
+}
+/** Per-table, per-column annotation map built from migration SQL comments. */
+export type AnnotationMap = Record<string, Record<string, ColAnnotation>>;
+/**
+ * Determine column kind from naming conventions:
+ *   *_at / *_on            → date
+ *   is_* / has_* / can_*   → bool
+ */
+export declare function annotationFromName(colName: string): {
+    kind: ColumnKind;
+} | null;
+/**
+ * Parse `-- @bool | @date | @json [TsType] | @public | @private[:strategy] | @secret[:strategy]`
+ * inline annotations from migration SQL files in `migrationsDir`.
+ *
+ * Multiple annotations on the same comment line are supported, e.g.:
+ *   `deleted_at TIMESTAMP -- @date @private:keep`
+ *
+ * Covers both CREATE TABLE body lines and ALTER TABLE ... ADD [COLUMN] statements.
+ */
+export declare function parseAnnotations(migrationsDir: string): AnnotationMap;
+export {};

package/dist/src/functions/db/annotation-parser.js

@@ -0,0 +1,93 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Determine column kind from naming conventions:
+ *   *_at / *_on            → date
+ *   is_* / has_* / can_*   → bool
+ */
+export function annotationFromName(colName) {
+    if (/_at$|_on$/.test(colName))
+        return { kind: 'date' };
+    if (/^is_|^has_|^can_/.test(colName))
+        return { kind: 'bool' };
+    return null;
+}
+function parseStrategy(s) {
+    if (!s)
+        return null;
+    const valid = ['fake:email', 'fake:name', 'hash', 'keep'];
+    return valid.includes(s) ? s : null;
+}
+function parseComment(comment) {
+    const ann = {};
+    if (/@bool\b/i.test(comment)) {
+        ann.kind = 'bool';
+    }
+    else if (/@date\b/i.test(comment)) {
+        ann.kind = 'date';
+    }
+    else {
+        const jsonM = comment.match(/@json\b(?:\s+([^\s@]+))?/i);
+        if (jsonM) {
+            ann.kind = 'json';
+            if (jsonM[1])
+                ann.tsType = jsonM[1].trim();
+        }
+    }
+    const classM = comment.match(/@(public|private|secret)(?::([^\s@]+))?/i);
+    if (classM) {
+        ann.classification = classM[1].toLowerCase();
+        ann.anonymize = parseStrategy(classM[2]);
+    }
+    return ann;
+}
+/**
+ * Parse `-- @bool | @date | @json [TsType] | @public | @private[:strategy] | @secret[:strategy]`
+ * inline annotations from migration SQL files in `migrationsDir`.
+ *
+ * Multiple annotations on the same comment line are supported, e.g.:
+ *   `deleted_at TIMESTAMP -- @date @private:keep`
+ *
+ * Covers both CREATE TABLE body lines and ALTER TABLE ... ADD [COLUMN] statements.
+ */
+export function parseAnnotations(migrationsDir) {
+    let files;
+    try {
+        files = readdirSync(migrationsDir).filter((f) => f.endsWith('.sql')).sort();
+    }
+    catch {
+        return {};
+    }
+    const result = {};
+    function merge(tableName, colName, partial) {
+        if (!partial.kind && partial.classification === undefined)
+            return;
+        if (!result[tableName])
+            result[tableName] = {};
+        result[tableName][colName] = { ...result[tableName][colName], ...partial };
+    }
+    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;
+                const lineMatch = trimmed.match(/^(\w+)\s+\w[^-]*--\s*(.+?)\s*,?\s*$/);
+                if (!lineMatch)
+                    continue;
+                merge(tableName, lineMatch[1].toLowerCase(), parseComment(lineMatch[2]));
+            }
+        }
+        const alterPattern = /ALTER\s+TABLE\s+"?(\w+)"?\s+ADD\s+(?:COLUMN\s+)?"?(\w+)"?\s+\w[^;\n-]*(?:;\s*)?--\s*(.+?)(?:\r?\n|$)/gim;
+        let alterMatch;
+        while ((alterMatch = alterPattern.exec(content)) !== null) {
+            merge(alterMatch[1].toLowerCase(), alterMatch[2].toLowerCase(), parseComment(alterMatch[3]));
+        }
+    }
+    return result;
+}

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