@indigoai-us/hq-cli 5.61.0 → 5.62.0

package/src/commands/db-provision.ts

@@ -0,0 +1,102 @@
+/**
+ * hq db provision — request remote vault DB binding (US-009).
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+
+import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
+
+export interface DbProvisionCommandDeps {
+  resolveCompany: (slug: string) => Promise<{ companyUid: string; companySlug: string }>;
+  getAccessToken: () => Promise<string>;
+  apiBaseUrl: string;
+  fetchImpl?: typeof fetch;
+}
+
+const defaultDeps = (): DbProvisionCommandDeps => ({
+  async resolveCompany(slug) {
+    // Production path: resolve via vault API membership. Tests inject mocks.
+    // Keep slug as placeholder uid only when HQ_DB_MOCK_CONTROL_PLANE=1.
+    if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
+      return { companyUid: `cmp_${slug}`, companySlug: slug };
+    }
+    throw new Error(
+      "company resolution not wired in this build path — inject deps or set HQ_DB_MOCK_CONTROL_PLANE=1 for local mock",
+    );
+  },
+  async getAccessToken() {
+    if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
+      return "mock-token";
+    }
+    throw new Error("auth token resolution not wired — inject deps for production");
+  },
+  apiBaseUrl:
+    process.env.HQ_API_BASE_URL ||
+    process.env.HQ_CLOUD_API_URL ||
+    "https://hqapi.getindigo.ai",
+});
+
+export function registerDbProvisionCommand(
+  db: Command,
+  depsFactory: () => DbProvisionCommandDeps = defaultDeps,
+): void {
+  db.command("provision")
+    .description(
+      "Provision (or re-bind) the company remote vault DB via HQ control plane",
+    )
+    .requiredOption("--company <slug>", "Company slug")
+    .option("--region <region>", "AWS region", "us-east-1")
+    .action(async (opts: { company: string; region?: string }) => {
+      try {
+        const deps = depsFactory();
+        const company = String(opts.company ?? "").trim();
+        if (!company) {
+          console.error(chalk.red("Error: --company is required"));
+          process.exitCode = 1;
+          return;
+        }
+
+        const resolved = await deps.resolveCompany(company);
+        const client = new ControlPlaneDbClient({
+          baseUrl: deps.apiBaseUrl,
+          getAccessToken: deps.getAccessToken,
+          fetchImpl: deps.fetchImpl,
+        });
+
+        const result = await client.provision({
+          companyUid: resolved.companyUid,
+          companySlug: resolved.companySlug,
+          region: opts.region,
+        });
+
+        console.log(`company: ${result.companySlug}`);
+        console.log(`remote: ${result.status}`);
+        console.log(`engine: ${result.engineId}`);
+        console.log(`region: ${result.region}`);
+        console.log(`resourceArn: ${result.resourceArn}`);
+        console.log(`secretRef: ${result.secretRef}`);
+        console.log(`idempotent: ${result.idempotent ? "yes" : "no"}`);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : "Unknown error";
+        const status = (error as { status?: number }).status;
+        if (status === 402 || /PLAN_REQUIRED|Team plan|\$500/i.test(msg)) {
+          console.error(
+            chalk.red("Error:"),
+            "Remote vault DB requires the HQ Team plan ($500/mo).",
+          );
+          console.error(
+            chalk.dim(
+              "Local databases still work: hq db status|sql|migrate — no Team plan required.",
+            ),
+          );
+        } else {
+          console.error(chalk.red("Error:"), msg);
+        }
+        if (/postgres:\/\//i.test(msg)) {
+          console.error(chalk.red("Error: refused to print secret material"));
+        }
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/db-sql.ts

@@ -0,0 +1,124 @@
+/**
+ * hq db sql — run SQL against the company local vault DB (US-004).
+ *
+ * Default is read-only. Prefer `hq db migrate` for schema changes.
+ * Never prints remote connection strings.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import fs from "node:fs";
+
+import { runRemoteSql } from "../lib/db/remote-sql.js";
+import { formatSqlResult, runLocalSql } from "../lib/db/sql.js";
+
+function readSqlArg(sqlArgs: string[], stdinFlag: boolean): string {
+  if (stdinFlag || sqlArgs.length === 0) {
+    if (process.stdin.isTTY && sqlArgs.length === 0) {
+      throw new Error(
+        "SQL required: pass as arguments after -- or pipe via stdin",
+      );
+    }
+    return fs.readFileSync(0, "utf8");
+  }
+  return sqlArgs.join(" ");
+}
+
+export function registerDbSqlCommand(db: Command): void {
+  db.command("sql")
+    .description(
+      "Run SQL against the company vault DB (local default; --remote for secrets-injected remote; read-only by default)",
+    )
+    .requiredOption("--company <slug>", "Company slug (tenant scope; required)")
+    .option("--write", "Allow write/DDL statements (discouraged for ad-hoc DDL)", false)
+    .option(
+      "--remote",
+      "Use remote tier via vault-bound credentials (not auto-replicated with local)",
+      false,
+    )
+    .option(
+      "--db-path <path>",
+      "Dangerous: open a non-canonical DB path (denied unless --allow-cross-company-path)",
+    )
+    .option(
+      "--allow-cross-company-path",
+      "Dangerous: permit --db-path outside this company's canonical local DB",
+      false,
+    )
+    .option("--format <fmt>", "Output format: jsonl | table", "jsonl")
+    .option("--home <path>", "Override home for local DB root (tests)")
+    .option("--stdin", "Read SQL from stdin", false)
+    .argument("[sql...]", "SQL statement (or use --stdin / pipe)")
+    .action(
+      async (
+        sqlParts: string[],
+        opts: {
+          company: string;
+          write?: boolean;
+          remote?: boolean;
+          dbPath?: string;
+          allowCrossCompanyPath?: boolean;
+          format?: string;
+          home?: string;
+          stdin?: boolean;
+        },
+      ) => {
+        try {
+          const company = String(opts.company ?? "").trim();
+          if (!company) {
+            console.error(chalk.red("Error: --company is required"));
+            process.exitCode = 1;
+            return;
+          }
+
+          const sql = readSqlArg(sqlParts, !!opts.stdin).trim();
+          const format =
+            opts.format === "table" ? ("table" as const) : ("jsonl" as const);
+
+          if (opts.remote) {
+            // Local and remote are not auto-replicated (v1 limitation).
+            const remoteResult = await runRemoteSql({
+              company,
+              sql,
+              getConnectionConfig: async () => {
+                throw new Error("no remote binding");
+              },
+            });
+            console.log(
+              formatSqlResult(
+                {
+                  columns:
+                    remoteResult.rows[0]
+                      ? Object.keys(remoteResult.rows[0])
+                      : [],
+                  rows: remoteResult.rows,
+                  changes: 0,
+                  readonly: true,
+                },
+                format,
+              ),
+            );
+            return;
+          }
+
+          const result = runLocalSql({
+            company,
+            sql,
+            write: !!opts.write,
+            dbPathOverride: opts.dbPath,
+            allowCrossCompanyPath: !!opts.allowCrossCompanyPath,
+            format,
+            ...(opts.home ? { home: opts.home } : {}),
+          });
+
+          console.log(formatSqlResult(result, format));
+        } catch (error) {
+          console.error(
+            chalk.red("Error:"),
+            error instanceof Error ? error.message : "Unknown error",
+          );
+          process.exitCode = 1;
+        }
+      },
+    );
+}

package/src/commands/db-status.ts

@@ -0,0 +1,100 @@
+/**
+ * hq db status — ensure local vault DB exists and report health.
+ * Optionally reports remote tier when control plane returns a binding (US-009).
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+
+import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
+import {
+  ensureAndStatusLocalDb,
+  formatLocalDbStatus,
+} from "../lib/db/local.js";
+
+export function registerDbStatusCommand(db: Command): void {
+  db.command("status")
+    .description(
+      "Show local (and remote when bound) vault DB status; auto-creates local SQLite if missing",
+    )
+    .requiredOption(
+      "--company <slug>",
+      "Company slug (tenant scope; required)",
+    )
+    .option(
+      "--home <path>",
+      "Override home directory for local DB root (tests / advanced only)",
+    )
+    .option(
+      "--remote",
+      "Also query control plane for remote tier status (requires auth)",
+      false,
+    )
+    .option("--company-uid <uid>", "Company uid for remote status (with --remote)")
+    .action(
+      async (opts: {
+        company: string;
+        home?: string;
+        remote?: boolean;
+        companyUid?: string;
+      }) => {
+        try {
+          const company = String(opts.company ?? "").trim();
+          if (!company) {
+            console.error(chalk.red("Error: --company is required"));
+            process.exitCode = 1;
+            return;
+          }
+
+          const status = ensureAndStatusLocalDb(
+            company,
+            opts.home ? { home: opts.home } : undefined,
+          );
+
+          // Never print remote connection material.
+          console.log(formatLocalDbStatus(status));
+
+          if (opts.remote) {
+            const companyUid = opts.companyUid || `cmp_${company}`;
+            const baseUrl =
+              process.env.HQ_API_BASE_URL ||
+              process.env.HQ_CLOUD_API_URL ||
+              "https://hqapi.getindigo.ai";
+            try {
+              const client = new ControlPlaneDbClient({
+                baseUrl,
+                getAccessToken: async () => {
+                  if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
+                    return "mock-token";
+                  }
+                  throw new Error("auth required for remote status");
+                },
+              });
+              const remote = await client.status(companyUid);
+              if (!remote.remote) {
+                console.log("remote: (none)");
+              } else {
+                console.log(`remote: ${remote.remote.status}`);
+                console.log(`remoteEngine: ${remote.remote.engineId}`);
+                console.log(`remoteRegion: ${remote.remote.region}`);
+                console.log(`remoteResourceArn: ${remote.remote.resourceArn}`);
+              }
+            } catch (e) {
+              const msg = e instanceof Error ? e.message : "remote status failed";
+              console.log(`remote: error (${msg})`);
+            }
+          }
+
+          if (!status.healthy) {
+            process.exitCode = 1;
+          }
+        } catch (error) {
+          console.error(
+            chalk.red("Error:"),
+            error instanceof Error ? error.message : "Unknown error",
+          );
+          process.exitCode = 1;
+        }
+      },
+    );
+}

package/src/commands/db.ts

@@ -0,0 +1,26 @@
+/**
+ * hq db — vault database commands (local + remote tiers).
+ */
+
+import { Command } from "commander";
+
+import { registerDbMigrateCommand } from "./db-migrate.js";
+import { registerDbProvisionCommand } from "./db-provision.js";
+import { registerDbSqlCommand } from "./db-sql.js";
+import { registerDbStatusCommand } from "./db-status.js";
+
+/**
+ * Register the `hq db` command group and its subcommands.
+ */
+export function registerDbCommand(program: Command): void {
+  const db = program
+    .command("db")
+    .description(
+      "Vault databases — local SQLite per company and HQ-managed remote Postgres-class DBs",
+    );
+
+  registerDbStatusCommand(db);
+  registerDbSqlCommand(db);
+  registerDbMigrateCommand(db);
+  registerDbProvisionCommand(db);
+}

