@everystack/cli 0.2.33 → 0.2.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.2.33",
+  "version": "0.2.34",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -60,6 +60,7 @@
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",
+    "@aws-sdk/client-cloudwatch": "3.1053.0",
     "@aws-sdk/client-cloudwatch-logs": "3.1053.0",
     "@aws-sdk/client-lambda": "3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
@@ -74,6 +75,9 @@
     "@everystack/server": {
       "optional": true
     },
+    "@aws-sdk/client-cloudwatch": {
+      "optional": true
+    },
     "@aws-sdk/client-cloudwatch-logs": {
       "optional": true
     },
@@ -100,6 +104,7 @@
     }
   },
   "devDependencies": {
+    "@aws-sdk/client-cloudwatch": "3.1053.0",
     "@aws-sdk/client-cloudwatch-logs": "3.1053.0",
     "@aws-sdk/client-lambda": "3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",

package/src/cli/commands/db.ts

@@ -7,7 +7,7 @@
 
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
-import { step, success, fail, info } from '../output.js';
+import { step, success, fail, info, warn } from '../output.js';
 
 export async function dbMigrateCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
@@ -34,6 +34,11 @@ export async function dbMigrateCommand(flags: Record<string, string>): Promise<v
       process.exit(1);
     }
     success(result?.message || 'Migrations applied');
