dsh-hyperframes 0.3.2 → 0.4.0

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

@@ -1,128 +0,0 @@
-import { readdirSync, statSync, existsSync } from "node:fs";
-import { join, extname, basename } from "node:path";
-import { readManifest, appendRecord, nextId } from "./manifest.mjs";
-import { regenerateIndex } from "./index-gen.mjs";
-import { probe } from "./probe.mjs";
-import { matchTokens } from "./match.mjs";
-
-const AUDIO_EXT = new Set([".mp3", ".wav", ".ogg", ".m4a", ".aac"]);
-const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".ico"]);
-const VIDEO_EXT = new Set([".mp4", ".webm", ".mov"]);
-
-function inferType(filePath) {
-  const ext = extname(filePath).toLowerCase();
-  if (AUDIO_EXT.has(ext)) {
-    const lower = filePath.toLowerCase();
-    if (lower.includes("/bgm/") || lower.includes("/music/") || lower.startsWith("bgm/"))
-      return "bgm";
-    if (lower.includes("/sfx/") || lower.includes("/sound") || lower.startsWith("sfx/"))
-      return "sfx";
-    if (lower.includes("/voice/") || lower.includes("/narrat") || lower.startsWith("voice/"))
-      return "voice";
-    return "bgm";
-  }
-  if (IMAGE_EXT.has(ext)) {
-    if (ext === ".svg" || ext === ".ico") return "icon";
-    return "image";
-  }
-  if (VIDEO_EXT.has(ext)) return "video";
-  return null;
-}
-
-function walkDir(dir, base = "") {
-  const files = [];
-  if (!existsSync(dir)) return files;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const rel = base ? `${base}/${entry.name}` : entry.name;
-    if (entry.isDirectory()) {
-      files.push(...walkDir(join(dir, entry.name), rel));
-    } else {
-      files.push(rel);
-    }
-  }
-  return files;
-}
-
-export function scanExistingAssets(projectDir) {
-  const assetsDir = join(projectDir, "assets");
-  if (!existsSync(assetsDir)) return [];
-
-  const files = walkDir(assetsDir);
-  const found = [];
-  for (const rel of files) {
-    const type = inferType(rel);
-    if (!type) continue;
-    const fullPath = join(assetsDir, rel);
-    const stat = statSync(fullPath);
-    if (stat.size === 0) {
-      // A 0-byte asset would register clean but fail at render — skip it loudly
-      // rather than adopt a broken file.
-      console.error(`media-use: skipping 0-byte asset assets/${rel}`);
-      continue;
-    }
-    const meta = probe(fullPath);
-    found.push({
-      relativePath: `assets/${rel}`,
-      type,
-      size: stat.size,
-      name: basename(rel, extname(rel)),
-      ...meta,
-    });
-  }
-  return found;
-}
-
-export function adoptExistingAssets(projectDir) {
-  const existing = scanExistingAssets(projectDir);
-  if (existing.length === 0) return [];
-
-  const manifest = readManifest(projectDir);
-  const knownPaths = new Set(manifest.map((r) => r.path));
-
-  const adopted = [];
-  for (const asset of existing) {
-    if (knownPaths.has(asset.relativePath)) continue;
-
-    const id = nextId(projectDir, asset.type);
-    const record = {
-      id,
-      type: asset.type,
-      path: asset.relativePath,
-      source: "existing",
-      description: asset.name.replace(/[-_]/g, " "),
-      ...(asset.duration != null && { duration: asset.duration }),
-      ...(asset.width != null && { width: asset.width }),
-      ...(asset.height != null && { height: asset.height }),
-      provenance: { provider: "local", adopted: true },
-    };
-    appendRecord(projectDir, record);
-    adopted.push(record);
-  }
-
-  if (adopted.length > 0) regenerateIndex(projectDir);
-  return adopted;
-}
-
-// Adopt a pre-existing assets/ file only when it shares a meaningful word with
-// the intent. The old test — `name.includes(intent) || intent.includes(name)` —
-// silently returned the WRONG file: "whoosh" grabbed a stray who.mp3, and a
-// one-letter filename matched every intent. A false negative just falls through
-// to a catalog search (safe); a false positive ships the wrong asset. So bias to
-// precision: require a shared token, don't guess from substrings.
-export function findExistingAsset(projectDir, intent, type) {
-  const assetsDir = join(projectDir, "assets");
-  if (!existsSync(assetsDir)) return null;
-  const intentTokens = matchTokens(intent);
-  if (intentTokens.size === 0) return null;
-  for (const rel of walkDir(assetsDir)) {
-    const t = inferType(rel);
-    if (!t || (type && t !== type)) continue;
-    const stem = basename(rel, extname(rel));
-    for (const tok of matchTokens(stem)) {
-      if (intentTokens.has(tok)) {
-        return { relativePath: `assets/${rel}`, type: t, name: stem };
-      }
-    }
-  }
-  return null;
-}

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

