hyperframes 0.8.77 → 0.8.79

package/dist/skills/media-use/scripts/compatibility.test.mjs

@@ -6,6 +6,8 @@ import { execFileSync } from "node:child_process";
 import test from "node:test";
 import { pathToFileURL } from "node:url";
 
+process.env.HYPERFRAMES_MEDIA_HOME = mkdtempSync(join(tmpdir(), "media-use-compat-home-"));
+
 function run(scriptsDir, script, args) {
   return execFileSync(process.execPath, [join(scriptsDir, script), ...args], {
     encoding: "utf8",

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

@@ -1,17 +1,15 @@
 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";
+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 globalMediaDir() {
-  return join(homedir(), ".media");
-}
-
 export function contentHash(filePath) {
   const bytes = readFileSync(filePath);
   return createHash("sha256").update(bytes).digest("hex");
@@ -30,11 +28,11 @@ function markComplete(entryDir) {
 }
 
 // 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
+// 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(homedir());
+  return readManifest(mediaHome());
 }
 
 // Resolve a content-sha (full or unambiguous prefix) to a reusable global-cache
@@ -105,7 +103,7 @@ export function cachePut(filePath, record) {
     reusable: true,
     cached_path: dest,
   };
-  appendRecord(homedir(), globalRecord);
+  appendRecord(mediaHome(), globalRecord);
   return { sha, cached_path: dest };
 }
 

package/dist/skills/media-use/scripts/lib/candidates.test.mjs

@@ -6,13 +6,13 @@ import { tmpdir } from "node:os";
 import { listCandidates, formatCandidates, CANDIDATE_CAP } from "./candidates.mjs";
 import { findGlobalBySha } from "./cache.mjs";
 
-// candidates + findGlobalBySha are offline (no heygen), so we can override HOME
+// candidates + findGlobalBySha are offline (no heygen), so we can point HYPERFRAMES_MEDIA_HOME
 // to a temp dir and seed a fake global ~/.media manifest deterministically.
 function sandbox() {
   const root = mkdtempSync(join(tmpdir(), "mu-cand-"));
   const project = join(root, "proj");
   const home = join(root, "home");
-  process.env.HOME = home;
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
   return { root, project, home };
 }
 function seedManifest(dir, records) {

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

@@ -34,6 +34,8 @@ import {
   promote,
 } from "./cache.mjs";
 
+process.env.HYPERFRAMES_MEDIA_HOME = mkdtempSync(join(tmpdir(), "mu-media-home-"));
+
 let tmp;
 
 function setup() {

package/dist/skills/media-use/scripts/lib/media-home.mjs

@@ -0,0 +1,20 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// The one owner of where the person's media library lives. This repo's test runs set
+// HYPERFRAMES_MEDIA_HOME_REQUIRED, so a test that forgot HYPERFRAMES_MEDIA_HOME fails instead
+// of writing fixtures into the media library apps list as the person's own files.
+export function mediaHome() {
+  const override = process.env.HYPERFRAMES_MEDIA_HOME;
+  if (override) return override;
+  if (process.env.HYPERFRAMES_MEDIA_HOME_REQUIRED) {
+    throw new Error(
+      "media-use: a test reached the real ~/.media; set HYPERFRAMES_MEDIA_HOME to a temp dir",
+    );
+  }
+  return homedir();
+}
+
+export function globalMediaDir() {
+  return join(mediaHome(), ".media");
+}

package/dist/skills/media-use/scripts/lib/media-home.test.mjs

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { cachePut } from "./cache.mjs";
+import { globalMediaDir } from "./media-home.mjs";
+
+const HOME = mkdtempSync(join(tmpdir(), "media-home-"));
+process.env.HYPERFRAMES_MEDIA_HOME = HOME;
+
+test("the global cache writes into the media home a test points it at", () => {
+  const work = mkdtempSync(join(tmpdir(), "media-home-src-"));
+  const file = join(work, "clip.wav");
+  writeFileSync(file, "media-home regression bytes");
+  cachePut(file, { id: "bgm_001", type: "bgm", provenance: { prompt: "media home probe" } });
+  const manifest = join(HOME, ".media", "manifest.jsonl");
+  assert.ok(existsSync(manifest), "the temp media home holds the global manifest");
+  assert.match(readFileSync(manifest, "utf8"), /media home probe/);
+  assert.equal(globalMediaDir(), join(HOME, ".media"));
+});
+
+// A child process that resolves the media dir, with only the given media-home variables set.
+function runProbe(env) {
+  const lib = new URL("./media-home.mjs", import.meta.url).href;
+  const childEnv = { ...process.env };
+  delete childEnv.HYPERFRAMES_MEDIA_HOME;
+  delete childEnv.HYPERFRAMES_MEDIA_HOME_REQUIRED;
+  delete childEnv.NODE_TEST_CONTEXT;
+  const run = spawnSync(
+    process.execPath,
+    [
+      "--input-type=module",
+      "-e",
+      `const m = await import(${JSON.stringify(lib)}); console.log("dir=" + m.globalMediaDir());`,
+    ],
+    { encoding: "utf8", env: { ...childEnv, ...env } },
+  );
+  return { status: run.status, output: `${run.stdout}${run.stderr}` };
+}
+
+test("a repo test run that never points the media home anywhere fails instead of writing", () => {
+  const { status, output } = runProbe({ HYPERFRAMES_MEDIA_HOME_REQUIRED: "1" });
+  assert.notEqual(status, 0, output);
+  assert.match(output, /set HYPERFRAMES_MEDIA_HOME to a temp dir/);
+});
+
+// Node sets NODE_TEST_CONTEXT for every project's test runs, so another project whose own tests
+// spawn this CLI must get the person's real library, not the guard.
+test("another project's node --test run still resolves the real media home", () => {
+  const home = mkdtempSync(join(tmpdir(), "media-home-user-"));
+  const { status, output } = runProbe({
+    HOME: home,
+    USERPROFILE: home,
+    NODE_TEST_CONTEXT: "child-v8",
+  });
+  assert.equal(status, 0, output);
+  assert.ok(output.includes(`dir=${join(home, ".media")}`), output);
+});

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

@@ -1,19 +1,19 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
 
 const MISSES_FILE = "misses.jsonl";
 
 function missesPath() {
-  return join(homedir(), ".media", MISSES_FILE);
+  return join(globalMediaDir(), MISSES_FILE);
 }
 
 export function recordMiss({ type, intent, provider_override, local_only }) {
   try {
-    const dir = join(homedir(), ".media");
-    mkdirSync(dir, { recursive: true });
+    const path = missesPath();
+    mkdirSync(dirname(path), { recursive: true });
     appendFileSync(
-      join(dir, MISSES_FILE),
+      path,
       JSON.stringify({
         ts: new Date().toISOString(),
         type,

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

@@ -9,7 +9,7 @@ function sandbox() {
   const root = mkdtempSync(join(tmpdir(), "mu-misses-"));
   const home = join(root, "home");
   mkdirSync(home, { recursive: true });
-  process.env.HOME = home;
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
   return { root, home };
 }
 
@@ -54,6 +54,17 @@ test("recordMiss swallows filesystem failures", () => {
   }
 });
 
+test("recordMiss stays best-effort when the media home cannot be resolved", () => {
+  const savedEnv = { ...process.env };
+  delete process.env.HYPERFRAMES_MEDIA_HOME;
+  process.env.HYPERFRAMES_MEDIA_HOME_REQUIRED = "1";
+  try {
+    assert.doesNotThrow(() => recordMiss({ type: "sfx", intent: "no home", local_only: true }));
+  } finally {
+    restoreEnv(savedEnv);
+  }
+});
+
 test("readMisses skips corrupt lines", () => {
   const savedEnv = { ...process.env };
   const { root, home } = sandbox();

package/dist/skills/media-use/scripts/lib/prefs-store.mjs

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
 
 /**
  * Remembered defaults — the lightweight tier of HyperFrames user memory.
@@ -41,7 +41,7 @@ export function projectPrefsPath(projectDir) {
 }
 
 export function userPrefsPath() {
-  return join(homedir(), ".media", PREFS_FILE);
+  return join(globalMediaDir(), PREFS_FILE);
 }
 
 function emptyFile() {

package/dist/skills/media-use/scripts/lib/prefs-store.test.mjs

@@ -19,7 +19,7 @@ function sandbox() {
   mkdirSync(home, { recursive: true });
   mkdirSync(projectA, { recursive: true });
   mkdirSync(projectB, { recursive: true });
-  process.env.HOME = home;
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
   return { root, home, projectA, projectB };
 }
 

package/dist/skills/media-use/scripts/lib/recipe-store.mjs

@@ -8,8 +8,8 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
 import { appendRecord, mediaDir, nextId } from "./manifest.mjs";
 import { regenerateIndex } from "./index-gen.mjs";
 import { mergedPreferences } from "./prefs-store.mjs";
@@ -58,7 +58,7 @@ export function projectRecipesDir(projectDir) {
 }
 
 export function userRecipesDir() {
-  return join(homedir(), ".media", "recipes");
+  return join(globalMediaDir(), "recipes");
 }
 
 export function slugifyRecipeName(name) {

package/dist/skills/media-use/scripts/lib/recipe-store.test.mjs

@@ -83,7 +83,7 @@ function sandbox() {
   mkdirSync(project, { recursive: true });
   writeFileSync(join(project, "frame.md"), "# Frame spec\nbackground: #101014\n");
   writeFileSync(join(project, "STORYBOARD.md"), STORYBOARD);
-  process.env.HOME = home;
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
   return { root, home, project };
 }
 

package/dist/skills/media-use/scripts/lib/stats.test.mjs

@@ -11,7 +11,7 @@ function sandbox() {
   const projectDir = join(root, "project");
   mkdirSync(home, { recursive: true });
   mkdirSync(projectDir, { recursive: true });
-  process.env.HOME = home;
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
   return { root, home, projectDir };
 }
 

package/dist/skills/media-use/scripts/lib/telemetry.mjs

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
 
 const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
 const POSTHOG_HOST = "https://us.i.posthog.com";
@@ -72,7 +73,7 @@ function writeSharedConfig(config) {
 // one — otherwise cross-surface continuity would start over on upgrade.
 function legacyMediaAnonId() {
   try {
-    const file = join(homedir(), ".media", "anon-id");
+    const file = join(globalMediaDir(), "anon-id");
     if (existsSync(file)) {
       const id = readFileSync(file, "utf8").trim();
       if (id) return id;

package/dist/skills/media-use/scripts/lib/telemetry.test.mjs

@@ -18,6 +18,7 @@ function sandbox() {
   const home = join(root, "home");
   mkdirSync(home, { recursive: true });
   process.env.HOME = home;
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
   return { root, home };
 }
 

package/dist/skills/registry/localSemantic.js

@@ -21,13 +21,14 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
   rmSync,
   writeFileSync
 } from "fs";
 import { createRequire } from "module";
 import { homedir } from "os";
-import { basename, dirname, join } from "path";
+import { basename, dirname, join, sep } from "path";
 
 // src/utils/npxCommand.ts
 function buildCmdShimCommand(name, args, platform) {
@@ -50,6 +51,8 @@ function optionalPackageDir(name, cacheDir = CACHE_DIR) {
   return join(cacheDir, `${name.replace("/", "__")}@${OPTIONAL_PACKAGES[name]}`);
 }
 async function loadOptionalPackage(name, feature, deps = defaultDeps) {
+  const beside = deps.loadBesideCli(name);
+  if (beside !== null) return beside;
   const dir = optionalPackageDir(name, deps.cacheDir);
   const installed = deps.loadInstalled(dir, name);
   if (installed !== null) return installed;
@@ -81,6 +84,21 @@ function loadInstalled(dir, name) {
   if (!isInstalled(dir, name)) return null;
   return createRequire(join(dir, "package.json"))(name);
 }
+function pinnedCopyBesideCli(name, cliUrl) {
+  const req = createRequire(cliUrl);
+  try {
+    const entry = realpathSync(req.resolve(name));
+    const copy = (req.resolve.paths(name) ?? []).map((dir) => join(dir, name)).find((dir) => existsSync(dir) && entry.startsWith(realpathSync(dir) + sep));
+    if (!copy) return false;
+    const manifest = readFileSync(join(copy, "package.json"), "utf-8");
+    return JSON.parse(manifest).version === OPTIONAL_PACKAGES[name];
+  } catch {
+    return false;
+  }
+}
+function loadBesideCli(name, cliUrl = import.meta.url) {
+  return pinnedCopyBesideCli(name, cliUrl) ? createRequire(cliUrl)(name) : null;
+}
 function runNpm(args) {
   const npm = buildNpmCommand(args);
   const child = spawn(npm.command, npm.args, { stdio: ["ignore", "pipe", "pipe"] });
@@ -149,6 +167,7 @@ async function install(dir, name, version, run = runNpm) {
 }
 var defaultDeps = {
   cacheDir: CACHE_DIR,
+  loadBesideCli: (name) => loadBesideCli(name),
   loadInstalled,
   install,
   log: (line) => console.error(line)