@everystack/cli 0.4.88 → 0.4.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.88",
+  "version": "0.4.90",
   "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-apply.ts

@@ -266,7 +266,22 @@ async function runCatchUp(
       onStart: () => step('Catching the functions, views and triggers up to the checkout...'),
       onRefusal,
     });
-    if (verbose && outcome.run) for (const text of buildReconcileReport(outcome.run.plan)) info(text);
+    if (outcome.run) {
+      if (verbose) {
+        for (const text of buildReconcileReport(outcome.run.plan)) info(text);
+      } else if (outcome.run.plan.needsBaseline.length > 0) {
+        // NOT gated behind --verbose. A first-contact match (an object that predates Models
+        // tracking) is silently SKIPPED here — the reconciler will not guess whether live
+        // matches source — so a catch-up that only ever prints its full report under --verbose
+        // reads as "nothing to do" while real brownfield objects are left permanently
+        // unverified. This is the exact silence a consumer's derived-layer incident traced back
+        // to: db:apply reported success on every deploy while these objects sat unreconciled.
+        warn(
+          `${outcome.run.plan.needsBaseline.length} derived object(s) skipped (never reconciled, so this catch-up cannot tell whether live matches source): ${outcome.run.plan.needsBaseline.join(', ')} — ` +
+          'run `everystack db:reconcile --baseline` to record trust once you have verified it matches, or `--rebuild` to force it from source. Does not fail this apply.',
+        );
+      }
+    }
     return { ok: true, statements: outcome.statements };
   } catch (err: any) {
     const cause = String(err?.message ?? err);

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

@@ -64,7 +64,10 @@ import { resolveConfig, opsFunction } from '../config';
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { lambdaQueryRunner, lambdaSessionRunner } from '../aws';
 import { loadModels } from './db-generate';
-import { loadDeclaredDerived } from '../declared-derived';
+import { loadDeclaredDerived, type DeclaredDerived } from '../declared-derived';
+import { introspectDerived } from '../derived-introspect';
+import { planReconcile } from '../derived-plan';
+import { checkFails, buildReconcileReport } from './db-reconcile';
 import { governedRoleSet, ungovernedGrants } from '../authz-reconcile';
 import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline';
 import { alterTypeStatementTargets, findAlterTypeDependents, renderAlterTypeRefusal } from '../alter-type-dependents';
@@ -269,10 +272,13 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     // The modules' extensions ride the same read. Without them the plan omits every
     // CREATE EXTENSION the target lacks, and the apply fails on a type the plan promised.
     let declaredExtensions: string[] = [];
+    // Kept for the derived-layer visibility check below — this IS the declared derived layer
+    // (functions/views/matviews/triggers), read once and reused rather than loaded twice.
+    let declaredDerived: DeclaredDerived | null = null;
     try {
-      const declared = await loadDeclaredDerived(flags.models);
-      declaredGovernedRoles = declared?.governedRoles ?? [];
-      declaredExtensions = declared?.extensions ?? [];
+      declaredDerived = await loadDeclaredDerived(flags.models);
+      declaredGovernedRoles = declaredDerived?.governedRoles ?? [];
+      declaredExtensions = declaredDerived?.extensions ?? [];
     } catch {
       // The barrel's own compose errors surface on the paths that need the derived layer;
       // a plan must not fail to mint because a module could not be read for this one field.
@@ -456,6 +462,33 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       }
     }
 
