@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/integrations.ts

@@ -1,507 +0,0 @@
-/**
- * `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";
-import { AuthError } from "../utils/auth-error.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 {
-  /**
-   * 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;
-}
-
-// The integration gateway answers `POST /v1/integrations/mcp` JSON-RPC-style: a
-// transport failure is a non-2xx HTTP status, but a GOVERNED refusal arrives as
-// HTTP 200 carrying a JSON-RPC `error` object (mirrors hq-pro's
-// integration-mcp/server.ts error mapping). These caller-side codes are the
-// JSON-RPC analog of a client 4xx — the caller's request/state/permission,
-// expected and actionable, not an hq-cli defect — so they are printed to the
-// user and skipped for Sentry capture (HQ-CLI-B):
-//   -32003 UNAUTHORIZED   — connection-level access denial, e.g. the
-//                           "You do not have access to this integration. Ask its
-//                           owner to share it with you." (IntegrationAccessDenied)
-//                           that flooded Sentry, plus ConnectionNotFound / a
-//                           read-only share rejecting a write.
-//   -32602 INVALID_PARAMS — an unknown tool or unsupported provider for the
-//                           connection (a bad request the caller can correct).
-// Everything else stays unexpected so a genuine fault still reaches Sentry:
-// PROVIDER_ERROR (-32050, an upstream provider fault), INTERNAL_ERROR (-32603),
-// CONFLICT (-32009, which the gateway also raises for a confirm queue being
-// unavailable or an owner notification failing — real backend faults worth a
-// report), METHOD_NOT_FOUND / PARSE_ERROR, and any absent or unrecognized code.
-const EXPECTED_GATEWAY_ERROR_CODES = new Set<number>([-32003, -32602]);
-
-function isExpectedGatewayError(code: number | undefined): boolean {
-  return code != null && EXPECTED_GATEWAY_ERROR_CODES.has(code);
-}
-
-// 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
-    .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) {
-    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[] };
-  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.`,
-        { expected: true },
-      );
-    }
-    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."),
-        { expected: true },
-      );
-    }
-    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.",
-      { 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 },
-  );
-}
-
-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) {
-    raiseIfUnauthorized(res);
-    throw new IntegrationsCliError(
-      `Integration gateway request failed (HTTP ${res.status}).`,
-      { expected: isClientError(res.status) },
-    );
-  }
-  if (message.error) {
-    throw new IntegrationsCliError(
-      message.error.message ?? "Integration gateway returned an error.",
-      { expected: isExpectedGatewayError(message.error.code) },
-    );
-  }
-  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"}'`,
-            { expected: true },
-          );
-        }
-        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) {
-            raiseIfUnauthorized(res);
-            throw new IntegrationsCliError(
-              body.error ?? `${decision} failed (HTTP ${res.status})`,
-              { expected: isClientError(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/list.ts

@@ -1,85 +0,0 @@
-/**
- * hq modules list command (US-005)
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { Command } from 'commander';
-import { findHqRoot, readManifest, readLock, getModulesDir } from '../utils/manifest.js';
-import { isRepo, getCurrentCommit, isBehindRemote } from '../utils/git.js';
-
-export function registerListCommand(program: Command): void {
-  program
-    .command('list')
-    .alias('ls')
-    .description('List all modules and their status')
-    .action(async () => {
-      try {
-        const hqRoot = findHqRoot();
-        const manifest = readManifest(hqRoot);
-
-        if (!manifest || manifest.modules.length === 0) {
-          console.log('No modules in manifest. Use "hq modules add" to add modules.');
-          return;
-        }
-
-        const modulesDir = getModulesDir(hqRoot);
-        const lock = readLock(hqRoot);
-
-        console.log('Modules:\n');
-
-        for (const module of manifest.modules) {
-          console.log(`  ${module.name}`);
-
-          if (module.strategy === 'package') {
-            // hq-pack content pack — wired by scripts/scan-packages.sh
-            console.log(`    Strategy: package`);
-            console.log(`    Source:   ${module.source}`);
-            if (module.version) {
-              console.log(`    Version:  ${module.version}`);
-            }
-            if (module.installed_at) {
-              console.log(`    Path:     ${module.installed_at}`);
-            }
-            if (module.resolved_sha) {
-              console.log(`    SHA:      ${module.resolved_sha}`);
-            }
-            console.log();
-            continue;
-          }
-
-          // legacy git-repo module
-          const moduleDir = path.join(modulesDir, module.name);
-          const installed = await isRepo(moduleDir);
-
-          console.log(`    Repo:     ${module.repo}`);
-          console.log(`    Branch:   ${module.branch || 'main'}`);
-          console.log(`    Strategy: ${module.strategy}`);
-          console.log(`    Paths:    ${module.paths.map(p => `${p.src} -> ${p.dest}`).join(', ')}`);
-
-          if (installed) {
-            const commit = await getCurrentCommit(moduleDir);
-            const shortCommit = commit.slice(0, 7);
-            const lockedCommit = lock?.locked[module.name];
-            const isLocked = lockedCommit === commit;
-
-            console.log(`    Status:   ✓ installed @ ${shortCommit}${isLocked ? ' (locked)' : ''}`);
-
-            // Check if behind upstream
-            const { behind, commits } = await isBehindRemote(moduleDir);
-            if (behind) {
-              console.log(`    Updates:  ${commits} commit(s) behind remote`);
-            }
-          } else {
-            console.log(`    Status:   ✗ not installed`);
-          }
-
-          console.log();
-        }
-
-      } catch (error) {
-        console.error('Error:', error instanceof Error ? error.message : error);
-        process.exit(1);
-      }
-    });
-}

package/src/commands/login.ts

@@ -1,52 +0,0 @@
-/**
- * hq login — opens browser for Cognito auth.
- */
-
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { browserLogin, loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
-import { cognitoConfigForLoginProvider } from '../utils/login-provider.js';
-
-function peekIdToken(idToken: string): { email?: string; sub?: string } {
-  try {
-    const payload = idToken.split('.')[1];
-    if (!payload) return {};
-    const pad = payload.length % 4 === 0 ? '' : '='.repeat(4 - (payload.length % 4));
-    const normalized = payload.replace(/-/g, '+').replace(/_/g, '/') + pad;
-    const decoded = JSON.parse(Buffer.from(normalized, 'base64').toString('utf-8'));
-    return { email: decoded.email, sub: decoded.sub };
-  } catch {
-    return {};
-  }
-}
-
-export function registerLoginCommand(program: Command): void {
-  program
-    .command('login')
-    .description('Authenticate with HQ via Cognito')
-    .option(
-      '--provider <provider>',
-      'OAuth provider to use: google, microsoft, or picker',
-    )
-    .action(async (options: { provider?: string }) => {
-      try {
-        const existing = loadCachedTokens();
-        if (existing && !isExpiring(existing, 120)) {
-          const who = peekIdToken(existing.idToken).email ?? 'cached session';
-          console.log(chalk.green(`Already logged in as ${who}. Run \`hq logout\` to switch accounts.`));
-          return;
-        }
-
-        console.log('Opening browser for authentication...');
-        const tokens = await browserLogin(cognitoConfigForLoginProvider(options.provider));
-        const who = peekIdToken(tokens.idToken).email ?? 'HQ';
-        console.log(chalk.green(`Logged in as ${who}`));
-      } catch (error) {
-        console.error(
-          chalk.red('Login failed:'),
-          error instanceof Error ? error.message : 'Unknown error'
-        );
-        process.exit(1);
-      }
-    });
-}

package/src/commands/logout.ts

@@ -1,30 +0,0 @@
-/**
- * hq logout — clears cached Cognito session
- */
-
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { clearCachedTokens, loadCachedTokens } from '@indigoai-us/hq-cloud';
-
-export function registerLogoutCommand(program: Command): void {
-  program
-    .command('logout')
-    .description('Log out and clear cached credentials')
-    .action(async () => {
-      try {
-        const existing = loadCachedTokens();
-        if (!existing) {
-          console.log(chalk.yellow('No cached HQ session'));
-          return;
-        }
-        clearCachedTokens();
-        console.log(chalk.green('Logged out successfully'));
-      } catch (error) {
-        console.error(
-          chalk.red('Logout failed:'),
-          error instanceof Error ? error.message : 'Unknown error'
-        );
-        process.exit(1);
-      }
-    });
-}