@ultimat3/cli 1.2.0 → 3.0.0

package/src/db-backfill.ts

@@ -0,0 +1,401 @@
+// `x db backfill`, everything except the argv: the ledger `--list` reports, the declared-minus-
+// completed diff `--pending` reports, and the gate-plus-enqueue `<name>`/`--all` performs. A
+// driver plus plain strings in, plain data out — the `cmd-jobs.ts` / `jobs-report.ts` split
+// repeated, so every projection here is testable with no `ParsedArgs`, no app boot and no queue.
+// `cmd-db.ts` is the CLI wiring and nothing else.
+//
+// The decisions themselves are `@ultimat3/jobs`': `gateBackfill`, `pendingBackfills` and
+// `registeredBackfills` all live there, because the pass enforces the same rails and two copies of
+// "may this sweep run" would be two answers. What is decided HERE is only what the CLI knows —
+// which names were asked for, whether `--write` was passed, and what `x_migrations` says.
+
+import type { Environment } from '@ultimat3/core';
+import { createContext } from '@ultimat3/core';
+import { db, isLedgerMissing, readLedger } from '@ultimat3/db';
+import type {
+  BackfillDeclaration,
+  BackfillInput,
+  BackfillPendingReport,
+  BackfillProgress,
+  BackfillState,
+  BackfillStatus,
+  JobDriver,
+  JobHandle,
+} from '@ultimat3/jobs';
+import {
+  BACKFILL_STATUSES,
+  BackfillRunningError,
+  BackfillUnknownError,
+  backfillOrigin,
+  gateBackfill,
+  getBackfill,
+  inspectBackfills,
+  isBackfillStatus,
+  isPendingBackfillState,
+  pendingBackfills,
+  registeredBackfills,
+} from '@ultimat3/jobs';
+import { BadFlagError } from './errors';
+import { parseLimitFlag } from './jobs-report';
+import { msg } from './messages';
+import type { Finding, JsonValue } from './output';
+import { findingFrom } from './output';
+import { renderTable } from './table';
+
+/**
+ * The list and the guard are `@ultimat3/jobs`': a status the ledger can record and this flag
+ * rejects is exactly the drift a second copy here would produce.
+ */
+export function parseBackfillStatusFlag(value: string | undefined): BackfillStatus | undefined {
+  if (value === undefined) return undefined;
+  if (isBackfillStatus(value)) return value;
+  throw new BadFlagError({
+    flag: 'status',
+    command: 'db',
+    reason: `unknown status "${value}" (known: ${BACKFILL_STATUSES.join(', ')})`,
+    fix: 'x db backfill --list --json',
+  });
+}
+
+export interface BackfillListFilter {
+  readonly name?: string | undefined;
+  readonly status?: string | undefined;
+  readonly limit?: string | undefined;
+}
+
+/**
+ * Every pass the ledger holds, newest first, filtered by the flags as typed. The empty list is an
+ * ANSWER — a driver with no ledger and an app that has never swept anything are both "nothing has
+ * run", and `inspectBackfills` already refuses to throw for either.
+ */
+export async function listBackfills(
+  driver: JobDriver,
+  filter: BackfillListFilter = {},
+): Promise<readonly BackfillProgress[]> {
+  const status = parseBackfillStatusFlag(filter.status);
+  const limit = parseLimitFlag(filter.limit, 'db');
+  return inspectBackfills(driver, {
+    ...(filter.name === undefined ? {} : { name: filter.name }),
+    ...(status === undefined ? {} : { status }),
+    ...(limit === undefined ? {} : { limit }),
+  });
+}
+
+const HEADER = ['name', 'status', 'rows', 'cursor', 'started-at', 'duration-ms', 'run-id'] as const;
+
+/**
+ * `started-at` is the ledger's own ISO string, printed verbatim and never re-formatted: the repo
+ * forbids a date rendered without an explicit IANA `timeZone`, and not formatting at all is the
+ * one rendering with no zone to get wrong — the same rule `jobs-table.ts` states for `run-at-ms`.
+ * `--json` carries these exact values, so the two renders of one command stay comparable.
+ */
+export function renderBackfillTable(rows: readonly BackfillProgress[]): readonly string[] {
+  const none = msg('cli.db.backfill.none');
+  return renderTable(
+    HEADER,
+    rows.map((row) => [
+      row.name,
+      row.status,
+      String(row.rows),
+      row.cursor ?? none,
+      row.startedAt,
+      row.durationMs === null ? none : String(row.durationMs),
+      row.runId,
+    ]),
+  );
+}
+
+// ── declared minus completed ──────────────────────────────────────────────
+
+/**
+ * Every declaration this app made, judged against every pass the ledger holds. The ledger read is
+ * `inspectBackfills` and never a second one, and the arithmetic is `@ultimat3/jobs`' — this
+ * function is the join and nothing else.
+ */
+export async function pendingReport(
+  driver: JobDriver,
+  environment: Environment,
+): Promise<BackfillPendingReport> {
+  return pendingBackfills({
+    declarations: registeredBackfills(),
+    // Unfiltered and unlimited: a name whose only pass scrolled past a `--limit` would be reported
+    // as never run, which is the one answer this diff must never get wrong.
+    runs: await inspectBackfills(driver, { limit: Number.MAX_SAFE_INTEGER }),
+    environment,
+  });
+}
+
+const PENDING_HEADER = ['name', 'state', 'requires', 'environments', 'last-run-id'] as const;
+
+export function renderPendingTable(report: BackfillPendingReport): readonly string[] {
+  const none = msg('cli.db.backfill.none');
+  return renderTable(
+    PENDING_HEADER,
+    report.rows.map((row) => [
+      row.name,
+      row.state,
+      row.requires ?? none,
+      row.environments === null ? none : row.environments.join('|'),
+      row.lastRunId ?? none,
+    ]),
+  );
+}
+
+export function pendingToJson(report: BackfillPendingReport): JsonValue {
+  return {
+    environment: report.environment,
+    declared: report.rows.length,
+    pending: report.pending.map((row) => row.name),
+    orphaned: [...report.orphaned],
+    rows: report.rows.map((row) => ({
+      name: row.name,
+      state: row.state,
+      checksum: row.checksum,
+      ledgerChecksum: row.ledgerChecksum,
+      changed: row.changed,
+      requires: row.requires,
+      environments: row.environments === null ? null : [...row.environments],
+      lastRunId: row.lastRunId,
+      rows: row.rows,
+    })),
+  };
+}
+
+// ── running one ───────────────────────────────────────────────────────────
+
+/**
+ * Migration ids `x_migrations` records as applied. Three outcomes, and they mean different things:
+ *
+ * | Answer | When | Gate reads it as |
+ * |---|---|---|
+ * | the ids | the ledger was read | exactly what is applied |
+ * | `[]` | `x_migrations` does not exist | nothing applied — every `requires` is unsatisfied |
+ * | `undefined` | no declaration waits on a migration | there is nothing to check |
+ *
+ * An absent table is an ANSWER, never a failure: a database this app has never migrated genuinely
+ * has no applied migration, so `[]` blocks and that is the honest verdict. Everything else —
+ * permission denied, a timeout, a dropped connection, a malformed query — means the check DID NOT
+ * HAPPEN, and those propagate. A gate that read "I could not ask" as "it is applied" would let a
+ * sweep run against exactly the shape it exists to wait for, which is the silent pass this whole
+ * slice exists to remove.
+ *
+ * The read is skipped entirely when nothing declares `requires`: it opens the app's database, and
+ * a command with no question to ask must not fail for want of an answer it will not use.
+ */
+export async function readAppliedMigrations(): Promise<readonly string[] | undefined> {
+  if (!registeredBackfills().some((declaration) => declaration.requires !== null)) return undefined;
+  try {
+    return (await readLedger(db())).map((row) => row.id);
+  } catch (error) {
+    if (isLedgerMissing(error)) return [];
+    throw error;
+  }
+}
+
+/** What one name's turn produced. `planned` is the dry run — `--write` is never implied. */
+export type BackfillAction = 'planned' | 'enqueued' | 'deduped' | 'blocked';
+
+export interface BackfillPlanRow {
+  readonly name: string;
+  readonly action: BackfillAction;
+  readonly state: BackfillState | null;
+  /** The queue row a `--write` created. `null` for every dry run and every refusal. */
+  readonly jobId: string | null;
+  /** What `count()` still matches, when the declaration has one and it could be asked. */
+  readonly remaining: number | null;
+  readonly finding: Finding | null;
+}
+
+/**
+ * `count()` is the same predicate `source` selects on, so this is the one number that keeps a dry
+ * run honest. A tenanted sweep counts within one org — its `ctx.actor` carries none here — so a
+ * throw is reported as `null` rather than guessed at: a dry run that invented a row count is the
+ * failure `count()` exists to close.
+ */
+async function remainingFor(declaration: BackfillDeclaration): Promise<number | null> {
+  if (!declaration.counts) return null;
+  const handle = getBackfill(declaration.name);
+  const count = handle === undefined ? undefined : backfillOrigin(handle)?.count;
+  if (count === undefined) return null;
+  try {
+    return await count({ ctx: createContext({ role: 'migrate' }) });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One shape for `X_BACKFILL_UNKNOWN`, wherever it is raised. Two constructions of one code with
+ * different payloads — one listing the candidate names and one listing none — is a finding an
+ * agent cannot act on half the time, which is the same code meaning two things.
+ */
+const unknownRow = (
+  name: string,
+  state: BackfillState | null,
+  declarations: readonly BackfillDeclaration[],
+): BackfillPlanRow => ({
+  name,
+  action: 'blocked',
+  state,
+  jobId: null,
+  remaining: null,
+  finding: findingFrom(
+    new BackfillUnknownError({ backfill: name, known: declarations.map((row) => row.name) }),
+  ),
+});
+
+export interface BackfillRunInput {
+  readonly driver: JobDriver;
+  /** The names asked for, or every PENDING one when `--all` was passed. */
+  readonly names: readonly string[] | 'all';
+  readonly write: boolean;
+  readonly force: boolean;
+  readonly environment: Environment;
+  readonly appliedMigrations: readonly string[] | undefined;
+}
+
+/**
+ * One turn per name, isolated: a refusal or a throw becomes that name's row and the loop goes on.
+ * That isolation is the whole point of `--all` — one wedged cleanup must not block every later one
+ * forever, which is exactly what a `for` loop over a throwing gate would have done.
+ */
+export async function runBackfills(input: BackfillRunInput): Promise<readonly BackfillPlanRow[]> {
+  const report = await pendingReport(input.driver, input.environment);
+  const declarations = registeredBackfills();
+  const byName = new Map(declarations.map((row) => [row.name, row]));
+  // `--all` sweeps what is PENDING, and `--all --force` every name this environment may run: a
+  // forced rerun of a completed name is a decision, so it is never what a bare `--all` performs.
+  //
+  // Selected by STATE through `@ultimat3/jobs`' own predicate, never by `report.pending.includes`:
+  // that worked only because `pendingBackfills` filters the same array it returns, and the day it
+  // mapped its rows instead, `--all` would have found zero targets, exited 0 and reported that
+  // nothing needed sweeping — the silent success this slice exists to remove, reintroduced by an
+  // identity check nobody could see from here.
+  const targets =
+    input.names === 'all'
+      ? report.rows
+          .filter((row) =>
+            input.force ? row.state !== 'excluded' : isPendingBackfillState(row.state),
+          )
+          .map((row) => row.name)
+      : input.names;
+
+  const rows: BackfillPlanRow[] = [];
+  for (const name of targets) {
+    const declaration = byName.get(name);
+    const state = report.rows.find((row) => row.name === name)?.state ?? null;
+    if (declaration === undefined) {
+      rows.push(unknownRow(name, state, declarations));
+      continue;
+    }
+    const verdict = gateBackfill({
+      declaration,
+      environment: input.environment,
+      appliedMigrations: input.appliedMigrations,
+      // Only fetched for a name the diff already judged completed — the gate wants the row, and
+      // the diff is what knows whether there is one to want.
+      completed: state === 'completed' ? await newestCompleted(input.driver, name) : undefined,
+      force: input.force,
+    });
+    if (!verdict.run) {
+      rows.push({
+        name,
+        action: 'blocked',
+        state,
+        jobId: null,
+        remaining: null,
+        finding: findingFrom(verdict.error),
+      });
+      continue;
+    }
+    const remaining = await remainingFor(declaration);
+    if (!input.write) {
+      rows.push({ name, action: 'planned', state, jobId: null, remaining, finding: null });
+      continue;
+    }
+    // `getBackfill` cannot answer undefined here — `declaration` came from `registeredBackfills()`,
+    // which is derived from the same registry — so the handle is resolved once, at the only place
+    // that already proved the name exists. Resolving it again inside `enqueueOne` meant a second
+    // `X_BACKFILL_UNKNOWN` that could not list the candidates the first one lists.
+    const handle = getBackfill(name);
+    if (handle === undefined) {
+      rows.push(unknownRow(name, state, declarations));
+      continue;
+    }
+    rows.push(await enqueueOne(handle, state, remaining, input.force));
+  }
+  return rows;
+}
+
+const newestCompleted = async (
+  driver: JobDriver,
+  name: string,
+): Promise<BackfillProgress | undefined> =>
+  (await inspectBackfills(driver, { name, status: 'completed', limit: 1 }))[0];
+
+/**
+ * The queue is a job's execution surface, so `--write` ENQUEUES and never runs the pass inline —
+ * the rule `handle.as()` already states. That is also what makes `ROLE=backfill` a trigger rather
+ * than a gate: the container puts the sweeps on the queue and exits, and the workers already
+ * serving the new release are what drain them.
+ */
+async function enqueueOne(
+  handle: JobHandle<BackfillInput>,
+  state: BackfillState | null,
+  remaining: number | null,
+  force: boolean,
+): Promise<BackfillPlanRow> {
+  const name = handle.name;
+  try {
+    const result = await handle.enqueue({ force });
+    // One live pass per name, forced or not. A deduped enqueue started nothing, so the operator who
+    // asked for a pass has to hear about the one already holding the key.
+    return result.deduped
+      ? {
+          name,
+          action: 'deduped',
+          state,
+          jobId: result.id,
+          remaining,
+          finding: findingFrom(new BackfillRunningError({ backfill: name, jobId: result.id })),
+        }
+      : { name, action: 'enqueued', state, jobId: result.id, remaining, finding: null };
+  } catch (error) {
+    return { name, action: 'blocked', state, jobId: null, remaining, finding: findingFrom(error) };
+  }
+}
+
+const PLAN_HEADER = ['name', 'action', 'state', 'remaining', 'job-id'] as const;
+
+export function renderPlanTable(rows: readonly BackfillPlanRow[]): readonly string[] {
+  const none = msg('cli.db.backfill.none');
+  return renderTable(
+    PLAN_HEADER,
+    rows.map((row) => [
+      row.name,
+      row.action,
+      row.state ?? none,
+      row.remaining === null ? none : String(row.remaining),
+      row.jobId ?? none,
+    ]),
+  );
+}
+
+export function planToJson(rows: readonly BackfillPlanRow[]): JsonValue {
+  return rows.map((row) => ({
+    name: row.name,
+    action: row.action,
+    state: row.state,
+    remaining: row.remaining,
+    jobId: row.jobId,
+    finding:
+      row.finding === null
+        ? null
+        : {
+            code: row.finding.code,
+            cause: row.finding.cause,
+            fix: row.finding.fix,
+            docs: row.finding.docs ?? null,
+          },
+  }));
+}

package/src/db-branch.ts

@@ -0,0 +1,269 @@
+// What a branch database IS, for the two databases `x db` can be pointed at: the closed set of
+// verbs, the name a branch takes on disk or in `pg_database`, and list/create/drop for each mode.
+// Plain inputs, plain rows — no `ParsedArgs`, no `CommandResult` — so every rule here is testable
+// against a temp directory and a recording client, and `cmd-db-branch.ts` owns only the wiring.
+
+// `node:fs/promises` for `readdir`/`rm`/`stat` — Bun exposes no directory listing, no recursive
+// delete and no birthtime. `node:path` for the joiner Bun also does not have.
+import { readdir, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import type { DbClient } from '@ultimat3/db';
+import {
+  assertBranchName,
+  branchPglite,
+  createBranch,
+  currentDatabase,
+  dropBranch,
+  listBranches,
+  pgliteBranchDir,
+  pgliteDataDir,
+} from '@ultimat3/db';
+
+/**
+ * The closed set `x db branch` takes as its first positional, and the reason a branch name can no
+ * longer be mistaken for one. `x db branch <name>` read its argument as a name, so `x db branch
+ * ls` — a fix line three shipped errors hand out — cloned a database called `ls`.
+ *
+ * `reap` is deliberately absent: a nightly sweep is a `task` (`reapBranches` from `@ultimat3/db`),
+ * and a CLI verb for it would be a second path to one job with a max-age nobody can default.
+ */
+export const BRANCH_SUBCOMMANDS = ['ls', 'create', 'drop'] as const;
+
+export type BranchSubcommand = (typeof BRANCH_SUBCOMMANDS)[number];
+
+export const isBranchSubcommand = (word: string): word is BranchSubcommand =>
+  (BRANCH_SUBCOMMANDS as readonly string[]).includes(word);
+
+/**
+ * `@ultimat3/db` owns what a branch name may be (`[a-z0-9_-]+`, validated before it reaches a path
+ * or a `CREATE DATABASE`). Asked through its own assertion rather than re-spelled here, because a
+ * second copy of that regex is a second answer to "is this safe to interpolate".
+ */
+export function isBranchName(value: string): boolean {
+  try {
+    assertBranchName(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The database a connection URL names. `url.split('/').at(-1)` took the query string with it, so
+ * a refusal built from it named `postly?sslmode=require_branch_x` — a database that does not exist
+ * — in a message whose whole point is that a reader can check it. `pathname` is the one part that
+ * IS the database, and it arrives percent-encoded, which `pg_database` does not.
+ *
+ * Falls back rather than throwing: the caller is already reporting a failure, and a second throw
+ * from the reporter replaces a checkable refusal with a stack trace.
+ */
+export function databaseNameOf(url: string, fallback = 'postgres'): string {
+  try {
+    const name = decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+    return name === '' ? fallback : name;
+  } catch {
+    return fallback;
+  }
+}
+
+/** Where a branch's app answers once something serves it — the preview half of the design. */
+export const previewUrl = (branch: string, port: number): string =>
+  `http://${branch}.localhost:${port}`;
+
+/** One branch, whichever database it lives in. */
+export interface BranchRow {
+  readonly name: string;
+  /** Where it lives: a database name, or a PGlite data directory. Point `DATABASE_URL` at it. */
+  readonly location: string;
+  /** `null` where nothing recorded one — the embedded copy keeps no creation record of its own. */
+  readonly createdAt: string | null;
+  /** `null` where measuring it would cost a full walk of the branch. */
+  readonly sizeBytes: number | null;
+}
+
+/** `x db branch create <name>` on a real Postgres clones into `<source>_branch_<name>`. */
+export function branchDatabaseName(source: string, branch: string): string {
+  return `${source}_branch_${branch.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+}
+
+/**
+ * The reverse asked of NO source, and the ONE reader of it: `mcp-db-target.ts` decides whether
+ * `db.migrate` is aimed at a private database from a URL alone, with no connection to ask
+ * `current_database()` — so "a branch of somebody" is the only question it can pose, and the
+ * answer it wants for `analytics_branch_feat` is still "not the shared database". Anything holding
+ * a client asks `branchNameIn` instead, which is the question `ls` and `drop` need.
+ */
+export const branchNameOf = (database: string): string | null =>
+  /_branch_(.+)$/.exec(database)?.[1] ?? null;
+
+/**
+ * The same reverse asked of ONE source: is `database` a branch of `source`, and of what name?
+ * `branchNameOf` cannot answer that — it finds the first `_branch_` in any database on the server,
+ * so `analytics_branch_feat` reduced to `feat` for a session connected to `postly`, and
+ * `postly_branch_a_branch_b` reduced to `a_branch_b` for one connected to `postly_branch_a`.
+ * The exact inverse of `branchDatabaseName`, which is what makes a listed name safe to drop:
+ * `branchNameIn(s, branchDatabaseName(s, b))` is `b` with the same substitution applied.
+ */
+export function branchNameIn(source: string, database: string): string | null {
+  const prefix = `${source}_branch_`;
+  return database.startsWith(prefix) ? database.slice(prefix.length) : null;
+}
+
+/**
+ * The embedded peer: `branchPglite` copies `<dir>` to `<dir>-<name>`, so the branch name is the
+ * suffix. `pgliteBranchDir` is the forward rule and this is its inverse — written once, because
+ * `x db branch ls` and the MCP host's branch check must agree about what a branch directory is.
+ */
+export function pgliteBranchName(dir: string, source: string): string | null {
+  return dir.startsWith(`${source}-`) ? dir.slice(source.length + 1) : null;
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The directory's own creation time, which is when the copy landed. `branchPglite` returns a
+ * `createdAt` and persists it nowhere, so this is the only record there is — and filesystems that
+ * keep none report 0, which is answered as "unknown" rather than as 1970.
+ */
+async function createdAtOf(path: string): Promise<string | null> {
+  try {
+    const birth = (await stat(path)).birthtimeMs;
+    return birth > 0 ? new Date(birth).toISOString() : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function listPgliteBranches(url: string): Promise<readonly BranchRow[]> {
+  const source = pgliteDataDir(url);
+  const parent = dirname(source);
+  let entries: readonly string[];
+  try {
+    entries = await readdir(parent);
+  } catch {
+    // Nothing has run against this app yet. "No branches" is the honest answer to the question.
+    return [];
+  }
+  const rows: BranchRow[] = [];
+  for (const entry of entries.toSorted((a, b) => a.localeCompare(b))) {
+    const name = pgliteBranchName(entry, basename(source));
+    if (name === null) continue;
+    const location = join(parent, entry);
+    if (!(await isDirectory(location))) continue;
+    rows.push({ name, location, createdAt: await createdAtOf(location), sizeBytes: null });
+  }
+  return rows;
+}
+
+/** Where a branch WOULD live — what a refusal names, so it can be checked rather than believed. */
+export const pgliteBranchLocation = (url: string, branch: string): string =>
+  pgliteBranchDir(pgliteDataDir(url), branch);
+
+export async function createPgliteBranch(url: string, branch: string): Promise<BranchRow> {
+  const info = await branchPglite(branch, { from: url });
+  return {
+    name: info.name,
+    location: info.dataDir,
+    createdAt: info.createdAt,
+    sizeBytes: info.sizeBytes,
+  };
+}
+
+/**
+ * Answers whether there was a branch there, exactly as `dropBranch` does. The name is asserted
+ * before it reaches a path: it is spliced into a directory name, so an unvalidated one is
+ * traversal rather than a typo — and `pgliteBranchDir` can never resolve to the source itself.
+ */
+export async function dropPgliteBranch(url: string, branch: string): Promise<boolean> {
+  assertBranchName(branch);
+  const dir = pgliteBranchDir(pgliteDataDir(url), branch);
+  if (!(await isDirectory(dir))) return false;
+  await rm(dir, { recursive: true, force: true });
+  return true;
+}
+
+/**
+ * Branches OF `source`: `createBranch`'s marker comment AND this source's own prefix. The marker
+ * alone is not enough, and that is the whole reason this takes a source at all — it records when a
+ * clone was made and never what it was cloned from, so one Postgres server hosting two Ultimate
+ * apps answers `listBranches()` with both apps' clones and `postly_branch_feat` and
+ * `analytics_branch_feat` both reduce to the branch name `feat`.
+ */
+async function branchesOf(client: DbClient, source: string): Promise<readonly BranchRow[]> {
+  const rows: BranchRow[] = [];
+  for (const branch of await listBranches({ client })) {
+    const name = branchNameIn(source, branch.name);
+    if (name === null) continue;
+    rows.push({
+      name,
+      location: branch.name,
+      createdAt: branch.createdAt,
+      sizeBytes: branch.sizeBytes,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Only databases carrying `createBranch`'s own marker comment, and only branches of the database
+ * this session is connected to. A database this listing does not name is one `drop` may not touch,
+ * which is what makes "you may only drop what `ls` shows" a guard rather than a courtesy — and a
+ * row belonging to another app on the same server made that guard answer for a database it had
+ * never seen.
+ */
+export async function listExternalBranches(client: DbClient): Promise<readonly BranchRow[]> {
+  return branchesOf(client, await currentDatabase(client));
+}
+
+/**
+ * Through `createBranch`, never a hand-written `CREATE DATABASE`: it validates the name, refuses a
+ * database that already exists with `X_BRANCH_EXISTS`, and writes the marker comment that makes
+ * the clone visible to `ls`. The CLI shelled out to `psql` until now and wrote no marker at all,
+ * so every branch it made was invisible to the only lister the framework has.
+ */
+export async function createExternalBranch(client: DbClient, branch: string): Promise<BranchRow> {
+  const source = await currentDatabase(client);
+  const database = branchDatabaseName(source, branch);
+  const info = await createBranch(database, { client, base: source });
+  return {
+    // The name `ls` will show for it, derived the way `ls` derives one — a create that reported a
+    // name the listing then spells differently is a `drop` the caller has to guess at.
+    name: branchNameIn(source, database) ?? database,
+    location: database,
+    createdAt: info.createdAt,
+    // `createBranch` reports 0 for a database it has not measured; unknown is the truthful word.
+    sizeBytes: null,
+  };
+}
+
+/**
+ * `force`, because a branch exists to be thrown away and its own sessions must not outvote that.
+ *
+ * The listing is the guard, so it is taken HERE — on the connection about to issue the `DROP`, one
+ * statement before it — and never accepted from a caller that listed earlier. Two things it closes:
+ * a name approved by another app's clone (the listing is now this source's alone), and a database
+ * that merely LOOKS like a branch of this one — `postly_branch_feat` with no marker is somebody
+ * else's database and `drop database if exists` would have taken it without asking.
+ *
+ * It is not atomic and cannot be: `DROP DATABASE` runs in no transaction, so no single statement
+ * can both verify the marker and delete. What remains is the gap between two adjacent statements on
+ * one session — another process dropping and recreating `<source>_branch_<name>` inside it would
+ * have this drop take the new one. Closing that needs a lock around both halves inside
+ * `@ultimat3/db`'s own `dropBranch`, which is where the `DROP` lives; a `psql` at the next terminal
+ * would still not hold it.
+ */
+export async function dropExternalBranch(client: DbClient, branch: string): Promise<boolean> {
+  const source = await currentDatabase(client);
+  // Matched on the DATABASE, not on the listed name: `branchDatabaseName` substitutes `-` for `_`,
+  // so `feat-x` and `feat_x` are one clone and both spellings must reach it.
+  const database = branchDatabaseName(source, branch);
+  const listed = await branchesOf(client, source);
+  if (!listed.some((row) => row.location === database)) return false;
+  return dropBranch(database, { client, force: true });
+}