@pikku/cli 0.12.89 → 0.12.90

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

@@ -1,5 +1,6 @@
 import { Kysely } from 'kysely';
 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';
@@ -54,19 +55,150 @@ export interface MigrateAndCodegenOutcome {
     classificationsScaffolded: boolean;
     classificationsJsonWritten: boolean;
 }
-export declare function migrateAndCodegen(resolved: ResolvedDb): Promise<MigrateAndCodegenOutcome>;
+export interface MigrateAndCodegenOptions {
+    /**
+     * Apply the migrations to a throwaway database and introspect that, instead
+     * of touching the configured one.
+     *
+     * The generated types describe the schema the migrations define, which is the
+     * contract — a live database additionally carries whatever has drifted into
+     * it (tables a runtime bootstrapped, leftovers from a reverted branch), and
+     * introspecting one makes codegen depend on a reachable, already-migrated
+     * server. That ordering is the problem this solves: codegen can now run
+     * before deploy-time migrations, on a machine with no database at all.
+     *
+     * SQLite uses `:memory:`; Postgres uses an embedded PGlite (real Postgres,
+     * and it needs no `CREATEDB` privilege anywhere).
+     */
+    scratch?: boolean;
+}
+export declare function migrateAndCodegen(resolved: ResolvedDb, options?: MigrateAndCodegenOptions): Promise<MigrateAndCodegenOutcome>;
 export declare function seed(resolved: ResolvedDb): Promise<SeedResult>;
 export declare function reset(resolved: ResolvedDb, rootDir: string): Promise<void>;
 export declare function createKysely<DB>(resolved: ResolvedDb): Promise<Kysely<DB>>;
-type SchemaMap = Map<string, Set<string>>;
-export interface DesiredAuthSchema {
+/**
+ * Every table and its columns, keyed by the name the introspector reports.
+ *
+ * Carries the whole {@link ColumnInfo}, not just the names, because the same
+ * map has to answer both "does this column exist" and "what would the statement
+ * that adds it look like" — and a map of names can only answer the first.
+ */
+type SchemaMap = Map<string, Map<string, ColumnInfo>>;
+/**
+ * A schema somebody other than the project's own migrations defines — Better
+ * Auth, the pikku runtime, an addon.
+ *
+ * Every such source answers the same two questions, which is what lets one
+ * mechanism serve all of them: `tables` is what must exist, and `sql` is what
+ * creates it.
+ */
+export interface DesiredSchema {
     tables: SchemaMap;
     sql: string;
 }
+export type DesiredAuthSchema = DesiredSchema;
 export declare function desiredAuthSchema(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
     error: (msg: string) => void;
 }): Promise<DesiredAuthSchema | null>;
+/** A runtime schema left out because nothing in the project creates what it needs. */
+export interface SkippedRuntimeSchema {
+    schema: string;
+    /** The prerequisite that was not there, as `table.column`. */
+    requires: string;
+    owner: string;
+}
+export interface DesiredRuntimeSchema extends DesiredSchema {
+    skipped: SkippedRuntimeSchema[];
+}
+/**
+ * The tables `@pikku/kysely`'s runtime services need, as declared.
+ *
+ * Materialized the same way the auth schema is: applied to a throwaway database
+ * and introspected, so one declaration answers both "what should exist" and
+ * "what SQL creates it" without a hand-written per-dialect copy.
+ *
+ * Auth goes into the same database first, because it is a prerequisite — the
+ * scope tables grant to a user, so they reference the table Better Auth owns.
+ * Its tables are subtracted from the result: they are covered by auth's own
+ * source, and counting them twice would have `db generate` write them twice.
+ *
+ * A project with no auth configured is not an error here. It genuinely has no
+ * scope tables, so the schemas that wanted them are left out and returned in
+ * `skipped` — reported rather than dropped, because the tables they would have
+ * recognised now have nothing to explain them.
+ */
+export declare function desiredRuntimeSchema(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
+    error: (msg: string) => void;
+}): Promise<DesiredRuntimeSchema>;
 export declare function introspectSchema(resolved: ResolvedDb): Promise<SchemaMap>;
