@everystack/cli 0.3.22 → 0.3.25

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[];
@@ -135,6 +146,13 @@ export function mintEdgePlan(
     );
   }
 
+  // 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,
@@ -142,10 +160,12 @@ export function mintEdgePlan(
     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,
@@ -183,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(', ')}`);

package/src/cli/index.ts

@@ -18,6 +18,9 @@ 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 { dbBackfillCommand } from './commands/db-backfill.js';
+import { dbTemplateRefreshCommand, dbBranchCommand } from './commands/db-branch.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';
@@ -200,6 +203,18 @@ async function main() {
     case 'db:check':
       await dbCheckCommand(flags);
       break;
+    case 'db:approvers':
+      await dbApproversCommand(flags);
+      break;
+    case 'db:backfill':
+      await dbBackfillCommand(flags);
+      break;
+    case 'db:template:refresh':
+      await dbTemplateRefreshCommand(flags);
+      break;
+    case 'db:branch':
+      await dbBranchCommand(flags);
+      break;
     case 'db:authz:pull':
       await dbAuthzPullCommand(flags);
       break;
@@ -327,8 +342,12 @@ 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>] [--models <barrel>] [--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"; force needs the snapshot you took + --confirm), 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:backfill       [--database-url <url>] [--dir db/backfills] [--apply] [--mark-applied <file.sql>] [--json]  One-shot data jobs in their own lane: plan shows applied (by CONTENT identity — renames/comment edits are no-ops) / pending (in order, unbounded-pass advisories) / blocked (a name that already ran in a different form — one-shot jobs are immutable). --apply runs each pending job as its own transaction, recorded in everystack.backfill_log (a failure rolls back alone, is recorded, stops the run); --mark-applied records without running. Never runs as a schema side effect; direct connection required
+  everystack db:template:refresh [--database-url <url>] [--models <barrel>] [--sql-dir db/sql] [--seed "<cmd>"] [--no-seed]  (Re)build the dev template <base>_tpl FROM THE DECLARED STATE (both layers, fingerprint MATCH bar) + seed-as-code (the app's db:seed script, run with DATABASE_URL pointed at the template; --seed overrides). All or nothing: a failed build/seed leaves NO template. Never a data copy
+  everystack db:branch         [--list | --drop --confirm | --prune --confirm] [--database-url <url>]  Mint (or find) the current git branch's database from the template (CREATE DATABASE … TEMPLATE — schema, authz, derived layer, and seed rows inherited), print its DATABASE_URL, then db:sync evolves it with the checkout. --list maps every branch DB to its branch; --prune drops the ones whose branch is gone (never guesses: unknown mappings are kept)
   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/model-api.ts

@@ -34,3 +34,10 @@ export * from './authz-owner-probe.js';
 
 // --- the SECDEF function catalog the contract introspection needs -----------
 export { FUNCTIONS_SQL, catalogFunctionToDescriptor } from './security-catalog.js';
+
+// --- databases FROM the declared state: ephemeral test DBs + the builder ----
+// `createEphemeralDatabase(adminUrl, models, { sources })` is the packaged
+// create-sync-drop shape for consumer test suites: a fresh database at the
+// declared state (state + authz + derived), verified to fingerprint MATCH,
+// dropped when you're done — never long-lived, never poisoned.
+export * from './db-build.js';

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 {