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.

feat(audit:deploy): refuse a deploy whose installed dependencies differ from the lockfile

nirholasbfc385dc782e
diff --git a/CLAUDE.md b/CLAUDE.md
index 9cc880cbf..3143229a9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -298,7 +298,7 @@ Remember stop-and-ask gate 2: production deploys need owner approval unless the
`check:conflicts` → `check:browser-graph` → `check:tdz-bootstrap` → `ensure:avatar-studio` → `build:info:snapshot` → `docs:freshness` → `build:lib:full` (the UMD lib) → `build:avatar-sdk` → `build:chat` → `build` (the frontend `vite build`) → `publish:lib` → `build:info` → `check:dist` → `check:pages`
Why the order is load-bearing: `check:conflicts` runs first so an unresolved merge-conflict marker fails in seconds instead of after a full build. `check:tdz-bootstrap` sits beside it for the same reason: it refuses a browser module whose top-level bootstrap call runs above the `let`s that call writes. JavaScriptCore checks an assignment target's temporal dead zone before evaluating the right-hand side and V8 does not, so that ordering ships green on Chrome and throws "Cannot access uninitialized variable." on every Safari, which is how `/avatars/:id` went dead on iOS and macOS while every desktop check passed. `build:lib:full` writes `dist-lib/agent-3d.js`, `build:avatar-sdk` copies that bundle into `avatar-sdk/dist/index.mjs`, and the frontend `vite build` resolves `avatar-sdk/src/agent.js` against it, so both must come BEFORE `build`; skipping them shipped whatever stale `avatar-sdk/dist` the build machine happened to hold, and in a fresh worktree failed the build outright with `Could not resolve "../dist/index.mjs"` (2026-08-17). The frontend `vite build` runs with `emptyOutDir`, so it WIPES `dist/` and everything that writes into `dist/` must come after it: that is why `publish:lib`, which mirrors the UMD lib into `dist/`, follows `build` rather than sitting next to `build:lib:full`, and `check:dist` fails without that bundle present. `ensure:avatar-studio` consumes `character-studio/build` and `build:chat` consumes `chat/node_modules`, which is exactly why step 1 stages worktree artifacts. `docs:freshness` measures documentation drift against git history and writes `public/docs-freshness.json` plus its summary, so it must run before `build` copies `public/` into `dist/`; running it here is what keeps `/docs/freshness` and every docs-page freshness badge describing the commit actually deployed instead of whenever someone last ran it by hand. Do NOT hand-run `build:vercel` as the frontend build: it builds the SDK/lib sub-artifacts, NOT the static HTML pages, so `dist/` ends up without `/`, `/create`, etc. and `check:dist` fails.
-3. **Submit: `npm run deploy:gcp:submit`.** That is `db:check` (exit 4 if any migration is pending), then `check:gcloudignore`, then `audit:deploy` (no committed symlinks, no unsatisfied peer deps, no undeclared `api/` imports, decoder assets present), then the same `gcloud builds submit --config server/cloudbuild.yaml --region us-central1 --project aerial-vehicle-466722-p5`. `check:gcloudignore` simulates the upload and fails when a file the server imports at runtime would be excluded from the build context: an omitted `services/home-relay/src/token.js` shipped revision 00412 answering `/api/healthz` with `ERR_MODULE_NOT_FOUND` on every request (2026-09-04). Do NOT hand-run the bare `gcloud builds submit`: it is the only step that would have caught new code shipping over an old schema, and skipping it is how production ended up serving handlers that query columns their migration never applied (`column "blocks_behind" does not exist`, live on 2026-08-14). If the gate says migrations are pending, apply them first (`npm run db:status`, then `npm run db:migrate`); if it says `DATABASE_URL is not set`, step 1 did not copy `.env.local`. EVERY cloudbuild config must pin `serviceAccount: .../three-ws-build@...` (the default compute SA was deleted), and manual submits need `--substitutions=SHORT_SHA=manual$(date +%s)` when the config tags images with `$SHORT_SHA`.
+3. **Submit: `npm run deploy:gcp:submit`.** That is `db:check` (exit 4 if any migration is pending), then `check:gcloudignore`, then `audit:deploy` (no committed symlinks, no unsatisfied peer deps, no undeclared `api/` imports, decoder assets present, and an installed `node_modules` that matches `package-lock.json`), then the same `gcloud builds submit --config server/cloudbuild.yaml --region us-central1 --project aerial-vehicle-466722-p5`. `check:gcloudignore` simulates the upload and fails when a file the server imports at runtime would be excluded from the build context: an omitted `services/home-relay/src/token.js` shipped revision 00412 answering `/api/healthz` with `ERR_MODULE_NOT_FOUND` on every request (2026-09-04). The lockfile match exists because the image installs from the lockfile while every local test, and every deploy worktree that hardlinks this `node_modules`, runs whatever is on disk: a dependency bump nobody reinstalled shipped `@x402/extensions` 2.25.0 untested and every paid x402 route answered 500 on import (2026-09-17). If it fails, run `npm install`, then `npm test`, before deploying. Do NOT hand-run the bare `gcloud builds submit`: it is the only step that would have caught new code shipping over an old schema, and skipping it is how production ended up serving handlers that query columns their migration never applied (`column "blocks_behind" does not exist`, live on 2026-08-14). If the gate says migrations are pending, apply them first (`npm run db:status`, then `npm run db:migrate`); if it says `DATABASE_URL is not set`, step 1 did not copy `.env.local`. EVERY cloudbuild config must pin `serviceAccount: .../three-ws-build@...` (the default compute SA was deleted), and manual submits need `--substitutions=SHORT_SHA=manual$(date +%s)` when the config tags images with `$SHORT_SHA`.
4. **Purge CDN: `npm run deploy:gcp:purge-cdn`.** The purge is synchronous on purpose. Do not re-add `--async`, or post-deploy checks read stale edge content and report phantom failures.
5. **Verify the deploy landed.** `curl -s https://three.ws/api/version` returns the live commit SHA + Cloud Run revision, and `npm run smoke:prod` sweeps every page declared in `data/pages.json` against the live site (`deploy:gcp` runs it automatically after the purge).
diff --git a/scripts/audit-deploy-artifacts.mjs b/scripts/audit-deploy-artifacts.mjs
index 55caf3230..bbbb16368 100644
--- a/scripts/audit-deploy-artifacts.mjs
+++ b/scripts/audit-deploy-artifacts.mjs
@@ -21,6 +21,18 @@
* 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.
+ *
* Runs standalone (`node scripts/audit-deploy-artifacts.mjs`), as phase 1 of
* scripts/build-vercel.mjs, and via tests/deploy-artifacts.test.js.
*/
@@ -213,6 +225,12 @@ export async function findUndeclaredApiImports({ apiDir = resolve(ROOT, 'api') }
...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
@@ -236,6 +254,7 @@ export async function findUndeclaredApiImports({ apiDir = resolve(ROOT, 'api') }
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,
@@ -247,7 +266,7 @@ export async function findUndeclaredApiImports({ apiDir = resolve(ROOT, 'api') }
}
// ---------------------------------------------------------------------------
-// 3. Critical static runtime assets in dist/
+// 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),
@@ -272,6 +291,42 @@ export function findMissingDistAssets() {
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) continue;
+ drift.push({
+ path,
+ locked: info.version,
+ installed,
+ kind: installed === null ? 'missing' : 'stale',
+ });
+ }
+ return drift;
+}
+
// ---------------------------------------------------------------------------
// CLI
// ---------------------------------------------------------------------------
@@ -325,12 +380,24 @@ if (isMain) {
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`);
+ }
+
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, decoder assets ${distAssets.skipped ? 'skipped (no dist/)' : 'present'}`,
+ `[audit:deploy] clean in ${elapsed}s: no committed symlinks, no unsatisfied peers, no undeclared api imports, install tree matches the lockfile, decoder assets ${distAssets.skipped ? 'skipped (no dist/)' : 'present'}`,
);
}
diff --git a/tests/deploy-artifacts.test.js b/tests/deploy-artifacts.test.js
index ca235933f..4f63e74ee 100644
--- a/tests/deploy-artifacts.test.js
+++ b/tests/deploy-artifacts.test.js
@@ -8,17 +8,35 @@
// silently vanished and every /api/cron/* died with ERR_MODULE_NOT_FOUND.
// 3. Undeclared (phantom) bare imports in api/ — they resolve today only via
// hoisting from some transitive dep, and disappear on the next dedupe.
+// 4. An install tree that drifted from package-lock.json. The image installs
+// from the lockfile while local tests run whatever is on disk, so a bump
+// nobody reinstalled ships untested (@x402/extensions 2.25.0, 2026-09-17:
+// every paid x402 route 500ed on import while the suite stayed green).
//
// The same checks gate the Vercel build (scripts/build-vercel.mjs phase 1);
// running them here means `npm test` catches the regression before a push.
-import { describe, it, expect } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it, expect, afterEach } from 'vitest';
import {
findCommittedSymlinks,
findUnsatisfiedPeers,
findUndeclaredApiImports,
+ findLockDrift,
} from '../scripts/audit-deploy-artifacts.mjs';
+const scratchDirs = [];
+function scratchDir() {
+ const dir = mkdtempSync(join(tmpdir(), 'deploy-artifacts-'));
+ scratchDirs.push(dir);
+ return dir;
+}
+afterEach(() => {
+ while (scratchDirs.length) rmSync(scratchDirs.pop(), { recursive: true, force: true });
+});
+
describe('deploy artifacts', () => {
it('has no committed symlinks (Vercel function tracing cannot resolve them)', () => {
expect(findCommittedSymlinks()).toEqual([]);
@@ -31,6 +49,89 @@ describe('deploy artifacts', () => {
it('has no undeclared bare imports in api/', async () => {
expect(await findUndeclaredApiImports()).toEqual([]);
});
+
+ it('runs against the dependency versions the lockfile will install in the image', () => {
+ expect(findLockDrift()).toEqual([]);
+ });
+});
+
+describe('findUndeclaredApiImports logic', () => {
+ // vitest is a declared devDependency of this repo, which makes it a stable
+ // stand-in for "tooling package that is present but not a runtime dependency".
+ it('allows a lazy import of a declared devDependency', async () => {
+ const apiDir = scratchDir();
+ writeFileSync(join(apiDir, 'tool.js'), "export async function run() {\n\treturn import('vitest');\n}\n");
+ expect(await findUndeclaredApiImports({ apiDir })).toEqual([]);
+ });
+
+ it('still fails a static import of a devDependency, which would load with the handler', async () => {
+ const apiDir = scratchDir();
+ writeFileSync(join(apiDir, 'handler.js'), "import { vi } from 'vitest';\nexport default vi;\n");
+ const problems = await findUndeclaredApiImports({ apiDir });
+ expect(problems.map((p) => p.specifier)).toEqual(['vitest']);
+ });
+
+ it('still fails a lazy import of a package declared nowhere', async () => {
+ const apiDir = scratchDir();
+ writeFileSync(join(apiDir, 'tool.js'), "export const load = () => import('three-ws-undeclared-package');\n");
+ const problems = await findUndeclaredApiImports({ apiDir });
+ expect(problems.map((p) => p.specifier)).toEqual(['three-ws-undeclared-package']);
+ });
+});
+
+describe('findLockDrift logic', () => {
+ function installTree(packages) {
+ const root = scratchDir();
+ for (const [path, version] of Object.entries(packages)) {
+ mkdirSync(join(root, path), { recursive: true });
+ writeFileSync(join(root, path, 'package.json'), JSON.stringify({ version }));
+ }
+ return root;
+ }
+
+ it('reports a package installed at a different version than the lockfile pins', () => {
+ const root = installTree({ 'node_modules/some-sdk': '2.14.0' });
+ const lock = { packages: { '': {}, 'node_modules/some-sdk': { version: '2.25.0' } } };
+ expect(findLockDrift({ lock, root })).toEqual([
+ { path: 'node_modules/some-sdk', locked: '2.25.0', installed: '2.14.0', kind: 'stale' },
+ ]);
+ });
+
+ it('reports a locked production package that is not installed at all', () => {
+ const root = installTree({});
+ const lock = { packages: { '': {}, 'node_modules/some-sdk': { version: '1.0.0' } } };
+ expect(findLockDrift({ lock, root })).toEqual([
+ { path: 'node_modules/some-sdk', locked: '1.0.0', installed: null, kind: 'missing' },
+ ]);
+ });
+
+ it('passes a tree that matches, nested installs included', () => {
+ const root = installTree({
+ 'node_modules/some-sdk': '2.25.0',
+ 'node_modules/some-sdk/node_modules/core': '2.25.0',
+ });
+ const lock = {
+ packages: {
+ '': {},
+ 'node_modules/some-sdk': { version: '2.25.0' },
+ 'node_modules/some-sdk/node_modules/core': { version: '2.25.0' },
+ },
+ };
+ expect(findLockDrift({ lock, root })).toEqual([]);
+ });
+
+ it('ignores dev-only packages, absent optional ones, and workspace links', () => {
+ const root = installTree({ 'node_modules/dev-tool': '1.0.0' });
+ const lock = {
+ packages: {
+ '': {},
+ 'node_modules/dev-tool': { version: '9.9.9', dev: true },
+ 'node_modules/other-platform-binary': { version: '1.0.0', optional: true },
+ 'node_modules/workspace-pkg': { resolved: 'packages/workspace-pkg', link: true },
+ },
+ };
+ expect(findLockDrift({ lock, root })).toEqual([]);
+ });
});
describe('findUnsatisfiedPeers logic', () => {