dsh-hyperframes 0.2.0 → 0.3.0

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

@@ -0,0 +1,117 @@
+import { statSync } from "node:fs";
+import { readGlobalManifest } from "./cache.mjs";
+import { readManifest } from "./manifest.mjs";
+import { readMisses } from "./misses.mjs";
+
+const TOP_MISSES = 5;
+
+function emptyReport() {
+  return {
+    total_resolves: 0,
+    by_type: {},
+    by_source: {},
+    by_provider: {},
+    by_via: {},
+    misses: 0,
+    hit_rate: null,
+    top_missed_intents: {},
+    global_cache_assets: 0,
+    global_cache_disk_bytes: 0,
+    cross_project_reuse: 0,
+  };
+}
+
+function increment(map, key) {
+  if (!key) return;
+  map[key] = (map[key] || 0) + 1;
+}
+
+function timestampOf(record) {
+  return record?.ts || record?.timestamp || record?.created_at || record?.createdAt || null;
+}
+
+function inWindow(record, cutoff) {
+  if (!cutoff) return true;
+  const ts = timestampOf(record);
+  // Older manifest records may not carry a timestamp; keep them in the report
+  // because --days can only window records/misses that carry a ts/timestamp.
+  if (!ts) return true;
+  const time = Date.parse(ts);
+  return Number.isNaN(time) ? true : time >= cutoff;
+}
+
+function sourceOf(record) {
+  return record?._source || record?.source || record?.provenance?.source || "unknown";
+}
+
+function normalizeIntent(intent) {
+  return String(intent ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, " ");
+}
+
+function topMissedIntents(misses) {
+  const grouped = {};
+  for (const miss of misses) {
+    const type = miss?.type || "unknown";
+    const intent = normalizeIntent(miss?.intent);
+    if (!intent) continue;
+    grouped[type] ||= {};
+    grouped[type][intent] = (grouped[type][intent] || 0) + 1;
+  }
+  const out = {};
+  for (const [type, intents] of Object.entries(grouped)) {
+    out[type] = Object.entries(intents)
+      .map(([intent, count]) => ({ intent, count }))
+      .sort((a, b) => b.count - a.count || a.intent.localeCompare(b.intent))
+      .slice(0, TOP_MISSES);
+  }
+  return out;
+}
+
+function diskBytes(records) {
+  let total = 0;
+  for (const record of records) {
+    const p = record?.cached_path || record?.path;
+    if (!p) continue;
+    try {
+      total += statSync(p).size;
+    } catch {
+      // cache entries can outlive files; stats skips missing files
+    }
+  }
+  return total;
+}
+
+export function buildStats({ projectDir, days, now = Date.now() } = {}) {
+  // Only a positive finite --days windows the report; null / NaN / <= 0 mean
+  // "all time" rather than silently excluding everything (a negative cutoff
+  // would land in the future and drop every record). The reads below are each
+  // best-effort (they return [] / skip on IO errors), so there is no top-level
+  // catch masking a real logic bug as an all-zero "no usage" report.
+  const n = Number(days);
+  const cutoff = Number.isFinite(n) && n > 0 ? Number(now) - n * 24 * 60 * 60 * 1000 : null;
+  const records = (projectDir ? readManifest(projectDir) : []).filter((r) => inWindow(r, cutoff));
+  const misses = readMisses().filter((miss) => inWindow(miss, cutoff));
+  const globalRecords = readGlobalManifest();
+  const report = emptyReport();
+
+  report.total_resolves = records.length;
+  report.misses = misses.length;
+  for (const record of records) {
+    increment(report.by_type, record?.type || "unknown");
+    increment(report.by_source, sourceOf(record));
+    increment(report.by_provider, record?.provenance?.provider);
+    increment(report.by_via, record?.provenance?.via);
+  }
+
+  const attempts = report.total_resolves + report.misses;
+  report.hit_rate = attempts === 0 ? null : report.total_resolves / attempts;
+  report.top_missed_intents = topMissedIntents(misses);
+  report.global_cache_assets = globalRecords.length;
+  report.global_cache_disk_bytes = diskBytes(globalRecords);
+  report.cross_project_reuse = globalRecords.filter((r) => r?.provenance?.reused_by).length;
+
+  return report;
+}

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

