@everystack/cli 0.2.37 → 0.3.0

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

package/src/cli/rds-snapshot.ts

@@ -0,0 +1,47 @@
+/**
+ * db:snapshot — the pure core for RDS *physical* snapshots (the thin `aws rds` wrapper).
+ *
+ * RDS snapshot identifiers are far stricter than our backup ids: 1–255 chars, must start with a
+ * letter, letters/digits/hyphens only, no two consecutive hyphens, no trailing hyphen, stored
+ * lowercase. (Underscores, dots, colons — all rejected by RDS.) So our `YYYYMMDDTHHMMSSZ` stamp
+ * can't be used verbatim; this module builds a guaranteed-valid identifier and a validator that
+ * pins the contract. No IO — the clock is passed in. See docs/plans/db-backup-restore.md.
+ */
+
+/**
+ * RDS DBSnapshotIdentifier validity (per the AWS API reference):
+ *   - 1 to 255 letters, numbers, or hyphens
+ *   - first character must be a letter
+ *   - can't end with a hyphen or contain two consecutive hyphens
+ */
+const RDS_SNAPSHOT_ID = /^[A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)*$/;
+
+/** Whether `id` satisfies RDS's DBSnapshotIdentifier constraints. */
+export function isValidRdsSnapshotId(id: string): boolean {
+  return id.length >= 1 && id.length <= 255 && RDS_SNAPSHOT_ID.test(id);
+}
+
+/**
+ * Sanitize a stage name into the leading segment of an RDS identifier: lowercase, non-alphanumeric
+ * runs collapse to a single hyphen, and it is forced to start with a letter (a `db` prefix is
+ * prepended when the stage starts with a digit or is empty). Never emits a trailing hyphen.
+ */
+function sanitizeStage(stage: string): string {
+  let s = stage.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  if (s === '' || !/^[a-z]/.test(s)) s = `db-${s}`.replace(/-+$/g, '');
+  return s;
+}
+
+/**
+ * Build a valid, deterministic RDS snapshot identifier from a stage and a `YYYYMMDDTHHMMSSZ` stamp.
+ * The stamp is lowercased (its `T`/`Z` become valid letters); the result is
+ * `<sanitized-stage>-<stamp>`, e.g. `dev-20260628t120000z`. Throws if — against expectation — the
+ * composed id is still invalid, so a malformed id can never reach the AWS API.
+ */
+export function rdsSnapshotIdentifier(stage: string, stamp: string): string {
+  const id = `${sanitizeStage(stage)}-${stamp.toLowerCase()}`;
+  if (!isValidRdsSnapshotId(id)) {
+    throw new Error(`Could not build a valid RDS snapshot identifier from stage="${stage}", stamp="${stamp}" (got "${id}")`);
+  }
+  return id;
+}