@indigoai-us/hq-cli 5.109.2 → 5.109.4

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [5.109.4] — 2026-09-09
+
+### Fixed
+
+- A sign-in that never comes back no longer dead-ends. `hq integrations connect`
+  used to say "Timed out waiting for the browser sign-in. Run the connect
+  command again." — right for one of the three things that cause it and useless
+  for the other two. An app that will not accept HQ's temporary local return
+  address does not redirect back at all, so its refusal reaches HQ as silence;
+  retrying from the terminal fails identically every time. So does an app that
+  needs your workspace or instance address before its sign-in page will load.
+  HQ cannot tell these apart, so it now names all three and gives the recovery
+  for each: run it again, finish in the console (which uses a fixed address the
+  app accepts), or re-run with `--mcp-url` pointed at your own instance.
+
+## [5.109.3] — 2026-09-09
+
+### Fixed
+
+- A provider that refuses the sign-in request is no longer reported as you
+  declining it. `hq integrations connect` treated every `?error=` on the
+  callback as "Sign-in was declined", so a scope the provider will not grant,
+  a misconfigured client, or a provider outage all read as a choice you made —
+  and, because declines are treated as expected, none of them reached error
+  reporting. Only `access_denied` is a decline now; anything else reports as a
+  provider refusal and is visible. The error code is matched against the
+  RFC 6749 set and reported as `other` when it is outside it, so nothing the
+  provider sends is echoed back.
+
 ## [5.109.2] — 2026-09-09
 
 ### Fixed

package/dist/commands/integrations-connect.js

@@ -22,7 +22,7 @@ import { DEFAULT_VAULT_API_URL, ensureCognitoIdToken, } from "../utils/cognito-s
 import { getCompanyUid } from "../utils/vault-api.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";
+import { OAUTH_LOOPBACK_TIMEOUT_CODE, startLoopbackListener, } from "./integrations-oauth.js";
 /** hq-pro's machine code for "this endpoint needs a browser sign-in". */
 const OAUTH_REQUIRED_CODE = "INTEGRATION_FACTORY_OAUTH_REQUIRED";
 /**
@@ -518,7 +518,17 @@ async function connectViaOAuth(token, companyUid, target, opts) {
                 console.error(`Open this URL to sign in:\n  ${started.authorizationUrl}`);
             });
         }
-        const code = await pendingCode;
+        let code;
+        try {
+            code = await pendingCode;
+        }
+        catch (err) {
+            if (err instanceof IntegrationsCliError &&
+                err.code === OAUTH_LOOPBACK_TIMEOUT_CODE) {
+                return loopbackTimeoutHandoff(target, opts);
+            }
+            throw err;
+        }
         return await completeOAuth(token, companyUid, { state: started.state, code });
     }
     finally {
@@ -594,6 +604,56 @@ function targetSelectionHint(opts) {
     return undefined;
 }
 /** Shared tail of every console handoff: the page, then what to connect there. */
