@pikku/cli 0.12.93 → 0.12.99

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

@@ -16,6 +16,18 @@ export interface CodegenOptions {
      */
     enumsFile?: string;
     camelCase?: boolean;
+    /**
+     * Schema whose qualifier is dropped from the `DB` keys and the interface
+     * names, so `app.user` reads as `user`/`User` rather than `app.user`/
+     * `AppUser`. Tables in any other schema stay fully qualified. Omitting it
+     * qualifies everything, which is the safe default for a project spanning
+     * schemas.
+     *
+     * The key IS what Kysely puts in the SQL, so only set this for a schema the
+     * connection's `search_path` resolves — otherwise every query compiles and
+     * then fails to find the table at runtime.
+     */
+    defaultSchema?: string;
     rootDir?: string;
     /** DB dialect — drives real-type-aware date typing. Defaults to 'sqlite'. */
     dialect?: Dialect;

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

@@ -33,6 +33,16 @@ function snakeToPascal(name) {
         .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
         .join('');
 }
+/**
+ * Drop `defaultSchema`'s qualifier from a table name, leaving every other
+ * schema qualified. `app.user` → `user` when the default schema is `app`.
+ */
+function stripDefaultSchema(name, defaultSchema) {
+    if (!defaultSchema)
+        return name;
+    const prefix = `${defaultSchema}.`;
+    return name.startsWith(prefix) ? name.slice(prefix.length) : name;
+}
 function tableToInterfaceName(name) {
     return name
         .split('.')
@@ -105,10 +115,54 @@ function insertBase(annotation, col) {
         return 'unknown';
     return mapType(col.type);
 }
-function columnTypeExpression(col, annotation, classification) {
+/**
+ * The brand a `form` puts on a column's INSERT and UPDATE types.
+ *
+ * `plain` maps to null rather than to an identity wrapper: an unbranded column
+ * is the default every existing project already has, and emitting a wrapper for
+ * it would churn every generated file to say nothing.
+ */
+/** The erasable sensitivity brand on a column's SELECT type. */
+function classificationBrand(classification) {
+    return classification === 'secret'
+        ? 'Secret'
+        : classification === 'pii'
+            ? 'Pii'
+            : 'Private';
+}
+function formBrand(form) {
+    switch (form) {
+        case 'wrapped':
+            return 'WrappedValue';
+        case 'sealed':
+            return 'SealedValue';
+        case 'hashed':
+            return 'HashedValue';
+        default:
+            return null;
+    }
+}
+function columnTypeExpression(col, annotation, classification, form) {
     const nullable = !col.notNull && !col.pk;
     const isAutoInt = col.pk && mapType(col.type) === 'number';
     const isOptionalInsert = col.defaultValue !== null || isAutoInt || Boolean(col.generated);
+    // A declared `form` supersedes both branches below, because it constrains the
+    // side neither of them touches: what may be WRITTEN. The caller only reaches
+    // here with a form once it has confirmed the column resolves to `string`.
+    const brand = formBrand(form);
+    if (brand) {
+        // The two brands compose — `Secret<WrappedValue>` is still structurally
+        // `{ __classification__?: 'secret' }`, so the inspector's PKU910 output
+        // check keeps working, while a row read back is already a `WrappedValue`
+        // and flows into rewrap/re-seal calls without a cast.
+        const selectT = classification === 'public'
+            ? brand
+            : `${classificationBrand(classification)}<${brand}>`;
+        const insertT = `${brand}${isOptionalInsert ? ' | undefined' : ''}`;
+        return nullable
+            ? `ColumnType<${selectT} | null, ${insertT} | null, ${brand} | null>`
+            : `ColumnType<${selectT}, ${insertT}, ${brand}>`;
+    }
     if (classification === 'public') {
         const wrap = (inner) => isOptionalInsert ? `Generated<${inner}>` : inner;
         if (annotation?.kind === 'bool') {
@@ -139,11 +193,7 @@ function columnTypeExpression(col, annotation, classification) {
             return `Generated<${base}${nullable ? ' | null' : ''}>`;
         return nullable ? `${base} | null` : base;
     }
-    const B = classification === 'secret'
-        ? 'Secret'
-        : classification === 'pii'
-            ? 'Pii'
-            : 'Private';
+    const B = classificationBrand(classification);
     const sBase = selectBase(annotation, col);
     const iBase = insertBase(annotation, col);
     const selectT = nullable ? `${B}<${sBase}> | null` : `${B}<${sBase}>`;
@@ -159,7 +209,7 @@ function bareTableName(name) {
     return dot >= 0 ? name.slice(dot + 1) : name;
 }
 function emitInterface(table, camelCase, explicitAnnotations, dialect, enumByName, formatHints, warnings) {
-    const ifaceName = tableToInterfaceName(table.name);
+    const ifaceName = tableToInterfaceName(table.displayName ?? table.name);
     const bare = bareTableName(table.name);
     const tableCols = explicitAnnotations[bare] ?? {};
     const fields = table.columns
@@ -243,7 +293,44 @@ function emitInterface(table, camelCase, explicitAnnotations, dialect, enumByNam
             }
         }
         const classification = ann?.classification ?? 'private';
-        const type = columnTypeExpression(col, typeAnn, classification);
+        // A form brands the column with a nominal string subtype, so it only
+        // means anything where the resolved type IS a string. On a bytea/blob or
+        // a coerced column the brand would not compile, so skip it and say why —
+        // a secret that needs wrapping in a non-text column needs the column
+        // migrated to text first, which is a schema decision, not a codegen one.
+        let form = ann?.form;
+        if (form && form !== 'plain') {
+            const base = selectBase(typeAnn, col);
+            if (base !== 'string') {
+                warnings.push({
+                    severity: 'warn',
+                    code: ErrorCode.DB_FORM_ON_NON_STRING,
+                    message: `Column "${bare}.${col.name}": form '${form}' ignored — its resolved ` +
+                        `type is ${base}, not string. Ciphertext and digests are text; ` +
+                        `migrate the column or drop the form.`,
+                });
+                form = undefined;
+            }
+        }
+        // The point of the axis: a credential the application can replay is one
+        // that a database read alone hands to whoever has it. Warn rather than
+        // fail, because every project predating `form` has such columns and a
+        // hard error would break them all on the next migrate — `pikku db
+        // --fail-on-warn` is how a project opts into the ratchet.
+        // Checks what was DECLARED, not what survived the string test above, so a
+        // form rejected for a non-text column reports that one reason rather than
+        // two, and an explicit `form: 'plain'` is the acknowledgement that ends it.
+        if (classification === 'secret' && ann?.form === undefined) {
+            warnings.push({
+                severity: 'warn',
+                code: ErrorCode.DB_SECRET_COLUMN_STORED_PLAIN,
+                message: `Column "${bare}.${col.name}" is classified secret but stored in the clear. ` +
+                    `Declare how it is held in db/annotations.ts — form: 'hashed' | 'wrapped' | ` +
+                    `'sealed' — or form: 'plain' to state that reading the row is meant to ` +
+                    `yield a usable credential.`,
+            });
+        }
+        const type = columnTypeExpression(col, typeAnn, classification, form);
         const safeName = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(fieldName)
             ? fieldName
             : JSON.stringify(fieldName);
@@ -263,8 +350,12 @@ function emitManifest(tables, explicitAnnotations) {
             const classification = ann?.classification ?? 'private';
             const strategy = ann?.anonymize ?? null;
             const strategyLiteral = strategy === null ? 'null' : `'${strategy}'`;
+            // Emitted only when declared. An audit reading this manifest needs to
+            // tell "held in the clear, stated" from "nobody has said yet", and a
+            // defaulted 'plain' would erase exactly that difference.
+            const formLiteral = ann?.form ? `, form: '${ann.form}'` : '';
             return (`      ${JSON.stringify(col.name)}: ` +
-                `{ classification: '${classification}', anonymize_strategy: ${strategyLiteral} }`);
+                `{ classification: '${classification}', anonymize_strategy: ${strategyLiteral}${formLiteral} }`);
         })
             .join(',\n');
         return `    ${JSON.stringify(table.name)}: {\n${colEntries}\n    }`;
@@ -292,8 +383,14 @@ function emitManifest(tables, explicitAnnotations) {
  */
 function emitClassificationMap(tables) {
     const colEntry = [
-        `  /** Privacy level. Defaults to 'private' when omitted. */`,
+        `  /** Privacy level — can the value leave the process? Defaults to 'private'.`,
+        `   *  'encrypted' is the legacy spelling of \`security: 'secret', form: 'wrapped'\`. */`,
         `  security?: 'public' | 'private' | 'pii' | 'secret' | 'encrypted'`,
+        `  /** How the value is held at rest, independent of \`security\`. A form other`,
+        `   *  than 'plain' makes the column's INSERT/UPDATE type nominal, so only a`,
+        `   *  real encrypt/seal/hash result can be written to it. Defaults to 'plain',`,
+        `   *  which on a \`secret\` column is warned about (PKU483) until stated here. */`,
+        `  form?: 'plain' | 'hashed' | 'wrapped' | 'sealed'`,
         `  /** Anonymize strategy used by \`pikku db anonymize\`. */`,
         `  classification?: 'fake:email' | 'fake:name' | 'hash' | 'keep'`,
         `  /** Column kind override for codegen coercion + typing. */`,
@@ -419,24 +516,57 @@ export async function generateSchemaTypes(introspector, options) {
     }
     // ── schema.gen.ts ────────────────────────────────────────────────────────────
     const warnings = [];
+    // The name each table is known by in the generated types. With a
+    // `defaultSchema` that is the unqualified name — unless dropping the
+    // qualifier would make two tables share one name, in which case the table
+    // keeps its qualifier rather than silently shadowing the other.
+    const displayNames = new Map();
+    const claimedBy = new Map();
+    for (const t of tables) {
+        const stripped = stripDefaultSchema(t.name, options.defaultSchema);
+        const owner = claimedBy.get(stripped);
+        if (owner !== undefined && owner !== t.name) {
+            warnings.push({
+                severity: 'warn',
+                code: ErrorCode.DB_DEFAULT_SCHEMA_NAME_COLLISION,
+                message: `Dropping the "${options.defaultSchema}" qualifier would make "${t.name}" and ` +
+                    `"${owner}" both "${stripped}". "${t.name}" keeps its qualifier.`,
+            });
+            displayNames.set(t.name, t.name);
+            continue;
+        }
+        claimedBy.set(stripped, t.name);
+        displayNames.set(t.name, stripped);
+    }
+    const displayName = (name) => displayNames.get(name) ?? name;
     const zodFormats = {};
     const interfaces = tables
-        .map((t) => emitInterface(t, camelCase, explicitAnnotations, dialect, enumByName, zodFormats, warnings))
+        .map((t) => emitInterface({ ...t, displayName: displayName(t.name) }, camelCase, explicitAnnotations, dialect, enumByName, zodFormats, warnings))
         .join('\n\n');
     const dbEntries = tables
         .map((t) => {
-        const tableKey = camelCase ? snakeToCamel(t.name) : t.name;
+        const name = displayName(t.name);
+        const tableKey = camelCase ? snakeToCamel(name) : name;
         const safe = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableKey)
             ? tableKey
             : JSON.stringify(tableKey);
-        return `  ${safe}: ${tableToInterfaceName(t.name)}`;
+        return `  ${safe}: ${tableToInterfaceName(name)}`;
     })
         .join('\n');
+    // The form brands are nominal (`unique symbol`), so unlike the structural
+    // `Private`/`Secret` aliases they CANNOT be re-declared here: a local
+    // declaration would be a distinct type, and the ciphertext `@pikku/core`
+    // hands back would not be assignable to the column it belongs in. Import the
+    // one true declaration, and only when a column actually uses it.
+    const usedFormBrands = ['WrappedValue', 'SealedValue', 'HashedValue'].filter((brand) => new RegExp(`\\b${brand}\\b`).test(interfaces));
     const schemaBody = [
         `// Generated by @pikku/cli — do not edit by hand.`,
         `// Run \`pikku db migrate\` to refresh.`,
         ``,
         `import type { ColumnType } from 'kysely'`,
+        ...(usedFormBrands.length > 0
+            ? [`import type { ${usedFormBrands.join(', ')} } from '@pikku/core'`]
+            : []),
         ``,
         `export type Generated<T> = T extends ColumnType<infer S, infer I, infer U>`,
         `  ? ColumnType<S, I | undefined, U>`,
@@ -470,9 +600,12 @@ export async function generateSchemaTypes(introspector, options) {
             // 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;
+                // Keyed by the name the query is written against, since that is what
+                // the runtime plugin sees on the Kysely node.
+                const key = displayName(table.name);
+                if (!coercionMap[key])
+                    coercionMap[key] = {};
+                coercionMap[key][col.name] = kind;
             }
         }
     }

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

@@ -3,7 +3,7 @@ import { type MigrateResult } from './db-migrator.js';
 import type { ColumnInfo } from './db-introspector.js';
 import { type CodegenResult } from './db-codegen.js';
 import { type ZodCodegenResult } from './zod-codegen.js';
-import { type SeedResult } from './sqlite/seed.js';
+import { type DevSeedResult } from './sqlite/dev-seed.js';
 import type { UserConfigShape } from '../commands/db-shared.js';
 interface ResolvedDbBase {
     rootDir: string;
@@ -18,12 +18,18 @@ interface ResolvedDbBase {
     enumsFile: string;
     zodFile: string;
     camelCase: boolean;
+    /**
+     * Schema whose qualifier the generated types drop, from `db.defaultSchema`.
+     * Unlike `schema` this applies to both dialects — sqlite has no schemas to
+     * qualify with, so it is simply inert there.
+     */
+    defaultSchema?: string;
 }
 export interface ResolvedSqliteDb extends ResolvedDbBase {
     dialect: 'sqlite';
     dbFile: string;
     runtimeDir: string;
-    seedFile: string;
+    devSeedFile: string;
 }
 export interface ResolvedPostgresDb extends ResolvedDbBase {
     dialect: 'postgres';
@@ -31,7 +37,25 @@ export interface ResolvedPostgresDb extends ResolvedDbBase {
     connectionString?: string;
     pgliteDir?: string;
     runtimeDir: string;
-    seedFile: string;
+    devSeedFile: string;
+    /**
+     * Postgres extensions the embedded PGlite databases must load, as declared by
+     * `pgliteExtensions` in the project's config. See
+     * {@link loadPGliteExtensions}.
+     *
+     * Carried even in `url` mode: the shadow database the CLI migrates and
+     * introspects is PGlite whichever server the project itself runs against, so
+     * a migration that needs an extension needs it here too.
+     */
+    pgliteExtensions: string[];
+    /**
+     * The schema generated migrations create their tables in, from `db.schema`.
+     *
+     * Postgres only — hence its absence from `ResolvedSqliteDb` rather than a
+     * runtime check. sqlite's `REFERENCES` clause takes a bare table name, so
+     * qualified DDL does not compile there at all.
+     */
+    schema?: string;
 }
 export type ResolvedDb = ResolvedSqliteDb | ResolvedPostgresDb;
 /**
@@ -45,9 +69,47 @@ export declare function parseDatabaseUrl(url: string): Pick<UserConfigShape, 'sq
  * Resolve a UserConfigShape into an absolute-path descriptor.
  * Returns null when neither sqliteDb nor postgresUrl is configured.
  */
-export declare function resolveDb(userConfig: UserConfigShape, rootDir: string, outDir: string, runtimeDir?: string): ResolvedDb | null;
+export declare function resolveDb(userConfig: UserConfigShape, rootDir: string, outDir: string, runtimeDir?: string, dbConfig?: {
+    schema?: string;
+    defaultSchema?: string;
+} | string): ResolvedDb | null;
 /** @deprecated Use resolveDb(userConfig, ...) instead. */
 export declare function resolveLocalDb(sqliteDb: string | undefined, rootDir: string, outDir: string, runtimeDir?: string): ResolvedSqliteDb | null;
+/**
+ * What an embedded PGlite instance needs beyond its data directory: where to
+ * resolve extension packages from, and which ones to load.
+ *
+ * A `ResolvedPostgresDb` already is one, which is what lets every call site
+ * that has one pass it straight through.
+ */
+export interface PGliteExtensionContext {
+    rootDir: string;
+    pgliteExtensions: string[];
+}
+/**
+ * A PGlite extension, as the packages that publish one export it: an object
+ * carrying the `setup` that hands PGlite the WASM bundle, or a URL/string
+ * pointing at a remote one.
+ *
+ * Structural rather than imported from PGlite so a project's extension package
+ * — built against its own copy of `@electric-sql/pglite` — is recognised
+ * whatever the two versions are.
+ */
+type PGliteExtension = {
+    name?: string;
+    setup: (...args: any[]) => unknown;
+};
+/**
+ * Load every extension the project declares, keyed the way PGlite wants them.
+ *
+ * The key is the export name (`vector`, `hstore`), which is also the name the
+ * SQL uses, so `CREATE EXTENSION vector` finds what a declaration of
+ * `@electric-sql/pglite-pgvector` loaded. A module exporting several is fine —
+ * all of them are taken — and a `default` export is used only when it is the
+ * only extension there, so a package that default-exports the same object it
+ * also names is not registered twice.
+ */
+export declare function loadPGliteExtensions(rootDir: string, specs: string[]): Promise<Record<string, PGliteExtension>>;
 export interface MigrateAndCodegenOutcome {
     migrate: MigrateResult;
     codegen: CodegenResult;
@@ -73,7 +135,15 @@ export interface MigrateAndCodegenOptions {
     scratch?: boolean;
 }
 export declare function migrateAndCodegen(resolved: ResolvedDb, options?: MigrateAndCodegenOptions): Promise<MigrateAndCodegenOutcome>;
-export declare function seed(resolved: ResolvedDb): Promise<SeedResult>;
+/**
+ * Apply the dev seed file. Only {@link reset} calls this, immediately after
+ * migrating a database it has just wiped, which is what lets a seed file be
+ * plain `INSERT`s rather than idempotent ones.
+ *
+ * `reset` refuses production before it gets here, so this guard is unreachable
+ * through the CLI. It stays because the export is reachable without it.
+ */
+export declare function devSeed(resolved: ResolvedDb): Promise<DevSeedResult>;
 export declare function reset(resolved: ResolvedDb, rootDir: string): Promise<void>;
 export declare function createKysely<DB>(resolved: ResolvedDb): Promise<Kysely<DB>>;
 /**
@@ -229,6 +299,17 @@ export interface SchemaSource {
     desired: DesiredSchema;
     /** Prose for the migration header, saying where the SQL came from. */
     origin: string;
+    /**
+     * The schema this source's SQL is qualified into, when it is.
+     *
+     * Carried per source rather than read off the resolved database because only
+     * the sources pikku compiles can honour it. Better Auth writes its own
+     * migration SQL through its own migrator and an addon ships SQL as text —
+     * neither goes through the schema builder, so neither can be qualified from
+     * here, and claiming otherwise on their behalf would emit a delta that names
+     * a table in a schema their `CREATE TABLE` never put it in.
+     */
+    schema?: string;
 }
 /** One dialect's worth of a published schema. */
 export interface ExportedSchema {
@@ -265,7 +346,7 @@ export interface AddonDeclaration {
  * happens to be configured against — an addon is published once and consumed by
  * projects on either engine.
  */
-export declare function exportSchema(rootDir: string): Promise<SchemaArtifact>;
+export declare function exportSchema(rootDir: string, pgliteExtensions?: string[]): Promise<SchemaArtifact>;
 /**
  * The schema every wired addon publishes, as sources.
  *