@rebasepro/server-postgres 0.13.1-canary.gef9608c → 0.14.0

package/src/backup/backup-cli.ts

@@ -9,7 +9,9 @@ import fs from "fs";
 import os from "os";
 import readline from "readline";
 import chalk from "chalk";
-import { logger } from "@rebasepro/server";
+// Aliased: `out` is already a local in two of the commands below (the `--out`
+// backup destination).
+import { out as print, outWarn, outError } from "../cli-output";
 import type { StorageController } from "@rebasepro/server";
 import {
     BackupDestination,
@@ -73,7 +75,7 @@ async function resolveStorageForDestination(
 function requireConnection(): string {
     const conn = resolveConnectionString(process.env);
     if (!conn) {
-        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);
     }
     return conn;
@@ -117,19 +119,19 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
     const out = args["--out"] || process.env.BACKUP_DESTINATION || path.join(process.cwd(), "backups");
     const dest = parseBackupDestination(out);
 
-    logger.info("");
-    logger.info(chalk.bold("  💾 Rebase DB Backup"));
-    logger.info(chalk.gray(`  Database:    ${dbName}`));
-    logger.info(chalk.gray(`  Destination: ${out}`));
-    logger.info("");
+    print("");
+    print(chalk.bold("  💾 Rebase DB Backup"));
+    print(chalk.gray(`  Database:    ${dbName}`));
+    print(chalk.gray(`  Destination: ${out}`));
+    print("");
 
     // Version pre-flight (doctor-style).
     const pf = await preflight("pg_dump", connectionString);
     if (!pf.compatible) {
-        logger.error(chalk.red(`  ✗ ${pf.reason}`));
+        outError(chalk.red(`  ✗ ${pf.reason}`));
         process.exit(1);
     }
-    logger.info(chalk.gray(`  Using pg_dump ${pf.toolMajor} against server ${pf.serverMajor}.`));
+    print(chalk.gray(`  Using pg_dump ${pf.toolMajor} against server ${pf.serverMajor}.`));
 
     // Opt-in, and loud. With row security on, pg_dump stops refusing to read
     // rows it cannot see and starts leaving them out — an exit-0 backup that
@@ -139,13 +141,13 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
         : undefined;
 
     if (rowSecurity) {
-        logger.warn("");
-        logger.warn(chalk.yellow("  ⚠  Dumping with row-level security ON."));
-        logger.warn(chalk.gray(`     Reading as roles [${rowSecurity.roles.join(", ")}], which satisfies the generated`));
-        logger.warn(chalk.gray("     `admin_full_access` policy. This backup contains exactly the rows those"));
-        logger.warn(chalk.gray("     policies admit — a table whose policies have no admin rule comes out short,"));
-        logger.warn(chalk.gray("     and pg_dump will not say so. Prefer granting the dumping role BYPASSRLS."));
-        logger.warn("");
+        outWarn("");
+        outWarn(chalk.yellow("  ⚠  Dumping with row-level security ON."));
+        outWarn(chalk.gray(`     Reading as roles [${rowSecurity.roles.join(", ")}], which satisfies the generated`));
+        outWarn(chalk.gray("     `admin_full_access` policy. This backup contains exactly the rows those"));
+        outWarn(chalk.gray("     policies admit — a table whose policies have no admin rule comes out short,"));
+        outWarn(chalk.gray("     and pg_dump will not say so. Prefer granting the dumping role BYPASSRLS."));
+        outWarn("");
     }
 
     try {
@@ -164,10 +166,10 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
                 rowSecurity
             });
             await assertDumpValid(dump.localFile);
-            logger.info("");
-            logger.info(chalk.green(`  ✓ Backup written to ${dump.localFile} (${formatBytes(dump.sizeBytes)})`));
+            print("");
+            print(chalk.green(`  ✓ Backup written to ${dump.localFile} (${formatBytes(dump.sizeBytes)})`));
             if (dump.globalsFile) {
-                logger.info(chalk.gray(`    ✓ Roles captured to ${dump.globalsFile} (needed so RLS survives a restore).`));
+                print(chalk.gray(`    ✓ Roles captured to ${dump.globalsFile} (needed so RLS survives a restore).`));
             }
         } else {
             const storage = await resolveStorageForDestination(dest, process.env);
@@ -182,21 +184,21 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
             try {
                 await assertDumpValid(dump.localFile);
                 const uploaded = await uploadBackup(storage!, dump.localFile, dest);
-                logger.info("");
-                logger.info(chalk.green(`  ✓ Backup uploaded to ${uploaded.storageUrl} (${formatBytes(dump.sizeBytes)})`));
+                print("");
+                print(chalk.green(`  ✓ Backup uploaded to ${uploaded.storageUrl} (${formatBytes(dump.sizeBytes)})`));
                 // Upload the roles sidecar next to the dump so a restore can
                 // recreate roles the dump's GRANT/RLS statements depend on.
                 if (dump.globalsFile && fs.existsSync(dump.globalsFile)) {
                     const globalsUpload = await uploadBackup(storage!, dump.globalsFile, dest);
-                    logger.info(chalk.gray(`    ✓ Roles uploaded to ${globalsUpload.storageUrl} (needed so RLS survives a restore).`));
+                    print(chalk.gray(`    ✓ Roles uploaded to ${globalsUpload.storageUrl} (needed so RLS survives a restore).`));
                 }
-                logger.info(chalk.gray("    Ensure this bucket is private — backups may contain secrets and PII."));
+                print(chalk.gray("    Ensure this bucket is private — backups may contain secrets and PII."));
             } finally {
                 if (fs.existsSync(dump.localFile)) fs.unlinkSync(dump.localFile);
                 if (dump.globalsFile && fs.existsSync(dump.globalsFile)) fs.unlinkSync(dump.globalsFile);
             }
         }
