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
feat(publish): add a --stale check so a published npm package can't silently lag its source
nirholas07ebf85a82fd
diff --git a/docs/contributing.md b/docs/contributing.mdindex 1a0caee58..d1ac7a7c8 100644--- a/docs/contributing.md+++ b/docs/contributing.md@@ -205,7 +205,25 @@ GitHub token for that account (`GITHUB_TOKEN`, or the PAT on the `origin` remoteA token for a different account authenticates fine and is then rejected for thatnamespace.-**3. Standalone GitHub mirrors** - about 80 directories in this monorepo also+**3. Catching a published package that lagged its source** (`scripts/lib/stale-packages.mjs`,+run from either publish script):++```bash+npm run publish:stale # or: node scripts/publish-mcp-servers.mjs --stale+```++A publish only happens when someone runs the commands above. If source keeps moving+after that run and nobody runs it again, npm quietly serves a stale tarball forever;+nothing else notices. `--stale` checks every publishable directory (library packages+and MCP servers alike): for each one it reads `npm view <name> time --json`, and if+the local `version` is already on npm, counts commits to that directory after the+publish timestamp that touch something other than `README.md`, `CHANGELOG.md`, or a+test file. A package with such commits is stale; the report prints the exact bump and+publish command for each one and the command exits `1` if anything is stale. A local+version npm has never seen is reported separately as "never published" rather than as+an error. It never calls `npm publish` itself.++**4. Standalone GitHub mirrors** - about 80 directories in this monorepo alsolive in their own public repo at `github.com/<owner>/<name>` (a read-onlymirror; the monorepo stays canonical). [`data/standalone-mirrors.json`](../data/standalone-mirrors.json)is the single source of truth for "which directory is which public repo, indiff --git a/docs/ops/guard-wiring.md b/docs/ops/guard-wiring.mdindex fd80ed114..c1ca4b4cf 100644--- a/docs/ops/guard-wiring.md+++ b/docs/ops/guard-wiring.md@@ -132,6 +132,7 @@ They belong to an operator, or to a post-deploy check.| `check:xai-models` | The Grok catalog (`GROK_MODELS` in `api/_lib/chat-models.js`) against the models xAI serves: ids, context windows and prices, from the xAI API with a key or its public model docs without one | 0 | 0.7s | **manual (ops).** Measured 2026-10-08 against the public docs (no key on this box): 8 of 8 ids in sync. xAI ships and retires models on its own schedule, so it can go red with no diff on our side. Run it when a Grok rung errors or before touching the catalog. || `check:earnings-board` | Every row of `/api/leaderboard/earnings`, in all four windows, against the agent's own `/api/agents/:id/earnings` (creator fees, service income, total, rank) | 2 | 0.2s | **manual (post-deploy).** Measured 2026-10-08 against `https://three.ws`: the board answers 404 because the endpoint landed after the running image (`fe2a8b24f`), so exit 2 is a deploy lag, not a mismatch. Re-run after the next deploy, or point it at a local server with `--base http://localhost:<port>`. The offline half of the same comparison runs in `npm test` as [tests/agent-earnings-board.test.js](../../tests/agent-earnings-board.test.js). || `audit:upstreams:map` | Not a guard: `--map` regenerates `docs/resilience.md` | 0 | 38.6s | **manual (generator).** The guard half, `audit:upstreams`, is already in `gate`. |+| `publish:stale` | Every publishable package's local version against `npm view <name> time --json`, flagging one whose version is already on npm but whose directory has real source commits after that publish | 1 | ~55s for 102 packages | **manual (pre-release).** Network by definition (one `npm view` per package, concurrency 4) and about whether npm lags the repo, not about the diff. Measured 2026-10-14: 60+ of 102 publishable directories are stale, `@three-ws/avatar-agent` among them (1.2.3 published 2026-09-11, 7 real commits since). Run before cutting a release, or whenever "does npm match main" comes up. |### Needs a credential this box does not holddiff --git a/package.json b/package.jsonindex 0511386a3..ffb9f5ebf 100644--- a/package.json+++ b/package.json@@ -371,6 +371,7 @@"check:site-builder-embeds": "node scripts/check-site-builder-embeds.mjs","publish:packages": "node scripts/publish-packages.mjs","publish:packages:dry": "node scripts/publish-packages.mjs --dry-run",+ "publish:stale": "node scripts/publish-packages.mjs --stale","publish:queue:dry": "node scripts/publish-npm-queue.mjs","publish:queue": "node scripts/publish-npm-queue.mjs --publish","publish:mcp": "node scripts/publish-mcp-servers.mjs",diff --git a/scripts/lib/stale-packages.mjs b/scripts/lib/stale-packages.mjsnew file mode 100644index 000000000..73c1120cb--- /dev/null+++ b/scripts/lib/stale-packages.mjs@@ -0,0 +1,250 @@+// Shared staleness check for every npm-publishable package in this repo:+// `scripts/publish-packages.mjs --stale` and `scripts/publish-mcp-servers.mjs --stale`+// both call into this module so the rule lives in exactly one place.+//+// A package is STALE when its local `version` is already on npm and the+// source directory has commits after that version's publish timestamp that+// touch something other than README.md, CHANGELOG.md, or a test file. It is+// UNPUBLISHED when npm has no record of that version at all (a 404 for the+// whole name, or a version npm has never seen) - that is not an error, it+// just means nobody has run the publish script yet.++import { execFileSync } from 'node:child_process';+import { existsSync, readFileSync, readdirSync } from 'node:fs';+import { basename, resolve } from 'node:path';++// Top-level directories (outside packages/) that publish to npm on their own,+// pulled in by name rather than discovered, because they are the only ones.+export const TOP_LEVEL_PUBLISHABLE_DIRS = ['assistant-sdk', 'mcp-server', 'mcp-bridge', 'robinhood/hood-mcp'];++export function isIgnorableFile(path) {+ const base = basename(path);+ if (base === 'README.md' || base === 'CHANGELOG.md') return true;+ if (/\.test\.[cm]?[jt]sx?$/.test(path)) return true;+ if (/(^|\/)(tests?|__tests__)\//.test(path)) return true;+ return false;+}++/**+ * Commits touching `dir` since `sinceISO`, excluding ones whose only changed+ * files are README.md, CHANGELOG.md, or a test file. Runs against whatever+ * git repo contains `cwd` (or `dir` when `cwd` is omitted), so a test can+ * point it at a throwaway repo.+ */+export function commitsSince(dir, sinceISO, { cwd } = {}) {+ // `--since` is inclusive, which would count the publish commit itself (its+ // package.json version bump is real source, not an ignorable file). Push+ // the cutoff one second past the publish timestamp so only commits+ // strictly after it are counted.+ const exclusiveSince = new Date(new Date(sinceISO).getTime() + 1000).toISOString();+ let out;+ try {+ out = execFileSync(+ 'git',+ ['log', `--since=${exclusiveSince}`, '--name-only', '--pretty=format:%H%x01%s', '--', dir],+ { cwd: cwd || dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },+ );+ } catch {+ return [];+ }+ if (!out.trim()) return [];+ const commits = [];+ for (const block of out.trim().split(/\n\s*\n/)) {+ const lines = block.split('\n').filter((l) => l.length > 0);+ if (!lines.length) continue;+ const sep = lines[0].indexOf('\x01');+ if (sep === -1) continue;+ const hash = lines[0].slice(0, sep);+ const subject = lines[0].slice(sep + 1);+ const files = lines.slice(1).filter((f) => !isIgnorableFile(f));+ if (files.length) commits.push({ hash, subject });+ }+ return commits;+}++/** The highest dist-tag-independent version key in a `npm view <name> time --json` payload. */+export function latestPublishedVersion(npmTime) {+ const keys = Object.keys(npmTime).filter((k) => k !== 'created' && k !== 'modified');+ return keys[keys.length - 1];+}++/**+ * Pure classification: given the local version, the registry's `time`+ * payload (or `null` for "name never published", or `'unreadable'` for a+ * 403), and the commits already filtered by `commitsSince`, decide the+ * status. No I/O, so this is what the recorded-fixture test exercises.+ */+export function classify({ name, dir, localVersion, npmTime, commits }) {+ if (npmTime === 'unreadable') return { name, dir, localVersion, status: 'unreadable' };+ if (npmTime === null) return { name, dir, localVersion, status: 'unpublished' };+ const publishedAt = npmTime[localVersion];+ if (!publishedAt) return { name, dir, localVersion, status: 'unpublished' };+ return {+ name,+ dir,+ localVersion,+ publishedAt,+ npmLatest: latestPublishedVersion(npmTime),+ status: commits.length > 0 ? 'stale' : 'ok',+ commits: commits.length,+ newestCommitSubject: commits[0]?.subject || '',+ };+}++function sleep(ms) {+ return new Promise((r) => setTimeout(r, ms));+}++/** `npm view <name> time --json`, treating 404 as "never published" and 403 as "unreadable". */+async function npmViewTime(name, { retries = 3 } = {}) {+ for (let attempt = 0; ; attempt++) {+ try {+ const out = execFileSync('npm', ['view', name, 'time', '--json'], {+ encoding: 'utf8',+ stdio: ['ignore', 'pipe', 'pipe'],+ });+ return JSON.parse(out);+ } catch (err) {+ const stderr = String(err.stderr || err.message || '');+ if (/E404|404 Not Found/i.test(stderr)) return null;+ if (/E403|403 Forbidden/i.test(stderr)) return 'unreadable';+ if (/E429|429 Too Many Requests/i.test(stderr) && attempt < retries) {+ await sleep(500 * 2 ** attempt);+ continue;+ }+ throw new Error(`npm view ${name} time --json failed: ${stderr.split('\n')[0] || err.message}`);+ }+ }+}++async function mapLimit(items, limit, fn) {+ const results = new Array(items.length);+ let next = 0;+ async function worker() {+ for (;;) {+ const i = next++;+ if (i >= items.length) return;+ results[i] = await fn(items[i], i);+ }+ }+ await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));+ return results;+}++function readPkg(dir) {+ return JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8'));+}++/**+ * Every directory under `root` that publishes a non-private package.json:+ * all of packages/*, plus the top-level SDK/MCP directories that publish on+ * their own. Lane (library vs MCP server) does not matter here - staleness+ * is checked the same way regardless of which script ships the version bump.+ */+export function discoverPublishableDirs(root) {+ const found = [];+ const packagesDir = resolve(root, 'packages');+ if (existsSync(packagesDir)) {+ for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {+ if (!entry.isDirectory()) continue;+ const dir = `packages/${entry.name}`;+ if (!existsSync(resolve(root, dir, 'package.json'))) continue;+ if (readPkg(resolve(root, dir)).private) continue;+ found.push(dir);+ }+ }+ for (const dir of TOP_LEVEL_PUBLISHABLE_DIRS) {+ if (!existsSync(resolve(root, dir, 'package.json'))) continue;+ if (readPkg(resolve(root, dir)).private) continue;+ found.push(dir);+ }+ return found.sort();+}++/**+ * Runs the full stale check over `dirs` (repo-relative paths) and returns one+ * row per package. `concurrency` caps simultaneous `npm view` calls so a+ * full sweep does not trip the registry's rate limiter.+ */+export async function checkStale(root, dirs, { concurrency = 4 } = {}) {+ return mapLimit(dirs, concurrency, async (dir) => {+ const pkg = readPkg(resolve(root, dir));+ const name = pkg.name;+ const localVersion = pkg.version;+ let npmTime;+ try {+ npmTime = await npmViewTime(name);+ } catch (err) {+ return { name, dir, localVersion, status: 'error', error: err.message };+ }+ const commits =+ npmTime && npmTime !== 'unreadable' && npmTime[localVersion]+ ? commitsSince(dir, npmTime[localVersion], { cwd: root })+ : [];+ return classify({ name, dir, localVersion, npmTime, commits });+ });+}++export function formatReport(rows, { root } = {}) {+ const lines = [];+ const stale = rows.filter((r) => r.status === 'stale');+ const ok = rows.filter((r) => r.status === 'ok');+ const unpublished = rows.filter((r) => r.status === 'unpublished');+ const unreadable = rows.filter((r) => r.status === 'unreadable');+ const errored = rows.filter((r) => r.status === 'error');++ lines.push(`${rows.length} publishable packages checked.\n`);+ lines.push(+ 'package'.padEnd(38) ++ 'local'.padEnd(10) ++ 'npm latest'.padEnd(14) ++ 'commits since publish'.padEnd(24) ++ 'newest commit',+ );+ for (const r of [...stale, ...ok]) {+ lines.push(+ r.name.padEnd(38) ++ r.localVersion.padEnd(10) ++ (r.npmLatest || '').padEnd(14) ++ String(r.commits).padEnd(24) ++ (r.newestCommitSubject || ''),+ );+ }++ if (unpublished.length) {+ lines.push('\nNever published (not an error - nobody has run the publish script for this version yet):');+ for (const r of unpublished) lines.push(` - ${r.name}@${r.localVersion} (${r.dir})`);+ }+ if (unreadable.length) {+ lines.push('\nUnreadable from this machine (403 on a public lookup):');+ for (const r of unreadable) lines.push(` - ${r.name} (${r.dir})`);+ }+ if (errored.length) {+ lines.push('\nFailed to check:');+ for (const r of errored) lines.push(` - ${r.name} (${r.dir}): ${r.error}`);+ }+ if (stale.length) {+ lines.push('\nStale: local version is on npm, but source has moved since. Bump and publish:');+ for (const r of stale) {+ lines.push(`\n${r.name} (${r.dir})`);+ lines.push(` ${r.commits} commit(s) since ${r.publishedAt}, newest: "${r.newestCommitSubject}"`);+ lines.push(` bump: npm version patch --no-git-tag-version --prefix ${r.dir}`);+ const lane = root && existsSync(resolve(root, r.dir, 'server.json'))+ ? 'scripts/publish-mcp-servers.mjs'+ : 'scripts/publish-packages.mjs';+ lines.push(` publish: node ${lane} --only ${basename(r.dir)}`);+ }+ }+ return lines.join('\n');+}++/** Shared CLI entry point so both publish scripts print and exit identically on `--stale`. */+export async function runStaleCli(root) {+ const dirs = discoverPublishableDirs(root);+ const rows = await checkStale(root, dirs);+ console.log(formatReport(rows, { root }));+ const failed = rows.some((r) => r.status === 'error');+ const stale = rows.some((r) => r.status === 'stale');+ if (failed) return 1;+ return stale ? 1 : 0;+}diff --git a/scripts/publish-mcp-servers.mjs b/scripts/publish-mcp-servers.mjsindex 85c16dac1..5950c168a 100644--- a/scripts/publish-mcp-servers.mjs+++ b/scripts/publish-mcp-servers.mjs@@ -24,12 +24,14 @@// node scripts/publish-mcp-servers.mjs # publish what's missing// node scripts/publish-mcp-servers.mjs --only pumpfun-mcp,three-token-mcp// node scripts/publish-mcp-servers.mjs --npm-only # skip the registry step entirely+// node scripts/publish-mcp-servers.mjs --stale # same check as publish-packages.mjs --staleimport { execFileSync } from 'node:child_process';import { readFileSync, existsSync } from 'node:fs';import { resolve, dirname } from 'node:path';import { fileURLToPath, pathToFileURL } from 'node:url';import { homedir } from 'node:os';+import { runStaleCli } from './lib/stale-packages.mjs';const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');const REGISTRY = 'https://registry.modelcontextprotocol.io';@@ -264,6 +266,13 @@ if (!process.argv[1] || import.meta.url !== pathToFileURL(process.argv[1]).href));}+// --stale reuses the same check publish-packages.mjs runs: it reports across+// every publishable directory (library and MCP alike), so running it here+// too is just a convenience alias, not a second implementation.+if (args.includes('--stale')) {+ process.exit(await runStaleCli(root));+}+let registryToken = null;for (const server of SERVERS) {diff --git a/scripts/publish-packages.mjs b/scripts/publish-packages.mjsindex 81e49dbf8..915202729 100644--- a/scripts/publish-packages.mjs+++ b/scripts/publish-packages.mjs@@ -29,11 +29,13 @@// node scripts/publish-packages.mjs # publish what's missing// node scripts/publish-packages.mjs --only react # one package by key// node scripts/publish-packages.mjs --new # only never-published ones+// node scripts/publish-packages.mjs --stale # report published versions whose source moved on; exits 1 if anyimport { execFileSync } from 'node:child_process';import { readFileSync, readdirSync, existsSync } from 'node:fs';import { resolve, dirname } from 'node:path';import { fileURLToPath } from 'node:url';+import { runStaleCli } from './lib/stale-packages.mjs';const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');@@ -136,9 +138,17 @@ function preflight(dir, pkg) {return problems;}+const args = process.argv.slice(2);++// --stale skips the publish lane entirely: it reports which already-published+// packages have source commits past their publish date, across every+// publishable directory (library and MCP alike), and never calls `npm publish`.+if (args.includes('--stale')) {+ process.exit(await runStaleCli(root));+}+const PACKAGES = discoverPackages();-const args = process.argv.slice(2);const dryRun = args.includes('--dry-run');const newOnly = args.includes('--new');const onlyIdx = args.indexOf('--only');diff --git a/tests/publish-stale-packages.test.js b/tests/publish-stale-packages.test.jsnew file mode 100644index 000000000..f266b38cf--- /dev/null+++ b/tests/publish-stale-packages.test.js@@ -0,0 +1,146 @@+import { describe, it, expect, beforeAll, afterAll } from 'vitest';+import { execFileSync } from 'node:child_process';+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import {+ isIgnorableFile,+ commitsSince,+ classify,+ latestPublishedVersion,+} from '../scripts/lib/stale-packages.mjs';++// Recorded `npm view @three-ws/avatar-agent time --json`, measured 2026-10-08+// (see prompts/finish/_context/integrate-00-CONTEXT.md). Real package, real+// dates: the gap this fixture documents (1.2.3 published 2026-09-11, while+// commit 63be75388 landed in packages/avatar-agent-mcp on 2026-09-22) is the+// bug this whole order exists to catch.+const AVATAR_AGENT_TIME = {+ modified: '2026-09-11T17:14:12.992Z',+ '1.0.0': '2026-05-22T01:15:01.095Z',+ '1.0.1': '2026-05-22T01:24:54.060Z',+ '1.0.2': '2026-05-22T01:36:47.103Z',+ '1.0.3': '2026-05-22T10:09:00.665Z',+ '1.2.0': '2026-06-13T07:52:02.817Z',+ '1.2.1': '2026-07-04T22:24:23.210Z',+ '1.2.2': '2026-07-12T03:51:30.427Z',+ '1.2.3': '2026-09-11T17:14:12.857Z',+};++describe('isIgnorableFile', () => {+ it('ignores README and CHANGELOG at any depth', () => {+ expect(isIgnorableFile('packages/foo/README.md')).toBe(true);+ expect(isIgnorableFile('packages/foo/docs/CHANGELOG.md')).toBe(true);+ });++ it('ignores test files and test directories', () => {+ expect(isIgnorableFile('packages/foo/src/thing.test.js')).toBe(true);+ expect(isIgnorableFile('packages/foo/tests/thing.js')).toBe(true);+ expect(isIgnorableFile('packages/foo/test/thing.mjs')).toBe(true);+ });++ it('counts real source changes', () => {+ expect(isIgnorableFile('packages/foo/src/index.js')).toBe(false);+ expect(isIgnorableFile('packages/foo/package.json')).toBe(false);+ });+});++describe('latestPublishedVersion', () => {+ it('reads the last non-meta key as the latest publish', () => {+ expect(latestPublishedVersion(AVATAR_AGENT_TIME)).toBe('1.2.3');+ });+});++describe('classify', () => {+ const base = { name: '@three-ws/avatar-agent', dir: 'packages/avatar-agent-mcp', localVersion: '1.2.3' };++ it('is stale when the local version is published and source commits exist after it', () => {+ const row = classify({+ ...base,+ npmTime: AVATAR_AGENT_TIME,+ commits: [{ hash: '63be75388', subject: 'feat(mcp-packages): preview-before-spend tools' }],+ });+ expect(row.status).toBe('stale');+ expect(row.commits).toBe(1);+ expect(row.publishedAt).toBe('2026-09-11T17:14:12.857Z');+ expect(row.newestCommitSubject).toMatch(/preview-before-spend/);+ });++ it('is ok when the local version is published and nothing moved after it', () => {+ const row = classify({ ...base, npmTime: AVATAR_AGENT_TIME, commits: [] });+ expect(row.status).toBe('ok');+ });++ it('is unpublished when the local version is not in the registry time map', () => {+ const row = classify({ ...base, localVersion: '9.9.9', npmTime: AVATAR_AGENT_TIME, commits: [] });+ expect(row.status).toBe('unpublished');+ });++ it('is unpublished when npm has never heard of the package (404)', () => {+ const row = classify({ ...base, npmTime: null, commits: [] });+ expect(row.status).toBe('unpublished');+ });++ it('is unreadable when the registry lookup 403s', () => {+ const row = classify({ ...base, npmTime: 'unreadable', commits: [] });+ expect(row.status).toBe('unreadable');+ });+});++describe('commitsSince against a real temporary git repo', () => {+ let repo;+ let publishedAt;++ beforeAll(() => {+ repo = mkdtempSync(join(tmpdir(), 'stale-packages-'));+ const run = (args) => execFileSync('git', args, { cwd: repo, encoding: 'utf8' });+ run(['init', '-q']);+ run(['config', 'user.email', 't@t']);+ run(['config', 'user.name', 't']);++ mkdirSync(join(repo, 'packages', 'widget', 'src'), { recursive: true });+ mkdirSync(join(repo, 'packages', 'widget', 'tests'), { recursive: true });++ // Running git this fast can land every commit in the same wall-clock+ // second, which would make the "exclusive of the publish instant"+ // boundary in commitsSince ambiguous. Space commits 10 minutes apart by+ // explicit author/committer date so the ordering is unambiguous.+ let clock = Date.parse('2026-09-01T00:00:00Z');+ const commit = (file, content, message) => {+ writeFileSync(join(repo, file), content);+ run(['add', file]);+ const at = new Date(clock).toISOString();+ clock += 10 * 60 * 1000;+ execFileSync('git', ['commit', '-q', '-m', message], {+ cwd: repo,+ encoding: 'utf8',+ env: { ...process.env, GIT_AUTHOR_DATE: at, GIT_COMMITTER_DATE: at },+ });+ };++ // Published here: nothing after this point should count unless it is a+ // real source change.+ commit('packages/widget/package.json', '{"name":"widget","version":"1.0.0"}\n', 'publish 1.0.0');+ publishedAt = run(['log', '-1', '--format=%cI']).trim();++ commit('packages/widget/README.md', '# widget\nupdated docs\n', 'docs: refresh README');+ commit('packages/widget/tests/widget.test.js', 'test();\n', 'test: add coverage');+ commit('packages/widget/src/index.js', 'export const widget = 1;\n', 'feat: real behavior change');+ });++ afterAll(() => {+ rmSync(repo, { recursive: true, force: true });+ });++ it('counts only the commit that touched real source', () => {+ const commits = commitsSince('packages/widget', publishedAt, { cwd: repo });+ expect(commits).toHaveLength(1);+ expect(commits[0].subject).toBe('feat: real behavior change');+ });++ it('finds nothing before any commit landed', () => {+ const future = new Date(Date.now() + 86400000).toISOString();+ const commits = commitsSince('packages/widget', future, { cwd: repo });+ expect(commits).toHaveLength(0);+ });+});