dsh-hyperframes 0.1.1 → 0.3.0

package/skills/media-use/scripts/lib/local-run.test.mjs

@@ -0,0 +1,121 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { runLocalModel } from "./local-run.mjs";
+
+const strongCpu = { ramMB: 16000, gpu: { present: false, vramMB: 0 }, appleSilicon: false };
+const tiny = { ramMB: 512, gpu: { present: false, vramMB: 0 }, appleSilicon: false };
+const ok = () => {}; // which/exec that succeed
+
+test("recommends the CLI path when no local tier fits the machine", () => {
+  const r = runLocalModel("tts", { specs: tiny, which: ok, exec: ok });
+  assert.equal(r.recommend, "cli");
+});
+
+test("recommends install when the tool is not on PATH", () => {
+  const r = runLocalModel("tts", {
+    specs: strongCpu,
+    which: () => {
+      throw new Error("not found");
+    },
+    exec: ok,
+    vars: { text: "hi", out: "/tmp/v.wav" },
+  });
+  assert.equal(r.recommend, "install");
+  assert.equal(r.model, "kokoro");
+  assert.match(r.command, /pip install kokoro/);
+});
+
+test("runs the model and returns the output path when installed", () => {
+  let ran = "";
+  const r = runLocalModel("tts", {
+    specs: strongCpu,
+    which: ok,
+    exec: (cmd) => {
+      ran = cmd;
+    },
+    vars: { text: "hello world", voice: "af_heart", out: "/tmp/v.wav" },
+  });
+  assert.equal(r.model, "kokoro");
+  assert.equal(r.out, "/tmp/v.wav");
+  assert.match(ran, /hello world/, "invoke template filled with vars");
+  assert.match(ran, /\/tmp\/v\.wav/);
+});
+
+test("a failing run degrades to an install recommendation, never throws", () => {
+  const r = runLocalModel("upscale", {
+    specs: strongCpu,
+    which: ok,
+    exec: () => {
+      throw new Error("boom");
+    },
+    vars: { in: "a.png", out: "b.png" },
+  });
+  assert.equal(r.recommend, "install");
+});
+
+test("a tier whose tool is missing demotes to the next tier that fits", () => {
+  // 64GB + GPU fits BOTH tts tiers, so the ladder has two rungs: fish-speech
+  // (its own binary) above Kokoro (`python -m kokoro`). fish-speech absent must
+  // not cost the user Kokoro.
+  const strongGpu = { ramMB: 64000, gpu: { present: true, vramMB: 24000 } };
+  let ran = "";
+  const r = runLocalModel("tts", {
+    specs: strongGpu,
+    which: (bin) => {
+      if (bin === "fish-speech") throw new Error("not found");
+    },
+    exec: (cmd) => {
+      ran = cmd;
+    },
+    vars: { text: "hello", voice: "af_heart", out: "/tmp/v.wav" },
+  });
+
+  assert.equal(r.model, "kokoro", "demoted past the missing fish-speech binary");
+  assert.equal(r.tier, "medium");
+  assert.match(ran, /kokoro/);
+});
+
+test("every fitting tier failing reports the last tier's install command", () => {
+  const strongGpu = { ramMB: 64000, gpu: { present: true, vramMB: 24000 } };
+  const r = runLocalModel("tts", {
+    specs: strongGpu,
+    which: ok,
+    exec: () => {
+      throw new Error("boom");
+    },
+    vars: { text: "hi", out: "/tmp/v.wav" },
+  });
+
+  assert.equal(r.recommend, "install");
+  assert.equal(r.model, "kokoro", "the smallest fitting tier is the actionable one");
+});
+
+test("the install recommendation states the download size", () => {
+  // nothing today tells the user what they are agreeing to before a tool
+  // starts pulling weights, so the size travels in the payload AND in the
+  // text a caller shows them
+  const r = runLocalModel("tts", {
+    specs: strongCpu,
+    which: () => {
+      throw new Error("not found");
+    },
+  });
+
+  assert.equal(r.recommend, "install");
+  assert.equal(typeof r.sizeMB, "number");
+  assert.ok(r.sizeMB > 0);
+  assert.match(r.reason, /GB to download/);
+});
+
+test("a failed run still reports the tier's size", () => {
+  const r = runLocalModel("tts", {
+    specs: strongCpu,
+    which: ok,
+    exec: () => {
+      throw new Error("boom");
+    },
+  });
+
+  assert.equal(r.recommend, "install");
+  assert.equal(typeof r.sizeMB, "number");
+});

