@everystack/cli 0.4.87 → 0.4.89

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.88] - 2026-09-21
+
+### Fixed
+
+- cache:purge probes a site's own hostname, and takes --host
+
 ## [0.4.87] - 2026-09-21
 
 ### BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.87",
+  "version": "0.4.89",
   "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/audit.ts

@@ -8,7 +8,7 @@
  * the heavier `audit:lighthouse` stay separate commands (run them explicitly).
  */
 
-import { resolveConfig, opsFunction, probeUrl } from '../config';
+import { resolveConfig, opsFunction, probeUrl, ambiguousSiteNote } from '../config';
 import { runBundleAudit, runBundleWeightAudit, reportBundleAudit } from './bundle';
 import { runUiAudit, reportUiAudit } from './ui-audit';
 import { checkRunbook } from './runbook';
@@ -33,6 +33,8 @@ export async function auditCommand(flags: Record<string, string>): Promise<void>
     fail('No router URL to audit. Pass --host or ensure the stage has a deployed URL.');
     process.exit(1);
   }
+  const ambiguous = flags.host ? undefined : ambiguousSiteNote(config);
+  if (ambiguous) info(ambiguous);
   info(`Region: ${config.region}, URL: ${base}`);
 
   let failures = 0;

package/src/cli/commands/bundle.ts

@@ -48,7 +48,7 @@ import {
   DEFAULT_UI_BLOAT_BUDGET,
   type UiBloatBudget,
 } from '../ui-bloat';
-import { resolveConfig, probeUrl } from '../config';
+import { resolveConfig, probeUrl, ambiguousSiteNote } from '../config';
 import { fail, info, step, success, warn } from '../output';
 
 // Expo Router web export puts client chunks under client/_expo/...; a plain
