@everystack/cli 0.3.21 → 0.3.23

package/src/cli/git-descent.ts

@@ -0,0 +1,251 @@
+/**
+ * git-descent — a protected database is a git ref (brick 7 of the
+ * migration-authority design).
+ *
+ * The rule git already taught everyone: `db:apply` is a fast-forward push.
+ * The target's live fingerprint maps to the git commit whose committed
+ * models DECLARE that state; the deploying checkout must be a descendant
+ * of such a commit, or the apply refuses — "rebase first". This is what
+ * stops the multi-dev disaster case: A merges and deploys, B (branched
+ * before A merged) mints against the target — the concurrency lock passes,
+ * because B's plan was minted against current reality, but B's edge would
+ * REVERT A's merged work. The descent check catches exactly that: the
+ * commit declaring the target's state is not in B's history.
+ *
+ * The search runs over GIT ALONE, never `schema_log` (the ledger is a
+ * memoir, not a control surface — design decision 7): enumerate every
+ * historical state of the models directory across all refs, compile each
+ * unique tree, and ask whether its predicted live endpoint equals the
+ * target's live fingerprint (brick 4's merged prediction, so unmodeled
+ * brownfield tables ride through the test). A fingerprint no commit
+ * declares is a DRIFT report and an explicit operator decision — never a
+ * guess. Identity is the models-directory TREE, not the commit: a
+ * cherry-picked identical state is the same declared state.
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect.js';
+import type { AuthzContract } from './authz-contract.js';
+import { fingerprintLive } from './schema-fingerprint.js';
+import { predictLiveFingerprint } from './edge-plan.js';
+
+/** Compile a models barrel on disk. The default rides the CLI's runtime (tsx). */
+export type ModelsLoader = (barrel: string) => Promise<ModelDescriptor[]>;
+
+export interface LiveState {
+  snapshot: SchemaSnapshot;
+  contract: AuthzContract;
+}
+
+export interface DescentOptions {
+  /** Where git commands run. Default: process.cwd(). */
+  cwd?: string;
+  /** The Postgres schema the Models default to. Default: `public`. */
+  schema?: string;
+  loader?: ModelsLoader;
+  /**
+   * Where historical trees materialize. Default: a fresh temp dir under the
+   * repo's node_modules — bare imports (`@everystack/model`) must resolve
+   * from the materialized files, and node walks parent directories.
+   */
+  materializeRoot?: string;
+  /** The ref that must descend from the declaring commit. Default: HEAD. */
+  headRef?: string;
+}
+
+export type DescentVerdict =
+  /** Not a git checkout (or no commits yet) — the rule cannot be verified here. */
+  | { status: 'no-git' }
+  /** The target has no tables — nothing to protect, first apply bootstraps it. */
+  | { status: 'fresh-target' }
+  /** Fast-forward: `commit` declares the target's live state and is an ancestor of HEAD. */
+  | { status: 'ok'; commit: string; tree: string; scannedTrees: number }
+  /** The declaring commits exist but none is an ancestor of HEAD — rebase first. */
+  | { status: 'diverged'; commits: string[]; tree: string; reason: string }
+  /** No committed models state declares the live fingerprint — operator decision. */
+  | { status: 'drift'; scannedTrees: number; compileFailures: string[]; reason: string };
+
+export interface ModelTreeCandidate {
+  /** The models directory's tree oid — the identity of a declared state. */
+  tree: string;
+  /** Every enumerated commit carrying that tree, newest first. */
+  commits: string[];
+}
+
+const short = (ref: string): string => ref.slice(0, 12);
+
+function git(args: string[], cwd: string): string | null {
+  try {
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+  } catch {
+    return null;
+  }
+}
+
+const defaultLoader: ModelsLoader = async (barrel) => {
+  const mod: any = await import(pathToFileURL(path.resolve(barrel)).href);
+  const models = mod.models ?? mod.default;
+  if (!Array.isArray(models)) throw new Error(`${barrel} does not export a \`models\` array`);
+  return models;
+};
+
+/**
+ * Every historical state of the models directory across ALL refs, newest
+ * first, grouped by tree oid. `--full-history` keeps every !TREESAME commit
+ * (no simplification dropping a state introduced on a side branch); one
+ * `cat-file --batch-check` resolves all `<sha>:<dir>` specs in a single
+ * child process, in input order.
+ */
+export function enumerateModelTrees(modelsDir: string, cwd: string): ModelTreeCandidate[] {
+  const out = git(['rev-list', '--all', '--full-history', '--date-order', '--', modelsDir], cwd);
+  if (out === null) return [];
+  const shas = out.trim().split('\n').filter(Boolean);
+  if (shas.length === 0) return [];
+
+  const specs = shas.map((sha) => (modelsDir === '.' ? `${sha}^{tree}` : `${sha}:${modelsDir}`));
+  let batch: string;
+  try {
+    batch = execFileSync('git', ['cat-file', '--batch-check'], {
+      cwd,
+      input: specs.join('\n') + '\n',
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }).toString();
+  } catch {
+    return [];
+  }
+
+  const byTree = new Map<string, string[]>();
+  const order: string[] = [];
+  batch.trim().split('\n').forEach((line, i) => {
+    const m = line.trim().match(/^([0-9a-f]{40,64}) tree /);
+    if (!m) return; // the directory is absent at that commit, or not a tree
+    if (!byTree.has(m[1])) {
+      byTree.set(m[1], []);
+      order.push(m[1]);
+    }
+    byTree.get(m[1])!.push(shas[i]);
+  });
+  return order.map((tree) => ({ tree, commits: byTree.get(tree)! }));
+}
+
+/** Extract a tree into `dest` — `git archive` piped to tar, no shell. */
+export function materializeTree(tree: string, dest: string, cwd: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  const archive = execFileSync('git', ['archive', '--format=tar', tree], {
+    cwd,
+    maxBuffer: 512 * 1024 * 1024,
+  });
+  execFileSync('tar', ['-xf', '-', '-C', dest], { input: archive });
+}
+
+/**
+ * The fast-forward rule. Given the target's live state (already
+ * introspected — the apply path has it in hand), find the commit whose
+ * committed models declare that state and verify the checkout descends
+ * from it. Any declaring ancestor satisfies the rule; `diverged` is
+ * reported only when NO tree declaring the state has one.
+ */
+export async function verifyDescent(
+  modelsPath: string,
+  live: LiveState,
+  opts: DescentOptions = {},
+): Promise<DescentVerdict> {
+  if (live.snapshot.tables.length === 0) return { status: 'fresh-target' };
+
+  const cwd = opts.cwd ?? process.cwd();
+  const rootOut = git(['rev-parse', '--show-toplevel'], cwd);
+  if (rootOut === null) return { status: 'no-git' };
+  const repoRoot = rootOut.trim();
+  const headOut = git(['rev-parse', opts.headRef ?? 'HEAD'], cwd);
+  if (headOut === null) return { status: 'no-git' };
+  const head = headOut.trim();
+
+  // realpath the cwd side: `--show-toplevel` resolves symlinks (macOS tmpdir
+  // is /var → /private/var), and a mismatched prefix would walk the models
+  // path right out of the repo.
+  const modelsAbs = path.resolve(fs.realpathSync(cwd), modelsPath);
+  const rel = path.relative(repoRoot, modelsAbs);
+  const modelsDir = path.dirname(rel) || '.';
+  const barrel = path.basename(modelsAbs);
+
+  const candidates = enumerateModelTrees(modelsDir, repoRoot);
+  const liveFingerprint = fingerprintLive(live.snapshot, live.contract).hash;
+
+  const nodeModules = path.join(repoRoot, 'node_modules');
+  const materializeRoot = opts.materializeRoot
+    ?? fs.mkdtempSync(path.join(fs.existsSync(nodeModules) ? nodeModules : os.tmpdir(), '.everystack-descent-'));
+  const ownsRoot = !opts.materializeRoot;
+  const loader = opts.loader ?? defaultLoader;
+
+  const compileFailures: string[] = [];
+  const declaringButDiverged: ModelTreeCandidate[] = [];
+  try {
+    for (const candidate of candidates) {
+      const dest = path.join(materializeRoot, candidate.tree);
+      let predicted: string;
+      try {
+        if (!fs.existsSync(dest)) materializeTree(candidate.tree, dest, repoRoot);
+        const models = await loader(path.join(dest, barrel));
+        predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema });
+      } catch (err: any) {
+        compileFailures.push(`${short(candidate.tree)} (at ${short(candidate.commits[0])}): ${err.message}`);
+        continue;
+      }
+      if (predicted !== liveFingerprint) continue;
+
+      for (const commit of candidate.commits) {
+        try {
+          execFileSync('git', ['merge-base', '--is-ancestor', commit, head], {
+            cwd: repoRoot,
+            stdio: 'ignore',
+          });
+          return {
+            status: 'ok',
+            commit,
+            tree: candidate.tree,
+            scannedTrees: candidates.indexOf(candidate) + 1,
+          };
+        } catch {
+          // not an ancestor — keep looking; an identical tree elsewhere may be
+        }
+      }
+      declaringButDiverged.push(candidate);
+    }
+  } finally {
+    if (ownsRoot) fs.rmSync(materializeRoot, { recursive: true, force: true });
+  }
+
+  if (declaringButDiverged.length > 0) {
+    const commits = declaringButDiverged.flatMap((c) => c.commits);
+    return {
+      status: 'diverged',
+      commits,
+      tree: declaringButDiverged[0].tree,
+      reason:
+        `the target's state is declared by ${short(commits[0])}` +
+        (commits.length > 1 ? ` (+${commits.length - 1} more)` : '') +
+        ', which is NOT an ancestor of your checkout — your branch diverged before it. ' +
+        'Rebase onto it and re-mint, so your edge moves the target forward instead of reverting merged work.',
+    };
+  }
+
+  const failureNote = compileFailures.length > 0
+    ? ` (${compileFailures.length} historical tree(s) no longer compile and were skipped)`
+    : '';
+  return {
+    status: 'drift',
+    scannedTrees: candidates.length,
+    compileFailures,
+    reason:
+      `no committed models state declares the target's live fingerprint ${short(liveFingerprint)} — ` +
+      `scanned ${candidates.length} historical tree(s) across all refs${failureNote}. ` +
+      'Either the database was hand-edited (drift) or the declaring history was rewritten. ' +
+      'Align the models with the live database first (db:pull, commit), ' +
+      'or force with ceremony: --force-descent <snapshot-ref> --confirm.',
+  };
+}

