explainmyrepo 0.1.1 → 0.1.3

package/bin/explainmyrepo.mjs

@@ -39,6 +39,9 @@ OPTIONS
   --no-quality           skip the local vision quality gate (faster dry iterations)
   --no-refine            grade once but don't auto-iterate the copy to lift weak axes
   --max-refine <n>       max content-refine passes when below the quality bar (default 2)
+  --ship-best-effort     always deploy the best version (with an honest scorecard) instead of
+                         holding when the world-class bar isn't reached — guarantees a URL.
+                         Only truly broken pages (missing/broken diagrams) still hold.
   --register-kb          OPT-IN: if the repo isn't a kb.config target, inject a generated
                          entry into kb/kb.config.mjs (the one step that edits the shared registry)
   --from <station>       resume: start at this station id (needs an existing --out build)
@@ -65,7 +68,7 @@ EXAMPLES
   npx explainmyrepo owner/cool-lib --from concept --out ./explainer-builds/cool-lib
 `;
 
-const BOOL_FLAGS = new Set(['--no-deploy', '--no-publish', '--no-notify', '--no-quality', '--no-refine', '--register-kb', '--dry-run', '-h', '--help', '-v', '--version']);
+const BOOL_FLAGS = new Set(['--no-deploy', '--no-publish', '--no-notify', '--no-quality', '--no-refine', '--ship-best-effort', '--register-kb', '--dry-run', '-h', '--help', '-v', '--version']);
 const VALUE_FLAGS = new Set(['--out', '--model', '--from', '--to', '--only', '--max-refine']);
 
 function parseArgs(argv) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainmyrepo",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Turn any GitHub repo into a bespoke, art-directed explainer site — for humans and their AI — in one command.",
   "type": "module",
   "bin": {

package/src/orchestrator.mjs

@@ -85,14 +85,10 @@ async function kbRegisterStation({ buildDir, env, model, apiKey, opts }) {
   fs.writeFileSync(genPath, `// GENERATED kb.config target entry for "${slug}" — paste into kb/kb.config.mjs targets{}.\nexport default ${JSON.stringify({ [slug]: entry }, null, 2)};\n`);
   log(`${C.dim}wrote generated entry → ${path.relative(process.cwd(), genPath)}${C.reset}`);
 
-  if (!opts.registerKb) {
-    throw new Error(
-      `kb:register — "${slug}" must be a registered kb.config target before build-kb can index it.\n` +
-      `  • A generated entry was written to ${genPath}.\n` +
-      `  • Re-run with --register-kb to inject it into kb/kb.config.mjs automatically (the one step that edits the shared registry), or paste it in by hand.`,
-    );
-  }
-  // --register-kb (opt-in, CLEARLY the single step that mutates kb/kb.config.mjs) ----------------
+  // Auto-register (no flag needed) so ANY repo just works. Inject the AI-authored entry into THIS
+  // build's kb.config copy. In real use that copy is ephemeral — a fresh CI checkout on the hosted
+  // path, or the throwaway npx install locally — so this never mutates a shared/committed registry.
+  // (--register-kb is now a no-op alias, kept for backward compatibility.)
   let src = fs.readFileSync(cfgPath, 'utf8');
   const anchor = 'export const targets = {';
   const at = src.indexOf(anchor);