@@ -430,7 +430,10 @@ export async function bundleAuditCommand(
   let target = positional || flags.url;
   if (!target) {
     try {
-      target = probeUrl(await resolveConfig(flags.stage));
+      const stageConfig = await resolveConfig(flags.stage);
+      target = probeUrl(stageConfig);
+      const ambiguous = ambiguousSiteNote(stageConfig);
+      if (ambiguous) info(ambiguous);
     } catch (err: any) {
       fail(err.message);
       info('Pass a URL positionally or use --stage <name>.');

package/src/cli/commands/cache.ts

@@ -13,6 +13,9 @@ import { resolveConfig, probeUrl } from '../config';
 import { putKvsKey, createInvalidation, getDistributionStatus, getFromS3 } from '../aws';
 import { step, success, warn, fail, info } from '../output';
 
+/** One black-holed candidate must not stall the gate for the OS connect timeout. */
+const PROBE_TIMEOUT_MS = 10_000;
+
 const VALID_ORIGINS = ['api', 'media', 'web'] as const;
 type CacheOrigin = typeof VALID_ORIGINS[number];
 
@@ -34,10 +37,28 @@ export async function cachePurgeCommand(flags: Record<string, string>): Promise<
 
   const force = flags.force === 'true';
 
+  // What the gate probes: --host wins, else every discovered candidate (aliases before the domain).
+  let candidates: string[];
+  if (flags.host !== undefined) {
+    // parseFlags gives a value-less --host the string 'true'; '' is --host= . Neither is a host.
+    const host = flags.host === 'true' || flags.host === '' ? undefined : normalizeHost(flags.host);
+    if (!host) {
+      fail(`--host "${flags.host}" is not a hostname or URL.`);
+      info('Pass the site\'s public address, for example --host https://www.example.com');
+      process.exit(1);
+    }
+    if (host.startsWith('http://')) {
+      warn('--host is plaintext http://: anyone on the path can forge the release header and pass the gate.');
+    }
+    candidates = [host];
+  } else {
+    candidates = config.siteUrls?.length ? config.siteUrls : [probeUrl(config)].filter(Boolean);
+  }
+
   // Safety gate: verify the origin is serving the expected release and the distribution is stable.
   if (!force) {
     const channel = flags.channel || flags.stage || 'production';
-    const blocked = await preflight(config.region, probeUrl(config), config.updatesBucket, channel, config.distributionId);
+    const blocked = await preflight(config.region, candidates, config.updatesBucket, channel, config.distributionId);
     if (blocked) {
       fail(blocked);
       info('Pass --force to override this check.');
@@ -105,13 +126,24 @@ export async function cachePurgeCommand(flags: Record<string, string>): Promise<
   }
 }
 
+/** `www.example.com` or `https://www.example.com/` to `https://www.example.com`; undefined if it is not a host. */
+function normalizeHost(value: string): string | undefined {
+  const withScheme = /^https?:\/\//i.test(value) ? value : `https://${value}`;
+  try {
+    const u = new URL(withScheme);
+    return u.host && !/\s/.test(value) ? `${u.protocol}//${u.host}` : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Pre-purge safety checks. Returns an error message if blocked, null if clear.
  * @internal Exported for testing.
  */
 export async function preflight(
   region: string,
-  siteUrl: string,
+  siteUrl: string | readonly string[],
   updatesBucket: string,
   channel: string,
   distributionId?: string,
@@ -133,27 +165,55 @@ export async function preflight(
     return `Channel manifest for "${channel}" has no updateId.`;
   }
 
-  // 2. Probe the origin for the serving release.
-  if (!siteUrl) {
+  // 2. Probe for the serving release. The gate passes when ANY candidate serves the expected
+  // release: a CloudFront Function can gate by Host, so the raw cloudfront.net address may answer
+  // 403 while the site's own hostname answers 200 with x-everystack-release.
+  const urls = (typeof siteUrl === 'string' ? [siteUrl] : [...siteUrl]).filter(Boolean);
+  if (urls.length === 0) {
     return (
       'No site URL for this stage, so the origin cannot be probed. ' +
-      'Set CDN_URL on the API function and redeploy, or tag the distribution sst:app/sst:stage; ' +
-      'then re-run with --refresh to discover the stage again. Or pass --force to skip this check.'
+      'Pass --host <the site\'s public URL>, set CDN_URL on the API function and redeploy, or tag the distribution sst:app/sst:stage ' +
+      'and re-run with --refresh. Or pass --force to skip this check.'
     );
   }
-  try {
-    const probe = `${siteUrl}?_probe=${Date.now()}`;
-    const res = await fetch(probe, { redirect: 'follow' });
-    const serving = res.headers.get('x-everystack-release');
-    if (serving !== expectedUpdateId) {
+  const outcomes: Array<{ url: string; serving?: string | null; status?: number; error?: string }> = [];
+  let served = false;
+  for (const url of urls) {
+    try {
+      const res = await fetch(`${url}?_probe=${Date.now()}`, { redirect: 'follow', signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+      const serving = res.headers.get('x-everystack-release');
+      if (serving === expectedUpdateId) {
+        served = true;
+        break;
+      }
+      outcomes.push({ url, serving, status: res.status });
+    } catch (err: any) {
+      outcomes.push({ url, error: err.message });
+    }
+  }
+  if (!served) {
+    const want = expectedUpdateId.slice(0, 12);
+    const stale = 'Purging now would expose stale containers to uncached traffic.';
+    if (outcomes.length === 1) {
+      const o = outcomes[0];
+      if (o.error !== undefined) return `Could not reach origin at ${o.url}: ${o.error}`;
       return (
-        `Origin is serving release ${serving ? serving.slice(0, 12) + '...' : '(none)'} ` +
-        `but the channel pointer is ${expectedUpdateId.slice(0, 12)}.... Probed ${siteUrl}. ` +
-        `Purging now would expose stale containers to uncached traffic.`
+        `Origin is serving release ${o.serving ? o.serving.slice(0, 12) + '...' : '(none)'} ` +
+        `but the channel pointer is ${want}.... Probed ${o.url}. ${stale}` +
+        (o.serving ? '' : " If the site's public hostname differs, pass --host <url>.")
       );
     }
-  } catch (err: any) {
-    return `Could not reach origin at ${siteUrl}: ${err.message}`;
+    const tried = outcomes
+      .map((o) =>
+        o.error !== undefined
+          ? `${o.url} (unreachable: ${o.error})`
+          : `${o.url} (${o.serving ? 'release ' + o.serving.slice(0, 12) + '...' : `HTTP ${o.status}, no x-everystack-release header`})`,
+      )
+      .join(', ');
+    return (
+      `No probed URL serves release ${want}...: ${tried}. ${stale} ` +
+      "If the site's public hostname is not listed, pass --host <url>."
+    );
   }
 
   // 3. Check distribution status (if discoverable).

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/diag.ts

@@ -13,7 +13,7 @@
  *   everystack diag [url] --hydration  # Analyze SSR hydration issues
  */
 
-import { resolveConfig, probeUrl } from '../config';
+import { resolveConfig, probeUrl, ambiguousSiteNote } from '../config';
 import { getFromS3 } from '../aws';
 import { step, success, fail, info, warn } from '../output';
 import { analyzeHtml, generateHydrationReport } from '../hydration-analyzer';
@@ -54,6 +54,8 @@ export async function diagCommand(
   let url = positionalUrl;
   if (!url) {
     url = probeUrl(config);
+    const ambiguous = ambiguousSiteNote(config);
+    if (ambiguous) info(ambiguous);
     if (!url) {
       fail('No URL provided and no site URL for this stage. Pass a URL, set CDN_URL on the API function, or use --stage on a deployed stage.');
       process.exit(1);

package/src/cli/commands/lighthouse.ts

@@ -21,7 +21,7 @@ import {
   type ExtractedRun,
   type LhReport,
 } from '../lighthouse';
-import { resolveConfig, probeUrl } from '../config';
+import { resolveConfig, probeUrl, ambiguousSiteNote } from '../config';
 import { step, info, fail, warn } from '../output';
 
 function runLighthouse(url: string, outPath: string): LhReport {
@@ -70,6 +70,8 @@ export async function auditLighthouseCommand(flags: Record<string, string>): Pro
     try {
       const config = await resolveConfig(flags.stage);
       host = probeUrl(config);
+      const ambiguous = ambiguousSiteNote(config);
+      if (ambiguous) info(ambiguous);
     } catch (err: any) {
       fail(err.message);
       info('Pass --host <url> to audit a specific URL without resolving a stage.');

package/src/cli/commands/security-probe.ts

@@ -26,7 +26,7 @@ import {
   type CatalogGrant,
   type ProbeResult,
 } from '../security-probe';
-import { resolveConfig, opsFunction, probeUrl } from '../config';
+import { resolveConfig, opsFunction, probeUrl, ambiguousSiteNote } from '../config';
 import { invokeAction } from '../aws';
 import { step, info, fail, success, warn } from '../output';
 
@@ -193,6 +193,8 @@ export async function securityProbeCommand(flags: Record<string, string>): Promi
     fail('No router URL to probe. Pass --host or ensure the stage has a deployed URL.');
     process.exit(1);
   }
+  const ambiguous = flags.host ? undefined : ambiguousSiteNote(config);
+  if (ambiguous) info(ambiguous);
   info(`Region: ${config.region}, Function: ${opsFunction(config)}, URL: ${base}`);
 
   let results: ProbeResult[];

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/config.ts

@@ -16,6 +16,10 @@ export interface CliConfig {
   baseUrl: string;
   /** What cache:purge and update's release check probe. Falls back to baseUrl when absent. */
   siteUrl?: string;
+  /** Candidate URLs to probe, best first (see DiscoveredConfig.siteUrls). Absent on older configs. */
+  siteUrls?: string[];
+  /** The stage distribution's concrete aliases (empty when CDN_URL is set). */
+  siteAliases?: string[];
   region: string;
   apiFunctionName: string;
   /** Dedicated operator function (db/console actions). Falls back to apiFunctionName. */
@@ -41,6 +45,20 @@ export function probeUrl(config: Pick<CliConfig, 'baseUrl' | 'siteUrl'>): string
   return config.siteUrl || config.baseUrl || '';
 }
 
+/**
+ * One line for single-probe commands when the stage's distribution has several aliases and no
+ * CDN_URL: siteUrl is then the cloudfront.net domain, not a chosen host. A green there is a result
+ * for a host users may never hit, so say which one it is, every run. Undefined when unambiguous.
+ */
+export function ambiguousSiteNote(config: Pick<CliConfig, 'baseUrl' | 'siteUrl' | 'siteAliases'>): string | undefined {
+  const aliases = config.siteAliases ?? [];
+  if (config.baseUrl || aliases.length < 2) return undefined;
+  return (
+    `Site URL is ambiguous: this stage's distribution has aliases ${aliases.join(', ')}. Probing ${probeUrl(config)}. ` +
+    'Choose one with --host <alias> (or pass the URL to diag and bundle:audit).'
+  );
+}
+
 /** Operator invoke target — dedicated ops function when deployed, else the API function. */
 export function opsFunction(config: CliConfig): string {
   return config.opsFunctionName ?? config.apiFunctionName;
@@ -168,6 +186,7 @@ export async function resolveConfig(stage?: string): Promise<CliConfig> {
   return {
     baseUrl: outputs.routerUrl,
     siteUrl: outputs.routerUrl,
+    siteUrls: [outputs.routerUrl],
     region,
     apiFunctionName: outputs.apiFunctionName,
     opsFunctionName: outputs.opsFunctionName,

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;
@@ -33,13 +35,16 @@ interface DistributionSummaryLite {
  */
 export interface DistributionMatch {
   id: string;
-  /** cloudfront.net domain, no scheme — the host this distribution always answers on. */
+  /** cloudfront.net domain, no scheme. A CloudFront Function may still answer 403 on it. */
   domain?: string;
+  /** Concrete custom-domain aliases (wildcards dropped), in CloudFront's order: the site's real hostnames. */
+  aliases: string[];
   by: 'host' | 'comment' | 'tag';
 }
 
 function toMatch(dist: DistributionSummaryLite, by: DistributionMatch['by']): DistributionMatch | undefined {
-  return dist.Id ? { id: dist.Id, domain: dist.DomainName, by } : undefined;
+  const aliases = (dist.Aliases?.Items ?? []).filter((a) => !a.includes('*'));
+  return dist.Id ? { id: dist.Id, domain: dist.DomainName, aliases, by } : undefined;
 }
 
 function matchByHost(items: readonly DistributionSummaryLite[], routerHost?: string): DistributionMatch | undefined {
@@ -109,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 {
@@ -120,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

@@ -27,6 +27,14 @@ interface DiscoveredConfig {
    * tag-confirmed CloudFront distribution, else ''. Probe-only; never shipped.
    */
   siteUrl: string;
+  /**
+   * Every URL worth probing, best first: CDN_URL alone when set, else the distribution's custom
+   * aliases then its cloudfront.net domain. A CloudFront Function can gate by Host and answer 403 on
+   * the raw domain, so the gate passes if ANY of these serves the release. siteUrl is the first.
+   */
+  siteUrls: string[];
+  /** The distribution's concrete aliases; two or more make siteUrl a guess, which commands announce. */
+  siteAliases: string[];
   region: string;
   apiFunctionName: string;
   opsFunctionName?: string;
@@ -71,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,
@@ -84,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());
 }
 
 // ---------------------------------------------------------------------------
@@ -102,7 +145,8 @@ interface CfFunctionResult {
  */
 export async function discoverCfFunction(
   region: string,
-  prefix: string,
+  appName: string,
+  stage: string,
 ): Promise<CfFunctionResult> {
   const {
     CloudFrontClient,
@@ -111,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;
@@ -134,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.`,
     );
   }
@@ -160,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(
@@ -173,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;
 
@@ -199,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.`,
     );
   }
@@ -243,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',
@@ -253,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;
@@ -293,22 +349,26 @@ 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),
   ]);
 
   // Distribution discovery is best-effort (status CDN section, cache:purge --invalidate)
   let distributionId: string | undefined;
+  let distributionHosts: string[] = [];
+  let distributionAliases: string[] = [];
   let distributionDomain: string | undefined;
   try {
     const { discoverDistributionMatch } = await import('./discover-distribution');
@@ -323,7 +383,11 @@ export async function discoverConfig(
     distributionId = match?.id;
     // A Comment-substring match can name another app's stage; only a confirmed one may say
     // which site a purge probes.
-    if (match && match.by !== 'comment') distributionDomain = match.domain;
+    if (match && match.by !== 'comment') {
+      distributionAliases = match.aliases;
+      distributionDomain = match.domain;
+      distributionHosts = [...match.aliases, ...(match.domain ? [match.domain] : [])];
+    }
   } catch {
     // Non-fatal
   }
@@ -331,18 +395,31 @@ export async function discoverConfig(
   // CDN_URL is optional on the API Lambda. Without it the stage's own distribution supplies the
   // probe URL — and only that: baseUrl stays as deployed (see DiscoveredConfig).
   const baseUrl = lambdaResult.routerUrl || '';
-  const siteUrl = baseUrl || (distributionDomain ? `https://${distributionDomain}` : '');
+  // Gate candidates: every host worth trying, best first. siteUrl is what single-probe commands use
+  // with no fallback, so it must not be a guess: CDN_URL, else the ONE alias if there is exactly one,
+  // else the cloudfront.net domain (loud on a hostname-gating site, and commands say which host).
+  const siteUrls = baseUrl ? [baseUrl] : distributionHosts.map((h) => `https://${h}`);
+  const siteAliases = baseUrl ? [] : distributionAliases;
+  const siteUrl = baseUrl
+    ? baseUrl
+    : distributionAliases.length === 1
+      ? `https://${distributionAliases[0]}`
+      : distributionDomain
+        ? `https://${distributionDomain}`
+        : '';
 
   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.`,
     );
   }
@@ -368,6 +445,8 @@ export async function discoverConfig(
   return {
     baseUrl,
     siteUrl,
+    siteUrls,
+    siteAliases,
     region,
     apiFunctionName: lambdaResult.functionName,
     opsFunctionName: opsFn,
@@ -387,13 +466,15 @@ export async function discoverConfig(
 // ---------------------------------------------------------------------------
 
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const CACHE_VERSION = 6; // Bump when CachedOutputs schema changes to invalidate stale caches (5: +backupsBucket, 6: +siteUrl; getCachedConfig drops v5 files, an empty siteUrl is cached as a fact)
+const CACHE_VERSION = 7; // Bump when CachedOutputs schema changes to invalidate stale caches (5: +backupsBucket, 6: +siteUrl, 7: +siteUrls; v6 pinned the cloudfront.net domain, which a hostname-gating function answers 403)
 
 interface CachedOutputs {
   _cachedAt: number;
   _version?: number;
   routerUrl?: string;
   siteUrl?: string;
+  siteUrls?: string[];
+  siteAliases?: string[];
   apiFunctionName?: string;
   opsFunctionName?: string;
   imageFunctionName?: string;
@@ -422,6 +503,8 @@ export async function getCachedConfig(stage: string): Promise<DiscoveredConfig |
     return {
       baseUrl: cached.routerUrl || '',
       siteUrl: cached.siteUrl ?? cached.routerUrl ?? '',
+      siteUrls: cached.siteUrls ?? [],
+      siteAliases: cached.siteAliases ?? [],
       region: process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || 'us-east-1',
       apiFunctionName: cached.apiFunctionName,
       opsFunctionName: cached.opsFunctionName,
@@ -500,6 +583,8 @@ export async function setCachedConfig(stage: string, config: DiscoveredConfig):
     _version: CACHE_VERSION,
     routerUrl: config.baseUrl,
     siteUrl: config.siteUrl,
+    siteUrls: config.siteUrls,
+    siteAliases: config.siteAliases,
     apiFunctionName: config.apiFunctionName,
     opsFunctionName: config.opsFunctionName,
     imageFunctionName: config.imageFunctionName,

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

@@ -367,6 +367,7 @@ Usage:
   everystack cache:purge       [--stage <name>] --origin api     Bust API origin cache (api|media|web)
   everystack cache:purge       [--stage <name>] --path "/api/posts"  Bust specific path cache
   everystack cache:purge       [--stage <name>] --invalidate     Also create CloudFront edge invalidation
+  everystack cache:purge       [--stage <name>] --host <url>     Probe this public URL for the release check (a site whose CloudFront Function gates by hostname)
   everystack diag              [url] [--path /about] [--channel <name>] [--stage <name>]  Diagnose page freshness
   everystack diag              [url] --hydration  Analyze SSR hydration issues (fetches full HTML)
   everystack analyze:ssr       [--app ./app]      Scan app code for SSR anti-patterns

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);
+}