Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

11.8 KB
Raw Blame
#!/usr/bin/env node
/**
 * Refuse to build when a Node-only module has leaked into the BROWSER bundle.
 *
 * Why this exists
 * ---------------
 * `api/` is server code and `src/` is browser code, but a handful of `src/`
 * modules legitimately reuse a shared helper from `api/_lib/` (SNS resolution,
 * BNB chain clients, vault message signing). That shortcut is only safe while
 * the helper it reaches stays free of Node built-ins — and nothing enforced it.
 *
 * On 2026-07-29 `api/_lib/solana/connection.js` gained a top-level
 * `import { cacheGet, cacheSet } from '../cache.js'` for a fleet-wide RPC
 * breaker. `api/_lib/cache.js` statically imports `node:zlib` and `node:util`,
 * and connection.js is reachable from a real browser entry:
 *
 *   public/agent/index.html
 *     → src/agent-skills.js → src/agent-skills-pumpfun.js
 *     → src/solana/sns.js → api/_lib/solana/connection.js → api/_lib/cache.js
 *
 * `npm run build` died with `"promisify" is not exported by
 * "__vite-browser-external"` after four minutes — AFTER the vite step had
 * already wiped `dist/`. Every deploy was blocked until it was traced by hand.
 *
 * This walks the same graph the bundler does, starting from the HTML entries,
 * and fails with the exact import chain the moment a `node:` built-in becomes
 * reachable. It runs in milliseconds, before anything is built or destroyed.
 *
 * The fix at the other end is usually not "make the helper browser-safe" but
 * "do not reach L2 from a browser at all": load the server-only piece lazily
 * behind a `typeof window === 'undefined'` check, so the browser keeps a
 * correct local-only behaviour and the bundler never sees the built-in.
 *
 * Usage:
 *   node scripts/check-browser-graph.mjs          # exits 1 on any leak
 */

import { readFileSync, existsSync } from 'node:fs';
import { dirname, resolve, relative } from 'node:path';
import { execFileSync } from 'node:child_process';

const ROOT = resolve(new URL('..', import.meta.url).pathname);

// Built-ins that have no browser implementation. `node:`-prefixed specifiers are
// unambiguous; bare 'fs'/'path' style imports are caught by the same list.
const NODE_BUILTINS = new Set([
	'assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'crypto', 'dgram',
	'dns', 'fs', 'http', 'http2', 'https', 'module', 'net', 'os', 'path', 'perf_hooks',
	'process', 'readline', 'repl', 'stream', 'string_decoder', 'tls', 'tty', 'url',
	'util', 'v8', 'vm', 'worker_threads', 'zlib',
]);

// `node:crypto`, `node:buffer` and `node:process` have real browser shims that
// vite/rollup substitute cleanly (vite-plugin-node-polyfills is configured), so
// they are not build breakers. Everything else is.
const POLYFILLED = new Set(['crypto', 'buffer', 'process', 'stream', 'util/types']);

function tracked(patterns) {
	return execFileSync('git', ['ls-files', ...patterns], { cwd: ROOT, encoding: 'utf8' })
		.split('\n')
		.filter(Boolean)
		.map((f) => resolve(ROOT, f))
		.filter((f) => existsSync(f)); // a tracked-but-deleted path is not our problem
}

