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.

test(deploy): let a deploy worktree run the suite, so a ship can be tested at its own commit

nirholasa9b232f19b3c
diff --git a/CLAUDE.md b/CLAUDE.md
index e2f2c6d64..ef932ba6b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -286,7 +286,7 @@ When reverting, do NOT use git's default `Revert "<original title>"` message: it
Remember stop-and-ask gate 2: production deploys need owner approval unless the owner's current instruction is itself the approval. Full runbook incl. LB/DNS/TLS/env/rollback/recovery: `docs/ops/gcp-production.md`. GPU workers deploy from their own `workers/<name>/cloudbuild.yaml`.
0. **Reclaim disk first: `npm run clean:worktrees` (add `--apply` to act).** Deploy worktrees are created by every deploy and removed by nobody. On 2026-08-04 ten had accumulated and filled the 126 GB disk to 100%, which fails in a way that reads like a different bug entirely: `git worktree add` dies mid-checkout with `No space left on device` and leaves a half-written tree behind. The script only reclaims a linked worktree that is detached, clean, and idle past `--min-age-hours` (default 2, so a concurrent agent's live build is never deleted); anything with uncommitted work is reported and kept.
-1. **Prepare a CLEAN worktree: `npm run prep:worktree -- --apply`.** That is the whole step; it encodes everything below, and running it beats staging by hand. Plan first with a bare `npm run prep:worktree` (writes nothing), `--path <dir>` to stage your own tree instead of colliding with a concurrent agent on the default `/workspaces/.deploy-wt`, `--force` to replace an existing tree (refused if it holds uncommitted work). What it does: `git worktree add --detach <path> HEAD`, then hardlinks THREE artifacts with `cp -al` on the same filesystem (not just the first): `node_modules`, `chat/node_modules`, and `character-studio/build`, plus copies BOTH `.env` and `.env.local`. Omitting either nested one kills the build minutes in: an OOM exit 144 on the avatar-studio rebuild, or `Cannot find package '@sveltejs/vite-plugin-svelte'` on the chat build. A nested artifact that is missing from the source tree is BUILT first (`deps:chat`, `build:avatar-studio`) rather than skipped, which is the failure a hand-run `cp -al` produces on a machine that has never deployed. `.env.local` is the one that carries `DATABASE_URL`, and without it step 3's migration gate cannot read the schema state and refuses to submit. **Remove it when the deploy lands** (`git worktree remove --force <path>`); that is what step 0 exists to clean up after. See `docs/ops/gcp-production.md`.
+1. **Prepare a CLEAN worktree: `npm run prep:worktree -- --apply`.** That is the whole step; it encodes everything below, and running it beats staging by hand. Plan first with a bare `npm run prep:worktree` (writes nothing), `--path <dir>` to stage your own tree instead of colliding with a concurrent agent on the default `/workspaces/.deploy-wt`, `--force` to replace an existing tree (refused if it holds uncommitted work). What it does: `git worktree add --detach <path> HEAD`, then hardlinks every artifact in the `ARTIFACTS` list of `scripts/prepare-deploy-worktree.mjs` with `cp -al` on the same filesystem (not just the first). Three of them are build-critical, `node_modules`, `chat/node_modules` and `character-studio/build`; the optional ones (`walk-sdk/dist`, `multiplayer/node_modules`, `animation-sources`) are what let the worktree also run the repo's own test suite, so a pre-ship `npm test` can be taken at the exact commit being shipped instead of in the shared tree. It then copies BOTH `.env` and `.env.local`. Omitting either nested one kills the build minutes in: an OOM exit 144 on the avatar-studio rebuild, or `Cannot find package '@sveltejs/vite-plugin-svelte'` on the chat build. A nested artifact that is missing from the source tree is BUILT first (`deps:chat`, `build:avatar-studio`) rather than skipped, which is the failure a hand-run `cp -al` produces on a machine that has never deployed. `.env.local` is the one that carries `DATABASE_URL`, and without it step 3's migration gate cannot read the schema state and refuses to submit. **Remove it when the deploy lands** (`git worktree remove --force <path>`); that is what step 0 exists to clean up after. See `docs/ops/gcp-production.md`.
2. **Build: `npm run build:gcp`.** ORDER IS LOAD-BEARING and `build:gcp` already encodes it. Never hand-run the steps in a different order. The full chain, in order:
`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`
diff --git a/scripts/prepare-deploy-worktree.mjs b/scripts/prepare-deploy-worktree.mjs
index 031651497..30ae9b083 100644
--- a/scripts/prepare-deploy-worktree.mjs
+++ b/scripts/prepare-deploy-worktree.mjs
@@ -103,6 +103,35 @@ export const ARTIFACTS = [
optional: true,
why: 'an in-worktree agent-payments-sdk rebuild',
},
+ // The three below are not build inputs: build:gcp is green without them. They
+ // are what lets a deploy worktree run the repository's own test suite, which
+ // is the only way to test the exact commit being shipped rather than the
+ // shared tree with every concurrent session's work in it. Without them a full
+ // vitest run from a worktree reports eighteen failures that are all missing
+ // files, which reads as a broken commit and is the reason the pre-ship test
+ // run kept being taken in the dirty main tree instead.
+ {
+ // Same shape as agent-payments-sdk/dist: gitignored, so the package source
+ // arrives with nothing behind its entry and tour-sdk's importers die on
+ // "Failed to resolve entry for package @three-ws/walk".
+ rel: 'walk-sdk/dist',
+ build: ['npm', ['run', 'build', '--prefix', 'walk-sdk']],
+ optional: true,
+ why: "tour-sdk's suites, which import @three-ws/walk",
+ },
+ {
+ rel: 'multiplayer/node_modules',
+ build: null,
+ optional: true,
+ why: 'the multiplayer server-boot suite, which joins a real colyseus room',
+ },
+ {
+ // Gitignored GLB fixtures, ~113 MB, hardlinked so they cost nothing.
+ rel: 'animation-sources',
+ build: null,
+ optional: true,
+ why: 'the glb-diff and model-diff suites, whose fixtures are gitignored',
+ },
];
/** Env files copied (never hardlinked: a deploy tree must not share their inode). */
diff --git a/tests/check-tdz-bootstrap.test.js b/tests/check-tdz-bootstrap.test.js
index c57dbd3d8..7a26f5729 100644
--- a/tests/check-tdz-bootstrap.test.js
+++ b/tests/check-tdz-bootstrap.test.js
@@ -14,8 +14,12 @@
*/
import { describe, it, expect } from 'vitest';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
import { analyze, tracked } from '../scripts/check-tdz-bootstrap.mjs';
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
const names = (src) => analyze('t.js', src).map((f) => f.name).sort();
describe('check:tdz-bootstrap catches what shipped', () => {
@@ -151,7 +155,11 @@ describe('the sweep actually reaches the pages it claims to cover', () => {
// every top-level page, including the one whose regression it was written
// for. A count alone would not have caught that; naming the file does.
it('includes top-level page modules, not just nested ones', () => {
- const files = tracked(['src', 'public']).map((f) => f.replace(/^.*\/three\.ws\//, ''));
+ // Relative to the repo this test lives in, never to a hardcoded checkout
+ // name: run from a deploy worktree (/workspaces/.deploy-wt-*) a
+ // `/three.ws/` regex strips nothing and every expectation below fails
+ // for a reason that has nothing to do with the sweep.
+ const files = tracked(['src', 'public']).map((f) => relative(repoRoot, f));
expect(files).toContain('src/avatar-page.js');
expect(files).toContain('src/three-tier-page.js');
expect(files).toContain('public/forever.js');
diff --git a/tests/setup-git-hooks.test.js b/tests/setup-git-hooks.test.js
index eb8d6d291..de52cc96f 100644
--- a/tests/setup-git-hooks.test.js
+++ b/tests/setup-git-hooks.test.js
@@ -402,7 +402,12 @@ describe('pre-push hook (behavior)', () => {
describe('this repository', () => {
it('has the current hook version installed', () => {
- const hookPath = join(repoRoot, '.git', 'hooks', 'pre-push');
+ // Ask git where the hooks live rather than assuming `<root>/.git/hooks`.
+ // In a linked worktree (every deploy worktree here is one) `.git` is a
+ // FILE pointing at the common dir, so the assumed path does not exist and
+ // this reads as "the hook is missing" when it is installed and working.
+ const gitDir = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: repoRoot, encoding: 'utf8' }).trim();
+ const hookPath = join(resolve(repoRoot, gitDir), 'hooks', 'pre-push');
expect(existsSync(hookPath)).toBe(true);
const body = readFileSync(hookPath, 'utf8');
expect(body).toContain('three.ws pre-push hook');