@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g1822133

package/src/cli.ts

@@ -5,19 +5,25 @@ import path from "path";
 import fs from "fs";
 import { fileURLToPath } from "url";
 import { logger } from "@rebasepro/server";
+import { out, outWarn, outError } from "./cli-output";
+import { formatRelativeTime } from "@rebasepro/utils";
 import {
     diagnoseMissingBin,
     resolveLocalBin,
     getTableIncludes,
     getDevDatabaseUrl,
     ensureDevDatabaseExists,
+    applySearchDdl,
+    getSearchExcludes,
+    readSearchDdl,
+    seedDevDatabaseSearchHelpers,
     getTableExcludes,
     ExcludeIntrospectionError,
     promptConfirm
 } from "./cli-helpers";
 import { checkDatabaseConnectivity, diagnoseDbError } from "./cli-errors";
 import { forLibpq } from "./utils/connection-string";
-import { AUTH_BOOTSTRAP_SQL } from "./schema/auth-bootstrap-sql";
+import { dropLegacyAuthSchema, RLS_BOOTSTRAP_SQL } from "./schema/rls-bootstrap-sql";
 import { detectDestructiveStatements, decidePushSafety } from "./schema/destructive-sql";
 
 const __cliDirname = path.dirname(fileURLToPath(import.meta.url));
