@raishin/vanguard-frontier-agentic 3.15.0 → 3.17.0

package/scripts/generate-mods.mjs

@@ -0,0 +1,784 @@
+#!/usr/bin/env node
+/**
+ * Generator: the files marked "G" under mods/<id>/ plus catalog/mods.json.
+ *
+ * Source of truth is mods/<id>/mod.toml (plus patterns.json for the pattern mods) and the
+ * two shared files scripts/mods/common.mjs and scripts/mods/runtime.mjs. Everything else
+ * this script writes is derived and must never be hand-edited. Hand-written files in a mod
+ * (README.md, bin/, hooks/register.ts, lib/core.mjs, ...) are never touched.
+ *
+ * mod.toml is read with a strict TOML-subset parser (comments, bare-key tables, basic
+ * strings, integers, booleans, arrays of strings). Anything else is an error, so a manifest
+ * can never mean one thing to this script and another to Python's tomllib.
+ *
+ * Deterministic by construction: no clock, no env, no network, no shell, nothing outside
+ * the repo. Output is sorted; JSON is 2-space with a trailing newline.
+ *
+ * Usage:
+ *   node scripts/generate-mods.mjs                    # write generated files, delete stale ones
+ *   node scripts/generate-mods.mjs --check            # verify in sync (CI); writes nothing
+ *   node scripts/generate-mods.mjs --print-manifests  # parsed mod.toml files as JSON
+ *
+ * Exports: parseToml, validateManifest, loadMods, renderMod, renderAll.
+ *   loadMods(root) -> { mods, ctx, errors }   (the only function that reads the disk)
+ *   renderAll(mods, ctx) -> Map<repo-relative path, content>, sorted by path
+ */
+import {
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+const HARNESSES = ['claude-code', 'kiro', 'codex']
+const HARNESS_NAMES = { 'claude-code': 'Claude Code', kiro: 'Kiro', codex: 'Codex' }
+const EVENTS = ['PreToolUse', 'PostToolUse', 'SessionStart'] // canonical order
+const EV_KEBAB = { PreToolUse: 'pre-tool-use', PostToolUse: 'post-tool-use', SessionStart: 'session-start' }
+const SURFACES = ['native', 'classic']
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const VERSION_RE = /^\d+\.\d+\.\d+$/
+const CTRL_RE = /[\u0000-\u001f\u007f]/
+const LIVE_AGENT_RE = /-live-.*-guard-agent$/
+const GEN_HEADER = '// Generated by scripts/generate-mods.mjs'
+
+// Paths the generator owns inside a mod. Everything else in a mod is hand-written.
+const OWNED_DIRS = ['.claude-plugin', 'claude-code', 'kiro', 'codex'] // every file inside is generated
+const OWNED_FILES = {
+  lib: ['common.mjs', 'runtime.mjs', 'patterns.mjs', 'live-agents.mjs'],
+  hooks: ['hooks.json'],
+}
+
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0)
+const json = (v) => JSON.stringify(v, null, 2) + '\n'
+const isTable = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+function aggregate(errors) {
+  const e = new Error(errors.join('\n'))
+  e.errors = errors
+  return e
+}
+
+// ---------------------------------------------------------------------------------------
+// TOML subset parser
+// ---------------------------------------------------------------------------------------
+
+// table object -> Map(key -> line); key '' is the table's own header line. Lets schema
+// errors point at file:line without changing the plain-object shape parseToml returns.
+const LINES = new WeakMap()
+const ESCAPES = { '"': '"', '\\': '\\', n: '\n', t: '\t', r: '\r' }
+
+export function parseToml(text, fileLabel = 'mod.toml') {
+  const n = text.length
+  const root = {}
+  LINES.set(root, new Map())
+  const defined = new Set() // explicitly declared [tables], by dotted path
+  let cur = root
+  let pos = 0
+  let line = 1
+
+  const fail = (msg = 'unsupported TOML', at = line) => {
+    throw new Error(`${fileLabel}:${at}: ${msg}`)
+  }
+  const isWs = (c) => c === ' ' || c === '\t'
+  const atNewline = () => text[pos] === '\n' || (text[pos] === '\r' && text[pos + 1] === '\n')
+  const eatNewline = () => {
+    pos += text[pos] === '\r' ? 2 : 1
+    line++
+  }
+  const skipWs = () => {
+    while (pos < n && isWs(text[pos])) pos++
+  }
+  const skipComment = () => {
+    if (text[pos] === '#') while (pos < n && !atNewline()) pos++
+  }
+  const skipWsNl = () => {
+    for (;;) {
+      skipWs()
+      if (pos < n && atNewline()) eatNewline()
+      else if (text[pos] === '#') skipComment()
+      else return
+    }
+  }
+  const endOfLine = () => {
+    skipWs()
+    skipComment()
+    if (pos >= n) return
+    if (atNewline()) eatNewline()
+    else fail()
+  }
+
+  const BARE = /[A-Za-z0-9_-]+/y
+  const bareKey = () => {
+    BARE.lastIndex = pos
+    const m = BARE.exec(text)
+    if (!m) return ''
+    pos += m[0].length
+    if (FORBIDDEN_KEYS.has(m[0])) fail(`forbidden key ${m[0]}`)
+    return m[0]
+  }
+
+  const readString = () => {
+    if (text.startsWith('"""', pos)) fail() // multiline basic string
+    pos++
+    let out = ''
+    for (;;) {
+      if (pos >= n) fail()
+      const c = text[pos]
+      if (c === '"') {
+        pos++
+        return out
+      }
+      if (c === '\\') {
+        const e = text[pos + 1]
+        if (e === 'u') {
+          const hex = text.slice(pos + 2, pos + 6)
+          if (!/^[0-9A-Fa-f]{4}$/.test(hex)) fail()
+          const cp = parseInt(hex, 16)
+          if (cp >= 0xd800 && cp <= 0xdfff) fail() // lone surrogate is not a scalar value
+          out += String.fromCharCode(cp)
+          pos += 6
+        } else if (e !== undefined && Object.hasOwn(ESCAPES, e)) {
+          out += ESCAPES[e]
+          pos += 2
+        } else fail()
+        continue
+      }
+      const code = c.charCodeAt(0)
+      if (code === 0x0a || code === 0x0d || (code < 0x20 && c !== '\t') || code === 0x7f) fail()
+      out += c
+      pos++
+    }
+  }
+
+  const readArray = () => {
+    const startLine = line
+    pos++
+    const items = []
+    for (;;) {
+      skipWsNl()
+      if (pos >= n) fail('unsupported TOML', startLine)
+      if (text[pos] === ']') {
+        pos++
+        return items
+      }
+      if (text[pos] !== '"') fail() // only strings: no nesting, no mixed arrays, no inline tables
+      items.push(readString())
+      skipWsNl()
+      if (text[pos] === ',') pos++
+      else if (text[pos] === ']') {
+        pos++
+        return items
+      } else fail()
+    }
+  }
+
+  const SCALAR = /(?:-?(?:0|[1-9][0-9]*)|true|false)(?=[ \t\r\n#,\]]|$)/y
+  const readValue = () => {
+    const c = text[pos]
+    if (c === '"') return readString()
+    if (c === '[') return readArray()
+    SCALAR.lastIndex = pos
+    const m = SCALAR.exec(text)
+    if (!m) fail() // literal strings, floats, dates, inline tables, ...
+    pos += m[0].length
+    if (m[0] === 'true') return true
+    if (m[0] === 'false') return false
+    const v = Number(m[0])
+    if (!Number.isSafeInteger(v)) fail()
+    return v || 0 // folds -0 into 0
+  }
+
+  while (pos < n) {
+    skipWs()
+    if (pos >= n) break
+    if (atNewline()) {
+      eatNewline()
+      continue
+    }
+    if (text[pos] === '#') {
+      skipComment()
+      continue
+    }
+    if (text[pos] === '[') {
+      if (text[pos + 1] === '[') fail() // array of tables
+      const headerLine = line
+      pos++
+      const segs = []
+      for (;;) {
+        skipWs()
+        const seg = bareKey()
+        if (!seg) fail()
+        segs.push(seg)
+        skipWs()
+        if (text[pos] === '.') pos++
+        else if (text[pos] === ']') {
+          pos++
+          break
+        } else fail()
+      }
+      endOfLine()
+      cur = root
+      for (const seg of segs) {
+        if (!Object.hasOwn(cur, seg)) {
+          const t = {}
+          LINES.set(t, new Map())
+          cur[seg] = t
+          LINES.get(cur).set(seg, headerLine)
+        } else if (!isTable(cur[seg])) fail(`duplicate key ${seg}`, headerLine)
+        cur = cur[seg]
+      }
+      const dotted = segs.join('.')
+      if (defined.has(dotted)) fail(`duplicate table [${dotted}]`, headerLine)
+      defined.add(dotted)
+      LINES.get(cur).set('', headerLine)
+      continue
+    }
+    const keyLine = line
+    const key = bareKey() // quoted keys fall through to fail() below
+    if (!key) fail()
+    skipWs()
+    if (text[pos] !== '=') fail() // also rejects dotted keys
+    pos++
+    skipWs()
+    const value = readValue()
+    endOfLine()
+    if (Object.hasOwn(cur, key)) fail(`duplicate key ${key}`, keyLine)
+    cur[key] = value
+    LINES.get(cur).set(key, keyLine)
+  }
+  return root
+}
+
+// ---------------------------------------------------------------------------------------
+// mod.toml schema
+// ---------------------------------------------------------------------------------------
+
+/** Returns an array of `<label>[:<line>]: <message>` strings; empty when the manifest is valid. */
+export function validateManifest(m, dirName, label) {
+  const errs = []
+  const err = (table, key, msg) => {
+    const l = LINES.get(table)?.get(key)
+    errs.push(`${label}${l ? `:${l}` : ''}: ${msg}`)
+  }
+  const q = (name, k) => (name ? `${name}.${k}` : k)
+  const keys = (t, name, required, optional = []) => {
+    for (const k of required) if (!Object.hasOwn(t, k)) err(t, '', `missing key ${q(name, k)}`)
+    for (const k of Object.keys(t)) {
+      if (!required.includes(k) && !optional.includes(k)) err(t, k, `unknown key ${q(name, k)}`)
+    }
+  }
+  const sub = (t, k, name) => {
+    if (!Object.hasOwn(t, k)) {
+      err(t, '', `missing table [${q(name, k)}]`)
+      return null
+    }
+    if (!isTable(t[k])) {
+      err(t, k, `${q(name, k)} must be a table`)
+      return null
+    }
+    return t[k]
+  }
+  const text = (t, k, name) => {
+    const v = t[k]
+    if (v === undefined) return // keys() already reported it missing
+    if (typeof v !== 'string' || !v.trim() || CTRL_RE.test(v)) {
+      err(t, k, `${q(name, k)} must be a non-empty single-line string`)
+    }
+  }
+  const strArray = (t, k, name, { oneOf, unique = false, nonEmpty = false } = {}) => {
+    const v = t[k]
+    if (v === undefined) return
+    if (!Array.isArray(v) || v.some((s) => typeof s !== 'string' || !s || CTRL_RE.test(s))) {
+      err(t, k, `${q(name, k)} must be an array of non-empty single-line strings`)
+      return
+    }
+    if (nonEmpty && v.length === 0) err(t, k, `${q(name, k)} must not be empty`)
+    if (unique && new Set(v).size !== v.length) err(t, k, `${q(name, k)} must not repeat a value`)
+    if (oneOf) for (const s of v) if (!oneOf.includes(s)) err(t, k, `${q(name, k)}: unknown value "${s}"`)
+  }
+
+  if (!isTable(m)) return [`${label}: manifest must be a table`]
+  keys(m, '', ['mod', 'footprint', 'harnesses'])
+
+  const mod = Object.hasOwn(m, 'mod') ? sub(m, 'mod', '') : null
+  if (mod) {
+    keys(mod, 'mod', ['id', 'name', 'description', 'version', 'reach_level', 'events'])
+    if (typeof mod.id === 'string') {
+      if (!ID_RE.test(mod.id)) err(mod, 'id', 'mod.id must be kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$)')
+      else if (mod.id !== dirName) err(mod, 'id', `mod.id "${mod.id}" must equal the directory name "${dirName}"`)
+    } else if (mod.id !== undefined) err(mod, 'id', 'mod.id must be a string')
+    text(mod, 'name', 'mod')
+    text(mod, 'description', 'mod')
+    if (mod.version !== undefined && !(typeof mod.version === 'string' && VERSION_RE.test(mod.version))) {
+      err(mod, 'version', 'mod.version must match ^\\d+\\.\\d+\\.\\d+$')
+    }
+    if (mod.reach_level !== undefined && !(Number.isInteger(mod.reach_level) && mod.reach_level >= 0 && mod.reach_level <= 3)) {
+      err(mod, 'reach_level', 'mod.reach_level must be an integer 0..3')
+    }
+    strArray(mod, 'events', 'mod', { oneOf: EVENTS, unique: true, nonEmpty: true })
+  }
+
+  const fp = Object.hasOwn(m, 'footprint') ? sub(m, 'footprint', '') : null
+  if (fp) {
+    const names = ['env_reads', 'file_writes', 'spawns', 'egress_hosts']
+    keys(fp, 'footprint', names)
+    for (const k of names) strArray(fp, k, 'footprint')
+  }
+
+  const hs = Object.hasOwn(m, 'harnesses') ? sub(m, 'harnesses', '') : null
+  if (hs) {
+    keys(hs, 'harnesses', HARNESSES)
+    for (const h of HARNESSES) {
+      if (!Object.hasOwn(hs, h)) continue
+      const t = sub(hs, h, 'harnesses')
+      if (!t) continue
+      const name = `harnesses.${h}`
+      if (typeof t.supported !== 'boolean') {
+        err(t, Object.hasOwn(t, 'supported') ? 'supported' : '', `${name}.supported must be a boolean`)
+        continue
+      }
+      if (!t.supported) {
+        keys(t, name, ['supported', 'reason'])
+        text(t, 'reason', name)
+        continue
+      }
+      const claude = h === 'claude-code'
+      keys(t, name, claude ? ['supported', 'events', 'surfaces'] : ['supported', 'events'], claude ? ['unsupported', 'degraded'] : ['requires', 'unsupported', 'degraded'])
+      strArray(t, 'events', name, { oneOf: EVENTS, unique: true })
+      if (claude) strArray(t, 'surfaces', name, { oneOf: SURFACES, unique: true })
+      else strArray(t, 'requires', name)
+      const allowed = claude ? [...EVENTS, ...SURFACES] : EVENTS
+      for (const k of ['unsupported', 'degraded']) {
+        if (!Object.hasOwn(t, k)) continue
+        const st = sub(t, k, name)
+        if (!st) continue
+        for (const key of Object.keys(st)) {
+          if (!allowed.includes(key)) err(st, key, `${name}.${k}.${key}: key must be one of ${allowed.join(', ')}`)
+          else text(st, key, `${name}.${k}`)
+        }
+      }
+    }
+  }
+  return errs
+}
+
+// ---------------------------------------------------------------------------------------
+// Loading (the only disk reads)
+// ---------------------------------------------------------------------------------------
+
+// Check components without following symlinks, before any read, mkdir or removal.
+function safePath(root, rel) {
+  const base = path.resolve(root)
+  const abs = path.resolve(base, rel)
+  const relative = path.relative(base, abs)
+  if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+    throw new Error(`${rel}: escapes the repo`)
+  }
+  let current = base
+  for (const part of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, part)
+    try {
+      if (lstatSync(current).isSymbolicLink()) throw new Error(`${rel}: symlink in repo path`)
+    } catch (e) {
+      if (e.code === 'ENOENT') break
+      throw e
+    }
+  }
+  return abs
+}
+
+function readText(root, rel) {
+  const buf = readFileSync(safePath(root, rel))
+  const s = buf.toString('utf8')
+  if (!Buffer.from(s, 'utf8').equals(buf)) throw new Error('not valid UTF-8, so it cannot be copied byte for byte')
+  return s
+}
+
+function modDirs(root, errors) {
+  try {
+    return readdirSync(safePath(root, 'mods'), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+      .map((e) => e.name)
+      .sort(cmp)
+  } catch (e) {
+    errors.push(e.code === 'ENOENT' ? 'mods/: directory is missing' : e.message)
+    return []
+  }
+}
+
+/** Parse (no schema check) every mods/<dir>/mod.toml. */
+function readManifests(root) {
+  const errors = []
+  const entries = []
+  for (const dir of modDirs(root, errors)) {
+    const label = `mods/${dir}/mod.toml`
+    try {
+      entries.push({ dir, label, manifest: parseToml(readText(root, label), label) })
+    } catch (e) {
+      errors.push(e.code === 'ENOENT' ? `${label}: missing` : e.message.startsWith(label) ? e.message : `${label}: ${e.message}`)
+    }
+  }
+  return { entries, errors }
+}
+
+const usesLiveAgents = (patterns) => Array.isArray(patterns) && patterns.some((p) => Array.isArray(p?.agents))
+
+/**
+ * Read and validate every mod. Mods with errors are left out of `mods`; every error is
+ * collected rather than thrown. `ctx` carries the shared inputs renderMod needs:
+ * { common, runtime, agentIds } (agentIds is null unless a mod needs the live-agent lists).
+ */
+export function loadMods(root = ROOT) {
+  const { entries, errors } = readManifests(root)
+  const mods = []
+  for (const { dir, label, manifest } of entries) {
+    let ok = true
+    const report = (msgs) => {
+      errors.push(...msgs)
+      if (msgs.length) ok = false
+    }
+    report(validateManifest(manifest, dir, label))
+    let patterns = null
+    const pLabel = `mods/${dir}/patterns.json`
+    try {
+      const p = JSON.parse(readText(root, pLabel))
+      if (!Array.isArray(p) || p.some((e) => !isTable(e))) throw new Error('must be an array of objects')
+      for (const e of p) {
+        if (Object.hasOwn(e, 'agents') && !(Array.isArray(e.agents) && e.agents.every((a) => typeof a === 'string'))) {
+          throw new Error(`pattern ${e.id}: agents must be an array of strings`)
+        }
+      }
+      patterns = p
+    } catch (e) {
+      if (e.code !== 'ENOENT') report([`${pLabel}: ${e.message}`])
+    }
+    if (ok) mods.push({ id: dir, dir: `mods/${dir}`, manifest, patterns })
+  }
+
+  const ctx = { common: null, runtime: null, agentIds: null }
+  for (const k of ['common', 'runtime']) {
+    const rel = `scripts/mods/${k}.mjs`
+    try {
+      ctx[k] = readText(root, rel)
+    } catch (e) {
+      errors.push(`${rel}: ${e.code === 'ENOENT' ? 'missing' : e.message}`)
+    }
+  }
+  if (mods.some((m) => usesLiveAgents(m.patterns))) {
+    try {
+      const agents = JSON.parse(readText(root, 'catalog/agents.json'))
+      if (!Array.isArray(agents)) throw new Error('must be an array')
+      ctx.agentIds = agents.map((a) => a?.id).filter((id) => typeof id === 'string')
+    } catch (e) {
+      errors.push(`catalog/agents.json: ${e.code === 'ENOENT' ? 'missing' : e.message}`)
+    }
+  }
+  return { mods, ctx, errors }
+}
+
+// ---------------------------------------------------------------------------------------
+// Rendering (pure)
+// ---------------------------------------------------------------------------------------
+
+const inCanonicalOrder = (events) => EVENTS.filter((e) => events.includes(e))
+
+function hookEntry(command) {
+  return [{ hooks: [{ type: 'command', command }] }]
+}
+
+function hooksByEvent(events, command) {
+  return { hooks: Object.fromEntries(inCanonicalOrder(events).map((e) => [e, hookEntry(command(e))])) }
+}
+
+function renderUnsupported(manifest, h) {
+  const t = manifest.harnesses[h]
+  const unsupported = t.unsupported ?? {}
+  const degraded = t.degraded ?? {}
+  if (t.supported && !Object.keys(unsupported).length && !Object.keys(degraded).length) return null
+  const blocks = [
+    `# ${manifest.mod.name} on ${HARNESS_NAMES[h]}`,
+    '<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->',
+  ]
+  if (!t.supported) blocks.push(`## Not supported\n\n${t.reason}`)
+  for (const [title, table] of [['Unsupported', unsupported], ['Degraded', degraded]]) {
+    const ks = Object.keys(table).sort(cmp)
+    if (ks.length) blocks.push(`## ${title}\n\n${ks.map((k) => `- \`${k}\`: ${table[k]}`).join('\n')}`)
+  }
+  return blocks.join('\n\n') + '\n'
+}
+
+/** Every generated file of one mod: Map<repo-relative path, content>. */
+export function renderMod(mod, ctx) {
+  if (typeof ctx?.common !== 'string' || typeof ctx?.runtime !== 'string') {
+    throw new TypeError('renderMod: ctx.common and ctx.runtime must be strings (see loadMods)')
+  }
+  const { id, manifest: m, patterns } = mod
+  const out = new Map()
+  const put = (rel, content) => out.set(`mods/${id}/${rel}`, content)
+
+  put('lib/common.mjs', ctx.common)
+  put('lib/runtime.mjs', ctx.runtime)
+
+  if (patterns) {
+    put('lib/patterns.mjs', `${GEN_HEADER} from patterns.json. Do not edit.\nexport default ${JSON.stringify(patterns, null, 2)};\n`)
+  }
+  if (usesLiveAgents(patterns)) {
+    if (!Array.isArray(ctx.agentIds)) throw new TypeError('renderMod: ctx.agentIds is required for a mod with agent-bearing patterns')
+    const selected = [...new Set(ctx.agentIds.filter((a) => LIVE_AGENT_RE.test(a)))].sort(cmp)
+    const known = new Set(selected)
+    const covered = new Set()
+    const errors = []
+    for (const p of patterns) {
+      for (const a of Array.isArray(p.agents) ? p.agents : []) {
+        if (known.has(a)) covered.add(a)
+        else errors.push(`mods/${id}/patterns.json: pattern ${p.id} references "${a}", which is not a live guard agent in catalog/agents.json`)
+      }
+    }
+    if (errors.length) throw aggregate(errors)
+    const coveredList = [...covered].sort(cmp)
+    const uncovered = selected.filter((a) => !covered.has(a))
+    put(
+      'lib/live-agents.mjs',
+      `${GEN_HEADER} from patterns.json and catalog/agents.json. Do not edit.\n` +
+        `export const covered = ${JSON.stringify(coveredList, null, 2)};\n` +
+        `export const uncovered = ${JSON.stringify(uncovered, null, 2)};\n`,
+    )
+  }
+
+  const cc = m.harnesses['claude-code']
+  if (cc.supported && cc.surfaces.includes('native')) {
+    put('.claude-plugin/plugin.json', json({ name: id, version: m.mod.version, description: m.mod.description }))
+    put('hooks/hooks.json', json({ modules: ['./register.ts'] }))
+  }
+  if (cc.supported && cc.surfaces.includes('classic')) {
+    put(
+      'claude-code/settings.hooks.json',
+      json(hooksByEvent(cc.events, (e) => `node "$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/${id}/bin/hook.mjs" --harness claude-code --event ${e}`)),
+    )
+  }
+  if (m.harnesses.kiro.supported) {
+    for (const e of inCanonicalOrder(m.harnesses.kiro.events)) {
+      put(
+        `kiro/${id}-${EV_KEBAB[e]}-hook.json`,
+        json({
+          version: 'v1',
+          hooks: [
+            {
+              name: `${id}:${e}`,
+              description: m.mod.description,
+              trigger: e,
+              action: { type: 'command', command: `node .kiro/vanguard-mods/${id}/bin/hook.mjs --harness kiro --event ${e}` },
+            },
+          ],
+        }),
+      )
+    }
+  }
+  if (m.harnesses.codex.supported) {
+    put('codex/hooks.json', json(hooksByEvent(m.harnesses.codex.events, (e) => `node .codex/vanguard-mods/${id}/bin/hook.mjs --harness codex --event ${e}`)))
+  }
+  for (const h of HARNESSES) {
+    const md = renderUnsupported(m, h)
+    if (md) put(`${h}/UNSUPPORTED.md`, md)
+  }
+  return new Map([...out].sort((a, b) => cmp(a[0], b[0])))
+}
+
+/** Every generated file for all mods plus catalog/mods.json, sorted by path; input order is irrelevant. */
+export function renderAll(mods, ctx) {
+  const sorted = [...mods].sort((a, b) => cmp(a.id, b.id))
+  const files = new Map()
+  const errors = []
+  for (const mod of sorted) {
+    try {
+      for (const [k, v] of renderMod(mod, ctx)) files.set(k, v)
+    } catch (e) {
+      errors.push(...(e.errors ?? [e.message]))
+    }
+  }
+  if (errors.length) throw aggregate(errors)
+  files.set(
+    'catalog/mods.json',
+    json(
+      sorted.map(({ id, manifest: m }) => ({
+        id,
+        name: m.mod.name,
+        version: m.mod.version,
+        description: m.mod.description,
+        reach_level: m.mod.reach_level,
+        events: [...m.mod.events],
+        harnesses: HARNESSES.filter((h) => m.harnesses[h].supported).sort(cmp),
+        path: `mods/${id}`,
+        footprint: {
+          env_reads: [...m.footprint.env_reads],
+          file_writes: [...m.footprint.file_writes],
+          spawns: [...m.footprint.spawns],
+          egress_hosts: [...m.footprint.egress_hosts],
+        },
+      })),
+    ),
+  )
+  return new Map([...files].sort((a, b) => cmp(a[0], b[0])))
+}
+
+// ---------------------------------------------------------------------------------------
+// Disk sync
+// ---------------------------------------------------------------------------------------
+
+const exists = (abs) => {
+  try {
+    lstatSync(abs)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function walkFiles(root, rel, found = []) {
+  const abs = safePath(root, rel)
+  let entries
+  try {
+    entries = readdirSync(abs, { withFileTypes: true })
+  } catch {
+    return found
+  }
+  for (const e of entries) {
+    const child = `${rel}/${e.name}`
+    safePath(root, child)
+    if (e.isDirectory()) walkFiles(root, child, found)
+    else found.push(child) // files, symlinks and anything else count as files
+  }
+  return found
+}
+
+/** Generated paths on disk that the current render no longer produces. */
+function findStale(root, ids, expected) {
+  const stale = []
+  for (const id of ids) {
+    const base = `mods/${id}`
+    for (const d of OWNED_DIRS) stale.push(...walkFiles(root, `${base}/${d}`))
+    for (const [d, names] of Object.entries(OWNED_FILES)) {
+      for (const name of names) if (exists(safePath(root, `${base}/${d}/${name}`))) stale.push(`${base}/${d}/${name}`)
+    }
+  }
+  return stale.filter((rel) => !expected.has(rel)).sort(cmp)
+}
+
+function findDrift(root, expected) {
+  const drift = []
+  for (const [rel, content] of expected) {
+    const abs = safePath(root, rel)
+    let actual = null
+    try {
+      actual = readFileSync(abs)
+    } catch {
+      // missing or unreadable counts as drift
+    }
+    if (!actual || !actual.equals(Buffer.from(content, 'utf8'))) drift.push(rel)
+  }
+  return drift
+}
+
+function safeWrite(root, realRoot, rel, content) {
+  const abs = safePath(root, rel)
+  mkdirSync(path.dirname(abs), { recursive: true })
+  const dir = realpathSync(path.dirname(abs))
+  if (dir !== realRoot && !dir.startsWith(realRoot + path.sep)) throw new Error(`${rel}: resolves outside the repo`)
+  if (exists(abs) && lstatSync(abs).isSymbolicLink()) throw new Error(`${rel}: is a symlink; refusing to write through it`)
+  writeFileSync(abs, content)
+}
+
+function pruneEmpty(abs) {
+  let entries
+  try {
+    entries = readdirSync(abs, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const e of entries) if (e.isDirectory()) pruneEmpty(path.join(abs, e.name))
+  if (readdirSync(abs).length === 0) rmdirSync(abs)
+}
+
+// ---------------------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------------------
+
+export function main(argv = process.argv.slice(2), root = ROOT) {
+  const modes = ['--check', '--print-manifests']
+  if (argv.length > 1 || (argv.length === 1 && !modes.includes(argv[0]))) {
+    console.error('Usage: node scripts/generate-mods.mjs [--check | --print-manifests]')
+    return 2
+  }
+  const fail = (errors) => {
+    for (const e of errors) console.error(e)
+    return 1
+  }
+
+  if (argv[0] === '--print-manifests') {
+    const { entries, errors } = readManifests(root)
+    if (errors.length) return fail(errors)
+    console.log(JSON.stringify(Object.fromEntries(entries.map((e) => [e.dir, e.manifest])), null, 2))
+    return 0
+  }
+
+  const { mods, ctx, errors } = loadMods(root)
+  let expected = new Map()
+  if (ctx.common !== null && ctx.runtime !== null) {
+    try {
+      expected = renderAll(mods, ctx)
+    } catch (e) {
+      errors.push(...(e.errors ?? [e.message]))
+    }
+  }
+  if (errors.length) return fail(errors)
+
+  let drift, stale
+  try {
+    drift = findDrift(root, expected)
+    stale = findStale(root, mods.map((m) => m.id), expected)
+  } catch (e) {
+    return fail([e.message])
+  }
+
+  if (argv[0] === '--check') {
+    const paths = [...new Set([...drift, ...stale])].sort(cmp)
+    if (paths.length === 0) {
+      console.log('OK: mods in sync')
+      return 0
+    }
+    console.error(`FAIL: mods out of sync (${paths.length} paths). Run: npm run mods:write`)
+    for (const p of paths) console.error(`  ${p}`)
+    return 1
+  }
+
+  try {
+    const realRoot = realpathSync(root)
+    for (const rel of drift) safeWrite(root, realRoot, rel, expected.get(rel))
+    for (const rel of stale) unlinkSync(path.join(root, rel))
+    for (const m of mods) for (const d of OWNED_DIRS) pruneEmpty(path.join(root, 'mods', m.id, d))
+  } catch (e) {
+    return fail([e.message])
+  }
+  console.log(`Generated ${mods.length} mods for ${HARNESSES.length} harnesses`)
+  return 0
+}
+
+function isEntryPoint() {
+  if (!process.argv[1]) return false
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
+  } catch {
+    return false
+  }
+}
+
+if (isEntryPoint()) process.exitCode = main()