hyperframes 0.8.169 → 0.8.170

package/dist/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/dist/skills/media-use/scripts/lib/registry.mjs

@@ -10,6 +10,8 @@
 // own auth. Providers, by type:
 //   - heygen CLI: catalog + TTS, first for every type it serves (OAuth free
 //     allowance first, then the user's HeyGen billing path)
+//   - Openverse: free, keyless sound effects (CC0 / CC BY), with the bundled
+//     library as the offline fallback
 //   - mflux: local FLUX-class image gen, spec-selected to the machine's RAM
 //     (free, private, offline once cached)
 //   - codex CLI: image gen on the user's ChatGPT sub — the better-quality upsell
@@ -21,7 +23,7 @@
 // (e.g. "make an image with codex").
 
 import { bgmProvider } from "./bgm-provider.mjs";
-import { sfxProvider } from "./sfx-provider.mjs";
+import { OPENVERSE_SFX_PROVIDER, sfxProvider } from "./sfx-provider.mjs";
 import { bundledSfxProvider } from "./bundled-sfx-provider.mjs";
 import { imageProvider, iconProvider } from "./image-provider.mjs";
 import { brandProvider } from "./brand-provider.mjs";
@@ -46,8 +48,8 @@ const P = (name, caps) => ({ name, network: true, paid: true, ...caps }); // rem
 const REGISTRY = {
   bgm: [N("heygen.audio.sounds", { search: bgmProvider.search })],
   sfx: [
+    N(OPENVERSE_SFX_PROVIDER, { search: sfxProvider.search }),
     A("bundled.sfx", { search: bundledSfxProvider.search }),
-    N("heygen.audio.sounds", { search: sfxProvider.search }),
   ],
   image: [
     N("heygen.asset.search", { search: imageProvider.search }),

package/dist/skills/media-use/scripts/lib/registry.test.mjs

@@ -32,18 +32,18 @@ test("listTypes exposes the v2 media types", () => {
   }
 });
 
-test("heygen provider is first for every type it serves except bundled sfx", () => {
+test("heygen provider is first for every type it serves", () => {
   for (const t of ["bgm", "image", "icon"]) {
     const first = getProviders(t)[0];
     assert.ok(first, `no enabled provider for ${t}`);
     assert.match(first.name, /^heygen/, `${t} first provider is ${first.name}`);
   }
-  assert.equal(getProviders("sfx")[0].name, "bundled.sfx");
+  assert.ok(!getProviders("sfx").some((p) => p.name.startsWith("heygen")), "sfx never asks HeyGen");
 });
 
-test("sanctioned providers only: heygen, local mflux/kokoro/ltx, codex, design spec, logo tiers", () => {
+test("sanctioned providers only: heygen, Openverse, local mflux/kokoro/ltx, codex, design spec, logo tiers", () => {
   const allowed =
-    /^heygen|^bundled\.sfx$|^mflux\.local$|^kokoro\.local$|^ltx\.local$|^codex\.image_gen$|^design_spec$|^thesvg$|^github\.avatar$|^favicon\.ddg$|^color_grade\.local$|^cube_lut\.local$/;
+    /^heygen|^openverse\.audio$|^bundled\.sfx$|^mflux\.local$|^kokoro\.local$|^ltx\.local$|^codex\.image_gen$|^design_spec$|^thesvg$|^github\.avatar$|^favicon\.ddg$|^color_grade\.local$|^cube_lut\.local$/;
   for (const t of listTypes()) {
     for (const p of getProviders(t)) {
       assert.ok(allowed.test(p.name), `${t} lists unsanctioned provider: ${p.name}`);
@@ -85,13 +85,14 @@ test("video cascade: HeyGen first, LTX local fallback, generate-only", async ()
   assert.equal(await runCapability("video", "search", "x", {}), null);
 });
 
-test("sfx cascade: bundled library first, HeyGen catalog remains the network fallback", () => {
+test("sfx cascade: Openverse first, the bundled library is the offline fallback", () => {
   const ps = getProviders("sfx");
-  assert.equal(ps[0].name, "bundled.sfx");
-  assert.equal(typeof ps[0].search, "function");
-  assert.ok(!ps[0].network, "bundled SFX remain available offline");
-  assert.equal(ps[1].name, "heygen.audio.sounds");
-  assert.ok(ps[1].network, "HeyGen SFX catalog is network-only");
+  assert.deepEqual(
+    ps.map((p) => p.name),
+    ["openverse.audio", "bundled.sfx"],
+  );
+  assert.ok(ps[0].network && !ps[0].paid, "Openverse is free and network-only");
+  assert.ok(!ps[1].network, "bundled SFX remain available offline");
 });
 
 test("ctx.provider forces one generator (e.g. 'make an image WITH codex')", async () => {
@@ -201,9 +202,8 @@ test("providerTierFor reports the registry's own A/N/P declaration", () => {
 });
 
 test("providerTierFor agrees across every type that declares the same name", () => {
-  // heygen.audio.sounds serves both bgm and sfx; heygen.asset.search serves both
-  // image and icon. A name whose tier depended on the media type would make the
-  // telemetry property meaningless.
+  // heygen.asset.search serves both image and icon. A name whose tier depended
+  // on the media type would make the telemetry property meaningless.
   const byName = new Map();
   for (const type of listTypes()) {
     for (const name of providerNamesFor(type)) {

package/dist/skills/media-use/scripts/lib/sfx-provider.mjs

@@ -1,22 +1,32 @@
-import { heygenSearch } from "./heygen-search.mjs";
+import { OpenverseUnavailableError, searchOpenverseSfx } from "./openverse.mjs";
+
+export const OPENVERSE_SFX_PROVIDER = "openverse.audio";
 
 export const sfxProvider = {
   async search(intent) {
-    const results = heygenSearch("audio sounds list", intent, {
-      type: "sound_effects",
-      minScore: 0.4,
-    });
-    if (!results) return null;
-    const best = results[0];
+    let sound;
+    try {
+      sound = await searchOpenverseSfx(intent);
+    } catch (error) {
+      if (!(error instanceof OpenverseUnavailableError)) throw error;
+      console.error(`media-use: ${error.message}; using the bundled sound effects`);
+      return null;
+    }
+    if (!sound) return null;
     return {
-      url: best.audio_url,
+      url: sound.url,
+      ext: sound.ext,
       source: "search",
-      // ext derived from audio_url by resolve.mjs — catalog SFX are .mp3 or .wav
       metadata: {
-        description: best.description || best.name || intent,
-        duration: best.duration || null,
-        provider: "heygen.audio.sounds",
-        provenance: { track_id: best.id, score: best.score, query: intent },
+        description: sound.title || intent,
+        duration: sound.durationS,
+        provider: OPENVERSE_SFX_PROVIDER,
+        provenance: {
+          openverse_id: sound.id,
+          license: sound.license,
+          credit: sound.credit,
+          source_url: sound.sourceUrl,
+        },
       },
     };
   },

package/dist/skills/media-use/scripts/resolve.mjs

@@ -12,6 +12,8 @@ import {
   findByPrompt,
   findByEntity,
   nextId,
+  typeDirPath,
+  withMediaLock,
   withReservedFile,
   withReservedFileSync,
 } from "./lib/manifest.mjs";
@@ -55,6 +57,8 @@ import {
   versionLessThan,
 } from "./lib/heygen-cli.mjs";
 import { BundledSfxAssetsError, inspectBundledSfxAssets } from "./lib/bundled-sfx-provider.mjs";
+import { OPENVERSE_SFX_PROVIDER } from "./lib/sfx-provider.mjs";
+import { writeSfxCredit } from "./lib/openverse.mjs";
 import {
   fetchMediaVectors,
   mediaVectorRows,
@@ -441,57 +445,43 @@ async function run() {
     return resolveColor(type, intent, { projectDir });
   }
 
-  // SFX search is bundled, local-index, then HeyGen.
+  // SFX search is Openverse, the bundled library, then the local media index.
   let searchResult = null;
   let providerFailure = null;
   let localIndexFailure = null;
   try {
-    if (type === "sfx" && !args.provider) {
-      searchResult = await runCapability(type, "search", intent, {
-        ...ctx,
-        provider: "bundled.sfx",
-      });
-      if (!searchResult && !localOnly) {
-        const registry =
-          process.env.HYPERFRAMES_REGISTRY ||
-          "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry";
-        try {
-          await fetchMediaVectors(registry);
-          const ranked = await rankMediaRowsWithVectors(
-            intent,
-            mediaVectorRows().filter((row) => row.kind === "sfx"),
-          );
-          const row = ranked.rows[0];
-          const candidates = row
-            ? [resolve(row.file), join(import.meta.dirname, "..", "..", "..", row.file)]
-            : [];
-          const localPath = candidates.find((candidate) => existsSync(candidate));
-          if (row && localPath) {
-            searchResult = {
-              localPath,
-              ext: extname(localPath),
-              source: "local-index",
-              metadata: {
-                description: row.description,
-                duration: row.duration ?? null,
-                provider: "catalog.local",
-                provenance: { library_key: row.id, tier: ranked.tier },
-              },
-            };
-          }
-        } catch (error) {
-          localIndexFailure = error;
+    searchResult = await runCapability(type, "search", intent, ctx);
+    if (!searchResult && type === "sfx" && !args.provider && !localOnly) {
+      const registry =
+        process.env.HYPERFRAMES_REGISTRY ||
+        "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry";
+      try {
+        await fetchMediaVectors(registry);
+        const ranked = await rankMediaRowsWithVectors(
+          intent,
+          mediaVectorRows().filter((row) => row.kind === "sfx"),
+        );
+        const row = ranked.rows[0];
+        const candidates = row
+          ? [resolve(row.file), join(import.meta.dirname, "..", "..", "..", row.file)]
+          : [];
+        const localPath = candidates.find((candidate) => existsSync(candidate));
+        if (row && localPath) {
+          searchResult = {
+            localPath,
+            ext: extname(localPath),
+            source: "local-index",
+            metadata: {
+              description: row.description,
+              duration: row.duration ?? null,
+              provider: "catalog.local",
+              provenance: { library_key: row.id, tier: ranked.tier },
+            },
+          };
         }
+      } catch (error) {
+        localIndexFailure = error;
       }
-      if (!searchResult) searchResult = await runCapability(type, "search", intent, ctx);
-      // Keep HeyGen remediation diagnostics while bundled remains authoritative.
-      else if (!localOnly)
-        await runCapability(type, "search", intent, {
-          ...ctx,
-          provider: "heygen.audio.sounds",
-        });
-    } else {
-      searchResult = await runCapability(type, "search", intent, ctx);
     }
   } catch (error) {
     providerFailure = error;
@@ -602,16 +592,6 @@ async function run() {
     },
   };
 
-  const heygenRemediation = consumeHeygenRemediation();
-  if (
-    searchResult.metadata?.provider === "bundled.sfx" &&
-    !localOnly &&
-    !args.provider &&
-    heygenRemediation
-  ) {
-    record.advisory = heygenRemediation;
-  }
-
   appendRecord(projectDir, record);
   regenerateIndex(projectDir);
   // Promote fetched assets into the global cache for reuse.
@@ -1304,6 +1284,16 @@ async function reuseGlobal(shaArg) {
 }
 
 async function result(record, source) {
+  const { provider, license, credit, source_url: sourceUrl } = record.provenance ?? {};
+  // Under the media lock: two resolves at once each read, then rewrite, the whole credits file.
+  if (provider === OPENVERSE_SFX_PROVIDER)
+    withMediaLock(projectDir, () =>
+      writeSfxCredit(join(typeDirPath(projectDir, "sfx"), "CREDITS.md"), record.path, {
+        license,
+        credit,
+        sourceUrl,
+      }),
+    );
   // Non-PII usage event: which media type, how it resolved, which provider won.
   // Never the intent text or paths. Awaited so a short-lived run flushes it.
   await track("media_use_resolve", {

package/dist/{skills-FSZK6FIG.js → skills-ONFYYL6R.js}

@@ -6,8 +6,8 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   trackSkillsInstallSkipped
-} from "./chunk-FQJDV2RI.js";
-import "./chunk-FSX7GTBB.js";
+} from "./chunk-4B6PUT4R.js";
+import "./chunk-FSP2JNAP.js";
 import {
   diag
 } from "./chunk-VWG7OQKU.js";
@@ -35,15 +35,15 @@ import {
   isCoreSkill,
   presentSkills,
   pruneOrphanedLockEntries
-} from "./chunk-VCXVZRR2.js";
+} from "./chunk-EHDKCMKX.js";
 import {
   withMeta
-} from "./chunk-K5PU5ISL.js";
+} from "./chunk-GG3V5BHG.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-BNEKKUPG.js";
+import "./chunk-UQPH3Y45.js";
 import {
   buildNpxCommand
 } from "./chunk-6BEFEWFB.js";

package/dist/{skillsUpdateCheck-3354HXDJ.js → skillsUpdateCheck-JTHZOHRT.js}

@@ -9,13 +9,13 @@ import {
   printSkillsUpdateNotice,
   refreshSkillsCache,
   skillsCheckDue
-} from "./chunk-VCXVZRR2.js";
-import "./chunk-K5PU5ISL.js";
+} from "./chunk-EHDKCMKX.js";
+import "./chunk-GG3V5BHG.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-BNEKKUPG.js";
+import "./chunk-UQPH3Y45.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-M2WBOQ2Q.js";
 export {