@pikku/cli 0.12.89 → 0.12.90

package/dist/src/functions/commands/db-baseline.js

@@ -0,0 +1,48 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { resolveDb, baseline } from '../db/local-db.js';
+import { loadUserConfigForDb } from './db-shared.js';
+/**
+ * Record the pending migrations as applied, without running them.
+ *
+ * For a database that already contains what they describe. The case it exists
+ * for is a schema that was created at boot and written down afterwards: every
+ * deployment already has those tables, so applying the migration fails, and
+ * leaving it pending forever means the history never catches up with reality.
+ *
+ * Refuses unless the database really is up to date, because that is the entire
+ * premise. A database that is behind gets the same report `db check` gives —
+ * baselining it would bury a real gap under a history claiming otherwise.
+ */
+export const dbBaseline = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const userConfig = await loadUserConfigForDb({ config, logger });
+        if (!userConfig)
+            return;
+        const resolved = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+        if (!resolved) {
+            logger.error('pikku db baseline: no database configured — set sqliteDb or postgresUrl in your createConfig.');
+            throw new Error('no database configured');
+        }
+        const result = await baseline(resolved, config.rootDir, config.srcDirectories, logger);
+        if (result.status === 'behind') {
+            logger.error('db baseline: refused — the database does not yet contain everything the migrations describe:');
+            if (result.drift.missingTables.length) {
+                logger.error(`  missing tables: ${result.drift.missingTables.join(', ')}`);
+            }
+            for (const { table, columns } of result.drift.missingColumns) {
+                logger.error(`  ${table} missing columns: ${columns.join(', ')}`);
+            }
+            logger.error('  Baselining now would record migrations that never ran. Run `pikku db migrate` instead.');
+            throw new Error('database is behind its migrations');
+        }
+        if (result.recorded.length === 0) {
+            logger.info('db baseline: nothing pending — every migration is recorded');
+            return;
+        }
+        logger.info(`db baseline: recorded ${result.recorded.length} migration(s) as applied without running them:`);
+        for (const name of result.recorded) {
+            logger.info(`  ${name}`);
+        }
+    },
+});

package/dist/src/functions/commands/db-check.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Report how the configured database differs from the schema its migrations
+ * define.
+ *
+ * Answers the question nobody can otherwise answer without going and looking by
+ * hand: does this database still match what we wrote down? Missing tables and
+ * columns fail the command — the database is behind and a migration has not
+ * been applied. Tables the migrations never mention are reported but never
+ * fail: something created them outside the migration history, which is worth
+ * seeing but is not this command's to fix.
+ */
+export declare const dbCheck: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/db-check.js

@@ -0,0 +1,64 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { resolveDb, computeSchemaDrift } from '../db/local-db.js';
+import { loadUserConfigForDb } from './db-shared.js';
+/**
+ * Report how the configured database differs from the schema its migrations
+ * define.
+ *
+ * Answers the question nobody can otherwise answer without going and looking by
+ * hand: does this database still match what we wrote down? Missing tables and
+ * columns fail the command — the database is behind and a migration has not
+ * been applied. Tables the migrations never mention are reported but never
+ * fail: something created them outside the migration history, which is worth
+ * seeing but is not this command's to fix.
+ */
+export const dbCheck = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const userConfig = await loadUserConfigForDb({ config, logger });
+        if (!userConfig)
+            return;
+        const resolved = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+        if (!resolved) {
+            logger.error('pikku db check: no database configured — set sqliteDb or postgresUrl in your createConfig.');
+            throw new Error('no database configured');
+        }
+        const drift = await computeSchemaDrift(resolved, config.rootDir, config.srcDirectories, logger);
+        // Table names elide the `public` schema, which reads as ambiguous in a
+        // report whose whole point can be a second copy of `app.orders` sitting in
+        // `public`. Put the schema back for display only.
+        const qualify = (table) => resolved.dialect === 'postgres' && !table.includes('.')
+            ? `public.${table}`
+            : table;
+        if (drift.runtimeTables.length) {
+            logger.info(`db check: ${drift.runtimeTables.length} table(s) the pikku runtime created at boot, which no migration records:`);
+            for (const table of drift.runtimeTables) {
+                logger.info(`  ${qualify(table)}`);
+            }
+            logger.info('  Run `pikku db generate` to write them down, so the schema stops depending on which services happened to start.');
+        }
+        if (drift.extraTables.length) {
+            logger.info(`db check: ${drift.extraTables.length} table(s) in the database that no migration creates:`);
+            for (const table of drift.extraTables) {
+                logger.info(`  ${qualify(table)}`);
+            }
+            logger.info('  Left alone — a migration cannot know whether these hold data worth keeping.');
+            for (const { schema, requires, owner } of drift.skippedRuntimeSchemas) {
+                logger.info(`  Note: the runtime's '${schema}' tables could not be recognised — it needs '${requires}', which this project does not create. ${owner} owns it.`);
+            }
+        }
+        if (drift.inSync) {
+            logger.info('db check: the database matches its migrations');
+            return;
+        }
+        logger.error('db check: the database is behind its migrations:');
+        if (drift.missingTables.length) {
+            logger.error(`  missing tables: ${drift.missingTables.map(qualify).join(', ')}`);
+        }
+        for (const { table, columns } of drift.missingColumns) {
+            logger.error(`  ${qualify(table)} missing columns: ${columns.join(', ')}`);
+        }
+        logger.error('  Run `pikku db migrate` to apply them.');
+        throw new Error('database schema is behind its migrations');
+    },
+});

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

