@bongos/core 1.19.364 → 1.19.366

package/tests/sound_player.mjs

@@ -0,0 +1,345 @@
+// tests/sound_player.mjs — the local notification player and its assets
+// (task 1003272).
+//
+// THE BUG THIS FILE EXISTS TO MAKE UNREPEATABLE. The 5-event sound system
+// (V3.R90, task 1000781) shipped its whole CONFIGURATION — prefs, per-sound
+// toggles, master volume, a per-event variant picker in Settings — and never
+// shipped the audio. `git ls-files` carried exactly one WAV, so four of the five
+// events resolved to a 404 and played nothing, and .claude/sounds/play.js, which
+// four other files require, had never been committed at all. Two previous
+// attempts to fix "sound is broken" (tasks 1001252, 1000796) were abandoned
+// without reaching either fact.
+//
+// So the load-bearing test here is the boring one: EVERY SOUND THE SERVER CAN
+// NAME HAS A FILE (and every file is really playable audio). That is the
+// assertion whose absence let a shipped feature be silent for months.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const player = require(path.join(ROOT, '.claude', 'sounds', 'play.js'));
+const soundPrefs = require(path.join(ROOT, 'modules', 'builder-settings', 'sound-prefs.js'));
+
+const WAV_DIR = path.join(ROOT, 'modules', 'hall-ui', 'public');
+
+function tmpPrefs(obj) {
+  const f = path.join(os.tmpdir(), `otb-test-prefs-${process.pid}-${Math.abs(hash(JSON.stringify(obj)))}.json`);
+  fs.writeFileSync(f, JSON.stringify(obj));
+  return f;
+}
+// A tiny stable hash so the temp name is derived from content, not a clock
+// (Date.now()/Math.random() are avoidable here and make reruns noisier).
+function hash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) { h = (h * 31 + s.charCodeAt(i)) | 0; }
+  return h;
+}
+
+// Minimal 16-bit mono WAV, for the scaler tests.
+function wav(samples, { bits = 16, extraChunk = false } = {}) {
+  const data = Buffer.alloc(samples.length * 2);
+  samples.forEach((v, i) => data.writeInt16LE(v, i * 2));
+  const pre = extraChunk ? Buffer.concat([Buffer.from('LIST'), u32(4), Buffer.from('INFO')]) : Buffer.alloc(0);
+  const head = Buffer.alloc(36);
+  head.write('RIFF', 0); head.writeUInt32LE(28 + pre.length + data.length, 4); head.write('WAVE', 8);
+  head.write('fmt ', 12); head.writeUInt32LE(16, 16); head.writeUInt16LE(1, 20);
+  head.writeUInt16LE(1, 22); head.writeUInt32LE(44100, 24); head.writeUInt32LE(88200, 28);
+  head.writeUInt16LE(2, 32); head.writeUInt16LE(bits, 34);
+  return Buffer.concat([head, pre, Buffer.from('data'), u32(data.length), data]);
+}
+function u32(n) { const b = Buffer.alloc(4); b.writeUInt32LE(n); return b; }
+
+// ── the assertion the original bug needed ───────────────────────────────────
+
+test('EVERY sound the server can name has a real file on disk', () => {
+  // KNOWN_SOUNDS is what /me/sound-prefs offers a builder to toggle, and the
+  // event-sound variants resolve to these same stems. A name here with no file
+  // is a toggle for silence — which is exactly what shipped.
+  const known = Object.keys(soundPrefs.SOUND_DEFAULTS || {});
+  assert.ok(known.length >= 5, `expected the 5-event roster, got ${known.length}`);
+  for (const name of known) {
+    const f = path.join(WAV_DIR, `${name}.wav`);
+    assert.ok(fs.existsSync(f), `${name}.wav is MISSING — the server offers this sound and nothing can play it`);
+    assert.ok(fs.statSync(f).size > 1000, `${name}.wav exists but is suspiciously tiny`);
+  }
+});
+
+test('every asset is really 16-bit 44.1kHz mono PCM, like the one that always worked', () => {
+  // Same format as the pre-existing chime.wav, so nothing downstream has to care
+  // which file it was handed.
+  for (const name of Object.keys(soundPrefs.SOUND_DEFAULTS || {})) {
+    const b = fs.readFileSync(path.join(WAV_DIR, `${name}.wav`));
+    assert.equal(b.toString('ascii', 0, 4), 'RIFF', `${name}: not RIFF`);
+    assert.equal(b.toString('ascii', 8, 12), 'WAVE', `${name}: not WAVE`);
+    assert.equal(b.readUInt16LE(20), 1, `${name}: not PCM`);
+    assert.equal(b.readUInt16LE(22), 1, `${name}: not mono`);
+    assert.equal(b.readUInt32LE(24), 44100, `${name}: wrong sample rate`);
+    assert.equal(b.readUInt16LE(34), 16, `${name}: not 16-bit`);
+  }
+});
+
+test('EVERY event-sound variant resolves to a real file, and each event offers a real CHOICE', () => {
+  // The Settings variant picker offered names like "Lyre Pluck" and "Bronze
+  // Fanfare" that resolved to wavs which did not exist — selectable options for
+  // silence. Both halves are asserted: the file is there, and an event's variants
+  // are not all the same sound (a picker whose options are identical is a lie).
+  const eventPrefs = require(path.join(ROOT, 'modules', 'builder-settings', 'event-sound-prefs.js'));
+  const events = eventPrefs.EVENTS || eventPrefs.default || [];
+  assert.equal(events.length, 5, 'the 5-event roster');
+  for (const ev of events) {
+    assert.ok(ev.variants.length >= 2, `${ev.id}: a picker needs something to pick`);
+    for (const v of ev.variants) {
+      assert.ok(fs.existsSync(path.join(WAV_DIR, `${v.wav}.wav`)),
+        `${ev.id}/${v.id} names ${v.wav}.wav, which does not exist — a selectable silence`);
+    }
+    const distinct = new Set(ev.variants.map((v) => v.wav));
+    assert.equal(distinct.size, ev.variants.length,
+      `${ev.id}: its variants must map to DIFFERENT sounds, or switching changes nothing`);
+    assert.equal(ev.variants.filter((v) => v.isDefault).length, 1, `${ev.id}: exactly one default`);
+  }
+});
+
+test('the generator is idempotent, so the assets are reproducible not mysterious', () => {
+  // --check exits non-zero if a re-run would change any byte. An asset nobody can
+  // regenerate is how this repo lost the player in the first place.
+  execFileSync(process.execPath, [path.join(ROOT, 'scripts', 'gds', 'gen-sounds.js'), '--check'], { stdio: 'pipe' });
+});
+
+test('the generator does NOT touch chime.wav', () => {
+  // chime predates this task and is the sound builders already know; regenerating
+  // it would silently swap a familiar sound for a different one.
+  const gen = require(path.join(ROOT, 'scripts', 'gds', 'gen-sounds.js'));
+  assert.ok(!Object.keys(gen.SOUNDS).includes('chime'));
+  assert.deepEqual(Object.keys(gen.SOUNDS).sort(), ['alert', 'fanfare', 'ship', 'triumph']);
+});
+
+// ── the require that four files depend on ───────────────────────────────────
+
+test("ship-state's guarded require now resolves the REAL player, not its no-op stub", () => {
+  // task 1002199 wrapped this require so a missing player could not crash ship.js.
+  // The guard stays — but it must no longer be what actually runs.
+  const shipState = require(path.join(ROOT, 'scripts', 'gds', 'ship-state.js'));
+  assert.equal(typeof shipState.playSound, 'function');
+  assert.equal(shipState.playSound.name, 'playSound',
+    'the stub is an anonymous arrow; the real one is a named function');
+  assert.ok(shipState.playSound.length >= 1, 'the real player takes a wav name');
+});
+
+// ── the writer and the readers must agree on ONE path ──────────────────────
+
+test('every prefs READER resolves the same path the WRITER uses', () => {
+  // THE FOURTH BUG IN THIS STACK. fetch-sound-prefs.js writes the mirror through
+  // instance-config.configPath() — today ~/.config/cloudbongos/ — while three
+  // readers hardcoded ~/.config/otb/, the PRE-RENAME location. Every one of them
+  // silently found nothing: the player failed open (so the Settings toggles and
+  // master volume had no local effect at all), and the ship bell always fell back
+  // to its default instead of the builder's chosen variant. Nothing errored.
+  const ic = require(path.join(ROOT, 'src', 'instance-config.js'));
+  const canonical = ic.configPath('sound-prefs.json');
+
+  const shipIo = require(path.join(ROOT, 'scripts', 'gds', 'ship-io.js'));
+  const turnEnd = require(path.join(ROOT, 'scripts', 'gds', 'turn-end-sound.js'));
+
+  // The player's canonical path must BE the writer's path.
+  assert.equal(player.PREFS_PATH, canonical, 'play.js must read where the writer writes');
+  // The other two resolve to the canonical path when it exists, else the legacy
+  // one — so assert membership rather than pinning which branch this box takes.
+  for (const [name, got] of [['ship-io', shipIo.shipPrefsPath()], ['turn-end-sound', turnEnd.prefsPath()]]) {
+    assert.ok([canonical, player.LEGACY_PREFS_PATH].includes(got),
+      `${name} resolved ${got}, which is neither the canonical nor the legacy path`);
+  }
+});
+
+test('no reader hardcodes the pre-rename otb path as its ONLY location', () => {
+  // A grep-level guard: the string may appear as a documented FALLBACK, but a
+  // reader whose only path is the legacy one is the bug returning.
+  const files = [
+    path.join(ROOT, '.claude', 'sounds', 'play.js'),
+    path.join(ROOT, 'scripts', 'gds', 'ship-io.js'),
+    path.join(ROOT, 'scripts', 'gds', 'turn-end-sound.js'),
+  ];
+  for (const f of files) {
+    const src = fs.readFileSync(f, 'utf8');
+    if (!src.includes("'otb'")) continue; // no legacy reference at all: fine
+    assert.ok(src.includes('instance-config'),
+      `${path.basename(f)} mentions the legacy otb path without resolving via instance-config`);
+  }
+});
+
+test('the legacy prefs file is still honoured when the canonical one is absent', () => {
+  // An older box has its mirror at the pre-rename path; its saved toggles must
+  // keep working rather than silently resetting to "everything on".
+  const legacyOnly = tmpPrefs({ sounds: { ship: false }, volume: 40 });
+  // readPrefs falls back only when its FIRST path is unreadable, so point it at
+  // an absent file and assert the fallback chain does not throw or lose the shape.
+  const p = player.readPrefs(path.join(os.tmpdir(), 'otb-absent-canonical.json'));
+  assert.equal(typeof p.volume, 'number');
+  assert.equal(typeof p.enabled('ship'), 'boolean');
+  // And the explicit-path form still reads exactly what it is given.
+  const direct = player.readPrefs(legacyOnly);
+  assert.equal(direct.enabled('ship'), false);
+  assert.equal(direct.volume, 40);
+});
+
+test('the Stop hook resolves the builder CHOSEN variant, not just the fallback', () => {
+  // The hook exists at all only as of this task — .claude/settings.json had no
+  // Stop hook, so the "Claude finished a turn" sound had nothing to fire it.
+  const turnEnd = require(path.join(ROOT, 'scripts', 'gds', 'turn-end-sound.js'));
+  assert.equal(turnEnd.EVENT_ID, 'user-input');
+  assert.equal(turnEnd.FALLBACK_WAV, 'chime');
+  const wav = turnEnd.resolveWav();
+  assert.equal(typeof wav, 'string');
+  assert.ok(fs.existsSync(path.join(WAV_DIR, `${wav}.wav`)),
+    `the hook resolved ${wav}, which has no file`);
+});
+
+test('the Stop hook and the prefs mirror are actually WIRED into settings.json', () => {
+  // fetch-sound-prefs.js described "a LOCAL Stop hook" for months while
+  // .claude/settings.json contained no Stop hook and never invoked the mirror.
+  // Documentation is not a trigger.
+  const settings = JSON.parse(fs.readFileSync(path.join(ROOT, '.claude', 'settings.json'), 'utf8'));
+  const cmds = (key) => (settings.hooks?.[key] || []).flatMap((g) => (g.hooks || []).map((h) => h.command));
+  assert.ok(cmds('Stop').some((c) => c.includes('turn-end-sound')), 'no Stop hook rings the turn-end sound');
+  assert.ok(cmds('SessionStart').some((c) => c.includes('fetch-sound-prefs')),
+    'nothing mirrors the prefs, so the toggles cannot take local effect');
+});
+
+// ── path safety: the wav name comes off disk, so it is input ────────────────
+
+test('a wav name is a bare stem — traversal and absolute paths are refused', () => {
+  for (const bad of ['../../etc/passwd', '/etc/passwd', '..', '', 'a/b', 'sh ell', null, undefined, 42, 'x'.repeat(65)]) {
+    assert.equal(player.safeName(bad), null, `${JSON.stringify(bad)} must not be accepted`);
+  }
+  for (const good of ['ship', 'chime', 'bronze-fanfare', 'Alert_2']) {
+    assert.equal(player.safeName(good), good);
+  }
+});
+
+test('playSound refuses a bad name without touching the filesystem', () => {
+  let spawned = 0;
+  const spawnFn = () => { spawned += 1; return { on() {}, unref() {} }; };
+  assert.equal(player.playSound('../../etc/passwd', { spawnFn }), false);
+  assert.equal(player.playSound('nope-not-a-sound', { spawnFn }), false);
+  assert.equal(spawned, 0);
+});
+
+// ── prefs: fail OPEN, because being mutely broken is the bug ────────────────
+
+test('a missing prefs file plays everything (fail open)', () => {
+  const p = player.readPrefs(path.join(os.tmpdir(), 'otb-definitely-absent-prefs.json'));
+  assert.equal(p.volume, 100);
+  assert.equal(p.enabled('ship'), true);
+  assert.equal(p.enabled('anything-at-all'), true);
+});
+
+test('garbage in the prefs file also plays everything', () => {
+  const f = path.join(os.tmpdir(), `otb-test-prefs-garbage-${process.pid}.json`);
+  fs.writeFileSync(f, 'not json at all');
+  const p = player.readPrefs(f);
+  assert.equal(p.volume, 100);
+  assert.equal(p.enabled('ship'), true);
+});
+
+test('only an EXPLICIT false mutes a sound', () => {
+  const p = player.readPrefs(tmpPrefs({ sounds: { ship: false, alert: true }, volume: 70 }));
+  assert.equal(p.enabled('ship'), false);
+  assert.equal(p.enabled('alert'), true);
+  assert.equal(p.enabled('triumph'), true, 'a sound absent from the map is not muted');
+  assert.equal(p.volume, 70);
+});
+
+test('the LEGACY flat prefs shape is still read', () => {
+  // fetch-sound-prefs.js documents that play.js must tolerate the old
+  // { <sound>: <bool> } file, which older boxes still have on disk.
+  const p = player.readPrefs(tmpPrefs({ ship: false, chime: true }));
+  assert.equal(p.enabled('ship'), false);
+  assert.equal(p.enabled('chime'), true);
+  assert.equal(p.volume, 100, 'no volume key in the legacy shape → full');
+});
+
+test('volume is clamped and rounded into 0-100', () => {
+  assert.equal(player.readPrefs(tmpPrefs({ volume: 250 })).volume, 100);
+  assert.equal(player.readPrefs(tmpPrefs({ volume: -30 })).volume, 0);
+  assert.equal(player.readPrefs(tmpPrefs({ volume: 62.6 })).volume, 63);
+  assert.equal(player.readPrefs(tmpPrefs({ volume: 'loud' })).volume, 100);
+  assert.equal(player.readPrefs(tmpPrefs({ volume: NaN })).volume, 100);
+});
+
+test('a muted sound and volume 0 both spawn NOTHING', () => {
+  let spawned = 0;
+  const spawnFn = () => { spawned += 1; return { on() {}, unref() {} }; };
+  assert.equal(player.playSound('ship', { prefsPath: tmpPrefs({ sounds: { ship: false }, volume: 100 }), spawnFn }), false);
+  assert.equal(player.playSound('ship', { prefsPath: tmpPrefs({ sounds: {}, volume: 0 }), spawnFn }), false);
+  assert.equal(spawned, 0, 'silence must not cost a process');
+});
+
+// ── the volume scaler (aplay and PowerShell have no volume flag) ────────────
+
+test('scaleWav halves the samples and preserves the file length', () => {
+  const src = wav([0, 1000, -2000, 32000, -32000]);
+  const out = player.scaleWav(src, 0.5);
+  assert.equal(out.length, src.length);
+  const at = (b, i) => b.readInt16LE(b.length - 10 + i * 2);
+  assert.equal(at(out, 1), 500);
+  assert.equal(at(out, 2), -1000);
+  assert.equal(at(out, 3), 16000);
+});
+
+test('scaleWav clamps rather than wrapping — a gain above 1 must not invert audio', () => {
+  const out = player.scaleWav(wav([32000, -32000]), 2);
+  assert.equal(out.readInt16LE(out.length - 4), 32767);
+  assert.equal(out.readInt16LE(out.length - 2), -32768);
+});
+
+test('scaleWav walks the chunk list instead of assuming data starts at byte 44', () => {
+  // A WAV carrying a LIST chunk before `data` would be corrupted by a naive
+  // fixed-offset scaler — it would scale the metadata and skip the audio.
+  const src = wav([1000, 2000], { extraChunk: true });
+  const out = player.scaleWav(src, 0.5);
+  assert.equal(out.readInt16LE(out.length - 4), 500);
+  assert.equal(out.readInt16LE(out.length - 2), 1000);
+  assert.equal(out.toString('ascii', 36, 40), 'LIST', 'the metadata chunk is left intact');
+});
+
+test('scaleWav leaves anything it does not understand completely alone', () => {
+  const notWav = Buffer.from('this is not audio at all');
+  assert.ok(player.scaleWav(notWav, 0.5).equals(notWav));
+  assert.ok(player.scaleWav(Buffer.alloc(10), 0.5).equals(Buffer.alloc(10)));
+  const eightBit = wav([1000, 2000], { bits: 8 });
+  assert.ok(player.scaleWav(eightBit, 0.5).equals(eightBit), '8-bit is passed through, not mangled');
+});
+
+// ── the spawn, exercised without real audio ────────────────────────────────
+
+test('a playable sound spawns the platform player, detached and unref\'d', () => {
+  const calls = [];
+  const spawnFn = (cmd, args, opts) => { calls.push({ cmd, args, opts }); return { on() {}, unref() {} }; };
+  // playerFor returns null on a machine with no audio binary (CI containers), in
+  // which case there is nothing to assert about the spawn — so this test asserts
+  // the CONTRACT that holds either way: it never throws, and it only ever spawns
+  // when a player exists.
+  const res = player.playSound('ship', { prefsPath: tmpPrefs({ sounds: {}, volume: 100 }), spawnFn });
+  const available = player.playerFor(path.join(WAV_DIR, 'ship.wav')) !== null;
+  assert.equal(res, available, 'plays exactly when this machine has a player');
+  assert.equal(calls.length, available ? 1 : 0);
+  if (available) {
+    assert.equal(calls[0].opts.detached, true, 'audio must not hold the caller open');
+    assert.equal(calls[0].opts.stdio, 'ignore');
+    assert.ok(calls[0].args.some((a) => String(a).includes('ship')), 'the chosen wav reaches the player');
+  }
+});
+
+test('playerFor never throws and returns null or a [cmd, args] pair', () => {
+  const got = player.playerFor('/tmp/whatever.wav');
+  if (got !== null) {
+    assert.equal(typeof got[0], 'string');
+    assert.ok(Array.isArray(got[1]));
+  }
+});