package/src/cli/index.ts

@@ -17,6 +17,8 @@ import { dbSyncCommand } from './commands/db-sync.js';
 import { dbDiffCommand } from './commands/db-diff.js';
 import { dbPlanCommand } from './commands/db-plan.js';
 import { dbApplyCommand } from './commands/db-apply.js';
+import { dbCheckCommand } from './commands/db-check.js';
+import { dbApproversCommand } from './commands/db-approvers.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';
@@ -196,6 +198,12 @@ async function main() {
     case 'db:apply':
       await dbApplyCommand(flags);
       break;
+    case 'db:check':
+      await dbCheckCommand(flags);
+      break;
+    case 'db:approvers':
+      await dbApproversCommand(flags);
+      break;
     case 'db:authz:pull':
       await dbAuthzPullCommand(flags);
       break;
@@ -323,7 +331,9 @@ Usage:
   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:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed
-  everystack db:apply          --plan <file.plan.json> [--database-url <url>]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), apply as one transaction (schema_log w/ plan_ref), verify it landed exactly on plan.to. Idempotent when already at the target state; direct connection required
+  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + a snapshot (automatic via db:backup with --stage, else --snapshot-ref) + the stage's approver set when declared (STS identity-verified). Every refusal is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there; direct connection required
+  everystack db:check          [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, db/sql parses) and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
+  everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only
   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/schema-source.ts

