@everystack/cli 0.2.39 → 0.3.3

package/src/cli/migration-compile.ts

@@ -0,0 +1,133 @@
+/**
+ * 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, Module } from '@everystack/model';
+import type { AuthzContract, TableContract } from './authz-contract.js';
+import { compileCreateTable, compileEnums, foreignKeySql, modelConstraintSpecs, qualifiedTable, 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[] = [];
+  const schemaOf = (m: ModelDescriptor): string => m.schema ?? 'public';
+
+  // 0a. Non-public schemas — `CREATE SCHEMA` for each distinct one a model lives in,
+  //     before any table is created in it. public is the implicit default, never emitted.
+  const schemas = [...new Set(models.map(schemaOf))].filter((s) => s !== 'public').sort();
+  sql.push(...schemas.map((s) => `CREATE SCHEMA IF NOT EXISTS "${s}";`));
+
+  // The authz contracts — computed once, used for the schema USAGE grants here and the
+  // table-level reconcile below.
+  const contracts = models.map((m) => compileTableContract(m));
+
+  // 0a-bis. Schema USAGE — a role can't reach a table in a non-public schema without USAGE on
+  //   it, so a table/column grant there is dead without this. Derived from the grants: every
+  //   role that holds any privilege on a table in a non-public schema gets USAGE on that schema
+  //   (public USAGE is granted to PUBLIC by default, so it is never emitted). This replaces the
+  //   hand-written `GRANT USAGE ON SCHEMA auth/ops/dist …` the old bootstrap carried.
+  for (const schema of schemas) {
+    const roles = new Set<string>();
+    for (const c of contracts) {
+      if (!c.table.startsWith(`${schema}.`)) continue;
+      for (const r of Object.keys(c.grants)) roles.add(r);
+      for (const r of Object.keys(c.columnGrants ?? {})) roles.add(r);
+    }
+    if (roles.size) {
+      const targets = [...roles].sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
+      sql.push(`GRANT USAGE ON SCHEMA "${schema}" TO ${targets};`);
+    }
+  }
+
+  // 0b. 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. The ON clause is the
+  //     schema-qualified table, so a non-public index targets the right table.
+  const indexCreates: SchemaChange[] = [];
+  for (const model of models) {
+    for (const ix of modelConstraintSpecs(model).indexes) {
+      indexCreates.push({ kind: 'createIndex', table: qualifiedTable(model), 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.
+  //    The baseline keys on each model's resolved schema, so a non-public table
+  //    diffs against its own empty state, not a phantom public one.
+  const desired: AuthzContract = { tables: contracts, functions: [] };
+  const baseline: AuthzContract = { tables: models.map((m) => emptyTable(`${schemaOf(m)}.${m.table}`)), functions: [] };
+  sql.push(...emitReconcileSql(desired, baseline));
+
+  return sql;
+}
+
+/**
+ * Compile a set of Modules into one COMPLETE greenfield migration — the whole deploy, no
+ * hand-written bootstrap left:
+ *
+ *   1. CREATE EXTENSION (deduped, sorted)        — the bootstrap a package's SQL needs
+ *   2. compileMigration(flattened models)        — schemas, tables, FKs, indexes, RLS, authz
+ *   3. package functions/triggers (each thunk)   — imperative package SQL, AFTER the tables
+ *
+ * Roles are NOT emitted — they are cluster-global (`db:provision`), and the GRANTs in step 2
+ * assume they exist (as the dogfood pre-creates them). `compileMigration` is left untouched as
+ * the schema+authz core the contract round-trips through; the functions are emitted verbatim
+ * here, outside that round-trip (they are imperative, package-owned — not modeled).
+ */
+export function compileModuleMigration(modules: Module[], opts: CompileTableOptions = {}): string[] {
+  const sql: string[] = [];
+
+  // 1. Extensions — deduped + sorted, quoted so a hyphenated name (`uuid-ossp`) is valid.
+  const extensions = [...new Set(modules.flatMap((m) => m.extensions))].sort();
+  sql.push(...extensions.map((e) => `CREATE EXTENSION IF NOT EXISTS "${e}";`));
+
+  // 2. Schema + authz for every modeled table.
+  sql.push(...compileMigration(modules.flatMap((m) => m.models), opts));
+
+  // 3. Package SQL — functions + triggers, after the tables they reference. Each thunk's
+  //    output is a self-contained multi-statement block applied as one unit.
+  for (const fn of modules.flatMap((m) => m.functions)) {
+    const text = fn().trim();
+    if (text) sql.push(text);
+  }
+
+  return sql;
+}

