dsh-hyperframes 0.9.0 → 0.9.2

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

@@ -1,5 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import * as fs from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
+import { withFileLock } from "./config-lock.mjs";
 import { globalMediaDir } from "./media-home.mjs";
 
 /**
@@ -15,7 +17,7 @@ import { globalMediaDir } from "./media-home.mjs";
  *   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
+ * Consumption contract (media-use references/memory.md): a remembered
  * value becomes the recommended option with a receipt naming its source — it
  * never skips a question, and explicit request content always wins.
  */
@@ -70,10 +72,25 @@ function readPrefsFile(path) {
 
 /** Atomic write (tmp + rename) so a crash never leaves a torn file. */
 function writePrefsFile(path, file) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`);
+    renameSync(tmp, path);
+  } finally {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {}
+  }
+}
+
+function updatePrefsFile(path, update) {
   mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp`;
-  writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`);
-  renameSync(tmp, path);
+  return withFileLock(`${path}.lock`, fs, () => {
+    const file = readPrefsFile(path);
+    const result = update(file);
+    writePrefsFile(path, file);
+    return result;
+  });
 }
 
 /** `style_preset` entries are stored per workflow as `style_preset.<workflow>`. */
@@ -112,16 +129,18 @@ function dedupe(list) {
  * 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;
+  return updatePrefsFile(projectPrefsPath(projectDir), (file) => {
+    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 };
+    return confirmedIn;
+  });
 }
 
 /**
@@ -129,21 +148,20 @@ function recordProjectTier(projectDir, fullKey, value, projectName, now) {
  * 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;
+  return updatePrefsFile(userPrefsPath(), (file) => {
+    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 };
+    }
+    return promoted;
+  });
 }
 
 /**

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

@@ -14,6 +14,9 @@ import { appendRecord, mediaDir, nextId } from "./manifest.mjs";
 import { regenerateIndex } from "./index-gen.mjs";
 import { mergedPreferences } from "./prefs-store.mjs";
 
+// A filter keeps Node 22 off its native copy, which writes nothing under a non-ASCII path on Windows.
+const NON_ASCII_SAFE_DIR_COPY = { recursive: true, force: true, filter: () => true };
+
 /**
  * Recipes — the heavyweight tier of HyperFrames user memory.
  *
@@ -35,7 +38,7 @@ import { mergedPreferences } from "./prefs-store.mjs";
 const FRONTMATTER_CONTENT_KEYS = new Set(["message", "audience", "mode"]);
 
 /** BRIEF.md frontmatter keys that describe this run, not the reusable type —
- * a recipe never locks the run's shape, so the intent layer always re-asks. */
+ * a recipe never locks the run's shape, so these are always asked again. */
 const BRIEF_CONTENT_KEYS = new Set(["flow", "storyboard", "message", "audience"]);
 
 /** Per-frame metadata that is content, not structure. */
@@ -279,7 +282,8 @@ export function freezeRecipe({ projectDir, name, workflow, blocks }) {
   try {
     const userDir = join(userRecipesDir(), slug);
     mkdirSync(userDir, { recursive: true });
-    cpSync(dir, userDir, { recursive: true, force: true });
+    cpSync(dir, userDir, NON_ASCII_SAFE_DIR_COPY);
+    if (!briefSkeleton) rmSync(join(userDir, "brief-skeleton.md"), { force: true });
   } catch {
     // The project-tier freeze already landed.
   }
@@ -339,7 +343,7 @@ export function useRecipe({ projectDir, name }) {
       );
     }
     mkdirSync(dir, { recursive: true });
-    cpSync(userDir, dir, { recursive: true, force: true });
+    cpSync(userDir, dir, NON_ASCII_SAFE_DIR_COPY);
     const imported = readRecipeJson(dir);
     appendRecord(root, {
       id: nextId(root, "recipe"),

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

@@ -35,9 +35,12 @@ function posthogHost() {
   return override || POSTHOG_HOST;
 }
 
-/** True when telemetry must NOT be sent (opt-out envs, CI, dev). */
+/** True when telemetry must NOT be sent (opt-out envs, CI, dev, shared config). */
 export function optedOut() {
   return (
+    // `hyperframes telemetry disable` writes telemetryEnabled: false to the
+    // shared config; one opt-out must cover the CLI and the media-use scripts.
+    readSharedConfig().telemetryEnabled === false ||
     process.env.HYPERFRAMES_NO_TELEMETRY === "1" ||
     process.env.DO_NOT_TRACK === "1" ||
     process.env.CI === "true" ||

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

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { optedOut } from "./telemetry.mjs";
+
+// optedOut() reads ~/.hyperframes/config.json and env vars. Point HOME at a temp
+// dir so the run never touches the real config, and pin the env opt-outs to a
+// neutral state; restore both afterwards.
+const ENV_KEYS = [
+  "HOME",
+  "USERPROFILE",
+  "HYPERFRAMES_NO_TELEMETRY",
+  "DO_NOT_TRACK",
+  "CI",
+  "NODE_ENV",
+];
+const savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+const home = mkdtempSync(join(tmpdir(), "mu-telemetry-"));
+const configPath = join(home, ".hyperframes", "config.json");
+
+function writeConfig(contents) {
+  if (contents === null) {
+    rmSync(configPath, { force: true });
+  } else {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, contents);
+  }
+}
+
+test.before(() => {
+  for (const key of ENV_KEYS) delete process.env[key];
+  process.env.HOME = process.env.USERPROFILE = home;
+});
+
+test.after(() => {
+  for (const key of ENV_KEYS) {
+    if (savedEnv[key] === undefined) delete process.env[key];
+    else process.env[key] = savedEnv[key];
+  }
+  rmSync(home, { recursive: true, force: true });
+});
+
+test("optedOut is false with no config and no opt-out env", () => {
+  writeConfig(null);
+  assert.equal(optedOut(), false);
+});
+
+test("optedOut honors telemetryEnabled: false from the shared config", () => {
+  writeConfig(JSON.stringify({ telemetryEnabled: false }));
+  assert.equal(optedOut(), true);
+});
+
+test("optedOut is false when the shared config enables telemetry", () => {
+  writeConfig(JSON.stringify({ telemetryEnabled: true }));
+  assert.equal(optedOut(), false);
+});
+
+test("optedOut treats an unreadable shared config as no opt-out", () => {
+  writeConfig("{not json");
+  assert.equal(optedOut(), false);
+});
+
+test("optedOut still honors the env opt-outs", () => {
+  writeConfig(JSON.stringify({ telemetryEnabled: true }));
+  process.env.DO_NOT_TRACK = "1";
+  try {
+    assert.equal(optedOut(), true);
+  } finally {
+    delete process.env.DO_NOT_TRACK;
+  }
+});

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

@@ -14,5 +14,5 @@ export function normalizeWords(input) {
 export function wordListsFromMediaMeta(input) {
   if (Array.isArray(input) || Array.isArray(input?.words)) return [normalizeWords(input)];
   if (!Array.isArray(input?.voices)) return [];
-  return input.voices.map((voice) => normalizeWords(voice)).filter((words) => words.length > 0);
+  return input.voices.map((voice) => normalizeWords(voice));
 }

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

@@ -11,9 +11,8 @@
  *     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/references/brief-contract.md § 2
- * (Remembered defaults): a remembered value becomes the recommended option
- * with a receipt — it never skips a question.
+ * Consumption rule (references/memory.md): a remembered value becomes the
+ * recommended option with a receipt — it never skips a question.
  */
 import { parseArgs } from "node:util";
 import { mergedPreferences, recordPreference } from "./lib/prefs-store.mjs";

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

@@ -18,9 +18,7 @@
  *     Adopt a recipe: import it from the user tier if needed, copy its
  *     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/references/review-loop.md § 4 and
- * the intent layer's recipe check (hyperframes SKILL.md § 4).
+ * When recipes are offered and consumed: references/memory.md.
  */
 import { parseArgs } from "node:util";
 import { freezeRecipe, listRecipes, useRecipe } from "./lib/recipe-store.mjs";

package/skills/media-use/scripts/transcript-cut.mjs

@@ -98,7 +98,10 @@ function run() {
       // with priming silence (~25-35ms for AAC), which concat then bakes in as a
       // gap at each cut -- a defect distinct from, and surviving, the fades
       // below. PCM has no priming, so audio is encoded exactly once, at concat.
-      const ext = args.copy ? extname(outPath) || ".mp4" : isAudioOnly(outPath) ? ".wav" : ".mkv";
+      // The video container is .mov, not .mkv: ffmpeg writes Matroska
+      // timestamps in whole milliseconds, which moves frames off the source's
+      // frame grid, and the concat copy below carries that into the output.
+      const ext = args.copy ? extname(outPath) || ".mp4" : isAudioOnly(outPath) ? ".wav" : ".mov";
       const out = join(tmpDir, `segment-${String(index).padStart(4, "0")}${ext}`);
       // --copy stays fade-free (stream copy cannot filter). A segment's true
       // start/end (index 0's start, the last segment's end) borders nothing
@@ -183,20 +186,27 @@ function cutSegment(inputPath, segment, outPath, copy, fade) {
     "-y",
     "-nostdin",
     "-ss",
-    fmt(segment.start),
+    seekTime(segment.start),
     "-i",
     inputPath,
     "-to",
-    fmt(segment.end - segment.start),
+    seekTime(segment.end - segment.start),
   ];
   if (copy) {
     argv.push("-c", "copy", "-avoid_negative_ts", "make_zero");
-  } else if (extname(outPath).toLowerCase() === ".mkv") {
+  } else if (extname(outPath).toLowerCase() === ".mov") {
     // Concat splices raw segment edges together; without a short ramp the
     // waveform steps discontinuously at every boundary and you hear a click.
     if (fade) argv.push("-af", fade);
     // Video intermediate: keep the picture cheap and the audio uncompressed.
     argv.push("-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-c:a", "pcm_s16le");
+    // A keyframe every second. The renderer seeks into this footage, and x264
+    // on its own leaves up to 250 frames between keyframes.
+    argv.push("-force_key_frames", "expr:gte(t,n_forced)");
+    // Constant frame rate from the first frame. Left to itself, ffmpeg 7 starts
+    // a range that begins between two source frames one frame late, and .mov
+    // rounds that lead-in to the millisecond.
+    argv.push("-fps_mode", "cfr");
   } else {
     if (fade) argv.push("-af", fade);
     argv.push("-c:a", "pcm_s16le");
@@ -265,6 +275,15 @@ function fmt(n) {
     .replace(/\.?0+$/, "");
 }
 
+// -ss/-to name frames, and ffmpeg's accurate seek drops everything before the
+// time it is given: at 30 fps, frame 386 sits at 12.866666 s, and a 3-decimal
+// -ss of 12.867 starts that segment on frame 387 instead, leaving the cut a
+// frame short from the join on. So the values ffmpeg gets keep frame precision,
+// while fmt() above stays at 3 decimals for the times that are only printed.
+function seekTime(n) {
+  return Number(n).toFixed(6);
+}
+
 function round3(n) {
   return Math.round(Number(n) * 1000) / 1000;
 }

package/skills/media-use/scripts/transcript-cut.test.mjs

@@ -47,6 +47,155 @@ function readPcm(filePath) {
   return samples;
 }
 
+// Three kept ranges, none starting or ending on a frame boundary of any rate below.
+const UNALIGNED_KEEP = "0.137-1.913,2.845-4.111,4.9-5.47";
+const UNALIGNED_KEPT_SECONDS = 1.776 + 1.266 + 0.57;
+
+function cutVideo(t, rate, keep = UNALIGNED_KEEP) {
+  const { dir, cleanup } = fixture();
+  t.after(cleanup);
+
+  const source = join(dir, "source.mp4");
+  execFileSync("ffmpeg", [
+    "-y",
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-f",
+    "lavfi",
+    "-i",
+    `testsrc2=size=160x90:rate=${rate}:duration=6`,
+    "-f",
+    "lavfi",
+    "-i",
+    `sine=frequency=440:duration=6:sample_rate=${SAMPLE_RATE}`,
+    "-c:v",
+    "libx264",
+    "-preset",
+    "ultrafast",
+    "-pix_fmt",
+    "yuv420p",
+    "-c:a",
+    "aac",
+    source,
+  ]);
+
+  const transcriptPath = join(dir, "transcript.json");
+  writeFileSync(transcriptPath, JSON.stringify({ words: [{ text: "tone", start: 0, end: 6 }] }));
+
+  const output = join(dir, "out.mp4");
+  const result = run([
+    "--input",
+    source,
+    "--transcript",
+    transcriptPath,
+    "--keep",
+    keep,
+    "--out",
+    output,
+    "--json",
+  ]);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  return output;
+}
+
+function readVideoTimestamps(filePath) {
+  const probe = JSON.parse(
+    execFileSync(
+      "ffprobe",
+      [
+        "-v",
+        "error",
+        "-select_streams",
+        "v:0",
+        "-show_entries",
+        "stream=time_base:packet=pts",
+        "-of",
+        "json",
+        "--",
+        filePath,
+      ],
+      { encoding: "utf8" },
+    ),
+  );
+  const [tickNum, tickDen] = probe.streams[0].time_base.split("/").map(Number);
+  // Packets come in decode order; B-frames put that out of presentation order.
+  const pts = probe.packets.map((packet) => Number(packet.pts)).sort((a, b) => a - b);
+  return { tickNum, tickDen, pts };
+}
+
+for (const rate of ["30", "30000/1001", "60"]) {
+  test(
+    `puts every frame of a ${rate} fps video cut on the frame grid, with no gaps`,
+    { skip: !HAS_FFMPEG },
+    (t) => {
+      const [rateNum, rateDen = 1] = rate.split("/").map(Number);
+      const { tickNum, tickDen, pts } = readVideoTimestamps(cutVideo(t, rate));
+      assert.ok(pts.length > rateNum / rateDen, "expected several seconds of video");
+
+      // Frame i belongs at exactly i / rate seconds. Compared as integers, so a
+      // timestamp rounded to the millisecond (0.067 for 2/30) cannot pass.
+      const offGrid = pts.filter(
+        (value, index) => value * tickNum * rateNum !== index * rateDen * tickDen,
+      );
+      assert.equal(
+        offGrid.length,
+        0,
+        `${offGrid.length} of ${pts.length} frames are off the ${rate} fps grid (timestamps in units of ${tickNum}/${tickDen} s)`,
+      );
+    },
+  );
+}
+
+test(
+  "keeps the keyframes of a video cut no more than a second apart",
+  { skip: !HAS_FFMPEG },
+  (t) => {
+    // One kept range of almost four seconds, so only the encoder decides where keyframes go.
+    const output = cutVideo(t, "30", "0.137-4.111,4.9-5.47");
+    const probe = JSON.parse(
+      execFileSync(
+        "ffprobe",
+        [
+          "-v",
+          "error",
+          "-select_streams",
+          "v:0",
+          "-show_entries",
+          "packet=pts_time,flags",
+          "-of",
+          "json",
+          "--",
+          output,
+        ],
+        { encoding: "utf8" },
+      ),
+    );
+    const keyframes = probe.packets
+      .filter((packet) => packet.flags.startsWith("K"))
+      .map((packet) => Number(packet.pts_time))
+      .sort((a, b) => a - b);
+    const gaps = keyframes.slice(1).map((time, index) => time - keyframes[index]);
+    const widest = Math.max(...gaps);
+    // A frame of slack: the forced keyframe is the first frame at or after each second.
+    assert.ok(widest < 1.05, `keyframes are up to ${widest.toFixed(3)}s apart`);
+  },
+);
+
+test(
+  "does not pad the audio of a video cut with encoder priming at each splice",
+  { skip: !HAS_FFMPEG },
+  (t) => {
+    const seconds = readPcm(cutVideo(t, "30")).length / SAMPLE_RATE;
+    // The single AAC encode may round the end up by a frame or two (23 ms each).
+    // Encoding every segment separately instead adds about 25 ms per splice on top.
+    assert.ok(
+      Math.abs(seconds - UNALIGNED_KEPT_SECONDS) < 0.05,
+      `audio runs ${seconds.toFixed(3)}s for ${UNALIGNED_KEPT_SECONDS.toFixed(3)}s kept`,
+    );
+  },
+);
+
 test(
   "keeps a spliced tone continuous at every cut, with no raw phase jump or silence gap",
   { skip: !HAS_FFMPEG },
@@ -115,3 +264,78 @@ test(
     );
   },
 );
+
+// Frame 32 at 30 fps sits at 1.0666666 s. A -ss rounded to 1.067 lands just past
+// it, so ffmpeg's accurate seek starts that segment on frame 33 and the cut comes
+// out a frame short from the join on.
+const THIRTY_FPS_FRAME_32 = 32 / 30;
+
+test("a kept range starting on a 30 fps frame keeps that frame", { skip: !HAS_FFMPEG }, (t) => {
+  const { dir, cleanup } = fixture();
+  t.after(cleanup);
+
+  const source = join(dir, "src.mp4");
+  execFileSync("ffmpeg", [
+    "-y",
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-f",
+    "lavfi",
+    "-i",
+    "testsrc2=size=320x180:rate=30",
+    "-f",
+    "lavfi",
+    "-i",
+    `sine=frequency=440:sample_rate=${SAMPLE_RATE}`,
+    "-t",
+    "4",
+    "-c:v",
+    "libx264",
+    "-pix_fmt",
+    "yuv420p",
+    "-c:a",
+    "aac",
+    source,
+  ]);
+
+  const transcriptPath = join(dir, "transcript.json");
+  writeFileSync(transcriptPath, JSON.stringify([{ text: "a", start: 0.1, end: 3.9 }]));
+
+  const output = join(dir, "out.mp4");
+  const result = run([
+    "--input",
+    source,
+    "--transcript",
+    transcriptPath,
+    "--keep",
+    `0-1,${THIRTY_FPS_FRAME_32}-3`,
+    "--out",
+    output,
+    "--json",
+  ]);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+
+  // Frames 0-29 for 0-1s, then frames 32-89 for the second segment. Rounding
+  // -ss to the millisecond drops frame 32 and yields 87.
+  const frames = Number(
+    execFileSync(
+      "ffprobe",
+      [
+        "-v",
+        "error",
+        "-select_streams",
+        "v",
+        "-count_packets",
+        "-show_entries",
+        "stream=nb_read_packets",
+        "-of",
+        "csv=p=0",
+        "--",
+        output,
+      ],
+      { encoding: "utf8" },
+    ).trim(),
+  );
+  assert.equal(frames, 88, `expected 88 frames, got ${frames}`);
+});