package/skills/media-use/scripts/lib/logo-provider.mjs

@@ -0,0 +1,222 @@
+// Official brand marks — the `logo` type's provider tiers, tried in registry
+// order. Every tier was verified against a 54-brand stress test (2026-07,
+// 100% cascade hit). Hit counts below are a snapshot of that run — they
+// drift as the alias/org maps grow; re-run the stress test to refresh them.
+//
+//   1. svgl          — official full-color vector SVGs (+ wordmark variants);
+//                      40/54 first-hits. Search is substring-based, so
+//                      entities go through alias normalization first
+//                      ("nextjs" never matches "Next.js" raw).
+//   2. simple-icons  — monochrome official glyphs; caught the long tail the
+//                      others miss (nike, visa, toyota, wechat, bytedance).
+//                      Pinned CDN build for determinism.
+//   3. github avatar — the org's official logo for brands with a GitHub
+//                      presence. Known orgs only: guessing a login risks a
+//                      same-named personal account.
+//   4. domain favicon — small-raster last resort (DuckDuckGo ip3). Responses
+//                      under ~500B are DDG's globe placeholder, not a hit.
+//
+// HeyGen asset search is deliberately absent: for brand queries it returns
+// generic look-alike icons (0/3 in testing) — worse than a miss. A total miss
+// falls through to resolve's normal failure path (`no provider could resolve
+// logo`, exit 1).
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const SVGL_API = "https://api.svgl.app";
+const SIMPLE_ICONS_CDN = "https://cdn.jsdelivr.net/npm/simple-icons@16.25.0/icons";
+const FAVICON_MIN_BYTES = 500;
+
+// svgl search queries per entity, tried in order after the raw entity.
+const SVGL_ALIASES = {
+  nextjs: ["next.js", "next"],
+  aws: ["amazon web services"],
+  huggingface: ["hugging face"],
+  cocacola: ["coca-cola"],
+  mcdonalds: ["mcdonald's"],
+};
+
+// simple-icons slugs that differ from the normalized entity.
+const SIMPLE_ICON_SLUGS = {
+  nextjs: "nextdotjs",
+  aws: "amazonwebservices",
+};
+
+// Known GitHub orgs. Only mapped entities resolve at this tier — a brand name
+// is NOT a GitHub login, and guessing hits same-named personal accounts.
+const GITHUB_ORGS = {
+  slack: "slackhq",
+  meta: "facebook",
+  google: "google",
+  microsoft: "microsoft",
+  aws: "aws",
+  vercel: "vercel",
+  nextjs: "vercel",
+  alibaba: "alibaba",
+  heygen: "heygen-com",
+};
+
+// Favicon domains that aren't `<entity>.com`.
+const FAVICON_DOMAINS = {
+  cocacola: "coca-cola.com",
+  aws: "aws.amazon.com",
+  nextjs: "nextjs.org",
+};
+
+const norm = (s) =>
+  String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+
+/** The brand entity for a query: --entity wins; else the intent minus filler. */
+export function entityFrom(intent, entity) {
+  if (entity) return entity.toLowerCase().trim();
+  return String(intent)
+    .toLowerCase()
+    .replace(/\b(logo|logos|icon|brand|official|mark)\b/g, "")
+    .trim()
+    .replace(/\s+/g, " ");
+}
+
+/** Exact match after stripping case/spacing/punctuation — "Next.js" ≡ "nextjs". */
+export function titleMatches(title, entity) {
+  return norm(title) === norm(entity);
+}
+
+export function svglQueriesFor(entity) {
+  return [entity, ...(SVGL_ALIASES[norm(entity)] || [])];
+}
+
+export function simpleIconSlugsFor(entity) {
+  const slugs = [norm(entity)];
+  const alias = SIMPLE_ICON_SLUGS[norm(entity)];
+  if (alias) slugs.push(alias);
+  return slugs;
+}
+
+export function githubOrgFor(entity) {
+  return GITHUB_ORGS[norm(entity)] || null;
+}
+
+export function faviconDomainFor(entity) {
+  return FAVICON_DOMAINS[norm(entity)] || `${norm(entity)}.com`;
+}
+
+async function fetchJson(url) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+  if (!res.ok) return null;
+  return res.json();
+}
+
+async function urlExists(url) {
+  const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(10_000) });
+  return res.ok;
+}
+
+export async function svglSearch(intent, ctx = {}) {
+  const entity = entityFrom(intent, ctx.entity);
+  for (const q of svglQueriesFor(entity)) {
+    let items;
+    try {
+      items = await fetchJson(`${SVGL_API}?search=${encodeURIComponent(q)}`);
+    } catch {
+      return null; // network down — let the next tier try its own host
+    }
+    if (!Array.isArray(items)) continue;
+    const hit = items.find((it) => titleMatches(it.title, q) || titleMatches(it.title, entity));
+    if (!hit) continue;
+    const route = typeof hit.route === "string" ? hit.route : hit.route?.light;
+    if (!route) continue;
+    return {
+      url: route,
+      ext: ".svg",
+      source: "search",
+      metadata: {
+        description: `${hit.title} logo (official mark)`,
+        provider: "svgl",
+        provenance: { entity, query: q, route, wordmark: Boolean(hit.wordmark) },
+      },
+    };
+  }
+  return null;
+}
+
+export async function simpleIconsSearch(intent, ctx = {}) {
+  const entity = entityFrom(intent, ctx.entity);
+  for (const slug of simpleIconSlugsFor(entity)) {
+    const url = `${SIMPLE_ICONS_CDN}/${slug}.svg`;
+    let ok;
+    try {
+      ok = await urlExists(url);
+    } catch {
+      return null;
+    }
+    if (!ok) continue;
+    return {
+      url,
+      ext: ".svg",
+      source: "search",
+      metadata: {
+        description: `${entity} logo (official monochrome glyph)`,
+        provider: "simple-icons",
+        provenance: { entity, slug, pinned: "simple-icons@16.25.0" },
+      },
+    };
+  }
+  return null;
+}
+
+export async function githubAvatarSearch(intent, ctx = {}) {
+  const entity = entityFrom(intent, ctx.entity);
+  const org = githubOrgFor(entity);
+  if (!org) return null;
+  const url = `https://github.com/${org}.png?size=460`;
+  try {
+    if (!(await urlExists(url))) return null;
+  } catch {
+    return null;
+  }
+  return {
+    url,
+    ext: ".png",
+    source: "search",
+    metadata: {
+      description: `${entity} logo (GitHub org avatar)`,
+      provider: "github.avatar",
+      provenance: { entity, org },
+    },
+  };
+}
+
+export async function faviconSearch(intent, ctx = {}) {
+  const entity = entityFrom(intent, ctx.entity);
+  const domain = faviconDomainFor(entity);
+  const url = `https://icons.duckduckgo.com/ip3/${domain}.ico`;
+  let body;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return null;
+    body = Buffer.from(await res.arrayBuffer());
+  } catch {
+    return null;
+  }
+  if (body.byteLength < FAVICON_MIN_BYTES) return null; // DDG placeholder, not a logo
+  // Hand the verified bytes over as a local file: the freeze step copies it
+  // instead of re-downloading, so the size check is authoritative over what
+  // gets frozen and the favicon tier costs one network round-trip, not two.
+  const bytes = body.byteLength;
+  const tmp = join(mkdtempSync(join(tmpdir(), "media-use-logo-")), `${domain}.ico`);
+  writeFileSync(tmp, body);
+  return {
+    localPath: tmp,
+    ext: ".ico",
+    source: "search",
+    metadata: {
+      description: `${entity} favicon (small raster — chip-size use only)`,
+      provider: "favicon.ddg",
+      provenance: { entity, domain, bytes, low_res: true },
+    },
+  };
+}

