@everystack/cli 0.2.39 → 0.3.0

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

@@ -0,0 +1,83 @@
+/**
+ * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
+ *
+ *   db:pull --stage <name> [--schema public] [--out models/index.ts]
+ *
+ * The reverse of db:generate: that writes migrations FROM Models; this writes Models FROM the
+ * database. It introspects the deployed schema through the read-only ops Lambda `db:query`
+ * action and renders the TypeScript a Model is written in — a starting point you review and
+ * refine (it flags, as inline comments, anything the field builder can't yet express).
+ *
+ * The rendered source is the artifact: it goes to stdout (so `db:pull > models.ts` works) or
+ * to `--out`. Every progress/diagnostic line goes to stderr, so the stdout pipe stays pure
+ * source. The renderer (model-render.ts) is pure; this shell is the IO.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { introspectSchema } from '../schema-introspect.js';
+import { renderModelSource } from '../model-render.js';
+import type { QueryRunner } from '../authz-contract.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { fail } from '../output.js';
+
+// Progress → stderr, so stdout carries only the rendered source (this command is codegen,
+// not a report — the shared output helpers write to stdout, which would corrupt a redirect).
+const note = (m: string) => console.error(`  > ${m}`);
+const ok = (m: string) => console.error(`  ✓ ${m}`);
+const detail = (m: string) => console.error(`  ${m}`);
+const caution = (m: string) => console.error(`  ! ${m}`);
+
+/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
+function lambdaRunner(region: string, fn: string): QueryRunner {
+  return async (sql: string) => {
+    const result: any = await invokeAction(region, fn, 'db:query', { sql });
+    if (result?.error) throw new Error(`Introspection query failed: ${result.error}`);
+    return result?.rows ?? [];
+  };
+}
+
+export async function dbPullCommand(flags: Record<string, string>): Promise<void> {
+  const schema = flags.schema || 'public';
+
+  let current;
+  try {
+    note('Resolving deployed config...');
+    const config = await resolveConfig(flags.stage);
+    detail(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+    note(`Introspecting live database (schema: ${schema})...`);
+    current = await introspectSchema(lambdaRunner(config.region, opsFunction(config)));
+  } catch (err: any) {
+    fail(err.message);
+    detail('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
+    process.exit(1);
+  }
+
+  const pulled = current.tables.filter((t) => t.table.startsWith(`${schema}.`));
+  if (pulled.length === 0) {
+    fail(`No tables found in schema "${schema}".`);
+    process.exit(1);
+  }
+
+  const source = renderModelSource(current, { schema });
+
+  if (flags.out) {
+    const outPath = path.resolve(flags.out);
+    try {
+      await fs.mkdir(path.dirname(outPath), { recursive: true });
+      await fs.writeFile(outPath, source, 'utf8');
+    } catch (err: any) {
+      fail(`Could not write ${flags.out}: ${err.message}`);
+      process.exit(1);
+    }
+    ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${pulled.length} model(s).`);
+  } else {
+    process.stdout.write(source);
+    ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
+  }
+
+  const flagged = (source.match(/\/\/ (FIXME|TODO|composite|CHECK|FK →)/g) ?? []).length;
+  if (flagged) caution(`${flagged} inline comment(s) flag things to review (unmapped types, checks, cross-schema FKs).`);
+  process.exit(0);
+}

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

@@ -0,0 +1,113 @@
+/**
+ * db:snapshot / db:snapshots — RDS *physical* snapshots, the thin `aws rds` control-plane wrapper.
+ *
+ * Unlike db:backup (logical pg_dump, runs in the ops Lambda), these are plain RDS management calls
+ * made directly from the CLI with the operator's IAM — no Lambda, no VPC, no pg_dump layer. They
+ * only apply when the DB is an RDS instance; for any other Postgres, use db:backup. See
+ * docs/plans/db-backup-restore.md.
+ */
+
+import { resolveConfig, type CliConfig } from '../config.js';
+import { createRdsSnapshot, describeRdsSnapshots, type RdsSnapshotSummary } from '../aws.js';
+import { utcStamp } from '../backup.js';
+import { rdsSnapshotIdentifier } from '../rds-snapshot.js';
+import { step, success, fail, info } from '../output.js';
+
+/**
+ * Resolve the RDS DB instance identifier: explicit `--instance` wins, else the deployed
+ * `databaseInstanceId` stack output. A missing or `placeholder` value means the DB isn't RDS (or
+ * the stage is in dev mode) — fail with a pointer to db:backup rather than calling AWS with junk.
+ */
+function resolveInstanceId(config: CliConfig, flags: Record<string, string>): string {
+  const id = flags.instance ?? config.databaseInstanceId;
+  if (!id || id === 'placeholder') {
+    fail(
+      'No RDS instance id available. db:snapshot needs an RDS instance.\n' +
+      '  - If your DB is RDS: redeploy so the `databaseInstanceId` output is present, or pass --instance <id>.\n' +
+      '  - If your DB is not RDS (Aurora, a container, self-hosted): use `everystack db:backup` for a portable logical backup.',
+    );
+    process.exit(1);
+  }
+  return id;
+}
+
+/** Only an authorization failure warrants the IAM hint; other RDS errors (state, quota) don't. */
+function isAccessDenied(err: any): boolean {
+  const name = String(err?.name ?? '');
+  return /AccessDenied|Unauthorized|NotAuthorized/i.test(name);
+}
+
+function fmtSize(gib?: number): string {
+  return gib == null ? '-' : `${gib} GiB`;
+}
+
+function fmtDate(d?: Date): string {
+  return d ? d.toISOString().replace('.000Z', 'Z') : '(creating)';
+}
+
+export async function dbSnapshotCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const instanceId = resolveInstanceId(config, flags);
+  const snapshotId = rdsSnapshotIdentifier(flags.stage ?? 'manual', utcStamp(new Date()));
+
+  info(`Region: ${config.region}, Instance: ${instanceId}`);
+  step(`Creating RDS snapshot ${snapshotId}...`);
+
+  try {
+    const snap = await createRdsSnapshot(config.region, instanceId, snapshotId);
+    success(`Snapshot ${snap.identifier} (${snap.status}) — physical RDS image of ${instanceId}.`);
+    info('It becomes restorable once status is "available". Track it with `everystack db:snapshots`.');
+  } catch (err: any) {
+    fail(`Snapshot failed: ${err.message}`);
+    if (isAccessDenied(err)) {
+      info('Ensure your IAM identity has rds:CreateDBSnapshot on this instance.');
+    } else if (/not currently in the available state|InvalidDBInstanceState/i.test(String(err?.message ?? err?.name))) {
+      info('The instance is busy (another snapshot may be in progress). Wait for it to finish, then retry.');
+    }
+    process.exit(1);
+  }
+}
+
+export async function dbSnapshotsCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const instanceId = resolveInstanceId(config, flags);
+  step(`Listing manual RDS snapshots for ${instanceId}...`);
+
+  let snaps: RdsSnapshotSummary[];
+  try {
+    snaps = await describeRdsSnapshots(config.region, instanceId);
+  } catch (err: any) {
+    fail(`List failed: ${err.message}`);
+    if (isAccessDenied(err)) {
+      info('Ensure your IAM identity has rds:DescribeDBSnapshots.');
+    }
+    process.exit(1);
+  }
+
+  if (snaps.length === 0) {
+    info('No manual snapshots. Create one with `everystack db:snapshot`.');
+    return;
+  }
+
+  for (const s of snaps) {
+    const enc = s.encrypted ? ' [encrypted]' : '';
+    info(`${s.identifier}  ${s.status.padEnd(10)}  ${fmtSize(s.sizeGiB).padEnd(8)}  pg${s.engineVersion ?? '?'}  ${fmtDate(s.created)}${enc}`);
+  }
+  success(`${snaps.length} snapshot${snaps.length === 1 ? '' : 's'}.`);
+}