@@ -0,0 +1,165 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildStats } from "./stats.mjs";
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-stats-"));
+  const home = join(root, "home");
+  const projectDir = join(root, "project");
+  mkdirSync(home, { recursive: true });
+  mkdirSync(projectDir, { recursive: true });
+  process.env.HOME = home;
+  return { root, home, projectDir };
+}
+
+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 seedManifest(dir, records) {
+  mkdirSync(join(dir, ".media"), { recursive: true });
+  writeFileSync(
+    join(dir, ".media/manifest.jsonl"),
+    records.map((record) => JSON.stringify(record)).join("\n") + "\n",
+  );
+}
+
+function isoDaysAgo(days) {
+  return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+}
+
+test("buildStats aggregates resolves, misses, providers, sources, and reuse", () => {
+  const savedEnv = { ...process.env };
+  const { root, home, projectDir } = sandbox();
+  try {
+    seedManifest(projectDir, [
+      {
+        id: "bgm_001",
+        type: "bgm",
+        source: "search",
+        ts: isoDaysAgo(0),
+        provenance: { provider: "heygen.audio.sounds", prompt: "upbeat", via: "url" },
+      },
+      {
+        id: "image_001",
+        type: "image",
+        _source: "reused-explicit",
+        timestamp: isoDaysAgo(0),
+        provenance: { provider: "local", reused_by: "agent" },
+      },
+      {
+        id: "bgm_002",
+        type: "bgm",
+        source: "generated",
+        provenance: { provider: "codex" },
+      },
+    ]);
+    const cachedFile = join(home, ".media/mu-v1-cache/asset.wav");
+    mkdirSync(join(cachedFile, ".."), { recursive: true });
+    writeFileSync(cachedFile, "12345");
+    seedManifest(home, [
+      {
+        id: "bgm_009",
+        type: "bgm",
+        reusable: true,
+        cached_path: cachedFile,
+        provenance: { provider: "heygen.audio.sounds", reused_by: "agent" },
+      },
+    ]);
+    writeFileSync(
+      join(home, ".media/misses.jsonl"),
+      JSON.stringify({
+        ts: isoDaysAgo(0),
+        type: "bgm",
+        intent: "dark cinematic riser",
+      }) + "\n",
+      { flag: "a" },
+    );
+
+    const stats = buildStats({ projectDir });
+    assert.equal(stats.total_resolves, 3);
+    assert.deepEqual(stats.by_type, { bgm: 2, image: 1 });
+    assert.deepEqual(stats.by_source, { search: 1, "reused-explicit": 1, generated: 1 });
+    assert.equal(stats.by_provider["heygen.audio.sounds"], 1);
+    assert.equal(stats.by_via.url, 1);
+    assert.equal(stats.misses, 1);
+    assert.equal(stats.hit_rate, 0.75);
+    assert.deepEqual(stats.top_missed_intents.bgm[0], {
+      intent: "dark cinematic riser",
+      count: 1,
+    });
+    assert.equal(stats.global_cache_assets, 1);
+    assert.equal(stats.global_cache_disk_bytes, 5);
+    assert.equal(stats.cross_project_reuse, 1);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("buildStats returns a zeroed report when nothing exists", () => {
+  const savedEnv = { ...process.env };
+  const { root, projectDir } = sandbox();
+  try {
+    const stats = buildStats({ projectDir });
+    assert.equal(stats.total_resolves, 0);
+    assert.deepEqual(stats.by_type, {});
+    assert.deepEqual(stats.by_source, {});
+    assert.deepEqual(stats.by_provider, {});
+    assert.deepEqual(stats.by_via, {});
+    assert.equal(stats.misses, 0);
+    assert.equal(stats.hit_rate, null);
+    assert.deepEqual(stats.top_missed_intents, {});
+    assert.equal(stats.global_cache_assets, 0);
+    assert.equal(stats.global_cache_disk_bytes, 0);
+    assert.equal(stats.cross_project_reuse, 0);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("buildStats returns JSON-safe output", () => {
+  const savedEnv = { ...process.env };
+  const { root, projectDir } = sandbox();
+  try {
+    const stats = buildStats({ projectDir });
+    assert.deepEqual(JSON.parse(JSON.stringify(stats)), stats);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("buildStats applies days window to timestamped records and misses", () => {
+  const savedEnv = { ...process.env };
+  const { root, home, projectDir } = sandbox();
+  try {
+    seedManifest(projectDir, [
+      { id: "bgm_old", type: "bgm", ts: isoDaysAgo(100), provenance: { provider: "old" } },
+      { id: "bgm_new", type: "bgm", ts: isoDaysAgo(1), provenance: { provider: "new" } },
+      { id: "image_untimed", type: "image", provenance: { provider: "none" } },
+    ]);
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(
+      join(home, ".media/misses.jsonl"),
+      [
+        JSON.stringify({ ts: isoDaysAgo(100), type: "bgm", intent: "old miss" }),
+        JSON.stringify({ ts: isoDaysAgo(1), type: "bgm", intent: "new miss" }),
+      ].join("\n"),
+    );
+
+    const stats = buildStats({ projectDir, days: 7 });
+    assert.equal(stats.total_resolves, 2);
+    assert.deepEqual(stats.by_type, { bgm: 1, image: 1 });
+    assert.equal(stats.misses, 1);
+    assert.equal(stats.top_missed_intents.bgm[0].intent, "new miss");
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,222 @@
+// 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.
+
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
+const POSTHOG_HOST = "https://us.i.posthog.com";
+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" ||
+    process.env.CI === "1" ||
+    process.env.NODE_ENV === "test" ||
+    process.env.NODE_ENV === "development"
+  );
+}
+
+// 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()) {
+    warnedNonDefaultHost = true;
+    console.error(
+      `media-use: telemetry is redirected to a non-default host via MEDIA_USE_TELEMETRY_HOST (${override}) — unset it unless this is intentional.`,
+    );
+  }
+  return override || POSTHOG_HOST;
+}
+
+/** True when telemetry must NOT be sent (opt-out envs, CI, dev). */
+export function optedOut() {
+  return (
+    process.env.HYPERFRAMES_NO_TELEMETRY === "1" ||
+    process.env.DO_NOT_TRACK === "1" ||
+    process.env.CI === "true" ||
+    process.env.CI === "1" ||
+    process.env.NODE_ENV === "development"
+  );
+}
+
+// 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.
+function sharedConfigPath() {
+  return join(homedir(), ".hyperframes", "config.json");
+}
+
+function readSharedConfig() {
+  try {
+    const file = sharedConfigPath();
+    if (existsSync(file)) {
+      const parsed = JSON.parse(readFileSync(file, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    }
+  } catch {
+    // unreadable config → treat as empty; never throw
+  }
+  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");
+}
+
+// Adopt a pre-existing media-use-only id (~/.media/anon-id from before this
+// change) so upgraders keep their PostHog persona instead of resetting to a new
+// one — otherwise cross-surface continuity would start over on upgrade.
+function legacyMediaAnonId() {
+  try {
+    const file = join(homedir(), ".media", "anon-id");
+    if (existsSync(file)) {
+      const id = readFileSync(file, "utf8").trim();
+      if (id) return id;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+// Stable per-machine id from the shared config; seeds it (adopting a legacy
+// media-use id when present) if absent.
+function anonymousId() {
+  try {
+    const config = readSharedConfig();
+    if (typeof config.anonymousId === "string" && config.anonymousId.trim()) {
+      return config.anonymousId.trim();
+    }
+    const id = legacyMediaAnonId() || randomUUID();
+    writeSharedConfig({ ...config, anonymousId: id });
+    return id;
+  } catch {
+    return "anon"; // best-effort; a shared bucket is fine if the fs is read-only
+  }
+}
+
+function heygenAccountDistinctId() {
+  const file = join(process.env.HEYGEN_CONFIG_DIR || join(homedir(), ".heygen"), "credentials");
+  try {
+    if (!existsSync(file)) return null;
+    const raw = readFileSync(file, "utf8").trim();
+    if (!raw.startsWith("{")) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const user = parsed.user;
+    if (!user || typeof user !== "object" || Array.isArray(user)) return null;
+    const id = typeof user.email === "string" && user.email.trim() ? user.email : user.username;
+    // Lowercased so this joins with the CLI's own identify call regardless of
+    // the account's stored email casing — two different-case distinct ids
+    // would otherwise split one person across two PostHog profiles.
+    return typeof id === "string" && id.trim() ? id.trim().toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
+function showTelemetryNotice() {
+  if (optedOut()) return;
+  try {
+    const config = readSharedConfig();
+    // Shared with the CLI (config.telemetryNoticeShown): shown once per person
+    // across surfaces, not once per tool.
+    if (config.telemetryNoticeShown === true) return;
+    console.error(
+      [
+        "media-use sends usage telemetry: media type, resolution source, and provider; never intent text, file names, or paths.",
+        "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 });
+  } catch {
+    // notice is best-effort; never surface into the command
+  }
+}
+
+async function postBatch(batch) {
+  try {
+    await fetch(`${posthogHost()}/batch/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Connection: "close" },
+      body: JSON.stringify({ api_key: POSTHOG_API_KEY, batch }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch {
+    // telemetry is best-effort; never surface into the command
+  }
+}
+
+async function postEvent(event, properties, distinctId) {
+  await postBatch([
+    {
+      event,
+      properties: { ...properties, surface: "media-use", $ip: null },
+      distinct_id: distinctId,
+      timestamp: new Date().toISOString(),
+    },
+  ]);
+}
+
+async function identifyAccount(anonId) {
+  if (optedOut() || identifiedAccount) return;
+  const distinctId = heygenAccountDistinctId();
+  if (!distinctId) return;
+  identifiedAccount = true;
+  await postEvent("$identify", { $anon_distinct_id: anonId }, distinctId);
+}
+
+/**
+ * Fire-and-forget a single event to PostHog. Best-effort: awaited with a short
+ * timeout so a short-lived script flushes before exit, but any failure (offline,
+ * opted out) is swallowed. `properties` must be non-PII (no intent/paths).
+ */
+export async function track(event, properties = {}) {
+  if (optedOut()) return;
+  showTelemetryNotice();
+  const anonId = anonymousId();
+  await identifyAccount(anonId);
+  await postEvent(event, properties, anonId);
+}
+
+export function __anonymousIdForTest() {
+  return anonymousId();
+}
+
+export function __resetTelemetryForTest() {
+  identifiedAccount = false;
+  warnedNonDefaultHost = false;
+}