@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/gen-session-index.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+'use strict';
+// gen-session-index.js — session-log index, generated (Cloud Bongos portable core; ADR 0062 §8, task 1226).
+//
+// WHY. The old CLAUDE.md §13 was a HAND-MAINTAINED index of every session: it bloated the
+// always-loaded context file, drifted, and its links recurrently dangled when a session file was
+// renamed/mis-slugged (the bug recurs as idea 57, BFG F2, task 580). The fix (ADR 0062 §8): the
+// session-log PROSE is canonical in docs/session-logs/*.md (older entries compressed into
+// docs/session-log-archive.md) + the DB session corpus (session_logs / the BFG session_records);
+// the index is GENERATED from those files so no instance hand-maintains it and a link can NEVER
+// dangle (the generator only ever links files that exist on disk).
+//
+// It writes two artifacts, the gen-diagrams.js / gen-repo-map.js pattern (ADR 0063):
+//   (1) docs/session-log-index.md — the FULL index (every session file, newest first). The
+//       browseable full history (renders on GitHub / the hall).
+//   (2) a BOUNDED "recent sessions" snippet injected between markers in CLAUDE.md §13 — the only
+//       session-log content the always-loaded context file carries.
+//
+// Zero-dependency, deterministic (sorts by date desc then filename; no timestamps) — so `--check`
+// is a clean idempotent CI gate, wired into scripts/bongos/fitness.js (Path C) and auto-regenerated +
+// committed at ship by ship.js (regenerateSessionIndex), exactly like the repo map.
+//
+// Usage:
+//   node scripts/bongos/gen-session-index.js             # regenerate the index + CLAUDE.md snippet
+//   node scripts/bongos/gen-session-index.js --check       # write nothing; exit 2 if EITHER bucket would change
+//   node scripts/bongos/gen-session-index.js --check-block # exit 2 only if the tracked CLAUDE.md §13 snippet drifts (CI gate)
+//   node scripts/bongos/gen-session-index.js --check-whole # exit 2 only if docs/session-log-index.md drifts
+//   node scripts/bongos/gen-session-index.js --whole-only  # WRITE the index only; never touch the tracked
+//                                                       # CLAUDE.md snippet (sparse-checkout use; task 1002962)
+// docs/session-log-index.md is GITIGNORED + regenerated at deploy since ADR 0110 (task 1926).
+//   node scripts/bongos/gen-session-index.js --json       # print the parsed entries as JSON (debug)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
+
+// The session log, its index, and the CLAUDE.md §13 snippet are all HOST (instance) content —
+// docs/session-logs/ + docs/session-log-index.md + the instance root CLAUDE.md. Resolve them under
+// the host repo so a STANDALONE instance (core in node_modules, ADR 0108) indexes its OWN sessions,
+// not the vendored core's. On the monorepo/at-ship this still resolves to the checkout (cwd
+// fallback). Do NOT reintroduce a hardcoded `path.resolve(__dirname,'..','..')` — post-split it
+// points INTO node_modules/@bongos/core (the exact bug gen-repo-map/gen-file-map warn against; the
+// reason gen-session-index was writing the core's index on a standalone box — task 1002314).
+const REPO_ROOT = resolveInstanceRoot();
+const LOGS_DIR = path.join(REPO_ROOT, 'docs', 'session-logs');
+const INDEX_PATH = path.join(REPO_ROOT, 'docs', 'session-log-index.md');
+const CLAUDE_PATH = path.join(REPO_ROOT, 'CLAUDE.md');
+
+// How many of the most-recent sessions the always-loaded CLAUDE.md snippet carries. The rest live
+// in the generated full index. Bounded on purpose (ADR 0062 §8) — the context file must stay lean.
+//
+// 10 -> 3 (task 1003688). At 10 this block was 1,795 chars, 8.4% of a CLAUDE.md that loads IN FULL
+// in every session, of every craft, whether or not the reader cares what shipped last week. Its job
+// is to answer "what just happened here" — and the 3 newest answer that; entries 4-10 were history,
+// which is what docs/session-log-index.md and docs/session-logs/ are for. This is the one number to
+// change if that balance ever needs revisiting: the header text, the fitness gate and
+// tests/session_index.mjs all read it rather than restating it.
+const SNIPPET_COUNT = 3;
+
+// Only dated session-log files are entries — a date-prefixed slug is the naming contract (§12).
+// This excludes any stray README / the index itself / non-session markdown in the directory.
+const SESSION_FILE_RE = /^(\d{4}-\d{2}-\d{2})-.*\.md$/;
+
+const BEGIN = '<!-- BEGIN GENERATED SESSION-LOG SNIPPET (scripts/bongos/gen-session-index.js — do not hand-edit) -->';
+const END = '<!-- END GENERATED SESSION-LOG SNIPPET -->';
+
+// Turn a raw H1/H3 heading into clean link TEXT: strip heading markers + backticks, de-linkify
+// embedded markdown links (so the entry — itself a link — has no broken NESTED links), and de-hash
+// bare `#NNN` task refs to plain numbers (committed markdown must pass the linkify-refs CI gate; a
+// bare #NNN auto-links to a GitHub issue and 404s). Genuine `PR #N` / `issue #N` keep their `#`.
+function cleanTitle(rawHeading) {
+  let t = String(rawHeading || '');
+  t = t.replace(/^#{1,6}\s+/, ''); // drop leading heading markers
+  t = t.replace(/`/g, ''); // code spans add nothing as link text and can hide a #NNN
+  t = t.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1'); // de-linkify [text](url) -> text (no nested links)
+  // de-hash bare #NNN -> NNN, but leave real GitHub refs (PR/issue/pull request #N) alone
+  t = t.replace(/(\bPR\b|\bpull request\b|\bissue\b)?(\s*)#(\d{1,7})\b/gi, (m, kw, sp, n) =>
+    kw ? `${kw}${sp}#${n}` : `${sp}${n}`
+  );
+  return t.replace(/\s+/g, ' ').trim();
+}
+
+// Parse one session-log file into { date, file, title }. date comes from the filename (the reliable
+// contract); title from the first heading, prefixed with the date if the heading doesn't already
+// lead with it, so every rendered entry reads uniformly `YYYY-MM-DD — title`.
+function parseEntry(filename, content) {
+  const m = SESSION_FILE_RE.exec(filename);
+  if (!m) return null;
+  const date = m[1];
+  const slug = filename.replace(/^\d{4}-\d{2}-\d{2}-/, '').replace(/\.md$/, '');
+  const headingLine = (content.split('\n').find((l) => /^#{1,6}\s+\S/.test(l)) || '').trim();
+  let title = cleanTitle(headingLine) || slug.replace(/-/g, ' ');
+  if (!title.startsWith(date)) title = `${date} — ${title}`;
+  return { date, file: filename, title };
+}
+
+// Read + parse every dated session-log file, newest first (date desc, then filename desc so a
+// same-day tiebreak is stable — deterministic for the --check gate).
+function collectEntries(dir = LOGS_DIR) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const entries = [];
+  for (const name of names) {
+    if (!SESSION_FILE_RE.test(name)) continue;
+    const content = fs.readFileSync(path.join(dir, name), 'utf8');
+    const e = parseEntry(name, content);
+    if (e) entries.push(e);
+  }
+  entries.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : a.file < b.file ? 1 : -1));
+  return entries;
+}
+
+const line = (e, prefix) => `- [${e.title}](${prefix}${e.file})`;
+
+// docs/session-log-index.md — the full generated index (links relative to docs/).
+function renderIndex(entries) {
+  const L = [];
+  L.push('# Session log — index');
+  L.push('');
+  L.push('> **AUTO-GENERATED — do not hand-edit.** Regenerate with `node scripts/bongos/gen-session-index.js` (auto-regenerated + committed at ship, like `gen-repo-map.js`). Generated from the files in [`session-logs/`](session-logs/) so a link can never dangle (retires the recurring §13 drift: idea 57, [#580](https://example.com/builders#/task/580)). The session PROSE is canonical in those files (older entries compressed into [`session-log-archive.md`](session-log-archive.md)); the DB session corpus (`session_logs` + the BFG `session_records`) is the structured record. See [ADR 0062](adr/0062-medusa-instance-model-decoupling.md) §8 · [ADR 0063](adr/0063-generated-repo-map-symbol-skeleton.md).');
+  L.push('');
+  L.push(`**${entries.length} sessions**, newest first.`);
+  L.push('');
+  for (const e of entries) L.push(line(e, 'session-logs/'));
+  L.push('');
+  L.push('---');
+  L.push('');
+  L.push('Older prose compressed for context budget: [`session-log-archive.md`](session-log-archive.md).');
+  return L.join('\n').replace(/\n+$/, '') + '\n';
+}
+
+// The bounded snippet injected into CLAUDE.md §13 (links relative to repo root).
+function renderSnippet(entries, count = SNIPPET_COUNT) {
+  const recent = entries.slice(0, count);
+  const L = [];
+  L.push(BEGIN);
+  // NOT A MARKDOWN LINK, deliberately. docs/session-log-index.md is GITIGNORED
+  // (ADR 0110 — deploy-regenerated, never committed), so a repo-relative link to
+  // it dangles in every fresh checkout. This snippet is written into the TRACKED
+  // CLAUDE.md, so linking it here minted a stale link in CI on every run: that is
+  // what pushed doc_stale_links past the fitness ratchet baseline and turned the
+  // required `unit` check red on main, blocking all PR merges and (via publish.yml's
+  // workflow_run trigger) all releases. Name the file in a code span; never re-link it.
+  L.push(`**Recent sessions** (newest ${recent.length} — full history in \`docs/session-log-index.md\`):`);
+  L.push('');
+  for (const e of recent) L.push(line(e, 'docs/session-logs/'));
+  L.push(END);
+  return L.join('\n');
+}
+
+// Replace the marked snippet region in CLAUDE.md (mirrors gen-repo-map.injectBlock).
+function injectSnippet(existing, snippet) {
+  const b = existing.indexOf(BEGIN);
+  const e = existing.indexOf(END);
+  if (b !== -1 && e !== -1 && e > b) {
+    return existing.slice(0, b) + snippet + existing.slice(e + END.length);
+  }
+  return existing; // markers absent → leave the file untouched (the §13 section seeds them)
+}
+
+function computeWrites() {
+  const entries = collectEntries();
+  const writes = [];
+
+  // Two buckets (ADR 0110, task 1926): 'whole' = docs/session-log-index.md, now
+  // GITIGNORED + regenerated at deploy (no committed copy → no branch
+  // collisions); 'block' = the bounded CLAUDE.md §13 snippet, still tracked, so it
+  // stays a HARD CI gate. main() gates them separately (--check-block vs --check-whole).
+  const idxNext = renderIndex(entries);
+  const idxCur = fs.existsSync(INDEX_PATH) ? fs.readFileSync(INDEX_PATH, 'utf8') : '';
+  if (!sameContent(idxCur, idxNext)) writes.push({ full: INDEX_PATH, content: idxNext, rel: 'docs/session-log-index.md', bucket: 'whole' });
+
+  if (fs.existsSync(CLAUDE_PATH)) {
+    const cur = fs.readFileSync(CLAUDE_PATH, 'utf8');
+    const next = injectSnippet(cur, renderSnippet(entries));
+    if (!sameContent(cur, next)) {
+      if (next === cur && cur.indexOf(BEGIN) === -1) {
+        console.error('gen-session-index: WARN CLAUDE.md has no snippet markers — skipping snippet injection.');
+      } else {
+        writes.push({ full: CLAUDE_PATH, content: next, rel: 'CLAUDE.md', bucket: 'block' });
+      }
+    }
+  }
+  return { entries, writes };
+}
+
+function main() {
+  // `--check` = both buckets; `--check-block` = only the tracked CLAUDE.md §13 snippet
+  // (the HARD CI gate); `--check-whole` = only the gitignored docs/session-log-index.md
+  // (deploy owns its freshness). See computeWrites() + ADR 0110.
+  const checkAll = process.argv.includes('--check');
+  const checkWhole = process.argv.includes('--check-whole');
+  const checkBlock = process.argv.includes('--check-block');
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(collectEntries(), null, 2) + '\n');
+    return;
+  }
+  // WRITE-side bucket selection — the sibling of the --check-* flags (task 1002962,
+  // the gen-repo-map --whole-only twin). On a SPARSE checkout, writing the TRACKED
+  // bucket dirties the tree and the next `git pull` aborts on "local changes would
+  // be overwritten" — a silent, permanent sync deadlock. A sparse checkout
+  // regenerates only the gitignored artifact; the tracked CLAUDE.md §13 snippet
+  // arrives with the pull, generated from the whole tree.
+  const wholeOnly = process.argv.includes('--whole-only');
+  const all = computeWrites().writes;
+  const writes = wholeOnly ? all.filter((w) => w.bucket === 'whole') : all;
+  if (checkAll || checkWhole || checkBlock) {
+    const wantBlock = checkAll || checkBlock;
+    const wantWhole = checkAll || checkWhole;
+    const stale = writes.filter((w) => (w.bucket === 'block' && wantBlock) || (w.bucket === 'whole' && wantWhole));
+    const mode = checkBlock ? '--check-block' : checkWhole ? '--check-whole' : '--check';
+    if (stale.length) {
+      console.error(`gen-session-index ${mode}: STALE — would update ${stale.map((w) => w.rel).join(', ')}`);
+      console.error('  run: node scripts/bongos/gen-session-index.js  (and commit any TRACKED files it changes)');
+      process.exit(2);
+    }
+    console.log(`gen-session-index ${mode}: up to date.`);
+    return;
+  }
+  if (!writes.length) {
+    console.log('gen-session-index: index + snippet already current — no changes.');
+    return;
+  }
+  for (const w of writes) fs.writeFileSync(w.full, w.content);
+  console.log(`gen-session-index: wrote ${writes.length} file(s): ${writes.map((w) => w.rel).join(', ')}`);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  cleanTitle,
+  parseEntry,
+  collectEntries,
+  renderIndex,
+  renderSnippet,
+  injectSnippet,
+  computeWrites,
+  SNIPPET_COUNT,
+  BEGIN,
+  END,
+  SESSION_FILE_RE,
+};

