@indigoai-us/hq-cli 5.68.2 → 5.69.0

package/src/utils/cli-telemetry.test.ts

@@ -0,0 +1,153 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Each case does vi.resetModules() + a dynamic import() to reset the module-scoped
+// once-per-process memoization; the cold transform/import is slow, so raise the
+// per-test timeout well above the default 5s.
+vi.setConfig({ testTimeout: 30_000 });
+
+const mocks = vi.hoisted(() => ({
+  browserLogin: vi.fn(),
+  isExpiring: vi.fn(),
+  isMachineIdentity: vi.fn(),
+  loadCachedTokens: vi.fn(),
+  refreshTokens: vi.fn(),
+  vaultApiFetch: vi.fn(),
+}));
+
+vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@indigoai-us/hq-cloud")>();
+  return { ...actual, ...mocks };
+});
+
+vi.mock("./vault-api.js", () => ({
+  vaultApiFetch: mocks.vaultApiFetch,
+}));
+
+vi.mock("../cli-version.js", () => ({
+  CLI_NAME: "@indigoai-us/hq-cli",
+  CLI_VERSION: "5.68.1",
+}));
+
+const HUMAN_TOKENS = {
+  accessToken: "human-access-token",
+  idToken: "human-id-token",
+  refreshToken: "human-refresh-token",
+  expiresAt: Date.now() + 3_600_000,
+  tokenType: "Bearer" as const,
+};
+
+const MACHINE_TOKENS = {
+  ...HUMAN_TOKENS,
+  accessToken: "machine-access-token",
+  idToken: "machine-id-token",
+};
+
+async function loadEmitter() {
+  vi.resetModules();
+  return import("./cli-telemetry.js");
+}
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  mocks.isMachineIdentity.mockReturnValue(false);
+  mocks.isExpiring.mockReturnValue(false);
+  mocks.vaultApiFetch.mockResolvedValue(new Response(null, { status: 202 }));
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("emitCliSessionStarted", () => {
+  it("posts the privacy-safe event with a valid cached human token", async () => {
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    await emitCliSessionStarted();
+
+    expect(mocks.vaultApiFetch).toHaveBeenCalledTimes(1);
+    const request = mocks.vaultApiFetch.mock.calls[0]?.[0];
+    expect(request).toMatchObject({
+      token: HUMAN_TOKENS.accessToken,
+      path: "/v1/telemetry/events",
+      method: "POST",
+      signal: expect.any(AbortSignal),
+    });
+    expect(request.body.events).toHaveLength(1);
+    expect(request.body.events[0]).toEqual({
+      eventName: "cli_session_started",
+      app: "hq-cli",
+      source: "cli",
+      occurredAt: expect.any(String),
+      schemaVersion: 1,
+      properties: { version: "5.68.1" },
+    });
+  });
+
+  it("uses the cached ID token for a machine identity", async () => {
+    mocks.isMachineIdentity.mockReturnValue(true);
+    mocks.loadCachedTokens.mockReturnValue(MACHINE_TOKENS);
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    await emitCliSessionStarted();
+
+    expect(mocks.vaultApiFetch).toHaveBeenCalledWith(
+      expect.objectContaining({ token: MACHINE_TOKENS.idToken }),
+    );
+  });
+
+  it.each([
+    ["is absent", null, false],
+    ["is expiring", HUMAN_TOKENS, true],
+  ])(
+    "does not emit or refresh/login when the cached token %s",
+    async (_description, cachedTokens, expiring) => {
+      mocks.loadCachedTokens.mockReturnValue(cachedTokens);
+      mocks.isExpiring.mockReturnValue(expiring);
+      const { emitCliSessionStarted } = await loadEmitter();
+
+      await emitCliSessionStarted();
+
+      expect(mocks.vaultApiFetch).not.toHaveBeenCalled();
+      expect(mocks.refreshTokens).not.toHaveBeenCalled();
+      expect(mocks.browserLogin).not.toHaveBeenCalled();
+    },
+  );
+
+  it("swallows a non-2xx telemetry response", async () => {
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.vaultApiFetch.mockResolvedValue(new Response(null, { status: 503 }));
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    await expect(emitCliSessionStarted()).resolves.toBeUndefined();
+  });
+
+  it("aborts a slow telemetry request without failing the command", async () => {
+    vi.useFakeTimers();
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.vaultApiFetch.mockImplementation(
+      ({ signal }: { signal: AbortSignal }) =>
+        new Promise((_resolve, reject) => {
+          signal.addEventListener("abort", () => reject(new Error("aborted")), {
+            once: true,
+          });
+        }),
+    );
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    const emission = emitCliSessionStarted();
+    await vi.advanceTimersByTimeAsync(1_200);
+
+    await expect(emission).resolves.toBeUndefined();
+    expect(mocks.vaultApiFetch.mock.calls[0]?.[0].signal.aborted).toBe(true);
+  });
+
+  it("posts at most once when the root hook is invoked repeatedly", async () => {
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    await Promise.all([emitCliSessionStarted(), emitCliSessionStarted()]);
+
+    expect(mocks.vaultApiFetch).toHaveBeenCalledTimes(1);
+  });
+});

