dsh-hyperframes 0.10.2 → 0.11.0

package/skills/media-use/scripts/lib/prefs-store.concurrent.test.mjs

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import { fork } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { projectPrefsPath, recordPreference, userPrefsPath } from "./prefs-store.mjs";
+
+async function inSandbox(task) {
+  const root = mkdtempSync(join(tmpdir(), "mu-prefs-concurrent-"));
+  const previousHome = process.env.HYPERFRAMES_MEDIA_HOME;
+  process.env.HYPERFRAMES_MEDIA_HOME = join(root, "home");
+  const project = join(root, "project");
+  mkdirSync(project);
+  try {
+    await task({ root, project });
+  } finally {
+    if (previousHome === undefined) delete process.env.HYPERFRAMES_MEDIA_HOME;
+    else process.env.HYPERFRAMES_MEDIA_HOME = previousHome;
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function worker(root, source, args = []) {
+  const path = join(mkdtempSync(join(root, "worker-")), "worker.cjs");
+  writeFileSync(path, source);
+  const child = fork(path, args, { silent: true, execArgv: [] });
+  let stderr = "";
+  child.stderr.setEncoding("utf8").on("data", (data) => (stderr += data));
+  const ready = new Promise((resolve, reject) => {
+    child.once("message", resolve);
+    child.once("error", reject);
+    child.once("exit", () => reject(new Error(`worker exited before ready: ${stderr}`)));
+  });
+  const closed = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code) => resolve({ code, stderr }));
+  });
+  return { child, ready, closed };
+}
+
+for (const tier of ["project", "user"]) {
+  test(`record re-reads the ${tier} tier after another process releases its lock`, async () => {
+    await inSandbox(async ({ root, project }) => {
+      const path = tier === "project" ? projectPrefsPath(project) : userPrefsPath();
+      mkdirSync(dirname(path), { recursive: true });
+      const held = worker(
+        root,
+        `const fs = require("node:fs");
+         const path = process.argv[2];
+         fs.writeFileSync(path + ".lock", "held", { flag: "wx" });
+         process.send("locked");
+         setTimeout(() => {
+           fs.writeFileSync(path, JSON.stringify({version: 1,
+             preferences: {aspect: {value: "1080x1920", confirmed_in: ["other"]}},
+             sightings: {aspect: {"1080x1920": ["other"]}}}));
+           fs.rmSync(path + ".lock");
+           process.disconnect();
+         }, 300);`,
+        [path],
+      );
+      try {
+        await held.ready;
+        recordPreference({ projectDir: project, key: "destination", value: "youtube-shorts" });
+        const result = await held.closed;
+        assert.equal(result.code, 0, result.stderr);
+        const file = JSON.parse(readFileSync(path, "utf8"));
+        assert.equal(file.preferences.aspect?.value, "1080x1920");
+        if (tier === "project") {
+          assert.equal(file.preferences.destination?.value, "youtube-shorts");
+        } else {
+          assert.deepEqual(file.sightings.destination?.["youtube-shorts"], ["project"]);
+          assert.deepEqual(file.sightings.aspect?.["1080x1920"], ["other"]);
+        }
+      } finally {
+        held.child.kill();
+        await held.closed;
+      }
+    });
+  });
+}
+
+test("parallel records preserve every project key and promote every shared user sighting", async () => {
+  await inSandbox(async ({ root, project }) => {
+    const secondProject = join(root, "second-project");
+    mkdirSync(secondProject);
+    const modulePath = fileURLToPath(new URL("./prefs-store.mjs", import.meta.url));
+    const choices = {
+      destination: "youtube-shorts",
+      aspect: "1080x1920",
+      language: "en",
+      flow: "automation",
+    };
+    const children = [project, secondProject].flatMap((projectDir) =>
+      Object.entries(choices).map(([key, value]) =>
+        worker(
+          root,
+          `const {pathToFileURL} = require("node:url");
+           import(pathToFileURL(process.argv[2])).then(({recordPreference}) => {
+             process.send("ready");
+             process.once("message", () => {
+               try {recordPreference(JSON.parse(process.argv[3]));}
+               catch (error) {console.error(error.message); process.exitCode = 1;}
+               process.disconnect();
+             });
+           });`,
+          [modulePath, JSON.stringify({ projectDir, key, value })],
+        ),
+      ),
+    );
+    try {
+      await Promise.all(children.map((child) => child.ready));
+      for (const child of children) child.child.send("record");
+      const results = await Promise.all(children.map((child) => child.closed));
+      for (const result of results) assert.equal(result.code, 0, result.stderr);
+      for (const projectDir of [project, secondProject]) {
+        const file = JSON.parse(readFileSync(projectPrefsPath(projectDir), "utf8"));
+        assert.deepEqual(Object.keys(file.preferences).sort(), Object.keys(choices).sort());
+        for (const [key, value] of Object.entries(choices))
+          assert.equal(file.preferences[key].value, value);
+        assert.deepEqual(readdirSync(dirname(projectPrefsPath(projectDir))), ["preferences.json"]);
+      }
+      const user = JSON.parse(readFileSync(userPrefsPath(), "utf8"));
+      for (const [key, value] of Object.entries(choices)) {
+        assert.equal(user.preferences[key].value, value);
+        assert.deepEqual(user.sightings[key][value].sort(), ["project", "second-project"]);
+      }
+      assert.deepEqual(readdirSync(dirname(userPrefsPath())), ["preferences.json"]);
+    } finally {
+      for (const child of children) child.child.kill();
+      await Promise.all(children.map((child) => child.closed));
+    }
+  });
+});
+
+for (const tier of ["project", "user"]) {
+  test(`an abandoned ${tier} lock never permits an unlocked preference write`, async () => {
+    await inSandbox(async ({ project }) => {
+      const path = tier === "project" ? projectPrefsPath(project) : userPrefsPath();
+      mkdirSync(dirname(path), { recursive: true });
+      const original = JSON.stringify({ version: 1, preferences: {}, sightings: {} });
+      writeFileSync(path, original);
+      const lock = `${path}.lock`;
+      writeFileSync(lock, "abandoned");
+      const past = new Date(Date.now() - 60_000);
+      utimesSync(lock, past, past);
+      const record = () => recordPreference({ projectDir: project, key: "language", value: "en" });
+      if (tier === "project") {
+        assert.throws(record, (error) => error.code === "HF_SETTINGS_LOCKED");
+        assert.equal(existsSync(userPrefsPath()), false);
+      } else {
+        assert.equal(record().promoted, false);
+        assert.equal(
+          JSON.parse(readFileSync(projectPrefsPath(project), "utf8")).preferences.language.value,
+          "en",
+        );
+      }
+      assert.equal(readFileSync(path, "utf8"), original);
+      assert.equal(readFileSync(lock, "utf8"), "abandoned");
+      assert.equal(existsSync(`${path}.${process.pid}.tmp`), false);
+    });
+  });
+}

