@everystack/cli 0.4.59 → 0.4.61

package/src/cli/stage-backup.ts

@@ -0,0 +1,229 @@
+/**
+ * The fingerprint sandwich around a stage backup — ONE implementation, three callers.
+ *
+ * A `db:backup` artifact carries a live base-schema fingerprint in its `.meta.json`, and the
+ * destructive-apply gate compares it against `plan.from`. That comparison is only meaningful if the
+ * fingerprint describes the schema the dump ACTUALLY holds. A dump taken across a concurrent
+ * migration holds a schema matching NEITHER endpoint, so its stamped fingerprint is a lie the gate
+ * would later trust. The sandwich reads the schema before the dump and again after it, and keeps
+ * the artifact only if the two agree.
+ *
+ * WHY THIS LIVES IN THE CLI: it used to run inside the task image, which imported
+ * `@everystack/cli/apply` to do it. The image is published and digest-pinned, so that froze a copy
+ * of the very CLI internals the gate depends on while the operator's checkout kept moving — a
+ * silent version skew on a safety-critical input. Here it runs from the operator's own checkout,
+ * the same code `db:apply` uses, so the two can never disagree about what a fingerprint means.
+ *
+ * WHY IT IS SHARED: `fingerprint` is a REQUIRED field on the backup job. Three commands dispatch
+ * backups (db:backup, db:fork, db:swap --snapshot logical), and when the field was added to one of
+ * them the other two silently broke. One implementation, one contract.
+ *
+ * The dispatch/poll/retract wiring is dependency-injected so the whole decision table is testable
+ * without AWS.
+ */
+
+import { invokeAction, lambdaSessionRunner } from './aws';
+import { pollTaskUntilStopped } from './task-poll';
+
+/** The verdict on a completed dump's fingerprint pair. Pure — the heart of the sandwich. */
+export type SandwichVerdict = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Did the schema hold still across the dump window?
+ *
+ * Agreement proves no DDL landed ANYWHERE between the two reads, so the fingerprint genuinely
+ * describes the dump's schema. Disagreement means the artifact is unusable as a safety net —
+ * better a refused backup than a false one.
+ */
+export function judgeSandwich(fpBefore: string, fpAfter: string): SandwichVerdict {
+  if (fpBefore === fpAfter) return { ok: true };
+  return {
+    ok: false,
+    reason:
+      `the schema changed during the dump (${fpBefore.slice(0, 12)} → ${fpAfter.slice(0, 12)}), `
+      + 'so the backup spans a migration and its fingerprint cannot be proven. Re-run when no migration is concurrent.',
+  };
+}
+
+export interface StageBackupDeps {
+  /** Read the live base-schema fingerprint. Called twice, bracketing the dump. */
+  readFingerprint: () => Promise<string>;
+  /** Dispatch `db:backup` with the operator-computed fingerprint. */
+  dispatch: (fingerprint: string) => Promise<{ runId: string; taskArn: string; id: string; key: string; warning?: string }>;
+  /**
+   * Wait for the task to stop; resolve ok, or a human reason it did not.
+   *
+   * `stampedFingerprint` is what the task reported writing into the artifact's `.meta.json`. It is
+   * the evidence the image honored the job — see the skew check in runStageBackup.
+   */
+  awaitTask: (ids: { runId: string; taskArn: string; id: string }) => Promise<{ ok: true; bytes?: number; stampedFingerprint?: string } | { ok: false; reason: string }>;
+  /** Delete a retracted artifact (the ops Lambda's db:backup:retract). */
+  retract: (key: string) => Promise<void>;
+  /** Progress output. Optional so tests stay quiet. */
+  onStep?: (message: string) => void;
+}
+
+export type StageBackupResult =
+  | { ok: true; id: string; key: string; bytes?: number; fingerprint: string; warning?: string }
+  | { ok: false; reason: string; retracted?: boolean; orphanKey?: string };
+
+/**
+ * Take a stage backup whose fingerprint is PROVEN stable, or refuse.
+ *
+ * Never throws for an expected failure — every outcome is a verdict the caller renders, so the
+ * three commands can word their own consequences ("the swap was NOT applied", "the fork stopped")
+ * without re-deriving the logic.
+ */
+export async function runStageBackup(deps: StageBackupDeps): Promise<StageBackupResult> {
+  const step = deps.onStep ?? (() => {});
+
+  step('Reading the live schema fingerprint (before the dump)...');
+  let fpBefore: string;
+  try {
+    fpBefore = await deps.readFingerprint();
+  } catch (err: any) {
+    // Refuse BEFORE dispatching: a dump whose fingerprint cannot be proven is not a safety net, and
+    // taking one anyway would burn the dump window and still leave nothing trustworthy.
+    return { ok: false, reason: `the schema fingerprint could not be read, so no backup was dispatched: ${err?.message ?? String(err)}` };
+  }
+
+  let dispatched: { runId: string; taskArn: string; id: string; key: string; warning?: string };
+  try {
+    dispatched = await deps.dispatch(fpBefore);
+  } catch (err: any) {
+    return { ok: false, reason: `the backup would not dispatch: ${err?.message ?? String(err)}` };
+  }
+
+  const finished = await deps.awaitTask(dispatched);
+  if (!finished.ok) return { ok: false, reason: finished.reason };
+
+  // Did the image actually USE the fingerprint we sent?
+  //
+  // This is the version-skew guard, and it deliberately does not rely on the image cooperating. An
+  // older task image ignores the job's `fingerprint` field entirely and computes its own, stamping
+  // the manifest with a value this CLI never produced — the exact stale-internals problem the
+  // operator-side move exists to remove, arriving through a pinned digest nobody re-published. A
+  // protocol handshake cannot catch that, because an old image does not know to check it. Comparing
+  // what came back against what we sent works against ANY image, old or new.
+  if (finished.stampedFingerprint !== undefined && finished.stampedFingerprint !== fpBefore) {
+    step('Retracting the backup (the task stamped a fingerprint we did not send)...');
+    const mismatch =
+      `the task stamped fingerprint ${finished.stampedFingerprint.slice(0, 12)} but the operator sent `
+      + `${fpBefore.slice(0, 12)} — the task image computed its own instead of using the job's, which means it `
+      + 'predates the operator-side fingerprint contract. Re-publish the Task image (or pin a newer digest).';
+    try {
+      await deps.retract(dispatched.key);
+      return { ok: false, reason: `${mismatch} Backup ${dispatched.id} was retracted.`, retracted: true };
+    } catch (err: any) {
+      return {
+        ok: false,
+        reason: `${mismatch} Backup ${dispatched.id} could ALSO not be retracted (${err?.message ?? String(err)}) — delete it by hand.`,
+        retracted: false,
+        orphanKey: dispatched.key,
+      };
+    }
+  }
+
+  step('Re-reading the schema fingerprint (after the dump)...');
+  let fpAfter: string;
+  try {
+    fpAfter = await deps.readFingerprint();
+  } catch (err: any) {
+    // The dump exists but is unproven. Do NOT retract — an unreadable fingerprint is not evidence
+    // the schema moved, and silently destroying a good backup is the worse error.
+    return {
+      ok: false,
+      reason: `the dump finished but the schema fingerprint could not be re-read (${err?.message ?? String(err)}), so backup ${dispatched.id} is NOT proven stable. Verify no migration ran during the dump, or re-run.`,
+      orphanKey: dispatched.key,
+    };
+  }
+
+  const verdict = judgeSandwich(fpBefore, fpAfter);
+  if (verdict.ok) {
+    // A task that reported no fingerprint at all is not the skew case above — the result-ledger
+    // write is explicitly best-effort, so a blip there loses the whole result row. Failing the
+    // backup for that would turn a cosmetic outage into a lost safety net, so say it and continue.
+    const unverified = finished.stampedFingerprint === undefined
+      ? 'the task did not report the fingerprint it stamped, so the artifact could not be verified against what the operator sent (the result-ledger write is best-effort)'
+      : undefined;
+    const warning = [dispatched.warning, unverified].filter(Boolean).join('; ') || undefined;
+    return { ok: true, id: dispatched.id, key: dispatched.key, bytes: finished.bytes, fingerprint: fpBefore, warning };
+  }
+
+  step('Retracting the backup (its fingerprint cannot be proven)...');
+  try {
+    await deps.retract(dispatched.key);
+    return { ok: false, reason: `${verdict.reason} Backup ${dispatched.id} was retracted.`, retracted: true };
+  } catch (err: any) {
+    // The artifact outlived the failure. Say so loudly with the key — an unproven backup left in
+    // the bucket is exactly what the destructive-apply gate must never pick up.
+    return {
+      ok: false,
+      reason: `${verdict.reason} Backup ${dispatched.id} could ALSO not be retracted (${err?.message ?? String(err)}) — delete it by hand so the destructive-apply gate never trusts it.`,
+      retracted: false,
+      orphanKey: dispatched.key,
+    };
+  }
+}
+
+/**
+ * Bind the sandwich to a real stage: the ops Lambda supplies the session the fingerprint is read
+ * over, dispatches the task, reports status, and performs the retraction — so the operator never
+ * holds a database URL or an S3 credential for any of it.
+ *
+ * The ONE place the wiring is written. A caller that hand-rolled this is how `fingerprint` became
+ * required in db:backup while db:fork and db:swap kept dispatching without it.
+ */
+export function stageBackupDeps(
+  config: { region: string },
+  opsFn: string,
+  stage: string | undefined,
+  hooks: { onStep?: (message: string) => void; onDispatch?: (d: { runId: string; taskArn: string; id: string; warning?: string }) => void } = {},
+): StageBackupDeps {
+  return {
+    // BOTH ends of the sandwich read over this ONE closure, so they cannot land on different lanes.
+    // That matters: a before-read over a direct session and an after-read over the two-invoke
+    // ops-Lambda blend could manufacture a false mismatch — or, worse, a false match. The symmetry
+    // is structural here rather than asserted; if a caller ever needs to override one end, it has to
+    // override both.
+    readFingerprint: async () => {
+      // The SAME helper db:apply's concurrency lock uses — that shared definition is the point.
+      const { liveBaseFingerprint } = await import('./apply-execute');
+      return (await liveBaseFingerprint(lambdaSessionRunner(config.region, opsFn))).hash;
+    },
+    dispatch: async (fingerprint) => {
+      const dispatched: any = await invokeAction(config.region, opsFn, 'db:backup', {
+        stage, actor: process.env.USER ?? null, fingerprint,
+      });
+      if (dispatched?.error) throw new Error(dispatched.error);
+      hooks.onDispatch?.(dispatched);
+      return dispatched;
+    },
+    awaitTask: async (ids) => {
+      const poll = await pollTaskUntilStopped(config.region, opsFn, { runId: ids.runId, taskArn: ids.taskArn });
+      if (poll.outcome === 'timeout') {
+        return { ok: false, reason: `the dump did not finish in time (last status: ${poll.lastStatus}). Run id ${ids.runId} — reconcile via ECS / everystack.task_log.` };
+      }
+      if (poll.outcome === 'error') {
+        return { ok: false, reason: `the task status could not be read (${poll.status.error}). The dump may still be running — reconcile run id ${ids.runId}.` };
+      }
+      if (poll.status.exitCode !== 0) {
+        return { ok: false, reason: `the dump exited ${poll.status.exitCode ?? 'unknown'}${poll.status.stoppedReason ? ` — ${poll.status.stoppedReason}` : ''}. Read the task logs (CloudWatch).` };
+      }
+      return {
+        ok: true,
+        bytes: poll.status.result?.bytes as number | undefined,
+        // What the task says it wrote into the artifact's .meta.json — the skew evidence.
+        stampedFingerprint: poll.status.result?.fingerprint as string | undefined,
+      };
+    },
+    retract: async (key) => {
+      // `stage` scopes what the action is willing to delete — it refuses any key outside this
+      // stage's backup prefix, so a retraction cannot reach an export artifact or a restore intent.
+      const res: any = await invokeAction(config.region, opsFn, 'db:backup:retract', { key, stage });
+      if (res?.error) throw new Error(res.error);
+      if (!res?.retracted) throw new Error(`the ops function did not confirm the retraction (returned ${JSON.stringify(res)})`);
+    },
+    onStep: hooks.onStep,
+  };
+}

