@everystack/cli 0.1.0

package/src/cli/discover.ts

@@ -0,0 +1,321 @@
+/**
+ * AWS resource discovery for stage-aware CLI operations.
+ *
+ * When --stage is provided, discovers deployed resources by querying AWS
+ * using SST's naming convention: {appName}-{stage}-{ResourceName}-{hash}.
+ *
+ * Discovery chain:
+ * 1. Parse app name from sst.config.ts
+ * 2. Find CloudFront function → get KVS ARN from its association
+ * 3. Find Lambda function → get function name (+ CDN_URL env var if present)
+ * 4. Find S3 buckets → get updatesBucket + clientBundlesBucket
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/** Mirrors DiscoveredConfig from config.ts — defined locally to avoid circular imports. */
+interface DiscoveredConfig {
+  baseUrl: string;
+  region: string;
+  apiFunctionName: string;
+  updatesBucket: string;
+  clientBundlesBucket: string;
+  kvsArn?: string;
+}
+
+// ---------------------------------------------------------------------------
+// App name parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse SST app name from sst.config.ts.
+ *
+ * SST app names are always string literals in the app() return block:
+ *   name: 'my-app'   or   name: "my-app"
+ */
+export async function parseAppName(configPath?: string): Promise<string> {
+  const filePath = configPath || path.resolve('sst.config.ts');
+  let content: string;
+  try {
+    content = await fs.readFile(filePath, 'utf8');
+  } catch {
+    throw new Error(
+      `Could not find sst.config.ts at ${filePath}. Run from the SST project directory.`,
+    );
+  }
+
+  const match = content.match(/name:\s*['"]([^'"]+)['"]/);
+  if (!match) {
+    throw new Error(
+      `Could not parse app name from ${filePath}. Expected name: 'your-app' in the app() function.`,
+    );
+  }
+
+  return match[1];
+}
+
+// ---------------------------------------------------------------------------
+// CloudFront function discovery (→ KVS ARN)
+// ---------------------------------------------------------------------------
+
+interface CfFunctionResult {
+  kvsArn?: string;
+}
+
+/**
+ * Find the Router viewer-request CloudFront function for a stage and extract
+ * its associated KVS ARN.
+ */
+export async function discoverCfFunction(
+  region: string,
+  prefix: string,
+): Promise<CfFunctionResult> {
+  const {
+    CloudFrontClient,
+    ListFunctionsCommand,
+    DescribeFunctionCommand,
+  } = await import('@aws-sdk/client-cloudfront');
+
+  const client = new CloudFrontClient({ region });
+  const needle = `${prefix}RouterCloudfrontFunctionRequest-`.toLowerCase();
+
+  let marker: string | undefined;
+  let matchName: string | undefined;
+
+  // Paginate through all CF functions
+  do {
+    const res = await client.send(
+      new ListFunctionsCommand({ Marker: marker, MaxItems: 50 }),
+    );
+    const items = res.FunctionList?.Items || [];
+    for (const fn of items) {
+      if (fn.Name && fn.Name.toLowerCase().startsWith(needle)) {
+        matchName = fn.Name;
+        break;
+      }
+    }
+    if (matchName) break;
+    marker = res.FunctionList?.NextMarker;
+  } while (marker);
+
+  if (!matchName) {
+    throw new Error(
+      `No CloudFront function found matching "${prefix}RouterCloudfrontFunctionRequest-*". ` +
+        `Check that the stage has been deployed.`,
+    );
+  }
+
+  // Describe to get KVS association
+  const desc = await client.send(
+    new DescribeFunctionCommand({ Name: matchName, Stage: 'LIVE' }),
+  );
+  const kvAssociations =
+    desc.FunctionSummary?.FunctionConfig?.KeyValueStoreAssociations?.Items;
+  const kvsArn = kvAssociations?.[0]?.KeyValueStoreARN;
+
+  return { kvsArn };
+}
+
+// ---------------------------------------------------------------------------
+// Lambda discovery (→ function name, routerUrl)
+// ---------------------------------------------------------------------------
+
+interface LambdaResult {
+  functionName: string;
+  routerUrl?: string;
+}
+
+/**
+ * Find the API Lambda function for a stage.
+ * Optionally extracts CDN_URL from environment variables.
+ */
+export async function discoverLambda(
+  region: string,
+  prefix: string,
+): Promise<LambdaResult> {
+  const {
+    LambdaClient,
+    ListFunctionsCommand,
+    GetFunctionConfigurationCommand,
+  } = await import('@aws-sdk/client-lambda');
+
+  const client = new LambdaClient({ region });
+  const needle = `${prefix}ApiFunction-`.toLowerCase();
+
+  let marker: string | undefined;
+  let matchName: string | undefined;
+
+  do {
+    const res = await client.send(
+      new ListFunctionsCommand({ Marker: marker, MaxItems: 50 }),
+    );
+    const items = res.Functions || [];
+    for (const fn of items) {
+      if (fn.FunctionName && fn.FunctionName.toLowerCase().startsWith(needle)) {
+        matchName = fn.FunctionName;
+        break;
+      }
+    }
+    if (matchName) break;
+    marker = res.NextMarker;
+  } while (marker);
+
+  if (!matchName) {
+    throw new Error(
+      `No API Lambda found for prefix "${prefix}ApiFunction-*". ` +
+        `Check that the stage has been deployed and you have lambda:ListFunctions permission.`,
+    );
+  }
+
+  // Get env vars for routerUrl (CDN_URL)
+  const config = await client.send(
+    new GetFunctionConfigurationCommand({ FunctionName: matchName }),
+  );
+  const envVars = config.Environment?.Variables || {};
+
+  return {
+    functionName: matchName,
+    routerUrl: envVars.CDN_URL,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// S3 bucket discovery
+// ---------------------------------------------------------------------------
+
+interface BucketsResult {
+  updatesBucket?: string;
+  clientBundlesBucket?: string;
+}
+
+/**
+ * Find the updates and client-bundles S3 buckets for a stage.
+ */
+export async function discoverBuckets(
+  region: string,
+  prefix: string,
+): Promise<BucketsResult> {
+  const { S3Client, ListBucketsCommand } = await import('@aws-sdk/client-s3');
+
+  const client = new S3Client({ region });
+  const res = await client.send(new ListBucketsCommand({}));
+  const buckets = res.Buckets || [];
+
+  const updatesNeedle = `${prefix}updatesbucket-`.toLowerCase();
+  const clientNeedle = `${prefix}clientbundlesbucket-`.toLowerCase();
+
+  let updatesBucket: string | undefined;
+  let clientBundlesBucket: string | undefined;
+
+  for (const b of buckets) {
+    if (!b.Name) continue;
+    const lower = b.Name.toLowerCase();
+    if (lower.startsWith(updatesNeedle)) updatesBucket = b.Name;
+    if (lower.startsWith(clientNeedle)) clientBundlesBucket = b.Name;
+    if (updatesBucket && clientBundlesBucket) break;
+  }
+
+  return { updatesBucket, clientBundlesBucket };
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover all CLI resources for a given app + stage by querying AWS.
+ */
+export async function discoverConfig(
+  appName: string,
+  stage: string,
+  region: string,
+): Promise<DiscoveredConfig> {
+  const prefix = `${appName}-${stage}-`;
+
+  // Run CF function + Lambda + S3 discovery in parallel
+  const [cfResult, lambdaResult, bucketsResult] = await Promise.all([
+    discoverCfFunction(region, prefix),
+    discoverLambda(region, prefix),
+    discoverBuckets(region, prefix),
+  ]);
+
+  if (!bucketsResult.updatesBucket) {
+    throw new Error(
+      `Could not find S3 bucket "${prefix}updatesbucket-*". ` +
+        `Check that stage "${stage}" has been deployed and you have s3:ListAllMyBuckets permission.`,
+    );
+  }
+
+  if (!bucketsResult.clientBundlesBucket) {
+    throw new Error(
+      `Could not find S3 bucket "${prefix}clientbundlesbucket-*". ` +
+        `Check that stage "${stage}" has been deployed.`,
+    );
+  }
+
+  return {
+    baseUrl: lambdaResult.routerUrl || '',
+    region,
+    apiFunctionName: lambdaResult.functionName,
+    updatesBucket: bucketsResult.updatesBucket,
+    clientBundlesBucket: bucketsResult.clientBundlesBucket,
+    kvsArn: cfResult.kvsArn,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Config cache (per-stage)
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+interface CachedOutputs {
+  _cachedAt: number;
+  routerUrl?: string;
+  apiFunctionName?: string;
+  updatesBucket?: string;
+  clientBundlesBucket?: string;
+  kvsArn?: string;
+}
+
+function cachePath(stage: string): string {
+  return path.resolve('.sst', `outputs.${stage}.json`);
+}
+
+export async function getCachedConfig(stage: string): Promise<DiscoveredConfig | null> {
+  try {
+    const raw = await fs.readFile(cachePath(stage), 'utf8');
+    const cached: CachedOutputs = JSON.parse(raw);
+    if (Date.now() - cached._cachedAt > CACHE_TTL_MS) return null;
+    if (!cached.apiFunctionName || !cached.updatesBucket || !cached.clientBundlesBucket) {
+      return null;
+    }
+    return {
+      baseUrl: cached.routerUrl || '',
+      region: process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || 'us-east-1',
+      apiFunctionName: cached.apiFunctionName,
+      updatesBucket: cached.updatesBucket,
+      clientBundlesBucket: cached.clientBundlesBucket,
+      kvsArn: cached.kvsArn,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function setCachedConfig(stage: string, config: DiscoveredConfig): Promise<void> {
+  const data: CachedOutputs = {
+    _cachedAt: Date.now(),
+    routerUrl: config.baseUrl,
+    apiFunctionName: config.apiFunctionName,
+    updatesBucket: config.updatesBucket,
+    clientBundlesBucket: config.clientBundlesBucket,
+    kvsArn: config.kvsArn,
+  };
+  try {
+    await fs.writeFile(cachePath(stage), JSON.stringify(data, null, 2));
+  } catch {
+    // Cache write failure is non-fatal
+  }
+}

package/src/cli/hydration-analyzer.ts

@@ -0,0 +1,224 @@
+/**
+ * hydration-analyzer — detect SSR hydration issues.
+ *
+ * Analyzes HTML responses to detect common hydration mismatches:
+ *   - Type inconsistencies (string aggregates vs numbers)
+ *   - Timezone rendering differences
+ *   - Relative time in cached responses
+ *   - Stale data indicators
+ */
+
+interface HydrationIssue {
+  type: 'aggregate-string' | 'timezone-mismatch' | 'relative-time' | 'stale-data' | 'other';
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+  fix?: string;
+  location?: string;
+}
+
+interface HydrationAnalysis {
+  issues: HydrationIssue[];
+  cacheAge?: number;
+  hasLoaderData: boolean;
+  suspectPatterns: {
+    aggregateNumbers: string[];
+    dateStrings: string[];
+    relativeTimeStrings: string[];
+  };
+}
+
+/**
+ * Analyze HTML for potential hydration issues.
+ */
+export function analyzeHtml(html: string, cacheAge?: number): HydrationAnalysis {
+  const issues: HydrationIssue[] = [];
+  const suspectPatterns = {
+    aggregateNumbers: [] as string[],
+    dateStrings: [] as string[],
+    relativeTimeStrings: [] as string[],
+  };
+
+  // Check for loader data presence (indicates SSR ran)
+  const hasLoaderData = html.includes('__EXPO_ROUTER_HYDRATE__');
+
+  // 1. Detect potential aggregate strings that should be numbers
+  // Common patterns: "0 followers", "42 posts", "123 likes"
+  const aggregatePattern = /(\d+)\s+(followers?|following|posts?|likes?|comments?|views?)/gi;
+  let match;
+  while ((match = aggregatePattern.exec(html)) !== null) {
+    const count = match[1];
+    const entity = match[2];
+    suspectPatterns.aggregateNumbers.push(`${count} ${entity}`);
+
+    // If count looks like it might be rendered from a string (no formatting, just digits)
+    if (/^\d+$/.test(count) && parseInt(count, 10) > 0) {
+      // This is a heuristic - we can't definitively say it's wrong without comparing to client render
+      // But we can flag it for manual inspection
+    }
+  }
+
+  // 2. Detect date strings that might have timezone issues
+  // Patterns: "January 15, 2026", "Jan 15, 2026", "2026-01-15"
+  const datePattern = /\b(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},\s+\d{4}\b/gi;
+  while ((match = datePattern.exec(html)) !== null) {
+    suspectPatterns.dateStrings.push(match[0]);
+  }
+
+  // Short date pattern: "Jan 15, 2026"
+  const shortDatePattern = /\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+\d{1,2},\s+\d{4}\b/gi;
+  while ((match = shortDatePattern.exec(html)) !== null) {
+    suspectPatterns.dateStrings.push(match[0]);
+  }
+
+  // 3. Detect relative time strings (these should NOT be in SSR HTML)
+  const relativeTimePatterns = [
+    /\b(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+ago\b/gi,
+    /\bjust now\b/gi,
+    /\ba (few seconds|moment) ago\b/gi,
+  ];
+
+  for (const pattern of relativeTimePatterns) {
+    while ((match = pattern.exec(html)) !== null) {
+      suspectPatterns.relativeTimeStrings.push(match[0]);
+    }
+  }
+
+  if (suspectPatterns.relativeTimeStrings.length > 0) {
+    issues.push({
+      type: 'relative-time',
+      severity: 'warning',
+      message: `Found relative time strings in SSR HTML: ${suspectPatterns.relativeTimeStrings.join(', ')}`,
+      fix: 'Use absolute timestamps for SSR. Render relative time on client only.',
+    });
+
+    // If cached for a long time, this is definitely stale
+    if (cacheAge && cacheAge > 300) {
+      issues.push({
+        type: 'stale-data',
+        severity: 'error',
+        message: `Relative time strings in HTML cached for ${cacheAge}s will be stale`,
+        fix: 'Never render relative time during SSR. Use absolute dates instead.',
+      });
+    }
+  }
+
+  // 4. Check cache age for date staleness
+  if (cacheAge && cacheAge > 86400 && suspectPatterns.dateStrings.length > 0) {
+    issues.push({
+      type: 'stale-data',
+      severity: 'warning',
+      message: `HTML cached for ${Math.floor(cacheAge / 86400)} days. Dates may be stale.`,
+      fix: 'Consider shorter cache TTL for pages with time-sensitive content.',
+    });
+  }
+
+  return {
+    issues,
+    cacheAge,
+    hasLoaderData,
+    suspectPatterns,
+  };
+}
+
+/**
+ * Compare SSR HTML with expected client render to detect mismatches.
+ * This is a heuristic analysis - true comparison requires running client-side React.
+ */
+export function compareRendering(ssrHtml: string, expectedClientHtml?: string): HydrationIssue[] {
+  const issues: HydrationIssue[] = [];
+
+  // If we have both versions, we can do a more detailed comparison
+  if (expectedClientHtml) {
+    // Check for text content differences
+    const ssrText = stripHtmlTags(ssrHtml);
+    const clientText = stripHtmlTags(expectedClientHtml);
+
+    if (ssrText !== clientText) {
+      issues.push({
+        type: 'other',
+        severity: 'error',
+        message: 'SSR and client render produce different text content',
+        fix: 'Check for timezone issues, aggregate type coercions, and relative time rendering.',
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Strip HTML tags to get text content for comparison.
+ */
+function stripHtmlTags(html: string): string {
+  return html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Generate a diagnostic report from hydration analysis.
+ */
+export function generateHydrationReport(analysis: HydrationAnalysis): string {
+  const lines: string[] = [];
+
+  if (!analysis.hasLoaderData) {
+    lines.push('  ⚠  No __EXPO_ROUTER_HYDRATE__ flag found. SSR may not be running correctly.');
+    lines.push('');
+  }
+
+  const hasSuspectPatterns =
+    analysis.suspectPatterns.aggregateNumbers.length > 0 ||
+    analysis.suspectPatterns.dateStrings.length > 0 ||
+    analysis.suspectPatterns.relativeTimeStrings.length > 0;
+
+  if (analysis.issues.length === 0 && !hasSuspectPatterns) {
+    lines.push('  ✓  No hydration issues detected');
+    return lines.join('\n');
+  }
+
+  if (analysis.issues.length > 0) {
+    lines.push('  Potential Hydration Issues:');
+    lines.push('  ' + '='.repeat(58));
+    lines.push('');
+
+    for (const issue of analysis.issues) {
+      const icon = issue.severity === 'error' ? '✗' : issue.severity === 'warning' ? '⚠' : 'ℹ';
+      lines.push(`  ${icon}  ${issue.message}`);
+      if (issue.fix) {
+        lines.push(`     Fix: ${issue.fix}`);
+      }
+      if (issue.location) {
+        lines.push(`     Location: ${issue.location}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Add suspect patterns if found (show even without critical issues)
+  if (analysis.suspectPatterns.aggregateNumbers.length > 0) {
+    lines.push('  Found aggregate numbers (check for string/number mismatches):');
+    for (const pattern of analysis.suspectPatterns.aggregateNumbers.slice(0, 5)) {
+      lines.push(`    - ${pattern}`);
+    }
+    if (analysis.suspectPatterns.aggregateNumbers.length > 5) {
+      lines.push(`    ... and ${analysis.suspectPatterns.aggregateNumbers.length - 5} more`);
+    }
+    lines.push('');
+  }
+
+  if (analysis.suspectPatterns.dateStrings.length > 0) {
+    lines.push('  Found date strings (check for timezone: \'UTC\' in toLocaleDateString):');
+    for (const pattern of analysis.suspectPatterns.dateStrings.slice(0, 3)) {
+      lines.push(`    - ${pattern}`);
+    }
+    if (analysis.suspectPatterns.dateStrings.length > 3) {
+      lines.push(`    ... and ${analysis.suspectPatterns.dateStrings.length - 3} more`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}