package/skills/media-use/scripts/lib/prefs-store.test.mjs

@@ -0,0 +1,245 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import fs from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  mergedPreferences,
+  preferenceKeyFor,
+  projectPrefsPath,
+  recordPreference,
+  userPrefsPath,
+} from "./prefs-store.mjs";
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-prefs-"));
+  const home = join(root, "home");
+  const projectA = join(root, "proj-a");
+  const projectB = join(root, "proj-b");
+  mkdirSync(home, { recursive: true });
+  mkdirSync(projectA, { recursive: true });
+  mkdirSync(projectB, { recursive: true });
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
+  return { root, home, projectA, projectB };
+}
+
+function restoreEnv(saved) {
+  for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+  Object.assign(process.env, saved);
+}
+
+function withSandbox(fn) {
+  const savedEnv = { ...process.env };
+  const box = sandbox();
+  try {
+    fn(box);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(box.root, { recursive: true, force: true });
+  }
+}
+
+for (const code of ["EPERM", "EBUSY"]) {
+  test(`temporary-file cleanup ${code} does not fail a successful preference record`, (t) => {
+    const remove = fs.rmSync;
+    t.mock.method(fs, "rmSync", (path, options) => {
+      if (path.endsWith(".tmp")) throw Object.assign(new Error("cleanup failed"), { code });
+      return remove(path, options);
+    });
+    syncBuiltinESMExports();
+    t.after(() => {
+      t.mock.restoreAll();
+      syncBuiltinESMExports();
+    });
+
+    withSandbox(({ projectA, projectB }) => {
+      recordPreference({ projectDir: projectA, key: "language", value: "en" });
+      const second = recordPreference({ projectDir: projectB, key: "language", value: "en" });
+      assert.equal(second.promoted, true);
+      for (const path of [
+        projectPrefsPath(projectA),
+        projectPrefsPath(projectB),
+        userPrefsPath(),
+      ]) {
+        assert.equal(JSON.parse(readFileSync(path, "utf8")).preferences.language.value, "en");
+      }
+    });
+  });
+
+  test(`temporary-file cleanup ${code} preserves the original preference write error`, (t) => {
+    const remove = fs.rmSync;
+    const write = fs.writeFileSync;
+    const writeError = Object.assign(new Error("disk full"), { code: "ENOSPC" });
+    t.mock.method(fs, "rmSync", (path, options) => {
+      if (path.endsWith(".tmp")) throw Object.assign(new Error("cleanup failed"), { code });
+      return remove(path, options);
+    });
+    t.mock.method(fs, "writeFileSync", (path, ...args) => {
+      if (path.endsWith(".tmp")) throw writeError;
+      return write(path, ...args);
+    });
+    syncBuiltinESMExports();
+    t.after(() => {
+      t.mock.restoreAll();
+      syncBuiltinESMExports();
+    });
+
+    withSandbox(({ projectA }) => {
+      assert.throws(
+        () => recordPreference({ projectDir: projectA, key: "language", value: "en" }),
+        (error) => error === writeError,
+      );
+    });
+  });
+}
+
+test("record writes the project tier and get merges it as source=project", () => {
+  withSandbox(({ projectA }) => {
+    const result = recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    assert.equal(result.promoted, false);
+    assert.deepEqual(result.confirmed_in, ["proj-a"]);
+
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.destination.value, "x-feed");
+    assert.equal(merged.destination.source, "project");
+
+    const onDisk = JSON.parse(readFileSync(projectPrefsPath(projectA), "utf8"));
+    assert.equal(onDisk.preferences.destination.value, "x-feed");
+  });
+});
+
+test("one project never promotes: a fresh project sees nothing user-tier", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    // proj-b has no project entry, and the value was only confirmed once.
+    assert.equal(mergedPreferences(projectB).destination, undefined);
+  });
+});
+
+test("the same value confirmed in two projects promotes to the user tier", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    const second = recordPreference({ projectDir: projectB, key: "destination", value: "x-feed" });
+    assert.equal(second.promoted, true);
+
+    const userFile = JSON.parse(readFileSync(userPrefsPath(), "utf8"));
+    assert.deepEqual(userFile.preferences.destination.confirmed_in.sort(), ["proj-a", "proj-b"]);
+
+    // A third project with no local entry now inherits the promoted default.
+    const projectC = join(projectA, "..", "proj-c");
+    mkdirSync(projectC, { recursive: true });
+    const merged = mergedPreferences(projectC);
+    assert.equal(merged.destination.value, "x-feed");
+    assert.equal(merged.destination.source, "user");
+  });
+});
+
+test("record is idempotent per project — confirmed_in stays deduped", () => {
+  withSandbox(({ projectA }) => {
+    recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    const again = recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    assert.deepEqual(again.confirmed_in, ["proj-a"]);
+    assert.equal(again.promoted, false);
+  });
+});
+
+test("a changed value restarts provenance instead of inheriting confirmations", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    recordPreference({ projectDir: projectB, key: "destination", value: "x-feed" });
+    const switched = recordPreference({
+      projectDir: projectA,
+      key: "destination",
+      value: "youtube",
+    });
+    assert.deepEqual(switched.confirmed_in, ["proj-a"]);
+    assert.equal(switched.promoted, false);
+    // The previously promoted value keeps serving other projects until youtube
+    // earns its own two confirmations.
+    const userFile = JSON.parse(readFileSync(userPrefsPath(), "utf8"));
+    assert.equal(userFile.preferences.destination.value, "x-feed");
+  });
+});
+
+test("project tier overrides a promoted user-tier value", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "yes" });
+    recordPreference({ projectDir: projectB, key: "storyboard", value: "yes" });
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "no" });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.storyboard.value, "no");
+    assert.equal(merged.storyboard.source, "project");
+  });
+});
+
+test("the retired mode key is rejected", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(
+      () => recordPreference({ projectDir: projectA, key: "mode", value: "collaborative" }),
+      /unknown preference key/,
+    );
+  });
+});
+
+test("the run-shape keys record and promote like any field", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "flow", value: "automation" });
+    const promoted = recordPreference({ projectDir: projectB, key: "flow", value: "automation" });
+    assert.equal(promoted.promoted, true);
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "yes" });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.flow.value, "automation");
+    assert.equal(merged.storyboard.value, "yes");
+    assert.equal(merged.storyboard.source, "project");
+  });
+});
+
+test("style_preset is keyed per workflow", () => {
+  withSandbox(({ projectA }) => {
+    assert.equal(
+      preferenceKeyFor("style_preset", "faceless-explainer"),
+      "style_preset.faceless-explainer",
+    );
+    assert.equal(preferenceKeyFor("destination", "faceless-explainer"), "destination");
+    recordPreference({
+      projectDir: projectA,
+      key: "style_preset",
+      value: "pin-and-paper",
+      workflow: "faceless-explainer",
+    });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged["style_preset.faceless-explainer"].value, "pin-and-paper");
+    assert.equal(merged["style_preset"], undefined);
+  });
+});
+
+test("style_preset without a workflow is rejected, never stored bare", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(
+      () => recordPreference({ projectDir: projectA, key: "style_preset", value: "pin-and-paper" }),
+      /pass --workflow/,
+    );
+    assert.deepEqual(mergedPreferences(projectA), {});
+  });
+});
+
+test("unknown keys and empty values are rejected", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(() => recordPreference({ projectDir: projectA, key: "vibe", value: "x" }));
+    assert.throws(() => recordPreference({ projectDir: projectA, key: "voice", value: "  " }));
+  });
+});
+
+test("corrupt files are treated as empty instead of crashing", () => {
+  withSandbox(({ projectA, home }) => {
+    mkdirSync(join(projectA, ".media"), { recursive: true });
+    writeFileSync(projectPrefsPath(projectA), "not json");
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(userPrefsPath(), '{"preferences": 42}');
+    assert.deepEqual(mergedPreferences(projectA), {});
+    const result = recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    assert.equal(result.value, "zh");
+  });
+});

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

