dsh-hyperframes 0.2.0 → 0.3.1

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

@@ -0,0 +1,261 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import {
+  getProviders,
+  getProvider,
+  listTypes,
+  providerMatches,
+  providerNamesFor,
+  runProviders,
+  runCapability,
+  providerTierFor,
+  buildProviderTierIndex,
+} from "./registry.mjs";
+
+// --- registry shape -------------------------------------------------------
+
+test("listTypes exposes the v2 media types", () => {
+  const types = listTypes();
+  for (const t of [
+    "bgm",
+    "sfx",
+    "image",
+    "icon",
+    "logo",
+    "voice",
+    "video",
+    "brand",
+    "grade",
+    "lut",
+  ]) {
+    assert.ok(types.includes(t), `missing type: ${t}`);
+  }
+});
+
+test("heygen provider is first for every type it serves", () => {
+  for (const t of ["bgm", "sfx", "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}`);
+  }
+});
+
+test("sanctioned providers only: heygen, 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$|^svgl$|^simple-icons$|^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}`);
+    }
+  }
+});
+
+test("image cascade: heygen catalog, then local mflux, then the codex upsell", () => {
+  const ps = getProviders("image");
+  assert.match(ps[0].name, /^heygen/, "heygen catalog first");
+  const names = ps.map((p) => p.name);
+  const mflux = ps.find((p) => p.name === "mflux.local");
+  const codex = ps.find((p) => p.name === "codex.image_gen");
+  assert.ok(mflux && typeof mflux.generate === "function", "local mflux registered");
+  assert.ok(codex && typeof codex.generate === "function", "codex upsell registered");
+  assert.ok(names.indexOf("mflux.local") < names.indexOf("codex.image_gen"), "local before codex");
+  assert.ok(!mflux.network, "local mflux is kept under --local-only");
+  assert.ok(codex.network, "codex is network (skipped under --local-only)");
+});
+
+test("voice cascade: HeyGen TTS first, Kokoro remains the local fallback", () => {
+  const ps = getProviders("voice");
+  assert.equal(ps[0].name, "heygen.tts", "HeyGen TTS is first when credentials exist");
+  assert.ok(ps[0].network, "HeyGen TTS is network (skipped under --local-only)");
+  assert.ok(ps[0].paid, "HeyGen TTS may bill after the OAuth free allowance");
+  assert.equal(ps[1].name, "kokoro.local", "local Kokoro is the offline fallback");
+  assert.ok(!ps[1].network, "local Kokoro kept under --local-only");
+  assert.ok(!ps[1].paid, "local Kokoro is free");
+});
+
+test("video cascade: HeyGen first, LTX local fallback, generate-only", async () => {
+  assert.deepEqual(providerNamesFor("video"), ["heygen.video", "ltx.local"]);
+  assert.equal(providerMatches("video", "ltx.local"), true);
+
+  const ps = getProviders("video");
+  assert.ok(ps[0].network, "HeyGen video is network (skipped under --local-only)");
+  assert.ok(ps[0].paid, "HeyGen video may bill after the OAuth free allowance");
+  assert.ok(!ps[1].network, "local LTX is kept under --local-only");
+  assert.equal(await runCapability("video", "search", "x", {}), null);
+});
+
+test("sfx cascade: HeyGen catalog first, bundled library remains the local fallback", () => {
+  const ps = getProviders("sfx");
+  assert.equal(ps[0].name, "heygen.audio.sounds");
+  assert.ok(ps[0].network, "HeyGen SFX catalog is network-only");
+  assert.equal(ps[1].name, "bundled.sfx");
+  assert.equal(typeof ps[1].search, "function");
+  assert.ok(!ps[1].network, "bundled SFX remain available offline");
+});
+
+test("ctx.provider forces one generator (e.g. 'make an image WITH codex')", async () => {
+  const providers = [
+    { name: "heygen.asset.search", network: true, search: async () => null },
+    { name: "mflux.local", generate: async () => ({ hit: "local" }) },
+    { name: "codex.image_gen", network: true, generate: async () => ({ hit: "codex" }) },
+  ];
+  // no override: local wins (first generate to return non-null)
+  assert.deepEqual(await runProviders(providers, "generate", "x", {}), { hit: "local" });
+  // override to codex: skip local, use codex even though local would have worked
+  assert.deepEqual(await runProviders(providers, "generate", "x", { provider: "codex" }), {
+    hit: "codex",
+  });
+  // override matches the full name too
+  assert.deepEqual(
+    await runProviders(providers, "generate", "x", { provider: "codex.image_gen" }),
+    { hit: "codex" },
+  );
+  // --local-only wins even over a forced network provider: no network call,
+  // clean miss (the caller surfaces the conflict). A forced LOCAL provider under
+  // --local-only still runs.
+  assert.equal(
+    await runProviders(providers, "generate", "x", { provider: "codex", localOnly: true }),
+    null,
+  );
+  assert.deepEqual(
+    await runProviders(providers, "generate", "x", { provider: "mflux", localOnly: true }),
+    { hit: "local" },
+  );
+});
+
+test("getProvider returns the first provider with its type, throws for unknown", () => {
+  const p = getProvider("bgm");
+  assert.equal(p.type, "bgm");
+  assert.equal(typeof p.search, "function");
+  assert.throws(() => getProvider("unknown_type"), /unknown media type/);
+});
+
+test("getProviders throws for unknown type", () => {
+  assert.throws(() => getProviders("nope"), /unknown media type/);
+});
+
+// --- deterministic capability execution (runProviders core) ---------------
+
+test("runProviders calls providers in order and returns the first non-null", async () => {
+  const calls = [];
+  const providers = [
+    {
+      name: "a",
+      enabled: true,
+      search: async () => {
+        calls.push("a");
+        return null;
+      },
+    },
+    {
+      name: "b",
+      enabled: true,
+      search: async () => {
+        calls.push("b");
+        return { hit: "b" };
+      },
+    },
+    {
+      name: "c",
+      enabled: true,
+      search: async () => {
+        calls.push("c");
+        return { hit: "c" };
+      },
+    },
+  ];
+  const res = await runProviders(providers, "search", "x", {});
+  assert.deepEqual(res, { hit: "b" });
+  assert.deepEqual(calls, ["a", "b"], "must stop at first non-null, never call c");
+});
+
+test("runProviders skips providers missing the requested capability", async () => {
+  const providers = [
+    { name: "a", enabled: true /* no search */ },
+    { name: "b", enabled: true, search: async () => ({ hit: "b" }) },
+  ];
+  const res = await runProviders(providers, "search", "x", {});
+  assert.deepEqual(res, { hit: "b" });
+});
+
+test("runProviders returns null when no provider yields a result", async () => {
+  const providers = [{ name: "a", enabled: true, search: async () => null }];
+  assert.equal(await runProviders(providers, "search", "x", {}), null);
+});
+
+test("runCapability('bgm','process') is null — process slot is graceful when unfilled", async () => {
+  assert.equal(await runCapability("bgm", "process", "x", {}), null);
+});
+
+// --- provider cost tier (telemetry) ---------------------------------------
+
+test("providerTierFor reports the registry's own A/N/P declaration", () => {
+  assert.equal(providerTierFor("heygen.tts"), "network_paid");
+  assert.equal(providerTierFor("heygen.video"), "network_paid");
+  assert.equal(providerTierFor("heygen.audio.sounds"), "network_free");
+  assert.equal(providerTierFor("heygen.asset.search"), "network_free");
+  assert.equal(providerTierFor("codex.image_gen"), "network_free");
+  assert.equal(providerTierFor("bundled.sfx"), "local");
+  assert.equal(providerTierFor("kokoro.local"), "local");
+});
+
+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.
+  const byName = new Map();
+  for (const type of listTypes()) {
+    for (const name of providerNamesFor(type)) {
+      const tier = providerTierFor(name);
+      assert.ok(tier, `every declared provider has a tier (${type}/${name})`);
+      const prior = byName.get(name);
+      if (prior) assert.equal(tier, prior, `${name} must carry one tier across types`);
+      byName.set(name, tier);
+    }
+  }
+});
+
+test("providerTierFor returns undefined for a name the registry does not declare", () => {
+  assert.equal(providerTierFor("does.not.exist"), undefined);
+  assert.equal(providerTierFor(undefined), undefined);
+  assert.equal(providerTierFor(null), undefined);
+  assert.equal(providerTierFor(""), undefined);
+});
+
+test("buildProviderTierIndex throws when one name carries two tiers", () => {
+  assert.throws(
+    () =>
+      buildProviderTierIndex([
+        [{ name: "dual", network: true }],
+        [{ name: "dual", network: true, paid: true }],
+      ]),
+    /declared network_free under one media type and network_paid under another/,
+  );
+});
+
+test("buildProviderTierIndex accepts the same name repeated at the same tier", () => {
+  const index = buildProviderTierIndex([
+    [{ name: "same", network: true }],
+    [{ name: "same", network: true }],
+  ]);
+  assert.equal(index.get("same"), "network_free");
+});
+
+test("--local-only skips every network provider (even free remote ones)", async () => {
+  let remoteRan = false;
+  const providers = [
+    {
+      name: "heygen",
+      network: true,
+      search: async () => {
+        remoteRan = true;
+        return { hit: "net" };
+      },
+    },
+    { name: "local", search: async () => ({ hit: "local" }) },
+  ];
+  assert.deepEqual(await runProviders(providers, "search", "x", { localOnly: true }), {
+    hit: "local",
+  });
+  assert.equal(remoteRan, false, "the remote provider must not be called offline");
+});

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

