@everystack/cli 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "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-snapshot.ts

@@ -23,7 +23,9 @@ function resolveInstanceId(config: CliConfig, flags: Record<string, string>): st
   if (!id || id === 'placeholder') {
     fail(
       'No RDS instance id available. db:snapshot needs an RDS instance.\n' +
-      '  - If your DB is RDS: redeploy so the `databaseInstanceId` output is present, or pass --instance <id>.\n' +
+      '  - If your DB is RDS: add `databaseInstanceId: database.id` to the outputs return block in\n' +
+      '    sst.config.ts and redeploy (run db:snapshot from the app directory so .sst/outputs.json is\n' +
+      '    readable), or pass --instance <id>.\n' +
       '  - If your DB is not RDS (Aurora, a container, self-hosted): use `everystack db:backup` for a portable logical backup.',
     );
     process.exit(1);

package/src/cli/commands/db.ts

@@ -292,13 +292,19 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   for (const warning of plan.warnings) info(`  ⚠ ${warning}`);
   console.log('');
   info('Finish the wiring in sst.config.ts (one-time):');
-  info('  API:  declare `new sst.Secret("DatabaseUrl")` and link it to the Api function; remove the');
-  info('        raw Postgres component from the Api link (keep it on the ops/worker functions).');
+  info('  API — PRECONDITION: your handler must escalate per request (pgSettings + SET ROLE /');
+  info('        withRole). The authenticator holds no privileges of its own (NOINHERIT); a handler');
+  info('        that never escalates cannot see the schema — every endpoint fails "relation does');
+  info('        not exist". If unsure, do NOT flip the API yet.');
+  info('        Flip in TWO deploys: (1) declare `new sst.Secret("DatabaseUrl")` and link it to the');
+  info('        Api function, KEEPING the raw Postgres component linked (the explicit secret already');
+  info('        outranks it; the component is your instant rollback). Verify with real requests +');
+  info(`        db:doctor. (2) Then remove the raw Postgres component from the Api link (keep it on`);
+  info('        the ops/worker functions) and redeploy.');
   if (result.adminRole) {
     info('  Ops:  declare `new sst.Secret("AdminDatabaseUrl", "")` and link it to the Ops function —');
     info(`        operator tasks then run as ${result.adminRole}, not the Postgres master.`);
   }
-  info('Then redeploy.');
   info(`Verify:  everystack db:doctor --stage ${flags.stage}`);
 }
 

package/src/cli/commands/deploy.ts

@@ -22,14 +22,31 @@ export function buildDeployArgs(flags: Record<string, string>): string[] {
   return ['sst', 'deploy', '--stage', stage];
 }
 
