@everystack/server 0.2.17 → 0.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -40,6 +40,10 @@
       "types": "./src/stubs.ts",
       "default": "./src/stubs.ts"
     },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "default": "./src/testing/index.ts"
+    },
     "./plugin": {
       "types": "./src/plugin.ts",
       "default": "./src/plugin.ts"
@@ -63,6 +67,7 @@
     "lint": "tsc --noEmit"
   },
   "peerDependencies": {
+    "esbuild": ">=0.20.0",
     "@aws-sdk/client-cloudfront-keyvaluestore": ">=3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",
@@ -76,6 +81,9 @@
     "sst": "4.13.1"
   },
   "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    },
     "@aws-sdk/client-cloudfront-keyvaluestore": {
       "optional": true
     },
@@ -113,6 +121,7 @@
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
     "drizzle-orm": "0.41.0",
+    "esbuild": "0.25.12",
     "jest": "29.7.0",
     "postgres": "3.4.9",
     "sst": "4.13.1",

package/src/testing/bundle-boundary.ts

@@ -0,0 +1,271 @@
+/**
+ * @everystack/server/testing — server bundle-boundary assertion.
+ *
+ * Fail-closed guard for the runtime boundary: bundles each server entry with
+ * esbuild and asserts that no client/native-only module (react, react-native,
+ * expo, d3, react-query, …) appears in the Node graph. A new leak turns CI red
+ * with the exact import chain, instead of bloating or crashing the Lambda in
+ * production.
+ *
+ * This replaces the fail-OPEN `clientStubs` denylist: the denylist only
+ * triggered at runtime; this triggers at build time, before merge.
+ *
+ * Usage (in an app's server test suite):
+ *
+ *   import { assertServerBundlesClean } from '@everystack/server/testing';
+ *
+ *   it('keeps client code out of the Lambda bundle', async () => {
+ *     await assertServerBundlesClean({
+ *       entries: ['server/api.ts', 'server/worker.ts', 'server/ops.ts'],
+ *     });
+ *   });
+ *
+ * Requires `esbuild` to be resolvable from the caller (it ships with SST, so
+ * any everystack app already has it). Declared as an optional peer.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Client/native-only packages that must never appear in a Node/Lambda bundle.
+ * This is the boundary invariant — owned here, NOT derived from `clientStubs`,
+ * so the stub denylist can be deleted without weakening the guard.
+ */
+export const CLIENT_ONLY_MODULES = [
+  'react',
+  'react-dom',
+  'react-native',
+  'react-native-web',
+  'react-native-safe-area-context',
+  'react-native-screens',
+  'expo',
+  'expo-router',
+  'expo-status-bar',
+  '@tanstack/react-query',
+];
+
+/** Package-name prefixes that are also forbidden (e.g. the d3 charting family). */
+export const CLIENT_ONLY_PREFIXES = ['d3-'];
+
+/**
+ * Infra deps that legitimately bundle into a Lambda. Externalized during the
+ * probe only to keep it fast and avoid resolving their (large) graphs — none
+ * reach the forbidden set, so excluding them cannot hide a leak.
+ */
+export const DEFAULT_INFRA_EXTERNAL = [
+  'sst',
+  'drizzle-orm',
+  'pg',
+  'postgres',
+  'sharp',
+  'heic-decode',
+  '@aws-sdk/*',
+  'aws-sdk',
+];
+
+export interface BoundaryLeak {
+  /** The forbidden module specifier that was imported (e.g. "react-native"). */
+  module: string;
+  /** Import chain from the entry to the file that imports it (display paths). */
+  chain: string[];
+}
+
+export interface BoundaryResult {
+  entry: string;
+  /** Total modules in the entry's graph (excluding externals). */
+  moduleCount: number;
+  leaks: BoundaryLeak[];
+  /** Set if esbuild failed to bundle the entry at all. */
+  bundleError?: string;
+}
+
+export interface BoundaryOptions {
+  /** Server entry files, absolute or relative to `cwd`. */
+  entries: string[];
+  /** Base dir for relative entries and resolution. Default: process.cwd(). */
+  cwd?: string;
+  /** Override the forbidden package list. Default: CLIENT_ONLY_MODULES. */
+  forbidden?: string[];
+  /** Override the forbidden prefix list. Default: CLIENT_ONLY_PREFIXES. */
+  forbiddenPrefixes?: string[];
+  /** Override the infra externals. Default: DEFAULT_INFRA_EXTERNAL. */
+  infraExternal?: string[];
+}
+
+/** Reduce an import specifier to its bare package name (handles scopes + subpaths). */
+function barePackage(spec: string): string {
+  if (spec.startsWith('@')) {
+    const [scope, name] = spec.split('/');
+    return name ? `${scope}/${name}` : scope;
+  }
+  return spec.split('/')[0];
+}
+
+function makeForbiddenMatcher(forbidden: string[], prefixes: string[]) {
+  const set = new Set(forbidden);
+  return (spec: string): boolean => {
+    const bare = barePackage(spec);
+    return set.has(bare) || prefixes.some((p) => bare.startsWith(p));
+  };
+}
+
+/** Resolve explicit `./foo.js` relative imports to `.ts` source (NodeNext style). */
+function jsToTsPlugin(): import('esbuild').Plugin {
+  return {
+    name: 'js-to-ts',
+    setup(build) {
+      build.onResolve({ filter: /^\.\.?\// }, (args) => {
+        if (!args.path.endsWith('.js')) return undefined;
+        const base = path.resolve(args.resolveDir, args.path.slice(0, -3));
+        for (const cand of [base + '.ts', base + '.tsx', path.join(base, 'index.ts')]) {
+          if (fs.existsSync(cand)) return { path: cand };
+        }
+        return undefined;
+      });
+    },
+  };
+}
+
+let esbuildPromise: Promise<typeof import('esbuild')> | undefined;
+async function loadEsbuild(): Promise<typeof import('esbuild')> {
+  if (!esbuildPromise) {
+    esbuildPromise = import('esbuild').catch(() => {
+      throw new Error(
+        "@everystack/server/testing requires 'esbuild' to be installed " +
+          '(it ships with SST). Add it as a devDependency to run the bundle-boundary assertion.',
+      );
+    });
+  }
+  return esbuildPromise;
+}
+
+const display = (p: string): string =>
+  p.replace(/^.*\/node_modules\//, '').replace(/^(\.\.\/)+/, '');
+
+/**
+ * Bundle each entry and report any forbidden modules in its graph.
+ *
+ * The forbidden set is externalized so the build always completes (esbuild
+ * cannot parse react-native's Flow syntax, so a real RN leak would otherwise
+ * throw before producing a metafile). Leaks are then read from the metafile's
+ * import graph, with the chain back to the entry.
+ */
+export async function analyzeServerBundles(opts: BoundaryOptions): Promise<BoundaryResult[]> {
+  const esbuild = await loadEsbuild();
+  const cwd = opts.cwd ?? process.cwd();
+  const forbidden = opts.forbidden ?? CLIENT_ONLY_MODULES;
+  const prefixes = opts.forbiddenPrefixes ?? CLIENT_ONLY_PREFIXES;
+  const infra = opts.infraExternal ?? DEFAULT_INFRA_EXTERNAL;
+  const isForbidden = makeForbiddenMatcher(forbidden, prefixes);
+
+  const results: BoundaryResult[] = [];
+  for (const rel of opts.entries) {
+    const entryPath = path.isAbsolute(rel) ? rel : path.resolve(cwd, rel);
+    if (!fs.existsSync(entryPath)) {
+      results.push({ entry: rel, moduleCount: 0, leaks: [], bundleError: 'entry not found' });
+      continue;
+    }
+    try {
+      const build = await esbuild.build({
+        entryPoints: [entryPath],
+        bundle: true,
+        platform: 'node',
+        format: 'esm',
+        metafile: true,
+        write: false,
+        logLevel: 'silent',
+        absWorkingDir: cwd,
+        // Externalize the forbidden set (exact names + prefix wildcards) so they
+        // stay as detectable import edges instead of being bundled. Without the
+        // wildcards a prefix-matched package (e.g. d3-scale) would be bundled and
+        // silently escape detection.
+        external: [...infra, ...forbidden, ...prefixes.map((p) => `${p}*`)],
+        plugins: [jsToTsPlugin()],
+      });
+      const inputs = build.metafile.inputs;
+      const keys = Object.keys(inputs);
+
+      // Leak edges: a bundled file that imports a forbidden (externalized) module.
+      const edges: { file: string; module: string }[] = [];
+      for (const [file, meta] of Object.entries(inputs)) {
+        for (const imp of meta.imports ?? []) {
+          if (isForbidden(imp.path)) edges.push({ file, module: imp.path });
+        }
+      }
+
+      // BFS from the entry to a leaking file, over the in-graph import edges.
+      const entryKey = keys.find((k) => path.resolve(cwd, k) === entryPath) ?? keys[0];
+      const adj = (f: string): string[] =>
+        (inputs[f]?.imports ?? []).map((i) => i.path).filter((p) => inputs[p]);
+      const chainTo = (target: string): string[] => {
+        const queue: string[][] = [[entryKey]];
+        const seen = new Set([entryKey]);
+        while (queue.length) {
+          const trail = queue.shift()!;
+          const head = trail[trail.length - 1];
+          if (head === target) return trail.map(display);
+          for (const next of adj(head)) {
+            if (!seen.has(next)) {
+              seen.add(next);
+              queue.push([...trail, next]);
+            }
+          }
+        }
+        return [display(target)];
+      };
+
+      const seenLeak = new Set<string>();
+      const leaks: BoundaryLeak[] = [];
+      for (const { file, module } of edges) {
+        const dedupe = `${file} -> ${module}`;
+        if (seenLeak.has(dedupe)) continue;
+        seenLeak.add(dedupe);
+        leaks.push({ module, chain: [...chainTo(file), module] });
+      }
+
+      results.push({ entry: rel, moduleCount: keys.length, leaks });
+    } catch (err) {
+      results.push({
+        entry: rel,
+        moduleCount: 0,
+        leaks: [],
+        bundleError: err instanceof Error ? err.message.split('\n')[0] : String(err),
+      });
+    }
+  }
+  return results;
+}
+
+/** Format a failing report into an actionable error message. */
+export function formatBoundaryFailure(results: BoundaryResult[]): string {
+  const lines: string[] = ['Client/native modules leaked into a server bundle:\n'];
+  for (const r of results) {
+    if (r.bundleError) {
+      lines.push(`  ❌ ${r.entry}: bundle error — ${r.bundleError}`);
+      continue;
+    }
+    if (!r.leaks.length) continue;
+    const mods = [...new Set(r.leaks.map((l) => l.module))];
+    lines.push(`  ❌ ${r.entry}: ${mods.length} forbidden module(s) — ${mods.join(', ')}`);
+    // One representative chain to make the fix obvious.
+    const sample = r.leaks[0];
+    lines.push(`     e.g. ${sample.chain.join('\n          -> ')}`);
+  }
+  lines.push('\nFix at the source: import the server-safe entry (e.g. /rpc, /config),');
+  lines.push('not the React barrel. See docs/bundle-size.md.');
+  return lines.join('\n');
+}
+
+/**
+ * Assert every server entry bundles free of client/native modules.
+ * Throws an aggregated, actionable error if any entry leaks or fails to build.
+ */
+export async function assertServerBundlesClean(opts: BoundaryOptions): Promise<BoundaryResult[]> {
+  const results = await analyzeServerBundles(opts);
+  const failed = results.filter((r) => r.bundleError || r.leaks.length > 0);
+  if (failed.length) {
+    throw new Error(formatBoundaryFailure(results));
+  }
+  return results;
+}

package/src/testing/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @everystack/server/testing — test-time guards for the runtime boundary.
+ */
+export {
+  assertServerBundlesClean,
+  analyzeServerBundles,
+  formatBoundaryFailure,
+  CLIENT_ONLY_MODULES,
+  CLIENT_ONLY_PREFIXES,
+  DEFAULT_INFRA_EXTERNAL,
+  type BoundaryOptions,
+  type BoundaryResult,
+  type BoundaryLeak,
+} from './bundle-boundary';
+
+export {
+  assertWebBundleClean,
+  analyzeWebBundle,
+  formatWebReport,
+  barePackageFromSource,
+  type WebBundleOptions,
+  type WebBundleAnalysis,
+  type PackageContribution,
+} from './web-bundle';

package/src/testing/web-bundle.ts

@@ -0,0 +1,266 @@
+/**
+ * @everystack/server/testing — web bundle guard.
+ *
+ * The client-side analog of assertServerBundlesClean, with a deliberate design
+ * choice: it maintains NO list of "native-only" packages. everystack can't know
+ * any given app's dependencies' web-capability, and such a list goes stale the
+ * moment a package adds web support. Instead the gate is list-free:
+ *
+ *   - SIZE BUDGET — total + largest-chunk uncompressed bytes (the parse-cost
+ *     metric). Pure numbers, never stale. This is the durable CI gate against
+ *     re-bloat.
+ *   - COMPOSITION REPORT — per-package attributed bytes, so a human can triage
+ *     "why is <package> on web?" The bundle size names the suspects, not a
+ *     registry.
+ *   - REGRESSION (app-local) — `expectAbsent`: packages THIS app declares it
+ *     keeps out of web (its shim keys + lazy-gated natives). The guard asserts
+ *     they stay absent. The only list is the app's, owned by the app.
+ *
+ * It reads the real Metro web output (`expo export --source-maps external
+ * --platform web`) + source maps and attributes generated bytes to source
+ * packages (a self-contained source-map-explorer). Attribution is an estimate
+ * (maps track UTF-16 columns, not bytes — drifts by ~multibyte chars); the size
+ * budget and `expectAbsent` checks are exact (file size + the map's `sources`).
+ *
+ * Usage (in an app's test suite, after an export):
+ *
+ *   import { assertWebBundleClean } from '@everystack/server/testing';
+ *   await assertWebBundleClean({
+ *     bundleDir: 'dist/client/_expo/static/js/web',
+ *     maxBytes: 6_500_000,                                  // the durable gate
+ *     expectAbsent: ['react-native-view-shot', '@rnmapbox/maps'], // THIS app's list
+ *   });
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const B64_INDEX: Record<string, number> = {};
+for (let i = 0; i < B64.length; i++) B64_INDEX[B64[i]] = i;
+
+/** Decode a base64-VLQ-encoded source-map segment into its integer fields. */
+function decodeVlqSegment(segment: string): number[] {
+  const result: number[] = [];
+  let value = 0;
+  let shift = 0;
+  for (const ch of segment) {
+    const digit = B64_INDEX[ch];
+    if (digit === undefined) return result;
+    const continuation = digit & 0x20;
+    value += (digit & 0x1f) << shift;
+    if (continuation) {
+      shift += 5;
+    } else {
+      const negate = value & 1;
+      value >>= 1;
+      result.push(negate ? -value : value);
+      value = 0;
+      shift = 0;
+    }
+  }
+  return result;
+}
+
+/** Reduce a source path to its bare package name (or '(app)' for non-node_modules). */
+export function barePackageFromSource(source: string): string {
+  const m = source.match(/node_modules\/((@[^/]+\/[^/]+)|[^/]+)/);
+  if (m) return m[1];
+  return '(app)';
+}
+
+export interface PackageContribution {
+  pkg: string;
+  bytes: number;
+  sourceFiles: number;
+}
+
+export interface WebBundleAnalysis {
+  totalBytes: number;
+  chunks: { file: string; bytes: number }[];
+  byPackage: PackageContribution[];
+  unmappedBytes: number;
+  /** Packages from `expectAbsent` that were found in the bundle (regressions). */
+  unexpected: { pkg: string; chunk: string; sourceFile: string }[];
+}
+
+export interface WebBundleOptions {
+  /** Directory containing the web JS chunks + their .map files. */
+  bundleDir: string;
+  /**
+   * Packages this app expects to be ABSENT from the web bundle — its own shim
+   * keys + lazy-gated natives. The guard flags any that appear. This is the
+   * app's regression list; everystack maintains none.
+   */
+  expectAbsent?: string[];
+  /** Fail if total JS exceeds this (uncompressed bytes — the parse-cost metric). */
+  maxBytes?: number;
+  /** Fail if any single chunk exceeds this. */
+  maxChunkBytes?: number;
+}
+
+/**
+ * Attribute generated bytes in one chunk to its source packages via the map.
+ * Mirrors source-map-explorer: for each generated line, each mapping segment
+ * owns the generated columns from its start to the next segment's start.
+ */
+function attributeChunk(
+  jsPath: string,
+  mapPath: string,
+): { byPackage: Map<string, { bytes: number; files: Set<string> }>; unmapped: number; total: number } {
+  const generated = fs.readFileSync(jsPath, 'utf8');
+  const map = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
+  const sources: string[] = map.sources || [];
+  const lines = generated.split('\n');
+
+  const byPackage = new Map<string, { bytes: number; files: Set<string> }>();
+  let unmapped = 0;
+  let total = 0;
+
+  // Absolute fields carried across the whole mappings string (per spec).
+  let srcIdx = 0;
+  const mappingLines = (map.mappings || '').split(';');
+
+  for (let lineNo = 0; lineNo < lines.length; lineNo++) {
+    const content = lines[lineNo].length;
+    const hasNewline = lineNo < lines.length - 1; // split() drops N-1 separators
+    total += content + (hasNewline ? 1 : 0);
+    if (hasNewline) unmapped += 1; // the separator newline is never mapped
+    const segs = (mappingLines[lineNo] || '').split(',').filter(Boolean);
+    if (!segs.length) {
+      unmapped += content;
+      continue;
+    }
+    // Decode this line's segments into [genCol, srcIdxForSeg].
+    let genCol = 0;
+    const decoded: { genCol: number; src: number | null }[] = [];
+    for (const seg of segs) {
+      const fields = decodeVlqSegment(seg);
+      if (!fields.length) continue;
+      genCol += fields[0];
+      if (fields.length >= 4) {
+        srcIdx += fields[1];
+        decoded.push({ genCol, src: srcIdx });
+      } else {
+        decoded.push({ genCol, src: null });
+      }
+    }
+    if (!decoded.length) {
+      unmapped += content;
+      continue;
+    }
+    // Bytes before the first segment are unmapped.
+    unmapped += decoded[0].genCol;
+    for (let i = 0; i < decoded.length; i++) {
+      const start = decoded[i].genCol;
+      const end = i + 1 < decoded.length ? decoded[i + 1].genCol : content;
+      const span = Math.max(0, end - start);
+      const src = decoded[i].src;
+      if (src === null || src < 0 || src >= sources.length) {
+        unmapped += span;
+        continue;
+      }
+      const pkg = barePackageFromSource(sources[src]);
+      let entry = byPackage.get(pkg);
+      if (!entry) {
+        entry = { bytes: 0, files: new Set() };
+        byPackage.set(pkg, entry);
+      }
+      entry.bytes += span;
+      entry.files.add(sources[src]);
+    }
+  }
+  return { byPackage, unmapped, total };
+}
+
+/** Analyze every chunk in bundleDir and roll up per-package contributions. */
+export function analyzeWebBundle(opts: WebBundleOptions): WebBundleAnalysis {
+  const dir = opts.bundleDir;
+  const expectAbsent = new Set(opts.expectAbsent ?? []);
+
+  const jsFiles = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.js') && fs.existsSync(path.join(dir, f + '.map')));
+
+  const rollup = new Map<string, { bytes: number; files: Set<string> }>();
+  const chunks: { file: string; bytes: number }[] = [];
+  const unexpected: { pkg: string; chunk: string; sourceFile: string }[] = [];
+  let totalBytes = 0;
+  let unmappedBytes = 0;
+
+  for (const f of jsFiles) {
+    const jsPath = path.join(dir, f);
+    const bytes = fs.statSync(jsPath).size;
+    chunks.push({ file: f, bytes });
+    totalBytes += bytes;
+    const { byPackage, unmapped } = attributeChunk(jsPath, path.join(dir, f + '.map'));
+    unmappedBytes += unmapped;
+    for (const [pkg, v] of byPackage) {
+      const r = rollup.get(pkg) ?? { bytes: 0, files: new Set<string>() };
+      r.bytes += v.bytes;
+      for (const sf of v.files) r.files.add(sf);
+      rollup.set(pkg, r);
+      if (expectAbsent.has(pkg)) {
+        unexpected.push({ pkg, chunk: f, sourceFile: [...v.files][0] });
+      }
+    }
+  }
+
+  const byPackage = [...rollup.entries()]
+    .map(([pkg, v]) => ({ pkg, bytes: v.bytes, sourceFiles: v.files.size }))
+    .sort((a, b) => b.bytes - a.bytes);
+
+  // Dedupe to one row per package.
+  const seen = new Set<string>();
+  const dedup = unexpected.filter((l) => (seen.has(l.pkg) ? false : seen.add(l.pkg)));
+
+  return { totalBytes, chunks: chunks.sort((a, b) => b.bytes - a.bytes), byPackage, unmappedBytes, unexpected: dedup };
+}
+
+const kb = (n: number) => (n / 1024).toFixed(1) + ' KB';
+const mb = (n: number) => (n / 1048576).toFixed(2) + ' MB';
+
+/** Human-readable composition + verdict report. */
+export function formatWebReport(a: WebBundleAnalysis, top = 15): string {
+  const out: string[] = [];
+  out.push(`Web bundle: ${mb(a.totalBytes)} across ${a.chunks.length} chunk(s)`);
+  for (const c of a.chunks.slice(0, 4)) out.push(`  ${mb(c.bytes).padStart(9)}  ${c.file}`);
+  out.push(`\nTop ${top} packages by attributed bytes:`);
+  for (const p of a.byPackage.slice(0, top)) {
+    out.push(`  ${kb(p.bytes).padStart(11)}  ${p.pkg}  (${p.sourceFiles} files)`);
+  }
+  if (a.unexpected.length) {
+    out.push(`\n❌ EXPECTED-ABSENT packages found in web (${a.unexpected.length}):`);
+    for (const l of a.unexpected) {
+      out.push(`  ${l.pkg}  → its shim/lazy-gate isn't working (${l.sourceFile})`);
+    }
+  }
+  return out.join('\n');
+}
+
+/**
+ * Assert the web bundle is under budget and free of regressions.
+ * Throws an actionable report (incl. the composition) on failure.
+ */
+export function assertWebBundleClean(opts: WebBundleOptions): WebBundleAnalysis {
+  const a = analyzeWebBundle(opts);
+  const problems: string[] = [];
+  if (a.unexpected.length) {
+    problems.push(
+      `${a.unexpected.length} expected-absent package(s) reappeared in web: ` +
+        a.unexpected.map((l) => l.pkg).join(', ') +
+        " — a shim or lazy-gate regressed.",
+    );
+  }
+  if (opts.maxBytes && a.totalBytes > opts.maxBytes) {
+    problems.push(`web bundle ${mb(a.totalBytes)} exceeds budget ${mb(opts.maxBytes)}.`);
+  }
+  if (opts.maxChunkBytes) {
+    const over = a.chunks.find((c) => c.bytes > opts.maxChunkBytes!);
+    if (over) problems.push(`chunk ${over.file} ${mb(over.bytes)} exceeds per-chunk budget ${mb(opts.maxChunkBytes)}.`);
+  }
+  if (problems.length) {
+    throw new Error('Web bundle guard failed:\n  - ' + problems.join('\n  - ') + '\n\n' + formatWebReport(a));
+  }
+  return a;
+}