hermes-agent/optional-skills/creative/system-atlas/assets/build.mjs
teknium1 f41b2c615d feat(skills): system-atlas — explorable isometric architecture atlases (port of inkboard/system-atlas, MIT)
Ports the system-atlas agent skill: one data.mjs file renders both an
interactive isometric HTML map (progressive-disclosure chapters, moving
data packets, question tracking by Q-ID) and a generated text twin
(SYSTEM.md) for the repo.

Why: architecture discussions that outgrow a single diagram — the skill
encodes hard-earned rules (max 3 structures per chapter, shapes+labels,
docs-policy ask before committing). Upstream 410 stars since Aug 20,
VoltAgent-listed; complements architecture-diagram (static SVG) with an
explorable, stateful artifact.

- optional-skills/creative/system-atlas/: SKILL.md (89 lines),
  references/ (design language, process lessons), assets/ (build.mjs,
  template.html, data.example.mjs) vendored verbatim; LICENSE.txt (MIT,
  Harshyt Goel)
- Live smoke: node --check both .mjs OK; node build.mjs produced
  atlas.html (41.5 KB) + SYSTEM.md from the example data, zero deps
- docs: own catalog row + generated page + sidebar entry only
2026-09-12 21:28:58 -07:00

104 lines
5.5 KiB
JavaScript

