@indigoai-us/hq-cloud 5.19.0 → 5.20.0

package/src/bin/sync-runner.ts

@@ -83,6 +83,7 @@ import { share as defaultShare } from "../cli/share.js";
 import type { ShareOptions, ShareResult } from "../cli/share.js";
 import type { ConflictStrategy } from "../cli/conflict.js";
 import type { UploadAuthor } from "../s3.js";
+import { collectAndSendTelemetry } from "../telemetry.js";
 
 /**
  * Sync direction for a run.
@@ -278,6 +279,15 @@ export interface RunnerDeps {
   sync?: (options: SyncOptions) => Promise<SyncResult>;
   /** Share function (push phase). Defaults to `cli/share.share`. */
   share?: (options: ShareOptions) => Promise<ShareResult>;
+  /**
+   * Telemetry collector — runs just before the `all-complete` emit. Default
+   * implementation calls `collectAndSendTelemetry` from `../telemetry.js`
+   * using the real VaultClient; tests that inject `createVaultClient` are
+   * implicitly opted out (the default skips when the client isn't a real
+   * `VaultClient`). Tests that want to assert telemetry behavior should pass
+   * an explicit stub here.
+   */
+  collectTelemetry?: () => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -445,6 +455,55 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs };
 }
 
+// ---------------------------------------------------------------------------
+// Telemetry default — closes over the runner's vault client. Skipped when
+// the caller injected a `createVaultClient` stub, because we have no
+// guarantee the stub implements `getTelemetryOptIn` / `postUsage`. The real
+// `VaultClient` from `../vault-client.js` always does. All errors are
+// swallowed — telemetry must never abort or delay sync.
+// ---------------------------------------------------------------------------
+
+async function defaultCollectTelemetry(
+  client: VaultClientSurface,
+  clientIsStub: boolean,
+): Promise<void> {
+  if (clientIsStub) return;
+  try {
+    // machineId: prefer ~/.hq/menubar.json (set by the menubar app on first
+    // launch). When absent — e.g. fresh CLI-only install — fall back to a
+    // value that makes the row identifiable as "unattributed" rather than
+    // crashing or spoofing another machine's id.
+    const menubarPath = path.join(os.homedir(), ".hq", "menubar.json");
+    let machineId = "unknown";
+    try {
+      const raw = await fs.promises.readFile(menubarPath, "utf-8");
+      const parsed = JSON.parse(raw) as { machineId?: unknown };
+      if (typeof parsed.machineId === "string" && parsed.machineId.length > 0) {
+        machineId = parsed.machineId;
+      }
+    } catch {
+      // No menubar.json — proceed with "unknown".
+    }
+
+    // installerVersion: callers (the Tauri menubar) set this when spawning
+    // the runner so the historical `installerVersion` dimension on
+    // CloudWatch keeps reporting the menubar version, not the runner's
+    // package version. CLI callers can leave it unset.
+    const installerVersion = process.env.HQ_INSTALLER_VERSION ?? "hq-cloud";
+
+    await collectAndSendTelemetry({
+      // The runtime guarantee here is that `clientIsStub === false` means
+      // `client` came from `new VaultClient(vaultConfig)` (see runRunner),
+      // which structurally satisfies `TelemetryClientSurface`.
+      client: client as unknown as Parameters<typeof collectAndSendTelemetry>[0]["client"],
+      machineId,
+      installerVersion,
+    });
+  } catch {
+    // Fire-and-forget; nothing escapes the boundary.
+  }
+}
+
 // ---------------------------------------------------------------------------
 // runRunner — testable entrypoint
 // ---------------------------------------------------------------------------
@@ -922,6 +981,20 @@ export async function runRunner(
     });
   }
 