package/src/utils/cli-telemetry.ts

@@ -0,0 +1,61 @@
+import { CLI_VERSION } from "../cli-version.js";
+import {
+  isExpiring,
+  isMachineIdentity,
+  loadCachedTokens,
+} from "./cognito-session.js";
+import { vaultApiFetch } from "./vault-api.js";
+
+const TELEMETRY_TIMEOUT_MS = 1_200;
+
+let cliSessionStartedPromise: Promise<void> | undefined;
+
+/**
+ * Emit the authenticated CLI session signal using an already-cached token.
+ * This deliberately never refreshes a session or opens a browser.
+ */
+export function emitCliSessionStarted(): Promise<void> {
+  cliSessionStartedPromise ??= emitCachedCliSessionStarted();
+  return cliSessionStartedPromise;
+}
+
+async function emitCachedCliSessionStarted(): Promise<void> {
+  try {
+    const cached = loadCachedTokens();
+    if (!cached || isExpiring(cached, 120)) return;
+
+    const token = isMachineIdentity() ? cached.idToken : cached.accessToken;
+    if (!token) return;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+
+    try {
+      const response = await vaultApiFetch({
+        token,
+        path: "/v1/telemetry/events",
+        method: "POST",
+        body: {
+          events: [
+            {
+              eventName: "cli_session_started",
+              app: "hq-cli",
+              source: "cli",
+              occurredAt: new Date().toISOString(),
+              schemaVersion: 1,
+              properties: { version: CLI_VERSION },
+            },
+          ],
+        },
+        signal: controller.signal,
+      });
+      if (!response.ok) return;
+    } catch {
+      // Telemetry is best effort and must never affect a CLI command.
+    } finally {
+      clearTimeout(timeout);
+    }
+  } catch {
+    // Cached-token reads are also best effort (for example, a malformed cache).
+  }
+}

package/src/utils/cognito-session.ts

@@ -38,6 +38,10 @@ import {
 } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 
+// Re-export the cached-session primitives for callers that must deliberately
+// avoid the refresh/login behavior in the higher-level helpers below.
+export { isExpiring, isMachineIdentity, loadCachedTokens };
+
 export const DEFAULT_COGNITO: CognitoAuthConfig = {
   region: process.env.AWS_REGION ?? "us-east-1",
   userPoolDomain: process.env.HQ_COGNITO_DOMAIN ?? "vault-indigo-hq-prod",

package/src/utils/vault-api.test.ts

@@ -229,3 +229,21 @@ describe('vaultApiFetch breadcrumb URL sanitization', () => {
     expect(errorCrumb.data?.url).toContain('?<redacted>');
   });
 });
+
+describe('vaultApiFetch abort signals', () => {
+  it('passes an optional abort signal to fetch', async () => {
+    fetchMock.mockResolvedValueOnce(mockResponse(200, {}));
+    const controller = new AbortController();
+
+    await vaultApiFetch({
+      token: 'tok',
+      path: '/v1/telemetry/events',
+      signal: controller.signal,
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ signal: controller.signal }),
+    );
+  });
+});

package/src/utils/vault-api.ts

@@ -7,6 +7,7 @@ export interface VaultApiOptions {
   method?: string;
   body?: Record<string, unknown>;
   query?: Record<string, string>;
+  signal?: AbortSignal;
 }
 
 export async function vaultApiFetch(opts: VaultApiOptions): Promise<Response> {
@@ -31,6 +32,7 @@ export async function vaultApiFetch(opts: VaultApiOptions): Promise<Response> {
       'Content-Type': 'application/json',
     },
     body: opts.body ? JSON.stringify(opts.body) : undefined,
+    signal: opts.signal,
   });
   if (!response.ok) {
     Sentry.addBreadcrumb({