package/src/commands/integrations.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Unit tests for `hq integrations list|tools|call|approve` (integrations.ts).
+ *
+ * Coverage:
+ *   - toolPrefixForProvider — factory-prefix stripping + slug normalization
+ *     (must mirror hq-pro's factoryToolPrefix so composed HQ tool names hit
+ *     registered gateway tools)
+ *   - selectConnection — by id, by provider (factory:-prefixed match),
+ *     single-active default, and the guiding errors for none/ambiguous
+ *   - unwrapGatewayResult — MCP text-content unwrapping + non-JSON fallback
+ *   - queued-outcome detection + the approve hint in `call`
+ *   - approve — posts to the confirm route and prints the unwrapped result
+ */
+
+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,
+    ensureCognitoIdToken: vi.fn(async () => "test-id-token"),
+  };
+});
+
+vi.mock("../utils/vault-api.js", async (importOriginal) => {
+  const original = await importOriginal<typeof import("../utils/vault-api.js")>();
+  return {
+    ...original,
+    getCompanyUid: vi.fn(async () => "cmp_acme"),
+    vaultApiFetch: vi.fn(),
+  };
+});
+
+import { vaultApiFetch } from "../utils/vault-api.js";
+import {
+  IntegrationsCliError,
+  queuedOutcome,
+  registerIntegrationsCommand,
+  selectConnection,
+  toolPrefixForProvider,
+  unwrapGatewayResult,
+} from "./integrations.js";
+
+const vaultApiFetchMock = vi.mocked(vaultApiFetch);
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  } as unknown as Response;
+}
+
+function connectionsResponse() {
+  return jsonResponse({
+    connections: [
+      {
+        id: "acct_factory_linear",
+        provider: "factory:linear",
+        status: "connected",
+        writePolicy: "confirm",
+        installation: { displayName: "Linear MCP server", status: "installed" },
+      },
+    ],
+  });
+}
+
+function gatewayTextResponse(payload: unknown) {
+  return jsonResponse({
+    jsonrpc: "2.0",
+    id: "x",
+    result: { content: [{ type: "text", text: JSON.stringify(payload) }] },
+  });
+}
+
+async function runCli(argv: string[]): Promise<void> {
+  const program = new Command();
+  program.exitOverride();
+  registerIntegrationsCommand(program);
+  await program.parseAsync(["node", "hq", ...argv]);
+}
+
+let logSpy: MockInstance;
+beforeEach(() => {
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+});
+afterEach(() => {
+  vi.clearAllMocks();
+  logSpy.mockRestore();
+});
+
+function logged(): string {
+  return logSpy.mock.calls.map((call) => call.join(" ")).join("\n");
+}
+
+describe("toolPrefixForProvider", () => {
+  it("strips the factory: prefix and normalizes to the gateway's tool prefix", () => {
+    expect(toolPrefixForProvider("factory:linear")).toBe("linear");
+    expect(toolPrefixForProvider("factory:google-workspace")).toBe("google.workspace");
+    expect(toolPrefixForProvider("Linear")).toBe("linear");
+  });
+});
+
+describe("selectConnection", () => {
+  const linear = {
+    id: "acct_1",
+    provider: "factory:linear",
+    status: "connected",
+  };
+  const notion = {
+    id: "acct_2",
+    provider: "factory:notion",
+    status: "connected",
+  };
+
+  it("matches --provider against the bare factory slug", () => {
+    expect(selectConnection([linear, notion], { provider: "linear" })).toBe(linear);
+  });
+
+  it("defaults to the single active connection", () => {
+    expect(selectConnection([linear], {})).toBe(linear);
+  });
+
+  it("guides on ambiguity and on unknown providers", () => {
+    expect(() => selectConnection([linear, notion], {})).toThrow(/--provider/);
+    expect(() => selectConnection([linear], { provider: "jira" })).toThrow(
+      /Connected: linear/,
+    );
+    expect(() => selectConnection([], {})).toThrow(/No connected apps yet/);
+  });
+
+  it("resolves an explicit connection id even when revoked", () => {
+    const revoked = { ...linear, status: "revoked" };
+    expect(selectConnection([revoked], { connection: "acct_1" })).toBe(revoked);
+    expect(() => selectConnection([revoked], { connection: "acct_9" })).toThrow(
+      IntegrationsCliError,
+    );
+  });
+});
+
+describe("unwrapGatewayResult + queuedOutcome", () => {
+  it("unwraps MCP text content into the inner JSON payload", () => {
+    expect(
+      unwrapGatewayResult({
+        content: [{ type: "text", text: '{"tools":[{"name":"list_issues"}]}' }],
+      }),
+    ).toEqual({ tools: [{ name: "list_issues" }] });
+  });
+
+  it("falls back to raw text / raw result on non-JSON shapes", () => {
+    expect(
+      unwrapGatewayResult({ content: [{ type: "text", text: "plain" }] }),
+    ).toBe("plain");
+    expect(unwrapGatewayResult({ other: 1 })).toEqual({ other: 1 });
+  });
+
+  it("detects the queued-for-approval outcome", () => {
+    expect(
+      queuedOutcome({ queuedForApproval: true, queueId: "cq_1" }),
+    ).toMatchObject({ queueId: "cq_1" });
+    expect(queuedOutcome({ issues: [] })).toBeNull();
+  });
+});
+
+describe("hq integrations tools", () => {
+  it("composes the read tool name from the connection's provider and lists upstream tools", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        gatewayTextResponse({
+          tools: [{ name: "list_issues", title: "List issues" }],
+        }),
+      );
+
+    await runCli(["integrations", "tools", "--provider", "linear"]);
+
+    const gatewayCall = vaultApiFetchMock.mock.calls[1]![0];
+    expect(gatewayCall).toMatchObject({
+      path: "/v1/integrations/mcp",
+      method: "POST",
+    });
+    expect(gatewayCall.body).toMatchObject({
+      method: "tools/call",
+      params: {
+        companyUid: "cmp_acme",
+        name: "linear.mcp.tools.list",
+        arguments: { companyUid: "cmp_acme", connectionId: "acct_factory_linear" },
+      },
+    });
+    expect(logged()).toContain("list_issues");
+  });
+});
+
+describe("hq integrations call", () => {
+  it("sends the upstream tool + args + idempotency key and prints the result", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(gatewayTextResponse({ issues: [{ id: "DEV-1" }] }));
+
+    await runCli([
+      "integrations",
+      "call",
+      "list_issues",
+      "--provider",
+      "linear",
+      "--args",
+      '{"assignee":"me"}',
+      "--idempotency-key",
+      "stable-key",
+    ]);
+
+    const gatewayCall = vaultApiFetchMock.mock.calls[1]![0];
+    expect(gatewayCall.body).toMatchObject({
+      params: {
+        name: "linear.mcp.tools.call",
+        arguments: {
+          toolName: "list_issues",
+          arguments: { assignee: "me" },
+          idempotencyKey: "stable-key",
+        },
+      },
+    });
+    expect(logged()).toContain("DEV-1");
+  });
+
+  it("surfaces a queued outcome with the exact approve command", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        gatewayTextResponse({
+          queuedForApproval: true,
+          status: "queued",
+          queueId: "cq_123",
+          connectionId: "acct_factory_linear",
+        }),
+      );
+
+    await runCli([
+      "integrations",
+      "call",
+      "save_issue",
+      "--provider",
+      "linear",
+      "--args",
+      "{}",
+    ]);
+
+    const output = logged();
+    expect(output).toContain("Queued for approval");
+    expect(output).toContain("hq integrations approve cq_123 --provider linear");
+  });
+
+  it("rejects non-object --args with a usage hint", async () => {
+    await expect(
+      runCli(["integrations", "call", "t", "--provider", "linear", "--args", "[1]"]),
+    ).rejects.toThrow(/--args must be a JSON object/);
+    expect(vaultApiFetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("hq integrations approve", () => {
+  it("posts the decision to the confirm route and prints the unwrapped result", async () => {
+    vaultApiFetchMock
+      .mockResolvedValueOnce(connectionsResponse())
+      .mockResolvedValueOnce(
+        jsonResponse({
+          status: "resumed",
+          result: { content: [{ type: "text", text: '{"issues":[]}' }] },
+        }),
+      );
+
+    await runCli(["integrations", "approve", "cq_123", "--provider", "linear"]);
+
+    const confirmCall = vaultApiFetchMock.mock.calls[1]![0];
+    expect(confirmCall).toMatchObject({
+      path: "/v1/integrations/confirm/cq_123/approve",
+      method: "POST",
+      body: { companyUid: "cmp_acme", connectionId: "acct_factory_linear" },
+    });
+    expect(logged()).toContain("Approved");
+  });
+});