hyperframes 0.8.57 → 0.8.59

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

@@ -0,0 +1,44 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mergeTokensToWords } from "./parakeet-words.mjs";
+
+test("mergeTokensToWords joins sub-word tokens on the space boundary", () => {
+  const parakeet = {
+    text: "Hello everyone. Um,",
+    sentences: [
+      {
+        tokens: [
+          { text: " H", start: 0.0, end: 0.24 },
+          { text: "ello", start: 0.24, end: 0.48 },
+          { text: " everyone.", start: 0.48, end: 1.28 },
+          { text: " Um,", start: 1.28, end: 1.92 },
+        ],
+      },
+    ],
+  };
+  const { words } = mergeTokensToWords(parakeet);
+  assert.deepEqual(words, [
+    { text: "Hello", start: 0.0, end: 0.48 },
+    { text: "everyone.", start: 0.48, end: 1.28 },
+    { text: "Um,", start: 1.28, end: 1.92 },
+  ]);
+});
+
+test("mergeTokensToWords spans multiple sentences and drops empties", () => {
+  const parakeet = {
+    text: "Hi there",
+    sentences: [
+      { tokens: [{ text: "Hi", start: 0, end: 0.2 }] },
+      { tokens: [{ text: " there", start: 0.5, end: 0.9 }] },
+    ],
+  };
+  const { words } = mergeTokensToWords(parakeet);
+  assert.equal(words.length, 2);
+  assert.equal(words[1].text, "there");
+  assert.equal(words[1].start, 0.5);
+});
+
+test("mergeTokensToWords tolerates missing sentences/tokens", () => {
+  assert.deepEqual(mergeTokensToWords({}).words, []);
+  assert.deepEqual(mergeTokensToWords({ sentences: [{}] }).words, []);
+});

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

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+/**
+ * Remembered defaults — the lightweight tier of HyperFrames user memory.
+ *
+ * Two files, same shape as the rest of media-use's storage split:
+ * - project `.media/preferences.json` — committed with the repo, so the whole
+ *   team inherits it; written every time a brief answer is confirmed.
+ * - user `~/.media/preferences.json` — personal, cross-repo. A key is promoted
+ *   here only once the same value has been confirmed in two different projects
+ *   (`PROMOTE_AT`), so a one-off choice never pollutes the global defaults.
+ *   Pre-promotion evidence accumulates in the user file's `sightings` ledger —
+ *   project files can't see each other, so the cross-project count has to live
+ *   user-side.
+ *
+ * Consumption contract (brief-contract § 2, Remembered defaults): a remembered
+ * value becomes the recommended option with a receipt naming its source — it
+ * never skips a question, and explicit request content always wins.
+ */
+
+const PREFS_FILE = "preferences.json";
+
+/** Keys the brief contract records; `style_preset` is stored per workflow. */
+export const PREFERENCE_KEYS = [
+  "destination",
+  "aspect",
+  "language",
+  "flow",
+  "storyboard",
+  "voice",
+  "style_preset",
+];
+
+/** A value must be confirmed in this many distinct projects to go user-tier. */
+export const PROMOTE_AT = 2;
+
+export function projectPrefsPath(projectDir) {
+  return join(resolve(projectDir), ".media", PREFS_FILE);
+}
+
+export function userPrefsPath() {
+  return join(homedir(), ".media", PREFS_FILE);
+}
+
+function emptyFile() {
+  return { version: 1, preferences: {}, sightings: {} };
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Tolerant read — a missing or malformed file counts as empty. */
+function readPrefsFile(path) {
+  try {
+    if (!existsSync(path)) return emptyFile();
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!isRecord(parsed)) return emptyFile();
+    return {
+      version: 1,
+      preferences: isRecord(parsed.preferences) ? parsed.preferences : {},
+      sightings: isRecord(parsed.sightings) ? parsed.sightings : {},
+    };
+  } catch {
+    return emptyFile();
+  }
+}
+
+/** Atomic write (tmp + rename) so a crash never leaves a torn file. */
+function writePrefsFile(path, file) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/** `style_preset` entries are stored per workflow as `style_preset.<workflow>`. */
+export function preferenceKeyFor(key, workflow) {
+  return key === "style_preset" && workflow ? `style_preset.${workflow}` : key;
+}
+
+function validEntry(entry) {
+  return isRecord(entry) && typeof entry.value === "string" && entry.value.length > 0;
+}
+
+/**
+ * The merged view the brief reads: user-tier promoted entries first, project
+ * entries on top (project wins). Each entry carries `source` plus the receipt
+ * material (`confirmed_in`, `updated_at`).
+ */
+export function mergedPreferences(projectDir) {
+  const user = readPrefsFile(userPrefsPath());
+  const project = readPrefsFile(projectPrefsPath(projectDir));
+  const merged = {};
+  for (const [key, entry] of Object.entries(user.preferences)) {
+    if (validEntry(entry)) merged[key] = { ...entry, source: "user" };
+  }
+  for (const [key, entry] of Object.entries(project.preferences)) {
+    if (validEntry(entry)) merged[key] = { ...entry, source: "project" };
+  }
+  return merged;
+}
+
+function dedupe(list) {
+  return [...new Set(list)];
+}
+
+/**
+ * Project tier: same value accumulates confirmations; a changed value starts
+ * provenance over (the old confirmations vouched for the old value).
+ */
+function recordProjectTier(projectDir, fullKey, value, projectName, now) {
+  const path = projectPrefsPath(projectDir);
+  const file = readPrefsFile(path);
+  const previous = file.preferences[fullKey];
+  const keepProvenance = validEntry(previous) && previous.value === value;
+  const confirmedIn = keepProvenance
+    ? dedupe([...(Array.isArray(previous.confirmed_in) ? previous.confirmed_in : []), projectName])
+    : [projectName];
+  file.preferences[fullKey] = { value, confirmed_in: confirmedIn, updated_at: now };
+  writePrefsFile(path, file);
+  return confirmedIn;
+}
+
+/**
+ * User tier: accumulate this sighting in the ledger, and promote the key once
+ * the same value has been confirmed in PROMOTE_AT distinct projects.
+ */
+function recordUserSighting(fullKey, value, projectName, now) {
+  const path = userPrefsPath();
+  const file = readPrefsFile(path);
+  const keySightings = isRecord(file.sightings[fullKey]) ? file.sightings[fullKey] : {};
+  const seenIn = dedupe([
+    ...(Array.isArray(keySightings[value]) ? keySightings[value] : []),
+    projectName,
+  ]);
+  keySightings[value] = seenIn;
+  file.sightings[fullKey] = keySightings;
+  const promoted = seenIn.length >= PROMOTE_AT;
+  if (promoted) {
+    file.preferences[fullKey] = { value, confirmed_in: seenIn, updated_at: now };
+  }
+  writePrefsFile(path, file);
+  return promoted;
+}
+
+/**
+ * Record one confirmed brief answer. Always writes the project tier; feeds the
+ * user tier's sightings ledger and promotes once the same value has been
+ * confirmed in PROMOTE_AT distinct projects. Idempotent per project.
+ */
+export function recordPreference({ projectDir, key, value, workflow }) {
+  if (!PREFERENCE_KEYS.includes(key)) {
+    throw new Error(`unknown preference key: "${key}" (known: ${PREFERENCE_KEYS.join(", ")})`);
+  }
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("a preference needs a non-empty string value");
+  }
+  if (key === "style_preset" && (!workflow || !String(workflow).trim())) {
+    throw new Error("style_preset is stored per workflow — pass --workflow <w>");
+  }
+  const fullKey = preferenceKeyFor(key, workflow);
+  const projectName = basename(resolve(projectDir));
+  const trimmed = value.trim();
+  const now = new Date().toISOString();
+
+  const confirmedIn = recordProjectTier(projectDir, fullKey, trimmed, projectName, now);
+
+  // Best-effort — a read-only home directory must never fail a brief.
+  let promoted = false;
+  try {
+    promoted = recordUserSighting(fullKey, trimmed, projectName, now);
+  } catch {
+    // The project record already landed; promotion just waits for next time.
+  }
+
+  return { key: fullKey, value: trimmed, confirmed_in: confirmedIn, promoted };
+}

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