+  // Fire telemetry collector before the all-complete emit so the cursor at
+  // `~/.hq/telemetry-cursor.json` is consistent with what the menubar sees.
+  // Awaited fully — fire-and-forget would lose in-flight POSTs at process
+  // exit, and the previous 10s race was wrong: a first-run user with
+  // backlog (e.g. 60K Claude session events) takes well over 10s legitimately,
+  // and the race silently dropped the entire batch when it fired. Errors
+  // are swallowed inside `defaultCollectTelemetry`; per-request timeouts
+  // come from `VaultClient`'s retry loop (3 attempts × exponential backoff),
+  // which naturally bounds the outer wait.
+  const telemetryFn =
+    deps.collectTelemetry ??
+    (() => defaultCollectTelemetry(client, deps.createVaultClient !== undefined));
+  await telemetryFn().catch(() => undefined);
+
   emit({
     type: "all-complete",
     companiesAttempted: plan.length,

package/src/client-info.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Tests for the client-info helpers and header injection.
+ *
+ * Two layers are exercised here:
+ *   1. The pure functions in `client-info.ts` — buildClientHeaders,
+ *      clientInfoFromPackage, detectHqCoreVersion.
+ *   2. End-to-end injection into VaultClient.request, since "the headers
+ *      actually land on outbound fetch" is the property consumers care about.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  buildClientHeaders,
+  clientInfoFromPackage,
+  detectHqCoreVersion,
+  HEADER_CLIENT_NAME,
+  HEADER_CLIENT_VERSION,
+  HEADER_HQ_CORE_VERSION,
+} from "./client-info.js";
+import { VaultClient } from "./vault-client.js";
+
+describe("buildClientHeaders", () => {
+  it("returns empty object when info is undefined", () => {
+    expect(buildClientHeaders(undefined)).toEqual({});
+  });
+
+  it("emits User-Agent + x-hq-client-{name,version} from name/version", () => {
+    const headers = buildClientHeaders({
+      name: "@indigoai-us/hq-cli",
+      version: "5.15.0",
+    });
+    expect(headers["User-Agent"]).toBe("@indigoai-us/hq-cli/5.15.0");
+    expect(headers[HEADER_CLIENT_NAME]).toBe("@indigoai-us/hq-cli");
+    expect(headers[HEADER_CLIENT_VERSION]).toBe("5.15.0");
+    expect(headers[HEADER_HQ_CORE_VERSION]).toBeUndefined();
+  });
+
+  it("includes x-hq-core-version only when hqCoreVersion is set", () => {
+    const headers = buildClientHeaders({
+      name: "@indigoai-us/hq-cli",
+      version: "5.15.0",
+      hqCoreVersion: "14.1.0",
+    });
+    expect(headers[HEADER_HQ_CORE_VERSION]).toBe("14.1.0");
+  });
+
+  it("emits arbitrary extra fields as x-hq-client-<key> headers", () => {
+    const headers = buildClientHeaders({
+      name: "x",
+      version: "1.0.0",
+      extra: { machine: "ec2-bot-7", channel: "stable" },
+    });
+    expect(headers["x-hq-client-machine"]).toBe("ec2-bot-7");
+    expect(headers["x-hq-client-channel"]).toBe("stable");
+  });
+});
+
+describe("clientInfoFromPackage", () => {
+  it("extracts name and version from a parsed package.json", () => {
+    expect(clientInfoFromPackage({ name: "foo", version: "1.2.3" })).toEqual({
+      name: "foo",
+      version: "1.2.3",
+    });
+  });
+
+  it("throws when name is missing", () => {
+    expect(() => clientInfoFromPackage({ version: "1.0.0" })).toThrow(/name/);
+  });
+
+  it("throws when version is missing", () => {
+    expect(() => clientInfoFromPackage({ name: "foo" })).toThrow(/version/);
+  });
+
+  it("throws on non-string fields", () => {
+    expect(() =>
+      clientInfoFromPackage({ name: 42 as unknown as string, version: "1.0.0" }),
+    ).toThrow();
+  });
+});
+
+describe("detectHqCoreVersion", () => {
+  let tmpRoot: string;
+  const origHqHome = process.env.HQ_HOME;
+  const origHqRoot = process.env.HQ_ROOT;
+
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), "hq-core-detect-"));
+    delete process.env.HQ_HOME;
+    delete process.env.HQ_ROOT;
+  });
+
+  afterEach(() => {
+    rmSync(tmpRoot, { recursive: true, force: true });
+    if (origHqHome !== undefined) process.env.HQ_HOME = origHqHome;
+    if (origHqRoot !== undefined) process.env.HQ_ROOT = origHqRoot;
+  });
+
+  function seedHqCore(root: string, version: string): void {
+    mkdirSync(join(root, "core"), { recursive: true });
+    mkdirSync(join(root, "companies"), { recursive: true });
+    writeFileSync(
+      join(root, "core", "core.yaml"),
+      `version: 1\nhqVersion: "${version}"\nupdatedAt: "2026-05-13T00:00:00Z"\n`,
+    );
+  }
+
+  it("returns undefined when nothing on the walk-up has core.yaml", () => {
+    expect(detectHqCoreVersion(tmpRoot)).toBeUndefined();
+  });
+
+  it("returns hqVersion when startDir is the hq-core root", () => {
+    seedHqCore(tmpRoot, "14.1.0");
+    expect(detectHqCoreVersion(tmpRoot)).toBe("14.1.0");
+  });
+
+  it("walks upward to find core.yaml from a nested cwd", () => {
+    seedHqCore(tmpRoot, "14.2.0");
+    const nested = join(tmpRoot, "companies", "acme", "projects", "p1");
+    mkdirSync(nested, { recursive: true });
+    expect(detectHqCoreVersion(nested)).toBe("14.2.0");
+  });
+
+  it("ignores directories that have core.yaml but no companies/ — disambiguates fixtures", () => {
+    mkdirSync(join(tmpRoot, "core"), { recursive: true });
+    writeFileSync(
+      join(tmpRoot, "core", "core.yaml"),
+      `version: 1\nhqVersion: "99.0.0"\n`,
+    );
+    // No companies/ at this level → not an hq-core root.
+    expect(detectHqCoreVersion(tmpRoot)).toBeUndefined();
+  });
+
+  it("honors HQ_HOME env override before walking cwd", () => {
+    seedHqCore(tmpRoot, "14.3.0");
+    process.env.HQ_HOME = tmpRoot;
+    // startDir intentionally points elsewhere — env should win.
+    const elsewhere = mkdtempSync(join(tmpdir(), "elsewhere-"));
+    try {
+      expect(detectHqCoreVersion(elsewhere)).toBe("14.3.0");
+    } finally {
+      rmSync(elsewhere, { recursive: true, force: true });
+    }
+  });
+
+  it("parses unquoted hqVersion values too", () => {
+    mkdirSync(join(tmpRoot, "core"), { recursive: true });
+    mkdirSync(join(tmpRoot, "companies"), { recursive: true });
+    writeFileSync(
+      join(tmpRoot, "core", "core.yaml"),
+      `version: 1\nhqVersion: 14.4.0\n`,
+    );
+    expect(detectHqCoreVersion(tmpRoot)).toBe("14.4.0");
+  });
+});
+
+describe("VaultClient stamps client headers on outbound requests", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("includes x-hq-client-name + x-hq-client-version when clientInfo is set", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ memberships: [] }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+
+    const client = new VaultClient({
+      apiUrl: "https://vault.test.example.com",
+      authToken: "tok",
+      clientInfo: {
+        name: "@indigoai-us/hq-cli",
+        version: "5.15.0",
+        hqCoreVersion: "14.1.0",
+      },
+    });
+
+    await client.listMyMemberships();
+
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const init = fetchSpy.mock.calls[0]?.[1] as RequestInit;
+    const headers = init.headers as Record<string, string>;
+    expect(headers[HEADER_CLIENT_NAME]).toBe("@indigoai-us/hq-cli");
+    expect(headers[HEADER_CLIENT_VERSION]).toBe("5.15.0");
+    expect(headers[HEADER_HQ_CORE_VERSION]).toBe("14.1.0");
+    expect(headers["User-Agent"]).toBe("@indigoai-us/hq-cli/5.15.0");
+  });
+
+  it("omits client headers when clientInfo is not set — back-compat", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ memberships: [] }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+
+    const client = new VaultClient({
+      apiUrl: "https://vault.test.example.com",
+      authToken: "tok",
+    });
+
+    await client.listMyMemberships();
+
+    const headers = (fetchSpy.mock.calls[0]?.[1] as RequestInit)
+      .headers as Record<string, string>;
+    expect(headers[HEADER_CLIENT_NAME]).toBeUndefined();
+    expect(headers[HEADER_CLIENT_VERSION]).toBeUndefined();
+    expect(headers["User-Agent"]).toBeUndefined();
+  });
+});