package/src/cli/commands/deploy.ts

@@ -0,0 +1,46 @@
+/**
+ * `everystack deploy` — deploy the stack's infrastructure.
+ *
+ * A thin wrapper over `sst deploy` so a consumer never has to type or know about SST: the
+ * framework owns the infra tool, the consumer just runs `everystack deploy --stage <name>`.
+ * Infra only — migrations (`db:migrate`) and OTA (`update`) stay explicit, the same split
+ * `sst deploy` itself has.
+ *
+ * The arg build is pure (unit-tested); the command streams sst's output through and exits
+ * with its code so CI sees a failed deploy.
+ */
+
+import { spawn } from 'node:child_process';
+import { step, success, fail, info } from '../output.js';
+
+/** The `sst` argv `everystack deploy` runs. Pure, so the mapping is unit-tested. */
+export function buildDeployArgs(flags: Record<string, string>): string[] {
+  const stage = flags.stage || 'dev';
+  return ['sst', 'deploy', '--stage', stage];
+}
+
+export async function deployCommand(flags: Record<string, string>): Promise<void> {
+  const stage = flags.stage || 'dev';
+  const args = buildDeployArgs(flags);
+
+  step(`Deploying stage "${stage}"...`);
+  await new Promise<void>((resolve) => {
+    // `npx` resolves the consumer's local sst (the same way the export step runs expo).
+    const child = spawn('npx', args, { stdio: 'inherit', env: { ...process.env, FORCE_COLOR: '1' } });
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        fail(`Deploy failed (exit ${code}).`);
+        process.exit(code ?? 1);
+      }
+    });
+    child.on('error', (err) => {
+      fail(`Could not run sst: ${err.message}`);
+      info('Install it as a dev dependency: `pnpm add -D sst`.');
+      process.exit(1);
+    });
+  });
+  success(`Deployed stage "${stage}".`);
+  info('Next: `everystack db:migrate --stage ' + stage + '` to apply migrations, `everystack update` to publish the app bundle.');
+}