@@ -36,7 +42,7 @@ async function loadEnv(): Promise<void> {
 
         for (const p of envPaths) {
             if (fs.existsSync(p)) {
-                const parsed = dotenv.config({ path: p });
+                const parsed = dotenv.config({ path: p, quiet: true });
                 if (parsed.parsed) {
                     for (const [key, val] of Object.entries(parsed.parsed)) {
                         if (process.env[key] === undefined) {
@@ -53,6 +59,13 @@ async function loadEnv(): Promise<void> {
 }
 
 export async function runPluginCommand(args: string[]) {
+    // Also set as an environment variable, not just per `config()` call: this
+    // command spawns `tsx` subprocesses (the schema generator, the DDL
+    // generator, doctor) that load `.env` themselves, and they inherit this.
+    // dotenv reads it before `options.quiet`; an explicit `false` still wins.
+    if (process.env.DOTENV_CONFIG_QUIET === undefined) {
+        process.env.DOTENV_CONFIG_QUIET = "true";
+    }
     await loadEnv();
     const domain = args[0]; // "db" or "schema"
     const subcommand = args[1];
@@ -64,15 +77,22 @@ export async function runPluginCommand(args: string[]) {
     } else if (domain === "doctor") {
         await doctorPluginCommand(args);
     } else {
-        logger.error(chalk.red(`Unknown domain command: ${domain}`));
+        outError(chalk.red(`Unknown domain command: ${domain}`));
         process.exit(1);
     }
 }
 
+/** The migration files on disk, sorted, or none if the directory is absent. */
+function listMigrationFiles(): string[] {
+    const dir = path.resolve(process.cwd(), "drizzle", "migrations");
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter(f => f.endsWith(".sql")).sort();
+}
+
 async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
     const VALID_ACTIONS = ["push", "generate", "migrate", "branch", "backup", "restore", "backups"];
     if (!subcommand || !VALID_ACTIONS.includes(subcommand)) {
-        logger.error(chalk.red(`Unknown db command. Valid: ${VALID_ACTIONS.join(", ")}`));
+        outError(chalk.red(`Unknown db command. Valid: ${VALID_ACTIONS.join(", ")}`));
         process.exit(1);
     }
 
@@ -105,17 +125,19 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
     const collectionsPath = argsList["--collections"] || path.join("..", "config", "collections");
 
     if (subcommand === "generate") {
-        logger.info("");
-        logger.info(chalk.bold("  📦 Rebase DB Generate"));
-        logger.info(chalk.gray("  Step 1/2: Generating Drizzle schema & Postgres DDL from collections..."));
-        logger.info("");
+        out("");
+        out(chalk.bold("  📦 Rebase DB Generate"));
+        out(chalk.gray("  Step 1/2: Generating Drizzle schema & Postgres DDL from collections..."));
+        out("");
         await schemaCommand("generate", rawArgs);
         await generatePostgresDdlCommand(rawArgs);
-        logger.info("");
-        logger.info(chalk.gray("  Step 2/2: Generating SQL migration files with Atlas..."));
-        logger.info("");
+        out("");
+        out(chalk.gray("  Step 2/2: Generating SQL migration files with Atlas..."));
+        out("");
         const migrationName = argsList._[0] || "migration";
+        const migrationsBefore = listMigrationFiles();
         await runAtlas("migrate", ["diff", migrationName, "--dir", "file://drizzle/migrations", "--to", "file://drizzle/schema.sql"], collectionsPath);
+        const wroteNewMigration = listMigrationFiles().length > migrationsBefore.length;
         
         // Post-process the newest migration file
         try {
@@ -136,45 +158,72 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
                         /CREATE SCHEMA (?!IF NOT EXISTS)("[^"]+");/g,
                         "CREATE SCHEMA IF NOT EXISTS $1;"
                     );
+                    // Atlas never writes the search objects into a migration —
+                    // it is not shown them — so a migration replayed against a
+                    // fresh database would build every table except the part
+                    // that makes search work. Appending, because these are
+                    // `ALTER TABLE ... ADD COLUMN` over the tables the
+                    // migration just created.
+                    //
+                    // Only into a migration Atlas just wrote. The file picked
+                    // here is simply the newest one, which when there was no
+                    // diff is a migration that has already run in production:
+                    // editing it changes a hash Atlas has recorded, and the
+                    // appended SQL would never be applied anywhere.
+                    const searchContent = readSearchDdl();
+                    if (searchContent && wroteNewMigration) {
+                        migrationContent = `${migrationContent}\n\n${searchContent}`;
+                        out(chalk.gray("  ✓ Appended search DDL to the migration"));
+                    } else if (searchContent) {
+                        // Reachable whenever a `search` block is the *only*
+                        // thing that changed: Atlas cannot see one, so it finds
+                        // nothing to diff and writes no file.
+                        out(chalk.gray(
+                            "  ℹ Search DDL not written to a migration — this change produced none.\n" +
+                            "    It is applied by `rebase db push`, and at boot by the schema ensure.\n" +
+                            "    For a migration-only deployment, add drizzle/search.sql to a migration by hand."
+                        ));
+                    }
+
                     fs.writeFileSync(newestMigrationFile, migrationContent, "utf-8");
 
-                    // Append RLS policies, preceded by the auth bootstrap so the
+                    // Append RLS policies, preceded by the RLS bootstrap so the
                     // migration is self-contained: Atlas replays migrations
-                    // against a clean dev database where `auth.uid()` would not
-                    // otherwise exist.
+                    // against a clean dev database where `rebase.uid()` would
+                    // not otherwise exist.
                     const policiesFile = path.resolve(process.cwd(), "drizzle", "policies.sql");
                     if (fs.existsSync(policiesFile)) {
                         const policiesContent = fs.readFileSync(policiesFile, "utf-8");
-                        fs.appendFileSync(newestMigrationFile, "\n\n" + AUTH_BOOTSTRAP_SQL + "\n" + policiesContent);
-                        logger.info(chalk.gray(`  ✓ Appended RLS policies to migration file: ${path.basename(newestMigrationFile)}`));
+                        fs.appendFileSync(newestMigrationFile, "\n\n" + RLS_BOOTSTRAP_SQL + "\n" + policiesContent);
+                        out(chalk.gray(`  ✓ Appended RLS policies to migration file: ${path.basename(newestMigrationFile)}`));
                         
                         // Re-hash the migration directory
-                        logger.info(chalk.gray("  Re-hashing migration files..."));
+                        out(chalk.gray("  Re-hashing migration files..."));
                         await runAtlas("migrate", ["hash", "--dir", "file://drizzle/migrations"], collectionsPath);
-                        logger.info(chalk.gray("  ✓ Migration directory checksum updated successfully."));
+                        out(chalk.gray("  ✓ Migration directory checksum updated successfully."));
                     }
                 }
             }
         } catch (err) {
-            logger.warn(chalk.yellow(`  ⚠️  Failed to append policies or re-hash migration: ${err instanceof Error ? err.message : String(err)}`));
+            outWarn(chalk.yellow(`  ⚠️  Failed to append policies or re-hash migration: ${err instanceof Error ? err.message : String(err)}`));
         }
 
-        logger.info("");
-        logger.info(`  You can now run ${chalk.bold.green("rebase db migrate")} to apply the migrations to your database.`);
-        logger.info("");
+        out("");
+        out(`  You can now run ${chalk.bold.green("rebase db migrate")} to apply the migrations to your database.`);
+        out("");
     } else {
-        logger.info("");
-        logger.info(chalk.bold(`  🗄️  Rebase DB ${subcommand.charAt(0).toUpperCase() + subcommand.slice(1)}`));
-        logger.info("");
+        out("");
+        out(chalk.bold(`  🗄️  Rebase DB ${subcommand.charAt(0).toUpperCase() + subcommand.slice(1)}`));
+        out("");
 
         if (subcommand === "push") {
-            logger.info(chalk.gray("  Step 1/3: Generating Drizzle schema & Postgres DDL from collections..."));
-            logger.info("");
+            out(chalk.gray("  Step 1/3: Generating Drizzle schema & Postgres DDL from collections..."));
+            out("");
             await schemaCommand("generate", rawArgs);
             await generatePostgresDdlCommand(rawArgs);
-            logger.info("");
-            logger.info(chalk.gray("  Step 2/3: Pushing schema to database with Atlas..."));
-            logger.info("");
+            out("");
+            out(chalk.gray("  Step 2/3: Pushing schema to database with Atlas..."));
+            out("");
             const databaseUrl = process.env.DATABASE_URL;
             if (databaseUrl) {
                 await ensureAuthSchemaAndFunctions(databaseUrl);
@@ -199,19 +248,19 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
             });
 
             if (destructive.length > 0) {
-                logger.warn(chalk.yellow(`  ⚠️  This push includes ${destructive.length} destructive change(s) that will DESTROY data:`));
-                logger.warn("");
+                outWarn(chalk.yellow(`  ⚠️  This push includes ${destructive.length} destructive change(s) that will DESTROY data:`));
+                outWarn("");
                 for (const d of destructive) {
-                    logger.warn(chalk.red(`       ${d.kind}: `) + chalk.gray(d.statement.replace(/\s+/g, " ")));
+                    outWarn(chalk.red(`       ${d.kind}: `) + chalk.gray(d.statement.replace(/\s+/g, " ")));
                 }
-                logger.warn("");
-                logger.warn(chalk.yellow("  Full planned changes:"));
-                logger.warn(chalk.gray(plan.trim().split("\n").map((l) => `       ${l}`).join("\n")));
-                logger.warn("");
+                outWarn("");
+                outWarn(chalk.yellow("  Full planned changes:"));
+                outWarn(chalk.gray(plan.trim().split("\n").map((l) => `       ${l}`).join("\n")));
+                outWarn("");
 
                 if (decision === "refuse") {
-                    logger.error(chalk.red("  ✗ Aborting: destructive changes require confirmation."));
-                    logger.error(chalk.gray("    Re-run interactively, or pass --allow-destructive to proceed. Back up first: rebase db backup"));
+                    outError(chalk.red("  ✗ Aborting: destructive changes require confirmation."));
+                    outError(chalk.gray("    Re-run interactively, or pass --allow-destructive to proceed. Back up first: rebase db backup"));
                     process.exit(1);
                 }
                 if (decision === "confirm") {
@@ -219,25 +268,30 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
                         chalk.yellow("  Type 'yes' to apply these destructive changes (this cannot be undone): ")
                     );
                     if (!confirmed) {
-                        logger.info(chalk.gray("  Aborted. No changes were made."));
+                        out(chalk.gray("  Aborted. No changes were made."));
                         process.exit(1);
                     }
                 } else {
                     // decision === "apply" via --allow-destructive
-                    logger.warn(chalk.yellow("  Proceeding because --allow-destructive was passed."));
+                    outWarn(chalk.yellow("  Proceeding because --allow-destructive was passed."));
                 }
             }
 
             await runAtlas("schema", ["apply", "--to", "file://drizzle/schema.sql", "--auto-approve"], collectionsPath);
-            logger.info("");
+            out("");
             
             if (databaseUrl) {
                 await ensureAuthTables(databaseUrl, collectionsPath);
+                // After the tables exist and before the policies: the search
+                // column is `ALTER TABLE ... ADD COLUMN`, and a policy may
+                // reference the table it is added to.
+                await applySearchDdl(databaseUrl);
                 await applyPolicies(databaseUrl);
                 await reconcilePolicies(databaseUrl, collectionsPath);
                 await ensureRlsUserRole(databaseUrl);
+                await retireLegacyAuthSchema(databaseUrl);
             } else {
-                logger.warn(chalk.yellow("  ⚠️  DATABASE_URL not found in environment, skipping RLS policies application."));
+                outWarn(chalk.yellow("  ⚠️  DATABASE_URL not found in environment, skipping RLS policies application."));
             }
         } else if (subcommand === "migrate") {
             const databaseUrl = process.env.DATABASE_URL;
@@ -248,12 +302,13 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
             await runAtlas("migrate", ["apply", "--dir", "file://drizzle/migrations", ...extraArgs], collectionsPath);
             if (databaseUrl) {
                 await ensureRlsUserRole(databaseUrl);
+                await retireLegacyAuthSchema(databaseUrl);
             }
         }
 
-        logger.info("");
-        logger.info(chalk.green(`  ✓ rebase db ${subcommand} completed successfully.`));
-        logger.info("");
+        out("");
+        out(chalk.green(`  ✓ rebase db ${subcommand} completed successfully.`));
+        out("");
     }
 }
 
