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
#!/usr/bin/env node
// Enforce the CLAUDE.md hard rules on the lines you actually changed.
//
// The hard rules (no TODOs, no stubs, no fake data, no em-dashes) were enforced
// only by agent discipline, which means they were enforced unevenly. A
// repo-wide sweep is not an option: 5,985 tracked files already contain an
// em-dash, and rewriting them all would be a catastrophic diff that buries
// every real change for a month.
//
// So this guard is DIFF-SCOPED. It reads added lines only, which stops the
// bleeding without touching history: your change is held to the rules, the
// legacy around it is left alone until someone touches it deliberately. That
// makes the rules enforceable today instead of aspirational forever.
//
// Modes:
// node scripts/check-rules.mjs working tree + staged, vs HEAD
// node scripts/check-rules.mjs --staged staged only (pre-commit)
// node scripts/check-rules.mjs --base <ref> everything since <ref> (branch review)
// node scripts/check-rules.mjs --base <ref> --head <ref> a pushed ref that is not HEAD (pre-push hook)
// node scripts/check-rules.mjs --paths a.js b.js only these files
//
// --paths matters here: concurrent agents share this worktree, so a bare
// `git diff HEAD` shows everyone's in-flight work, not yours. Scope to the
// files you touched and you get a verdict on YOUR change.
//
// In --base mode (the pre-push hook) it ALSO lints the subject line of every
// commit in base..head. History filled up with "chore: sync working tree"
// sweeps that say nothing about the diff they carry, which makes the log
// useless for archaeology. A subject must describe the change: banned generic
// subjects and sub-15-character subjects fail the push. Merge commits and the
// deliberately-neutral revert messages CLAUDE.md mandates are exempt.
//
// Exit 1 on any violation, with file:line and the rule broken.
import { execFileSync } from 'node:child_process';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const argv = process.argv.slice(2);
const staged = argv.includes('--staged');
const baseIdx = argv.indexOf('--base');
const base = baseIdx === -1 ? null : argv[baseIdx + 1];
const headIdx = argv.indexOf('--head');
const head = headIdx === -1 ? 'HEAD' : argv[headIdx + 1];
const pathsIdx = argv.indexOf('--paths');
const paths = pathsIdx === -1 ? [] : argv.slice(pathsIdx + 1).filter((a) => !a.startsWith('--'));
const git = (args) =>
execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
// Generated, vendored, and build output. Changes here are machine-written, so
// holding them to prose rules produces noise and no signal.
const SKIP = [
/^dist\//,
/^dist-lib\//,
// The Marketplace Action executes this generated ncc bundle directly. Its
// source remains fully scanned under satellites/glb-quality-gate/src/.
/^satellites\/glb-quality-gate\/dist\//,
/^node_modules\//,
/(^|\/)node_modules\//,
/^public\/chat\/assets\//,
/^public\/locales\//,
/^data\/_generated\//,
/^docs\/ALL\.md$/,
/^CHANGELOG\.md$/,
/^public\/changelog\.(json|xml)$/,
// Machine-written mirrors of tool text that lives in source: the catalog is
// written by scripts/build-mcp-catalog.mjs, the fixture by
// scripts/audit-mcp-golden.mjs --update. Prose rules belong on the tool
// descriptions themselves, not on the generated copies of them.
/^public\/mcp-catalog\.json$/,
/^tests\/fixtures\/mcp-golden-tools\.json$/,
/^locales\//,
// The standalone deployer site's build output. site/build.mjs esbuilds
// site/src into packages/metaplex-agent-mcp/docs/ and copies the HTML and
// CSS beside it, because GitHub Pages serves that directory from main. The
// bundle carries upstream library strings (including a vendored
// not-implemented throw) that no edit of ours can reach. The sources in
// site/ are still scanned.
/^packages\/metaplex-agent-mcp\/docs\//,
// Third-party bundles we vendor to serve from our own origin (e.g. the
// meshopt decoder). The bytes are upstream's, license header included, so
// holding them to house prose rules reports the vendor's copyright line as
// commented-out code. Our own code that loads them is still scanned.
/^public\/vendor\//,
// Whole third-party source trees under third_party/ (MIT drops kept
// byte-identical to upstream so a re-sync stays a diff instead of a merge).
// The prose there is the upstream author's, and rewriting its typography to
// satisfy a house rule would make every future sync conflict on punctuation
// (the current drop carries 1625 em-dashes that are upstream's to fix). Our
// own code and docs that USE them are still scanned, and so is this tree by
// scripts/check-secrets.mjs: a third party's leaked key is still a leaked key
// in our history. Provenance and licences: third_party/README.md.
/^third_party\//,
// Foundry dependencies vendored beside a contracts project (forge-std,
// OpenZeppelin, Uniswap v4-core). Same reasoning as third_party/: the source
// is upstream's, pinned to a commit, and never edited here. Our own contracts,
// tests and scripts next to them are still scanned.
/^contracts\/(.+\/)?lib\//,
/\.min\.(js|css)$/,
/package-lock\.json$/,
/\.(png|jpg|jpeg|gif|webp|glb|gltf|bin|woff2?|ttf|mp4|wasm|ico|svg)$/i,
// The two guards themselves. Their rule tables must contain the banned
// patterns verbatim (the dash characters, the word TODO, the
// not-implemented string) in order to detect them, so scanning them
// reports the detector as the offense. A linter cannot lint its own
// pattern table.
/^scripts\/check-rules\.mjs$/,
/^scripts\/check-claude-md\.mjs$/,
// The guard registry, for the same reason. Every guard there carries a
// PROOF: the exact violation it must reject, stored verbatim so
// scripts/prove-guards.mjs can write it into a sandbox and watch the guard
// fire. Proving this script works therefore requires storing a line that
// this script forbids. Scanning the fixtures reports the evidence as the
// offense. The prose fields (title, protects, why, proof summaries) are
// still held to the typography rule, by scripts/audit-guards.mjs.
/^data\/guards\.json$/,
/^public\/guards\.json$/,
// Captured third-party text, stored verbatim as evidence. The X account
// archive is what was actually published, character for character, so
// rewriting its typography to satisfy a house rule would falsify the
// record the archive exists to preserve. The rule applies to prose we
// write, not to prose we transcribe.
/^data\/x-archive\//,
// The store-submission evidence captures, for the same reason. Each of these
// is a verbatim JSON-RPC wire payload pulled from the LIVE production server
// and kept so an OpenAI or MCP-directory reviewer can diff what we claim
// against what the endpoint actually answers. Normalizing their typography to
// satisfy a house rule falsifies the capture (it was done once, and the
// committed evidence silently stopped matching production). Prose rules
// belong on the tool descriptions in api/, which is where the wording that
// ends up in these files is authored.
/^prompts\/store-submissions\/_generated\/[a-z-]*tools-list\.json$/,
// Captured live API responses, stored verbatim as the evidence a gauntlet run
// produced. Same reasoning as the archive above: the third party's own
// wording is the record, and retyping its punctuation to satisfy a house
// rule would make the evidence a paraphrase of what the endpoint said.
/^prompts\/okx-ai\/e2e-evidence\//,
// The quality-bar audit captures, for the same reason. Every file under
// prompts/quality-bar/_generated/ is written by a harness (e.g.
// scripts/mobile-touch-audit.mjs) against the LIVE site and stores what the
// page actually renders, control labels and document titles included. It is
// the before-and-after evidence a finish work order is scored against, so
// retyping its punctuation would make the record disagree with production
// and hide the very drift the capture exists to prove. The pages whose copy
// these files quote are still scanned.
/^prompts\/quality-bar\/_generated\//,
// The baked animation library. Every clip, the manifest, and the signature
// index are written by scripts/build-animations.mjs and
// scripts/compact-clips.mjs from FBX sources deliberately kept out of the
// repo, so nothing in them is prose anyone wrote. Skipping them also keeps a
// re-bake (117 files, hundreds of MB of diff) out of the diff this guard has
// to read.
/^public\/animations\/clips\//,
/^public\/animations\/(manifest|signatures)\.json$/,
];
const skipped = (file) => SKIP.some((re) => re.test(file));
// Each rule states the CLAUDE.md line it enforces, so a failure teaches the
// rule rather than just blocking. `test` receives the added line's content.
const RULES = [
{
id: 'em-dash',
rule: 'the em-dash and en-dash are banned everywhere in this repo',
test: (line) => /[—–]/.test(line),
// The one legitimate mention is text that names the banned characters.
except: (line) => /em-dash|en-dash|em dash|en dash/i.test(line),
},
{
id: 'todo',
rule: 'no TODO comments, no "implement later", no stub functions',
test: (line) => /(^|[^A-Za-z])(TODO|FIXME|XXX|HACK)\b/.test(line) && /(\/\/|\/\*|\*|#|<!--)/.test(line),
// A guard that forbids TODOs must be allowed to say the word "TODO".
except: (line) => /check-rules|completionist|CLAUDE\.md|eslint|todoPattern/i.test(line),
},
{
id: 'not-implemented',
rule: 'no `throw new Error("not implemented")`, implement it',
test: (line) => /throw new Error\(\s*['"`][^'"`]*not[ _-]?implemented/i.test(line),
},
{
id: 'commented-out-code',
rule: 'no commented-out code in committed work, delete or implement',
// Conservative: only a commented line that ends in a statement
// terminator and contains an assignment or call, which prose never does.
test: (line) => /^\s*\/\/\s*(const|let|var|function|await|return|if\s*\(|for\s*\(|[\w.]+\s*\()/.test(line) && /[;{)]\s*$/.test(line),
except: (line) => /eslint|@ts-|prettier|https?:\/\//.test(line),
},
{
id: 'sample-data',
rule: 'no fallback sample arrays shipped to production, real fetch only',
test: (line) => /^\s*(const|let|var)\s+(sample|mock|fake|dummy|placeholder)[A-Z]\w*\s*=\s*\[/.test(line),
},
];
// Commit-subject lint, --base mode only: the pre-push hook hands us exactly
// the commits leaving the machine, so this is the one place a message rule can
// be enforced without judging other agents' in-flight work. A commit message
// is the only documentation a diff carries into history; "chore: sync working
// tree" documents nothing.
const BANNED_SUBJECTS = new Set([
'sync working tree',
'sync',
'wip',
'update',
'updates',
'change',
'changes',
'misc',
'stuff',
'cleanup',
'clean up',
'minor changes',
'various fixes',
'more work',
'progress',
'checkpoint',
'save work',
'commit',
'work',
]);
if (base) {
let commits = [];
try {
commits = git(['log', '--format=%H%x00%s', `${base}..${head}`]).split('\n').filter(Boolean);
} catch (err) {
console.error(`[check-rules] could not read the commit list (${base}..${head}): ${err.message}`);
process.exit(1);
}
const bad = [];
for (const row of commits) {
const [sha, subject = ''] = row.split('\0');
const s = subject.trim();
// Merge commits are machine-written; neutral revert messages are
// mandated by CLAUDE.md (never echo the reverted content).
if (/^merge /i.test(s)) continue;
if (/^(revert previous change|roll back the prior commit)$/i.test(s)) continue;
// Strip a conventional-commit prefix so `chore: sync` and `sync` are
// judged by the same words.
const meat = s.replace(/^[a-z]+(\([^)]*\))?!?:\s*/i, '').trim();
if (BANNED_SUBJECTS.has(meat.toLowerCase())) {
bad.push({ sha, subject: s, why: 'generic sweep subject, says nothing about the diff' });
} else if (meat.length < 15) {
bad.push({ sha, subject: s, why: 'subject too short to describe the change (min 15 chars after the type prefix)' });
}
}
if (bad.length) {
console.error(`[check-rules] ${bad.length} commit(s) being pushed have a meaningless subject:\n`);
for (const b of bad) {
console.error(`[check-rules] ${b.sha.slice(0, 9)} "${b.subject}"`);
console.error(`[check-rules] ${b.why}`);
}
console.error('\n[check-rules] CLAUDE.md rule: every commit message describes the actual diff,');
console.error('[check-rules] `type(scope): what changed and why a reader would care`.');
console.error('[check-rules] Reword with `git commit --amend` (last commit) or a rebase, then push again.');
process.exit(1);
}
}
// Which revisions to compare. The file list and the diff itself are read
// against this same selector.
let range;
if (base) range = [`${base}...${head}`];
else if (staged) range = ['--staged'];
else range = ['HEAD'];
// Read the changed file names first, then diff them in batches, rather than
// asking git for one blob. Two reasons, both load-bearing at push time: the
// SKIP list drops generated output BEFORE git prints it, and no single spawn
// has to hold the whole diff. A push that re-baked the animation library
// produced a 215 MB diff, which overflowed execFileSync's buffer and failed the
// push with `spawnSync git ENOBUFS` (2026-09-01). That reads like a rule
// violation and is not one, and the only way past it was to bypass the guard.
const FILES_PER_DIFF = 100;
const listArgs = ['diff', '--name-only', '-z', ...range];
if (paths.length) listArgs.push('--', ...paths);
let changedFiles;
try {
changedFiles = git(listArgs).split('\0').filter(Boolean);
} catch (err) {
console.error(`[check-rules] could not list the changed files (${listArgs.join(' ')}): ${err.message}`);
process.exit(1);
}
const scannable = changedFiles.filter((f) => !skipped(f));
// Where a file MOVED, batch its old path alongside its new one. Git pairs the
// two into a rename and diffs only the lines that actually changed, but that
// pairing needs both paths inside the same pathspec: limit the diff to the new
// path alone (which is all `--name-only` prints) and git falls back to calling
// it a brand-new file, so every legacy line in a file someone merely moved
// reads as an added line. That turned the 2026-09-02 move of 228 work orders
// into `prompts/finish/` into 293 phantom em-dash violations in prose nobody
// wrote that day, which is the exact "rewrite the world to move a file"
// outcome this guard's diff scoping exists to prevent.
const renamedFrom = new Map();
try {
const statusArgs = ['diff', '--name-status', '--find-renames', '-z', ...range];
if (paths.length) statusArgs.push('--', ...paths);
const fields = git(statusArgs).split('\0').filter(Boolean);
for (let i = 0; i < fields.length; i += 1) {
if (!/^R\d*$/.test(fields[i])) continue;
renamedFrom.set(fields[i + 2], fields[i + 1]);
i += 2;
}
} catch {
// Rename detection is an optimization; without it the diff is merely noisier.
}
let diff = '';
for (let i = 0; i < scannable.length; i += FILES_PER_DIFF) {
const batch = scannable.slice(i, i + FILES_PER_DIFF);
const sources = batch.map((f) => renamedFrom.get(f)).filter(Boolean);
const diffArgs = ['diff', '--unified=0', '--find-renames', ...range, '--', ...batch, ...sources];
try {
diff += git(diffArgs);
} catch (err) {
console.error(`[check-rules] could not read the diff for ${batch.length} file(s) starting at ${batch[0]}: ${err.message}`);
process.exit(1);
}
}
// A brand-new file is invisible to `git diff HEAD`: it has no tracked
// counterpart, so nothing shows up and a whole file of TODOs would pass. Treat
// every line of an untracked file as added, which is what it is. Skipped in
// --base mode, where the comparison is between two committed refs.
if (!base) {
const untrackedArgs = ['ls-files', '--others', '--exclude-standard'];
if (paths.length) untrackedArgs.push('--', ...paths);
let untracked = [];
try {
untracked = git(untrackedArgs).split('\n').filter(Boolean);
} catch {
untracked = [];
}
const { readFileSync } = await import('node:fs');
for (const f of untracked) {
if (skipped(f)) continue;
let body;
try {
body = readFileSync(path.join(root, f), 'utf8');
} catch {
continue; // unreadable or binary; nothing to enforce
}
if (body.includes('\u0000')) continue;
diff += `\n+++ b/${f}\n@@ -0,0 +1 @@\n${body.split('\n').map((l) => `+${l}`).join('\n')}\n`;
}
}
// Walk the unified diff, tracking the current file and new-file line number so
// every violation can be reported at a location the author can click.
const violations = [];
let file = null;
let lineNo = 0;
let filesScanned = 0;
for (const raw of diff.split('\n')) {
if (raw.startsWith('+++ ')) {
const p = raw.slice(4).replace(/^b\//, '');
file = p === '/dev/null' ? null : p;
if (file && !skipped(file)) filesScanned += 1;
continue;
}
if (raw.startsWith('@@')) {
const m = raw.match(/\+(\d+)/);
lineNo = m ? Number(m[1]) : 0;
continue;
}
if (!raw.startsWith('+') || raw.startsWith('+++')) continue;
const content = raw.slice(1);
if (file && !skipped(file)) {
for (const r of RULES) {
if (r.test(content) && !(r.except && r.except(content))) {
violations.push({ file, line: lineNo, id: r.id, rule: r.rule, content: content.trim().slice(0, 100) });
}
}
}
lineNo += 1;
}
if (violations.length) {
const byRule = new Map();
for (const v of violations) byRule.set(v.id, (byRule.get(v.id) || 0) + 1);
console.error(`[check-rules] ${violations.length} hard-rule violation(s) in changed lines:\n`);
for (const v of violations) {
console.error(`[check-rules] ${v.file}:${v.line} [${v.id}]`);
console.error(`[check-rules] ${v.rule}`);
console.error(`[check-rules] > ${v.content}`);
}
console.error(
`\n[check-rules] ${[...byRule].map(([k, n]) => `${k}:${n}`).join(' ')} across ${filesScanned} changed file(s).`,
);
console.error('[check-rules] These are CLAUDE.md hard rules. Fix them in this change, not later.');
process.exit(1);
}
console.log(`[check-rules] OK: no hard-rule violations in the added lines of ${filesScanned} changed file(s)`);