@pikku/cli 0.12.34 → 0.12.35

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

@@ -1,6 +1,26 @@
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { loadAnnotations, parseAnnotations, annotationFromName, } from './annotation-parser.js';
+import { loadAnnotations, nameSuggestsKind, } from './annotation-parser.js';
+import { ZOD_FORMATS } from './zod-codegen.js';
+/**
+ * The column kind implied by the *real* DB type, dialect-aware. Postgres has
+ * native temporal/boolean types so we can trust them; SQLite stores dates as
+ * TEXT and booleans as INTEGER, so its declared types are indeterminate and we
+ * derive nothing (return null). Used both to auto-type Postgres dates and to
+ * detect name↔type contradictions for warnings.
+ */
+function realKind(dialect, sqlType) {
+    if (dialect !== 'postgres')
+        return null;
+    const u = sqlType.toUpperCase();
+    if (u.includes('TIMESTAMP') || u === 'DATE')
+        return 'date';
+    if (u === 'BOOLEAN' || u === 'BOOL')
+        return 'bool';
+    if (u === 'UUID')
+        return 'uuid';
+    return null;
+}
 // ─── Name helpers ─────────────────────────────────────────────────────────────
 function snakeToPascal(name) {
     return name
@@ -11,6 +31,10 @@ function snakeToPascal(name) {
 function snakeToCamel(name) {
     return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
+/** Escape a value for embedding inside a single-quoted TS string literal. */
+function escapeTsString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
 // ─── Type mapping ─────────────────────────────────────────────────────────────
 function mapType(sqlType) {
     const upper = sqlType.toUpperCase();
@@ -40,21 +64,30 @@ function mapType(sqlType) {
 }
 // ─── Type expression ─────────────────────────────────────────────────────────
 function selectBase(annotation, col) {
+    // An explicit `tsType` is a general type override and wins over everything.
+    if (annotation?.tsType)
+        return annotation.tsType;
     if (annotation?.kind === 'bool')
         return 'boolean';
     if (annotation?.kind === 'date')
         return 'Date';
+    if (annotation?.kind === 'uuid')
+        return 'Uuid';
     if (annotation?.kind === 'json')
-        return annotation.tsType ?? 'unknown';
+        return 'unknown';
     return mapType(col.type);
 }
 function insertBase(annotation, col) {
+    if (annotation?.tsType)
+        return annotation.tsType;
     if (annotation?.kind === 'bool')
         return 'boolean | number';
     if (annotation?.kind === 'date')
         return 'Date | string';
+    if (annotation?.kind === 'uuid')
+        return 'Uuid';
     if (annotation?.kind === 'json')
-        return annotation.tsType ?? 'unknown';
+        return 'unknown';
     return mapType(col.type);
 }
 function columnTypeExpression(col, annotation, classification) {
@@ -73,14 +106,17 @@ function columnTypeExpression(col, annotation, classification) {
             const rw = nullable ? 'Date | string | null' : 'Date | string';
             return wrap(`ColumnType<${base}, ${rw}, ${rw}>`);
         }
+        if (annotation?.kind === 'uuid') {
+            return wrap(nullable ? 'Uuid | null' : 'Uuid');
+        }
+        if (annotation?.tsType) {
+            const base = nullable
+                ? `${annotation.tsType} | null`
+                : annotation.tsType;
+            return wrap(base);
+        }
         if (annotation?.kind === 'json') {
-            const base = annotation.tsType
-                ? nullable
-                    ? `${annotation.tsType} | null`
-                    : annotation.tsType
-                : nullable
-                    ? 'unknown | null'
-                    : 'unknown';
+            const base = nullable ? 'unknown | null' : 'unknown';
             return wrap(base);
         }
         const base = mapType(col.type);
@@ -109,18 +145,63 @@ function bareTableName(name) {
     const dot = name.indexOf('.');
     return dot >= 0 ? name.slice(dot + 1) : name;
 }
-function emitInterface(table, camelCase, explicitAnnotations) {
+function emitInterface(table, camelCase, explicitAnnotations, dialect, enumByName, formatHints, warnings) {
     const ifaceName = snakeToPascal(table.name);
-    const tableCols = explicitAnnotations[bareTableName(table.name)] ?? {};
+    const bare = bareTableName(table.name);
+    const tableCols = explicitAnnotations[bare] ?? {};
     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 ann = tableCols[col.name] ?? null;
+        // Effective typing kind: explicit annotation wins; otherwise, on Postgres
+        // the *real* column type tells us (a timestamp genuinely is a Date). On
+        // SQLite there is no native date storage (dates are TEXT), so nothing is
+        // derived — `string` unless explicitly `kind: 'date'`.
+        // On Postgres, real `timestamp`/`uuid` types carry through automatically
+        // (no annotation needed); SQLite has neither native type so derives nothing.
+        const real = realKind(dialect, col.type);
+        const derived = !ann?.tsType && (real === 'date' || real === 'uuid') ? real : undefined;
+        const typingKind = ann?.kind ?? derived;
+        // Warn (don't force) only on a genuine contradiction the real type can
+        // prove: a column NAMED like a date/bool whose actual type disagrees
+        // (e.g. `created_at` that is really a boolean in Postgres). On SQLite the
+        // type is indeterminate, so there is nothing to contradict — no warning.
+        if (!ann?.kind && !ann?.tsType) {
+            const suggested = nameSuggestsKind(col.name);
+            if (suggested && real && suggested !== real) {
+                warnings.push(`Column "${bare}.${col.name}" is named like a ${suggested} but its DB type ` +
+                    `is ${col.type} (${real}). If intentional, set its kind in db/annotations.ts.`);
+            }
+        }
+        // A Postgres enum column reports `type` as 'USER-DEFINED'; its real values
+        // come from `udtName`. Type it as a union of string literals — only when
+        // no explicit `tsType`/`kind` overrides it. This reuses the `tsType`
+        // plumbing, so it flows through both the public and classified branches.
+        const enumValues = col.udtName ? enumByName.get(col.udtName) : undefined;
+        const enumUnion = enumValues && enumValues.length > 0
+            ? enumValues.map((v) => `'${escapeTsString(v)}'`).join(' | ')
+            : null;
+        const effectiveTsType = ann?.tsType ?? (typingKind ? undefined : (enumUnion ?? undefined));
+        const typeAnn = typingKind || effectiveTsType
+            ? { kind: typingKind, tsType: effectiveTsType }
+            : null;
+        // A `format` validator refines the zod schema only and keeps the TS type
+        // as `string`. It therefore applies only when the resolved select base is
+        // plain `string`; on anything else (Date/Uuid/boolean/enum/unknown via
+        // kind/tsType) it would contradict the type, so warn and skip.
+        if (ann?.format) {
+            const base = selectBase(typeAnn, col);
+            if (base === 'string') {
+                ;
+                (formatHints[ifaceName] ??= {})[fieldName] = ann.format;
+            }
+            else {
+                warnings.push(`Column "${bare}.${col.name}": format '${ann.format}' ignored — its ` +
+                    `resolved type is ${base}, not string. Remove the conflicting kind/tsType.`);
+            }
+        }
+        const classification = ann?.classification ?? 'private';
+        const type = columnTypeExpression(col, typeAnn, classification);
         const safeName = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(fieldName)
             ? fieldName
             : JSON.stringify(fieldName);
@@ -168,7 +249,21 @@ function emitManifest(tables, explicitAnnotations) {
  * flag added or removed columns.
  */
 function emitClassificationMap(tables) {
-    const colEntry = `  security: 'public' | 'private' | 'pii' | 'secret' | 'encrypted'\n  classification?: 'fake:email' | 'fake:name' | 'hash' | 'keep'\n  description?: string`;
+    const colEntry = [
+        `  /** Privacy level. Defaults to 'private' when omitted. */`,
+        `  security?: 'public' | 'private' | 'pii' | 'secret' | 'encrypted'`,
+        `  /** Anonymize strategy used by \`pikku db anonymize\`. */`,
+        `  classification?: 'fake:email' | 'fake:name' | 'hash' | 'keep'`,
+        `  /** Column kind override for codegen coercion + typing. */`,
+        `  kind?: 'date' | 'bool' | 'json' | 'uuid'`,
+        `  /** TypeScript type override, e.g. \`string[]\` or \`MyJson\`. Wins over \`kind\`. */`,
+        `  tsType?: string`,
+        `  /** Zod string-format validator (keeps the TS type as \`string\`). */`,
+        `  format?: ${Object.keys(ZOD_FORMATS)
+            .map((f) => `'${f}'`)
+            .join(' | ')}`,
+        `  description?: string`,
+    ].join('\n');
     // Group tables by schema (for postgres schema.table names)
     const schemaMap = new Map();
     for (const table of tables) {
@@ -225,20 +320,32 @@ function emitClassificationMap(tables) {
  */
 export async function generateSchemaTypes(introspector, options) {
     const camelCase = options.camelCase ?? true;
+    const dialect = options.dialect ?? 'sqlite';
     const tableNames = await introspector.listTables();
     const tables = await Promise.all(tableNames.map(async (name) => ({
         name,
         columns: await introspector.getColumns(name),
     })));
     const explicitAnnotations = options.rootDir
-        ? loadAnnotations(options.rootDir, options.migrationsDir)
-        : options.migrationsDir
-            ? parseAnnotations(options.migrationsDir)
-            : {};
+        ? loadAnnotations(options.rootDir)
+        : {};
+    // Enum types — used to auto-type enum columns as string-literal unions. Keyed
+    // by both bare and schema-qualified name; `udtName` is bare so the bare key
+    // resolves it (a one-line changeset note flags the cross-schema-name caveat).
+    const enums = await introspector.listEnums();
+    const enumByName = new Map();
+    for (const e of enums) {
+        enumByName.set(e.name, e.values);
+        enumByName.set(`${e.schema}.${e.name}`, e.values);
+    }
     // ── schema.d.ts ─────────────────────────────────────────────────────────────
+    const warnings = [];
+    const zodFormats = {};
     const interfaces = tables
-        .map((t) => emitInterface(t, camelCase, explicitAnnotations))
+        .map((t) => emitInterface(t, camelCase, explicitAnnotations, dialect, enumByName, zodFormats, warnings))
         .join('\n\n');
+    for (const w of warnings)
+        console.warn(`[pikku db] ${w}`);
     const dbEntries = tables
         .map((t) => {
         const tableKey = camelCase ? snakeToCamel(t.name) : t.name;
@@ -265,6 +372,9 @@ export async function generateSchemaTypes(introspector, options) {
         `export type Private<T> = T & { readonly __classification__?: 'private' }`,
         `export type Pii<T> = T & { readonly __classification__?: 'pii' }`,
         `export type Secret<T> = T & { readonly __classification__?: 'secret' }`,
+        // Transparent alias (structurally a string, so plain strings stay
+        // interchangeable) — its name lets the zod codegen emit `z.uuid()`.
+        `export type Uuid = string`,
         ``,
         interfaces,
         ``,
@@ -278,9 +388,11 @@ export async function generateSchemaTypes(introspector, options) {
     for (const table of tables) {
         const tableCols = explicitAnnotations[bareTableName(table.name)] ?? {};
         for (const col of table.columns) {
-            const sqlAnn = tableCols[col.name];
-            const kind = sqlAnn?.kind ?? annotationFromName(col.name)?.kind;
-            if (kind) {
+            // Coercion is driven only by an explicit `kind` in db/annotations.ts —
+            // no name inference. An unannotated `*_at` column is not coerced. `uuid`
+            // is a string in both dialects, so it needs no runtime coercion.
+            const kind = tableCols[col.name]?.kind;
+            if (kind && kind !== 'uuid') {
                 if (!coercionMap[table.name])
                     coercionMap[table.name] = {};
                 coercionMap[table.name][col.name] = kind;
@@ -315,10 +427,7 @@ export async function generateSchemaTypes(introspector, options) {
     // ── pikku-db-schema.gen.json ─────────────────────────────────────────────────
     let schemaJsonBody = null;
     if (options.schemaJsonFile) {
-        const [fkResults, enums] = await Promise.all([
-            Promise.all(tableNames.map((name) => introspector.getForeignKeys(name))),
-            introspector.listEnums(),
-        ]);
+        const fkResults = await Promise.all(tableNames.map((name) => introspector.getForeignKeys(name)));
         const fkMap = new Map(tableNames.map((name, i) => [name, fkResults[i]]));
         const jsonTables = tables.map((t) => ({
             name: t.name,
@@ -423,5 +532,7 @@ export async function generateSchemaTypes(introspector, options) {
         manifestWritten: manifestChanged,
         classificationMapWritten: classificationMapChanged,
         tables: tables.map((t) => t.name),
+        warnings,
+        zodFormats,
     };
 }

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

@@ -7,6 +7,12 @@ export interface ColumnInfo {
     defaultValue: string | null;
     /** True for virtual or stored generated columns — these are read-only and never inserted. */
     generated?: boolean;
+    /**
+     * Underlying DB type name (Postgres `udt_name`). For an enum column `type` is
+     * the generic `'USER-DEFINED'`, while `udtName` holds the actual enum type
+     * name used to resolve its values. Undefined on SQLite (no native enums).
+     */
+    udtName?: string;
 }
 export interface ForeignKeyInfo {
     column: string;

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

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, } from 'node:fs';
 import { resolve, isAbsolute, relative, dirname, join } from 'node:path';
-import { execSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
+import { runInNewContext } from 'node:vm';
+import { transformSync } from 'esbuild';
 import { migrate } from './db-migrator.js';
 import { generateSchemaTypes } from './db-codegen.js';
 import { generateZodTypes } from './zod-codegen.js';
@@ -42,7 +42,11 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
         classificationMapFile: join(outDir, 'db', 'classification-map.gen.d.ts'),
         schemaJsonFile: join(outDir, 'db', 'pikku-db-schema.gen.json'),
         classificationsFile: join(rootDir, 'db', 'annotations.ts'),
-        classificationsGenJsonFile: join(outDir, 'db', 'annotations.gen.json'),
+        // Compiled sidecar lives beside the authored annotations.ts in db/ — this is
+        // where both consumers read it: the codegen's loadAnnotations() and the
+        // pikku-console addon (db/annotations.gen.json). Writing it into outDir
+        // (.pikku) would leave both readers looking at a file that never appears.
+        classificationsGenJsonFile: join(rootDir, 'db', 'annotations.gen.json'),
         zodFile: join(outDir, 'db', 'zod.gen.ts'),
         camelCase: true,
     });
@@ -87,6 +91,9 @@ function resolveAgainst(root, p) {
 export async function migrateAndCodegen(resolved) {
     let migrateResult;
     let codegenResult;
+    // Compile any authored db/annotations.ts → sidecar BEFORE codegen so edits
+    // reflect in a single `db migrate` (codegen reads the sidecar).
+    compileClassifications(resolved.classificationsFile, resolved.classificationsGenJsonFile);
     if (resolved.dialect === 'sqlite') {
         mkdirSync(dirname(resolved.dbFile), { recursive: true });
         const runtime = await loadSqliteRuntime();
@@ -103,7 +110,7 @@ export async function migrateAndCodegen(resolved) {
                 schemaJsonFile: resolved.schemaJsonFile,
                 camelCase: resolved.camelCase,
                 rootDir: resolved.rootDir,
-                migrationsDir: resolved.migrationsDir,
+                dialect: 'sqlite',
             });
         }
         finally {
@@ -129,7 +136,7 @@ export async function migrateAndCodegen(resolved) {
                     schemaJsonFile: resolved.schemaJsonFile,
                     camelCase: resolved.camelCase,
                     rootDir: resolved.rootDir,
-                    migrationsDir: resolved.migrationsDir,
+                    dialect: 'postgres',
                 });
             }
             finally {
@@ -143,9 +150,13 @@ export async function migrateAndCodegen(resolved) {
     const zodResult = generateZodTypes({
         schemaFile: resolved.schemaFile,
         outFile: resolved.zodFile,
+        formats: codegenResult.zodFormats,
     });
     // ── Classifications step ──────────────────────────────────────────────────
-    const { scaffolded, jsonWritten } = syncClassifications(resolved.classificationsFile, resolved.classificationsGenJsonFile, codegenResult.tables);
+    // Scaffold the authored file if missing (needs the table list), then compile
+    // it to the sidecar so a freshly-scaffolded file is captured too.
+    const scaffolded = scaffoldClassificationsFile(resolved.classificationsFile, codegenResult.tables);
+    const jsonWritten = compileClassifications(resolved.classificationsFile, resolved.classificationsGenJsonFile);
     return {
         migrate: migrateResult,
         codegen: codegenResult,
@@ -179,86 +190,93 @@ export function reset(resolved, rootDir) {
 }
 // ── Classification sync ───────────────────────────────────────────────────────
 /**
- * Loads `db/classifications.ts` via tsx, serialises it to
- * `.pikku/db/classifications.gen.json` for runtime consumption (console, etc.).
- *
- * If `db/classifications.ts` doesn't exist yet, writes a scaffold with every
- * table defaulting to `private` so the developer has a starting point.
+ * If `db/annotations.ts` doesn't exist yet, write a scaffold listing every
+ * table/column so the developer has a typed starting point. Every field of
+ * `ColumnEntry` is optional, so the empty-per-table scaffold is valid and means
+ * "everything default `private`". Returns whether a scaffold was written.
  */
-function syncClassifications(classificationsFile, genJsonFile, tableNames) {
-    let scaffolded = false;
-    if (!existsSync(classificationsFile)) {
-        const relMap = join(dirname(classificationsFile), '..', '.pikku', 'db', 'classification-map.gen.d.ts');
-        const relMapPosix = relMap.replace(/\\/g, '/');
-        const groups = new Map();
-        for (const name of tableNames) {
-            const dot = name.indexOf('.');
-            const schema = dot >= 0 ? name.slice(0, dot) : '';
-            const table = dot >= 0 ? name.slice(dot + 1) : name;
-            if (!groups.has(schema))
-                groups.set(schema, []);
-            groups.get(schema).push(table);
-        }
-        const bodyLines = [
-            `import type { DbClassificationMap } from '${relMapPosix}'`,
-            ``,
-            `export const classifications = {`,
-        ];
-        for (const [schema, tables] of groups) {
-            if (schema)
-                bodyLines.push(`  ${JSON.stringify(schema)}: {`);
-            for (const table of tables) {
-                bodyLines.push(schema
-                    ? `    ${JSON.stringify(table)}: {`
-                    : `  ${JSON.stringify(table)}: {`);
-                bodyLines.push(schema ? `    },` : `  },`);
-            }
-            if (schema)
-                bodyLines.push(`  },`);
+function scaffoldClassificationsFile(classificationsFile, tableNames) {
+    if (existsSync(classificationsFile))
+        return false;
+    const relMap = join(dirname(classificationsFile), '..', '.pikku', 'db', 'classification-map.gen.d.ts');
+    const relMapPosix = relMap.replace(/\\/g, '/');
+    const groups = new Map();
+    for (const name of tableNames) {
+        const dot = name.indexOf('.');
+        const schema = dot >= 0 ? name.slice(0, dot) : '';
+        const table = dot >= 0 ? name.slice(dot + 1) : name;
+        if (!groups.has(schema))
+            groups.set(schema, []);
+        groups.get(schema).push(table);
+    }
+    const bodyLines = [
+        `import type { DbClassificationMap } from '${relMapPosix}'`,
+        ``,
+        `export const classifications = {`,
+    ];
+    for (const [schema, tables] of groups) {
+        if (schema)
+            bodyLines.push(`  ${JSON.stringify(schema)}: {`);
+        for (const table of tables) {
+            bodyLines.push(schema
+                ? `    ${JSON.stringify(table)}: {`
+                : `  ${JSON.stringify(table)}: {`);
+            bodyLines.push(schema ? `    },` : `  },`);
         }
-        bodyLines.push(`} satisfies DbClassificationMap`, ``);
-        mkdirSync(dirname(classificationsFile), { recursive: true });
-        writeFileSync(classificationsFile, bodyLines.join('\n'), 'utf8');
-        scaffolded = true;
+        if (schema)
+            bodyLines.push(`  },`);
     }
-    // Resolve tsx from the CLI package's own node_modules so it works regardless
-    // of whether the user's project has tsx installed.
-    const _require = createRequire(fileURLToPath(import.meta.url));
-    let tsxEsmPath = null;
+    bodyLines.push(`} satisfies DbClassificationMap`, ``);
+    mkdirSync(dirname(classificationsFile), { recursive: true });
+    writeFileSync(classificationsFile, bodyLines.join('\n'), 'utf8');
+    return true;
+}
+/**
+ * Compile `db/annotations.ts` into the `annotations.gen.json` sidecar that the
+ * codegen and the pikku-console addon read. No-op if the authored file doesn't
+ * exist (nothing to compile yet). Returns whether the sidecar changed on disk.
+ *
+ * Uses esbuild (a CLI dependency) to transpile the TS in-process and a `vm`
+ * sandbox to evaluate it — no subprocess and no tsx. The previous `node --import
+ * tsx/esm` subprocess silently fails on Node ≥ 23 (ERR_REQUIRE_CYCLE_MODULE),
+ * which is why this sidecar never materialised before.
+ *
+ * Run BEFORE codegen so authored edits reflect in a single `db migrate` (and
+ * again after, to capture a freshly-scaffolded file).
+ */
+function compileClassifications(classificationsFile, genJsonFile) {
+    if (!existsSync(classificationsFile))
+        return false;
+    let value;
     try {
-        tsxEsmPath = _require.resolve('tsx/esm');
+        const src = readFileSync(classificationsFile, 'utf8');
+        const { code } = transformSync(src, {
+            loader: 'ts',
+            format: 'cjs',
+        });
+        const mod = { exports: {} };
+        runInNewContext(code, {
+            module: mod,
+            exports: mod.exports,
+            require: createRequire(classificationsFile),
+        });
+        value = Object.values(mod.exports)[0];
     }
     catch {
-        // tsx not bundled with this CLI install — skip JSON emit
+        return false; // syntax/transform error — skip JSON emit
     }
-    const script = [
-        `import * as mod from ${JSON.stringify(classificationsFile)}`,
-        `const val = Object.values(mod)[0]`,
-        `process.stdout.write(JSON.stringify(val))`,
-    ].join('\n');
-    let jsonWritten = false;
-    if (tsxEsmPath) {
-        try {
-            const json = execSync(`node --import ${JSON.stringify(tsxEsmPath)} --input-type=module`, {
-                input: script,
-                encoding: 'utf8',
-                stdio: ['pipe', 'pipe', 'pipe'],
-            });
-            const existing = existsSync(genJsonFile)
-                ? readFileSync(genJsonFile, 'utf8')
-                : null;
-            const next = JSON.stringify(JSON.parse(json), null, 2) + '\n';
-            if (existing !== next) {
-                mkdirSync(dirname(genJsonFile), { recursive: true });
-                writeFileSync(genJsonFile, next, 'utf8');
-                jsonWritten = true;
-            }
-        }
-        catch {
-            // annotations file has syntax errors — skip JSON emit
-        }
+    if (value === undefined)
+        return false;
+    const next = JSON.stringify(value, null, 2) + '\n';
+    const existing = existsSync(genJsonFile)
+        ? readFileSync(genJsonFile, 'utf8')
+        : null;
+    if (existing !== next) {
+        mkdirSync(dirname(genJsonFile), { recursive: true });
+        writeFileSync(genJsonFile, next, 'utf8');
+        return true;
     }
-    return { scaffolded, jsonWritten };
+    return false;
 }
 export async function createKysely(resolved) {
     mkdirSync(dirname(resolved.dbFile), { recursive: true });

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

@@ -33,6 +33,7 @@ export class PostgresIntrospector {
         const result = await this.client.query(`SELECT
          c.column_name,
          c.data_type,
+         c.udt_name,
          c.is_nullable,
          c.column_default,
          c.is_generated,
@@ -54,6 +55,7 @@ export class PostgresIntrospector {
         return result.rows.map((r) => ({
             name: r.column_name,
             type: r.data_type,
+            udtName: r.udt_name,
             notNull: r.is_nullable === 'NO',
             pk: Boolean(r.is_pk),
             defaultValue: r.column_default,

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

@@ -1,6 +1,44 @@
+/**
+ * Canonical map of `format` tokens (authored in `db/annotations.ts`) to the zod
+ * expression they emit. These are all *string* refinements — they do not change
+ * the column's TypeScript type (it stays `string`), only the runtime validator.
+ * This is the single source of truth: `annotation-parser` imports it to validate
+ * authored values and `db-codegen` imports the key list to emit the `format`
+ * union in `ColumnEntry`. All confirmed present in zod 4.
+ */
+export declare const ZOD_FORMATS: {
+    readonly email: "z.email()";
+    readonly url: "z.url()";
+    readonly emoji: "z.emoji()";
+    readonly e164: "z.e164()";
+    readonly jwt: "z.jwt()";
+    readonly cuid: "z.cuid()";
+    readonly cuid2: "z.cuid2()";
+    readonly ulid: "z.ulid()";
+    readonly nanoid: "z.nanoid()";
+    readonly base64: "z.base64()";
+    readonly base64url: "z.base64url()";
+    readonly ipv4: "z.ipv4()";
+    readonly ipv6: "z.ipv6()";
+    readonly cidrv4: "z.cidrv4()";
+    readonly cidrv6: "z.cidrv6()";
+    readonly isoDate: "z.iso.date()";
+    readonly isoTime: "z.iso.time()";
+    readonly isoDatetime: "z.iso.datetime()";
+    readonly isoDuration: "z.iso.duration()";
+};
+export type ZodFormat = keyof typeof ZOD_FORMATS;
 export interface ZodCodegenOptions {
     schemaFile: string;
     outFile: string;
+    /**
+     * Per-interface, per-field `format` overrides. Keyed by the *interface* name
+     * (PascalCase, as it appears in `schema.d.ts`) and the *field* name (camelCase),
+     * matching how `parseTables` reads the schema. Computed by `db-codegen` (which
+     * owns the snake→Pascal/camel name mapping) so this emitter stays a dumb
+     * string→zod translator.
+     */
+    formats?: Record<string, Record<string, ZodFormat>>;
 }
 export interface ZodCodegenResult {
     outFile: string;