+    // DERIVED-LAYER VISIBILITY — db:apply ALWAYS reconciles functions/views/matviews/triggers
+    // against the models, whether or not a --plan is passed; the edge this command mints never
+    // covers that layer. Without this, an empty table/column/grant edge reads as "the target
+    // matches the checkout" even when a function body changed underneath it — an operator who
+    // trusts an empty plan never learns db:apply still has work to do. Read-only: the same pure
+    // planReconcile() that backs `db:reconcile --check`, applied to nothing here — advisory
+    // only, like the FK-orphan and backfill checks above, so it can go stale between mint and
+    // apply without corrupting the plan file (see the file header's rationale for why nothing
+    // read-time-only belongs in the artifact).
+    if (declaredDerived) {
+      try {
+        const liveDerived = await introspectDerived(session);
+        const derivedPlan = planReconcile(
+          { objects: declaredDerived.objects, warnings: [] },
+          liveDerived,
+          { renamedTables: declaredDerived.renamedTables },
+        );
+        if (checkFails(derivedPlan)) {
+          warn('derived layer out of sync (functions/views/matviews/triggers) — this plan does not preview these, only tables/columns/grants:');
+          for (const line of buildReconcileReport(derivedPlan)) warn(`  ${line}`);
+          warn('db:apply always catches up the derived layer, --plan or not — run it to reconcile the above.');
+        }
+      } catch (err: any) {
+        warn(`derived-layer check could not run against this target (${err?.message ?? err}) — db:plan cannot say whether functions/views/matviews/triggers are in sync.`);
+      }
+    }
+
     await reportPipelineLastRun(runner);
 
     // THE DEFAULT REPORT — the only thing a reader sees when nothing is wrong.

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

@@ -61,6 +61,7 @@ import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws';
 import { modelContractPreflight } from '../model-wire-lane';
 import { MODEL_WIRE_CONTRACT, type ReconcileWirePayload } from '../../wire';
 import { step, success, fail, info, warn } from '../output';
+import { splitIdentityList } from '../utils/identity-list';
 
 // ---------------------------------------------------------------------------
 // The testable core.
@@ -622,7 +623,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
 
   // --only <a,b>: restrict the reconcile to the named identities (surgical). With --rebuild it is
   // the recovery path for a self-consistent-but-wrong provenance row (a mistaken --rebaseline).
-  const only = flags.only ? flags.only.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+  const only = flags.only ? splitIdentityList(flags.only) : undefined;
   // An empty/whitespace --only would silently degrade to a FULL reconcile — refuse it, since the
   // operator clearly meant to scope the run.
   if (flags.only !== undefined && !only?.length) {

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

@@ -30,6 +30,7 @@ import { resolveConfig, opsFunction } from '../config';
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { invokeAction } from '../aws';
 import { step, success, fail, info } from '../output';
+import { splitIdentityList } from '../utils/identity-list';
 
 export async function dbRefreshCommand(flags: Record<string, string>): Promise<void> {
   // The declared matviews, in dependency order (a dependent matview reads its parents' fresh rows).
@@ -40,7 +41,7 @@ export async function dbRefreshCommand(flags: Record<string, string>): Promise<v
     fail(err.message);
     process.exit(1);
   }
-  const only = flags.only ? flags.only.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+  const only = flags.only ? splitIdentityList(flags.only) : undefined;
   // --verify-nonempty: after refreshing, gate on populated-but-zero-rows matviews (the dark-panel
   // check) — credential-free, a scoped EXISTS on only what was just refreshed.
   const verifyNonempty = flags['verify-nonempty'] === 'true';

package/src/cli/commands/db.ts

@@ -5,7 +5,7 @@
  * No HTTP endpoints, no shared secrets — IAM is the authorization layer.
  */
 
-import { resolveConfig, opsFunction } from '../config';
+import { resolveConfig, opsFunction, probeUrl, type CliConfig } from '../config';
 import { invokeAction } from '../aws';
 import { step, success, fail, info, warn } from '../output';
 import { opsAdviceLines, IAM_ADVICE } from '../ops-advice';
@@ -613,6 +613,29 @@ export function parseUrlConnection(url: string): { host: string; port: string; d
   };
 }
 
