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.

test(examples): feed the marker-guard fixture a scratch file, not the real doc

nirholas0550c3e5870b
diff --git a/docs/avatar-thumbnails.md b/docs/avatar-thumbnails.md
index 69e1242b9..ea5ec638e 100644
--- a/docs/avatar-thumbnails.md
+++ b/docs/avatar-thumbnails.md
@@ -214,7 +214,7 @@ const { url, bytes, ms } = await renderThumbnail({
console.log(url, bytes, ms); // https://<cdn>/thumb/<id>.png 104356 5182
console.log(await coverage());
-// { total: 12754, covered: 2988, missing: 9766, exhausted: 0 }
+// { total: 26398, covered: 26361, missing: 37, exhausted: 33 }
```
`renderThumbnail()` uploads the PNG **before** it writes the key, so a failed upload
diff --git a/scripts/build-examples-index.mjs b/scripts/build-examples-index.mjs
index f24c2fd17..39cb95abc 100644
--- a/scripts/build-examples-index.mjs
+++ b/scripts/build-examples-index.mjs
@@ -18,7 +18,7 @@
// or an HTML <title>/comment, never from a hand-kept list here.
import { readFileSync, writeFileSync, readdirSync, existsSync, statSync, renameSync } from 'node:fs';
-import { join, relative, basename, dirname } from 'node:path';
+import { join, relative, resolve, basename, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
// Write through a temp file in the same directory, then rename. rename(2) is
@@ -302,7 +302,18 @@ writeAtomic(OUT, `${JSON.stringify(payload, null, '\t')}\n`);
// Mirror the same index into docs/examples.md between markers, so the doc's
// inventory is regenerated rather than hand-kept. Everything outside the
// markers is hand-written and left untouched.
-const DOC = join(root, 'docs/examples.md');
+//
+// EXAMPLES_DOC retargets that mirror at another file. The marker-guard test
+// needs to feed this generator a deliberately broken doc, and doing that to the
+// real docs/examples.md leaves the repo holding the broken fixture whenever the
+// run dies before its restore (a SIGKILLed vitest fork, a cancelled CI job),
+// which then fails every later run against a doc nobody edited. Pointing the
+// test at a scratch file keeps the hazard out of the worktree entirely.
+const DOC = process.env.EXAMPLES_DOC ? resolve(process.env.EXAMPLES_DOC) : join(root, 'docs/examples.md');
+// Repo-relative reads best for the real doc; anything outside the repo (a test's
+// scratch file) is named in full rather than as a pile of `../`.
+const _docRel = relative(root, DOC);
+const DOC_LABEL = !_docRel || _docRel.startsWith('..') ? DOC : _docRel;
const START = '<!-- BEGIN GENERATED EXAMPLES INDEX (npm run build:examples) -->';
const END = '<!-- END GENERATED EXAMPLES INDEX -->';
@@ -360,7 +371,7 @@ if (startAt !== -1 && endAt !== -1 && endAt > startAt) {
next = `${doc.trimEnd()}\n\n---\n\n${block}\n`;
} else {
throw new Error(
- `docs/examples.md has a malformed generated block (START at ${startAt}, END at ${endAt}). ` +
+ `${DOC_LABEL} has a malformed generated block (START at ${startAt}, END at ${endAt}). ` +
'Fix or remove the markers by hand; refusing to rewrite the file.',
);
}
@@ -370,7 +381,7 @@ if (startAt !== -1 && endAt !== -1 && endAt > startAt) {
const handWritten = (text) => text.split(START)[0].trim().length;
if (handWritten(next) < handWritten(doc)) {
throw new Error(
- 'Refusing to write docs/examples.md: the hand-written section above the generated block ' +
+ `Refusing to write ${DOC_LABEL}: the hand-written section above the generated block ` +
`would shrink from ${handWritten(doc)} to ${handWritten(next)} characters.`,
);
}
diff --git a/tests/examples-index.test.js b/tests/examples-index.test.js
index d4412c23e..c4380ec37 100644
--- a/tests/examples-index.test.js
+++ b/tests/examples-index.test.js
@@ -7,8 +7,9 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { execFileSync } from 'node:child_process';
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
import { join } from 'node:path';
+import { tmpdir } from 'node:os';
const root = process.cwd();
const SCRIPT = join(root, 'scripts/build-examples-index.mjs');
@@ -17,8 +18,8 @@ const JSON_OUT = join(root, 'data/examples.json');
const START = '<!-- BEGIN GENERATED EXAMPLES INDEX (npm run build:examples) -->';
const END = '<!-- END GENERATED EXAMPLES INDEX -->';
-function run() {
- return execFileSync('node', [SCRIPT], { cwd: root, encoding: 'utf8' });
+function run(env = {}) {
+ return execFileSync('node', [SCRIPT], { cwd: root, encoding: 'utf8', env: { ...process.env, ...env } });
}
function handWrittenPart(text) {
@@ -38,11 +39,11 @@ describe('examples index generator', () => {
if (originalJson !== null) writeFileSync(JSON_OUT, originalJson);
}
- // afterEach never runs if the run is interrupted (a killed CI job, a Ctrl-C,
- // a vitest timeout), which would leave the real docs/examples.md holding the
- // malformed fixture below and every later run failing on a doc no one edited.
- // The same restore is therefore armed at the process level for the signals a
- // test run actually dies from.
+ // afterEach never runs if the run is interrupted (a killed CI job, a Ctrl-C, a
+ // vitest timeout). The malformed fixture no longer goes anywhere near the real
+ // doc, so the worst an interrupt can now leave behind is a correctly
+ // regenerated file, but restoring on the catchable signals still keeps the
+ // shared worktree byte-identical to how the run found it.
const onExit = () => restore();
const onSignal = () => {
restore();
@@ -95,9 +96,20 @@ describe('examples index generator', () => {
it('refuses to write when the markers are malformed instead of rewriting the file', () => {
// An END with no START is the shape that would make a naive indexOf pair
- // slice away real content.
- writeFileSync(DOC, `# Examples Gallery\n\nHand written prose.\n\n${END}\n`);
- expect(() => run()).toThrow();
- expect(readFileSync(DOC, 'utf8')).toContain('Hand written prose.');
+ // slice away real content. The broken fixture goes in a scratch file, not
+ // the real docs/examples.md: a fork killed between the write and the
+ // restore used to leave the repo holding it, and every later run then
+ // failed on a doc nobody had edited.
+ const dir = mkdtempSync(join(tmpdir(), 'examples-index-'));
+ const scratch = join(dir, 'examples.md');
+ try {
+ writeFileSync(scratch, `# Examples Gallery\n\nHand written prose.\n\n${END}\n`);
+ expect(() => run({ EXAMPLES_DOC: scratch })).toThrow();
+ expect(readFileSync(scratch, 'utf8')).toContain('Hand written prose.');
+ // The real doc is untouched by the refusal.
+ expect(readFileSync(DOC, 'utf8')).toContain(START);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
});
});