package/scripts/bongos/gen-sounds.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// scripts/bongos/gen-sounds.js — synthesize the notification WAVs (task 1003272).
+//
+// WHY A GENERATOR RATHER THAN FOUR COMMITTED BINARIES. The 5-event sound system
+// (V3.R90, task 1000781) shipped its configuration — the prefs, the toggles, the
+// master volume, the per-event variant picker — and never shipped the audio. Only
+// chime.wav has ever existed in this repo, so four of the five events resolved to
+// a 404 and played nothing. Two prior attempts to fix "sound is broken" (tasks
+// 1001252 and 1000796) were abandoned without reaching that.
+//
+// An opaque binary nobody can regenerate is how a repo loses assets in the first
+// place (the local player itself vanished in the 1.18.0 re-seed and no commit
+// records it). These are simple synthesized tones, so the honest artifact is the
+// recipe: a few dozen lines of additive synthesis anyone can read, adjust, and
+// re-run. `node scripts/bongos/gen-sounds.js` is idempotent — same bytes every time,
+// no timestamps, no randomness — so it can be a CI freshness check like the other
+// generators if that is ever wanted.
+//
+// chime.wav IS NOT TOUCHED. It predates this task and is the one asset the system
+// always had; regenerating it would replace a sound builders already know with a
+// different one for no reason. This writes only the four that were missing.
+//
+// WHERE THEY GO, and why one copy. modules/hall-ui/public/ is served at
+// /builders/<name>.wav, which is exactly what settings.js previews
+// (`new Audio('/builders/' + wavName + '.wav')`). The local player
+// (.claude/sounds/play.js) reads the SAME files from that directory rather than
+// keeping a second copy — two copies of an asset are two things to drift.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RATE = 44100;
+const OUT_DIR = path.resolve(__dirname, '..', '..', 'modules', 'hall-ui', 'public');
+
+// Equal-temperament note table, only the notes these sounds use. Named rather
+// than numeric so the voicings below read as music instead of magic numbers.
+const HZ = {
+  A5: 880.00, D6: 1174.66,
+  C5: 523.25, E5: 659.25, G5: 783.99,
+  C6: 1046.50, E6: 1318.51, G6: 1567.98,
+};
+
+// One struck note: a fundamental plus a little second and third harmonic (a bell
+// is not a sine wave), under an exponential decay with a short fade-in. The
+// fade-in matters — starting a waveform at full amplitude is an audible click.
+function note({ freq, start, dur, gain = 0.5, decay = 4.5 }) {
+  const voices = [
+    { mult: 1, amp: 1.0 },
+    { mult: 2, amp: 0.28 },
+    { mult: 3, amp: 0.10 },
+  ];
+  const attack = Math.min(0.006, dur / 8); // seconds
+  return { freq, start, dur, gain, decay, voices, attack };
+}
+
+// Render a list of notes into one mono float buffer, summed (notes may overlap).
+function render(notes) {
+  const end = notes.reduce((m, n) => Math.max(m, n.start + n.dur), 0);
+  const total = Math.ceil((end + 0.03) * RATE); // a little tail so nothing cuts
+  const buf = new Float64Array(total);
+  for (const n of notes) {
+    const from = Math.floor(n.start * RATE);
+    const len = Math.floor(n.dur * RATE);
+    for (let i = 0; i < len; i++) {
+      const t = i / RATE;
+      const env = Math.exp(-n.decay * t) * Math.min(1, t / n.attack);
+      let s = 0;
+      for (const v of n.voices) s += v.amp * Math.sin(2 * Math.PI * n.freq * v.mult * t);
+      buf[from + i] += s * env * n.gain;
+    }
+  }
+  // Normalize to a consistent peak so no sound is jarringly louder than another,
+  // then a short linear fade-out so the file never ends mid-cycle (another click).
+  let peak = 0;
+  for (let i = 0; i < total; i++) peak = Math.max(peak, Math.abs(buf[i]));
+  const scale = peak > 0 ? 0.82 / peak : 0;
+  const fade = Math.min(total, Math.floor(0.02 * RATE));
+  for (let i = 0; i < total; i++) {
+    let s = buf[i] * scale;
+    const fromEnd = total - 1 - i;
+    if (fromEnd < fade) s *= fromEnd / fade;
+    buf[i] = s;
+  }
+  return buf;
+}
+
+// 16-bit mono PCM, 44100 Hz — byte-for-byte the format of the existing chime.wav,
+// so nothing downstream has to care which file it got.
+function toWav(samples) {
+  const dataBytes = samples.length * 2;
+  const out = Buffer.alloc(44 + dataBytes);
+  out.write('RIFF', 0);
+  out.writeUInt32LE(36 + dataBytes, 4);
+  out.write('WAVE', 8);
+  out.write('fmt ', 12);
+  out.writeUInt32LE(16, 16);      // fmt chunk size
+  out.writeUInt16LE(1, 20);       // PCM
+  out.writeUInt16LE(1, 22);       // mono
+  out.writeUInt32LE(RATE, 24);
+  out.writeUInt32LE(RATE * 2, 28); // byte rate
+  out.writeUInt16LE(2, 32);        // block align
+  out.writeUInt16LE(16, 34);       // bits
+  out.write('data', 36);
+  out.writeUInt32LE(dataBytes, 40);
+  for (let i = 0; i < samples.length; i++) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]));
+    out.writeInt16LE(Math.round(clamped * 32767), 44 + i * 2);
+  }
+  return out;
+}
+
+// The four voicings. Each is written to match what the event MEANS — the labels
+// come from modules/builder-settings/sound-prefs.js.
+const SOUNDS = {
+  // "When Claude needs your input" — a two-tone ask, rising so it reads as a
+  // question. Short and unhurried: this one can fire while someone is thinking.
+  alert: [
+    note({ freq: HZ.A5, start: 0.00, dur: 0.26, gain: 0.5, decay: 7 }),
+    note({ freq: HZ.D6, start: 0.15, dur: 0.40, gain: 0.5, decay: 6 }),
+  ],
+  // "When a task ships" — a settled two-note rise, C5 to G5. A fifth, because it
+  // should sound finished rather than expectant.
+  ship: [
+    note({ freq: HZ.C5, start: 0.00, dur: 0.30, gain: 0.5, decay: 6 }),
+    note({ freq: HZ.G5, start: 0.14, dur: 0.55, gain: 0.5, decay: 4.5 }),
+  ],
+  // "When a big task ships" — the same idea carried further: a major triad
+  // arpeggio landing on the octave.
+  triumph: [
+    note({ freq: HZ.C5, start: 0.00, dur: 0.26, gain: 0.42, decay: 7 }),
+    note({ freq: HZ.E5, start: 0.11, dur: 0.26, gain: 0.42, decay: 7 }),
+    note({ freq: HZ.G5, start: 0.22, dur: 0.30, gain: 0.46, decay: 6 }),
+    note({ freq: HZ.C6, start: 0.34, dur: 0.75, gain: 0.55, decay: 3.4 }),
+  ],
+  // "When you earn a rank promotion" — the brightest of the four, a four-note
+  // fanfare that overlaps into a held top note.
+  fanfare: [
+    note({ freq: HZ.G5, start: 0.00, dur: 0.22, gain: 0.40, decay: 8 }),
+    note({ freq: HZ.C6, start: 0.10, dur: 0.22, gain: 0.44, decay: 8 }),
+    note({ freq: HZ.E6, start: 0.20, dur: 0.26, gain: 0.46, decay: 7 }),
+    note({ freq: HZ.G6, start: 0.31, dur: 0.90, gain: 0.55, decay: 3.0 }),
+  ],
+};
+
+function main() {
+  const check = process.argv.includes('--check');
+  const written = [];
+  const stale = [];
+  for (const [name, notes] of Object.entries(SOUNDS)) {
+    const file = path.join(OUT_DIR, `${name}.wav`);
+    const wav = toWav(render(notes));
+    let current = null;
+    try { current = fs.readFileSync(file); } catch { /* absent */ }
+    if (current && current.equals(wav)) continue;
+    if (check) { stale.push(path.relative(path.resolve(__dirname, '..', '..'), file)); continue; }
+    fs.writeFileSync(file, wav);
+    written.push(`${name}.wav (${wav.length} bytes)`);
+  }
+  if (check) {
+    if (stale.length) {
+      console.error(`gen-sounds --check: STALE — would rewrite ${stale.join(', ')}`);
+      console.error('  run: node scripts/bongos/gen-sounds.js  (and commit the result)');
+      process.exit(1);
+    }
+    console.log('gen-sounds --check: up to date.');
+    return;
+  }
+  console.log(written.length
+    ? `gen-sounds: wrote ${written.join(', ')}`
+    : 'gen-sounds: all sounds already current — no changes.');
+}
+
+if (require.main === module) main();
+module.exports = { render, toWav, SOUNDS, RATE };