@@ -263,16 +318,20 @@ async function ensureAuthSchemaAndFunctions(databaseUrl: string): Promise<void>
         const client = new Client({ connectionString: databaseUrl });
         await client.connect();
         try {
-            await client.query(AUTH_BOOTSTRAP_SQL);
-            // Runtime-only: pre-create the schema Atlas uses for its revision
-            // table (`--revisions-schema rebase`). Kept out of
-            // AUTH_BOOTSTRAP_SQL so it never enters the migration stream.
-            await client.query("CREATE SCHEMA IF NOT EXISTS rebase");
+            // Creates the `rebase` schema as its first statement, which also
+            // covers the schema Atlas puts its revision table in
+            // (`--revisions-schema rebase`). That used to need a separate,
+            // deliberately migration-stream-excluded statement here, because the
+            // helper functions lived in `auth` and creating `rebase` from the
+            // preamble would have made Atlas plan a DROP for it. The generator
+            // now always declares `rebase` in the desired schema, so there is
+            // nothing to keep out.
+            await client.query(RLS_BOOTSTRAP_SQL);
         } finally {
             await client.end();
         }
     } catch (err) {
-        logger.warn(chalk.yellow(`  ⚠️  Failed to bootstrap auth schema and helper functions: ${err instanceof Error ? err.message : String(err)}`));
+        outWarn(chalk.yellow(`  ⚠️  Failed to bootstrap the RLS helper functions: ${err instanceof Error ? err.message : String(err)}`));
     }
 }
 
@@ -309,7 +368,7 @@ async function ensureAuthTables(databaseUrl: string, collectionsPath: string): P
             await client.end();
         }
     } catch (err) {
-        logger.warn(chalk.yellow(`  ⚠️  Failed to ensure framework auth tables: ${err instanceof Error ? err.message : String(err)}`));
+        outWarn(chalk.yellow(`  ⚠️  Failed to ensure framework auth tables: ${err instanceof Error ? err.message : String(err)}`));
     }
 }
 
