@everystack/cli 0.4.12 → 0.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

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

@@ -1,14 +1,24 @@
 /**
- * `everystack db:export --schema <name> --stage <n>` — the schema-scoped, fingerprint-stamped
- * artifact (canonical-sync gap B). pg_dump ONE schema → the stage's S3 artifact bucket, stamped
- * with the DECLARED schema fingerprint from the checkout, so db:swap can gate an incoming artifact
- * against the target's declared shape (declared-vs-declared: does the artifact and the stage agree
- * on the schema's shape). everystack owns the export so that fingerprint is one formula both sides.
+ * `everystack db:export --schema <name> [--stage <n> | --database-url <url>]` — the schema-scoped,
+ * fingerprint-stamped artifact (canonical-sync gap B). pg_dump ONE schema, stamped with the
+ * DECLARED schema fingerprint from the checkout, so db:swap can gate an incoming artifact against
+ * the target's declared shape (declared-vs-declared: does the artifact and the stage agree on the
+ * schema's shape). everystack owns the export so that fingerprint is one formula both sides.
  *
- * The dump runs in the ops Lambda (the DB is private); the CLI computes the fingerprint from the
- * models and invokes the action. Verification of the streaming path is a deploy smoke test.
+ * Two venues, mirroring db:swap:
+ * - `--stage` (default): the dump runs in the ops Lambda (the DB is private) → the stage's S3
+ *   artifact bucket, gzipped. Verification of the streaming path is a deploy smoke test.
+ * - `--database-url` (explicit flag only, never the env — the venue choice must be deliberate):
+ *   the CLI runs pg_dump itself against a reachable database and writes a plain `-Fc` `.dump`
+ *   plus the sibling `.meta.json` db:swap reads. This is the build-locally → publish → swap
+ *   on-ramp: a consumer pipeline shells this instead of hand-rolling pg_dump and duplicating
+ *   the fingerprint formula.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
 import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
 import { invokeAction } from '../aws.js';
@@ -17,11 +27,119 @@ import { resolveModelsPath } from '../models-path.js';
 import { loadModels } from './db-generate.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
 import { pgDumpPreflightError } from './db-backup.js';
+import { pgEnvFromUrl } from './db.js';
+import { utcStamp } from '../backup.js';
 import { step, success, fail, info } from '../output.js';
 
 const fmtBytes = (b?: number): string =>
   b == null ? '?' : b >= 1024 ** 3 ? `${(b / 1024 ** 3).toFixed(1)} GB` : b >= 1024 ** 2 ? `${(b / 1024 ** 2).toFixed(1)} MB` : `${(b / 1024).toFixed(0)} KB`;
 
+export type ExportVenue = { kind: 'local'; url: string } | { kind: 'stage'; stage: string | undefined };
+
+/**
+ * Which venue runs the dump. Local ONLY on an explicit `--database-url` — never the env, so a
+ * DATABASE_URL in the shell can't silently flip a stage export into a local one. Both flags at
+ * once is ambiguous and refused.
+ */
+export function resolveExportVenue(flags: Record<string, string>): ExportVenue {
+  const url = flags['database-url'];
+  if (url && flags.stage) {
+    throw new Error('db:export takes one venue: --database-url (dump a reachable database locally) OR --stage (dump the stage\'s private database in the ops Lambda) — not both.');
+  }
+  return url ? { kind: 'local', url } : { kind: 'stage', stage: flags.stage };
+}
+
+/**
+ * Where a local artifact lands. Mirrors the S3 scheme (`<stamp>-<shortId>`, meta as a sibling)
+ * with the schema in the file name since there is no bucket prefix; the id says `local` where
+ * the S3 id says the stage. Plain `.dump` (no gzip): db:swap's pg_restore reads the file as-is.
+ */
+export function localArtifactPaths(
+  schema: string,
+  now: Date,
+  shortId: string,
+  opts: { out?: string; outDir?: string } = {},
+): { dumpPath: string; metaPath: string; id: string } {
+  const stamp = utcStamp(now);
+  let dumpPath: string;
+  if (opts.out) {
+    if (!opts.out.endsWith('.dump')) {
+      throw new Error(`--out must end in .dump (got ${opts.out}) — db:swap resolves the sibling .meta.json from that suffix.`);
+    }
+    dumpPath = opts.out;
+  } else {
+    dumpPath = path.join(opts.outDir ?? '.', `${schema}-${stamp}-${shortId}.dump`);
+  }
+  return {
+    dumpPath,
+    metaPath: dumpPath.replace(/\.dump$/, '.meta.json'),
+    id: `${schema}/local/${stamp}-${shortId}`,
+  };
+}
+
+/** The meta record the swap gate reads — same shape as the S3 sidecar, `path` instead of `key`. */
+export function localArtifactMeta(opts: {
+  id: string;
+  schema: string;
+  createdAt: Date;
+  bytes: number;
+  path: string;
+  fingerprint: string;
+}): Record<string, unknown> {
+  return {
+    id: opts.id,
+    schema: opts.schema,
+    stage: 'local',
+    createdAt: opts.createdAt.toISOString(),
+    bytes: opts.bytes,
+    path: opts.path,
+    fingerprint: opts.fingerprint,
+  };
+}
+
+/** pg_dump args for the local venue — same dump shape as the ops venue, written straight to a file. */
+export function pgDumpLocalArgs(schema: string, dumpPath: string): string[] {
+  return ['-Fc', '--no-owner', '--no-privileges', '--no-comments', `--schema=${schema}`, '-f', dumpPath];
+}
+
+/**
+ * Run the local export: pg_dump one schema to a `-Fc` file, then write the meta sidecar. The
+ * connection rides PG* env (never argv). A failed dump removes the partial file — a truncated
+ * artifact never ships. Throws on failure; the command wraps it.
+ */
+export async function runLocalExport(opts: {
+  url: string;
+  schema: string;
+  fingerprint: string;
+  out?: string;
+  outDir?: string;
+}): Promise<{ id: string; dumpPath: string; metaPath: string; bytes: number }> {
+  const now = new Date();
+  const shortId = randomBytes(3).toString('hex');
+  const { dumpPath, metaPath, id } = localArtifactPaths(opts.schema, now, shortId, opts);
+
+  const env = { ...process.env, ...pgEnvFromUrl(opts.url) };
+  const child = spawn('pg_dump', pgDumpLocalArgs(opts.schema, dumpPath), { env, stdio: ['ignore', 'ignore', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      child.on('error', reject);
+      child.on('close', (code) =>
+        code === 0 ? resolve() : reject(new Error(`pg_dump exited ${code}: ${stderr.trim()}`)));
+    });
+  } catch (err) {
+    fs.rmSync(dumpPath, { force: true });
+    throw err;
+  }
+
+  const bytes = fs.statSync(dumpPath).size;
+  fs.writeFileSync(metaPath, JSON.stringify(localArtifactMeta({
+    id, schema: opts.schema, createdAt: now, bytes, path: dumpPath, fingerprint: opts.fingerprint,
+  }), null, 2));
+  return { id, dumpPath, metaPath, bytes };
+}
+
 export async function dbExportCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema;
   if (!schema) {
@@ -29,6 +147,14 @@ export async function dbExportCommand(flags: Record<string, string>): Promise<vo
     process.exit(1);
   }
 