@@ -0,0 +1,11 @@
+/**
+ * Regenerate the database types from the migration files alone, without
+ * connecting to the configured database.
+ *
+ * `db migrate` can only emit types after it has migrated the real database,
+ * which forces codegen to run late — after a deploy has already moved the
+ * schema. This command applies the same migrations to a throwaway database and
+ * introspects that, so `pikku all` can be given an accurate table zod on a
+ * machine with no database reachable at all.
+ */
+export declare const dbCodegen: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

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

@@ -0,0 +1,39 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { resolveDb, migrateAndCodegen } from '../db/local-db.js';
+import { loadUserConfigForDb } from './db-shared.js';
+/**
+ * Regenerate the database types from the migration files alone, without
+ * connecting to the configured database.
+ *
+ * `db migrate` can only emit types after it has migrated the real database,
+ * which forces codegen to run late — after a deploy has already moved the
+ * schema. This command applies the same migrations to a throwaway database and
+ * introspects that, so `pikku all` can be given an accurate table zod on a
+ * machine with no database reachable at all.
+ */
+export const dbCodegen = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const userConfig = await loadUserConfigForDb({ config, logger });
+        if (!userConfig)
+            return;
+        const resolved = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+        if (!resolved) {
+            logger.error('pikku db codegen: no database configured — set sqliteDb or postgresUrl in your createConfig.');
+            throw new Error('no database configured');
+        }
+        const { migrate, codegen, zod } = await migrateAndCodegen(resolved, {
+            scratch: true,
+        });
+        for (const warning of codegen.warnings) {
+            logger.diagnostic(warning);
+        }
+        logger.info(`db codegen: applied ${migrate.applied.length} migration(s) to a scratch ${resolved.dialect} database`);
+        logger.info(codegen.written
+            ? `db codegen: regenerated ${codegen.outFile} (${codegen.tables.length} tables)`
+            : `db codegen: ${codegen.outFile} unchanged`);
+        logger.info(zod.written
+            ? `db codegen: regenerated ${zod.outFile} (${zod.tables.length} tables)`
+            : `db codegen: ${zod.outFile} unchanged`);
+    },
+});

package/dist/src/functions/commands/db-export.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Publish this package's schema so a project consuming it as an addon can
+ * create its tables.
+ *
+ * An addon has no database of its own — it runs inside the consumer, against
+ * the consumer's — so it must never create tables at boot. It says what it
+ * needs, and the consumer's `db generate` folds that into its own migration
+ * history, where the project can review it like any other migration.
+ *
+ * Run this from the addon's build, beside the rest of its codegen.
+ */
+export declare const dbExport: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/db-export.js

@@ -0,0 +1,31 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pikkuSessionlessFunc } from '#pikku';
+import { exportSchema } from '../db/local-db.js';
+/**
+ * Publish this package's schema so a project consuming it as an addon can
+ * create its tables.
+ *
+ * An addon has no database of its own — it runs inside the consumer, against
+ * the consumer's — so it must never create tables at boot. It says what it
+ * needs, and the consumer's `db generate` folds that into its own migration
+ * history, where the project can review it like any other migration.
+ *
+ * Run this from the addon's build, beside the rest of its codegen.
+ */
+export const dbExport = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const artifact = await exportSchema(config.rootDir);
+        const dialects = Object.keys(artifact);
+        if (dialects.length === 0) {
+            logger.info('db export: no db/sqlite or db/postgres migrations — nothing to publish');
+            return;
+        }
+        const file = join(config.outDir, 'db', 'pikku-db-meta.gen.json');
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+        logger.info(`db export: wrote ${file} for ${dialects.join(', ')}`);
+        logger.info('  Ship it with the package — a consumer resolves it through the package name.');
+    },
+});

package/dist/src/functions/commands/db-generate.js

@@ -1,9 +1,9 @@
 import { pikkuSessionlessFunc } from '#pikku';