+    // Journal drift warnings — a migration file the journal doesn't list
+    // will silently never apply. Never swallow these.
+    for (const warning of result?.warnings ?? []) {
+      warn(warning);
+    }
   } catch (err: any) {
     fail(`Migration failed: ${err.message}`);
     info('Ensure your IAM user/role has lambda:InvokeFunction permission.');

package/src/cli/commands/status.ts

@@ -0,0 +1,262 @@
+/**
+ * `everystack status` — platform health from the terminal.
+ *
+ * Three sections, each independent:
+ *   CDN      — CloudFront metrics from CloudWatch (requests, hit rate, error rates)
+ *   Lambda   — per-function invocations / errors / p95 duration
+ *   Platform — per-origin rollup summary via the ops Lambda's platform:health
+ *              action (same numbers as /admin/health)
+ *
+ * On a V1 stack (no database) the platform section degrades to a note —
+ * CDN and Lambda metrics still work with nothing but IAM credentials.
+ */
+
+import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { fail, info, step } from '../output.js';
+
+export interface MetricSpec {
+  namespace: string;
+  metricName: string;
+  stat: string;
+  dimensions: Record<string, string>;
+  /** CloudFront metrics live in us-east-1 regardless of stack region. */
+  region?: string;
+}
+
+export interface StatusDeps {
+  /** Fetch a single aggregated CloudWatch datapoint for the window. Null = no data. */
+  getMetric: (region: string, spec: MetricSpec, hours: number) => Promise<number | null>;
+  invoke: typeof invokeAction;
+}
+
+interface OriginSummaryLite {
+  source: string;
+  requestCount: number;
+  hitRatio: number | null;
+  availability: number | null;
+  status5xx: number;
+}
+
+export interface StatusData {
+  hours: number;
+  cdn: {
+    distributionId: string;
+    requests: number | null;
+    cacheHitRate: number | null;
+    rate4xx: number | null;
+    rate5xx: number | null;
+  } | null;
+  lambdas: Array<{
+    label: string;
+    functionName: string;
+    invocations: number | null;
+    errors: number | null;
+    p95Ms: number | null;
+  }>;
+  platform: {
+    perOrigin: OriginSummaryLite[];
+    totals: { requestCount: number; availability: number | null; hitRatio: number | null; status5xx: number };
+    percentiles: {
+      p50: number | null; p95: number | null; p99: number | null;
+      under100ms: number | null; under300ms: number | null; under1s: number | null;
+    };
+  } | null;
+  platformError: string | null;
+}
+
+async function defaultGetMetric(
+  region: string,
+  spec: MetricSpec,
+  hours: number,
+): Promise<number | null> {
+  const { CloudWatchClient, GetMetricDataCommand } = await import('@aws-sdk/client-cloudwatch');
+  const client = new CloudWatchClient({ region: spec.region ?? region });
+  const end = new Date();
+  const start = new Date(end.getTime() - hours * 3600_000);
+  const response = await client.send(new GetMetricDataCommand({
+    StartTime: start,
+    EndTime: end,
+    MetricDataQueries: [{
+      Id: 'm0',
+      MetricStat: {
+        Metric: {
+          Namespace: spec.namespace,
+          MetricName: spec.metricName,
+          Dimensions: Object.entries(spec.dimensions).map(([Name, Value]) => ({ Name, Value })),
+        },
+        Period: hours * 3600,
+        Stat: spec.stat,
+      },
+    }],
+  }));
+  const values = response.MetricDataResults?.[0]?.Values ?? [];
+  if (values.length === 0) return null;
+  return values.reduce((a, b) => a + b, 0) / (spec.stat === 'Sum' ? 1 : values.length);
+}
+
+export async function gatherStatus(
+  config: CliConfig,
+  hours: number,
+  deps: StatusDeps,
+): Promise<StatusData> {
+  const data: StatusData = {
+    hours,
+    cdn: null,
+    lambdas: [],
+    platform: null,
+    platformError: null,
+  };
+
+  const tasks: Promise<void>[] = [];
+
+  if (config.distributionId) {
+    const cfDims = { DistributionId: config.distributionId, Region: 'Global' };
+    const cf = (metricName: string, stat: string) =>
+      deps.getMetric(config.region, {
+        namespace: 'AWS/CloudFront', metricName, stat, dimensions: cfDims, region: 'us-east-1',
+      }, hours).catch(() => null);
+    tasks.push(
+      Promise.all([
+        cf('Requests', 'Sum'),
+        cf('CacheHitRate', 'Average'),
+        cf('4xxErrorRate', 'Average'),
+        cf('5xxErrorRate', 'Average'),
+      ]).then(([requests, cacheHitRate, rate4xx, rate5xx]) => {
+        data.cdn = { distributionId: config.distributionId!, requests, cacheHitRate, rate4xx, rate5xx };
+      }),
+    );
+  }
+
+  const lambdaTargets = [
+    { label: 'api', functionName: config.apiFunctionName },
+    { label: 'image', functionName: config.imageFunctionName },
+    { label: 'worker', functionName: config.workerFunctionName },
+  ].filter((t): t is { label: string; functionName: string } => !!t.functionName);
+
+  for (const target of lambdaTargets) {
+    const dims = { FunctionName: target.functionName };
+    const lm = (metricName: string, stat: string) =>
+      deps.getMetric(config.region, {
+        namespace: 'AWS/Lambda', metricName, stat, dimensions: dims,
+      }, hours).catch(() => null);
+    tasks.push(
+      Promise.all([
+        lm('Invocations', 'Sum'),
+        lm('Errors', 'Sum'),
+        lm('Duration', 'p95'),
+      ]).then(([invocations, errors, p95Ms]) => {
+        data.lambdas.push({ ...target, invocations, errors, p95Ms });
+      }),
+    );
+  }
+
+  tasks.push(
+    deps
+      .invoke(config.region, opsFunction(config), 'platform:health', { hours })
+      .then((result) => {
+        const payload = result as StatusData['platform'] & { error?: string };
+        if (payload && !payload.error && payload.totals) {
+          data.platform = payload;
+        } else {
+          data.platformError = payload?.error ?? 'empty response';
+        }
+      })
+      .catch((err: Error) => {
+        data.platformError = err.message;
+      }),
+  );
+
+  await Promise.all(tasks);
+  // Keep lambda section in declaration order regardless of resolution order
+  data.lambdas.sort(
+    (a, b) =>
+      lambdaTargets.findIndex((t) => t.label === a.label) -
+      lambdaTargets.findIndex((t) => t.label === b.label),
+  );
+  return data;
+}
+
+const DASH = '—';
+
+function num(value: number | null | undefined): string {
+  if (value === null || value === undefined) return DASH;
+  return Math.round(value).toLocaleString();
+}
+
+function pct(value: number | null | undefined, digits = 0): string {
+  if (value === null || value === undefined) return DASH;
+  return `${(value * 100).toFixed(digits)}%`;
+}
+
+/** CloudWatch rate metrics arrive as 0–100, ratios from rollups as 0–1. */
+function rate(value: number | null | undefined, digits = 1): string {
+  if (value === null || value === undefined) return DASH;
+  return `${value.toFixed(digits)}%`;
+}
+
+function ms(value: number | null | undefined): string {
+  if (value === null || value === undefined) return DASH;
+  return `${Math.round(value)}ms`;
+}
+
+export function formatStatus(data: StatusData): string[] {
+  const lines: string[] = [];
+
+  if (data.cdn) {
+    lines.push(`CDN ${data.cdn.distributionId} (last ${data.hours}h)`);
+    lines.push(
+      `  requests ${num(data.cdn.requests)}  cache hit ${rate(data.cdn.cacheHitRate)}  4xx ${rate(data.cdn.rate4xx, 2)}  5xx ${rate(data.cdn.rate5xx, 2)}`,
+    );
+  }
+
+  if (data.lambdas.length > 0) {
+    lines.push('Lambda');
+    for (const fn of data.lambdas) {
+      lines.push(
+        `  ${fn.label.padEnd(7)} invocations ${num(fn.invocations)}  errors ${num(fn.errors)}  p95 ${ms(fn.p95Ms)}`,
+      );
+    }
+  }
+
+  if (data.platform) {
+    const p = data.platform;
+    lines.push(`Platform (rollups, last ${data.hours}h)`);
+    for (const origin of p.perOrigin) {
+      lines.push(
+        `  ${origin.source.padEnd(7)} ${num(origin.requestCount).padStart(8)} reqs  hit ${pct(origin.hitRatio)}  availability ${pct(origin.availability, 2)}`,
+      );
+    }
+    lines.push(
+      `  p50 ${ms(p.percentiles.p50)} · p95 ${ms(p.percentiles.p95)} · p99 ${ms(p.percentiles.p99)} · ${pct(p.percentiles.under300ms, 1)} under 300ms · availability ${pct(p.totals.availability, 2)}`,
+    );
+  } else {
+    lines.push(`Platform: no database rollups (V1 stack or pipeline not deployed) — ${data.platformError ?? ''}`);
+  }
+
+  return lines;
+}
+
+export async function statusCommand(
+  flags: Record<string, string>,
+  deps?: Partial<StatusDeps>,
+): Promise<void> {
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: unknown) {
+    fail((err as Error).message);
+    process.exit(1);
+  }
+
+  const hours = Number(flags.hours) > 0 ? Number(flags.hours) : 1;
+  const data = await gatherStatus(config, hours, {
+    getMetric: deps?.getMetric ?? defaultGetMetric,
+    invoke: deps?.invoke ?? invokeAction,
+  });
+
+  for (const line of formatStatus(data)) {
+    info(line);
+  }
+}