package/src/cli/config.ts

@@ -24,6 +24,10 @@ export interface CliConfig {
   mediaBucket?: string;
   kvsArn?: string;
   distributionId?: string;
+  /** RDS DB instance identifier (for db:snapshot). Absent when the DB isn't RDS or in dev mode. */
+  databaseInstanceId?: string;
+  /** Private S3 bucket holding logical backups (for db:backup:download presign). */
+  backupsBucket?: string;
 }
 
 /** Operator invoke target — dedicated ops function when deployed, else the API function. */
@@ -44,6 +48,8 @@ interface SstOutputs {
   mediaBucket?: string;
   kvsArn?: string;
   distributionId?: string;
+  databaseInstanceId?: string;
+  backupsBucket?: string;
 }
 
 export async function resolveConfig(stage?: string): Promise<CliConfig> {
@@ -115,5 +121,7 @@ export async function resolveConfig(stage?: string): Promise<CliConfig> {
     mediaBucket: outputs.mediaBucket,
     kvsArn: outputs.kvsArn,
     distributionId: outputs.distributionId,
+    databaseInstanceId: outputs.databaseInstanceId,
+    backupsBucket: outputs.backupsBucket,
   };
 }

package/src/cli/index.ts

@@ -3,10 +3,16 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { updateCommand } from './commands/update.js';
+import { deployCommand } from './commands/deploy.js';
 import { certsCommand } from './commands/certs.js';
 import { channelsCommand } from './commands/channels.js';
 import { branchesCommand } from './commands/branches.js';
 import { dbMigrateCommand, dbSeedCommand, dbResetCommand, dbPsqlCommand, dbDoctorCommand, dbProvisionCommand } from './commands/db.js';
+import { dbAuthzPullCommand, dbAuthzDiffCommand, dbAuthzTestCommand, dbAuthzOwnerCommand, dbAuthzReportCommand } from './commands/db-authz.js';
+import { dbGenerateCommand } from './commands/db-generate.js';
+import { dbPullCommand } from './commands/db-pull.js';
+import { dbSnapshotCommand, dbSnapshotsCommand } from './commands/db-snapshot.js';
+import { dbBackupProbeCommand, dbBackupCommand, dbBackupsCommand, dbRestoreCommand, dbBackupDownloadCommand } from './commands/db-backup.js';
 import { consoleCommand } from './commands/console.js';
 import { cachePurgeCommand } from './commands/cache.js';
 import { statusCommand } from './commands/status.js';
