@indigoai-us/hq-cli 5.101.7 → 5.102.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## [Unreleased]
 
+## [5.102.0] — 2026-08-17
+
+### Added
+
+- **`hq integrations` now covers the whole lifecycle**, not just using an
+  already-connected app. Previously the CLI could `list` / `tools` / `call` /
+  `approve` / `reject`, and everything else had to happen on the console.
+
+  Find and add:
+  - `hq integrations catalog [query]` (alias `search`) — browse or search
+    connectable apps, showing each one's sign-in style and provenance.
+  - `hq integrations inspect <app>` — surfaces, credentials, and warnings for
+    an app before you commit to it.
+  - `hq integrations discover <docsUrl>` — find a connectable server from a
+    documentation page.
+  - `hq integrations connect <app>` (alias `add`) — connect by domain, catalog
+    entry (`--entry-id`), docs page (`--docs-url`), or a raw endpoint
+    (`--mcp-url`). Auth mode is detected rather than declared: no-auth installs
+    directly, API-key apps read the key from `--token-stdin` / a hidden prompt
+    / `--token`, and OAuth apps run a browser sign-in. If hq-pro answers
+    `INTEGRATION_FACTORY_OAUTH_REQUIRED` to a direct install, the browser flow
+    starts automatically.
+  - `hq integrations reconnect [app]` — re-authenticate an app whose stored
+    credentials stopped working.
+
+  Govern and remove:
+  - `hq integrations show [app]` — one connection in full.
+  - `hq integrations policy [app] [--set auto-allow|confirm|deny]`.
+  - `hq integrations grants|grant|ungrant` — per-tool approval exceptions.
+  - `hq integrations access|share|unshare` — who in the company may use an app.
+  - `hq integrations audit` / `pending` — recent activity and queued approvals.
+  - `hq integrations disconnect [app]` (alias `remove`) — deletes stored
+    credentials; confirms first, and refuses non-interactively without `--yes`.
+
+  OAuth sign-in uses an RFC 8252 §7.3 loopback listener (`127.0.0.1`, ephemeral
+  port, pinned callback path), so the code never leaves the machine and the
+  PKCE verifier stays server-side in hq-pro. Against a backend that does not
+  admit a loopback callback, connect degrades to printing the sign-in URL for
+  the console to finish, and says so rather than reporting a false success.
+
+  Requires hq-pro with `INTEGRATION_FACTORY_OAUTH_LOOPBACK_ENABLED` for the
+  fully CLI-native OAuth path; every other verb works against any current
+  deployment.
+
 ## [5.101.7] — 2026-08-17
 
 ### Changed