package/src/cli/migration-generate.ts

@@ -0,0 +1,178 @@
+/**
+ * `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';
+  // A table's schema comes from the model first (package tables live in dist/ops/auth),
+  // then the call default — so one run spans schemas.
+  const schemaOf = (m: ModelDescriptor): string => m.schema ?? schema;
+  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) => [`${schemaOf(m)}.${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,36 @@
+/**
+ * `@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 './schema-source.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';

package/src/cli/model-render.ts

@@ -0,0 +1,262 @@
+/**
+ * `db:pull`'s pure core — an introspected SchemaSnapshot back into `field()` model source.
+ *
+ * The inverse of compileTableSchema: that turns a Model into the structured schema; this
+ * turns the structured schema (read from a live database) into the TypeScript a Model is
+ * written in. The brownfield on-ramp — point at an existing database, get reviewable Models
+ * to start from.
+ *
+ * It renders what the field builder can express today (type, primary key, not-null,
+ * single-column unique, single-column references, the common defaults) and SURFACES what it
+ * can't as inline comments rather than faking it: an unmapped column type, a composite
+ * unique, a CHECK that needs a manual `.validate()`, a foreign key to a table outside the
+ * pulled set. Reversing a CHECK back to its Zod refinement is a later increment.
+ *
+ * Pure and deterministic — the command shell (commands/db-pull.ts) does the IO.
+ */
+
+import type { SchemaSnapshot, TableSchema, ColumnSchema, CheckConstraint } from './schema-introspect.js';
+import { normalizeDefault, normalizeCheck } from './schema-diff.js';
+
+/**
+ * Reverse a CHECK predicate back into the `.validate(z…)` that produced it — the inverse of
+ * `fieldCheckPredicate`. Only the stable, SQL-expressible shapes that compiler emits round-trip;
+ * anything else returns null and stays a raw `check(sql\`…\`)`. Returns the single column the
+ * check is on and the Zod expression, so the renderer can hang `.validate()` on that field.
+ */
+export function checkToValidate(expr: string): { column: string; zod: string } | null {
+  const s = normalizeCheck(expr);
+  let m: RegExpMatchArray | null;
+
+  if ((m = s.match(/^char_length\((\w+)\) = (\d+)$/))) return { column: m[1], zod: `z.string().length(${m[2]})` };
+  if ((m = s.match(/^char_length\((\w+)\) BETWEEN (\d+) AND (\d+)$/))) return { column: m[1], zod: `z.string().min(${m[2]}).max(${m[3]})` };
+  if ((m = s.match(/^char_length\((\w+)\) >= (\d+)$/))) return { column: m[1], zod: `z.string().min(${m[2]})` };
+  if ((m = s.match(/^char_length\((\w+)\) <= (\d+)$/))) return { column: m[1], zod: `z.string().max(${m[2]})` };
+
+  if ((m = s.match(/^(\w+) BETWEEN (-?\d+(?:\.\d+)?) AND (-?\d+(?:\.\d+)?)$/))) return { column: m[1], zod: `z.number().min(${m[2]}).max(${m[3]})` };
+
+  if ((m = s.match(/^(\w+) IN \((.+)\)$/))) {
+    const vals = m[2].split(',').map((v) => v.trim());
+    if (vals.length && vals.every((v) => /^'.*'$/.test(v))) {
+      const items = vals.map((v) => v.slice(1, -1).replace(/''/g, "'"));
+      return { column: m[1], zod: `z.enum([${items.map((i) => JSON.stringify(i)).join(', ')}])` };
+    }
+    return null;
+  }
+
+  // One or more numeric comparisons on the same column (`x >= 1`, `x > 1 AND x < 10`).
+  let column: string | null = null;
+  const chain: string[] = [];
+  for (const part of s.split(' AND ')) {
+    const c = part.match(/^(\w+) (>=|>|<=|<) (-?\d+(?:\.\d+)?)$/);
+    if (!c || (column && column !== c[1])) return null;
+    column = c[1];
+    chain.push(c[2] === '>=' ? `min(${c[3]})` : c[2] === '>' ? `gt(${c[3]})` : c[2] === '<=' ? `max(${c[3]})` : `lt(${c[3]})`);
+  }
+  return column ? { column, zod: `z.number().${chain.join('.')}` } : null;
+}
+
+export interface RenderOptions {
+  /** Only pull tables in this Postgres schema (others are framework-managed). Default: `public`. */
+  schema?: string;
+}
+
+/** `format_type` → the `field.*()` factory that produces it (the non-parameterized types). */
+const FIELD_FACTORY: Record<string, string> = {
+  uuid: 'uuid',
+  text: 'text',
+  integer: 'integer',
+  bigint: 'bigint',
+  boolean: 'boolean',
+  jsonb: 'jsonb',
+  date: 'date',
+  'timestamp with time zone': 'timestamptz',
+  'timestamp without time zone': 'timestamp',
+  timestamp: 'timestamp',
+};
+
+/**
+ * The full `field.*()` call for a `format_type` string, or null when no field maps it.
+ * Handles the parameterized types `format_type` spells out — `numeric(p,s)` and
+ * `character varying(n)` — so a pulled column round-trips back to the same DDL. A
+ * scale-0 numeric renders as the cleaner `field.numeric(p)` (identical to `(p, 0)`).
+ */
+export function fieldFactoryCall(type: string): string | null {
+  const direct = FIELD_FACTORY[type];
+  if (direct) return `field.${direct}()`;
+
+  const num = type.match(/^numeric(?:\((\d+),(\d+)\))?$/);
+  if (num) {
+    if (num[1] == null) return 'field.numeric()';
+    return num[2] === '0' ? `field.numeric(${num[1]})` : `field.numeric(${num[1]}, ${num[2]})`;
+  }
+
+  const vc = type.match(/^character varying(?:\((\d+)\))?$/);
+  if (vc) return vc[1] != null ? `field.varchar(${vc[1]})` : 'field.varchar()';
+
+  return null;
+}
+
+/** `public.image_variants` / `image_variants` → `image_variants` (the bare table name). */
+function bareName(table: string): string {
+  return table.replace(/^[^.]+\./, '');
+}
+
+/** A table name → its model variable: PascalCase, naively singularized. `image_variants` → `ImageVariant`. */
+export function modelVarName(table: string): string {
+  const bare = bareName(table);
+  const singular = bare.endsWith('s') ? bare.slice(0, -1) : bare;
+  return singular.split('_').filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+
+/** `author_id` → `authorId` (a SQL column to its camelCase field key — the inverse of the compiler's snake_case). */
+function toCamelCase(name: string): string {
+  return name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+
+/** The `.default*()` modifier for a column default, or null when the expression isn't one we map. */
+function renderDefault(expr: string): string | null {
+  const n = normalizeDefault(expr);
+  if (n == null) return null;
+  if (n === 'now()') return '.defaultNow()';
+  if (n === 'gen_random_uuid()') return '.defaultRandom()';
+  const str = n.match(/^'([\s\S]*)'$/);
+  if (str) return `.default(${JSON.stringify(str[1].replace(/''/g, "'"))})`;
+  if (n === 'true' || n === 'false') return `.default(${n})`;
+  if (/^-?\d+(\.\d+)?$/.test(n)) return `.default(${n})`;
+  return null;
+}
+
+/** A single-quoted TS string literal (the model idiom), escaping embedded quotes. */
+function tsLiteral(value: string): string {
+  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+/** One field line: `    authorId: field.uuid().notNull().references(() => Profile),` (+ any surfacing comment). */
+function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>, enums: Map<string, string[]>, validates: Map<string, string>): string {
+  // An enum column's type is the enum's name; render the explicit-name field.enum with its
+  // values (the always-explicit form round-trips the name and the value order).
+  const enumValues = enums.get(col.type);
+  const call = enumValues
+    ? `field.enum(${tsLiteral(col.type)}, [${enumValues.map(tsLiteral).join(', ')}])`
+    : fieldFactoryCall(col.type);
+  let expr = call ?? 'field.text()';
+  let comment = call ? '' : ` // FIXME: column type '${col.type}' has no field mapping`;
+
+  const isPk = table.primaryKey.includes(col.name);
+  if (isPk) expr += '.primaryKey()';
+  else if (col.notNull) expr += '.notNull()';
+
+  if (table.uniques.some((u) => u.columns.length === 1 && u.columns[0] === col.name)) expr += '.unique()';
+
+  const fk = table.foreignKeys.find((f) => f.columns.length === 1 && f.columns[0] === col.name);
+  if (fk) {
+    if (known.has(bareName(fk.refTable))) {
+      const actions = [
+        fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
+        fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
+      ].filter(Boolean);
+      const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
+      expr += `.references(() => ${modelVarName(fk.refTable)}${opts})`;
+    } else comment += ` // FK → ${fk.refTable} (not in the pulled set)`;
+  }
+
+  if (col.default != null) {
+    const d = renderDefault(col.default);
+    if (d) expr += d;
+    else comment += ` // TODO: unmapped default ${col.default}`;
+  }
+
+  const validate = validates.get(col.name);
+  if (validate) expr += `.validate(${validate})`;
+
+  return `    ${toCamelCase(col.name)}: ${expr},${comment}`;
+}
+
+/**
+ * The `constraints: [...]` block for a table's composite uniques, checks, indexes, and
+ * multi-column foreign keys — the table-level surface a column-scoped `field()` can't carry.
+ * Single-column uniques and FKs are rendered on the field (`.unique()` / `.references()`), so
+ * only composite ones land here. A composite FK whose target isn't in the pulled set is
+ * surfaced as a comment, not faked. Returns '' when there are none.
+ */
+function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], known: Set<string>): string {
+  const items: string[] = [];
+  for (const u of table.uniques) {
+    if (u.columns.length > 1) items.push(`unique(${u.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`);
+  }
+  for (const ck of checks) {
+    items.push(`check(sql\`${normalizeCheck(ck.expr)}\`)`);
+  }
+  for (const ix of table.indexes) {
+    let s = `index(${ix.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`;
+    if (ix.unique) s += '.unique()';
+    if (ix.where) s += `.where(sql\`${normalizeCheck(ix.where)}\`)`;
+    items.push(s);
+  }
+  for (const fk of table.foreignKeys) {
+    if (fk.columns.length <= 1) continue; // single-column FKs are rendered on the field
+    const cols = `[${fk.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')}]`;
+    const refCols = `[${fk.refColumns.map((c) => tsLiteral(toCamelCase(c))).join(', ')}]`;
+    if (!known.has(bareName(fk.refTable))) {
+      items.push(`// FIXME: composite FK ${cols} → ${fk.refTable} ${refCols} (target not in the pulled set)`);
+      continue;
+    }
+    const actions = [
+      fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
+      fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
+    ].filter(Boolean);
+    const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
+    items.push(`foreignKey(${cols}, () => ${modelVarName(fk.refTable)}, ${refCols}${opts})`);
+  }
+  if (!items.length) return '';
+  return `\n  constraints: [\n${items.map((i) => `    ${i},`).join('\n')}\n  ],`;
+}
+
+/** One `export const X = defineModel(...)` block for a table. */
+export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map()): string {
+  // A CHECK that reverses to a single field's .validate() is rendered on the field (ergonomic);
+  // the rest stay table-level check(). Both round-trip — this only chooses the nicer form.
+  const validates = new Map<string, string>();
+  const columnNames = new Set(table.columns.map((c) => c.name));
+  const tableChecks: CheckConstraint[] = [];
+  for (const ck of table.checks) {
+    const v = checkToValidate(ck.expr);
+    if (v && columnNames.has(v.column) && !validates.has(v.column)) validates.set(v.column, v.zod);
+    else tableChecks.push(ck);
+  }
+
+  const fields = table.columns.map((c) => renderField(table, c, known, enums, validates)).join('\n');
+  const constraints = renderConstraintsBlock(table, tableChecks, known);
+
+  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n  fields: {\n${fields}\n  },${constraints}\n});`;
+}
+
+/**
+ * Render a whole snapshot as a single Models module: the import, one block per table (scoped
+ * to `opts.schema`), and the `models` array the rest of the framework consumes. The tables
+ * come pre-sorted from assembleSchema, so the output is stable.
+ */
+export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions = {}): string {
+  const schema = opts.schema ?? 'public';
+  const tables = snapshot.tables.filter((t) => t.table.startsWith(`${schema}.`));
+  const known = new Set(tables.map((t) => bareName(t.table)));
+  const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
+
+  const blocks = tables.map((t) => renderModelBlock(t, known, enums));
+  const body = blocks.join('\n\n');
+
+  // Import only what the rendered models actually use, so the file reads clean.
+  const symbols = ['defineModel', 'field'];
+  if (/\bunique\(/.test(body)) symbols.push('unique');
+  if (/\bcheck\(/.test(body)) symbols.push('check');
+  if (/\bindex\(/.test(body)) symbols.push('index');
+  if (/\bforeignKey\(/.test(body)) symbols.push('foreignKey');
+  if (/\bsql`/.test(body)) symbols.push('sql');
+  const imports = [`import { ${symbols.join(', ')} } from '@everystack/model';`];
+  if (/\.validate\(/.test(body)) imports.push(`import { z } from 'zod';`);
+  const header = imports.join('\n');
+  const footer = `export const models = [${tables.map((t) => modelVarName(t.table)).join(', ')}];`;
+
+  return [header, ...blocks, footer].join('\n\n') + '\n';
+}

