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.

15.4 KB
Raw Blame
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { execFileSync } from 'node:child_process';
import { mkdtempSync, rmSync, writeFileSync, mkdirSync, copyFileSync, readFileSync, existsSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { proveGuard, normalizeProof, VERDICTS } from '../scripts/lib/guard-proofs.mjs';

// Guards the guard. audit-guards is the only thing standing between
// data/guards.json and quiet fiction, and it is rendered in two public places
// (docs/guards.md and /guards), so a false claim there misleads every reader
// rather than just failing a build.
//
// The claim most likely to rot is the stage column. A guard can be dropped from
// the gate chain in a one-word edit while its registry entry still says "gate",
// and nothing about the repo looks wrong afterwards: the script exists, the npm
// script exists, the docs render. Only comparing the claim against the real npm
// chain catches it, so that case is covered from both directions here.
//
// Each test builds a complete miniature repo rather than mutating the real one,
// because the real registry is supposed to stay green and a test that edits it
// would race every other agent working in this worktree.

const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const auditor = join(repoRoot, 'scripts', 'audit-guards.mjs');

let sandbox;

/**
 * Build a miniature repo: the auditor, a package.json, a data/guards.json, and
 * a stub file for every script the registry mentions.
 */
function makeRepo(name, { guards, exempt = [], stages, scripts, extraScripts = [], hookTemplate }) {
	const dir = join(sandbox, name);
	mkdirSync(join(dir, 'scripts', 'lib'), { recursive: true });
	mkdirSync(join(dir, 'data'), { recursive: true });
	copyFileSync(auditor, join(dir, 'scripts', 'audit-guards.mjs'));
	// The auditor imports its proof helpers relatively, so the sandbox repo
	// needs the lib file at the same path or every scenario dies on import.
	copyFileSync(join(dirname(auditor), 'lib', 'guard-proofs.mjs'), join(dir, 'scripts', 'lib', 'guard-proofs.mjs'));

	for (const g of guards) {
		if (g.script && g.__skipFile !== true) {
			writeFileSync(join(dir, g.script), '#!/usr/bin/env node\n');
		}
	}
	for (const rel of extraScripts) writeFileSync(join(dir, rel), '#!/usr/bin/env node\n');
	if (hookTemplate !== undefined) writeFileSync(join(dir, 'scripts', 'setup-git-hooks.mjs'), hookTemplate);

	writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'fixture', scripts }, null, 2));
	const registry = {
		updated: '2026-07-30',
		summary: 'fixture',
		stages: stages ?? [
			{ id: 'prebuild', title: 'Prebuild', when: 'x', description: 'y' },
			{ id: 'gate', title: 'Gate', when: 'x', description: 'y' },
			{ id: 'build:gcp', title: 'Deploy build', when: 'x', description: 'y' },
			{ id: 'deploy:submit', title: 'Deploy submit', when: 'x', description: 'y' },
			{ id: 'pre-push', title: 'Pre-push', when: 'x', description: 'y' },
			{ id: 'manual', title: 'On demand', when: 'x', description: 'y' },
		],
		guards: guards.map(({ __skipFile, ...g }) => g),
		// Every fixture necessarily contains a copy of the auditor, which the
		// reverse check would otherwise report as an unregistered guard. The
		// real repo registers it properly instead of exempting it.
		exempt: [...exempt, { pattern: 'scripts/audit-guards.mjs', reason: 'the auditor under test' }],
	};
	writeFileSync(join(dir, 'data', 'guards.json'), JSON.stringify(registry, null, 2));
	// The auditor also checks the published copy the /guards page fetches, and
	// requires it byte-identical to the tab-serialized registry. Without it every
	// fixture would fail on that one note regardless of what it means to test.
	mkdirSync(join(dir, 'public'), { recursive: true });
	writeFileSync(join(dir, 'public', 'guards.json'), `${JSON.stringify(registry, null, '\t')}\n`);
	// Same story for docs/guards.md: the auditor requires every registered guard
	// to appear in its tables by npm command, so each fixture gets a minimal
	// table naming its guards.
	mkdirSync(join(dir, 'docs'), { recursive: true });
	const docRows = registry.guards
		.flatMap((g) => [g.npm, ...(g.npmAliases || [])])
		.filter(Boolean)
		.map((n) => `| ${n} | \`npm run ${n}\` | fixture |`)
		.join('\n');
	writeFileSync(join(dir, 'docs', 'guards.md'), `| Guard | Command | Protects |\n|---|---|---|\n${docRows}\n`);
	return dir;
}

