@everystack/cli 0.1.0

package/src/cli/commands/diag.ts

@@ -0,0 +1,242 @@
+/**
+ * diag — diagnose deployed page freshness and hydration issues.
+ *
+ * Fetches the deployed page via HEAD, reads the latest channel manifest
+ * from S3, and compares. Reports CDN cache status, release version,
+ * and whether the served content matches the latest OTA update.
+ *
+ * With --hydration flag, fetches full HTML and analyzes for common
+ * SSR hydration issues: type mismatches, timezone problems, relative time.
+ *
+ * Usage:
+ *   everystack diag [url] [--path /about] [--channel production] [--stage dev]
+ *   everystack diag [url] --hydration  # Analyze SSR hydration issues
+ */
+
+import { resolveConfig } from '../config.js';
+import { getFromS3 } from '../aws.js';
+import { step, success, fail, info, warn } from '../output.js';
+import { analyzeHtml, generateHydrationReport } from '../hydration-analyzer.js';
+
+interface DiagResult {
+  url: string;
+  status: number;
+  statusText: string;
+  cacheStatus?: string;
+  cacheAge?: string;
+  cacheControl?: string;
+  bundleKey?: string;
+  updateId?: string;
+  runtimeVersion?: string;
+  releaseCreated?: string;
+}
+
+interface Manifest {
+  updateId?: string;
+  runtimeVersion?: string;
+  createdAt?: string;
+  storagePrefix?: string;
+}
+
+function extractStoragePrefix(bundleKey: string): string | null {
+  // Bundle key format: releases/{branch}/{version}/{groupId}/{platform}/bundle.tar.br
+  // Storage prefix:    releases/{branch}/{version}/{groupId}
+  const match = bundleKey.match(/^(.+)\/web\/bundle\.tar\.br$/);
+  return match?.[1] ?? null;
+}
+
+export async function diagCommand(
+  positionalUrl: string | undefined,
+  flags: Record<string, string>,
+): Promise<void> {
+  const channel = flags.channel || 'production';
+
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // Build the URL: positional arg > baseUrl + --path
+  let url = positionalUrl;
+  if (!url) {
+    if (!config.baseUrl) {
+      fail('No URL provided and no baseUrl in config. Pass a URL or use --stage.');
+      process.exit(1);
+    }
+    url = config.baseUrl;
+  }
+  // Strip trailing slash from base URL before appending path
+  url = url.replace(/\/+$/, '');
+  if (flags.path) {
+    const p = flags.path.startsWith('/') ? flags.path : '/' + flags.path;
+    url = url + p;
+  }
+
+  // 1. Fetch the deployed page
+  const checkHydration = flags.hydration === 'true' || flags.hydration === '1';
+  const method = checkHydration ? 'GET' : 'HEAD';
+
+  step(`Fetching ${url}...`);
+  let diag: DiagResult;
+  let html: string | undefined;
+  try {
+    const response = await fetch(url, {
+      method,
+      redirect: 'follow',
+    });
+    diag = {
+      url,
+      status: response.status,
+      statusText: response.statusText,
+      cacheStatus: response.headers.get('x-cache') ?? undefined,
+      cacheAge: response.headers.get('age') ?? undefined,
+      cacheControl: response.headers.get('cache-control') ?? undefined,
+      bundleKey: response.headers.get('x-bundle-key') ?? undefined,
+      updateId: response.headers.get('x-update-id') ?? undefined,
+      runtimeVersion: response.headers.get('x-runtime-version') ?? undefined,
+      releaseCreated: response.headers.get('x-release-created') ?? undefined,
+    };
+
+    // Fetch full HTML if hydration analysis requested
+    if (checkHydration) {
+      html = await response.text();
+    }
+  } catch (err: any) {
+    fail(`Failed to fetch ${url}: ${err.message}`);
+    info('Check the URL is correct and includes the protocol (https://).');
+    process.exit(1);
+  }
+
+  // 2. Fetch the latest manifest from S3
+  step(`Reading latest ${channel} manifest from S3...`);
+  let manifest: Manifest | null = null;
+  try {
+    const manifestKey = `${channel}/web/manifest.json`;
+    const data = await getFromS3(config.region, config.updatesBucket, manifestKey);
+    if (data) {
+      manifest = JSON.parse(data.toString('utf8'));
+    }
+  } catch {
+    // Non-fatal — report what we have
+  }
+
+  // 3. Compare and report
+  console.log('');
+  console.log('  Diagnostic Report');
+  console.log('  ============================================================');
+  console.log('');
+  console.log(`  URL:              ${diag.url}`);
+  console.log(`  Status:           ${diag.status} ${diag.statusText}`);
+  console.log('');
+
+  // CDN info
+  if (diag.cacheStatus) {
+    console.log(`  CDN Cache:        ${diag.cacheStatus}`);
+  }
+  if (diag.cacheAge) {
+    console.log(`  Cache Age:        ${diag.cacheAge}s`);
+  }
+  if (diag.cacheControl) {
+    console.log(`  Cache-Control:    ${diag.cacheControl}`);
+  }
+  if (diag.cacheStatus || diag.cacheAge || diag.cacheControl) {
+    console.log('');
+  }
+
+  // Served release info
+  if (diag.bundleKey) {
+    console.log(`  Bundle Key:       ${diag.bundleKey}`);
+  }
+  if (diag.updateId) {
+    console.log(`  Update ID:        ${diag.updateId}`);
+  }
+  if (diag.runtimeVersion) {
+    console.log(`  Runtime Version:  ${diag.runtimeVersion}`);
+  }
+  if (diag.releaseCreated) {
+    console.log(`  Release Created:  ${diag.releaseCreated}`);
+  }
+  if (!diag.bundleKey && !diag.updateId) {
+    warn('  No release headers found. Update @everystack/server to get version headers on SSR responses.');
+  }
+  console.log('');
+
+  // Latest manifest info
+  if (manifest) {
+    console.log(`  Latest (${channel}):`);
+    if (manifest.updateId) {
+      console.log(`    Update ID:      ${manifest.updateId}`);
+    }
+    if (manifest.runtimeVersion) {
+      console.log(`    Runtime Ver:    ${manifest.runtimeVersion}`);
+    }
+    if (manifest.createdAt) {
+      console.log(`    Created At:     ${manifest.createdAt}`);
+    }
+    if (manifest.storagePrefix) {
+      console.log(`    Storage Prefix: ${manifest.storagePrefix}`);
+    }
+  } else {
+    warn(`  No manifest found in S3 for channel "${channel}".`);
+    info('  Run `everystack update` to publish a release first.');
+  }
+
+  console.log('');
+  console.log('  ------------------------------------------------------------');
+
+  // 4. Version comparison
+  if (!manifest) {
+    warn('  Cannot compare: no manifest available.');
+  } else if (diag.updateId && manifest.updateId) {
+    // Primary comparison: updateId
+    if (diag.updateId === manifest.updateId) {
+      success('  Version match: serving the latest release');
+    } else {
+      fail(`  Version mismatch: serving ${diag.updateId}, latest is ${manifest.updateId}`);
+      info('  Run `everystack cache:purge --origin web` to bust the CDN cache.');
+    }
+  } else if (diag.bundleKey && manifest.storagePrefix) {
+    // Fallback comparison: storagePrefix from bundle key
+    const servedPrefix = extractStoragePrefix(diag.bundleKey);
+    if (servedPrefix && servedPrefix === manifest.storagePrefix) {
+      success('  Version match: serving the latest release (matched via bundle key)');
+    } else if (servedPrefix) {
+      fail(`  Version mismatch: serving ${servedPrefix}, latest is ${manifest.storagePrefix}`);
+      info('  Run `everystack cache:purge --origin web` to bust the CDN cache.');
+    } else {
+      warn('  Cannot determine served version from bundle key.');
+    }
+  } else {
+    warn('  Cannot compare: missing version headers. Update @everystack/server to emit release metadata.');
+  }
+
+  console.log('');
+
+  // 5. Hydration analysis (if requested)
+  if (html) {
+    console.log('  ------------------------------------------------------------');
+    console.log('');
+    step('Analyzing SSR hydration...');
+
+    const cacheAge = diag.cacheAge ? parseInt(diag.cacheAge, 10) : undefined;
+    const analysis = analyzeHtml(html, cacheAge);
+    const report = generateHydrationReport(analysis);
+
+    console.log('');
+    console.log(report);
+    console.log('');
+
+    if (analysis.issues.length > 0) {
+      info('  Use these findings to identify type mismatches, timezone issues, and');
+      info('  relative time rendering that may cause hydration errors in production.');
+    }
+    console.log('');
+  } else if (checkHydration) {
+    info('  Hydration analysis skipped: no HTML content received.');
+    console.log('');
+  }
+}