@@ -91,6 +97,9 @@ async function main() {
     case 'update':
       await updateCommand(flags);
       break;
+    case 'deploy':
+      await deployCommand(flags);
+      break;
     case 'certs:generate':
       await certsCommand('generate', flags);
       break;
@@ -121,6 +130,50 @@ async function main() {
     case 'db:provision':
       await dbProvisionCommand(flags);
       break;
+    case 'db:snapshot':
+      await dbSnapshotCommand(flags);
+      break;
+    case 'db:snapshots':
+      await dbSnapshotsCommand(flags);
+      break;
+    case 'db:backup:probe':
+      await dbBackupProbeCommand(flags);
+      break;
+    case 'db:backup':
+      await dbBackupCommand(flags);
+      break;
+    case 'db:backups':
+      await dbBackupsCommand(flags);
+      break;
+    case 'db:restore':
+      await dbRestoreCommand(flags);
+      break;
+    case 'db:backup:download': {
+      const backupId = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+      await dbBackupDownloadCommand(flags, backupId);
+      break;
+    }
+    case 'db:generate':
+      await dbGenerateCommand(flags);
+      break;
+    case 'db:pull':
+      await dbPullCommand(flags);
+      break;
+    case 'db:authz:pull':
+      await dbAuthzPullCommand(flags);
+      break;
+    case 'db:authz:diff':
+      await dbAuthzDiffCommand(flags);
+      break;
+    case 'db:authz:test':
+      await dbAuthzTestCommand(flags);
+      break;
+    case 'db:authz:owner':
+      await dbAuthzOwnerCommand(flags);
+      break;
+    case 'db:authz:report':
+      await dbAuthzReportCommand(flags);
+      break;
     case 'console':
       await consoleCommand(flags);
       break;
@@ -181,6 +234,7 @@ function printHelp() {
 everystack - CLI for Expo apps on everystack
 
 Usage:
+  everystack deploy            [--stage <name>]  Deploy infrastructure (wraps sst deploy — no need to know SST)
   everystack update            --branch <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--skip-export]
   everystack update            --channel <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--skip-export]
   everystack db:migrate        [--stage <name>]  Run database migrations on deployed Lambda
@@ -190,6 +244,20 @@ Usage:
   everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (works for private RDS)
   everystack db:doctor         [--stage <name>]  Check the DB is least-privilege + RLS-subject (api vs operator connection)
   everystack db:provision      [--stage <name>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB)
+  everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
+  everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
+  everystack db:backup:probe   [--stage <name>]  Verify the pg_dump layer is attached + version-compatible with the server
+  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id)
+  everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
+  everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
+  everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
+  everystack db:generate       [--stage <name>] [--name <label>] [--models models/index.ts] [--allow-drops]  Diff models vs the live DB → write the next migration (never touches the DB; DROPs held back unless --allow-drops)
+  everystack db:pull           [--stage <name>] [--schema public] [--out <file>]  Introspect the live DB → render field() Models (the brownfield on-ramp; stdout unless --out)
+  everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
+  everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
+  everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)
+  everystack db:authz:owner    [--stage <name>] [--models models/index.ts]  Red-team owner isolation: two JWT identities per owner-scoped table — catches IDOR (non-zero exit on a leak)
+  everystack db:authz:report   [--dir authz]  Render the committed contract as a human-readable authorization review (no DB)
   everystack console           --stage <name> [--sandbox]  Interactive REPL on deployed Lambda
   everystack status            [--stage <name>] [--hours <n>]  Platform health: CDN, Lambda, rollup summary
   everystack security:audit    [--dir <path>] [--config <file>]  Static scan of migration SQL (pre-merge gate)

package/src/cli/migration-compile.ts