@@ -320,19 +379,82 @@ async function ensureAuthTables(databaseUrl: string, collectionsPath: string): P
  * connection would bypass RLS (superuser / BYPASSRLS / table owner).
  */
 async function ensureRlsUserRole(databaseUrl: string): Promise<void> {
-    const { detectConnectionPosture, ensureAppRole, REBASE_USER_ROLE } = await import("./security/rls-enforcement");
-    const { Client } = await import("pg");
-    const client = new Client({ connectionString: databaseUrl });
-    await client.connect();
+    // Every failure in here used to escape uncaught, and `db migrate`'s caller
+    // turns that into a bare `process.exit(1)` — so the migration would apply,
+    // print `-- ok`, and then the command would die with NO output whatsoever
+    // and a non-zero status. Seen with a module-resolution error inside the
+    // dynamic import, where the entire diagnosis was one silent exit code.
+    //
+    // Reported rather than rethrown, and deliberately not fatal: the schema
+    // change has already landed at this point, so failing the command implies a
+    // rollback that did not happen. What is actually lost is the role
+    // provisioning, and the message says so and how to finish it by hand.
+    // No `auth`: the RLS helpers live in `rebase` now, and a schema the
+    // framework no longer creates must not be granted on — on a Supabase
+    // database that would hand the end-user role USAGE on their auth schema.
+    const schemas = ["public", "rebase"];
+    let rls: typeof import("./security/rls-enforcement");
+    try {
+        rls = await import("./security/rls-enforcement");
+    } catch (err) {
+        // A module-resolution failure here is a build problem, not a database
+        // one, and it is exactly the case that used to produce the silent exit.
+        outError(chalk.red(
+            `\n  ✗ Could not load the RLS provisioning module: ${err instanceof Error ? err.message : String(err)}`
+        ));
+        return;
+    }
+
     try {
-        const runSql = async (text: string) => (await client.query(text)).rows as Record<string, unknown>[];
-        const posture = await detectConnectionPosture(runSql);
-        if (posture.privileged) {
-            await ensureAppRole(runSql, ["public", "rebase", "auth"]);
-            logger.info(chalk.gray(`  ✓ RLS role "${REBASE_USER_ROLE}" provisioned/refreshed.`));
+        const { Client } = await import("pg");
+        const client = new Client({ connectionString: databaseUrl });
+        await client.connect();
+        try {
+            const runSql = async (text: string) => (await client.query(text)).rows as Record<string, unknown>[];
+            const posture = await rls.detectConnectionPosture(runSql);
+            if (posture.privileged) {
+                await rls.ensureAppRole(runSql, schemas);
+                out(chalk.gray(`  ✓ RLS role "${rls.REBASE_USER_ROLE}" provisioned/refreshed.`));
+            }
+        } finally {
+            await client.end();
         }
-    } finally {
-        await client.end();
+    } catch (err) {
+        outError(chalk.red(
+            `\n  ✗ The schema change was applied, but the "${rls.REBASE_USER_ROLE}" role could not be ` +
+            `provisioned: ${err instanceof Error ? err.message : String(err)}`
+        ));
+        outError(chalk.gray(rls.appRoleSetupInstructions("your database user", schemas)));
+    }
+}
+
+/**
+ * Retire the pre-1.0 `auth` schema, once nothing depends on it any more.
+ *
+ * Runs last on purpose. Postgres refuses to drop a function an RLS policy still
+ * calls, so this only succeeds after the policies above have been rewritten to
+ * `rebase.uid()`. See `dropLegacyAuthSchema` for what it reports when something
+ * hand-written is still holding the schema open, and DROP_LEGACY_AUTH_SCHEMA_SQL
+ * for the guards that keep it off a Supabase `auth` schema.
+ */
+async function retireLegacyAuthSchema(databaseUrl: string): Promise<void> {
+    try {
+        const { Client } = await import("pg");
+        const client = new Client({ connectionString: databaseUrl });
+        await client.connect();
+        try {
+            await dropLegacyAuthSchema(
+                async (text) => (await client.query(text)).rows as Record<string, unknown>[],
+                {
+                    info: (m) => out(chalk.gray(`  ${m}`)),
+                    warn: (m) => outWarn(chalk.yellow(`  ⚠️  ${m}`))
+                }
+            );
+        } finally {
+            await client.end();
+        }
+    } catch {
+        // Connection-level failure only; the schema is inert either way.
     }
 }
 
@@ -341,8 +463,8 @@ async function applyPolicies(databaseUrl: string): Promise<void> {
         const policiesPath = path.resolve(process.cwd(), "drizzle", "policies.sql");
         if (!fs.existsSync(policiesPath)) return;
         
-        logger.info(chalk.gray("  Step 3/3: Applying RLS policies to database..."));
-        logger.info("");
+        out(chalk.gray("  Step 3/3: Applying RLS policies to database..."));
+        out("");
         
         const policiesContent = fs.readFileSync(policiesPath, "utf-8");
         const { Client } = await import("pg");
@@ -350,16 +472,16 @@ async function applyPolicies(databaseUrl: string): Promise<void> {
         await client.connect();
         try {
             await client.query(policiesContent);
-            logger.info(chalk.green("  ✓ RLS policies applied successfully."));
+            out(chalk.green("  ✓ RLS policies applied successfully."));
         } finally {
             await client.end();
         }
     } catch (err) {
         const hint = diagnoseDbError(err, databaseUrl);
         if (hint) {
-            logger.error(hint);
+            outError(hint);
         } else {
-            logger.error(chalk.red(`  ✗ Failed to apply RLS policies: ${err instanceof Error ? err.message : String(err)}`));
+            outError(chalk.red(`  ✗ Failed to apply RLS policies: ${err instanceof Error ? err.message : String(err)}`));
         }
         process.exit(1);
     }
@@ -393,34 +515,34 @@ async function reconcilePolicies(databaseUrl: string, collectionsPath: string):
             const { dropped, kept } = await dropOrphanedPolicies(client as never, drift, collections);
 
             for (const p of dropped) {
-                logger.info(chalk.gray(`  ✓ Dropped superseded policy "${p.name}" on ${p.schema}.${p.table}`));
+                out(chalk.gray(`  ✓ Dropped superseded policy "${p.name}" on ${p.schema}.${p.table}`));
             }
             if (dropped.length > 0) {
-                logger.info(chalk.green(`  ✓ Removed ${dropped.length} superseded RLS ${dropped.length === 1 ? "policy" : "policies"}.`));
+                out(chalk.green(`  ✓ Removed ${dropped.length} superseded RLS ${dropped.length === 1 ? "policy" : "policies"}.`));
             }
 
             // Custom-named orphans are indistinguishable from policies someone
             // wrote in SQL deliberately, so they are reported, never dropped.
             if (kept.length > 0) {
-                logger.warn(chalk.yellow("  ⚠️  Policies in the database that no collection describes:"));
+                outWarn(chalk.yellow("  ⚠️  Policies in the database that no collection describes:"));
                 for (const p of kept) {
-                    logger.warn(chalk.yellow(`       • ${p.schema}.${p.table} → "${p.name}" (${p.command} TO ${p.roles.join(", ")})`));
+                    outWarn(chalk.yellow(`       • ${p.schema}.${p.table} → "${p.name}" (${p.command} TO ${p.roles.join(", ")})`));
                 }
-                logger.warn(chalk.yellow("       These still grant access. Drop them by hand if they are stale."));
+                outWarn(chalk.yellow("       These still grant access. Drop them by hand if they are stale."));
             }
 
             // Missing/diverged are not push's to fix, but staying silent about
             // them is how a database ends up not matching its config.
             const remaining = { ...drift, orphaned: kept };
             if (hasDrift(remaining) && (remaining.missing.length > 0 || remaining.diverged.length > 0)) {
-                logger.warn(chalk.yellow("  ⚠️  RLS policies do not match your collections:"));
-                logger.warn(formatPolicyDrift({ ...remaining, orphaned: [] }));
+                outWarn(chalk.yellow("  ⚠️  RLS policies do not match your collections:"));
+                outWarn(formatPolicyDrift({ ...remaining, orphaned: [] }));
             }
         } finally {
             await client.end();
         }
     } catch (err) {
-        logger.warn(chalk.yellow(`  ⚠️  Could not reconcile RLS policies: ${err instanceof Error ? err.message : String(err)}`));
+        outWarn(chalk.yellow(`  ⚠️  Could not reconcile RLS policies: ${err instanceof Error ? err.message : String(err)}`));
     }
 }
 
