dsh-hyperframes 0.3.2 → 0.4.0

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

@@ -1,128 +0,0 @@
-import { execFileSync } from "node:child_process";
-import { existsSync, unlinkSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { describeDownload, probeSpecs } from "./specs.mjs";
-import { buildArgv, selectModelLadder } from "./local-models.mjs";
-
-// Local image generation via mflux (FLUX-on-MLX), the Mac-native runner.
-// Spec-gated: selectModelLadder("imagegen", specs) returns every FLUX-class
-// model the machine's AVAILABLE RAM can actually run (medium FLUX-schnell
-// --low-ram on ~24GB, up to Qwen-Image on 64GB+), best first. When nothing
-// local fits, or no fitting tier can actually run here, this returns null so
-// the registry falls through to the codex image upsell.
-//
-// The official FLUX repos are HF-gated, so the model entries point --path at
-// non-gated community 4-bit re-uploads; the repo is resolved to a local snapshot
-// (hf download, idempotent) because a bare repo id breaks mlx unflatten.
-
-// Resolve an HF repo to its local snapshot dir. `hf download` is idempotent and
-// prints the snapshot path as its last line.
-function resolveSnapshot(repo, execFn, pathExists) {
-  const out = execFn("hf", ["download", repo], {
-    encoding: "utf8",
-    timeout: 1_800_000,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  const path = out?.trim().split(/\r?\n/).pop()?.trim();
-  return path && pathExists(path) ? path : null;
-}
-
-export async function mfluxImageGenerate(
-  intent,
-  ctx,
-  execFn = execFileSync,
-  pathExists = existsSync,
-  unlinkFn = unlinkSync,
-) {
-  const specs = ctx?.specs || probeSpecs();
-  const ladder = selectModelLadder("imagegen", specs, { preferTier: ctx?.preferTier });
-  if (!ladder.length) return null; // no local model fits -> codex upsell/fallback
-
-  // Each attempt mints its own timestamped output path, so a partial artifact
-  // from a failed tier is orphaned rather than overwritten - and a lower tier
-  // then succeeding hides it. Discard it before demoting. Best-effort: a
-  // partial we cannot remove must never mask the real failure.
-  const discardPartial = (path) => {
-    try {
-      if (pathExists(path)) unlinkFn(path);
-    } catch {
-      // nothing actionable: the generate failure below is the real story
-    }
-  };
-
-  // Best tier first, demoting past any tier that cannot run here (runner off
-  // PATH, a snapshot that won't download, an OOM) rather than failing local
-  // image gen outright. Every demotion is reported, so a quietly smaller model
-  // is never mistaken for the tier the machine nominally qualified for.
-  for (const model of ladder) {
-    const bin = model.invoke.trim().split(/\s+/)[0];
-    // Not installed? Surface the exact enable-command (before the model
-    // download) so the agent learns the free local path is available instead of
-    // silently taking the codex upsell.
-    try {
-      execFn("which", [bin], { stdio: ["ignore", "ignore", "ignore"] });
-    } catch {
-      console.error(
-        `media-use: local image gen not enabled (\`${bin}\` not on PATH). Install for free on-device FLUX: ${model.install}. Heads up: ${model.id} ${describeDownload(model.sizeMB)}.`,
-      );
-      continue;
-    }
-
-    const outPath = join(tmpdir(), `media-use-mflux-${process.pid}-${Date.now()}.png`);
-    const vars = {
-      prompt: intent,
-      w: ctx?.width || 512,
-      h: ctx?.height || 512,
-      seed: ctx?.seed ?? 42,
-      out: outPath,
-    };
-    if (model.repo && model.invoke.includes("{model_path}")) {
-      let snap = null;
-      let why = `could not resolve a local snapshot of ${model.repo}`;
-      try {
-        snap = resolveSnapshot(model.repo, execFn, pathExists);
-      } catch (err) {
-        why = `hf download failed: ${err.stderr?.toString().trim().slice(-200) || err.message}`;
-      }
-      if (!snap) {
-        console.error(`media-use: local image gen (${model.id}): ${why}`);
-        continue;
-      }
-      vars.model_path = snap;
-    }
-
-    const argv = buildArgv(model.invoke, vars);
-    argv.shift(); // drop the bin (already validated)
-    try {
-      execFn(bin, argv, {
-        encoding: "utf8",
-        timeout: 1_800_000,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-    } catch (err) {
-      discardPartial(outPath);
-      console.error(
-        `media-use: local image gen (${model.id}) failed: ${err.stderr?.toString().trim().slice(-200) || err.message}`,
-      );
-      continue;
-    }
-    if (!pathExists(outPath)) {
-      console.error(
-        `media-use: local image gen (${model.id}) exited cleanly but wrote no output file`,
-      );
-      continue;
-    }
-    return {
-      localPath: outPath,
-      ext: ".png",
-      source: "generated",
-      metadata: {
-        description: intent,
-        provider: `mflux.${model.id}`,
-        provenance: { model: model.id, tier: model.tier, prompt: intent },
-      },
-    };
-  }
-  return null;
-}

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

@@ -1,174 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mfluxImageGenerate } from "./mflux-provider.mjs";
-
-// 40GB clears the 32GB klein tier and the 8GB schnell tier below it; the 64GB
-// qwen tier stays out of reach. Two rungs is what makes demotion observable.
-const bothTiersSpecs = { availableRamMB: 40000, gpu: { present: true } };
-const SNAPSHOT = "/tmp/hf-snapshot";
-
-// exec stub covering all three shells-out mflux does: the PATH probe, the
-// idempotent `hf download`, and the generate itself.
-function stubExec({ failGenerateFor = [], failWhichFor = [] } = {}) {
-  const calls = [];
-  const exec = (...call) => {
-    calls.push(call);
-    const [bin, argv] = call;
-    if (bin === "which") {
-      if (failWhichFor.includes(argv[0])) throw new Error("not found");
-      return "";
-    }
-    if (bin === "hf") return `Fetching 6 files...\n${SNAPSHOT}\n`;
-    if (failGenerateFor.some((id) => argv.join(" ").includes(id))) {
-      const err = new Error("exit 1");
-      err.stderr = "mlx.core.metal: out of memory";
-      throw err;
-    }
-    return "";
-  };
-  return { calls, exec };
-}
-
-const generateCalls = (calls) =>
-  calls.filter(([bin]) => bin !== "which" && bin !== "hf").map(([, argv]) => argv.join(" "));
-
-test("no local model fits: falls through to the upsell without shelling out", async () => {
-  const { calls, exec } = stubExec();
-
-  const result = await mfluxImageGenerate(
-    "a red bicycle",
-    { specs: { availableRamMB: 100, gpu: { present: true } } },
-    exec,
-    () => true,
-  );
-
-  assert.equal(result, null);
-  assert.deepEqual(calls, []);
-});
-
-test("a top tier that cannot run demotes to the next fitting tier", async (t) => {
-  const errors = [];
-  t.mock.method(console, "error", (message) => errors.push(message));
-  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b"] });
-
-  const result = await mfluxImageGenerate(
-    "a red bicycle",
-    { specs: bothTiersSpecs },
-    exec,
-    () => true,
-  );
-
-  assert.ok(result, "the schnell tier still produced an image");
-  assert.equal(result.metadata.provider, "mflux.flux-schnell-mflux-q4");
-  const generated = generateCalls(calls);
-  assert.equal(generated.length, 2, "klein attempted first, then schnell");
-  assert.match(generated[0], /flux2-klein-4b/);
-  assert.match(generated[1], /--model schnell/);
-  assert.equal(errors.length, 1, "the demotion is reported, not silent");
-  assert.match(errors[0], /flux2-klein-mflux-q4\) failed/);
-});
-
-test("a snapshot that will not resolve demotes rather than failing outright", async (t) => {
-  const errors = [];
-  t.mock.method(console, "error", (message) => errors.push(message));
-  const calls = [];
-  const exec = (...call) => {
-    calls.push(call);
-    const [bin, argv] = call;
-    if (bin === "which") return "";
-    // klein's weights won't download; schnell's do
-    if (bin === "hf") {
-      if (argv[1].includes("FLUX.2-klein")) throw new Error("403 Forbidden");
-      return `${SNAPSHOT}\n`;
-    }
-    return "";
-  };
-
-  const result = await mfluxImageGenerate(
-    "a red bicycle",
-    { specs: bothTiersSpecs },
-    exec,
-    () => true,
-  );
-
-  assert.ok(result, "demoted past the ungettable weights");
-  assert.equal(result.metadata.provider, "mflux.flux-schnell-mflux-q4");
-  assert.equal(errors.length, 1);
-  assert.match(errors[0], /hf download failed/);
-});
-
-test("runner missing from PATH reports the install hint per tier and returns null", async (t) => {
-  const errors = [];
-  t.mock.method(console, "error", (message) => errors.push(message));
-  const { exec } = stubExec({ failWhichFor: ["mflux-generate"] });
-
-  const result = await mfluxImageGenerate(
-    "a red bicycle",
-    { specs: bothTiersSpecs },
-    exec,
-    () => true,
-  );
-
-  assert.equal(result, null);
-  assert.equal(errors.length, 2, "both fitting tiers reported");
-  assert.match(errors[0], /uv pip install mflux/);
-  // each hint states that tier's download cost before the user commits
-  assert.match(errors[0], /GB of weights to/);
-  assert.match(errors[1], /GB of weights to/);
-});
-
-// Same per-attempt temp path, same orphaning risk as the LTX provider: a
-// partial png from a failed tier must not survive a lower tier succeeding.
-const outputOf = (argv) => argv[argv.indexOf("--output") + 1];
-const attemptedOutputs = (calls) =>
-  calls.filter(([bin]) => bin !== "which" && bin !== "hf").map(([, argv]) => outputOf(argv));
-
-test("a failed attempt's partial output is discarded before demoting", async (t) => {
-  t.mock.method(console, "error", () => {});
-  const unlinked = [];
-  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b"] });
-
-  const result = await mfluxImageGenerate(
-    "a red bicycle",
-    { specs: bothTiersSpecs },
-    exec,
-    () => true,
-    (path) => unlinked.push(path),
-  );
-
-  assert.ok(result, "the schnell tier still produced an image");
-  assert.deepEqual(unlinked, [attemptedOutputs(calls)[0]], "the failed klein partial is removed");
-});
-
-test("every tier failing discards every partial, one per attempt", async (t) => {
-  t.mock.method(console, "error", () => {});
-  const unlinked = [];
-  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b", "schnell"] });
-
-  const result = await mfluxImageGenerate(
-    "a red bicycle",
-    { specs: bothTiersSpecs },
-    exec,
-    () => true,
-    (path) => unlinked.push(path),
-  );
-
-  assert.equal(result, null);
-  assert.deepEqual(unlinked, attemptedOutputs(calls), "nothing is left behind");
-});
-
-test("a successful generation is never discarded", async () => {
-  const unlinked = [];
-  const { exec } = stubExec();
-
-  const result = await mfluxImageGenerate(
-    "a red bicycle",
-    { specs: bothTiersSpecs },
-    exec,
-    () => true,
-    (path) => unlinked.push(path),
-  );
-
-  assert.ok(result);
-  assert.deepEqual(unlinked, [], "the returned artifact must survive");
-});

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

@@ -1,49 +0,0 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-const MISSES_FILE = "misses.jsonl";
-
-function missesPath() {
-  return join(homedir(), ".media", MISSES_FILE);
-}
-
-export function recordMiss({ type, intent, provider_override, local_only }) {
-  try {
-    const dir = join(homedir(), ".media");
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(
-      join(dir, MISSES_FILE),
-      JSON.stringify({
-        ts: new Date().toISOString(),
-        type,
-        intent,
-        provider_override: !!provider_override,
-        local_only: !!local_only,
-      }) + "\n",
-    );
-  } catch {
-    // local miss logging is best-effort; never surface into resolve
-  }
-}
-
-export function readMisses() {
-  const p = missesPath();
-  try {
-    if (!existsSync(p)) return [];
-    const raw = readFileSync(p, "utf8");
-    const records = [];
-    for (const line of raw.split(/\r?\n/)) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      try {
-        records.push(JSON.parse(trimmed));
-      } catch {
-        // skip malformed local lines, don't crash stats
-      }
-    }
-    return records;
-  } catch {
-    return [];
-  }
-}

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

@@ -1,78 +0,0 @@
-import { strict as assert } from "node:assert";
-import { test } from "node:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { readMisses, recordMiss } from "./misses.mjs";
-
-function sandbox() {
-  const root = mkdtempSync(join(tmpdir(), "mu-misses-"));
-  const home = join(root, "home");
-  mkdirSync(home, { recursive: true });
-  process.env.HOME = home;
-  return { root, home };
-}
-
-function restoreEnv(saved) {
-  for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
-  Object.assign(process.env, saved);
-}
-
-test("recordMiss appends a well-formed local miss", () => {
-  const savedEnv = { ...process.env };
-  const { root, home } = sandbox();
-  try {
-    recordMiss({ type: "bgm", intent: "moody synth pulse", provider_override: true });
-    const misses = readMisses();
-    assert.equal(misses.length, 1);
-    assert.equal(misses[0].type, "bgm");
-    assert.equal(misses[0].intent, "moody synth pulse");
-    assert.equal(misses[0].provider_override, true);
-    assert.equal(misses[0].local_only, false);
-    assert.ok(!Number.isNaN(Date.parse(misses[0].ts)));
-
-    const raw = readFileSync(join(home, ".media/misses.jsonl"), "utf8");
-    assert.match(raw, /moody synth pulse/);
-  } finally {
-    restoreEnv(savedEnv);
-    rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test("recordMiss swallows filesystem failures", () => {
-  const savedEnv = { ...process.env };
-  const { root, home } = sandbox();
-  try {
-    writeFileSync(join(home, ".media"), "not a directory");
-    assert.doesNotThrow(() =>
-      recordMiss({ type: "image", intent: "unwritable", local_only: true }),
-    );
-    assert.equal(existsSync(join(home, ".media/misses.jsonl")), false);
-  } finally {
-    restoreEnv(savedEnv);
-    rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test("readMisses skips corrupt lines", () => {
-  const savedEnv = { ...process.env };
-  const { root, home } = sandbox();
-  try {
-    mkdirSync(join(home, ".media"), { recursive: true });
-    writeFileSync(
-      join(home, ".media/misses.jsonl"),
-      [
-        JSON.stringify({ ts: "2026-07-09T00:00:00.000Z", type: "bgm", intent: "one" }),
-        "{not json",
-        JSON.stringify({ ts: "2026-07-09T00:00:01.000Z", type: "sfx", intent: "two" }),
-      ].join("\n"),
-    );
-    assert.deepEqual(
-      readMisses().map((miss) => miss.intent),
-      ["one", "two"],
-    );
-  } finally {
-    restoreEnv(savedEnv);
-    rmSync(root, { recursive: true, force: true });
-  }
-});

package/skills/media-use/scripts/lib/npx-sync.test.mjs

@@ -1,50 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { resolveNpxInvocation } from "./npx-sync.mjs";
-
-// Coverage parity with tts-local-provider.test.mjs, for the whisper.cpp
-// fallback's call-site shape (transcribe.mjs runWhisper): the same three
-// branches, but with the hard-fail contract — no fallback provider exists,
-// so an unresolvable npx must throw actionably instead of returning null.
-
-const envWithNpxCli = {
-  npm_execpath: "C:/Program Files/nodejs/node_modules/npm/bin/npm-cli.js",
-  npm_node_execpath: "C:/Program Files/nodejs/node.exe",
-};
-const npxCliPath = "C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js";
-const pathExists = (path) => path === npxCliPath;
-
-const WHISPER_ARGV = ["hyperframes", "transcribe", "C:\\media\\input.wav", "--dir", "C:\\work"];
-const WHISPER_OPTS = { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 };
-
-test("win32: routes the whisper fallback through node + npx-cli, never bare npx", () => {
-  const resolved = resolveNpxInvocation(
-    WHISPER_ARGV,
-    WHISPER_OPTS,
-    "win32",
-    envWithNpxCli,
-    pathExists,
-  );
-
-  assert.equal(resolved.cmd, envWithNpxCli.npm_node_execpath);
-  assert.equal(resolved.args[0], npxCliPath);
-  assert.deepEqual(resolved.args.slice(1, 3), ["hyperframes", "transcribe"]);
-  // execFileSync options survive the rerouting (the timeout bounds the
-  // whisper build/model download; the pipes surface its errors).
-  assert.deepEqual(resolved.opts.stdio, ["ignore", "pipe", "pipe"]);
-  assert.equal(resolved.opts.timeout, 1_800_000);
-});
-
-test("win32 without a resolvable npx-cli: throws the actionable install hint", () => {
-  assert.throws(
-    () => resolveNpxInvocation(WHISPER_ARGV, WHISPER_OPTS, "win32", {}, () => false),
-    /npx-cli\.js was not found/,
-  );
-});
-
-test("non-win32: spawns plain npx unchanged", () => {
-  const resolved = resolveNpxInvocation(WHISPER_ARGV, WHISPER_OPTS, "darwin", {}, () => false);
-
-  assert.equal(resolved.cmd, "npx");
-  assert.deepEqual(resolved.args, WHISPER_ARGV);
-});

package/skills/media-use/scripts/lib/parakeet-words.test.mjs

@@ -1,44 +0,0 @@
-import { strict as assert } from "node:assert";
-import { test } from "node:test";
-import { mergeTokensToWords } from "./parakeet-words.mjs";
-
-test("mergeTokensToWords joins sub-word tokens on the space boundary", () => {
-  const parakeet = {
-    text: "Hello everyone. Um,",
-    sentences: [
-      {
-        tokens: [
-          { text: " H", start: 0.0, end: 0.24 },
-          { text: "ello", start: 0.24, end: 0.48 },
-          { text: " everyone.", start: 0.48, end: 1.28 },
-          { text: " Um,", start: 1.28, end: 1.92 },
-        ],
-      },
-    ],
-  };
-  const { words } = mergeTokensToWords(parakeet);
-  assert.deepEqual(words, [
-    { text: "Hello", start: 0.0, end: 0.48 },
-    { text: "everyone.", start: 0.48, end: 1.28 },
-    { text: "Um,", start: 1.28, end: 1.92 },
-  ]);
-});
-
-test("mergeTokensToWords spans multiple sentences and drops empties", () => {
-  const parakeet = {
-    text: "Hi there",
-    sentences: [
-      { tokens: [{ text: "Hi", start: 0, end: 0.2 }] },
-      { tokens: [{ text: " there", start: 0.5, end: 0.9 }] },
-    ],
-  };
-  const { words } = mergeTokensToWords(parakeet);
-  assert.equal(words.length, 2);
-  assert.equal(words[1].text, "there");
-  assert.equal(words[1].start, 0.5);
-});
-
-test("mergeTokensToWords tolerates missing sentences/tokens", () => {
-  assert.deepEqual(mergeTokensToWords({}).words, []);
-  assert.deepEqual(mergeTokensToWords({ sentences: [{}] }).words, []);
-});