@@ -100,7 +96,7 @@ async function kbRegisterStation({ buildDir, env, model, apiKey, opts }) {
   const inject = `\n  ${JSON.stringify(slug)}: ${JSON.stringify(entry, null, 2).replace(/\n/g, '\n  ')},`;
   src = src.slice(0, at + anchor.length) + inject + src.slice(at + anchor.length);
   fs.writeFileSync(cfgPath, src);
-  log(`${C.yellow}injected "${slug}" into kb/kb.config.mjs (--register-kb).${C.reset}`);
+  log(`${C.yellow}auto-registered "${slug}" into this build's kb.config.${C.reset}`);
   const m2 = await importCfg();
   try { m2.getTarget(slug); } catch (e) { throw new Error(`kb:register — injection did not take: ${e.message}`); }
   return { ok: true, registered: true };
@@ -399,19 +395,28 @@ export async function run(repoUrl, opts = {}) {
   }
 
   if (!(quality && quality.passed)) {
-    // NEVER ship a below-bar page silently — the whole point. Stop before deploy/publish, report the gap.
+    // Below the world-class bar. DEFAULT: hold — never ship slop (the whole point). With
+    // --ship-best-effort: deliver the best version anyway so a stranger ALWAYS gets a URL, with the
+    // honest scorecard travelling alongside — UNLESS it's genuinely broken (no device rendered the
+    // mandatory diagrams), which always holds.
     reportQualityGap(quality);
-    log(`\n${C.yellow}${C.bold}Held at the quality gate — did NOT deploy or publish a below-bar page.${C.reset}`);
-    log(`${C.dim}Best local build: ${outDir}/site . Lift the gaps above (or re-run with a higher --max-refine), then ship the remaining steps with: ${C.cyan}--from ${post[0] ? post[0].id : 'deploy'} --out ${outDir}${C.reset}`);
-    return { ok: false, gated: true, quality, outDir, results: preR.results };
-  }
-
-  const meanPair = quality.scorecard.map((c) => `${String(c.device).replace(/\(.*/, '')} ${c.meanScore}`).join(' / ');
-  if (quality.exemplary) {
-    log(`\n${C.green}${C.bold}Quality gate PASSED — world-class (mean ${meanPair}).${C.reset} Shipping.`);
+    const diagramsOk = !!(quality && Array.isArray(quality.scorecard) && quality.scorecard.some((c) => c.inv18?.passed));
+    if (!(opts.shipBestEffort && diagramsOk)) {
+      log(`\n${C.yellow}${C.bold}Held at the quality gate — did NOT deploy or publish a below-bar page.${C.reset}`);
+      log(`${C.dim}Best local build: ${outDir}/site . ${opts.shipBestEffort ? 'Held because the mandatory diagrams did not render — the one thing we will not ship broken. ' : ''}Lift the gaps above (or re-run with a higher --max-refine), then ship with: ${C.cyan}--from ${post[0] ? post[0].id : 'deploy'} --out ${outDir}${C.reset}`);
+      return { ok: false, gated: true, quality, outDir, results: preR.results };
+    }
+    const meanBE = quality.scorecard.map((c) => `${String(c.device).replace(/\(.*/, '')} ${c.meanScore}`).join(' / ');
+    log(`\n${C.yellow}${C.bold}Below the world-class bar (mean ${meanBE}) — shipping the best version (--ship-best-effort).${C.reset}`);
+    log(`${C.dim}Structurally sound (mandatory diagrams present). The per-axis gaps above are recorded in the scorecard and delivered honestly, not hidden. A stranger always gets a real page.${C.reset}`);
   } else {
-    log(`\n${C.green}${C.bold}Quality gate PASSED — ship-worthy (mean ${meanPair}).${C.reset} Shipping.`);
-    log(`${C.dim}Genuinely good + no slop + real legible diagrams (INV-18). The world-class target (mean ≥ 90 / worst axis ≥ 85 / all 5 operators) is not fully reached — the per-axis gap is recorded in build.json refineNotes and travels with the scorecard.${C.reset}`);
+    const meanPair = quality.scorecard.map((c) => `${String(c.device).replace(/\(.*/, '')} ${c.meanScore}`).join(' / ');
+    if (quality.exemplary) {
+      log(`\n${C.green}${C.bold}Quality gate PASSED — world-class (mean ${meanPair}).${C.reset} Shipping.`);
+    } else {
+      log(`\n${C.green}${C.bold}Quality gate PASSED — ship-worthy (mean ${meanPair}).${C.reset} Shipping.`);
+      log(`${C.dim}Genuinely good + no slop + real legible diagrams (INV-18). The world-class target (mean ≥ 90 / worst axis ≥ 85 / all 5 operators) is not fully reached — the per-axis gap is recorded in build.json refineNotes and travels with the scorecard.${C.reset}`);
+    }
   }
   const postR = post.length ? await runStations(post, baseArgs, total, qIdx + 1) : { ok: true, results: [] };
   finalSummary(outDir);

package/tools/quality-grade.mjs

@@ -348,6 +348,27 @@ async function scrollToTop(page, loc, offset) {
 // capture the grading crops — viewport-segment section crops + dedicated element
 // crops of the two mandatory diagrams. Returns { domInv18, fullPagePath, crops[], pageHeight }.
 // ----------------------------------------------------------------------------
+// Ensure the Chromium browser binary exists. The `playwright` npm package installs fine, but the
+// actual ~150MB browser is downloaded separately — a fresh machine (or `npx explainmyrepo`) won't
+// have it. Install it once, automatically, so the quality gate "just works" for a stranger.
+async function ensureChromium(chromium) {
+  let exePath = null;
+  try { exePath = chromium.executablePath(); } catch { /* path unknown */ }
+  if (exePath && fs.existsSync(exePath)) return; // already installed (respects PLAYWRIGHT_BROWSERS_PATH)
+  console.error('[quality-grade] Chromium browser not found — installing it once (~150MB, one-time)…');
+  const { execFileSync } = await import('node:child_process');
+  const { createRequire } = await import('node:module');
+  const require2 = createRequire(import.meta.url);
+  // playwright's `exports` blocks require.resolve('playwright/cli.js'), so find the package root
+  // (package.json is exported) and reach cli.js — the file that backs the `playwright` bin — directly.
+  let pwRoot;
+  try { pwRoot = path.dirname(require2.resolve('playwright/package.json')); }
+  catch { pwRoot = path.dirname(require2.resolve('playwright')); }
+  const pwCli = path.join(pwRoot, 'cli.js');
+  execFileSync(process.execPath, [pwCli, 'install', 'chromium'], { stdio: 'inherit', env: process.env });
+  console.error('[quality-grade] Chromium installed.');
+}
+
 async function renderDevice(chromium, url, device, assetsDir) {
   const browser = await chromium.launch({ headless: true });
   try {
@@ -660,6 +681,9 @@ async function main() {
   let chromium;
   try { ({ chromium } = await import('playwright')); }
   catch (e) { return emit(false, {}, `playwright is not installed (npm i -D playwright && npx playwright install chromium): ${e?.message || e}`); }
+  // Fresh machines have the package but not the browser binary — install it once, automatically.
+  try { await ensureChromium(chromium); }
+  catch (e) { return emit(false, {}, `could not auto-install the Chromium browser (try 'npx playwright install chromium' manually): ${e?.message || e}`); }
 
   const assetsDir = path.join(buildDir, 'assets');
   fs.mkdirSync(assetsDir, { recursive: true });