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.

deploy(gate): guard the build context and the pinned viewer before a submit

nirholas82581e64497a
diff --git a/CLAUDE.md b/CLAUDE.md
index f7bbdb424..40385610c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -292,7 +292,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` → `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. 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) followed by the same `gcloud builds submit --config server/cloudbuild.yaml --region us-central1 --project aerial-vehicle-466722-p5`. 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 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`.
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/package-lock.json b/package-lock.json
index 159836470..7bea76231 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -183,7 +183,6 @@
"imapflow": "^1.7.6",
"jose": "^5.9.6",
"lightweight-charts": "^5.2.0",
- "lil-gui": "^0.21.0",
"livekit-client": "^2.19.2",
"livepeer": "^3.5.0",
"lru-cache": "^11.5.2",
@@ -29568,10 +29567,6 @@
"fancy-canvas": "2.1.0"
}
},
- "node_modules/lil-gui": {
- "version": "0.21.0",
- "license": "MIT"
- },
"node_modules/lilconfig": {
"version": "3.1.3",
"dev": true,
diff --git a/package.json b/package.json
index 43fba7155..98662469c 100644
--- a/package.json
+++ b/package.json
@@ -216,7 +216,7 @@
"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs",
"audit:handlers": "node scripts/audit-empty-handlers.mjs",
"audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",
- "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:mcp-listing && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget",
+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:mcp-listing && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget",
"test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js",
"audit:mcp-golden": "node scripts/audit-mcp-golden.mjs",
"audit:mcp-safety": "node scripts/audit-mcp-safety.mjs",
@@ -358,6 +358,7 @@
"check:rules": "node scripts/check-rules.mjs",
"check:fetch-timeouts": "node scripts/check-fetch-timeouts.mjs",
"check:vendored": "node scripts/check-vendored-workers.mjs",
+ "check:model-viewer": "node scripts/check-model-viewer-version.mjs",
"check:secrets": "node scripts/check-secrets.mjs",
"check:gcloudignore": "node scripts/check-gcloudignore.mjs",
"check:home-voice": "node scripts/check-home-voice.mjs",
@@ -377,7 +378,7 @@
"ensure:avatar-studio": "test -f character-studio/build/index.html || npm run build:avatar-studio",
"deploy:gcp": "npm run check:dist && npm run check:pages && npm run db:check && gcloud builds submit --config server/cloudbuild.yaml --region us-central1 --project aerial-vehicle-466722-p5 && npm run deploy:gcp:purge-cdn && npm run smoke:prod",
"deploy:gcp:full": "npm run build:gcp && npm run deploy:gcp",
- "deploy:gcp:submit": "npm run db:check && gcloud builds submit --config server/cloudbuild.yaml --region us-central1 --project aerial-vehicle-466722-p5",
+ "deploy:gcp:submit": "npm run db:check && npm run check:gcloudignore && gcloud builds submit --config server/cloudbuild.yaml --region us-central1 --project aerial-vehicle-466722-p5",
"deploy:gcp:purge-cdn": "gcloud compute url-maps invalidate-cdn-cache three-ws-lb --path '/*' --project aerial-vehicle-466722-p5",
"postversion": "git push threews HEAD && git push threews --tags",
"validate:cards": "node scripts/validate-agent-cards.mjs",
@@ -552,7 +553,6 @@
"imapflow": "^1.7.6",
"jose": "^5.9.6",
"lightweight-charts": "^5.2.0",
- "lil-gui": "^0.21.0",
"livekit-client": "^2.19.2",
"livepeer": "^3.5.0",
"lru-cache": "^11.5.2",
diff --git a/tests/gcloudignore-wiring.test.js b/tests/gcloudignore-wiring.test.js
new file mode 100644
index 000000000..87f9edee9
--- /dev/null
+++ b/tests/gcloudignore-wiring.test.js
@@ -0,0 +1,51 @@
+// Guards the deploy-context check that the 2026-09-04 healthz outage exposed.
+//
+// `.gcloudignore` is an allowlist: everything is excluded and specific paths are
+// re-included. It never re-included `services/`, so `services/home-relay/src/token.js`
+// was absent from the image while `api/_lib/home/relay.js` imported it at module
+// load. Revision 00412 answered `/api/healthz`, `/api/wk`, `/api/x402-pay` and every
+// `/api/home/*` route with ERR_MODULE_NOT_FOUND on every request, and no build step
+// was red: a missing re-include is not a build error, it is a runtime one.
+//
+// `scripts/check-gcloudignore.mjs` was written to catch exactly that, but it was
+// wired into no npm script, so nothing ran it and the omission shipped anyway. These
+// tests pin the wiring as well as the rules: an unwired guard is not a guard.
+
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const scripts = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8')).scripts;
+
+describe('gcloudignore build-context guard', () => {
+ it('is wired into deploy:gcp:submit ahead of the upload', () => {
+ const submit = scripts['deploy:gcp:submit'] ?? '';
+ expect(submit).toContain('npm run check:gcloudignore');
+ expect(submit.indexOf('check:gcloudignore')).toBeLessThan(submit.indexOf('gcloud builds submit'));
+ });
+
+ it('is wired into the repo gate', () => {
+ expect(scripts.gate ?? '').toContain('npm run check:gcloudignore');
+ });
+
+ it('passes against the committed .gcloudignore', () => {
+ const run = () =>
+ execFileSync('node', ['scripts/check-gcloudignore.mjs'], {
+ cwd: ROOT,
+ encoding: 'utf8',
+ timeout: 120_000,
+ });
+ expect(run).not.toThrow();
+ });
+
+ it('keeps the runtime-imported service modules present and required', () => {
+ const guard = readFileSync(path.join(ROOT, 'scripts/check-gcloudignore.mjs'), 'utf8');
+ for (const rel of ['services/home-relay/src/token.js', 'services/home-satellite/src/token.js']) {
+ expect(existsSync(path.join(ROOT, rel))).toBe(true);
+ expect(guard).toContain(rel);
+ }
+ });
+});