explainmyrepo 0.1.1

package/tools/build-kb.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// build-kb.mjs — Station 1 (UNDERSTAND): build the REAL RVF KB + structured extraction.
+//
+// Thin wrapper over the existing, already-working kb/ engine (ADR-0005 D3). It runs, in order:
+//   1. kb/build-kb.mjs       --target <slug>  -> the real RVF store (HNSW, local 384-dim embeds)
+//   2. kb/extract-symbols.mjs        <slug>   -> <slug>-symbols.json     (public API surface)
+//   3. kb/dep-graph.mjs              <slug>    -> <slug>-dep-graph.json   (component/dep graph)
+//   4. kb/entrypoints.mjs           <slug>     -> <slug>-entrypoints.json (build/test/run commands)
+// (2–4 feed the INV-18 architecture + flow diagrams and the Station-6 pack. The authored primer
+// and its index-primer step are a later, brain-owned deliverable — NOT this tool's job.)
+//
+// Uniform tool convention (tools/CONTRACT.md §b): `node tools/build-kb.mjs <build-dir>`.
+//   reads  : <build-dir>/build.json -> repo.slug, repo.clonePath, repo.name
+//   writes : the `understanding` + `kb` slots; the real store files under kb/stores/<slug>/
+//   stdout : exactly ONE JSON result object; child engine output is routed to stderr; exit 0 iff ok.
+//
+// PURE: reads only its declared build.json slice + its own freshly-produced outputs. FAIL LOUD: a
+// failed RVF build, a missing/empty store, or a non-canonical .small.rvf (a missing `embed` block)
+// all stop non-zero with a clear reason — NEVER a JSON-only fallback (INV-06) and never a placeholder.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));   // tools/
+const REPO_ROOT = path.resolve(__dirname, '..');                 // Ruv-Explainer/
+const KB_DIR = path.join(REPO_ROOT, 'kb');
+
+// ---------- uniform result protocol ----------
+function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
+function fail(error) { console.error(`[build-kb] FAIL: ${error}`); emit({ ok: false, outputs: {}, error }); process.exit(1); }
+function done(outputs) { emit({ ok: true, outputs, error: null }); process.exit(0); }
+
+// Run a kb/ engine script; child stdout + stderr are routed to OUR stderr (fd 2) so our stdout
+// stays a single clean JSON object. A non-zero child exit throws -> we fail loud.
+// extraEnv is merged into process.env — used to forward KB_REPO_DIR so all scripts index the
+// correct build-dir clone instead of the hardcoded repoDir in kb/kb.config.mjs (Blocker-1 fix).
+function runKbScript(script, args, timeout, extraEnv = {}) {
+  const scriptPath = path.join(KB_DIR, script);
+  if (!fs.existsSync(scriptPath)) fail(`kb engine script missing: ${path.relative(REPO_ROOT, scriptPath)}`);
+  console.error(`[build-kb] run: node kb/${script} ${args.join(' ')}`);
+  try {
+    execFileSync(process.execPath, [scriptPath, ...args], {
+      cwd: REPO_ROOT, env: { ...process.env, ...extraEnv }, stdio: ['ignore', 2, 2], timeout, maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch (e) {
+    const why = e && e.signal ? `timed out / killed (${e.signal})` : `exit ${e && e.status}`;
+    fail(`kb/${script} failed for target "${args[args.length - 1]}" (${why}) — is the target registered in kb/kb.config.mjs with an \`embed\` block? (repoDir forwarded via KB_REPO_DIR: ${extraEnv.KB_REPO_DIR || 'not set'}) (${e && e.message ? e.message.split('\n')[0] : ''})`);
+  }
+}
+
+function countJsonlLines(file) {
+  let n = 0;
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) if (line.trim()) n++;
+  return n;
+}
+
+function readJsonSafe(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function main() {
+  const buildDir = process.argv[2];
+  if (!buildDir) fail('usage: node tools/build-kb.mjs <build-dir>  (missing build dir argument)');
+  const buildJsonPath = path.join(path.resolve(buildDir), 'build.json');
+  if (!fs.existsSync(buildJsonPath)) fail(`build.json not found at ${buildJsonPath} — run clone-repo first`);
+
+  let ctx;
+  try { ctx = JSON.parse(fs.readFileSync(buildJsonPath, 'utf8')); }
+  catch (e) { fail(`build.json is not valid JSON: ${e.message}`); }
+
+  const slug = ctx?.repo?.slug;
+  const clonePath = ctx?.repo?.clonePath;
+  const repoName = ctx?.repo?.name || slug;
+  if (!slug) fail('build.json has no repo.slug — run clone-repo first');
+  if (!clonePath || !fs.existsSync(clonePath) || !fs.statSync(clonePath).isDirectory()) {
+    fail(`repo.clonePath is missing or not a directory: ${clonePath} — run clone-repo first`);
+  }
+
+  // ---- run the real kb/ engine (build first, then the three structured extractors) ----
+  // Forward clonePath via KB_REPO_DIR so all four scripts index THIS build dir's clone,
+  // not the hardcoded repoDir in kb/kb.config.mjs (CONTRACT §b build-dir guarantee, Blocker-1 fix).
+  const kbEnv = { KB_REPO_DIR: clonePath };
+  runKbScript('build-kb.mjs', ['--target', slug], 1_200_000, kbEnv);   // embeds every chunk; allow time
+  runKbScript('extract-symbols.mjs', [slug], 600_000, kbEnv);           // rustdoc-json can be slow
+  runKbScript('dep-graph.mjs', [slug], 300_000, kbEnv);
+  runKbScript('entrypoints.mjs', [slug], 300_000, kbEnv);
+
+  // ---- verify the real outputs exist (no fake KB, no silent partial) ----
+  const storeDir = path.join(KB_DIR, 'stores', slug);
+  const f = {
+    rvf: path.join(storeDir, `${slug}-kb.rvf`),
+    smallRvf: path.join(storeDir, `${slug}-kb.small.rvf`),
+    passages: path.join(storeDir, `${slug}-kb.passages.jsonl`),
+    ids: path.join(storeDir, `${slug}-kb.ids.json`),
+    symbols: path.join(storeDir, `${slug}-symbols.json`),
+    depGraph: path.join(storeDir, `${slug}-dep-graph.json`),
+    entrypoints: path.join(storeDir, `${slug}-entrypoints.json`),
+  };
+
+  if (!fs.existsSync(f.rvf)) {
+    if (fs.existsSync(f.smallRvf)) {
+      fail(`build-kb wrote ${slug}-kb.small.rvf instead of the canonical ${slug}-kb.rvf — the target "${slug}" is missing an \`embed\` block in kb/kb.config.mjs (ADR-0005 D3). make-pack globs <slug>-kb.rvf and cannot find a .small.rvf store.`);
+    }
+    fail(`RVF build produced no store at ${path.relative(REPO_ROOT, f.rvf)} — the real KB build failed (INV-06: no JSON fallback)`);
+  }
+  for (const [key, file] of [['passages', f.passages], ['ids', f.ids], ['symbols', f.symbols], ['dep-graph', f.depGraph], ['entrypoints', f.entrypoints]]) {
+    if (!fs.existsSync(file)) fail(`expected ${key} output missing: ${path.relative(REPO_ROOT, file)} — structured extraction did not complete`);
+  }
+
+  // ---- passageCount > 0 (INV-06) ----
+  let passageCount;
+  try { passageCount = countJsonlLines(f.passages); }
+  catch (e) { fail(`could not read passages file ${path.relative(REPO_ROOT, f.passages)}: ${e.message}`); }
+  if (!(passageCount > 0)) fail(`KB has ${passageCount} passages — an empty corpus is not a real KB (INV-06)`);
+
+  // ---- embed model: read the sidecar the engine wrote next to the canonical .rvf ----
+  const embedCfg = readJsonSafe(`${f.rvf}.embed.json`);
+  const embedModel = (embedCfg && embedCfg.model) || 'Xenova/bge-small-en-v1.5';
+  if (!embedCfg) console.error(`[build-kb] warning: no ${slug}-kb.rvf.embed.json sidecar; reporting default embedModel ${embedModel}`);
+
+  // ---- mechanical (non-judgment) facts for the understanding slot ----
+  const dep = readJsonSafe(f.depGraph) || {};
+  const sym = readJsonSafe(f.symbols) || {};
+  const ent = readJsonSafe(f.entrypoints) || {};
+  const ecosystems = Array.isArray(dep.ecosystems) && dep.ecosystems.length ? dep.ecosystems.join('+') : 'unknown';
+  const componentCount = typeof dep.componentCount === 'number' ? dep.componentCount : (Array.isArray(dep.nodes) ? dep.nodes.length : 0);
+  const symbolCount = typeof sym.count === 'number' ? sym.count : (Array.isArray(sym.symbols) ? sym.symbols.length : 0);
+  const commandCount = Array.isArray(ent.commands) ? ent.commands.length : 0;
+  const summary = `${repoName} — ${ecosystems} repository indexed into a 384-dim RVF knowledge base: `
+    + `${passageCount} passages, ${componentCount} components, ${symbolCount} public symbols, ${commandCount} entrypoint commands.`;
+
+  // ---- assemble the two slots; paths are repo-root-relative (matching CONTRACT §a) ----
+  const rel = (p) => path.relative(REPO_ROOT, p);
+  const understanding = { repoName, summary, passageCount };
+  const kb = {
+    slug,
+    storeDir: rel(storeDir),
+    rvfPath: rel(f.rvf),
+    passagesPath: rel(f.passages),
+    idsPath: rel(f.ids),
+    embedModel,
+    primerPath: rel(path.join(storeDir, `${slug}-primer.md`)),   // authored later by the brain (S1)
+    symbolsPath: rel(f.symbols),
+    depGraphPath: rel(f.depGraph),
+    entrypointsPath: rel(f.entrypoints),
+  };
+
+  ctx.understanding = { ...(ctx.understanding || {}), ...understanding };
+  ctx.kb = { ...(ctx.kb || {}), ...kb };
+  try { fs.writeFileSync(buildJsonPath, JSON.stringify(ctx, null, 2) + '\n'); }
+  catch (e) { fail(`could not write build.json: ${e.message}`); }
+
+  console.error(`[build-kb] OK ${slug}: ${passageCount} passages, ${symbolCount} symbols, ${componentCount} components (${ecosystems})`);
+  done({ slot: ['understanding', 'kb'], understanding, kb, passageCount });
+}
+
+main();

package/tools/clone-repo.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// clone-repo.mjs — Station 0–1 (VALIDATE + CLONE).
+//
+// Validate that the target repo URL is reachable, then clone it into <build-dir>/repo. Supports
+// PUBLIC repos and PRIVATE / owner repos via a GitHub token supplied with the top-level
+// `git -c http.extraheader=...` option — which is process-scoped and is NEVER written into the
+// cloned repo's config (so no credentials are baked into the saved remote).
+//
+// Uniform tool convention (tools/CONTRACT.md §b): `node tools/clone-repo.mjs <build-dir>`.
+//   reads  : <build-dir>/build.json -> repo.url   (+ GITHUB_TOKEN / GH_TOKEN from env for private)
+//   writes : the `repo` slot (owner/name/slug/private/defaultBranch/clonePath/reachable) and the
+//            top-level buildId (set first, here); the working tree at <build-dir>/repo/
+//   stdout : exactly ONE JSON result object; all diagnostics go to stderr; exit 0 iff ok:true.
+//
+// PURE: reads only repo.url (its declared slice) + the env token; writes only the repo slot +
+// buildId + its own working tree. FAIL LOUD: any failure exits non-zero with a clear reason and
+// never writes a placeholder / partial clone past an error (tools/CONTRACT.md §b·6, INV-04).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+
+// ---------- uniform result protocol ----------
+function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
+function fail(error) { console.error(`[clone-repo] FAIL: ${error}`); emit({ ok: false, outputs: {}, error }); process.exit(1); }
+function done(outputs) { emit({ ok: true, outputs, error: null }); process.exit(0); }
+
+// ---------- url parsing (https | scp-like git@host:owner/name) ----------
+function parseRepoUrl(raw) {
+  let s = String(raw || '').trim();
+  if (!s) return null;
+  const scp = s.match(/^git@([^:]+):(.+)$/);          // git@github.com:owner/name(.git)
+  if (scp) s = `https://${scp[1]}/${scp[2]}`;
+  if (!/^[a-z]+:\/\//i.test(s)) s = `https://${s}`;     // bare github.com/owner/name
+  s = s.replace(/\/+$/, '');
+  let u;
+  try { u = new URL(s); } catch { return null; }
+  const parts = u.pathname.replace(/^\/+/, '').split('/').filter(Boolean);
+  if (parts.length < 2) return null;
+  const owner = parts[0];
+  const name = parts[1].replace(/\.git$/i, '');
+  if (!owner || !name) return null;
+  return { host: u.host, owner, name, cloneUrl: `https://${u.host}/${owner}/${name}.git` };
+}
+
+// ---------- git helpers (token never logged) ----------
+function runGit(args, { capture = true, timeout = 120000 } = {}) {
+  try {
+    const out = execFileSync('git', args, {
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },   // never block on an interactive prompt
+      stdio: ['ignore', capture ? 'pipe' : 2, 'pipe'],     // non-captured stdout -> our stderr (fd 2)
+      timeout, maxBuffer: 32 * 1024 * 1024,
+    });
+    return { ok: true, stdout: capture && out ? out.toString() : '', stderr: '' };
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return { ok: false, stdout: '', stderr: 'git executable not found on PATH' };
+    return { ok: false, stdout: e.stdout ? e.stdout.toString() : '', stderr: e.stderr ? e.stderr.toString().trim() : (e.message || 'git failed'), code: e.status };
+  }
+}
+
+function defaultBranchFromSymref(lsRemoteStdout) {
+  const m = (lsRemoteStdout || '').match(/^ref:\s+refs\/heads\/(\S+)\s+HEAD/m);
+  return m ? m[1] : null;
+}
+
+function main() {
+  const buildDir = process.argv[2];
+  if (!buildDir) fail('usage: node tools/clone-repo.mjs <build-dir>  (missing build dir argument)');
+  const buildDirAbs = path.resolve(buildDir);
+  const buildJsonPath = path.join(buildDirAbs, 'build.json');
+  if (!fs.existsSync(buildJsonPath)) fail(`build.json not found at ${buildJsonPath} — the brain must create the build dir + build.json (with repo.url) first`);
+
+  let ctx;
+  try { ctx = JSON.parse(fs.readFileSync(buildJsonPath, 'utf8')); }
+  catch (e) { fail(`build.json is not valid JSON: ${e.message}`); }
+
+  const url = ctx?.repo?.url;
+  if (!url) fail('build.json has no repo.url — clone-repo requires repo.url as its declared input');
+
+  const parsed = parseRepoUrl(url);
+  if (!parsed) fail(`could not parse owner/name from repo.url "${url}" (expected https://host/owner/name or git@host:owner/name)`);
+  const { host, owner, name, cloneUrl } = parsed;
+
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '';
+  const base = `https://${host}/`;
+  const authArgs = token
+    ? ['-c', `http.${base}.extraheader=AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`]
+    : [];
+  // Probe args neutralise any ambient credential helper so "public vs private" is an HONEST signal.
+  const noAuthProbe = ['-c', 'credential.helper=', 'ls-remote', '--symref', cloneUrl, 'HEAD'];
+  const authProbe = [...authArgs, '-c', 'credential.helper=', 'ls-remote', '--symref', cloneUrl, 'HEAD'];
+
+  // ---- Station 0: reachability + public/private detection ----
+  console.error(`[clone-repo] probing ${owner}/${name} on ${host} (unauthenticated)`);
+  let isPrivate;
+  let symref;
+  const pub = runGit(noAuthProbe);
+  if (pub.ok) {
+    isPrivate = false;
+    symref = pub.stdout;
+  } else if (token) {
+    console.error('[clone-repo] unauthenticated probe failed — retrying with token');
+    const prv = runGit(authProbe);
+    if (!prv.ok) fail(`repo not reachable even with a token: ${owner}/${name} — check the URL and that the token can access it (git: ${prv.stderr || `exit ${prv.code}`})`);
+    isPrivate = true;
+    symref = prv.stdout;
+  } else {
+    fail(`repo not reachable unauthenticated: ${owner}/${name} — if it is PRIVATE set GITHUB_TOKEN or GH_TOKEN; if PUBLIC check the URL (git: ${pub.stderr || `exit ${pub.code}`})`);
+  }
+
+  // ---- Station 1: clone into <build-dir>/repo (idempotent: replace any prior tree) ----
+  const dest = path.join(buildDirAbs, 'repo');
+  try { fs.rmSync(dest, { recursive: true, force: true }); }
+  catch (e) { fail(`could not clear prior clone at ${dest}: ${e.message}`); }
+  fs.mkdirSync(buildDirAbs, { recursive: true });
+
+  // Top-level `git -c ...` (BEFORE the `clone` subcommand) applies the auth header to THIS process
+  // only; it is NOT persisted into <dest>/.git/config, so the saved remote stays credential-free.
+  const cloneArgs = [...authArgs, 'clone', '--depth', '1', '--no-tags', '--single-branch', cloneUrl, dest];
+  console.error(`[clone-repo] cloning ${cloneUrl} -> ${dest} (private=${isPrivate})`);
+  const cloned = runGit(cloneArgs, { capture: false, timeout: 600000 });
+  if (!cloned.ok) fail(`git clone failed for ${owner}/${name}: ${cloned.stderr || `exit ${cloned.code}`}`);
+
+  // Guard: never bake creds into the saved remote (defence-in-depth on the §1 invariant).
+  try {
+    const savedCfg = fs.readFileSync(path.join(dest, '.git', 'config'), 'utf8');
+    if (/extraheader/i.test(savedCfg)) fail('refusing to finish: an http.extraheader leaked into the cloned repo config (credentials would be baked into the remote)');
+  } catch { /* no .git/config readable — handled by the working-tree check below */ }
+
+  if (!fs.existsSync(path.join(dest, '.git'))) fail(`clone produced no .git directory at ${dest}`);
+
+  // defaultBranch: prefer the remote symref; fall back to the checked-out HEAD.
+  let defaultBranch = defaultBranchFromSymref(symref);
+  if (!defaultBranch) {
+    const head = runGit(['-C', dest, 'rev-parse', '--abbrev-ref', 'HEAD']);
+    defaultBranch = head.ok ? head.stdout.trim() : null;
+  }
+  if (!defaultBranch) fail('cloned successfully but could not determine the default branch');
+
+  // ---- merge ONLY the repo slot (+ buildId, set first here) ----
+  const repoSlot = {
+    url,
+    owner,
+    name,
+    slug: name,
+    private: isPrivate,
+    defaultBranch,
+    clonePath: dest,
+    reachable: true,
+  };
+  ctx.buildId = ctx.buildId || randomUUID();   // correlation + idempotency key; set first (clone-repo)
+  ctx.repo = { ...(ctx.repo || {}), ...repoSlot };
+  try { fs.writeFileSync(buildJsonPath, JSON.stringify(ctx, null, 2) + '\n'); }
+  catch (e) { fail(`could not write build.json: ${e.message}`); }
+
+  console.error(`[clone-repo] OK ${owner}/${name} (${defaultBranch}${isPrivate ? ', private' : ', public'}) -> ${dest}`);
+  done({ slot: 'repo', buildId: ctx.buildId, repo: repoSlot, clonePath: dest });
+}
+
+main();

package/tools/deploy.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// deploy.mjs — Station 8 tool #10: deploy the already-passed page to its own per-build URL.
+//
+// CONTRACT (tools/CONTRACT.md): node tools/deploy.mjs <build-dir>
+//   Reads (declared inputs):  page.dir, repo.slug   (+ deploy-provider token from env)
+//   Writes (own slot only):   publish.liveUrl, publish.http200
+//   stdout = ONE JSON result object; diagnostics → stderr; exit 0 iff ok:true, else non-zero.
+//
+// Provider-agnostic adapter, DEFAULT NETLIFY (clean {slug}-explainer.netlify.app subdomain, zero
+// DNS work). Vercel is a one-line swap-in via the ADAPTERS map (DEPLOY_PROVIDER=vercel). The deploy
+// is a direct, atomic, immutable per-build upload — the owner can later git-connect the published
+// repo for auto-redeploy; that is a post-publish owner action, not this station's job.
+//
+// FAIL LOUD: a missing token, a failed deploy, or a liveUrl that does not return 200 unauthenticated
+// is a non-zero exit with a clear message — never a placeholder URL, never a silent green.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sanitize = (s) => String(s).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+
+// ---- BuildContext I/O (only the declared slice in, only the owned slot out) ----
+function readContext(buildDir) {
+  const p = path.join(buildDir, 'build.json');
+  let raw;
+  try { raw = fs.readFileSync(p, 'utf8'); }
+  catch { throw new Error(`build.json not found at ${p} (run earlier stations first)`); }
+  try { return JSON.parse(raw); }
+  catch (e) { throw new Error(`build.json is not valid JSON: ${e.message}`); }
+}
+function mergeSlot(buildDir, slot, partial) {
+  const p = path.join(buildDir, 'build.json');
+  const obj = JSON.parse(fs.readFileSync(p, 'utf8'));   // re-read fresh, merge ONLY this slot's keys
+  obj[slot] = { ...(obj[slot] || {}), ...partial };
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+}
+
+// ---- shared helpers ----
+async function api(url, opts, label) {
+  const res = await fetch(url, opts);
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${label} failed: HTTP ${res.status} ${res.statusText} — ${text.slice(0, 300)}`);
+  return text ? JSON.parse(text) : {};
+}
+function zipDir(dir, zipPath) {
+  try {
+    fs.rmSync(zipPath, { force: true });
+    execFileSync('zip', ['-r', '-X', zipPath, '.'], { cwd: dir, stdio: ['ignore', 'ignore', 'inherit'] });
+  } catch (e) {
+    throw new Error(`zip of site dir failed (is the system 'zip' installed?): ${e.message}`);
+  }
+}
+function collectFiles(dir) {
+  const out = [];
+  const walk = (d, base) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const abs = path.join(d, e.name);
+      const rel = base ? `${base}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(abs, rel);
+      else if (e.isFile()) out.push({ rel, abs });
+    }
+  };
+  walk(dir, '');
+  return out;
+}
+async function verify200(url, tries = 12) {
+  for (let i = 0; i < tries; i++) {
+    try { const r = await fetch(url, { redirect: 'follow' }); if (r.status === 200) return true; }
+    catch { /* propagation lag — retry */ }
+    await sleep(3000);
+  }
+  return false;
+}
+
+// ---- adapter: Netlify (DEFAULT) ----
+async function deployNetlify({ pageDir, slug }) {
+  const token = process.env.NETLIFY_AUTH_TOKEN;
+  if (!token) throw new Error('NETLIFY_AUTH_TOKEN not set in environment (deploy-provider token required)');
+  const auth = { Authorization: `Bearer ${token}` };
+  const name = `${sanitize(slug)}-explainer`;
+
+  const sites = await api(`https://api.netlify.com/api/v1/sites?name=${encodeURIComponent(name)}&filter=all`,
+    { headers: auth }, 'netlify list sites');
+  let site = (Array.isArray(sites) ? sites : []).find((s) => s.name === name) || null;
+  if (!site) {
+    site = await api('https://api.netlify.com/api/v1/sites',
+      { method: 'POST', headers: { ...auth, 'Content-Type': 'application/json' }, body: JSON.stringify({ name }) },
+      'netlify create site');
+  }
+  console.error(`[deploy] netlify site '${name}' (id ${site.id})`);
+
+  const zipPath = path.join(os.tmpdir(), `deploy-${name}-${Date.now()}.zip`);
+  zipDir(pageDir, zipPath);
+  const zipBuf = fs.readFileSync(zipPath);
+  const deploy = await api(`https://api.netlify.com/api/v1/sites/${site.id}/deploys`,
+    { method: 'POST', headers: { ...auth, 'Content-Type': 'application/zip' }, body: zipBuf },
+    'netlify deploy');
+  fs.rmSync(zipPath, { force: true });
+
+  for (let i = 0; i < 80; i++) {
+    const d = await api(`https://api.netlify.com/api/v1/sites/${site.id}/deploys/${deploy.id}`,
+      { headers: auth }, 'netlify deploy status');
+    if (d.state === 'ready') { console.error('[deploy] netlify deploy ready'); break; }
+    if (d.state === 'error') throw new Error(`netlify deploy errored: ${d.error_message || 'unknown'}`);
+    if (i === 79) throw new Error('netlify deploy did not reach state=ready within timeout');
+    await sleep(3000);
+  }
+  return { liveUrl: site.ssl_url || `https://${name}.netlify.app`, provider: 'netlify' };
+}
+
+// ---- Vercel adapters DELETED 2026-06-30 (at the owner's instruction) ----
+// A Vercel auto-fallback once deployed a demo into a shared personal-Vercel "site" project and overwrote
+// an unrelated LIVE site (warrior-nation). ALL Vercel deploy code (REST adapter + CLI adapter) was removed.
+// Deploys go to NETLIFY ONLY — each explainer to its OWN {slug}-explainer.netlify.app site. Do NOT
+// reintroduce Vercel or any silent provider fallback; if another provider is ever truly needed, add a
+// new, ISOLATED, opt-in adapter deliberately and review it for the shared-target failure mode.
+const ADAPTERS = { netlify: deployNetlify };
+
+// Netlify is the ONLY target. If its token is missing or invalid we FAIL LOUD with exactly how to refresh
+// it — never a guess, never a different provider, never another account.
+async function resolveProvider() {
+  if (!process.env.NETLIFY_AUTH_TOKEN) {
+    throw new Error('NETLIFY_AUTH_TOKEN is not set. Create a Netlify personal access token at https://app.netlify.com/user/applications#personal-access-tokens and put NETLIFY_AUTH_TOKEN=… in .env, then retry. Deploys go to Netlify only.');
+  }
+  const r = await fetch('https://api.netlify.com/api/v1/user', { headers: { Authorization: `Bearer ${process.env.NETLIFY_AUTH_TOKEN}` } }).catch(() => null);
+  if (!r || !r.ok) throw new Error(`NETLIFY_AUTH_TOKEN is set but not valid (HTTP ${r ? r.status : 'network error'}). Refresh it at https://app.netlify.com/user/applications#personal-access-tokens and update NETLIFY_AUTH_TOKEN in .env. Deploys go to Netlify only — no fallback.`);
+  return 'netlify';
+}
+
+async function main() {
+  if (typeof fetch !== 'function') throw new Error('global fetch unavailable — Node 18+ required');
+  const buildDir = process.argv[2];
+  if (!buildDir) throw new Error('usage: node tools/deploy.mjs <build-dir>');
+
+  const bc = readContext(buildDir);
+  const slug = bc.repo?.slug;
+  const pageDir = path.resolve(bc.page?.dir || '');
+  if (!slug) throw new Error('repo.slug missing in build.json (run clone-repo first)');
+  if (!bc.page?.dir) throw new Error('page.dir missing in build.json (run assemble-page first)');
+  if (!fs.existsSync(path.join(pageDir, 'index.html'))) throw new Error(`page.dir has no index.html: ${pageDir}`);
+
+  const provider = await resolveProvider();
+  const adapter = ADAPTERS[provider];
+  if (!adapter) throw new Error(`unknown DEPLOY_PROVIDER '${provider}' (supported: ${Object.keys(ADAPTERS).join(', ')})`);
+
+  const { liveUrl } = await adapter({ pageDir, slug });
+  console.error(`[deploy] ${provider} → ${liveUrl} (verifying 200 unauthenticated)`);
+  const http200 = await verify200(liveUrl);
+  if (!http200) throw new Error(`deployed to ${liveUrl} but it did not return 200 unauthenticated within timeout`);
+
+  mergeSlot(buildDir, 'publish', { liveUrl, http200: true });
+  return { liveUrl, http200: true, provider, slot: 'publish' };
+}
+
+main()
+  .then((outputs) => { process.stdout.write(JSON.stringify({ ok: true, outputs, error: null }) + '\n'); process.exit(0); })
+  .catch((e) => { process.stdout.write(JSON.stringify({ ok: false, outputs: {}, error: e.message || String(e) }) + '\n'); process.exit(1); });