@@ -0,0 +1,189 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  mergedPreferences,
+  preferenceKeyFor,
+  projectPrefsPath,
+  recordPreference,
+  userPrefsPath,
+} from "./prefs-store.mjs";
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-prefs-"));
+  const home = join(root, "home");
+  const projectA = join(root, "proj-a");
+  const projectB = join(root, "proj-b");
+  mkdirSync(home, { recursive: true });
+  mkdirSync(projectA, { recursive: true });
+  mkdirSync(projectB, { recursive: true });
+  process.env.HOME = home;
+  return { root, home, projectA, projectB };
+}
+
+function restoreEnv(saved) {
+  for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+  Object.assign(process.env, saved);
+}
+
+function withSandbox(fn) {
+  const savedEnv = { ...process.env };
+  const box = sandbox();
+  try {
+    fn(box);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(box.root, { recursive: true, force: true });
+  }
+}
+
+test("record writes the project tier and get merges it as source=project", () => {
+  withSandbox(({ projectA }) => {
+    const result = recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    assert.equal(result.promoted, false);
+    assert.deepEqual(result.confirmed_in, ["proj-a"]);
+
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.destination.value, "x-feed");
+    assert.equal(merged.destination.source, "project");
+
+    const onDisk = JSON.parse(readFileSync(projectPrefsPath(projectA), "utf8"));
+    assert.equal(onDisk.preferences.destination.value, "x-feed");
+  });
+});
+
+test("one project never promotes: a fresh project sees nothing user-tier", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    // proj-b has no project entry, and the value was only confirmed once.
+    assert.equal(mergedPreferences(projectB).destination, undefined);
+  });
+});
+
+test("the same value confirmed in two projects promotes to the user tier", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    const second = recordPreference({ projectDir: projectB, key: "destination", value: "x-feed" });
+    assert.equal(second.promoted, true);
+
+    const userFile = JSON.parse(readFileSync(userPrefsPath(), "utf8"));
+    assert.deepEqual(userFile.preferences.destination.confirmed_in.sort(), ["proj-a", "proj-b"]);
+
+    // A third project with no local entry now inherits the promoted default.
+    const projectC = join(projectA, "..", "proj-c");
+    mkdirSync(projectC, { recursive: true });
+    const merged = mergedPreferences(projectC);
+    assert.equal(merged.destination.value, "x-feed");
+    assert.equal(merged.destination.source, "user");
+  });
+});
+
+test("record is idempotent per project — confirmed_in stays deduped", () => {
+  withSandbox(({ projectA }) => {
+    recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    const again = recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    assert.deepEqual(again.confirmed_in, ["proj-a"]);
+    assert.equal(again.promoted, false);
+  });
+});
+
+test("a changed value restarts provenance instead of inheriting confirmations", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "destination", value: "x-feed" });
+    recordPreference({ projectDir: projectB, key: "destination", value: "x-feed" });
+    const switched = recordPreference({
+      projectDir: projectA,
+      key: "destination",
+      value: "youtube",
+    });
+    assert.deepEqual(switched.confirmed_in, ["proj-a"]);
+    assert.equal(switched.promoted, false);
+    // The previously promoted value keeps serving other projects until youtube
+    // earns its own two confirmations.
+    const userFile = JSON.parse(readFileSync(userPrefsPath(), "utf8"));
+    assert.equal(userFile.preferences.destination.value, "x-feed");
+  });
+});
+
+test("project tier overrides a promoted user-tier value", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "yes" });
+    recordPreference({ projectDir: projectB, key: "storyboard", value: "yes" });
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "no" });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.storyboard.value, "no");
+    assert.equal(merged.storyboard.source, "project");
+  });
+});
+
+test("the retired mode key is rejected", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(
+      () => recordPreference({ projectDir: projectA, key: "mode", value: "collaborative" }),
+      /unknown preference key/,
+    );
+  });
+});
+
+test("the run-shape keys record and promote like any field", () => {
+  withSandbox(({ projectA, projectB }) => {
+    recordPreference({ projectDir: projectA, key: "flow", value: "automation" });
+    const promoted = recordPreference({ projectDir: projectB, key: "flow", value: "automation" });
+    assert.equal(promoted.promoted, true);
+    recordPreference({ projectDir: projectA, key: "storyboard", value: "yes" });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged.flow.value, "automation");
+    assert.equal(merged.storyboard.value, "yes");
+    assert.equal(merged.storyboard.source, "project");
+  });
+});
+
+test("style_preset is keyed per workflow", () => {
+  withSandbox(({ projectA }) => {
+    assert.equal(
+      preferenceKeyFor("style_preset", "faceless-explainer"),
+      "style_preset.faceless-explainer",
+    );
+    assert.equal(preferenceKeyFor("destination", "faceless-explainer"), "destination");
+    recordPreference({
+      projectDir: projectA,
+      key: "style_preset",
+      value: "pin-and-paper",
+      workflow: "faceless-explainer",
+    });
+    const merged = mergedPreferences(projectA);
+    assert.equal(merged["style_preset.faceless-explainer"].value, "pin-and-paper");
+    assert.equal(merged["style_preset"], undefined);
+  });
+});
+
+test("style_preset without a workflow is rejected, never stored bare", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(
+      () => recordPreference({ projectDir: projectA, key: "style_preset", value: "pin-and-paper" }),
+      /pass --workflow/,
+    );
+    assert.deepEqual(mergedPreferences(projectA), {});
+  });
+});
+
+test("unknown keys and empty values are rejected", () => {
+  withSandbox(({ projectA }) => {
+    assert.throws(() => recordPreference({ projectDir: projectA, key: "vibe", value: "x" }));
+    assert.throws(() => recordPreference({ projectDir: projectA, key: "voice", value: "  " }));
+  });
+});
+
+test("corrupt files are treated as empty instead of crashing", () => {
+  withSandbox(({ projectA, home }) => {
+    mkdirSync(join(projectA, ".media"), { recursive: true });
+    writeFileSync(projectPrefsPath(projectA), "not json");
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(userPrefsPath(), '{"preferences": 42}');
+    assert.deepEqual(mergedPreferences(projectA), {});
+    const result = recordPreference({ projectDir: projectA, key: "language", value: "zh" });
+    assert.equal(result.value, "zh");
+  });
+});

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

