@indigoai-us/hq-cli 5.94.1 → 5.94.3

package/dist/utils/network-transport-error.js

@@ -0,0 +1,184 @@
+// src/utils/network-transport-error.ts
+//
+// Classify raw NETWORK TRANSPORT failures — the request never reached (or
+// never completed against) the server — as the user's connectivity rather
+// than an hq-cli code defect. Sibling of `environmental-error.ts` (HQ-CLI-2,
+// full disk / read-only fs) and `expected-cli-error.ts` (HQ-CLI-6, client
+// 4xx): a failure that is not an hq-cli defect is surfaced to the user with an
+// actionable message and skipped for Sentry capture.
+//
+// HQ-CLI-G (Sentry 7652140783): `hq integrations list` resolved the caller's
+// company through `vaultApiFetch` → bare `fetch`; undici could not connect and
+// threw `TypeError: fetch failed` whose `cause` was
+// `ConnectTimeoutError: Connect Timeout Error (attempted address:
+// hqapi.hq.computer:443, timeout: 10000ms)`. That value is not an
+// `IntegrationsCliError`, so `environmentalFsErrorMessage` and
+// `unexpectedCliErrorMessage` both returned null and the top-level handler
+// took its last-resort branch: capture to Sentry (culprit `?(undici)`, no
+// actionable stack) and print NOTHING. The same process had reached the same
+// host one second earlier, so this was a transient client-side connect
+// failure. Suppressing the crash report is only half the fix — the silent
+// exit is the other half, which is why this returns a MESSAGE, never a bare
+// boolean.
+//
+// Matching is deliberately conservative. A recognized errno / undici code (or
+// a recognized undici error name) must appear on the error or somewhere in its
+// bounded cause chain; message text alone never qualifies. That keeps an
+// hq-cli bug that happens to surface as a `TypeError` reportable.
+import { redactErrorText } from "./redact-error-text.js";
+/** The exact message undici gives the `fetch()` wrapper around a transport fault. */
+const FETCH_FAILED_MESSAGE = "fetch failed";
+/**
+ * Recognized transport codes → the phrase shown to the user.
+ *
+ * Deliberately absent:
+ *   - EPIPE — a closed downstream reader, handled earlier and exits 0 (HQ-6B).
+ *   - UND_ERR_RESPONSE_STATUS_CODE — the server answered; that is an HTTP
+ *     status to classify at the call site, not a transport failure.
+ */
+const TRANSPORT_CODE_REASONS = {
+    ECONNREFUSED: "the connection was refused",
+    ECONNRESET: "the connection was reset",
+    ENOTFOUND: "the hostname could not be resolved",
+    EAI_AGAIN: "the DNS lookup failed temporarily",
+    ETIMEDOUT: "the connection timed out",
+    EHOSTUNREACH: "the host is unreachable",
+    ENETUNREACH: "the network is unreachable",
+    ENETDOWN: "the network is down",
+    UND_ERR_CONNECT_TIMEOUT: "the connection timed out",
+    UND_ERR_HEADERS_TIMEOUT: "the server did not respond in time",
+    UND_ERR_SOCKET: "the connection closed unexpectedly",
+};
+/**
+ * Recognized undici error names, for builds where the `code` property is
+ * absent but the typed error still identifies itself (the shape Sentry
+ * recorded for HQ-CLI-G was `ConnectTimeoutError`).
+ */
+const TRANSPORT_NAME_REASONS = {
+    ConnectTimeoutError: "the connection timed out",
+    HeadersTimeoutError: "the server did not respond in time",
+    SocketError: "the connection closed unexpectedly",
+};
+/**
+ * Depth cap for `cause` traversal. A self-referential or mutually-referential
+ * cause chain must terminate rather than hang the error boundary, so the walk
+ * is bounded on BOTH depth and a visited set.
+ */
+const MAX_CAUSE_DEPTH = 8;
+/** Hostnames/IPs only — anything else is dropped before it reaches stderr. */
+const SAFE_HOST_CHARACTERS = /[^A-Za-z0-9._:[\]-]/g;
+const MAX_HOST_LENGTH = 80;
+function readStringProperty(node, key) {
+    const value = node[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function errorNameOf(node) {
+    return (readStringProperty(node, "name") ??
+        (typeof node.constructor?.name === "string"
+            ? (node.constructor.name)
+            : null));
+}
+/**
+ * Best-effort host recovery: Node errno errors carry `hostname`/`address`
+ * (+ `port`); undici's ConnectTimeoutError only names the peer in its message
+ * ("attempted address: host:443").
+ */
+function hostFrom(node) {
+    const base = readStringProperty(node, "hostname") ?? readStringProperty(node, "address");
+    if (base) {
+        const port = node.port;
+        return typeof port === "number" && Number.isFinite(port) ? `${base}:${port}` : base;
+    }
+    const message = readStringProperty(node, "message");
+    if (message) {
+        const match = /attempted address:\s*([^\s,)]+)/i.exec(message);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/**
+ * Walk `root` and its `cause` chain (plus any `AggregateError.errors`, which
+ * is how undici reports a multi-address connect failure) for a recognized
+ * transport code or error name. Bounded by depth AND a visited set.
+ */
+function findTransportFailure(root) {
+    const seen = new Set();
+    const queue = [{ node: root, depth: 0 }];
+    let host = null;
+    while (queue.length > 0) {
+        const { node, depth } = queue.shift();
+        if (node === null || typeof node !== "object")
+            continue;
+        if (seen.has(node))
+            continue;
+        seen.add(node);
+        host = host ?? hostFrom(node);
+        const code = readStringProperty(node, "code");
+        if (code && TRANSPORT_CODE_REASONS[code]) {
+            return { code, reason: TRANSPORT_CODE_REASONS[code], host };
+        }
+        const name = errorNameOf(node);
+        if (name && TRANSPORT_NAME_REASONS[name]) {
+            return { code: name, reason: TRANSPORT_NAME_REASONS[name], host };
+        }
+        if (depth >= MAX_CAUSE_DEPTH)
+            continue;
+        const cause = node.cause;
+        if (cause !== undefined && cause !== null) {
+            queue.push({ node: cause, depth: depth + 1 });
+        }
+        const aggregated = node.errors;
+        if (Array.isArray(aggregated)) {
+            for (const entry of aggregated)
+                queue.push({ node: entry, depth: depth + 1 });
+        }
+    }
+    return null;
+}
+/**
+ * Reject anything whose SHAPE says "this may be an hq-cli defect" before the
+ * allowlist even runs. A `TypeError` is the one thing undici reuses for a
+ * transport fault, and only with the exact `fetch failed` message; every other
+ * `TypeError` is far likelier to be our own bug (calling a non-function,
+ * reading a property of undefined) and must stay reportable.
+ */
+function hasTransportShape(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err instanceof TypeError && err.message !== FETCH_FAILED_MESSAGE)
+        return false;
+    return true;
+}
+function classify(err) {
+    if (!hasTransportShape(err))
+        return null;
+    return findTransportFailure(err);
+}
+/**
+ * The recognized transport code for `err`, or null when `err` is not a
+ * transport failure. Used for breadcrumb annotation at the fetch call site —
+ * a bounded, non-secret label, never the error text itself.
+ */
+export function networkTransportErrorCode(err) {
+    return classify(err)?.code ?? null;
+}
+/**
+ * If `err` is a raw network transport failure, return a short, actionable
+ * user-facing message; otherwise return `null`.
+ *
+ * A non-null result means the caller should PRINT the message, exit non-zero,
+ * and SKIP Sentry capture — the condition is the caller's network, not a bug
+ * HQ can fix. A null result means "handle this as usual (capture to Sentry)".
+ */
+export function networkTransportErrorMessage(err) {
+    const failure = classify(err);
+    if (!failure)
+        return null;
+    const host = failure.host
+        ? redactErrorText(failure.host).replace(SAFE_HOST_CHARACTERS, "").slice(0, MAX_HOST_LENGTH)
+        : "";
+    const where = host ? ` (${host})` : "";
+    return `Could not reach HQ${where}: ${failure.reason}. Check your network connection and try again.`;
+}
+//# sourceMappingURL=network-transport-error.js.map

package/dist/utils/redact-error-text.d.ts

@@ -0,0 +1,10 @@
+/** Upper bound on any redacted diagnostic — a message, not a payload dump. */
+export declare const REDACTED_TEXT_MAX_LENGTH = 1000;
+/**
+ * Strip credentials from `text`, flatten control characters/whitespace, and
+ * bound the length. Idempotent, so applying it at both the throw site and the
+ * print site is safe. Returns `""` when nothing survives — callers supply
+ * their own fallback wording.
+ */
+export declare function redactErrorText(text: string): string;
+//# sourceMappingURL=redact-error-text.d.ts.map

package/dist/utils/redact-error-text.js

@@ -0,0 +1,33 @@
+// src/utils/redact-error-text.ts
+//
+// One credential-redaction + bounding chain for error text that leaves the
+// process — printed to the user's terminal or shipped to Sentry.
+//
+// It was originally inline in `unexpected-cli-error.ts`, which only runs on the
+// UNEXPECTED path. Once upstream-minted gateway text can be classified
+// `expected` (HQ-CLI-F), that text is printed by the top-level handler's
+// expected branch instead, which prints `err.message` verbatim. Rather than
+// duplicate the chain at the second print site, it lives here and both callers
+// share it: provider-minted text is untrusted and must never be printed raw.
+/** Upper bound on any redacted diagnostic — a message, not a payload dump. */
+export const REDACTED_TEXT_MAX_LENGTH = 1_000;
+/**
+ * Strip credentials from `text`, flatten control characters/whitespace, and
+ * bound the length. Idempotent, so applying it at both the throw site and the
+ * print site is safe. Returns `""` when nothing survives — callers supply
+ * their own fallback wording.
+ */
+export function redactErrorText(text) {
+    return text
+        .replace(/-----BEGIN[^-]+PRIVATE KEY-----[\s\S]*?-----END[^-]+PRIVATE KEY-----/g, "[REDACTED]")
+        .replace(/\p{Cc}/gu, " ")
+        .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED]")
+        .replace(/\b(password|secret|client[_-]?secret|api[_-]?key|(?:id|access|refresh)[_-]?token|token|authorization)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s&"'<>;,}]+)/gi, (_match, label) => `${label}=[REDACTED]`)
+        .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]")
+        .replace(/\b(?:hqk_|xox[abprs]-|github_pat_|gh[pousr]_)[A-Za-z0-9_-]+\b/gi, "[REDACTED]")
+        .replace(/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED]")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, REDACTED_TEXT_MAX_LENGTH);
+}
+//# sourceMappingURL=redact-error-text.js.map

package/dist/utils/unexpected-cli-error.d.ts

@@ -3,6 +3,22 @@
  * messages are already part of a user-facing protocol contract. Unknown
  * exceptions remain Sentry-only so local implementation details and secrets
  * are not printed indiscriminately.
+ *
+ * The redaction chain lives in `redact-error-text.ts` so the EXPECTED print
+ * path (which prints `err.message` directly from the top-level handler) can
+ * scrub the same upstream-minted text with the same rules.
  */
 export declare function unexpectedCliErrorMessage(err: unknown): string | null;
+/**
+ * Last-resort operator message for an error the CLI has no specific handling
+ * for. Redacted through the same chain as the integrations path; falls back to
+ * a fixed string when the value carries no usable message.
+ *
+ * Exists so the top-level handler can ALWAYS emit a diagnostic. It previously
+ * printed only when unexpectedCliErrorMessage() returned a value, and that
+ * returns null for everything except IntegrationsCliError — so any other
+ * failure (a qmd crash, for instance) exited 1 with zero bytes on both
+ * streams, which is indistinguishable from success-with-no-output.
+ */
+export declare function fallbackOperatorMessage(err: unknown): string;
 //# sourceMappingURL=unexpected-cli-error.d.ts.map

package/dist/utils/unexpected-cli-error.js

@@ -1,24 +1,37 @@
 import { IntegrationsCliError } from "../commands/integrations.js";
+import { redactErrorText } from "./redact-error-text.js";
 /**
  * Return a bounded operator-facing diagnostic for unexpected errors whose
  * messages are already part of a user-facing protocol contract. Unknown
  * exceptions remain Sentry-only so local implementation details and secrets
  * are not printed indiscriminately.
+ *
+ * The redaction chain lives in `redact-error-text.ts` so the EXPECTED print
+ * path (which prints `err.message` directly from the top-level handler) can
+ * scrub the same upstream-minted text with the same rules.
  */
 export function unexpectedCliErrorMessage(err) {
     if (!(err instanceof IntegrationsCliError) || err.expected)
         return null;
-    const message = err.message
-        .replace(/-----BEGIN[^-]+PRIVATE KEY-----[\s\S]*?-----END[^-]+PRIVATE KEY-----/g, "[REDACTED]")
-        .replace(/\p{Cc}/gu, " ")
-        .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED]")
-        .replace(/\b(password|secret|client[_-]?secret|api[_-]?key|(?:id|access|refresh)[_-]?token|token|authorization)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s&"'<>;,}]+)/gi, (_match, label) => `${label}=[REDACTED]`)
-        .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]")
-        .replace(/\b(?:hqk_|xox[abprs]-|github_pat_|gh[pousr]_)[A-Za-z0-9_-]+\b/gi, "[REDACTED]")
-        .replace(/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED]")
-        .replace(/\s+/g, " ")
-        .trim()
-        .slice(0, 1_000);
-    return message || "Integration request failed";
+    return redactErrorText(err.message) || "Integration request failed";
+}
+/**
+ * Last-resort operator message for an error the CLI has no specific handling
+ * for. Redacted through the same chain as the integrations path; falls back to
+ * a fixed string when the value carries no usable message.
+ *
+ * Exists so the top-level handler can ALWAYS emit a diagnostic. It previously
+ * printed only when unexpectedCliErrorMessage() returned a value, and that
+ * returns null for everything except IntegrationsCliError — so any other
+ * failure (a qmd crash, for instance) exited 1 with zero bytes on both
+ * streams, which is indistinguishable from success-with-no-output.
+ */
+export function fallbackOperatorMessage(err) {
+    const raw = err instanceof Error
+        ? `${err.name}: ${err.message}`
+        : typeof err === "string"
+            ? err
+            : "";
+    return redactErrorText(raw) || "command failed with an unreported error";
 }
 //# sourceMappingURL=unexpected-cli-error.js.map