package/src/cli/stage-read-consistency.ts

@@ -30,12 +30,12 @@
  * Lambda's db:apply action, for refusals that reach it.
  */
 
-import type { AuthzContract } from './authz-contract.js';
-import type { SessionRunner } from './session.js';
-import { introspectContract } from './authz-contract.js';
-import { introspectSchema, type SchemaSnapshot } from './schema-introspect.js';
-import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog.js';
-import { fingerprintLive } from './schema-fingerprint.js';
+import type { AuthzContract } from './authz-contract';
+import type { SessionRunner } from './session';
+import { introspectContract } from './authz-contract';
+import { introspectSchema, type SchemaSnapshot } from './schema-introspect';
+import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
+import { fingerprintLive } from './schema-fingerprint';
 
 /** One complete read of a target's base state, with its content address. */
 export interface StageReadPair {

package/src/cli/state-apply.ts

@@ -19,14 +19,14 @@
 
 import { execSync } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
-import { introspectContract, type AuthzContract, type QueryRunner } from './authz-contract.js';
-import type { SessionRunner } from './session.js';
-import { introspectSchema, type SchemaSnapshot } from './schema-introspect.js';
-import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog.js';
-import { generateMigrationSql, HELD_DROP_PREFIX } from './migration-generate.js';
+import { introspectContract, type AuthzContract, type QueryRunner } from './authz-contract';
+import type { SessionRunner } from './session';
+import { introspectSchema, type SchemaSnapshot } from './schema-introspect';
+import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
+import { generateMigrationSql, HELD_DROP_PREFIX } from './migration-generate';
 import type { SequenceDescriptor } from '@everystack/model';
-import { fingerprintLive } from './schema-fingerprint.js';
-import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply.js';
+import { fingerprintLive } from './schema-fingerprint';
+import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
 
 const NOTICE_PREFIX = '-- NOTICE';
 

package/src/cli/swap-execute.ts

@@ -20,9 +20,9 @@
  */
 
 import type { ModelDescriptor } from '@everystack/model';
-import type { QueryRunner } from './authz-contract.js';
-import type { SessionRunner } from './session.js';
-import { renderSchemaSwap, dropRetiringSql } from './schema-swap.js';
+import type { QueryRunner } from './authz-contract';
+import type { SessionRunner } from './session';
+import { renderSchemaSwap, dropRetiringSql } from './schema-swap';
 
 /** One validator's result. A `fatal` (default) failure rolls back; a `warn` failure is surfaced only. */
 export interface SwapCheck {

package/src/cli/swap-heartbeat.ts

@@ -39,7 +39,7 @@
  * waiting for a client that has stopped sending. `Lock` is never healthy here and reports at once.
  */
 
-import type { QueryRunner } from './authz-contract.js';
+import type { QueryRunner } from './authz-contract';
 
 /** One poll: what has landed, and what the loading backend is doing. */
 export interface HeartbeatSample {

package/src/cli/swap-pair.ts

@@ -50,13 +50,13 @@
  */
 
 import type { ModelDescriptor, DerivedDescriptor } from '@everystack/model';
-import { parseQualified } from './derived-source.js';
-import type { SourceObject } from './derived-source.js';
-import { rewriteStatementLineMulti, splitCodeSpans } from './schema-rewrite.js';
-import { parseGrantAttachments } from './derived-grants.js';
-import { derivedSearchPath, renderSetSearchPath, renderProvenanceUpsert, ENSURE_RECONCILER_SQL } from './derived-apply.js';
-import type { LiveObject } from './derived-introspect.js';
-import { compileTableContract } from './authz-compile.js';
+import { parseQualified } from './derived-source';
+import type { SourceObject } from './derived-source';
+import { rewriteStatementLineMulti, splitCodeSpans } from './schema-rewrite';
+import { parseGrantAttachments } from './derived-grants';
+import { derivedSearchPath, renderSetSearchPath, renderProvenanceUpsert, ENSURE_RECONCILER_SQL } from './derived-apply';
+import type { LiveObject } from './derived-introspect';
+import { compileTableContract } from './authz-compile';
 
 const SAFE_SCHEMA = /^[a-z_][a-z0-9_$]*$/;
 

package/src/cli/task-poll.ts

@@ -9,8 +9,8 @@
  * row + ECS both carry it). This owns the loop; the caller owns the success/failure messaging.
  */
 
-import { invokeAction } from './aws.js';
-import { info } from './output.js';
+import { invokeAction } from './aws';
+import { info } from './output';
 
 const POLL_INTERVAL_MS = 5_000;
 /** Backup/export/restore can run minutes on large databases — far longer than the probe's handshake. */

package/src/cli/ui-bloat.ts

@@ -29,7 +29,7 @@
  * mangled, pathless) — that is the local source auditor's job; this proves magnitude.
  */
 
-import type { AuditFinding } from './bundle-audit.js';
+import type { AuditFinding } from './bundle-audit';
 
 /** Thresholds for the design-bloat gates. All counts are occurrences in the bundle. */
 export interface UiBloatBudget {

package/src/cli/utils/secrets.ts

@@ -15,7 +15,7 @@
 
 import crypto from 'node:crypto';
 import { gunzipSync } from 'node:zlib';
-import { ensureOptionalAws } from '../aws.js';
+import { ensureOptionalAws } from '../aws';
 
 /**
  * Preflight the two optional-peer clients EVERY secrets operation needs (ssm for the passphrase,

package/src/exec.ts

@@ -8,13 +8,13 @@
  * URL on the operator's machine.
  */
 
-export { executeExec, assertNoTxnControl, execSha } from './cli/exec-execute.js';
-export type { ExecIntent, ExecOutcome, ExecuteExecOptions, ExecResult } from './cli/exec-execute.js';
+export { executeExec, assertNoTxnControl, execSha } from './cli/exec-execute';
+export type { ExecIntent, ExecOutcome, ExecuteExecOptions, ExecResult } from './cli/exec-execute';
 
-export { runExecInTx, SchemaChangedError, railStatements, EXEC_RAIL_DEFAULTS } from './cli/exec-run.js';
-export type { TxRunner, ExecStmtResult, ExecRails, RunExecInTxOptions } from './cli/exec-run.js';
+export { runExecInTx, SchemaChangedError, railStatements, EXEC_RAIL_DEFAULTS } from './cli/exec-run';
+export type { TxRunner, ExecStmtResult, ExecRails, RunExecInTxOptions } from './cli/exec-run';
 
-export { catalogDigestQuery } from './cli/exec-digest.js';
+export { catalogDigestQuery } from './cli/exec-digest';
 
-export { ENSURE_EXEC_LOG_SQL, renderExecIntentInsert, renderExecOutcomeUpdate } from './cli/exec-log.js';
-export type { ExecIntentRow, ExecOutcomeRow } from './cli/exec-log.js';
+export { ENSURE_EXEC_LOG_SQL, renderExecIntentInsert, renderExecOutcomeUpdate } from './cli/exec-log';
+export type { ExecIntentRow, ExecOutcomeRow } from './cli/exec-log';

package/src/reconcile.ts

@@ -7,5 +7,5 @@
  * --stage` needs no raw admin URL on the deployer's machine.
  */
 
-export { executeReconcile, buildReconcileReport } from './cli/commands/db-reconcile.js';
-export type { ReconcileRun, ExecuteOptions } from './cli/commands/db-reconcile.js';
+export { executeReconcile, buildReconcileReport } from './cli/commands/db-reconcile';
+export type { ReconcileRun, ExecuteOptions } from './cli/commands/db-reconcile';

package/src/refresh.ts

@@ -7,5 +7,5 @@
  * machine. The CLI ships the declared matview identities (dependency order); this refreshes them.
  */
 
-export { executeRefresh, matviewIdentities } from './cli/refresh-execute.js';
-export type { RefreshRun, RefreshRunner } from './cli/refresh-execute.js';
+export { executeRefresh, matviewIdentities } from './cli/refresh-execute';
+export type { RefreshRun, RefreshRunner } from './cli/refresh-execute';

package/src/sst.ts

@@ -11,7 +11,7 @@
  * @module
  */
 
-import { loadEnvConfig, type EnvConfig } from './env.js';
+import { loadEnvConfig, type EnvConfig } from './env';
 
 export { loadEnvConfig, type EnvConfig };