@@ -0,0 +1,39 @@
+import { execFileSync } from "node:child_process";
+import { extname } from "node:path";
+
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".ico"]);
+
+export function probe(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === ".svg") return { width: null, height: null, duration: null, codec: "svg" };
+
+  try {
+    // execFileSync (no shell) so a hostile filename like `"; rm -rf ~; ".png`
+    // can't break out of the quoting — filePath is passed as a literal argv entry.
+    const raw = execFileSync(
+      "ffprobe",
+      ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", "--", filePath],
+      { encoding: "utf8", timeout: 5000 },
+    );
+    const info = JSON.parse(raw);
+    const stream = info.streams?.[0];
+    const format = info.format;
+
+    const isImage = IMAGE_EXT.has(ext);
+    const duration = isImage
+      ? null
+      : parseFloat(format?.duration) || parseFloat(stream?.duration) || null;
+    const width = parseInt(stream?.width, 10) || null;
+    const height = parseInt(stream?.height, 10) || null;
+    const codec = stream?.codec_name || null;
+
+    return {
+      duration: duration != null ? Math.round(duration * 10) / 10 : null,
+      width,
+      height,
+      codec,
+    };
+  } catch {
+    return { duration: null, width: null, height: null, codec: null };
+  }
+}

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

@@ -0,0 +1,31 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { probe } from "./probe.mjs";
+
+// Regression for the shell-injection fix: probe() must pass the path as a literal
+// argv entry, never through a shell. A filename containing shell metacharacters
+// must NOT execute. Under the old execSync(`ffprobe ... "${path}"`) the embedded
+// `touch` ran and created the marker; under execFileSync it cannot, regardless of
+// whether ffprobe is installed (the injected command never reaches a shell).
+test("probe does not execute shell metacharacters in a filename", () => {
+  const dir = mkdtempSync(join(tmpdir(), "probe-inject-"));
+  const marker = join(dir, "INJECTED");
+  // Slash-free basename (a real on-disk filename) that breaks out of the old
+  // double-quoted interpolation and would `touch INJECTED` in the cwd.
+  const evil = join(dir, `clip"; touch INJECTED; echo ".mp4`);
+  const prevCwd = process.cwd();
+  try {
+    writeFileSync(evil, "not real media");
+    process.chdir(dir); // so a leaked `touch INJECTED` would land next to `marker`
+    const meta = probe(evil);
+    assert.equal(existsSync(marker), false, "injected `touch` must not have run");
+    // Bogus/unreadable media still returns the null-shaped result, never throws.
+    assert.deepEqual(Object.keys(meta).sort(), ["codec", "duration", "height", "width"]);
+  } finally {
+    process.chdir(prevCwd);
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,5 @@
+// Back-compat surface for the v1 provider API. The ordered, capability-based
+// registry now lives in registry.mjs; this re-exports the v1 helpers so existing
+// callers keep working. New code should import from registry.mjs directly
+// (getProviders / runCapability).
+export { getProvider, listTypes } from "./registry.mjs";