@everystack/cli 0.4.100 → 0.4.102

package/src/cli/plain-output.ts

@@ -14,6 +14,13 @@
  *   -               something is no longer true — dropped, revoked.
  *   ⚠ DESTRUCTIVE   real data can be lost. Orthogonal to the other two: its own line, never
  *                   combined with + or -.
+ *   ⚠ ACCESS        db:plan only: one summary line when the plan removes a policy, revokes a
+ *                   grant, turns row security off, or removes a function, view or trigger. Not destructive (no --confirm), but such a
+ *                   plan is never called "Safe to apply".
+ *   ⚠ CONSTRAINT    db:plan only: one line per primary key the plan replaces, naming the old key.
+ *                   Read from the replacement note the emitter writes from the change itself
+ *                   (schema-diff's parsePrimaryKeyReplacement), never from the DDL. Not
+ *                   destructive, but never called "Safe to apply" either.
  *
  * And a banned list (BANNED_DEFAULT_WORDS): words that mean something to us and nothing to the
  * reader. Nothing is deleted — the full internal report is exactly as it was, behind --verbose.
@@ -28,6 +35,9 @@
  */
 
 import { statementBody } from './sql-statement';
+import { parsePrimaryKeyReplacement } from './schema-diff';
+import type { ReconcileAction, ReconcilePlan } from './derived-plan';
+import type { DerivedKind } from './derived-source';
 
 // ---------------------------------------------------------------------------
 // The banned vocabulary.
@@ -168,7 +178,12 @@ export function describeChange(statement: string, opts: DescribeOptions = {}): P
       return { symbol: '-', text: `remove column ${table}.${unquote(a[1])}` };
     }
     if ((a = /^ADD\s+CONSTRAINT\s+("[^"]+"|[\w$]+)/i.exec(rest))) {
-      return { symbol: '+', text: `add constraint ${unquote(a[1])} on ${table}` };
+      // A foreign key names what it points at, always as schema.table: the reviewer must see
+      // when a key reaches into a table no model declares (another system's auth.users).
+      const ref = /\sFOREIGN\s+KEY\s*\([^)]*\)\s*REFERENCES\s+((?:"[^"]*"|[^\s("]+)(?:\.(?:"[^"]*"|[^\s("]+))?)/i.exec(rest);
+      const target = ref ? unquote(ref[1]) : null;
+      const referencing = target ? ` referencing ${target.includes('.') ? target : `public.${target}`}` : '';
+      return { symbol: '+', text: `add constraint ${unquote(a[1])} on ${table}${referencing}` };
     }
     if ((a = /^DROP\s+CONSTRAINT\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)/i.exec(rest))) {
       return { symbol: '-', text: `remove constraint ${unquote(a[1])} on ${table}` };
@@ -420,25 +435,198 @@ export interface PlanReportInput {
   planPath: string | null;
   /** --verbose: the promise behind "(--verbose for the full list)" — show every line, uncapped. */
   verbose?: boolean;
+  /**
+   * The function/view/trigger reconcile db:apply runs after the plan (planReconcile's output).
+   * Absent, or with nothing that changes an object, the report is byte-identical to one without it.
+   */
+  derived?: Pick<ReconcilePlan, 'actions' | 'regrants'>;
 }
 
+// ---------------------------------------------------------------------------
+// The functions, views and triggers db:apply reconciles after the plan.
+// ---------------------------------------------------------------------------
+
+/** The reader's word for each kind. A matview is a view to the reader, as it is above. */
+const DERIVED_KIND_WORD: Record<DerivedKind, string> = {
+  function: 'function', view: 'view', 'materialized view': 'view', trigger: 'trigger', sql: 'object',
+};
+
+/** `public.posts.posts_touch` (a trigger's identity) → `posts_touch on posts`; anything else → rel(). */
+function derivedName(a: Pick<ReconcileAction, 'identity' | 'kind'>): string {
+  if (a.kind === 'trigger') {
+    const dot = a.identity.lastIndexOf('.');
+    if (dot > 0) return `${a.identity.slice(dot + 1)} on ${rel(a.identity.slice(0, dot))}`;
+  }
+  return rel(a.identity);
+}
+
+/**
+ * The reconcile plan db:apply will run, as plain change lines — one per OBJECT, never per
+ * statement, so the reader sees what changes rather than how the DDL has to be written.
+ *
+ * It reads `planReconcile`'s output and decides nothing: db:plan builds that plan with the same
+ * declared objects and the same options db:apply's catch-up passes to `executeReconcile`, so the
+ * list is what the apply will do. A rebuild (the drop and the create of one identity) is ONE
+ * `+ update` line, as it is for the table edge. Bookkeeping that changes no object — baseline,
+ * rebaseline, backfill, prune — is left out; db:apply's catch-up never asks for the first two.
+ *
+ * `statements` carries the GRANT/REVOKE SQL behind the grant lines, so the access count reads the
+ * same statements the lines describe. `removed` names the kind of every object that is dropped
+ * and NOT rebuilt: such an object can enforce access (a SECURITY DEFINER function, a soft-delete
+ * trigger, a definer view), and dropping a function takes its EXECUTE grants with it — no REVOKE
+ * statement exists for the count to see.
+ */
+export function describeDerivedChanges(plan: Pick<ReconcilePlan, 'actions' | 'regrants'>): {
+  changes: PlainChange[];
+  statements: string[];
+  removed: string[];
+} {
+  const created = new Set(plan.actions.filter((a) => a.action === 'create').map((a) => a.identity));
+  const rebuilt = new Set(plan.actions.filter((a) => a.action === 'drop' && created.has(a.identity)).map((a) => a.identity));
+  const changes: PlainChange[] = [];
+  const statements: string[] = [];
+  const removed: string[] = [];
+  const grantLines = (sqls: readonly string[]): void => {
+    for (const s of sqls) {
+      statements.push(s);
+      changes.push(describeChange(s));
+    }
+  };
+  for (const a of plan.actions) {
+    const what = `${DERIVED_KIND_WORD[a.kind] ?? 'object'} ${derivedName(a)}`;
+    switch (a.action) {
+      case 'drop':
+        if (!rebuilt.has(a.identity)) {
+          changes.push({ symbol: '-', text: `remove ${what}` });
+          removed.push(DERIVED_KIND_WORD[a.kind] ?? 'object');
+        }
+        break;
+      case 'create':
+        changes.push(rebuilt.has(a.identity)
+          ? { symbol: '+', text: `update ${what}: ${a.reason.startsWith('source changed') ? 'definition updated' : 'rebuilt'}` }
+          : { symbol: '+', text: `add ${what}` });
+        break;
+      case 'replace':
+        changes.push({ symbol: '+', text: `update ${what}: definition updated` });
+        grantLines(a.revokes ?? []);
+        break;
+      case 'refresh':
+        changes.push({ symbol: '+', text: `refresh ${what}` });
+        break;
+      default:
+        break;
+    }
+  }
+  for (const r of plan.regrants) grantLines(r.statements);
+  return { changes, statements, removed };
+}
+
+// ---------------------------------------------------------------------------
+// Access: what a plan takes away, which is not the same as what it destroys.
+// ---------------------------------------------------------------------------
+
+export interface AccessChanges {
+  /** DROP POLICY statements. */
+  policies: number;
+  /** REVOKE statements. */
+  revokes: number;
+  /** Distinct tables with DISABLE / NO FORCE ROW LEVEL SECURITY (one table can get both). */
+  rowSecurityOff: number;
+}
+
+/**
+ * Count the statements that change who can read or write: a removed policy, a revoked grant,
+ * row security turned off. Read from the statement BODY (sql-statement's reading), so a
+ * `-- WARNING:` prologue that mentions a REVOKE does not count and one hiding a REVOKE does.
+ *
+ * NOT a destructive class. DESTRUCTIVE means data can be lost and gates --confirm, a snapshot
+ * and the stage refusal; none of those fit a policy change. This only decides the wording.
+ */
+export function accessChanges(statements: readonly string[]): AccessChanges {
+  const out: AccessChanges = { policies: 0, revokes: 0, rowSecurityOff: 0 };
+  const rlsOff = new Set<string>();
+  let m: RegExpExecArray | null;
+  for (const statement of statements) {
+    const s = head(statement);
+    if (/^DROP\s+POLICY\b/i.test(s)) out.policies++;
+    else if (/^REVOKE\b/i.test(s)) out.revokes++;
+    else if ((m = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s[\s\S]*\b(?:DISABLE|NO\s+FORCE)\s+ROW\s+LEVEL\s+SECURITY\b/i.exec(s))) rlsOff.add(rel(m[1]));
+  }
+  out.rowSecurityOff = rlsOff.size;
+  return out;
+}
+
+/** The order removed things are named in, after policies. */
+const REMOVED_KIND_ORDER = ['function', 'trigger', 'view', 'object'];
+
+/** The ⚠ ACCESS line, or null when the plan takes no access away. */
+function accessLine(a: AccessChanges, removedKinds: readonly string[] = []): string | null {
+  const removed = [
+    ...(a.policies ? [`${a.policies} ${plural(a.policies, 'policy', 'policies')}`] : []),
+    ...REMOVED_KIND_ORDER.flatMap((kind) => {
+      const n = removedKinds.filter((k) => k === kind).length;
+      return n ? [`${n} ${plural(n, kind, `${kind}s`)}`] : [];
+    }),
+  ];
+  const parts = [
+    ...(removed.length ? [`removes ${removed.join(', ')}`] : []),
+    ...(a.revokes ? [`revokes ${a.revokes} ${plural(a.revokes, 'grant', 'grants')}`] : []),
+    ...(a.rowSecurityOff ? [`turns off row security on ${a.rowSecurityOff} ${plural(a.rowSecurityOff, 'table', 'tables')}`] : []),
+  ];
+  return parts.length === 0 ? null : `${ACCESS_MARK} — ${parts.join(', ')}. Check who can still read and write.`;
+}
+
+const ACCESS_MARK = '⚠ ACCESS';
+
+/** The ⚠ CONSTRAINT lines: one per primary key the plan replaces. */
+function constraintLines(statements: readonly string[]): string[] {
+  return statements.flatMap((statement) => {
+    const r = parsePrimaryKeyReplacement(statement);
+    return r ? [`${CONSTRAINT_MARK} — primary key ${r.name} on ${rel(r.table)} is replaced by (${r.columns.join(', ')}). A foreign key on the old key fails the apply.`] : [];
+  });
+}
+
+const CONSTRAINT_MARK = '⚠ CONSTRAINT';
+
 /** db:plan's default output — the whole thing. */
 export function renderPlanReport(input: PlanReportInput): string[] {
   const { executable, target, stage, planPath, verbose = false } = input;
-  if (executable.length === 0) return ['Up to date. Nothing to plan.'];
+  const derived = input.derived ? describeDerivedChanges(input.derived) : { changes: [], statements: [], removed: [] };
+  if (executable.length === 0 && derived.changes.length === 0) return ['Up to date. Nothing to plan.'];
 
+  const limit = (n: number): number => (verbose ? n : MAX_LISTED_CHANGES);
   const destructive = new Set(input.destructive.map(statementKey));
-  const lines: string[] = [
-    `Plan: ${executable.length} ${plural(executable.length, 'change', 'changes')} (${target})`,
-    '',
-    ...changeLines(executable, destructive, verbose ? executable.length : MAX_LISTED_CHANGES),
-    '',
-  ];
-
+  const lines: string[] = executable.length > 0
+    ? [
+      `Plan: ${executable.length} ${plural(executable.length, 'change', 'changes')} (${target})`,
+      '',
+      ...changeLines(executable, destructive, limit(executable.length)),
+      '',
+    ]
+    : [`Plan: no table, column or grant changes (${target})`, ''];
+
+  // Not in the plan file, by design: db:apply reads these from the checkout at apply time and
+  // they go stale between mint and apply (see db-plan.ts). The header says so, so the file is
+  // never read as the whole change.
+  if (derived.changes.length > 0) {
+    const shown = derived.changes.slice(0, limit(derived.changes.length)).map((c) => `  ${c.symbol} ${c.text}`);
+    const hidden = derived.changes.length - shown.length;
+    if (hidden > 0) shown.push(`  … and ${hidden} more (--verbose for the full list)`);
+    lines.push(`Also on db:apply (from the checkout, not in ${planPath ?? 'the plan'}):`, '', ...shown, '');
+  }
+
+  const keys = constraintLines(executable);
+  lines.push(...keys);
+  const access = accessLine(accessChanges([...executable, ...derived.statements]), derived.removed);
+  if (access) lines.push(access);
   lines.push(
     destructive.size > 0
       ? `Verify the destructive ${plural(destructive.size, 'change', 'changes')}, then run db:backup before applying.`
-      : 'Non-destructive. Safe to apply.',
+      : access
+        ? 'Non-destructive. Verify the access changes before applying.'
+        : keys.length > 0
+          ? 'Non-destructive. Verify the replaced keys before applying.'
+          : 'Non-destructive. Safe to apply.',
   );
 
   // No file, no command to give — `--out -` piped the plan somewhere only the caller knows.

package/src/cli/runbook/model-section.ts

@@ -8,7 +8,7 @@
  */
 
 import { ModelLinkError } from '@everystack/model';
-import type { Ability, FieldSpec, ModelDescriptor, Relation } from '@everystack/model';
+import { relationDeleteActions, type Ability, type FieldSpec, type ModelDescriptor, type ReferentialAction, type Relation } from '@everystack/model';
 
 function typeLabel(spec: FieldSpec): string {
   let base: string;
@@ -42,14 +42,15 @@ function referenceTarget(spec: FieldSpec): string | null {
   }
 }
 
-function fieldLine(name: string, spec: FieldSpec): string {
+function fieldLine(name: string, spec: FieldSpec, derivedOnDelete?: ReferentialAction): string {
+  const onDelete = derivedOnDelete ?? spec.onDelete;
   const parts = [typeLabel(spec)];
   if (spec.isPrimaryKey) parts.push('pk');
   if (spec.isNotNull && !spec.isPrimaryKey) parts.push('not null');
   if (spec.isUnique) parts.push('unique');
   const target = referenceTarget(spec);
   if (target) {
-    parts.push(`→ ${target}${spec.onDelete && spec.onDelete !== 'no action' ? ` (${spec.onDelete})` : ''}`);
+    parts.push(`→ ${target}${onDelete && onDelete !== 'no action' ? ` (${onDelete})` : ''}`);
   }
   if (spec.defaultKind === 'now') parts.push('default: now()');
   else if (spec.defaultKind === 'random') parts.push('default: random');
@@ -79,7 +80,7 @@ function relationLine(name: string, rel: Relation): string {
     if (err instanceof ModelLinkError) throw err;
     /* forward reference that can't resolve here — label stays unknown */
   }
-  const shape = rel.kind === 'belongsTo' ? 'belongs to' : 'has many';
+  const shape = rel.kind === 'belongsTo' ? 'belongs to' : rel.kind === 'hasOne' ? 'has one' : 'has many';
   return `- \`${name}\` — ${shape} ${target} (via \`${rel.column}\`)`;
 }
 
@@ -155,6 +156,8 @@ export function renderDataModelSection(models: ModelDescriptor[], opts: DataMode
     '',
     "Compiled from the app's Models — edit `models/` and regenerate; never edit this section.",
   ];
+  // A parent's hasMany `dependent` sets a child FK's ON DELETE; derived from this set.
+  const dependents = relationDeleteActions(models);
   for (const m of models) {
     const heading = m.schema && m.schema !== 'public' ? `${m.schema}.${m.table}` : m.table;
     lines.push('', `### ${heading}`, '');
@@ -163,7 +166,7 @@ export function renderDataModelSection(models: ModelDescriptor[], opts: DataMode
     if (m.writtenBy !== 'app') annotations.push(`written by ${m.writtenBy}`);
     if (annotations.length) lines.push(`_Operational table — ${annotations.join('; ')}._`, '');
     for (const [name, builder] of Object.entries(m.fields)) {
-      lines.push(fieldLine(name, builder.spec));
+      lines.push(fieldLine(name, builder.spec, dependents.get(m)?.get(name)));
     }
     const relations = Object.entries(m.relations ?? {});
     if (relations.length) {

package/src/cli/schema-compile.ts

@@ -19,10 +19,10 @@
  * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
  */
 
-import type { ModelDescriptor, FieldSpec, SequenceDescriptor } from '@everystack/model';
+import type { ModelDescriptor, FieldSpec, SequenceDescriptor, DependentActions } from '@everystack/model';
 import { positionalCheckName } from '@everystack/model';
 import type { TableSchema, EnumType, SequenceSchema, UniqueConstraint, CheckConstraint, IndexSchema, ForeignKey } from './schema-introspect';
-import { nextvalSequence, identityClause, type RenameMap } from './schema-diff';
+import { nextvalSequence, identityClause, primaryKeyConstraintName, type RenameMap } from './schema-diff';
 import { normalizeDeparsedExpr } from './deparse-normal';
 
 /** `authorId` -> `author_id`. SQL identifiers are snake_case. */
@@ -154,7 +154,7 @@ const PG_TYPE: Record<string, string> = {
   date: 'date',
 };
 
-function pgType(spec: FieldSpec): string {
+export function pgType(spec: FieldSpec): string {
   // An array is the base type with `[]` appended — `text` → `text[]`, exactly as
   // `format_type` spells it.
   return spec.isArray ? `${scalarPgType(spec)}[]` : scalarPgType(spec);
@@ -214,16 +214,27 @@ function refActions(spec: { onDelete?: string; onUpdate?: string }): { onDelete?
  * key's permanent state is installed-and-unproven, so the differ must never emit a `VALIDATE`
  * for it and the from-scratch build must land it `NOT VALID` — otherwise the declared state and
  * the state a build of that declaration produces would be two different states.
+ *
+ * `dependents` is the model SET's derived ON DELETE (`relationDeleteActions(models)`): a parent's
+ * hasMany `dependent` sets the action of this model's FK on that field. A caller holding the set
+ * passes it; it is never read from or written into a field spec, so the result depends only on
+ * the set. Without it a field compiles exactly as it declares.
  */
-export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
+export function modelForeignKeys(model: ModelDescriptor, dependents?: DependentActions): ForeignKey[] {
   const out: ForeignKey[] = [];
+  const derived = dependents?.get(model);
 
   for (const [name, field] of Object.entries(model.fields)) {
+    // An external target (`{ schema, table, column }`, a table no model declares) yields the SAME
+    // fields a model target does, and nothing below this point knows which it was: the diff plans
+    // it and the fingerprint hashes it with no special case. Its column is a PostgreSQL name,
+    // verbatim; a model target's is its primary-key field, snake_cased.
+    const external = field.spec.referencesExternal;
     const ref = field.spec.references;
-    if (!ref) continue;
-    const target = ref() as ModelDescriptor;
+    if (!ref && !external) continue;
+    const target = external ? { schema: external.schema, table: external.table } : ref!() as ModelDescriptor;
     const col = toSnakeCase(name);
-    const targetPk = toSnakeCase(target.primaryKey[0] ?? 'id');
+    const targetPk = external ? external.column : toSnakeCase((target as ModelDescriptor).primaryKey[0] ?? 'id');
     out.push({
       // A DECLARED name wins; the generated one is the fallback. An adopted database keeps the
       // FK names its previous tooling chose (`fk_rails_9a1b2c3d4e`) instead of being renamed
@@ -233,16 +244,17 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
       columns: [col],
       refTable: refTableName(target),
       refColumns: [targetPk],
-      ...refActions(field.spec),
+      ...refActions({ onDelete: derived?.get(name) ?? field.spec.onDelete, onUpdate: field.spec.onUpdate }),
       ...(field.spec.referencesValidate === false ? { notValid: true } : {}),
     });
   }
 
   for (const con of model.constraints) {
     if (con.kind !== 'foreignKey') continue;
-    const target = con.references() as ModelDescriptor;
+    // External (`{ schema, table }`): the reference columns are PostgreSQL names, verbatim.
+    const target = con.external ?? con.references!() as ModelDescriptor;
     const cols = con.columns.map(toSnakeCase);
-    const refCols = con.refColumns.map(toSnakeCase);
+    const refCols = con.external ? [...con.refColumns] : con.refColumns.map(toSnakeCase);
     out.push({
       name: con.constraintName ?? generatedForeignKeyName(model.table, cols, target.table, refCols),
       ...(con.constraintName !== undefined ? { nameDeclared: true } : {}),
@@ -276,7 +288,7 @@ export function generatedForeignKeyName(table: string, columns: string[], refTab
  * target schema is off the search_path — so the desired side must match, or an unchanged auth FK
  * would read as drift. public stays bare because it is on the search_path (the proven output).
  */
-function refTableName(target: ModelDescriptor): string {
+function refTableName(target: { schema?: string; table: string }): string {
   return target.schema && target.schema !== 'public' ? `${target.schema}.${target.table}` : target.table;
 }
 
@@ -479,7 +491,8 @@ export function qualifiedTable(model: ModelDescriptor): string {
 /**
  * `CREATE TABLE` for a model's fields. Single-column primary keys are inline;
  * composite keys and uniques become table constraints, named the way drizzle
- * names them (`<table>_<cols>_pk`, `<table>_<col>_unique`).
+ * names them (`<table>_<cols>_pk`, `<table>_<col>_unique`). The key's name, either
+ * way, is `primaryKeyConstraintName`'s — the differ names a replaced key with it too.
  */
 export function compileCreateTable(model: ModelDescriptor, opts: CompileTableOptions = {}): string {
   const indent = opts.indent ?? '\t';
@@ -495,7 +508,7 @@ export function compileCreateTable(model: ModelDescriptor, opts: CompileTableOpt
   if (pkFields.length > 1) {
     const cols = pkFields.map(toSnakeCase);
     const quoted = cols.map((c) => `"${c}"`).join(',');
-    lines.push(`${indent}CONSTRAINT "${model.table}_${cols.join('_')}_pk" PRIMARY KEY(${quoted})`);
+    lines.push(`${indent}CONSTRAINT "${primaryKeyConstraintName(model.table, cols)}" PRIMARY KEY(${quoted})`);
   }
 
   for (const [name, field] of entries) {
@@ -534,7 +547,7 @@ export function compileCreateTable(model: ModelDescriptor, opts: CompileTableOpt
  * structured form for the brownfield diff. They share the field→type/default/check
  * helpers, so they never disagree.)
  */
-export function compileTableSchema(model: ModelDescriptor, opts: { schema?: string } = {}): TableSchema {
+export function compileTableSchema(model: ModelDescriptor, opts: { schema?: string; dependents?: DependentActions } = {}): TableSchema {
   const schema = model.schema ?? opts.schema ?? 'public';
   const entries = Object.entries(model.fields);
 
@@ -586,9 +599,14 @@ export function compileTableSchema(model: ModelDescriptor, opts: { schema?: stri
     table: `${schema}.${model.table}`,
     columns,
     primaryKey: model.primaryKey.map(toSnakeCase),
+    // What a from-scratch build names the key — the same field introspection fills, so the two
+    // producers still meet at one IR. Never hashed (the fingerprint reads the columns only).
+    ...(model.primaryKey.length > 0
+      ? { primaryKeyName: primaryKeyConstraintName(model.table, model.primaryKey.map(toSnakeCase)) }
+      : {}),
     uniques,
     checks,
-    foreignKeys: modelForeignKeys(model),
+    foreignKeys: modelForeignKeys(model, opts.dependents),
     indexes: tableConstraints.indexes,
   };
 }
@@ -648,8 +666,8 @@ export { sequenceCreateSql } from './schema-diff';
  * unproven-against-old-rows, so a migration artifact that installed it validated would build a
  * database that does not match the models it was generated from.
  */
-export function foreignKeySql(model: ModelDescriptor): string[] {
-  return modelForeignKeys(model).map((fk) => {
+export function foreignKeySql(model: ModelDescriptor, dependents?: DependentActions): string[] {
+  return modelForeignKeys(model, dependents).map((fk) => {
     const cols = fk.columns.map((c) => `"${c}"`).join(', ');
     const refCols = fk.refColumns.map((c) => `"${c}"`).join(', ');
     // Both sides are schema-qualified for a non-public table — `ALTER TABLE "auth"."identities"`