@everystack/cli 0.3.28 → 0.4.0

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

@@ -22,171 +22,181 @@
  */
 
 import fs from 'node:fs/promises';
-import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract.js';
-import { introspectSchema, type SchemaSnapshot } from '../schema-introspect.js';
+import { type QueryRunner } from '../authz-contract.js';
+import { introspectSchema } from '../schema-introspect.js';
+import { introspectContract } from '../authz-contract.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
-import { fingerprintLive } from '../schema-fingerprint.js';
-import { applyGeneratedStatements, currentGitRef } from '../state-apply.js';
-import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from '../derived-apply.js';
-import { checkPlanPrecondition, planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan.js';
-import { verifyDescent, type LiveState } from '../git-descent.js';
-import { checkDestructiveAuthority, readApproverParam, resolveCallerIdentity } from '../apply-authority.js';
+import { currentGitRef } from '../state-apply.js';
+import { planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan.js';
+import { verifyDescent, type DescentVerdict, type LiveState } from '../git-descent.js';
+import { checkDestructiveAuthority, readApproverParam, resolveCallerIdentity, type AuthorityVerdict } from '../apply-authority.js';
 import { resolveModelsPath } from '../models-path.js';
-import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveConfig, opsFunction } from '../config.js';
-import { invokeAction } from '../aws.js';
+import { invokeAction, lambdaQueryRunner } from '../aws.js';
+import { executeApplyPlan, type ApplyPlanResult } from '../apply-execute.js';
 import { step, success, fail, info, warn } from '../output.js';
 
+// The apply core lives in apply-execute.ts (shared with the ops Lambda's
+// db:apply action). Re-exported so the existing integration suites — and any
+// other in-repo caller — keep importing it from this command module.
+export { executeApplyPlan } from '../apply-execute.js';
+export type { ApplyPlanOptions, ApplyPlanResult } from '../apply-execute.js';
+
 // ---------------------------------------------------------------------------
-// The testable core.
+// The CLI shell.
 // ---------------------------------------------------------------------------
 
-export interface ApplyPlanOptions {
-  actor?: string | null;
-  /** Defaults to the plan's own gitRef (the intent that minted it). */
-  gitRef?: string | null;
-  /**
-   * The fast-forward rule (brick 7): called with the target's live state
-   * after the concurrency lock passes, BEFORE anything executes. Return
-   * `ok: false` to refuse — the checkout does not descend from the commit
-   * declaring the target's state. Omitted = no descent enforcement (tests,
-   * or an explicit, confirmed, snapshotted force).
-   */
-  verifyDescent?: (live: {
-    snapshot: SchemaSnapshot;
-    contract: AuthzContract;
-    fingerprint: string;
-  }) => Promise<{ ok: true } | { ok: false; reason: string }>;
-  /**
-   * Destructive authority (brick 9, decisions 11+12): called only when the
-   * plan is destructive, after the lock and descent checks pass. Return
-   * `ok: false` to refuse — the caller is not in the stage's declared
-   * approver set. Omitted = no authority gate (non-staged targets keep the
-   * ceremony the command shell enforces).
-   */
-  verifyAuthority?: () => Promise<{ ok: true } | { ok: false; reason: string }>;
-  /**
-   * Runs after every verification passes and BEFORE the edge executes, only
-   * for destructive plans — the auto-snapshot seam ("losing data should be
-   * hard": confirmed, approved, snapshotted, in that order). A throw here
-   * aborts the apply with nothing executed.
-   */
-  beforeDestructive?: () => Promise<void>;
-  /** Injectable clock for tests. */
-  now?: () => number;
-}
-
-export interface ApplyPlanResult {
-  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'authority-refused' | 'verify-failed';
-  liveFingerprint: string;
-  reason?: string;
-  logId?: number;
+/**
+ * Collapse a DescentVerdict into the ok/reason shape the apply core (and the
+ * ops Lambda's db:apply action) enforce. `no-git` / `fresh-target` pass — the
+ * rule can't be verified there — matching the direct-URL path's callback.
+ */
+export function descentVerdictForApply(verdict: DescentVerdict): { ok: true } | { ok: false; reason: string } {
+  switch (verdict.status) {
+    case 'ok':
+    case 'fresh-target':
+    case 'no-git':
+      return { ok: true };
+    case 'diverged':
+    case 'drift':
+      return { ok: false, reason: verdict.reason };
+  }
 }
 
 /**
- * Decision 7, made whole: every database records every refusal, not just
- * every apply. Best-effort by construction — a memoir INSERT that cannot be
- * written must never mask the refusal itself (a target that rejects the
- * bookkeeping write would have failed the apply's ENSURE identically).
+ * Render an ApplyPlanResult — shared by the direct (`--database-url`) and the
+ * credential-free staged (`--stage`) paths, so the two report identically.
+ * Every refusal and the verify-fault exit non-zero.
  */
-async function recordRefusal(
-  runner: QueryRunner,
-  plan: EdgePlan,
-  liveFingerprint: string,
-  gate: string,
-  reason: string,
-  options: ApplyPlanOptions,
-): Promise<void> {
-  try {
-    await runner(ENSURE_RECONCILER_SQL.join(';\n'));
-    await runner(renderSchemaLogInsert({
-      kind: 'state refusal',
-      outcome: 'refused',
-      actor: options.actor ?? null,
-      gitRef: options.gitRef ?? plan.gitRef,
-      planRef: planHash(plan),
-      fromFingerprint: liveFingerprint,
-      toFingerprint: plan.toFingerprint,
-      sql: `-- REFUSED (${gate}): ${reason}\n${plan.statements.join('\n;\n')}`,
-    }));
-  } catch {
-    // Swallowed deliberately — see the docblock.
+function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void {
+  switch (result.status) {
+    case 'already-applied':
+      success(`Already at ${plan.toFingerprint.slice(0, 12)} — nothing to do (idempotent re-apply).`);
+      break;
+    case 'refused':
+      fail(`REFUSED: ${result.reason}`);
+      process.exit(1);
+      break;
+    case 'descent-refused':
+      fail(`REFUSED (fast-forward rule): ${result.reason}`);
+      process.exit(1);
+      break;
+    case 'authority-refused':
+      fail(`REFUSED (destructive authority): ${result.reason}`);
+      process.exit(1);
+      break;
+    case 'verify-failed':
+      fail(`Verify FAILED: ${result.reason}`);
+      process.exit(1);
+      break;
+    case 'applied':
+      success(`Applied and verified — the target is at ${result.liveFingerprint.slice(0, 12)}, exactly as the plan predicted. Recorded in everystack.schema_log (plan_ref ${planHash(plan).slice(0, 12)}).`);
+      break;
   }
 }
 
-/** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
-export async function executeApplyPlan(
-  runner: QueryRunner,
+/**
+ * db:apply --stage: the credential-free staged write. The operator never holds
+ * a database URL — the WRITE runs in the ops Lambda's db:apply action against
+ * its resource-linked connection. The CLI keeps only what needs the checkout
+ * or the caller's identity: the fast-forward (descent) rule and the
+ * destructive-approver check. The Lambda re-verifies the concurrency lock,
+ * applies the DDL in one transaction, stamps schema_log, and verifies plan.to.
+ */
+async function applyPlanViaStage(
   plan: EdgePlan,
-  options: ApplyPlanOptions = {},
-): Promise<ApplyPlanResult> {
-  const before = await introspectSchema(runner);
-  const beforeAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
-  const live = fingerprintLive(before, beforeAuthz).hash;
+  flags: Record<string, string>,
+  forceDescent: string | undefined,
+): Promise<void> {
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  const { region } = config;
+  const fn = opsFunction(config);
 
-  if (live === plan.toFingerprint) {
-    return { status: 'already-applied', liveFingerprint: live };
-  }
-  const pre = checkPlanPrecondition(plan, live);
-  if (!pre.ok) {
-    await recordRefusal(runner, plan, live, 'concurrency lock', pre.reason, options);
-    return { status: 'refused', liveFingerprint: live, reason: pre.reason };
-  }
+  info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
 
-  if (options.verifyDescent) {
-    const descent = await options.verifyDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live });
-    if (!descent.ok) {
-      await recordRefusal(runner, plan, live, 'fast-forward rule', descent.reason, options);
-      return { status: 'descent-refused', liveFingerprint: live, reason: descent.reason };
+  try {
+    // Descent — the fast-forward rule needs the git checkout, so the CLI
+    // decides it (the Lambda has no checkout). Read the stage's state read-only
+    // via the ops Lambda's db:query action, run the rule locally, and hand the
+    // verdict to the write action, which enforces + records it in order.
+    let descentVerdict: { ok: true } | { ok: false; reason: string };
+    if (forceDescent !== undefined) {
+      warn(`DESCENT FORCED — the fast-forward rule is bypassed for this apply. Snapshot on record: ${forceDescent}.`);
+      descentVerdict = { ok: true };
+    } else {
+      step('Asking the stage its state (read-only via the ops Lambda)...');
+      const readRunner = lambdaQueryRunner(region, fn);
+      const snapshot = await introspectSchema(readRunner);
+      const contract = await introspectContract(readRunner, contractFunctionRow, FUNCTIONS_SQL);
+      step("Descent: searching git for the commit that declares the stage's state...");
+      const verdict = await verifyDescent(resolveModelsPath(flags.models), { snapshot, contract }, {});
+      switch (verdict.status) {
+        case 'ok':
+          info(`descent: ${verdict.commit.slice(0, 12)} declares the stage's state and is an ancestor of HEAD — fast-forward.`);
+          break;
+        case 'fresh-target':
+          info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
+          break;
+        case 'no-git':
+          warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
+          break;
+        case 'diverged':
+        case 'drift':
+          break; // the reason travels to the action's refusal + the memoir
+      }
+      descentVerdict = descentVerdictForApply(verdict);
     }
-  }
 
-  if (plan.destructive > 0 && options.verifyAuthority) {
-    const authority = await options.verifyAuthority();
-    if (!authority.ok) {
-      await recordRefusal(runner, plan, live, 'destructive authority', authority.reason, options);
-      return { status: 'authority-refused', liveFingerprint: live, reason: authority.reason };
+    // Destructive ceremony — the approver check is against the caller's REAL
+    // IAM identity (STS), which the Lambda cannot see, so the CLI resolves it
+    // and checks it against the stage's declared approver set (SSM). The
+    // snapshot itself runs IN the Lambda, before the DDL. --confirm always.
+    let authorityVerdict: AuthorityVerdict | undefined;
+    if (plan.destructive > 0) {
+      const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
+      if (flags.confirm !== 'true') {
+        fail(`This plan is DESTRUCTIVE — ${plan.destructive} statement(s) lose data (${shape}). Explicit confirmation is required, always: re-run with --confirm.`);
+        process.exit(1);
+      }
+      step(`Destructive authority: checking the approver set for stage ${flags.stage}...`);
+      const { parseAppName } = await import('../discover.js');
+      const appName = await parseAppName();
+      const approvers = await readApproverParam(region, appName, flags.stage);
+      const identity = approvers === null ? null : await resolveCallerIdentity(region);
+      authorityVerdict = checkDestructiveAuthority({ approvers, identity });
+      if (authorityVerdict.ok && authorityVerdict.reason === 'approved') {
+        info(`authority: ${identity} is a declared approver.`);
+      } else if (authorityVerdict.ok) {
+        warn('authority: no approver set declared for this stage — proceeding on ceremony alone. Declare one: everystack db:approvers --set <arn-or-name,...> --stage ' + flags.stage);
+      }
+      // A refusal is enforced + recorded server-side; reportApplyResult renders it.
     }
-  }
-
-  if (plan.destructive > 0 && options.beforeDestructive) {
-    await options.beforeDestructive();
-  }
-
-  const result = await applyGeneratedStatements(runner, plan.statements, {
-    actor: options.actor,
-    gitRef: options.gitRef ?? plan.gitRef,
-    planRef: planHash(plan),
-    fromFingerprint: live,
-    now: options.now,
-  });
 
-  const after = await introspectSchema(runner);
-  const afterAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
-  const landed = fingerprintLive(after, afterAuthz).hash;
-  if (result.logId !== undefined) {
-    await runner(renderSchemaLogFingerprintUpdate(result.logId, landed));
-  }
-
-  if (landed !== plan.toFingerprint) {
-    return {
-      status: 'verify-failed',
-      liveFingerprint: landed,
-      reason: `applied, but the target landed on ${landed.slice(0, 12)} — the plan predicted ${plan.toFingerprint.slice(0, 12)}. Investigate before touching this database again (db:fingerprint, db:generate).`,
-      ...(result.logId !== undefined ? { logId: result.logId } : {}),
-    };
+    step('Applying in the ops Lambda (credential-free — the operator never holds a database URL)...');
+    const result: any = await invokeAction(region, fn, 'db:apply', {
+      plan,
+      actor: process.env.USER ?? null,
+      gitRef: currentGitRef() ?? plan.gitRef,
+      descentVerdict,
+      ...(authorityVerdict ? { authorityVerdict } : {}),
+      stage: flags.stage,
+    });
+    if (result?.error) {
+      fail(`Apply failed: ${result.error}`);
+      process.exit(1);
+    }
+    if (result?.snapshotId) {
+      info(`snapshot on record: ${result.snapshotId} — restore with db:restore --from ${result.snapshotId} --confirm.`);
+    }
+    reportApplyResult(result as ApplyPlanResult, plan);
+  } catch (err: any) {
+    fail(`Apply failed: ${err.message}`);
+    process.exit(1);
   }
-  return {
-    status: 'applied',
-    liveFingerprint: landed,
-    ...(result.logId !== undefined ? { logId: result.logId } : {}),
-  };
 }
 
-// ---------------------------------------------------------------------------
-// The CLI shell.
-// ---------------------------------------------------------------------------
-
 export async function dbApplyCommand(flags: Record<string, string>): Promise<void> {
   const planPath = flags.plan;
   if (!planPath) {
@@ -213,10 +223,6 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     fail(err.message);
     process.exit(1);
   }
-  if (dbSource.kind !== 'url') {
-    fail('db:apply writes — it needs a direct connection (--database-url or DATABASE_URL).');
-    process.exit(1);
-  }
 
   // The fast-forward rule's force ceremony (design decision 9): explicit
   // (--force-descent), snapshotted (its value NAMES the snapshot you took),
@@ -233,6 +239,13 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     }
   }
 
+  // Deployed stage, no direct URL: the write runs in the ops Lambda — the
+  // operator never holds a database URL. --database-url stays local-only.
+  if (dbSource.kind === 'stage') {
+    await applyPlanViaStage(plan, flags, forceDescent);
+    return;
+  }
+
   // Losing data should be hard (decision 11): a destructive plan applies
   // only confirmed (--confirm, always), snapshotted (automatic with --stage,
   // named over a bare connection), and — when the stage declares an approver
@@ -279,7 +292,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     }
   }
 
-  step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+  step(connectingVia(dbSource));
   const { runner, end } = await createUrlRunner(dbSource.url);
 
   try {
@@ -315,30 +328,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       } : {}),
     });
 
