@everystack/cli 0.3.22 → 0.3.25

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-apply.ts

@@ -27,11 +27,14 @@ import { introspectSchema, type SchemaSnapshot } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { fingerprintLive } from '../schema-fingerprint.js';
 import { applyGeneratedStatements, currentGitRef } from '../state-apply.js';
-import { renderSchemaLogFingerprintUpdate } from '../derived-apply.js';
+import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from '../derived-apply.js';
 import { checkPlanPrecondition, planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan.js';
 import { verifyDescent, type LiveState } from '../git-descent.js';
+import { checkDestructiveAuthority, readApproverParam, resolveCallerIdentity } from '../apply-authority.js';
 import { resolveModelsPath } from '../models-path.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 // ---------------------------------------------------------------------------
@@ -54,17 +57,63 @@ export interface ApplyPlanOptions {
     contract: AuthzContract;
     fingerprint: string;
   }) => Promise<{ ok: true } | { ok: false; reason: string }>;
+  /**
+   * Destructive authority (brick 9, decisions 11+12): called only when the
+   * plan is destructive, after the lock and descent checks pass. Return
+   * `ok: false` to refuse — the caller is not in the stage's declared
+   * approver set. Omitted = no authority gate (non-staged targets keep the
+   * ceremony the command shell enforces).
+   */
+  verifyAuthority?: () => Promise<{ ok: true } | { ok: false; reason: string }>;
+  /**
+   * Runs after every verification passes and BEFORE the edge executes, only
+   * for destructive plans — the auto-snapshot seam ("losing data should be
+   * hard": confirmed, approved, snapshotted, in that order). A throw here
+   * aborts the apply with nothing executed.
+   */
+  beforeDestructive?: () => Promise<void>;
   /** Injectable clock for tests. */
   now?: () => number;
 }
 
 export interface ApplyPlanResult {
-  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'verify-failed';
+  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'authority-refused' | 'verify-failed';
   liveFingerprint: string;
   reason?: string;
   logId?: number;
 }
 
