pi-bro 0.29.0 → 0.31.0

package/resources/architecture-docs/scripts/check.mjs

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { render, safeRelative } from './render.mjs';
+import { localPath } from './inventory.mjs';
+
+// Match the repository checker’s backtick/tilde fence handling, plus inline
+// code spans. Mermaid is its own language and must not be parsed as Markdown.
+export function markdownLinks(text) {
+  let fence = '', width = 0;
+  const prose = [];
+  for (const line of text.split(/\r?\n/)) {
+    const token = /^\s*(`{3,}|~{3,})/.exec(line);
+    if (token) {
+      if (!fence) { fence = token[1][0]; width = token[1].length; }
+      else if (token[1][0] === fence && token[1].length >= width) fence = '';
+      prose.push('');
+    } else prose.push(fence || /^( {4}|\t)/.test(line) ? '' : line);
+  }
+  const source = prose.join('\n').replace(/(`+)(?!`)[\s\S]*?\1(?!`)/g, '');
+  return [...source.matchAll(/!?\[[^\]]*\]\((<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\)/g)]
+    .map(m => m[1].replace(/^<|>$/g, ''));
+}
+
+/** Validate the files that would exist after import, not just the model's view.
+ * Omitted assets resolve against the original repo; staging helpers never do.
+ * knownFiles is optional for the standalone CLI; the pipeline supplies it.
+ */
+export function check(root, { repositoryRoot = root, knownFiles } = {}) {
+  root = path.resolve(root);
+  repositoryRoot = path.resolve(repositoryRoot);
+  const docs = localPath(root, 'docs/architecture'), errors = [];
+  const known = knownFiles ? new Set(knownFiles) : undefined;
+  const knownTarget = relative => !known || known.has(relative) || [...known].some(p => p.startsWith(relative + '/'));
+  const targetExists = relative => {
+    if (relative === '.bro-architecture-support' || relative.startsWith('.bro-architecture-support/')) {
+      throw new Error('Reference to temporary architecture support: ' + relative);
+    }
+    safeRelative(relative, 'reference');
+    // Only proposed documentation may resolve against the staged tree. Source
+    // references and untouched/omitted assets must also exist in the real repo.
+    if (relative.startsWith('docs/architecture/') && fs.existsSync(localPath(root, relative))) return true;
+    return knownTarget(relative) && fs.existsSync(localPath(repositoryRoot, relative));
+  };
+  let result;
+  try { result = render(root, true); } catch (error) { errors.push(error.message); }
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const name = path.join(dir, entry.name), relative = path.relative(root, name).split(path.sep).join('/');
+      if (entry.isSymbolicLink()) { errors.push('Symlink inside architecture docs: ' + relative); continue; }
+      if (entry.isDirectory()) walk(name);
+      else if (entry.name.endsWith('.md')) {
+        for (const link of markdownLinks(fs.readFileSync(name, 'utf8'))) {
+          if (!link || link.startsWith('#') || /^(https?:|mailto:|data:)/i.test(link)) continue;
+          try {
+            const target = decodeURIComponent(link.split('#')[0]);
+            if (path.isAbsolute(target) || target.includes('\\') || /^[a-z][a-z0-9+.-]*:/i.test(target)) throw new Error('Unsafe local link: ' + link);
+            const resolved = path.relative(root, path.resolve(path.dirname(name), target)).split(path.sep).join('/');
+            if (!targetExists(resolved)) throw new Error('Broken link: ' + link);
+          } catch (error) {
+            errors.push((error instanceof URIError ? 'Invalid URL: ' + link : error.message) + ' in ' + relative);
+          }
+        }
+      }
+    }
+  };
+  if (!fs.existsSync(path.join(docs, 'README.md'))) errors.push('Missing docs/architecture/README.md');
+  if (fs.existsSync(docs)) walk(docs); else errors.push('Missing docs/architecture/');
+  if (result) {
+    for (const node of result.graph.nodes) {
+      for (const src of node.sources || []) {
+        try { if (!targetExists(src)) errors.push('Missing graph source: ' + src); } catch (error) { errors.push(error.message); }
+      }
+      if (node.doc) {
+        try { if (!targetExists('docs/architecture/' + safeRelative(node.doc, 'doc'))) errors.push('Missing graph guide: ' + node.doc); }
+        catch (error) { errors.push(error.message); }
+      }
+    }
+    if (!result.html.includes('id="graph-data"') || result.html.includes('src="https://') || result.html.includes('href="https://')) errors.push('HTML viewer is not self-contained');
+  }
+  if (errors.length) throw new Error(errors.join('\n'));
+  return { nodes: result.graph.nodes.length, edges: result.graph.edges.length };
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { const out = check(path.resolve(process.argv[2] || '.')); console.log('Architecture docs OK · ' + out.nodes + ' nodes · ' + out.edges + ' edges'); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/resources/architecture-docs/scripts/inventory.mjs

@@ -0,0 +1,83 @@
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readdirSync, existsSync as fssExists } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const EXCLUDE = new Set(['.git', 'node_modules', '.venv', 'venv', '.next', 'dist', 'build', 'coverage', '.cache', '__pycache__', '.turbo']);
+const SECRET = /(^|\/)(\.env(?:\..*)?|\.?credentials(?:\..*)?|auth\.json|id_rsa|id_ed25519|.*\.pem|.*\.key)$/i;
+
+/** Check every existing ancestor before reading or creating anything beneath it. */
+export function localPath(root, relative) {
+  if (!relative || path.isAbsolute(relative) || relative.includes('\\') || relative.split('/').some(p => !p || p === '.' || p === '..') || /[\x00-\x1f:]/.test(relative)) {
+    throw new Error('Unsafe project path: ' + relative);
+  }
+  let current = root;
+  for (const part of ['', ...relative.split('/')]) {
+    if (part) current = path.join(current, part);
+    try {
+      if (lstatSync(current).isSymbolicLink()) throw new Error('Refusing symlink: ' + relative);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return current;
+}
+
+export function listProjectFiles(root) {
+  let candidates;
+  try {
+    const data = execFileSync('git', ['-C', root, 'ls-files', '--cached', '--others', '--exclude-standard', '-z'], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    candidates = data.split('\0').filter(Boolean);
+  } catch {
+    candidates = [];
+    const visit = (dir, prefix = '') => {
+      for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+        if (EXCLUDE.has(dirent.name) || (prefix === '' && dirent.name === '.git')) continue;
+        const rel = prefix ? prefix + '/' + dirent.name : dirent.name;
+        if (dirent.isDirectory()) visit(path.join(dir, dirent.name), rel);
+        else if (dirent.isFile()) candidates.push(rel);
+      }
+    };
+    visit(root);
+  }
+  // Architecture docs may be intentionally ignored by Git. Still read and preserve them.
+  const architecture = localPath(root, 'docs/architecture');
+  const docs = [];
+  const visitDocs = (dir, prefix) => {
+    if (!fssExists(dir)) return;
+    for (const item of readdirSync(dir, { withFileTypes: true })) {
+      const rel = prefix + '/' + item.name;
+      if (item.isDirectory()) visitDocs(path.join(dir, item.name), rel);
+      else if (item.isFile()) docs.push(rel);
+    }
+  };
+  visitDocs(architecture, 'docs/architecture');
+  const unique = [...new Set([...candidates, ...docs])].sort();
+  return unique.filter(p => {
+    const rel = p.replaceAll('\\', '/');
+    if (path.isAbsolute(rel) || rel.split('/').includes('..') || rel.split('/').some(x => EXCLUDE.has(x)) || SECRET.test(rel)) return false;
+    try { return lstatSync(localPath(root, rel)).isFile(); } catch { return false; }
+  });
+}
+
+export function inventory(root, files = listProjectFiles(root)) {
+  const count = {};
+  const top = {};
+  for (const file of files) {
+    const ext = path.extname(file).toLowerCase() || '(none)';
+    count[ext] = (count[ext] || 0) + 1;
+    const folder = file.split('/')[0];
+    top[folder] = (top[folder] || 0) + 1;
+  }
+  const meaningful = /(readme|package\.json|pyproject\.toml|go\.mod|cargo\.toml|dockerfile|compose|dbt_project\.yml|schema\.yml|workflow|dag|app\.py|main\.[a-z]+|src\/bro\.ts|agents\.md)/i;
+  return {
+    files: files.length,
+    byExtension: Object.fromEntries(Object.entries(count).sort((a,b) => b[1]-a[1]).slice(0,20)),
+    topLevel: Object.fromEntries(Object.entries(top).sort((a,b) => b[1]-a[1]).slice(0,25)),
+    landmarks: files.filter(f => meaningful.test(f)).slice(0,120),
+    existingArchitectureDocs: files.filter(f => f.startsWith('docs/architecture/')).slice(0,150)
+  };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(process.argv[2] || '.');
+  console.log(JSON.stringify(inventory(root), null, 2));
+}

package/resources/architecture-docs/scripts/layout.mjs

@@ -0,0 +1,61 @@
+/** Pure layout: condense strongly connected components, then rank the DAG.
+ * A cycle shares a column; its downstream nodes do not get trapped there.
+ */
+export function layoutGraph(nodes, edges) {
+  const successors = new Map(nodes.map(n => [n.id, []]));
+  for (const e of edges) successors.get(e.from).push(e.to);
+  const indices = new Map(), low = new Map(), stack = [], active = new Set(), groups = [], groupOf = new Map();
+  let next = 0;
+  function visit(id) {
+    indices.set(id, next); low.set(id, next++); stack.push(id); active.add(id);
+    for (const other of successors.get(id)) {
+      if (!indices.has(other)) { visit(other); low.set(id, Math.min(low.get(id), low.get(other))); }
+      else if (active.has(other)) low.set(id, Math.min(low.get(id), indices.get(other)));
+    }
+    if (low.get(id) === indices.get(id)) {
+      const group = []; let member;
+      do { member = stack.pop(); active.delete(member); groupOf.set(member, groups.length); group.push(member); } while (member !== id);
+      groups.push(group);
+    }
+  }
+  for (const n of nodes) if (!indices.has(n.id)) visit(n.id);
+  const dag = groups.map(() => new Set()), degree = groups.map(() => 0), rank = groups.map(() => 0);
+  for (const e of edges) {
+    const from = groupOf.get(e.from), to = groupOf.get(e.to);
+    if (from !== to && !dag[from].has(to)) { dag[from].add(to); degree[to]++; }
+  }
+  const queue = groups.map((_, i) => i).filter(i => !degree[i]);
+  for (let i = 0; i < queue.length; i++) {
+    for (const to of dag[queue[i]]) {
+      rank[to] = Math.max(rank[to], rank[queue[i]] + 1);
+      if (--degree[to] === 0) queue.push(to);
+    }
+  }
+  const levels = [...new Set(rank)].sort((a, b) => a - b);
+  const column = new Map(nodes.map(n => [n.id, levels.indexOf(rank[groupOf.get(n.id)])]));
+  const columns = levels.map(() => []);
+  for (const n of nodes) columns[column.get(n.id)].push(n);
+  for (const list of columns) list.sort((a, b) => a.label.localeCompare(b.label));
+  const W = 224, H = 80, DY = 144, P = 52;
+  const lanes = levels.map(() => 0);
+  for (const e of edges) if (column.get(e.from) === column.get(e.to)) lanes[column.get(e.from)]++;
+  const positions = new Map(); let x = P;
+  columns.forEach((list, col) => {
+    list.forEach((n, row) => positions.set(n.id, { x, y: P + row * DY, column: col }));
+    x += W + Math.max(100, 60 + lanes[col] * 24);
+  });
+  const used = levels.map(() => 0);
+  const routes = edges.map(e => {
+    const a = positions.get(e.from), b = positions.get(e.to);
+    if (a.column === b.column) {
+      // Enter and leave on the right. Separate lanes keep feedback arrows and
+      // their rotated labels out of component boxes and out of the next column.
+      const right = a.x + W, lane = right + 36 + 24 * used[a.column]++;
+      const y = a.y + 24, y2 = b.y + 56;
+      return { d: `M${right} ${y} H${lane} V${y2} H${right}`, labelX: lane - 5, labelY: (y + y2) / 2, rotation: -90 };
+    }
+    const x1 = a.x + W, y1 = a.y + H / 2, x2 = b.x, y2 = b.y + H / 2, mid = Math.max(25, (x2 - x1) * .4);
+    return { d: `M${x1} ${y1} C${x1 + mid} ${y1},${x2 - mid} ${y2},${x2} ${y2}`, labelX: (x1 + x2) / 2, labelY: (y1 + y2) / 2 - 8, rotation: 0 };
+  });
+  return { nodeWidth: W, nodeHeight: H, width: x + P, height: P * 2 + Math.max(1, ...columns.map(c => c.length)) * DY, positions: Object.fromEntries(positions), routes };
+}

package/resources/architecture-docs/scripts/pipeline.mjs

@@ -0,0 +1,228 @@
+import fs from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { listProjectFiles, inventory, localPath } from './inventory.mjs';
+import { validateGraph, safeRelative, render } from './render.mjs';
+import { check } from './check.mjs';
+
+const exec=promisify(execFile);
+const CURRENT=path.dirname(fileURLToPath(import.meta.url));
+const RESOURCES=path.resolve(CURRENT,'..');
+const MAX_FILE=1024*1024,MAX_TOTAL=80*1024*1024,MAX_FILES=25000;
+const digest=b=>crypto.createHash('sha256').update(b).digest('hex');
+const inside=(root,name)=>name===root||name.startsWith(root+path.sep);
+const skip=/((^|\/)\.env($|\.)|(^|\/)auth\.json$|(^|\/)credentials(?:\.[^/]*)?$|\.pem$|\.key$|id_rsa$|id_ed25519$)/i;
+
+async function projectRoot(cwd){
+  const current=await fs.realpath(path.resolve(cwd));
+  try{
+    const {stdout}=await exec('git',['-C',current,'rev-parse','--show-toplevel'],{timeout:5000});
+    const resolved=await fs.realpath(path.resolve(stdout.trim()));
+    if(inside(resolved,current))return resolved;
+  }catch{}
+  return current;
+}
+async function describeRevision(root){
+  try{const {stdout}=await exec('git',['-C',root,'rev-parse','--short=12','HEAD'],{timeout:5000});
+  return 'Commit '+stdout.trim()+' (with working files when present)';}
+  catch{return 'Local project snapshot';}
+}
+function cancelled(signal) { signal?.throwIfAborted(); }
+async function hashFile(file, signal) {
+  const hash = crypto.createHash('sha256');
+  for await (const bytes of createReadStream(file)) { cancelled(signal); hash.update(bytes); }
+  return hash.digest('hex');
+}
+async function stage(cwd, { signal, maxFileBytes = MAX_FILE, maxTotalBytes = MAX_TOTAL } = {}) {
+  cancelled(signal);
+  const root = await projectRoot(cwd), paths = listProjectFiles(root);
+  if (!paths.length) throw new Error('No non-ignored project files were found in ' + root);
+  if (paths.length > MAX_FILES) throw new Error('Too many input files (' + paths.length + '); narrow the workspace first');
+  // Existing docs get first use of the model budget. Their baseline is independent
+  // of that budget, including large generated HTML and binary assets left in place.
+  paths.sort((a, b) => Number(b.startsWith('docs/architecture/')) - Number(a.startsWith('docs/architecture/')) || a.localeCompare(b));
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'pi-bro-architecture-'));
+  const workspace = path.join(dir, 'project'), files = [], omitted = [], documents = [];
+  let used = 0;
+  try {
+    await fs.mkdir(workspace, { recursive: true });
+    for (const relative of paths) {
+      cancelled(signal);
+      if (skip.test(relative) || relative.startsWith('.bro-architecture-support/')) continue;
+      const source = localPath(root, relative);
+      const stat = await fs.lstat(source);
+      if (!stat.isFile()) continue;
+      const isDoc = relative.startsWith('docs/architecture/');
+      if (isDoc) documents.push({ path: relative, sha: await hashFile(source, signal), mode: stat.mode & 0o777 });
+      if (stat.size > maxFileBytes || used + stat.size > maxTotalBytes) { omitted.push(relative + ' (size or snapshot budget)'); continue; }
+      const bytes = await fs.readFile(source);
+      if (bytes.includes(0)) { omitted.push(relative + ' (binary)'); continue; }
+      used += bytes.length;
+      const dest = path.join(workspace, relative);
+      await fs.mkdir(path.dirname(dest), { recursive: true });
+      await fs.writeFile(dest, bytes, { mode: 0o600 });
+      files.push({ path: relative, sha: digest(bytes) });
+    }
+    if (!files.length) throw new Error('No readable source files were found');
+    const support = path.join(workspace, '.bro-architecture-support');
+    await fs.mkdir(support, { recursive: true });
+    await fs.cp(path.join(RESOURCES, 'references'), path.join(support, 'references'), { recursive: true });
+    const information = { root, dir, workspace, files, documents, knownFiles: paths, omitted, revision: await describeRevision(root), inventory: inventory(root, files.map(f => f.path)) };
+    cancelled(signal);
+    await fs.writeFile(path.join(dir, 'state.json'), JSON.stringify(information), { mode: 0o600 });
+    cancelled(signal);
+    return { root, dir, workspace, inventory: information.inventory, omitted: omitted.slice(0, 40), included: files.length };
+  } catch (error) { await fs.rm(dir, { recursive: true, force: true }); throw error; }
+}
+function parseProposal(text){
+  if(typeof text!=='string'||Buffer.byteLength(text,'utf8')>2*1024*1024)throw new Error('Model output is missing or too large');
+  let source=text.trim();
+  if(source.startsWith('```'))source=source.replace(/^```(?:json)?\s*\n?/i,'').replace(/\n?```\s*$/,'');
+  let value;try{value=JSON.parse(source);}catch{throw new Error('Architecture model did not return a single valid JSON proposal; re-run to try again');}
+  if(!value||typeof value!=='object'||Array.isArray(value))throw new Error('Architecture proposal must be an object');
+  if(!value.files||typeof value.files!=='object'||Array.isArray(value.files)||!Object.hasOwn(value.files,'README.md'))throw new Error('Proposal needs files.README.md');
+  if(typeof value.summary!=='string'||!value.summary.trim()||value.summary.length>10000)throw new Error('Proposal needs a short summary');
+  if(!Array.isArray(value.unknowns)||value.unknowns.length>100||value.unknowns.some(x=>typeof x!=='string'||x.length>1000))throw new Error('Invalid unknowns');
+  validateGraph(value.graph);
+  if(Object.keys(value.files).length>80)throw new Error('Too many generated files');
+  let bytes=0;
+  for(const [relative,content] of Object.entries(value.files)){
+    safeRelative(relative,'output');
+    if(!(/\.md$|\.mmd$/i.test(relative))||relative.startsWith('diagrams/')&& !relative.endsWith('.mmd')||['architecture.graph.json','architecture.html'].includes(relative))throw new Error('Output must be Markdown or Mermaid: '+relative);
+    if(typeof content!=='string'||!content.trim())throw new Error('Empty documentation file: '+relative);
+    bytes+=Buffer.byteLength(content);
+    if(bytes>1024*1024)throw new Error('Generated documentation exceeds 1 MiB');
+  }
+  if(!value.files['README.md'].includes('architecture.html'))value.files['README.md']+='\n\n[Explore the architecture map](architecture.html)\n';
+  return value;
+}
+async function stagedInputsAgree(state, signal) {
+  for (const original of state.files) {
+    cancelled(signal);
+    const file = localPath(state.workspace, original.path);
+    let hash; try { hash = await hashFile(file, signal); } catch (error) { cancelled(signal); throw new Error('Staged source was removed: ' + original.path); }
+    if (hash !== original.sha) throw new Error('Staged source was modified during inspection: ' + original.path);
+  }
+}
+async function originalsAgree(state, signal) {
+  const originals = new Map([...state.files, ...(state.documents || [])].map(f => [f.path, f]));
+  for (const original of originals.values()) {
+    cancelled(signal);
+    const file = localPath(state.root, original.path);
+    let hash; try { hash = await hashFile(file, signal); } catch (error) { cancelled(signal); throw new Error('Source changed during documentation: ' + original.path); }
+    if (hash !== original.sha) throw new Error('Source changed during documentation: ' + original.path + '. Re-run to document the new revision.');
+  }
+}
+async function prepareChanges(state, proposal, signal) {
+  const docs = localPath(state.workspace, 'docs/architecture');
+  await fs.mkdir(docs, { recursive: true });
+  const files = { ...proposal.files };
+  const graph = { ...proposal.graph, project: { ...proposal.graph.project, revision: state.revision || 'Local project snapshot' } };
+  files['architecture.graph.json'] = JSON.stringify(graph, null, 2) + '\n';
+  for (const [relative, text] of Object.entries(files)) {
+    cancelled(signal);
+    const target = localPath(state.workspace, 'docs/architecture/' + relative);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, text, { mode: 0o600 });
+  }
+  localPath(state.workspace, 'docs/architecture/architecture.html');
+  render(state.workspace);
+  files['architecture.html'] = await fs.readFile(path.join(docs, 'architecture.html'), 'utf8');
+  check(state.workspace, { repositoryRoot: state.root, knownFiles: state.knownFiles });
+  cancelled(signal);
+  return files;
+}
+async function install(state, files, signal) {
+  const root = state.root, docs = localPath(root, 'docs/architecture');
+  await originalsAgree(state, signal);
+  const originals = new Map((state.documents || state.files).map(f => [f.path, f]));
+  const previous = new Map(), pending = [];
+  for (const [relative, text] of Object.entries(files)) {
+    cancelled(signal);
+    safeRelative(relative, 'output');
+    const target = localPath(root, 'docs/architecture/' + relative);
+    let old = null, mode;
+    try { old = await fs.readFile(target); mode = (await fs.stat(target)).mode & 0o777; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const original = originals.get('docs/architecture/' + relative);
+    if (original) {
+      if (!old || digest(old) !== original.sha) throw new Error('Architecture document changed during generation: ' + relative);
+    } else if (old) throw new Error('New architecture document appeared during generation: ' + relative);
+    previous.set(relative, { bytes: old, mode });
+    if (!old || old.toString('utf8') !== text) pending.push({ relative, text, target });
+  }
+  const completed = [], temporaries = [];
+  try {
+    for (const item of pending) {
+      cancelled(signal);
+      localPath(root, 'docs/architecture/' + item.relative);
+      await fs.mkdir(path.dirname(item.target), { recursive: true });
+      const tmp = item.target + '.bro-' + crypto.randomUUID() + '.tmp';
+      temporaries.push(tmp);
+      // New public docs use the normal umask; refresh keeps the existing mode.
+      await fs.writeFile(tmp, item.text, { flag: 'wx' });
+      const before = previous.get(item.relative);
+      if (before.mode !== undefined) await fs.chmod(tmp, before.mode);
+    }
+    for (let i = 0; i < pending.length; i++) {
+      cancelled(signal);
+      const item = pending[i], before = previous.get(item.relative).bytes;
+      localPath(root, 'docs/architecture/' + item.relative);
+      let live = null; try { live = await fs.readFile(item.target); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      if ((before === null) !== (live === null) || (before && live && !before.equals(live))) throw new Error('Architecture docs changed during import: ' + item.relative);
+      await fs.rename(temporaries[i], item.target);
+      completed.push(item);
+      // In-process cancellation throws here, then waits for rollback. It never
+      // kills the importer between a rename and recording what must be restored.
+      cancelled(signal);
+    }
+    cancelled(signal);
+    return completed.map(item => 'docs/architecture/' + item.relative);
+  } catch (error) {
+    const failures = [];
+    for (const item of completed.reverse()) {
+      try {
+        localPath(root, 'docs/architecture/' + item.relative);
+        const live = await fs.readFile(item.target);
+        if (!live.equals(Buffer.from(item.text))) throw new Error('Another writer changed this document');
+        const before = previous.get(item.relative);
+        if (before.bytes === null) await fs.rm(item.target);
+        else {
+          const tmp = item.target + '.bro-' + crypto.randomUUID() + '.tmp';
+          temporaries.push(tmp);
+          await fs.writeFile(tmp, before.bytes, { flag: 'wx' });
+          await fs.chmod(tmp, before.mode);
+          await fs.rename(tmp, item.target);
+        }
+      } catch { failures.push(item.relative); }
+    }
+    if (failures.length) throw new Error(error.message + '; rollback was incomplete for ' + failures.join(', '));
+    throw error;
+  } finally {
+    for (const tmp of temporaries) await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+async function apply(dir, proposalPath, { signal } = {}) {
+  cancelled(signal);
+  const state = JSON.parse(await fs.readFile(path.join(dir, 'state.json'), 'utf8'));
+  if (state.dir !== path.resolve(dir)) throw new Error('Snapshot identity mismatch');
+  const proposal = parseProposal(await fs.readFile(proposalPath, 'utf8'));
+  await stagedInputsAgree(state, signal);
+  const files = await prepareChanges(state, proposal, signal);
+  const updated = await install(state, files, signal);
+  return { root: state.root, updated, summary: proposal.summary, unknowns: proposal.unknowns, nodes: proposal.graph.nodes.length };
+}
+export {stage,parseProposal,apply};
+if(process.argv[1]&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url)){
+  const command=process.argv[2];
+  try{
+    if(command==='prepare')console.log(JSON.stringify(await stage(process.argv[3]||'.')));
+    else if(command==='apply')console.log(JSON.stringify(await apply(path.resolve(process.argv[3]),path.resolve(process.argv[4]))));
+    else throw new Error('Use prepare <repo> or apply <snapshot-dir> <proposal.json>');
+  }catch(e){console.error(e.message);process.exitCode=1;}
+}

package/resources/architecture-docs/scripts/render.mjs

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { layoutGraph } from './layout.mjs';
+
+const HERE=path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE=path.resolve(HERE,'../assets/architecture-viewer.html');
+export const sha=(text)=>crypto.createHash('sha256').update(text).digest('hex');
+
+function nonempty(value,name,max=5000){if(typeof value!=='string'||!value.trim()||value.length>max)throw new Error(name+' must be non-empty text');return value;}
+export function safeRelative(value,name){
+  if(typeof value!=='string'||!value||value.includes('\\')||path.posix.isAbsolute(value)||value.startsWith('/')||value.split('/').some(x=>x===''||x==='.'||x==='..')||/[\x00-\x1f?#]/.test(value)||/^[A-Za-z]:/.test(value)) throw new Error('Unsafe '+name+': '+String(value));
+  return value;
+}
+export function validateGraph(g){
+  if(!g||typeof g!=='object'||Array.isArray(g))throw new Error('Graph must be an object');
+  if(!g.project||typeof g.project!=='object')throw new Error('Graph needs project');
+  nonempty(g.project.name,'project.name',200);nonempty(g.project.summary,'project.summary',2000);
+  if(g.project.revision!==undefined)nonempty(g.project.revision,'project.revision',500);
+  if(!Array.isArray(g.nodes)||!g.nodes.length||g.nodes.length>250)throw new Error('Graph needs 1–250 nodes');
+  if(!Array.isArray(g.edges)||g.edges.length>1500)throw new Error('Invalid graph edges');
+  if(g.flows!==undefined&&!Array.isArray(g.flows))throw new Error('Invalid flows');
+  const ids=new Set();
+  for(const n of g.nodes){
+    if(!n||typeof n!=='object'||typeof n.id!=='string'||!/^[a-zA-Z0-9_-]{1,80}$/.test(n.id)||ids.has(n.id))throw new Error('Invalid/duplicate node id');
+    ids.add(n.id);nonempty(n.label,'node.label',120);nonempty(n.description,'node.description',2000);
+    if(n.kind!==undefined)nonempty(n.kind,'node.kind',80);
+    if(n.sources!==undefined){if(!Array.isArray(n.sources)||n.sources.length>30)throw new Error('Invalid node sources');for(const p of n.sources)safeRelative(p,'source');}
+    if(n.doc!==undefined)safeRelative(n.doc,'doc');
+  }
+  for(const e of g.edges){if(!e||!ids.has(e.from)||!ids.has(e.to))throw new Error('Edge references a missing node');nonempty(e.label,'edge.label',250);}
+  const flowIDs=new Set();for(const f of g.flows||[]){if(!f||typeof f.id!=='string'||!/^[a-zA-Z0-9_-]{1,80}$/.test(f.id)||flowIDs.has(f.id))throw new Error('Invalid/duplicate flow id');flowIDs.add(f.id);nonempty(f.label,'flow.label',150);if(!Array.isArray(f.steps)||!f.steps.length||f.steps.some(id=>!ids.has(id)))throw new Error('Flow references a missing node');}
+  return g;
+}
+const escapeHTML=(s)=>String(s).replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replaceAll('"','&quot;');
+export function renderGraph(raw,graph){
+  validateGraph(graph);
+  const template=fs.readFileSync(TEMPLATE,'utf8');
+  const fallback='<ul>'+graph.nodes.map(n=>'<li><strong>'+escapeHTML(n.label)+'</strong> — '+escapeHTML(n.description)+'</li>').join('')+'</ul>';
+  const json=JSON.stringify({ ...graph, layout: layoutGraph(graph.nodes, graph.edges) }).replaceAll('<','\\u003c').replaceAll('>','\\u003e').replaceAll('&','\\u0026');
+  const values={
+    '__TITLE__':escapeHTML(graph.project.name),
+    '__SUMMARY__':escapeHTML(graph.project.summary),
+    '__REVISION__':escapeHTML(graph.project.revision||'repository snapshot'),
+    '__SHA__':sha(raw),
+    '__DATA__':json,
+    '__NOSCRIPT__':fallback
+  };
+  return template.replace(/__TITLE__|__SUMMARY__|__REVISION__|__SHA__|__DATA__|__NOSCRIPT__/g,m=>values[m]);
+}
+export function render(root,checkOnly=false){
+  const docs=path.join(root,'docs','architecture');
+  const raw=fs.readFileSync(path.join(docs,'architecture.graph.json'),'utf8');
+  const graph=validateGraph(JSON.parse(raw));
+  const html=renderGraph(raw,graph);
+  const file=path.join(docs,'architecture.html');
+  if(checkOnly){
+    if(!fs.existsSync(file)||fs.readFileSync(file,'utf8')!==html)throw new Error('architecture.html is missing or stale; re-render the graph');
+  } else fs.writeFileSync(file,html);
+  return {graph,html,file};
+}
+if(process.argv[1]&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url)){
+  try{const root=path.resolve(process.argv[2]||'.');const result=render(root,process.argv.includes('--check'));console.log((process.argv.includes('--check')?'Checked ':'Rendered ')+path.relative(root,result.file));}
+  catch(e){console.error(e.message);process.exitCode=1;}
+}