@@ -0,0 +1,24 @@
+// Paginated text search over a manifest (project or global) by id / description
+// / entity. Plain substring match — no vector DB (B4): the agent's own file
+// search covers semantics; this just keeps result pages small enough to not
+// blow the context window.
+
+const PAGE = 10;
+
+export function searchRecords(records, query, { page = 1, pageSize = PAGE } = {}) {
+  const q = String(query || "")
+    .trim()
+    .toLowerCase();
+  const matched = q
+    ? records.filter((r) =>
+        [r.id, r.description, r.entity, r.type].some(
+          (f) => f && String(f).toLowerCase().includes(q),
+        ),
+      )
+    : records.slice();
+  const total = matched.length;
+  const pages = Math.max(1, Math.ceil(total / pageSize));
+  const p = Math.min(Math.max(1, page), pages);
+  const start = (p - 1) * pageSize;
+  return { results: matched.slice(start, start + pageSize), total, page: p, pages, pageSize };
+}

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

@@ -0,0 +1,32 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { searchRecords } from "./search.mjs";
+
+const recs = Array.from({ length: 23 }, (_, i) => ({
+  id: `bgm_${i}`,
+  type: i % 2 ? "bgm" : "sfx",
+  description: i === 5 ? "energetic tech whoosh" : `track ${i}`,
+}));
+
+test("matches id / description / type, case-insensitively", () => {
+  assert.equal(searchRecords(recs, "ENERGETIC").results.length, 1);
+  assert.equal(searchRecords(recs, "energetic").results[0].id, "bgm_5");
+  assert.ok(searchRecords(recs, "sfx").total > 0);
+});
+
+test("caps page size and reports pagination", () => {
+  const r = searchRecords(recs, "", { pageSize: 10 });
+  assert.equal(r.results.length, 10, "never returns more than a page");
+  assert.equal(r.total, 23);
+  assert.equal(r.pages, 3);
+  assert.equal(r.page, 1);
+});
+
+test("page navigation returns the right slice, clamps out-of-range", () => {
+  assert.equal(searchRecords(recs, "", { page: 3, pageSize: 10 }).results.length, 3);
+  assert.equal(searchRecords(recs, "", { page: 99, pageSize: 10 }).page, 3, "clamped to last page");
+});
+
+test("empty query returns everything (paginated)", () => {
+  assert.equal(searchRecords(recs, "").total, 23);
+});

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

