dsh-hyperframes 0.1.1 → 0.3.0

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

@@ -0,0 +1,388 @@
+import { strict as assert } from "node:assert";
+import {
+  mkdtempSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  readManifest,
+  appendRecord,
+  findByPrompt,
+  findByEntity,
+  nextId,
+  allocateId,
+  withReservedFileSync,
+  normalizePrompt,
+  manifestPath,
+  mediaDir,
+  typeDirPath,
+  typeSubdir,
+} from "./manifest.mjs";
+import { regenerateIndex, generateIndexContent } from "./index-gen.mjs";
+import {
+  contentHash,
+  cachePut,
+  cacheGet,
+  cacheGetByEntity,
+  importFromCache,
+  promote,
+} from "./cache.mjs";
+
+let tmp;
+
+function setup() {
+  tmp = mkdtempSync(join(tmpdir(), "mu-test-"));
+}
+
+function cleanup() {
+  if (tmp) rmSync(tmp, { recursive: true, force: true });
+}
+
+function makeRecord(overrides = {}) {
+  return {
+    id: "bgm_001",
+    type: "bgm",
+    path: ".media/audio/bgm/bgm_001.wav",
+    source: "search",
+    description: "soft minimal ambient",
+    duration: 11,
+    provenance: { provider: "heygen.audio.sounds", prompt: "subtle tech" },
+    ...overrides,
+  };
+}
+
+function runTests() {
+  const tests = [];
+
+  function test(name, fn) {
+    tests.push({ name, fn });
+  }
+
+  // --- manifest.mjs ---
+
+  test("readManifest returns empty array when no manifest exists", () => {
+    setup();
+    const result = readManifest(tmp);
+    assert.deepStrictEqual(result, []);
+    cleanup();
+  });
+
+  test("appendRecord writes valid JSONL and readManifest parses it back", () => {
+    setup();
+    const record = makeRecord();
+    appendRecord(tmp, record);
+    const records = readManifest(tmp);
+    assert.equal(records.length, 1);
+    assert.deepStrictEqual(records[0], record);
+    cleanup();
+  });
+
+  test("appendRecord creates .media/ and type subdirs on first write", () => {
+    setup();
+    appendRecord(tmp, makeRecord());
+    assert.ok(existsSync(mediaDir(tmp)));
+    assert.ok(existsSync(typeDirPath(tmp, "bgm")));
+    cleanup();
+  });
+
+  test("lut and grade artifacts use the shared .media/luts subdir", () => {
+    assert.equal(typeSubdir("lut"), "luts");
+    assert.equal(typeSubdir("grade"), "luts");
+
+    setup();
+    const allocated = allocateId(tmp, "lut", ".cube");
+    assert.equal(allocated.localPath, ".media/luts/lut_001.cube");
+    assert.ok(existsSync(join(tmp, allocated.localPath)));
+    cleanup();
+  });
+
+  test("appendRecord appends multiple records", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ id: "bgm_001" }));
+    appendRecord(tmp, makeRecord({ id: "bgm_002", provenance: { prompt: "energetic" } }));
+    const records = readManifest(tmp);
+    assert.equal(records.length, 2);
+    assert.equal(records[0].id, "bgm_001");
+    assert.equal(records[1].id, "bgm_002");
+    cleanup();
+  });
+
+  test("findByPrompt returns exact-match record", () => {
+    setup();
+    appendRecord(tmp, makeRecord());
+    const found = findByPrompt(tmp, "subtle tech", "bgm");
+    assert.ok(found);
+    assert.equal(found.id, "bgm_001");
+    cleanup();
+  });
+
+  test("findByPrompt returns null on miss", () => {
+    setup();
+    appendRecord(tmp, makeRecord());
+    assert.equal(findByPrompt(tmp, "nonexistent", "bgm"), null);
+    cleanup();
+  });
+
+  test("findByPrompt filters by type", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ type: "sfx" }));
+    assert.equal(findByPrompt(tmp, "subtle tech", "bgm"), null);
+    assert.ok(findByPrompt(tmp, "subtle tech", "sfx"));
+    cleanup();
+  });
+
+  test("findByPrompt matches across case and whitespace variants", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ provenance: { provider: "x", prompt: "calm ambient piano" } }));
+    assert.ok(findByPrompt(tmp, "Calm Ambient Piano", "bgm"), "case-insensitive");
+    assert.ok(findByPrompt(tmp, "  calm   ambient  piano ", "bgm"), "whitespace-insensitive");
+    assert.equal(findByPrompt(tmp, "calm ambient guitar", "bgm"), null, "still a real miss");
+    cleanup();
+  });
+
+  test("normalizePrompt trims, lowercases, collapses whitespace", () => {
+    assert.equal(normalizePrompt("  Upbeat   Tech  Launch "), "upbeat tech launch");
+    assert.equal(normalizePrompt(null), "");
+  });
+
+  test("allocateId reserves the id on disk so a pre-append caller can't reuse it (MU-23)", () => {
+    setup();
+    const a = allocateId(tmp, "bgm", ".wav");
+    assert.equal(a.id, "bgm_001");
+    assert.ok(existsSync(join(tmp, a.localPath)), "placeholder reserved on disk");
+    // Second allocation BEFORE any manifest append (the download window) must not
+    // hand back bgm_001 again, even with a different extension.
+    const b = allocateId(tmp, "bgm", ".mp3");
+    assert.equal(b.id, "bgm_002");
+    assert.notEqual(a.localPath, b.localPath);
+    // Lock file is released (not left behind).
+    assert.ok(!existsSync(join(tmp, ".media", ".lock")), "lock released");
+    cleanup();
+  });
+
+  test("allocateId continues past the highest manifest id", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ id: "bgm_005" }));
+    assert.equal(allocateId(tmp, "bgm", ".wav").id, "bgm_006");
+    cleanup();
+  });
+
+  test("failed reservation rollback preserves another completed reservation", () => {
+    setup();
+    const kept = withReservedFileSync(tmp, "bgm", ".wav", (reservation) => {
+      writeFileSync(reservation.fullPath, "completed asset");
+      return reservation;
+    });
+
+    assert.throws(
+      () =>
+        withReservedFileSync(tmp, "bgm", ".wav", () => {
+          throw new Error("populate failed");
+        }),
+      /populate failed/,
+    );
+
+    assert.equal(kept.id, "bgm_001");
+    assert.equal(readFileSync(kept.fullPath, "utf8"), "completed asset");
+    assert.deepStrictEqual(readdirSync(typeDirPath(tmp, "bgm")), ["bgm_001.wav"]);
+    assert.equal(allocateId(tmp, "bgm", ".wav").id, "bgm_002");
+    cleanup();
+  });
+
+  test("empty reservation result releases the placeholder", () => {
+    setup();
+    assert.equal(
+      withReservedFileSync(tmp, "image", ".jpg", () => null),
+      null,
+    );
+    assert.deepStrictEqual(readdirSync(typeDirPath(tmp, "image")), []);
+    cleanup();
+  });
+
+  test("findByEntity matches case-insensitively", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ entity: "GitHub", type: "icon" }));
+    assert.ok(findByEntity(tmp, "github"));
+    assert.ok(findByEntity(tmp, "GITHUB"));
+    assert.equal(findByEntity(tmp, "gitlab"), null);
+    cleanup();
+  });
+
+  test("nextId generates sequential ids", () => {
+    setup();
+    assert.equal(nextId(tmp, "bgm"), "bgm_001");
+    appendRecord(tmp, makeRecord({ id: "bgm_001" }));
+    assert.equal(nextId(tmp, "bgm"), "bgm_002");
+    appendRecord(tmp, makeRecord({ id: "bgm_002" }));
+    assert.equal(nextId(tmp, "bgm"), "bgm_003");
+    cleanup();
+  });
+
+  // --- index-gen.mjs ---
+
+  test("regenerateIndex produces plain-column table", () => {
+    setup();
+    appendRecord(tmp, makeRecord());
+    regenerateIndex(tmp);
+    const content = readFileSync(join(tmp, ".media", "index.md"), "utf8");
+    assert.ok(content.includes("# .media · 1 asset"));
+    assert.ok(content.includes("bgm_001"));
+    assert.ok(content.includes("soft minimal ambient"));
+    assert.ok(content.includes("11s"));
+    cleanup();
+  });
+
+  test("regenerateIndex handles empty manifest", () => {
+    setup();
+    mkdirSync(join(tmp, ".media"), { recursive: true });
+    writeFileSync(manifestPath(tmp), "");
+    regenerateIndex(tmp);
+    const content = readFileSync(join(tmp, ".media", "index.md"), "utf8");
+    assert.ok(content.includes("# .media · 0 assets"));
+    cleanup();
+  });
+
+  test("generateIndexContent includes dims for images", () => {
+    const records = [
+      makeRecord({ id: "img_001", type: "image", width: 1920, height: 1080, duration: null }),
+    ];
+    const content = generateIndexContent(records);
+    assert.ok(content.includes("1920×1080"));
+    assert.ok(content.includes("img_001"));
+  });
+
+  test("regenerateIndex matches manifest content after multiple writes", () => {
+    setup();
+    appendRecord(tmp, makeRecord({ id: "bgm_001" }));
+    appendRecord(
+      tmp,
+      makeRecord({ id: "sfx_001", type: "sfx", description: "whoosh", duration: 3 }),
+    );
+    regenerateIndex(tmp);
+    const content = readFileSync(join(tmp, ".media", "index.md"), "utf8");
+    assert.ok(content.includes("# .media · 2 assets"));
+    assert.ok(content.includes("bgm_001"));
+    assert.ok(content.includes("sfx_001"));
+    assert.ok(content.includes("whoosh"));
+    cleanup();
+  });
+
+  // --- cache.mjs ---
+
+  test("cacheGet returns null when cache is empty", () => {
+    const result = cacheGet("nonexistent prompt", "bgm");
+    assert.equal(result, null);
+  });
+
+  test("cachePut + cacheGet round-trip", () => {
+    setup();
+    const filePath = join(tmp, "test.wav");
+    writeFileSync(filePath, "fake audio bytes for testing");
+    const record = makeRecord({ provenance: { prompt: "cache test" } });
+
+    const { sha } = cachePut(filePath, record);
+    assert.ok(sha);
+    assert.equal(sha.length, 64);
+
+    const found = cacheGet("cache test", "bgm");
+    assert.ok(found);
+    assert.equal(found.reusable, true);
+    assert.equal(found.sha, sha);
+
+    // cross-project reuse must survive trivial prompt variation, not just
+    // byte-identical intents (the whole point of normalizePrompt).
+    assert.ok(cacheGet("  Cache   Test ", "bgm"), "cacheGet is case/whitespace-insensitive");
+    cleanup();
+  });
+
+  test("cacheGetByEntity finds cached asset", () => {
+    setup();
+    const filePath = join(tmp, "logo.png");
+    writeFileSync(filePath, "fake png bytes");
+    const record = makeRecord({
+      type: "icon",
+      entity: "TestCorp",
+      provenance: { prompt: "TestCorp logo" },
+    });
+
+    cachePut(filePath, record);
+    const found = cacheGetByEntity("testcorp");
+    assert.ok(found);
+    assert.equal(found.entity, "TestCorp");
+    cleanup();
+  });
+
+  test("contentHash is deterministic", () => {
+    setup();
+    const filePath = join(tmp, "det.bin");
+    writeFileSync(filePath, "deterministic content");
+    const h1 = contentHash(filePath);
+    const h2 = contentHash(filePath);
+    assert.equal(h1, h2);
+    cleanup();
+  });
+
+  test("promote copies project asset to global cache", () => {
+    setup();
+    const record = makeRecord();
+    appendRecord(tmp, record);
+    const filePath = join(tmp, record.path);
+    mkdirSync(join(filePath, ".."), { recursive: true });
+    writeFileSync(filePath, "promotable audio data");
+
+    const { sha } = promote(tmp, "bgm_001");
+    assert.ok(sha);
+
+    const cached = cacheGet("subtle tech", "bgm");
+    assert.ok(cached);
+    assert.equal(cached.sha, sha);
+    cleanup();
+  });
+
+  test("importFromCache copies cached file into project", () => {
+    setup();
+    const filePath = join(tmp, "source.wav");
+    writeFileSync(filePath, "importable audio");
+    const record = makeRecord({ provenance: { prompt: "import test" } });
+    const { sha } = cachePut(filePath, record);
+
+    const cached = cacheGet("import test", "bgm");
+    const projectDir = mkdtempSync(join(tmpdir(), "mu-import-"));
+    const imported = importFromCache(cached, projectDir, "bgm_001", ".media/audio/bgm/bgm_001.wav");
+
+    assert.ok(imported);
+    assert.equal(imported.id, "bgm_001");
+    assert.equal(imported.provenance.imported_from, sha);
+    assert.ok(existsSync(join(projectDir, ".media/audio/bgm/bgm_001.wav")));
+
+    rmSync(projectDir, { recursive: true, force: true });
+    cleanup();
+  });
+
+  // --- run ---
+
+  let passed = 0;
+  let failed = 0;
+  for (const { name, fn } of tests) {
+    try {
+      fn();
+      passed++;
+      console.log(`  \x1b[32m✓\x1b[0m ${name}`);
+    } catch (err) {
+      failed++;
+      console.log(`  \x1b[31m✗\x1b[0m ${name}`);
+      console.log(`    ${err.message}`);
+    }
+  }
+  console.log(`\n${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+}
+
+console.log("media-use · manifest/index/cache tests\n");
+runTests();

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

@@ -0,0 +1,47 @@
+// Shared lexical-matching helpers used by both the assets/ scan (adopt.mjs) and
+// the reuse-candidate ranker (candidates.mjs), and the type-equivalence check
+// used by resolve.mjs and candidates.mjs. Kept in one place so the icon<->image
+// equivalence and the token rules can't drift between the "do" path (resolve)
+// and the "look" path (candidates).
+
+// Common filler words that should never, on their own, make two strings match.
+const MATCH_STOPWORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "this",
+  "that",
+  "your",
+  "our",
+]);
+
+// Split into lowercased word tokens of length >= 3, minus stopwords.
+export function matchTokens(text) {
+  return new Set(
+    String(text)
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((t) => t.length >= 3 && !MATCH_STOPWORDS.has(t)),
+  );
+}
+
+// Count of shared meaningful word tokens between two strings. 0 = no lexical
+// overlap (the candidate ranker still surfaces these, ordered after overlaps).
+export function tokenOverlap(a, b) {
+  const ta = matchTokens(a);
+  const tb = matchTokens(b);
+  let n = 0;
+  for (const t of ta) if (tb.has(t)) n++;
+  return n;
+}
+
+// icon, image, and logo are interchangeable: all live in images/, and
+// figma-imported brand marks are recorded as type image while agents ask for
+// logos as icon or logo.
+export function typesMatch(a, b) {
+  if (a === b) return true;
+  const visual = new Set(["icon", "image", "logo"]);
+  return visual.has(a) && visual.has(b);
+}

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

@@ -0,0 +1,128 @@
+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;
+}