package/src/cli/pg-ident.ts

@@ -0,0 +1,59 @@
+/**
+ * Postgres identifier quoting for emitted DDL.
+ *
+ * A bare identifier that collides with a reserved keyword (`user`, `order`, `group`,
+ * `table`, …) is a syntax error: `GRANT … ON public.user` fails to parse. The data layer
+ * already quotes every table name unconditionally (`compileCreateTable` emits
+ * `CREATE TABLE "user"`); the authz layer emitted bare names and so broke on a reserved
+ * table name. This is the shared quoter that closes that gap.
+ *
+ * The rule mirrors what drizzle/pg_dump do: a simple lowercase identifier that is NOT a
+ * reserved word is left bare (so `public.posts` stays `public.posts` — the proven output is
+ * unchanged), and anything else — a reserved word, a mixed-case or special-character name,
+ * or an already-quoted token — is double-quoted. Quoting preserves the exact stored name,
+ * which is correct because that is the name the table was created under.
+ */
+
+/**
+ * Postgres *reserved* keywords — the set that cannot appear as a table/column identifier
+ * without quoting (the "reserved" column of the keyword table; the "reserved (can be
+ * function or type)" words are usable as table names and are deliberately omitted, so we
+ * never over-quote). Lowercased for a case-insensitive lookup.
+ */
+const RESERVED = new Set([
+  'all', 'analyse', 'analyze', 'and', 'any', 'array', 'as', 'asc', 'asymmetric',
+  'both', 'case', 'cast', 'check', 'collate', 'column', 'constraint', 'create',
+  'current_catalog', 'current_date', 'current_role', 'current_time', 'current_timestamp',
+  'current_user', 'default', 'deferrable', 'desc', 'distinct', 'do', 'else', 'end',
+  'except', 'false', 'fetch', 'for', 'foreign', 'from', 'grant', 'group', 'having',
+  'in', 'initially', 'intersect', 'into', 'lateral', 'leading', 'limit', 'localtime',
+  'localtimestamp', 'not', 'null', 'offset', 'on', 'only', 'or', 'order', 'placing',
+  'primary', 'references', 'returning', 'select', 'session_user', 'some', 'symmetric',
+  'table', 'then', 'to', 'trailing', 'true', 'union', 'unique', 'user', 'using',
+  'variadic', 'when', 'where', 'window', 'with',
+]);
+
+/** A bare-safe identifier: a simple lowercase name that is not a reserved keyword. */
+function isBareSafe(id: string): boolean {
+  return /^[a-z_][a-z0-9_]*$/.test(id) && !RESERVED.has(id);
+}
+
+/**
+ * Quote a single identifier when it needs it. A bare-safe name is returned unchanged
+ * (preserving the existing output for normal tables); an already-quoted token is passed
+ * through; anything else is double-quoted with embedded quotes doubled.
+ */
+export function quoteIdent(id: string): string {
+  if (/^".*"$/.test(id)) return id;
+  if (isBareSafe(id)) return id;
+  return `"${id.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Quote each part of a (possibly) schema-qualified name independently:
+ * `public.user` → `public."user"`, `public.posts` → `public.posts`. The contract's table
+ * names are `<schema>.<table>` with simple parts, so a plain dot split is exact.
+ */
+export function quoteQualified(qualified: string): string {
+  return qualified.split('.').map(quoteIdent).join('.');
+}