package/src/cli/commands/logs.ts

@@ -0,0 +1,282 @@
+/**
+ * Logs commands — query application logs and tail CloudWatch logs.
+ *
+ * These commands help debug production issues by accessing:
+ * - Application logs stored in the database (logs:errors)
+ * - Lambda container logs from CloudWatch (logs:tail)
+ */
+
+import { resolveConfig } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { step, success, fail, info } from '../output.js';
+
+export async function logsErrorsCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${config.apiFunctionName}`);
+
+  const limit = flags.limit ? parseInt(flags.limit, 10) : 20;
+  const source = flags.source;
+  const level = flags.level || 'error'; // error or fatal
+
+  step(`Fetching last ${limit} ${level} logs...`);
+
+  try {
+    const result: any = await invokeAction(
+      config.region,
+      config.apiFunctionName,
+      'logs:errors',
+      { limit, source, level },
+    );
+
+    if (result?.error) {
+      fail(`Failed to fetch errors: ${result.error}`);
+      process.exit(1);
+    }
+
+    const errors = result.errors || [];
+
+    if (errors.length === 0) {
+      success('No errors found!');
+      return;
+    }
+
+    const sourceLabel = result.source === 's3' ? ' (s3)' : '';
+    success(`Found ${errors.length} ${level} log(s)${sourceLabel}:\n`);
+
+    // Format and display errors
+    for (const error of errors) {
+      console.log(`[${error.timestamp}] ${error.level.toUpperCase()}`);
+      console.log(`Source: ${error.source || 'unknown'}`);
+      console.log(`Message: ${error.message}`);
+
+      if (error.traceId) {
+        console.log(`TraceID: ${error.traceId}`);
+      }
+
+      if (error.userId) {
+        console.log(`UserID: ${error.userId}`);
+      }
+
+      if (error.error) {
+        console.log(`Error: ${error.error.name}: ${error.error.message}`);
+        if (error.error.stack) {
+          console.log(`Stack:\n${error.error.stack.split('\n').slice(0, 5).join('\n')}`);
+        }
+      }
+
+      if (error.data) {
+        console.log(`Data: ${JSON.stringify(error.data, null, 2)}`);
+      }
+
+      console.log('---\n');
+    }
+  } catch (err: any) {
+    fail(`Failed to fetch errors: ${err.message}`);
+    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    process.exit(1);
+  }
+}
+
+export async function logsTailCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${config.apiFunctionName}`);
+
+  const filterPattern = flags.filter;
+  const since = flags.since || '5m'; // 5m, 1h, 1d
+
+  step(`Tailing logs (filter: ${filterPattern || 'none'}, since: ${since})...`);
+
+  try {
+    // Import AWS SDK dynamically
+    const { CloudWatchLogsClient, FilterLogEventsCommand, DescribeLogStreamsCommand } =
+      await import('@aws-sdk/client-cloudwatch-logs');
+
+    const client = new CloudWatchLogsClient({ region: config.region });
+
+    // Determine log group name from function name
+    const logGroupName = `/aws/lambda/${config.apiFunctionName}`;
+
+    // Parse since duration to milliseconds
+    const sinceMs = parseDuration(since);
+    const startTime = Date.now() - sinceMs;
+
+    success(`Streaming logs from ${logGroupName}...\n`);
+
+    // Poll for new logs every 2 seconds
+    let nextToken: string | undefined;
+    let lastTimestamp = startTime;
+
+    const poll = async () => {
+      try {
+        const params: any = {
+          logGroupName,
+          startTime: lastTimestamp,
+          filterPattern,
+        };
+
+        if (nextToken) {
+          params.nextToken = nextToken;
+        }
+
+        const response = await client.send(new FilterLogEventsCommand(params));
+
+        if (response.events && response.events.length > 0) {
+          for (const event of response.events) {
+            if (event.timestamp && event.timestamp > lastTimestamp) {
+              lastTimestamp = event.timestamp;
+            }
+
+            const timestamp = event.timestamp
+              ? new Date(event.timestamp).toISOString()
+              : '';
+            const message = event.message || '';
+
+            console.log(`[${timestamp}] ${message.trimEnd()}`);
+          }
+        }
+
+        nextToken = response.nextToken;
+
+        // Continue polling
+        setTimeout(poll, 2000);
+      } catch (err: any) {
+        if (err.name === 'ResourceNotFoundException') {
+          fail(`Log group not found: ${logGroupName}`);
+          info('The Lambda function may not have been invoked yet.');
+          process.exit(1);
+        }
+        throw err;
+      }
+    };
+
+    await poll();
+  } catch (err: any) {
+    fail(`Failed to tail logs: ${err.message}`);
+    info('Ensure your IAM user/role has logs:FilterLogEvents permission.');
+    process.exit(1);
+  }
+}
+
+export async function logsQueryCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${config.apiFunctionName}`);
+
+  // Build query parameters
+  const query: Record<string, any> = {
+    limit: flags.limit ? parseInt(flags.limit, 10) : 50,
+  };
+
+  if (flags.level) query.level = flags.level;
+  if (flags.source) query.source = flags.source;
+  if (flags.traceId) query.traceId = flags.traceId;
+  if (flags.userId) query.userId = flags.userId;
+  if (flags.deviceId) query.deviceId = flags.deviceId;
+  if (flags.sessionId) query.sessionId = flags.sessionId;
+  if (flags.platform) query.platform = flags.platform;
+  if (flags.environment) query.environment = flags.environment;
+  if (flags.search) query.search = flags.search;
+  if (flags.since) query.since = flags.since;
+
+  step(`Querying logs with filters: ${JSON.stringify(query)}...`);
+
+  try {
+    const result: any = await invokeAction(
+      config.region,
+      config.apiFunctionName,
+      'logs:query',
+      query,
+    );
+
+    if (result?.error) {
+      fail(`Failed to query logs: ${result.error}`);
+      process.exit(1);
+    }
+
+    const logs = result.logs || [];
+
+    if (logs.length === 0) {
+      success('No logs found matching the criteria.');
+      return;
+    }
+
+    const sourceLabel = result.source === 's3' ? ' (s3)' : '';
+    success(`Found ${logs.length} log(s)${sourceLabel}:\n`);
+
+    // Format and display logs
+    for (const log of logs) {
+      const timestamp = new Date(log.timestamp).toISOString();
+      const level = (log.level || 'info').toUpperCase().padEnd(5);
+
+      console.log(`[${timestamp}] ${level} ${log.source || 'unknown'}`);
+      console.log(`  ${log.message || '(no message)'}`);
+
+      if (log.traceId) {
+        console.log(`  TraceID: ${log.traceId}`);
+      }
+
+      if (log.userId) {
+        console.log(`  UserID: ${log.userId}`);
+      }
+
+      if (log.deviceId) {
+        console.log(`  DeviceID: ${log.deviceId}`);
+      }
+
+      if (log.error) {
+        console.log(`  Error: ${log.error.name}: ${log.error.message}`);
+      }
+
+      if (log.data && Object.keys(log.data).length > 0) {
+        console.log(`  Data: ${JSON.stringify(log.data, null, 2).split('\n').join('\n  ')}`);
+      }
+
+      console.log('');
+    }
+  } catch (err: any) {
+    fail(`Failed to query logs: ${err.message}`);
+    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    process.exit(1);
+  }
+}
+
+function parseDuration(duration: string): number {
+  const match = duration.match(/^(\d+)([smhd])$/);
+  if (!match) {
+    return 5 * 60 * 1000; // Default: 5 minutes
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  switch (unit) {
+    case 's': return value * 1000;
+    case 'm': return value * 60 * 1000;
+    case 'h': return value * 60 * 60 * 1000;
+    case 'd': return value * 24 * 60 * 60 * 1000;
+    default: return 5 * 60 * 1000;
+  }
+}