package/dist/utils/vault-api.js

@@ -3,6 +3,7 @@ import { Sentry } from '../sentry.js';
 import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
 import { recordPlanLimitStatus } from '../lib/plan-limit-nag.js';
+import { networkTransportErrorCode } from './network-transport-error.js';
 /**
  * Best-effort peek of a 2xx JSON body for plan-limit status (US-016).
  *
@@ -134,15 +135,34 @@ export async function vaultApiFetch(opts) {
         level: "info",
         data: { url: safeUrl, method },
     });
-    const response = await fetch(url.toString(), {
-        method,
-        headers: {
-            Authorization: `Bearer ${opts.token}`,
-            'Content-Type': 'application/json',
-        },
-        body: opts.body ? JSON.stringify(opts.body) : undefined,
-        signal: opts.signal,
-    });
+    let response;
+    try {
+        response = await fetch(url.toString(), {
+            method,
+            headers: {
+                Authorization: `Bearer ${opts.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: opts.body ? JSON.stringify(opts.body) : undefined,
+            signal: opts.signal,
+        });
+    }
+    catch (err) {
+        // A transport failure never reaches the server, so the non-2xx breadcrumb
+        // below never fires and the run's last HTTP trace is the request that
+        // silently vanished (exactly what made HQ-CLI-G's event unreadable). Leave
+        // a bounded, non-secret trail — the already-redacted safeUrl plus the
+        // recognized transport code — then RE-THROW the original error untouched,
+        // so `main.ts`'s classifier stays the single decision point.
+        const code = networkTransportErrorCode(err);
+        Sentry.addBreadcrumb({
+            category: "http",
+            message: `${method} ${path} → transport error`,
+            level: "warning",
+            data: { url: safeUrl, method, ...(code ? { code } : {}) },
+        });
+        throw err;
+    }
     if (!response.ok) {
         Sentry.addBreadcrumb({
             category: "http",

package/package.json

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