@indigoai-us/hq-cloud 5.19.0 → 5.20.0

package/src/telemetry.test.ts

@@ -0,0 +1,394 @@
+/**
+ * Tests for the usage telemetry collector. Mirrors the Rust test matrix at
+ * `hq-workspace/apps/hq-sync/src-tauri/src/commands/telemetry.rs::tests` so a
+ * behavioral regression in either implementation surfaces in both suites.
+ *
+ * The vault client is stubbed structurally rather than via fetch-mock so the
+ * tests stay deterministic without spinning up wiremock — the production
+ * boundary is `TelemetryClientSurface`, not the HTTP layer.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  collectAndSendTelemetry,
+  sanitizeRow,
+  type CollectTelemetryOptions,
+  type TelemetryClientSurface,
+} from "./telemetry.js";
+import type {
+  TelemetryOptInResponse,
+  UsageBatch,
+  UsageIngestResult,
+} from "./vault-client.js";
+
+// ── Test stubs ────────────────────────────────────────────────────────────────
+
+interface StubClient extends TelemetryClientSurface {
+  /** Every UsageBatch handed to `postUsage`, in arrival order. */
+  posts: UsageBatch[];
+  /** Number of times `getTelemetryOptIn` was called. */
+  optInCalls: number;
+}
+
+function makeClient(opts: {
+  optInResponse?: TelemetryOptInResponse | Error;
+  postResponse?: UsageIngestResult | Error;
+} = {}): StubClient {
+  const optInResponse = opts.optInResponse ?? { enabled: true, updatedAt: null };
+  const postResponse = opts.postResponse ?? { ok: true, written: 0, skipped: [] };
+
+  const posts: UsageBatch[] = [];
+  const stub: StubClient = {
+    posts,
+    optInCalls: 0,
+    async getTelemetryOptIn() {
+      this.optInCalls++;
+      if (optInResponse instanceof Error) throw optInResponse;
+      return optInResponse;
+    },
+    async postUsage(batch: UsageBatch) {
+      posts.push(batch);
+      if (postResponse instanceof Error) throw postResponse;
+      return postResponse;
+    },
+  };
+  return stub;
+}
+
+interface TestEnv {
+  root: string;
+  claudeProjects: string;
+  cursorPath: string;
+  menubarPath: string;
+}
+
+function setupEnv(): TestEnv {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-telemetry-test-"));
+  const claudeProjects = path.join(root, ".claude", "projects");
+  fs.mkdirSync(claudeProjects, { recursive: true });
+  fs.mkdirSync(path.join(root, ".hq"), { recursive: true });
+  return {
+    root,
+    claudeProjects,
+    cursorPath: path.join(root, ".hq", "telemetry-cursor.json"),
+    menubarPath: path.join(root, ".hq", "menubar.json"),
+  };
+}
+
+function teardownEnv(env: TestEnv): void {
+  fs.rmSync(env.root, { recursive: true, force: true });
+}
+
+function writeJsonl(env: TestEnv, sub: string, name: string, lines: string[]): string {
+  const dir = path.join(env.claudeProjects, sub);
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, name);
+  fs.writeFileSync(p, lines.map((l) => `${l}\n`).join(""));
+  return p;
+}
+
+function readCursor(env: TestEnv): { version: string; files: Record<string, { offset: number; mtime: number }> } {
+  return JSON.parse(fs.readFileSync(env.cursorPath, "utf-8"));
+}
+
+function makeOpts(env: TestEnv, client: TelemetryClientSurface): CollectTelemetryOptions {
+  return {
+    client,
+    machineId: "test-machine",
+    installerVersion: "test-version",
+    claudeProjectsRoot: env.claudeProjects,
+    cursorPath: env.cursorPath,
+    menubarPath: env.menubarPath,
+  };
+}
+
+// Representative Claude Code session rows. Mirror the Rust fixtures exactly so
+// drift between implementations is detectable.
+const USER_ROW = JSON.stringify({
+  type: "user",
+  timestamp: "2026-04-25T10:00:00Z",
+  sessionId: "s1",
+  uuid: "u1",
+  parentUuid: null,
+  userType: "human",
+  entrypoint: "cli",
+  cwd: "/Users/x/proj",
+  gitBranch: "main",
+  version: "1.0",
+  message: { role: "user", content: [{ type: "text", text: "hello world" }], id: "msg_1" },
+});
+
+const ASST_ROW = JSON.stringify({
+  type: "assistant",
+  timestamp: "2026-04-25T10:00:01Z",
+  sessionId: "s1",
+  uuid: "u2",
+  parentUuid: "u1",
+  message: {
+    role: "assistant",
+    model: "claude-opus",
+    content: [{ type: "text", text: "hi" }, { type: "thinking", thinking: "hmm" }],
+    stop_sequence: "</end>",
+    usage: { input_tokens: 42, output_tokens: 7, cache_read_input_tokens: 100 },
+    id: "msg_2",
+  },
+  toolUseIds: ["t1"],
+  toolResults: [{ id: "t1", output: "x" }],
+  requestId: "req_1",
+});
+
+// ── sanitizeRow ───────────────────────────────────────────────────────────────
+
+describe("sanitizeRow", () => {
+  it("returns null for non-objects", () => {
+    expect(sanitizeRow(null)).toBeNull();
+    expect(sanitizeRow("string")).toBeNull();
+    expect(sanitizeRow(42)).toBeNull();
+    expect(sanitizeRow([])).toBeNull();
+  });
+
+  it("keeps only top-level allowlist fields", () => {
+    const row = JSON.parse(USER_ROW);
+    const out = sanitizeRow(row);
+    expect(out).not.toBeNull();
+    const keys = new Set(Object.keys(out!));
+    // KEEP: sessionId, timestamp, uuid, cwd, gitBranch, userType
+    for (const expected of ["sessionId", "timestamp", "uuid", "cwd", "gitBranch", "userType"]) {
+      expect(keys.has(expected)).toBe(true);
+    }
+    // Sensitive / unknown fields must be absent:
+    for (const removed of ["type", "parentUuid", "entrypoint", "version", "message", "content", "thinking", "text", "toolUseIds", "toolResults"]) {
+      expect(keys.has(removed)).toBe(false);
+    }
+  });
+
+  it("promotes message.model and flattens message.usage to camelCase", () => {
+    const row = JSON.parse(ASST_ROW);
+    const out = sanitizeRow(row);
+    expect(out).not.toBeNull();
+    expect(out!.model).toBe("claude-opus");
+    expect(out!.inputTokens).toBe(42);
+    expect(out!.outputTokens).toBe(7);
+    expect(out!.cacheReadInputTokens).toBe(100);
+    // cacheCreationInputTokens not present in fixture; must be absent (not 0/null).
+    expect("cacheCreationInputTokens" in out!).toBe(false);
+    // `message` must not survive — its prompt/thinking/tools are exactly what
+    // we're trying to keep off the wire.
+    expect("message" in out!).toBe(false);
+  });
+
+  it("rejects every field outside the server KEEP allowlist", () => {
+    const out = sanitizeRow(JSON.parse(ASST_ROW))!;
+    const allowed = new Set([
+      "sessionId", "timestamp", "uuid", "cwd", "gitBranch", "userType",
+      "model", "inputTokens", "outputTokens",
+      "cacheCreationInputTokens", "cacheReadInputTokens",
+    ]);
+    for (const key of Object.keys(out)) {
+      expect(allowed.has(key), `field "${key}" must be in server allowlist`).toBe(true);
+    }
+  });
+});
+
+// ── collectAndSendTelemetry ───────────────────────────────────────────────────
+
+describe("collectAndSendTelemetry", () => {
+  let env: TestEnv;
+  beforeEach(() => { env = setupEnv(); });
+  afterEach(() => { teardownEnv(env); });
+
+  it("(a) opt-in=false → sends nothing and does not write cursor", async () => {
+    const client = makeClient({ optInResponse: { enabled: false, updatedAt: null } });
+    writeJsonl(env, "proj", "s.jsonl", [USER_ROW, ASST_ROW]);
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(result.enabled).toBe(false);
+    expect(result.optInSource).toBe("server");
+    expect(client.posts).toHaveLength(0);
+    expect(fs.existsSync(env.cursorPath)).toBe(false);
+  });
+
+  it("(b) missing cursor → reads all rows from offset 0, advances to EOF", async () => {
+    const client = makeClient();
+    const jsonlPath = writeJsonl(env, "proj", "s.jsonl", [USER_ROW, ASST_ROW]);
+    const fileSize = fs.statSync(jsonlPath).size;
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(result.enabled).toBe(true);
+    expect(result.eventsSent).toBe(2);
+    expect(client.posts).toHaveLength(1);
+    expect(client.posts[0].events).toHaveLength(2);
+    expect(client.posts[0].machineId).toBe("test-machine");
+    expect(client.posts[0].installerVersion).toBe("test-version");
+
+    const cursor = readCursor(env);
+    expect(cursor.files[jsonlPath].offset).toBe(fileSize);
+  });
+
+  it("(c) sanitizer strips REMOVE fields — only allowlisted fields reach wire", async () => {
+    const client = makeClient();
+    writeJsonl(env, "proj", "full.jsonl", [USER_ROW, ASST_ROW]);
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+    expect(client.posts).toHaveLength(1);
+
+    const allowed = new Set([
+      "sessionId", "timestamp", "uuid", "cwd", "gitBranch", "userType",
+      "model", "inputTokens", "outputTokens",
+      "cacheCreationInputTokens", "cacheReadInputTokens",
+    ]);
+    for (const ev of client.posts[0].events) {
+      for (const key of Object.keys(ev)) {
+        expect(allowed.has(key), `field "${key}" must be in allowlist`).toBe(true);
+      }
+      expect("message" in ev).toBe(false);
+      for (const banned of ["content", "thinking", "text", "toolUseIds", "toolResults"]) {
+        expect(banned in ev).toBe(false);
+      }
+    }
+  });
+
+  it("(d) 1 MiB cap forces ≥2 batches when rows are large", async () => {
+    const client = makeClient();
+    // ~25 KiB per row × 50 rows ≈ 1.25 MiB → ≥2 batches.
+    const longBranch = "x".repeat(25_000);
+    const lines: string[] = [];
+    for (let i = 0; i < 50; i++) {
+      lines.push(JSON.stringify({
+        type: "user",
+        timestamp: `2026-04-25T10:00:${String(i % 60).padStart(2, "0")}Z`,
+        sessionId: "s1",
+        uuid: `u${i}`,
+        cwd: "/Users/x",
+        gitBranch: longBranch,
+        userType: "human",
+        message: { role: "user", content: [{ type: "text", text: "hi" }], id: "m" },
+      }));
+    }
+    writeJsonl(env, "proj", "large.jsonl", lines);
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(result.batchesSent).toBeGreaterThanOrEqual(2);
+    expect(result.eventsSent).toBe(50);
+
+    // Final batch must be < 1 MiB on the wire.
+    const lastWire = Buffer.byteLength(JSON.stringify(client.posts.at(-1)), "utf-8");
+    expect(lastWire).toBeLessThan(1_000_000);
+  });
+
+  it("(e) POST 500 → cursor NOT advanced", async () => {
+    const client = makeClient({ postResponse: new Error("server 500") });
+    writeJsonl(env, "proj", "s.jsonl", [USER_ROW, ASST_ROW, USER_ROW]);
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(result.eventsSent).toBe(0);
+    expect(result.batchesSent).toBe(0);
+    expect(client.posts).toHaveLength(1); // we still tried
+
+    // Cursor file is written (with rotation/empty resets), but the file's
+    // entry must NOT carry a non-zero offset.
+    if (fs.existsSync(env.cursorPath)) {
+      const cursor = readCursor(env);
+      const allOffsets = Object.values(cursor.files).map((e) => e.offset);
+      expect(allOffsets.every((off) => off === 0)).toBe(true);
+    }
+  });
+
+  it("(f) atomic cursor write — no .tmp leftover", async () => {
+    const client = makeClient();
+    writeJsonl(env, "proj", "s.jsonl", [USER_ROW]);
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(fs.existsSync(env.cursorPath)).toBe(true);
+    expect(fs.existsSync(`${env.cursorPath}.tmp`)).toBe(false);
+  });
+
+  it("(g) new file between runs starts at offset 0", async () => {
+    const client = makeClient();
+    writeJsonl(env, "proj-a", "a.jsonl", [USER_ROW]);
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+    const postsAfterRun1 = client.posts.length;
+    expect(postsAfterRun1).toBeGreaterThanOrEqual(1);
+
+    // Add a new fixture between runs.
+    const pathB = writeJsonl(env, "proj-b", "b.jsonl", [ASST_ROW]);
+    await collectAndSendTelemetry(makeOpts(env, client));
+
+    const cursor = readCursor(env);
+    const sizeB = fs.statSync(pathB).size;
+    expect(cursor.files[pathB].offset).toBe(sizeB);
+  });
+
+  it("(h) truncated/rotated file resets cursor to 0", async () => {
+    const client = makeClient();
+    const pathA = writeJsonl(env, "proj", "a.jsonl", [USER_ROW, ASST_ROW, USER_ROW]);
+    const originalSize = fs.statSync(pathA).size;
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+    let cursor = readCursor(env);
+    expect(cursor.files[pathA].offset).toBe(originalSize);
+
+    // Truncate to 0 → next run must detect rotation and reset.
+    fs.truncateSync(pathA, 0);
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+
+    cursor = readCursor(env);
+    expect(cursor.files[pathA].offset).toBe(0);
+  });
+
+  it("(i) opt-in GET fails → falls back to menubar.json (telemetryEnabled=true → runs)", async () => {
+    const client = makeClient({ optInResponse: new Error("server 500") });
+    fs.writeFileSync(env.menubarPath, JSON.stringify({ telemetryEnabled: true }));
+    writeJsonl(env, "proj", "s.jsonl", [USER_ROW]);
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(result.enabled).toBe(true);
+    expect(result.optInSource).toBe("menubar-fallback");
+    expect(client.posts).toHaveLength(1);
+  });
+
+  it("(i') opt-in GET fails AND menubar.json says false → skips", async () => {
+    const client = makeClient({ optInResponse: new Error("server 500") });
+    fs.writeFileSync(env.menubarPath, JSON.stringify({ telemetryEnabled: false }));
+    writeJsonl(env, "proj", "s.jsonl", [USER_ROW]);
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(result.enabled).toBe(false);
+    expect(result.optInSource).toBe("menubar-fallback");
+    expect(client.posts).toHaveLength(0);
+  });
+
+  it("(j) missing claude/projects directory → no crash, no posts", async () => {
+    fs.rmSync(env.claudeProjects, { recursive: true });
+    const client = makeClient();
+
+    const result = await collectAndSendTelemetry(makeOpts(env, client));
+
+    expect(result.enabled).toBe(true);
+    expect(result.filesScanned).toBe(0);
+    expect(client.posts).toHaveLength(0);
+  });
+
+  it("(k) second run with no new content sends nothing", async () => {
+    const client = makeClient();
+    writeJsonl(env, "proj", "s.jsonl", [USER_ROW, ASST_ROW]);
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+    expect(client.posts).toHaveLength(1);
+
+    await collectAndSendTelemetry(makeOpts(env, client));
+    expect(client.posts).toHaveLength(1); // no second POST
+  });
+});