@indigoai-us/hq-cli 5.73.1 → 5.75.0

package/src/commands/integrations.test.ts

@@ -34,6 +34,7 @@ vi.mock("../utils/vault-api.js", async (importOriginal) => {
 });
 
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { AuthError, isAuthError } from "../utils/auth-error.js";
 import {
   IntegrationsCliError,
   queuedOutcome,
@@ -258,6 +259,16 @@ describe("hq integrations call", () => {
     ).rejects.toThrow(/--args must be a JSON object/);
     expect(vaultApiFetchMock).not.toHaveBeenCalled();
   });
+
+  it("marks non-object --args as expected", async () => {
+    try {
+      await runCli(["integrations", "call", "t", "--provider", "linear", "--args", "[1]"]);
+      throw new Error("expected runCli to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(true);
+    }
+  });
 });
 
 describe("hq integrations approve", () => {
@@ -282,3 +293,223 @@ describe("hq integrations approve", () => {
     expect(logged()).toContain("Approved");
   });
 });
+
+describe("expected integrations errors", () => {
+  const linear = {
+    id: "acct_1",
+    provider: "factory:linear",
+    status: "connected",
+  };
+  const notion = {
+    id: "acct_2",
+    provider: "factory:notion",
+    status: "connected",
+  };
+
+  it("marks a non-owner 403 approve as expected (skips Sentry) and preserves the message", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { error: "Only a company owner can approve or reject queued integration writes" },
+          403,
+        ),
+      );
+
+    try {
+      await runCli(["integrations", "approve", "cq_123", "--provider", "linear"]);
+      throw new Error("expected runCli to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(true);
+      expect((err as Error).message).toContain("Only a company owner");
+    }
+  });
+
+  it("still captures a genuine server 500 on approve (expected === false)", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(jsonResponse({ error: "boom" }, 500));
+
+    try {
+      await runCli(["integrations", "approve", "cq_123", "--provider", "linear"]);
+      throw new Error("expected runCli to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(false);
+    }
+  });
+
+  it("marks reject 403 as expected too", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { error: "Only a company owner can approve or reject queued integration writes" },
+          403,
+        ),
+      );
+
+    try {
+      await runCli(["integrations", "reject", "cq_123", "--provider", "linear"]);
+      throw new Error("expected runCli to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IntegrationsCliError);
+      expect((err as IntegrationsCliError).expected).toBe(true);
+    }
+
+    expect(vaultApiFetchMock.mock.calls[1]![0].path).toBe(
+      "/v1/integrations/confirm/cq_123/reject",
+    );
+  });
+
+  it("marks local connection selection usage errors as expected", () => {
+    for (const fn of [
+      () => selectConnection([], {}),
+      () => selectConnection([linear, notion], {}),
+      () => selectConnection([linear], { provider: "jira" }),
+    ]) {
+      try {
+        fn();
+        throw new Error("expected selectConnection to throw");
+      } catch (err) {
+        expect(err).toBeInstanceOf(IntegrationsCliError);
+        expect((err as IntegrationsCliError).expected).toBe(true);
+      }
+    }
+  });
+});
+
+// HQ-CLI-9: `hq integrations call get_board_info --provider monday …` hit a 401
+// on POST /v1/integrations/mcp while the caller's HQ session was rejected. The
+// old `callGateway` threw a plain, opaque `IntegrationsCliError("Integration
+// gateway request failed (HTTP 401).")` that shipped to Sentry as an
+// unactionable fatal. A gateway 401 is an expired/missing session — the same
+// expected auth state the vault company-resolution paths already raise as
+// `AuthError` (HQ-CLI-8). The fix routes every integration-gateway 401 through
+// that typed AuthError so the user gets one actionable "run `hq login`" message
+// and Sentry is skipped, while genuine 4xx/5xx faults keep their behavior.
+describe("integration gateway 401 → AuthError (HQ-CLI-9)", () => {
+  it("throws an actionable AuthError (not an opaque IntegrationsCliError) when callGateway 401s", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(jsonResponse({ error: "Unauthorized" }, 401));
+
+    const err = await runCli([
+      "integrations",
+      "call",
+      "get_board_info",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect(err).toBeInstanceOf(AuthError);
+    expect((err as Error).message).toMatch(/hq login/);
+    // The gateway request was actually attempted (connections + gateway call).
+    expect(vaultApiFetchMock.mock.calls[1]![0].path).toBe("/v1/integrations/mcp");
+  });
+
+  it("throws an AuthError when the admin (fetchConnections) call 401s", async () => {
+    vaultApiFetchMock.mockResolvedValueOnce(jsonResponse({ error: "Unauthorized" }, 401));
+
+    const err = await runCli(["integrations", "list"]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/hq login/);
+  });
+
+  it("throws an AuthError when an approve confirm call 401s", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(jsonResponse({ error: "Unauthorized" }, 401));
+
+    const err = await runCli([
+      "integrations",
+      "approve",
+      "cq_123",
+      "--provider",
+      "linear",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/hq login/);
+  });
+
+  // Scope guards: only a 401 becomes an AuthError. A genuine server 500 still
+  // reports (expected === false), and a provider-level JSON-RPC error (HTTP 200
+  // with `message.error`) stays an IntegrationsCliError — so real faults and
+  // upstream tool errors are never misclassified as an auth state.
+  it("keeps a gateway 500 as a reporting IntegrationsCliError (not an AuthError)", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(jsonResponse({ error: "boom" }, 500));
+
+    const err = await runCli([
+      "integrations",
+      "call",
+      "get_board_info",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(false);
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as IntegrationsCliError).expected).toBe(false);
+  });
+
+  it("keeps an upstream provider error (HTTP 200 message.error) as an IntegrationsCliError", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        jsonResponse({
+          jsonrpc: "2.0",
+          id: "x",
+          error: { code: -32050, message: "monday rejected the board id" },
+        }),
+      );
+
+    const err = await runCli([
+      "integrations",
+      "call",
+      "get_board_info",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]).then(
+      () => {
+        throw new Error("expected runCli to throw");
+      },
+      (e: unknown) => e,
+    );
+
+    expect(isAuthError(err)).toBe(false);
+    expect(err).toBeInstanceOf(IntegrationsCliError);
+    expect((err as Error).message).toMatch(/monday rejected the board id/);
+  });
+});