function run(dir) {
	try {
		return { code: 0, out: execFileSync('node', [join(dir, 'scripts', 'audit-guards.mjs')], { encoding: 'utf8' }) };
	} catch (err) {
		return { code: err.status, out: `${err.stdout || ''}${err.stderr || ''}` };
	}
}

/** A registry entry that passes every check, used as the baseline to break. */
const goodGuard = {
	id: 'check-thing',
	script: 'scripts/check-thing.mjs',
	npm: 'check:thing',
	title: 'A thing',
	protects: 'The thing.',
	why: 'Because the thing broke once.',
	stages: ['gate'],
	needs: 'none',
	// The auditor requires every guard to declare a proof; the sandboxed
	// two-sided kind is exercised by the 'guard proofs' block below, so fixtures
	// here use the declared-live escape hatch.
	proof: { kind: 'live', reason: 'fixture guard, proven elsewhere' },
};
const goodScripts = { 'check:thing': 'node scripts/check-thing.mjs', gate: 'npm run check:thing' };

beforeAll(() => {
	sandbox = mkdtempSync(join(tmpdir(), 'guard-registry-'));
});

afterAll(() => {
	rmSync(sandbox, { recursive: true, force: true });
});

describe('audit-guards', () => {
	it('passes on a registry that tells the truth', () => {
		const dir = makeRepo('good', { guards: [goodGuard], scripts: goodScripts });
		const { code, out } = run(dir);
		expect(code).toBe(0);
		expect(out).toContain('1 guards registered');
		expect(out).toContain('gate:1');
	});

	it('fails when a registered script does not exist', () => {
		const dir = makeRepo('missing-script', {
			guards: [{ ...goodGuard, __skipFile: true }],
			scripts: goodScripts,
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('does not exist');
	});

	it('fails when the npm script it claims is missing', () => {
		const dir = makeRepo('missing-npm', {
			guards: [goodGuard],
			scripts: { gate: 'npm run check:thing' },
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('missing from package.json');
	});

	it('fails when the npm script does not actually run the guard', () => {
		// The subtle one: the name exists, so a naive check passes, but it was
		// repointed at a different script during a rename.
		const dir = makeRepo('npm-mismatch', {
			guards: [goodGuard],
			scripts: { 'check:thing': 'node scripts/check-other.mjs', gate: 'npm run check:thing' },
			extraScripts: ['scripts/check-other.mjs'],
			exempt: [{ pattern: 'scripts/check-other.mjs', reason: 'fixture' }],
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('does not actually run');
	});

	it('fails when a guard claims a stage it is not wired into', () => {
		// The claim most likely to rot: dropped from the chain, still advertised.
		const dir = makeRepo('stage-lie', {
			guards: [goodGuard],
			scripts: { 'check:thing': 'node scripts/check-thing.mjs', gate: 'npm run something-else' },
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('claims it runs in `gate`');
		expect(out).toContain('not in the gate chain');
	});

	it('does not confuse a prefix for a real gate entry', () => {
		// `npm run check:thing-extra` must not satisfy a claim for `check:thing`.
		const dir = makeRepo('prefix-trap', {
			guards: [goodGuard],
			scripts: {
				'check:thing': 'node scripts/check-thing.mjs',
				'check:thing-extra': 'node scripts/check-thing.mjs',
				gate: 'npm run check:thing-extra',
			},
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('claims it runs in `gate`');
	});

	it('verifies a prebuild claim against the raw node call, not an npm name', () => {
		const base = { ...goodGuard, stages: ['prebuild'] };
		const wired = makeRepo('prebuild-ok', {
			guards: [base],
			scripts: { 'check:thing': 'node scripts/check-thing.mjs', prebuild: 'node scripts/check-thing.mjs' },
		});
		expect(run(wired).code).toBe(0);

		const unwired = makeRepo('prebuild-lie', {
			guards: [base],
			scripts: { 'check:thing': 'node scripts/check-thing.mjs', prebuild: 'node scripts/build-something.mjs' },
		});
		const { code, out } = run(unwired);
		expect(code).toBe(1);
		expect(out).toContain('the prebuild chain');
	});

	it('verifies a pre-push claim against the installed hook template', () => {
		const base = { ...goodGuard, stages: ['pre-push'] };
		const wired = makeRepo('hook-ok', {
			guards: [base],
			scripts: goodScripts,
			hookTemplate: 'node scripts/check-thing.mjs --base "$remote_sha"',
		});
		expect(run(wired).code).toBe(0);

		const unwired = makeRepo('hook-lie', {
			guards: [base],
			scripts: goodScripts,
			hookTemplate: 'echo "no guards here"',
		});
		const { code, out } = run(unwired);
		expect(code).toBe(1);
		expect(out).toContain('the pre-push hook template');
	});

	it('accepts an alias name when the gate runs the variant', () => {
		// check-cron-drift is registered under its primary name but the gate runs
		// its --offline variant, which is a different npm script.
		const dir = makeRepo('alias', {
			guards: [{ ...goodGuard, npmAliases: ['check:thing-offline'] }],
			scripts: {
				'check:thing': 'node scripts/check-thing.mjs',
				'check:thing-offline': 'node scripts/check-thing.mjs --offline',
				gate: 'npm run check:thing-offline',
			},
		});
		expect(run(dir).code).toBe(0);
	});

	it('fails when a guard on disk is not registered at all', () => {
		const dir = makeRepo('unregistered', {
			guards: [goodGuard],
			scripts: goodScripts,
			extraScripts: ['scripts/audit-secret.mjs'],
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('audit-secret.mjs');
		expect(out).toContain('not in data/guards.json');
	});

	it('accepts an unregistered script that matches an exempt pattern', () => {
		const dir = makeRepo('exempt-ok', {
			guards: [goodGuard],
			scripts: goodScripts,
			extraScripts: ['scripts/verify-vendor.mjs', 'scripts/audit-thing.mjs'],
			exempt: [
				{ pattern: 'scripts/verify-*.mjs', reason: 'vendor integration check' },
				{ pattern: 'scripts/audit-thing.mjs', reason: 'fixture' },
			],
		});
		expect(run(dir).code).toBe(0);
	});

	it('does not let an exempt glob leak across directories', () => {
		// `scripts/*` must not match `scripts/nested/x.mjs`; the auditor only reads
		// the top level, but the pattern itself must stay tight.
		const dir = makeRepo('glob-tight', {
			guards: [goodGuard],
			scripts: goodScripts,
			extraScripts: ['scripts/audit-loose.mjs'],
			exempt: [{ pattern: 'scripts/check-*.mjs', reason: 'only checks' }],
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('audit-loose.mjs');
	});

	it('rejects an exempt pattern with no reason', () => {
		const dir = makeRepo('exempt-no-reason', {
			guards: [goodGuard],
			scripts: goodScripts,
			extraScripts: ['scripts/audit-thing.mjs'],
			exempt: [{ pattern: 'scripts/audit-thing.mjs', reason: '' }],
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('gives no reason');
	});

	it('requires the fields the docs and the page render', () => {
		const dir = makeRepo('missing-copy', {
			guards: [{ ...goodGuard, why: '' }],
			scripts: goodScripts,
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('missing `why`');
	});

	it('rejects an unknown stage rather than silently ignoring it', () => {
		const dir = makeRepo('bad-stage', {
			guards: [{ ...goodGuard, stages: ['someday'] }],
			scripts: goodScripts,
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('unknown stage');
	});

	it('flags a verifiable stage the registry never describes for readers', () => {
		const dir = makeRepo('undescribed-stage', {
			guards: [goodGuard],
			scripts: goodScripts,
			stages: [{ id: 'gate', title: 'Gate', when: 'x', description: 'y' }],
		});
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('never describes it for readers');
	});

	it('fails when a json-op proof edits a file that does not exist', () => {
		// The rot that motivated this: public/event.json was deliberately retired
		// while its guard's proof kept editing it in place, which crashed every
		// prove run at apply time. The auditor must catch the dead target first.
		const jsonOpGuard = {
			...goodGuard,
			proof: {
				summary: 'fixture violation via json op',
				violation: { json: [{ file: 'public/gone.json', pointer: 'items', insert: { a: 1 } }] },
				expect: 'gone',
			},
		};
		const dir = makeRepo('json-op-dead-target', { guards: [jsonOpGuard], scripts: goodScripts });
		const { code, out } = run(dir);
		expect(code).toBe(1);
		expect(out).toContain('the fixture can never apply');

		const okDir = makeRepo('json-op-live-target', { guards: [jsonOpGuard], scripts: goodScripts });
		writeFileSync(join(okDir, 'public', 'gone.json'), '{"items": []}\n');
		expect(run(okDir).code).toBe(0);
	});
});

describe('guard proofs', () => {
	it('reports an unappliable fixture as a failing verdict instead of throwing', () => {
		// A throw here would abort the whole prove run and silently skip every
		// guard after the broken one, so the runner depends on this contract.
		const dir = join(sandbox, 'proof-apply-error');
		mkdirSync(dir, { recursive: true });
		const proof = normalizeProof({
			id: 'check-thing',
			proof: {
				summary: 'edits a file that is not there',
				violation: { json: [{ file: 'public/gone.json', pointer: 'items', insert: { a: 1 } }] },
				expect: 'gone',
			},
		});
		const result = proveGuard({ id: 'check-thing', command: 'true' }, proof, dir, {
			run: () => ({ code: 0, output: '', timedOut: false, ms: 1 }),
		});
		expect(result.verdict).toBe(VERDICTS.CONTROL_FAILED);
		expect(result.note).toContain('could not be applied');
		expect(result.output).toContain('gone.json');
		// The sandbox is left exactly as it was found.
		expect(existsSync(join(dir, 'public', 'gone.json'))).toBe(false);
	});
});

describe('this repository', () => {
	it('has a registry that passes its own audit', () => {
		const { code, out } = (() => {
			try {
				return { code: 0, out: execFileSync('node', [auditor], { cwd: repoRoot, encoding: 'utf8' }) };
			} catch (err) {
				return { code: err.status, out: `${err.stdout || ''}${err.stderr || ''}` };
			}
		})();
		expect(code, out).toBe(0);
	});

	it('registers every guard the gate actually runs', () => {
		// The gate is the chain a human is told to run before calling work done,
		// so anything in it must be explainable from the registry.
		const pkg = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8'));
		const registry = JSON.parse(readFileSync(join(repoRoot, 'data', 'guards.json'), 'utf8'));
		const known = new Set(registry.guards.flatMap((g) => [g.npm, ...(g.npmAliases || [])].filter(Boolean)));
		// Test stages are covered by the test files themselves, not by this registry.
		const notGuards = new Set(['test:gate', 'test:gate-3d']);
		const gateSteps = [...pkg.scripts.gate.matchAll(/npm run ([a-z0-9:._-]+)/g)].map((m) => m[1]);
		const unexplained = gateSteps.filter((s) => !known.has(s) && !notGuards.has(s));
		expect(unexplained, `gate steps missing from data/guards.json: ${unexplained.join(', ')}`).toEqual([]);
	});
});