@rebasepro/server-postgres 0.10.0 → 0.10.1-canary.14e53ae

package/src/backup/backup-cli.ts

@@ -13,19 +13,22 @@ import { logger } from "@rebasepro/server";
 import type { StorageController } from "@rebasepro/server";
 import {
     BackupDestination,
+    globalsFileForDump,
     parseBackupDestination,
     parseDbNameFromUrl,
     resolveConnectionString,
     withDatabaseName
 } from "./pg-tools";
 import {
+    applyGlobals,
     BackupToolError,
     createDump,
     ensureDatabaseExists,
     listBackups,
     preflight,
     restoreDump,
-    uploadBackup
+    uploadBackup,
+    validateDump
 } from "./backup-service";
 
 function formatBytes(bytes: number): string {
@@ -140,8 +143,12 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
                 noOwner: args["--no-owner"],
                 inheritStdio: true
             });
+            await assertDumpValid(dump.localFile);
             logger.info("");
             logger.info(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).`));
+            }
         } else {
             const storage = await resolveStorageForDestination(dest, process.env);
             const dump = await createDump({
@@ -152,12 +159,20 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
                 inheritStdio: true
             });
             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)})`));
+                // 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).`));
+                }
                 logger.info(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("");
@@ -177,6 +192,7 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
             "--create-db": Boolean,
             "--clean": Boolean,
             "--no-owner": Boolean,
+            "--continue-on-error": Boolean,
             "--yes": Boolean,
             "-y": "--yes"
         },
@@ -206,7 +222,11 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
     logger.info("");
 
     // Resolve the local file to restore from (download object-storage keys).
+    // Also resolve the `.globals.sql` roles sidecar so cluster roles can be
+    // recreated before the restore — without them the dump's GRANT/RLS
+    // statements fail and RLS is silently lost.
     let localFile: string;
+    let globalsSql: string | null = null;
     let cleanupTemp = false;
     try {
         if (/^(s3|gs):\/\//.test(backupArg)) {
@@ -221,12 +241,16 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
             localFile = path.join(tmpDir, path.basename(key));
             fs.writeFileSync(localFile, Buffer.from(await file.arrayBuffer()));
             cleanupTemp = true;
+            const globalsObj = await storage.getObject(globalsFileForDump(key), bucket);
+            if (globalsObj) globalsSql = Buffer.from(await globalsObj.arrayBuffer()).toString("utf-8");
         } else {
             localFile = path.resolve(backupArg);
             if (!fs.existsSync(localFile)) {
                 logger.error(chalk.red(`  ✗ Backup file not found: ${localFile}`));
                 process.exit(1);
             }
+            const globalsPath = globalsFileForDump(localFile);
+            if (fs.existsSync(globalsPath)) globalsSql = fs.readFileSync(globalsPath, "utf-8");
         }
 
         // Version pre-flight. Check against the base connection — the server
@@ -261,11 +285,29 @@ 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…"));
+            const { applied, skipped } = await applyGlobals(
+                targetConnection,
+                globalsSql,
+                (m) => logger.info(chalk.gray(m))
+            );
+            logger.info(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."));
+        }
+
         await restoreDump({
             connectionString: targetConnection,
             inputFile: localFile,
             clean: args["--clean"],
             noOwner: args["--no-owner"],
+            // Fail loudly by default so a skipped GRANT never leaves RLS off.
+            exitOnError: !args["--continue-on-error"],
             inheritStdio: true
         });
 
@@ -322,6 +364,17 @@ export async function backupsCommand(rawArgs: string[]): Promise<void> {
     }
 }
 
