Generate a topic-map graph from Markdown frontmatter

# ─────────────────────────────────────────────────────────────
# Prerequisites: Node.js 18+ and a Markdown vault whose topic
# pages carry `topic:` and `relates:` YAML frontmatter.
# ─────────────────────────────────────────────────────────────

# 1. In each TOPIC page, declare the neuron id and its synapses:
#    ---
#    title: "Proxmox Cluster"
#    topic: proxmox-cluster
#    relates: [storage-layout, cluster-networking]
#    tags: [infrastructure]
#    ---

# 2. Dry run — see what WOULD be generated, write nothing
node scripts/build-topic-map.mjs .

# 3. Generate the maps for real (deterministic: stamp the date)
node scripts/build-topic-map.mjs . --write --date 2026-07-15

# 4. Verify the generated glia
ls topics/                    # one MOC page per region
git status                    # region/* tags + brain-region blocks updated

# 5. Drift gate — run before every commit. Non-zero exit = stale.
node scripts/build-topic-map.mjs . --check \
  || { echo "Maps stale — run --write, then stage."; exit 1; }

# 6. Optional: wire the gate into a pre-commit hook
cat > .git/hooks/pre-commit <<'EOF'
#!/bin/bash
node scripts/build-topic-map.mjs . --check || {
  echo "Topic maps are stale. Run: node scripts/build-topic-map.mjs . --write --date $(date +%F)"
  exit 1
}
EOF
chmod +x .git/hooks/pre-commit

# ─────────────────────────────────────────────────────────────
# Reference: a minimal build-topic-map.mjs skeleton.
# Save as scripts/build-topic-map.mjs. Hardened CLI: validates the
# root positional, rejects unknown flags, honors -h/--help.
# ─────────────────────────────────────────────────────────────
cat > scripts/build-topic-map.mjs <<'EOF'
#!/usr/bin/env node
import { readdir, readFile, writeFile } from 'node:fs/promises';
import { join, extname } from 'node:path';

const USAGE = `Usage: build-topic-map.mjs <vault-root> [--write] [--check] [--date YYYY-MM-DD]
  <vault-root>   directory to scan (required)
  --write        write generated MOC/tag/backlink files
  --check        exit non-zero if committed maps differ from generated
  --date DATE    stamp regeneration date (deterministic output)
  -h, --help     show this help`;

const args = process.argv.slice(2);
if (args.includes('-h') || args.includes('--help')) { console.log(USAGE); process.exit(0); }

const flags = new Set(['--write', '--check', '--date']);
const root = args.find(a => !a.startsWith('-') && args[args.indexOf(a) - 1] !== '--date');
if (!root) { console.error('error: <vault-root> is required\n\n' + USAGE); process.exit(2); }
for (const a of args) {
  if (a.startsWith('--') && !flags.has(a)) { console.error(`error: unknown flag ${a}\n\n` + USAGE); process.exit(2); }
}
const write = args.includes('--write');
const check = args.includes('--check');
const date = args[args.indexOf('--date') + 1] || '';

// Walk .md files, parse frontmatter topic:/relates:, build regions.
async function walk(dir, out = []) {
  for (const e of await readdir(dir, { withFileTypes: true })) {
    if (e.name.startsWith('.')) continue;
    const p = join(dir, e.name);
    if (e.isDirectory()) await walk(p, out);
    else if (extname(e.name) === '.md') out.push(p);
  }
  return out;
}

const files = await walk(root);
const neurons = [];
for (const f of files) {
  const txt = await readFile(f, 'utf8');
  const m = txt.match(/^---\n([\s\S]*?)\n---/);
  if (!m) continue;
  const topic = (m[1].match(/^topic:\s*(.+)$/m) || [])[1]?.trim();
  if (!topic) continue;
  const rel = (m[1].match(/^relates:\s*\[(.*)\]/m) || [])[1] || '';
  const tags = (m[1].match(/^tags:\s*\[(.*)\]/m) || [])[1] || '';
  const region = (tags.match(/region\/([\w-]+)/) || [])[1] || 'unsorted';
  neurons.push({ file: f, topic, region, relates: rel.split(',').map(s => s.trim()).filter(Boolean) });
}

// Group into regions → one MOC per region.
const byRegion = {};
for (const n of neurons) (byRegion[n.region] ||= []).push(n);

let stale = false;
for (const [region, members] of Object.entries(byRegion)) {
  const moc = `---\ntitle: "${region}"\ntype: moc\nupdated: ${date}\n---\n# ${region}\n\n`
    + members.map(n => `- [[${n.topic}]]`).join('\n') + '\n';
  const dest = join(root, 'topics', `${region}.md`);
  if (check) {
    const cur = await readFile(dest, 'utf8').catch(() => '');
    if (cur !== moc) { stale = true; console.error(`stale: ${dest}`); }
  } else if (write) {
    await writeFile(dest, moc);
    console.log(`wrote ${dest}`);
  } else {
    console.log(`would write ${dest} (${members.length} neurons)`);
  }
}
if (check && stale) process.exit(1);
EOF