@everystack/cli 0.3.23 → 0.3.27

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

@@ -0,0 +1,220 @@
+/**
+ * `everystack db:template:refresh` + `everystack db:branch` — per-branch
+ * dev databases from a models-built template (brick 5-remainder,
+ * decision 14).
+ *
+ *   db:template:refresh [--database-url <url>] [--models <barrel>]
+ *                       [--sql-dir db/sql] [--seed "<cmd>"] [--no-seed]
+ *   db:branch                       # mint (or find) the current branch's DB
+ *   db:branch --list                # every branch DB, mapped to its branch
+ *   db:branch --drop --confirm      # drop the current branch's DB
+ *   db:branch --prune --confirm     # drop DBs whose git branch is gone
+ *
+ * The template is built FROM THE DECLARED STATE (both layers, fingerprint
+ * MATCH bar) plus seed-as-code — the app's own `db:seed` script, run as a
+ * subprocess with DATABASE_URL pointed at the fresh template. Never a data
+ * copy: deterministic, PII-free (real data enters branch testing through
+ * stage forks, brick 10). Branch databases mint via `CREATE DATABASE …
+ * TEMPLATE`, keyed on the git branch, and `db:sync` evolves them with the
+ * checkout — disposable by construction, never long-lived, never poisoned.
+ */
+
+import fs from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import type { ModelDescriptor } from '@everystack/model';
+import {
+  executeTemplateRefresh,
+  ensureBranchDatabase,
+  listBranchDatabases,
+  readTemplateProvenance,
+  prunableBranchDatabases,
+  dropBranchDatabase,
+  branchDatabaseName,
+  baseNameFromUrl,
+  templateName,
+  currentBranch,
+  localBranches,
+} from '../branch-db.js';
+import { currentGitRef } from '../state-apply.js';
+import { fingerprintModels } from '../schema-fingerprint.js';
+import { resolveDbSource, type DbSource } from '../db-source.js';
+import { resolveModelsPath } from '../models-path.js';
+import { readSqlDirIfPresent } from './db-sync.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+function requireUrl(flags: Record<string, string>, verb: string): string {
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (dbSource.kind !== 'url') {
+    fail(`${verb} manages local databases — it needs a direct connection (--database-url or DATABASE_URL).`);
+    process.exit(1);
+  }
+  return dbSource.url;
+}
+
+/** The seed convention: the app's own `db:seed` script from package.json. */
+async function detectSeedCommand(): Promise<string | null> {
+  try {
+    const pkg = JSON.parse(await fs.readFile('package.json', 'utf8'));
+    return pkg?.scripts?.['db:seed'] ? 'npm run db:seed' : null;
+  } catch {
+    return null;
+  }
+}
+
+function runSeedSubprocess(command: string, templateUrl: string): void {
+  const result = spawnSync(command, {
+    shell: true,
+    stdio: 'inherit',
+    env: { ...process.env, DATABASE_URL: templateUrl },
+  });
+  if (result.status !== 0) {
+    throw new Error(`seed command failed (exit ${result.status}): ${command}`);
+  }
+}
+
+export async function dbTemplateRefreshCommand(flags: Record<string, string>): Promise<void> {
+  const url = requireUrl(flags, 'db:template:refresh');
+
+  const modelsPath = resolveModelsPath(flags.models);
+  let models: ModelDescriptor[];
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    models = await loadModels(modelsPath);
+    info(`${models.length} model(s).`);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  const sources = await readSqlDirIfPresent(flags['sql-dir'] || 'db/sql');
+
+  let seedCommand: string | null = null;
+  if (flags['no-seed'] === 'true') {
+    info('Seeding skipped (--no-seed).');
+  } else if (flags.seed && flags.seed !== 'true') {
+    seedCommand = flags.seed;
+  } else {
+    seedCommand = await detectSeedCommand();
+    if (seedCommand) info(`Seed: package.json db:seed script (override with --seed "<cmd>" / --no-seed).`);
+    else warn('No db:seed script in package.json — the template builds UNSEEDED (declare one, or pass --seed "<cmd>").');
+  }
+
+  const template = templateName(baseNameFromUrl(url));
+  step(`Rebuilding ${template} from the declared state (drop → create → sync both layers → seed)...`);
+  try {
+    const result = await executeTemplateRefresh(url, models, {
+      sources,
+      actor: process.env.USER ?? null,
+      gitRef: currentGitRef(),
+      seed: seedCommand === null ? null : (templateUrl) => {
+        step(`Seeding: ${seedCommand} (DATABASE_URL → ${redactUrl(templateUrl)})...`);
+        runSeedSubprocess(seedCommand!, templateUrl);
+        return Promise.resolve();
+      },
+    });
+    for (const line of result.report) info(`  ${line}`);
+    success(`Template ${result.database} is the declared state at ${result.fingerprint.slice(0, 12)}${seedCommand ? ', seeded' : ''}. Mint branch databases: everystack db:branch`);
+  } catch (err: any) {
+    fail(`Template refresh failed — no template was left behind (all or nothing): ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/** Redact credentials when echoing a URL. */
+function redactUrl(url: string): string {
+  return url.replace(/\/\/[^@/]+@/, '//***@');
+}
+
+export async function dbBranchCommand(flags: Record<string, string>): Promise<void> {
+  const url = requireUrl(flags, 'db:branch');
+
+  if (flags.list === 'true') {
+    const provenance = await readTemplateProvenance(url);
+    if (provenance) {
+      info(`template ${templateName(baseNameFromUrl(url))}: fingerprint ${provenance.fingerprint.slice(0, 12)}, built ${provenance.builtAt}${provenance.gitRef ? ` at ${provenance.gitRef.slice(0, 12)}` : ''}`);
+    } else {
+      warn(`no template — build it once: everystack db:template:refresh`);
+    }
+    const all = await listBranchDatabases(url);
+    if (all.length === 0) {
+      info('no branch databases.');
+      return;
+    }
+    const live = new Set(localBranches());
+    for (const d of all) {
+      const state = d.branch === null ? 'branch unknown (comment lost)' : live.has(d.branch) ? d.branch : `${d.branch} — branch GONE (db:branch --prune)`;
+      info(`  ${d.database}  ←  ${state}`);
+    }
+    return;
+  }
+
+  if (flags.prune === 'true') {
+    const dead = prunableBranchDatabases(await listBranchDatabases(url), localBranches());
+    if (dead.length === 0) {
+      success('Nothing to prune — every branch database maps to a live branch.');
+      return;
+    }
+    for (const d of dead) info(`  ${d.database}  ←  ${d.branch} (gone)`);
+    if (flags.confirm !== 'true') {
+      fail(`Would drop the ${dead.length} database(s) above — confirm with --confirm.`);
+      process.exit(1);
+    }
+    for (const d of dead) {
+      await dropBranchDatabase(url, d.database);
+      info(`dropped ${d.database}`);
+    }
+    success(`Pruned ${dead.length} branch database(s).`);
+    return;
+  }
+
+  const branch = currentBranch();
+  if (branch === null) {
+    fail('db:branch is keyed on the git branch — not a repository, or detached HEAD.');
+    process.exit(1);
+  }
+
+  if (flags.drop === 'true') {
+    const database = branchDatabaseName(baseNameFromUrl(url), branch);
+    if (flags.confirm !== 'true') {
+      fail(`Would drop ${database} (branch ${branch}) — confirm with --confirm.`);
+      process.exit(1);
+    }
+    await dropBranchDatabase(url, database);
+    success(`Dropped ${database}.`);
+    return;
+  }
+
+  const result = await ensureBranchDatabase(url, branch);
+  switch (result.status) {
+    case 'no-template':
+      fail(`No template ${result.template} — build it once: everystack db:template:refresh. Branch databases mint from it.`);
+      process.exit(1);
+      break;
+    case 'exists':
+      info(`${result.database} already exists for branch ${branch}.`);
+      break;
+    case 'created': {
+      success(`Minted ${result.database} from ${result.template} (branch ${branch}).`);
+      try {
+        const provenance = await readTemplateProvenance(url);
+        const declared = fingerprintModels(await loadModels(resolveModelsPath(flags.models))).hash;
+        if (provenance && provenance.fingerprint !== declared) {
+          info(`· your checkout declares ${declared.slice(0, 12)}; the template was built at ${provenance.fingerprint.slice(0, 12)} — db:sync below evolves it (refresh the template when it drifts far).`);
+        }
+      } catch {
+        // The staleness note is best-effort — minting already succeeded.
+      }
+      break;
+    }
+  }
+  console.log('');
+  console.log(`  export DATABASE_URL="${result.url}"`);
+  console.log('');
+  info(`then: everystack db:sync    # evolve it with your checkout as you edit`);
+}

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

@@ -28,20 +28,22 @@
  */
 
 import fs from 'node:fs/promises';
-import postgres from 'postgres';
 import type { ModelDescriptor } from '@everystack/model';
-import type { TableContract } from '../authz-contract.js';
 import { compileDeclaredState } from '../declared-diff.js';
 import { compileMigration } from '../migration-compile.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import { parseSqlSources, type SourceFile } from '../derived-source.js';
 import { currentGitRef } from '../state-apply.js';
-import { createUrlRunner } from '../db-source.js';
+import { createDatabase, dropDatabase, buildIntoDatabase, withDatabase } from '../db-build.js';
 import { resolveModelsPath } from '../models-path.js';
-import { executeSync, buildSyncReport, readSqlDirIfPresent } from './db-sync.js';
+import { readSqlDirIfPresent } from './db-sync.js';
 import { loadModels } from './db-generate.js';
 import { step, success, fail, info, warn } from '../output.js';
 
+// The role derivation moved to the shared builder (db-build) with brick
+// 5-remainder; re-exported here because db:check is where it grew up.
+export { rolesFromContract } from '../db-build.js';
+
 const DEFAULT_SQL_DIR = 'db/sql';
 const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 
@@ -145,19 +147,6 @@ export function checkFailed(findings: CheckFinding[]): boolean {
 // The ephemeral compose ring.
 // ---------------------------------------------------------------------------
 
-/** Every role the contract grants to or names in a policy — the compose DB needs them. */
-export function rolesFromContract(tables: TableContract[]): string[] {
-  const roles = new Set<string>();
-  for (const t of tables) {
-    for (const grantee of Object.keys(t.grants)) roles.add(grantee);
-    for (const grantee of Object.keys(t.columnGrants ?? {})) roles.add(grantee);
-    for (const p of t.policies) for (const r of p.roles) roles.add(r);
-  }
-  roles.delete('PUBLIC');
-  roles.delete('public');
-  return [...roles].sort();
-}
-
 export interface EphemeralComposeResult {
   database: string;
   createdRoles: string[];
@@ -168,12 +157,10 @@ export interface EphemeralComposeResult {
 }
 
 /**
- * Build the declared state from scratch on an ephemeral database: CREATE
- * DATABASE, roles the contract references (NOLOGIN, cluster-level, created
- * only if absent), one `executeSync` for both layers, DROP DATABASE —
- * always, error or not. The bar is `converged && fingerprintMatch`: a
- * fresh database has nothing unmodeled and nothing to drop, so anything
- * short of MATCH is a real compose fault.
+ * Build the declared state from scratch on an ephemeral database (the
+ * shared db-build core), then DROP it — always, error or not. The bar is
+ * `converged && fingerprintMatch`: a fresh database has nothing unmodeled
+ * and nothing to drop, so anything short of MATCH is a real compose fault.
  */
 export async function executeEphemeralCompose(
   adminUrl: string,
@@ -181,46 +168,17 @@ export async function executeEphemeralCompose(
   sources: SourceFile[] | null,
   opts: { actor?: string | null; gitRef?: string | null } = {},
 ): Promise<EphemeralComposeResult> {
-  const dbName = `escheck_${process.pid}_${Date.now()}`;
-  const admin = postgres(adminUrl, { max: 1 });
-  try {
-    await admin.unsafe(`CREATE DATABASE "${dbName}"`);
-  } finally {
-    await admin.end();
-  }
-
-  const { runner, end } = await createUrlRunner(adminUrl.replace(/\/[^/?]+(\?|$)/, `/${dbName}$1`));
+  const database = `escheck_${process.pid}_${Date.now()}`;
+  await createDatabase(adminUrl, database);
   try {
-    const roles = rolesFromContract(compileDeclaredState(models).contract.tables);
-    for (const role of roles) {
-      if (!/^[a-z_][a-z0-9_$]*$/i.test(role)) {
-        throw new Error(`contract references a role name that is not a plain identifier: ${JSON.stringify(role)}`);
-      }
-      await runner(
-        `DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}') THEN CREATE ROLE "${role}" NOLOGIN; END IF; END $$`,
-      );
-    }
-
-    const run = await executeSync(runner, models, sources, {
+    const built = await buildIntoDatabase(withDatabase(adminUrl, database), models, {
+      sources,
       actor: opts.actor ?? 'db:check',
       gitRef: opts.gitRef ?? null,
     });
-    return {
-      database: dbName,
-      createdRoles: roles,
-      converged: run.converged,
-      fingerprintMatch: run.fingerprintMatch,
-      fingerprint: run.state.toFingerprint,
-      report: buildSyncReport(run),
-    };
+    return { database, ...built };
   } finally {
-    await end?.();
-    const reaper = postgres(adminUrl, { max: 1 });
-    try {
-      await reaper.unsafe(`DROP DATABASE IF EXISTS "${dbName}" WITH (FORCE)`);
-    } finally {
-      await reaper.end();
-    }
+    await dropDatabase(adminUrl, database);
   }
 }
 

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

@@ -0,0 +1,139 @@
+/**
+ * `everystack db:fork` — fork one stage's database into another
+ * (branch-stages plan, brick 2; docs/plans/branch-stages.md).
+ *
+ *   db:fork --from-stage staging --stage feat-foo --confirm [--backup <id>]
+ *
+ * Three moves, all existing surfaces: back up the source (or reuse a named
+ * backup), presign the dump with the OPERATOR's credentials — the presigned
+ * URL is the whole cross-stage hand-off, no bucket policies, no IAM
+ * coupling, expires in an hour — and invoke the target's `db:restore` with
+ * the URL. The target stage must already be deployed (`sst deploy --stage
+ * feat-foo`); the fork replaces its database with the source's data, and
+ * the branch's own schema changes then land through the front door
+ * (`db:plan` → `db:apply` — the forked state is one a main commit declares,
+ * so the fast-forward rule composes for free).
+ *
+ * Production is never a fork target, flat — that is disaster recovery
+ * (`db:restore`), not a fork. Forking FROM production carries the PII
+ * data-governance warning. Teardown is the stage's own: `sst remove`.
+ */
+
+import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
+import { invokeAction, presignGet } from '../aws.js';
+import { keyForId, parseBackupRef, isProductionTier, crossStageGuard } from '../backup.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+export type ForkGuardVerdict =
+  | { ok: true; piiWarning: string | null }
+  | { ok: false; reason: string };
+
+/** The pure gate — see the module docblock for the decisions it enforces. */
+export function checkForkGuards(input: { from?: string; stage?: string; confirm: boolean }): ForkGuardVerdict {
+  const { from, stage, confirm } = input;
+  if (!from || from === 'true') {
+    return { ok: false, reason: 'db:fork needs the source: --from-stage <name> (the stage whose data you are forking).' };
+  }
+  if (!stage || stage === 'true') {
+    return { ok: false, reason: 'db:fork needs the target: --stage <name> (an already-deployed feature stage; `sst deploy --stage <name>` first).' };
+  }
+  if (from === stage) {
+    return { ok: false, reason: 'source and target are the same stage — restoring a stage onto itself is db:restore, not a fork.' };
+  }
+  if (isProductionTier(stage)) {
+    return { ok: false, reason: `"${stage}" is production-tier — a fork never overwrites production. Restoring production is disaster recovery: db:restore, with its own ceremony.` };
+  }
+  if (!confirm) {
+    return { ok: false, reason: `db:fork REPLACES ${stage}'s database with ${from}'s data — confirm with --confirm.` };
+  }
+  const pii = crossStageGuard(from, stage);
+  return { ok: true, piiWarning: pii.requiresConfirm ? (pii.warning ?? null) : null };
+}
+
+export async function dbForkCommand(flags: Record<string, string>): Promise<void> {
+  const verdict = checkForkGuards({
+    from: flags['from-stage'],
+    stage: flags.stage,
+    confirm: flags.confirm === 'true',
+  });
+  if (!verdict.ok) {
+    fail(verdict.reason);
+    process.exit(1);
+  }
+  if (verdict.piiWarning) warn(verdict.piiWarning.replace(/pass --confirm to proceed\.?$/i, 'confirmed.'));
+
+  const from = flags['from-stage'];
+  const target = flags.stage;
+
+  step(`Resolving source stage ${from}...`);
+  let source: CliConfig;
+  try {
+    source = await resolveConfig(from);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (!source.backupsBucket) {
+    fail(`Stage ${from} has no backupsBucket in its deployed config — logical backups are the fork's transport (docs/backups.md).`);
+    process.exit(1);
+  }
+
+  // Move 1: a backup of the source — fresh by default, or a named one.
+  let backupId = flags.backup;
+  if (backupId && backupId !== 'true') {
+    const ref = parseBackupRef(backupId);
+    if (!ref || !keyForId(backupId)) {
+      fail(`Malformed backup id: ${backupId}`);
+      process.exit(1);
+    }
+    if (ref.stage !== from) {
+      fail(`Backup ${backupId} belongs to stage "${ref.stage}", not --from-stage ${from} — a fork's data names its source honestly.`);
+      process.exit(1);
+    }
+    info(`Reusing backup ${backupId}.`);
+  } else {
+    step(`Backing up ${from} (pg_dump → S3; may take a while for large databases)...`);
+    const result: any = await invokeAction(source.region, opsFunction(source), 'db:backup', { stage: from });
+    if (result?.error) {
+      fail(`Source backup failed: ${result.error}`);
+      process.exit(1);
+    }
+    backupId = result.id;
+    info(`Backup ${backupId}.`);
+  }
+
+  // Move 2: the presigned hand-off — the operator's credentials ARE the authorization.
+  step('Presigning the dump (1 hour)...');
+  let url: string;
+  try {
+    url = await presignGet(source.region, source.backupsBucket, keyForId(backupId)!, 3600);
+  } catch (err: any) {
+    fail(`Presign failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Move 3: restore into the target over the URL.
+  step(`Resolving target stage ${target}...`);
+  let targetConfig: CliConfig;
+  try {
+    targetConfig = await resolveConfig(target);
+  } catch (err: any) {
+    fail(`${err.message}\nDeploy the feature stage first: sst deploy --stage ${target}`);
+    process.exit(1);
+  }
+  step(`Restoring into ${target} (streamed; replaces its database)...`);
+  const restored: any = await invokeAction(targetConfig.region, opsFunction(targetConfig), 'db:restore', {
+    url,
+    confirm: true,
+  });
+  if (restored?.error) {
+    fail(`Restore failed: ${restored.error}`);
+    process.exit(1);
+  }
+
+  success(`Forked ${from} → ${target} (backup ${backupId}).`);
+  info('Next:');
+  info(`  everystack db:fingerprint --stage ${target}     # where the fork is (a state some main commit declares)`);
+  info(`  everystack db:plan --stage ${target}            # your branch's edge on top — descent composes for free`);
+  info(`  sst remove --stage ${target}                    # teardown takes the database with it`);
+}

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

@@ -25,6 +25,8 @@ import { introspectSchema } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan.js';
 import { verifyDescent } from '../git-descent.js';
+import { planBackfills, readBackfillLog } from '../backfill.js';
+import { readSqlDirIfPresent } from './db-sync.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
@@ -113,6 +115,25 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
         warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
       }
     }
+
+    // Visibility, never automation (brick 8): the review surface names the
+    // target's pending backfills — expand → backfill → contract stays a
+    // sequence of deliberate acts, and a contraction plan minted while its
+    // data move is unrun should be caught by the human reading this.
+    const backfillFiles = await readSqlDirIfPresent('db/backfills');
+    if (backfillFiles !== null) {
+      try {
+        const bf = planBackfills(backfillFiles, await readBackfillLog(runner));
+        if (bf.blocked.length > 0) {
+          warn(`${bf.blocked.length} backfill(s) BLOCKED on this target (edited after running) — everystack db:backfill names the fix.`);
+        }
+        if (bf.pending.length > 0) {
+          warn(`${bf.pending.length} backfill(s) pending on this target: ${bf.pending.map((p) => p.file).join(', ')} — run them deliberately (db:backfill --apply) before a contraction lands.`);
+        }
+      } catch (err: any) {
+        warn(`backfill lane: could not read everystack.backfill_log (${err.message}) — pending-backfill visibility unavailable.`);
+      }
+    }
     if (out !== '-') {
       success(`Wrote ${out} — review it, then \`everystack db:apply --plan ${out}\`.`);
       warn('Plans are ephemeral release artifacts — attach to the run, do NOT commit.');

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

@@ -46,6 +46,7 @@ import { fingerprintModels } from '../schema-fingerprint.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import type { SourceFile } from '../derived-source.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { planBackfills, readBackfillLog } from '../backfill.js';
 import { resolveModelsPath } from '../models-path.js';
 import { executeReconcile, buildReconcileReport, type ReconcileRun } from './db-reconcile.js';
 import { loadModels } from './db-generate.js';
@@ -294,8 +295,22 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
       },
     );
 
+    // Visibility, never automation (brick 8): pending backfills surface
+    // here, but a schema verb never runs a data job.
+    let backfills: { pending: number; blocked: number } | null = null;
+    const backfillFiles = await readSqlDirIfPresent('db/backfills');
+    if (backfillFiles !== null) {
+      try {
+        const bf = planBackfills(backfillFiles, await readBackfillLog(runner));
+        backfills = { pending: bf.pending.length, blocked: bf.blocked.length };
+      } catch (err: any) {
+        warn(`backfill lane: could not read everystack.backfill_log (${err.message}) — pending-backfill visibility unavailable.`);
+      }
+    }
+
     if (flags.json === 'true') {
       console.log(JSON.stringify({
+        backfills,
         state: {
           applied: run.state.applied,
           executed: run.state.classified.executable.length,
@@ -317,6 +332,12 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
       }, null, 2));
     } else {
       for (const line of buildSyncReport(run)) info(line);
+      if (backfills && backfills.blocked > 0) {
+        warn(`${backfills.blocked} backfill(s) BLOCKED (edited after running) — everystack db:backfill names the fix.`);
+      }
+      if (backfills && backfills.pending > 0) {
+        info(`· ${backfills.pending} backfill(s) pending — data jobs run deliberately, never as a sync side effect: everystack db:backfill --apply`);
+      }
       console.log('');
       if (!run.converged) {
         fail('NOT converged — fix the findings above and re-run db:sync.');

package/src/cli/commands/runbook.ts

@@ -36,9 +36,10 @@ function cliVersion(): string {
 }
 
 /** Import the app's Model barrel for the data-model chapter. Absent or unloadable → honest warning, no chapter. */
-async function loadDataModel(root: string, hasIndex: boolean): Promise<{ dataModel: string | null; warning: string | null }> {
-  if (!hasIndex) return { dataModel: null, warning: null };
-  const barrel = path.join(root, 'models', 'index.ts');
+async function loadDataModel(root: string, models: { dir: string | null; hasIndex: boolean }): Promise<{ dataModel: string | null; warning: string | null }> {
+  if (!models.hasIndex || !models.dir) return { dataModel: null, warning: null };
+  // The detected home (db/models preferred, legacy models/ fallback) — never hardcoded.
+  const barrel = path.join(root, models.dir, 'index.ts');
   try {
     const mod = await import(pathToFileURL(barrel).href);
     const models = mod.models ?? mod.default;
@@ -64,7 +65,7 @@ export interface RunbookRun {
 /** Result-producing core, shared by the command, `--check`, and the `audit` capstone. */
 export async function runRunbook(root: string): Promise<RunbookRun> {
   const reality = detectProjectReality(root);
-  const { dataModel, warning } = await loadDataModel(reality.root, reality.models.hasIndex);
+  const { dataModel, warning } = await loadDataModel(reality.root, reality.models);
   const outPath = path.join(reality.root, OUT_REL);
   const oldText = fs.existsSync(outPath) ? fs.readFileSync(outPath, 'utf8') : null;
   const result = generateRunbook(reality, { cliVersion: cliVersion(), dataModel }, oldText ?? undefined);