@indigoai-us/hq-cli 5.345.31 → 5.345.32

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+## [5.345.32] — 2026-10-06
+- `hq integrations list --usable` lists only the apps you can use right now: connected, shared with you under the same access rule the HQ gateway applies, and backed by a provider the gateway has registered. Each row shows the app name, its website domain, and the flag that selects exactly that connection in `hq integrations tools` and `call` (`--provider <slug>`, or `--connection <id>` when two connections share a provider). `--json` returns `{companyUid, viewerAccessKnown, apps}`. `--no-login` makes `list` fail instead of opening a browser sign-in, for hooks and scripts.
+
 ## [5.345.31] — 2026-10-06
 - HQ Anywhere commands now require both the operator runtime switch and the signed-in person's `hq-anywhere` setting. `hq doctor` reports the setting state and access stays off when it cannot be read.
 

package/dist/command-catalog.generated.d.ts

@@ -4054,6 +4054,14 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--json";
             readonly description: "Machine-readable output";
             readonly hidden: false;
+        }, {
+            readonly flags: "--usable";
+            readonly description: "Only apps you can use right now (connected and shared with you), with the --provider value to call them";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--no-login";
+            readonly description: "Fail instead of opening a browser sign-in when there is no HQ session";
+            readonly hidden: false;
         }];
         readonly subcommands: readonly [];
     }, {

package/dist/command-catalog.generated.js

@@ -4897,6 +4897,16 @@ export const COMMAND_CATALOG = [
                         "flags": "--json",
                         "description": "Machine-readable output",
                         "hidden": false
+                    },
+                    {
+                        "flags": "--usable",
+                        "description": "Only apps you can use right now (connected and shared with you), with the --provider value to call them",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--no-login",
+                        "description": "Fail instead of opening a browser sign-in when there is no HQ session",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []

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

@@ -225,6 +225,46 @@ export declare function toolPrefixForProvider(provider: string): string;
  */
 export declare function fetchAdminSurface(token: string, companyUid: string): Promise<AdminSurface>;
 export declare function fetchConnections(token: string, companyUid: string): Promise<AdminConnection[]>;
+/**
+ * One app the caller can use right now through the HQ gateway. Field names
+ * follow the bot `company_apps` projection (name, provider, domain, status),
+ * so session context and bot context describe an app the same way. No
+ * endpoint URLs, credentials, scopes, or creator identities.
+ */
+export interface UsableApp {
+    connectionId: string;
+    /** Display name, stripped of control characters and capped in length. */
+    name: string;
+    provider: string;
+    domain: string | null;
+    status: string;
+    /** Bare provider slug, e.g. `notion`. */
+    providerArg: string;
+    /**
+     * The flag that resolves to exactly this connection in `hq integrations
+     * tools|call`: `--provider <slug>` when no other active row shares the
+     * provider, else `--connection <id>`.
+     */
+    selector: string;
+}
+export interface UsableAppsResult {
+    companyUid: string;
+    /**
+     * False when the server ignored `view=summary` (an older deploy). Its rows
+     * carry no `viewerAccess`, so nothing can be confirmed usable and `apps` is
+     * empty rather than guessed.
+     */
+    viewerAccessKnown: boolean;
+    apps: UsableApp[];
+}
+/**
+ * The apps the caller may use, from `GET /v1/integrations/admin?view=summary`.
+ * A row counts only when all of these hold, mirroring the gateway's checks:
+ * the server's per-caller ACL decision (`viewerAccess.usable`) is true, the
+ * status is one the gateway serves, and the gateway has a provider registered
+ * for it. Fails closed: a row without `viewerAccess` is not listed.
+ */
+export declare function fetchUsableApps(token: string, companyUid: string): Promise<UsableAppsResult>;
 /**
  * Resolve one connection by `--connection acct_…` or `--provider linear`
  * (matches `factory:<slug>`, bare provider ids, and an installation's human

package/dist/commands/integrations-core.js

@@ -355,6 +355,96 @@ export async function fetchAdminSurface(token, companyUid) {
 export async function fetchConnections(token, companyUid) {
     return (await fetchAdminSurface(token, companyUid)).connections;
 }
+/**
+ * Statuses the gateway serves. `needs-attention` is derived by the summary
+ * view from a stored `connected` row whose token renewal is failing, so the
+ * gateway still dispatches to it.
+ */
+const GATEWAY_SERVED_STATUSES = new Set(["connected", "needs-attention"]);
+/**
+ * Providers hq-pro registers statically (`createIntegrationProviderRegistry`).
+ * Every other provider is registered per company from a factory installation
+ * keyed by its `runtimeProviderId`; a connection with neither is refused by the
+ * gateway as `ProviderUnsupported`.
+ */
+const STATIC_GATEWAY_PROVIDERS = new Set(["google-workspace", "linear", "slack"]);
+const MAX_APP_NAME_LENGTH = 60;
+/**
+ * Display names are set by whoever installed the app and end up in agent
+ * context, so keep them to one short line of printable text.
+ */
+function safeAppName(raw, fallback) {
+    const cleaned = (raw ?? "")
+        .replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleaned)
+        return fallback;
+    const chars = Array.from(cleaned);
+    return chars.length > MAX_APP_NAME_LENGTH
+        ? `${chars.slice(0, MAX_APP_NAME_LENGTH - 1).join("").trimEnd()}…`
+        : cleaned;
+}
+/** Case-insensitive code-point order, so the list reads the same in every locale. */
+function compareNames(a, b) {
+    const x = a.toLowerCase();
+    const y = b.toLowerCase();
+    return x < y ? -1 : x > y ? 1 : 0;
+}
+function gatewayHasProvider(row) {
+    if (STATIC_GATEWAY_PROVIDERS.has(row.provider))
+        return true;
+    return row.installation?.runtimeProviderId === row.provider;
+}
+/**
+ * The apps the caller may use, from `GET /v1/integrations/admin?view=summary`.
+ * A row counts only when all of these hold, mirroring the gateway's checks:
+ * the server's per-caller ACL decision (`viewerAccess.usable`) is true, the
+ * status is one the gateway serves, and the gateway has a provider registered
+ * for it. Fails closed: a row without `viewerAccess` is not listed.
+ */
+export async function fetchUsableApps(token, companyUid) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/admin",
+        query: { companyUid, view: "summary" },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to list integrations");
+    const data = (await res.json());
+    const viewerAccessKnown = data.view === "summary";
+    const rows = Array.isArray(data.connections) ? data.connections : [];
+    // `--provider` picks the first non-revoked row with that provider, whoever
+    // may use it, so a shared provider needs `--connection` to be exact.
+    const activeByProvider = new Map();
+    for (const row of rows) {
+        if (row.status === "revoked")
+            continue;
+        const key = bareProvider(row.provider).toLowerCase();
+        activeByProvider.set(key, (activeByProvider.get(key) ?? 0) + 1);
+    }
+    const apps = viewerAccessKnown
+        ? rows
+            .filter((row) => row.viewerAccess?.usable === true &&
+            GATEWAY_SERVED_STATUSES.has(row.status) &&
+            gatewayHasProvider(row))
+            .map((row) => {
+            const providerArg = bareProvider(row.provider);
+            const shared = (activeByProvider.get(providerArg.toLowerCase()) ?? 0) > 1;
+            return {
+                connectionId: row.id,
+                name: safeAppName(row.installation?.displayName, providerArg),
+                provider: row.provider,
+                domain: typeof row.domain === "string" && row.domain ? row.domain : null,
+                status: row.status,
+                providerArg,
+                selector: shared ? `--connection ${row.id}` : `--provider ${providerArg}`,
+            };
+        })
+            .sort((a, b) => compareNames(a.name, b.name))
+        : [];
+    return { companyUid: data.companyUid ?? companyUid, viewerAccessKnown, apps };
+}
 /**
  * Resolve one connection by `--connection acct_…` or `--provider linear`
  * (matches `factory:<slug>`, bare provider ids, and an installation's human

package/dist/commands/integrations.d.ts

@@ -51,8 +51,8 @@
  */
 import { Command } from "commander";
 import { type PendingApproval } from "./integrations-api.js";