-        logger.info("");
+        print("");
     } catch (err) {
         reportError(err);
         process.exit(1);
@@ -236,11 +238,11 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
         ? withDatabaseName(baseConnection, args["--target-db"])
         : baseConnection;
 
-    logger.info("");
-    logger.info(chalk.bold("  ♻️  Rebase DB Restore"));
-    logger.info(chalk.gray(`  Source:  ${backupArg}`));
-    logger.info(chalk.gray(`  Target:  ${targetDb ?? "(from DATABASE_URL)"}`));
-    logger.info("");
+    print("");
+    print(chalk.bold("  ♻️  Rebase DB Restore"));
+    print(chalk.gray(`  Source:  ${backupArg}`));
+    print(chalk.gray(`  Target:  ${targetDb ?? "(from DATABASE_URL)"}`));
+    print("");
 
     // Resolve the local file to restore from (download object-storage keys).
     // Also resolve the `.globals.sql` roles sidecar so cluster roles can be
@@ -267,7 +269,7 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
         } else {
             localFile = path.resolve(backupArg);
             if (!fs.existsSync(localFile)) {
-                logger.error(chalk.red(`  ✗ Backup file not found: ${localFile}`));
+                outError(chalk.red(`  ✗ Backup file not found: ${localFile}`));
                 process.exit(1);
             }
             const globalsPath = globalsFileForDump(localFile);
@@ -279,29 +281,29 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
         // exist yet when --create-db is used.
         const pf = await preflight("pg_restore", baseConnection);
         if (!pf.compatible) {
-            logger.error(chalk.red(`  ✗ ${pf.reason}`));
+            outError(chalk.red(`  ✗ ${pf.reason}`));
             process.exit(1);
         }
 
         // Create the target database when requested.
         if (args["--create-db"]) {
             if (!targetDb) {
-                logger.error(chalk.red("  ✗ --create-db requires a resolvable target database name (use --target-db)."));
+                outError(chalk.red("  ✗ --create-db requires a resolvable target database name (use --target-db)."));
                 process.exit(1);
             }
             const created = await ensureDatabaseExists(baseConnection, targetDb);
-            logger.info(chalk.gray(created ? `  ✓ Created database "${targetDb}".` : `  • Database "${targetDb}" already exists.`));
+            print(chalk.gray(created ? `  ✓ Created database "${targetDb}".` : `  • Database "${targetDb}" already exists.`));
         }
 
         // Destructive-action gate. Restores overwrite data; never run without
         // an explicit yes (interactive confirmation or --yes).
         if (!args["--yes"]) {
-            logger.warn(chalk.yellow(
+            outWarn(chalk.yellow(
                 `  ⚠️  This will restore into "${targetDb ?? "the target database"}" and may overwrite existing data.`
             ));
             const confirmed = await promptConfirm(chalk.yellow("     Type 'yes' to continue: "));
             if (!confirmed) {
-                logger.info(chalk.gray("  Aborted. No changes were made."));
+                print(chalk.gray("  Aborted. No changes were made."));
                 process.exit(1);
             }
         }
@@ -309,17 +311,17 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
         // Recreate cluster roles before restoring so GRANT/RLS statements in
         // the dump apply. Best-effort and idempotent (see applyGlobals).
         if (globalsSql) {
-            logger.info(chalk.gray("  Recreating cluster roles from the backup's roles sidecar…"));
+            print(chalk.gray("  Recreating cluster roles from the backup's roles sidecar…"));
             const { applied, skipped } = await applyGlobals(
                 targetConnection,
                 globalsSql,
-                (m) => logger.info(chalk.gray(m))
+                (m) => print(chalk.gray(m))
             );
-            logger.info(chalk.gray(`  ✓ Roles: ${applied} applied, ${skipped} skipped (already present or not permitted).`));
+            print(chalk.gray(`  ✓ Roles: ${applied} applied, ${skipped} skipped (already present or not permitted).`));
         } else {
-            logger.warn(chalk.yellow("  ⚠️  No roles sidecar (.globals.sql) accompanies this backup."));
-            logger.warn(chalk.yellow("     If the dump grants to roles that don't exist (e.g. rebase_user), the restore"));
-            logger.warn(chalk.yellow("     will fail — recreate those roles first, or use a backup that includes its globals."));
+            outWarn(chalk.yellow("  ⚠️  No roles sidecar (.globals.sql) accompanies this backup."));
+            outWarn(chalk.yellow("     If the dump grants to roles that don't exist (e.g. rebase_user), the restore"));
+            outWarn(chalk.yellow("     will fail — recreate those roles first, or use a backup that includes its globals."));
         }
 
         await restoreDump({
@@ -332,9 +334,9 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
             inheritStdio: true
         });
 
-        logger.info("");
-        logger.info(chalk.green(`  ✓ Restore completed into "${targetDb ?? "the target database"}".`));
-        logger.info("");
+        print("");
+        print(chalk.green(`  ✓ Restore completed into "${targetDb ?? "the target database"}".`));
+        print("");
     } catch (err) {
         reportError(err);
         process.exit(1);
@@ -355,7 +357,7 @@ export async function backupsCommand(rawArgs: string[]): Promise<void> {
         return;
     }
     if (action !== "list") {
-        logger.error(chalk.red(`Unknown backups action: "${action}". Valid: list`));
+        outError(chalk.red(`Unknown backups action: "${action}". Valid: list`));
         process.exit(1);
     }
 
@@ -366,19 +368,19 @@ export async function backupsCommand(rawArgs: string[]): Promise<void> {
     try {
         const storage = await resolveStorageForDestination(dest, process.env);
         const backups = await listBackups(dest, storage ?? undefined);
-        logger.info("");
+        print("");
         if (backups.length === 0) {
-            logger.info(chalk.gray(`  No backups found at ${out}.`));
+            print(chalk.gray(`  No backups found at ${out}.`));
         } else {
-            logger.info(chalk.bold(`  💾 ${backups.length} backup(s) at ${out}:`));
-            logger.info("");
+            print(chalk.bold(`  💾 ${backups.length} backup(s) at ${out}:`));
+            print("");
             for (const b of backups) {
                 const when = b.createdAt ? b.createdAt.toISOString() : "unknown date";
                 const name = dest.kind === "local" ? path.basename(b.key) : b.key;
-                logger.info(`  ${chalk.green("●")} ${chalk.bold(name)} ${chalk.gray(`— ${when}`)}`);
+                print(`  ${chalk.green("●")} ${chalk.bold(name)} ${chalk.gray(`— ${when}`)}`);
             }
         }
-        logger.info("");
+        print("");
     } catch (err) {
         reportError(err);
         process.exit(1);
@@ -398,15 +400,15 @@ async function assertDumpValid(localFile: string): Promise<void> {
 
 function reportError(err: unknown): void {
     if (err instanceof BackupToolError) {
-        logger.error(chalk.red(`  ✗ ${err.message}`));
-        if (err.hint) logger.error(chalk.gray(`    ${err.hint}`));
+        outError(chalk.red(`  ✗ ${err.message}`));
+        if (err.hint) outError(chalk.gray(`    ${err.hint}`));
     } else {
-        logger.error(chalk.red(`  ✗ ${err instanceof Error ? err.message : String(err)}`));
+        outError(chalk.red(`  ✗ ${err instanceof Error ? err.message : String(err)}`));
     }
 }
 
 function printBackupHelp(): void {
-    logger.info(`
+    print(`
 ${chalk.bold("rebase db backup")} — Create a database backup (pg_dump, custom format)
 
 ${chalk.green.bold("Usage")}
@@ -442,7 +444,7 @@ ${chalk.green.bold("Notes")}
 }
 
 function printRestoreHelp(): void {
-    logger.info(`
+    print(`
 ${chalk.bold("rebase db restore")} — Restore a database from a backup (pg_restore)
 
 ${chalk.green.bold("Usage")}
@@ -472,7 +474,7 @@ ${chalk.red.bold("Warning")}
 }
 
 function printBackupsHelp(): void {
-    logger.info(`
+    print(`
 ${chalk.bold("rebase db backups")} — Manage stored backups
 
 ${chalk.green.bold("Usage")}

package/src/cli-errors.ts

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { logger } from "@rebasepro/server";
+import { outWarn, outError } from "./cli-output";
 
 /**
  * Detect whether an error (or AggregateError wrapping multiple attempts)
@@ -220,20 +220,20 @@ export async function checkDatabaseConnectivity(databaseUrl: string): Promise<vo
         await client.query("SELECT 1");
     } catch (err: unknown) {
         if (isEconnrefused(err)) {
-            logger.error(formatConnectionRefusedBanner(databaseUrl));
+            outError(formatConnectionRefusedBanner(databaseUrl));
             process.exit(1);
         }
         if (isAuthFailure(err)) {
-            logger.error(formatAuthFailureBanner(databaseUrl));
+            outError(formatAuthFailureBanner(databaseUrl));
             process.exit(1);
         }
         if (isSslNotEnabled(err)) {
-            logger.error(formatSslNotEnabledBanner(databaseUrl));
+            outError(formatSslNotEnabledBanner(databaseUrl));
             process.exit(1);
         }
         // Unknown error — warn but don't block; let the downstream tool surface details
-        logger.warn(chalk.yellow(`  ⚠  Could not verify database connectivity: ${err instanceof Error ? err.message : String(err)}`));
-        logger.warn(chalk.gray("    Proceeding anyway — the command may fail if the database is unreachable."));
+        outWarn(chalk.yellow(`  ⚠  Could not verify database connectivity: ${err instanceof Error ? err.message : String(err)}`));
+        outWarn(chalk.gray("    Proceeding anyway — the command may fail if the database is unreachable."));
     } finally {
         try {
             await client?.end();

package/src/cli-helpers.ts

@@ -6,7 +6,7 @@ import { createRequire } from "module";
 import readline from "readline";
 import { pathToFileURL } from "url";
 import chalk from "chalk";
-import { logger } from "@rebasepro/server";
+import { out, outWarn } from "./cli-output";
 import type { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
 import { moduleDir as __helpersDirname } from "./module-dir";
 
@@ -119,6 +119,19 @@ export async function getTableIncludesFromCollections(allCollections: Collection
 }
 
 export async function getTableIncludes(collectionsPath: string): Promise<string[]> {
+    return getTableIncludesFromCollections(await loadCollectionsForCli(collectionsPath));
+}
+
+/**
+ * Load a project's collections the way the Atlas-facing commands need them.
+ *
+ * Deliberately forgiving — a file that fails to import is skipped rather than
+ * fatal — because the callers use this to *narrow* what Atlas may touch, and a
+ * hard failure here would block a push over an unrelated broken file. Callers
+ * that cannot tolerate a partial answer (the table excludes, which fail closed)
+ * check the result themselves.
+ */
+export async function loadCollectionsForCli(collectionsPath: string): Promise<CollectionConfig[]> {
     // Note: a relative --collections path resolves against the *current working
     // directory*, not the backend package. When invoked via the generated npm
     // script (cwd = backend/), the script uses "../config/collections" to
@@ -127,7 +140,7 @@ export async function getTableIncludes(collectionsPath: string): Promise<string[
     const resolvedPath = path.resolve(collectionsPath);
     const collections: CollectionConfig[] = [];
     if (!fs.existsSync(resolvedPath)) {
-        logger.warn(chalk.yellow(
+        outWarn(chalk.yellow(
             `  ⚠  Collections path not found: "${collectionsPath}"\n` +
             `     Resolved to: ${resolvedPath}\n` +
             `     (relative to cwd: ${process.cwd()})\n` +
@@ -158,7 +171,7 @@ export async function getTableIncludes(collectionsPath: string): Promise<string[
         }
     }
 
-    return getTableIncludesFromCollections(collections);
+    return collections;
 }
 
 export function getDevDatabaseUrl(databaseUrl: string): string {
@@ -185,7 +198,7 @@ export async function ensureDevDatabaseExists(databaseUrl: string, devDatabaseUr
             const res = await client.query("SELECT 1 FROM pg_database WHERE datname = $1", [devDbName]);
             if (res.rowCount === 0) {
                 await client.query(`CREATE DATABASE "${devDbName}"`);
-                logger.info(chalk.gray(`  ✓ Created validation database "${devDbName}"`));
+                out(chalk.gray(`  ✓ Created validation database "${devDbName}"`));
             }
         } finally {
             await client.end();
@@ -195,6 +208,99 @@ export async function ensureDevDatabaseExists(databaseUrl: string, devDatabaseUr
     }
 }
 
+/**
+ * The generated SQL for the project's `search` blocks, if it has any.
+ *
+ * @param drizzleDir directory holding the generated SQL. Defaults to `drizzle`
+ *        under the working directory.
+ */
+export function readSearchDdl(drizzleDir: string = path.resolve(process.cwd(), "drizzle")): string {
+    const searchFile = path.join(drizzleDir, "search.sql");
+    if (!fs.existsSync(searchFile)) return "";
+    return fs.readFileSync(searchFile, "utf-8").trim();
+}
+
+/**
+ * Bring the search column, its index and their helpers up to date.
+ *
+ * Runs *after* Atlas, not before: the statements are `ALTER TABLE ... ADD
+ * COLUMN`, so the table has to exist. Atlas is told to ignore these objects
+ * entirely (`getSearchExcludes`) — it cannot manage them, and left to itself it
+ * would plan a `DROP COLUMN` for every one, since they are absent from the
+ * desired state it was given.
+ *
+ * A no-op when no collection declared `search`. A failure is *not* swallowed:
+ * silently pushing a schema whose search column never appeared is how a
+ * collection ends up with search configured, no error anywhere, and no results.
+ */
+export async function applySearchDdl(
+    databaseUrl: string,
+    drizzleDir: string = path.resolve(process.cwd(), "drizzle")
+): Promise<void> {
+    const sql = readSearchDdl(drizzleDir);
+    if (!sql) return;
+
+    const { Client } = await import("pg");
+    const client = new Client({ connectionString: databaseUrl });
+    await client.connect();
+    try {
+        await client.query(sql);
+    } finally {
+        await client.end();
+    }
+    out(chalk.gray("  ✓ Applied full-text search columns and indexes"));
+}
+
+/**
+ * Glob patterns keeping Atlas away from the search objects.
+ *
+ * Returns an empty list — and so changes nothing — for a project with no
+ * `search` block, which is every project that has not opted in.
+ */
+export async function getSearchExcludes(collectionsPath: string): Promise<string[]> {
+    const { searchExcludePatterns } = await import("./schema/generate-postgres-ddl-logic");
+    return searchExcludePatterns(await loadCollectionsForCli(collectionsPath));
+}
+
+/**
+ * Give the dev database the search helper functions before Atlas plans.
+ *
+ * Excluding the search column keeps Atlas from *diffing* it, but not from
+ * materialising the inspected schema — column and all — in the dev database to
+ * analyse the plan against. That replay is where a push against an
+ * already-searchable database died with `function public.rebase_search_text
+ * (jsonb) does not exist`: the column came across, the function it calls did
+ * not, because Atlas will not carry a function at all.
+ *
+ * Only the extensions and functions, never the tables: the dev database holds
+ * whatever Atlas puts there and nothing of ours.
+ *
+ * Best-effort by design. Failing here would block a push for a project whose
+ * collections merely failed to import, and if the functions really are needed
+ * and really are missing, Atlas says so a moment later in its own words.
+ */
+export async function seedDevDatabaseSearchHelpers(
+    devDatabaseUrl: string,
+    collectionsPath: string
+): Promise<void> {
+    try {
+        const { searchPrerequisiteStatements } = await import("./schema/generate-postgres-ddl-logic");
+        const statements = searchPrerequisiteStatements(await loadCollectionsForCli(collectionsPath));
+        if (statements.length === 0) return;
+
+        const { Client } = await import("pg");
+        const client = new Client({ connectionString: devDatabaseUrl });
+        await client.connect();
+        try {
+            await client.query(statements.join("\n"));
+        } finally {
+            await client.end();
+        }
+    } catch {
+        // See above: not worth failing a push over.
+    }
+}
+
 /**
  * Query the live database for every user table/view outside the system
  * catalogs. Separated from {@link getTableExcludes} so its failure mode can
@@ -255,13 +361,20 @@ export async function getTableExcludes(
     const queryTables = deps.queryExistingTables ?? queryExistingTables;
 
     const includes = await getIncludes(collectionsPath);
-    // Framework-owned schemas Rebase manages itself — the declarative apply
-    // must never touch them. `auth` holds the helper functions; `rebase` holds
-    // the auth tables (users, refresh_tokens, …) and Atlas's own revision
-    // table. Excluding both the schema object AND its contents keeps Atlas
-    // from planning a `DROP SCHEMA … CASCADE` — which on a live database would
-    // take the user/auth tables with it. `atlas_schema_revisions.*` is kept
-    // for backwards-compatibility with any external revision schema.
+    // Schemas the declarative apply must never touch. `rebase` holds the auth
+    // tables (users, refresh_tokens, …), the RLS helper functions and Atlas's
+    // own revision table. Excluding both the schema object AND its contents
+    // keeps Atlas from planning a `DROP SCHEMA … CASCADE` — which on a live
+    // database would take the user/auth tables with it.
+    // `atlas_schema_revisions.*` is kept for backwards-compatibility with any
+    // external revision schema.
+    //
+    // `auth` stays on this list even though Rebase no longer creates it, and
+    // that is the point: on a database still holding the pre-1.0 schema it must
+    // survive until the guarded cleanup retires it, and on a Supabase database
+    // it is somebody else's and must never be in scope at all. Removing it here
+    // would let a `db push` plan `DROP SCHEMA auth CASCADE` against a live
+    // Supabase installation.
     const excludes: string[] = ["atlas_schema_revisions.*", "auth", "auth.*", "rebase", "rebase.*"];
 
     let existingTables: string[];

package/src/cli-output.ts

@@ -0,0 +1,43 @@
+/**
+ * Terminal output for the `rebase db|schema|doctor` commands.
+ *
+ * These commands used to write every line through `logger`, and that is a
+ * category error with three separate consequences:
+ *
+ *  - `logger` prefixes each line with its own level, so a box-drawn report
+ *    arrived as `ℹ️ [INFO]   ┌─ ✗ Missing Column ───` and the frame no longer
+ *    lined up with anything;
+ *  - `logger` is gated by `LOG_LEVEL`, which ships in the scaffold's own
+ *    `.env.example` — a developer who quietened their dev server with
+ *    `LOG_LEVEL=warn` got a `rebase db push` that printed almost nothing and
+ *    still exited non-zero, indistinguishable from a crash;
+ *  - under `NODE_ENV=production` `logger` emits JSON, so the whole report
+ *    became log records with the chalk escape codes embedded in them.
+ *
+ * A CLI's report *is* its return value. It goes to the terminal unconditionally
+ * and unadorned. `packages/cli` has always written its output this way; this is
+ * the same three functions for the plugin CLI that `rebase` delegates to.
+ *
+ * `logger` still belongs in this package's *runtime* — a request handler has no
+ * terminal and its lines want levels, timestamps and redaction. The rule is the
+ * caller, not the severity: anything a developer reads because they typed a
+ * command goes here, anything a server emits while running goes to `logger`.
+ *
+ * Errors and warnings go to stderr so `rebase db push > plan.txt` keeps the
+ * diagnosis on the terminal where it is readable.
+ */
+
+/** One line of human-facing output on stdout. */
+export const out = (line = ""): void => {
+    console.log(line);
+};
+
+/** One line of human-facing warning output on stderr. */
+export const outWarn = (line = ""): void => {
+    console.warn(line);
+};
+
+/** One line of human-facing error output on stderr. */
+export const outError = (line = ""): void => {
+    console.error(line);
+};