+/**
+ * Rotation's non-blocking origin check. probeUrl falls back to siteUrl when there is no
+ * CDN_URL, so a stage without one still gets checked here instead of silently skipping the
+ * check (reading config.baseUrl directly did that). Exported for testing without invoking the
+ * whole rotation flow.
+ */
+export async function probeRotationOrigin(
+  config: Pick<CliConfig, 'baseUrl' | 'siteUrl'>,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: boolean; message: string } | undefined> {
+  const url = probeUrl(config);
+  if (!url) return undefined;
+  try {
+    const probe = `${url}?_probe=${Date.now()}`;
+    const res = await fetchImpl(probe, { redirect: 'follow' });
+    return res.ok
+      ? { ok: true, message: 'Origin responding.' }
+      : { ok: false, message: `Origin returned ${res.status}.` };
+  } catch (err: any) {
+    return { ok: false, message: `Origin probe failed: ${err.message}` };
+  }
+}
+
 /**
  * db:provision --rotate — swap the active A/B role for one or both credential slots.
  *
@@ -812,15 +835,10 @@ async function rotateCredentials(flags: Record<string, string>): Promise<void> {
     }
 
     // Origin HTTP check (non-blocking — the login probe is the real gate).
-    if (config.baseUrl) {
-      try {
-        const probe = `${config.baseUrl}?_probe=${Date.now()}`;
-        const res = await fetch(probe, { redirect: 'follow' });
-        if (res.ok) success('Origin responding.');
-        else warn(`Origin returned ${res.status}.`);
-      } catch (err: any) {
-        warn(`Origin probe failed: ${err.message}`);
-      }
+    const originResult = await probeRotationOrigin(config);
+    if (originResult) {
+      if (originResult.ok) success(originResult.message);
+      else warn(originResult.message);
     }
 
     // Retire old roles and drain sessions — using the roles recorded at

package/src/cli/commands/update.ts

@@ -129,13 +129,16 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
       warn(`Could not load SST secrets: ${err.message}`);
       info('Secrets may be unavailable during export. Provide env vars from the caller if needed.');
     }
+  }
 
-    // After the secrets step: a secret may supply HOST_URL.
-    const noHostUrl = await missingHostUrlError(flags.stage, { siteUrl: resolvedConfig?.siteUrl });
-    if (noHostUrl) {
-      fail(noHostUrl);
-      process.exit(1);
-    }
+  // Runs whether or not --stage was given: the harm (baking the app's default URL into a
+  // published channel's bundle) is the same either way, and the documented day-to-day flow is
+  // `update --channel production` with no --stage at all. A secret loaded above may supply
+  // HOST_URL, which is why this runs after that step rather than before it.
+  const noHostUrl = await missingHostUrlError(flags.stage, { siteUrl: resolvedConfig?.siteUrl });
+  if (noHostUrl) {
+    fail(noHostUrl);
+    process.exit(1);
   }
 
   const branch = flags.branch;

package/src/cli/discover-distribution.ts

@@ -11,6 +11,8 @@
  *   3. Comment contains the {app}-{stage}- prefix (legacy setups; a substring, so a last resort)
  */
 
