explainmyrepo 0.1.1

package/tools/readme-enhance.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+// readme-enhance.mjs — Station 8b, tool #13 of tools/CONTRACT.md (OPTIONAL, off the critical path).
+//
+// JOB (one mechanical thing): OFFER to enhance the SOURCE repo's README — add an architectural
+// explanation + the SHARED Station-4 SVG diagrams (architecture + flow, authored once, reused here)
+// + an explainer badge linking to the live explainer — and deliver it as a PULL REQUEST ONLY on the
+// source repo. NEVER a direct push, NEVER a push to the default branch (INV-16). This wraps the
+// `~/.claude/skills/readme-enhance` conventions (version-headerless, surgical, validate-against-repo)
+// and the `gh` CLI mechanically; it makes no judgment calls.
+//
+// OPTIONAL / OFFERED. The offer is controlled by the brain via the environment: this tool only opens
+// a PR when README_ENHANCE is truthy (1/true/yes/on). Unset/false ⇒ a clean no-op that records
+// readmePr = { prUrl: "declined", svgsShared: [] } and exits 0. (Station 8b cue: "if declined, the
+// station is a clean no-op.")
+//
+// FAIL-LOUD: when ENABLED and a declared input or a git/gh step genuinely fails, this tool exits
+// NON-ZERO with a clear reason (per CONTRACT (b)·6) — it never writes a placeholder PR. Per ADR-0005
+// Station 8b / INV-03 / INV-16 the BRAIN treats that non-zero as a NON-BLOCKING WARNING: a
+// readme-enhance failure is a warning, it never blocks, gates, or sinks the core ship.
+//
+// Uniform invocation:  node tools/readme-enhance.mjs <build-dir>
+//
+// Reads (declared inputs only — CONTRACT roster row 13):
+//   build.json: repo { owner, name, slug, clonePath, defaultBranch, url },
+//               publish.liveUrl,
+//               visuals.architectureDiagram { svgPath, altText },
+//               visuals.flowDiagram         { svgPath, altText }
+//   env:        README_ENHANCE (opt-in), GitHub token via the ambient `gh` auth / GH_TOKEN.
+// Writes (its own slot + the PR, nothing else):
+//   build.json: readmePr { prUrl | "declined", svgsShared[] }
+//   the source clone at <build-dir>/repo: docs/explainer/{architecture,flow}.svg + a README block,
+//   on a feature branch, pushed (to origin if writable, else a fork) and opened as a PR via gh.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const TOOL = 'readme-enhance';
+const BRANCH = 'explainer/readme-enhancement';
+const SVG_DIR = 'docs/explainer';
+const MARK_START = '<!-- explainmyrepo:start -->';
+const MARK_END = '<!-- explainmyrepo:end -->';
+const TRUE_RE = /^(1|true|yes|on)$/i;
+
+// stdout carries ONLY the single JSON result object; all diagnostics go to stderr.
+function emit(result) {
+  process.stdout.write(JSON.stringify(result) + '\n');
+}
+function log(msg) {
+  process.stderr.write(`[${TOOL}] ${msg}\n`);
+}
+function fail(message) {
+  log(message);
+  emit({ ok: false, outputs: {}, error: message });
+  process.exit(1);
+}
+
+// Run a command, capture stdout (trimmed). Throw on non-zero with stderr surfaced.
+function run(cmd, args, opts = {}) {
+  try {
+    return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts }).trim();
+  } catch (err) {
+    const stderr = (err.stderr || '').toString().trim();
+    const e = new Error(`${cmd} ${args.join(' ')} failed: ${stderr || err.message}`);
+    e.stderr = stderr;
+    throw e;
+  }
+}
+
+// Resolve a path token (absolute or relative to the build dir) into an absolute path.
+function resolveIn(buildDir, p) {
+  return path.isAbsolute(p) ? p : path.resolve(buildDir, p);
+}
+
+const buildDir = process.argv[2];
+if (!buildDir) fail('usage: node tools/readme-enhance.mjs <build-dir>');
+
+const buildJsonPath = path.join(buildDir, 'build.json');
+let ctx;
+try {
+  ctx = JSON.parse(fs.readFileSync(buildJsonPath, 'utf8'));
+} catch (err) {
+  fail(`cannot read ${buildJsonPath}: ${err.message}`);
+}
+
+// ── OPTIONAL gate: only act when the brain opted in via the environment ──────────────────────────
+const enabled = TRUE_RE.test(String(process.env.README_ENHANCE || '').trim());
+if (!enabled) {
+  ctx.readmePr = { prUrl: 'declined', svgsShared: [] };
+  fs.writeFileSync(buildJsonPath, JSON.stringify(ctx, null, 2) + '\n');
+  log('README_ENHANCE not set — clean no-op (declined).');
+  emit({ ok: true, outputs: { readmePr: ctx.readmePr, declined: true }, error: null });
+  process.exit(0);
+}
+
+// ── ENABLED: validate the declared inputs (loud on any absence) ──────────────────────────────────
+const repo = ctx.repo;
+if (!repo || !repo.owner || !repo.name || !repo.clonePath) {
+  fail('repo slot incomplete — need repo.owner, repo.name, repo.clonePath (run clone-repo first).');
+}
+const liveUrl = ctx.publish?.liveUrl;
+if (!liveUrl) fail('publish.liveUrl is absent — run deploy (Station 8) before the README PR.');
+
+const arch = ctx.visuals?.architectureDiagram;
+const flow = ctx.visuals?.flowDiagram;
+if (!arch?.svgPath) fail('visuals.architectureDiagram.svgPath is absent — run make-diagrams (Station 4) first.');
+if (!flow?.svgPath) fail('visuals.flowDiagram.svgPath is absent — run make-diagrams (Station 4) first.');
+
+const archSvg = resolveIn(buildDir, arch.svgPath);
+const flowSvg = resolveIn(buildDir, flow.svgPath);
+if (!fs.existsSync(archSvg)) fail(`shared architecture SVG not found on disk: ${archSvg}`);
+if (!fs.existsSync(flowSvg)) fail(`shared flow SVG not found on disk: ${flowSvg}`);
+
+const clone = resolveIn(buildDir, repo.clonePath);
+if (!fs.existsSync(clone)) fail(`source clone not found: ${clone} (run clone-repo first).`);
+try {
+  run('git', ['-C', clone, 'rev-parse', '--is-inside-work-tree']);
+} catch {
+  fail(`not a git work tree: ${clone}`);
+}
+
+const baseBranch =
+  repo.defaultBranch ||
+  (() => {
+    try {
+      return run('git', ['-C', clone, 'symbolic-ref', '--short', 'HEAD']);
+    } catch {
+      return 'main';
+    }
+  })();
+
+// ── Build the surgical README enhancement (badge + shared SVGs + architectural explanation) ───────
+const repoName = repo.name;
+const archAlt = (arch.altText || `Architecture diagram for ${repoName}.`).trim();
+const flowAlt = (flow.altText || `Process / data-flow diagram for ${repoName}.`).trim();
+const archRel = `${SVG_DIR}/architecture.svg`;
+const flowRel = `${SVG_DIR}/flow.svg`;
+
+const block = [
+  MARK_START,
+  '## Explainer',
+  '',
+  `[![Explainer — live](https://img.shields.io/badge/Explainer-live-7c3aed?style=flat-square)](${liveUrl})`,
+  '',
+  `A visual, newcomer-friendly explainer for **${repoName}** is live: ${liveUrl}`,
+  '',
+  '### Architecture',
+  '',
+  archAlt,
+  '',
+  `![${archAlt.replace(/[\r\n]+/g, ' ')}](${archRel})`,
+  '',
+  '### How it works',
+  '',
+  flowAlt,
+  '',
+  `![${flowAlt.replace(/[\r\n]+/g, ' ')}](${flowRel})`,
+  MARK_END,
+  '',
+].join('\n');
+
+// Pick the existing README (case-insensitive) or default to README.md.
+function findReadme(dir) {
+  const hit = fs.readdirSync(dir).find((f) => /^readme(\.md|\.markdown)?$/i.test(f));
+  return hit || 'README.md';
+}
+const readmeName = findReadme(clone);
+const readmePath = path.join(clone, readmeName);
+
+// ALWAYS read before editing. Insert-or-replace our delimited block (idempotent on re-run).
+let readme = '';
+if (fs.existsSync(readmePath)) {
+  readme = fs.readFileSync(readmePath, 'utf8');
+}
+let nextReadme;
+if (readme.includes(MARK_START) && readme.includes(MARK_END)) {
+  nextReadme = readme.replace(new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}\\n?`), block);
+} else if (readme.trim().length === 0) {
+  nextReadme = `# ${repoName}\n\n${block}`;
+} else {
+  nextReadme = `${readme.replace(/\s*$/, '')}\n\n${block}`;
+}
+
+// ── Stage the change on a feature branch in the clone (NEVER the default branch) ──────────────────
+let prUrl;
+try {
+  run('git', ['-C', clone, 'checkout', '-B', BRANCH]);
+
+  const svgAbsDir = path.join(clone, SVG_DIR);
+  fs.mkdirSync(svgAbsDir, { recursive: true });
+  fs.copyFileSync(archSvg, path.join(svgAbsDir, 'architecture.svg'));
+  fs.copyFileSync(flowSvg, path.join(svgAbsDir, 'flow.svg'));
+  fs.writeFileSync(readmePath, nextReadme);
+
+  run('git', ['-C', clone, 'add', '--', readmeName, SVG_DIR]);
+
+  // Commit with an explicit identity (the clone may carry none). No Co-Authored-By trailer.
+  try {
+    run('git', [
+      '-C', clone,
+      '-c', 'user.name=explainmyrepo',
+      '-c', 'user.email=explainmyrepo@users.noreply.github.com',
+      'commit', '-m', 'docs: add explainmyrepo architecture explainer + shared diagrams',
+    ]);
+  } catch (err) {
+    if (!/nothing to commit/i.test(err.stderr || err.message)) throw err;
+    log('no README changes to commit (already enhanced) — proceeding to PR.');
+  }
+} catch (err) {
+  fail(`failed to stage the README enhancement: ${err.message}`);
+}
+
+// ── Push (origin if writable, else a fork) and open the PR via gh — never a direct push to base ──
+let headRef = BRANCH; // owner:branch form filled in for the fork path
+try {
+  // Idempotency: if a PR already exists for this head, reuse it.
+  const existing = run('gh', [
+    'pr', 'list', '--repo', `${repo.owner}/${repo.name}`,
+    '--head', BRANCH, '--state', 'open', '--json', 'url', '--jq', '.[0].url // ""',
+  ]);
+  if (existing) {
+    log(`a PR already exists for ${BRANCH} — reusing it.`);
+    prUrl = existing;
+  }
+} catch {
+  /* gh pr list is best-effort detection; fall through to create */
+}
+
+if (!prUrl) {
+  let pushedToOrigin = false;
+  try {
+    run('git', ['-C', clone, 'push', '--force-with-lease', '-u', 'origin', BRANCH]);
+    pushedToOrigin = true;
+  } catch (err) {
+    log(`push to origin failed (likely no write access): ${err.stderr || err.message} — trying a fork.`);
+  }
+
+  if (!pushedToOrigin) {
+    // Fork under our account, push the branch there, open a cross-repo PR.
+    let login;
+    try {
+      run('gh', ['repo', 'fork', `${repo.owner}/${repo.name}`, '--clone=false']);
+      login = run('gh', ['api', 'user', '--jq', '.login']);
+    } catch (err) {
+      fail(`could not fork ${repo.owner}/${repo.name} for the PR: ${err.message}`);
+    }
+    try {
+      run('git', ['-C', clone, 'remote', 'remove', 'explainer-fork']);
+    } catch {
+      /* no pre-existing fork remote — fine */
+    }
+    try {
+      run('git', ['-C', clone, 'remote', 'add', 'explainer-fork', `https://github.com/${login}/${repo.name}.git`]);
+      run('git', ['-C', clone, 'push', '--force-with-lease', '-u', 'explainer-fork', BRANCH]);
+    } catch (err) {
+      fail(`could not push the branch to the fork ${login}/${repo.name}: ${err.message}`);
+    }
+    headRef = `${login}:${BRANCH}`;
+  }
+
+  const title = `docs: add a visual explainer for ${repoName}`;
+  const body = [
+    `This optional PR adds a short **Explainer** section to the README:`,
+    '',
+    `- an explainer badge linking to the live explainer (${liveUrl})`,
+    '- an **Architecture** diagram and a **How it works** flow diagram (shared SVGs, authored once)',
+    '- a brief architectural explanation alongside each diagram',
+    '',
+    'It touches only the README and `docs/explainer/`. Merge it or close it — no pressure.',
+    '',
+    '🤖 Generated with [Claude Code](https://claude.com/claude-code)',
+  ].join('\n');
+
+  try {
+    prUrl = run('gh', [
+      'pr', 'create',
+      '--repo', `${repo.owner}/${repo.name}`,
+      '--base', baseBranch,
+      '--head', headRef,
+      '--title', title,
+      '--body', body,
+    ]);
+    // gh prints the PR URL on the last line of stdout.
+    prUrl = prUrl.split('\n').map((l) => l.trim()).filter(Boolean).pop();
+  } catch (err) {
+    fail(`gh pr create failed: ${err.message}`);
+  }
+}
+
+if (!prUrl || !/^https?:\/\//.test(prUrl)) {
+  fail(`could not determine the opened PR URL (got: ${JSON.stringify(prUrl)}).`);
+}
+
+// ── Merge ONLY the readmePr slot back; leave every other slot untouched ───────────────────────────
+ctx.readmePr = { prUrl, svgsShared: ['architecture.svg', 'flow.svg'] };
+fs.writeFileSync(buildJsonPath, JSON.stringify(ctx, null, 2) + '\n');
+
+log(`opened README PR: ${prUrl}`);
+emit({
+  ok: true,
+  outputs: {
+    readmePr: ctx.readmePr,
+    prUrl,
+    head: headRef,
+    base: baseBranch,
+    svgsShared: ctx.readmePr.svgsShared,
+  },
+  error: null,
+});
+process.exit(0);