package/src/client-info.ts

@@ -0,0 +1,121 @@
+/**
+ * Client identification — every HQ client that talks to hq-cloud-api should
+ * stamp its name and version on outbound requests so the server can attribute
+ * traffic, gate on minimum versions, and surface deprecation warnings.
+ *
+ * The CLI in particular sends a third header (`x-hq-core-version`) when it's
+ * invoked from inside an hq-core checkout, so the server sees which scaffold
+ * generation the user is running against.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { ClientInfo } from "./types.js";
+
+export const HEADER_CLIENT_NAME = "x-hq-client-name";
+export const HEADER_CLIENT_VERSION = "x-hq-client-version";
+export const HEADER_HQ_CORE_VERSION = "x-hq-core-version";
+
+/**
+ * Build the set of `x-hq-*` headers (plus a derived `User-Agent`) for a
+ * ClientInfo. Returns an empty object when info is undefined so callers can
+ * spread the result unconditionally.
+ */
+export function buildClientHeaders(
+  info: ClientInfo | undefined,
+): Record<string, string> {
+  if (!info) return {};
+
+  const headers: Record<string, string> = {
+    "User-Agent": `${info.name}/${info.version}`,
+    [HEADER_CLIENT_NAME]: info.name,
+    [HEADER_CLIENT_VERSION]: info.version,
+  };
+
+  if (info.hqCoreVersion) {
+    headers[HEADER_HQ_CORE_VERSION] = info.hqCoreVersion;
+  }
+
+  if (info.extra) {
+    for (const [k, v] of Object.entries(info.extra)) {
+      headers[`x-hq-client-${k}`] = v;
+    }
+  }
+
+  return headers;
+}
+
+/**
+ * Build a ClientInfo from a parsed package.json. Most consumers will call this
+ * once at startup and pass the result into every VaultServiceConfig.
+ */
+export function clientInfoFromPackage(pkg: {
+  name?: unknown;
+  version?: unknown;
+}): ClientInfo {
+  if (typeof pkg.name !== "string" || pkg.name.length === 0) {
+    throw new Error("clientInfoFromPackage: package.json is missing a name");
+  }
+  if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+    throw new Error("clientInfoFromPackage: package.json is missing a version");
+  }
+  return { name: pkg.name, version: pkg.version };
+}
+
+/**
+ * Walk upward from `startDir` looking for `core/core.yaml`. When found, parse
+ * out the `hqVersion` field and return it. Returns undefined if we never find
+ * an hq-core checkout — i.e. the caller is running from a plain user dir.
+ *
+ * Honors `HQ_HOME` env var as an explicit override so multi-checkout setups
+ * (e.g. CI bots, the menubar app pointing at a non-cwd HQ root) can pin the
+ * detection without relying on cwd.
+ *
+ * Why a regex instead of a YAML parser: `core.yaml` lives at the very top of
+ * the file and the field has a stable shape — adding a YAML dep just to read
+ * one string would balloon every consumer's bundle. The current shape is
+ * `hqVersion: "X.Y.Z"` (quoted) per the canonical seed; we tolerate unquoted
+ * too.
+ */
+export function detectHqCoreVersion(startDir?: string): string | undefined {
+  const fromEnv = process.env.HQ_HOME ?? process.env.HQ_ROOT;
+  if (fromEnv) {
+    const v = readCoreVersionAt(fromEnv);
+    if (v) return v;
+  }
+
+  let dir = resolve(startDir ?? process.cwd());
+  while (true) {
+    const v = readCoreVersionAt(dir);
+    if (v) return v;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+function readCoreVersionAt(hqRoot: string): string | undefined {
+  // hq-core identity requires BOTH core/core.yaml AND companies/ — matches the
+  // CLI's own detection (commit bc827d0). Without this guard, any directory
+  // containing a stray `core/core.yaml` (e.g. a test fixture) would be
+  // misidentified as an hq-core root.
+  const yamlPath = join(hqRoot, "core", "core.yaml");
+  const companiesPath = join(hqRoot, "companies");
+  let content: string;
+  try {
+    content = readFileSync(yamlPath, "utf8");
+  } catch {
+    return undefined;
+  }
+  try {
+    // statSync would be marginally cleaner, but readdirSync of a nonexistent
+    // path throws synchronously which is what we want.
+    readFileSync(companiesPath, { flag: "r" });
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    // EISDIR is the success case — companies/ exists and is a directory.
+    if (e.code !== "EISDIR") return undefined;
+  }
+  const match = /^hqVersion:\s*["']?([^"'\s]+)/m.exec(content);
+  return match ? match[1] : undefined;
+}

package/src/context.ts

@@ -7,6 +7,7 @@
  */
 
 import type { EntityContext, VaultServiceConfig } from "./types.js";
+import { buildClientHeaders } from "./client-info.js";
 
 /** Minimum remaining TTL before auto-refresh triggers (2 minutes). */
 const REFRESH_THRESHOLD_MS = 2 * 60 * 1000;
@@ -231,7 +232,10 @@ async function fetchEntity(
   config: VaultServiceConfig,
 ): Promise<EntityResponse> {
   const res = await fetch(`${config.apiUrl}/entity/${uid}`, {
-    headers: { Authorization: `Bearer ${await resolveAuthToken(config)}` },
+    headers: {
+      Authorization: `Bearer ${await resolveAuthToken(config)}`,
+      ...buildClientHeaders(config.clientInfo),
+    },
   });
   if (!res.ok) {
     const body = await res.text();
@@ -255,7 +259,10 @@ async function fetchEntityBySlug(
   // sync runner's "I want MY company" intent.
   const checkUrl = `${config.apiUrl}/entity/check-slug/me?type=${encodeURIComponent(type)}&slug=${encodeURIComponent(slug)}`;
   const checkRes = await fetch(checkUrl, {
-    headers: { Authorization: `Bearer ${await resolveAuthToken(config)}` },
+    headers: {
+      Authorization: `Bearer ${await resolveAuthToken(config)}`,
+      ...buildClientHeaders(config.clientInfo),
+    },
   });
   if (!checkRes.ok) {
     const body = await checkRes.text();
@@ -290,6 +297,7 @@ async function postVend(
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${await resolveAuthToken(config)}`,
+      ...buildClientHeaders(config.clientInfo),
     },
     body: JSON.stringify({ ...body, durationSeconds: DEFAULT_SESSION_DURATION_SECONDS }),
   });