@everystack/cli 0.3.3 → 0.3.4

package/src/cli/commands/bundle.ts

@@ -0,0 +1,452 @@
+/**
+ * `everystack bundle:analyze [dir]` — client web-bundle size + composition.
+ *
+ * Run after a web export with source maps:
+ *   npx expo export -p web --source-maps --output-dir dist
+ *   everystack bundle:analyze dist
+ *
+ * Config-free: the JS bundle is located by Expo convention, and composition is
+ * derived from the source map itself.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  measureChunks,
+  composeSourceMap,
+  formatBundleReport,
+  type ChunkInput,
+  type Composition,
+} from '../bundle.js';
+import {
+  scanSecretShapes,
+  extractBundleUrls,
+  extractAssetUrls,
+  extractExtraEnvKeys,
+  classifyPrivateEnvKeys,
+  scanSecretValue,
+  summarize,
+  type AuditFinding,
+} from '../bundle-audit.js';
+import {
+  scanAssetWeights,
+  scanTotalWeight,
+  scanJsWeight,
+  scanSourceMapsPresent,
+  scanDependencyWeight,
+  analyzeChunkBloat,
+  largestFiles,
+  formatBytes,
+  resolveWeightBudget,
+  classifyAsset,
+  DEFAULT_WEIGHT_BUDGET,
+  type AssetFile,
+  type WeightBudget,
+} from '../bundle-weight.js';
+import { resolveConfig } from '../config.js';
+import { fail, info, step, success, warn } from '../output.js';
+
+// Expo Router web export puts client chunks under client/_expo/...; a plain
+// `expo export` omits the client/ prefix. Convention, not config.
+const JS_DIR_CANDIDATES = [
+  'client/_expo/static/js/web',
+  '_expo/static/js/web',
+];
+
+function resolveJsDir(dir: string): string | null {
+  for (const candidate of JS_DIR_CANDIDATES) {
+    const abs = path.join(dir, candidate);
+    try {
+      if (fs.statSync(abs).isDirectory()) return abs;
+    } catch {
+      // try next candidate
+    }
+  }
+  return null;
+}
+
+export async function bundleAnalyzeCommand(
+  positional: string | undefined,
+  flags: Record<string, string>,
+): Promise<void> {
+  const dir = positional || flags.dir || 'dist';
+  const jsDir = resolveJsDir(dir);
+  if (!jsDir) {
+    fail(
+      `No client JS bundle found under ${dir} (looked for ${JS_DIR_CANDIDATES.join(', ')}).`,
+    );
+    info('Run `npx expo export -p web --source-maps --output-dir dist` first.');
+    process.exit(1);
+  }
+
+  step(`Analyzing client bundle in ${jsDir} ...`);
+  const files = fs.readdirSync(jsDir).filter((f) => f.endsWith('.js'));
+  if (files.length === 0) {
+    fail(`No .js chunks in ${jsDir}.`);
+    process.exit(1);
+  }
+
+  const chunks: ChunkInput[] = files.map((name) => ({
+    name,
+    buf: fs.readFileSync(path.join(jsDir, name)),
+  }));
+  const sized = measureChunks(chunks);
+
+  // Composition comes from the largest chunk's source map, when present.
+  let composition: Composition | null = null;
+  const mapPath = path.join(jsDir, sized[0].name + '.map');
+  if (fs.existsSync(mapPath)) {
+    try {
+      composition = composeSourceMap(JSON.parse(fs.readFileSync(mapPath, 'utf8')));
+    } catch (err: any) {
+      info(`(could not parse source map: ${err.message})`);
+    }
+  }
+
+  console.log('');
+  console.log(formatBundleReport(sized, composition).join('\n'));
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// bundle:audit — served-bundle secret-leak scan.
+// ---------------------------------------------------------------------------
+
+async function fetchText(
+  url: string,
+): Promise<{ ok: boolean; status: number; text: string; bytes: number }> {
+  const res = await fetch(url, { redirect: 'follow' });
+  const text = res.ok ? await res.text() : '';
+  const cl = Number(res.headers.get('content-length'));
+  const bytes = Number.isFinite(cl) && cl > 0 ? cl : Buffer.byteLength(text, 'utf8');
+  return { ok: res.ok, status: res.status, text, bytes };
+}
+
+/**
+ * Size of a remote asset via HEAD (Content-Length) — measures a large file
+ * (e.g. a 180MB JSON) without downloading it. Falls back to a ranged GET when
+ * the origin omits Content-Length on HEAD; null if neither works.
+ */
+async function headSize(url: string): Promise<number | null> {
+  try {
+    const head = await fetch(url, { method: 'HEAD', redirect: 'follow' });
+    const cl = Number(head.headers.get('content-length'));
+    if (head.ok && Number.isFinite(cl) && cl > 0) return cl;
+  } catch {
+    // fall through to ranged GET
+  }
+  try {
+    const res = await fetch(url, { headers: { Range: 'bytes=0-0' }, redirect: 'follow' });
+    const range = res.headers.get('content-range'); // e.g. "bytes 0-0/184000000"
+    const total = range && range.includes('/') ? Number(range.split('/')[1]) : NaN;
+    if (Number.isFinite(total) && total > 0) return total;
+    const cl = Number(res.headers.get('content-length'));
+    if (Number.isFinite(cl) && cl > 0) return cl;
+  } catch {
+    // give up — best-effort
+  }
+  return null;
+}
+
+/** Parse KEY=VALUE dotenv lines (operator-produced via `everystack secrets export`). */
+function parseDotenv(raw: string): { key: string; value: string }[] {
+  const out: { key: string; value: string }[] = [];
+  for (const line of raw.split('\n')) {
+    const m = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/);
+    if (!m) continue;
+    let value = m[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out.push({ key: m[1], value });
+  }
+  return out;
+}
+
+export interface BundleAuditResult {
+  findings: AuditFinding[];
+  chunkCount: number;
+  /** Biggest served/exported files, largest first — always shown, gate or not. */
+  largest?: AssetFile[];
+}
+
+/** Result-producing core, shared by the command wrapper and the `audit` capstone. */
+export async function runBundleAudit(
+  base: string,
+  opts: { valuesFrom?: string; weight?: boolean; budget?: WeightBudget } = {},
+): Promise<BundleAuditResult> {
+  step(`Fetching ${base} ...`);
+  const root = await fetchText(base);
+  if (!root.ok) {
+    throw new Error(`${base} returned HTTP ${root.status}.`);
+  }
+
+  // Discover client chunks from the HTML, then follow lazy chunks referenced
+  // inside the downloaded JS (Expo code-splitting). Convention-located.
+  const seen = new Set<string>();
+  const queue = extractBundleUrls(root.text);
+  const artifacts: { source: string; text: string }[] = [{ source: 'index.html', text: root.text }];
+  // Served file → byte size, for the weight scan (HTML + JS measured from the GET).
+  const sizes = new Map<string, number>([['index.html', root.bytes]]);
+  while (queue.length) {
+    const rel = queue.shift()!;
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    const chunk = await fetchText(`${base}/${rel}`);
+    if (!chunk.ok) {
+      warn(`could not fetch ${rel} (HTTP ${chunk.status})`);
+      continue;
+    }
+    artifacts.push({ source: rel, text: chunk.text });
+    sizes.set(rel, chunk.bytes);
+    for (const next of extractBundleUrls(chunk.text)) {
+      if (!seen.has(next)) queue.push(next);
+    }
+  }
+  step(`Scanning ${artifacts.length} artifact(s) (1 HTML + ${seen.size} JS chunk(s)) ...`);
+
+  const findings: AuditFinding[] = [];
+
+  // 1. Source maps must not be publicly served.
+  const firstChunk = [...seen][0];
+  if (firstChunk) {
+    const map = await fetchText(`${base}/${firstChunk}.map`);
+    if (map.ok) {
+      findings.push({
+        severity: 'fail',
+        check: 'source-map',
+        source: `${firstChunk}.map`,
+        detail: 'source map is publicly served — exposes original source + comments',
+      });
+    }
+  }
+
+  // 2. Generic secret shapes + 3. private (non-EXPO_PUBLIC) env keys in extra.
+  for (const a of artifacts) {
+    findings.push(...scanSecretShapes(a.text, a.source));
+    findings.push(...classifyPrivateEnvKeys(extractExtraEnvKeys(a.text), a.source));
+  }
+
+  // 4. Operator-run value canary (reads secret values; never run by Claude).
+  if (opts.valuesFrom) {
+    step(`Value canary against secrets in ${opts.valuesFrom} ...`);
+    const secrets = parseDotenv(fs.readFileSync(path.resolve(opts.valuesFrom), 'utf8'));
+    for (const { key, value } of secrets) {
+      for (const a of artifacts) {
+        const hit = scanSecretValue(a.text, key, value, a.source);
+        if (hit) findings.push(hit);
+      }
+    }
+  }
+
+  // 5. Weight/size gate over the *served* bundle. Static assets (images, data
+  // files) are discovered from the crawled text and sized via HEAD — a 180MB
+  // data file is gated without downloading it.
+  let largest: AssetFile[] | undefined;
+  if (opts.weight !== false) {
+    const budget = { ...DEFAULT_WEIGHT_BUDGET, ...(opts.budget || {}) };
+    const assetRefs = new Set<string>();
+    for (const a of artifacts) for (const u of extractAssetUrls(a.text)) assetRefs.add(u);
+    step(`Weighing ${seen.size} JS chunk(s) + ${assetRefs.size} static asset(s) ...`);
+    for (const rel of assetRefs) {
+      const size = await headSize(`${base}/${rel}`);
+      if (size != null) sizes.set(rel, size);
+    }
+    const files: AssetFile[] = [...sizes].map(([p, size]) => ({ path: p, size }));
+    findings.push(...scanAssetWeights(files, budget));
+    findings.push(...scanTotalWeight(files, budget));
+    findings.push(...scanJsWeight(files, budget));
+    // Name the data inlined into JS chunks (the most useful diagnosis).
+    for (const a of artifacts) {
+      if (classifyAsset(a.source) === 'js') {
+        findings.push(...analyzeChunkBloat(a.text, a.source, budget));
+      }
+    }
+    largest = largestFiles(files);
+  }
+
+  return { findings, chunkCount: seen.size, largest };
+}
+
+/** Print bundle-audit findings; returns the number of failures (fail severity). */
+export function reportBundleAudit(result: BundleAuditResult): number {
+  const { findings, chunkCount, largest } = result;
+  const { fail: fails, warn: warns } = summarize(findings);
+
+  // Always list the largest files — useful even when nothing trips a budget.
+  if (largest && largest.length) {
+    info(`Largest files (top ${largest.length}):`);
+    for (const f of largest) info(`  ${formatBytes(f.size).padStart(10)}  ${f.path}`);
+    console.log('');
+  }
+
+  if (findings.length === 0) {
+    success(`bundle:audit — clean. No leaks or weight issues across ${chunkCount} artifact(s).`);
+    return 0;
+  }
+  for (const f of findings) {
+    if (f.severity === 'fail') fail(`[${f.check}] ${f.source}: ${f.detail}`);
+    else warn(`[${f.check}] ${f.source}: ${f.detail}`);
+  }
+  console.log('');
+  const summary = `bundle:audit — ${fails} failure(s), ${warns} warning(s)`;
+  if (fails > 0) fail(summary);
+  else warn(summary);
+  return fails;
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem path — scan a local Expo export (leak + weight together).
+// ---------------------------------------------------------------------------
+
+/** Recursively list every file under `root` as {path (relative), size}. */
+export function walkExport(root: string): AssetFile[] {
+  const out: AssetFile[] = [];
+  const walk = (abs: string): void => {
+    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+      const childAbs = path.join(abs, entry.name);
+      if (entry.isDirectory()) {
+        walk(childAbs);
+      } else if (entry.isFile()) {
+        out.push({
+          path: path.relative(root, childAbs),
+          size: fs.statSync(childAbs).size,
+        });
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * Audit a local Expo export directory: weight/size gates over every file, plus
+ * the leak scanners over the on-disk HTML + JS text (no deploy/network needed).
+ * This is the gate the governance layer runs before publish.
+ */
+export async function runBundleWeightAudit(
+  dir: string,
+  opts: { budget?: WeightBudget; valuesFrom?: string } = {},
+): Promise<BundleAuditResult> {
+  const root = path.resolve(dir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`${dir} is not a directory — pass an Expo export output dir.`);
+  }
+  const budget = { ...DEFAULT_WEIGHT_BUDGET, ...(opts.budget || {}) };
+
+  const files = walkExport(root);
+  if (files.length === 0) throw new Error(`${dir} is empty — run \`npx expo export\` first.`);
+  step(`Scanning ${files.length} file(s) in ${dir} ...`);
+
+  const findings: AuditFinding[] = [];
+
+  // --- weight/size gates ---------------------------------------------------
+  findings.push(...scanAssetWeights(files, budget));
+  findings.push(...scanTotalWeight(files, budget));
+  findings.push(...scanJsWeight(files, budget));
+  findings.push(...scanSourceMapsPresent(files));
+
+  // --- leak gates over on-disk text (HTML + JS) ----------------------------
+  const textFiles = files.filter(
+    (f) => f.path.endsWith('.html') || classifyAsset(f.path) === 'js',
+  );
+  for (const f of textFiles) {
+    const text = fs.readFileSync(path.join(root, f.path), 'utf8');
+    findings.push(...scanSecretShapes(text, f.path));
+    findings.push(...classifyPrivateEnvKeys(extractExtraEnvKeys(text), f.path));
+    if (classifyAsset(f.path) === 'js') {
+      findings.push(...analyzeChunkBloat(text, f.path, budget));
+    }
+    if (opts.valuesFrom) {
+      const secrets = parseDotenv(fs.readFileSync(path.resolve(opts.valuesFrom), 'utf8'));
+      for (const { key, value } of secrets) {
+        const hit = scanSecretValue(text, key, value, f.path);
+        if (hit) findings.push(hit);
+      }
+    }
+  }
+
+  // --- dependency weight (best-effort, from the largest chunk's source map) -
+  const jsDir = resolveJsDir(root);
+  if (jsDir) {
+    const jsFiles = fs.readdirSync(jsDir).filter((f) => f.endsWith('.js'));
+    if (jsFiles.length) {
+      const sized = measureChunks(
+        jsFiles.map((name) => ({ name, buf: fs.readFileSync(path.join(jsDir, name)) })),
+      );
+      const mapPath = path.join(jsDir, sized[0].name + '.map');
+      if (fs.existsSync(mapPath)) {
+        try {
+          const composition = composeSourceMap(JSON.parse(fs.readFileSync(mapPath, 'utf8')));
+          findings.push(...scanDependencyWeight(composition, budget));
+        } catch {
+          // unparseable map — dep-weight is best-effort, skip silently
+        }
+      }
+    }
+  }
+
+  return { findings, chunkCount: files.length, largest: largestFiles(files) };
+}
+
+export async function bundleAuditCommand(
+  positional: string | undefined,
+  flags: Record<string, string>,
+): Promise<void> {
+  // Local-export mode: --dir <export> (or a positional that is a directory) runs
+  // leak + weight gates over the export on disk — no deploy needed.
+  const localDir =
+    flags.dir ||
+    (positional && fs.existsSync(positional) && fs.statSync(positional).isDirectory()
+      ? positional
+      : undefined);
+  if (localDir) {
+    let result: BundleAuditResult;
+    try {
+      result = await runBundleWeightAudit(localDir, {
+        budget: resolveWeightBudget(flags),
+        valuesFrom: flags['values-from'],
+      });
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+    console.log('');
+    process.exit(reportBundleAudit(result) > 0 ? 1 : 0);
+  }
+
+  let target = positional || flags.url;
+  if (!target) {
+    try {
+      target = (await resolveConfig(flags.stage)).baseUrl;
+    } catch (err: any) {
+      fail(err.message);
+      info('Pass a URL positionally or use --stage <name>.');
+      process.exit(1);
+    }
+  }
+  const base = target.replace(/\/+$/, '');
+
+  if (!flags['values-from'] && flags.values) {
+    info('Value canary: run `everystack secrets export --stage <name> > .env` then re-run with --values-from .env');
+    info('(everystack never reads secret values itself; the export is your explicit step.)');
+  }
+
+  let result: BundleAuditResult;
+  try {
+    result = await runBundleAudit(base, {
+      valuesFrom: flags['values-from'],
+      weight: !flags['leak-only'],
+      budget: resolveWeightBudget(flags),
+    });
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  console.log('');
+  process.exit(reportBundleAudit(result) > 0 ? 1 : 0);
+}

package/src/cli/commands/lighthouse.ts

@@ -0,0 +1,104 @@
+/**
+ * `everystack audit:lighthouse [--stage <name>] [--host <url>] [--runs N] [--path /]`
+ *
+ * Mobile Lighthouse audit (Perf / A11y / Best-Practices / SEO) reported as a
+ * distribution over N runs, because the Performance score swings run-to-run with
+ * LCP. Warms the CloudFront edge first, then measures the warm-HTML path.
+ *
+ * Config-free: the target URL is the deployed router URL from SST outputs
+ * (resolveConfig), or --host. Requires `npx lighthouse` and a headless Chrome.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  CATEGORIES,
+  extractRun,
+  aggregate,
+  formatLighthouseReport,
+  type ExtractedRun,
+  type LhReport,
+} from '../lighthouse.js';
+import { resolveConfig } from '../config.js';
+import { step, info, fail, warn } from '../output.js';
+
+function runLighthouse(url: string, outPath: string): LhReport {
+  // Warm the edge so we measure the real-user (cached-HTML) experience.
+  try {
+    execFileSync('curl', ['-s', '-o', '/dev/null', url], { timeout: 30_000 });
+  } catch {
+    // warming is best-effort
+  }
+  execFileSync(
+    'npx',
+    [
+      'lighthouse',
+      url,
+      `--only-categories=${CATEGORIES.join(',')}`,
+      '--chrome-flags=--headless=new --no-sandbox',
+      '--output=json',
+      `--output-path=${outPath}`,
+      '--quiet',
+    ],
+    { stdio: ['ignore', 'ignore', 'ignore'], timeout: 120_000 },
+  );
+  return JSON.parse(readFileSync(outPath, 'utf8'));
+}
+
+/** Run Lighthouse N times and return the per-run extracts. Shared with the
+ *  `audit` capstone. */
+export async function collectLighthouseRuns(url: string, runs: number): Promise<ExtractedRun[]> {
+  const tmp = mkdtempSync(join(tmpdir(), 'everystack-lh-'));
+  const extracts: ExtractedRun[] = [];
+  for (let i = 0; i < runs; i++) {
+    step(`Lighthouse run ${i + 1}/${runs} on ${url} ...`);
+    try {
+      const report = runLighthouse(url, join(tmp, `lh-${i}.json`));
+      extracts.push(extractRun(report));
+    } catch (err: any) {
+      warn(`run ${i + 1} failed: ${err.message?.split('\n')[0] ?? err}`);
+    }
+  }
+  return extracts;
+}
+
+export async function auditLighthouseCommand(flags: Record<string, string>): Promise<void> {
+  let host = flags.host;
+  if (!host) {
+    try {
+      const config = await resolveConfig(flags.stage);
+      host = config.baseUrl;
+    } catch (err: any) {
+      fail(err.message);
+      info('Pass --host <url> to audit a specific URL without resolving a stage.');
+      process.exit(1);
+    }
+  }
+  if (!host) {
+    fail('No URL to audit. Pass --host <url> or --stage <name>.');
+    process.exit(1);
+  }
+
+  const runs = flags.runs ? parseInt(flags.runs, 10) : 3;
+  const pathName = flags.path || '/';
+  const url = host.replace(/\/+$/, '') + (pathName.startsWith('/') ? pathName : '/' + pathName);
+
+  const extracts = await collectLighthouseRuns(url, runs);
+
+  if (extracts.length === 0) {
+    fail('All Lighthouse runs failed. Is `npx lighthouse` installed and Chrome available?');
+    process.exit(1);
+  }
+
+  const agg = aggregate(extracts);
+  console.log('');
+  console.log(formatLighthouseReport(url, extracts.length, agg).join('\n'));
+
+  if (flags.json) {
+    writeFileSync(flags.json, JSON.stringify(agg, null, 2));
+    info(`Raw results → ${flags.json}`);
+  }
+  process.exit(0);
+}