-    switch (result.status) {
-      case 'already-applied':
-        success(`Already at ${plan.toFingerprint.slice(0, 12)} — nothing to do (idempotent re-apply).`);
-        break;
-      case 'refused':
-        fail(`REFUSED: ${result.reason}`);
-        process.exit(1);
-        break;
-      case 'descent-refused':
-        fail(`REFUSED (fast-forward rule): ${result.reason}`);
-        process.exit(1);
-        break;
-      case 'authority-refused':
-        fail(`REFUSED (destructive authority): ${result.reason}`);
-        process.exit(1);
-        break;
-      case 'verify-failed':
-        fail(`Verify FAILED: ${result.reason}`);
-        process.exit(1);
-        break;
-      case 'applied':
-        success(`Applied and verified — the target is at ${result.liveFingerprint.slice(0, 12)}, exactly as the plan predicted. Recorded in everystack.schema_log (plan_ref ${planHash(plan).slice(0, 12)}).`);
-        break;
-    }
+    reportApplyResult(result, plan);
   } catch (err: any) {
     fail(`Apply failed and rolled back: ${err.message}`);
     process.exit(1);

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

@@ -27,7 +27,7 @@ import {
   type BackfillPlan,
 } from '../backfill.js';
 import { currentGitRef } from '../state-apply.js';
-import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { readSqlDirIfPresent } from './db-sync.js';
 import { step, success, fail, info, warn } from '../output.js';
 
@@ -69,7 +69,7 @@ export async function dbBackfillCommand(flags: Record<string, string>): Promise<
     process.exit(1);
   }
 
