dsh-hyperframes 0.1.1 → 0.3.0

package/skills/media-use/scripts/lib/heygen-cli.mjs

@@ -0,0 +1,191 @@
+import { execFileSync } from "node:child_process";
+import { track } from "./telemetry.mjs";
+
+// v0.3.0 is the first CLI that can use an OAuth session; v0.1.x/0.2.x reject it
+// ("heygen-cli can't use OAuth yet"), and OAuth is what the free-usage path
+// needs — so anything below this can't authenticate for free usage at all.
+export const HEYGEN_MIN_VERSION = "0.3.0";
+// Free-usage path is OAuth (`--oauth` → subscription/free credits); `--api-key`
+// bills API credits, so the onboarding steers to OAuth. Keep pipe-to-shell
+// installer text out of the runtime module; the docs are the safer source of
+// truth for platform-specific setup.
+export const HEYGEN_INSTALL_COMMAND =
+  "Install the CLI from https://developers.heygen.com/cli, then run: heygen auth login --oauth";
+export const HEYGEN_AUTH_COMMAND = "heygen auth login --oauth";
+export const HEYGEN_UPDATE_COMMAND = "heygen update";
+export const HEYGEN_CLIENT_SOURCE_ARGV = ["--headers", "X-HeyGen-Client-Source: media-use"];
+
+export const HEYGEN_NOT_FOUND_MESSAGE = `media-use: heygen CLI not found — it's the free path for bgm/image/voice/avatar-video. ${HEYGEN_INSTALL_COMMAND}`;
+export const HEYGEN_NOT_AUTHENTICATED_MESSAGE = `media-use: heygen CLI not authenticated (free usage) — run: ${HEYGEN_AUTH_COMMAND}`;
+export const HEYGEN_OUTDATED_MESSAGE = `media-use: heygen CLI is outdated — run: ${HEYGEN_UPDATE_COMMAND}  (need >= v${HEYGEN_MIN_VERSION})`;
+
+const ACTIONABLE_MESSAGES = new Set([
+  HEYGEN_NOT_FOUND_MESSAGE,
+  HEYGEN_NOT_AUTHENTICATED_MESSAGE,
+  HEYGEN_OUTDATED_MESSAGE,
+]);
+
+export function classifyHeygenError(err) {
+  return classifyHeygenErrorResult(err).message;
+}
+
+export function classifyHeygenErrorCode(err) {
+  return classifyHeygenErrorResult(err).code;
+}
+
+function classifyHeygenErrorResult(err) {
+  const detail = heygenErrorDetail(err);
+  const text = [err?.stderr, err?.stdout, err?.message, detail]
+    .map((value) => textOf(value))
+    .filter(Boolean)
+    .join("\n");
+  const lower = text.toLowerCase();
+
+  // Only ENOENT (spawn of a missing binary) or a shell's "command not found"
+  // mean the CLI itself is absent. A bare "not found" would misfire on the CLI's
+  // own resource errors (e.g. a stale voiceId → "voice not found"), whose message
+  // embeds the `heygen ...` command line — sending users to reinstall a CLI they
+  // just ran successfully. Keep this narrow.
+  if (err?.code === "ENOENT" || lower.includes("command not found")) {
+    return { code: "not_found", message: HEYGEN_NOT_FOUND_MESSAGE };
+  }
+
+  if (
+    lower.includes("unauthorized") ||
+    lower.includes("unauthenticated") ||
+    // \b401\b, not a bare "401" substring — otherwise request IDs (req-401abc),
+    // URLs, and retry-after headers would misclassify as an auth failure.
+    /\b401\b/.test(lower) ||
+    lower.includes("not logged in") ||
+    lower.includes("no api key") ||
+    lower.includes("missing api key") ||
+    lower.includes("invalid api key") ||
+    lower.includes("login required") ||
+    lower.includes("auth required") ||
+    lower.includes("authentication required")
+  ) {
+    return { code: "not_authenticated", message: HEYGEN_NOT_AUTHENTICATED_MESSAGE };
+  }
+
+  const version = firstSemver(text);
+  if (version && versionLessThan(version, HEYGEN_MIN_VERSION)) {
+    return { code: "outdated", message: HEYGEN_OUTDATED_MESSAGE };
+  }
+
+  if (
+    lower.includes("rate limit") ||
+    lower.includes("quota") ||
+    lower.includes("insufficient credit") ||
+    lower.includes("too many requests") ||
+    lower.includes("throttled") ||
+    /\b429\b/.test(lower)
+  ) {
+    return { code: "rate_limited", message: detail };
+  }
+
+  return { code: "other", message: detail };
+}
+
+// reportHeygenFailure's callers (voice-provider.mjs, heygen-search.mjs) are
+// synchronous and several layers below the CLI's process.exit() calls, so
+// they can't await this tracking call themselves. Stash each attempt's
+// promise here so a caller closer to exit (resolve.mjs) can join it first —
+// same "awaited so a short-lived run flushes it" discipline telemetry.mjs's
+// track() already documents, just reachable from a sync call site.
+const pendingFailureTracking = new Set();
+// resolve.mjs is a single-shot CLI (one resolve per process), so one shared
+// consume-once slot is sufficient. If resolve becomes an in-process/concurrent
+// API, move this state into a per-resolve context before reusing that path.
+let pendingRemediation = null;
+
+export function consumeHeygenRemediation() {
+  const remediation = pendingRemediation;
+  pendingRemediation = null;
+  return remediation;
+}
+
+export function reportHeygenFailure(err, context, trackEvent = track) {
+  const { code, message } = classifyHeygenErrorResult(err);
+  if (code === "not_found" || code === "outdated") {
+    pendingRemediation = { code, message };
+  }
+  if (ACTIONABLE_MESSAGES.has(message)) {
+    console.error(message);
+  } else {
+    console.error(`media-use: \`${context}\` failed: ${message}`);
+  }
+  try {
+    const tracked = Promise.resolve(
+      trackEvent("media_use_provider_error", { provider: "heygen", reason: code }),
+    ).catch(() => {});
+    pendingFailureTracking.add(tracked);
+    void tracked.finally(() => pendingFailureTracking.delete(tracked));
+    return tracked;
+  } catch {
+    // Telemetry must never affect the provider failure path.
+    return Promise.resolve();
+  }
+}
+
+// Awaits every provider-error track fired since the last flush, so a caller
+// about to process.exit() doesn't orphan one mid-request (both are separate,
+// non-keepalive HTTP connections with no ordering guarantee otherwise).
+// Never rejects: each tracked promise already swallows its own failure.
+export async function flushHeygenFailureTracking() {
+  if (pendingFailureTracking.size === 0) return;
+  await Promise.all(pendingFailureTracking);
+}
+
+// Shared discovery/generation helper for the CLI-shelling providers (voice,
+// avatar-video): run a heygen JSON subcommand, report+classify on failure,
+// and hand the caller the classified reason via onError (used by callers that
+// need to distinguish e.g. not_authenticated from other failures).
+export function runHeygenJson(bin, argv, label, onError) {
+  let out;
+  try {
+    out = execFileSync(bin, argv, {
+      encoding: "utf8",
+      timeout: 120000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (err) {
+    reportHeygenFailure(err, `${bin} ${label}`);
+    onError?.(classifyHeygenErrorCode(err));
+    return null;
+  }
+  try {
+    return JSON.parse(out);
+  } catch {
+    console.error(`media-use: \`${bin} ${label}\` returned non-JSON output`);
+    return null;
+  }
+}
+
+export function firstSemver(text) {
+  const match = String(text || "").match(/\bv?(\d+)\.(\d+)\.(\d+)\b/);
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+
+export function versionLessThan(version, minimum) {
+  const left = versionParts(version);
+  const right = versionParts(minimum);
+  if (!left || !right) return false;
+  for (let i = 0; i < 3; i++) {
+    if (left[i] < right[i]) return true;
+    if (left[i] > right[i]) return false;
+  }
+  return false;
+}
+
+function heygenErrorDetail(err) {
+  return textOf(err?.stderr) || textOf(err?.stdout) || err?.message || String(err);
+}
+
+function textOf(value) {
+  return value == null ? "" : String(value).trim();
+}
+
+function versionParts(version) {
+  const match = String(version || "").match(/^v?(\d+)\.(\d+)\.(\d+)$/);
+  return match ? match.slice(1).map((part) => Number.parseInt(part, 10)) : null;
+}

package/skills/media-use/scripts/lib/heygen-cli.test.mjs

@@ -0,0 +1,301 @@
+import { strict as assert } from "node:assert";
+import { spawnSync } from "node:child_process";
+import { test } from "node:test";
+import {
+  classifyHeygenError,
+  classifyHeygenErrorCode,
+  consumeHeygenRemediation,
+  flushHeygenFailureTracking,
+  HEYGEN_NOT_AUTHENTICATED_MESSAGE,
+  HEYGEN_NOT_FOUND_MESSAGE,
+  HEYGEN_OUTDATED_MESSAGE,
+  reportHeygenFailure,
+} from "./heygen-cli.mjs";
+
+function captureFailureReport(err, context, trackEvent) {
+  const originalError = console.error;
+  const stderrCalls = [];
+  console.error = (...args) => stderrCalls.push(args);
+  try {
+    if (trackEvent) {
+      reportHeygenFailure(err, context, trackEvent);
+    } else {
+      reportHeygenFailure(err, context);
+    }
+  } finally {
+    console.error = originalError;
+  }
+  return stderrCalls;
+}
+
+test("classifies ENOENT-style missing heygen errors with install instructions", () => {
+  const message = classifyHeygenError({ code: "ENOENT", message: "spawn heygen ENOENT" });
+
+  assert.equal(message, HEYGEN_NOT_FOUND_MESSAGE);
+});
+
+test("classifies auth failures with login instructions", () => {
+  const message = classifyHeygenError({ stderr: Buffer.from("Error: not logged in") });
+
+  assert.equal(message, HEYGEN_NOT_AUTHENTICATED_MESSAGE);
+});
+
+test("classifies a real 401 as auth, but not a bare 401 substring in prose", () => {
+  assert.equal(
+    classifyHeygenError({ stderr: Buffer.from("HTTP 401 Unauthorized") }),
+    HEYGEN_NOT_AUTHENTICATED_MESSAGE,
+  );
+  // A request id that merely contains "401" must NOT read as an auth failure.
+  const noise = classifyHeygenError({ stderr: Buffer.from("upload failed (request req-401abc)") });
+  assert.notEqual(noise, HEYGEN_NOT_AUTHENTICATED_MESSAGE);
+});
+
+test("classifies old heygen versions with update instructions", () => {
+  const message = classifyHeygenError({
+    stderr: Buffer.from("heygen v0.1.5 does not support --headers"),
+  });
+
+  assert.equal(message, HEYGEN_OUTDATED_MESSAGE);
+});
+
+test("does not misclassify a resource 'not found' error as a missing CLI", () => {
+  // A stale voiceId makes `heygen voice speech create` fail with "voice not
+  // found"; the error message embeds the `heygen ...` command line. This must
+  // pass through as detail, not send the user to reinstall a working CLI.
+  const message = classifyHeygenError({
+    stderr: Buffer.from("Error: voice not found (id: stale-123)"),
+    message: "Command failed: heygen voice speech create --voice stale-123",
+  });
+
+  assert.notEqual(message, HEYGEN_NOT_FOUND_MESSAGE);
+  assert.equal(message, "Error: voice not found (id: stale-123)");
+});
+
+test("classifies a shell 'command not found' as a missing CLI", () => {
+  const message = classifyHeygenError({ stderr: Buffer.from("bash: heygen: command not found") });
+
+  assert.equal(message, HEYGEN_NOT_FOUND_MESSAGE);
+});
+
+test("passes through unrelated errors", () => {
+  const message = classifyHeygenError({
+    stderr: Buffer.from("rate limit exceeded"),
+    message: "Command failed",
+  });
+
+  assert.equal(message, "rate limit exceeded");
+});
+
+test("classifies existing HeyGen failures with stable reason codes", () => {
+  assert.equal(classifyHeygenErrorCode({ code: "ENOENT" }), "not_found");
+  assert.equal(
+    classifyHeygenErrorCode({ stderr: Buffer.from("HTTP 401 Unauthorized") }),
+    "not_authenticated",
+  );
+  assert.equal(
+    classifyHeygenErrorCode({ stderr: Buffer.from("heygen v0.1.5 is unsupported") }),
+    "outdated",
+  );
+  assert.equal(classifyHeygenErrorCode({ stderr: Buffer.from("provider unavailable") }), "other");
+});
+
+test("classifies rate-limit text case-insensitively", () => {
+  assert.equal(
+    classifyHeygenErrorCode({ stderr: Buffer.from("RATE LIMIT exceeded") }),
+    "rate_limited",
+  );
+});
+
+test("classifies quota and insufficient-credit errors as rate limited", () => {
+  for (const detail of ["Quota exhausted", "INSUFFICIENT CREDIT remaining"]) {
+    assert.equal(classifyHeygenErrorCode({ stderr: Buffer.from(detail) }), "rate_limited");
+  }
+});
+
+test("classifies the literal 429 reason phrase and throttling language as rate limited", () => {
+  for (const detail of ["Too Many Requests", "Error: throttled by upstream, retry later"]) {
+    assert.equal(classifyHeygenErrorCode({ stderr: Buffer.from(detail) }), "rate_limited");
+  }
+});
+
+test("does not misclassify unrelated errors that share a word with the new phrasing", () => {
+  // Shares "too many" with "too many requests" but is a distinct failure (fd
+  // exhaustion, not a rate limit) — the match must require the full phrase.
+  assert.equal(
+    classifyHeygenErrorCode({ stderr: Buffer.from("Too many open file descriptors") }),
+    "other",
+  );
+});
+
+test("classifies a bare 429 as rate limited without matching request IDs", () => {
+  assert.equal(
+    classifyHeygenErrorCode({ stderr: Buffer.from("HTTP 429 Too Many Requests") }),
+    "rate_limited",
+  );
+  assert.equal(
+    classifyHeygenErrorCode({ stderr: Buffer.from("request req-429abc failed") }),
+    "other",
+  );
+});
+
+test("tracks not-found failures without changing actionable output", () => {
+  const trackingCalls = [];
+  const stderrCalls = captureFailureReport({ code: "ENOENT" }, "heygen asset search", (...args) =>
+    trackingCalls.push(args),
+  );
+
+  assert.deepEqual(stderrCalls, [[HEYGEN_NOT_FOUND_MESSAGE]]);
+  assert.deepEqual(trackingCalls, [
+    ["media_use_provider_error", { provider: "heygen", reason: "not_found" }],
+  ]);
+});
+
+test("records missing and outdated CLI remediation once", () => {
+  consumeHeygenRemediation();
+  captureFailureReport({ code: "ENOENT" }, "heygen audio sounds list", () => {});
+  assert.deepEqual(consumeHeygenRemediation(), {
+    code: "not_found",
+    message: HEYGEN_NOT_FOUND_MESSAGE,
+  });
+  assert.equal(consumeHeygenRemediation(), null);
+
+  captureFailureReport(
+    { stderr: Buffer.from("heygen v0.1.5 does not support --headers") },
+    "heygen audio sounds list",
+    () => {},
+  );
+  assert.deepEqual(consumeHeygenRemediation(), {
+    code: "outdated",
+    message: HEYGEN_OUTDATED_MESSAGE,
+  });
+  assert.equal(consumeHeygenRemediation(), null);
+});
+
+test("does not record non-install remediation", () => {
+  consumeHeygenRemediation();
+  for (const error of [
+    { stderr: Buffer.from("HTTP 401 Unauthorized") },
+    { stderr: Buffer.from("quota exhausted") },
+    { stderr: Buffer.from("provider unavailable") },
+  ]) {
+    captureFailureReport(error, "heygen audio sounds list", () => {});
+    assert.equal(consumeHeygenRemediation(), null);
+  }
+});
+
+test("tracks generic failures without including raw detail", () => {
+  const trackingCalls = [];
+  const stderrCalls = captureFailureReport(
+    { stderr: Buffer.from("private provider detail") },
+    "heygen asset search",
+    (...args) => trackingCalls.push(args),
+  );
+
+  assert.deepEqual(stderrCalls, [
+    ["media-use: `heygen asset search` failed: private provider detail"],
+  ]);
+  assert.deepEqual(trackingCalls, [
+    ["media_use_provider_error", { provider: "heygen", reason: "other" }],
+  ]);
+});
+
+test("keeps failure output observable when telemetry is opted out", () => {
+  const previousOptOut = process.env.HYPERFRAMES_NO_TELEMETRY;
+  process.env.HYPERFRAMES_NO_TELEMETRY = "1";
+  try {
+    const stderrCalls = captureFailureReport({ code: "ENOENT" }, "heygen asset search");
+
+    assert.deepEqual(stderrCalls, [[HEYGEN_NOT_FOUND_MESSAGE]]);
+  } finally {
+    if (previousOptOut === undefined) {
+      delete process.env.HYPERFRAMES_NO_TELEMETRY;
+    } else {
+      process.env.HYPERFRAMES_NO_TELEMETRY = previousOptOut;
+    }
+  }
+});
+
+test("keeps failure output observable when tracking throws synchronously", () => {
+  const originalError = console.error;
+  const stderrCalls = [];
+  let thrown;
+  console.error = (...args) => stderrCalls.push(args);
+  try {
+    try {
+      reportHeygenFailure({ code: "ENOENT" }, "heygen asset search", () => {
+        throw new Error("tracking failed");
+      });
+    } catch (err) {
+      thrown = err;
+    }
+  } finally {
+    console.error = originalError;
+  }
+
+  assert.deepEqual(stderrCalls, [[HEYGEN_NOT_FOUND_MESSAGE]]);
+  assert.equal(thrown, undefined);
+});
+
+test("does not leave rejected tracking promises unhandled", () => {
+  const moduleUrl = new URL("./heygen-cli.mjs", import.meta.url).href;
+  const script = `
+    import { reportHeygenFailure } from ${JSON.stringify(moduleUrl)};
+    reportHeygenFailure(
+      { stderr: "provider unavailable" },
+      "heygen asset search",
+      () => Promise.reject(new Error("tracking failed")),
+    );
+    await new Promise((resolve) => setImmediate(resolve));
+  `;
+  const child = spawnSync(
+    process.execPath,
+    ["--unhandled-rejections=strict", "--input-type=module", "--eval", script],
+    { encoding: "utf8", timeout: 5000 },
+  );
+
+  assert.equal(child.error, undefined);
+  assert.equal(child.signal, null);
+  assert.equal(child.status, 0, child.stderr);
+  assert.equal(child.stderr, "media-use: `heygen asset search` failed: provider unavailable\n");
+});
+
+test("flushHeygenFailureTracking waits for a pending report before resolving", async () => {
+  const events = [];
+  let releaseTrack;
+  const gate = new Promise((resolve) => {
+    releaseTrack = resolve;
+  });
+
+  // Mirrors the real call sites (voice-provider.mjs, heygen-search.mjs):
+  // fire-and-forget, the return value is never awaited by the caller.
+  reportHeygenFailure({ code: "ENOENT" }, "heygen voice speech", () =>
+    gate.then(() => {
+      events.push("track-settled");
+    }),
+  );
+
+  const flushed = flushHeygenFailureTracking().then(() => {
+    events.push("flush-resolved");
+  });
+
+  // Let several pending microtasks drain before releasing the gate, so this
+  // proves flush is genuinely still waiting on the tracked promise -- not
+  // merely that it hasn't had a tick yet.
+  await Promise.resolve();
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.deepEqual(events, [], "flush must not resolve while the tracked promise is still pending");
+
+  releaseTrack();
+  await flushed;
+
+  assert.deepEqual(
+    events,
+    ["track-settled", "flush-resolved"],
+    "flush must resolve only after the pending track settles, in that order",
+  );
+});
+
+test("flushHeygenFailureTracking resolves immediately when nothing is pending", async () => {
+  await flushHeygenFailureTracking();
+});

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

@@ -0,0 +1,45 @@
+import { execFileSync } from "node:child_process";
+import { HEYGEN_CLIENT_SOURCE_ARGV, reportHeygenFailure } from "./heygen-cli.mjs";
+
+export function heygenSearch(subcommand, query, { type, limit = 5, minScore } = {}) {
+  // execFileSync with an argv array (no shell), so query/type/etc. are passed as
+  // literal arguments — no quoting tricks, no command injection. subcommand is a
+  // hardcoded multi-word string (e.g. "audio sounds list"), split into tokens.
+  // Tag the caller via the CLI's allowlisted attribution header (heygen >= v0.3.0).
+  const args = [...HEYGEN_CLIENT_SOURCE_ARGV, ...subcommand.split(" "), "--query", query];
+  if (type) args.push("--type", type);
+  args.push("--limit", String(limit));
+  // Server-side score floor. Honored by `audio sounds list`; the `asset search`
+  // backend rejects it, so only audio providers pass minScore (see image-provider).
+  if (minScore != null) args.push("--min-score", String(minScore));
+
+  let out;
+  try {
+    out = execFileSync("heygen", args, {
+      encoding: "utf8",
+      timeout: 15000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (err) {
+    // Don't swallow a broken command / auth failure as "no results" — that turns
+    // a typo or expired key into a silent dead end. Surface it, then give up.
+    reportHeygenFailure(err, `heygen ${subcommand}`);
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(out);
+  } catch {
+    console.error(`media-use: \`heygen ${subcommand}\` returned non-JSON output`);
+    return null;
+  }
+  if (parsed?.error) {
+    const e = parsed.error;
+    console.error(`media-use: \`heygen ${subcommand}\` error: ${e.message ?? JSON.stringify(e)}`);
+    return null;
+  }
+
+  const data = parsed?.data;
+  return Array.isArray(data) && data.length > 0 ? data : null;
+}

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

@@ -0,0 +1,49 @@
+import { strict as assert } from "node:assert";
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { HEYGEN_CLIENT_SOURCE_HEADERS } from "../../audio/scripts/lib/heygen.mjs";
+import { HEYGEN_CLIENT_SOURCE_ARGV } from "./heygen-cli.mjs";
+import { heygenSearch } from "./heygen-search.mjs";
+
+test("tags HeyGen searches with the shared media-use client source", () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-use-heygen-search-"));
+  const capturePath = join(dir, "argv.log");
+  const heygenPath = join(dir, "heygen");
+  const previousPath = process.env.PATH;
+  const previousCapturePath = process.env.HEYGEN_CAPTURE_PATH;
+
+  writeFileSync(
+    heygenPath,
+    `#!/bin/sh
+printf '%s\\n' "$*" >> "$HEYGEN_CAPTURE_PATH"
+printf '%s\\n' '{"data":[{"id":"x"}]}'
+`,
+  );
+  chmodSync(heygenPath, 0o755);
+  process.env.PATH = `${dir}:${previousPath ?? ""}`;
+  process.env.HEYGEN_CAPTURE_PATH = capturePath;
+
+  try {
+    const result = heygenSearch("audio sounds list", "ocean", { limit: 1 });
+    const argv = readFileSync(capturePath, "utf8").trim();
+
+    assert.deepEqual(result, [{ id: "x" }]);
+    assert.match(argv, /X-HeyGen-Client-Source: media-use/);
+  } finally {
+    if (previousPath === undefined) delete process.env.PATH;
+    else process.env.PATH = previousPath;
+    if (previousCapturePath === undefined) delete process.env.HEYGEN_CAPTURE_PATH;
+    else process.env.HEYGEN_CAPTURE_PATH = previousCapturePath;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("keeps CLI and REST media-use client source headers in lockstep", () => {
+  const [entry] = Object.entries(HEYGEN_CLIENT_SOURCE_HEADERS);
+  assert.ok(entry);
+  const [key, value] = entry;
+
+  assert.equal(HEYGEN_CLIENT_SOURCE_ARGV[1], `${key}: ${value}`);
+});