explainmyrepo 0.1.1

package/kb/make-dropin.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// make-dropin.mjs — build the v1.3.1 single-384 drop-in zip for ONE target.
+//
+// Layout (mirrors the proven #1 metaharness-dropin.zip, single-variant):
+//   for-ai/     <slug>-kb.rvf (+ .idmap.json) + <slug>-kb.passages.jsonl + <slug>-kb.ids.json
+//               + ask-kb.mjs + kb-mcp-server.mjs + kb.config.mjs + resolve-deps.mjs + package.json
+//   for-humans/ <slug>-primer.md  +  studio/{audio + report + prompt}   ← STUDIO IS IN THE ZIP (D13/V)
+//   README.md   manifest.json
+//
+// Usage: node kb/make-dropin.mjs ruvn ../ruv-explainer-ruvn/downloads/ruvn-dropin.zip
+//
+// Self-contained: the studio media (NotebookLM audio overview + report + prompt) is bundled INSIDE
+// the zip's for-humans/studio/ — verify with `unzip -l`. Uses system `zip`.
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const KB_DIR = path.dirname(fileURLToPath(import.meta.url)); // kb/
+const ROOT = path.resolve(KB_DIR, '..');
+
+const slug = process.argv[2];
+const outArg = process.argv[3];
+if (!slug || !outArg) {
+  console.error('usage: node kb/make-dropin.mjs <slug> <out.zip>');
+  process.exit(2);
+}
+const OUT = path.isAbsolute(outArg) ? outArg : path.resolve(process.cwd(), outArg);
+const storeDir = path.join(KB_DIR, 'stores', slug);
+const studioDir = path.join(storeDir, 'studio', 'for-humans');
+
+// Read provenance from kb.config (sha/date) + the gate score we just proved.
+function readLastBuilt() {
+  const p = path.join(KB_DIR, '.last-built.json');
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return {}; }
+}
+
+function must(p) { if (!fs.existsSync(p)) throw new Error(`missing: ${p}`); return p; }
+
+const FOR_AI = [
+  [`${slug}-kb.rvf`, `for-ai/${slug}-kb.rvf`],
+  [`${slug}-kb.rvf.idmap.json`, `for-ai/${slug}-kb.rvf.idmap.json`],
+  [`${slug}-kb.rvf.embed.json`, `for-ai/${slug}-kb.rvf.embed.json`],
+  [`${slug}-kb.passages.jsonl`, `for-ai/${slug}-kb.passages.jsonl`],
+  [`${slug}-kb.ids.json`, `for-ai/${slug}-kb.ids.json`],
+].map(([f, dst]) => [path.join(storeDir, f), dst]);
+
+// Structured enrichment artifacts (AI-comprehension recipe v1.3.2): exact symbol/dep/entrypoint
+// lookups the AI uses alongside semantic search. Generated by kb/extract-symbols|dep-graph|
+// entrypoints.mjs. Shipped if present; a build that skips them still produces a valid drop-in.
+const FOR_AI_STRUCTURED = [
+  [`${slug}-symbols.json`, `for-ai/${slug}-symbols.json`],
+  [`${slug}-dep-graph.json`, `for-ai/${slug}-dep-graph.json`],
+  [`${slug}-entrypoints.json`, `for-ai/${slug}-entrypoints.json`],
+].map(([f, dst]) => [path.join(storeDir, f), dst]).filter(([src]) => fs.existsSync(src));
+
+const FOR_AI_TOOLS = [
+  ['ask-kb.mjs', 'for-ai/ask-kb.mjs'],
+  ['kb-mcp-server.mjs', 'for-ai/kb-mcp-server.mjs'],
+  ['kb.config.mjs', 'for-ai/kb.config.mjs'],
+  ['resolve-deps.mjs', 'for-ai/resolve-deps.mjs'],
+].map(([f, dst]) => [path.join(KB_DIR, f), dst]);
+
+// for-ai/package.json (drop-in runnable)
+const forAiPkg = {
+  name: `${slug}-dropin-kb`,
+  version: '0.1.0',
+  private: true,
+  type: 'module',
+  description: `${slug} drop-in knowledge pack — single 384-dim RVF knowledge base + structured symbol/dep/entrypoint index + MCP server (search_kb · lookup_symbol · get_entrypoints · get_dep_graph). Run \`npm i\` then \`node ask-kb.mjs ${slug} "your question"\` or \`node ask-kb.mjs ${slug} --symbol <name>\`.`,
+  scripts: { ask: `node ask-kb.mjs ${slug}`, mcp: 'node kb-mcp-server.mjs' },
+  dependencies: { '@ruvector/rvf': '^0.2.2', '@xenova/transformers': '^2.17.2' },
+  engines: { node: '>=18' },
+};
+
+// for-humans/ primer + studio (studio MUST be present — D13/V; fail RED otherwise)
+const primerSrc = must(path.join(storeDir, `${slug}-primer.md`));
+// `studio-links.json` is metadata (notebook/video URLs) read below — NOT a file to ship in the zip.
+const studioFiles = fs.existsSync(studioDir)
+  ? fs.readdirSync(studioDir)
+      .filter((f) => !f.startsWith('.') && f !== 'studio-links.json')
+      .map((f) => [path.join(studioDir, f), `for-humans/studio/${f}`])
+  : [];
+const hasAudio = studioFiles.some(([, d]) => /\.(m4a|mp3|wav)$/i.test(d));
+const hasReport = studioFiles.some(([, d]) => /report\.md$/i.test(d));
+if (!studioFiles.length || !hasAudio || !hasReport) {
+  throw new Error(`STUDIO-IN-ZIP guard (D13/V): for-humans/studio must contain the audio overview AND report. ` +
+    `Found under ${studioDir}: ${studioFiles.map(([, d]) => path.basename(d)).join(', ') || '(none)'}. ` +
+    `Refusing to build a studio-less drop-in.`);
+}
+
+// Optional EXTRA studio artifacts that ride in the zip (infographic PNG, slide-deck PDF/PPTX).
+const infographicFile = studioFiles.find(([, d]) => /infographic.*\.png$/i.test(d));
+const slidesFile = studioFiles.find(([, d]) => /slides?.*\.(pdf|pptx)$/i.test(d));
+const infographicName = infographicFile ? path.basename(infographicFile[1]) : null;
+const slidesName = slidesFile ? path.basename(slidesFile[1]) : null;
+
+// Optional links to the (large) video + the public NotebookLM notebook, kept OUT of the zip to stay light.
+// Read from studio/for-humans/studio-links.json: { "notebookUrl": "...", "videoUrl": "...", "videoNote": "..." }
+let studioLinks = {};
+try { studioLinks = JSON.parse(fs.readFileSync(path.join(studioDir, 'studio-links.json'), 'utf8')); } catch { /* optional */ }
+
+const lb = readLastBuilt();
+const manifest = {
+  name: `${slug}-dropin`,
+  version: lb.version || 'v0.1.1',
+  builtAt: lb.builtAt || new Date().toISOString().slice(0, 10),
+  sha: lb.targetRepoSha || lb.sha || null,
+  embedder: 'Xenova/bge-small-en-v1.5 (384-dim, single variant, recipe v1.3.1)',
+  gateA: lb.gateA || { passed: true },
+  contents: {
+    'for-ai': [...FOR_AI, ...FOR_AI_STRUCTURED, ...FOR_AI_TOOLS].map(([, d]) => d.replace('for-ai/', '')).concat(['package.json']),
+    'for-humans': [`${slug}-primer.md`, ...studioFiles.map(([, d]) => d.replace('for-humans/', ''))],
+  },
+  structured: {
+    symbols: FOR_AI_STRUCTURED.some(([, d]) => d.endsWith('-symbols.json')) ? `${slug}-symbols.json` : null,
+    depGraph: FOR_AI_STRUCTURED.some(([, d]) => d.endsWith('-dep-graph.json')) ? `${slug}-dep-graph.json` : null,
+    entrypoints: FOR_AI_STRUCTURED.some(([, d]) => d.endsWith('-entrypoints.json')) ? `${slug}-entrypoints.json` : null,
+    note: 'Exact symbol/dependency/entrypoint lookups (AI-comprehension recipe). Use alongside ask-kb semantic search.',
+  },
+  studio: {
+    audio: studioFiles.find(([, d]) => /\.(m4a|mp3|wav)$/i.test(d))?.[1] || null,
+    report: studioFiles.find(([, d]) => /report\.md$/i.test(d))?.[1] || null,
+    prompt: studioFiles.find(([, d]) => /prompt\.md$/i.test(d))?.[1] || null,
+    infographic: infographicFile?.[1] || null,
+    slides: slidesFile?.[1] || null,
+    notebookUrl: studioLinks.notebookUrl || null,
+    videoUrl: studioLinks.videoUrl || null,
+    note: 'NotebookLM media pack — play the audio first, then skim the report; infographic + slides ride inside; the video + live notebook are linked (see README).',
+  },
+  description: `${slug} drop-in knowledge pack. Unzip, npm i in for-ai/, point .mcp.json at kb-mcp-server.mjs, add CLAUDE.md gate. The for-humans/studio/ media (audio, report, infographic, slides) ride inside this zip; the video + public notebook are linked from the README. See README.md.`,
+};
+
+const audioName = path.basename(manifest.studio.audio || `${slug}-audio-overview.m4a`);
+const reportName = path.basename(manifest.studio.report || `${slug}-report.md`);
+
+const extraTreeLines = [
+  infographicName ? `      🖼 ${infographicName}  — the whole story on one sheet (NotebookLM infographic)` : null,
+  slidesName ? `      📊 ${slidesName}  — a detailed slide deck you can flip through` : null,
+].filter(Boolean).join('\n');
+
+const linkLines = [
+  studioLinks.notebookUrl ? `- **Open the full NotebookLM studio (public):** ${studioLinks.notebookUrl}` : null,
+  studioLinks.videoUrl
+    ? `- **Watch the video overview:** ${studioLinks.videoUrl}${studioLinks.videoNote ? ` — ${studioLinks.videoNote}` : ''}`
+    : null,
+].filter(Boolean).join('\n');
+
+const readme = `# ${slug} Drop-in
+
+One zip. Two halves. The NotebookLM studio media rides **inside** this zip.
+
+## What's inside
+
+\`\`\`
+${slug}-dropin/
+  for-humans/   — read & listen first
+    ${slug}-primer.md
+    studio/
+      🎧 ${audioName}   — NotebookLM AUDIO OVERVIEW (play this first)
+      📄 ${reportName}  — the written deep-dive briefing
+${extraTreeLines ? extraTreeLines + '\n' : ''}      audio-overview-prompt.md  — the prompt that generated the audio
+  for-ai/       — the searchable knowledge pack (wire this into your agent)
+    ${slug}-kb.rvf            — single 384-dim bge-small vector DB (the "brain")
+    ${slug}-kb.passages.jsonl — full passage text (tagged source_type: src|test|example|doc|config)
+    ${slug}-kb.ids.json       — id → passage index
+    ${slug}-symbols.json      — exact public API: every symbol + signature + doc + location
+    ${slug}-dep-graph.json    — component dependency graph (what depends on what)
+    ${slug}-entrypoints.json  — build/test/run/install commands + binaries
+    ask-kb.mjs · kb-mcp-server.mjs · kb.config.mjs · resolve-deps.mjs · package.json
+  README.md     — this file
+  manifest.json — build metadata + Gate A score
+\`\`\`
+
+## Studio (NotebookLM)
+Start with the audio: play \`for-humans/studio/${audioName}\` — a friendly two-host overview of ${slug}.
+Prefer reading? Open \`for-humans/studio/${reportName}\`.${infographicName ? `
+Want it on one sheet? Open \`for-humans/studio/${infographicName}\`.` : ''}${slidesName ? `
+Prefer slides? Open \`for-humans/studio/${slidesName}\`.` : ''}
+${linkLines ? `
+The full media pack also includes a **video overview**, linked below to keep this download light:
+
+${linkLines}
+` : ''}
+
+## Three steps to wire the AI half in
+\`\`\`bash
+# 1 — unzip + install (two deps, Node 18+)
+unzip ${slug}-dropin.zip && cd ${slug}-dropin/for-ai && npm install
+
+# 2 — ask the brain a question straight away
+node ask-kb.mjs ${slug} "what does ${slug} actually do"
+
+# 3 — point your AI host at it with a .mcp.json in your project root:
+#   { "mcpServers": { "${slug}-kb": { "command": "node", "args": ["for-ai/kb-mcp-server.mjs"] } } }
+\`\`\`
+
+Built with the Repo-Primer recipe (ADR-0001 v1.3.1). Embedder: ${manifest.embedder}.
+Source: github.com/ruvnet/${slug} @ ${manifest.sha || '(see manifest)'}.
+`;
+
+// ---- stage + zip ----
+const stage = fs.mkdtempSync(path.join(os.tmpdir(), `dropin-${slug}-`));
+function copy(src, dst) {
+  const d = path.join(stage, dst);
+  fs.mkdirSync(path.dirname(d), { recursive: true });
+  fs.copyFileSync(src, d);
+}
+for (const [src, dst] of [...FOR_AI, ...FOR_AI_STRUCTURED, ...FOR_AI_TOOLS]) copy(must(src), dst);
+copy(primerSrc, `for-humans/${slug}-primer.md`);
+for (const [src, dst] of studioFiles) copy(src, dst);
+fs.writeFileSync(path.join(stage, 'for-ai/package.json'), JSON.stringify(forAiPkg, null, 2) + '\n');
+fs.writeFileSync(path.join(stage, 'README.md'), readme);
+fs.writeFileSync(path.join(stage, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+fs.mkdirSync(path.dirname(OUT), { recursive: true });
+fs.rmSync(OUT, { force: true });
+execFileSync('zip', ['-r', '-X', OUT, '.'], { cwd: stage, stdio: 'inherit' });
+fs.rmSync(stage, { recursive: true, force: true });
+const size = fs.statSync(OUT).size;
+console.log(`\nbuilt ${path.relative(ROOT, OUT)} (${(size / 1e6).toFixed(1)} MB)`);
+console.log(`studio in zip: 🎧 ${audioName}  📄 ${reportName}`);

package/kb/resolve-deps.mjs

@@ -0,0 +1,126 @@
+// resolve-deps.mjs — portable resolver for the Cognitum KB scripts.
+//
+// Resolves the two runtime deps the KB needs in a machine-independent order:
+//
+//   @ruvector/rvf        -> RvfDatabase (the .rvf vector store)
+//   @xenova/transformers -> the MiniLM embedder
+//
+// Resolution order (first hit wins) for EACH dep:
+//   1. The project's own node_modules (so `cd kb && npm i` or a root install just works).
+//   2. An explicit env override   (RVF_MODULE_PATH / XENOVA_PATH).
+//   3. The author's Mac npm-global / AppealArmor paths (LAST resort, so local dev still runs).
+//
+// This file ships INSIDE the zips, so it must not assume anything beyond Node 18+ and the
+// two npm deps being installable via `npm i @ruvector/rvf @xenova/transformers`.
+
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const KB_DIR = path.dirname(__filename);
+
+// require() rooted at THIS file — node walks up node_modules from kb/ to the project root,
+// so it finds deps installed either in kb/node_modules or the project root node_modules.
+const localRequire = createRequire(__filename);
+
+// @ruvector/rvf and @xenova/transformers are declared dependencies, so they resolve from
+// node_modules (step 1) on any machine after `npm install`. The env overrides remain for
+// non-standard layouts. (No machine-specific fallback paths — those don't belong in a
+// published package.)
+
+function existsModuleDir(p) {
+  // p may be a package root dir OR a file path; treat presence as resolvable.
+  try { return fs.existsSync(p); } catch { return false; }
+}
+
+/**
+ * Resolve and return the @ruvector/rvf module ({ RvfDatabase, ... }).
+ * Order: project node_modules -> RVF_MODULE_PATH env -> Mac npm-global.
+ */
+export function loadRvf() {
+  // 1. project node_modules (kb/ or root)
+  try {
+    return { mod: localRequire('@ruvector/rvf'), via: 'project node_modules' };
+  } catch { /* fall through */ }
+
+  // 2. explicit env override (dir of the package, or a path createRequire can resolve from)
+  const envPath = process.env.RVF_MODULE_PATH;
+  if (envPath && existsModuleDir(envPath)) {
+    // If env points at a node_modules root, require @ruvector/rvf from there; else require it directly.
+    const base = envPath.endsWith('@ruvector/rvf') || envPath.endsWith('@ruvector/rvf/')
+      ? envPath
+      : path.join(envPath, '@ruvector/rvf');
+    try {
+      const req = createRequire(path.join(envPath, 'noop.js'));
+      return { mod: req('@ruvector/rvf'), via: `RVF_MODULE_PATH (${envPath})` };
+    } catch {
+      try { return { mod: localRequire(base), via: `RVF_MODULE_PATH dir (${base})` }; } catch { /* fall through */ }
+    }
+  }
+
+  throw new Error(
+    "Cannot resolve '@ruvector/rvf'. Run `npm i` (it is a declared dependency), "
+    + 'or set RVF_MODULE_PATH to a node_modules dir that contains it.'
+  );
+}
+
+/**
+ * Resolve and dynamically import @xenova/transformers.
+ * Order: project node_modules -> XENOVA_PATH env -> Mac AppealArmor build.
+ * Returns { T, modelCache, via } where T is the imported module namespace.
+ */
+export async function loadTransformers() {
+  // 1. project node_modules — resolve the package entry, import via file:// URL.
+  try {
+    const resolved = localRequire.resolve('@xenova/transformers');
+    const T = await import('file://' + resolved);
+    return { T, modelCache: chooseModelCache(), via: 'project node_modules' };
+  } catch { /* fall through */ }
+
+  // 2. explicit env override — may be a transformers.js file path or a package dir.
+  const envPath = process.env.XENOVA_PATH;
+  if (envPath) {
+    const url = envPath.startsWith('file://') ? envPath
+      : envPath.endsWith('.js') ? 'file://' + path.resolve(envPath)
+      : 'file://' + path.join(path.resolve(envPath), 'src/transformers.js');
+    try {
+      const T = await import(url);
+      return { T, modelCache: chooseModelCache(), via: `XENOVA_PATH (${envPath})` };
+    } catch { /* fall through */ }
+  }
+
+  throw new Error(
+    "Cannot resolve '@xenova/transformers'. Run `npm i` (it is a declared dependency), "
+    + 'or set XENOVA_PATH to the transformers package dir / src/transformers.js.'
+  );
+}
+
+/**
+ * Pick a model cache directory. KB_MODEL_CACHE wins; otherwise a kb-local `models-cache`
+ * if it already has the model; otherwise the Mac cache if present; otherwise a kb-local
+ * dir (created lazily) into which a remote download will be cached.
+ * `modelName` lets the big (bge) variant resolve its cache by its own model, not just MiniLM;
+ * defaults to MiniLM-384 so existing small-build callers are unchanged.
+ */
+export function chooseModelCache(modelName = 'Xenova/all-MiniLM-L6-v2') {
+  if (process.env.KB_MODEL_CACHE) return process.env.KB_MODEL_CACHE;
+  const kbLocal = path.join(KB_DIR, 'models-cache');
+  if (fs.existsSync(path.join(kbLocal, modelName))) return kbLocal;
+  return kbLocal; // remote download lands here on first run
+}
+
+/**
+ * Configure a transformers namespace `T` for a given model: point at the cache, and allow
+ * remote download ONLY when THAT model isn't already cached (offline-first).
+ * `modelName` defaults to the MiniLM-384 embedder so existing callers keep working; the big
+ * variant passes `'Xenova/bge-base-en-v1.5'` so its own cache check is correct.
+ * Returns { modelCache, haveLocalModel }.
+ */
+export function configureModel(T, modelCache, modelName = 'Xenova/all-MiniLM-L6-v2') {
+  const haveLocalModel = fs.existsSync(path.join(modelCache, modelName));
+  T.env.localModelPath = modelCache;
+  T.env.allowRemoteModels = !haveLocalModel; // fresh machine -> download from HuggingFace
+  return { modelCache, haveLocalModel };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "explainmyrepo",
+  "version": "0.1.1",
+  "description": "Turn any GitHub repo into a bespoke, art-directed explainer site — for humans and their AI — in one command.",
+  "type": "module",
+  "bin": {
+    "explainmyrepo": "bin/explainmyrepo.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "tools/",
+    "kb/*.mjs",
+    "kb/CONTRACT.md",
+    "assets/"
+  ],
+  "keywords": [
+    "explainer",
+    "documentation",
+    "github",
+    "repo",
+    "ai",
+    "knowledge-base",
+    "static-site",
+    "npx"
+  ],
+  "homepage": "https://github.com/stuinfla/Repo-Explainer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stuinfla/Repo-Explainer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stuinfla/Repo-Explainer/issues"
+  },
+  "author": "ISOvision",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ruvector/rvf": "^0.2.2",
+    "@xenova/transformers": "^2.17.2",
+    "playwright": "^1.61.1"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "start": "node bin/explainmyrepo.mjs"
+  }
+}