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.

14.1 KB
Raw Blame
#!/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 on another filesystem than the repo 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 ../.deploy-wt-2
//
// --path (default .deploy-wt beside the repo, so /workspaces/.deploy-wt in the
// codespace) 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 ? path.join(path.dirname(ROOT), '.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',
	},
	{
		// The workspace symlink node_modules/@three-ws/agent-payments resolves to
		// ../../agent-payments-sdk, whose package.json main/module/exports all
		// point into dist/. dist/ is gitignored, so a fresh worktree carries the
		// package source with no entry behind it, and every importer dies with
		// "Failed to resolve entry for package @three-ws/agent-payments" rather
		// than naming the artifact that is actually missing.
		rel: 'agent-payments-sdk/dist',
		build: ['npm', ['run', 'build', '--prefix', 'agent-payments-sdk']],
		why: 'anything importing @three-ws/agent-payments, which otherwise fails to resolve its entry',
	},
	{
		rel: 'agent-payments-sdk/node_modules',
		build: null,
		optional: true,
		why: 'an in-worktree agent-payments-sdk rebuild',
	},
	// The four below are not inputs to build:gcp, which is green without them.
	// They are what lets a deploy worktree run the repository's own gate and test
	// suite, which is the only way to verify 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, and `npm run gate` cannot pass at all, which
	// reads as a broken commit and is why the pre-ship verification kept being
	// taken in the dirty main tree instead.
	{
		// tour-sdk pins its own esbuild (0.27.7 against the root's 0.28.1) and the
		// committed public/tour-builder/tour.global.js is that version's output.
		// Built with the root's esbuild the helper prelude differs, so
		// audit:tour-global reports the bundle stale over a toolchain version
		// nobody changed, and the gate can never go green in a fresh worktree.
		rel: 'tour-sdk/node_modules',
		build: null,
		optional: true,
		why: 'audit:tour-global, which rebuilds the bundle with the esbuild tour-sdk pins',
	},
	{
		// 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',
	},
];

/**
 * How to hardlink one artifact into the staged tree.
 *
 * An artifact is not always all-or-nothing in git. `animation-sources` holds
 * tracked .fbx sources next to gitignored .glb fixtures, so `git worktree add`
 * creates the directory with only the tracked half in it. Treating a
 * destination that merely EXISTS as already staged then drops every file this
 * entry was added for, and the suite fails on 25 missing fixtures that read as
 * a broken commit rather than an unstaged tree. So an existing destination is
 * merged into instead of skipped: `--update=none` hardlinks what checkout could
 * not produce and leaves every file the worktree already owns exactly as it is,
 * which matters because a hardlinked tracked file would make an edit in the
 * deploy tree rewrite the source tree too.
 *
 * @param {string} src absolute path in the source tree
 * @param {string} dest absolute path in the staged tree
 * @param {boolean} destExists does dest already exist (git checked part of it out)
 * @returns {string[]} argv for `cp`
 */
export function cpArgsFor(src, dest, destExists) {
	return destExists ? ['-al', '--update=none', `${src}/.`, `${dest}/`] : ['-al', src, dest];
}

/** 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);
		const merging = existsSync(dest);
		execFileSync('cp', cpArgsFor(p.src, dest, merging), { cwd: ROOT, timeout: 900_000 });
		console.log(`[prep:worktree] hardlinked ${merging ? `the untracked half of ${p.rel}` : 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();
}