dsh-hyperframes 0.2.0 → 0.3.0

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

@@ -0,0 +1,316 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { ltxVideoGenerate } from "./ltx-video-provider.mjs";
+
+const fittingSpecs = { availableRamMB: 20000, gpu: { present: true } };
+
+test("no fitting local model: falls through without checking for a binary", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const calls = [];
+
+  const result = await ltxVideoGenerate(
+    "a calm ocean wave at sunset",
+    { specs: { availableRamMB: 100, gpu: { present: true } } },
+    (...call) => calls.push(call),
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.deepEqual(calls, []);
+});
+
+test("binary missing from PATH: prints the model install hint and falls through", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const calls = [];
+  const fakeExec = (...call) => {
+    calls.push(call);
+    throw new Error("not found");
+  };
+
+  const result = await ltxVideoGenerate(
+    "a calm ocean wave at sunset",
+    { specs: fittingSpecs },
+    fakeExec,
+  );
+
+  assert.equal(result, null);
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].slice(0, 2), ["which", ["ltx-2-mlx"]]);
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /git clone https:\/\/github\.com\/dgrauet\/ltx-2-mlx/);
+  // the install hint is the accept moment: say what the pull costs
+  assert.match(errors[0], /GB of weights to/);
+});
+
+test("generate argv substitutes a spaced prompt after tokenizing and uses verified defaults", async () => {
+  const calls = [];
+  const checkedPaths = [];
+  const fakeExec = (...call) => calls.push(call);
+  const pathExists = (path) => {
+    checkedPaths.push(path);
+    return false;
+  };
+  const intent = "a calm ocean wave at sunset";
+
+  const result = await ltxVideoGenerate(intent, { specs: fittingSpecs }, fakeExec, pathExists);
+
+  assert.equal(result, null);
+  assert.equal(calls.length, 2);
+  const [bin, argv, opts] = calls[1];
+  assert.equal(bin, "ltx-2-mlx");
+  assert.equal(opts.timeout, 1_800_000);
+
+  const expectedPairs = [
+    ["--prompt", intent],
+    ["--width", "512"],
+    ["--height", "320"],
+    ["--frames", "33"],
+    ["--output", checkedPaths[0]],
+  ];
+  let previousIndex = -1;
+  for (const [flag, value] of expectedPairs) {
+    const index = argv.indexOf(flag);
+    assert.ok(index > previousIndex, `${flag} should follow the previous required option`);
+    assert.equal(argv[index + 1], value);
+    previousIndex = index;
+  }
+  assert.equal(argv.filter((arg) => arg === intent).length, 1);
+});
+
+test("successful generation returns the generated MP4 result", async () => {
+  const calls = [];
+  const fakeExec = (...call) => calls.push(call);
+  const intent = "a calm ocean wave at sunset";
+
+  const result = await ltxVideoGenerate(intent, { specs: fittingSpecs }, fakeExec, () => true);
+
+  assert.ok(result);
+  assert.equal(calls.length, 2);
+  assert.equal(dirname(result.localPath), tmpdir());
+  assert.match(result.localPath, /media-use-ltx-\d+-\d+\.mp4$/);
+  assert.deepEqual(result, {
+    localPath: result.localPath,
+    ext: ".mp4",
+    source: "generated",
+    metadata: {
+      description: intent,
+      provider: "ltx.local",
+      provenance: { prompt: intent },
+    },
+  });
+});
+
+test("generate failure returns null instead of throwing", async (t) => {
+  t.mock.method(console, "error", () => {});
+  let calls = 0;
+  const fakeExec = () => {
+    calls += 1;
+    if (calls === 2) {
+      const error = new Error("generation failed");
+      error.stderr = "LTX failed";
+      throw error;
+    }
+  };
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: fittingSpecs },
+    fakeExec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.equal(calls, 2);
+});
+
+test("missing generated output returns null and says so", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: fittingSpecs },
+    () => {},
+    () => false,
+  );
+
+  assert.equal(result, null);
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /wrote no output file/);
+});
+
+// 40GB clears BOTH videogen tiers, so the ladder has two rungs. `fittingSpecs`
+// above sits under the large tier's floor on purpose: every other test in this
+// file exercises the medium tier alone, which is precisely why a broken large
+// tier could sit in the table unnoticed.
+const bothTiersSpecs = { availableRamMB: 40000, gpu: { present: true } };
+
+const isGenerate = (call) => call[0] !== "which";
+
+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 = [];
+  // The runner is installed, but the large tier's weights are gated: the
+  // download 401s and `generate` exits non-zero. The medium tier then works.
+  const fakeExec = (...call) => {
+    calls.push(call);
+    if (isGenerate(call) && call[1].includes("dgrauet/ltx-2.3-mlx-q8")) {
+      const err = new Error("exit 1");
+      err.stderr = "401 Client Error: Unauthorized for url: .../ltx-2.3-mlx-q8";
+      throw err;
+    }
+  };
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: bothTiersSpecs },
+    fakeExec,
+    () => true,
+  );
+
+  assert.ok(result, "the medium tier still produced a video");
+  const generated = calls.filter(isGenerate).map((call) => call[1].join(" "));
+  assert.equal(generated.length, 2, "large attempted first, then medium");
+  assert.match(generated[0], /dgrauet\/ltx-2\.3-mlx-q8/);
+  assert.match(generated[1], /dgrauet\/ltx-2\.3-mlx-q4/);
+  // the demotion is reported, never silent: a smaller model changes the output
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /ltx-2\.3-mlx-q8\) failed/);
+  assert.match(errors[0], /401/);
+});
+
+test("every fitting tier failing returns null, one reason per tier", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const fakeExec = (...call) => {
+    if (isGenerate(call)) throw new Error("mlx out of memory");
+  };
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: bothTiersSpecs },
+    fakeExec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.equal(errors.length, 2, "both tiers tried, both reported");
+  assert.match(errors[0], /ltx-2\.3-mlx-q8/);
+  assert.match(errors[1], /ltx-2\.3-mlx-q4/);
+});
+
+test("preferTier pins the attempt to one tier instead of demoting", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const calls = [];
+  const fakeExec = (...call) => {
+    calls.push(call);
+    if (isGenerate(call)) throw new Error("boom");
+  };
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: bothTiersSpecs, preferTier: "large" },
+    fakeExec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  const generated = calls.filter(isGenerate).map((call) => call[1].join(" "));
+  assert.equal(generated.length, 1, "pinned to large: no demotion to medium");
+  assert.match(generated[0], /dgrauet\/ltx-2\.3-mlx-q8/);
+});
+
+// A failed attempt's temp path is minted per attempt (it carries a timestamp),
+// so without cleanup a partial mp4 from a failed tier is orphaned rather than
+// overwritten - and a lower tier then succeeding hides it. Partial video files
+// are the expensive case, which is why this is pinned.
+const outputOf = (argv) => argv[argv.indexOf("--output") + 1];
+
+test("a failed attempt's partial output is discarded before demoting", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const unlinked = [];
+  const attempted = [];
+  const fakeExec = (...call) => {
+    if (!isGenerate(call)) return;
+    attempted.push(outputOf(call[1]));
+    if (call[1].includes("dgrauet/ltx-2.3-mlx-q8")) {
+      // OOM mid-write is one of the advertised demotion cases
+      const err = new Error("exit 1");
+      err.stderr = "mlx.core.metal: out of memory";
+      throw err;
+    }
+  };
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: bothTiersSpecs },
+    fakeExec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.ok(result, "the medium tier still produced a video");
+  assert.deepEqual(unlinked, [attempted[0]], "the failed large-tier partial is removed");
+});
+
+test("every tier failing discards every partial, one per attempt", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const unlinked = [];
+  const attempted = [];
+  const fakeExec = (...call) => {
+    if (!isGenerate(call)) return;
+    attempted.push(outputOf(call[1]));
+    throw new Error("mlx out of memory");
+  };
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: bothTiersSpecs },
+    fakeExec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.equal(result, null);
+  assert.equal(attempted.length, 2, "both tiers attempted");
+  assert.deepEqual(unlinked, attempted, "nothing is left behind on the all-fail path");
+});
+
+test("a successful generation is never discarded", async () => {
+  const unlinked = [];
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: bothTiersSpecs },
+    () => {},
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.ok(result);
+  assert.deepEqual(unlinked, [], "the returned artifact must survive");
+});
+
+test("an unremovable partial does not mask the generate failure", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const fakeExec = (...call) => {
+    if (isGenerate(call)) throw new Error("mlx out of memory");
+  };
+
+  const result = await ltxVideoGenerate(
+    "storm clouds",
+    { specs: bothTiersSpecs },
+    fakeExec,
+    () => true,
+    () => {
+      throw new Error("EPERM: operation not permitted");
+    },
+  );
+
+  // cleanup is best-effort: a partial we cannot delete must not become the error
+  assert.equal(result, null);
+});

