@everystack/cli 0.3.18 → 0.3.19

package/README.md

@@ -219,6 +219,7 @@ everystack db:pull                      # introspect a live DB → field() Model
 everystack db:reconcile                 # deploy the derived layer (functions/views/matviews) from db/sql — no migrations
 everystack db:fingerprint               # content-address the live base schema vs the Models — MATCH/MISMATCH
 everystack db:sync                      # make the database match your checkout — state + compute, one verb (dev DBs)
+everystack db:diff                      # the state edge between two declared states — no DB, CI-pure; reverse = computed rollback
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.18",
+  "version": "0.3.19",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

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

@@ -0,0 +1,87 @@
+/**
+ * `everystack db:diff` — the state edge between two declared states, no
+ * database anywhere (brick 3's command surface).
+ *
+ *   db:diff --from-models <barrel> [--to-models db/models/index.ts]
+ *           [--allow-drops] [--check] [--json]
+ *
+ * Compiles both model sets and prints the SQL edge from one to the other —
+ * the same statement grammar db:generate produces (executable DDL, held
+ * drops, notices), computed with no connection, no network, no side
+ * effects. Deterministic: same two states, same edge, forever.
+ *
+ * The uses this unlocks:
+ * - CI plan preview: materialize the base branch's models, diff to HEAD's,
+ *   attach the edge to the PR. `--check` exits 1 when the edge is non-empty.
+ * - Computed rollback: swap the flags. The reverse edge is derived from the
+ *   same two states — nobody authors a down migration.
+ * - Review: the exact SQL a `db:sync` / `db:generate --apply` will run when
+ *   the target database sits at the from-state.
+ *
+ * Between two declared states a removed table is intent (unlike the live
+ * diff, where an undeclared table is unmodeled and untouchable) — removals
+ * surface as drops, held back unless `--allow-drops`, like everywhere else.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import { diffDeclaredStates } from '../declared-diff.js';
+import { classifyGeneratedStatements } from '../state-apply.js';
+import { fingerprintModels } from '../schema-fingerprint.js';
+import { resolveModelsPath } from '../models-path.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+export async function dbDiffCommand(flags: Record<string, string>): Promise<void> {
+  const fromPath = flags['from-models'];
+  if (!fromPath) {
+    fail('db:diff needs --from-models <barrel> — the declared state to diff FROM (--to-models defaults to the checkout\'s db/models).');
+    process.exit(1);
+  }
+  const toPath = resolveModelsPath(flags['to-models']);
+
+  let from: ModelDescriptor[];
+  let to: ModelDescriptor[];
+  try {
+    step(`Loading FROM models from ${fromPath}...`);
+    from = await loadModels(fromPath);
+    step(`Loading TO models from ${toPath}...`);
+    to = await loadModels(toPath);
+    info(`${from.length} → ${to.length} model(s).`);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const statements = diffDeclaredStates(from, to, { allowDrops: flags['allow-drops'] === 'true' });
+  const classified = classifyGeneratedStatements(statements);
+  const fromFingerprint = fingerprintModels(from).hash;
+  const toFingerprint = fingerprintModels(to).hash;
+
+  if (flags.json === 'true') {
+    console.log(JSON.stringify({
+      fromFingerprint,
+      toFingerprint,
+      statements,
+      executable: classified.executable.length,
+      heldDrops: classified.heldDrops.length,
+      notices: classified.notices.length,
+      empty: statements.length === 0,
+    }, null, 2));
+  } else {
+    console.log('');
+    if (statements.length === 0) {
+      success('The two states are identical — the edge is empty.');
+    } else {
+      info(`edge — ${statements.length} statement(s):`);
+      console.log('');
+      for (const s of statements) console.log(s.endsWith(';') ? s : `${s};`);
+      console.log('');
+      if (classified.heldDrops.length) warn(`${classified.heldDrops.length} destructive change(s) held back as comments (re-run with --allow-drops to emit them).`);
+      if (classified.notices.length) info(`${classified.notices.length} notice(s) — renames / manual follow-ups.`);
+    }
+    info(`fingerprint: ${fromFingerprint.slice(0, 12)} → ${toFingerprint.slice(0, 12)}`);
+  }
+
+  if (flags.check === 'true' && statements.length > 0) process.exit(1);
+  process.exit(0);
+}

package/src/cli/declared-diff.ts

@@ -0,0 +1,89 @@
+/**
+ * declared-diff — the state edge between two DECLARED states, no live
+ * database anywhere (brick 3 of the migration-authority design).
+ *
+ * The live diff (db:generate) asks "what does the database need to become
+ * the models?" — one side is introspected. This module answers the same
+ * question between two model sets: compile the FROM models to the exact
+ * snapshot + contract shapes introspection produces, and run the one diff
+ * engine over them (`scope: 'full'` — between declared states the from-side
+ * is fully known, so a removed table is intent and becomes a drop, held by
+ * the same `allowDrops` gate as everywhere else).
+ *
+ * What this buys, per the design:
+ * - CI-pure plan previews: the edge between any two git states is
+ *   `diffDeclaredStates(modelsAt(A), modelsAt(B))` — no database, no
+ *   network, deterministic.
+ * - Computed rollback: the reverse edge is the same call with the arguments
+ *   swapped — `diff(B, A)` — derived, never authored. Down migrations stop
+ *   being a thing anyone writes.
+ * - The seed of plan minting (brick 4/7): a plan is this edge plus the two
+ *   fingerprints naming its endpoints.
+ *
+ * The identity that makes it trustworthy, proven on real PostgreSQL in the
+ * integration suite: build a database at A, apply `diff(A→B)`, and
+ * `fingerprintLive` equals `fingerprintModels(B)` exactly — the pure edge
+ * and the live edge are the same edge.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect.js';
+import type { AuthzContract } from './authz-contract.js';
+import { compileTableSchema, compileEnums } from './schema-compile.js';
+import { compileTableContract } from './authz-compile.js';
+import { generateMigrationSql } from './migration-generate.js';
+
+export interface DeclaredState {
+  snapshot: SchemaSnapshot;
+  contract: AuthzContract;
+}
+
+export interface DeclaredDiffOptions {
+  /** The Postgres schema the Models default to. Default: `public`. */
+  schema?: string;
+  /** Emit real drops for removals. Default false — held back as comments. */
+  allowDrops?: boolean;
+}
+
+/**
+ * Compile a model set to the shapes introspection produces — the same
+ * compilation `fingerprintModels` hashes, exposed as a state the diff
+ * engine can treat as "current".
+ */
+export function compileDeclaredState(
+  models: ModelDescriptor[],
+  opts: { schema?: string } = {},
+): DeclaredState {
+  const schema = opts.schema ?? 'public';
+  return {
+    snapshot: {
+      tables: models.map((m) => compileTableSchema(m, { schema })),
+      enums: compileEnums(models),
+    },
+    contract: {
+      tables: models.map((m) => compileTableContract(m, { schema })),
+      functions: [],
+    },
+  };
+}
+
+/**
+ * The pure state edge `from → to`: the statement stream `db:generate` would
+ * produce against a live database at `from`, computed with no database.
+ * Same statement grammar throughout — executable DDL, held drops as
+ * comments, notices — so `classifyGeneratedStatements` and the apply path
+ * treat it identically. Swap the arguments for the reverse edge.
+ */
+export function diffDeclaredStates(
+  from: ModelDescriptor[],
+  to: ModelDescriptor[],
+  opts: DeclaredDiffOptions = {},
+): string[] {
+  const a = compileDeclaredState(from, { schema: opts.schema });
+  return generateMigrationSql(to, a.snapshot, {
+    schema: opts.schema,
+    allowDrops: opts.allowDrops,
+    liveAuthz: a.contract,
+    scope: 'full',
+  });
+}