package/dist/commands/integrations-api.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Typed client for hq-pro's integration-factory routes.
+ *
+ * One function per endpoint, each a thin `vaultApiFetch` + `raiseForResponse`
+ * pair. The wire shapes below MIRROR hq-pro (`src/vault-service/handlers/
+ * integrations-admin.ts`) rather than importing from it — hq-cli takes no
+ * cross-repo source dependency — so every field a newer backend might not emit
+ * is optional and read defensively.
+ */
+import { type GranteeType, type Permission, type WriteAllowlistGrant, type WritePolicy } from "./integrations-core.js";
+export interface CatalogEntry {
+    name: string;
+    domain: string;
+    description?: string;
+    /** True when the app is one-click connectable (has a remote MCP surface). */
+    mcpReady: boolean;
+    scope?: "company" | "global";
+    /**
+     * Provenance: `integrations.sh` is the curated third-party feed,
+     * `hq-recommended` is first-party, `hq-discovered` is a Community definition
+     * learned from a successful connect elsewhere.
+     */
+    source?: "hq-discovered" | "integrations.sh" | "hq-recommended";
+    authClass?: "none" | "key" | "oauth";
+    /** Opaque server-owned id; prefer it over echoing connection details back. */
+    entryId?: string;
+}
+export declare function listCatalog(token: string, companyUid: string, opts?: {
+    limit?: number;
+    query?: string;
+}): Promise<CatalogEntry[]>;
+export interface BlueprintSurface {
+    kind: string;
+    slug: string;
+    name: string;
+    url?: string;
+    docs?: string;
+    authStatus: "required" | "optional" | "none" | "unknown";
+    credentialIds: string[];
+    readiness: {
+        strategy: string;
+        score: number;
+        reason: string;
+    };
+}
+export interface Blueprint {
+    provider: string;
+    displayName: string;
+    domain: string;
+    summary?: string;
+    description?: string;
+    credentials: Array<{
+        id: string;
+        type: string;
+        label: string;
+        generateUrl?: string;
+    }>;
+    surfaces: BlueprintSurface[];
+    recommendedSurface?: BlueprintSurface;
+    warnings: Array<{
+        code: string;
+        message: string;
+        source?: string;
+    }>;
+}
+export declare function pullBlueprint(token: string, companyUid: string, input: {
+    domain?: string;
+    query?: string;
+    catalogEntryId?: string;
+}): Promise<Blueprint>;
+export interface DocsDiscovery {
+    docsUrl: string;
+    displayName: string;
+    provider: string;
+    mcpUrl: string;
+    authMode: "none" | "bearer" | "oauth";
+    transport: string;
+    verification: "verified" | "pending-auth";
+    confidence: "high" | "medium";
+    evidenceUrls: string[];
+}
+export interface DiscoverDocsResult {
+    /** Absent when hq-pro verified no MCP surface on the page. */
+    discovery?: DocsDiscovery;
+    /**
+     * Caller- and company-bound continuation token. Passing this to connect is
+     * what lets hq-pro trust the endpoint WITHOUT re-reading a URL the terminal
+     * echoed back at it. Short-lived (~15 min).
+     */
+    discoveryReceiptId?: string;
+    sourceTruncated?: boolean;
+}
+export declare function discoverDocs(token: string, companyUid: string, docsUrl: string): Promise<DiscoverDocsResult>;
+export interface InstallResult {
+    connection: {
+        id: string;
+        provider: string;
+        status: string;
+        scopes?: string[];
+    };
+    installation: {
+        id: string;
+        displayName: string;
+        domain: string;
+        status: "installed" | "needs_credentials";
+        surface?: {
+            kind?: string;
+            url?: string;
+            authStatus?: string;
+        };
+    };
+    mcp?: {
+        tools?: Array<{
+            name: string;
+            description?: string;
+            mode?: string;
+        }>;
+    };
+    credential?: {
+        required: boolean;
+        configured: boolean;
+        authStatus?: string;
+    };
+    writeAllowlist?: WriteAllowlistGrant[];
+}
+export interface InstallInput {
+    domain?: string;
+    query?: string;
+    catalogEntryId?: string;
+    discoveryReceiptId?: string;
+    mcpUrl?: string;
+    provider?: string;
+    displayName?: string;
+    docsUrl?: string;
+    authMode?: "none" | "bearer";
+    bearerToken?: string;
+}
+export declare function installIntegration(token: string, companyUid: string, input: InstallInput): Promise<InstallResult>;
+export declare function uninstallIntegration(token: string, companyUid: string, installationId: string): Promise<{
+    installationId: string;
+    connectionId: string;
+}>;
+export interface OAuthStartResult {
+    provider: string;
+    displayName: string;
+    /** The remote auth server's authorize URL — open this in a browser. */
+    authorizationUrl: string;
+    state: string;
+    expiresAt: string;
+}
+export interface OAuthStartInput {
+    mcpUrl?: string;
+    catalogEntryId?: string;
+    discoveryReceiptId?: string;
+    provider?: string;
+    displayName?: string;
+    domain?: string;
+    docsUrl?: string;
+    /**
+     * The native client's loopback callback. hq-pro accepts it only when its
+     * loopback flag is on and the URI matches the pinned RFC 8252 §7.3 shape;
+     * omitting it pins the console callback instead.
+     */
+    redirectUri?: string;
+}
+export declare function startOAuth(token: string, companyUid: string, input: OAuthStartInput): Promise<OAuthStartResult>;
+export declare function completeOAuth(token: string, companyUid: string, input: {
+    state: string;
+    code: string;
+}): Promise<InstallResult>;
+export declare function updateGovernance(token: string, companyUid: string, input: {
+    connectionId: string;
+    writePolicy?: WritePolicy;
+    /**
+     * REPLACES the connection's whole per-tool allowlist — hq-pro has no
+     * add/remove verb. Callers must read the current list, merge, and send the
+     * full result, never a delta.
+     */
+    writeAllowlist?: WriteAllowlistGrant[];
+}): Promise<{
+    writePolicy?: WritePolicy;
+    writeAllowlist: WriteAllowlistGrant[];
+}>;
+export interface ConnectionAccess {
+    connectionId: string;
+    provider: string;
+    creator: {
+        uid: string;
+        name?: string | null;
+    };
+    /** True when the connection predates access control and has no ACL row. */
+    grandfathered: boolean;
+    /** Whether THIS caller may grant/revoke. */
+    canManage: boolean;
+    access: {
+        mode: string;
+        grantCount: number;
+    };
+    entries: Array<{
+        granteeType: GranteeType;
+        granteeId: string;
+        granteeName?: string | null;
+        permission: Permission;
+        grantedBy: string;
+        grantedByName?: string | null;
+        grantedAt: string;
+    }>;
+}
+export declare function getConnectionAccess(token: string, companyUid: string, connectionId: string): Promise<ConnectionAccess>;
+export declare function mutateConnectionAccess(token: string, companyUid: string, action: "grant" | "revoke", input: {
+    connectionId: string;
+    granteeType: GranteeType;
+    granteeId?: string;
+    permission?: Permission;
+}): Promise<ConnectionAccess>;
+//# sourceMappingURL=integrations-api.d.ts.map