@@ -0,0 +1,23 @@
+import { heygenSearch } from "./heygen-search.mjs";
+
+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];
+    return {
+      url: best.audio_url,
+      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 },
+      },
+    };
+  },
+};

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

@@ -0,0 +1,132 @@
+// Machine-capability probe for the spec-gated local-model fallback.
+//
+// Local models are USER-INSTALLED and local-use-only — media-use recommends,
+// spec-checks, and assists install, but never bundles or runs them as a service.
+// This probe answers "what tier can this machine actually run?" so selection can
+// offer a medium/large local model, or fall back to recommending the CLI path.
+//
+// `osMod` and `exec` are injectable for tests. `exec(cmd)` returns the command's
+// stdout as a string, or throws / returns null on failure.
+
+import os from "node:os";
+import { statfsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { execSync } from "node:child_process";
+
+function defaultExec(cmd) {
+  return execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 4000 });
+}
+
+// Available (not just total) RAM — the real budget for "will this model fit
+// alongside the OS + open apps". On unified-memory Macs the model shares system
+// RAM, so a big model on a busy machine OOMs/thrashes even if total RAM looks
+// ample. macOS: vm_stat free + inactive + speculative + purgeable pages (all
+// reclaimable). Linux: /proc/meminfo MemAvailable. Fallback: total (optimistic
+// but stable when the probe is unavailable, e.g. in tests).
+function availableRamMB(platform, exec, totalMB) {
+  try {
+    if (platform === "darwin") {
+      const out = String(exec("vm_stat"));
+      const pageSize = parseInt((out.match(/page size of (\d+)/) || [])[1] || "16384", 10);
+      const pages = (name) => {
+        const m = out.match(new RegExp(`${name}:\\s+(\\d+)`));
+        return m ? parseInt(m[1], 10) : 0;
+      };
+      const reclaimable =
+        pages("Pages free") +
+        pages("Pages inactive") +
+        pages("Pages speculative") +
+        pages("Pages purgeable");
+      const mb = Math.round((reclaimable * pageSize) / (1024 * 1024));
+      if (mb > 0) return mb;
+    } else if (platform === "linux") {
+      const out = String(exec("cat /proc/meminfo"));
+      const m = out.match(/MemAvailable:\s+(\d+)\s+kB/);
+      if (m) return Math.round(parseInt(m[1], 10) / 1024);
+    }
+  } catch {
+    // probe unavailable — fall through to the total-RAM estimate
+  }
+  return totalMB;
+}
+
+function detectGpu(platform, arch, ramMB, exec) {
+  // Apple Silicon: Metal GPU with unified memory — VRAM tracks system RAM.
+  if (platform === "darwin" && arch === "arm64") {
+    return { present: true, kind: "apple", vramMB: ramMB };
+  }
+  // NVIDIA: query total VRAM. Any failure (no driver, no GPU) -> no GPU.
+  try {
+    const out = exec("nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits");
+    const mb = parseInt(String(out).trim().split(/\r?\n/)[0], 10);
+    if (Number.isFinite(mb) && mb > 0) return { present: true, kind: "nvidia", vramMB: mb };
+  } catch {
+    // fall through — no usable GPU
+  }
+  return { present: false, kind: null, vramMB: 0 };
+}
+
+export function probeSpecs({ osMod = os, exec = defaultExec } = {}) {
+  const platform = osMod.platform();
+  const arch = osMod.arch();
+  const cpuCores = osMod.cpus().length;
+  const ramMB = Math.round(osMod.totalmem() / (1024 * 1024));
+  return {
+    platform,
+    arch,
+    cpuCores,
+    ramMB,
+    availableRamMB: availableRamMB(platform, exec, ramMB),
+    appleSilicon: platform === "darwin" && arch === "arm64",
+    gpu: detectGpu(platform, arch, ramMB, exec),
+  };
+}
+
+// Where Hugging Face actually puts downloaded weights. A free-space check
+// against cwd measures the wrong filesystem, so the disk question has to be
+// asked about this directory. Precedence follows huggingface_hub's own order.
+export function weightsCacheDir({ env = process.env, osMod = os } = {}) {
+  if (env.HF_HUB_CACHE) return env.HF_HUB_CACHE;
+  if (env.HUGGINGFACE_HUB_CACHE) return env.HUGGINGFACE_HUB_CACHE;
+  if (env.HF_HOME) return join(env.HF_HOME, "hub");
+  return join(osMod.homedir(), ".cache", "huggingface", "hub");
+}
+
+// Free space on the filesystem that will hold the weights. The cache dir
+// usually does not exist until the first download and statfs throws on a
+// missing path, so walk up to the deepest ancestor that does exist. Returns
+// null when even the root cannot be read, so callers can say "unknown" instead
+// of implying zero and scaring someone off a download that would have worked.
+export function freeSpaceMB(dir, statfsFn = statfsSync) {
+  let path = dir;
+  for (;;) {
+    try {
+      const { bavail, bsize } = statfsFn(path);
+      return (bavail * bsize) / 1e6;
+    } catch {
+      const parent = dirname(path);
+      if (parent === path) return null;
+      path = parent;
+    }
+  }
+}
+
+// One line the user reads BEFORE agreeing to a pull that can be tens of GB.
+// Always names the size and where it lands. When it will not fit we say so
+// plainly rather than withholding the tier: a machine that could free up space
+// should still be told the tier exists. `statfsFn` / `env` / `osMod` are
+// injectable for tests.
+export function describeDownload(
+  sizeMB,
+  { statfsFn = statfsSync, env = process.env, osMod = os } = {},
+) {
+  const dir = weightsCacheDir({ env, osMod });
+  const gb = (mb) => (mb / 1000).toFixed(1);
+  const head = `downloads ~${gb(sizeMB)}GB of weights to ${dir}`;
+  const free = freeSpaceMB(dir, statfsFn);
+  if (free == null) return `${head} (free space unknown)`;
+  if (free < sizeMB) {
+    return `${head}, but only ${gb(free)}GB is free there, so it will NOT fit as-is`;
+  }
+  return `${head} (${gb(free)}GB free there)`;
+}

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