package/src/cli/index.ts

@@ -14,6 +14,7 @@ import { dbPullCommand } from './commands/db-pull.js';
 import { dbReconcileCommand } from './commands/db-reconcile.js';
 import { dbFingerprintCommand } from './commands/db-fingerprint.js';
 import { dbSyncCommand } from './commands/db-sync.js';
+import { dbDiffCommand } from './commands/db-diff.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';
@@ -184,6 +185,9 @@ async function main() {
     case 'db:sync':
       await dbSyncCommand(flags);
       break;
+    case 'db:diff':
+      await dbDiffCommand(flags);
+      break;
     case 'db:authz:pull':
       await dbAuthzPullCommand(flags);
       break;
@@ -309,6 +313,7 @@ Usage:
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--sql-dir db/sql] [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--overwrite-drift] [--json]  Reconcile the derived layer (functions/views/matviews) against db/sql sources: plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (direct connection only) and records provenance + schema_log. Hand-edits are drift (never overwritten silently); first contact with existing objects wants --baseline, once.
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against db/sql, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
+  everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   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)

package/src/cli/migration-generate.ts

@@ -33,6 +33,15 @@ export interface GenerateOptions {
    * never silently loses data. Destruction needs intent, the same rule renames are built on.
    */
   allowDrops?: boolean;
+  /**
+   * How much of `current` the diff may see. `'declared'` (default) scopes it to the
+   * tables/enums the Models declare — right against a LIVE database, where an
+   * undeclared table is unmodeled (auth, jobs, another team's) and must be invisible,
+   * never dropped. `'full'` diffs everything — right between two DECLARED states
+   * (declared-diff), where the from-side is fully known and absence is intent: a
+   * removed table/enum becomes a drop (still held by the `allowDrops` gate).
+   */
+  scope?: 'declared' | 'full';
   /**
    * The live authorization contract (`introspectContract`). When provided, the migration
    * carries the authz layer too — the Models' `abilities` compiled to RLS/policies/grants,
@@ -94,11 +103,15 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   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)),
-  };
+  // (auth, jobs, observability ship their own) is invisible to the diff, so it is never
+  // dropped. `scope: 'full'` (declared-diff, model→model) skips the filter: there the
+  // from-side is fully declared too, so absence is intent and removals must surface.
+  const scopedCurrent: SchemaSnapshot = opts.scope === 'full'
+    ? { tables: current.tables, enums: current.enums ?? [] }
+    : {
+        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);