-import { resolveDb, generateAuthMigration } from '../db/local-db.js';
+import { resolveDb, generateMigrations } from '../db/local-db.js';
 import { loadUserConfigForDb } from './db-shared.js';
 export const dbGenerate = pikkuSessionlessFunc({
     remote: true,
-    func: async ({ logger, config }) => {
+    func: async ({ logger, config, getInspectorState }) => {
         const userConfig = await loadUserConfigForDb({ config, logger });
         if (!userConfig)
             return;
@@ -12,31 +12,24 @@ export const dbGenerate = pikkuSessionlessFunc({
             logger.error('pikku db generate: no database configured — set sqliteDb or postgresUrl in your createConfig.');
             throw new Error('no database configured');
         }
-        const result = await generateAuthMigration(resolved, config.rootDir, config.srcDirectories, logger);
-        switch (result.status) {
-            case 'no-auth':
-                logger.info('db generate: no pikkuBetterAuth found — nothing to generate');
-                return;
-            case 'up-to-date':
-                logger.info('db generate: Better Auth schema already covered by existing migrations — nothing to generate');
-                return;
-            case 'incremental-unsupported': {
-                const cols = (result.missingColumns ?? [])
-                    .map((m) => `${m.table}(${m.columns.join(', ')})`)
-                    .join('; ');
-                logger.error('db generate: the Better Auth config requires schema changes on top of an existing auth schema:');
-                if (result.missingTables?.length) {
-                    logger.error(`  missing tables: ${result.missingTables.join(', ')}`);
-                }
-                if (cols)
-                    logger.error(`  missing columns: ${cols}`);
-                logger.error('  Write a forward migration adding these by hand (incremental auto-generation is not yet supported).');
-                throw new Error('incremental auth schema change requires a manual migration');
+        const state = await getInspectorState();
+        const addons = [...state.rpc.wireAddonDeclarations.values()].map(({ package: pkg, remote }) => ({ package: pkg, remote }));
+        const { upToDate, written } = await generateMigrations(resolved, config.rootDir, config.srcDirectories, logger, addons);
+        for (const source of upToDate) {
+            logger.info(`db generate: ${source} is already covered by existing migrations`);
+        }
+        if (written.length === 0) {
+            if (upToDate.length === 0) {
+                logger.info('db generate: nothing declares tables — nothing to generate');
+            }
+            return;
+        }
+        for (const { source, file, needsBackfill } of written) {
+            logger.info(`db generate: wrote ${file} for ${source}`);
+            for (const column of needsBackfill) {
+                logger.warn(`  ${column} is NOT NULL with no default — decide what existing rows get before applying.`);
             }
-            case 'written':
-                logger.info(`db generate: wrote ${result.file}`);
-                logger.info('  Review it, then run `pikku db migrate` to apply.');
-                return;
         }
+        logger.info('  Review them, then run `pikku db migrate` to apply.');
     },
 });

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

@@ -1,3 +1,15 @@
+/**
+ * The migrator's own bookkeeping table, which belongs to no dialect and to no
+ * project's schema.
+ *
+ * Every introspector hides it for that reason. Leaving it visible on one
+ * dialect and not the other is not cosmetic: a schema source exported from a
+ * database that has been migrated would publish `sql_migrations` as one of its
+ * own tables, and the consumer — which also has it — would then read the source
+ * as partially covered and emit column deltas instead of the source's own SQL,
+ * silently dropping its primary keys, indexes and constraints.
+ */
+export declare const MIGRATION_TRACKING_TABLE = "sql_migrations";
 export declare class MigrationDriftError extends Error {
     readonly file: string;
     readonly recordedHash: string;
@@ -23,10 +35,29 @@ export interface MigrationExecutor {
     ensureTrackingTable(): Promise<void>;
     getApplied(): Promise<AppliedMigration[]>;
     runMigration(sql: string, name: string, hash: string): Promise<void>;
+    /**
+     * Record a migration as applied without running its SQL.
+     *
+     * For a database that already contains what the migration describes, because
+     * something created those tables before anyone wrote them down. Only ever
+     * called once the caller has confirmed that is actually true — recording a
+     * migration whose tables are absent leaves a database permanently behind with
+     * no pending migration to reveal it.
+     */
+    recordMigration(name: string, hash: string): Promise<void>;
 }
+export declare function migrate(executor: MigrationExecutor, migrationsDir: string): Promise<MigrateResult>;
 /**
- * Apply pending migrations from `migrationsDir/*.sql` using the supplied
- * executor. Hashes raw file bytes on apply; subsequent runs re-hash and bail
- * with `MigrationDriftError` if any applied file has changed on disk.
+ * Record every pending migration as applied, without running any of it.
+ *
+ * The escape hatch for a database that already has the tables a migration
+ * creates — the shape you get when a runtime bootstrapped its own schema at
+ * boot and the migration writing it down was authored afterwards. Running that
+ * migration would fail on every existing deployment; skipping it forever would
+ * leave the history lying. Recording it says what is true.
+ *
+ * Deliberately unconditional here. Whether the database really does match is a
+ * question about schemas, not migration files, so the caller answers it first
+ * and this only runs once it has.
  */
-export declare function migrate(executor: MigrationExecutor, migrationsDir: string): Promise<MigrateResult>;
+export declare function baselineMigrations(executor: MigrationExecutor, migrationsDir: string): Promise<string[]>;

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

@@ -1,6 +1,18 @@
 import { createHash } from 'node:crypto';
-import { readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+/**
+ * The migrator's own bookkeeping table, which belongs to no dialect and to no
+ * project's schema.
+ *
+ * Every introspector hides it for that reason. Leaving it visible on one
+ * dialect and not the other is not cosmetic: a schema source exported from a
+ * database that has been migrated would publish `sql_migrations` as one of its
+ * own tables, and the consumer — which also has it — would then read the source
+ * as partially covered and emit column deltas instead of the source's own SQL,
+ * silently dropping its primary keys, indexes and constraints.
+ */
+export const MIGRATION_TRACKING_TABLE = 'sql_migrations';
 export class MigrationDriftError extends Error {
     file;
     recordedHash;
@@ -31,9 +43,25 @@ function sha256(bytes) {
  * executor. Hashes raw file bytes on apply; subsequent runs re-hash and bail
  * with `MigrationDriftError` if any applied file has changed on disk.
  */
-export async function migrate(executor, migrationsDir) {
-    await executor.ensureTrackingTable();
-    const applied = await executor.getApplied();
+/**
+ * The migrations on disk, or none.
+ *
+ * A project that has never generated a migration has no directory to read, and
+ * that is the ordinary first-run state rather than a failure — it is precisely
+ * the project `db generate` exists to serve.
+ */
+const migrationFiles = (migrationsDir) => existsSync(migrationsDir)
+    ? readdirSync(migrationsDir)
+        .filter((f) => f.endsWith('.sql'))
+        .sort()
+    : [];
+/**
+ * Re-hash every applied migration and bail if one has changed on disk.
+ *
+ * Applies to baselining as much as to migrating: recording a file as applied
+ * only means anything if the file is still the one that was applied.
+ */
+function assertNoDrift(applied, migrationsDir) {
     for (const row of applied) {
         let currentHash = null;
         try {
@@ -46,13 +74,15 @@ export async function migrate(executor, migrationsDir) {
             throw new MigrationDriftError(row.name, row.hash, currentHash, row.applied_at, migrationsDir);
         }
     }
-    const appliedSet = new Set(applied.map((r) => r.name));
-    const files = readdirSync(migrationsDir)
-        .filter((f) => f.endsWith('.sql'))
-        .sort();
+}
+export async function migrate(executor, migrationsDir) {
+    await executor.ensureTrackingTable();
+    const applied = await executor.getApplied();
+    assertNoDrift(applied, migrationsDir);
+    const appliedNames = new Set(applied.map((r) => r.name));
     const result = { applied: [], skipped: [] };
-    for (const name of files) {
-        if (appliedSet.has(name)) {
+    for (const name of migrationFiles(migrationsDir)) {
+        if (appliedNames.has(name)) {
             result.skipped.push(name);
             continue;
         }
@@ -63,3 +93,30 @@ export async function migrate(executor, migrationsDir) {
     }
     return result;
 }
+/**
+ * Record every pending migration as applied, without running any of it.
+ *
+ * The escape hatch for a database that already has the tables a migration
+ * creates — the shape you get when a runtime bootstrapped its own schema at
+ * boot and the migration writing it down was authored afterwards. Running that
+ * migration would fail on every existing deployment; skipping it forever would
+ * leave the history lying. Recording it says what is true.
+ *
+ * Deliberately unconditional here. Whether the database really does match is a
+ * question about schemas, not migration files, so the caller answers it first
+ * and this only runs once it has.
+ */
+export async function baselineMigrations(executor, migrationsDir) {
+    await executor.ensureTrackingTable();
+    const applied = await executor.getApplied();
+    assertNoDrift(applied, migrationsDir);
+    const appliedNames = new Set(applied.map((r) => r.name));
+    const recorded = [];
+    for (const name of migrationFiles(migrationsDir)) {
+        if (appliedNames.has(name))
+            continue;
+        await executor.recordMigration(name, sha256(readFileSync(join(migrationsDir, name))));
+        recorded.push(name);
+    }
+    return recorded;
+}