@indigoai-us/hq-cli 5.109.0 → 5.109.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [5.109.2] — 2026-09-09
+
+### Fixed
+
+- `hq integrations connect <app>` now says so when the app is already
+  connected, instead of opening a browser and waiting for a sign-in that
+  changes nothing. It prints the reconnect command for re-authorizing the
+  existing connection, and `--force` still adds a second one. Across a
+  few-hundred-app sweep the old behavior read as a silent failure.
+
+  The check only short-circuits a connection that is genuinely finished. A row
+  whose installation is still at `needs_credentials`, `pending`, `error`, or
+  `revoked` falls through to the ordinary connect, because that connect is the
+  only thing that repairs those states. An installation status the CLI does not
+  recognize is treated the same way, so an unknown state costs a redundant
+  sign-in rather than a stranded integration.
+
+## [5.109.1] — 2026-09-08
+
+### Added
+
+- `hq access` records each outcome (outcome, company, timestamp only) to
+  `.hq/access-outcomes.jsonl` so the cause mix can be reviewed later.
+
 ## [5.109.0] — 2026-09-08
 
 ### Added

package/dist/commands/access.js

@@ -26,6 +26,7 @@ import { listActiveMembers } from "./members.js";
 import { buildDmBody } from "./dm.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { findRecentAccessRequest, formatTimeAgo, recordAccessRequest, } from "../utils/access-requests.js";
+import { recordAccessOutcome } from "../utils/access-outcomes.js";
 export function outcomeExitCode(outcome) {
     if (outcome === "local" || outcome === "not-synced")
         return 0;
@@ -146,7 +147,25 @@ function aclDenied(tree) {
     const perm = tree.effectivePermission;
     return perm === null || perm === "none" || perm === "deny";
 }
-function finish(outcome, fields) {
+/**
+ * Build the result and record one cause-mix telemetry line. Every exit path
+ * goes through here, so each run is recorded exactly once. The write is
+ * best-effort: a failure adds a step + one stderr warning and never changes
+ * the outcome or exit code. Only outcome, company, and timestamp are stored.
+ */
+function finish(outcome, fields, ctx) {
+    try {
+        recordAccessOutcome(ctx.hqRoot, {
+            outcome,
+            company: fields.company,
+            ts: new Date((ctx.now ?? Date.now)()).toISOString(),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        fields.steps.push(`telemetry: write failed — ${msg}`);
+        ctx.stderr(`warning: could not record access outcome telemetry: ${msg}`);
+    }
     return { outcome, exitCode: outcomeExitCode(outcome), ...fields };
 }
 export function resolveGrantor(tree, members) {
@@ -194,6 +213,7 @@ export async function runAccess(input) {
     const steps = [];
     const relative = normalizeTarget(input.target, slug);
     const anchored = (key) => `companies/${slug}/${key}`;
+    const finishCtx = { hqRoot: deps.hqRoot, now: deps.now, stderr };
     let vendDenied = false;
     try {
         await deps.vaultClient.sts.vend({ companyUid: deps.companyUid });
@@ -252,7 +272,7 @@ export async function runAccess(input) {
                 company: slug,
                 exists: false,
                 steps,
-            });
+            }, finishCtx);
             emit(input, result, log);
             return result;
         }
@@ -275,7 +295,7 @@ export async function runAccess(input) {
                     exists: false,
                     candidates,
                     steps,
-                });
+                }, finishCtx);
                 emit(input, result, log);
                 return result;
             }
@@ -511,7 +531,7 @@ export async function runAccess(input) {
         ...(requestSentAt ? { requestSentAt } : {}),
         ...(alreadyAskedAt ? { alreadyAskedAt } : {}),
         ...(requestNote ? { requestNote } : {}),
-    });
+    }, finishCtx);
     emit(input, result, log);
     return result;
 }

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

@@ -17,6 +17,7 @@
  * "key" but is really OAuth-protected still connects on the first try.
  */
 import { Command } from "commander";
+import type { AdminConnection } from "./integrations-core.js";
 /**
  * Validate `--auth` against the supported enum, rejecting an unknown value
  * before anything is installed. A finite provider/runtime option must never be
@@ -46,5 +47,6 @@ export declare function consoleOrigin(vaultApiUrl?: string): string | undefined;
  * by slug), or undefined when the console for this control plane is unknown.
  */
 export declare function consoleIntegrationsUrl(companySlug: string | undefined, origin: string | undefined): string | undefined;