// Builds <outDir>/SYSTEM.md and <outDir>/atlas.html from data.mjs (same folder).
// Usage: bun <atlasDir>/build.mjs — outDir = parent of atlasDir by default, or META.outDir
import { readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { META, DECISIONS, GROUPS, NODES, FLOWS, CH, HOW_HTML } from './data.mjs';
const here = dirname(fileURLToPath(import.meta.url));
const outDir = META.outDir ? join(here, META.outDir) : join(here, '..');
// ---------- shared helpers ----------
const Q = (c) => (typeof c === 'string' ? { q: c } : c);
const md = (s) =>
String(s)
.replace(/<code>(.*?)<\/code>/g, '`$1`')
.replace(/<mark>(.*?)<\/mark>/g, '**$1**')
.replace(/<em>(.*?)<\/em>/g, '_$1_')
.replace(/<b>(.*?)<\/b>/g, '**$1**')
.replace(/<\/p>\s*<p>/g, '\n\n')
.replace(/<[^>]+>/g, '')
.replace(/&nbsp;/g, ' ')
.replace(/&amp;/g, '&')
.replace(/&lt;/g, '<')
.replace(/&gt;/g, '>')
.trim();
const groupTitle = Object.fromEntries(GROUPS.map((g) => [g.id, g.title]));
const cnt = { open: 0, res: 0 };
NODES.forEach((n) => (n.cond || []).map(Q).forEach((c) => (c.r || c.to ? cnt.res++ : cnt.open++)));
// ---------- SYSTEM.md ----------
function buildSystemMd() {
const out = [];
out.push(`# ${META.title} — System Definition`, '');
out.push(META.intro, '');
out.push(`_Question status: **${cnt.open} open · ${cnt.res} resolved**._`, '');
out.push('## One paragraph', '', META.onePara, '');
out.push('## Decisions locked', '', '| Axis | Decision | ADR |', '|---|---|---|');
DECISIONS.forEach((d) => out.push(`| ${d.axis} | ${d.decision} | ${d.adr} |`));
out.push('');
out.push('## Cost model', '');
META.costModel.forEach((l) => out.push(l));
if (META.deepDive) out.push('## Deep dives', '', META.deepDive, '');
out.push('## Reading order (the atlas chapters)', '');
CH.forEach((c, i) => out.push(`${i + 1}. **${c.title}** — ${md(c.lede)}${c.reveal.length ? ` _(adds ${c.reveal.join(', ')})_` : ''}`));
out.push('');
out.push('## Structures', '');
const index = [];
for (const g of GROUPS) {
out.push(`### ${g.title}${g.id === 'off' ? ' (designed for, not built)' : ''}`, '');
for (const n of NODES.filter((n) => n.group === g.id)) {
out.push(`#### ${n.code} · ${n.name}${n.ghost ? ' _(not switched on)_' : ''}`, '');
out.push(`**In one line.** ${md(n.one)}`, '');
out.push(`**What it does.** ${md(n.what)}`, '');
out.push(`**How it's built.** ${md(n.how)}`, '');
if (n.steps) {
out.push('**Steps in execution.**', '');
n.steps.forEach((s, i) => out.push(`${i + 1}. **${s[0]}** — ${s[1]}`));
out.push('');
}
const cs = (n.cond || []).map(Q);
if (cs.length) {
out.push('**Questions.**', '');
cs.forEach((c, i) => {
const id = `Q-${n.code}${i + 1}`;
out.push(c.r ? `- ~~**${id}** ${md(c.q)}~~ ✓ ${md(c.r)}` : c.to ? `- **${id}** ${md(c.q)} → _${md(c.to)}_` : `- **${id}** ${md(c.q)}`);
index.push([id, n.code, c]);
});
out.push('');
}
}
}
out.push('## Flows (representative packets)', '', 'Payload shapes are what the design implies, not measured traffic.', '');
for (const f of FLOWS) {
out.push(`### ${f.name}`, '', '| # | From → To | Packet | Representative payload |', '|---|---|---|---|');
f.hops.forEach((h, i) => out.push(`| ${i + 1} | ${h[0]} → ${h[1]} | ${h[2]} | \`${JSON.stringify(h[3]).replace(/\|/g, '\\|')}\` |`));
out.push('');
}
out.push('## Questions — index', '', 'Reference by ID. ✓ resolved (with date) · otherwise open.', '');
index.forEach(([id, code, c]) => out.push(c.r ? `- ~~**${id}**~~ (${code}) ✓ ${md(c.r)}` : `- **${id}** (${code}) ${md(c.q)}`));
out.push('');
if (META.platformGives || META.weOwn) out.push('## What the platform gives vs what we own', '', `**Platform gives:** ${META.platformGives||''}`, '', `**We own:** ${META.weOwn||''}`, '');
if (META.filesystem) out.push('## Planned filesystem', '', '```', META.filesystem.trimEnd(), '```', '');
out.push('## How this file is maintained', '', `Generated from \`${META.sourcePath||'atlas/data.mjs'}\` by \`${META.buildCmd||'bun atlas/build.mjs'}\`, which also builds the interactive atlas (\`atlas.html\`${META.artifactUrl?`, published at ${META.artifactUrl}`:''}). Edit the data file, rebuild, republish — never edit this file by hand.`, '');
return out.join('\n');
}
// ---------- atlas.html ----------
function buildAtlasHtml() {
const tpl = readFileSync(join(here, 'template.html'), 'utf8');
const decisionsHtml = DECISIONS.map((d) => `<li><b>${d.axis}.</b> ${md(d.decision).replace(/\*\*(.*?)\*\*/g, '<b>$1</b>').replace(/`(.*?)`/g, '<code>$1</code>').replace(/\[(.*?)\]\((.*?)\)/g, '$1')}</li>`).join('');
const data = [
`const GROUPS = ${JSON.stringify(GROUPS)};`,
`const NODES = ${JSON.stringify(NODES)};`,
`const FLOWS = ${JSON.stringify(FLOWS)};`,
`const CH = ${JSON.stringify(CH)};`,
`const HOW_HTML = ${JSON.stringify(HOW_HTML)};`,
`const DECISIONS_HTML = ${JSON.stringify(decisionsHtml)};`,
].join('\n');
return tpl.replace('__TITLE__', META.title + ' Atlas').replace('/*__DATA__*/', data + `\nconst STATS = ${JSON.stringify(META.stats||[])};\nconst TITLE = ${JSON.stringify(META.title||'System')};`);
}
writeFileSync(join(outDir, 'SYSTEM.md'), buildSystemMd());
writeFileSync(join(outDir, 'atlas.html'), buildAtlasHtml());
console.log(`built SYSTEM.md + atlas.html · ${cnt.open} open · ${cnt.res} resolved · ${NODES.length} structures · ${DECISIONS.length} decisions`);