@pikku/cli 0.12.33 → 0.12.35

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

@@ -1,29 +1,44 @@
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { ZOD_FORMATS } from './zod-codegen.js';
 /**
- * Determine column kind from naming conventions:
- *   *_at / *_on            → date
- *   is_* / has_* / can_*   → bool
+ * Warn-only naming heuristic. We no longer *infer* a column's kind from its
+ * name (it produced wrong types — e.g. SQLite stores `*_at` as ISO TEXT, not a
+ * `Date`). Instead the codegen warns when a column name looks like it wants a
+ * `kind` but none is declared in `db/annotations.ts`, so the developer can opt
+ * in explicitly. Returns the *suggested* kind, or null.
  */
-export function annotationFromName(colName) {
+export function nameSuggestsKind(colName) {
     if (/_at$|_on$/.test(colName))
-        return { kind: 'date' };
+        return 'date';
     if (/^is_|^has_|^can_/.test(colName))
-        return { kind: 'bool' };
+        return 'bool';
     return null;
 }
-// ── Load from db/annotations.gen.json sidecar ────────────────────────────────
+function parseStrategy(s) {
+    if (!s)
+        return null;
+    const valid = ['fake:email', 'fake:name', 'hash', 'keep'];
+    return valid.includes(s)
+        ? s
+        : null;
+}
 /**
- * Try to load annotations from a `db/annotations.gen.json` sidecar generated
- * by `yarn db:types`. Returns null if the file doesn't exist.
+ * Load annotations from the `db/annotations.gen.json` sidecar, which is
+ * compiled from the developer-authored `db/annotations.ts` (`DbClassificationMap`)
+ * by `syncClassifications`. This is the single source of column classification
+ * and type-override information — there is no SQL-comment fallback.
  *
- * The JSON file uses snake_case keys (raw DB names) so it can be read
- * directly without any conversion. It is emitted by bin/db-classify.ts.
+ * The authored `ColumnEntry` shape is:
+ *   { security?, classification?: <anonymize strategy>, kind?, tsType?, description? }
+ * where `security` is the privacy level and `classification` is the anonymize
+ * strategy. Returns `{}` if the sidecar doesn't exist yet (first migrate run,
+ * before it has been generated).
  */
-function loadAnnotationsSidecar(rootDir) {
+export function loadAnnotations(rootDir) {
     const jsonPath = join(rootDir, 'db', 'annotations.gen.json');
     if (!existsSync(jsonPath))
-        return null;
+        return {};
     try {
         const raw = JSON.parse(readFileSync(jsonPath, 'utf8'));
         const result = {};
@@ -33,111 +48,36 @@ function loadAnnotationsSidecar(rootDir) {
                 if (!ann)
                     continue;
                 const entry = {};
-                if (ann.kind === 'bool' || ann.kind === 'date' || ann.kind === 'json')
+                if (ann.kind === 'bool' ||
+                    ann.kind === 'date' ||
+                    ann.kind === 'json' ||
+                    ann.kind === 'uuid')
                     entry.kind = ann.kind;
                 if (ann.tsType)
                     entry.tsType = ann.tsType;
-                const vis = ann.visibility;
-                if (vis === 'public' || vis === 'private' || vis === 'secret')
-                    entry.classification = vis;
+                if (ann.format && ann.format in ZOD_FORMATS)
+                    entry.format = ann.format;
+                // `security` is the privacy level. `encrypted` brands as `secret`.
+                switch (ann.security) {
+                    case 'public':
+                    case 'private':
+                    case 'pii':
+                    case 'secret':
+                        entry.classification = ann.security;
+                        break;
+                    case 'encrypted':
+                        entry.classification = 'secret';
+                        break;
+                }
+                const strategy = parseStrategy(ann.classification);
+                if (strategy !== null)
+                    entry.anonymize = strategy;
                 result[table][col] = entry;
             }
         }
         return result;
     }
-    catch {
-        return null;
-    }
-}
-// ── SQL comment parsing (fallback) ───────────────────────────────────────────
-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|pii|secret)(?::([^\s@]+))?/i);
-    if (classM) {
-        ann.classification = classM[1].toLowerCase();
-        const strategy = parseStrategy(classM[2]);
-        if (strategy !== null)
-            ann.anonymize = strategy;
-    }
-    return ann;
-}
-/**
- * Parse `-- @bool | @date | @json [TsType] | @public | @private[:strategy] | @pii[:strategy] | @secret[:strategy]`
- * inline annotations from migration SQL files in `migrationsDir`.
- */
-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;
-}
-// ── Public entry point ────────────────────────────────────────────────────────
-/**
- * Load annotations for a project. Tries `db/annotations.ts` sidecar first;
- * falls back to SQL comment parsing from `migrationsDir` if not found.
- */
-export function loadAnnotations(rootDir, migrationsDir) {
-    const sidecar = loadAnnotationsSidecar(rootDir);
-    if (sidecar)
-        return sidecar;
-    return migrationsDir ? parseAnnotations(migrationsDir) : {};
 }

package/dist/src/functions/db/coercion-plugin.d.ts

@@ -1,5 +1,5 @@
 import type { KyselyPlugin } from 'kysely';
-export type ColumnKind = 'date' | 'bool' | 'json';
+export type ColumnKind = 'date' | 'bool' | 'json' | 'uuid';
 export type CoercionMap = Record<string, Record<string, ColumnKind>>;
 export interface CreateCoercionPluginOptions {
     map: CoercionMap;

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

@@ -23,6 +23,10 @@ function fromDb(value, kind) {
             catch {
                 return value;
             }
+        case 'uuid':
+            // UUIDs are strings in both Postgres and SQLite — no runtime coercion.
+            // (Codegen also omits `uuid` from the coercion map; this is defensive.)
+            return value;
     }
 }
 function snakeToCamel(name) {

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

@@ -1,4 +1,6 @@
 import type { DbIntrospector } from './db-introspector.js';
+import { type ZodFormat } from './zod-codegen.js';
+type Dialect = 'sqlite' | 'postgres';
 export interface CodegenOptions {
     outFile: string;
     coercionFile: string;
@@ -7,7 +9,8 @@ export interface CodegenOptions {
     schemaJsonFile?: string;
     camelCase?: boolean;
     rootDir?: string;
-    migrationsDir?: string;
+    /** DB dialect — drives real-type-aware date typing. Defaults to 'sqlite'. */
+    dialect?: Dialect;
 }
 export interface CodegenResult {
     outFile: string;
@@ -19,6 +22,14 @@ export interface CodegenResult {
     manifestWritten: boolean;
     classificationMapWritten: boolean;
     tables: string[];
+    /** Non-fatal codegen warnings (e.g. name looks like a date but unannotated). */
+    warnings: string[];
+    /**
+     * Per-interface, per-field zod `format` overrides for the zod codegen. Keyed
+     * by interface name (PascalCase) and field name (camelCase), matching the
+     * shapes the zod emitter parses out of `schema.d.ts`.
+     */
+    zodFormats: Record<string, Record<string, ZodFormat>>;
 }
 /**
  * Introspect `introspector` and emit:
@@ -27,3 +38,4 @@ export interface CodegenResult {
  *   - `classification.gen.ts`  Data-classification manifest (when manifestFile set)
  */
 export declare function generateSchemaTypes(introspector: DbIntrospector, options: CodegenOptions): Promise<CodegenResult>;
+export {};

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;
@@ -258,9 +365,16 @@ export async function generateSchemaTypes(introspector, options) {
         `  ? ColumnType<S, I | undefined, U>`,
         `  : ColumnType<T, T | undefined, T>`,
         ``,
-        `export type Private<T> = T & { readonly __classification__: 'private' }`,
-        `export type Pii<T> = T & { readonly __classification__: 'pii' }`,
-        `export type Secret<T> = T & { readonly __classification__: 'secret' }`,
+        // `__classification__` is optional so plain values stay assignable to branded
+        // columns (Kysely where/insert/update operands) while the brand remains
+        // structurally detectable for the inspector's PKU910 output check. Keep this
+        // in lockstep with `@pikku/core`'s data-classification.ts definitions.
+        `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,
         ``,
@@ -274,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;
@@ -311,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,
@@ -419,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;