hyperframes 0.8.58 → 0.8.59

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

@@ -0,0 +1,388 @@
+import { strict as assert } from "node:assert";
+import {
+  mkdtempSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  readManifest,
+  appendRecord,
+  findByPrompt,
+  findByEntity,
+  nextId,
+  allocateId,
+  withReservedFileSync,
+  normalizePrompt,
+  manifestPath,
+  mediaDir,
+  typeDirPath,
+  typeSubdir,
+} from "./manifest.mjs";
+import { regenerateIndex, generateIndexContent } from "./index-gen.mjs";
+import {
+  contentHash,
+  cachePut,
+  cacheGet,
+  cacheGetByEntity,
+  importFromCache,
+  promote,
+} from "./cache.mjs";
+
+let tmp;
+
+function setup() {
+  tmp = mkdtempSync(join(tmpdir(), "mu-test-"));
+}
+
+function cleanup() {
+  if (tmp) rmSync(tmp, { recursive: true, force: true });
+}
+
+function makeRecord(overrides = {}) {
+  return {
+    id: "bgm_001",
+    type: "bgm",
+    path: ".media/audio/bgm/bgm_001.wav",
+    source: "search",
+    description: "soft minimal ambient",
+    duration: 11,
+    provenance: { provider: "heygen.audio.sounds", prompt: "subtle tech" },
+    ...overrides,
+  };
+}
+
+function runTests() {
+  const tests = [];
+
+  function test(name, fn) {
+    tests.push({ name, fn });
+  }
+
+  // --- manifest.mjs ---
+
+  test("readManifest returns empty array when no manifest exists", () => {
+    setup();
+    const result = readManifest(tmp);
+    assert.deepStrictEqual(result, []);
+    cleanup();
+  });
+
+  test("appendRecord writes valid JSONL and readManifest parses it back", () => {
+    setup();
+    const record = makeRecord();
+    appendRecord(tmp, record);
+    const records = readManifest(tmp);
+    assert.equal(records.length, 1);
+    assert.deepStrictEqual(records[0], record);
+    cleanup();
+  });
+
+  test("appendRecord creates .media/ and type subdirs on first write", () => {
+    setup();
+    appendRecord(tmp, makeRecord());
+    assert.ok(existsSync(mediaDir(tmp)));
+    assert.ok(existsSync(typeDirPath(tmp, "bgm")));
+    cleanup();
+  });
+
+  test("lut and grade artifacts use the shared .media/luts subdir", () => {
+    assert.equal(typeSubdir("lut"), "luts");
+    assert.equal(typeSubdir("grade"), "luts");
+
+    setup();
+    const allocated = allocateId(tmp, "lut", ".cube");
+    assert.equal(allocated.localPath, ".media/luts/lut_001.cube");
+    assert.ok(existsSync(join(tmp, allocated.localPath)));
+    cleanup();
+  });
+
+  test("appendRecord appends multiple records", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ id: "bgm_001" }));
+    appendRecord(tmp, makeRecord({ id: "bgm_002", provenance: { prompt: "energetic" } }));
+    const records = readManifest(tmp);
+    assert.equal(records.length, 2);
+    assert.equal(records[0].id, "bgm_001");
+    assert.equal(records[1].id, "bgm_002");
+    cleanup();
+  });
+
+  test("findByPrompt returns exact-match record", () => {
+    setup();
+    appendRecord(tmp, makeRecord());
+    const found = findByPrompt(tmp, "subtle tech", "bgm");
+    assert.ok(found);
+    assert.equal(found.id, "bgm_001");
+    cleanup();
+  });
+
+  test("findByPrompt returns null on miss", () => {
+    setup();
+    appendRecord(tmp, makeRecord());
+    assert.equal(findByPrompt(tmp, "nonexistent", "bgm"), null);
+    cleanup();
+  });
+
+  test("findByPrompt filters by type", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ type: "sfx" }));
+    assert.equal(findByPrompt(tmp, "subtle tech", "bgm"), null);
+    assert.ok(findByPrompt(tmp, "subtle tech", "sfx"));
+    cleanup();
+  });
+
+  test("findByPrompt matches across case and whitespace variants", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ provenance: { provider: "x", prompt: "calm ambient piano" } }));
+    assert.ok(findByPrompt(tmp, "Calm Ambient Piano", "bgm"), "case-insensitive");
+    assert.ok(findByPrompt(tmp, "  calm   ambient  piano ", "bgm"), "whitespace-insensitive");
+    assert.equal(findByPrompt(tmp, "calm ambient guitar", "bgm"), null, "still a real miss");
+    cleanup();
+  });
+
+  test("normalizePrompt trims, lowercases, collapses whitespace", () => {
+    assert.equal(normalizePrompt("  Upbeat   Tech  Launch "), "upbeat tech launch");
+    assert.equal(normalizePrompt(null), "");
+  });
+
+  test("allocateId reserves the id on disk so a pre-append caller can't reuse it (MU-23)", () => {
+    setup();
+    const a = allocateId(tmp, "bgm", ".wav");
+    assert.equal(a.id, "bgm_001");
+    assert.ok(existsSync(join(tmp, a.localPath)), "placeholder reserved on disk");
+    // Second allocation BEFORE any manifest append (the download window) must not
+    // hand back bgm_001 again, even with a different extension.
+    const b = allocateId(tmp, "bgm", ".mp3");
+    assert.equal(b.id, "bgm_002");
+    assert.notEqual(a.localPath, b.localPath);
+    // Lock file is released (not left behind).
+    assert.ok(!existsSync(join(tmp, ".media", ".lock")), "lock released");
+    cleanup();
+  });
+
+  test("allocateId continues past the highest manifest id", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ id: "bgm_005" }));
+    assert.equal(allocateId(tmp, "bgm", ".wav").id, "bgm_006");
+    cleanup();
+  });
+
+  test("failed reservation rollback preserves another completed reservation", () => {
+    setup();
+    const kept = withReservedFileSync(tmp, "bgm", ".wav", (reservation) => {
+      writeFileSync(reservation.fullPath, "completed asset");
+      return reservation;
+    });
+
+    assert.throws(
+      () =>
+        withReservedFileSync(tmp, "bgm", ".wav", () => {
+          throw new Error("populate failed");
+        }),
+      /populate failed/,
+    );
+
+    assert.equal(kept.id, "bgm_001");
+    assert.equal(readFileSync(kept.fullPath, "utf8"), "completed asset");
+    assert.deepStrictEqual(readdirSync(typeDirPath(tmp, "bgm")), ["bgm_001.wav"]);
+    assert.equal(allocateId(tmp, "bgm", ".wav").id, "bgm_002");
+    cleanup();
+  });
+
+  test("empty reservation result releases the placeholder", () => {
+    setup();
+    assert.equal(
+      withReservedFileSync(tmp, "image", ".jpg", () => null),
+      null,
+    );
+    assert.deepStrictEqual(readdirSync(typeDirPath(tmp, "image")), []);
+    cleanup();
+  });
+
+  test("findByEntity matches case-insensitively", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ entity: "GitHub", type: "icon" }));
+    assert.ok(findByEntity(tmp, "github"));
+    assert.ok(findByEntity(tmp, "GITHUB"));
+    assert.equal(findByEntity(tmp, "gitlab"), null);
+    cleanup();
+  });
+
+  test("nextId generates sequential ids", () => {
+    setup();
+    assert.equal(nextId(tmp, "bgm"), "bgm_001");
+    appendRecord(tmp, makeRecord({ id: "bgm_001" }));
+    assert.equal(nextId(tmp, "bgm"), "bgm_002");
+    appendRecord(tmp, makeRecord({ id: "bgm_002" }));
+    assert.equal(nextId(tmp, "bgm"), "bgm_003");
+    cleanup();
+  });
+
+  // --- index-gen.mjs ---
+
+  test("regenerateIndex produces plain-column table", () => {
+    setup();
+    appendRecord(tmp, makeRecord());
+    regenerateIndex(tmp);
+    const content = readFileSync(join(tmp, ".media", "index.md"), "utf8");
+    assert.ok(content.includes("# .media · 1 asset"));
+    assert.ok(content.includes("bgm_001"));
+    assert.ok(content.includes("soft minimal ambient"));
+    assert.ok(content.includes("11s"));
+    cleanup();
+  });
+
+  test("regenerateIndex handles empty manifest", () => {
+    setup();
+    mkdirSync(join(tmp, ".media"), { recursive: true });
+    writeFileSync(manifestPath(tmp), "");
+    regenerateIndex(tmp);
+    const content = readFileSync(join(tmp, ".media", "index.md"), "utf8");
+    assert.ok(content.includes("# .media · 0 assets"));
+    cleanup();
+  });
+
+  test("generateIndexContent includes dims for images", () => {
+    const records = [
+      makeRecord({ id: "img_001", type: "image", width: 1920, height: 1080, duration: null }),
+    ];
+    const content = generateIndexContent(records);
+    assert.ok(content.includes("1920×1080"));
+    assert.ok(content.includes("img_001"));
+  });
+
+  test("regenerateIndex matches manifest content after multiple writes", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ id: "bgm_001" }));
+    appendRecord(
+      tmp,
+      makeRecord({ id: "sfx_001", type: "sfx", description: "whoosh", duration: 3 }),
+    );
+    regenerateIndex(tmp);
+    const content = readFileSync(join(tmp, ".media", "index.md"), "utf8");
+    assert.ok(content.includes("# .media · 2 assets"));
+    assert.ok(content.includes("bgm_001"));
+    assert.ok(content.includes("sfx_001"));
+    assert.ok(content.includes("whoosh"));
+    cleanup();
+  });
+
+  // --- cache.mjs ---
+
+  test("cacheGet returns null when cache is empty", () => {
+    const result = cacheGet("nonexistent prompt", "bgm");
+    assert.equal(result, null);
+  });
+
+  test("cachePut + cacheGet round-trip", () => {
+    setup();
+    const filePath = join(tmp, "test.wav");
+    writeFileSync(filePath, "fake audio bytes for testing");
+    const record = makeRecord({ provenance: { prompt: "cache test" } });
+
+    const { sha } = cachePut(filePath, record);
+    assert.ok(sha);
+    assert.equal(sha.length, 64);
+
+    const found = cacheGet("cache test", "bgm");
+    assert.ok(found);
+    assert.equal(found.reusable, true);
+    assert.equal(found.sha, sha);
+
+    // cross-project reuse must survive trivial prompt variation, not just
+    // byte-identical intents (the whole point of normalizePrompt).
+    assert.ok(cacheGet("  Cache   Test ", "bgm"), "cacheGet is case/whitespace-insensitive");
+    cleanup();
+  });
+
+  test("cacheGetByEntity finds cached asset", () => {
+    setup();
+    const filePath = join(tmp, "logo.png");
+    writeFileSync(filePath, "fake png bytes");
+    const record = makeRecord({
+      type: "icon",
+      entity: "TestCorp",
+      provenance: { prompt: "TestCorp logo" },
+    });
+
+    cachePut(filePath, record);
+    const found = cacheGetByEntity("testcorp");
+    assert.ok(found);
+    assert.equal(found.entity, "TestCorp");
+    cleanup();
+  });
+
+  test("contentHash is deterministic", () => {
+    setup();
+    const filePath = join(tmp, "det.bin");
+    writeFileSync(filePath, "deterministic content");
+    const h1 = contentHash(filePath);
+    const h2 = contentHash(filePath);
+    assert.equal(h1, h2);
+    cleanup();
+  });
+
+  test("promote copies project asset to global cache", () => {
+    setup();
+    const record = makeRecord();
+    appendRecord(tmp, record);
+    const filePath = join(tmp, record.path);
+    mkdirSync(join(filePath, ".."), { recursive: true });
+    writeFileSync(filePath, "promotable audio data");
+
+    const { sha } = promote(tmp, "bgm_001");
+    assert.ok(sha);
+
+    const cached = cacheGet("subtle tech", "bgm");
+    assert.ok(cached);
+    assert.equal(cached.sha, sha);
+    cleanup();
+  });
+
+  test("importFromCache copies cached file into project", () => {
+    setup();
+    const filePath = join(tmp, "source.wav");
+    writeFileSync(filePath, "importable audio");
+    const record = makeRecord({ provenance: { prompt: "import test" } });
+    const { sha } = cachePut(filePath, record);
+
+    const cached = cacheGet("import test", "bgm");
+    const projectDir = mkdtempSync(join(tmpdir(), "mu-import-"));
+    const imported = importFromCache(cached, projectDir, "bgm_001", ".media/audio/bgm/bgm_001.wav");
+
+    assert.ok(imported);
+    assert.equal(imported.id, "bgm_001");
+    assert.equal(imported.provenance.imported_from, sha);
+    assert.ok(existsSync(join(projectDir, ".media/audio/bgm/bgm_001.wav")));
+
+    rmSync(projectDir, { recursive: true, force: true });
+    cleanup();
+  });
+
+  // --- run ---
+
+  let passed = 0;
+  let failed = 0;
+  for (const { name, fn } of tests) {
+    try {
+      fn();
+      passed++;
+      console.log(`  \x1b[32m✓\x1b[0m ${name}`);
+    } catch (err) {
+      failed++;
+      console.log(`  \x1b[31m✗\x1b[0m ${name}`);
+      console.log(`    ${err.message}`);
+    }
+  }
+  console.log(`\n${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+}
+
+console.log("media-use · manifest/index/cache tests\n");
+runTests();

package/dist/skills/media-use/scripts/lib/match.mjs

@@ -0,0 +1,47 @@
+// Shared lexical-matching helpers used by both the assets/ scan (adopt.mjs) and
+// the reuse-candidate ranker (candidates.mjs), and the type-equivalence check
+// used by resolve.mjs and candidates.mjs. Kept in one place so the icon<->image
+// equivalence and the token rules can't drift between the "do" path (resolve)
+// and the "look" path (candidates).
+
+// Common filler words that should never, on their own, make two strings match.
+const MATCH_STOPWORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "this",
+  "that",
+  "your",
+  "our",
+]);
+
+// Split into lowercased word tokens of length >= 3, minus stopwords.
+export function matchTokens(text) {
+  return new Set(
+    String(text)
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((t) => t.length >= 3 && !MATCH_STOPWORDS.has(t)),
+  );
+}
+
+// Count of shared meaningful word tokens between two strings. 0 = no lexical
+// overlap (the candidate ranker still surfaces these, ordered after overlaps).
+export function tokenOverlap(a, b) {
+  const ta = matchTokens(a);
+  const tb = matchTokens(b);
+  let n = 0;
+  for (const t of ta) if (tb.has(t)) n++;
+  return n;
+}
+
+// icon, image, and logo are interchangeable: all live in images/, and
+// figma-imported brand marks are recorded as type image while agents ask for
+// logos as icon or logo.
+export function typesMatch(a, b) {
+  if (a === b) return true;
+  const visual = new Set(["icon", "image", "logo"]);
+  return visual.has(a) && visual.has(b);
+}

package/dist/skills/media-use/scripts/lib/media-fetch.mjs

@@ -0,0 +1,71 @@
+// Media downloads use public HTTP(S) URLs. Validate every redirect target;
+// a provider result must meet the same host policy as a direct ingest URL.
+// Public HTTPS-to-HTTP redirects are allowed, matching direct HTTP support.
+// This is a literal-host policy, not DNS pinning: DNS resolution remains trusted.
+
+import { BlockList, isIP } from "node:net";
+
+const blocked = new BlockList();
+for (const [network, prefix] of [
+  ["0.0.0.0", 8],
+  ["10.0.0.0", 8],
+  ["100.64.0.0", 10],
+  ["127.0.0.0", 8],
+  ["169.254.0.0", 16],
+  ["172.16.0.0", 12],
+  ["192.0.0.0", 24],
+  ["192.0.2.0", 24],
+  ["192.88.99.0", 24],
+  ["192.168.0.0", 16],
+  ["198.18.0.0", 15],
+  ["198.51.100.0", 24],
+  ["203.0.113.0", 24],
+  ["224.0.0.0", 4],
+  ["240.0.0.0", 4],
+])
+  blocked.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+  ["::", 128],
+  ["::1", 128],
+  ["fc00::", 7],
+  ["fe80::", 10],
+  ["fec0::", 10],
+  ["ff00::", 8],
+  ["2001:db8::", 32],
+])
+  blocked.addSubnet(network, prefix, "ipv6");
+
+export function isPublicMediaUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+    const host = url.hostname.replace(/\.$/, "");
+    if (
+      host === "localhost" ||
+      host.endsWith(".localhost") ||
+      host.endsWith(".local") ||
+      host.endsWith(".internal")
+    )
+      return false;
+    const address = host.replace(/^\[|\]$/g, "");
+    const family = isIP(address);
+    return family === 0 || !blocked.check(address, family === 4 ? "ipv4" : "ipv6");
+  } catch {
+    return false;
+  }
+}
+
+export async function fetchMedia(url, { method = "GET", signal, fetchImpl = fetch } = {}) {
+  let current = String(url);
+  for (let hop = 0; hop <= 5; hop++) {
+    if (!isPublicMediaUrl(current))
+      throw new Error("Media download blocked: URL is not public HTTP(S)");
+    const response = await fetchImpl(current, { method, signal, redirect: "manual" });
+    if (!(response.status >= 300 && response.status < 400)) return response;
+    const location = response.headers.get("location");
+    if (!location) return response;
+    await response.body?.cancel();
+    current = new URL(location, current).href;
+  }
+  throw new Error("Media download exceeded redirect limit");
+}

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

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fetchMedia, isPublicMediaUrl } from "./media-fetch.mjs";
+import { freezeUrl } from "./freeze.mjs";
+import { downloadTo } from "../../audio/scripts/lib/heygen.mjs";
+import { synthesizeHeygen } from "../../audio/scripts/lib/tts.mjs";
+import { faviconSearch } from "./logo-provider.mjs";
+
+test("blocks private, reserved, alternate-encoded and mapped hosts", () => {
+  for (const host of [
+    "localhost",
+    "localhost.",
+    "a.localhost",
+    "svc.internal",
+    "svc.local",
+    "127.1",
+    "2130706433",
+    "0x7f000001",
+    "10.0.0.1",
+    "169.254.169.254",
+    "100.100.100.200",
+    "192.168.1.1",
+    "172.31.0.1",
+    "224.0.0.1",
+    "[::]",
+    "[::1]",
+    "[::ffff:127.0.0.1]",
+    "[::ffff:a00:1]",
+    "[fe80::1]",
+    "[fd00::1]",
+    "[ff02::1]",
+  ]) {
+    assert.equal(isPublicMediaUrl(`https://${host}/asset`), false, host);
+  }
+  for (const url of [
+    "https://cdn.example/asset.cube",
+    "http://example.com/clip.mp4",
+    "https://8.8.8.8/a",
+    "https://[::ffff:8.8.8.8]/a",
+  ])
+    assert.equal(isPublicMediaUrl(url), true, url);
+  assert.equal(isPublicMediaUrl("file:///tmp/a.mp4"), false);
+});
+
+test("follows public relative redirects manually and forwards cancellation", async () => {
+  const calls = [];
+  const signal = new AbortController().signal;
+  const response = await fetchMedia("https://cdn.example/a", {
+    method: "HEAD",
+    signal,
+    fetchImpl: async (url, options) => {
+      calls.push(url);
+      assert.equal(options.redirect, "manual");
+      assert.equal(options.signal, signal);
+      assert.equal(options.method, "HEAD");
+      return calls.length === 1
+        ? new Response(null, { status: 302, headers: { location: "/b" } })
+        : new Response("media");
+    },
+  });
+  assert.deepEqual(calls, ["https://cdn.example/a", "https://cdn.example/b"]);
+  assert.equal(await response.text(), "media");
+});
+
+test("rejects private redirect targets before requesting them and cancels redirect bodies", async () => {
+  let calls = 0;
+  let cancelled = false;
+  await assert.rejects(
+    fetchMedia("https://cdn.example/a", {
+      fetchImpl: async () => {
+        calls++;
+        return new Response(
+          new ReadableStream({
+            cancel() {
+              cancelled = true;
+            },
+          }),
+          {
+            status: 302,
+            headers: { location: "http://169.254.169.254/latest/meta-data" },
+          },
+        );
+      },
+    }),
+    /blocked/,
+  );
+  assert.equal(calls, 1);
+  assert.equal(cancelled, true);
+});
+
+test("bounds redirect loops", async () => {
+  let calls = 0;
+  await assert.rejects(
+    fetchMedia("https://cdn.example/a", {
+      fetchImpl: async () => {
+        calls++;
+        return new Response(null, { status: 302, headers: { location: "/a" } });
+      },
+    }),
+    /redirect limit/,
+  );
+  assert.equal(calls, 6);
+});
+
+test("freeze refuses a public-to-private redirect without writing response bytes", async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "hf-freeze-redirect-"));
+  t.mock.method(globalThis, "fetch", async (_url, options) =>
+    options?.redirect === "manual"
+      ? new Response(null, { status: 302, headers: { location: "http://127.0.0.1/private.mp4" } })
+      : new Response("private response"),
+  );
+  try {
+    await assert.rejects(freezeUrl("https://cdn.example/a.mp4", join(dir, "out.mp4")), /blocked/);
+    assert.deepEqual(readdirSync(dir), []);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+for (const entry of ["heygen audio", "tts mp3", "tts wav", "favicon"]) {
+  test(`${entry} blocks private redirects before saving or transcoding`, async (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-provider-redirect-"));
+    const requests = [];
+    const fetchImpl = t.mock.method(globalThis, "fetch", async (url, options) => {
+      requests.push(url);
+      return options?.redirect === "manual"
+        ? new Response(null, {
+            status: 302,
+            headers: { location: "http://169.254.169.254/private" },
+          })
+        : new Response(new Uint8Array(600));
+    });
+    try {
+      if (entry === "heygen audio") {
+        await assert.rejects(
+          downloadTo("https://cdn.example/audio", join(dir, "audio.mp3")),
+          /blocked/,
+        );
+      } else if (entry === "favicon") {
+        assert.equal(await faviconSearch("GitHub logo"), null);
+      } else {
+        const result = await synthesizeHeygen(
+          {
+            text: "hi",
+            voiceId: "v1",
+            lang: "en",
+            speed: 1,
+            wavAbs: join(dir, entry === "tts wav" ? "audio.wav" : "audio.mp3"),
+          },
+          {
+            heygenAuthHeaders: () => ({}),
+            heygenJSON: async () => ({ data: { audio_url: "https://cdn.example/audio" } }),
+            fetch: fetchImpl,
+            transcodeToWav: () => assert.fail("private bytes must not reach ffmpeg"),
+          },
+        );
+        assert.equal(result.ok, false);
+        assert.match(result.error, /blocked/);
+      }
+      assert.equal(requests.length, 1);
+      assert.deepEqual(readdirSync(dir), []);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+}

package/dist/skills/media-use/scripts/lib/media-search.d.mts

@@ -0,0 +1,9 @@
+export function rankMediaRows<
+  T extends {
+    id: string;
+    kind: string;
+    title: string;
+    description: string;
+    tags: string[];
+  },
+>(query: string, rows: T[]): T[];