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(deploy): stage a deploy worktree in one command instead of hand-copying its artifacts

nirholasddf05d8b6902
diff --git a/scripts/prepare-deploy-worktree.mjs b/scripts/prepare-deploy-worktree.mjs
new file mode 100644
index 000000000..700b74d8a
--- /dev/null
+++ b/scripts/prepare-deploy-worktree.mjs
@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// prepare-deploy-worktree.mjs: stage a clean deploy worktree, correctly, in one command.
+//
+// This is the missing half of the worktree lifecycle. clean-deploy-worktrees.mjs
+// reclaims deploy trees after the fact; nothing created them, so every deploy
+// re-ran the runbook's five-command ritual by hand. That ritual has three ways
+// to go wrong, and each one fails minutes later somewhere that does not name the
+// real cause:
+//
+// 1. `cp -al` of an artifact that does not exist in the source tree. Both
+// nested dependency trees are gitignored, so a machine that has never run
+// a deploy has no chat/node_modules and no character-studio/build. The
+// copy dies with "No such file or directory", and an agent who continues
+// anyway hits the failures in (2).
+// 2. Skipping a nested artifact. Missing chat/node_modules fails the chat
+// build with "Cannot find package '@sveltejs/vite-plugin-svelte'"; missing
+// character-studio/build makes ensure:avatar-studio run the real
+// avatar-studio vite build, which gets OOM-killed (exit 144) on a box
+// already hosting concurrent agent builds. Both land several minutes in.
+// 3. `cp -al` across a filesystem boundary. Hardlinks cannot span devices, so
+// a worktree staged outside /workspaces silently falls back to nothing at
+// all: cp exits non-zero and the tree is left half-staged.
+//
+// This script closes all three: it BUILDS a missing artifact instead of failing
+// on it, stages every one of them, and verifies the hardlink target shares a
+// device with the source before it starts.
+//
+// node scripts/prepare-deploy-worktree.mjs plan only, writes nothing
+// node scripts/prepare-deploy-worktree.mjs --apply stage the worktree
+// node scripts/prepare-deploy-worktree.mjs --apply --path /workspaces/.deploy-wt-2
+//
+// --path (default /workspaces/.deploy-wt) lets concurrent agents stage their own
+// tree instead of colliding on the shared default. --force replaces an existing
+// tree at that path, but only when clean-deploy-worktrees.mjs would have judged
+// it reclaimable, so a tree holding uncommitted work is never destroyed.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, statSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { dirtyCount } from './clean-deploy-worktrees.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const APPLY = process.argv.includes('--apply');
+const FORCE = process.argv.includes('--force');
+const TARGET = (() => {
+ const i = process.argv.indexOf('--path');
+ const raw = i === -1 ? '/workspaces/.deploy-wt' : process.argv[i + 1];
+ if (!raw || raw.startsWith('--')) fail('--path needs a directory argument');
+ return path.resolve(raw);
+})();
+
+/**
+ * The artifacts `build:gcp` needs that git does not carry. Order matters only
+ * for readability; each is independent.
+ *
+ * `build` is how we regenerate the artifact when the source tree lacks it, run
+ * from ROOT. A null build means the artifact cannot be regenerated cheaply and
+ * its absence is a hard stop.
+ */
+export const ARTIFACTS = [
+ {
+ rel: 'node_modules',
+ build: null,
+ missingHint: 'run `npm install` in the main worktree first',
+ why: 'every step of build:gcp',
+ },
+ {
+ rel: 'chat/node_modules',
+ build: ['npm', ['run', 'deps:chat']],
+ why: "build:chat, which otherwise fails with \"Cannot find package '@sveltejs/vite-plugin-svelte'\"",
+ },
+ {
+ rel: 'character-studio/build',
+ build: ['npm', ['run', 'build:avatar-studio']],
+ why: 'ensure:avatar-studio, which otherwise runs the real build and gets OOM-killed (exit 144)',
+ },
+ {
+ // Not in the runbook's list, but staging it means a worktree whose
+ // character-studio/build is ever invalidated can rebuild in place
+ // instead of dying on a missing dependency tree.
+ rel: 'character-studio/node_modules',
+ build: null,
+ optional: true,
+ why: 'an in-worktree avatar-studio rebuild',
+ },
+];
+
+/** Env files copied (never hardlinked: a deploy tree must not share their inode). */
+const ENV_FILES = ['.env', '.env.local'];
+
+/**
+ * Decide what to do with each artifact, given only a presence oracle. Pure, so
+ * the rule that a missing REQUIRED artifact is built rather than skipped can be
+ * pinned by tests without staging a real worktree.
+ *
+ * @param {(rel: string) => boolean} present does this artifact exist in the source tree
+ * @param {typeof ARTIFACTS} artifacts
+ * @returns {{rel:string, action:'stage'|'build'|'skip'|'blocked'}[]}
+ */
+export function planArtifacts(present, artifacts = ARTIFACTS) {
+ return artifacts.map((a) => {
+ if (present(a.rel)) return { ...a, action: 'stage' };
+ if (a.optional) return { ...a, action: 'skip' };
+ return { ...a, action: a.build ? 'build' : 'blocked' };
+ });
+}
+
+function fail(message) {
+ console.error(`[prep:worktree] ${message}`);
+ process.exit(1);
+}
+
+function git(args, cwd = ROOT, timeoutMs = 600_000) {
+ return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/** Same-device check. `cp -al` cannot cross a filesystem boundary. */
+function sameDevice(a, b) {
+ try {
+ return statSync(a).dev === statSync(b).dev;
+ } catch {
+ return false;
+ }
+}
+
+function run() {
+ const mainTop = path.resolve(git(['rev-parse', '--show-toplevel']).trim());
+ if (mainTop !== ROOT) fail(`run this from the main worktree (${ROOT}), not ${mainTop}`);
+ if (TARGET === ROOT) fail('--path must not be the main worktree');
+
+ const head = git(['rev-parse', 'HEAD']).trim();
+ console.log(`[prep:worktree] target ${TARGET}`);
+ console.log(`[prep:worktree] source ${ROOT} at ${head.slice(0, 9)}`);
+
+ // Hardlinks are the whole point: a full copy of node_modules is several GB
+ // per tree and is what filled the disk in the first place.
+ const parent = path.dirname(TARGET);
+ if (!existsSync(parent)) fail(`parent directory ${parent} does not exist`);
+ if (!sameDevice(ROOT, parent)) {
+ fail(`${parent} is on a different filesystem than ${ROOT}, so cp -al cannot hardlink into it. Pick a --path under the same mount.`);
+ }
+
+ const existing = existsSync(TARGET);
+ if (existing && !FORCE) {
+ fail(`${TARGET} already exists. Another agent may be building there. Pass --force to replace it, or --path to stage your own.`);
+ }
+ if (existing && FORCE) {
+ // Reuse the reclaimability rule rather than inventing a second one:
+ // uncommitted work is the one thing here that cannot be regenerated.
+ let dirty = 0;
+ try {
+ dirty = dirtyCount(git(['status', '--porcelain'], TARGET, 180_000));
+ } catch (err) {
+ fail(`cannot read git status in ${TARGET} (${String(err.message).slice(0, 80)}), refusing to replace it`);
+ }
+ if (dirty > 0) fail(`${TARGET} holds ${dirty} uncommitted file(s). Refusing to replace it even with --force.`);
+ }
+
+ // Plan the artifact work before touching anything, so plan mode is honest.
+ const plan = planArtifacts((rel) => existsSync(path.join(ROOT, rel))).map((p) => ({ ...p, src: path.join(ROOT, p.rel) }));
+ for (const p of plan.filter((x) => x.action === 'blocked')) {
+ fail(`${p.rel} is missing from ${ROOT} and cannot be regenerated here: ${p.missingHint}`);
+ }
+
+ console.log('');
+ for (const p of plan) {
+ const verb = { stage: 'STAGE ', build: 'BUILD ', skip: 'SKIP ' }[p.action];
+ const note = p.action === 'build' ? ' (missing, will be generated first)' : p.action === 'skip' ? ' (absent and optional)' : '';
+ console.log(` ${verb}${p.rel}${note}\n needed by ${p.why}`);
+ }
+
+ const envPlan = ENV_FILES.map((f) => ({ file: f, present: existsSync(path.join(ROOT, f)) }));
+ console.log('');
+ for (const e of envPlan) {
+ console.log(` ${(e.present ? 'COPY' : 'ABSENT').padEnd(6)} ${e.file}${e.present ? '' : ' (not on this machine; build:gcp does not need it, deploy:gcp does)'}`);
+ }
+
+ if (!APPLY) {
+ console.log('\nPlan only. Re-run with --apply to stage the worktree.');
+ process.exit(0);
+ }
+
+ // Build the missing artifacts in the SOURCE tree, not the new one. They are
+ // gitignored, so building them here also makes every later deploy fast.
+ for (const p of plan.filter((x) => x.action === 'build')) {
+ console.log(`\n[prep:worktree] building ${p.rel} in ${ROOT} (this is the slow part, and it happens once)`);
+ const [cmd, args] = p.build;
+ execFileSync(cmd, args, { cwd: ROOT, stdio: 'inherit', timeout: 1_800_000 });
+ if (!existsSync(p.src)) fail(`${p.rel} still missing after \`${cmd} ${args.join(' ')}\``);
+ }
+
+ if (existing && FORCE) {
+ console.log(`\n[prep:worktree] removing the existing clean tree at ${TARGET}`);
+ git(['worktree', 'remove', '--force', TARGET]);
+ }
+
+ console.log(`\n[prep:worktree] git worktree add --detach ${TARGET} ${head.slice(0, 9)}`);
+ execFileSync('git', ['worktree', 'add', '--detach', TARGET, head], { cwd: ROOT, stdio: 'inherit', timeout: 900_000 });
+
+ for (const p of plan) {
+ if (p.action === 'skip') continue;
+ const dest = path.join(TARGET, p.rel);
+ if (existsSync(dest)) continue;
+ execFileSync('cp', ['-al', p.src, dest], { cwd: ROOT, timeout: 900_000 });
+ console.log(`[prep:worktree] hardlinked ${p.rel}`);
+ }
+
+ for (const e of envPlan) {
+ if (!e.present) continue;
+ copyFileSync(path.join(ROOT, e.file), path.join(TARGET, e.file));
+ console.log(`[prep:worktree] copied ${e.file}`);
+ }
+
+ // Prove the tree is actually usable rather than asserting it.
+ const missing = ARTIFACTS.filter((a) => !a.optional).filter((a) => !existsSync(path.join(TARGET, a.rel)));
+ if (missing.length) fail(`staged tree is incomplete, missing: ${missing.map((m) => m.rel).join(', ')}`);
+ if (!existsSync(path.join(TARGET, 'character-studio/build/index.html'))) {
+ fail('character-studio/build/index.html is absent in the staged tree, so ensure:avatar-studio would rebuild and risk exit 144');
+ }
+
+ console.log(`\n[prep:worktree] ready at ${TARGET}`);
+ console.log('Next:');
+ console.log(` cd ${TARGET} && npm run build:gcp`);
+ console.log(' gcloud builds submit --config server/cloudbuild.yaml --region us-central1 --project aerial-vehicle-466722-p5');
+ console.log(`\nWhen the deploy lands: git worktree remove --force ${TARGET}`);
+ console.log('(or leave it for `npm run clean:worktrees -- --apply` once it is idle past the age floor)');
+}
+
+// Importing this file must not stage anything; only a direct invocation acts.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ run();
+}
diff --git a/tests/prepare-deploy-worktree.test.js b/tests/prepare-deploy-worktree.test.js
new file mode 100644
index 000000000..b19a20db8
--- /dev/null
+++ b/tests/prepare-deploy-worktree.test.js
@@ -0,0 +1,96 @@
+// Tests for the deploy-worktree stager (scripts/prepare-deploy-worktree.mjs).
+//
+// The script exists because staging a deploy tree by hand failed in three ways
+// that all surface minutes later, disguised as something else. Two things are
+// worth pinning: that a missing REQUIRED artifact is BUILT rather than quietly
+// skipped (skipping is exactly what produced the exit-144 and missing-svelte
+// dead builds), and that the hardlink target is rejected up front when it
+// cannot possibly hardlink.
+
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ARTIFACTS, planArtifacts } from '../scripts/prepare-deploy-worktree.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPT = path.join(ROOT, 'scripts/prepare-deploy-worktree.mjs');
+
+/** Run the script in plan mode. It writes nothing, so this is safe in CI. */
+function plan(args) {
+ try {
+ const stdout = execFileSync('node', [SCRIPT, ...args], { cwd: ROOT, encoding: 'utf8', timeout: 120_000, stdio: ['ignore', 'pipe', 'pipe'] });
+ return { code: 0, out: stdout };
+ } catch (err) {
+ return { code: err.status ?? 1, out: `${err.stdout || ''}${err.stderr || ''}` };
+ }
+}
+
+describe('ARTIFACTS', () => {
+ it('covers all three artifacts the runbook requires, none of them optional', () => {
+ const required = ARTIFACTS.filter((a) => !a.optional).map((a) => a.rel);
+ expect(required).toEqual(['node_modules', 'chat/node_modules', 'character-studio/build']);
+ });
+
+ it('can regenerate every required artifact except the root dependency tree', () => {
+ for (const a of ARTIFACTS.filter((x) => !x.optional && x.rel !== 'node_modules')) {
+ expect(a.build, `${a.rel} needs a build command`).toBeTruthy();
+ }
+ // node_modules cannot be rebuilt from inside a deploy prep step without
+ // re-resolving the lockfile, so its absence must stop the run instead.
+ expect(ARTIFACTS.find((a) => a.rel === 'node_modules').build).toBe(null);
+ });
+});
+
+describe('planArtifacts', () => {
+ it('stages everything when the source tree is fully populated', () => {
+ const p = planArtifacts(() => true);
+ expect(p.every((x) => x.action === 'stage')).toBe(true);
+ });
+
+ it('builds a missing nested artifact rather than skipping it', () => {
+ const p = planArtifacts((rel) => rel !== 'character-studio/build' && rel !== 'chat/node_modules');
+ const byRel = Object.fromEntries(p.map((x) => [x.rel, x.action]));
+ expect(byRel['character-studio/build']).toBe('build');
+ expect(byRel['chat/node_modules']).toBe('build');
+ });
+
+ it('blocks, never builds, when the root dependency tree is absent', () => {
+ const p = planArtifacts((rel) => rel !== 'node_modules');
+ expect(p.find((x) => x.rel === 'node_modules').action).toBe('blocked');
+ });
+
+ it('skips an absent optional artifact without blocking the run', () => {
+ const p = planArtifacts((rel) => !rel.startsWith('character-studio/node_modules'));
+ expect(p.find((x) => x.rel === 'character-studio/node_modules').action).toBe('skip');
+ expect(p.some((x) => x.action === 'blocked')).toBe(false);
+ });
+});
+
+describe('guards (plan mode, writes nothing)', () => {
+ it('refuses a target on another filesystem, where cp -al cannot hardlink', () => {
+ const r = plan(['--path', '/tmp/deploy-wt-vitest-probe']);
+ expect(r.code).toBe(1);
+ expect(r.out).toMatch(/different filesystem/);
+ });
+
+ it('refuses a --path with no argument instead of staging somewhere unintended', () => {
+ const r = plan(['--path', '--apply']);
+ expect(r.code).toBe(1);
+ expect(r.out).toMatch(/--path needs a directory argument/);
+ });
+
+ it('refuses to stage over the main worktree', () => {
+ const r = plan(['--path', ROOT]);
+ expect(r.code).toBe(1);
+ expect(r.out).toMatch(/must not be the main worktree/);
+ });
+
+ it('plans without applying by default, and says so', () => {
+ const r = plan(['--path', '/workspaces/.deploy-wt-vitest-unused']);
+ expect(r.code).toBe(0);
+ expect(r.out).toMatch(/Plan only\. Re-run with --apply/);
+ for (const a of ARTIFACTS.filter((x) => !x.optional)) expect(r.out).toContain(a.rel);
+ });
+});