-  step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+  step(connectingVia(dbSource));
   const { runner, end } = await createUrlRunner(dbSource.url);
   try {
     const opts = { actor: process.env.USER ?? null, gitRef: currentGitRef() };

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

@@ -63,6 +63,22 @@ export async function dbBackupProbeCommand(flags: Record<string, string>): Promi
   }
 }
 
+/**
+ * Interpret a `db:backup:probe` result into a fail-clean remedy, or `null` when a dump is safe to
+ * run. Pre-flighting this before the dump turns a missing or version-incompatible pg_dump layer
+ * into a one-line remedy instead of a cryptic runtime crash mid-dump.
+ */
+export function pgDumpPreflightError(probe: any): string | null {
+  if (!probe || probe.error) {
+    const detail = probe?.error ?? 'the pg_dump layer probe returned no result';
+    return `${detail}\nBuild + publish the layer with scripts/build-pgdump-layer.sh, export PGDUMP_LAYER_ARN, then redeploy.`;
+  }
+  if (probe.compatible === false) {
+    return `pg_dump ${probe.pgDump ?? '(unknown)'} (major ${probe.pgDumpMajor}) is older than the server (major ${probe.serverMajor}) — it will refuse to dump (no bypass exists). Rebuild the layer with pg_dump >= ${probe.serverMajor}.`;
+  }
+  return null;
+}
+
 /** db:backup — pg_dump the stage's DB to S3 (runs in the ops Lambda). Prints the new backup id. */
 export async function dbBackupCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
