feat(media-use): usage visibility — shared telemetry identity, miss log, resolve --stats (#2113)

* feat(media-use): usage visibility — shared telemetry identity, miss log, resolve --stats - U6: join the CLI/studio telemetry identity — read the shared install id from ~/.hyperframes/config.json (seed if absent) instead of a media-use-only ~/.media/anon-id, and $identify to the HeyGen account (email/username) once per run on sign-in. One PostHog person across surfaces; pseudonymous before sign-in, account-linked after. Event properties stay coarse (no intent/paths). - U1: one-time first-run disclosure to stderr + Privacy section in SKILL.md; honors DO_NOT_TRACK / HYPERFRAMES_NO_TELEMETRY. - U2: persist resolve misses to ~/.media/misses.jsonl (local → intent kept; the media_use_resolve_miss telemetry event stays intent-free). - U3: `resolve --stats` (+ --days) — local usage report over .media/ + ~/.media (volume by type, source/provider/via split, hit-rate, top missed intents, global-cache size/reuse); human + --json. - U4: reproducible PostHog dashboard definition (references/telemetry-dashboard.md). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * fix(media-use): address #2113 review — shared notice state, legacy id migration, stats robustness - Notice-shown state now lives in the shared ~/.hyperframes/config.json (config.telemetryNoticeShown, the CLI's own field) instead of a media-use-only ~/.media marker — so shared-identity users see the first-run notice once per person, not once per tool. - Migrate a pre-existing ~/.media/anon-id into the shared config on upgrade, so media-use-only users keep their PostHog persona instead of resetting. - buildStats: --days only windows on a positive finite value (negative/NaN → all time, not an empty report); dropped the top-level catch that masked a real error as an all-zero "no usage" report (sub-reads are individually guarded). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-09-12 15:20:13 +00:00 · 2026-07-09 18:33:55 -04:00
parent cdb8d736f1
commit 16eb11367a
11 changed files with 948 additions and 43 deletions
@@ -1,11 +1,14 @@
-// Anonymous, opt-out usage tracking for media-use, mirroring the hyperframes CLI
-// telemetry (packages/cli/src/telemetry). Answers "is this actually used, and
-// which capabilities" without any PII: we send the media TYPE, the resolution
-// SOURCE, and the winning PROVIDER: never the intent text, file names, or paths.
+// 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), and
-// $ip:null so no IP is recorded. Fire-and-forget: telemetry never blocks a
+// 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";
@@ -16,6 +19,7 @@ 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;

 /** True when telemetry must NOT be sent (opt-out envs, CI, dev). */
 export function optedOut() {
@@ -28,21 +32,135 @@ export function optedOut() {
  );
 }

-// Stable per-machine anonymous id, persisted in the dir media-use already owns.
-function anonymousId() {
-  const dir = join(homedir(), ".media");
-  const file = join(dir, "anon-id");
+// 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 {
-    if (existsSync(file)) return readFileSync(file, "utf8").trim();
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const id = randomUUID();
-    writeFileSync(file, id);
+    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;
+    return typeof id === "string" && id.trim() ? id.trim() : 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(`${POSTHOG_HOST}/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,
@@ -50,25 +168,16 @@ function anonymousId() {
 */
 export async function track(event, properties = {}) {
  if (optedOut()) return;
-  const body = JSON.stringify({
-    api_key: POSTHOG_API_KEY,
-    batch: [
-      {
-        event,
-        properties: { ...properties, surface: "media-use", $ip: null },
-        distinct_id: anonymousId(),
-        timestamp: new Date().toISOString(),
-      },
-    ],
-  });
-  try {
-    await fetch(`${POSTHOG_HOST}/batch/`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json", Connection: "close" },
-      body,
-      signal: AbortSignal.timeout(TIMEOUT_MS),
-    });
-  } catch {
-    // telemetry is best-effort; never surface into the command
-  }
+  showTelemetryNotice();
+  const anonId = anonymousId();
+  await identifyAccount(anonId);
+  await postEvent(event, properties, anonId);
+}
+
+export function __anonymousIdForTest() {
+  return anonymousId();
+}
+
+export function __resetTelemetryForTest() {
+  identifiedAccount = false;
 }