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 23:29:50 +00:00 · 2026-07-09 18:33:55 -04:00
parent cdb8d736f1
commit 16eb11367a
11 changed files with 948 additions and 43 deletions
@@ -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;
+}