@indigoai-us/hq-cli 5.61.0 → 5.62.0

package/src/commands/integrations.ts

@@ -0,0 +1,438 @@
+/**
+ * `hq integrations` subcommand group — use company-connected apps (the
+ * integration factory's governed gateway) from any HQ-authenticated session.
+ *
+ * The console connects apps (e.g. Linear via OAuth sign-in); cloud agents get
+ * their tools natively through hq-pro's integration MCP gateway
+ * (POST /v1/integrations/mcp). This command gives LOCAL sessions (Claude
+ * Code / Codex chats, scripts) the same first-class path — no hand-crafted
+ * authenticated curl calls.
+ *
+ * Subcommands:
+ *   hq integrations list                     Connected apps for the company.
+ *   hq integrations tools --provider <p>     What the connected app can do.
+ *   hq integrations call <tool> --provider <p> --args '<json>'
+ *                                            Invoke one of the app's tools.
+ *   hq integrations approve|reject <queueId> --provider <p>
+ *                                            Decide a queued (approval-gated)
+ *                                            call; approve executes it.
+ *
+ * Governance: reads flow freely; calls that can change the app are subject to
+ * the connection's write policy (default: a person approves first). A queued
+ * outcome is surfaced clearly with the exact approve command to run.
+ *
+ * Auth: Cognito ID token via the shared session cache (`hq auth refresh`
+ * semantics); company resolves like every other command — `--company <slug>`
+ * or the caller's single active membership. Never hardcoded.
+ */
+
+import { randomUUID } from "node:crypto";
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoIdToken } from "../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+
+interface AdminConnection {
+  id: string;
+  provider: string;
+  status: string;
+  writePolicy?: string;
+  installation?: {
+    displayName?: string;
+    domain?: string;
+    status?: string;
+  } | null;
+}
+
+interface GatewayMessage {
+  result?: unknown;
+  error?: { code?: number; message?: string };
+}
+
+export class IntegrationsCliError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IntegrationsCliError";
+  }
+}
+
+/** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
+export function toolPrefixForProvider(provider: string): string {
+  return provider
+    .replace(/^factory:/, "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ".");
+}
+
+export async function fetchConnections(
+  token: string,
+  companyUid: string,
+): Promise<AdminConnection[]> {
+  const res = await vaultApiFetch({
+    token,
+    path: "/v1/integrations/admin",
+    query: { companyUid },
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    throw new IntegrationsCliError(
+      body.error ?? `Failed to list integrations (HTTP ${res.status})`,
+    );
+  }
+  const data = (await res.json()) as { connections?: AdminConnection[] };
+  return data.connections ?? [];
+}
+
+/**
+ * Resolve one connection by `--connection acct_…` or `--provider linear`
+ * (matches `factory:<slug>` and bare provider ids, case-insensitive). Errors
+ * list what IS connected so the fix is one command away.
+ */
+export function selectConnection(
+  connections: AdminConnection[],
+  opts: { connection?: string; provider?: string },
+): AdminConnection {
+  const active = connections.filter((c) => c.status !== "revoked");
+  if (opts.connection) {
+    const match = connections.find((c) => c.id === opts.connection);
+    if (!match) {
+      throw new IntegrationsCliError(
+        `No connection '${opts.connection}'. Run \`hq integrations list\` to see connected apps.`,
+      );
+    }
+    return match;
+  }
+  if (opts.provider) {
+    const want = opts.provider.trim().toLowerCase();
+    const match = active.find((c) => {
+      const bare = c.provider.replace(/^factory:/, "").toLowerCase();
+      return bare === want || c.provider.toLowerCase() === want;
+    });
+    if (!match) {
+      const available = active
+        .map((c) => c.provider.replace(/^factory:/, ""))
+        .join(", ");
+      throw new IntegrationsCliError(
+        `No connected app matches '${opts.provider}'.` +
+          (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps on the console Integrations page."),
+      );
+    }
+    return match;
+  }
+  if (active.length === 1) return active[0];
+  if (active.length === 0) {
+    throw new IntegrationsCliError(
+      "No connected apps yet. Connect one on the console Integrations page, then retry.",
+    );
+  }
+  throw new IntegrationsCliError(
+    `Multiple apps are connected — pick one with --provider:\n` +
+      active.map((c) => `  --provider ${c.provider.replace(/^factory:/, "")}`).join("\n"),
+  );
+}
+
+export async function callGateway(
+  token: string,
+  params: Record<string, unknown>,
+): Promise<GatewayMessage> {
+  const res = await vaultApiFetch({
+    token,
+    path: "/v1/integrations/mcp",
+    method: "POST",
+    body: {
+      jsonrpc: "2.0",
+      id: `hq-cli-${randomUUID()}`,
+      method: "tools/call",
+      params,
+    },
+  });
+  const message = (await res.json().catch(() => null)) as GatewayMessage | null;
+  if (!res.ok || !message) {
+    throw new IntegrationsCliError(
+      `Integration gateway request failed (HTTP ${res.status}).`,
+    );
+  }
+  if (message.error) {
+    throw new IntegrationsCliError(
+      message.error.message ?? "Integration gateway returned an error.",
+    );
+  }
+  return message;
+}
+
+/**
+ * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`
+ * where `text` is the provider's JSON. Unwrap to the inner payload; fall back
+ * to the raw result when the shape differs.
+ */
+export function unwrapGatewayResult(result: unknown): unknown {
+  if (result && typeof result === "object" && Array.isArray((result as { content?: unknown }).content)) {
+    const content = (result as { content: Array<{ type?: string; text?: string }> }).content;
+    const text = content.find((c) => c.type === "text")?.text;
+    if (typeof text === "string") {
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    }
+  }
+  return result;
+}
+
+interface QueuedOutcome {
+  queuedForApproval: true;
+  queueId: string;
+  connectionId: string;
+  expiresAt?: string;
+}
+
+export function queuedOutcome(payload: unknown): QueuedOutcome | null {
+  if (
+    payload &&
+    typeof payload === "object" &&
+    (payload as { queuedForApproval?: unknown }).queuedForApproval === true &&
+    typeof (payload as { queueId?: unknown }).queueId === "string"
+  ) {
+    return payload as unknown as QueuedOutcome;
+  }
+  return null;
+}
+
+function printJson(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export function registerIntegrationsCommand(program: Command): void {
+  const integrations = program
+    .command("integrations")
+    .description(
+      "Use company-connected apps (Linear, Notion, …) through HQ's governed integration gateway",
+    );
+
+  integrations
+    .command("list")
+    .description("List the company's connected apps")
+    .option("--company <slug>", "Company slug (defaults to your single active company)")
+    .option("--json", "Machine-readable output")
+    .action(async (opts: { company?: string; json?: boolean }) => {
+      const token = await ensureCognitoIdToken();
+      const companyUid = await getCompanyUid(token, opts.company);
+      const connections = await fetchConnections(token, companyUid);
+      if (opts.json) {
+        printJson(connections);
+        return;
+      }
+      if (connections.length === 0) {
+        console.log(
+          "No apps connected yet. Connect one on the console Integrations page.",
+        );
+        return;
+      }
+      for (const c of connections) {
+        const name =
+          c.installation?.displayName ?? c.provider.replace(/^factory:/, "");
+        const flags = [
+          c.status,
+          c.writePolicy ? `writes: ${c.writePolicy}` : null,
+          c.installation?.status === "needs_credentials" ? "needs sign-in" : null,
+        ]
+          .filter(Boolean)
+          .join(" · ");
+        console.log(
+          `${chalk.bold(name)}  (${c.provider.replace(/^factory:/, "")})  ${chalk.dim(flags)}`,
+        );
+        console.log(chalk.dim(`  connection: ${c.id}`));
+      }
+    });
+
+  integrations
+    .command("tools")
+    .description("List what a connected app can do")
+    .option("--provider <slug>", "Connected app (e.g. linear)")
+    .option("--connection <id>", "Connection id (acct_…)")
+    .option("--company <slug>", "Company slug")
+    .option("--json", "Machine-readable output")
+    .action(
+      async (opts: {
+        provider?: string;
+        connection?: string;
+        company?: string;
+        json?: boolean;
+      }) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = selectConnection(
+          await fetchConnections(token, companyUid),
+          opts,
+        );
+        const prefix = toolPrefixForProvider(connection.provider);
+        const message = await callGateway(token, {
+          companyUid,
+          name: `${prefix}.mcp.tools.list`,
+          arguments: { companyUid, connectionId: connection.id },
+        });
+        const payload = unwrapGatewayResult(message.result) as {
+          tools?: Array<{ name: string; title?: string; description?: string }>;
+        };
+        if (opts.json) {
+          printJson(payload);
+          return;
+        }
+        const tools = payload?.tools ?? [];
+        if (tools.length === 0) {
+          console.log("The app reported no tools.");
+          return;
+        }
+        for (const tool of tools) {
+          const label = tool.title && tool.title !== tool.name ? `  ${chalk.dim(tool.title)}` : "";
+          console.log(`${chalk.bold(tool.name)}${label}`);
+        }
+        console.log(
+          chalk.dim(
+            `\n${tools.length} tools. Call one with: hq integrations call <tool> --provider ${connection.provider.replace(/^factory:/, "")} --args '<json>'`,
+          ),
+        );
+      },
+    );
+
+  integrations
+    .command("call <tool>")
+    .description("Call one of a connected app's tools (approval-gated when it changes things)")
+    .option("--provider <slug>", "Connected app (e.g. linear)")
+    .option("--connection <id>", "Connection id (acct_…)")
+    .option("--company <slug>", "Company slug")
+    .option("--args <json>", "Tool arguments as JSON", "{}")
+    .option(
+      "--idempotency-key <key>",
+      "Stable key so retries execute at most once (default: generated)",
+    )
+    .option("--json", "Machine-readable output")
+    .action(
+      async (
+        tool: string,
+        opts: {
+          provider?: string;
+          connection?: string;
+          company?: string;
+          args: string;
+          idempotencyKey?: string;
+          json?: boolean;
+        },
+      ) => {
+        let parsedArgs: Record<string, unknown>;
+        try {
+          const raw: unknown = JSON.parse(opts.args);
+          if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new Error("not an object");
+          }
+          parsedArgs = raw as Record<string, unknown>;
+        } catch {
+          throw new IntegrationsCliError(
+            `--args must be a JSON object, e.g. --args '{"assignee":"me"}'`,
+          );
+        }
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = selectConnection(
+          await fetchConnections(token, companyUid),
+          opts,
+        );
+        const prefix = toolPrefixForProvider(connection.provider);
+        const idempotencyKey = opts.idempotencyKey ?? `hq-cli-${randomUUID()}`;
+        const message = await callGateway(token, {
+          companyUid,
+          name: `${prefix}.mcp.tools.call`,
+          arguments: {
+            companyUid,
+            connectionId: connection.id,
+            toolName: tool,
+            arguments: parsedArgs,
+            idempotencyKey,
+          },
+        });
+        const payload = unwrapGatewayResult(message.result);
+        const queued = queuedOutcome(payload);
+        if (queued) {
+          if (opts.json) {
+            printJson(payload);
+            return;
+          }
+          console.log(
+            chalk.yellow(
+              "Queued for approval — this call can change the app, so a company owner decides first.",
+            ),
+          );
+          console.log(
+            `Approve with:\n  hq integrations approve ${queued.queueId} --provider ${connection.provider.replace(/^factory:/, "")}`,
+          );
+          if (queued.expiresAt) {
+            console.log(chalk.dim(`Expires ${queued.expiresAt}`));
+          }
+          return;
+        }
+        printJson(payload);
+      },
+    );
+
+  for (const decision of ["approve", "reject"] as const) {
+    integrations
+      .command(`${decision} <queueId>`)
+      .description(
+        decision === "approve"
+          ? "Approve a queued call — it executes exactly once (owner only)"
+          : "Reject a queued call (owner only)",
+      )
+      .option("--provider <slug>", "Connected app (e.g. linear)")
+      .option("--connection <id>", "Connection id (acct_…)")
+      .option("--company <slug>", "Company slug")
+      .option("--json", "Machine-readable output")
+      .action(
+        async (
+          queueId: string,
+          opts: {
+            provider?: string;
+            connection?: string;
+            company?: string;
+            json?: boolean;
+          },
+        ) => {
+          const token = await ensureCognitoIdToken();
+          const companyUid = await getCompanyUid(token, opts.company);
+          const connection = selectConnection(
+            await fetchConnections(token, companyUid),
+            opts,
+          );
+          const res = await vaultApiFetch({
+            token,
+            path: `/v1/integrations/confirm/${encodeURIComponent(queueId)}/${decision}`,
+            method: "POST",
+            body: { companyUid, connectionId: connection.id },
+          });
+          const body = (await res.json().catch(() => ({}))) as {
+            status?: string;
+            result?: unknown;
+            error?: string;
+          };
+          if (!res.ok) {
+            throw new IntegrationsCliError(
+              body.error ?? `${decision} failed (HTTP ${res.status})`,
+            );
+          }
+          if (opts.json) {
+            printJson(body);
+            return;
+          }
+          console.log(
+            decision === "approve"
+              ? chalk.green(`Approved — the call ran (status: ${body.status ?? "resumed"}).`)
+              : chalk.yellow(`Rejected (status: ${body.status ?? "rejected"}).`),
+          );
+          if (decision === "approve" && body.result !== undefined) {
+            printJson(unwrapGatewayResult(body.result));
+          }
+        },
+      );
+  }
+}