-export { IntegrationsCliError, callGateway, fetchConnections, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
-export type { AdminConnection } from "./integrations-core.js";
+export { IntegrationsCliError, callGateway, fetchConnections, fetchUsableApps, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
+export type { AdminConnection, UsableApp, UsableAppsResult } from "./integrations-core.js";
 /** Wait for a decided queue item without resending the approve request. */
 export declare function waitForApprovalTerminal(token: string, companyUid: string, queueId: string, options?: {
     timeoutMs?: number;

package/dist/commands/integrations.js

@@ -54,12 +54,12 @@ import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { redactSensitiveUrl, redactSensitiveUrls, redactUrlsInText } from "../utils/redact-url.js";
-import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, fetchUsableApps, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
 import { registerConnectCommands } from "./integrations-connect.js";
 import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
 import { fetchPendingApprovals } from "./integrations-api.js";
-export { IntegrationsCliError, callGateway, fetchConnections, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
+export { IntegrationsCliError, callGateway, fetchConnections, fetchUsableApps, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
 /**
  * Gateway metadata is additive and may be absent when talking to an older
  * gateway. Parse it defensively so an unknown or malformed value never breaks
@@ -220,9 +220,33 @@ export function registerIntegrationsCommand(program) {
         .description("List the company's connected apps")
         .option("--company <slug>", "Company slug, e.g. indigo (defaults to your single active company)")
         .option("--json", "Machine-readable output")
+        .option("--usable", "Only apps you can use right now (connected and shared with you), with the --provider value to call them")
+        .option("--no-login", "Fail instead of opening a browser sign-in when there is no HQ session")
         .action(async (opts) => {
-        const token = await ensureCognitoIdToken();
+        const token = await ensureCognitoIdToken(opts.login === false ? { interactive: false } : {});
         const companyUid = await getCompanyUid(token, opts.company);
+        if (opts.usable) {
+            const result = await fetchUsableApps(token, companyUid);
+            if (opts.json) {
+                printJson(result);
+                return;
+            }
+            if (!result.viewerAccessKnown) {
+                console.log("This HQ server cannot report which apps are shared with you yet. Run `hq integrations list` to see every connected app.");
+                return;
+            }
+            if (result.apps.length === 0) {
+                console.log("No connected apps are available to you in this company. Run `hq integrations list` to see what is connected, or ask an admin to share one.");
+                return;
+            }
+            for (const app of result.apps) {
+                const where = app.domain ? ` (${app.domain})` : "";
+                const flag = app.status === "needs-attention" ? chalk.yellow("  needs attention") : "";
+                console.log(`${chalk.bold(app.name)}${chalk.dim(where)}${flag}`);
+                console.log(chalk.dim(`  hq integrations tools ${app.selector}`));
+            }
+            return;
+        }
         const connections = await fetchConnections(token, companyUid);
         if (opts.json) {
             printJson(connections);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.31",
+  "version": "5.345.32",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {