dsh-hyperframes 0.3.1 → 0.4.0

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

@@ -0,0 +1,85 @@
+// Media downloads use public HTTP(S) URLs. Validate every redirect target;
+// a provider result must meet the same host policy as a direct ingest URL.
+// Public HTTPS-to-HTTP redirects are allowed, matching direct HTTP support.
+// This is a literal-host policy, not DNS pinning: DNS resolution remains trusted.
+
+import { BlockList, isIP } from "node:net";
+
+const blocked = new BlockList();
+for (const [network, prefix] of [
+  ["0.0.0.0", 8],
+  ["10.0.0.0", 8],
+  ["100.64.0.0", 10],
+  ["127.0.0.0", 8],
+  ["169.254.0.0", 16],
+  ["172.16.0.0", 12],
+  ["192.0.0.0", 24],
+  ["192.0.2.0", 24],
+  ["192.88.99.0", 24],
+  ["192.168.0.0", 16],
+  ["198.18.0.0", 15],
+  ["198.51.100.0", 24],
+  ["203.0.113.0", 24],
+  ["224.0.0.0", 4],
+  ["240.0.0.0", 4],
+])
+  blocked.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+  ["::", 128],
+  ["::1", 128],
+  ["fc00::", 7],
+  ["fe80::", 10],
+  ["fec0::", 10],
+  ["ff00::", 8],
+  ["2001:db8::", 32],
+])
+  blocked.addSubnet(network, prefix, "ipv6");
+
+export function isPublicMediaUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+    const host = url.hostname.replace(/\.$/, "");
+    if (
+      host === "localhost" ||
+      host.endsWith(".localhost") ||
+      host.endsWith(".local") ||
+      host.endsWith(".internal")
+    )
+      return false;
+    const address = host.replace(/^\[|\]$/g, "");
+    const family = isIP(address);
+    return family === 0 || !blocked.check(address, family === 4 ? "ipv4" : "ipv6");
+  } catch {
+    return false;
+  }
+}
+
+export async function fetchMedia(url, { method = "GET", signal, fetchImpl = fetch } = {}) {
+  let current = String(url);
+  for (let hop = 0; hop <= 5; hop++) {
+    if (!isPublicMediaUrl(current))
+      throw new Error("Media download blocked: URL is not public HTTP(S)");
+    const response = await fetchImpl(current, { method, signal, redirect: "manual" });
+    if (!(response.status >= 300 && response.status < 400)) return response;
+    const location = response.headers.get("location");
+    if (!location) return response;
+    await response.body?.cancel();
+    current = new URL(location, current).href;
+  }
+  throw new Error("Media download exceeded redirect limit");
+}
+
+// Stream and abort once the cap is crossed, so a lying or chunked body can't buffer past it.
+export async function readCappedBody(res, maxBytes, label) {
+  const declared = Number(res.headers.get("content-length"));
+  if (declared > maxBytes) throw new Error(`${label}: ${declared} bytes exceeds ${maxBytes} cap`);
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of res.body) {
+    total += chunk.length;
+    if (total > maxBytes) throw new Error(`${label}: stream exceeds ${maxBytes} cap`);
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks, total);
+}

package/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/skills/media-use/scripts/lib/npx-sync.mjs

@@ -1,5 +1,18 @@
 import { existsSync } from "node:fs";
-import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
+import { dirname, join } from "node:path";
+
+function resolveNpxCliPath(env, pathExists) {
+  const npmExecPath = env.npm_execpath;
+  const nodeExecPath = env.npm_node_execpath || process.execPath;
+  if (npmExecPath) {
+    const fileName = npmExecPath.replace(/\\/g, "/").split("/").pop()?.toLowerCase();
+    const candidate =
+      fileName === "npx-cli.js" ? npmExecPath : join(dirname(npmExecPath), "npx-cli.js");
+    if (pathExists(candidate)) return candidate;
+  }
+  const besideNode = join(dirname(nodeExecPath), "node_modules", "npm", "bin", "npx-cli.js");
+  return pathExists(besideNode) ? besideNode : null;
+}
 
 // Sync-spawn analog of the audio engine's spawnP, for execFileSync call sites
 // that must hard-fail (rather than fall through to another provider) when npx