package/src/commands/members.ts

@@ -754,10 +754,10 @@ export function registerMembersCommand(program: Command): void {
             `  1. Manually notify ${inviteeEmail ?? "the invitee"}: ask them to sign into HQ`,
           );
           console.log(
-            `     at https://hq.getindigo.ai with that email address.`,
+            `     at https://hq.computer with that email address.`,
           );
           console.log(
-            `  2. Or use the hq-console UI at https://hq.getindigo.ai to issue the`,
+            `  2. Or use the hq-console UI at https://hq.computer to issue the`,
           );
           console.log(
             `     invite instead — the UI path triggers an automated email via Resend.`,

package/src/commands/outposts.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Unit tests for `hq outposts` (outposts.ts).
+ *
+ * Mirrors company.test.ts: mock ensureCognitoToken, spy on global fetch, drive
+ * through a Commander program, assert the /outpost/* request shape (method +
+ * path + query) plus the destroy guard and the teardown-incomplete retry path.
+ * Outposts are caller-scoped, so there is no company resolution to mock.
+ */
+
+import { Command } from "commander";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+vi.mock("../utils/cognito-session.js", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("../utils/cognito-session.js")>();
+  return {
+    ...original,
+    ensureCognitoToken: vi.fn(async () => "test-token"),
+  };
+});
+
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { registerOutpostsCommand } from "./outposts.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchSpy: MockInstance<typeof fetch>;
+let exitSpy: MockInstance<typeof process.exit>;
+let logSpy: MockInstance<typeof console.log>;
+const mockEnsureCognitoToken = vi.mocked(ensureCognitoToken);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+  mockEnsureCognitoToken.mockResolvedValue("test-token");
+  exitSpy = vi.spyOn(process, "exit").mockImplementation((code?: number) => {
+    throw new Error(`process.exit(${code})`);
+  }) as unknown as MockInstance<typeof process.exit>;
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.name("hq").exitOverride();
+  registerOutpostsCommand(program);
+  return program;
+}
+
+async function run(args: string[]): Promise<void> {
+  await buildProgram().parseAsync(["node", "hq", ...args]);
+}
+
+describe("hq outposts list", () => {
+  it("GETs /outpost/list", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        outposts: [
+          {
+            outpostId: "primary",
+            state: "running",
+            instanceName: "outpost-abc",
+            region: "us-east-1",
+            agentRuntime: "claude",
+            platform: "ec2",
+            createdAt: "2026-01-01T00:00:00Z",
+          },
+        ],
+      }),
+    );
+
+    await run(["outposts", "list"]);
+
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/list");
+    expect(init?.method ?? "GET").toBe("GET");
+  });
+
+  it("emits raw JSON with --json", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { outposts: [] }));
+    await run(["outposts", "list", "--json"]);
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("[]");
+  });
+});
+
+describe("hq outposts status", () => {
+  it("GETs /outpost/status with the --id query param", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { state: "running" }));
+    await run(["outposts", "status", "--id", "2"]);
+    const url = String(fetchSpy.mock.calls[0][0]);
+    expect(url).toContain("/outpost/status");
+    expect(url).toContain("outpostId=2");
+  });
+
+  it("omits outpostId when --id is not given", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { state: "running" }));
+    await run(["outposts", "status"]);
+    expect(String(fetchSpy.mock.calls[0][0])).not.toContain("outpostId=");
+  });
+});
+
+describe("hq outposts codex-enable / login", () => {
+  it("POSTs /outpost/codex/enable", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+    await run(["outposts", "codex-enable"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/codex/enable");
+    expect(init?.method).toBe("POST");
+  });
+
+  it("POSTs /outpost/regenerate-login-url", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+    await run(["outposts", "login"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/regenerate-login-url");
+    expect(init?.method).toBe("POST");
+  });
+});
+
+describe("hq outposts destroy", () => {
+  it("refuses without --yes and does not call the API", async () => {
+    await expect(run(["outposts", "destroy"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("POSTs /outpost/destroy with --yes", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { ok: true, userId: "u1" }),
+    );
+    await run(["outposts", "destroy", "--yes"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/destroy");
+    expect(init?.method).toBe("POST");
+  });
+
+  it("treats a 409 teardown-incomplete as retryable (no exit)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(409, { error: true, step: "teardown-incomplete" }),
+    );
+    await run(["outposts", "destroy", "--id", "2", "--yes"]);
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toMatch(/still in progress/i);
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("exits 1 on a genuine failure", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(500, { error: "boom", step: "teardown" }),
+    );
+    await expect(
+      run(["outposts", "destroy", "--yes"]),
+    ).rejects.toThrow("process.exit(1)");
+  });
+});