+export declare function findAlreadyConnected(connections: readonly AdminConnection[], app: string): AdminConnection | undefined;
 export declare function registerConnectCommands(integrations: Command): void;
 //# sourceMappingURL=integrations-connect.d.ts.map

package/dist/commands/integrations-connect.js

@@ -20,7 +20,7 @@ import chalk from "chalk";
 import open from "open";
 import { DEFAULT_VAULT_API_URL, ensureCognitoIdToken, } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
-import { IntegrationsCliError, bareProvider, connectionDomain, printJson, revokedConnectionDetails, resolveConnection, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, connectionDomain, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, } from "./integrations-core.js";
 import { completeOAuth, discoverDocs, installIntegration, listCatalog, pullBlueprint, startOAuth, } from "./integrations-api.js";
 import { startLoopbackListener } from "./integrations-oauth.js";
 /** hq-pro's machine code for "this endpoint needs a browser sign-in". */
@@ -886,6 +886,115 @@ async function connectApp(token, companyUid, app, opts, expectedRevivedConnectio
         throw err;
     }
 }
+/**
+ * The connection `app` already names, if it is connected RIGHT NOW.
+ *
+ * `connect` used to start a fresh sign-in for an app that was already
+ * connected: it opened a browser, printed an authorize URL and waited, saying
+ * nothing about the connection already sitting there. Sweeping a few hundred
+ * apps, that reads as a silent failure — you approve a vendor a second time and
+ * get no acknowledgement that the first one exists.
+ *
+ * Only `status === "connected"` counts. A `needs-reauth`, `error` or `revoked`
+ * row is NOT a reason to refuse: those are exactly the rows a person runs this
+ * command to repair, and blocking them would strand the app.
+ *
+ * Matching is deliberately anchored on the app's own name. A connected
+ * `installation.domain` matches when it IS the app, or is a subdomain of it
+ * (`notion.com` is served by `mcp.notion.com`) — never the reverse, so an
+ * unrelated host can never be read as this app. The provider slug and display
+ * name are matched too, because `connect notion` and `connect notion.com` are
+ * the same request.
+ */
+/**
+ * Whether a row is finished enough that starting another sign-in would be
+ * redundant work rather than the repair the caller needs.
+ *
+ * `connection.status === "connected"` is NOT sufficient on its own. A row can
+ * be connected at the connection level while its installation still sits at
+ * `needs_credentials`, `pending`, `error`, or `revoked` — states whose ONLY
+ * remedy is the very connect the caller just asked for. Short-circuiting those
+ * would strand them: the command would report "already connected" about a thing
+ * that cannot be used, and the person would have no way to fix it.
+ *
+ * So this is an allowlist, not a denylist of known-bad states. An absent
+ * installation is treated as settled (a non-factory connection has no
+ * installation to be mid-flight), but any PRESENT status other than `installed`
+ * is treated as unfinished. A status this CLI has not heard of therefore falls
+ * through to the ordinary connect — the safe direction, since a redundant
+ * sign-in costs a browser round-trip while a wrong skip costs a broken
+ * integration with no visible path out.
+ */
+function isSettledInstallation(connection) {
+    const status = connection.installation?.status?.trim().toLowerCase();
+    return status === undefined || status === "" || status === "installed";
+}
+export function findAlreadyConnected(connections, app) {
+    const want = app.trim().toLowerCase();
+    if (want === "")
+        return undefined;
+    const wantSlug = displayNameSlug(want);
+    return connections.find((connection) => {
+        if (connection.status !== "connected")
+            return false;
+        if (!isSettledInstallation(connection))
+            return false;
+        const domain = (connectionDomain(connection) ?? "").toLowerCase();
+        if (domain === want || domain.endsWith(`.${want}`))
+            return true;
+        if (bareProvider(connection.provider).toLowerCase() === want)
+            return true;
+        const displayName = (connection.installation?.displayName ?? "").trim();
+        if (displayName === "")
+            return false;
+        if (displayName.toLowerCase() === want)
+            return true;
+        // `connect aws-marketplace` is the copy-pasteable form of the display name
+        // "AWS Marketplace", and it is what the catalog resolver already accepts.
+        // Compare on the same slug both ways or this check misses every app whose
+        // name has a space in it.
+        return wantSlug !== "" && displayNameSlug(displayName) === wantSlug;
+    });
+}
+/**
+ * Report an app as already connected instead of opening a second sign-in.
+ * Returns true when the connect should stop here.
+ */
+async function refuseIfAlreadyConnected(token, companyUid, app, opts) {
+    // Only a plain `connect <app>`. An explicit --mcp-url / --docs-url /
+    // --entry-id names an endpoint rather than an installed app, and --force is
+    // the deliberate "yes, add another one" escape hatch.
+    if (!app || opts.force || opts.mcpUrl || opts.docsUrl || opts.entryId)
+        return false;
+    let connections;
+    try {
+        connections = (await fetchAdminSurface(token, companyUid)).connections ?? [];
+    }
+    catch {
+        // Never let this convenience check block a connect. If the list cannot be
+        // read, fall through and let the real flow report whatever is wrong.
+        return false;
+    }
+    const existing = findAlreadyConnected(connections, app);
+    if (!existing)
+        return false;
+    const slug = bareProvider(existing.provider);
+    if (opts.json) {
+        printJson({
+            ok: true,
+            alreadyConnected: true,
+            provider: slug,
+            connection: existing.id,
+            ...(connectionDomain(existing) ? { domain: connectionDomain(existing) } : {}),
+        });
+        return true;
+    }
+    const label = existing.installation?.displayName ?? slug;
+    console.log(chalk.green(`${label} is already connected.`));
+    console.log(chalk.dim(`  Sign in again:  hq integrations reconnect --provider ${slug}\n` +
+        `  Add a second:   hq integrations connect ${shellQuote(app)} --force`));
+    return true;
+}
 export function registerConnectCommands(integrations) {
     integrations
         .command("catalog [query]")
@@ -1014,11 +1123,14 @@ export function registerConnectCommands(integrations) {
         .option("--scopes <list>", "Permissions to request, space- or comma-separated (default: what the app needs)")
         .option("--no-browser", "Print the sign-in URL instead of opening a browser")
         .option("--timeout <seconds>", "How long to wait for a browser sign-in (default 300)")
+        .option("--force", "Connect again even if this app is already connected")
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
         assertAuthMode(opts.auth);
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
+        if (await refuseIfAlreadyConnected(token, companyUid, app, opts))
+            return;
         await connectApp(token, companyUid, app, opts);
     });
     integrations

