@indigoai-us/hq-cli 5.73.0 → 5.74.0

package/src/utils/expected-cli-error.ts

@@ -0,0 +1,39 @@
+// src/utils/expected-cli-error.ts
+//
+// Classify errors that are the CALLER's request/state/permission rather than an
+// hq-cli code defect: a bad flag, malformed input, a correctly-denied client
+// 4xx (e.g. a non-owner running `hq integrations approve`). These are
+// user-facing and actionable — the CLI prints a clear message and does NOT
+// report them to Sentry, otherwise a correctly-enforced authorization denial
+// floods the tracker with identical, unfixable crash reports.
+//
+// This is the caller-side analog of hq-pro's `expectedDenialResponse`, and a
+// sibling of `environmental-error.ts` (HQ-CLI-2) and
+// `intercepted-process-exit.ts` (HQ-CLI-3): errors that are NOT hq-cli defects
+// are surfaced to the user but skipped for Sentry capture.
+//
+// HQ-CLI-6: `hq integrations approve|reject` by a non-owner got a correct 403
+// ("Only a company owner can approve or reject queued integration writes"); the
+// thrown error propagated to the top-level handler, which captured it to Sentry
+// as an error-level crash and printed nothing to the user.
+
+/**
+ * An error the CLI should surface to the user (clear message, exit 1) but NOT
+ * report to Sentry. Carriers set `expected: true`.
+ */
+export interface ExpectedUserError extends Error {
+  expected: true;
+}
+
+/**
+ * True when `err` is an Error explicitly marked `expected === true`. A non-null
+ * result means the top-level handler should print `err.message` and skip Sentry
+ * capture. Anything else (unmarked errors, non-Error values) returns false so
+ * genuine faults still reach Sentry.
+ */
+export function isExpectedUserError(err: unknown): err is ExpectedUserError {
+  return (
+    err instanceof Error &&
+    (err as { expected?: unknown }).expected === true
+  );
+}

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

@@ -5,7 +5,9 @@ vi.mock('../sentry.js', () => ({
 }));
 
 import { Sentry } from '../sentry.js';
-import { getEntityUid, resolveCallerPersonUid, vaultApiFetch } from './vault-api.js';
+import { getCompanyUid, getEntityUid, resolveCallerPersonUid, vaultApiFetch } from './vault-api.js';
+import { isAuthError } from './auth-error.js';
+import { isCompanySelectionError } from './company-selection-error.js';
 
 const fetchMock = vi.fn();
 const originalFetch = globalThis.fetch;
@@ -199,6 +201,138 @@ describe('getEntityUid', () => {
   });
 });
 