package/src/commands/integrations.ts

@@ -31,6 +31,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { AuthError } from "../utils/auth-error.js";
 
 interface AdminConnection {
   id: string;
@@ -50,12 +51,43 @@ interface GatewayMessage {
 }
 
 export class IntegrationsCliError extends Error {
-  constructor(message: string) {
+  /**
+   * True when the error is the caller's request/state/permission (a client 4xx
+   * or a local input/usage error) rather than an hq-cli defect. Expected errors
+   * are printed to the user but skipped for Sentry capture (HQ-CLI-6). Defaults
+   * to false so an unclassified error still reaches Sentry.
+   */
+  readonly expected: boolean;
+
+  constructor(message: string, opts: { expected?: boolean } = {}) {
     super(message);
     this.name = "IntegrationsCliError";
+    this.expected = opts.expected ?? false;
   }
 }
 
+/**
+ * A client 4xx is the caller's request/state/permission (bad params, stale
+ * queueId, a non-owner approving) — expected and user-facing, not a bug. A 5xx
+ * (or a 2xx protocol violation) is a genuine server/unknown fault worth a Sentry
+ * crash report.
+ */
+function isClientError(status: number): boolean {
+  return status >= 400 && status < 500;
+}
+
+// A 401 from ANY integration-gateway vault call means the caller's HQ session
+// is expired or missing — an expected auth state fixed by `hq login`, not an
+// hq-cli defect. Raise the same typed AuthError the vault company-resolution
+// paths use (HQ-CLI-8) so the top-level handler prints one actionable message
+// and skips Sentry, instead of surfacing the opaque, unactionable
+// "Integration gateway request failed (HTTP 401)" that shipped as a fatal from
+// `callGateway` (HQ-CLI-9). Non-401 statuses keep their existing behavior:
+// other 4xx stay expected client errors, 5xx still report.
+function raiseIfUnauthorized(res: Response): void {
+  if (res.status === 401) throw new AuthError();
+}
+
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
 export function toolPrefixForProvider(provider: string): string {
   return provider
@@ -75,9 +107,11 @@ export async function fetchConnections(
     query: { companyUid },
   });
   if (!res.ok) {
+    raiseIfUnauthorized(res);
     const body = (await res.json().catch(() => ({}))) as { error?: string };
     throw new IntegrationsCliError(
       body.error ?? `Failed to list integrations (HTTP ${res.status})`,
+      { expected: isClientError(res.status) },
     );
   }
   const data = (await res.json()) as { connections?: AdminConnection[] };
@@ -99,6 +133,7 @@ export function selectConnection(
     if (!match) {
       throw new IntegrationsCliError(
         `No connection '${opts.connection}'. Run \`hq integrations list\` to see connected apps.`,
+        { expected: true },
       );
     }
     return match;
@@ -116,6 +151,7 @@ export function selectConnection(
       throw new IntegrationsCliError(
         `No connected app matches '${opts.provider}'.` +
           (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps on the console Integrations page."),
+        { expected: true },
       );
     }
     return match;
@@ -124,11 +160,13 @@ export function selectConnection(
   if (active.length === 0) {
     throw new IntegrationsCliError(
       "No connected apps yet. Connect one on the console Integrations page, then retry.",
+      { expected: true },
     );
   }
   throw new IntegrationsCliError(
     `Multiple apps are connected — pick one with --provider:\n` +
       active.map((c) => `  --provider ${c.provider.replace(/^factory:/, "")}`).join("\n"),
+    { expected: true },
   );
 }
 
@@ -149,8 +187,10 @@ export async function callGateway(
   });
   const message = (await res.json().catch(() => null)) as GatewayMessage | null;
   if (!res.ok || !message) {
+    raiseIfUnauthorized(res);
     throw new IntegrationsCliError(
       `Integration gateway request failed (HTTP ${res.status}).`,
+      { expected: isClientError(res.status) },
     );
   }
   if (message.error) {
@@ -331,6 +371,7 @@ export function registerIntegrationsCommand(program: Command): void {
         } catch {
           throw new IntegrationsCliError(
             `--args must be a JSON object, e.g. --args '{"assignee":"me"}'`,
+            { expected: true },
           );
         }
         const token = await ensureCognitoIdToken();
@@ -416,8 +457,10 @@ export function registerIntegrationsCommand(program: Command): void {
             error?: string;
           };
           if (!res.ok) {
+            raiseIfUnauthorized(res);
             throw new IntegrationsCliError(
               body.error ?? `${decision} failed (HTTP ${res.status})`,
+              { expected: isClientError(res.status) },
             );
           }
           if (opts.json) {

package/src/commands/outposts.test.ts

@@ -305,6 +305,9 @@ describe("hq outposts exec", () => {
 
   it("wraps the command to run from the box's HQ folder, then runs it", () => {
     const wrapped = withRemoteHqDir("pwd");
+    // SSM may invoke the command as root with HOME unset. Seed a real home so
+    // tools such as gh do not write machine state into the HQ checkout.
+    expect(wrapped).toContain('export HOME="${HOME:-/root}"');
     // cd into $HOME/hq (SSH/login user) …
     expect(wrapped).toContain('cd "$HOME/hq"');
     // … falling back to ec2-user's home for the SSM/root path (no $HOME) …
@@ -531,6 +534,140 @@ describe("hq outposts exec — Lightsail SSH fallback", () => {
   });
 });
 
+
+describe("hq outposts exec --async / --detach", () => {
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
+  it("--detach submits with HQ-dir wrapper and prints commandId without waiting", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        ok: true,
+        userId: "u",
+        outpostId: "3",
+        instanceId: "i-3",
+        commandId: "cmd-detach",
+        outputPrefix: "outpost-exec/u/3/n/out",
+        executionTimeoutSeconds: 172800,
+      }),
+    );
+
+    await run(["outposts", "exec", "--detach", "--id", "3", "--json", "sleep", "999"]);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/exec");
+    expect(String(url)).toContain("outpostId=3");
+    expect(JSON.parse(init?.body as string)).toEqual({
+      mode: "submit",
+      command: withRemoteHqDir("'sleep' '999'"),
+    });
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+    expect(printed).toContain('"commandId":"cmd-detach"');
+    // No second poll.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("--async submits then polls until done and streams stdout", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u",
+          outpostId: "primary",
+          instanceId: "i",
+          commandId: "cmd-async",
+          outputPrefix: "p",
+          executionTimeoutSeconds: 7200,
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u",
+          outpostId: "primary",
+          status: "Success",
+          done: true,
+          exitCode: 0,
+          stdout: "finished\n",
+          stderr: "",
+        }),
+      );
+
+    await run([
+      "outposts",
+      "exec",
+      "--async",
+      "--timeout-seconds",
+      "7200",
+      "echo",
+      "finished",
+    ]);
+
+    // submit + one result poll (terminal on first poll)
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(JSON.parse(fetchSpy.mock.calls[0][1]?.body as string)).toEqual({
+      mode: "submit",
+      command: withRemoteHqDir("'echo' 'finished'"),
+      timeoutSeconds: 7200,
+    });
+    expect(JSON.parse(fetchSpy.mock.calls[1][1]?.body as string)).toEqual({
+      mode: "result",
+      commandId: "cmd-async",
+    });
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+    expect(printed).toContain("finished\n");
+    expect(process.exitCode).toBe(0);
+  });
+
+  it("refuses --async and --detach together", async () => {
+    await expect(
+      run(["outposts", "exec", "--async", "--detach", "true"]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("exec-submit forwards --timeout-seconds", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        ok: true,
+        commandId: "cmd-sub",
+        executionTimeoutSeconds: 3600,
+        userId: "u",
+        outpostId: "primary",
+        instanceId: "i",
+        outputPrefix: "p",
+      }),
+    );
+    await run([
+      "outposts",
+      "exec-submit",
+      "--timeout-seconds",
+      "3600",
+      "--json",
+      "sleep",
+      "10",
+    ]);
+    expect(JSON.parse(fetchSpy.mock.calls[0][1]?.body as string)).toEqual({
+      mode: "submit",
+      command: "'sleep' '10'",
+      timeoutSeconds: 3600,
+    });
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+    expect(printed).toContain("cmd-sub");
+  });
+});
+
 describe("hq outposts asynchronous exec", () => {
   it("sends the stage, submit, and result mode request bodies", async () => {
     fetchSpy