@indigoai-us/hq-cloud 5.18.1 → 5.19.1

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.test.ts

@@ -47,6 +47,31 @@ function setupFetchMock(overrides?: {
   fetchMock.mockImplementation(async (url: string) => {
     const urlStr = String(url);
 
+    // New per-user-namespace slug resolver (hq-pro PR 67). Maps slug
+    // lookups to `{available: false, conflictingCompanyUid}` so the
+    // caller follows up with `/entity/{uid}`, which lands in the
+    // `/entity/cmp_` branch below — that's where `entityBody` and
+    // `entityStatus` overrides apply. The check-slug branch only
+    // honors `entityStatus` (so tests can simulate a 404/500 on the
+    // namespace lookup itself); its response shape stays fixed.
+    if (urlStr.includes("/entity/check-slug/me")) {
+      return {
+        ok: (overrides?.entityStatus ?? 200) < 400,
+        status: overrides?.entityStatus ?? 200,
+        json: async () => ({
+          available: false,
+          conflictingCompanyUid: mockEntity.uid,
+        }),
+        text: async () =>
+          JSON.stringify({
+            available: false,
+            conflictingCompanyUid: mockEntity.uid,
+          }),
+      };
+    }
+
+    // Kept for any tests that still mock the legacy global endpoint
+    // directly (none should, post-PR 67 — but harmless if invoked).
     if (urlStr.includes("/entity/by-slug/")) {
       return {
         ok: (overrides?.entityStatus ?? 200) < 400,
@@ -97,10 +122,16 @@ describe("resolveEntityContext", () => {
     expect(ctx.credentials.accessKeyId).toBe("ASIA_TEST_KEY");
     expect(ctx.region).toBe("us-east-1");
 
-    // Verify entity lookup used by-slug endpoint
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(String(fetchMock.mock.calls[0][0])).toContain("/entity/by-slug/company/acme");
-    expect(String(fetchMock.mock.calls[1][0])).toContain("/sts/vend");
+    // Verify entity lookup used the new per-user-namespace endpoint
+    // (PR 67) + a follow-up `/entity/{uid}` materialization + STS.
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(String(fetchMock.mock.calls[0][0])).toContain(
+      "/entity/check-slug/me?type=company&slug=acme",
+    );
+    expect(String(fetchMock.mock.calls[1][0])).toContain(
+      `/entity/${mockEntity.uid}`,
+    );
+    expect(String(fetchMock.mock.calls[2][0])).toContain("/sts/vend");
   });
 
   it("resolves context by UID directly", async () => {
@@ -120,7 +151,9 @@ describe("resolveEntityContext", () => {
     const ctx2 = await resolveEntityContext("acme", mockConfig);
 
     expect(ctx1).toBe(ctx2); // Same reference
-    expect(fetchMock).toHaveBeenCalledTimes(2); // Only 1 entity + 1 vend call
+    // 3 fetches per resolve under the new model: check-slug + entity.get + sts/vend.
+    // 1 resolve here (second call hits cache, no new fetches).
+    expect(fetchMock).toHaveBeenCalledTimes(3);
   });
 
   it("auto-refreshes when credentials expire soon", async () => {
@@ -137,7 +170,8 @@ describe("resolveEntityContext", () => {
     // Second call should refresh because <2 min remaining
     const ctx2 = await resolveEntityContext("acme", mockConfig);
     expect(ctx2).not.toBe(ctx1);
-    expect(fetchMock).toHaveBeenCalledTimes(4); // 2 entity + 2 vend calls
+    // 2 resolves × 3 fetches each = 6 under the new model.
+    expect(fetchMock).toHaveBeenCalledTimes(6);
   });
 
   it("throws when entity has no bucket", async () => {
@@ -153,8 +187,11 @@ describe("resolveEntityContext", () => {
   it("throws on entity lookup failure", async () => {
     setupFetchMock({ entityStatus: 404 });
 
+    // The namespace lookup fails first under the new model — error
+    // message now reflects "Failed to check slug" before the
+    // entity.get(uid) step is reached.
     await expect(resolveEntityContext("nonexistent", mockConfig)).rejects.toThrow(
-      /Failed to find entity/,
+      /Failed to check slug/,
     );
   });
 
@@ -201,12 +238,20 @@ describe("routing by UID prefix and vend-self dispatch", () => {
     expect(vendCalls[0]).toContain("/sts/vend-self");
   });
 
-  it("foo_bar slug: entity resolved via /entity/by-slug/company/foo_bar and credentials via /sts/vend", async () => {
+  it("foo_bar slug: entity resolved via /entity/check-slug/me + /entity/<uid> and credentials via /sts/vend", async () => {
     const calls: string[] = [];
     vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url: string) => {
       const u = String(url);
       calls.push(u);
-      if (u.includes("/entity/by-slug/")) {
+      if (u.includes("/entity/check-slug/me")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+          text: async () => "",
+        };
+      }
+      if (u.includes(`/entity/${mockEntity.uid}`)) {
         return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
       }
       if (u.includes("/sts/vend")) {
@@ -217,19 +262,29 @@ describe("routing by UID prefix and vend-self dispatch", () => {
 
     await resolveEntityContext("foo_bar", mockConfig);
 
-    expect(calls.some((u) => u.includes("/entity/by-slug/company/foo_bar"))).toBe(true);
+    expect(
+      calls.some((u) => u.includes("/entity/check-slug/me?type=company&slug=foo_bar")),
+    ).toBe(true);
     const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
     expect(vendCalls).toHaveLength(1);
     expect(vendCalls[0]).not.toContain("/sts/vend-self");
     expect(vendCalls[0]).toContain("/sts/vend");
   });
 
-  it("team_alpha slug: entity resolved via /entity/by-slug/company/team_alpha and credentials via /sts/vend", async () => {
+  it("team_alpha slug: entity resolved via /entity/check-slug/me + /entity/<uid> and credentials via /sts/vend", async () => {
     const calls: string[] = [];
     vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url: string) => {
       const u = String(url);
       calls.push(u);
-      if (u.includes("/entity/by-slug/")) {
+      if (u.includes("/entity/check-slug/me")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+          text: async () => "",
+        };
+      }
+      if (u.includes(`/entity/${mockEntity.uid}`)) {
         return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
       }
       if (u.includes("/sts/vend")) {
@@ -240,7 +295,9 @@ describe("routing by UID prefix and vend-self dispatch", () => {
 
     await resolveEntityContext("team_alpha", mockConfig);
 
-    expect(calls.some((u) => u.includes("/entity/by-slug/company/team_alpha"))).toBe(true);
+    expect(
+      calls.some((u) => u.includes("/entity/check-slug/me?type=company&slug=team_alpha")),
+    ).toBe(true);
     const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
     expect(vendCalls).toHaveLength(1);
     expect(vendCalls[0]).not.toContain("/sts/vend-self");
@@ -283,7 +340,9 @@ describe("refreshEntityContext", () => {
     const ctx2 = await refreshEntityContext("acme", mockConfig);
 
     expect(ctx2).not.toBe(ctx1);
-    expect(fetchMock).toHaveBeenCalledTimes(4); // 2 initial + 2 refresh
+    // 2 resolves × 3 fetches each = 6 under the new model
+    // (check-slug + entity.get + sts/vend each).
+    expect(fetchMock).toHaveBeenCalledTimes(6);
   });
 });