@@ -0,0 +1,69 @@
+/**
+ * The one generator — compose the Model into a single ordered migration.
+ *
+ * This is the unified-migration thesis made concrete: a set of Models compiles to
+ * ONE ordered list of SQL statements covering *both* layers, in dependency order:
+ *
+ *   1. CREATE TABLE …            (data — fields → DDL + CHECK)
+ *   2. ALTER TABLE … FOREIGN KEY (data — references, after every table exists)
+ *   3. ENABLE/FORCE RLS · policies · grants   (authz — abilities, after the
+ *                                              columns they reference exist)
+ *
+ * It is not two pipelines: the authz statements reference columns the DDL just
+ * created, so they live in the same ordered migration. This composes the four
+ * compilers already built — compileCreateTable + foreignKeySql (data) and
+ * compileTableContract + emitReconcileSql (authz) — with no new SQL emission.
+ *
+ * This is the greenfield form (empty database → the whole schema). The brownfield
+ * form diffs against an introspected snapshot instead of the empty baseline; that
+ * lands with whole-DB introspection. The emission is identical either way.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { AuthzContract, TableContract } from './authz-contract.js';
+import { compileCreateTable, compileEnums, foreignKeySql, modelConstraintSpecs, type CompileTableOptions } from './schema-compile.js';
+import { compileTableContract } from './authz-compile.js';
+import { emitReconcileSql } from './authz-reconcile.js';
+import { emitSchemaSql, type SchemaChange } from './schema-diff.js';
+
+/** The empty (not-yet-created) authz state for a table — the greenfield baseline. */
+function emptyTable(table: string): TableContract {
+  return { table, rls: { enabled: false, forced: false }, grants: {}, policies: [] };
+}
+
+/**
+ * Compile a set of Models into one ordered migration (greenfield: empty DB → full
+ * schema). Tables, then foreign keys, then authz — the order a fresh database must
+ * apply them in.
+ */
+export function compileMigration(models: ModelDescriptor[], opts: CompileTableOptions = {}): string[] {
+  const sql: string[] = [];
+
+  // 0. Enum types — `CREATE TYPE … AS ENUM`, before any table/column references them.
+  const enumCreates: SchemaChange[] = compileEnums(models).map((e) => ({ kind: 'createType', name: e.name, values: e.values }));
+  sql.push(...emitSchemaSql(enumCreates));
+
+  // 1. Tables (with columns, CHECKs, single/composite PK, uniques).
+  for (const model of models) sql.push(compileCreateTable(model, opts));
+
+  // 2. Foreign keys — after every table exists.
+  for (const model of models) sql.push(...foreignKeySql(model));
+
+  // 2b. Standalone indexes — after the columns they cover exist.
+  const indexCreates: SchemaChange[] = [];
+  for (const model of models) {
+    for (const ix of modelConstraintSpecs(model).indexes) {
+      indexCreates.push({ kind: 'createIndex', table: `"${model.table}"`, name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) });
+    }
+  }
+  sql.push(...emitSchemaSql(indexCreates));
+
+  // 3. Authz — RLS + policies + grants, after the columns they reference. Reuse
+  //    the reconcile emitter against the empty baseline: every policy/grant is a
+  //    pure creation, in the same dependency-correct order reconcile already uses.
+  const desired: AuthzContract = { tables: models.map((m) => compileTableContract(m)), functions: [] };
+  const baseline: AuthzContract = { tables: models.map((m) => emptyTable(`public.${m.table}`)), functions: [] };
+  sql.push(...emitReconcileSql(desired, baseline));
+
+  return sql;
+}

package/src/cli/migration-generate.ts