package/src/cli/discover-distribution.ts

@@ -3,34 +3,92 @@
  *
  * Separated from discover.ts to avoid Jest ESM module resolution issues
  * with the @aws-sdk/client-cloudfront ListDistributions types.
+ *
+ * SST Routers do not put the app/stage in the distribution Comment, so
+ * matching runs in order of reliability:
+ *   1. DomainName / Aliases match the discovered router URL host
+ *   2. Comment contains the {app}-{stage}- prefix (legacy setups)
+ *   3. sst:app + sst:stage tags (authoritative, but one API call per candidate)
  */
 
+export interface DistributionHints {
+  /** Host of the discovered router URL, e.g. d111abc.cloudfront.net or a custom domain. */
+  routerHost?: string;
+  appName?: string;
+  stage?: string;
+}
+
+interface DistributionSummaryLite {
+  Id?: string;
+  Comment?: string;
+  DomainName?: string;
+  ARN?: string;
+  Aliases?: { Items?: string[] };
+}
+
+/** Pure matcher for the cheap passes (domain, alias, legacy comment). Exported for tests. */
+export function matchDistribution(
+  items: readonly DistributionSummaryLite[],
+  prefix: string,
+  routerHost?: string,
+): string | undefined {
+  const host = routerHost?.toLowerCase();
+  if (host) {
+    for (const dist of items) {
+      if (dist.DomainName?.toLowerCase() === host) return dist.Id;
+      if (dist.Aliases?.Items?.some((alias) => alias.toLowerCase() === host)) return dist.Id;
+    }
+  }
+  const needle = prefix.toLowerCase();
+  for (const dist of items) {
+    if ((dist.Comment || '').toLowerCase().includes(needle)) return dist.Id;
+  }
+  return undefined;
+}
+
 /**
- * Find the CloudFront distribution for a stage by matching the Comment field.
- * SST sets the Comment to include the app name and stage.
+ * Find the CloudFront distribution for a stage.
  * Best-effort: returns undefined if not found.
  */
 export async function discoverDistribution(
   region: string,
   prefix: string,
+  hints: DistributionHints = {},
 ): Promise<string | undefined> {
-  const { CloudFrontClient, ListDistributionsCommand } = await import('@aws-sdk/client-cloudfront');
+  const { CloudFrontClient, ListDistributionsCommand, ListTagsForResourceCommand } =
+    await import('@aws-sdk/client-cloudfront');
   const client = new CloudFrontClient({ region });
-  const distNeedle = prefix.toLowerCase();
 
+  const items: DistributionSummaryLite[] = [];
   let marker: string | undefined;
   do {
     const res = await client.send(
       new ListDistributionsCommand({ Marker: marker, MaxItems: 50 }),
     );
-    for (const dist of res.DistributionList?.Items || []) {
-      const comment = (dist.Comment || '').toLowerCase();
-      if (comment.includes(distNeedle)) {
-        return dist.Id;
-      }
-    }
+    items.push(...((res.DistributionList?.Items || []) as DistributionSummaryLite[]));
     marker = res.DistributionList?.IsTruncated ? res.DistributionList.NextMarker : undefined;
   } while (marker);
 
+  const cheap = matchDistribution(items, prefix, hints.routerHost);
+  if (cheap) return cheap;
+
+  // Tag pass — authoritative but one call per distribution, so it runs last.
+  if (hints.appName && hints.stage) {
+    for (const dist of items) {
+      if (!dist.ARN) continue;
+      try {
+        const res = await client.send(new ListTagsForResourceCommand({ Resource: dist.ARN }));
+        const tags = new Map(
+          (res.Tags?.Items || []).map((t) => [t.Key, t.Value]),
+        );
+        if (tags.get('sst:app') === hints.appName && tags.get('sst:stage') === hints.stage) {
+          return dist.Id;
+        }
+      } catch {
+        // Tag read denied or transient — keep scanning
+      }
+    }
+  }
+
   return undefined;
 }