@@ -18,7 +31,20 @@ export function resolveNpxInvocation(
   env = process.env,
   pathExists = existsSync,
 ) {
-  const resolved = resolveSpawnCommand("npx", argv, opts, platform, env, pathExists);
+  const resolved =
+    platform !== "win32"
+      ? { cmd: "npx", args: argv, opts: { stdio: "ignore", ...opts } }
+      : (() => {
+          const nodeExecPath = env.npm_node_execpath || process.execPath;
+          const npxCliPath = resolveNpxCliPath(env, pathExists);
+          return npxCliPath
+            ? {
+                cmd: nodeExecPath,
+                args: [npxCliPath, ...argv.map((arg) => String(arg))],
+                opts: { stdio: "ignore", windowsHide: true, ...opts },
+              }
+            : null;
+        })();
   if (!resolved) {
     // npx-on-win32 with no resolvable npx-cli.js — same terminal condition
     // spawnP warns about, surfaced as a throw for callers with no fallback.

package/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/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/skills/media-use/scripts/lib/telemetry.mjs

@@ -1,20 +1,13 @@
-// Opt-out usage tracking for media-use, sharing the hyperframes CLI/studio
-// identity (packages/cli/src/telemetry): the same install id from
-// ~/.hyperframes/config.json, plus a $identify to the HeyGen account on sign-in,
-// so a person is one PostHog profile across surfaces — not a fresh id per tool.
-// Not fully anonymous by design (it must dedupe): pseudonymous before sign-in,
-// account-linked after. Event PROPERTIES stay coarse — media TYPE, resolution
-// SOURCE, winning PROVIDER — never the intent text, file names, or paths.
-//
-// Same public PostHog project key as the CLI (a write-only ingestion key, safe
-// to ship), same opt-outs (DO_NOT_TRACK / HYPERFRAMES_NO_TELEMETRY / CI / dev),
-// and $ip:null so no IP is recorded. Fire-and-forget: telemetry never blocks a
-// resolve and never throws into it.
+// Usage tracking shares the CLI and Studio identity. Properties stay coarse and
+// never carry intent text, file names, or paths.
 
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as fs from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { withFileLock } from "./config-lock.mjs";
+import { globalMediaDir } from "./media-home.mjs";
 
 const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
 const POSTHOG_HOST = "https://us.i.posthog.com";
@@ -22,10 +15,6 @@ const TIMEOUT_MS = 1500;
 let identifiedAccount = false;
 let warnedNonDefaultHost = false;
 
-// Same CI/test signals the test suite itself sets (resolve.test.mjs's U7 test
-// sets NODE_ENV=test and clears CI to prove the interception seam works) —
-// reused here, not a new heuristic, so that deliberate test usage never
-// triggers the warning below.
 function isTestOrCiContext() {
   return (
     process.env.CI === "true" ||
@@ -35,16 +24,6 @@ function isTestOrCiContext() {
   );
 }
 
-// Test-only interception seam: a real HTTP destination a test can point at,
-// so a spawned-child test (resolve.test.mjs) can prove track() never reaches
-// production rather than trusting DO_NOT_TRACK alone (a future call site or
-// test could forget to set that env var). Falls back to the real production
-// host whenever unset — production behavior is unchanged.
-//
-// Safety net: if this ever leaks into a real user's shell, track() would
-// silently redirect to a likely-dead host and postBatch()'s catch{} would
-// swallow the failure with zero signal. Surface one stderr warning outside
-// test/CI contexts so a real user gets some indication instead of silence.
 function posthogHost() {
   const override = process.env.MEDIA_USE_TELEMETRY_HOST;
   if (override && !warnedNonDefaultHost && !isTestOrCiContext()) {
@@ -67,12 +46,7 @@ export function optedOut() {
   );
 }
 
-// CLI + studio share one install identity in ~/.hyperframes/config.json
-// (packages/cli/src/telemetry/config.ts — same path, same `anonymousId` /
-// `telemetryNoticeShown` fields). Read and write that same file so media-use is
-// the same PostHog person and shows the notice once per person, not per tool.
-// Computed per call (not a module const) so it honors HOME at runtime — tests
-// sandbox HOME, and os.homedir() re-reads it each call.
+// Read and write the shared config so media-use keeps one identity per install.
 function sharedConfigPath() {
   return join(homedir(), ".hyperframes", "config.json");
 }
@@ -90,10 +64,24 @@ function readSharedConfig() {
   return {};
 }
 
-function writeSharedConfig(config) {
-  const dir = join(homedir(), ".hyperframes");
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "config.json"), JSON.stringify(config, null, 2) + "\n");
+// Best effort: skipped when the lock cannot be taken or the file cannot be read, never written unlocked.
+function updateSharedConfig(patch) {
+  const file = sharedConfigPath();
+  mkdirSync(dirname(file), { recursive: true });
+  try {
+    withFileLock(`${file}.lock`, fs, () => {
+      let config = {};
+      try {
+        config = JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        if (error.code !== "ENOENT") return;
+      }
+      if (!config || typeof config !== "object" || Array.isArray(config)) return;
+      const tmp = `${file}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify({ ...config, ...patch }, null, 2) + "\n", { mode: 0o600 });
+      renameSync(tmp, file);
+    });
+  } catch {}
 }
 
 // Adopt a pre-existing media-use-only id (~/.media/anon-id from before this
@@ -101,7 +89,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;
@@ -121,7 +109,7 @@ function anonymousId() {
       return config.anonymousId.trim();
     }
     const id = legacyMediaAnonId() || randomUUID();
-    writeSharedConfig({ ...config, anonymousId: id });
+    updateSharedConfig({ anonymousId: id });
     return id;
   } catch {
     return "anon"; // best-effort; a shared bucket is fine if the fs is read-only
@@ -161,7 +149,7 @@ function showTelemetryNotice() {
         "If you sign in to HeyGen, usage links to your account email or username. Opt out with HYPERFRAMES_NO_TELEMETRY=1 or DO_NOT_TRACK=1.",
       ].join("\n"),
     );
-    writeSharedConfig({ ...config, telemetryNoticeShown: true });
+    updateSharedConfig({ telemetryNoticeShown: true });
   } catch {
     // notice is best-effort; never surface into the command
   }

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

@@ -0,0 +1,21 @@
+function round3(n) {
+  return Math.round(Number(n) * 1000) / 1000;
+}
+
+// 30ms in/out ramps kill the click at every concat boundary. A segment shorter
+// than 4x the ramp would spend its whole length fading, so scale down there and
+// skip entirely on a degenerate one. fadeIn/fadeOut are false at the export's
+// own true start/end, where there is no splice to smooth.
+export function fadeFilterFor(durationSeconds, { fadeIn, fadeOut }) {
+  if (!fadeIn && !fadeOut) return null;
+  const FADE_SECONDS = 0.03;
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0.01) return null;
+  const d = Math.min(FADE_SECONDS, durationSeconds / 4);
+  const parts = [];
+  if (fadeIn) parts.push(`afade=t=in:st=0:d=${round3(d)}`);
+  if (fadeOut) {
+    const out = round3(durationSeconds - d);
+    if (out > 0) parts.push(`afade=t=out:st=${out}:d=${round3(d)}`);
+  }
+  return parts.length ? parts.join(",") : null;
+}

package/skills/media-use/scripts/prefs.mjs

@@ -11,7 +11,7 @@
  *     Record one confirmed brief answer into the project tier; the same value
  *     confirmed in two different projects promotes the key to the user tier.
  *
- * Consumption rules live in hyperframes-core/references/brief-contract.md § 2
+ * Consumption rules live in hyperframes/references/brief-contract.md § 2
  * (Remembered defaults): a remembered value becomes the recommended option
  * with a receipt — it never skips a question.
  */

package/skills/media-use/scripts/recipe.mjs

@@ -19,7 +19,7 @@
  *     frame.md over the project's, and print the brief values + skeleton path.
  *
  * When recipes are offered/consumed is the review loop's and the intent
- * layer's business — see hyperframes-core/references/review-loop.md § 4 and
+ * layer's business — see hyperframes/references/review-loop.md § 4 and
  * the intent layer's recipe check (hyperframes SKILL.md § 4).
  */
 import { parseArgs } from "node:util";

package/skills/media-use/scripts/resolve-plugin.test.mjs

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+test(
+  "plugin resolver uses the release CLI without a repository checkout",
+  { skip: process.platform === "win32" },
+  (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-resolve-plugin-"));
+    t.after(() => rmSync(dir, { recursive: true, force: true }));
+    mkdirSync(join(dir, "lib"));
+    for (const file of ["resolve.mjs", "lib/npx-sync.mjs"]) {
+      copyFileSync(fileURLToPath(new URL(file, import.meta.url)), join(dir, file));
+    }
+    writeFileSync(
+      join(dir, "npx"),
+      `#!${process.execPath}\nconsole.log(JSON.stringify({args:process.argv.slice(2),skip:process.env.HYPERFRAMES_SKIP_SKILLS}));process.exit(7);`,
+      { mode: 0o755 },
+    );
+    const result = spawnSync(process.execPath, [join(dir, "resolve.mjs"), "--intent", "a & b"], {
+      cwd: dir,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        PATH: `${dir}${delimiter}${process.env.PATH}`,
+        HYPERFRAMES_PLUGIN_VERSION: "1.2.3",
+        HYPERFRAMES_SKIP_SKILLS: "1",
+      },
+    });
+    assert.equal(result.status, 7, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      args: ["--yes", "hyperframes@1.2.3", "media-use", "resolve", "--intent", "a & b"],
+      skip: "1",
+    });
+  },
+);
+
+test("helper package override keeps a contributor's local CLI", (t) => {
+  const root = mkdtempSync(join(tmpdir(), "hf-resolve-local-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const scripts = join(root, "skills/media-use/scripts");
+  mkdirSync(join(scripts, "lib"), { recursive: true });
+  mkdirSync(join(root, "packages/cli/dist"), { recursive: true });
+  for (const file of ["resolve.mjs", "lib/npx-sync.mjs"]) {
+    copyFileSync(fileURLToPath(new URL(file, import.meta.url)), join(scripts, file));
+  }
+  writeFileSync(join(root, "packages/cli/dist/cli.js"), 'console.log("local-cli");');
+  const result = spawnSync(process.execPath, [join(scripts, "resolve.mjs")], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      HYPERFRAMES_PLUGIN_VERSION: "",
+      HYPERFRAMES_SKILL_PKG_VERSION: "0.8.79",
+    },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout.trim(), "local-cli");
+});