+describe('getCompanyUid company-selection classification (HQ-CLI-7)', () => {
+  // The exact production scenario: a user with multiple active memberships runs
+  // a command with no --company. The prompt is expected, user-actionable guidance
+  // — it must be a CompanySelectionError so the top-level handler prints it and
+  // SKIPS Sentry capture, not a plain Error that gets shipped as a fatal.
+  it('throws a CompanySelectionError (not a plain Error) on multiple active memberships', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        memberships: [
+          { companyUid: 'cmp_a', role: 'member', status: 'active', membershipKey: 'k1' },
+          { companyUid: 'cmp_b', role: 'owner', status: 'active', membershipKey: 'k2' },
+          { companyUid: 'cmp_c', role: 'member', status: 'active', membershipKey: 'k3' },
+        ],
+      }),
+    );
+    const err = await getCompanyUid('tok', undefined).catch((e: unknown) => e);
+    expect(isCompanySelectionError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/Multiple active companies found/);
+    expect((err as Error).message).toMatch(/--company cmp_a/);
+  });
+
+  it('throws a CompanySelectionError when the caller has no active memberships', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        memberships: [
+          { companyUid: 'cmp_x', role: 'member', status: 'invited', membershipKey: 'k' },
+        ],
+      }),
+    );
+    const err = await getCompanyUid('tok', undefined).catch((e: unknown) => e);
+    expect(isCompanySelectionError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/No active company memberships/);
+  });
+
+  it('resolves silently to the single active membership (no selection error)', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        memberships: [
+          { companyUid: 'cmp_only', role: 'member', status: 'active', membershipKey: 'k' },
+        ],
+      }),
+    );
+    const uid = await getCompanyUid('tok', undefined);
+    expect(uid).toBe('cmp_only');
+  });
+
+  it('classifies the slug-collision (409, none in namespace) case as a selection error', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(
+        mockResponse(409, {
+          error: 'Slug "acme" matches 2 live entities',
+          uids: ['cmp_one', 'cmp_two'],
+        }),
+      );
+    const err = await getCompanyUid('tok', 'acme').catch((e: unknown) => e);
+    expect(isCompanySelectionError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/--company cmp_one/);
+  });
+
+  // A genuine fault must NOT be classified as a selection prompt — it still
+  // reports to Sentry. Guards against over-broadening the carve-out.
+  it('does NOT classify a failed membership fetch as a selection error (still reports)', async () => {
+    fetchMock.mockResolvedValueOnce(mockResponse(401, { error: 'unauthorized' }));
+    const err = await getCompanyUid('tok', undefined).catch((e: unknown) => e);
+    expect(isCompanySelectionError(err)).toBe(false);
+    expect((err as Error).message).toMatch(/Failed to fetch memberships/);
+  });
+});
+
+describe('resolveCompanyUid 401 → AuthError', () => {
+  it('short-circuits when check-slug/me returns 401 and does not call global by-slug', async () => {
+    fetchMock.mockResolvedValueOnce(mockResponse(401, { error: 'Unauthorized' }));
+
+    const err = await getEntityUid('tok', { companySlug: 'liverecover' }).catch(
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/hq login/);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0][0]).toMatch(/\/entity\/check-slug\/me/);
+  });
+
+  it('classifies a 401 from the global by-slug fallback as an AuthError', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(404, { available: true }))
+      .mockResolvedValueOnce(mockResponse(401, { error: 'Unauthorized' }));
+
+    const err = await getCompanyUid('tok', 'liverecover').catch(
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/hq login/);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps a global 409 slug collision on the CompanySelectionError path', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(
+        mockResponse(409, {
+          error: 'Slug "liverecover" matches 2 live entities',
+          uids: ['cmp_one', 'cmp_two'],
+        }),
+      );
+
+    const err = await getCompanyUid('tok', 'liverecover').catch(
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(false);
+    expect(isCompanySelectionError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/--company cmp_one/);
+  });
+
+  it('keeps a global 500 as a plain company-resolution Error', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(mockResponse(500, { error: 'Internal Server Error' }));
+
+    const err = await getCompanyUid('tok', 'liverecover').catch(
+      (e: unknown) => e,
+    );
+
+    expect(err).toBeInstanceOf(Error);
+    expect(isAuthError(err)).toBe(false);
+    expect((err as Error).message).toMatch(/Failed to resolve company slug/);
+  });
+});
+
 describe('vaultApiFetch breadcrumb URL sanitization', () => {
   it('redacts query string in request breadcrumb data.url', async () => {
     fetchMock.mockResolvedValueOnce(mockResponse(200, {}));

package/src/utils/vault-api.ts

@@ -1,5 +1,7 @@
 import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
 import { Sentry } from '../sentry.js';
+import { AuthError } from './auth-error.js';
+import { CompanySelectionError } from './company-selection-error.js';
 
 export interface VaultApiOptions {
   token: string;
@@ -106,12 +108,21 @@ export function looksLikeCompanyUid(ref: string): boolean {
   return ref.startsWith(COMPANY_UID_PREFIX);
 }
 
+// A 401 from ANY vault resolution call means the caller's HQ session is
+// expired or missing — an expected auth state fixed by `hq login`, not a
+// code defect. Raise a typed AuthError so the top-level handler prints an
+// actionable message and skips Sentry capture (HQ-CLI-8).
+function raiseIfUnauthorized(res: Response): void {
+  if (res.status === 401) throw new AuthError();
+}
+
 async function resolveCompanyByUid(token: string, uid: string): Promise<string> {
   const res = await vaultApiFetch({
     token,
     path: `/entity/${encodeURIComponent(uid)}`,
   });
   if (!res.ok) {
+    raiseIfUnauthorized(res);
     const body = (await res.json().catch(() => ({}))) as { error?: string };
     throw new Error(
       `Failed to resolve company '${uid}': ${body.error ?? res.statusText}`,
@@ -149,11 +160,13 @@ async function resolveSlugInCallerNamespace(
     query: { type: 'company', slug },
   });
   if (!res.ok) {
+    raiseIfUnauthorized(res);
     // Namespace lookup unavailable (e.g. membership table not configured →
-    // 503, or the caller has no person entity). Signal "couldn't resolve here"
-    // and let the caller fall back to the global lookup. vaultApiFetch already
-    // recorded the non-2xx as a Sentry breadcrumb, so this is not a silent
-    // swallow.
+    // 503, or the caller has no person entity). A 401 short-circuits above
+    // because the token is bad and the global fallback would only 401 again;
+    // other non-2xx statuses signal "couldn't resolve here" and let the caller
+    // fall back to the global lookup. vaultApiFetch already recorded the
+    // non-2xx as a Sentry breadcrumb, so this is not a silent swallow.
     return null;
   }
   const data = (await res.json()) as {
@@ -187,6 +200,7 @@ async function resolveCompanyUid(token: string, ref: string): Promise<string> {
     path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
   });
   if (!res.ok) {
+    raiseIfUnauthorized(res);
     const body = (await res.json().catch(() => ({}))) as {
       error?: string;
       uids?: string[];
@@ -197,7 +211,7 @@ async function resolveCompanyUid(token: string, ref: string): Promise<string> {
     // tell them exactly how — re-run with `--company <uid>` — and list the
     // candidates, instead of echoing the generic server message.
     if (res.status === 409 && Array.isArray(body.uids) && body.uids.length > 0) {
-      throw new Error(
+      throw new CompanySelectionError(
         `Company slug '${ref}' matches ${body.uids.length} companies and none ` +
           `is in your namespace. Re-run with --company <uid> to pick one:\n` +
           body.uids.map((u) => `  --company ${u}`).join('\n'),
@@ -222,13 +236,13 @@ async function resolveCompanyFromMemberships(token: string): Promise<string> {
   const data = (await res.json()) as { memberships: MembershipEntry[] };
   const active = data.memberships.filter((m) => m.status === 'active');
   if (active.length === 0) {
-    throw new Error('No active company memberships found. Use --company <slug> to specify.');
+    throw new CompanySelectionError('No active company memberships found. Use --company <slug> to specify.');
   }
   if (active.length === 1) {
     return active[0].companyUid;
   }
   const uids = active.map((m) => m.companyUid);
-  throw new Error(
+  throw new CompanySelectionError(
     `Multiple active companies found. Re-run with --company <slug-or-uid> to ` +
       `pick one:\n` +
       uids.map((u) => `  --company ${u}`).join('\n'),