package/skills/media-use/scripts/lib/lut-preset-provider.mjs

@@ -0,0 +1,266 @@
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { withReservedFile, withReservedFileSync } from "./manifest.mjs";
+import { freezeUrl } from "./freeze.mjs";
+import { tokenOverlap } from "./match.mjs";
+import { buildCube } from "./cube-build.mjs";
+import { validateCube, validateCubeFile } from "./cube-validate.mjs";
+
+const SKILL_DIR = join(import.meta.dirname, "..", "..");
+const LUT_DIR = join(SKILL_DIR, "luts");
+const LUT_INDEX = join(LUT_DIR, "index.json");
+export const LIBRARY_LUT_OFFLINE_CODE = "MEDIA_USE_LIBRARY_LUT_OFFLINE";
+
+// Presets this released resolver can safely emit at this stack layer.
+// Effect-backed treatment presets join after their runtime support lands.
+export const RESOLVABLE_PRESET_IDS = [
+  "neutral",
+  "warm-daylight",
+  "clean-studio",
+  "skin-soft",
+  "food-pop",
+  "night-lift",
+  "muted-editorial",
+  "vintage-wash",
+  "mono-clean",
+  "mono-fade",
+  "soft-boost",
+  "bright-pop",
+  "deep-contrast",
+  "creator-camcorder",
+  "vhs-playback",
+  "home-movie-8mm",
+  "editorial-halftone",
+  "two-ink-print",
+];
+
+const PRESET_SYNONYMS = {
+  neutral: ["neutral", "identity", "none", "ungraded", "natural base"],
+  "warm-daylight": [
+    "warm daylight",
+    "warm natural light",
+    "golden daylight",
+    "sunlit",
+    "warm sunny",
+    "warm clean",
+    "clean warm",
+    "warm product",
+  ],
+  "clean-studio": [
+    "clean studio",
+    "studio clean",
+    "cool studio",
+    "product studio",
+    "cool clean",
+    "clean cool",
+    "cool crisp",
+  ],
+  "skin-soft": ["skin soft", "soft skin", "portrait soft", "beauty skin"],
+  "food-pop": ["food pop", "food vibrant", "appetizing", "restaurant color"],
+  "night-lift": ["night lift", "night", "low light lift", "city night"],
+  "muted-editorial": ["muted editorial", "editorial muted", "magazine muted"],
+  "vintage-wash": ["vintage wash", "vintage", "retro wash", "aged film"],
+  "mono-clean": ["mono clean", "black white clean", "monochrome clean"],
+  "mono-fade": ["mono fade", "black white fade", "faded monochrome"],
+  "soft-boost": [
+    "soft boost",
+    "soft bright",
+    "gentle boost",
+    "natural lift",
+    "natural light",
+    "gentle lift",
+    "soft natural",
+  ],
+  "bright-pop": [
+    "bright pop",
+    "bright punchy",
+    "vivid bright",
+    "fresh pop",
+    "fresh",
+    "bright fresh",
+    "clean colorful",
+  ],
+  "deep-contrast": ["deep contrast", "high contrast punchy", "punchy contrast", "bold contrast"],
+  "creator-camcorder": ["creator camcorder", "creator video", "ugc camera", "handheld creator"],
+  "vhs-playback": ["vhs playback", "vhs tape", "analog tape", "degraded tape"],
+  "home-movie-8mm": ["8mm home movie", "8mm film", "family film", "small gauge film"],
+  "editorial-halftone": ["editorial halftone", "halftone", "print dots", "newsprint"],
+  "two-ink-print": ["two ink print", "two ink editorial", "duotone print", "poster print"],
+};
+
+function presetCandidates() {
+  return RESOLVABLE_PRESET_IDS.map((id) => ({
+    kind: "preset",
+    preset: id,
+    synonyms: PRESET_SYNONYMS[id] ?? [],
+    text: [id, ...(PRESET_SYNONYMS[id] ?? [])].join(" "),
+  }));
+}
+
+export function readBundledLutIndex() {
+  if (!existsSync(LUT_INDEX)) return [];
+  const parsed = JSON.parse(readFileSync(LUT_INDEX, "utf8"));
+  const entries = Array.isArray(parsed) ? parsed : parsed.looks;
+  if (!Array.isArray(entries)) return [];
+  return entries.map((entry) => {
+    const params =
+      entry.params && typeof entry.params === "object" && !Array.isArray(entry.params)
+        ? entry.params
+        : null;
+    const url = typeof entry.url === "string" && entry.url.trim() ? entry.url.trim() : null;
+    return {
+      id: String(entry.id),
+      description: String(entry.description ?? entry.id),
+      tags: Array.isArray(entry.tags) ? entry.tags.map(String) : [],
+      intensity: Number.isFinite(Number(entry.intensity)) ? Number(entry.intensity) : 1,
+      ...(params && { params }),
+      ...(url && { url }),
+    };
+  });
+}
+
+function libraryCandidates() {
+  return readBundledLutIndex().map((entry) => ({
+    kind: "library",
+    ...entry,
+    text: [entry.id, entry.description, ...entry.tags].join(" "),
+  }));
+}
+
+export function matchColorLook(intent) {
+  const normalized = String(intent ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, " ");
+  if (RESOLVABLE_PRESET_IDS.includes(normalized)) {
+    return { kind: "preset", preset: normalized, score: 99 };
+  }
+
+  const candidates = [...presetCandidates(), ...libraryCandidates()]
+    .map((candidate, index) => ({
+      ...candidate,
+      index,
+      score: tokenOverlap(intent, candidate.text),
+    }))
+    .filter((candidate) => candidate.score >= 2)
+    .sort((a, b) => b.score - a.score || a.index - b.index);
+
+  if (candidates.length === 0) return null;
+  const best = candidates[0];
+  if (best.kind === "preset") {
+    return { kind: "preset", preset: best.preset, score: best.score };
+  }
+  return {
+    kind: "library",
+    id: best.id,
+    description: best.description,
+    tags: best.tags,
+    intensity: best.intensity,
+    ...(best.params && { params: best.params }),
+    ...(best.url && { url: best.url }),
+    score: best.score,
+  };
+}
+
+export function isLibraryLutOfflineMiss(err) {
+  return err?.code === LIBRARY_LUT_OFFLINE_CODE;
+}
+
+function libraryRecord(match, { id, localPath, fullPath, via }) {
+  return {
+    id,
+    localPath,
+    fullPath,
+    lut: { src: localPath, intensity: match.intensity },
+    source: "library",
+    description: match.description,
+    metadata: {
+      provider: "cube_lut.library",
+      provenance: {
+        look_id: match.id,
+        tags: match.tags,
+        via,
+      },
+    },
+  };
+}
+
+function assertValidCubeText(cube, label) {
+  const check = validateCube(cube);
+  if (!check.ok) throw new Error(`${label}: ${check.error}`);
+}
+
+function assertValidCubeFile(path, label) {
+  const check = validateCubeFile(path);
+  if (!check.ok) throw new Error(`${label}: ${check.error}`);
+}
+
+function offlineLibraryMiss(match) {
+  const err = new Error(`library LUT "${match.id}" is CDN-only and --local-only is set`);
+  err.code = LIBRARY_LUT_OFFLINE_CODE;
+  return err;
+}
+
+export async function freezeLibraryLut(match, { projectDir, type, localOnly = false }) {
+  if (!match || match.kind !== "library") {
+    throw new Error("freezeLibraryLut requires a library match");
+  }
+
+  // Prefer the CDN url so looks download on-demand (like bgm/image). Fall back
+  // to deterministic buildCube params when offline (--local-only) or if the
+  // download/validation fails, so resolution is never blocked on the network.
+  if (match.url && !localOnly) {
+    try {
+      return await withReservedFile(
+        projectDir,
+        type,
+        ".cube",
+        async ({ id, localPath, fullPath }) => {
+          const tmpPath = `${fullPath}.tmp`;
+          try {
+            // Download + validate at a .tmp path, then atomically rename. A crash
+            // (SIGKILL/OOM) between write and validate can't orphan an invalid .cube
+            // at the final path — only a validated cube is ever renamed into place.
+            await freezeUrl(match.url, tmpPath);
+            assertValidCubeFile(tmpPath, `downloaded library LUT ${match.id} failed validation`);
+            renameSync(tmpPath, fullPath);
+            return libraryRecord(match, { id, localPath, fullPath, via: "url" });
+          } finally {
+            rmSync(tmpPath, { force: true });
+          }
+        },
+      );
+    } catch (err) {
+      if (!match.params) {
+        throw new Error(`failed to freeze library LUT ${match.id}: ${err.message}`);
+      }
+      // else: fall through to the params fallback below
+    }
+  }
+
+  if (match.params) {
+    return withReservedFileSync(projectDir, type, ".cube", ({ id, localPath, fullPath }) => {
+      const tmpPath = `${fullPath}.tmp`;
+      try {
+        const cube = buildCube(match.params);
+        assertValidCubeText(cube, `invalid library LUT ${match.id}`);
+        // Write + validate at .tmp, then atomic rename — same no-orphan guarantee
+        // as the url path above.
+        writeFileSync(tmpPath, cube);
+        assertValidCubeFile(tmpPath, `invalid frozen LUT ${localPath}`);
+        renameSync(tmpPath, fullPath);
+        return libraryRecord(match, {
+          id,
+          localPath,
+          fullPath,
+          via: match.url ? "params-fallback" : "params",
+        });
+      } finally {
+        rmSync(tmpPath, { force: true });
+      }
+    });
+  }
+
+  if (match.url) throw offlineLibraryMiss(match); // url-only entry, offline
+  throw new Error(`misconfigured library LUT "${match.id}": expected params or url`);
+}