@everystack/cli 0.3.23 → 0.3.27

package/README.md

@@ -223,6 +223,10 @@ everystack db:diff                      # the state edge between two declared st
 everystack db:plan | db:apply           # mint a reviewable plan against a target, apply it fingerprint-verified at both ends + the fast-forward rule (checkout must descend from the commit declaring the target's state); destructive plans: --confirm + snapshot + approver set when declared
 everystack db:check                     # the CI gate per PR: merged declared state composes + artifacts match regeneration (+ ephemeral from-scratch build w/ a scratch PG)
 everystack db:approvers                 # declare who can DESTROY: the stage's destructive-approver set (SSM, STS-verified at apply)
+everystack db:backfill                  # one-shot data jobs in db/backfills/*.sql — content-hash identity, own per-DB record, never a schema side effect
+everystack db:template:refresh          # (re)build the dev template from the declared state + your db:seed script — never a data copy
+everystack db:branch                    # per-branch dev DB minted from the template, keyed on the git branch (--list / --prune --confirm)
+everystack db:fork                      # fork a deployed stage's DB into a feature stage (backup → presigned hand-off → restore); production is never a target
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.23",
+  "version": "0.3.27",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/backfill.ts

@@ -0,0 +1,231 @@
+/**
+ * backfill — one-shot data jobs in their own lane (brick 8 of the
+ * migration-authority design, decision 15).
+ *
+ * Schema is fingerprint-governed; DATA has no live authority to fingerprint,
+ * so the backfill lane is the one place a per-database ledger is correct:
+ * `everystack.backfill_log` records what ran here, and the runner READS it —
+ * unlike `schema_log`, which stays a write-only memoir. The distrust that
+ * killed the migration tape doesn't transfer: nothing is numbered, nothing
+ * is watermarked, and identity is the NORMALIZED CONTENT HASH (the same
+ * comment-insensitive, dollar-quote-aware lexing as db/sql) — renaming a
+ * file or editing a comment is a no-op, never a re-run.
+ *
+ * One-shot jobs are IMMUTABLE. A file whose name already ran on this
+ * database in a different form is BLOCKED, loudly, with the fix named: a
+ * genuinely new job gets a new file; a cosmetic-but-not-comment edit gets
+ * `--mark-applied`. Never silently re-run, never silently skipped. A prior
+ * FAILED run is a retry, not an edit — it stays pending.
+ *
+ * Backfills never run as a side effect of a schema apply (expand →
+ * backfill → contract is a sequence of deliberate acts); the schema verbs
+ * only SURFACE pending backfills as notices. Long-running smells get an
+ * advisory naming the jobs lane — advisory only, taste is not enforced.
+ */
+
+import { createHash } from 'node:crypto';
+import { lex, normalizeSql, splitSqlStatements, type SourceFile } from './derived-source.js';
+import { escapeLiteral } from './derived-apply.js';
+import type { QueryRunner } from './authz-contract.js';
+
+// ---------------------------------------------------------------------------
+// Identity + advisories (pure).
+// ---------------------------------------------------------------------------
+
+/** The job's identity: sha256 over the comment-insensitive canonical form. */
+export function backfillIdentity(sql: string): string {
+  return createHash('sha256').update(normalizeSql(sql)).digest('hex');
+}
+
+/**
+ * The statement with comments dropped and quoted content blanked — a shape
+ * regexes can interrogate without being fooled by `'WHERE it hurts'`.
+ */
+function sqlSkeleton(sql: string): string {
+  let out = '';
+  lex(sql, (ch, state) => {
+    if (state === 'line-comment' || state === 'block-comment') return;
+    if (state === 'single' || state === 'dollar') return; // quoted content blanked
+    out += ch;
+  });
+  return out;
+}
+
+/** Advisory only — an unbounded data pass belongs in the jobs lane, but taste never blocks. */
+export function backfillAdvisories(sql: string): string[] {
+  const advisories: string[] = [];
+  for (const statement of splitSqlStatements(sql)) {
+    const skeleton = sqlSkeleton(statement);
+    const verb = skeleton.match(/^\s*(UPDATE|DELETE)\b/i)?.[1];
+    if (verb && !/\bWHERE\b/i.test(skeleton)) {
+      advisories.push(
+        `${verb.toUpperCase()} without WHERE — an unbounded pass over the table. Fine for small tables; for big ones, batch it or run it as a job (@everystack/jobs).`,
+      );
+    }
+  }
+  return advisories;
+}
+
+// ---------------------------------------------------------------------------
+// Planning (pure).
+// ---------------------------------------------------------------------------
+
+export interface BackfillRecord {
+  name: string;
+  identity: string;
+  outcome: string; // 'applied' | 'marked-applied' | 'failed'
+}
+
+export interface BackfillPlan {
+  applied: { file: string; identity: string }[];
+  /** To run, in file-name order. */
+  pending: { file: string; identity: string; sql: string; advisories: string[] }[];
+  /** Edited-after-run — refused with the fix named. */
+  blocked: { file: string; identity: string; reason: string }[];
+}
+
+const baseName = (file: string): string => file.split('/').pop() ?? file;
+const counts = (outcome: string): boolean => outcome === 'applied' || outcome === 'marked-applied';
+
+export function planBackfills(files: SourceFile[], log: BackfillRecord[]): BackfillPlan {
+  const appliedIdentities = new Set(log.filter((r) => counts(r.outcome)).map((r) => r.identity));
+  const appliedByName = new Map<string, string>(); // name → identity that ran under it
+  for (const r of log) {
+    if (counts(r.outcome)) appliedByName.set(r.name, r.identity);
+  }
+
+  const plan: BackfillPlan = { applied: [], pending: [], blocked: [] };
+  for (const file of [...files].sort((a, b) => baseName(a.file).localeCompare(baseName(b.file)))) {
+    const identity = backfillIdentity(file.sql);
+    if (appliedIdentities.has(identity)) {
+      plan.applied.push({ file: file.file, identity });
+      continue;
+    }
+    const ranAs = appliedByName.get(baseName(file.file));
+    if (ranAs !== undefined && ranAs !== identity) {
+      plan.blocked.push({
+        file: file.file,
+        identity,
+        reason:
+          `${baseName(file.file)} already ran on this database in a different form — one-shot jobs are immutable. ` +
+          'A genuinely new job gets a NEW file name; if this edit changed nothing the job does, record it: --mark-applied.',
+      });
+      continue;
+    }
+    plan.pending.push({ file: file.file, identity, sql: file.sql, advisories: backfillAdvisories(file.sql) });
+  }
+  return plan;
+}
+
+// ---------------------------------------------------------------------------
+// The record + the runner.
+// ---------------------------------------------------------------------------
+
+export const ENSURE_BACKFILL_SQL: string[] = [
+  'CREATE SCHEMA IF NOT EXISTS everystack',
+  `CREATE TABLE IF NOT EXISTS everystack.backfill_log (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  applied_at timestamptz NOT NULL DEFAULT now(),
+  identity text NOT NULL,
+  name text NOT NULL,
+  actor text,
+  git_ref text,
+  sql text NOT NULL,
+  duration_ms integer,
+  outcome text NOT NULL
+)`,
+];
+
+export interface BackfillLogEntry {
+  identity: string;
+  name: string;
+  sql: string;
+  outcome: string;
+  actor?: string | null;
+  gitRef?: string | null;
+  durationMs?: number;
+}
+
+export function renderBackfillLogInsert(entry: BackfillLogEntry): string {
+  const opt = (v: string | null | undefined): string => (v == null ? 'NULL' : escapeLiteral(v));
+  const duration = entry.durationMs === undefined ? 'NULL' : String(Math.round(entry.durationMs));
+  return `INSERT INTO everystack.backfill_log (identity, name, actor, git_ref, sql, duration_ms, outcome)
+VALUES (${escapeLiteral(entry.identity)}, ${escapeLiteral(entry.name)}, ${opt(entry.actor)}, ${opt(entry.gitRef)}, ${escapeLiteral(entry.sql)}, ${duration}, ${escapeLiteral(entry.outcome)})`;
+}
+
+/** The applied record for this database. Empty when the lane has never run here. */
+export async function readBackfillLog(runner: QueryRunner): Promise<BackfillRecord[]> {
+  const rows = await runner(`
+    SELECT name, identity, outcome FROM everystack.backfill_log ORDER BY id
+  `).catch((err: any) => {
+    if (/relation .*backfill_log.* does not exist|schema .* does not exist/i.test(err.message ?? '')) return [];
+    throw err;
+  });
+  return rows as BackfillRecord[];
+}
+
+export interface BackfillRunOptions {
+  actor?: string | null;
+  gitRef?: string | null;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+export interface BackfillRunResult {
+  ran: { file: string; identity: string; durationMs: number }[];
+  /** The first failure, if any — the run STOPS there (later files may depend on it). */
+  failed?: { file: string; identity: string; error: string };
+}
+
+/**
+ * Run the pending jobs in order, each as its own single batch (one implicit
+ * transaction per job — a failed job rolls back alone and is recorded as
+ * `failed`, staying pending for the retry). Blocked files never execute.
+ */
+export async function executeBackfills(
+  runner: QueryRunner,
+  plan: BackfillPlan,
+  options: BackfillRunOptions = {},
+): Promise<BackfillRunResult> {
+  const now = options.now ?? Date.now;
+  const result: BackfillRunResult = { ran: [] };
+  if (plan.pending.length === 0) return result;
+
+  await runner(ENSURE_BACKFILL_SQL.join(';\n'));
+  for (const job of plan.pending) {
+    const name = baseName(job.file);
+    const started = now();
+    try {
+      await runner(job.sql);
+      const durationMs = now() - started;
+      await runner(renderBackfillLogInsert({
+        identity: job.identity, name, sql: job.sql, outcome: 'applied',
+        actor: options.actor, gitRef: options.gitRef, durationMs,
+      }));
+      result.ran.push({ file: job.file, identity: job.identity, durationMs });
+    } catch (err: any) {
+      await runner(renderBackfillLogInsert({
+        identity: job.identity, name, sql: `-- FAILED: ${err.message}\n${job.sql}`, outcome: 'failed',
+        actor: options.actor, gitRef: options.gitRef, durationMs: now() - started,
+      }));
+      result.failed = { file: job.file, identity: job.identity, error: err.message };
+      return result;
+    }
+  }
+  return result;
+}
+
+/** The adopt hatch: record a job as applied WITHOUT running it (mirrors --baseline). */
+export async function markBackfillApplied(
+  runner: QueryRunner,
+  file: SourceFile,
+  options: BackfillRunOptions = {},
+): Promise<string> {
+  const identity = backfillIdentity(file.sql);
+  await runner(ENSURE_BACKFILL_SQL.join(';\n'));
+  await runner(renderBackfillLogInsert({
+    identity, name: baseName(file.file), sql: file.sql, outcome: 'marked-applied',
+    actor: options.actor, gitRef: options.gitRef,
+  }));
+  return identity;
+}

package/src/cli/branch-db.ts

@@ -0,0 +1,269 @@
+/**
+ * branch-db — per-branch dev databases from a models-built template
+ * (brick 5-remainder of the migration-authority design, decision 14).
+ *
+ * The original wound: one shared dev database, poisoned by every branch
+ * switch. The cure: the dev template `<base>_tpl` is built FROM THE
+ * DECLARED STATE plus seed-as-code — deterministic, PII-free, refreshed by
+ * an explicit `db:template:refresh`, never a data copy (real data enters
+ * branch testing only through stage forks, brick 10) — and each branch
+ * gets its own database, minted `CREATE DATABASE … TEMPLATE`, keyed on the
+ * git branch. `db:sync` then evolves it with the checkout. Branch
+ * databases are disposable by construction: never long-lived, never
+ * poisoned.
+ *
+ * Names are deterministic lowercase identifiers; branches that clean to
+ * the same text (`feat/foo` vs `feat_foo`) get a disambiguating content
+ * hash. The raw branch name travels as a database COMMENT, so listing and
+ * pruning map databases back to branches without guessing — a database
+ * whose comment is gone is never pruned.
+ */
+
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import type { ModelDescriptor } from '@everystack/model';
+import type { QueryRunner } from './authz-contract.js';
+import { escapeLiteral } from './derived-apply.js';
+import { createUrlRunner } from './db-source.js';
+import {
+  withDatabase,
+  createDatabase,
+  dropDatabase,
+  buildIntoDatabase,
+  type BuildOptions,
+} from './db-build.js';
+
+export { withDatabase } from './db-build.js';
+
+// ---------------------------------------------------------------------------
+// Naming (pure).
+// ---------------------------------------------------------------------------
+
+const FAMILY_SUFFIX = /(_tpl|_br_.*|_eph_.*)$/;
+
+/** The family's base name, from ANY member's URL (base, template, branch, ephemeral). */
+export function baseNameFromUrl(url: string): string {
+  const m = url.match(/\/([^/?]+)(\?|$)/);
+  if (!m) throw new Error('the connection URL names no database — add the path segment (postgres://…/mydb)');
+  return m[1].replace(FAMILY_SUFFIX, '');
+}
+
+export function templateName(base: string): string {
+  return `${base}_tpl`;
+}
+
+/**
+ * The branch database's name: deterministic, collision-free, ≤63 chars.
+ * A branch that IS already a clean identifier passes through readably;
+ * anything cleaned (case, slashes, unicode) or truncated carries a 6-char
+ * content hash so `feat/foo` and `feat_foo` never collide.
+ */
+export function branchDatabaseName(base: string, branch: string): string {
+  const prefix = `${base}_br_`;
+  const clean = branch.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  const budget = 63 - prefix.length;
+  if (clean === branch && clean.length > 0 && clean.length <= budget) return `${prefix}${clean}`;
+  const hash = createHash('sha256').update(branch).digest('hex').slice(0, 6);
+  const body = clean.slice(0, Math.max(0, budget - 7));
+  return `${prefix}${body ? `${body}_` : ''}${hash}`;
+}
+
+// ---------------------------------------------------------------------------
+// Comments — the branch mapping and the template provenance (pure).
+// ---------------------------------------------------------------------------
+
+const BRANCH_PREFIX = 'everystack branch: ';
+
+export function branchComment(branch: string): string {
+  return `${BRANCH_PREFIX}${branch}`;
+}
+
+export function parseBranchComment(comment: string | null): string | null {
+  if (!comment || !comment.startsWith(BRANCH_PREFIX)) return null;
+  return comment.slice(BRANCH_PREFIX.length);
+}
+
+export function templateComment(fingerprint: string, gitRef: string | null, builtAt: string): string {
+  return `everystack template fp=${fingerprint} git=${gitRef ?? 'none'} built=${builtAt}`;
+}
+
+export function parseTemplateComment(
+  comment: string | null,
+): { fingerprint: string; gitRef: string | null; builtAt: string } | null {
+  const m = comment?.match(/^everystack template fp=(\S+) git=(\S+) built=(\S+)$/);
+  if (!m) return null;
+  return { fingerprint: m[1], gitRef: m[2] === 'none' ? null : m[2], builtAt: m[3] };
+}
+
+// ---------------------------------------------------------------------------
+// Pruning (pure).
+// ---------------------------------------------------------------------------
+
+export interface BranchDatabase {
+  database: string;
+  /** From the database comment; null when the mapping is lost — never pruned. */
+  branch: string | null;
+}
+
+/** Databases whose branch no longer exists — and ONLY those. Unknown = kept. */
+export function prunableBranchDatabases(
+  databases: BranchDatabase[],
+  liveBranches: string[],
+): BranchDatabase[] {
+  const live = new Set(liveBranches);
+  return databases.filter((d) => d.branch !== null && !live.has(d.branch));
+}
+
+// ---------------------------------------------------------------------------
+// Git (thin).
+// ---------------------------------------------------------------------------
+
+export function currentBranch(cwd?: string): string | null {
+  try {
+    const out = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd, stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim();
+    return out === 'HEAD' ? null : out; // detached HEAD names no branch
+  } catch {
+    return null;
+  }
+}
+
+export function localBranches(cwd?: string): string[] {
+  try {
+    return execSync('git for-each-ref --format=%(refname:short) refs/heads', {
+      cwd, stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration.
+// ---------------------------------------------------------------------------
+
+async function withAdmin<T>(adminUrl: string, fn: (runner: QueryRunner) => Promise<T>): Promise<T> {
+  const { runner, end } = await createUrlRunner(adminUrl);
+  try {
+    return await fn(runner);
+  } finally {
+    await end?.();
+  }
+}
+
+async function databaseExists(runner: QueryRunner, name: string): Promise<boolean> {
+  const rows = await runner(`SELECT 1 FROM pg_database WHERE datname = ${escapeLiteral(name)}`);
+  return rows.length > 0;
+}
+
+async function setComment(runner: QueryRunner, database: string, comment: string): Promise<void> {
+  await runner(`COMMENT ON DATABASE "${database}" IS ${escapeLiteral(comment)}`);
+}
+
+export interface TemplateRefreshOptions extends BuildOptions {
+  /** Runs against the freshly built template (the app's own seed, injected by the shell). */
+  seed?: ((templateUrl: string) => Promise<void>) | null;
+  /** Injectable for tests. Default: now, ISO. */
+  builtAt?: string;
+}
+
+export interface TemplateRefreshResult {
+  database: string;
+  url: string;
+  fingerprint: string;
+  report: string[];
+}
+
+/**
+ * (Re)build the dev template from the declared state + seed. All or
+ * nothing: a template that fails to build (or seed) is DROPPED — a broken
+ * template silently minting broken branch databases is the one outcome
+ * this must never produce.
+ */
+export async function executeTemplateRefresh(
+  adminUrl: string,
+  models: ModelDescriptor[],
+  options: TemplateRefreshOptions = {},
+): Promise<TemplateRefreshResult> {
+  const base = baseNameFromUrl(adminUrl);
+  const template = templateName(base);
+  await dropDatabase(adminUrl, template);
+  await createDatabase(adminUrl, template);
+  const url = withDatabase(adminUrl, template);
+  try {
+    const built = await buildIntoDatabase(url, models, options);
+    if (!(built.converged && built.fingerprintMatch)) {
+      throw new Error(`the template did not land on the declared state:\n${built.report.join('\n')}`);
+    }
+    if (options.seed) await options.seed(url);
+    await withAdmin(adminUrl, (runner) =>
+      setComment(runner, template, templateComment(
+        built.fingerprint,
+        options.gitRef ?? null,
+        options.builtAt ?? new Date().toISOString(),
+      )),
+    );
+    return { database: template, url, fingerprint: built.fingerprint, report: built.report };
+  } catch (err) {
+    await dropDatabase(adminUrl, template).catch(() => {});
+    throw err;
+  }
+}
+
+export type EnsureBranchResult =
+  | { status: 'created' | 'exists'; database: string; url: string; template: string }
+  | { status: 'no-template'; database: string; url: string; template: string };
+
+/** Mint (or find) the current branch's database from the template. */
+export async function ensureBranchDatabase(adminUrl: string, branch: string): Promise<EnsureBranchResult> {
+  const base = baseNameFromUrl(adminUrl);
+  const template = templateName(base);
+  const database = branchDatabaseName(base, branch);
+  const url = withDatabase(adminUrl, database);
+
+  const exists = await withAdmin(adminUrl, (runner) => databaseExists(runner, database));
+  if (exists) return { status: 'exists', database, url, template };
+
+  const templateExists = await withAdmin(adminUrl, (runner) => databaseExists(runner, template));
+  if (!templateExists) return { status: 'no-template', database, url, template };
+
+  await createDatabase(adminUrl, database, template);
+  await withAdmin(adminUrl, (runner) => setComment(runner, database, branchComment(branch)));
+  return { status: 'created', database, url, template };
+}
+
+/** Every branch database in the family, with its branch (from the comment). */
+export async function listBranchDatabases(adminUrl: string): Promise<BranchDatabase[]> {
+  const base = baseNameFromUrl(adminUrl);
+  return withAdmin(adminUrl, async (runner) => {
+    const rows = await runner(
+      `SELECT datname, shobj_description(oid, 'pg_database') AS comment
+       FROM pg_database WHERE datname LIKE ${escapeLiteral(`${base}\\_br\\_%`)} ORDER BY datname`,
+    );
+    return rows.map((r: any) => ({ database: r.datname, branch: parseBranchComment(r.comment) }));
+  });
+}
+
+/** The template's provenance, or null when no template exists. */
+export async function readTemplateProvenance(
+  adminUrl: string,
+): Promise<{ fingerprint: string; gitRef: string | null; builtAt: string } | null> {
+  const base = baseNameFromUrl(adminUrl);
+  return withAdmin(adminUrl, async (runner) => {
+    const rows = await runner(
+      `SELECT shobj_description(oid, 'pg_database') AS comment
+       FROM pg_database WHERE datname = ${escapeLiteral(templateName(base))}`,
+    );
+    if (rows.length === 0) return null;
+    return parseTemplateComment(rows[0].comment);
+  });
+}
+
+/** Drop a branch database — refuses anything outside the `_br_` family. */
+export async function dropBranchDatabase(adminUrl: string, database: string): Promise<void> {
+  if (!/_br_/.test(database)) {
+    throw new Error(`${database} is not a branch database — this path only drops the _br_ family.`);
+  }
+  await dropDatabase(adminUrl, database);
+}

package/src/cli/commands/db-backfill.ts

@@ -0,0 +1,127 @@
+/**
+ * `everystack db:backfill` — the one-shot data-job lane (brick 8).
+ *
+ *   db:backfill [--database-url <url>] [--dir db/backfills] [--json]
+ *   db:backfill --apply                     # run the pending jobs, in order
+ *   db:backfill --mark-applied <file.sql>   # record without running (adopt hatch)
+ *
+ * Plan first, always: applied (by content identity — renames and comment
+ * edits are no-ops), pending (in file-name order, with jobs-lane advisories
+ * for unbounded passes), and blocked (a file name that already ran here in
+ * a different form — one-shot jobs are immutable; the fix is named). Apply
+ * runs each pending job as its own transaction and records it in
+ * `everystack.backfill_log`; a failure rolls back alone, is recorded, and
+ * stops the run. Backfills NEVER run as a side effect of a schema verb —
+ * db:sync and db:plan only surface the pending count.
+ *
+ * Needs a direct connection (--database-url / DATABASE_URL): the lane
+ * reads and writes its own per-database record.
+ */
+
+import type { QueryRunner } from '../authz-contract.js';
+import {
+  planBackfills,
+  readBackfillLog,
+  executeBackfills,
+  markBackfillApplied,
+  type BackfillPlan,
+} from '../backfill.js';
+import { currentGitRef } from '../state-apply.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { readSqlDirIfPresent } from './db-sync.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const DEFAULT_DIR = 'db/backfills';
+
+export function buildBackfillReport(plan: BackfillPlan): string[] {
+  const lines: string[] = [];
+  lines.push(`= ${plan.applied.length} applied (by content identity)`);
+  for (const b of plan.blocked) lines.push(`! BLOCKED ${b.file}: ${b.reason}`);
+  if (plan.pending.length === 0) {
+    lines.push('= nothing pending');
+  } else {
+    lines.push(`~ ${plan.pending.length} pending, in order:`);
+    for (const p of plan.pending) {
+      lines.push(`~   ${p.file}`);
+      for (const a of p.advisories) lines.push(`·     advisory: ${a}`);
+    }
+  }
+  return lines;
+}
+
+export async function dbBackfillCommand(flags: Record<string, string>): Promise<void> {
+  const dir = flags.dir || DEFAULT_DIR;
+  const files = await readSqlDirIfPresent(dir);
+  if (files === null) {
+    info(`No ${dir}/ directory — the backfill lane is not declared. One-shot data jobs live there as *.sql files.`);
+    return;
+  }
+
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (dbSource.kind !== 'url') {
+    fail('db:backfill needs a direct connection (--database-url or DATABASE_URL) — the lane reads and writes its per-database record.');
+    process.exit(1);
+  }
+
+  step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+  const { runner, end } = await createUrlRunner(dbSource.url);
+  try {
+    const opts = { actor: process.env.USER ?? null, gitRef: currentGitRef() };
+
+    if (flags['mark-applied'] !== undefined) {
+      const name = flags['mark-applied'];
+      const file = files.find((f) => f.file.endsWith(`/${name}`) || f.file === name);
+      if (name === 'true' || !file) {
+        fail(`--mark-applied needs a file from ${dir}/ (got ${name === 'true' ? 'nothing' : name}).`);
+        process.exit(1);
+      }
+      const identity = await markBackfillApplied(runner as QueryRunner, file, opts);
+      success(`Recorded ${file.file} as applied WITHOUT running it (identity ${identity.slice(0, 12)}).`);
+      return;
+    }
+
+    const plan = planBackfills(files, await readBackfillLog(runner));
+    for (const line of buildBackfillReport(plan)) info(line);
+
+    if (flags.json === 'true') {
+      console.log(JSON.stringify({
+        applied: plan.applied,
+        pending: plan.pending.map(({ sql: _sql, ...rest }) => rest),
+        blocked: plan.blocked,
+      }, null, 2));
+    }
+
+    if (flags.apply !== 'true') {
+      if (plan.pending.length > 0) info(`Run them: everystack db:backfill --apply`);
+      if (plan.blocked.length > 0) process.exit(1);
+      return;
+    }
+
+    if (plan.pending.length === 0) {
+      success('Nothing to run.');
+      if (plan.blocked.length > 0) process.exit(1);
+      return;
+    }
+
+    step(`Running ${plan.pending.length} backfill(s), each as its own transaction...`);
+    const result = await executeBackfills(runner, plan, opts);
+    for (const ran of result.ran) info(`~ ${ran.file} applied in ${ran.durationMs}ms`);
+    if (result.failed) {
+      fail(`${result.failed.file} FAILED and rolled back (recorded; it stays pending for the retry): ${result.failed.error}`);
+      process.exit(1);
+    }
+    if (plan.blocked.length > 0) {
+      fail('Pending jobs ran, but blocked file(s) remain above — fix them (new file name, or --mark-applied).');
+      process.exit(1);
+    }
+    success(`${result.ran.length} backfill(s) applied and recorded in everystack.backfill_log.`);
+  } finally {
+    await end?.();
+  }
+}