package/src/cli/discover.ts

@@ -273,13 +273,20 @@ export async function discoverConfig(
       .catch(() => undefined),
   ]);
 
-  // Distribution discovery is best-effort (not critical for most CLI operations)
+  // Distribution discovery is best-effort (status CDN section, cache:purge --invalidate)
   let distributionId: string | undefined;
   try {
     const { discoverDistribution } = await import('./discover-distribution.js');
-    distributionId = await discoverDistribution(region, prefix);
+    const routerHost = lambdaResult.routerUrl
+      ? new URL(lambdaResult.routerUrl).host
+      : undefined;
+    distributionId = await discoverDistribution(region, prefix, {
+      routerHost,
+      appName,
+      stage,
+    });
   } catch {
-    // Non-fatal — only needed for cache:purge --invalidate
+    // Non-fatal
   }
 
   if (!bucketsResult.updatesBucket) {
@@ -329,7 +336,7 @@ export async function discoverConfig(
 // ---------------------------------------------------------------------------
 
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const CACHE_VERSION = 3; // Bump when CachedOutputs schema changes to invalidate stale caches
+const CACHE_VERSION = 4; // Bump when CachedOutputs schema changes to invalidate stale caches
 
 interface CachedOutputs {
   _cachedAt: number;

package/src/cli/index.ts

@@ -9,6 +9,7 @@ import { branchesCommand } from './commands/branches.js';
 import { dbMigrateCommand, dbSeedCommand, dbResetCommand, dbPsqlCommand } from './commands/db.js';
 import { consoleCommand } from './commands/console.js';
 import { cachePurgeCommand } from './commands/cache.js';
+import { statusCommand } from './commands/status.js';
 import { diagCommand } from './commands/diag.js';
 import { analyzeSSRCommand } from './commands/analyze.js';
 import { logsErrorsCommand, logsTailCommand, logsQueryCommand } from './commands/logs.js';
@@ -119,6 +120,9 @@ async function main() {
     case 'cache:purge':
       await cachePurgeCommand(flags);
       break;
+    case 'status':
+      await statusCommand(flags);
+      break;
     case 'diag': {
       // Positional URL: first arg after 'diag' that doesn't start with '--'
       const diagUrl = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
@@ -174,6 +178,7 @@ Usage:
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
   everystack db:psql           [--stage <name>] -c <command>  Execute SQL query via Lambda (private RDS)
   everystack console           --stage <name> [--sandbox]  Interactive REPL on deployed Lambda
+  everystack status            [--stage <name>] [--hours <n>]  Platform health: CDN, Lambda, rollup summary
   everystack certs:generate    [--output ./certs]
   everystack certs:configure   [--input ./certs] [--keyid main]
   everystack cache:purge       [--stage <name>]                  Bust all cached content (global epoch)