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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
/**
* Deploy-artifact pre-flight audit.
*
* Catches, in seconds, the two failure classes that took production down on
* 2026-06-11 (465 consecutive 500s + every deploy failing for 90 minutes):
*
* 1. Committed symlinks. Vercel's function bundler cannot resolve symlinks
* checked into the repo — data/skills/metamask-* (symlinks into
* .agents/skills/) failed every build after ~18 minutes of tracing with
* "File …/.agents/skills/metamask-agent-workflows does not exist",
* which kept the cron/avatar fixes from ever reaching production.
*
* 2. Unresolvable runtime imports. .npmrc sets legacy-peer-deps=true, so
* npm never auto-installs peer dependencies: when helius-sdk 3.0 moved
* @solana-program/stake to peerDependencies, the package silently
* vanished from the install tree and every /api/cron/* invocation died
* at module load with ERR_MODULE_NOT_FOUND. Two checks close that gap:
* a. every non-optional peerDependency in the production lock tree
* resolves (with a documented allowlist of known-unused peers);
* b. every bare import in api/**∕*.js is declared in package.json —
* phantom deps that only exist via hoisting disappear on dedupe.
*
* 3. An install tree that no longer matches the lockfile. The image is built
* with a clean install from package-lock.json, but every local test and
* every deploy worktree (which hardlinks this node_modules) runs whatever
* is on disk. When a dependency bump lands in the lockfile and nobody
* reinstalls, the suite keeps passing against the OLD version while
* production boots the NEW one. On 2026-09-17 that shipped
* @x402/extensions 2.25.0, whose resource-server extension throws at
* construction without an `origin`: api/_lib/siwx-server.js built it at
* module load, so every paidEndpoint() route, /api/mcp, the facilitator
* and /.well-known/x402 answered 500 while local tests (on 2.14.0)
* stayed green.
*
* 4. A workspace package.json that the lockfile does not describe. Renaming
* or bumping a workspace (packages/*, the SDKs) without regenerating
* package-lock.json leaves the local tree working, because the workspace
* is a symlink, while npm ci in the image refuses the whole install. On
* 2026-10-10 the rename of packages/three-ws-cli to @three-ws/cli failed
* the Docker step with "Missing: @three-ws/[email protected] from lock file".
*
* Runs standalone (`node scripts/audit-deploy-artifacts.mjs`), as phase 1 of
* scripts/build-vercel.mjs, and via tests/deploy-artifacts.test.js.
*/
import { execFileSync } from 'node:child_process';
import { readFileSync, existsSync, readdirSync } from 'node:fs';
import { builtinModules } from 'node:module';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { globSync } from 'glob';
import { init, parse } from 'es-module-lexer';
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
// ---------------------------------------------------------------------------
// 1. Committed symlinks
// ---------------------------------------------------------------------------
/**
* Returns the repo paths of every symlink in the git index (mode 120000).
* Local-only symlinks (e.g. .claude/skills/, created by setup-claude-skills.mjs)
* are gitignored and never appear here; anything that does appear will reach
* Vercel's checkout and break function tracing.
*/
export function findCommittedSymlinks({ cwd = ROOT } = {}) {
let out;
try {
out = execFileSync('git', ['ls-files', '-s'], {
cwd,
encoding: 'utf8',
maxBuffer: 64 * 1024 * 1024,
stdio: ['ignore', 'pipe', 'pipe'],
});
} catch {
// Vercel's build container has no .git directory, so the index is
// unavailable there. Committed symlinks materialize as real symlinks in
// the checkout, so scan the filesystem instead. Skipped dirs are the
// install-time symlink producers that never reach the git index
// (node_modules/.bin, setup-claude-skills.mjs → .claude/skills).
return findSymlinksOnDisk(cwd);
}
const symlinks = [];
for (const line of out.split('\n')) {
if (line.startsWith('120000 ')) {
symlinks.push(line.split('\t')[1]);
}
}
return symlinks;
}
const SYMLINK_SCAN_SKIP = new Set(['node_modules', '.git', '.claude', '.vercel', '.next']);
function findSymlinksOnDisk(root) {
const symlinks = [];
const stack = [''];
while (stack.length) {
const rel = stack.pop();
let entries;
try {
entries = readdirSync(resolve(root, rel), { withFileTypes: true });
} catch {
continue;
}
for (const entry of entries) {
if (SYMLINK_SCAN_SKIP.has(entry.name)) continue;
const entryRel = rel ? `${rel}/${entry.name}` : entry.name;
if (entry.isSymbolicLink()) symlinks.push(entryRel);
else if (entry.isDirectory()) stack.push(entryRel);
}
}
return symlinks.sort();
}
// ---------------------------------------------------------------------------
// 2. Unsatisfied peer dependencies in the production lock tree
// ---------------------------------------------------------------------------
// Known-unsatisfied peers verified unused at runtime (types-only packages,
// react-native in a web app, codegen CLIs, optional transports). Keyed as
// "<importer package name>|<peer name>" so npm dedupe moves don't churn the
// list. Anything NOT listed here fails the audit: either install the peer or,
// after verifying the code paths that need it are never reached, add it here
// with a justification.
const KNOWN_UNUSED_PEERS = new Set([
'@solana/pay|@solana-program/memo', // memo ix builder — we never attach memos via @solana/pay
'@solana/pay|@solana-program/token-2022', // token-2022 transfers unused (legacy SPL only)
'@solana/pay|@solana/kit-plugin-instruction-plan', // kit plugin paths unused
'@solana/pay|@solana/kit-plugin-payer', // kit plugin paths unused
'@solana/pay|@solana/kit-plugin-rpc', // kit plugin paths unused
'@hey-api/client-fetch|@hey-api/openapi-ts', // codegen CLI, build-time only
'@lit/react|@types/react', // types-only
'@recast-navigation/three|@types/three', // types-only
'@solana-mobile/mobile-wallet-adapter-protocol|react-native', // web build never hits RN paths
'@solana/codecs-strings|fastestsmallesttextencoderdecoder', // polyfill for envs without TextEncoder; Node has it
'@types/react-transition-group|@types/react', // types-only
'arweave-stream-tx|arweave', // arweave upload path unused
'colyseus|@colyseus/uwebsockets-transport', // we use the default WS transport
'livekit-client|@types/dom-mediacapture-record', // types-only
'react-native-webrtc|react-native', // web build never hits RN paths
'three-gpu-pathtracer|xatlas-web', // UVUnwrapper-only; we import WebGLPathTracer from the index, which never re-exports UVUnwrapper
'@web3auth/auth|color', // referenced only in whitelabel .d.ts type declarations, never imported in dist runtime code
'manifold-3d|esbuild-wasm', // only lib/bundler.js (the manifold-cad editor) imports esbuild; we load manifold.js, the core WASM kernel, which never touches it
]);
function packageNameFromLockPath(lockPath) {
const idx = lockPath.lastIndexOf('node_modules/');
return idx === -1 ? lockPath : lockPath.slice(idx + 'node_modules/'.length);
}
/**
* Walks package-lock.json and returns every non-optional peerDependency of a
* production package that does not resolve anywhere in the importer's
* node_modules ancestor chain. This is exactly the hole legacy-peer-deps
* opens: npm records the peer requirement but never installs it.
*/
export function findUnsatisfiedPeers({ lock } = {}) {
if (!lock) {
lock = JSON.parse(readFileSync(resolve(ROOT, 'package-lock.json'), 'utf8'));
}
const pkgs = lock.packages || {};
const problems = [];
for (const [path, info] of Object.entries(pkgs)) {
if (!path || info.link) continue;
if (info.dev || info.devOptional) continue;
const peers = info.peerDependencies || {};
const meta = info.peerDependenciesMeta || {};
for (const peer of Object.keys(peers)) {
if (meta[peer]?.optional) continue;
let found = false;
let base = path;
for (;;) {
const candidate = `${base ? `${base}/` : ''}node_modules/${peer}`;
if (pkgs[candidate]) {
found = true;
break;
}
const idx = base.lastIndexOf('node_modules/');
if (idx === -1) break;
base = base.slice(0, idx).replace(/\/$/, '');
}
if (!found && !pkgs[`node_modules/${peer}`]) {
const key = `${packageNameFromLockPath(path)}|${peer}`;
if (!KNOWN_UNUSED_PEERS.has(key)) {
problems.push({ importer: path, peer });
}
}
}
}
return problems;
}
// ---------------------------------------------------------------------------
// 3. Undeclared bare imports in api/
// ---------------------------------------------------------------------------
function bareSpecifierToPackageName(spec) {
const parts = spec.split('/');
return spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
}
function workspacePackageNames(rootPkg) {
const names = new Set();
for (const pattern of rootPkg.workspaces || []) {
for (const dir of globSync(pattern, { cwd: ROOT })) {
const manifest = resolve(ROOT, dir, 'package.json');
if (!existsSync(manifest)) continue;
try {
const { name } = JSON.parse(readFileSync(manifest, 'utf8'));
if (name) names.add(name);
} catch {
// unreadable workspace manifest — covered by npm install itself
}
}
}
return names;
}
/**
* Lexes every api/**∕*.js file (static AND literal dynamic imports) and
* returns bare specifiers whose package is not a Node builtin, not declared
* in package.json dependencies/optionalDependencies, and not a workspace
* package. Those imports work today only via hoisting from some transitive
* dependency — an upstream bump or dedupe deletes them with no signal until
* the function 500s at runtime.
*/
export async function findUndeclaredApiImports({ apiDir = resolve(ROOT, 'api') } = {}) {
await init;
const rootPkg = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf8'));
const declared = new Set([
...Object.keys(rootPkg.dependencies || {}),
...Object.keys(rootPkg.optionalDependencies || {}),
...workspacePackageNames(rootPkg),
]);
// A devDependency is declared, so it is not a phantom, and the Cloud Run image
// installs devDependencies. It is still only acceptable behind a dynamic
// import: those are lazy tooling paths (the x-content reviewer's browser and
// spell checker) that never run at module load, so they cannot take a handler
// down on import. A static import of one stays a failure.
const declaredDev = new Set(Object.keys(rootPkg.devDependencies || {}));
const builtins = new Set(builtinModules);
const problems = [];
// Test and test-config files under api/ run via vitest only; they are never
// part of a deployed function bundle, so their devDep imports are fine.
const files = globSync('**/*.js', {
cwd: apiDir,
absolute: true,
ignore: ['**/*.test.js', '**/vitest.config.js'],
});
for (const file of files) {
let imports;
try {
[imports] = parse(readFileSync(file, 'utf8'));
} catch (err) {
problems.push({ file, specifier: null, reason: `parse error: ${err.message}` });
continue;
}
for (const imp of imports) {
const spec = imp.specifier;
if (!spec) continue; // non-literal dynamic import
if (spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('node:')) continue;
const name = bareSpecifierToPackageName(spec);
if (builtins.has(name) || declared.has(name)) continue;
if (imp.type === 'dynamic' && declaredDev.has(name)) continue;
problems.push({
file,
specifier: spec,
reason: 'not declared in package.json dependencies',
});
}
}
return problems;
}
// ---------------------------------------------------------------------------
// 4. Critical static runtime assets in dist/
// ---------------------------------------------------------------------------
// The Draco/Basis decoder binaries are gitignored (regenerated from
// node_modules by scripts/copy-three-decoders.mjs at postinstall/prebuild),
// so nothing in git guarantees they reach the built dist/. The 2026-07-17
// production sweep found the whole /three/ decoder tree missing from the
// running image: /scene hard-failed and every Draco/KTX2-compressed GLB was
// one asset swap away from breaking. Assert their presence whenever a dist/
// exists (i.e. in any post-build / pre-deploy run).
export function findMissingDistAssets() {
const dist = resolve(ROOT, 'dist');
if (!existsSync(dist)) return { skipped: true, missing: [] };
const required = [
'three/draco/draco_decoder.wasm',
'three/draco/gltf/draco_decoder.wasm',
'three/basis/basis_transcoder.wasm',
// Scene Studio's <script src="/three/draco/draco_encoder.js"> (pages/scene.html)
// It shares the single decoder copy rather than carrying its own.
'three/draco/draco_encoder.js',
'scene-studio/basis/basis_transcoder.wasm',
];
return { skipped: false, missing: required.filter((p) => !existsSync(resolve(dist, p))) };
}
// ---------------------------------------------------------------------------
// 5. Install tree matches the lockfile
// ---------------------------------------------------------------------------
/**
* Compares every production package in package-lock.json with what is actually
* installed and returns the ones that differ: `stale` (a different version on
* disk) or `missing` (nothing on disk). Dev-only packages never reach the
* image, and optional ones are legitimately absent on a platform they do not
* target, so neither is reported.
*/
export function findLockDrift({ lock, root = ROOT } = {}) {
if (!lock) {
lock = JSON.parse(readFileSync(resolve(root, 'package-lock.json'), 'utf8'));
}
const drift = [];
for (const [path, info] of Object.entries(lock.packages || {})) {
if (!path.startsWith('node_modules/') || info.link) continue;
if (info.dev || info.devOptional) continue;
let installed = null;
try {
installed = JSON.parse(readFileSync(resolve(root, path, 'package.json'), 'utf8')).version;
} catch {
if (info.optional || info.peer) continue;
}
if (installed === info.version || String(installed).replace(/^v/, '') === info.version) continue;
drift.push({
path,
locked: info.version,
installed,
kind: installed === null ? 'missing' : 'stale',
});
}
return drift;
}
// ---------------------------------------------------------------------------
// 6. Every workspace package.json matches its lockfile entry
// ---------------------------------------------------------------------------
/**
* Returns each workspace whose package.json name or version differs from its
* package-lock.json entry, or that has no entry at all. npm ci rejects the
* install on any of these, so the image build would fail at the Docker step.
*/
export function findWorkspaceLockMismatch({ lock, pkg, root = ROOT } = {}) {
if (!lock) lock = JSON.parse(readFileSync(resolve(root, 'package-lock.json'), 'utf8'));
if (!pkg) pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
const entries = lock.packages || {};
const mismatches = [];
for (const dir of pkg.workspaces || []) {
let manifest;
try {
manifest = JSON.parse(readFileSync(resolve(root, dir, 'package.json'), 'utf8'));
} catch {
continue;
}
const locked = entries[dir];
if (!locked) {
mismatches.push({ dir, name: manifest.name, version: manifest.version, locked: null });
continue;
}
if (locked.name !== manifest.name || locked.version !== manifest.version) {
mismatches.push({
dir,
name: manifest.name,
version: manifest.version,
locked: `${locked.name}@${locked.version}`,
});
}
}
return mismatches;
}
// ---------------------------------------------------------------------------
// CLI
// ---------------------------------------------------------------------------
const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isMain) {
const start = Date.now();
let failed = false;
const symlinks = findCommittedSymlinks();
if (symlinks.length) {
failed = true;
console.error(
`[audit:deploy] FAIL — ${symlinks.length} committed symlink(s); Vercel's bundler cannot resolve them (broke every deploy after c96cdefd):`,
);
for (const s of symlinks) console.error(` ${s} → replace with a real copy of the target`);
}
const peers = findUnsatisfiedPeers();
if (peers.length) {
failed = true;
console.error(
`[audit:deploy] FAIL — ${peers.length} unsatisfied peer dependency(ies); legacy-peer-deps never installs peers, so these are missing at runtime (the @solana-program/stake outage):`,
);
for (const { importer, peer } of peers) {
console.error(
` ${importer} requires ${peer} → add "${peer}" to package.json dependencies (or allowlist in scripts/audit-deploy-artifacts.mjs after verifying it is unused)`,
);
}
}
const undeclared = await findUndeclaredApiImports();
if (undeclared.length) {
failed = true;
console.error(
`[audit:deploy] FAIL — ${undeclared.length} undeclared bare import(s) in api/; phantom deps vanish on dedupe:`,
);
for (const { file, specifier, reason } of undeclared) {
console.error(` ${file}: ${specifier ?? ''} (${reason})`);
}
}
const distAssets = findMissingDistAssets();
if (distAssets.skipped) {
console.log('[audit:deploy] note — no dist/ present, decoder-asset check skipped (run after build to enable)');
} else if (distAssets.missing.length) {
failed = true;
console.error(
`[audit:deploy] FAIL — ${distAssets.missing.length} critical decoder asset(s) missing from dist/ (the /scene draco outage): run npm install so copy-three-decoders.mjs regenerates public/three, then rebuild:`,
);
for (const m of distAssets.missing) console.error(` dist/${m}`);
}
const drift = findLockDrift();
if (drift.length) {
failed = true;
console.error(
`[audit:deploy] FAIL: ${drift.length} installed package(s) do not match package-lock.json, so local tests are not exercising the versions the image will run (the @x402/extensions 2.25.0 outage). Run \`npm install\`, then \`npm test\`, before deploying:`,
);
for (const d of drift.slice(0, 15)) {
console.error(` ${d.path} locked ${d.locked}, ${d.kind === 'missing' ? 'not installed' : `installed ${d.installed}`}`);
}
if (drift.length > 15) console.error(` ... and ${drift.length - 15} more`);
console.error(
' In a deploy worktree node_modules is hardlinked to the shared tree, so do not run npm install or npm ci there: it writes through the links. The shared tree is what drifted (often another agent installing against an uncommitted lockfile). Restore a missing package in the worktree only: `npm pack <name>@<locked version> --pack-destination /tmp`, then untar it into node_modules/<name> with --strip-components=1.',
);
}
const workspaceDrift = findWorkspaceLockMismatch();
if (workspaceDrift.length) {
failed = true;
console.error(
`[audit:deploy] FAIL: ${workspaceDrift.length} workspace package.json(s) disagree with package-lock.json, so npm ci in the image will refuse to install (the @three-ws/cli rename). Run \`npm install --package-lock-only --ignore-scripts\` in the shared tree and commit package-lock.json:`,
);
for (const w of workspaceDrift) {
console.error(` ${w.dir} is ${w.name}@${w.version}, lockfile has ${w.locked ?? 'no entry'}`);
}
}
const elapsed = ((Date.now() - start) / 1000).toFixed(1);
if (failed) {
console.error(`\n[audit:deploy] failed in ${elapsed}s`);
process.exit(1);
}
console.log(
`[audit:deploy] clean in ${elapsed}s: no committed symlinks, no unsatisfied peers, no undeclared api imports, install tree and workspaces match the lockfile, decoder assets ${distAssets.skipped ? 'skipped (no dist/)' : 'present'}`,
);
}