+  let venue: ExportVenue;
+  try {
+    venue = resolveExportVenue(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
   // The DECLARED fingerprint of just this schema — the stamp the swap gate compares against.
   const modelsPath = resolveModelsPath(flags.models);
   let fingerprint: string;
@@ -43,10 +169,22 @@ export async function dbExportCommand(flags: Record<string, string>): Promise<vo
     process.exit(1);
   }
 
+  if (venue.kind === 'local') {
+    step(`Running pg_dump --schema=${schema} against --database-url...`);
+    try {
+      const res = await runLocalExport({ url: venue.url, schema, fingerprint, out: flags.out });
+      success(`Artifact ${res.dumpPath} (${fmtBytes(res.bytes)}, fingerprint ${fingerprint.slice(0, 12)}, meta ${res.metaPath}). Deploy with: everystack db:swap --schema ${schema} --from ${res.dumpPath} --database-url <target>`);
+    } catch (err: any) {
+      fail(`Export failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   step('Resolving deployed config...');
   let config: CliConfig;
   try {
-    config = await resolveConfig(flags.stage);
+    config = await resolveConfig(venue.stage);
   } catch (err: any) {
     fail(err.message);
     process.exit(1);
@@ -68,7 +206,7 @@ export async function dbExportCommand(flags: Record<string, string>): Promise<vo
   step(`Running pg_dump --schema=${schema} → S3 (this may take a while for large schemas)...`);
   let result: any;
   try {
-    result = await invokeAction(config.region, opsFunction(config), 'db:export', { schema, stage: flags.stage, fingerprint });
+    result = await invokeAction(config.region, opsFunction(config), 'db:export', { schema, stage: venue.stage, fingerprint });
   } catch (err: any) {
     fail(`Export failed: ${err.message}`);
     process.exit(1);

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

@@ -86,8 +86,11 @@ async function restoreIntoIncoming(url: string, artifactPath: string, schema: st
   ]);
 }
 
-/** Load the artifact's meta (fingerprint) from a sibling `.meta.json`, or fall back to a flag. */
-function readArtifactFingerprint(artifactPath: string, flag?: string): string | null {
+/**
+ * Load the artifact's meta (fingerprint) from a sibling `.meta.json`, or fall back to a flag.
+ * Exported so the db:export local venue can prove its meta round-trips into this gate.
+ */
+export function readArtifactFingerprint(artifactPath: string, flag?: string): string | null {
   if (flag) return flag;
   const metaPath = artifactPath.replace(/\.dump(\.gz)?$/, '.meta.json');
   try {

package/src/cli/index.ts

@@ -361,7 +361,7 @@ Usage:
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
-  everystack db:export         --schema <name> [--stage <name>] [--models <barrel>]  Schema-scoped pg_dump → S3 artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp)
+  everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
   everystack db:swap           --schema <name> --database-url <url> --from <artifact.dump> [--fingerprint <hash>]  Land a schema artifact atomically: fingerprint gate → restore into <schema>_incoming (COPY-safe rewrite) → one txn (drop+rename+recreate app→schema FKs, re-apply authz) → verify → drop retiring. Refresh-free; app.* untouched. DESTRUCTIVE (--stage/--direct ops venue rides stage-write-lanes)
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default