dsh-hyperframes 0.10.1 → 0.11.0

package/skills/media-use/scripts/lib/misses.mjs

@@ -0,0 +1,49 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
+
+const MISSES_FILE = "misses.jsonl";
+
+function missesPath() {
+  return join(globalMediaDir(), MISSES_FILE);
+}
+
+export function recordMiss({ type, intent, provider_override, local_only }) {
+  try {
+    const path = missesPath();
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(
+      path,
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        type,
+        intent,
+        provider_override: !!provider_override,
+        local_only: !!local_only,
+      }) + "\n",
+    );
+  } catch {
+    // local miss logging is best-effort; never surface into resolve
+  }
+}
+
+export function readMisses() {
+  const p = missesPath();
+  try {
+    if (!existsSync(p)) return [];
+    const raw = readFileSync(p, "utf8");
+    const records = [];
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        records.push(JSON.parse(trimmed));
+      } catch {
+        // skip malformed local lines, don't crash stats
+      }
+    }
+    return records;
+  } catch {
+    return [];
+  }
+}

package/skills/media-use/scripts/lib/misses.test.mjs

@@ -0,0 +1,89 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readMisses, recordMiss } from "./misses.mjs";
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-misses-"));
+  const home = join(root, "home");
+  mkdirSync(home, { recursive: true });
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
+  return { root, home };
+}
+
+function restoreEnv(saved) {
+  for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+  Object.assign(process.env, saved);
+}
+
+test("recordMiss appends a well-formed local miss", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    recordMiss({ type: "bgm", intent: "moody synth pulse", provider_override: true });
+    const misses = readMisses();
+    assert.equal(misses.length, 1);
+    assert.equal(misses[0].type, "bgm");
+    assert.equal(misses[0].intent, "moody synth pulse");
+    assert.equal(misses[0].provider_override, true);
+    assert.equal(misses[0].local_only, false);
+    assert.ok(!Number.isNaN(Date.parse(misses[0].ts)));
+
+    const raw = readFileSync(join(home, ".media/misses.jsonl"), "utf8");
+    assert.match(raw, /moody synth pulse/);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("recordMiss swallows filesystem failures", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    writeFileSync(join(home, ".media"), "not a directory");
+    assert.doesNotThrow(() =>
+      recordMiss({ type: "image", intent: "unwritable", local_only: true }),
+    );
+    assert.equal(existsSync(join(home, ".media/misses.jsonl")), false);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("recordMiss stays best-effort when the media home cannot be resolved", () => {
+  const savedEnv = { ...process.env };
+  delete process.env.HYPERFRAMES_MEDIA_HOME;
+  process.env.HYPERFRAMES_MEDIA_HOME_REQUIRED = "1";
+  try {
+    assert.doesNotThrow(() => recordMiss({ type: "sfx", intent: "no home", local_only: true }));
+  } finally {
+    restoreEnv(savedEnv);
+  }
+});
+
+test("readMisses skips corrupt lines", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(
+      join(home, ".media/misses.jsonl"),
+      [
+        JSON.stringify({ ts: "2026-07-09T00:00:00.000Z", type: "bgm", intent: "one" }),
+        "{not json",
+        JSON.stringify({ ts: "2026-07-09T00:00:01.000Z", type: "sfx", intent: "two" }),
+      ].join("\n"),
+    );
+    assert.deepEqual(
+      readMisses().map((miss) => miss.intent),
+      ["one", "two"],
+    );
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/skills/media-use/scripts/lib/npx-sync.mjs

@@ -1,18 +1,5 @@
 import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-function resolveNpxCliPath(env, pathExists) {
-  const npmExecPath = env.npm_execpath;
-  const nodeExecPath = env.npm_node_execpath || process.execPath;
-  if (npmExecPath) {
-    const fileName = npmExecPath.replace(/\\/g, "/").split("/").pop()?.toLowerCase();
-    const candidate =
-      fileName === "npx-cli.js" ? npmExecPath : join(dirname(npmExecPath), "npx-cli.js");
-    if (pathExists(candidate)) return candidate;
-  }
-  const besideNode = join(dirname(nodeExecPath), "node_modules", "npm", "bin", "npx-cli.js");
-  return pathExists(besideNode) ? besideNode : null;
-}
+import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
 
 // Sync-spawn analog of the audio engine's spawnP, for execFileSync call sites
 // that must hard-fail (rather than fall through to another provider) when npx
@@ -31,20 +18,7 @@ export function resolveNpxInvocation(
   env = process.env,
   pathExists = existsSync,
 ) {
-  const resolved =
-    platform !== "win32"
-      ? { cmd: "npx", args: argv, opts: { stdio: "ignore", ...opts } }
-      : (() => {
-          const nodeExecPath = env.npm_node_execpath || process.execPath;
-          const npxCliPath = resolveNpxCliPath(env, pathExists);
-          return npxCliPath
-            ? {
-                cmd: nodeExecPath,
-                args: [npxCliPath, ...argv.map((arg) => String(arg))],
-                opts: { stdio: "ignore", windowsHide: true, ...opts },
-              }
-            : null;
-        })();
+  const resolved = resolveSpawnCommand("npx", argv, opts, platform, env, pathExists);
   if (!resolved) {
     // npx-on-win32 with no resolvable npx-cli.js — same terminal condition
     // spawnP warns about, surfaced as a throw for callers with no fallback.

package/skills/media-use/scripts/lib/npx-sync.test.mjs

@@ -0,0 +1,50 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveNpxInvocation } from "./npx-sync.mjs";
+
+// Coverage parity with tts-local-provider.test.mjs, for the whisper.cpp
+// fallback's call-site shape (transcribe.mjs runWhisper): the same three
+// branches, but with the hard-fail contract — no fallback provider exists,
+// so an unresolvable npx must throw actionably instead of returning null.
+
+const envWithNpxCli = {
+  npm_execpath: "C:/Program Files/nodejs/node_modules/npm/bin/npm-cli.js",
+  npm_node_execpath: "C:/Program Files/nodejs/node.exe",
+};
+const npxCliPath = "C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js";
+const pathExists = (path) => path === npxCliPath;
+
+const WHISPER_ARGV = ["hyperframes", "transcribe", "C:\\media\\input.wav", "--dir", "C:\\work"];
+const WHISPER_OPTS = { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 };
+
+test("win32: routes the whisper fallback through node + npx-cli, never bare npx", () => {
+  const resolved = resolveNpxInvocation(
+    WHISPER_ARGV,
+    WHISPER_OPTS,
+    "win32",
+    envWithNpxCli,
+    pathExists,
+  );
+
+  assert.equal(resolved.cmd, envWithNpxCli.npm_node_execpath);
+  assert.equal(resolved.args[0], npxCliPath);
+  assert.deepEqual(resolved.args.slice(1, 3), ["hyperframes", "transcribe"]);
+  // execFileSync options survive the rerouting (the timeout bounds the
+  // whisper build/model download; the pipes surface its errors).
+  assert.deepEqual(resolved.opts.stdio, ["ignore", "pipe", "pipe"]);
+  assert.equal(resolved.opts.timeout, 1_800_000);
+});
+
+test("win32 without a resolvable npx-cli: throws the actionable install hint", () => {
+  assert.throws(
+    () => resolveNpxInvocation(WHISPER_ARGV, WHISPER_OPTS, "win32", {}, () => false),
+    /npx-cli\.js was not found/,
+  );
+});
+
+test("non-win32: spawns plain npx unchanged", () => {
+  const resolved = resolveNpxInvocation(WHISPER_ARGV, WHISPER_OPTS, "darwin", {}, () => false);
+
+  assert.equal(resolved.cmd, "npx");
+  assert.deepEqual(resolved.args, WHISPER_ARGV);
+});

package/skills/media-use/scripts/lib/openverse.mjs

@@ -0,0 +1,134 @@
+// Sound effects from Openverse (https://api.openverse.org): free, no key.
+// Anonymous use is rate limited (20 requests a minute, 200 a day); callers fall
+// back to the bundled library when it is unavailable.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+const OPENVERSE_AUDIO_URL = "https://api.openverse.org/v1/audio/";
+// The only licences media-use accepts: no NonCommercial, ShareAlike or NoDerivatives.
+export const OPENVERSE_SFX_LICENSES = new Set(["cc0", "by"]);
+const PLAYABLE_FILETYPES = new Set(["mp3", "wav", "ogg", "flac"]);
+const MAX_SFX_MS = 15000;
+const IDEAL_SFX_MS = 4000;
+const BY_PENALTY = 2;
+const SEARCH_TIMEOUT_MS = 10000;
+
+// Openverse text lands in markdown and JSON: one line, no control or markdown-structure characters, bounded.
+const oneLine = (text) =>
+  String(text ?? "")
+    .replace(/[\p{Cc}`[\]<>\\]+/gu, " ")
+    .trim()
+    .slice(0, 300);
+// Openverse's audio providers (api.openverse.org/v1/audio/stats/); a new provider's link is dropped until listed.
+const SOURCE_HOSTS = new Set(["freesound.org", "www.jamendo.com", "commons.wikimedia.org"]);
+function httpsUrl(url, hosts) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" && (!hosts || hosts.has(parsed.hostname))
+      ? oneLine(parsed.href)
+      : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Openverse could not answer (offline, rate limited, server error): stop asking it this run. */
+export class OpenverseUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OpenverseUnavailableError";
+  }
+}
+
+function usable(result) {
+  return (
+    OPENVERSE_SFX_LICENSES.has(result?.license) &&
+    PLAYABLE_FILETYPES.has(result.filetype) &&
+    typeof result.url === "string" &&
+    result.url.startsWith("https://") &&
+    Number.isFinite(result.duration) &&
+    result.duration > 0 &&
+    result.duration <= MAX_SFX_MS
+  );
+}
+
+// Lower is better: relevance position, then seconds past a typical cue length, then CC0 over CC BY.
+function penalty(result, position) {
+  const longBy = Math.max(0, result.duration - IDEAL_SFX_MS) / 1000;
+  return position + longBy + (result.license === "by" ? BY_PENALTY : 0);
+}
+
+/** Best usable sound in Openverse's relevance-ordered results, or null. */
+export function pickOpenverseSfx(results) {
+  let best = null;
+  results.forEach((result, position) => {
+    if (!usable(result)) return;
+    const score = penalty(result, position);
+    if (!best || score < best.score) best = { result, score };
+  });
+  if (!best) return null;
+  const r = best.result;
+  return {
+    id: r.id,
+    url: r.url,
+    ext: `.${r.filetype}`,
+    title: oneLine(r.title),
+    creator: oneLine(r.creator),
+    license: r.license,
+    licenseUrl: httpsUrl(r.license_url),
+    sourceUrl: httpsUrl(r.foreign_landing_url, SOURCE_HOSTS),
+    credit: oneLine(r.attribution),
+    durationS: Math.round(r.duration) / 1000,
+  };
+}
+
+/** Best licensed sound effect for `query`, null on no match; throws OpenverseUnavailableError. */
+export async function searchOpenverseSfx(query, { fetchImpl = fetch } = {}) {
+  const params = new URLSearchParams({
+    q: query,
+    page_size: "20",
+    license: [...OPENVERSE_SFX_LICENSES].join(","),
+  });
+  let response;
+  try {
+    response = await fetchImpl(`${OPENVERSE_AUDIO_URL}?${params}`, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(SEARCH_TIMEOUT_MS),
+    });
+  } catch (error) {
+    throw new OpenverseUnavailableError(`Openverse unreachable (${error.message})`);
+  }
+  if (response.status === 429)
+    throw new OpenverseUnavailableError("Openverse rate limit reached (HTTP 429)");
+  if (!response.ok) throw new OpenverseUnavailableError(`Openverse HTTP ${response.status}`);
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new OpenverseUnavailableError("Openverse returned non-JSON");
+  }
+  return pickOpenverseSfx(Array.isArray(body?.results) ? body.results : []);
+}
+
+/** Record a CC BY sound's credit for `file` in the project's credits file (one line per file). */
+export function writeSfxCredit(creditsPath, file, sound) {
+  if (sound.license !== "by") return;
+  // The sound may come from a saved record, not this run's pick: clean it again here.
+  const sourceUrl = httpsUrl(sound.sourceUrl, SOURCE_HOSTS);
+  const source = sourceUrl ? ` Source: ${sourceUrl}` : "";
+  const line = `- \`${file}\`: ${oneLine(sound.credit)}${source}`;
+  let prior = "";
+  try {
+    prior = readFileSync(creditsPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const kept = prior
+    .split("\n")
+    .filter((l) => l.startsWith("- ") && !l.startsWith(`- \`${file}\`:`));
+  const header =
+    "# Sound effect credits\n\nThese sounds are licensed CC BY: credit them wherever the video is published.\n\n";
+  mkdirSync(dirname(creditsPath), { recursive: true });
+  writeFileSync(creditsPath, `${header}${[...kept, line].join("\n")}\n`);
+}

package/skills/media-use/scripts/lib/openverse.test.mjs

@@ -0,0 +1,219 @@
+import { strict as assert } from "node:assert";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  OpenverseUnavailableError,
+  pickOpenverseSfx,
+  searchOpenverseSfx,
+  writeSfxCredit,
+} from "./openverse.mjs";
+
+const result = (overrides = {}) => ({
+  id: "ov-1",
+  title: "Deep Whoosh",
+  creator: "Kinoton",
+  license: "cc0",
+  license_url: "https://creativecommons.org/publicdomain/zero/1.0/",
+  foreign_landing_url: "https://freesound.org/people/Kinoton/sounds/351256",
+  url: "https://cdn.freesound.org/previews/351/351256_2247456-hq.mp3",
+  filetype: "mp3",
+  duration: 1200,
+  attribution: '"Deep Whoosh" by Kinoton is marked with CC0 1.0.',
+  ...overrides,
+});
+
+test("only CC0 and CC BY sounds are ever picked", () => {
+  for (const license of ["by-nc", "by-sa", "by-nd", "by-nc-sa", "by-nc-nd", "pdm", "sampling+"])
+    assert.equal(pickOpenverseSfx([result({ license })]), null, license);
+  assert.equal(pickOpenverseSfx([result({ license: "by" })]).license, "by");
+  assert.equal(pickOpenverseSfx([result({ license: "cc0" })]).license, "cc0");
+});
+
+test("sounds too long for a cue, or not playable, are skipped", () => {
+  assert.equal(pickOpenverseSfx([result({ duration: 15001 })]), null);
+  assert.equal(pickOpenverseSfx([result({ duration: null })]), null);
+  assert.equal(pickOpenverseSfx([result({ filetype: "aiff" })]), null);
+  assert.equal(pickOpenverseSfx([result({ url: "http://insecure.test/a.mp3" })]), null);
+});
+
+test("ranking keeps relevance order, then prefers short clips and CC0 over CC BY", () => {
+  const pick = (results) => pickOpenverseSfx(results).id;
+  assert.equal(pick([result({ id: "first" }), result({ id: "second" })]), "first");
+  assert.equal(pick([result({ id: "long", duration: 12000 }), result({ id: "short" })]), "short");
+  assert.equal(pick([result({ id: "by", license: "by" }), result({ id: "cc0" })]), "cc0");
+  assert.equal(
+    pick([
+      result({ id: "by", license: "by" }),
+      ...Array(3).fill(result({ license: "by-nc" })),
+      result({ id: "cc0" }),
+    ]),
+    "by",
+    "a much more relevant CC BY sound still wins",
+  );
+});
+
+test("a pick carries what the project needs to play and credit it", () => {
+  assert.deepEqual(pickOpenverseSfx([result({ license: "by", filetype: "wav", duration: 450 })]), {
+    id: "ov-1",
+    url: "https://cdn.freesound.org/previews/351/351256_2247456-hq.mp3",
+    ext: ".wav",
+    title: "Deep Whoosh",
+    creator: "Kinoton",
+    license: "by",
+    licenseUrl: "https://creativecommons.org/publicdomain/zero/1.0/",
+    sourceUrl: "https://freesound.org/people/Kinoton/sounds/351256",
+    credit: '"Deep Whoosh" by Kinoton is marked with CC0 1.0.',
+    durationS: 0.45,
+  });
+});
+
+test("Openverse text is kept to one bounded line, and only https links survive", () => {
+  const pick = pickOpenverseSfx([
+    result({
+      license: "by",
+      title: "Pop\n# Heading",
+      attribution: `"Pop" by Ana.\n- \`assets/sfx/other.mp3\`: forged credit\r\u0007${"x".repeat(400)}`,
+      foreign_landing_url: "javascript:alert(1)",
+      license_url: "http://creativecommons.org/licenses/by/4.0/",
+    }),
+  ]);
+  assert.equal(pick.title, "Pop # Heading");
+  assert.equal(pick.credit.length, 300);
+  assert.ok(!/\p{Cc}/u.test(pick.credit), "no line breaks or control characters");
+  assert.equal(pick.sourceUrl, "");
+  assert.equal(pick.licenseUrl, "");
+});
+
+test("search asks Openverse for JSON and only the allowed licences", async () => {
+  const calls = [];
+  const sound = await searchOpenverseSfx("ui click", {
+    fetchImpl: async (url, init) => {
+      calls.push({ url: new URL(url), init });
+      return Response.json({ results: [result({ license: "by-nc" }), result({ id: "ok" })] });
+    },
+  });
+  assert.equal(sound.id, "ok", "the licence field is checked even on a filtered response");
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].url.origin + calls[0].url.pathname, "https://api.openverse.org/v1/audio/");
+  assert.equal(calls[0].url.searchParams.get("q"), "ui click");
+  assert.equal(calls[0].url.searchParams.get("license"), "cc0,by");
+  assert.equal(calls[0].init.headers.Accept, "application/json");
+});
+
+test("no usable result is a miss, not an error", async () => {
+  const fetchImpl = async () => Response.json({ results: [] });
+  assert.equal(await searchOpenverseSfx("nothing", { fetchImpl }), null);
+});
+
+test("rate limits, server errors, bad bodies and network failures make Openverse unavailable", async () => {
+  const failures = [
+    [async () => new Response("slow down", { status: 429 }), /rate limit/],
+    [async () => new Response("down", { status: 503 }), /HTTP 503/],
+    [async () => new Response("<html>"), /non-JSON/],
+    [
+      async () => {
+        throw new TypeError("fetch failed");
+      },
+      /unreachable \(fetch failed\)/,
+    ],
+  ];
+  for (const [fetchImpl, message] of failures)
+    await assert.rejects(searchOpenverseSfx("whoosh", { fetchImpl }), (error) => {
+      assert.ok(error instanceof OpenverseUnavailableError);
+      assert.match(error.message, message);
+      return true;
+    });
+});
+
+test("credits list each CC BY file once and leave CC0 out", () => {
+  const dir = mkdtempSync(join(tmpdir(), "openverse-credits-"));
+  try {
+    const path = join(dir, "assets", "sfx", "CREDITS.md");
+    const by = {
+      license: "by",
+      credit: '"Pop" by Ana is licensed under CC BY 4.0.',
+      sourceUrl: "https://freesound.org/s/1",
+    };
+    writeSfxCredit(path, "assets/sfx/zap.mp3", { ...by, license: "cc0" });
+    assert.throws(() => readFileSync(path), /ENOENT/);
+    writeSfxCredit(path, "assets/sfx/pop.mp3", by);
+    writeSfxCredit(path, "assets/sfx/pop.mp3", {
+      ...by,
+      credit: '"Pop 2" by Ana is licensed under CC BY 4.0.',
+    });
+    writeSfxCredit(path, "assets/sfx/ding.mp3", by);
+    const lines = readFileSync(path, "utf8")
+      .split("\n")
+      .filter((l) => l.startsWith("- "));
+    assert.deepEqual(lines, [
+      '- `assets/sfx/pop.mp3`: "Pop 2" by Ana is licensed under CC BY 4.0. Source: https://freesound.org/s/1',
+      '- `assets/sfx/ding.mp3`: "Pop" by Ana is licensed under CC BY 4.0. Source: https://freesound.org/s/1',
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a credit with no https source link is written without one", () => {
+  const dir = mkdtempSync(join(tmpdir(), "openverse-credits-"));
+  try {
+    const path = join(dir, "CREDITS.md");
+    writeSfxCredit(path, "assets/sfx/pop.mp3", { license: "by", credit: "c.", sourceUrl: "" });
+    assert.match(readFileSync(path, "utf8"), /\n- `assets\/sfx\/pop\.mp3`: c\.\n$/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a hostile credit is written as one safe line, with no link off Openverse's providers", () => {
+  const dir = mkdtempSync(join(tmpdir(), "openverse-credits-"));
+  try {
+    const path = join(dir, "CREDITS.md");
+    const hostile = `"Pop" by Ana.\n- \`assets/sfx/x.mp3\`: forged [click](https://evil.test) <img src=x> \\${"x".repeat(5000)}`;
+    for (const sourceUrl of [
+      "javascript:alert(1)",
+      "https://evil.test/a",
+      "https://freesound.org/s/1\n- forged",
+    ]) {
+      writeSfxCredit(path, "assets/sfx/pop.mp3", { license: "by", credit: hostile, sourceUrl });
+      const lines = readFileSync(path, "utf8")
+        .split("\n")
+        .filter((l) => l.startsWith("- "));
+      assert.equal(lines.length, 1, sourceUrl);
+      assert.ok(
+        lines[0].startsWith('- `assets/sfx/pop.mp3`: "Pop" by Ana. - '),
+        lines[0].slice(0, 80),
+      );
+      assert.ok(
+        !/[\p{Cc}`[\]<>\\]/u.test(lines[0].slice("- `assets/sfx/pop.mp3`:".length)),
+        sourceUrl,
+      );
+      assert.ok(lines[0].length < 400, "bounded");
+      assert.doesNotMatch(lines[0], /javascript:|evil\.test\/a/);
+    }
+    assert.match(readFileSync(path, "utf8"), /Source: https:\/\/freesound\.org\/s\/1-%20forged\n$/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("earlier credit lines survive a new credit", () => {
+  const dir = mkdtempSync(join(tmpdir(), "openverse-credits-"));
+  try {
+    const path = join(dir, "CREDITS.md");
+    writeFileSync(path, "# Sound effect credits\n\n- `assets/sfx/old.mp3`: kept\n");
+    writeSfxCredit(path, "assets/sfx/new.mp3", {
+      license: "by",
+      credit: "c.",
+      sourceUrl: "https://freesound.org/s/2",
+    });
+    assert.match(
+      readFileSync(path, "utf8"),
+      /- `assets\/sfx\/old\.mp3`: kept\n- `assets\/sfx\/new\.mp3`: c\. Source: https:\/\/freesound\.org\/s\/2\n$/,
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/skills/media-use/scripts/lib/parakeet-words.test.mjs

@@ -0,0 +1,44 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mergeTokensToWords } from "./parakeet-words.mjs";
+
+test("mergeTokensToWords joins sub-word tokens on the space boundary", () => {
+  const parakeet = {
+    text: "Hello everyone. Um,",
+    sentences: [
+      {
+        tokens: [
+          { text: " H", start: 0.0, end: 0.24 },
+          { text: "ello", start: 0.24, end: 0.48 },
+          { text: " everyone.", start: 0.48, end: 1.28 },
+          { text: " Um,", start: 1.28, end: 1.92 },
+        ],
+      },
+    ],
+  };
+  const { words } = mergeTokensToWords(parakeet);
+  assert.deepEqual(words, [
+    { text: "Hello", start: 0.0, end: 0.48 },
+    { text: "everyone.", start: 0.48, end: 1.28 },
+    { text: "Um,", start: 1.28, end: 1.92 },
+  ]);
+});
+
+test("mergeTokensToWords spans multiple sentences and drops empties", () => {
+  const parakeet = {
+    text: "Hi there",
+    sentences: [
+      { tokens: [{ text: "Hi", start: 0, end: 0.2 }] },
+      { tokens: [{ text: " there", start: 0.5, end: 0.9 }] },
+    ],
+  };
+  const { words } = mergeTokensToWords(parakeet);
+  assert.equal(words.length, 2);
+  assert.equal(words[1].text, "there");
+  assert.equal(words[1].start, 0.5);
+});
+
+test("mergeTokensToWords tolerates missing sentences/tokens", () => {
+  assert.deepEqual(mergeTokensToWords({}).words, []);
+  assert.deepEqual(mergeTokensToWords({ sentences: [{}] }).words, []);
+});