@@ -437,9 +559,9 @@ async function branchCommand(rawArgs: string[]): Promise<void> {
         const dotenv = await import("dotenv");
         const envPath = process.env.DOTENV_CONFIG_PATH;
         if (envPath) {
-            dotenv.config({ path: envPath });
+            dotenv.config({ path: envPath, quiet: true });
         } else {
-            dotenv.config();
+            dotenv.config({ quiet: true });
         }
     } catch {
         // dotenv may not be installed
@@ -447,7 +569,7 @@ async function branchCommand(rawArgs: string[]): Promise<void> {
 
     const databaseUrl = process.env.DATABASE_URL || process.env.ADMIN_CONNECTION_STRING;
     if (!databaseUrl) {
-        logger.error(chalk.red("✗ DATABASE_URL is not set. Make sure your .env file is configured."));
+        outError(chalk.red("✗ DATABASE_URL is not set. Make sure your .env file is configured."));
         process.exit(1);
     }
 
@@ -471,8 +593,8 @@ max: 3 });
             case "create": {
                 const name = rawArgs[3];
                 if (!name) {
-                    logger.error(chalk.red("✗ Branch name is required."));
-                    logger.info(chalk.gray("  Usage: rebase db branch create <name> [--from <source>]"));
+                    outError(chalk.red("✗ Branch name is required."));
+                    out(chalk.gray("  Usage: rebase db branch create <name> [--from <source>]"));
                     process.exit(1);
                 }
                 let source: string | undefined;
@@ -480,81 +602,81 @@ max: 3 });
                 if (fromIdx !== -1 && rawArgs[fromIdx + 1]) {
                     source = rawArgs[fromIdx + 1];
                 }
-                logger.info("");
-                logger.info(chalk.bold("  🌿 Creating database branch..."));
-                logger.info(chalk.gray(`  Name:   ${name}`));
-                if (source) logger.info(chalk.gray(`  Source: ${source}`));
-                logger.info("");
+                out("");
+                out(chalk.bold("  🌿 Creating database branch..."));
+                out(chalk.gray(`  Name:   ${name}`));
+                if (source) out(chalk.gray(`  Source: ${source}`));
+                out("");
                 const branch = await branchService.createBranch(name, source ? { source } : undefined);
-                logger.info(chalk.green(`  ✓ Branch "${branch.name}" created successfully.`));
-                logger.info(chalk.gray(`    Database: rb_${branch.name}`));
-                logger.info(chalk.gray(`    Parent:   ${branch.parentDatabase}`));
-                logger.info("");
+                out(chalk.green(`  ✓ Branch "${branch.name}" created successfully.`));
+                out(chalk.gray(`    Database: rb_${branch.name}`));
+                out(chalk.gray(`    Parent:   ${branch.parentDatabase}`));
+                out("");
                 break;
             }
 
             case "list": {
                 const branches = await branchService.listBranches();
-                logger.info("");
+                out("");
                 if (branches.length === 0) {
-                    logger.info(chalk.gray("  No branches found. Create one with: rebase db branch create <name>"));
+                    out(chalk.gray("  No branches found. Create one with: rebase db branch create <name>"));
                 } else {
-                    logger.info(chalk.bold(`  🌿 ${branches.length} branch(es):`));
-                    logger.info("");
+                    out(chalk.bold(`  🌿 ${branches.length} branch(es):`));
+                    out("");
                     for (const b of branches) {
                         const size = b.sizeBytes != null
                             ? chalk.gray(` (${formatBytes(b.sizeBytes)})`)
                             : "";
                         const age = chalk.gray(` — created ${timeAgo(b.createdAt)}`);
-                        logger.info(`  ${chalk.green("●")} ${chalk.bold(b.name)}${size}${age}`);
-                        logger.info(chalk.gray(`    from ${b.parentDatabase}`));
+                        out(`  ${chalk.green("●")} ${chalk.bold(b.name)}${size}${age}`);
+                        out(chalk.gray(`    from ${b.parentDatabase}`));
                     }
                 }
-                logger.info("");
+                out("");
                 break;
             }
 
             case "delete": {
                 const name = rawArgs[3];
                 if (!name) {
-                    logger.error(chalk.red("✗ Branch name is required."));
-                    logger.info(chalk.gray("  Usage: rebase db branch delete <name>"));
+                    outError(chalk.red("✗ Branch name is required."));
+                    out(chalk.gray("  Usage: rebase db branch delete <name>"));
                     process.exit(1);
                 }
-                logger.info("");
-                logger.info(chalk.bold(`  🗑️  Deleting branch "${name}"...`));
+                out("");
+                out(chalk.bold(`  🗑️  Deleting branch "${name}"...`));
                 await branchService.deleteBranch(name);
-                logger.info(chalk.green(`  ✓ Branch "${name}" deleted.`));
-                logger.info("");
+                out(chalk.green(`  ✓ Branch "${name}" deleted.`));
+                out("");
                 break;
             }
 
             case "info": {
                 const name = rawArgs[3];
                 if (!name) {
-                    logger.error(chalk.red("✗ Branch name is required."));
-                    logger.info(chalk.gray("  Usage: rebase db branch info <name>"));
+                    outError(chalk.red("✗ Branch name is required."));
+                    out(chalk.gray("  Usage: rebase db branch info <name>"));
                     process.exit(1);
                 }
                 const info = await branchService.getBranchInfo(name);
-                logger.info("");
+                out("");
                 if (!info) {
-                    logger.error(chalk.red(`  ✗ Branch "${name}" not found.`));
+                    outError(chalk.red(`  ✗ Branch "${name}" not found.`));
                 } else {
-                    logger.info(chalk.bold(`  🌿 Branch: ${info.name}`));
-                    logger.info(chalk.gray(`    Database: rb_${info.name}`));
-                    logger.info(chalk.gray(`    Parent:   ${info.parentDatabase}`));
-                    logger.info(chalk.gray(`    Created:  ${info.createdAt.toISOString()}`));
+                    out(chalk.bold(`  🌿 Branch: ${info.name}`));
+                    out(chalk.gray(`    Database: rb_${info.name}`));
+                    out(chalk.gray(`    Parent:   ${info.parentDatabase}`));
+                    out(chalk.gray(`    Created:  ${info.createdAt.toISOString()}`));
                     if (info.sizeBytes != null) {
-                        logger.info(chalk.gray(`    Size:     ${formatBytes(info.sizeBytes)}`));
+                        out(chalk.gray(`    Size:     ${formatBytes(info.sizeBytes)}`));
                     }
                 }
-                logger.info("");
+                out("");
                 break;
             }
 
             default:
-                logger.error(chalk.red(`Unknown branch action: "${branchAction}".`));
+                outError(chalk.red(`Unknown branch action: "${branchAction}".`));
                 printBranchHelp();
                 process.exit(1);
         }
@@ -565,7 +687,7 @@ max: 3 });
 }
 
 function printBranchHelp() {
-    logger.info(`
+    out(`
 ${chalk.bold("rebase db branch")} — Database branching commands
 
 ${chalk.green.bold("Usage")}
@@ -599,15 +721,11 @@ function formatBytes(bytes: number): string {
     return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
 }
 
+/** A branch's age, for "…created 6d ago". */
 function timeAgo(date: Date): string {
-    const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
-    if (seconds < 60) return "just now";
-    const minutes = Math.floor(seconds / 60);
-    if (minutes < 60) return `${minutes}m ago`;
-    const hours = Math.floor(minutes / 60);
-    if (hours < 24) return `${hours}h ago`;
-    const days = Math.floor(hours / 24);
-    return `${days}d ago`;
+    // No horizon: a branch created a year ago should still report an age here,
+    // rather than fall back to a bare date in a one-line list entry.
+    return formatRelativeTime(date, { maxMs: Number.POSITIVE_INFINITY }) ?? "unknown";
 }
 
 
@@ -624,28 +742,28 @@ async function runAtlas(
         // other — see `diagnoseMissingBin`. This used to say "Install it with:
         // pnpm add -D @ariga/atlas" unconditionally, which is the exact command
         // that produces the far more common of the two states.
-        logger.error(chalk.red("\n✗ The atlas binary is missing, so the schema cannot be applied.\n"));
+        outError(chalk.red("\n✗ The atlas binary is missing, so the schema cannot be applied.\n"));
 
         if (diagnoseMissingBin("@ariga/atlas") === "build-script-blocked") {
-            logger.error(chalk.yellow("  @ariga/atlas IS installed — only its binary is missing.\n"));
-            logger.error(chalk.gray(
+            outError(chalk.yellow("  @ariga/atlas IS installed — only its binary is missing.\n"));
+            outError(chalk.gray(
                 "  It downloads that binary in a `preinstall` script, and pnpm 10+ does not\n" +
                 "  run a dependency's scripts unless you allow it. The install still exits 0,\n" +
                 "  so the only sign is `Ignored build scripts: @ariga/atlas` in its output.\n"
             ));
-            logger.error("  Fix it with either:\n");
-            logger.error(chalk.bold("    pnpm approve-builds\n"));
-            logger.error("  or, to record it in the project (what `rebase init` scaffolds):\n");
-            logger.error(chalk.bold(
+            outError("  Fix it with either:\n");
+            outError(chalk.bold("    pnpm approve-builds\n"));
+            outError("  or, to record it in the project (what `rebase init` scaffolds):\n");
+            outError(chalk.bold(
                 "    // package.json\n" +
                 "    \"pnpm\": { \"onlyBuiltDependencies\": [\"@ariga/atlas\"] }\n"
             ));
-            logger.error(chalk.gray("  Then re-run `pnpm install`.\n"));
+            outError(chalk.gray("  Then re-run `pnpm install`.\n"));
         } else {
-            logger.error(chalk.gray("  It is not installed in this project.\n"));
-            logger.error("  Install it with:\n");
-            logger.error(chalk.bold("    pnpm add -D @ariga/atlas\n"));
-            logger.error(chalk.gray(
+            outError(chalk.gray("  It is not installed in this project.\n"));
+            outError("  Install it with:\n");
+            outError(chalk.bold("    pnpm add -D @ariga/atlas\n"));
+            outError(chalk.gray(
                 "  If pnpm then reports `Ignored build scripts`, also run `pnpm approve-builds` —\n" +
                 "  the package carries a `preinstall` script that fetches the binary.\n"
             ));
@@ -665,7 +783,7 @@ async function runAtlas(
 
         for (const p of envPaths) {
             if (fs.existsSync(p)) {
-                const parsed = dotenv.config({ path: p });
+                const parsed = dotenv.config({ path: p, quiet: true });
                 if (parsed.parsed) {
                     for (const [key, val] of Object.entries(parsed.parsed)) {
                         if (env[key] === undefined) {
@@ -682,7 +800,7 @@ async function runAtlas(
 
     const databaseUrl = env.DATABASE_URL;
     if (!databaseUrl) {
-        logger.error(chalk.red("✗ DATABASE_URL is not set. Make sure your .env file is configured."));
+        outError(chalk.red("✗ DATABASE_URL is not set. Make sure your .env file is configured."));
         process.exit(1);
     }
 
@@ -693,6 +811,9 @@ async function runAtlas(
 
     const devDatabaseUrl = getDevDatabaseUrl(databaseUrl);
     await ensureDevDatabaseExists(databaseUrl, devDatabaseUrl);
+    if (collectionsPath) {
+        await seedDevDatabaseSearchHelpers(devDatabaseUrl, collectionsPath);
+    }
 
     // Atlas speaks libpq, which rejects the `sslmode=no-verify` that
     // node-postgres accepts — see `forLibpq`. Rewritten only for the argv, so
@@ -719,6 +840,16 @@ async function runAtlas(
         }
     }
 
+    // Search objects are Rebase's, not Atlas's — on both paths. `schema apply`
+    // would drop them as absent from the desired state; `migrate diff` would
+    // write that same drop into the next migration file, where it would sit
+    // waiting to be applied later.
+    if (collectionsPath && (args.includes("apply") || args.includes("diff"))) {
+        for (const exc of await getSearchExcludes(collectionsPath)) {
+            atlasArgs.push("--exclude", exc);
+        }
+    }
+
     if (domain === "schema" && args.includes("apply") && collectionsPath) {
         // Fail CLOSED: the exclude list is the only thing shielding
         // non-collection tables from the auto-approved apply. If we can't
@@ -729,11 +860,11 @@ async function runAtlas(
             excludes = await getTableExcludes(databaseUrl, collectionsPath);
         } catch (err) {
             if (err instanceof ExcludeIntrospectionError) {
-                logger.error(chalk.red("\n✗ Aborting push: could not determine which tables to protect."));
-                logger.error(chalk.gray(`  ${err.message}`));
-                logger.error(chalk.gray("  Refusing to apply — a partial exclude list could drop tables Rebase does not manage."));
+                outError(chalk.red("\n✗ Aborting push: could not determine which tables to protect."));
+                outError(chalk.gray(`  ${err.message}`));
+                outError(chalk.gray("  Refusing to apply — a partial exclude list could drop tables Rebase does not manage."));
                 const hint = diagnoseDbError(err.cause ?? err, databaseUrl);
-                if (hint) logger.error(hint);
+                if (hint) outError(hint);
                 process.exit(1);
             }
             throw err;
@@ -768,11 +899,11 @@ async function runAtlas(
     try {
         await subprocess;
     } catch {
-        logger.error(chalk.red(`\n✗ atlas ${domain} ${args.join(" ")} failed.\n`));
+        outError(chalk.red(`\n✗ atlas ${domain} ${args.join(" ")} failed.\n`));
         // Surface actionable recovery guidance for recognized failures.
         const hint = diagnoseDbError({ message: stderrText }, databaseUrl);
         if (hint) {
-            logger.error(hint);
+            outError(hint);
         }
         process.exit(1);
     }
@@ -802,7 +933,7 @@ async function generatePostgresDdlCommand(rawArgs: string[]): Promise<void> {
     const ddlScript = path.join(__cliDirname, "schema", "generate-postgres-ddl.ts");
     const tsxBin = resolveLocalBin("tsx");
     if (!tsxBin) {
-        logger.error(chalk.red("✗ Could not find tsx binary."));
+        outError(chalk.red("✗ Could not find tsx binary."));
         process.exit(1);
     }
 
@@ -823,12 +954,91 @@ async function generatePostgresDdlCommand(rawArgs: string[]): Promise<void> {
             env: { ...process.env as Record<string, string> }
         });
     } catch (err: unknown) {
-        logger.error(chalk.red(`✗ Failed to run Postgres DDL generator: ${err instanceof Error ? err.message : String(err)}`));
+        outError(chalk.red(`✗ Failed to run Postgres DDL generator: ${err instanceof Error ? err.message : String(err)}`));
+        process.exit(1);
+    }
+}
+
+/**
+ * `schema stale [--fix]` — is the generated Drizzle schema older than the rule
+ * that derives its foreign-key names?
+ *
+ * This exists for one upgrade path and is worth the command. 0.13 derives
+ * `category_id` where 0.12 derived `categorie_id`; boot-ensure renames the
+ * database column to match, and the project's checked-in
+ * `backend/src/schema.generated.ts` is then wrong in a way nothing the developer
+ * did would explain. Relation validation refuses to boot on it, permanently,
+ * because the rename has already been applied and will not run again.
+ *
+ * `rebase dev` calls this with `--fix` before starting the backend, so the
+ * upgrade behaves the way the release note says it does: the column moves and the
+ * project keeps working. Without `--fix` it reports and exits non-zero, which is
+ * what a build or a CI step wants.
+ */
+async function schemaStaleCommand(rawArgs: string[]): Promise<void> {
+    const argsList = arg(
+        {
+            "--collections": String,
+            "--output": String,
+            "--fix": Boolean,
+            "-c": "--collections",
+            "-o": "--output"
+        },
+        { argv: rawArgs.slice(2), permissive: true }
+    );
+
+    const collectionsPath = argsList["--collections"] || path.join("..", "config", "collections");
+    const outputPath = argsList["--output"] || path.join("src", "schema.generated.ts");
+    const schemaFile = path.resolve(process.cwd(), outputPath);
+
+    // No generated schema yet is not staleness — a fresh project has not run the
+    // generator, and saying "stale" about a file that does not exist would send
+    // the reader looking for something to fix.
+    if (!fs.existsSync(schemaFile)) return;
+
+    const { loadCollections } = await import("./schema/doctor");
+    const { findLegacyForeignKeyNames, describeLegacyForeignKeyNames } =
+        await import("./schema/generated-schema-staleness");
+
+    let stale;
+    try {
+        const collections = await loadCollections(path.resolve(process.cwd(), collectionsPath));
+        stale = findLegacyForeignKeyNames(fs.readFileSync(schemaFile, "utf8"), collections);
+    } catch (err) {
+        // Best-effort by design: a collections directory that will not load is a
+        // real error, but it is one the boot reports far better than this does.
+        logger.debug(`schema stale: skipped (${err instanceof Error ? err.message : String(err)})`);
+        return;
+    }
+
+    if (stale.length === 0) return;
+
+    out("");
+    outWarn(chalk.yellow(
+        `  ⚠️  ${outputPath} names ${stale.length} foreign key(s) the way an earlier release did:`
+    ));
+    out(chalk.gray(describeLegacyForeignKeyNames(stale)));
+    out("");
+
+    if (!argsList["--fix"]) {
+        outError(chalk.red(
+            "  The database column has already been renamed at boot, so the generated schema no " +
+            "longer matches it and the server will refuse to start."
+        ));
+        outError(chalk.red("  Run `rebase schema generate` to regenerate it."));
         process.exit(1);
     }
+
+    out(chalk.gray("  Regenerating the Drizzle schema so it matches..."));
+    await schemaCommand("generate", ["schema", "generate", `--collections=${collectionsPath}`, `--output=${outputPath}`]);
 }
 
 async function schemaCommand(subcommand: string, rawArgs: string[]): Promise<void> {
+    if (subcommand === "stale") {
+        await schemaStaleCommand(rawArgs);
+        return;
+    }
+
     if (subcommand === "generate") {
         const argsList = arg(
             {
@@ -849,13 +1059,13 @@ async function schemaCommand(subcommand: string, rawArgs: string[]): Promise<voi
         // If installed in node_modules, __cliDirname is node_modules/@rebasepro/server-postgres/dist or src.
         const generatorScript = path.join(__cliDirname, "schema", "generate-drizzle-schema.ts");
         if (!fs.existsSync(generatorScript)) {
-            logger.error(chalk.red(`✗ Could not find generate-drizzle-schema.ts at ${generatorScript}`));
+            outError(chalk.red(`✗ Could not find generate-drizzle-schema.ts at ${generatorScript}`));
             process.exit(1);
         }
 
         const tsxBin = resolveLocalBin("tsx");
         if (!tsxBin) {
-            logger.error(chalk.red("✗ Could not find tsx binary."));
+            outError(chalk.red("✗ Could not find tsx binary."));
             process.exit(1);
         }
 
@@ -863,9 +1073,9 @@ async function schemaCommand(subcommand: string, rawArgs: string[]): Promise<voi
         const outputPath = argsList["--output"] || path.join("src", "schema.generated.ts");
         const watch = argsList["--watch"] || false;
 
-        logger.info("");
-        logger.info(chalk.bold("  🔧 Rebase Schema Generator"));
-        logger.info("");
+        out("");
+        out(chalk.bold("  🔧 Rebase Schema Generator"));
+        out("");
 
         const cmdParts = [
             tsxBin,
@@ -884,7 +1094,7 @@ async function schemaCommand(subcommand: string, rawArgs: string[]): Promise<voi
                 env: { ...process.env as Record<string, string> }
             });
         } catch (err: unknown) {
-            logger.error(chalk.red(`✗ Failed to run schema generator: ${err instanceof Error ? err.message : String(err)}`));
+            outError(chalk.red(`✗ Failed to run schema generator: ${err instanceof Error ? err.message : String(err)}`));
             process.exit(1);
         }
     } else if (subcommand === "introspect") {
@@ -906,21 +1116,21 @@ async function schemaCommand(subcommand: string, rawArgs: string[]): Promise<voi
 
         const introspectScript = path.join(__cliDirname, "schema", "introspect-db.ts");
         if (!fs.existsSync(introspectScript)) {
-            logger.error(chalk.red(`✗ Could not find introspect-db.ts at ${introspectScript}`));
+            outError(chalk.red(`✗ Could not find introspect-db.ts at ${introspectScript}`));
             process.exit(1);
         }
 
         const tsxBin = resolveLocalBin("tsx");
         if (!tsxBin) {
-            logger.error(chalk.red("✗ Could not find tsx binary."));
+            outError(chalk.red("✗ Could not find tsx binary."));
             process.exit(1);
         }
 
         const outputPath = argsList["--output"] || argsList["--collections"] || path.join("..", "config", "collections");
 
-        logger.info("");
-        logger.info(chalk.bold("  🔍 Rebase Schema Introspector"));
-        logger.info("");
+        out("");
+        out(chalk.bold("  🔍 Rebase Schema Introspector"));
+        out("");
 
         const cmdParts = [
             tsxBin,
@@ -937,11 +1147,11 @@ async function schemaCommand(subcommand: string, rawArgs: string[]): Promise<voi
                 env: { ...process.env as Record<string, string> }
             });
         } catch (err: unknown) {
-            logger.error(chalk.red(`✗ Failed to run schema introspector: ${err instanceof Error ? err.message : String(err)}`));
+            outError(chalk.red(`✗ Failed to run schema introspector: ${err instanceof Error ? err.message : String(err)}`));
             process.exit(1);
         }
     } else {
-        logger.error(chalk.red("Unknown schema command."));
+        outError(chalk.red("Unknown schema command."));
         process.exit(1);
     }
 }
@@ -965,13 +1175,13 @@ async function doctorPluginCommand(rawArgs: string[]): Promise<void> {
 
     const doctorScript = path.join(__cliDirname, "schema", "doctor-cli.ts");
     if (!fs.existsSync(doctorScript)) {
-        logger.error(chalk.red(`✗ Could not find doctor.ts at ${doctorScript}`));
+        outError(chalk.red(`✗ Could not find doctor.ts at ${doctorScript}`));
         process.exit(1);
     }
 
     const tsxBin = resolveLocalBin("tsx");
     if (!tsxBin) {
-        logger.error(chalk.red("✗ Could not find tsx binary."));
+        outError(chalk.red("✗ Could not find tsx binary."));
         process.exit(1);
     }