+export interface SchemaDriftResult {
+    /** In the migrations, absent from the database — it is behind. */
+    missingTables: string[];
+    missingColumns: {
+        table: string;
+        columns: string[];
+    }[];
+    /**
+     * In the database and absent from the migrations, but declared by the pikku
+     * runtime — created by a service at boot rather than written down.
+     */
+    runtimeTables: string[];
+    /** In the database, absent from the migrations — nobody wrote it down. */
+    extraTables: string[];
+    /**
+     * Runtime schemas that could not be materialized, so their tables were not
+     * recognisable — the reason an `extraTables` entry may be a runtime table in
+     * disguise.
+     */
+    skippedRuntimeSchemas: SkippedRuntimeSchema[];
+    inSync: boolean;
+}
+/**
+ * Compare the schema the migration files define against the one the configured
+ * database actually has.
+ *
+ * The two halves are asymmetric and must stay that way. Something missing from
+ * the database is a database that is behind — the fix only ever adds, so it is
+ * safe to automate. Something present in the database but absent from the
+ * migrations is a table nobody wrote down: a runtime that created its own at
+ * boot, or the remains of a reverted branch. Dropping those is how data gets
+ * lost, so they are reported and never acted on.
+ *
+ * The pikku runtime declares tables of its own, and they are used here to
+ * recognise rather than to require. A project that never constructs the
+ * workflow or AI services should not be told it is missing their tables, so
+ * absence is not a finding. Presence is: a runtime table in the database that
+ * no migration creates gets reported as such, separately from the genuinely
+ * unexplained ones, because for those the remedy is known — `db generate`
+ * writes them down.
+ */
+export declare function computeSchemaDrift(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
+    error: (msg: string) => void;
+}): Promise<SchemaDriftResult>;
+export type BaselineResult = {
+    status: 'behind';
+    drift: SchemaDriftResult;
+} | {
+    status: 'recorded';
+    recorded: string[];
+};
+/**
+ * Record the pending migrations as applied, for a database that already has
+ * what they describe.
+ *
+ * The situation this exists for: a runtime created its tables at boot, and the
+ * migration writing them down was authored afterwards. Every existing
+ * deployment already has those tables, so running that migration fails; not
+ * running it leaves the history claiming the schema is something else.
+ *
+ * Guarded by the same question `db check` answers. If the database is behind
+ * its migrations in any way then the premise is false — the tables are not all
+ * there — and recording them would hide a real gap behind a history that says
+ * everything is applied. So it refuses and hands back the drift.
+ */
+export declare function baseline(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
+    error: (msg: string) => void;
+}): Promise<BaselineResult>;
 export interface AuthDriftResult {
     hasAuth: boolean;
     inSync: boolean;
@@ -79,16 +211,106 @@ export interface AuthDriftResult {
 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';
-    file?: string;
-    missingTables?: string[];
-    missingColumns?: {
-        table: string;
-        columns: string[];
-    }[];
+/**
+ * Something other than the project's own migrations that declares tables.
+ *
+ * Better Auth, the pikku runtime, an addon. They differ only in where the
+ * declaration comes from; once materialized they answer the same two questions,
+ * which is what lets one generator serve all of them.
+ */
+export interface SchemaSource {
+    /**
+     * Labels the generated migration and every report line about it.
+     *
+     * Part of the contract: change it and the migration written under the old
+     * name is orphaned, so `db generate` writes the tables a second time.
+     */
+    name: string;
+    desired: DesiredSchema;
+    /** Prose for the migration header, saying where the SQL came from. */
+    origin: string;
+}
+/** One dialect's worth of a published schema. */
+export interface ExportedSchema {
+    sql: string;
+    tables: Record<string, ColumnInfo[]>;
+}
+/**
+ * What an addon publishes: its schema, per dialect it supports.
+ *
+ * Per-dialect rather than one portable form because there is no portable form —
+ * the SQL an addon ships is the SQL it wrote for that engine, and a consumer
+ * on a dialect the addon never wrote for is a real incompatibility rather than
+ * something to paper over at generate time.
+ */
+export type SchemaArtifact = Partial<Record<ResolvedDb['dialect'], ExportedSchema>>;
+/** An addon as the consumer wired it. */
+export interface AddonDeclaration {
+    package: string;
+    /**
+     * A `wireRemoteAddon` addon runs on another host, against that host's
+     * database. Its tables are not this project's to create.
+     */
+    remote?: boolean;
+}
+/**
+ * Materialize this package's own migrations into something a consumer can use.
+ *
+ * The producer half of the addon channel, and the same trick the auth and
+ * runtime sources use: run the SQL into a throwaway database and introspect it,
+ * so the artifact answers both "what must exist" and "what creates it" without
+ * a second, hand-written description that drifts.
+ *
+ * Every dialect the package has migrations for is exported, not just the one it
+ * 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>;
+/**
+ * The schema every wired addon publishes, as sources.
+ *
+ * An addon never creates its own tables. It has no database of its own — it
+ * runs inside the consumer, against the consumer's — so the only honest place
+ * for its DDL is the consumer's own migration history, which is what turning it
+ * into a `SchemaSource` achieves.
+ */
+export declare function addonSchemaSources(rootDir: string, dialect: ResolvedDb['dialect'], addons: AddonDeclaration[], logger: {
+    error: (msg: string) => void;
+}): Promise<SchemaSource[]>;
+/**
+ * Every schema source the project has, in the order they must be applied.
+ *
+ * Auth comes first because the runtime's scope tables reference its `user`
+ * table; addons come last because they may reference either.
+ */
+export declare function schemaSources(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
+    error: (msg: string) => void;
+}, addons?: AddonDeclaration[]): Promise<SchemaSource[]>;
+export interface GeneratedMigration {
+    source: string;
+    file: string;
+    /** Columns the migration adds that need a backfill decision before it is applied. */
+    needsBackfill: string[];
+}
+export interface GenerateResult {
+    /** Sources whose tables the migrations already cover. */
+    upToDate: string[];
+    written: GeneratedMigration[];
 }
-export declare function generateAuthMigration(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
+/**
+ * Write a migration for every schema source the migrations do not yet cover.
+ *
+ * Three cases per source, and the distinction matters. Fully covered is
+ * nothing to do. Nothing covered writes the source's own SQL verbatim, which is
+ * the one case where the source knows better than any diff — it carries the
+ * indexes, constraints and ordering a table-and-column comparison cannot see.
+ * Partially covered writes the delta, because re-emitting the whole schema
+ * would fail on the tables that already exist.
+ *
+ * Migrations are written one file per source, numbered in dependency order, so
+ * a project can review and apply them independently.
+ */
+export declare function generateMigrations(resolved: ResolvedDb, rootDir: string, srcDirectories: string[], logger: {
     error: (msg: string) => void;
-}): Promise<GenerateAuthResult>;
+}, addons?: AddonDeclaration[]): Promise<GenerateResult>;
 export {};