+/**
+ * The environment the sst child receives: the FULL ambient environment plus color.
+ * Pinned as an explicit, tested contract because a consumer observed PGDUMP_LAYER_ARN
+ * reaching sst when invoked directly but not through this wrapper — sst.config.ts
+ * conditionals like `process.env.PGDUMP_LAYER_ARN ? { layers: [...] } : {}` silently
+ * collapse when a variable goes missing, and the deploy still exits green.
+ */
+export function deployEnv(base: Record<string, string | undefined>): Record<string, string | undefined> {
+  return { ...base, FORCE_COLOR: '1' };
+}
+
 export async function deployCommand(flags: Record<string, string>): Promise<void> {
   const stage = flags.stage || 'dev';
   const args = buildDeployArgs(flags);
 
   step(`Deploying stage "${stage}"...`);
+  // Say what the wrapper sees: an sst.config.ts conditional on an env var collapses
+  // SILENTLY when the var is missing, and the deploy still exits green — the operator
+  // must be able to tell "the wrapper never saw it" from "sst ignored it" at a glance.
+  if (process.env.PGDUMP_LAYER_ARN) {
+    info(`pg_dump layer: PGDUMP_LAYER_ARN is set → forwarded to sst (${process.env.PGDUMP_LAYER_ARN})`);
+  }
   await new Promise<void>((resolve) => {
     // `npx` resolves the consumer's local sst (the same way the export step runs expo).
-    const child = spawn('npx', args, { stdio: 'inherit', env: { ...process.env, FORCE_COLOR: '1' } });
+    const child = spawn('npx', args, { stdio: 'inherit', env: deployEnv(process.env) as NodeJS.ProcessEnv });
     child.on('close', (code) => {
       if (code === 0) {
         resolve();
@@ -65,5 +82,8 @@ export async function deployCommand(flags: Record<string, string>): Promise<void
     info(`Skipped the post-deploy probe: ${err?.message ?? err}`);
   }
 
-  info('Next: `everystack db:migrate --stage ' + stage + '` to apply migrations, `everystack update` to publish the app bundle.');
+  // The 0.4 flow: schema changes ride db:plan → db:apply. Migration-based apps still have
+  // db:migrate, but the copy-paste hint must advertise the canonical path — this exact
+  // line got copied into consumer runbooks with the retired verb.
+  info('Next: schema changes via `everystack db:plan --stage ' + stage + '` → `db:apply`; `everystack update` to publish the app bundle.');
 }

package/src/cli/config.ts

@@ -52,6 +52,35 @@ interface SstOutputs {
   backupsBucket?: string;
 }
 
+/**
+ * Merge deploy-stable fields from a local .sst/outputs.json into a discovered config.
+ * Discovery finds live resources (functions, buckets) but cannot see plain stack outputs
+ * like `databaseInstanceId` — a consumer's fresh deploy DID add the output and
+ * `db:snapshot --stage` still failed, because the discovery path never carried it.
+ * Only fields that are stable across deploys are merged (an instance id never rotates
+ * the way a Lambda hash does), so a stale outputs file cannot poison the live discovery.
+ */
+export function enrichConfigFromOutputs(
+  config: CliConfig,
+  outputs: Partial<SstOutputs> | null,
+): CliConfig {
+  if (!outputs) return config;
+  return {
+    ...config,
+    ...(config.databaseInstanceId ? {} : outputs.databaseInstanceId ? { databaseInstanceId: outputs.databaseInstanceId } : {}),
+  };
+}
+
+/** Best-effort read of the local .sst/outputs.json; null when absent/unreadable. */
+async function readLocalOutputs(): Promise<Partial<SstOutputs> | null> {
+  try {
+    const raw = await fs.readFile(path.resolve('.sst', 'outputs.json'), 'utf8');
+    return JSON.parse(raw) as Partial<SstOutputs>;
+  } catch {
+    return null;
+  }
+}
+
 export async function resolveConfig(stage?: string): Promise<CliConfig> {
   const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || 'us-east-1';
 
@@ -66,7 +95,7 @@ export async function resolveConfig(stage?: string): Promise<CliConfig> {
 
     // Check cache first
     const cached = await getCachedConfig(stage);
-    if (cached) return cached;
+    if (cached) return enrichConfigFromOutputs(cached, await readLocalOutputs());
 
     step(`Discovering resources for stage "${stage}"...`);
     const appName = await parseAppName();
@@ -74,7 +103,7 @@ export async function resolveConfig(stage?: string): Promise<CliConfig> {
 
     // Cache for future fast lookups
     await setCachedConfig(stage, config);
-    return config;
+    return enrichConfigFromOutputs(config, await readLocalOutputs());
   }
 
   // Default: read .sst/outputs.json (unchanged behavior)

package/src/cli/deploy-probe.ts

@@ -99,6 +99,104 @@ async function probeFunction(region: string, functionName: string): Promise<Prob
   }
 }
 
+/** A minimal APIGW v2 GET event — what a Function URL delivers for a real request. */
+export function syntheticGetEvent(path: string, queryString = ''): {
+  version: string;
+  routeKey: string;
+  rawPath: string;
+  rawQueryString: string;
+  headers: Record<string, string>;
+  requestContext: { http: { method: string; path: string; protocol: string; sourceIp: string; userAgent: string } };
+  isBase64Encoded: boolean;
+} {
+  return {
+    version: '2.0',
+    routeKey: '$default',
+    rawPath: path,
+    rawQueryString: queryString,
+    headers: { 'user-agent': 'everystack-deploy-probe' },
+    requestContext: {
+      http: { method: 'GET', path, protocol: 'HTTP/1.1', sourceIp: '127.0.0.1', userAgent: 'everystack-deploy-probe' },
+    },
+    isBase64Encoded: false,
+  };
+}
+
+/**
+ * Classify one table GET driven through the api function. `_health` proves BOOT; it
+ * touches no tables — a stage whose API role cannot see the schema (a NOINHERIT
+ * authenticator behind a handler that never escalates) boots fine and 500s on every
+ * real request. A consumer shipped exactly that dark site; this is the check that
+ * catches it at deploy time, with the failure named.
+ */
+export interface ReadProbeVerdict {
+  verdict: 'reads-ok' | 'auth-gated' | 'dark-site' | 'failed' | 'no-surface';
+  detail?: string;
+}
+
+export function classifyReadProbe(response: { statusCode?: number; body?: string }): ReadProbeVerdict {
+  const status = response.statusCode ?? 0;
+  if (status >= 200 && status < 300) return { verdict: 'reads-ok' };
+  if (status === 401 || status === 403) return { verdict: 'auth-gated' };
+  if (status === 404) return { verdict: 'no-surface' };
+  const body = response.body ?? '';
+  if (status >= 500 && /relation .* does not exist/i.test(body)) {
+    return {
+      verdict: 'dark-site',
+      detail:
+        'the API role cannot see the schema — the handler never escalates. The authenticator holds no '
+        + 'privileges of its own (NOINHERIT); the handler must SET ROLE per request (pgSettings + withRole). '
+        + `Raw response: ${body}`,
+    };
+  }
+  return { verdict: 'failed', detail: body || `HTTP ${status}` };
+}
+
+/** Invoke the api function with a synthetic HTTP GET; null when the invoke itself failed. */
+async function invokeHttpGet(
+  region: string,
+  functionName: string,
+  path: string,
+  queryString = '',
+): Promise<{ statusCode?: number; body?: string } | null> {
+  try {
+    const { LambdaClient, InvokeCommand } = await import('@aws-sdk/client-lambda');
+    const client = new LambdaClient({ region });
+    const response = await client.send(new InvokeCommand({
+      FunctionName: functionName,
+      Payload: new TextEncoder().encode(JSON.stringify(syntheticGetEvent(path, queryString))),
+    }));
+    if (response.FunctionError || !response.Payload) return null;
+    const parsed = JSON.parse(new TextDecoder().decode(response.Payload));
+    if (parsed && typeof parsed === 'object' && 'statusCode' in parsed) {
+      return { statusCode: parsed.statusCode, body: parsed.body };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Drive one real table read through the api function: GET / (the public table listing)
+ * names an exposed table, GET /<table>?limit=1 exercises role → schema → RLS. Best-effort:
+ * anything unprobeable stays neutral — only a positively classified failure is fatal.
+ */
+async function probeApiRead(region: string, functionName: string): Promise<ReadProbeVerdict | null> {
+  const listing = await invokeHttpGet(region, functionName, '/');
+  if (!listing || listing.statusCode !== 200 || !listing.body) return null;
+  let tables: string[];
+  try {
+    tables = (JSON.parse(listing.body) as { tables?: string[] }).tables ?? [];
+  } catch {
+    return null;
+  }
+  if (tables.length === 0) return null;
+  const read = await invokeHttpGet(region, functionName, `/${tables[0]}`, 'limit=1');
+  if (!read) return null;
+  return classifyReadProbe(read);
+}
+
 /**
  * Probe the stage's deployed functions and report. Returns whether deploy must fail: a function
  * that cannot boot (or answers unhealthy) is fatal; a probe that couldn't run is a warning.
@@ -137,6 +235,27 @@ export async function probeDeployedFunctions(
         info(`Could not probe ${target.label} function (${target.functionName}): ${result.detail}`);
         break;
     }
+
+    // Boot is necessary, not sufficient: drive one table read through the api function so a
+    // schema-invisible role (the dark-site shape) fails HERE, named, not on the first user.
+    if (target.label === 'api' && (result.verdict === 'healthy' || result.verdict === 'boot-ok')) {
+      const read = await probeApiRead(config.region, target.functionName);
+      if (read === null) {
+        // Nothing conclusive to probe (listing empty/unreadable) — stay neutral.
+      } else if (read.verdict === 'reads-ok') {
+        success('api read path OK (table read through the handler)');
+      } else if (read.verdict === 'auth-gated') {
+        info('api read path is auth-gated — boot verified, deeper read needs credentials');
+      } else if (read.verdict === 'no-surface') {
+        info('api exposes no tables to probe — skipped the read check');
+      } else if (read.verdict === 'dark-site') {
+        fatal = true;
+        fail(`api function is DARK: ${read.detail}`);
+      } else {
+        fatal = true;
+        fail(`api read probe failed: ${read.detail}`);
+      }
+    }
   }
   return { fatal };
 }

package/src/cli/index.ts

@@ -339,7 +339,7 @@ Usage:
   everystack deploy            [--stage <name>]  Deploy infrastructure (wraps sst deploy — no need to know SST)
   everystack update            --branch <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--skip-export]
   everystack update            --channel <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--skip-export]
-  everystack db:migrate        [--stage <name>]  Run database migrations on deployed Lambda
+  everystack db:migrate        [--stage <name>]  Run drizzle migrations (legacy — Models apps use db:plan → db:apply)
   everystack db:seed           [--stage <name>]  Seed database on deployed Lambda (dev only)
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
   everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)

package/src/cli/runbook/sections.ts

@@ -136,7 +136,12 @@ function deploy(r: ProjectReality): Block {
     '- `everystack channels list` — see the channels that exist.',
   ];
   if (r.hasDatabase) {
-    lines.push('', 'After a deploy that includes new migrations: `everystack db:migrate --stage <name>`.');
+    lines.push(
+      '',
+      r.migrationMode === 'everystack'
+        ? 'After a deploy, schema changes land via `everystack db:plan --stage <name>` → `db:apply`.'
+        : 'After a deploy that includes new migrations: `everystack db:migrate --stage <name>`.',
+    );
   }
   return gen('deploy', lines);
 }
@@ -222,7 +227,12 @@ function database(r: ProjectReality): Block {
     '## Database operations',
     '',
     ...flow,
-    '- `everystack db:migrate --stage <name>` — apply migrations on the deployed Lambda',
+    // db:migrate is the RETIRED verb for everystack-mode apps (plan → apply is the flow);
+    // advertising it here got copied into consumer runbooks verbatim. Migration-based
+    // apps still get it — it is their flow.
+    ...(r.migrationMode === 'everystack'
+      ? []
+      : ['- `everystack db:migrate --stage <name>` — apply migrations on the deployed Lambda']),
     '- `everystack db:seed --stage dev` — seed the database (dev only)',
     '- `everystack db:psql --stage dev` — psql into the stage database (credentials never exposed)',
     '- `everystack db:doctor` — verify the security posture (RLS, roles, search_path)',