@@ -304,6 +304,11 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
       const { call, builder: pgBuilder } = baseColumnSource(toSnakeCase(key), spec);
       pgCoreBuilders.add(pgBuilder);
       const mods = columnModifiers(spec, isComposite, modelsByDescriptor);
+      if (spec.isDeprecated) {
+        // The contract phase (decision 13): the column stays in the database and
+        // stays readable; the strikethrough warns new code away at author time.
+        colLines.push(`  /** @deprecated contract phase — readable, not writable; the physical drop is a later, gated act. */`);
+      }
       colLines.push(`  ${key}: ${call}${mods},`);
     }
 

package/src/cli/state-apply.ts

@@ -56,6 +56,36 @@ export function classifyGeneratedStatements(statements: string[]): ClassifiedSta
   return { executable, heldDrops, notices };
 }
 
+/**
+ * The destructive subset of an executable statement stream — destructive
+ * means DATA LOSS (brick 9's classification, design decision 11):
+ *
+ *   drops       — `DROP TABLE/COLUMN/TYPE`: the data is gone.
+ *   narrowings  — lossy/risky `ALTER COLUMN … SET DATA TYPE`: data loss
+ *                 wearing an ALTER. Detection rides the emitter's structural
+ *                 contract, not prose: a SAFE type change is a bare
+ *                 `SET DATA TYPE`; anything lossy or risky carries a `USING`
+ *                 cast (schema-diff's `classifyTypeChange`, conservative by
+ *                 default — the contract is pinned by test).
+ *
+ * Recoverable metadata is never destructive: policies, grants, constraints,
+ * defaults, nullability all re-declare from the models without touching a row.
+ */
+export interface DestructiveBreakdown {
+  drops: string[];
+  narrowings: string[];
+}
+
+export function classifyDestructive(executable: string[]): DestructiveBreakdown {
+  const drops: string[] = [];
+  const narrowings: string[] = [];
+  for (const statement of executable) {
+    if (/\bDROP\s+(TABLE|COLUMN|TYPE)\b/.test(statement)) drops.push(statement);
+    else if (/\bSET DATA TYPE\b/.test(statement) && /\bUSING\b/.test(statement)) narrowings.push(statement);
+  }
+  return { drops, narrowings };
+}
+
 /** The current git HEAD, for schema_log's intent pointer. Null outside a repo. */
 export function currentGitRef(): string | null {
   try {