@everystack/cli 0.3.21 → 0.3.23

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

@@ -0,0 +1,306 @@
+/**
+ * `everystack db:check` — the CI regenerate-and-match gate (brick 7's PR
+ * invariant: the merged declared state must compose, and generated
+ * artifacts must match regeneration).
+ *
+ *   db:check [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>]
+ *            [--database-url <url>] [--json]
+ *
+ * Two rings, both from the checkout alone (no target database is ever
+ * touched — the gate runs on every PR):
+ *
+ *   STATIC — the models load and compose (a semantic merge conflict that
+ *   git can't see, like two branches declaring the same table, fails
+ *   here); the generated drizzle schema matches a byte-for-byte
+ *   regeneration (hand-edited artifacts and forgotten `db:generate` runs
+ *   fail loudly); the derived sources in db/sql parse.
+ *
+ *   EPHEMERAL COMPOSE — with a scratch PostgreSQL (`--database-url` /
+ *   DATABASE_URL), build the merged declared state FROM SCRATCH on an
+ *   ephemeral database (created and dropped inside the run): state, authz,
+ *   and the derived layer. Cross-layer breakage both layers hid from the
+ *   static ring — a matview referencing a dropped column — fails here,
+ *   mechanically. The bar is the brick-2 identity: the fresh database must
+ *   land EXACTLY on the models' fingerprint (MATCH), which is
+ *   regenerate-and-match at full strength.
+ *
+ * Exit 1 on any failure; nothing is ever skipped silently.
+ */
+
+import fs from 'node:fs/promises';
+import postgres from 'postgres';
+import type { ModelDescriptor } from '@everystack/model';
+import type { TableContract } from '../authz-contract.js';
+import { compileDeclaredState } from '../declared-diff.js';
+import { compileMigration } from '../migration-compile.js';
+import { compileDrizzleSource } from '../schema-source.js';
+import { parseSqlSources, type SourceFile } from '../derived-source.js';
+import { currentGitRef } from '../state-apply.js';
+import { createUrlRunner } from '../db-source.js';
+import { resolveModelsPath } from '../models-path.js';
+import { executeSync, buildSyncReport, readSqlDirIfPresent } from './db-sync.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const DEFAULT_SQL_DIR = 'db/sql';
+const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
+
+// ---------------------------------------------------------------------------
+// The static ring (pure).
+// ---------------------------------------------------------------------------
+
+export interface CheckFinding {
+  level: 'ok' | 'note' | 'fail';
+  area: 'models' | 'compose' | 'artifact' | 'compute';
+  message: string;
+}
+
+export interface StaticCheckInput {
+  modelsPath: string;
+  /** null = the barrel did not load — the gate's first failure. */
+  models: ModelDescriptor[] | null;
+  modelsError?: string;
+  artifactPath: string;
+  /** null = no generated schema artifact on disk. */
+  artifactSource: string | null;
+  /** null = no db/sql directory. */
+  sources: SourceFile[] | null;
+}
+
+export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
+  const findings: CheckFinding[] = [];
+
+  if (input.models === null) {
+    findings.push({
+      level: 'fail',
+      area: 'models',
+      message: `models did not load from ${input.modelsPath}: ${input.modelsError ?? 'unknown error'}`,
+    });
+    return findings;
+  }
+  findings.push({ level: 'ok', area: 'models', message: `${input.models.length} model(s) loaded from ${input.modelsPath}` });
+
+  // The semantic merge conflict git can't see: two branches declaring the
+  // same table both merge cleanly — the merged state must still compose.
+  const seen = new Map<string, number>();
+  for (const m of input.models) seen.set(`${m.schema}.${m.table}`, (seen.get(`${m.schema}.${m.table}`) ?? 0) + 1);
+  const duplicates = [...seen.entries()].filter(([, n]) => n > 1).map(([t]) => t);
+  if (duplicates.length > 0) {
+    findings.push({
+      level: 'fail',
+      area: 'compose',
+      message: `the merged declared state does NOT compose: table(s) declared more than once — ${duplicates.join(', ')}. A merge landed two declarations of the same table; resolve to one.`,
+    });
+    return findings;
+  }
+  try {
+    compileDeclaredState(input.models);
+    const statements = compileMigration(input.models);
+    findings.push({ level: 'ok', area: 'compose', message: `declared state composes — ${statements.length} statement(s) from scratch` });
+  } catch (err: any) {
+    findings.push({ level: 'fail', area: 'compose', message: `the merged declared state does NOT compose: ${err.message}` });
+    return findings;
+  }
+
+  if (input.artifactSource === null) {
+    findings.push({
+      level: 'note',
+      area: 'artifact',
+      message: `no generated schema at ${input.artifactPath} — nothing to match (db:generate writes it)`,
+    });
+  } else if (input.artifactSource === compileDrizzleSource(input.models)) {
+    findings.push({ level: 'ok', area: 'artifact', message: `${input.artifactPath} matches regeneration byte-for-byte` });
+  } else {
+    findings.push({
+      level: 'fail',
+      area: 'artifact',
+      message: `${input.artifactPath} does NOT match regeneration — the models moved without db:generate, or the artifact was hand-edited (generated artifacts are never edited). Regenerate and commit.`,
+    });
+  }
+
+  if (input.sources === null) {
+    findings.push({ level: 'note', area: 'compute', message: 'no db/sql directory — derived layer not declared, nothing to parse' });
+  } else {
+    try {
+      const parsed = parseSqlSources(input.sources);
+      findings.push({
+        level: 'ok',
+        area: 'compute',
+        message: `${parsed.objects.length} derived object(s) parsed from ${input.sources.length} db/sql file(s)`,
+      });
+      for (const w of parsed.warnings) findings.push({ level: 'note', area: 'compute', message: w });
+    } catch (err: any) {
+      findings.push({ level: 'fail', area: 'compute', message: `db/sql does not parse: ${err.message}` });
+    }
+  }
+
+  return findings;
+}
+
+export function checkFailed(findings: CheckFinding[]): boolean {
+  return findings.some((f) => f.level === 'fail');
+}
+
+// ---------------------------------------------------------------------------
+// The ephemeral compose ring.
+// ---------------------------------------------------------------------------
+
+/** Every role the contract grants to or names in a policy — the compose DB needs them. */
+export function rolesFromContract(tables: TableContract[]): string[] {
+  const roles = new Set<string>();
+  for (const t of tables) {
+    for (const grantee of Object.keys(t.grants)) roles.add(grantee);
+    for (const grantee of Object.keys(t.columnGrants ?? {})) roles.add(grantee);
+    for (const p of t.policies) for (const r of p.roles) roles.add(r);
+  }
+  roles.delete('PUBLIC');
+  roles.delete('public');
+  return [...roles].sort();
+}
+
+export interface EphemeralComposeResult {
+  database: string;
+  createdRoles: string[];
+  converged: boolean;
+  fingerprintMatch: boolean;
+  fingerprint: string;
+  report: string[];
+}
+
+/**
+ * Build the declared state from scratch on an ephemeral database: CREATE
+ * DATABASE, roles the contract references (NOLOGIN, cluster-level, created
+ * only if absent), one `executeSync` for both layers, DROP DATABASE —
+ * always, error or not. The bar is `converged && fingerprintMatch`: a
+ * fresh database has nothing unmodeled and nothing to drop, so anything
+ * short of MATCH is a real compose fault.
+ */
+export async function executeEphemeralCompose(
+  adminUrl: string,
+  models: ModelDescriptor[],
+  sources: SourceFile[] | null,
+  opts: { actor?: string | null; gitRef?: string | null } = {},
+): Promise<EphemeralComposeResult> {
+  const dbName = `escheck_${process.pid}_${Date.now()}`;
+  const admin = postgres(adminUrl, { max: 1 });
+  try {
+    await admin.unsafe(`CREATE DATABASE "${dbName}"`);
+  } finally {
+    await admin.end();
+  }
+
+  const { runner, end } = await createUrlRunner(adminUrl.replace(/\/[^/?]+(\?|$)/, `/${dbName}$1`));
+  try {
+    const roles = rolesFromContract(compileDeclaredState(models).contract.tables);
+    for (const role of roles) {
+      if (!/^[a-z_][a-z0-9_$]*$/i.test(role)) {
+        throw new Error(`contract references a role name that is not a plain identifier: ${JSON.stringify(role)}`);
+      }
+      await runner(
+        `DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}') THEN CREATE ROLE "${role}" NOLOGIN; END IF; END $$`,
+      );
+    }
+
+    const run = await executeSync(runner, models, sources, {
+      actor: opts.actor ?? 'db:check',
+      gitRef: opts.gitRef ?? null,
+    });
+    return {
+      database: dbName,
+      createdRoles: roles,
+      converged: run.converged,
+      fingerprintMatch: run.fingerprintMatch,
+      fingerprint: run.state.toFingerprint,
+      report: buildSyncReport(run),
+    };
+  } finally {
+    await end?.();
+    const reaper = postgres(adminUrl, { max: 1 });
+    try {
+      await reaper.unsafe(`DROP DATABASE IF EXISTS "${dbName}" WITH (FORCE)`);
+    } finally {
+      await reaper.end();
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The CLI shell.
+// ---------------------------------------------------------------------------
+
+const MARK: Record<CheckFinding['level'], string> = { ok: '=', note: '·', fail: '!' };
+
+export async function dbCheckCommand(flags: Record<string, string>): Promise<void> {
+  const modelsPath = resolveModelsPath(flags.models);
+  let models: ModelDescriptor[] | null = null;
+  let modelsError: string | undefined;
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    models = await loadModels(modelsPath);
+  } catch (err: any) {
+    modelsError = err.message;
+  }
+
+  const artifactPath = flags['schema-out'] || DEFAULT_SCHEMA_OUT;
+  let artifactSource: string | null = null;
+  try {
+    artifactSource = await fs.readFile(artifactPath, 'utf8');
+  } catch {
+    artifactSource = null;
+  }
+  const sources = await readSqlDirIfPresent(flags['sql-dir'] || DEFAULT_SQL_DIR);
+
+  const findings = runStaticChecks({ modelsPath, models, modelsError, artifactPath, artifactSource, sources });
+  for (const f of findings) {
+    (f.level === 'fail' ? warn : info)(`${MARK[f.level]} ${f.area}: ${f.message}`);
+  }
+
+  let ephemeral: EphemeralComposeResult | null = null;
+  let ephemeralError: string | null = null;
+  const url = flags['database-url'] || process.env.DATABASE_URL;
+  const staticFailed = checkFailed(findings);
+  if (staticFailed) {
+    warn('ephemeral compose skipped — fix the static failures first.');
+  } else if (!url) {
+    warn('ephemeral compose SKIPPED — no --database-url / DATABASE_URL. Point db:check at a scratch PostgreSQL for the full gate (it creates and drops an ephemeral database).');
+  } else {
+    step('Composing the declared state from scratch on an ephemeral database...');
+    try {
+      ephemeral = await executeEphemeralCompose(url, models!, sources, {
+        actor: process.env.USER ?? 'db:check',
+        gitRef: currentGitRef(),
+      });
+      for (const line of ephemeral.report) info(`  ${line}`);
+    } catch (err: any) {
+      ephemeralError = err.message;
+      warn(`! compose: the declared state does NOT build from scratch: ${ephemeralError}`);
+    }
+  }
+
+  const ephemeralFailed = ephemeralError !== null
+    || (ephemeral !== null && !(ephemeral.converged && ephemeral.fingerprintMatch));
+  const failed = staticFailed || ephemeralFailed;
+
+  if (flags.json === 'true') {
+    console.log(JSON.stringify({
+      findings,
+      ephemeral: ephemeral === null ? null : {
+        converged: ephemeral.converged,
+        fingerprintMatch: ephemeral.fingerprintMatch,
+        fingerprint: ephemeral.fingerprint,
+        createdRoles: ephemeral.createdRoles,
+      },
+      ephemeralError,
+      ephemeralRan: ephemeral !== null,
+      failed,
+    }, null, 2));
+  } else if (failed) {
+    fail('db:check FAILED — the merged declared state is not shippable as-is (findings above).');
+  } else if (ephemeral !== null) {
+    success(`db:check passed — declared state composes from scratch and lands MATCH at ${ephemeral.fingerprint.slice(0, 12)}.`);
+  } else {
+    success('db:check passed (static ring only — no database provided for the ephemeral compose).');
+  }
+
+  if (failed) process.exit(1);
+}

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

@@ -24,6 +24,7 @@ import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { introspectSchema } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan.js';
+import { verifyDescent } from '../git-descent.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
@@ -101,6 +102,17 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
 
     for (const line of buildPlanSummary(plan)) info(line);
     info(`plan_ref: ${planHash(plan).slice(0, 12)}`);
+
+    // The fast-forward rule, warn-only at mint time (db:apply enforces it):
+    // a stale checkout mints a legal-looking plan whose edge REVERTS merged
+    // work — say so on the review surface, where a human still reads it.
+    if (plan.statements.length > 0) {
+      const verdict = await verifyDescent(modelsPath, { snapshot, contract }, {});
+      if (verdict.status === 'diverged' || verdict.status === 'drift') {
+        warn(`descent: ${verdict.reason}`);
+        warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
+      }
+    }
     if (out !== '-') {
       success(`Wrote ${out} — review it, then \`everystack db:apply --plan ${out}\`.`);
       warn('Plans are ephemeral release artifacts — attach to the run, do NOT commit.');

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

@@ -37,6 +37,7 @@ import { generateMigrationSql, unmodeledTables } from '../migration-generate.js'
 import {
   applyStateAndVerify,
   classifyGeneratedStatements,
+  classifyDestructive,
   currentGitRef,
   type ClassifiedStatements,
   type StateSyncOutcome,
@@ -212,7 +213,7 @@ export function syncFailed(run: SyncRun): boolean {
 // The CLI shell.
 // ---------------------------------------------------------------------------
 
-async function readSqlDirIfPresent(dir: string): Promise<SourceFile[] | null> {
+export async function readSqlDirIfPresent(dir: string): Promise<SourceFile[] | null> {
   let entries: string[];
   try {
     entries = await fs.readdir(dir);
@@ -277,6 +278,10 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
         onStatePlan: (statements, classified) => {
           if (classified.executable.length > 0) {
             info(`state plan — ${classified.executable.length} statement(s):`);
+            const { drops, narrowings } = classifyDestructive(classified.executable);
+            if (drops.length + narrowings.length > 0) {
+              warn(`${drops.length + narrowings.length} DESTRUCTIVE — ${drops.length} drop(s), ${narrowings.length} narrowing type change(s). Dev sync runs them; protected stages gate them (db:plan → db:apply).`);
+            }
             console.log('');
             for (const s of statements) console.log(s.endsWith(';') ? s : `${s};`);
             console.log('');

package/src/cli/edge-plan.ts

@@ -29,12 +29,22 @@ import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
 import { generateMigrationSql, unmodeledTables } from './migration-generate.js';
-import { classifyGeneratedStatements } from './state-apply.js';
+import { classifyGeneratedStatements, classifyDestructive } from './state-apply.js';
 import { fingerprintLive, fingerprintState, fingerprintModels, stableStringify } from './schema-fingerprint.js';
 import { compileDeclaredState } from './declared-diff.js';
 import { compileTableRenames } from './schema-compile.js';
 
-export const PLAN_VERSION = 1;
+export const PLAN_VERSION = 2;
+
+/** Classification counts (brick 9, decision 11): destructive = drops + narrowings. */
+export interface PlanClassification {
+  /** Executable statements that lose no data. */
+  additive: number;
+  /** `DROP TABLE/COLUMN/TYPE` — the data is gone. */
+  drops: number;
+  /** Lossy/risky `ALTER COLUMN … TYPE` — data loss wearing an ALTER. */
+  narrowings: number;
+}
 
 export interface EdgePlan {
   v: number;
@@ -47,8 +57,9 @@ export interface EdgePlan {
   /** The edge, in db:generate's statement grammar (no held drops — mint refuses them). */
   statements: string[];
   executable: number;
-  /** Executable statements that DROP something — shown red, explicit by construction. */
+  /** Executable statements that LOSE DATA (drops + narrowing type changes) — red, gated at apply. */
   destructive: number;
+  classification: PlanClassification;
   notices: number;
   /** Live tables no model declares — untouched by the edge, riding into `to` as-is. */
   unmodeled: string[];
@@ -64,35 +75,24 @@ export interface MintOptions {
 }
 
 /**
- * Mint the edge from a target's introspected state to the models' declared
- * state. Pure: introspection in, plan out. Throws when the edge would hold
- * drops back — a plan must be complete to have a reachable endpoint.
+ * The predicted live fingerprint of a target AFTER the models' edge lands:
+ * declared tables on their compiled shapes exactly (that is what
+ * apply-and-verify proves), unmodeled tables and enums riding through
+ * untouched. A pending table rename's SOURCE does not ride through — the
+ * edge renames it away, and it lands as its declared new name.
+ * fingerprintState sorts internally, so merge order is irrelevant.
+ *
+ * Two callers, one meaning: minting uses it as a plan's `to` endpoint, and
+ * git-descent uses it as the declares-test — a commit DECLARES a target's
+ * live state exactly when this prediction equals the live fingerprint
+ * (the edge from the target to that commit's models is empty).
  */
-export function mintEdgePlan(
+export function predictLiveFingerprint(
   models: ModelDescriptor[],
   snapshot: SchemaSnapshot,
   contract: AuthzContract,
-  opts: MintOptions = {},
-): EdgePlan {
-  const statements = generateMigrationSql(models, snapshot, {
-    schema: opts.schema,
-    allowDrops: opts.allowDrops,
-    liveAuthz: contract,
-  });
-  const classified = classifyGeneratedStatements(statements);
-  if (classified.heldDrops.length > 0) {
-    throw new Error(
-      `the edge holds ${classified.heldDrops.length} destructive change(s) back — a plan must be complete. ` +
-      'Re-mint with --allow-drops to carry the destruction explicitly, or mark the contraction in the models first and drop later.',
-    );
-  }
-
-  // The predicted endpoint: declared tables land exactly on their compiled
-  // shapes (that is what apply-and-verify proves), unmodeled tables and
-  // enums ride through untouched. A pending table rename's SOURCE does not
-  // ride through — the edge renames it away, and it lands as its declared
-  // new name. fingerprintState sorts internally, so merge order is
-  // irrelevant.
+  opts: { schema?: string } = {},
+): string {
   const declared = compileDeclaredState(models, { schema: opts.schema });
   const declaredTables = new Set(declared.snapshot.tables.map((t) => t.table));
   const currentNames = new Set(snapshot.tables.map((t) => t.table));
@@ -119,18 +119,53 @@ export function mintEdgePlan(
     ...declared.contract.tables,
     ...contract.tables.filter((t) => ridesThrough(t.table)),
   ];
+  return fingerprintState(mergedSnapshot, mergedAuthz).hash;
+}
+
+/**
+ * Mint the edge from a target's introspected state to the models' declared
+ * state. Pure: introspection in, plan out. Throws when the edge would hold
+ * drops back — a plan must be complete to have a reachable endpoint.
+ */
+export function mintEdgePlan(
+  models: ModelDescriptor[],
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  opts: MintOptions = {},
+): EdgePlan {
+  const statements = generateMigrationSql(models, snapshot, {
+    schema: opts.schema,
+    allowDrops: opts.allowDrops,
+    liveAuthz: contract,
+  });
+  const classified = classifyGeneratedStatements(statements);
+  if (classified.heldDrops.length > 0) {
+    throw new Error(
+      `the edge holds ${classified.heldDrops.length} destructive change(s) back — a plan must be complete. ` +
+      'Re-mint with --allow-drops to carry the destruction explicitly, or mark the contraction in the models first and drop later.',
+    );
+  }
+
+  // Data-destructive only: dropping a policy/grant is recoverable metadata
+  // (the authz phase is data-safe by construction); dropping a table,
+  // column, or type is not — and neither is a narrowing type change, which
+  // is data loss wearing an ALTER.
+  const breakdown = classifyDestructive(classified.executable);
+  const destructive = breakdown.drops.length + breakdown.narrowings.length;
 
   return {
     v: PLAN_VERSION,
     fromFingerprint: fingerprintLive(snapshot, contract).hash,
-    toFingerprint: fingerprintState(mergedSnapshot, mergedAuthz).hash,
+    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema }),
     declaredFingerprint: fingerprintModels(models, { schema: opts.schema }).hash,
     statements,
     executable: classified.executable.length,
-    // Data-destructive only: dropping a policy/grant is recoverable metadata
-    // (the authz phase is data-safe by construction); dropping a table,
-    // column, or type is not.
-    destructive: classified.executable.filter((s) => /\bDROP\s+(TABLE|COLUMN|TYPE)\b/.test(s)).length,
+    destructive,
+    classification: {
+      additive: classified.executable.length - destructive,
+      drops: breakdown.drops.length,
+      narrowings: breakdown.narrowings.length,
+    },
     notices: classified.notices.length,
     unmodeled: unmodeledTables(models, snapshot),
     gitRef: opts.gitRef ?? null,
@@ -168,7 +203,14 @@ export function buildPlanSummary(plan: EdgePlan): string[] {
   }
   lines.push(`${plan.executable} executable statement(s), ${plan.notices} notice(s)`);
   if (plan.destructive > 0) {
-    lines.push(`! ${plan.destructive} DESTRUCTIVE statement(s) — drops carried explicitly, review them`);
+    const { drops, narrowings } = classifyDestructive(classifyGeneratedStatements(plan.statements).executable);
+    lines.push(
+      `! ${plan.destructive} DESTRUCTIVE statement(s) — ${drops.length} drop(s), ${narrowings.length} narrowing type change(s). Data loss carried explicitly; the apply is gated (--confirm + snapshot, approver set when declared):`,
+    );
+    for (const statement of [...drops, ...narrowings]) {
+      const ddl = statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? statement;
+      lines.push(`!   ${ddl.trim()}`);
+    }
   }
   if (plan.unmodeled.length > 0) {
     lines.push(`· ${plan.unmodeled.length} unmodeled table(s) ride through untouched: ${plan.unmodeled.join(', ')}`);