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
// announce-kit.mjs - the announcement factory: a planned slot in, a finished
// pack, media recipe, and queue item out.
//
// The backlog is 300-plus shipped surfaces that have never been posted about.
// Writing each announcement by hand takes an afternoon, which is why fewer than
// 50 of 430 surfaces were ever announced. This does the parts that are
// mechanical and refuses to fake the parts that are not:
//
// 1. brief every checkable fact about the surface, harvested from the live
// page, the changelog, its docs, and its README
// (api/_lib/announce/brief.js)
// 2. media a capture recipe for the frame, added to data/announce-media.json
// so `npm run announce:media` can shoot it from the live route
// 3. draft a post written from that brief by the model chain, then held
// against every gate the queue enforces (voice, editorial, claims,
// evidence, repetition) and rewritten until it passes
// (api/_lib/announce/draft.js)
// 4. pack docs/announcements/<id>.md and <id>.post.txt, the format
// `npm run check:announce` gates and a human approves from
// 5. queue the item in data/x-content/queue.json, at status `draft`
//
// What it never does: approve anything, capture a frame it was not asked to,
// or post. Publishing stays where it was, behind a passing editorial review and
// the owner's approval.
//
// npm run announce:kit -- --count 3 # the next three planned slots
// npm run announce:kit -- --batch 1 # a whole week's batch
// npm run announce:kit -- --id labor-market # one surface by id
// npm run announce:kit -- --brief-only # briefs and recipes, no model
// npm run announce:kit -- --capture # also shoot the frames
// npm run announce:kit -- --include-gated # include owner-gated media
// npm run announce:kit -- --dry-run # write nothing, print the plan
//
// A draft the model cannot be trusted to write (or that you want to write
// yourself) can be dropped at data/announce-plan/drafts/<id>.json in the same
// shape the model returns; this script prefers it and runs it through the same
// checks.
import { spawnSync } from 'node:child_process';
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { briefPath, buildBrief } from '../api/_lib/announce/brief.js';
import { draftFindings, draftPost, itemFor } from '../api/_lib/announce/draft.js';
import { renderPack, renderPostFile } from '../api/_lib/announce/kit.js';
import { MissingLedgerError, ledgerEntryFor, loadLedger, loadOrBuildPlan } from '../api/_lib/announce/ledger.js';
import { patternsFor, slugFor } from '../api/_lib/announce/plan.js';
import { createPageReader } from '../api/_lib/x-content/verify.js';
import { validateItem } from '../api/_lib/x-content/queue.js';
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
function loadEnvFile(path) {
if (!existsSync(path)) return;
for (const line of readFileSync(path, 'utf8').split('\n')) {
const match = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/i);
if (match && !process.env[match[1]]) process.env[match[1]] = match[2].replace(/^["']|["']$/g, '');
}
}
loadEnvFile(join(root, '.env.local'));
loadEnvFile(join(root, '.env'));
const argv = process.argv.slice(2);
const flag = (name) => argv.includes(`--${name}`);
const option = (name, fallback = null) => {
const index = argv.indexOf(`--${name}`);
return index >= 0 && argv[index + 1] && !argv[index + 1].startsWith('--') ? argv[index + 1] : fallback;
};
const dryRun = flag('dry-run');
const briefOnly = flag('brief-only');
const includeGated = flag('include-gated');
const redraft = flag('redraft');
const live = !flag('no-live');
const QUEUE_FILE = join(root, 'data/x-content/queue.json');
const MEDIA_SPEC = join(root, 'data/announce-media.json');
const PACK_DIR = join(root, 'docs/announcements');
const DRAFT_DIR = join(root, 'data/announce-plan/drafts');
let ledger;
try {
ledger = loadLedger(root);
} catch (error) {
if (error instanceof MissingLedgerError) {
console.error(error.message);
process.exit(1);
}
throw error;
}
// Without --include-gated the factory can only pack ungated surfaces, so it
// plans against that same reality: gated surfaces are held out of the calendar
// rather than dated into slots nobody can fill, which is what kept the packable
// backlog weeks behind the slots it could have had.
const plan = loadOrBuildPlan(root, { start: option('start'), refresh: flag('refresh'), holdGated: !includeGated });
const wanted = (() => {
const id = option('id');
if (id) {
const slot = plan.slots.find((row) => row.id === id);
if (slot) return [slot];
// A packed surface leaves the plan (the plan is what is left to do), so
// re-running one after an edit rebuilds its slot from the queue item it
// already has. Its date, lane and shape are whatever was committed.
const queued = JSON.parse(readFileSync(QUEUE_FILE, 'utf8')).items.find((item) => item.id === id);
const entry = (ledger.entries || []).find((row) => slugFor(row.key) === id);
if (!queued || !entry) {
console.error(`no planned slot or queue item with id ${id}. See: npm run announce:plan`);
process.exit(1);
}
const offered = patternsFor(entry);
return [{
position: 0,
id,
key: entry.key,
kind: entry.kind,
section: entry.section,
url: entry.url || null,
lane: queued.lane,
// The shape it was packed in, unless the surface can no longer
// carry it: a route the capture photographed twice without
// anything changing stops being offered a clip, and re-running the
// factory over that pack must not promise a loop again.
pattern: offered.includes(queued.pattern) ? queued.pattern : offered[0],
tier: queued.tier,
notBefore: queued.notBefore,
windowMinutes: queued.windowMinutes || plan.slots[0]?.windowMinutes || 90,
batch: 0,
score: entry.score,
partner: entry.partner || null,
shot: `${id}-hero`,
motion: queued.pattern === 'clip',
mediaGate: null,
pack: `docs/announcements/${id}.md`,
}];
}
const batch = option('batch');
const pool = batch ? plan.slots.filter((row) => row.batch === Number(batch)) : plan.slots;
const eligible = includeGated ? pool : pool.filter((row) => !row.mediaGate);
return batch ? eligible : eligible.slice(0, Number(option('count', 3)));
})();
if (!wanted.length) {
console.error('nothing to do: every planned slot in range is either gated (use --include-gated) or already packed.');
process.exit(1);
}
const voice = existsSync(join(root, 'docs/announce-voice.md')) ? readFileSync(join(root, 'docs/announce-voice.md'), 'utf8') : null;
const queue = JSON.parse(readFileSync(QUEUE_FILE, 'utf8'));
// Every other live head in the queue, so a new draft is held against them for
// repetition. An item's own previous head is excluded: re-running the factory
// over a pack that already exists must not reject it for matching itself.
const queuedHeads = new Map(
(queue.items || []).filter((item) => item.status !== 'posted').map((item) => [item.id, item.posts?.[0]?.text || '']),
);
const headsExcept = (id) => [...queuedHeads.entries()].filter(([key, text]) => key !== id && text).map(([, text]) => text);
function upsertShot(slot, alt, entry) {
const spec = JSON.parse(readFileSync(MEDIA_SPEC, 'utf8'));
// A surface with a route is photographed. A package, worker, or service has
// no route, so its frame is a title card typeset from its own README and
// package.json by the same capture engine.
const shot = slot.url
? {
id: slot.shot,
surface: slot.key,
url: slot.url,
alt,
caption: `Captured from the live ${slot.url} route for the ${slot.id} announcement.`,
...(slot.motion ? { settle: 9000, motion: { seconds: 5, fps: 12 } } : {}),
}
: {
id: slot.shot,
surface: slot.key,
viewport: 'wide',
alt,
caption: `Title card for ${slot.key}, typeset from its README and package.json.`,
card: { dir: entry.dir || null, title: entry.title || slot.key, description: entry.description || '' },
};
const index = (spec.shots || []).findIndex((row) => row.id === slot.shot);
// Merge, so a hand-tuned viewport or settle survives a re-run, except for
// the motion recipe: a surface whose pattern is no longer a clip must stop
// being filmed, and a spread alone would keep filming it forever.
if (index >= 0) {
const previous = { ...spec.shots[index] };
if (!slot.motion) {
delete previous.motion;
delete previous.settle;
}
spec.shots[index] = { ...previous, ...shot };
}
else spec.shots.push(shot);
if (!dryRun) writeFileSync(MEDIA_SPEC, `${JSON.stringify(spec, null, '\t')}\n`);
// The manifest records the alt text that was captured with the frame, and a
// draft can change it after the capture. Keep the two in step rather than
// leaving the docs renderer quoting an alt nobody reviewed.
const manifestPath = join(root, 'public/announce/media-manifest.json');
if (!dryRun && existsSync(manifestPath)) {
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
const shots = Array.isArray(manifest.shots) ? manifest.shots : Object.values(manifest.shots || {});
const written = shots.find((row) => row.id === slot.shot);
if (written && written.alt !== alt) {
written.alt = alt;
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, '\t')}\n`);
}
}
return shot;
}
function upsertItem(item) {
const current = JSON.parse(readFileSync(QUEUE_FILE, 'utf8'));
const index = (current.items || []).findIndex((row) => row.id === item.id);
if (index >= 0) current.items[index] = item;
else current.items.push(item);
current.items.sort((left, right) => String(left.notBefore).localeCompare(String(right.notBefore)));
if (!dryRun) writeFileSync(QUEUE_FILE, `${JSON.stringify(current, null, '\t')}\n`);
}
function capture(shotId) {
const result = spawnSync(
'node',
['scripts/capture-doc-media.mjs', '--spec', 'data/announce-media.json', '--out', 'public/announce/img', '--manifest', 'public/announce/media-manifest.json', '--only', shotId],
{ cwd: root, stdio: 'inherit' },
);
return result.status === 0;
}
const pages = live ? createPageReader() : null;
const results = [];
try {
for (const slot of wanted) {
const entry = ledgerEntryFor(ledger, slot.key);
const rank = (ledger.entries || []).filter((row) => row.coverage === 'no').findIndex((row) => row.key === slot.key) + 1;
process.stderr.write(`\n${slot.id}: brief`);
const brief = await buildBrief(slot, { root, ledgerEntry: entry, pages });
if (!dryRun) {
mkdirSync(dirname(join(root, briefPath(slot.id))), { recursive: true });
writeFileSync(join(root, briefPath(slot.id)), `${JSON.stringify(brief, null, '\t')}\n`);
}
process.stderr.write(` (${brief.live.facts.length} live facts, ${brief.evidenceCandidates.length} evidence candidates, ${brief.changelog.length} changelog entries)`);
if (briefOnly) {
results.push({ id: slot.id, state: 'brief', detail: `${brief.evidenceCandidates.length} evidence candidates` });
continue;
}
const handWritten = join(DRAFT_DIR, `${slot.id}.json`);
let draft = null;
let model = 'hand-written draft';
let findings = [];
if (!redraft && existsSync(handWritten)) {
draft = JSON.parse(readFileSync(handWritten, 'utf8'));
findings = draftFindings(brief, draft, { root, otherHeads: headsExcept(slot.id) });
process.stderr.write(`\n${slot.id}: using ${handWritten.replace(`${root}/`, '')}`);
} else {
process.stderr.write(`\n${slot.id}: drafting`);
try {
const attempt = await draftPost(brief, { root, voice, otherHeads: headsExcept(slot.id) });
draft = attempt.draft;
model = attempt.model;
findings = attempt.ok ? [] : attempt.findings;
process.stderr.write(` (${attempt.attempts.length} attempt(s) on ${attempt.model})`);
} catch (error) {
// The chain's first line is only "no model was reachable:"; the reason
// each rung failed is on the lines after it, so keep them.
const reason = error.message.replace(/\s*\n\s*/g, ' | ');
results.push({ id: slot.id, state: 'no model', detail: reason });
process.stderr.write(` failed: ${reason}`);
continue;
}
}
if (findings.length) {
results.push({ id: slot.id, state: 'draft rejected', detail: findings[0] });
if (!dryRun) {
mkdirSync(DRAFT_DIR, { recursive: true });
writeFileSync(join(DRAFT_DIR, `${slot.id}.rejected.json`), `${JSON.stringify({ draft, findings }, null, '\t')}\n`);
}
continue;
}
upsertShot(slot, String(draft.alt || '').trim(), entry);
if (flag('capture') && !dryRun) {
process.stderr.write(`\n${slot.id}: capturing ${slot.shot}`);
if (!capture(slot.shot)) process.stderr.write(' (capture failed)');
}
const mediaPath = `public/announce/img/${slot.shot}.webp`;
// `review` means finished and waiting for the editorial bar; `draft`
// means something is still missing (almost always the frame, which is
// captured separately). The queue validator decides which, not this
// script's optimism.
const candidate = itemFor(brief, draft, { mediaPath });
const pack = renderPack({ brief, draft, slot, ledgerEntry: entry, rank: rank || null, total: (ledger.totals?.never ?? null), model, root });
// The pack is written before the item is judged, because the item points
// at the pack's `.post.txt` and the validator checks that file exists.
// Judging first failed every brand-new pack on a file this same run was
// about to write, which left the whole batch at `draft` until someone
// re-ran it.
if (!dryRun) {
mkdirSync(PACK_DIR, { recursive: true });
writeFileSync(join(PACK_DIR, `${slot.id}.md`), pack);
writeFileSync(join(PACK_DIR, `${slot.id}.post.txt`), renderPostFile(draft));
}
const problems = validateItem(candidate, root);
const item = { ...candidate, status: problems.length ? 'draft' : 'review' };
if (!dryRun) upsertItem(item);
queuedHeads.set(slot.id, item.posts[0].text);
results.push({
id: slot.id,
state: problems.length ? 'packed, item incomplete' : 'packed, awaiting review',
detail: problems.length ? problems[0] : `${slot.notBefore.slice(0, 16).replace('T', ' ')} UTC, T${item.tier} ${brief.lane}/${brief.pattern}`,
});
}
} finally {
if (pages) await pages.close();
}
console.log('\n');
console.log(`${'pack'.padEnd(28)} ${'state'.padEnd(24)} detail`);
for (const row of results) console.log(`${row.id.padEnd(28)} ${row.state.padEnd(24)} ${row.detail}`);
const packed = results.filter((row) => row.state.startsWith('packed'));
if (packed.length) {
console.log(`\nNext:\n npm run announce:media -- --only ${packed.map((row) => `${row.id}-hero`).join(',')}`);
console.log(' npm run check:announce');
console.log(' npm run x:content -- review --status review');
console.log(' npm run x:content -- approve --status review # owner: releases the batch to its slots');
}
if (dryRun) console.log('\n(dry run: nothing was written)');