+/**
+ * The loopback callback never arrived. Offer every recovery, claim no cause.
+ *
+ * This used to say "Timed out waiting for the browser sign-in. Run the connect
+ * command again." — advice that is right for one of the three things that
+ * produce this timeout and useless for the other two, with nothing to tell the
+ * user which they hit:
+ *
+ *   1. They did not finish in time. Retrying works.
+ *   2. The provider rejected HQ's `127.0.0.1:<port>` redirect_uri. RFC 8252
+ *      allows the variable port; plenty of providers demand an exactly
+ *      registered URI anyway and show their own error page. Because the URI is
+ *      unregistered they will not redirect to it, so their refusal reaches HQ
+ *      as silence. Retrying from the terminal fails identically forever; the
+ *      console's pinned callback IS registered, so finishing there works.
+ *   3. The app needs a workspace/instance address before its sign-in page will
+ *      load at all. Its generic authorize URL cannot complete for anyone.
+ *      `--mcp-url` already takes an instance-specific endpoint — the capability
+ *      exists, it was just never mentioned at the moment it is needed.
+ *
+ * HQ genuinely cannot tell these apart from here, so it names all three rather
+ * than picking one and sounding certain.
+ */
+function loopbackTimeoutHandoff(target, opts) {
+    console.error(chalk.yellow(`The sign-in for ${target.label} never came back, so nothing was connected.`));
+    console.error("Three things cause this, and HQ cannot tell which from here:");
+    console.error("  1. The sign-in was not finished in time — run the same command again.");
+    console.error(`  2. ${target.label} will not accept HQ's temporary local address as a ` +
+        "return URL. Retrying here always fails; finish it in the console " +
+        "instead, which uses a fixed address the app accepts.");
+    console.error(`  3. ${target.label} needs your workspace or instance address before its ` +
+        "sign-in page works at all. Re-run with that server's own endpoint:\n" +
+        "     hq integrations connect --mcp-url https://<your-workspace>.example.com/mcp");
+    const url = consoleIntegrationsUrl(opts.company, consoleOrigin());
+    printConsoleDestination(target, opts, url);
+    // Nothing was connected, so the command must not exit 0. Returning null the
+    // way consoleHandoff does would let `connectApp` complete normally and hand a
+    // script a success it did not get — the same unbacked claim this whole change
+    // is about, made in the exit status instead of in prose.
+    //
+    // A handoff and a timeout are different outcomes and deserve different exit
+    // codes: consoleHandoff means HQ knows what happens next and has routed you
+    // there, while this means the sign-in failed and HQ cannot say why. Set the
+    // status directly rather than throwing, so the three routes above stay the
+    // whole message instead of being followed by a duplicate headline — the same
+    // print-then-mark-failed shape integrations.ts already uses for a tool call
+    // that ran and failed.
+    process.exitCode = 1;
+    return null;
+}
 function printConsoleDestination(target, opts, url) {
     if (url) {
         console.error(`Open this page and connect ${target.label} from it:\n  ${url}`);

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

@@ -19,12 +19,43 @@
  * as `OAUTH_REDIRECT_URI_NOT_ALLOWED` at connect time.
  */
 export declare const LOOPBACK_CALLBACK_PATH = "/hq/integrations/oauth/callback";
+/**
+ * The loopback callback never arrived before the bound.
+ *
+ * Deliberately a code and not a message match: this is the ONLY signal HQ gets
+ * for a provider that rejects the ephemeral `127.0.0.1:<port>` redirect_uri,
+ * because such a provider refuses to redirect to an unregistered address and
+ * so sends nothing back at all. It is also what a person who simply did not
+ * finish in time produces. The two are indistinguishable from here, which is
+ * exactly why the caller must offer both recoveries rather than assert one.
+ */
+export declare const OAUTH_LOOPBACK_TIMEOUT_CODE = "OAUTH_LOOPBACK_TIMEOUT";
+/**
+ * Turn an `?error=` redirect into what to tell the user, and whether it is
+ * their doing.
+ *
+ * Every `?error=` used to be reported as "Sign-in was declined", marked
+ * expected, and therefore skipped for Sentry capture. Only `access_denied` is
+ * the person declining. `invalid_scope` is HQ or the catalog asking for
+ * something the provider does not grant; `unauthorized_client` and
+ * `invalid_request` are a misconfigured client; `server_error` is the provider
+ * failing. Reporting those as a decision the user made both misdirects the
+ * user — there is nothing for them to do differently — and hid the real,
+ * fixable causes from error reporting, because "expected" suppresses capture.
+ * So: `access_denied` stays expected and quiet; everything else is a provider
+ * rejection that reaches Sentry.
+ */
+export declare function authorizeErrorOutcome(raw: string): {
+    message: string;
+    expected: boolean;
+};
 export interface LoopbackListener {
     /** The redirect URI to hand hq-pro — includes the OS-assigned port. */
     redirectUri: string;
     /**
      * Resolves once the authorization server redirects back. Rejects on timeout,
-     * on an `?error=` response (the person clicked Deny), or on a state mismatch.
+     * on an `?error=` response, or on a state mismatch. Only `access_denied`
+     * means the person clicked Deny — see {@link authorizeErrorOutcome}.
      */
     waitForCode(expectedState: string): Promise<string>;
     close(): void;

package/dist/commands/integrations-oauth.js

@@ -23,6 +23,59 @@ import { IntegrationsCliError } from "./integrations-core.js";
 export const LOOPBACK_CALLBACK_PATH = "/hq/integrations/oauth/callback";
 /** How long to wait for the browser round trip before giving the port back. */
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * The loopback callback never arrived before the bound.
+ *
+ * Deliberately a code and not a message match: this is the ONLY signal HQ gets
+ * for a provider that rejects the ephemeral `127.0.0.1:<port>` redirect_uri,
+ * because such a provider refuses to redirect to an unregistered address and
+ * so sends nothing back at all. It is also what a person who simply did not
+ * finish in time produces. The two are indistinguishable from here, which is
+ * exactly why the caller must offer both recoveries rather than assert one.
+ */
+export const OAUTH_LOOPBACK_TIMEOUT_CODE = "OAUTH_LOOPBACK_TIMEOUT";
+/**
+ * The authorization-endpoint error codes RFC 6749 §4.1.2.1 defines. Anything
+ * outside this set is reported as `other`: the value arrives in a redirect
+ * query string a third party controls, so it is matched against a closed list
+ * and never echoed. `error_description` is deliberately never read at all.
+ */
+const OAUTH_AUTHORIZE_ERROR_CODES = new Set([
+    "invalid_request",
+    "unauthorized_client",
+    "access_denied",
+    "unsupported_response_type",
+    "invalid_scope",
+    "server_error",
+    "temporarily_unavailable",
+]);
+/**
+ * Turn an `?error=` redirect into what to tell the user, and whether it is
+ * their doing.
+ *
+ * Every `?error=` used to be reported as "Sign-in was declined", marked
+ * expected, and therefore skipped for Sentry capture. Only `access_denied` is
+ * the person declining. `invalid_scope` is HQ or the catalog asking for
+ * something the provider does not grant; `unauthorized_client` and
+ * `invalid_request` are a misconfigured client; `server_error` is the provider
+ * failing. Reporting those as a decision the user made both misdirects the
+ * user — there is nothing for them to do differently — and hid the real,
+ * fixable causes from error reporting, because "expected" suppresses capture.
+ * So: `access_denied` stays expected and quiet; everything else is a provider
+ * rejection that reaches Sentry.
+ */
+export function authorizeErrorOutcome(raw) {
+    const code = raw.trim().toLowerCase();
+    if (code === "access_denied") {
+        return { message: "Sign-in was declined.", expected: true };
+    }
+    const known = OAUTH_AUTHORIZE_ERROR_CODES.has(code) ? code : "other";
+    return {
+        message: `The provider refused the sign-in request (${known}). ` +
+            "Nothing was connected.",
+        expected: false,
+    };
+}
 /**
  * Escapes text destined for the callback page.
  *
@@ -180,7 +233,10 @@ export async function startLoopbackListener(opts = {}) {
                     timer = null;
                     const { code, state, error } = result;
                     if (error) {
-                        reject(new IntegrationsCliError(`Sign-in was declined (${error}).`, { expected: true }));
+                        const outcome = authorizeErrorOutcome(error);
+                        reject(new IntegrationsCliError(outcome.message, {
+                            expected: outcome.expected,
+                        }));
                         return;
                     }
                     if (!code || !state) {
@@ -205,7 +261,13 @@ export async function startLoopbackListener(opts = {}) {
                 }
                 timer = setTimeout(() => {
                     close();
-                    reject(new IntegrationsCliError("Timed out waiting for the browser sign-in. Run the connect command again.", { expected: true }));
+                    reject(new IntegrationsCliError("The sign-in never came back.", 
+                    // Typed, so the caller can offer the recovery routes without
+                    // matching on this sentence. A timeout is NOT self-evidently
+                    // "you were too slow": a provider that refuses HQ's ephemeral
+                    // loopback redirect_uri generally will not redirect back to it
+                    // at all, so its refusal reaches this branch as silence.
+                    { expected: true, code: OAUTH_LOOPBACK_TIMEOUT_CODE }));
                 }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
                 // Don't let a pending sign-in wait keep an otherwise-finished process
                 // alive: the explicit timeout above is the bound, not the event loop.

package/package.json

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