dsh-hyperframes 0.9.1 → 0.9.2

package/skills/media-use/audio/scripts/audio.test.mjs

@@ -1,14 +1,20 @@
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
-import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, existsSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { recordInManifest } from "./lib/media-record.mjs";
 import { resolveSfx } from "./lib/sfx.mjs";
 
 // Proves the relocated engine (skills/media-use/audio/) still resolves its
 // bundled SFX library from the moved location — the path most likely to break
-// on a subtree move. Offline (heygenOK:false), no network.
+// on a subtree move. Openverse is unreachable unless a test serves it.
+const offline = async () => {
+  throw new TypeError("fetch failed");
+};
+globalThis.fetch = offline;
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const sfxLibDir = join(HERE, "..", "assets", "sfx"); // same offset the engine uses
@@ -19,7 +25,6 @@ test("bundled SFX library resolves from the relocated path", async () => {
   try {
     const { sfx, anomalies } = await resolveSfx({
       cues: [{ id: "1", name: "whoosh" }],
-      heygenOK: false,
       hyperframesDir: dir,
       sfxLibDir,
     });
@@ -37,7 +42,6 @@ test("an unknown cue is reported, not fatal", async () => {
   try {
     const { sfx, anomalies } = await resolveSfx({
       cues: [{ id: "1", name: "definitely-not-a-real-sfx" }],
-      heygenOK: false,
       hyperframesDir: dir,
       sfxLibDir,
     });
@@ -47,3 +51,116 @@ test("an unknown cue is reported, not fatal", async () => {
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test("a person's own file under a bundled name survives, and the cue gets the next free name", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-audio-"));
+  try {
+    const own = join(dir, "assets", "sfx", "whoosh.mp3");
+    mkdirSync(dirname(own), { recursive: true });
+    writeFileSync(own, "the person's own whoosh");
+    const resolve = () =>
+      resolveSfx({
+        cues: [{ id: "1", name: "whoosh" }],
+        hyperframesDir: dir,
+        sfxLibDir,
+      });
+
+    const first = await resolve();
+    const second = await resolve();
+
+    assert.equal(readFileSync(own, "utf8"), "the person's own whoosh");
+    assert.deepEqual(
+      [first, second].map(({ sfx }) => [sfx[0].file, sfx[0].source]),
+      [
+        ["assets/sfx/whoosh-2.mp3", "local"],
+        ["assets/sfx/whoosh-2.mp3", "local"],
+      ],
+    );
+    assert.deepEqual(
+      readFileSync(join(dir, "assets/sfx/whoosh-2.mp3")),
+      readFileSync(join(sfxLibDir, "whoosh.mp3")),
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("two effects never share a file when one's name is taken by the person, run after run", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-audio-"));
+  try {
+    mkdirSync(join(dir, "assets", "sfx"), { recursive: true });
+    writeFileSync(join(dir, "assets", "sfx", "glitch.mp3"), "the person's own glitch");
+    globalThis.fetch = async (url) => {
+      const query = new URL(url).searchParams.get("q");
+      if (query)
+        return Response.json({
+          results: [
+            {
+              license: "cc0",
+              filetype: "mp3",
+              duration: 500,
+              url: `https://sound.test/${encodeURIComponent(query)}`,
+            },
+          ],
+        });
+      return new Response(`bytes of ${new URL(url).pathname}`);
+    };
+    const run = async (names) => {
+      const { sfx } = await resolveSfx({
+        cues: names.map((name, index) => ({ id: String(index), name })),
+        hyperframesDir: dir,
+        sfxLibDir,
+      });
+      const files = sfx.map(({ file }) => file);
+      recordInManifest(
+        dir,
+        [...new Set(files)].map((path) => ({ path, type: "sfx", source: "search" })),
+      );
+      return files;
+    };
+    try {
+      assert.deepEqual(await run(["glitch"]), ["assets/sfx/glitch-2.mp3"]);
+      assert.deepEqual(await run(["glitch", "glitch 2", "glitch"]), [
+        "assets/sfx/glitch-2.mp3",
+        "assets/sfx/glitch-2-2.mp3",
+        "assets/sfx/glitch-2.mp3",
+      ]);
+    } finally {
+      globalThis.fetch = offline;
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// The engine owns speed parsing; a fallback before the check would turn 0 or junk into 1.
+function runEngineWith(request, ...args) {
+  const dir = mkdtempSync(join(tmpdir(), "audio-speed-range-"));
+  try {
+    writeFileSync(join(dir, "audio_request.json"), JSON.stringify({ lines: [], ...request }));
+    return spawnSync(process.execPath, [join(HERE, "audio.mjs"), "--hyperframes", dir, ...args], {
+      encoding: "utf8",
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+for (const [label, request, args, shown] of [
+  ["request speed 5", { speed: 5 }, [], "5"],
+  ["request speed 0", { speed: 0 }, [], "0"],
+  ["request speed -1", { speed: -1 }, [], "-1"],
+  ["request speed text", { speed: "fast" }, [], '"fast"'],
+  ["--speed 0", {}, ["--speed", "0"], '"0"'],
+  ["--speed text", { speed: 1 }, ["--speed", "abc"], '"abc"'],
+]) {
+  test(`${label} stops the engine before any TTS runs`, () => {
+    const r = runEngineWith(request, ...args);
+    assert.equal(r.status, 1);
+    assert.ok(r.stderr.includes(`speed must be above 0 and at most 3, got ${shown}`), r.stderr);
+  });
+}
+
+test("a numeric string speed, as the adapters forward it, passes the check", () => {
+  assert.doesNotMatch(runEngineWith({ speed: "0.8" }, "--only", "tts").stderr, /speed must/);
+});

package/skills/{hyperframes-audio → media-use/audio}/scripts/carve.mjs

@@ -26,9 +26,10 @@
 
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { isMainModule } from "./lib/main-module.mjs";
 
 /** Sample rate the analysis runs at. Matches Studio's own decode rate, so the
  *  bands and envelopes come out the same either way. */
@@ -554,19 +555,6 @@ async function main() {
 
 // Only run as a CLI. Guarded so the pure helpers above can be unit-tested by
 // importing this module (`skills/**/*.test.mjs`, run by `bun run test:skills`).
-//
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-function isMainModule(importMetaUrl) {
-  if (!process.argv[1]) return false;
-  try {
-    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
-  } catch {
-    return false;
-  }
-}
-
 if (isMainModule(import.meta.url)) {
   await main();
 }

package/skills/media-use/audio/scripts/gemini-pipeline.test.mjs

@@ -9,9 +9,15 @@ import { spawnSync } from "node:child_process";
 // external audio tools are fixtures. This is not a live synthesis/render test.
 for (const expired of [false, true]) {
   for (const only of ["tts", "tts,bgm,sfx"]) {
+    // With expired credentials the person already has an assets/voice/intro.wav, which the engine must keep.
+    const voicePath = expired ? "assets/voice/intro-2.wav" : "assets/voice/intro.wav";
     test(`Gemini engine returns caption metadata with ${expired ? "expired" : "absent"} HeyGen credentials (${only})`, (t) => {
       const dir = mkdtempSync(join(tmpdir(), "hf-gemini-pipeline-"));
       t.after(() => rmSync(dir, { recursive: true, force: true }));
+      if (expired) {
+        mkdirSync(join(dir, "assets/voice"), { recursive: true });
+        writeFileSync(join(dir, "assets/voice/intro.wav"), "the person's own intro");
+      }
       const config = join(dir, "heygen");
       mkdirSync(config);
       if (expired)
@@ -48,7 +54,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 const args = process.argv.slice(2);
-assert.deepEqual(args.slice(0, 3), ['hyperframes', 'transcribe', 'assets/voice/intro.wav']);
+assert.deepEqual(args.slice(0, 3), ['hyperframes', 'transcribe', '${voicePath}']);
 assert.ok(fs.existsSync(args[2]));
 assert.equal(args[args.indexOf('--model')+1], 'small.en');
 fs.writeFileSync(path.join(args[args.indexOf('--dir')+1], 'transcript.json'), JSON.stringify([
@@ -99,7 +105,7 @@ fs.writeFileSync(path.join(args[args.indexOf('--dir')+1], 'transcript.json'), JS
       assert.deepEqual(meta.voices, [
         {
           id: "intro",
-          path: "assets/voice/intro.wav",
+          path: voicePath,
           duration_s: 1.25,
           words: [
             { id: "w0", text: "Hello", start: 0.1, end: 0.4 },
@@ -108,6 +114,18 @@ fs.writeFileSync(path.join(args[args.indexOf('--dir')+1], 'transcript.json'), JS
         },
       ]);
       assert.equal(meta.total_duration_s, 1.25);
+      const manifest = readFileSync(join(dir, ".media/manifest.jsonl"), "utf8").trim().split("\n");
+      assert.deepEqual(
+        manifest
+          .map((line) => JSON.parse(line))
+          .map(({ path, type, source }) => [path, type, source]),
+        [[voicePath, "voice", "generated"]],
+      );
+      if (expired)
+        assert.equal(
+          readFileSync(join(dir, "assets/voice/intro.wav"), "utf8"),
+          "the person's own intro",
+        );
     });
   }
 }

package/skills/media-use/audio/scripts/heygen-tts.mjs

@@ -94,7 +94,7 @@ const voiceId = await resolveVoiceId({ provider: "heygen", userVoice, lang });
 if (!userVoice) console.error(`· using voice ${voiceId}`);
 
 // ---------- synthesize (shared engine code) ----------
-const { ok, words } = await synthesizeOne({
+const { ok, words, error } = await synthesizeOne({
   provider: "heygen",
   text,
   voiceId,
@@ -103,7 +103,8 @@ const { ok, words } = await synthesizeOne({
   wavAbs: output,
   hyperframesDir: process.cwd(),
 });
-if (!ok) die("synthesis failed (HeyGen request/transcode error)");
+// HeyGen's own refusal, verbatim: a caller shows it or acts on it (a deleted voice, a limit).
+if (!ok) die(error ?? "synthesis failed (HeyGen request/transcode error)");
 
 let wordCount = 0;
 if (wordsPath) {

package/skills/media-use/audio/scripts/heygen-tts.test.mjs

@@ -0,0 +1,38 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const script = fileURLToPath(new URL("./heygen-tts.mjs", import.meta.url));
+// Every fetch answers as HeyGen does for a voice that no longer exists.
+const refusing = `data:text/javascript,globalThis.fetch = async () => new Response(${JSON.stringify(
+  JSON.stringify({ error: { code: "voice_not_found", message: "Voice not found: vc_gone" } }),
+)}, { status: 404, headers: { "content-type": "application/json" } });`;
+
+test("a refused speech prints HeyGen's own message, so a caller can act on it", () => {
+  const dir = mkdtempSync(join(tmpdir(), "heygen-tts-"));
+  const run = spawnSync(
+    process.execPath,
+    ["--import", refusing, script, "Hello", "--voice", "vc_gone", "-o", join(dir, "out.mp3")],
+    {
+      cwd: dir,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        HEYGEN_API_KEY: "",
+        HYPERFRAMES_API_KEY: "",
+        HEYGEN_ACCESS_TOKEN: "t",
+      },
+    },
+  );
+  assert.equal(run.status, 1);
+  assert.match(run.stderr, /✗ heygen-tts: Voice not found: vc_gone\n/);
+  assert.doesNotMatch(
+    run.stderr,
+    /HTTP 404|"error"/,
+    "HeyGen's message alone, not the raw response",
+  );
+});

package/skills/media-use/audio/scripts/heygen-voice.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// HeyGen voice clones: `clone <audio> --name <n>`, `delete <voice_id>`, `list --prefix <p>` (references/tts.md).
+// The clone id works as `heygen-tts.mjs --voice <id>`. A refusal prints HeyGen's own message and exits 1.
+// Auth: same resolver as heygen-tts.mjs (lib/heygen.mjs).
+
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { parseArgs } from "node:util";
+import { heygenAuthHeaders, heygenJSON, heygenMessage, loadEnvFromDir } from "./lib/heygen.mjs";
+import { isMainModule } from "./lib/main-module.mjs";
+
+const MEDIA_TYPES = { ".mp3": "audio/mpeg", ".wav": "audio/wav" };
+const POLL_MS = 2_000;
+const DEADLINE_MS = 120_000;
+
+async function clone(file, name, headers, { sleep, now }) {
+  const mediaType = MEDIA_TYPES[extname(file).toLowerCase()];
+  if (!mediaType) throw new Error(`unsupported audio file ${file}: use .mp3 or .wav`);
+  const data = readFileSync(file).toString("base64");
+  const created = await heygenJSON("/voices/clone", {
+    method: "POST",
+    headers,
+    body: { voice_name: name, audio: { type: "base64", media_type: mediaType, data } },
+  });
+  const id = created.data.voice_clone_id;
+  const deadline = now() + DEADLINE_MS;
+  for (;;) {
+    const { data: voice } = await heygenJSON(`/voices/${id}`, { headers });
+    if (voice.status === "complete") return { voice_id: voice.voice_id ?? id };
+    if (voice.status === "failed") throw new Error(voice.failure_message || "voice clone failed");
+    if (now() >= deadline) throw new Error(`voice clone ${id} not ready after 120 s`);
+    await sleep(POLL_MS);
+  }
+}
+
+async function list(prefix, headers) {
+  const mine = [];
+  const seen = new Set();
+  let token;
+  do {
+    if (token && seen.has(token)) throw new Error(`HeyGen returned page token ${token} twice`);
+    if (token) seen.add(token);
+    const query = new URLSearchParams({ type: "private", limit: "100" });
+    if (token) query.set("token", token);
+    const page = await heygenJSON(`/voices?${query}`, { headers });
+    mine.push(...page.data.filter((v) => (v.name ?? "").startsWith(prefix)));
+    token = page.has_more ? page.next_token : null;
+  } while (token);
+  // ponytail: the list response has no created_at, so one GET per match; bounded by the clone limit.
+  return Promise.all(
+    mine.map(async ({ voice_id, name }) => {
+      const { data } = await heygenJSON(`/voices/${voice_id}`, { headers });
+      return { voice_id, name, created_at: data.created_at ?? null };
+    }),
+  );
+}
+
+export async function main(
+  argv,
+  {
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    now = Date.now,
+    out = (s) => process.stdout.write(`${s}\n`),
+    err = (s) => process.stderr.write(`${s}\n`),
+  } = {},
+) {
+  try {
+    const { positionals, values } = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: { name: { type: "string" }, prefix: { type: "string", default: "" } },
+    });
+    const [command, arg] = positionals;
+    if (command === "clone") {
+      if (!arg || !values.name) throw new Error("usage: clone <audio-file> --name <name>");
+      out(JSON.stringify(await clone(arg, values.name, heygenAuthHeaders(), { sleep, now })));
+    } else if (command === "delete") {
+      if (!arg) throw new Error("usage: delete <voice_id>");
+      await heygenJSON(`/voices/${encodeURIComponent(arg)}`, {
+        method: "DELETE",
+        headers: heygenAuthHeaders(),
+      });
+    } else if (command === "list") {
+      out(JSON.stringify(await list(values.prefix, heygenAuthHeaders())));
+    } else {
+      throw new Error("usage: heygen-voice.mjs clone|delete|list (see the header of this file)");
+    }
+    return 0;
+  } catch (e) {
+    err(heygenMessage(e));
+    return 1;
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  loadEnvFromDir(process.cwd());
+  process.exitCode = await main(process.argv.slice(2));
+}

package/skills/media-use/audio/scripts/heygen-voice.test.mjs

@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { main } from "./heygen-voice.mjs";
+
+const realFetch = globalThis.fetch;
+const savedEnv = {
+  HEYGEN_ACCESS_TOKEN: process.env.HEYGEN_ACCESS_TOKEN,
+  HEYGEN_API_KEY: process.env.HEYGEN_API_KEY,
+};
+let dir;
+let calls;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "heygen-voice-"));
+  delete process.env.HEYGEN_ACCESS_TOKEN;
+  process.env.HEYGEN_API_KEY = "hg_test";
+  calls = [];
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  for (const [k, v] of Object.entries(savedEnv)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// routes: "METHOD /path" → array of [status, body] answered in order (last one repeats).
+function mockFetch(routes) {
+  globalThis.fetch = async (url, opts) => {
+    const key = `${opts.method} ${String(url).replace("https://api.heygen.com/v3", "")}`;
+    calls.push({ key, opts });
+    const queue = routes[key];
+    if (!queue) throw new Error(`unexpected request ${key}`);
+    const [status, body] = queue.length > 1 ? queue.shift() : queue[0];
+    return new Response(body === undefined ? null : JSON.stringify(body), { status });
+  };
+}
+
+async function run(argv, { sleep = async () => {}, now = () => 0 } = {}) {
+  const out = [];
+  const err = [];
+  const code = await main(argv, {
+    sleep,
+    now,
+    out: (s) => out.push(s),
+    err: (s) => err.push(s),
+  });
+  return { code, out: out.join("\n"), err: err.join("\n") };
+}
+
+function audioFile(name = "sample.mp3") {
+  const path = join(dir, name);
+  writeFileSync(path, Buffer.from("fake-audio"));
+  return path;
+}
+
+test("clone uploads base64 audio, polls until complete, prints the voice id", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc1" } }]],
+    "GET /voices/vc1": [
+      [200, { data: { status: "processing", voice_id: "vc1" } }],
+      [200, { data: { status: "complete", voice_id: "vc1", name: "Me" } }],
+    ],
+  });
+  const sleeps = [];
+  const r = await run(["clone", audioFile(), "--name", "Me"], {
+    sleep: async (ms) => sleeps.push(ms),
+  });
+  assert.deepEqual(r, { code: 0, out: '{"voice_id":"vc1"}', err: "" });
+  assert.deepEqual(sleeps, [2000]);
+  const post = calls[0];
+  assert.equal(post.opts.headers["X-Api-Key"], "hg_test");
+  assert.deepEqual(JSON.parse(post.opts.body), {
+    voice_name: "Me",
+    audio: {
+      type: "base64",
+      media_type: "audio/mpeg",
+      data: Buffer.from("fake-audio").toString("base64"),
+    },
+  });
+});
+
+test("clone sends audio/wav for a .wav file", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc1" } }]],
+    "GET /voices/vc1": [[200, { data: { status: "complete", voice_id: "vc1" } }]],
+  });
+  const r = await run(["clone", audioFile("take.WAV"), "--name", "Me"]);
+  assert.equal(r.code, 0);
+  assert.equal(JSON.parse(calls[0].opts.body).audio.media_type, "audio/wav");
+});
+
+test("clone prints HeyGen's refusal verbatim and exits 1", async () => {
+  const message =
+    "Voice clone limit reached (10). Delete unused clones or contact support to increase your limit.";
+  mockFetch({
+    "POST /voices/clone": [[400, { error: { code: "resource_limit_reached", message } }]],
+  });
+  const r = await run(["clone", audioFile(), "--name", "Me"]);
+  assert.deepEqual(r, { code: 1, out: "", err: message });
+});
+
+test("clone surfaces a failed clone's failure_message", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc1" } }]],
+    "GET /voices/vc1": [[200, { data: { status: "failed", failure_message: "Audio too noisy" } }]],
+  });
+  const r = await run(["clone", audioFile(), "--name", "Me"]);
+  assert.deepEqual(r, { code: 1, out: "", err: "Audio too noisy" });
+});
+
+test("clone gives up after the 120 s deadline", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc1" } }]],
+    "GET /voices/vc1": [[200, { data: { status: "processing" } }]],
+  });
+  let clock = 0;
+  const r = await run(["clone", audioFile(), "--name", "Me"], {
+    now: () => clock,
+    sleep: async (ms) => {
+      clock += ms;
+    },
+  });
+  assert.deepEqual(r, { code: 1, out: "", err: "voice clone vc1 not ready after 120 s" });
+  assert.equal(calls.filter((c) => c.key === "GET /voices/vc1").length, 61);
+});
+
+test("clone rejects an audio type other than mp3 or wav without calling HeyGen", async () => {
+  mockFetch({});
+  const r = await run(["clone", audioFile("take.ogg"), "--name", "Me"]);
+  assert.equal(r.code, 1);
+  assert.match(r.err, /use \.mp3 or \.wav/);
+  assert.equal(calls.length, 0);
+});
+
+test("delete calls DELETE /voices/<id> and exits 0", async () => {
+  mockFetch({ "DELETE /voices/vc1": [[200, { data: {} }]] });
+  const r = await run(["delete", "vc1"]);
+  assert.deepEqual(r, { code: 0, out: "", err: "" });
+});
+
+test("delete exits 0 on a 204 with no body, and escapes the id in the path", async () => {
+  mockFetch({ "DELETE /voices/a%2Fb": [[204]] });
+  const r = await run(["delete", "a/b"]);
+  assert.deepEqual(r, { code: 0, out: "", err: "" });
+});
+
+test("clone falls back to the clone id when the finished voice has no voice_id", async () => {
+  mockFetch({
+    "POST /voices/clone": [[200, { data: { voice_clone_id: "vc9" } }]],
+    "GET /voices/vc9": [[200, { data: { status: "complete" } }]],
+  });
+  const r = await run(["clone", audioFile(), "--name", "Me"]);
+  assert.deepEqual(r, { code: 0, out: '{"voice_id":"vc9"}', err: "" });
+});
+
+test("list skips a nameless voice and stops on a page token HeyGen repeats", async () => {
+  mockFetch({
+    "GET /voices?type=private&limit=100": [
+      [200, { data: [{ voice_id: "n", name: null }], has_more: true, next_token: "t2" }],
+    ],
+    "GET /voices?type=private&limit=100&token=t2": [
+      [200, { data: [], has_more: true, next_token: "t2" }],
+    ],
+  });
+  // A fake answers at once, so a list that never stops would starve any timeout: cap the calls instead.
+  const answer = globalThis.fetch;
+  globalThis.fetch = (...args) =>
+    calls.length >= 10 ? Promise.reject(new Error("paged forever")) : answer(...args);
+  const r = await run(["list", "--prefix", "desk-"]);
+  assert.deepEqual(r, { code: 1, out: "", err: "HeyGen returned page token t2 twice" });
+});
+
+test("delete prints HeyGen's 404 message verbatim and exits 1", async () => {
+  mockFetch({
+    "DELETE /voices/gone": [
+      [404, { error: { code: "voice_not_found", message: "Voice not found: gone" } }],
+    ],
+  });
+  const r = await run(["delete", "gone"]);
+  assert.deepEqual(r, { code: 1, out: "", err: "Voice not found: gone" });
+});
+
+test("list pages through private voices and returns prefix matches with created_at", async () => {
+  mockFetch({
+    "GET /voices?type=private&limit=100": [
+      [
+        200,
+        {
+          data: [
+            { voice_id: "a", name: "desk-1" },
+            { voice_id: "b", name: "other" },
+          ],
+          has_more: true,
+          next_token: "t2",
+        },
+      ],
+    ],
+    "GET /voices?type=private&limit=100&token=t2": [
+      [200, { data: [{ voice_id: "c", name: "desk-2" }], has_more: false }],
+    ],
+    "GET /voices/a": [[200, { data: { voice_id: "a", created_at: 1700000000 } }]],
+    "GET /voices/c": [[200, { data: { voice_id: "c", created_at: 1700000100 } }]],
+  });
+  const r = await run(["list", "--prefix", "desk-"]);
+  assert.equal(r.code, 0);
+  assert.deepEqual(JSON.parse(r.out), [
+    { voice_id: "a", name: "desk-1", created_at: 1700000000 },
+    { voice_id: "c", name: "desk-2", created_at: 1700000100 },
+  ]);
+});
+
+test("list prints HeyGen's refusal verbatim and exits 1", async () => {
+  const message = "Invalid or expired API key. Verify your x-api-key header.";
+  mockFetch({
+    "GET /voices?type=private&limit=100": [[401, { error: { code: "unauthorized", message } }]],
+  });
+  const r = await run(["list", "--prefix", "desk-"]);
+  assert.deepEqual(r, { code: 1, out: "", err: message });
+});
+
+test("a host-injected HEYGEN_ACCESS_TOKEN is sent as Bearer", async () => {
+  process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+  mockFetch({ "DELETE /voices/vc1": [[200, { data: {} }]] });
+  await run(["delete", "vc1"]);
+  assert.equal(calls[0].opts.headers.Authorization, "Bearer at_host");
+  assert.equal(calls[0].opts.headers["X-Api-Key"], undefined);
+});