@@ -0,0 +1,175 @@
+/**
+ * `db:generate`'s pure core — Models + live snapshot → a migration file.
+ *
+ * The brownfield generator, composed from the pieces already built and proven:
+ *
+ *   compileTableSchema + compileRenames (the desired side, from the Models)
+ *     → diffSchema (vs the introspected `current`)
+ *     → emitSchemaSql (the ALTER/CREATE/RENAME DDL)
+ *
+ * A whole *new* table renders through the greenfield `compileCreateTable` (byte-identical
+ * to what the app ships) rather than the IR renderer; its foreign keys still arrive as the
+ * diff's `addConstraint` changes, so they land after every table exists.
+ *
+ * Everything here is pure and deterministic — the clock (`when`) is injected, never read —
+ * so the command shell (commands/db-generate.ts) is a thin layer of IO over it.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect.js';
+import type { AuthzContract } from './authz-contract.js';
+import { compileTableSchema, compileRenames, compileCreateTable, compileEnums } from './schema-compile.js';
+import { compileTableContract } from './authz-compile.js';
+import { emitReconcileSql } from './authz-reconcile.js';
+import { diffSchema, emitSchemaSql, type SchemaChange } from './schema-diff.js';
+
+export interface GenerateOptions {
+  /** The Postgres schema the Models live in. Default: `public`. */
+  schema?: string;
+  /**
+   * Emit real `DROP COLUMN`/`DROP CONSTRAINT`/`DROP TABLE` for things present in the
+   * database but absent from the Models. Default `false` — those are held back as
+   * commented notices (see {@link HELD_DROP_PREFIX}), so a partial or lossy Model set
+   * never silently loses data. Destruction needs intent, the same rule renames are built on.
+   */
+  allowDrops?: boolean;
+  /**
+   * The live authorization contract (`introspectContract`). When provided, the migration
+   * carries the authz layer too — the Models' `abilities` compiled to RLS/policies/grants,
+   * diffed against this live state, appended after the data phase as one ordered file (the
+   * unified-migration thesis: declare once, generate both layers). Omitted → data-only, the
+   * backward-compatible default. Authz drops (`DROP POLICY`/`REVOKE`) are data-safe, so they
+   * are emitted regardless of `allowDrops` — `allowDrops` gates only data destruction.
+   */
+  liveAuthz?: AuthzContract;
+}
+
+/** The comment prefix a held-back destructive change carries (the command greps it to count them). */
+export const HELD_DROP_PREFIX = '-- DROP held back';
+
+/**
+ * A destructive change that removes data or an integrity guard with no re-creation —
+ * the set held back unless `allowDrops`. A constraint *replace* (a `dropConstraint`
+ * paired with an `addConstraint` of the same name) is NOT a removal: it loses no data
+ * and its add depends on the drop, so it is kept intact.
+ */
+function isRemoval(change: SchemaChange, replacedConstraints: Set<string>): boolean {
+  if (change.kind === 'dropColumn' || change.kind === 'dropTable' || change.kind === 'dropType' || change.kind === 'dropIndex') return true;
+  if (change.kind === 'dropConstraint') return !replacedConstraints.has(`${change.table}::${change.name}`);
+  return false;
+}
+
+/** Comment out a destructive statement, showing the exact DDL to run by hand or with `--allow-drops`. */
+function holdDrop(sql: string): string {
+  return `${HELD_DROP_PREFIX} (destructive — re-run db:generate with --allow-drops to emit it, or run it by hand):\n-- ${sql}`;
+}
+
+/**
+ * Tables present in the live database that no model declares. `db:generate` leaves these
+ * untouched — they belong to another concern (auth, jobs, observability all ship their own
+ * migrations), and dropping a table must be deliberate, never a side effect of a missing
+ * model. The command reports the count so the omission is visible, not silent.
+ */
+export function unmodeledTables(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
+  const schema = opts.schema ?? 'public';
+  const declared = new Set(models.map((m) => `${schema}.${m.table}`));
+  return current.tables.map((t) => t.table).filter((t) => !declared.has(t)).sort();
+}
+
+/**
+ * Compile the Models into the ordered SQL that evolves `current` to match them. Empty when
+ * the database already matches (the no-op generate).
+ *
+ * Scoped to the tables the models DECLARE: the diff never sees a table no model owns, so it
+ * cannot propose dropping one. db:generate manages your declared schema; everything else in
+ * the database (auth, jobs, observability) is left to its own migrations.
+ */
+export function generateMigrationSql(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
+  const schema = opts.schema ?? 'public';
+  const desiredEnums = compileEnums(models);
+  const desired: SchemaSnapshot = { tables: models.map((m) => compileTableSchema(m, { schema })), enums: desiredEnums };
+  const declaredTables = new Set(desired.tables.map((t) => t.table));
+  const declaredEnums = new Set(desiredEnums.map((e) => e.name));
+  // Scope both tables and enums to what the Models declare — an undeclared table OR enum
+  // (auth, jobs, observability ship their own) is invisible to the diff, so it is never dropped.
+  const scopedCurrent: SchemaSnapshot = {
+    tables: current.tables.filter((t) => declaredTables.has(t.table)),
+    enums: (current.enums ?? []).filter((e) => declaredEnums.has(e.name)),
+  };
+  const renames = compileRenames(models, { schema });
+  const changes = diffSchema(desired, scopedCurrent, renames);
+
+  const modelByTable = new Map(models.map((m) => [`${schema}.${m.table}`, m]));
+  const emitted = emitSchemaSql(changes, {
+    createTable: (change) => {
+      const model = modelByTable.get(change.table);
+      if (!model) throw new Error(`db:generate: no model found for new table ${change.table}`);
+      return compileCreateTable(model);
+    },
+  });
+
+  // Non-destructive by default: a column/constraint/table in the database but absent
+  // from the Models would otherwise become a DROP — silent data loss for a partial or
+  // lossy Model set. Hold removals back as comments unless `allowDrops`. emitSchemaSql
+  // returns one statement per change, index-aligned, so the gate stays a pure
+  // post-pass — `diffSchema`/`emitSchemaSql` remain honest (they always emit the DROP).
+  let dataPhase = emitted;
+  if (!opts.allowDrops) {
+    const replacedConstraints = new Set(
+      changes
+        .filter((c): c is Extract<SchemaChange, { kind: 'addConstraint' }> => c.kind === 'addConstraint')
+        .map((c) => `${c.table}::${c.constraint.name}`),
+    );
+    dataPhase = emitted.map((sql, i) => (isRemoval(changes[i], replacedConstraints) ? holdDrop(sql) : sql));
+  }
+
+  // Authz phase — appended after the data phase so a policy/grant references columns the
+  // data DDL just created. Emitted only when the live contract is supplied; the Models'
+  // `abilities` compile to the same contract shape introspection reads, so the two diff.
+  // Authz changes are data-safe (no row touches), so they are never held by `allowDrops`.
+  const authzPhase = opts.liveAuthz
+    ? emitReconcileSql({ tables: models.map((m) => compileTableContract(m, { schema })), functions: [] }, opts.liveAuthz)
+    : [];
+
+  return [...dataPhase, ...authzPhase];
+}
+
+/** The marker drizzle migration files put between statements. */
+const BREAKPOINT = '\n--> statement-breakpoint\n';
+
+/** Join statements into a drizzle-compatible migration file body (trailing newline). */
+export function formatMigrationFile(statements: string[]): string {
+  return statements.join(BREAKPOINT) + '\n';
+}
+
+export interface JournalEntry {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+}
+
+export interface Journal {
+  version: string;
+  dialect: string;
+  entries: JournalEntry[];
+}
+
+/** Sanitize a migration name into the snake_case the `NNNN_<tag>.sql` convention uses. */
+function sanitizeName(name: string): string {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'generated';
+}
+
+/**
+ * Plan the next migration file: its tag, filename, and the journal with the new entry
+ * appended. Pure — `when` is passed in (the command stamps it with the clock), so the same
+ * inputs always produce the same plan. The next index is one past the highest existing
+ * `idx`, matching how the runner and drizzle order migrations.
+ */
+export function planMigrationFile(journal: Journal, name: string, when: number): { tag: string; filename: string; journal: Journal } {
+  const idx = journal.entries.reduce((max, e) => Math.max(max, e.idx + 1), 0);
+  const tag = `${String(idx).padStart(4, '0')}_${sanitizeName(name)}`;
+  const entry: JournalEntry = { idx, version: journal.version || '7', when, tag, breakpoints: true };
+  return { tag, filename: `${tag}.sql`, journal: { ...journal, entries: [...journal.entries, entry] } };
+}

