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
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.mdindex 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: itRemember 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.mjsindex 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.jsindex 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.jsindex 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');