@@ -1,95 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,59 +0,0 @@
-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

@@ -1,108 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { extname, join } from "node:path";
-
-const LIB_DIR =
-  process.env.HYPERFRAMES_MEDIA_USE_SFX_DIR ||
-  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: "",
-  };
-}
-
-const normalize = (value) =>
-  String(value)
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, " ")
-    .trim();
-
-export function extensionForBundledSfxFile(filename) {
-  return extname(filename) || ".mp3";
-}
-
-function score(intent, key, entry) {
-  const query = normalize(intent);
-  const name = normalize(key);
-  if (query === name) return 100;
-  if (query.includes(name) || name.includes(query)) return 50;
-  const haystack = new Set(normalize(`${key} ${entry.description || ""}`).split(/\s+/));
-  return query.split(/\s+/).filter((token) => token && haystack.has(token)).length;
-}
-
-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 ranked = Object.entries(manifest)
-      .map(([key, entry]) => ({ key, entry, score: score(intent, key, entry) }))
-      .filter(({ entry, score }) => entry?.file && score > 0)
-      .sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));
-    const best = ranked[0];
-    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

@@ -1,85 +0,0 @@
-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";
-
-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 });
-  }
-});

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

@@ -1,150 +0,0 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
-import { join, basename } from "node:path";
-import { createHash } from "node:crypto";
-import { homedir } from "node:os";
-import { readManifest, appendRecord, normalizePrompt } from "./manifest.mjs";
-
-const SCHEMA_PREFIX = "mu-v1-";
-const KEY_HEX_CHARS = 16;
-const COMPLETE_SENTINEL = ".hf-complete";
-
-export function globalMediaDir() {
-  return join(homedir(), ".media");
-}
-
-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 HOME, 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(homedir());
-}
-
-// 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 matches = readGlobalManifest().filter(
-    (r) => r.reusable && typeof r.sha === "string" && r.sha.startsWith(p),
-  );
-  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) return null;
-  return isComplete(cacheEntryDir(globalMediaDir(), match.sha)) ? match : null;
-}
-
-export function cacheGet(prompt, type) {
-  const key = normalizePrompt(prompt);
-  if (!key) return null;
-  return validateCacheHit(
-    readGlobalManifest().find(
-      (r) =>
-        r.reusable &&
-        normalizePrompt(r.provenance?.prompt) === key &&
-        (type == null || r.type === type),
-    ),
-  );
-}
-
-export function cacheGetByEntity(entity) {
-  const lower = entity.toLowerCase();
-  return validateCacheHit(
-    readGlobalManifest().find((r) => r.reusable && r.entity && r.entity.toLowerCase() === lower),
-  );
-}
-
-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().find((r) => r.sha === sha);
-  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(homedir(), globalRecord);
-  return { sha, cached_path: dest };
-}
-
-export function importFromCache(cacheRecord, projectDir, localId, localPath) {
-  const sha = cacheRecord.sha;
-  const entryDir = cacheEntryDir(globalMediaDir(), sha);
-  if (!isComplete(entryDir)) return null;
-
-  const cachedFile = cacheRecord.cached_path;
-  if (!cachedFile || !existsSync(cachedFile)) return null;
-
-  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);
-}