@@ -0,0 +1,46 @@
+import { execFileSync } from "node:child_process";
+import { extname } from "node:path";
+import { ffprobeBinary } from "./ff-binaries.mjs";
+
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".ico"]);
+const AUDIO_EXT = new Set([".mp3", ".wav", ".ogg", ".m4a", ".aac"]);
+
+export function probe(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === ".svg") return { width: null, height: null, duration: null, codec: "svg" };
+
+  const ffprobe = ffprobeBinary();
+  try {
+    // execFileSync (no shell) so a hostile filename like `"; rm -rf ~; ".png`
+    // can't break out of the quoting — filePath is passed as a literal argv entry.
+    const raw = execFileSync(
+      ffprobe,
+      ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", "--", filePath],
+      { encoding: "utf8", timeout: 5000 },
+    );
+    const info = JSON.parse(raw);
+    const streams = info.streams ?? [];
+    const wantedType = AUDIO_EXT.has(ext) ? "audio" : "video";
+    const stream =
+      streams.find((s) => s.codec_type === wantedType && s.disposition?.attached_pic !== 1) ??
+      streams[0];
+    const format = info.format;
+
+    const isImage = IMAGE_EXT.has(ext);
+    const duration = isImage
+      ? null
+      : parseFloat(format?.duration) || parseFloat(stream?.duration) || null;
+    const width = parseInt(stream?.width, 10) || null;
+    const height = parseInt(stream?.height, 10) || null;
+    const codec = stream?.codec_name || null;
+
+    return {
+      duration: duration != null ? Math.round(duration * 10) / 10 : null,
+      width,
+      height,
+      codec,
+    };
+  } catch {
+    return { duration: null, width: null, height: null, codec: null };
+  }
+}

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