package/tools/repo-seo.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// repo-seo.mjs — Station 8 tool #12: make the explainer repo discoverable + suggest source-repo SEO.
+//
+// CONTRACT (tools/CONTRACT.md): node tools/repo-seo.mjs <build-dir>
+//   Reads (declared inputs):  publish.explainerRepoUrl, concept, understanding.summary (+ GitHub token)
+//   Writes (own slot only):   publish.repoTopics, publish.repoDescription, publish.sourceRepoSeoSuggested
+//   stdout = ONE JSON result object; diagnostics → stderr; exit 0 iff ok:true, else non-zero.
+//
+// Sets GitHub TOPICS + a strong description on the EXPLAINER repo via the GitHub API (GitHub is the
+// new AI-world social media). Topics/description are derived MECHANICALLY from the brain-authored
+// concept + understanding.summary — the tool never invents judgement. For the SOURCE repo it only
+// EMITS suggestions (offered, never set — INV-16).
+//
+// FAIL LOUD: a missing input, a failed API write, or a write that does not persist (verified by a
+// read-back) is a non-zero exit with a clear message — never a silent green.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const STOP = new Set(('the a an and or of to in for with on is are be this that it its as by from into how what why your you our we their they them use uses using via not no yes can will built make makes new one two repo repository project code library tool app site web page based simple easy fast just like more most all any each other than then over under between'.split(' ')));
+
+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');
+}
+const errText = (e) => (e.stderr ? e.stderr.toString() : '') || e.message || String(e);
+
+function requireGh() {
+  try { execFileSync('gh', ['--version'], { stdio: ['ignore', 'ignore', 'ignore'] }); }
+  catch { throw new Error("GitHub CLI 'gh' not found in PATH (required to set explainer-repo SEO)"); }
+}
+function parseRepoUrl(url) {
+  const m = String(url).match(/github\.com[/:]([^/]+)\/([^/.\s]+?)(?:\.git)?\/?$/);
+  if (!m) throw new Error(`cannot parse owner/repo from publish.explainerRepoUrl: ${url}`);
+  return { owner: m[1], repo: m[2] };
+}
+
+// ---- mechanical topic / description derivation ----
+const toTopic = (w) => w.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').slice(0, 50);
+function keywords(text, limit) {
+  const seen = new Set();
+  const out = [];
+  for (const raw of String(text || '').split(/[^A-Za-z0-9]+/)) {
+    const t = toTopic(raw);
+    if (t.length < 3 || STOP.has(t) || /^\d+$/.test(t) || seen.has(t)) continue;
+    seen.add(t); out.push(t);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+function buildTopics(concept, summary, baseSlug, { source }) {
+  const base = source ? [] : ['explainer', 'documentation', 'knowledge-base'];
+  const slug = source ? [] : keywords(baseSlug, 2);
+  const metaphor = keywords(concept?.metaphor, 2);
+  const tagline = keywords(concept?.tagline, 4);
+  const fromSummary = keywords(summary, 10);
+  const seen = new Set();
+  const out = [];
+  for (const t of [...base, ...slug, ...metaphor, ...tagline, ...fromSummary]) {
+    if (t && !seen.has(t)) { seen.add(t); out.push(t); }
+    if (out.length >= 20) break;   // GitHub caps topics at 20
+  }
+  if (!out.length) throw new Error('could not derive any valid topics from concept + understanding.summary');
+  return out;
+}
+const clamp = (s, n) => { const t = String(s).replace(/\s+/g, ' ').trim(); return t.length > n ? t.slice(0, n - 1).trimEnd() + '…' : t; };
+function buildDescription(concept, summary) {
+  const tag = concept?.tagline ? `${String(concept.tagline).trim()} — ` : '';
+  const d = clamp(`${tag}${summary}`, 350);   // GitHub repo description practical cap
+  if (!d) throw new Error('could not derive a repo description from concept.tagline + understanding.summary');
+  return d;
+}
+
+// ---- GitHub API via gh ----
+function ghSetDescription(owner, repo, description) {
+  try { execFileSync('gh', ['api', '-X', 'PATCH', `repos/${owner}/${repo}`, '-f', `description=${description}`], { stdio: ['ignore', 'ignore', 'pipe'] }); }
+  catch (e) { throw new Error(`set description on ${owner}/${repo} failed: ${errText(e).slice(0, 200)}`); }
+}
+function ghSetTopics(owner, repo, topics) {
+  try { execFileSync('gh', ['api', '-X', 'PUT', `repos/${owner}/${repo}/topics`, '--input', '-'], { input: JSON.stringify({ names: topics }), stdio: ['pipe', 'ignore', 'pipe'] }); }
+  catch (e) { throw new Error(`set topics on ${owner}/${repo} failed: ${errText(e).slice(0, 200)}`); }
+}
+function ghGetTopics(owner, repo) {
+  try { return JSON.parse(execFileSync('gh', ['api', `repos/${owner}/${repo}/topics`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })).names || []; }
+  catch (e) { throw new Error(`read-back of topics on ${owner}/${repo} failed: ${errText(e).slice(0, 200)}`); }
+}
+function ghGetDescription(owner, repo) {
+  try { return execFileSync('gh', ['api', `repos/${owner}/${repo}`, '--jq', '.description // ""'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }
+  catch (e) { throw new Error(`read-back of description on ${owner}/${repo} failed: ${errText(e).slice(0, 200)}`); }
+}
+
+async function main() {
+  const buildDir = process.argv[2];
+  if (!buildDir) throw new Error('usage: node tools/repo-seo.mjs <build-dir>');
+
+  const bc = readContext(buildDir);
+  const explainerRepoUrl = bc.publish?.explainerRepoUrl;
+  if (!explainerRepoUrl) throw new Error('publish.explainerRepoUrl missing in build.json (run publish-repo first)');
+  const concept = bc.concept || {};
+  const summary = bc.understanding?.summary;
+  if (!summary) throw new Error('understanding.summary missing in build.json (run build-kb first)');
+
+  requireGh();
+  if (!(process.env.GITHUB_TOKEN || process.env.GH_TOKEN)) throw new Error('GITHUB_TOKEN (or GH_TOKEN) not set in environment (required to set explainer-repo SEO)');
+
+  const { owner, repo } = parseRepoUrl(explainerRepoUrl);
+  const topics = buildTopics(concept, summary, repo.replace(/-explainer$/, ''), { source: false });
+  const description = buildDescription(concept, summary);
+
+  ghSetDescription(owner, repo, description);
+  ghSetTopics(owner, repo, topics);
+  console.error(`[repo-seo] set ${topics.length} topics + description on ${owner}/${repo}`);
+
+  // verify the writes actually persisted (fail loud, never a silent green)
+  const repoTopics = ghGetTopics(owner, repo);
+  const repoDescription = ghGetDescription(owner, repo);
+  if (!repoTopics.length) throw new Error(`topics did not persist on ${owner}/${repo} (GitHub API read-back returned none)`);
+  if (!repoDescription) throw new Error(`description did not persist on ${owner}/${repo} (GitHub API read-back returned empty)`);
+
+  // SUGGESTED only for the SOURCE repo (offered, never set — INV-16)
+  const sourceRepoSeoSuggested = {
+    topics: buildTopics(concept, summary, repo.replace(/-explainer$/, ''), { source: true }),
+    description: clamp(summary, 350),
+  };
+
+  mergeSlot(buildDir, 'publish', { repoTopics, repoDescription, sourceRepoSeoSuggested });
+  return { repoTopics, repoDescription, sourceRepoSeoSuggested, 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); });