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
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { execFileSync } from 'node:child_process';
import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync, copyFileSync, statSync, existsSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
// Guards the guard, twice over: the installer that writes .git/hooks/pre-push,
// and the hook body it writes.
//
// Why this file exists: scripts/check-rules.mjs shipped working and enforced by
// nothing, so violations reached main anyway. The hook is what makes it
// mandatory, which means the hook is now load-bearing for every push from this
// machine. Three properties have to hold or it does active harm:
//
// 1. It must not block a clean push. A pre-push hook that false-positives gets
// deleted by the first person it blocks, and then nothing is enforced
// again. The clean-push case below asserts it reaches the git-lfs handoff.
// 2. It must not swallow git-lfs. The stock LFS hook occupied this path first
// and consumes the pushed refs on stdin. Ours reads that same stdin to run
// its own per-ref check, so it has to replay the refs downstream or LFS
// silently stops uploading objects. That is a data-loss bug, invisible
// until a clone comes back with pointer files.
// 3. It must not clobber a hook it does not recognize. Overwriting someone's
// custom pre-push disables whatever it guarded, silently.
//
// The zero-sha cases matter because git uses the all-zeroes sha for both "new
// remote branch" and "delete this ref". Diffing against it produces a bogus
// range, so both must be skipped rather than checked.
const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const installer = join(repoRoot, 'scripts', 'setup-git-hooks.mjs');
const checkRules = join(repoRoot, 'scripts', 'check-rules.mjs');
const checkSecrets = join(repoRoot, 'scripts', 'check-secrets.mjs');
const ZERO = '0'.repeat(40);
// Assembled at runtime so this file does not itself contain a literal the
// hard-rules checker bans (it scans its own repo's added lines).
const STUB_COMMENT = `// ${'TO' + 'DO'}: implement later`;
let sandbox;
let repo;
let shimDir;
/**
* Copy the installer (and both checkers the hook shells out to) into `dir` as
* scripts/, mirroring the real layout.
*
* The installer deliberately resolves its target repo from its own file
* location rather than from cwd, because postinstall runs with an
* unpredictable cwd and must still install into the repo it ships with. So a
* staged copy is the only way to point it at a sandbox, and testing it this way
* exercises the real resolution path instead of a test-only override.
*/
function stageScripts(dir) {
mkdirSync(join(dir, 'scripts'), { recursive: true });
copyFileSync(installer, join(dir, 'scripts', 'setup-git-hooks.mjs'));
copyFileSync(checkRules, join(dir, 'scripts', 'check-rules.mjs'));
copyFileSync(checkSecrets, join(dir, 'scripts', 'check-secrets.mjs'));
}
/** Run the staged installer inside `dir`; returns { code, out }. */
function install(dir) {
try {
const out = execFileSync('node', [join(dir, 'scripts', 'setup-git-hooks.mjs')], { cwd: dir, encoding: 'utf8' });
return { code: 0, out };
} catch (err) {
return { code: err.status, out: `${err.stdout || ''}${err.stderr || ''}` };
}
}
/**
* Invoke the installed hook the way git does: refs on stdin, remote name and
* URL as argv. `env` overrides are merged in.
*/
function runHook(dir, stdin, env = {}) {
try {
const out = execFileSync('sh', [join(dir, '.git', 'hooks', 'pre-push'), 'threews', 'https://example.invalid'], {
cwd: dir,
input: stdin,
encoding: 'utf8',
env: { ...process.env, PATH: `${shimDir}:${process.env.PATH}`, ...env },
});
return { code: 0, out };
} catch (err) {
return { code: err.status, out: `${err.stdout || ''}${err.stderr || ''}` };
}
}
function git(dir, args) {
return execFileSync('git', ['-c', 'user.email=t@t', '-c', 'user.name=t', ...args], { cwd: dir, encoding: 'utf8' });
}
/** Commit everything and return the new sha. */
function commitAll(dir, message) {
git(dir, ['add', '-A']);
git(dir, ['commit', '-q', '-m', message, '--no-verify']);
return git(dir, ['rev-parse', 'HEAD']).trim();
}
beforeAll(() => {
sandbox = mkdtempSync(join(tmpdir(), 'hook-guard-'));
// A git-lfs stand-in that records the stdin it was handed, so the pass-through
// can be asserted rather than assumed.
shimDir = join(sandbox, 'bin');
mkdirSync(shimDir, { recursive: true });
const lfsLog = join(sandbox, 'lfs-stdin.txt');
writeFileSync(join(shimDir, 'git-lfs'), `#!/bin/sh\ncat > "${lfsLog}"\necho "lfs-shim ran"\nexit 0\n`);
execFileSync('chmod', ['755', join(shimDir, 'git-lfs')]);
repo = join(sandbox, 'repo');
mkdirSync(repo, { recursive: true });
git(repo, ['init', '-q']);
// The hook shells out to `node scripts/check-rules.mjs` and
// `node scripts/check-secrets.mjs`, resolved against the pushing repo, so
// both checkers have to exist here too.
stageScripts(repo);
writeFileSync(join(repo, 'clean.js'), 'export const ok = 1;\n');
commitAll(repo, 'base');
});
afterAll(() => {
rmSync(sandbox, { recursive: true, force: true });
});
describe('setup-git-hooks (installer)', () => {
it('installs an executable pre-push hook', () => {
const { code, out } = install(repo);
expect(code).toBe(0);
expect(out).toContain('installed pre-push hook');
const hookPath = join(repo, '.git', 'hooks', 'pre-push');
expect(existsSync(hookPath)).toBe(true);
expect(statSync(hookPath).mode & 0o111).toBeTruthy();
expect(readFileSync(hookPath, 'utf8')).toContain('check-rules.mjs');
});
it('is idempotent, so every npm install does not rewrite it', () => {
const hookPath = join(repo, '.git', 'hooks', 'pre-push');
const before = readFileSync(hookPath, 'utf8');
const { code, out } = install(repo);
expect(code).toBe(0);
expect(out).not.toContain('installed pre-push hook');
expect(readFileSync(hookPath, 'utf8')).toBe(before);
});
it('upgrades the stock git-lfs hook in place', () => {
const fresh = join(sandbox, 'lfs-repo');
mkdirSync(fresh, { recursive: true });
git(fresh, ['init', '-q']);
stageScripts(fresh);
const hookPath = join(fresh, '.git', 'hooks', 'pre-push');
writeFileSync(hookPath, '#!/bin/sh\ngit lfs pre-push "$@"\n');
const { code } = install(fresh);
expect(code).toBe(0);
const body = readFileSync(hookPath, 'utf8');
expect(body).toContain('check-rules.mjs');
// The LFS behavior it replaced must survive the upgrade.
expect(body).toContain('git lfs pre-push');
});
it('refuses to clobber an unrecognized custom hook', () => {
const fresh = join(sandbox, 'custom-repo');
mkdirSync(fresh, { recursive: true });
git(fresh, ['init', '-q']);
stageScripts(fresh);
const hookPath = join(fresh, '.git', 'hooks', 'pre-push');
const custom = '#!/bin/sh\n# somebody\'s own guard\nexit 0\n';
writeFileSync(hookPath, custom);
const { code, out } = install(fresh);
expect(code).toBe(1);
expect(out).toContain('not overwriting');
expect(readFileSync(hookPath, 'utf8')).toBe(custom);
});
it('exits quietly outside a git repository', () => {
const notARepo = join(sandbox, 'plain-dir');
mkdirSync(notARepo, { recursive: true });
stageScripts(notARepo);
const { code } = install(notARepo);
expect(code).toBe(0);
expect(existsSync(join(notARepo, '.git'))).toBe(false);
});
it('honors core.hooksPath instead of writing where git will not look', () => {
// CLAUDE.md and the stock LFS message both reference core.hooksPath. If the
// installer hardcoded .git/hooks, a repo using hooksPath would get a hook
// git never runs: enforcement silently off, with a file on disk implying
// it is on.
const fresh = join(sandbox, 'hookspath-repo');
const alt = join(fresh, 'my-hooks');
mkdirSync(alt, { recursive: true });
git(fresh, ['init', '-q']);
stageScripts(fresh);
git(fresh, ['config', 'core.hooksPath', 'my-hooks']);
const { code } = install(fresh);
expect(code).toBe(0);
expect(existsSync(join(alt, 'pre-push'))).toBe(true);
expect(existsSync(join(fresh, '.git', 'hooks', 'pre-push'))).toBe(false);
});
});
describe('setup-git-hooks (documented remote)', () => {
// Git remotes are local config and cannot be committed, so a fresh clone has
// only `origin` while CLAUDE.md's instruction is `git push threews main`. That
// command failed in this worktree on 2026-07-30. The installer re-derives the
// documented target so the instruction is true on every machine, which also
// keeps check:claude from red-flagging an innocent clone.
const REMOTE_DOC = [
'### Remotes',
'',
'- `threews` -> `https://github.com/nirholas/three.ws`',
'- `threeD` -> `https://github.com/nirholas/3D-Agent`',
'',
'When the user asks you to push: `git push threews main`.',
'',
].join('\n');
/** A repo with a CLAUDE.md remote table and only an `origin` remote, like a clone. */
function cloneLikeRepo(name, doc = REMOTE_DOC) {
const dir = join(sandbox, name);
mkdirSync(dir, { recursive: true });
git(dir, ['init', '-q']);
stageScripts(dir);
writeFileSync(join(dir, 'CLAUDE.md'), doc);
git(dir, ['remote', 'add', 'origin', 'https://github.com/nirholas/three.ws']);
return dir;
}
const remotesOf = (dir) => git(dir, ['remote']).split('\n').filter(Boolean);
it('adds the push target a clone does not have', () => {
const dir = cloneLikeRepo('clone-like');
const { code, out } = install(dir);
expect(code).toBe(0);
expect(out).toContain('added the `threews` remote');
expect(remotesOf(dir)).toContain('threews');
expect(git(dir, ['remote', 'get-url', 'threews']).trim()).toBe('https://github.com/nirholas/three.ws');
});
it('never creates the retired mirror, which the doc forbids fetching from', () => {
const dir = cloneLikeRepo('no-mirror');
install(dir);
// `threeD` is in the documented table but is not the push target, so it must
// not be created. Fetching from it has corrupted this repo's history before.
expect(remotesOf(dir)).not.toContain('threeD');
});
it('leaves an existing remote of that name untouched', () => {
const dir = cloneLikeRepo('existing-remote');
git(dir, ['remote', 'add', 'threews', 'https://github.com/someone/fork']);
install(dir);
// Repointing somebody's remote is how a push ends up at the wrong repo.
// Surfacing the mismatch is check:claude's job, not this script's.
expect(git(dir, ['remote', 'get-url', 'threews']).trim()).toBe('https://github.com/someone/fork');
});
it('is idempotent across installs', () => {
const dir = cloneLikeRepo('remote-idempotent');
install(dir);
const { out } = install(dir);
expect(out).not.toContain('added the');
expect(remotesOf(dir).filter((r) => r === 'threews')).toHaveLength(1);
});
it('does nothing when the doc names no push target', () => {
const dir = cloneLikeRepo('no-target', '# No remote table and no push instruction here.\n');
const { code } = install(dir);
expect(code).toBe(0);
expect(remotesOf(dir)).toEqual(['origin']);
});
it('still installs the hook when the remote is already correct', () => {
// The hook is the load-bearing half; remote setup must never short-circuit it.
const dir = cloneLikeRepo('hook-still-installed');
git(dir, ['remote', 'add', 'threews', 'https://github.com/nirholas/three.ws']);
const { code } = install(dir);
expect(code).toBe(0);
expect(existsSync(join(dir, '.git', 'hooks', 'pre-push'))).toBe(true);
});
});
describe('pre-push hook (behavior)', () => {
let baseSha;
let cleanSha;
let dirtySha;
beforeAll(() => {
install(repo);
baseSha = git(repo, ['rev-parse', 'HEAD']).trim();
writeFileSync(join(repo, 'added.js'), 'export const fine = 2;\n');
cleanSha = commitAll(repo, 'feat(test): add a module that follows every hard rule');
writeFileSync(join(repo, 'bad.js'), `${STUB_COMMENT}\nexport const x = 1;\n`);
dirtySha = commitAll(repo, 'feat(test): add a module whose body breaks a hard rule');
});
it('passes a clean push and hands the refs to git-lfs', () => {
const { code, out } = runHook(repo, `refs/heads/main ${cleanSha} refs/heads/main ${baseSha}\n`);
expect(code).toBe(0);
expect(out).toContain('lfs-shim ran');
// Property 2: the refs the hook consumed on stdin must reach LFS.
expect(readFileSync(join(sandbox, 'lfs-stdin.txt'), 'utf8')).toContain(cleanSha);
});
it('blocks a push whose commits break a hard rule, naming the file', () => {
const { code, out } = runHook(repo, `refs/heads/main ${dirtySha} refs/heads/main ${cleanSha}\n`);
expect(code).toBe(1);
expect(out).toContain('bad.js');
expect(out).toContain('SKIP_PUSH_CHECKS=1');
});
it('blocks a push whose commit subject is a generic sweep message', () => {
// The 22-of-60 "chore: sync working tree" era: the message lint rejects
// the subject even when the diff itself is clean.
writeFileSync(join(repo, 'swept.js'), 'export const swept = 4;\n');
const sweepSha = commitAll(repo, 'chore: sync working tree');
try {
const { code, out } = runHook(repo, `refs/heads/main ${sweepSha} refs/heads/main ${dirtySha}\n`);
expect(code).toBe(1);
expect(out).toContain('meaningless subject');
expect(out).toContain('sync working tree');
} finally {
git(repo, ['reset', '-q', '--hard', dirtySha]);
}
});
it('blocks a subject too short to describe anything, allows a neutral revert', () => {
writeFileSync(join(repo, 'short.js'), 'export const s = 5;\n');
const shortSha = commitAll(repo, 'fix: tweak');
writeFileSync(join(repo, 'short.js'), 'export const s = 6;\n');
const revertSha = commitAll(repo, 'Revert previous change');
try {
const blocked = runHook(repo, `refs/heads/main ${shortSha} refs/heads/main ${dirtySha}\n`);
expect(blocked.code).toBe(1);
expect(blocked.out).toContain('too short');
// The neutral revert wording CLAUDE.md mandates must pass the lint.
const allowed = runHook(repo, `refs/heads/main ${revertSha} refs/heads/main ${shortSha}\n`);
expect(allowed.out).not.toContain('meaningless subject');
expect(allowed.code).toBe(0);
} finally {
git(repo, ['reset', '-q', '--hard', dirtySha]);
}
});
it('does not run git-lfs when it blocks, so a rejected push uploads nothing', () => {
writeFileSync(join(sandbox, 'lfs-stdin.txt'), 'untouched');
const { code } = runHook(repo, `refs/heads/main ${dirtySha} refs/heads/main ${cleanSha}\n`);
expect(code).toBe(1);
expect(readFileSync(join(sandbox, 'lfs-stdin.txt'), 'utf8')).toBe('untouched');
});
it('SKIP_PUSH_CHECKS bypasses the check but still runs git-lfs', () => {
const { code, out } = runHook(repo, `refs/heads/main ${dirtySha} refs/heads/main ${cleanSha}\n`, {
SKIP_PUSH_CHECKS: '1',
});
expect(code).toBe(0);
expect(out).toContain('lfs-shim ran');
expect(out).not.toContain('hard-rule');
});
it('skips a ref deletion, which pushes no commits to check', () => {
const { code } = runHook(repo, `(delete) ${ZERO} refs/heads/gone ${dirtySha}\n`);
expect(code).toBe(0);
});
it('skips a brand-new remote branch, where the zero base is not a diffable range', () => {
const { code } = runHook(repo, `refs/heads/new ${dirtySha} refs/heads/new ${ZERO}\n`);
expect(code).toBe(0);
});
it('skips a remote sha absent from the local object database', () => {
// A stale remote tip that was never fetched cannot be diffed against.
// Erroring here would block pushes for a reason the author cannot act on.
const unknown = 'd'.repeat(40);
const { code } = runHook(repo, `refs/heads/main ${dirtySha} refs/heads/main ${unknown}\n`);
expect(code).toBe(0);
});
it('blocks the whole push when any one of several refs is dirty', () => {
const stdin =
`refs/heads/main ${cleanSha} refs/heads/main ${baseSha}\n` +
`refs/heads/other ${dirtySha} refs/heads/other ${cleanSha}\n`;
const { code, out } = runHook(repo, stdin);
expect(code).toBe(1);
expect(out).toContain('bad.js');
});
it('judges only the pushed commits, ignoring dirty working-tree state', () => {
// The reason the hook uses --base/--head instead of a worktree check:
// concurrent agents share this checkout, so an unrelated in-flight file
// must never block a push of already-committed clean work.
const stray = join(repo, 'stray-agent-file.js');
writeFileSync(stray, `${STUB_COMMENT}\nexport const y = 3;\n`);
try {
const { code } = runHook(repo, `refs/heads/main ${cleanSha} refs/heads/main ${baseSha}\n`);
expect(code).toBe(0);
} finally {
rmSync(stray, { force: true });
}
});
});
describe('this repository', () => {
it('has the current hook version installed', () => {
// 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');
expect(body).toContain('git lfs pre-push');
});
it('reinstalls the hook from postinstall, so a fresh clone is covered', () => {
const pkg = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8'));
expect(pkg.scripts.postinstall).toContain('setup-git-hooks.mjs');
});
});