@@ -0,0 +1,221 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { probe } from "./probe.mjs";
+import childProcess from "node:child_process";
+import { syncBuiltinESMExports } from "node:module";
+
+function mockProbe(t, streams, format = { duration: "2" }) {
+  t.mock.method(childProcess, "execFileSync", () => JSON.stringify({ streams, format }));
+  syncBuiltinESMExports();
+  t.after(() => {
+    t.mock.restoreAll();
+    syncBuiltinESMExports();
+  });
+}
+
+const AUDIO_STREAM = { codec_type: "audio", codec_name: "aac", duration: "3" };
+const VIDEO_STREAM = {
+  codec_type: "video",
+  codec_name: "h264",
+  width: 64,
+  height: 48,
+  duration: "4",
+};
+const COVER_STREAM = {
+  codec_type: "video",
+  codec_name: "mjpeg",
+  width: 100,
+  height: 100,
+  disposition: { attached_pic: 1 },
+};
+
+for (const [name, streams] of [
+  ["audio before video", [AUDIO_STREAM, VIDEO_STREAM]],
+  ["video before audio", [VIDEO_STREAM, AUDIO_STREAM]],
+  ["cover art before video", [COVER_STREAM, AUDIO_STREAM, VIDEO_STREAM]],
+]) {
+  test(`probe selects the video stream with ${name}`, (t) => {
+    mockProbe(t, streams);
+    assert.deepEqual(probe("clip.mp4"), {
+      duration: 2,
+      width: 64,
+      height: 48,
+      codec: "h264",
+    });
+  });
+}
+
+test("probe selects audio metadata for an audio file with cover art", (t) => {
+  mockProbe(t, [COVER_STREAM, AUDIO_STREAM]);
+  assert.deepEqual(probe("song.m4a"), { duration: 2, width: null, height: null, codec: "aac" });
+});
+
+test("probe uses the selected video's duration when the container has none", (t) => {
+  mockProbe(t, [AUDIO_STREAM, VIDEO_STREAM], {});
+  assert.equal(probe("clip.mp4").duration, 4);
+});
+
+test("probe selects image dimensions without reporting an image duration", (t) => {
+  mockProbe(t, [AUDIO_STREAM, VIDEO_STREAM]);
+  assert.deepEqual(probe("frame.png"), {
+    duration: null,
+    width: 64,
+    height: 48,
+    codec: "h264",
+  });
+});
+
+test("probe retains audio-only metadata and the empty-stream fallback", (t) => {
+  mockProbe(t, [AUDIO_STREAM]);
+  assert.deepEqual(probe("clip.mp4"), { duration: 2, width: null, height: null, codec: "aac" });
+});
+
+test("probe retains the container duration when no streams are reported", (t) => {
+  mockProbe(t, []);
+  assert.deepEqual(probe("clip.mp4"), { duration: 2, width: null, height: null, codec: null });
+});
+
+// Regression for the shell-injection fix: probe() must pass the path as a literal
+// argv entry, never through a shell. A filename containing shell metacharacters
+// must NOT execute. Under the old execSync(`ffprobe ... "${path}"`) the embedded
+// `touch` ran and created the marker; under execFileSync it cannot, regardless of
+// whether ffprobe is installed (the injected command never reaches a shell).
+test("probe does not execute shell metacharacters in a filename", () => {
+  const dir = mkdtempSync(join(tmpdir(), "probe-inject-"));
+  const marker = join(dir, "INJECTED");
+  // Slash-free basename (a real on-disk filename) that breaks out of the old
+  // double-quoted interpolation and would `touch INJECTED` in the cwd.
+  const evil = join(dir, `clip"; touch INJECTED; echo ".mp4`);
+  const prevCwd = process.cwd();
+  try {
+    writeFileSync(evil, "not real media");
+    process.chdir(dir); // so a leaked `touch INJECTED` would land next to `marker`
+    const meta = probe(evil);
+    assert.equal(existsSync(marker), false, "injected `touch` must not have run");
+    // Bogus/unreadable media still returns the null-shaped result, never throws.
+    assert.deepEqual(Object.keys(meta).sort(), ["codec", "duration", "height", "width"]);
+  } finally {
+    process.chdir(prevCwd);
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test(
+  "probe runs the ffprobe HYPERFRAMES_FFPROBE_PATH names",
+  { skip: process.platform === "win32" },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "probe-ffprobe-path-"));
+    const fake = join(dir, "fake-ffprobe");
+    writeFileSync(
+      fake,
+      `#!/bin/sh\n[ "$1" = -version ] && echo 'ffprobe version fake' && exit 0\necho '{"streams":[{"width":7,"height":3,"codec_name":"fake"}]}'\n`,
+    );
+    chmodSync(fake, 0o755);
+    const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+    process.env.HYPERFRAMES_FFPROBE_PATH = fake;
+    try {
+      assert.deepEqual(probe(join(dir, "clip.png")), {
+        duration: null,
+        width: 7,
+        height: 3,
+        codec: "fake",
+      });
+    } finally {
+      if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+      else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+test("probe refuses an HYPERFRAMES_FFPROBE_PATH that cannot run instead of reporting no metadata", () => {
+  const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+  process.env.HYPERFRAMES_FFPROBE_PATH = join(tmpdir(), "no-ffprobe-here", "ffprobe");
+  try {
+    assert.throws(
+      () => probe("clip.wav"),
+      /HYPERFRAMES_FFPROBE_PATH names ".*no-ffprobe-here.*fix it or unset it/,
+    );
+  } finally {
+    if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+  }
+});
+
+test("probe refuses an HYPERFRAMES_FFPROBE_PATH that names a folder", () => {
+  const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+  process.env.HYPERFRAMES_FFPROBE_PATH = tmpdir();
+  try {
+    assert.throws(() => probe("clip.wav"), /HYPERFRAMES_FFPROBE_PATH names .*fix it or unset it/);
+  } finally {
+    if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+  }
+});
+
+function withFfprobePath(value, run) {
+  const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+  process.env.HYPERFRAMES_FFPROBE_PATH = value;
+  try {
+    return run();
+  } finally {
+    if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+  }
+}
+
+test(
+  "probe refuses a configured ffprobe that cannot start, exits with an error, or is another tool",
+  {
+    skip: process.platform === "win32",
+  },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "probe-broken-ffprobe-"));
+    try {
+      const noInterpreter = join(dir, "no-interpreter");
+      writeFileSync(noInterpreter, "#!/nonexistent/interpreter\n");
+      const failing = join(dir, "failing");
+      writeFileSync(failing, "#!/bin/sh\nexit 3\n");
+      const otherTool = join(dir, "other-tool");
+      writeFileSync(otherTool, "#!/bin/sh\necho 'ffmpeg version 9.9'\n");
+      for (const broken of [noInterpreter, failing, otherTool]) {
+        chmodSync(broken, 0o755);
+        withFfprobePath(broken, () =>
+          assert.throws(
+            () => probe("clip.wav"),
+            /HYPERFRAMES_FFPROBE_PATH names .*fix it or unset it/,
+          ),
+        );
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+test(
+  "probe runs a relative HYPERFRAMES_FFPROBE_PATH from the working folder, not from PATH",
+  {
+    skip: process.platform === "win32",
+  },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "probe-relative-ffprobe-"));
+    const prevCwd = process.cwd();
+    try {
+      writeFileSync(
+        join(dir, "local-ffprobe"),
+        `#!/bin/sh\n[ "$1" = -version ] && echo 'ffprobe version fake' && exit 0\necho '{"streams":[{"width":5,"height":4,"codec_name":"local"}]}'\n`,
+      );
+      chmodSync(join(dir, "local-ffprobe"), 0o755);
+      process.chdir(dir);
+      const meta = withFfprobePath("local-ffprobe", () => probe("clip.png"));
+      assert.deepEqual(meta, { duration: null, width: 5, height: 4, codec: "local" });
+    } finally {
+      process.chdir(prevCwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);

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

@@ -0,0 +1,5 @@
+// Back-compat surface for the v1 provider API. The ordered, capability-based
+// registry now lives in registry.mjs; this re-exports the v1 helpers so existing
+// callers keep working. New code should import from registry.mjs directly
+// (getProviders / runCapability).
+export { getProvider, listTypes } from "./registry.mjs";