package/dist/commands/integrations-api.js

@@ -0,0 +1,135 @@
+/**
+ * Typed client for hq-pro's integration-factory routes.
+ *
+ * One function per endpoint, each a thin `vaultApiFetch` + `raiseForResponse`
+ * pair. The wire shapes below MIRROR hq-pro (`src/vault-service/handlers/
+ * integrations-admin.ts`) rather than importing from it — hq-cli takes no
+ * cross-repo source dependency — so every field a newer backend might not emit
+ * is optional and read defensively.
+ */
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { raiseForResponse, } from "./integrations-core.js";
+export async function listCatalog(token, companyUid, opts = {}) {
+    const query = {
+        companyUid,
+        limit: String(opts.limit ?? 60),
+    };
+    // hq-pro bounds the query itself; normalize whitespace here so an
+    // accidentally padded shell argument doesn't read as a different search.
+    const q = (opts.query ?? "").replace(/\s+/g, " ").trim();
+    if (q)
+        query.query = q;
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/catalog",
+        query,
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to browse the app catalog");
+    const body = (await res.json());
+    return body.entries ?? [];
+}
+export async function pullBlueprint(token, companyUid, input) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/blueprint",
+        method: "POST",
+        body: { companyUid, ...input },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to inspect the app");
+    const body = (await res.json());
+    return body.blueprint;
+}
+export async function discoverDocs(token, companyUid, docsUrl) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/discover-docs",
+        method: "POST",
+        body: { companyUid, docsUrl },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to read that documentation page");
+    return (await res.json());
+}
+export async function installIntegration(token, companyUid, input) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/install",
+        method: "POST",
+        body: { companyUid, ...input },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to connect the app");
+    return (await res.json());
+}
+export async function uninstallIntegration(token, companyUid, installationId) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/uninstall",
+        method: "POST",
+        body: { companyUid, installationId },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to disconnect the app");
+    return (await res.json());
+}
+export async function startOAuth(token, companyUid, input) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/oauth/start",
+        method: "POST",
+        body: { companyUid, ...input },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to start sign-in");
+    return (await res.json());
+}
+export async function completeOAuth(token, companyUid, input) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/oauth/complete",
+        method: "POST",
+        body: { companyUid, ...input },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to finish sign-in");
+    return (await res.json());
+}
+/* ------------------------------------------------------------------ */
+/* Governance: write policy + per-tool grants                          */
+/* ------------------------------------------------------------------ */
+export async function updateGovernance(token, companyUid, input) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/admin",
+        method: "PATCH",
+        body: { companyUid, ...input },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to update the app's settings");
+    return (await res.json());
+}
+export async function getConnectionAccess(token, companyUid, connectionId) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/access",
+        query: { companyUid, connectionId },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to read who can use this app");
+    return (await res.json());
+}
+export async function mutateConnectionAccess(token, companyUid, action, input) {
+    const res = await vaultApiFetch({
+        token,
+        path: `/v1/integrations/factory/access/${action}`,
+        method: "POST",
+        body: { companyUid, ...input },
+    });
+    if (!res.ok) {
+        await raiseForResponse(res, action === "grant" ? "Failed to share the app" : "Failed to remove access");
+    }
+    return (await res.json());
+}
+//# sourceMappingURL=integrations-api.js.map

package/dist/commands/integrations-connect.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `hq integrations catalog | inspect | discover | connect | reconnect`.
+ *
+ * The add half of the lifecycle: find an app, look at what it exposes, and
+ * connect it. Connecting is the interesting one — an app authenticates in one
+ * of three ways and hq-cli should not make the caller work out which:
+ *
+ *   none    the MCP endpoint is anonymously callable → install directly
+ *   key     the endpoint wants a bearer token → take it from --token /
+ *           --token-stdin / a hidden prompt, never from argv history
+ *   oauth   the endpoint speaks OAuth 2.1 → run the RFC 8252 loopback flow
+ *
+ * Detection is server-authoritative and lazy. Rather than guessing from
+ * catalog metadata (which can be stale), the command attempts the direct
+ * install and treats hq-pro's `INTEGRATION_FACTORY_OAUTH_REQUIRED` as the
+ * signal to switch into the browser flow. That way a catalog row that says
+ * "key" but is really OAuth-protected still connects on the first try.
+ */
+import { Command } from "commander";
+/**
+ * Validate `--auth` against the supported enum, rejecting an unknown value
+ * before anything is installed. A finite provider/runtime option must never be
+ * narrowed by a truthy cast — an unrecognised mode has to fail loudly rather
+ * than fall through to a default.
+ */
+export declare function assertAuthMode(value: string | undefined): void;
+/** Single-quote a value for a copy-pasteable shell command. */
+export declare function shellQuote(value: string): string;
+export declare function registerConnectCommands(integrations: Command): void;
+//# sourceMappingURL=integrations-connect.d.ts.map