package/skills/media-use/scripts/lib/logo-provider.test.mjs

@@ -0,0 +1,137 @@
+import test from "node:test";
+import assert from "node:assert";
+import { readFileSync } from "node:fs";
+import {
+  entityFrom,
+  titleMatches,
+  svglQueriesFor,
+  simpleIconSlugsFor,
+  githubOrgFor,
+  faviconDomainFor,
+  svglSearch,
+  simpleIconsSearch,
+  githubAvatarSearch,
+  faviconSearch,
+} from "./logo-provider.mjs";
+import { getProviders, runProviders } from "./registry.mjs";
+
+test("entityFrom strips filler words from the intent; --entity wins", () => {
+  assert.equal(entityFrom("LinkedIn logo"), "linkedin");
+  assert.equal(entityFrom("official Slack brand mark"), "slack");
+  assert.equal(entityFrom("anything", "Notion"), "notion");
+});
+
+test("titleMatches ignores case, spacing, punctuation — and rejects lookalikes", () => {
+  assert.ok(titleMatches("Next.js", "nextjs"));
+  assert.ok(titleMatches("Coca-Cola", "coca cola"));
+  assert.ok(!titleMatches("Slackware", "slack"));
+});
+
+test("svgl queries include the alias forms the raw entity can't match", () => {
+  assert.ok(svglQueriesFor("nextjs").includes("next.js"));
+  assert.ok(svglQueriesFor("aws").includes("amazon web services"));
+  assert.deepEqual(svglQueriesFor("figma"), ["figma"]);
+});
+
+test("simple-icons slugs cover the renamed entries", () => {
+  assert.ok(simpleIconSlugsFor("nextjs").includes("nextdotjs"));
+  assert.ok(simpleIconSlugsFor("aws").includes("amazonwebservices"));
+  assert.deepEqual(simpleIconSlugsFor("nike"), ["nike"]);
+});
+
+test("github avatar tier never guesses an org", () => {
+  assert.equal(githubOrgFor("slack"), "slackhq");
+  assert.equal(githubOrgFor("heygen"), "heygen-com");
+  assert.equal(githubOrgFor("some-random-startup"), null);
+});
+
+test("favicon domain defaults to <entity>.com with explicit overrides", () => {
+  assert.equal(faviconDomainFor("cocacola"), "coca-cola.com");
+  assert.equal(faviconDomainFor("stripe"), "stripe.com");
+});
+
+// --- async tiers, network mocked -------------------------------------------
+// The 54-brand stress test is a manual snapshot; these pin the same behavior
+// as CI gates: descriptor shape, alias retry, error→null fallthrough, the
+// placeholder filter, and the real cascade order under a mocked network.
+
+const json = (data) => new Response(JSON.stringify(data), { status: 200 });
+const status = (code) => new Response(null, { status: code });
+const bin = (n) => new Response(new Uint8Array(n), { status: 200 });
+
+test("svglSearch returns the descriptor shape on an exact title hit", async (t) => {
+  t.mock.method(globalThis, "fetch", async () =>
+    json([{ title: "Figma", route: "https://svgl.app/library/figma.svg" }]),
+  );
+  const res = await svglSearch("Figma logo", {});
+  assert.equal(res.url, "https://svgl.app/library/figma.svg");
+  assert.equal(res.ext, ".svg");
+  assert.equal(res.metadata.provider, "svgl");
+});
+
+test("svglSearch skips a non-array payload and retries with the alias query", async (t) => {
+  const seen = [];
+  t.mock.method(globalThis, "fetch", async (url) => {
+    seen.push(decodeURIComponent(String(url)));
+    return seen.length === 1
+      ? json({ error: "unexpected shape" })
+      : json([{ title: "Next.js", route: "https://svgl.app/library/nextjs.svg" }]);
+  });
+  const res = await svglSearch("nextjs logo", {});
+  assert.equal(res.metadata.provenance.query, "next.js", "hit came from the alias query");
+  assert.ok(seen.length >= 2, "raw query then alias");
+});
+
+test("svglSearch returns null when the network is down — the cascade falls through", async (t) => {
+  t.mock.method(globalThis, "fetch", async () => {
+    throw new Error("network down");
+  });
+  assert.equal(await svglSearch("figma logo", {}), null);
+});
+
+test("simpleIconsSearch falls to the next slug on a 404", async (t) => {
+  const seen = [];
+  t.mock.method(globalThis, "fetch", async (url) => {
+    seen.push(String(url));
+    return String(url).includes("amazonwebservices") ? status(200) : status(404);
+  });
+  const res = await simpleIconsSearch("aws logo", {});
+  assert.ok(res.url.endsWith("amazonwebservices.svg"));
+  assert.equal(seen.length, 2, "plain slug 404s first, alias slug hits");
+});
+
+test("faviconSearch rejects DDG's sub-500B placeholder with null", async (t) => {
+  t.mock.method(globalThis, "fetch", async () => bin(120));
+  assert.equal(await faviconSearch("someco logo", {}), null);
+});
+
+test("faviconSearch hands verified bytes over as a local file — one fetch, no re-download", async (t) => {
+  const fetchMock = t.mock.method(globalThis, "fetch", async () => bin(600));
+  const res = await faviconSearch("someco logo", {});
+  assert.ok(res.localPath, "returns a localPath, not a url");
+  assert.equal(readFileSync(res.localPath).byteLength, 600, "frozen bytes are the verified bytes");
+  assert.equal(fetchMock.mock.callCount(), 1, "single network round-trip");
+  assert.equal(res.metadata.provenance.low_res, true);
+});
+
+test("githubAvatarSearch never touches the network for an unmapped entity", async (t) => {
+  const fetchMock = t.mock.method(globalThis, "fetch", async () => status(200));
+  assert.equal(await githubAvatarSearch("some-random-startup logo", {}), null);
+  assert.equal(fetchMock.mock.callCount(), 0);
+});
+
+test("the real logo cascade falls through tier by tier to the first hit", async (t) => {
+  t.mock.method(globalThis, "fetch", async (url) => {
+    const u = String(url);
+    if (u.includes("api.svgl.app")) return json([]); // tier 1: no hit
+    if (u.includes("jsdelivr")) return status(404); // tier 2: no such slug
+    // tier 3 (github) is never called: entity is unmapped
+    if (u.includes("duckduckgo")) return bin(600); // tier 4: real favicon
+    throw new Error(`unexpected fetch: ${u}`);
+  });
+  const res = await runProviders(getProviders("logo"), "search", "zzzbrand logo", {
+    entity: "zzzbrand",
+  });
+  assert.ok(res, "cascade must land on the favicon tier");
+  assert.equal(res.metadata.provider, "favicon.ddg");
+});