@@ -0,0 +1,157 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { describeDownload, freeSpaceMB, probeSpecs, weightsCacheDir } from "./specs.mjs";
+
+// Fake os module + exec so the probe is deterministic across CI machines.
+const fakeOs = (over = {}) => ({
+  platform: () => over.platform ?? "linux",
+  arch: () => over.arch ?? "x64",
+  cpus: () => Array.from({ length: over.cores ?? 8 }),
+  totalmem: () => (over.ramMB ?? 16384) * 1024 * 1024,
+});
+
+test("probeSpecs reports structured caps", () => {
+  const s = probeSpecs({ osMod: fakeOs({ cores: 12, ramMB: 32768 }), exec: () => null });
+  assert.equal(s.cpuCores, 12);
+  assert.equal(s.ramMB, 32768);
+  assert.equal(s.platform, "linux");
+  assert.equal(s.gpu.present, false);
+  // probe unavailable (exec returns null) -> availableRamMB falls back to total
+  assert.equal(s.availableRamMB, 32768);
+});
+
+test("availableRamMB is read from /proc/meminfo on Linux", () => {
+  const exec = (cmd) =>
+    cmd.includes("meminfo") ? "MemTotal: 33554432 kB\nMemAvailable: 8388608 kB\n" : null;
+  const s = probeSpecs({ osMod: fakeOs({ platform: "linux", ramMB: 32768 }), exec });
+  assert.equal(s.availableRamMB, 8192, "8388608 kB -> 8192 MB");
+});
+
+test("availableRamMB is summed from reclaimable vm_stat pages on macOS", () => {
+  const vmStat =
+    "Mach Virtual Memory Statistics: (page size of 16384 bytes)\n" +
+    "Pages free:                    100000.\n" +
+    "Pages inactive:                200000.\n" +
+    "Pages speculative:              50000.\n" +
+    "Pages purgeable:                 10000.\n";
+  const exec = (cmd) => (cmd.includes("vm_stat") ? vmStat : null);
+  const s = probeSpecs({
+    osMod: fakeOs({ platform: "darwin", arch: "arm64", ramMB: 24576 }),
+    exec,
+  });
+  // (100000+200000+50000+10000) pages * 16384 B / 1MiB = 5625 MB
+  assert.equal(s.availableRamMB, 5625);
+});
+
+test("Apple Silicon is detected as a unified-memory GPU", () => {
+  const s = probeSpecs({
+    osMod: fakeOs({ platform: "darwin", arch: "arm64", ramMB: 24576 }),
+    exec: () => null,
+  });
+  assert.equal(s.appleSilicon, true);
+  assert.equal(s.gpu.present, true);
+  assert.equal(s.gpu.kind, "apple");
+  // unified memory: VRAM tracks system RAM
+  assert.equal(s.gpu.vramMB, 24576);
+});
+
+test("NVIDIA GPU is detected via nvidia-smi VRAM query", () => {
+  const exec = (cmd) => (cmd.includes("nvidia-smi") ? "24564" : null);
+  const s = probeSpecs({ osMod: fakeOs({ platform: "linux" }), exec });
+  assert.equal(s.gpu.present, true);
+  assert.equal(s.gpu.kind, "nvidia");
+  assert.equal(s.gpu.vramMB, 24564);
+});
+
+test("no GPU when nvidia-smi is absent / fails", () => {
+  const s = probeSpecs({
+    osMod: fakeOs({ platform: "linux" }),
+    exec: () => {
+      throw new Error("command not found");
+    },
+  });
+  assert.equal(s.gpu.present, false);
+  assert.equal(s.gpu.vramMB, 0);
+});
+
+// --- download disclosure: what the user is agreeing to before the pull ---
+
+const fakeHome = { homedir: () => "/home/tester" };
+// statfs reports blocks, not bytes: bavail * bsize. 1 MB blocks keep the sums
+// readable, and mirror the real struct's shape.
+const fakeStatfs = (freeMB, existsOnly) => (path) => {
+  if (existsOnly && path !== existsOnly) throw new Error(`ENOENT: ${path}`);
+  return { bavail: freeMB, bsize: 1e6 };
+};
+
+test("weightsCacheDir follows huggingface_hub's precedence", () => {
+  assert.equal(
+    weightsCacheDir({ env: {}, osMod: fakeHome }),
+    "/home/tester/.cache/huggingface/hub",
+  );
+  assert.equal(weightsCacheDir({ env: { HF_HOME: "/data/hf" }, osMod: fakeHome }), "/data/hf/hub");
+  assert.equal(
+    weightsCacheDir({ env: { HF_HOME: "/data/hf", HUGGINGFACE_HUB_CACHE: "/c" }, osMod: fakeHome }),
+    "/c",
+    "HUGGINGFACE_HUB_CACHE outranks HF_HOME",
+  );
+  assert.equal(
+    weightsCacheDir({ env: { HF_HUB_CACHE: "/a", HUGGINGFACE_HUB_CACHE: "/c" }, osMod: fakeHome }),
+    "/a",
+    "HF_HUB_CACHE wins outright",
+  );
+});
+
+test("freeSpaceMB walks up to the deepest existing ancestor", () => {
+  // the cache dir does not exist until the first download, and statfs throws
+  // on a missing path - so the answer has to come from an ancestor
+  const statfs = fakeStatfs(4096, "/home");
+  assert.equal(freeSpaceMB("/home/tester/.cache/huggingface/hub", statfs), 4096);
+});
+
+test("freeSpaceMB reports null rather than zero when nothing can be read", () => {
+  assert.equal(
+    freeSpaceMB("/home/tester/.cache", () => {
+      throw new Error("EACCES");
+    }),
+    null,
+    "unknown must not be reported as no-space",
+  );
+});
+
+test("describeDownload names the size and where it lands", () => {
+  const msg = describeDownload(87500, {
+    statfsFn: fakeStatfs(200000),
+    env: {},
+    osMod: fakeHome,
+  });
+  assert.match(msg, /~87\.5GB/);
+  assert.match(msg, /\/home\/tester\/\.cache\/huggingface\/hub/);
+  assert.match(msg, /200\.0GB free/);
+  assert.equal(/NOT fit/.test(msg), false, "it fits, so no warning");
+});
+
+test("describeDownload says plainly when the weights will not fit", () => {
+  const msg = describeDownload(87500, {
+    statfsFn: fakeStatfs(14000),
+    env: {},
+    osMod: fakeHome,
+  });
+  assert.match(msg, /only 14\.0GB is free there/);
+  assert.match(msg, /will NOT fit as-is/);
+  // the tier is still described, not withheld: a machine that could free up
+  // space should know the tier exists
+  assert.match(msg, /~87\.5GB/);
+});
+
+test("describeDownload admits when free space is unknown", () => {
+  const msg = describeDownload(87500, {
+    statfsFn: () => {
+      throw new Error("EACCES");
+    },
+    env: {},
+    osMod: fakeHome,
+  });
+  assert.match(msg, /free space unknown/);
+  assert.equal(/NOT fit/.test(msg), false, "unknown is not a refusal");
+});