@@ -75,6 +91,24 @@ export async function dbBackupCommand(flags: Record<string, string>): Promise<vo
   }
 
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+
+  // Pre-flight the pg_dump layer before the dump — a missing/incompatible layer becomes a one-line
+  // remedy here instead of crashing the runtime mid-dump (the probe returns a clean error, never a
+  // crash, when the layer is absent).
+  step('Checking the pg_dump layer...');
+  let probe: any;
+  try {
+    probe = await invokeAction(config.region, opsFunction(config), 'db:backup:probe', {});
+  } catch (err: any) {
+    fail(`Backup pre-flight failed: ${err.message}`);
+    process.exit(1);
+  }
+  const preflightError = pgDumpPreflightError(probe);
+  if (preflightError) {
+    fail(preflightError);
+    process.exit(1);
+  }
+
   step('Running pg_dump → S3 (this may take a while for large databases)...');
 
   let result: any;

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

@@ -4,7 +4,7 @@
  * decision 14).
  *
  *   db:template:refresh [--database-url <url>] [--models <barrel>]
- *                       [--sql-dir db/sql] [--seed "<cmd>"] [--no-seed]
+ *                       [--seed "<cmd>"] [--no-seed]
  *   db:branch                       # mint (or find) the current branch's DB
  *   db:branch --list                # every branch DB, mapped to its branch
  *   db:branch --drop --confirm      # drop the current branch's DB