package/src/cli/model-api.ts

@@ -0,0 +1,35 @@
+/**
+ * `@everystack/cli/model` — the programmatic surface of the v3 Model generator and red-team.
+ *
+ * Everything the CLI commands do (`db:generate`, `db:pull`, `db:authz:*`) is pure logic over a
+ * `QueryRunner`; this barrel exposes it so a consumer can generate and VERIFY their schema in
+ * their own tests/CI without shelling out to the CLI. The reference app dogfoods exactly this
+ * surface — its real Models are round-tripped through `compileMigration` / `generateMigrationSql`
+ * and red-teamed with the owner probe, against a real Postgres, proving the generator on a real app.
+ *
+ * The two entry shapes:
+ *   - GENERATE: `compileMigration(models)` (greenfield) or `generateMigrationSql(models, snapshot,
+ *     { liveAuthz })` (brownfield, both layers) → ordered SQL.
+ *   - VERIFY: `introspectSchema(run)` / `introspectContract(run, …)` → diff against the Models, and
+ *     `buildOwnerProbeSql` / `evaluateOwnerProbe` for behavioural owner-isolation checks.
+ */
+
+// --- data layer: compile, introspect, diff, render -------------------------
+export * from './schema-compile.js';
+export * from './schema-introspect.js';
+export * from './schema-diff.js';
+export * from './model-render.js';
+export * from './migration-compile.js';
+export * from './migration-generate.js';
+
+// --- authz layer: contract compile/introspect/diff/reconcile ---------------
+export * from './authz-compile.js';
+export * from './authz-contract.js';
+export * from './authz-reconcile.js';
+
+// --- red-team: grant enforcement + owner isolation -------------------------
+export * from './authz-redteam.js';
+export * from './authz-owner-probe.js';
+
+// --- the SECDEF function catalog the contract introspection needs -----------
+export { FUNCTIONS_SQL, catalogFunctionToDescriptor } from './security-catalog.js';