package/skills/media-use/scripts/lib/ltx-video-provider.mjs

@@ -0,0 +1,94 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describeDownload, probeSpecs } from "./specs.mjs";
+import { buildArgv, selectModel, selectModelLadder } from "./local-models.mjs";
+
+export async function ltxVideoGenerate(
+  intent,
+  ctx,
+  execFn = execFileSync,
+  pathExists = existsSync,
+  unlinkFn = unlinkSync,
+) {
+  const specs = ctx?.specs || probeSpecs();
+  const ladder = selectModelLadder("videogen", specs, { preferTier: ctx?.preferTier });
+  if (!ladder.length) {
+    const { reason } = selectModel("videogen", specs, { preferTier: ctx?.preferTier });
+    console.error(
+      `media-use: local video gen not enabled (${reason}). Enable a fitting free on-device LTX model to use this provider.`,
+    );
+    return null;
+  }
+
+  // Each attempt mints its own timestamped output path, so a partial artifact
+  // from a failed tier is orphaned rather than overwritten - and a lower tier
+  // then succeeding hides it. Discard it before demoting. Best-effort: a
+  // partial we cannot remove must never mask the real failure.
+  const discardPartial = (path) => {
+    try {
+      if (pathExists(path)) unlinkFn(path);
+    } catch {
+      // nothing actionable: the generate failure below is the real story
+    }
+  };
+
+  // Walk the whole ladder, best tier first. A tier that cannot run on this
+  // machine for a reason no spec check sees (runner off PATH, gated weights, an
+  // OOM) demotes to the next fitting tier instead of failing local video gen
+  // outright. Every demotion is reported: a silent drop to a smaller model
+  // leaves the caller wondering why the output looks the way it does.
+  for (const model of ladder) {
+    const bin = model.invoke.trim().split(/\s+/)[0];
+    try {
+      execFn("which", [bin], { stdio: ["ignore", "ignore", "ignore"] });
+    } catch {
+      console.error(
+        `media-use: local video gen not enabled (\`${bin}\` not on PATH). Install for free on-device LTX: ${model.install}. Heads up: ${model.id} ${describeDownload(model.sizeMB)}.`,
+      );
+      continue;
+    }
+
+    const outPath = join(tmpdir(), `media-use-ltx-${process.pid}-${Date.now()}.mp4`);
+    const argv = buildArgv(model.invoke, {
+      prompt: intent,
+      w: ctx?.width || 512,
+      h: ctx?.height || 320,
+      frames: ctx?.frames || 33,
+      out: outPath,
+    });
+    argv.shift();
+
+    try {
+      execFn(bin, argv, {
+        encoding: "utf8",
+        timeout: 1_800_000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (err) {
+      discardPartial(outPath);
+      console.error(
+        `media-use: local video gen (${model.id}) failed: ${err.stderr?.toString().trim().slice(-200) || err.message}`,
+      );
+      continue;
+    }
+    if (!pathExists(outPath)) {
+      console.error(
+        `media-use: local video gen (${model.id}) exited cleanly but wrote no output file`,
+      );
+      continue;
+    }
+    return {
+      localPath: outPath,
+      ext: ".mp4",
+      source: "generated",
+      metadata: {
+        description: intent,
+        provider: "ltx.local",
+        provenance: { prompt: intent },
+      },
+    };
+  }
+  return null;
+}