+/** Verify a freshly written dump; abort the command if it looks corrupt. */
+async function assertDumpValid(localFile: string): Promise<void> {
+    const check = await validateDump(localFile);
+    if (!check.ok) {
+        throw new BackupToolError(
+            `The backup failed validation and was not trusted: ${check.reason}`,
+            "The dump may be corrupt or truncated. Investigate before relying on it."
+        );
+    }
+}
+
 function reportError(err: unknown): void {
     if (err instanceof BackupToolError) {
         logger.error(chalk.red(`  ✗ ${err.message}`));
@@ -364,12 +417,18 @@ ${chalk.green.bold("Options")}
   ${chalk.blue("--create-db")}             Create the target database first if it doesn't exist
   ${chalk.blue("--clean")}                 Drop existing objects before recreating them
   ${chalk.blue("--no-owner")}              Ignore ownership from the dump
+  ${chalk.blue("--continue-on-error")}     Log and continue past errors ${chalk.red("(may leave RLS un-enforced!)")}
   ${chalk.blue("--yes, -y")}               Skip the interactive confirmation ${chalk.red("(destructive!)")}
 
 ${chalk.red.bold("Warning")}
   Restore is destructive and never runs automatically. Without --yes it
   requires an interactive 'yes'. Prefer --create-db/--target-db to restore
   into a fresh database rather than overwriting a live one.
+
+  By default the restore aborts on the first error (--exit-on-error) so a
+  skipped GRANT never silently leaves RLS un-enforced. Roles are recreated
+  from the backup's .globals.sql sidecar first; keep that file next to the
+  dump. Use --continue-on-error only when you understand the consequences.
 `);
 }
 

package/src/backup/backup-cron.ts

@@ -125,7 +125,7 @@ export function createBackupCron(config: BackupCronConfig): CronJobDefinition {
         // Backups of a large database can take a while; allow up to an hour.
         timeoutSeconds: 3600,
         async handler({ log }) {
-            const { createDump, pruneBackups, uploadBackup } = await import("./backup-service");
+            const { createDump, pruneBackups, uploadBackup, validateDump } = await import("./backup-service");
             const { destination } = config;
 
             if (destination.kind !== "local" && !config.storage) {
@@ -145,12 +145,32 @@ export function createBackupCron(config: BackupCronConfig): CronJobDefinition {
             });
             log(`Dump created: ${dump.fileName} (${formatBytes(dump.sizeBytes)})`);
 
+            // Validate BEFORE pruning: a corrupt-but-exit-0 dump must never be
+            // the reason the last good backup gets deleted.
+            const check = await validateDump(dump.localFile);
+            if (!check.ok) {
+                // Clean up the bad temp file for object destinations.
+                if (destination.kind !== "local" && fs.existsSync(dump.localFile)) {
+                    fs.unlinkSync(dump.localFile);
+                }
+                if (dump.globalsFile && destination.kind !== "local" && fs.existsSync(dump.globalsFile)) {
+                    fs.unlinkSync(dump.globalsFile);
+                }
+                throw new Error(`New backup failed validation — skipping upload and pruning to protect existing backups. ${check.reason}`);
+            }
+
             let storedKey = dump.localFile;
             try {
                 if (destination.kind !== "local") {
                     const uploaded = await uploadBackup(config.storage!, dump.localFile, destination);
                     storedKey = uploaded.storageUrl;
                     log(`Uploaded to ${uploaded.storageUrl}`);
+                    // Upload the roles sidecar so a restore can recreate the
+                    // roles the dump's GRANT/RLS statements depend on.
+                    if (dump.globalsFile && fs.existsSync(dump.globalsFile)) {
+                        const g = await uploadBackup(config.storage!, dump.globalsFile, destination);
+                        log(`Uploaded roles sidecar to ${g.storageUrl}`);
+                    }
                 }
             } finally {
                 // For object-storage destinations the local dump was a temp
@@ -158,6 +178,9 @@ export function createBackupCron(config: BackupCronConfig): CronJobDefinition {
                 if (destination.kind !== "local" && fs.existsSync(dump.localFile)) {
                     fs.unlinkSync(dump.localFile);
                 }
+                if (dump.globalsFile && destination.kind !== "local" && fs.existsSync(dump.globalsFile)) {
+                    fs.unlinkSync(dump.globalsFile);
+                }
             }
 
             let pruned: string[] = [];

package/src/backup/backup-logic.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure-ish orchestration for the backup/restore paths, kept free of `execa`
+ * and `pg` value imports so it can be unit-tested under jest (the impure
+ * edges — spawning processes, opening connections — live in
+ * `backup-service.ts`, which is vitest/runtime only).
+ *
+ * The functions here take their side-effecting dependency as an argument
+ * (a statement runner, an object deleter) so tests can inject fakes.
+ */
+import { globalsFileForDump, splitGlobalsStatements } from "./pg-tools";
+
+/**
+ * Replay a `pg_dumpall --globals-only` script one statement at a time,
+ * tolerating per-statement failures. On a same-cluster restore the roles
+ * usually already exist (`CREATE ROLE` → "already exists") and on a managed
+ * provider an `ALTER ROLE <superuser>` may be refused; neither should abort
+ * recreation of the roles that *are* missing. Returns how many statements
+ * applied vs were skipped.
+ *
+ * `runStatement` executes one SQL statement and rejects on error.
+ */
+export async function applyGlobalsWith(
+    runStatement: (sql: string) => Promise<void>,
+    globalsSql: string,
+    log: (message: string) => void = () => {}
+): Promise<{ applied: number; skipped: number }> {
+    let applied = 0;
+    let skipped = 0;
+    for (const statement of splitGlobalsStatements(globalsSql)) {
+        try {
+            await runStatement(statement);
+            applied++;
+        } catch (err) {
+            skipped++;
+            const firstLine = statement.split("\n")[0].slice(0, 80);
+            log(`  • Skipped global: ${firstLine} (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    return { applied, skipped };
+}
+
+/**
+ * Delete each pruned dump together with its `.globals.sql` roles sidecar, so
+ * pruning never orphans the roles file. The sidecar is best-effort — older
+ * backups predate it, so a missing-sidecar failure is swallowed while a
+ * failure deleting the dump itself propagates.
+ *
+ * `deleteObject` removes one key and rejects if it cannot (e.g. not found).
+ */
+export async function pruneWith(
+    keys: string[],
+    deleteObject: (key: string) => Promise<void>
+): Promise<void> {
+    for (const key of keys) {
+        await deleteObject(key);
+        try {
+            await deleteObject(globalsFileForDump(key));
+        } catch {
+            // Sidecar may not exist for older backups — ignore.
+        }
+    }
+}

package/src/backup/backup-service.ts

@@ -17,8 +17,11 @@ import {
     BackupDestination,
     buildBackupFilename,
     buildPgDumpArgs,
+    buildPgDumpallGlobalsArgs,
     buildPgRestoreArgs,
+    buildPgRestoreListArgs,
     checkToolServerCompatibility,
+    globalsFileForDump,
     joinStorageKey,
     parsePgToolMajor,
     parseBackupTimestamp,
@@ -26,6 +29,7 @@ import {
     VersionCompatibility
 } from "./pg-tools";
 import { BackupObject, RetentionOptions, selectBackupsToPrune } from "./retention";
+import { applyGlobalsWith, pruneWith } from "./backup-logic";
 
 export class BackupToolError extends Error {
     constructor(message: string, readonly hint?: string) {
@@ -34,13 +38,16 @@ export class BackupToolError extends Error {
     }
 }
 
-/** Locate `pg_dump` / `pg_restore`, honouring an env override. */
+/** Locate `pg_dump` / `pg_restore` / `pg_dumpall`, honouring an env override. */
 export function resolvePgBinary(
-    tool: "pg_dump" | "pg_restore",
+    tool: "pg_dump" | "pg_restore" | "pg_dumpall",
     env: Record<string, string | undefined> = process.env
 ): string | null {
-    const override = tool === "pg_dump" ? env.PG_DUMP_PATH : env.PG_RESTORE_PATH;
-    if (override && fs.existsSync(override)) return override;
+    const overrideVar =
+        tool === "pg_dump" ? env.PG_DUMP_PATH
+        : tool === "pg_restore" ? env.PG_RESTORE_PATH
+        : env.PG_DUMPALL_PATH;
+    if (overrideVar && fs.existsSync(overrideVar)) return overrideVar;
     return resolveLocalBin(tool);
 }
 
@@ -105,12 +112,23 @@ export interface BackupResult {
     localFile: string;
     fileName: string;
     sizeBytes: number;
+    /**
+     * Absolute path of the `.globals.sql` sidecar holding cluster-wide roles
+     * (present unless globals capture was disabled or unavailable).
+     */
+    globalsFile?: string;
+    globalsSizeBytes?: number;
 }
 
 /**
  * Produce a custom-format dump on local disk. When `outDir` is omitted the
  * file is written to the OS temp directory (used by the upload path, which
  * cleans it up afterwards).
+ *
+ * Alongside the `-Fc` dump it writes a `<name>.globals.sql` sidecar via
+ * `pg_dumpall --globals-only` so the roles the dump's GRANT/RLS statements
+ * depend on can be recreated on restore. Set `includeGlobals: false` to skip
+ * it (e.g. when the caller has no privilege to read cluster globals).
  */
 export async function createDump(opts: {
     connectionString: string;
@@ -120,6 +138,7 @@ export async function createDump(opts: {
     excludeSchemas?: string[];
     noOwner?: boolean;
     inheritStdio?: boolean;
+    includeGlobals?: boolean;
     env?: Record<string, string | undefined>;
 }): Promise<BackupResult> {
     const env = opts.env ?? process.env;
@@ -149,7 +168,91 @@ export async function createDump(opts: {
     });
 
     const sizeBytes = fs.existsSync(localFile) ? fs.statSync(localFile).size : 0;
-    return { localFile, fileName, sizeBytes };
+
+    const result: BackupResult = { localFile, fileName, sizeBytes };
+
+    if (opts.includeGlobals !== false) {
+        const dumpallBin = resolvePgBinary("pg_dumpall", env);
+        if (!dumpallBin) {
+            throw new BackupToolError(
+                "Could not find the 'pg_dumpall' binary needed to capture cluster roles.",
+                "Install the PostgreSQL client tools or set PG_DUMPALL_PATH. " +
+                "To take a role-incomplete backup anyway, pass includeGlobals: false."
+            );
+        }
+        const globalsFile = globalsFileForDump(localFile);
+        await execa(
+            dumpallBin,
+            buildPgDumpallGlobalsArgs({ connectionString: opts.connectionString, outFile: globalsFile }),
+            { stdio: opts.inheritStdio ? "inherit" : "pipe", env: { ...(env as Record<string, string>) } }
+        );
+        result.globalsFile = globalsFile;
+        result.globalsSizeBytes = fs.existsSync(globalsFile) ? fs.statSync(globalsFile).size : 0;
+    }
+
+    return result;
+}
+
+/**
+ * Cheap integrity check on a freshly written dump: it must be non-empty and
+ * `pg_restore --list` must parse its table of contents without error. Used
+ * before pruning older backups so a corrupt-but-exit-0 dump never becomes
+ * the reason the last good backup is deleted.
+ */
+export async function validateDump(
+    localFile: string,
+    env: Record<string, string | undefined> = process.env
+): Promise<{ ok: boolean; reason?: string }> {
+    if (!fs.existsSync(localFile)) {
+        return { ok: false, reason: `Dump file does not exist: ${localFile}` };
+    }
+    if (fs.statSync(localFile).size === 0) {
+        return { ok: false, reason: "Dump file is empty (0 bytes)." };
+    }
+    const bin = resolvePgBinary("pg_restore", env);
+    if (!bin) {
+        // Can't verify without pg_restore; treat as inconclusive-but-fail so
+        // pruning doesn't proceed on an unverified dump.
+        return { ok: false, reason: "Could not find 'pg_restore' to verify the dump." };
+    }
+    try {
+        await execa(bin, buildPgRestoreListArgs(localFile), {
+            stdio: "pipe",
+            env: { ...(env as Record<string, string>) }
+        });
+        return { ok: true };
+    } catch (err) {
+        return { ok: false, reason: `pg_restore --list failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+
+/**
+ * Replay a `pg_dumpall --globals-only` script to recreate cluster roles
+ * before a restore, so the dump's GRANT/RLS statements (which reference
+ * `rebase_user` and any owner roles) actually apply. Runs statement by
+ * statement and tolerates per-statement failures — on a same-cluster restore
+ * the roles usually already exist (`CREATE ROLE` → "already exists"), and on
+ * a managed provider an `ALTER ROLE <superuser>` may be refused; neither
+ * should abort role recreation. Returns how many statements applied vs were
+ * skipped.
+ */
+export async function applyGlobals(
+    connectionString: string,
+    globalsSql: string,
+    log: (message: string) => void = () => {}
+): Promise<{ applied: number; skipped: number }> {
+    const { Client } = await import("pg");
+    const client = new Client({ connectionString });
+    await client.connect();
+    try {
+        return await applyGlobalsWith(
+            async (sql) => { await client.query(sql); },
+            globalsSql,
+            log
+        );
+    } finally {
+        await client.end();
+    }
 }
 
 /**
@@ -157,12 +260,18 @@ export async function createDump(opts: {
  * `connectionString`. Destructive when `clean` is set (drops objects
  * first). Never called automatically — the CLI gates it behind explicit
  * confirmation.
+ *
+ * Runs with `--exit-on-error` by default: a restore that logs-and-continues
+ * past a failed GRANT (because a role was missing) reports success with RLS
+ * un-enforced. Callers should recreate roles first (see {@link applyGlobals})
+ * and only set `exitOnError: false` deliberately.
  */
 export async function restoreDump(opts: {
     connectionString: string;
     inputFile: string;
     clean?: boolean;
     noOwner?: boolean;
+    exitOnError?: boolean;
     inheritStdio?: boolean;
     env?: Record<string, string | undefined>;
 }): Promise<void> {
@@ -178,7 +287,8 @@ export async function restoreDump(opts: {
         connectionString: opts.connectionString,
         inputFile: opts.inputFile,
         clean: opts.clean,
-        noOwner: opts.noOwner
+        noOwner: opts.noOwner,
+        exitOnError: opts.exitOnError
     });
     await execa(bin, args, {
         stdio: opts.inheritStdio ? "inherit" : "pipe",
@@ -288,12 +398,21 @@ export async function pruneBackups(
 ): Promise<string[]> {
     const backups = await listBackups(dest, storage);
     const toDelete = selectBackupsToPrune(backups, options);
-    for (const key of toDelete) {
-        if (dest.kind === "local") {
-            if (fs.existsSync(key)) fs.unlinkSync(key);
-        } else if (storage) {
-            await storage.deleteObject(key, dest.bucket);
-        }
-    }
+
+    // Delete each dump together with its `.globals.sql` sidecar (pruneWith
+    // handles the pairing + best-effort sidecar). The deleter rejects on a
+    // missing key so pruneWith can swallow an absent sidecar.
+    const deleteObject =
+        dest.kind === "local"
+            ? async (key: string) => {
+                if (!fs.existsSync(key)) throw new Error(`not found: ${key}`);
+                fs.unlinkSync(key);
+            }
+            : async (key: string) => {
+                if (!storage) throw new BackupToolError("Storage backend required to prune object backups.");
+                await storage.deleteObject(key, dest.bucket);
+            };
+
+    await pruneWith(toDelete, deleteObject);
     return toDelete;
 }

package/src/backup/pg-tools.ts

@@ -202,7 +202,12 @@ export function buildPgRestoreArgs(opts: {
     inputFile: string;
     /** Drop objects before recreating them (destructive but idempotent). */
     clean?: boolean;
-    /** Continue past individual errors instead of aborting. */
+    /**
+     * Abort on the first error instead of logging and continuing. Defaults
+     * ON: a restore that silently skips failed GRANT/RLS statements (because
+     * a role is missing) "succeeds" with RLS un-enforced — a security hole.
+     * Fail loudly instead so the operator knows the restore is incomplete.
+     */
     exitOnError?: boolean;
     noOwner?: boolean;
 }): string[] {
@@ -213,13 +218,76 @@ export function buildPgRestoreArgs(opts: {
     if (opts.noOwner) {
         args.push("--no-owner");
     }
-    if (opts.exitOnError) {
+    // Default to --exit-on-error unless explicitly disabled.
+    if (opts.exitOnError !== false) {
         args.push("--exit-on-error");
     }
     args.push(opts.inputFile);
     return args;
 }
 
+/**
+ * Assemble the `pg_restore --list` argument vector. Reading a dump's table
+ * of contents parses the whole archive without touching a database, so it is
+ * a cheap integrity check that the file isn't truncated or corrupt.
+ */
+export function buildPgRestoreListArgs(inputFile: string): string[] {
+    return ["--list", inputFile];
+}
+
+/**
+ * Assemble the `pg_dumpall --globals-only` argument vector. Roles (and other
+ * cluster-wide objects) live outside any single database, so a per-database
+ * `pg_dump` omits them. Without the `rebase_user` role the RLS GRANT
+ * statements in the main dump fail on restore and RLS is silently lost — so
+ * every backup captures the globals into a sidecar `.globals.sql`.
+ *
+ * `--no-role-passwords` keeps role secrets out of the artifact (backups may
+ * be shipped off-box); roles are recreated password-less and re-secured by
+ * the operator.
+ */
+export function buildPgDumpallGlobalsArgs(opts: {
+    connectionString: string;
+    outFile: string;
+}): string[] {
+    return [
+        "--globals-only",
+        "--no-role-passwords",
+        "--no-password",
+        `--file=${opts.outFile}`,
+        `--dbname=${opts.connectionString}`
+    ];
+}
+
+/**
+ * Derive the globals sidecar path/key for a given `.dump` file. Keeps the
+ * two artifacts adjacent so listing, uploading and pruning can find one from
+ * the other. A name that doesn't end in `.dump` is returned unchanged with a
+ * `.globals.sql` suffix appended.
+ */
+export function globalsFileForDump(dumpPath: string): string {
+    return dumpPath.endsWith(".dump")
+        ? dumpPath.slice(0, -".dump".length) + ".globals.sql"
+        : dumpPath + ".globals.sql";
+}
+
+/**
+ * Split a `pg_dumpall --globals-only` script into individual statements.
+ * Used when replaying globals on restore so each `CREATE ROLE` / `GRANT`
+ * can run independently and a benign "role already exists" on one doesn't
+ * abort the rest. Drops `--` comment lines and blank statements.
+ */
+export function splitGlobalsStatements(sql: string): string[] {
+    const withoutComments = sql
+        .split("\n")
+        .filter((line) => !line.trim().startsWith("--"))
+        .join("\n");
+    return withoutComments
+        .split(";")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+
 /**
  * Resolve the Postgres connection string the backup commands should use,
  * mirroring the precedence the branch command already relies on.