// Three shapes, in order: a static `import`/`export ... from '...'` (the name
// clause may span lines, so newlines are allowed between the keyword and
// `from`. A `[^'"\n]` class here silently skipped every multi-line import,
// which is most of them in this repo and hid 44 real edges), a dynamic
// `import('...')`, and a bare side-effect `import '...'`.
const IMPORT_RE =
	/(?:^|\n)\s*(?:import|export)\b[^'"]*?from\s*['"]([^'"]+)['"]|(?:^|[^.\w])import\(\s*['"]([^'"]+)['"]\s*\)|(?:^|\n)\s*import\s*['"]([^'"]+)['"]/g;

/**
 * Every specifier `file` imports, tagged static vs dynamic.
 *
 * The distinction matters for BUILT-IN specifiers only. A STATIC
 * `import { promisify } from 'node:util'` is what breaks the build: rollup
 * swaps the module for __vite-browser-external and then rejects the named
 * export. A DYNAMIC `await import('node:util')` is the sanctioned escape hatch
 * (api/_lib/cache.js uses it): it stays an external dynamic import with no
 * module-level named bindings to check, and it only evaluates on the server
 * path that actually calls it. So dynamic BUILT-IN imports are not leaks.
 *
 * A dynamic import of a LOCAL module is a different thing entirely and IS
 * followed. Rollup resolves and binds it like any other module, so a
 * `typeof window === 'undefined'` guard around
 * `import('../brownout/index.js')` stops the browser from evaluating it but not
 * the bundler from binding its `import { AsyncLocalStorage } from
 * 'node:async_hooks'`. That is the exact shape that broke build:lib:full and
 * then `vite build` on 2026-08-28.
 */
function specifiersOf(file) {
	let src;
	try { src = readFileSync(file, 'utf8'); } catch { return []; }
	const out = [];
	for (const m of src.matchAll(IMPORT_RE)) {
		if (m[1]) out.push({ spec: m[1], dynamic: false });
		else if (m[2]) out.push({ spec: m[2], dynamic: true });
		else if (m[3]) out.push({ spec: m[3], dynamic: false });
	}
	return out;
}

function resolveLocal(fromFile, spec) {
	let p = resolve(dirname(fromFile), spec);
	if (existsSync(p) && !p.endsWith('.js') && existsSync(resolve(p, 'index.js'))) return resolve(p, 'index.js');
	if (!existsSync(p) && existsSync(`${p}.js`)) p = `${p}.js`;
	return existsSync(p) ? p : null;
}

function builtinName(spec) {
	const bare = spec.startsWith('node:') ? spec.slice(5) : spec;
	const root = bare.split('/')[0];
	return NODE_BUILTINS.has(root) ? root : null;
}

// ── Two browser targets, two graphs ──────────────────────────────────────────
// `npm run build:gcp` builds the browser twice, and this script has to cover
// both or it only half-guards the deploy:
//
//   app  vite build → dist/, seeded by the HTML pages AND the extra JS entries
//        in appConfig's rollupOptions.input (footer-bot, notifications, i18n
//        and friends), which are entry points no HTML file references.
//   lib  dist-lib/agent-3d.js, the <agent-3d> CDN embed, seeded by
//        build.lib.entry alone.
//
// On 2026-08-28 both broke on the same leak and neither was covered:
// api/_lib/brownout/ (node:async_hooks) was reachable through a server-guarded
// dynamic import, and the build died with `"AsyncLocalStorage" is not exported
// by "__vite-browser-external"`.

/**
 * @param {{label: string, seeds: () => Array<[string, string]>}} target
 *   seeds() yields [absolute file, human-readable origin] pairs.
 */
function walk(target) {
	const parent = new Map();
	const queue = [];
	const leaks = [];

	function enqueue(file, from) {
		if (parent.has(file)) return;
		parent.set(file, from);
		queue.push(file);
	}

	function chainTo(file) {
		const chain = [];
		let cur = file;
		while (cur && typeof cur === 'string' && cur.startsWith('/')) {
			chain.unshift(relative(ROOT, cur));
			cur = parent.get(cur);
		}
		if (cur) chain.unshift(cur);
		return chain;
	}

	for (const [file, from] of target.seeds()) enqueue(file, from);

	while (queue.length) {
		const file = queue.shift();
		for (const { spec, dynamic } of specifiersOf(file)) {
			const builtin = builtinName(spec);
			if (builtin) {
				// Dynamic is the sanctioned escape hatch for a built-in, and only
				// for a built-in: it stays external with nothing to bind.
				if (!dynamic && !POLYFILLED.has(builtin)) {
					leaks.push({ file, spec, chain: chainTo(file) });
				}
				continue;
			}
			if (!spec.startsWith('.')) continue; // bare package, the bundler's problem and not ours
			// Local edges are followed whether static or dynamic: rollup binds both.
			const next = resolveLocal(file, spec);
			if (next) enqueue(next, file);
		}
	}

	return { parent, leaks };
}

function htmlSeeds() {
	const out = [];
	for (const html of tracked(['pages/**/*.html', 'public/**/*.html', '*.html'])) {
		let src;
		try { src = readFileSync(html, 'utf8'); } catch { continue; }
		const label = relative(ROOT, html);
		for (const m of src.matchAll(/<script[^>]+src=["']([^"']+)["']/g)) {
			const spec = m[1];
			if (/^(https?:)?\/\//.test(spec)) continue;
			const abs = spec.startsWith('/')
				? resolve(ROOT, spec.slice(1))
				: resolve(dirname(html), spec);
			if (existsSync(abs)) out.push([abs, label]);
		}
		for (const m of src.matchAll(IMPORT_RE)) {
			const spec = m[1] || m[2] || m[3];
			if (!spec || /^(https?:)?\/\//.test(spec)) continue;
			const abs = spec.startsWith('/')
				? resolve(ROOT, spec.slice(1))
				: resolveLocal(html, spec);
			if (abs && existsSync(abs)) out.push([abs, label]);
		}
	}
	return out;
}

// Extra rollup entries, read out of the config rather than restated here: a
// hand-copied list goes stale the first time someone adds an entry, and an
// entry nobody walks is a leak nobody sees. Everything inside the `input: {`
// block, which is `resolve(__dirname, '<path>')` for every entry.
function configEntries() {
	const config = readFileSync(resolve(ROOT, 'vite.config.js'), 'utf8');
	const block = /\n\t*input: \{\n([\s\S]*?)\n\t*\},\n/.exec(config);
	if (!block) return [];
	const out = [];
	// Whitespace-tolerant: a formatter wrapping one long entry across lines must
	// not quietly drop that page's module graph from the walk.
	for (const m of block[1].matchAll(/resolve\(\s*__dirname,\s*'([^']+)'\s*,?\s*\)/g)) {
		const abs = resolve(ROOT, m[1]);
		if (existsSync(abs)) out.push([abs, `vite.config.js input: ${m[1]}`]);
	}
	return out;
}

// build.lib.entry in vite.config.js. Checked, not silently skipped: if the
// entry is ever renamed, this script must fail loudly rather than quietly stop
// covering the CDN bundle.
const LIB_ENTRY = resolve(ROOT, 'src/lib.js');
if (!existsSync(LIB_ENTRY)) {
	console.error(`check:browser-graph: lib entry ${relative(ROOT, LIB_ENTRY)} is missing.
It is build.lib.entry in vite.config.js; update this script if it moved.`);
	process.exit(1);
}

const TARGETS = [
	{ label: 'app (dist/)', seeds: () => [...htmlSeeds(), ...configEntries()] },
	{ label: 'lib (dist-lib/agent-3d.js)', seeds: () => [[LIB_ENTRY, 'build.lib.entry']] },
];

const results = TARGETS.map((t) => ({ target: t, ...walk(t) }));
const failures = results.filter((r) => r.leaks.length);

if (!failures.length) {
	const seen = new Set();
	for (const r of results) for (const f of r.parent.keys()) seen.add(f);
	console.log(`check:browser-graph: no Node-only imports reachable from ${seen.size} browser modules across ${TARGETS.length} targets`);
	process.exit(0);
}

for (const { target, leaks } of failures) {
	// One report per (module, specifier); the shortest chain is the clearest.
	const byKey = new Map();
	for (const leak of leaks) {
		const key = `${relative(ROOT, leak.file)}::${leak.spec}`;
		const prev = byKey.get(key);
		if (!prev || leak.chain.length < prev.chain.length) byKey.set(key, leak);
	}

	console.error(`\ncheck:browser-graph: ${byKey.size} Node-only import(s) reachable from the ${target.label} bundle:\n`);
	for (const leak of byKey.values()) {
		console.error(`  ${relative(ROOT, leak.file)} imports "${leak.spec}"`);
		console.error(`    ${leak.chain.join('\n      -> ')}\n`);
	}
}

console.error(`This breaks the build (rollup resolves the built-in to
__vite-browser-external and fails on its named exports), and for the app target
it fails AFTER the vite step has wiped dist/.

Fix at the boundary, not with a polyfill: load the server-only module lazily
behind a server check, so the browser keeps correct local-only behaviour.

    let _mod = null;
    function serverOnly() {
      if (typeof window !== 'undefined') return null;
      if (!_mod) _mod = import('./server-only.js').catch(() => null);
      return _mod;
    }

That alone is not enough when the server-only module imports a built-in at its
own module scope: rollup binds a dynamically imported LOCAL module like any
other, so the specifier must also be unreadable to it. Build it at runtime, as
src/shared/failover-fetch.js and api/_lib/solana/connection.js do:

    const SPEC = ['.', 'server-only.js'].join('/');
    _mod = import(/* @vite-ignore */ SPEC).catch(() => null);
`);
process.exit(1);