+import { warn } from './output';
+
 export interface DistributionHints {
   /** Host of the discovered router URL, e.g. d111abc.cloudfront.net or a custom domain. */
   routerHost?: string;
@@ -112,6 +114,7 @@ export async function discoverDistributionMatch(
   // Tag pass — authoritative, so it runs before the Comment guess (a Comment substring can name
   // another app's stage). One call per distribution; SST tags every distribution it makes.
   if (hints.appName && hints.stage) {
+    let warnedOnTagReadFailure = false;
     for (const dist of items) {
       if (!dist.ARN) continue;
       try {
@@ -123,7 +126,13 @@ export async function discoverDistributionMatch(
           return toMatch(dist, 'tag');
         }
       } catch {
-        // Tag read denied or transient — keep scanning
+        // Tag read denied or transient — keep scanning, but say so once. Silent here means
+        // siteUrl quietly degrades to empty and distributionId falls to the Comment guess,
+        // with nothing in the output naming why.
+        if (!warnedOnTagReadFailure) {
+          warnedOnTagReadFailure = true;
+          warn('cloudfront:ListTagsForResource failed during distribution discovery — falling back to Comment matching, which is a substring guess.');
+        }
       }
     }
   }

package/src/cli/discover.ts

@@ -79,11 +79,45 @@ export async function parseAppName(configPath?: string): Promise<string> {
   return match[1];
 }
 
+/**
+ * The prefix SST's `prefixName` produces for a resource named `resourceName` (e.g.
+ * "ApiFunction"), given the budget `physicalName(maxLen, name)` leaves after its trailing
+ * "-<8-char hash>" (maxLen - 9). Ports the SST platform's naming.ts prefixName exactly
+ * (see apps/example/.sst/platform/src/components/naming.ts): the STAGE is never truncated,
+ * the APP segment is cut to fit once app+stage+name would overflow the budget, and dropped
+ * entirely if even stage+name does.
+ * A naive "<app>-<stage>-<resourceName>" false-negatives on long app/stage names because it
+ * skips this truncation.
+ *
+ * `maxLen` is the physicalName length ceiling for the AWS resource TYPE being matched — it is
+ * NOT the same for every resource. SST's own naming table (component.ts namingRules) pins:
+ * Lambda functions and CloudFront functions at 64 (`aws:lambda/function:Function`,
+ * `aws:cloudfront/function:Function`), S3 buckets at 63 (`aws:s3/bucket:Bucket`, one character
+ * tighter). Reusing the Lambda budget for a bucket needle silently mis-truncates the app segment
+ * by one character once truncation actually kicks in.
+ */
+function sstPhysicalNamePrefix(
+  appName: string,
+  stage: string,
+  resourceName: string,
+  maxLen: number,
+): string {
+  const max = maxLen - 9;
+  const nameLen = resourceName.length;
+  const stageLen = stage.length;
+  if (nameLen + 1 >= max) return resourceName.substring(0, max);
+  if (nameLen + stageLen + 2 >= max) {
+    return `${stage.substring(0, max - nameLen - 1)}-${resourceName}`;
+  }
+  return `${appName.substring(0, max - stageLen - nameLen - 2)}-${stage}-${resourceName}`;
+}
+
 /**
  * Does a deploy-written .sst/outputs.json describe this stage? The file is the last deploy on ANY
  * stage and has no stage field, but its apiFunctionName is `<app>-<stage>-ApiFunction-<hash>`
- * (the convention discovery matches on). `.sst/stage` is NOT evidence: it is SST's personal-stage
- * marker and can name a different stage than the last deploy. Unknown means no.
+ * (the convention discovery matches on) — with the app segment possibly truncated by SST's
+ * prefixName (see sstPhysicalNamePrefix). `.sst/stage` is NOT evidence: it is SST's
+ * personal-stage marker and can name a different stage than the last deploy. Unknown means no.
  */
 export function outputsDescribeStage(
   outputs: { apiFunctionName?: string } | null | undefined,
@@ -92,7 +126,8 @@ export function outputsDescribeStage(
 ): boolean {
   const fn = outputs?.apiFunctionName;
   if (!fn) return false;
-  return fn.toLowerCase().startsWith(`${appName}-${stage}-ApiFunction-`.toLowerCase());
+  const prefix = sstPhysicalNamePrefix(appName, stage, 'ApiFunction', 64);
+  return fn.toLowerCase().startsWith(`${prefix}-`.toLowerCase());
 }
 
 // ---------------------------------------------------------------------------
@@ -110,7 +145,8 @@ interface CfFunctionResult {
  */
 export async function discoverCfFunction(
   region: string,
-  prefix: string,
+  appName: string,
+  stage: string,
 ): Promise<CfFunctionResult> {
   const {
     CloudFrontClient,
@@ -119,7 +155,9 @@ export async function discoverCfFunction(
   } = await import('@aws-sdk/client-cloudfront');
 
   const client = new CloudFrontClient({ region });
-  const needle = `${prefix}RouterCloudfrontFunctionRequest-`.toLowerCase();
+  // CloudFront functions share Lambda's 64-char physicalName ceiling (naming.ts namingRules).
+  const prefix = sstPhysicalNamePrefix(appName, stage, 'RouterCloudfrontFunctionRequest', 64);
+  const needle = `${prefix}-`.toLowerCase();
 
   let marker: string | undefined;
   let matchName: string | undefined;
@@ -142,7 +180,7 @@ export async function discoverCfFunction(
 
   if (!matchName) {
     throw new Error(
-      `No CloudFront function found matching "${prefix}RouterCloudfrontFunctionRequest-*". ` +
+      `No CloudFront function found matching "${prefix}-*". ` +
         `Check that the stage has been deployed.`,
     );
   }
@@ -168,12 +206,14 @@ interface LambdaResult {
 }
 
 /**
- * Find a Lambda function by SST resource name prefix.
+ * Find a Lambda function by SST resource name, truncating the app segment the way SST's
+ * physicalName does (see sstPhysicalNamePrefix) so a long app name still matches.
  * Returns the function name if found, undefined if not.
  */
 export async function discoverFunction(
   region: string,
-  prefix: string,
+  appName: string,
+  stage: string,
   resourceName: string,
 ): Promise<string | undefined> {
   const { LambdaClient, ListFunctionsCommand } = await importOptionalAws(
@@ -181,7 +221,7 @@ export async function discoverFunction(
   );
 
   const client = new LambdaClient({ region });
-  const needle = `${prefix}${resourceName}`.toLowerCase();
+  const needle = sstPhysicalNamePrefix(appName, stage, resourceName, 64).toLowerCase();
 
   let marker: string | undefined;
 
@@ -207,13 +247,15 @@ export async function discoverFunction(
  */
 export async function discoverLambda(
   region: string,
-  prefix: string,
+  appName: string,
+  stage: string,
 ): Promise<LambdaResult> {
-  const matchName = await discoverFunction(region, prefix, 'ApiFunction');
+  const matchName = await discoverFunction(region, appName, stage, 'ApiFunction');
 
   if (!matchName) {
+    const prefix = sstPhysicalNamePrefix(appName, stage, 'ApiFunction', 64);
     throw new Error(
-      `No API Lambda found for prefix "${prefix}ApiFunction-*". ` +
+      `No API Lambda found for prefix "${prefix}-*". ` +
         `Check that the stage has been deployed and you have lambda:ListFunctions permission.`,
     );
   }
@@ -251,7 +293,8 @@ interface BucketsResult {
  */
 export async function discoverBuckets(
   region: string,
-  prefix: string,
+  appName: string,
+  stage: string,
 ): Promise<BucketsResult> {
   const { S3Client, ListBucketsCommand } = await importOptionalAws(
     () => import('@aws-sdk/client-s3'), '@aws-sdk/client-s3', 'resource discovery',
@@ -261,15 +304,20 @@ export async function discoverBuckets(
   const res = await client.send(new ListBucketsCommand({}));
   const buckets = res.Buckets || [];
 
-  const updatesNeedle = `${prefix}updatesbucket-`.toLowerCase();
-  const clientNeedle = `${prefix}clientbundlesbucket-`.toLowerCase();
+  // S3 buckets physicalName-cap at 63 chars (naming.ts namingRules: "aws:s3/bucket:Bucket"),
+  // one tighter than Lambda/CloudFront functions' 64 — reusing the function budget here would
+  // mis-truncate the app segment by a character once truncation actually kicks in.
+  const bucketPrefix = (resourceName: string) =>
+    sstPhysicalNamePrefix(appName, stage, resourceName, 63);
+  const updatesNeedle = `${bucketPrefix('UpdatesBucket')}-`.toLowerCase();
+  const clientNeedle = `${bucketPrefix('ClientBundlesBucket')}-`.toLowerCase();
   // Media bucket resource is named 'Media' (not 'MediaBucket'), so match both patterns
-  const mediaNeedle = `${prefix}media-`.toLowerCase();
-  const mediaBucketNeedle = `${prefix}mediabucket-`.toLowerCase();
+  const mediaNeedle = `${bucketPrefix('Media')}-`.toLowerCase();
+  const mediaBucketNeedle = `${bucketPrefix('MediaBucket')}-`.toLowerCase();
   // Backups bucket (db:backup/restore/backup:download). Discovered like every other bucket, so the
   // --stage path carries it — db:backup:download presigns CLIENT-side and needs the name locally
   // (db:backup/backups run server-side in the ops Lambda, which is why only download failed).
-  const backupsNeedle = `${prefix}backupsbucket-`.toLowerCase();
+  const backupsNeedle = `${bucketPrefix('BackupsBucket')}-`.toLowerCase();
 
   let updatesBucket: string | undefined;
   let clientBundlesBucket: string | undefined;
@@ -301,17 +349,19 @@ export async function discoverConfig(
   stage: string,
   region: string,
 ): Promise<DiscoveredConfig> {
+  // Naive, untruncated — only for discoverDistributionMatch (Comment/tag matching, not the
+  // physicalName convention the other discover* calls below now truncate correctly for).
   const prefix = `${appName}-${stage}-`;
 
   // Run CF function + Lambda + S3 discovery in parallel
   const [cfResult, lambdaResult, bucketsResult, opsFn, imageFn, workerFn] = await Promise.all([
-    discoverCfFunction(region, prefix),
-    discoverLambda(region, prefix),
-    discoverBuckets(region, prefix),
-    discoverFunction(region, prefix, 'OpsFunction').catch(() => undefined),
-    discoverFunction(region, prefix, 'ImageFunction').catch(() => undefined),
-    discoverFunction(region, prefix, 'WorkerFunction')
-      .then(fn => fn || discoverFunction(region, prefix, 'JobsSubscriber'))
+    discoverCfFunction(region, appName, stage),
+    discoverLambda(region, appName, stage),
+    discoverBuckets(region, appName, stage),
+    discoverFunction(region, appName, stage, 'OpsFunction').catch(() => undefined),
+    discoverFunction(region, appName, stage, 'ImageFunction').catch(() => undefined),
+    discoverFunction(region, appName, stage, 'WorkerFunction')
+      .then(fn => fn || discoverFunction(region, appName, stage, 'JobsSubscriber'))
       .catch(() => undefined),
   ]);
 
@@ -359,15 +409,17 @@ export async function discoverConfig(
         : '';
 
   if (!bucketsResult.updatesBucket) {
+    const bucketPrefix = sstPhysicalNamePrefix(appName, stage, 'UpdatesBucket', 63);
     throw new Error(
-      `Could not find S3 bucket "${prefix}updatesbucket-*". ` +
+      `Could not find S3 bucket "${bucketPrefix}-*". ` +
         `Check that stage "${stage}" has been deployed and you have s3:ListAllMyBuckets permission.`,
     );
   }
 
   if (!bucketsResult.clientBundlesBucket) {
+    const bucketPrefix = sstPhysicalNamePrefix(appName, stage, 'ClientBundlesBucket', 63);
     throw new Error(
-      `Could not find S3 bucket "${prefix}clientbundlesbucket-*". ` +
+      `Could not find S3 bucket "${bucketPrefix}-*". ` +
         `Check that stage "${stage}" has been deployed.`,
     );
   }

package/src/cli/host-url.ts

@@ -106,17 +106,30 @@ async function dotenvSetsHostUrl(
 }
 
 /**
- * Why `update --stage` must stop: nothing supplied a HOST_URL, so the OTA bundle would bake the
- * app's default (often localhost) as updates.url. Devices could then never fetch the recovery
- * publish. Undefined when HOST_URL is set (env or dotenv) or no stage was given. The message
- * names the ways out, including the stage's own site URL when discovery found one.
+ * Why `update` must stop: nothing supplied a HOST_URL, so the OTA bundle would bake the app's
+ * default (often localhost) as updates.url. Devices could then never fetch the recovery publish.
+ * Undefined when HOST_URL is set (env or dotenv). Applies with OR without --stage — the
+ * documented day-to-day flow (getting-started.md) is `update --channel production` with no
+ * --stage at all, so a missing HOST_URL there is the SAME harm, not a smaller one: whatever
+ * bakes into that channel's bundle ships to real devices just the same. Without a stage there is
+ * no auto-discovery to fall back on (no --stage means no CDN_URL lookup, no site URL to offer),
+ * so the message says so plainly instead of naming a stage that was never given.
  */
 export async function missingHostUrlError(
   stage: string | undefined,
   opts: { env?: Record<string, string | undefined>; cwd?: string; siteUrl?: string; resolveFrom?: string } = {},
 ): Promise<string | undefined> {
   const { env = process.env, cwd = process.cwd(), siteUrl, resolveFrom = cwd } = opts;
-  if (!stage || env.HOST_URL || (await dotenvSetsHostUrl(cwd, env, resolveFrom))) return undefined;
+  if (env.HOST_URL || (await dotenvSetsHostUrl(cwd, env, resolveFrom))) return undefined;
+  if (!stage) {
+    return (
+      'No HOST_URL is set (env, dotenv, or a stage\'s .sst/outputs.json), so the bundle would ship ' +
+      'the app\'s default URL as updates.url. Export HOST_URL=<the public URL devices should fetch ' +
+      'updates from>, or re-run with --stage <stage> to discover it from the deployed API function\'s ' +
+      'CDN_URL. (A HOST_URL in a dotenv file counts only when the project\'s Expo can be found to ' +
+      'read it the way `expo export` does.)'
+    );
+  }
   const offer = siteUrl ? ` This stage's site URL is ${siteUrl}; export it as HOST_URL if that is its public URL.` : '';
   return (
     `No HOST_URL for stage "${stage}", so the bundle would ship the app's default URL as updates.url.${offer} ` +

package/src/cli/index.ts

@@ -331,8 +331,8 @@ Usage:
   everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--verify-nonempty] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url refreshes over a local connection (dev); --stage <name> --direct resolves the stage's operator connection from its ops Lambda (credential never on argv) and refreshes CLI-side on an UNBOUNDED clock, for a matview set that exceeds the ops-Lambda 900s limit; --only refreshes a named subset (full identity or bare name); --verify-nonempty gates on populated-but-zero-rows matviews (the dark-panel check — a scoped EXISTS on just what was refreshed, so a promotion script gets the gate with no read authority) and FAILS naming any empty; --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--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 the declared descriptors, 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> [--direct] | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -] [--verbose]  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; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line) DEFAULT OUTPUT is the plain change list: '+' something is now true, '-' something is no longer true, and a '⚠ DESTRUCTIVE' line of its own when real data can be lost. Nothing else. --verbose restores the full internal report (edge summary, kind histogram, adoption and ownership reports, plan ref)
-  everystack db:apply          [--plan <file.plan.json>] [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--state-only] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>] [--verbose]  THE deploy verb — it does the WHOLE job: the reviewed plan (tables, columns, grants), then ALWAYS the functions, views, matviews and triggers, against the same target, reported as one receipt. With NO --plan it does the catch-up alone (this is what replaces running db:reconcile --apply by hand). --state-only skips the catch-up for the narrow case that wants the tables alone. If the plan lands and the catch-up then fails, the exit is non-zero and the message says the table/column changes are committed and safe and gives the rerun, which retries only the catch-up. 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 — it protects MERGED work: a commit on any ref that declares the live state and is not an ancestor of HEAD refuses by name, escaped git-natively by fetch + merge/rebase + re-plan; --attest-lineage-lost <sha> waives it ONLY for a declaring commit proven gone from every ref. When NO commit on ANY ref declares the live state — a database everystack never wrote, or one hand-edited since its last apply — the rule has nothing to protect: over a full, current clone that is PROVEN DRIFT, the reviewed plan is the ORIGIN, it applies with a loud warning, and the origin is recorded in schema_log so every later apply descends from it. A shallow, partial, or behind-remote clone, or a models tree that will not compile, is UNVERIFIABLE and refuses with a fetch/prune runbook), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there DEFAULT OUTPUT is the receipt: the same change lines back, then 'Applied N changes.'. --verbose restores the endpoint and plan-ref line
+  everystack db:plan           [--stage <name> [--direct] | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -] [--verbose]  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; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line) DEFAULT OUTPUT is the plain change list: '+' something is now true, '-' something is no longer true, and a '⚠ DESTRUCTIVE' line of its own when real data can be lost. Nothing else. --verbose restores the full internal report (edge summary, kind histogram, adoption and ownership reports, plan ref). The edge covers tables/columns/grants ONLY — it also reads (never mints) whether the DERIVED layer (functions/views/matviews/triggers) is out of sync with the target and warns if so, since db:apply always reconciles that layer regardless of --plan: an empty edge here does not mean the target fully matches the checkout
+  everystack db:apply          [--plan <file.plan.json>] [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--state-only] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>] [--verbose]  THE deploy verb — it does the WHOLE job: the reviewed plan (tables, columns, grants), then ALWAYS the functions, views, matviews and triggers, against the same target, reported as one receipt. With NO --plan it does the catch-up alone (this is what replaces running db:reconcile --apply by hand). --state-only skips the catch-up for the narrow case that wants the tables alone. A brownfield derived object the reconciler has never touched before (no provenance row) is SKIPPED, never guessed at, and that skip prints by default (not only under --verbose): 'N derived object(s) skipped ... db:reconcile --baseline' — a plain apply that only showed this under --verbose read as full success while such objects sat permanently unreconciled. If the plan lands and the catch-up then fails, the exit is non-zero and the message says the table/column changes are committed and safe and gives the rerun, which retries only the catch-up. 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 — it protects MERGED work: a commit on any ref that declares the live state and is not an ancestor of HEAD refuses by name, escaped git-natively by fetch + merge/rebase + re-plan; --attest-lineage-lost <sha> waives it ONLY for a declaring commit proven gone from every ref. When NO commit on ANY ref declares the live state — a database everystack never wrote, or one hand-edited since its last apply — the rule has nothing to protect: over a full, current clone that is PROVEN DRIFT, the reviewed plan is the ORIGIN, it applies with a loud warning, and the origin is recorded in schema_log so every later apply descends from it. A shallow, partial, or behind-remote clone, or a models tree that will not compile, is UNVERIFIABLE and refuses with a fetch/prune runbook), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there DEFAULT OUTPUT is the receipt: the same change lines back, then 'Applied N changes.'. --verbose restores the endpoint and plan-ref line
   everystack db:build          --database-url <url> [--models <barrel>]  Build a database FROM the models and KEEP it — the fresh-database bootstrap a deleted migration folder is replaced BY. Runs the same compose db:check proves buildability with (extensions -> schemas -> contract roles -> declared functions -> state -> derived layer), against a real target, then reports MATCH. Venue is EXPLICIT: --database-url only, never the ambient environment, because this writes a whole schema. REFUSES a database that already holds objects — evolving an existing one is db:sync (dev) or db:plan -> db:apply (a stage). Contract roles are created NOLOGIN if absent, and roles are cluster-level
   everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json] [--verbose]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), 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 DEFAULT OUTPUT is ONE line: 'Up to date.' or 'N changes pending. Run db:plan to review.'. --verbose restores every finding and the from-scratch build report
   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

package/src/cli/utils/identity-list.ts

@@ -0,0 +1,28 @@
+/**
+ * Splits a `--only a,b,c` flag value into identities.
+ *
+ * A naive `.split(',')` breaks a function identity like `auth.change_password(text,
+ * text)` into two garbage fragments — the argument list's own commas are not
+ * separators. This only treats a comma as a separator when it sits outside any
+ * parentheses, so `schema.fn(text, text)` survives as one identity.
+ */
+export function splitIdentityList(input: string): string[] {
+  const identities: string[] = [];
+  let depth = 0;
+  let current = '';
+
+  for (const ch of input) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth = Math.max(0, depth - 1);
+
+    if (ch === ',' && depth === 0) {
+      identities.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  identities.push(current.trim());
+
+  return identities.filter(Boolean);
+}