dsh-hyperframes 0.10.1 → 0.11.0

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

@@ -0,0 +1,95 @@
+import { strict as assert } from "node:assert";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { findExistingAsset, adoptExistingAssets } from "./adopt.mjs";
+
+let tmp;
+function setup() {
+  tmp = mkdtempSync(join(tmpdir(), "mu-adopt-test-"));
+}
+function cleanup() {
+  if (tmp) rmSync(tmp, { recursive: true, force: true });
+}
+function drop(rel) {
+  const full = join(tmp, "assets", rel);
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, "x");
+}
+
+function runTests() {
+  const tests = [];
+  const test = (name, fn) => tests.push({ name, fn });
+
+  test("does NOT false-match a short filename stem (who.mp3 vs 'whoosh')", () => {
+    setup();
+    drop("sfx/who.mp3");
+    assert.equal(findExistingAsset(tmp, "whoosh", "sfx"), null);
+    cleanup();
+  });
+
+  test("does NOT match a one-letter filename against any intent", () => {
+    setup();
+    drop("images/a.jpg");
+    assert.equal(findExistingAsset(tmp, "gradient tech background", "image"), null);
+    cleanup();
+  });
+
+  test("matches on a shared meaningful word", () => {
+    setup();
+    drop("images/hero-shot.jpg");
+    const hit = findExistingAsset(tmp, "hero image", "image");
+    assert.ok(hit);
+    assert.equal(hit.relativePath, "assets/images/hero-shot.jpg");
+    cleanup();
+  });
+
+  test("matches multi-word overlap", () => {
+    setup();
+    drop("images/gradient-tech-bg.jpg");
+    assert.ok(findExistingAsset(tmp, "gradient tech background", "image"));
+    cleanup();
+  });
+
+  test("a shared stopword alone does not match", () => {
+    setup();
+    drop("video/the-video.mp4");
+    assert.equal(findExistingAsset(tmp, "the rocket", null), null);
+    cleanup();
+  });
+
+  test("respects the type filter", () => {
+    setup();
+    drop("sfx/rocket.mp3");
+    assert.equal(findExistingAsset(tmp, "rocket", "image"), null, "wrong type is skipped");
+    assert.ok(findExistingAsset(tmp, "rocket", "sfx"), "right type matches");
+    cleanup();
+  });
+
+  test("adoptExistingAssets still imports every typed file (unaffected by match rule)", () => {
+    setup();
+    drop("sfx/who.mp3");
+    drop("images/a.jpg");
+    assert.equal(adoptExistingAssets(tmp).length, 2);
+    cleanup();
+  });
+
+  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 · adopt / findExistingAsset tests\n");
+runTests();

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

@@ -0,0 +1,20 @@
+import { heygenSearch } from "./heygen-search.mjs";
+
+export const bgmProvider = {
+  async search(intent) {
+    const results = heygenSearch("audio sounds list", intent, { type: "music" });
+    if (!results) return null;
+    const best = results[0];
+    return {
+      url: best.audio_url,
+      source: "search",
+      // ext derived from audio_url by resolve.mjs — catalog tracks are .mp3 or .wav
+      metadata: {
+        description: best.description || intent,
+        duration: best.duration || null,
+        provider: "heygen.audio.sounds",
+        provenance: { track_id: best.id, score: best.score, query: intent },
+      },
+    };
+  },
+};

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

@@ -0,0 +1,59 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+function findDesignSpec(projectDir) {
+  for (const name of ["frame.md", "design.md", "DESIGN.md"]) {
+    const p = join(projectDir, name);
+    if (existsSync(p)) return { path: p, name };
+  }
+  return null;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const yaml = match[1];
+  const tokens = {};
+  for (const line of yaml.split("\n")) {
+    const m = line.match(/^\s*(\w[\w-]*):\s*(.+)/);
+    if (m) tokens[m[1]] = m[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return tokens;
+}
+
+function extractColors(tokens) {
+  const colors = [];
+  for (const [k, v] of Object.entries(tokens)) {
+    if (typeof v === "string" && /^#[0-9a-fA-F]{3,8}$/.test(v)) {
+      colors.push({ name: k, hex: v });
+    }
+  }
+  return colors;
+}
+
+export const brandProvider = {
+  async search(intent, { projectDir } = {}) {
+    if (!projectDir) return null;
+    const spec = findDesignSpec(projectDir);
+    if (!spec) return null;
+    const content = readFileSync(spec.path, "utf8");
+    const tokens = parseFrontmatter(content);
+    if (!tokens) return null;
+    const colors = extractColors(tokens);
+    return {
+      localPath: spec.path,
+      source: "local",
+      ext: ".md",
+      metadata: {
+        description: "Brand tokens from " + spec.name,
+        provider: "design_spec",
+        provenance: {
+          file: spec.name,
+          colors,
+          font: tokens.font || tokens.typography || null,
+          logo: tokens.logo || null,
+        },
+      },
+    };
+  },
+};

package/skills/media-use/scripts/lib/bundled-sfx-provider.mjs

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import { rankMediaRows } from "./media-search.mjs";
+
+const LIB_DIR =
+  process.env.HYPERFRAMES_MEDIA_USE_SFX_DIR ||
+  [
+    join(import.meta.dirname, "..", "..", "audio", "assets", "sfx"),
+    join(
+      import.meta.dirname,
+      "..",
+      "..",
+      "..",
+      "..",
+      "..",
+      "skills",
+      "media-use",
+      "audio",
+      "assets",
+      "sfx",
+    ),
+  ].find((candidate) => existsSync(candidate)) ||
+  join(import.meta.dirname, "..", "..", "audio", "assets", "sfx");
+
+export const BUNDLED_SFX_RECOVERY_COMMAND = "npx hyperframes skills update media-use";
+
+export class BundledSfxAssetsError extends Error {
+  constructor(health) {
+    super(
+      `bundled SFX assets are missing or incomplete (${health.detail}). Repair the installed media-use skill: ${health.fix}`,
+    );
+    this.name = "BundledSfxAssetsError";
+    this.code = health.code;
+    this.fix = health.fix;
+  }
+}
+
+function unhealthy(detail) {
+  return {
+    ok: false,
+    code: "bundled_sfx_assets_missing",
+    detail,
+    fix: BUNDLED_SFX_RECOVERY_COMMAND,
+  };
+}
+
+export function inspectBundledSfxAssets(libraryDir = LIB_DIR) {
+  const manifestPath = join(libraryDir, "manifest.json");
+  if (!existsSync(manifestPath)) return unhealthy(`manifest not found: ${manifestPath}`);
+
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return unhealthy(`manifest is not valid JSON: ${manifestPath}`);
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return unhealthy(`manifest must contain an object: ${manifestPath}`);
+  }
+
+  const entries = Object.entries(manifest);
+  if (entries.length === 0) return unhealthy(`manifest contains no SFX entries: ${manifestPath}`);
+  for (const [key, entry] of entries) {
+    if (!entry?.file || typeof entry.file !== "string") {
+      return unhealthy(`manifest entry "${key}" has no file`);
+    }
+    const assetPath = join(libraryDir, entry.file);
+    if (!existsSync(assetPath)) return unhealthy(`asset not found: ${assetPath}`);
+  }
+
+  return {
+    ok: true,
+    count: entries.length,
+    detail: `${entries.length} bundled SFX asset${entries.length === 1 ? "" : "s"} available`,
+    fix: "",
+  };
+}
+
+export function extensionForBundledSfxFile(filename) {
+  return extname(filename) || ".mp3";
+}
+
+export const bundledSfxProvider = {
+  async search(intent, ctx = {}) {
+    const libraryDir = ctx.libraryDir || LIB_DIR;
+    const health = inspectBundledSfxAssets(libraryDir);
+    if (!health.ok) throw new BundledSfxAssetsError(health);
+    const manifest = JSON.parse(readFileSync(join(libraryDir, "manifest.json"), "utf8"));
+
+    const rows = Object.entries(manifest).map(([key, entry]) => ({
+      id: key,
+      kind: "sfx",
+      title: key,
+      description: entry?.description || key,
+      tags: ["sfx"],
+      file: entry?.file || "",
+      duration: entry?.duration,
+    }));
+    const bestRow = rankMediaRows(intent, rows)[0];
+    const best =
+      bestRow && manifest[bestRow.id]?.file
+        ? { key: bestRow.id, entry: manifest[bestRow.id] }
+        : null;
+    if (!best) return null;
+
+    const localPath = join(libraryDir, best.entry.file);
+    return {
+      localPath,
+      ext: extensionForBundledSfxFile(best.entry.file),
+      source: "bundled",
+      metadata: {
+        description: best.entry.description || best.key,
+        duration: best.entry.duration ?? null,
+        provider: "bundled.sfx",
+        provenance: { library_key: best.key },
+      },
+    };
+  },
+};

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

@@ -0,0 +1,139 @@
+import { strict as assert } from "node:assert";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  BUNDLED_SFX_RECOVERY_COMMAND,
+  BundledSfxAssetsError,
+  bundledSfxProvider,
+  extensionForBundledSfxFile,
+  inspectBundledSfxAssets,
+} from "./bundled-sfx-provider.mjs";
+import { rankMediaRows } from "./media-search.mjs";
+
+test("derives bundled SFX extension from the manifest filename", () => {
+  assert.equal(extensionForBundledSfxFile("impact.wav"), ".wav");
+  assert.equal(extensionForBundledSfxFile("whoosh.ogg"), ".ogg");
+  assert.equal(extensionForBundledSfxFile("extensionless"), ".mp3");
+});
+
+test("reports an agent-friendly recovery when the bundled SFX manifest is absent", () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-missing-"));
+  try {
+    const health = inspectBundledSfxAssets(libraryDir);
+    assert.equal(health.ok, false);
+    assert.equal(health.code, "bundled_sfx_assets_missing");
+    assert.match(health.detail, /manifest\.json/);
+    assert.match(health.fix, /hyperframes skills update media-use/);
+    assert.equal(health.fix, BUNDLED_SFX_RECOVERY_COMMAND);
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("reports the exact missing file from an incomplete bundled SFX install", () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-incomplete-"));
+  try {
+    writeFileSync(
+      join(libraryDir, "manifest.json"),
+      JSON.stringify({ whoosh: { file: "whoosh.mp3", description: "transition" } }),
+    );
+    const health = inspectBundledSfxAssets(libraryDir);
+    assert.equal(health.ok, false);
+    assert.equal(health.code, "bundled_sfx_assets_missing");
+    assert.match(health.detail, /whoosh\.mp3/);
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("bundled provider raises a typed install error instead of a generic catalog miss", async () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-provider-"));
+  try {
+    await assert.rejects(
+      () => bundledSfxProvider.search("whoosh", { libraryDir }),
+      (error) => {
+        assert.ok(error instanceof BundledSfxAssetsError);
+        assert.equal(error.code, "bundled_sfx_assets_missing");
+        assert.match(error.message, /hyperframes skills update media-use/);
+        return true;
+      },
+    );
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("accepts a complete bundled SFX library", () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-complete-"));
+  try {
+    mkdirSync(libraryDir, { recursive: true });
+    writeFileSync(
+      join(libraryDir, "manifest.json"),
+      JSON.stringify({ whoosh: { file: "whoosh.mp3", description: "transition" } }),
+    );
+    writeFileSync(join(libraryDir, "whoosh.mp3"), "audio");
+    assert.deepEqual(inspectBundledSfxAssets(libraryDir), {
+      ok: true,
+      count: 1,
+      detail: "1 bundled SFX asset available",
+      fix: "",
+    });
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("prefers an exact key over a longer key with the same words", async () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-exact-key-"));
+  try {
+    writeFileSync(
+      join(libraryDir, "manifest.json"),
+      JSON.stringify({
+        "whoosh-cinematic": { file: "whoosh-cinematic.mp3", description: "long whoosh" },
+        whoosh: { file: "whoosh.mp3", description: "short whoosh" },
+      }),
+    );
+    writeFileSync(join(libraryDir, "whoosh-cinematic.mp3"), "cinematic audio");
+    writeFileSync(join(libraryDir, "whoosh.mp3"), "exact audio");
+
+    const result = await bundledSfxProvider.search("whoosh", { libraryDir });
+    assert.equal(result?.localPath, join(libraryDir, "whoosh.mp3"));
+    assert.equal(result?.metadata.provenance.library_key, "whoosh");
+
+    const stemmed = await bundledSfxProvider.search("whooshes", { libraryDir });
+    assert.equal(stemmed?.localPath, join(libraryDir, "whoosh.mp3"));
+    assert.equal(stemmed?.metadata.provenance.library_key, "whoosh");
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("literal ids outrank distinct ids with the same stem", () => {
+  const rows = [
+    {
+      id: "cats",
+      title: "Cats Fighting",
+      description: "fighting cats",
+      tags: ["yowl", "fight"],
+      kind: "sfx",
+    },
+    {
+      id: "cat",
+      title: "Cat",
+      description: "single cat",
+      tags: ["meow"],
+      kind: "sfx",
+    },
+  ];
+
+  assert.deepEqual(
+    rankMediaRows("cat", rows).map((row) => row.id),
+    ["cat", "cats"],
+  );
+  assert.deepEqual(
+    rankMediaRows("cats", rows).map((row) => row.id),
+    ["cats", "cat"],
+  );
+});

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

@@ -0,0 +1,162 @@
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  copyFileSync,
+  statSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+import { createHash } from "node:crypto";
+import { readManifest, appendRecord, normalizePrompt } from "./manifest.mjs";
+import { globalMediaDir, mediaHome } from "./media-home.mjs";
+
+export { globalMediaDir };
+
+const SCHEMA_PREFIX = "mu-v1-";
+const KEY_HEX_CHARS = 16;
+const COMPLETE_SENTINEL = ".hf-complete";
+
+export function contentHash(filePath) {
+  const bytes = readFileSync(filePath);
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function cacheEntryDir(rootDir, sha) {
+  return join(rootDir, SCHEMA_PREFIX + sha.slice(0, KEY_HEX_CHARS));
+}
+
+function isComplete(entryDir) {
+  return existsSync(join(entryDir, COMPLETE_SENTINEL));
+}
+
+function markComplete(entryDir) {
+  writeFileSync(join(entryDir, COMPLETE_SENTINEL), "", "utf8");
+}
+
+// The manifest helpers append their own ".media" to the dir they get, so the
+// global manifest must be addressed by mediaHome(), not by globalMediaDir() — passing
+// the latter nested it at ~/.media/.media/manifest.jsonl, invisible to the
+// Studio /api/assets/global route (which reads the documented flat path).
+export function readGlobalManifest() {
+  return readManifest(mediaHome());
+}
+
+// Resolve a content-sha (full or unambiguous prefix) to a reusable global-cache
+// record, for `resolve --reuse <sha>`. Returns null on no match, or
+// { ambiguous: true, count } when a prefix matches multiple distinct entries.
+// Completeness (the .hf-complete sentinel) is left to importFromCache so the
+// caller can surface an "incomplete cache entry" error distinctly from a miss.
+export function findGlobalBySha(shaPrefix) {
+  const p = String(shaPrefix || "")
+    .toLowerCase()
+    .trim();
+  if (!p) return null;
+  const matchingRecords = readGlobalManifest().filter(
+    (r) => r.reusable && typeof r.sha === "string" && r.sha.startsWith(p),
+  );
+  const matches = Array.from(new Map(matchingRecords.map((r) => [r.sha, r])).values());
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    const exact = matches.find((r) => r.sha === p);
+    if (exact) return exact;
+    return { ambiguous: true, count: matches.length };
+  }
+  return matches[0];
+}
+
+function validateCacheHit(match) {
+  if (!match?.sha || !match.cached_path) return null;
+  if (!isComplete(cacheEntryDir(globalMediaDir(), match.sha))) return null;
+  try {
+    const file = statSync(match.cached_path);
+    return file.isFile() && file.size > 0 ? match : null;
+  } catch {
+    return null;
+  }
+}
+
+export function cacheGet(prompt, type) {
+  const key = normalizePrompt(prompt);
+  if (!key) return null;
+  return (
+    readGlobalManifest().find(
+      (r) =>
+        r.reusable &&
+        normalizePrompt(r.provenance?.prompt) === key &&
+        (type == null || r.type === type) &&
+        validateCacheHit(r),
+    ) ?? null
+  );
+}
+
+export function cacheGetByEntity(entity) {
+  const lower = entity.toLowerCase();
+  return (
+    readGlobalManifest().find(
+      (r) => r.reusable && r.entity && r.entity.toLowerCase() === lower && validateCacheHit(r),
+    ) ?? null
+  );
+}
+
+export function cachePut(filePath, record) {
+  const sha = contentHash(filePath);
+  // Idempotent: same content already promoted -> don't duplicate the global
+  // record. ponytail: skips usage_count bump; add it when the metric is needed.
+  const existing = readGlobalManifest().findLast((r) => r.sha === sha && validateCacheHit(r));
+  if (existing) return { sha, cached_path: existing.cached_path, deduped: true };
+
+  const dir = globalMediaDir();
+  const entryDir = cacheEntryDir(dir, sha);
+  mkdirSync(entryDir, { recursive: true });
+
+  const dest = join(entryDir, basename(filePath));
+  copyFileSync(filePath, dest);
+  markComplete(entryDir);
+
+  const globalRecord = {
+    ...record,
+    sha,
+    reusable: true,
+    cached_path: dest,
+  };
+  appendRecord(mediaHome(), globalRecord);
+  return { sha, cached_path: dest };
+}
+
+export function importFromCache(cacheRecord, projectDir, localId, localPath) {
+  if (!validateCacheHit(cacheRecord)) return null;
+  const sha = cacheRecord.sha;
+  const cachedFile = cacheRecord.cached_path;
+
+  mkdirSync(join(projectDir, ".media"), { recursive: true });
+  const fullDest = join(projectDir, localPath);
+  mkdirSync(join(fullDest, ".."), { recursive: true });
+  copyFileSync(cachedFile, fullDest);
+
+  const projectRecord = {
+    ...cacheRecord,
+    id: localId,
+    path: localPath,
+    provenance: {
+      ...cacheRecord.provenance,
+      imported_from: sha,
+    },
+  };
+  delete projectRecord.sha;
+  delete projectRecord.reusable;
+  delete projectRecord.cached_path;
+
+  return projectRecord;
+}
+
+export function promote(projectDir, id) {
+  const records = readManifest(projectDir);
+  const record = records.find((r) => r.id === id);
+  if (!record) throw new Error(`asset not found in project manifest: ${id}`);
+
+  const filePath = join(projectDir, record.path);
+  if (!existsSync(filePath)) throw new Error(`asset file not found: ${filePath}`);
+
+  return cachePut(filePath, record);
+}