@@ -39,7 +39,7 @@ import { currentGitRef } from '../state-apply.js';
 import { fingerprintModels } from '../schema-fingerprint.js';
 import { resolveDbSource, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
-import { readSqlDirIfPresent } from './db-sync.js';
+import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import { loadModels } from './db-generate.js';
 import { step, success, fail, info, warn } from '../output.js';
 
@@ -92,7 +92,30 @@ export async function dbTemplateRefreshCommand(flags: Record<string, string>): P
     fail(err.message);
     process.exit(1);
   }
-  const sources = await readSqlDirIfPresent(flags['sql-dir'] || 'db/sql');
+  // B7 tombstone — db/sql is retired and no longer read.
+  try {
+    if (flags['sql-dir']) {
+      fail(await retiredSqlDirFlagRefusal(flags['sql-dir']));
+      process.exit(1);
+    }
+    const retired = await retiredSqlDirAnywhere(flags.models);
+    if (retired) {
+      fail(retired);
+      process.exit(1);
+    }
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  // The declared derived layer + sequences — branch/template DBs carry the SAME stream
+  // every other verb deploys, or a minted branch is silently missing its compute.
+  let declaredDb: DeclaredDerived | null = null;
+  try {
+    declaredDb = await loadDeclaredDerived(flags.models);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
 
   let seedCommand: string | null = null;
   if (flags['no-seed'] === 'true') {
@@ -109,7 +132,8 @@ export async function dbTemplateRefreshCommand(flags: Record<string, string>): P
   step(`Rebuilding ${template} from the declared state (drop → create → sync both layers → seed)...`);
   try {
     const result = await executeTemplateRefresh(url, models, {
-      sources,
+      declared: declaredDb?.objects,
+      sequences: declaredDb?.sequences,
       actor: process.env.USER ?? null,
       gitRef: currentGitRef(),
       seed: seedCommand === null ? null : (templateUrl) => {