+/**
+ * Decision 7, made whole: every database records every refusal, not just
+ * every apply. Best-effort by construction — a memoir INSERT that cannot be
+ * written must never mask the refusal itself (a target that rejects the
+ * bookkeeping write would have failed the apply's ENSURE identically).
+ */
+async function recordRefusal(
+  runner: QueryRunner,
+  plan: EdgePlan,
+  liveFingerprint: string,
+  gate: string,
+  reason: string,
+  options: ApplyPlanOptions,
+): Promise<void> {
+  try {
+    await runner(ENSURE_RECONCILER_SQL.join(';\n'));
+    await runner(renderSchemaLogInsert({
+      kind: 'state refusal',
+      outcome: 'refused',
+      actor: options.actor ?? null,
+      gitRef: options.gitRef ?? plan.gitRef,
+      planRef: planHash(plan),
+      fromFingerprint: liveFingerprint,
+      toFingerprint: plan.toFingerprint,
+      sql: `-- REFUSED (${gate}): ${reason}\n${plan.statements.join('\n;\n')}`,
+    }));
+  } catch {
+    // Swallowed deliberately — see the docblock.
+  }
+}
+
 /** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
 export async function executeApplyPlan(
   runner: QueryRunner,
@@ -80,16 +129,30 @@ export async function executeApplyPlan(
   }
   const pre = checkPlanPrecondition(plan, live);
   if (!pre.ok) {
+    await recordRefusal(runner, plan, live, 'concurrency lock', pre.reason, options);
     return { status: 'refused', liveFingerprint: live, reason: pre.reason };
   }
 
   if (options.verifyDescent) {
     const descent = await options.verifyDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live });
     if (!descent.ok) {
+      await recordRefusal(runner, plan, live, 'fast-forward rule', descent.reason, options);
       return { status: 'descent-refused', liveFingerprint: live, reason: descent.reason };
     }
   }
 
+  if (plan.destructive > 0 && options.verifyAuthority) {
+    const authority = await options.verifyAuthority();
+    if (!authority.ok) {
+      await recordRefusal(runner, plan, live, 'destructive authority', authority.reason, options);
+      return { status: 'authority-refused', liveFingerprint: live, reason: authority.reason };
+    }
+  }
+
+  if (plan.destructive > 0 && options.beforeDestructive) {
+    await options.beforeDestructive();
+  }
+
   const result = await applyGeneratedStatements(runner, plan.statements, {
     actor: options.actor,
     gitRef: options.gitRef ?? plan.gitRef,
@@ -170,6 +233,52 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     }
   }
 
+  // Losing data should be hard (decision 11): a destructive plan applies
+  // only confirmed (--confirm, always), snapshotted (automatic with --stage,
+  // named over a bare connection), and — when the stage declares an approver
+  // set — identity-approved (decision 12).
+  const isDestructive = plan.destructive > 0;
+  let verifyAuthority: (() => Promise<{ ok: true } | { ok: false; reason: string }>) | undefined;
+  let beforeDestructive: (() => Promise<void>) | undefined;
+  if (isDestructive) {
+    const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
+    if (flags.confirm !== 'true') {
+      fail(`This plan is DESTRUCTIVE — ${plan.destructive} statement(s) lose data (${shape}). Explicit confirmation is required, always: re-run with --confirm.`);
+      process.exit(1);
+    }
+    if (flags.stage) {
+      const config = await resolveConfig(flags.stage);
+      const { parseAppName } = await import('../discover.js');
+      const appName = await parseAppName();
+      verifyAuthority = async () => {
+        step(`Destructive authority: checking the approver set for stage ${flags.stage}...`);
+        const approvers = await readApproverParam(config.region, appName, flags.stage);
+        const identity = approvers === null ? null : await resolveCallerIdentity(config.region);
+        const verdict = checkDestructiveAuthority({ approvers, identity });
+        if (!verdict.ok) return verdict;
+        if (verdict.reason === 'approved') {
+          info(`authority: ${identity} is a declared approver.`);
+        } else {
+          warn('authority: no approver set declared for this stage — proceeding on ceremony alone. Declare one: everystack db:approvers --set <arn-or-name,...> --stage ' + flags.stage);
+        }
+        return { ok: true };
+      };
+      beforeDestructive = async () => {
+        step('Destructive apply — taking a snapshot first (db:backup)...');
+        const result: any = await invokeAction(config.region, opsFunction(config), 'db:backup', { stage: flags.stage });
+        if (result?.error) {
+          throw new Error(`auto-snapshot failed, so the destructive plan was NOT applied: ${result.error}`);
+        }
+        info(`snapshot on record: ${result?.id ?? 'backup complete'} — restore with db:restore --from ${result?.id ?? '<id>'} --confirm.`);
+      };
+    } else if (!flags['snapshot-ref']) {
+      fail(`This plan is DESTRUCTIVE (${shape}) and the target is a bare connection — the apply cannot take the snapshot itself. Take one (db:snapshot / db:backup / pg_dump) and name it: --snapshot-ref <ref>. Or pass --stage and the apply snapshots automatically, with the stage's approver set enforced.`);
+      process.exit(1);
+    } else {
+      warn(`DESTRUCTIVE apply over a bare connection — approver gating unavailable (no --stage), proceeding on ceremony: --confirm + snapshot ${flags['snapshot-ref']}.`);
+    }
+  }
+
   step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
   const { runner, end } = await createUrlRunner(dbSource.url);
 
@@ -182,6 +291,8 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     const result = await executeApplyPlan(runner, plan, {
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
+      ...(verifyAuthority ? { verifyAuthority } : {}),
+      ...(beforeDestructive ? { beforeDestructive } : {}),
       ...(forceDescent === undefined ? {
         verifyDescent: async (live: LiveState & { fingerprint: string }) => {
           step('Descent: searching git for the commit that declares the target\'s state...');
@@ -216,6 +327,10 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
         fail(`REFUSED (fast-forward rule): ${result.reason}`);
         process.exit(1);
         break;
+      case 'authority-refused':
+        fail(`REFUSED (destructive authority): ${result.reason}`);
+        process.exit(1);
+        break;
       case 'verify-failed':
         fail(`Verify FAILED: ${result.reason}`);
         process.exit(1);

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

@@ -0,0 +1,71 @@
+/**
+ * `everystack db:approvers` — declare who can destroy (brick 9, decision 12).
+ *
+ *   db:approvers --stage <name>                      # show the declared set
+ *   db:approvers --stage <name> --set "cto,arn:..."  # declare / replace
+ *   db:approvers --stage <name> --set ''             # declare EMPTY: destructive applies disabled
+ *   db:approvers --stage <name> --remove             # undeclare: back to ceremony-only
+ *
+ * The set lives stage-side (an SSM parameter in the stage's namespace) so a
+ * checkout edit can't reach it; lock it down further with IAM by denying
+ * `ssm:PutParameter` on `/everystack/<app>/<stage>/db-approvers` to
+ * non-admins — the same posture as the rest of the stage's parameters.
+ * Entries are exact ARNs or bare names matched against the caller's ARN
+ * path segments (`ty` matches `user/ty` and an assumed-role session `ty`).
+ */
+
+import { resolveConfig } from '../config.js';
+import {
+  approverParamName,
+  parseApproverValue,
+  readApproverParam,
+  writeApproverParam,
+  removeApproverParam,
+} from '../apply-authority.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+export async function dbApproversCommand(flags: Record<string, string>): Promise<void> {
+  if (!flags.stage) {
+    fail('db:approvers needs --stage <name> — the approver set is per-stage configuration.');
+    process.exit(1);
+  }
+
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  const { parseAppName } = await import('../discover.js');
+  const appName = await parseAppName();
+  const paramName = approverParamName(appName, flags.stage);
+
+  if (flags.remove === 'true') {
+    await removeApproverParam(config.region, appName, flags.stage);
+    success(`Removed ${paramName} — the stage is back to the undeclared posture (destructive applies gated by ceremony only).`);
+    return;
+  }
+
+  if (flags.set !== undefined) {
+    if (flags.set === 'true') {
+      fail("--set needs a value: a comma-separated list of ARNs or names (--set '' declares an EMPTY set, disabling destructive applies).");
+      process.exit(1);
+    }
+    const approvers = parseApproverValue(flags.set);
+    await writeApproverParam(config.region, appName, flags.stage, approvers);
+    if (approvers.length === 0) {
+      warn(`Declared an EMPTY approver set at ${paramName} — destructive applies are now DISABLED on ${flags.stage}.`);
+    } else {
+      success(`Declared ${approvers.length} approver(s) at ${paramName}: ${approvers.join(', ')}`);
+      info('Destructive db:apply runs against this stage now require one of these identities (STS-verified).');
+    }
+    return;
+  }
+
+  const approvers = await readApproverParam(config.region, appName, flags.stage);
+  if (approvers === null) {
+    info(`No approver set declared (${paramName} absent) — destructive applies are gated by ceremony only (--confirm + snapshot).`);
+    info("Declare one: everystack db:approvers --set 'cto,arn:aws:iam::…:user/…' --stage " + flags.stage);
+  } else if (approvers.length === 0) {
+    warn(`The approver set is declared EMPTY — destructive applies are DISABLED on ${flags.stage}.`);
+  } else {
+    info(`Destructive-approver set for ${flags.stage} (${approvers.length}):`);
+    for (const a of approvers) info(`  - ${a}`);
+  }
+}

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?.();
+  }
+}