package/dist/utils/access-outcomes.d.ts

@@ -0,0 +1,23 @@
+import type { AccessOutcome } from "../commands/access.js";
+/**
+ * One line of the `hq access` cause-mix ledger. Deliberately narrow: no path,
+ * requester, or grantor — only enough to review which outcomes users hit.
+ */
+export interface AccessOutcomeRecord {
+    outcome: AccessOutcome;
+    company: string;
+    ts: string;
+}
+export declare function accessOutcomesPath(hqRoot: string): string;
+/**
+ * Append one JSONL line. Best-effort by contract: callers are expected to
+ * catch and downgrade any failure, since telemetry must never change an
+ * `hq access` outcome or exit code.
+ */
+export declare function recordAccessOutcome(hqRoot: string, rec: AccessOutcomeRecord): void;
+/**
+ * Read the ledger. A missing file is the empty ledger; malformed lines are
+ * skipped so one bad append never hides the rest of the history.
+ */
+export declare function readAccessOutcomes(hqRoot: string): AccessOutcomeRecord[];
+//# sourceMappingURL=access-outcomes.d.ts.map

package/dist/utils/access-outcomes.js

@@ -0,0 +1,53 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function accessOutcomesPath(hqRoot) {
+    return path.join(hqRoot, ".hq", "access-outcomes.jsonl");
+}
+/**
+ * Append one JSONL line. Best-effort by contract: callers are expected to
+ * catch and downgrade any failure, since telemetry must never change an
+ * `hq access` outcome or exit code.
+ */
+export function recordAccessOutcome(hqRoot, rec) {
+    const file = accessOutcomesPath(hqRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const line = JSON.stringify({ outcome: rec.outcome, company: rec.company, ts: rec.ts });
+    fs.appendFileSync(file, `${line}\n`, "utf-8");
+}
+/**
+ * Read the ledger. A missing file is the empty ledger; malformed lines are
+ * skipped so one bad append never hides the rest of the history.
+ */
+export function readAccessOutcomes(hqRoot) {
+    const file = accessOutcomesPath(hqRoot);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed &&
+                typeof parsed === "object" &&
+                typeof parsed.outcome === "string" &&
+                typeof parsed.company === "string" &&
+                typeof parsed.ts === "string") {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // malformed line: skip
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=access-outcomes.js.map

package/package.json

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