@pikku/cli 0.12.34 → 0.12.36

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.d.ts

@@ -53,4 +53,37 @@ export declare function migrateAndCodegen(resolved: ResolvedDb): Promise<Migrate
 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>>;
+type SchemaMap = Map<string, Set<string>>;
+export interface DesiredAuthSchema {
+    tables: SchemaMap;
+    sql: string;
+}
+export declare function desiredAuthSchema(rootDir: string, srcDirectories: string[], logger: {
+    error: (msg: string) => void;
+}): Promise<DesiredAuthSchema | null>;
+export declare function introspectSchema(resolved: ResolvedDb): Promise<SchemaMap>;
+export interface AuthDriftResult {
+    hasAuth: boolean;
+    inSync: boolean;
+    missingTables: string[];
+    missingColumns: {
+        table: string;
+        columns: string[];
+    }[];
+}
+export declare function computeAuthDrift(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
+    error: (msg: string) => void;
+}): Promise<AuthDriftResult>;
+export interface GenerateAuthResult {
+    status: 'no-auth' | 'up-to-date' | 'written' | 'incremental-unsupported' | 'unsupported-dialect';
+    file?: string;
+    missingTables?: string[];
+    missingColumns?: {
+        table: string;
+        columns: string[];
+    }[];
+}
+export declare function generateAuthMigration(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
+    error: (msg: string) => void;
+}): Promise<GenerateAuthResult>;
 export {};