@indigoai-us/hq-cli 5.202.0 → 5.203.0

package/dist/main.js

@@ -53,6 +53,7 @@ import { registerCommandsWithRecovery } from "./startup-registration.js";
 import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
+import { runGlobalNetworkLifecycle } from "./utils/cli-network-lifecycle.js";
 /**
  * Total time one CLI invocation may await foreground network work. This spans
  * the hard version decision, pre-action observability, and release-health
@@ -152,7 +153,7 @@ export function handleStreamError(err, deps = defaultStreamErrorDependencies) {
 }
 process.stdout.on("error", (err) => handleStreamError(err));
 process.stderr.on("error", (err) => handleStreamError(err));
-initSentry();
+runGlobalNetworkLifecycle(process.argv, () => initSentry());
 const program = new Command();
 program
     .name("hq")
@@ -166,13 +167,15 @@ program.hook("preAction", async () => {
     // regardless, because the timer cannot be serviced while the event loop is
     // blocked. Keep anything added here asynchronous, or separately cheap: this
     // hook is on the path of EVERY hq command.
-    const budget = activeForegroundNetworkBudget;
-    if (!budget)
-        return;
-    await budget.waitFor(OBSERVABILITY_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => Promise.all([
-        emitCliSessionStarted(timeoutMs),
-        reportCliClientHealthInvocation({ timeoutMs }),
-    ]));
+    await runGlobalNetworkLifecycle(process.argv, async () => {
+        const budget = activeForegroundNetworkBudget;
+        if (!budget)
+            return;
+        await budget.waitFor(OBSERVABILITY_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => Promise.all([
+            emitCliSessionStarted(timeoutMs),
+            reportCliClientHealthInvocation({ timeoutMs }),
+        ]));
+    });
 });
 export async function runCli() {
     const foregroundNetworkBudget = new ForegroundNetworkBudget();
@@ -180,17 +183,19 @@ export async function runCli() {
     // Begin one registry refresh without awaiting it. Every command gate reads
     // only the client's held snapshot and falls back locally, so an offline or
     // slow registry cannot delay command parsing or alter a command failure.
-    void kickFlagRegistryReadiness();
+    runGlobalNetworkLifecycle(process.argv, () => {
+        void kickFlagRegistryReadiness();
+    });
     // Set when a self-update re-exec'd this command on a newer CLI: the child
     // already did the work, so this process only has to carry its exit status
     // out (after the finally block's telemetry, hence not process.exit here).
     let reexecStatus = null;
     try {
-        Sentry.addBreadcrumb({
+        runGlobalNetworkLifecycle(process.argv, () => Sentry.addBreadcrumb({
             category: "command",
             message: sanitizeArgv(process.argv.slice(2)).join(" "),
             level: "info",
-        });
+        }));
         // Version handling, both halves. Skipped for inspection flags
         // (`--version`, `--help`) so users debugging a broken install can still
         // introspect what they have, and silent on any failure — neither half may
@@ -204,7 +209,9 @@ export async function runCli() {
         //    it (hq-pro's `updateRecommended` and the cached npm latest from
         //    `version-check.ts`); whichever fires first re-execs, and the child
         //    carries a guard env so it can never update again.
-        if (!shouldSkipGate(process.argv)) {
+        const versionAction = await runGlobalNetworkLifecycle(process.argv, async () => {
+            if (shouldSkipGate(process.argv))
+                return "continue";
             const gate = (await foregroundNetworkBudget.waitFor(VERSION_GATE_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => enforceVersionGate(async (decision) => {
                 const outcome = await autoUpdateAndReexec(process.argv, decision.latestVersion);
                 if (outcome.action === "reexec")
@@ -212,16 +219,19 @@ export async function runCli() {
                 return outcome.action === "reexec";
             }, { timeoutMs }))) ?? "continue";
             if (gate === "reexec")
-                return;
+                return "reexec";
             const cachedLatest = staleAgainstCachedLatest();
             if (cachedLatest) {
                 const outcome = await autoUpdateAndReexec(process.argv, cachedLatest);
                 if (outcome.action === "reexec") {
                     reexecStatus = outcome.reexecStatus ?? 0;
-                    return;
+                    return "reexec";
                 }
             }
-        }
+            return "continue";
+        });
+        if (versionAction === "reexec")
+            return;
         // Register every contributor for the selected root only. Root help and
         // unknown-command recovery use generated metadata, so they keep the full
         // Commander surface without evaluating every command implementation.
@@ -256,19 +266,21 @@ export async function runCli() {
     finally {
         // Plan-limit nag (US-016): stderr-only, never throws, never touches
         // process.exitCode — safe to run after exit codes have been set.
-        emitPlanLimitNag();
-        // Release health: finalize the per-run session before the flush.
-        finishSentrySession();
-        // Neither task may turn a successful command into Node's
-        // `unsettled top-level await` exit. They are observability-only after the
-        // command has completed, so a bounded best-effort wait is the terminal
-        // lifecycle boundary for this invocation. The budget reserves this 500 ms
-        // slice even when the command itself was long-running.
-        const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
-        await settleWithin([
-            refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
-            Sentry.flush(releaseHealthTimeoutMs),
-        ], releaseHealthTimeoutMs);
+        await runGlobalNetworkLifecycle(process.argv, async () => {
+            emitPlanLimitNag();
+            // Release health: finalize the per-run session before the flush.
+            finishSentrySession();
+            // Neither task may turn a successful command into Node's
+            // `unsettled top-level await` exit. They are observability-only after the
+            // command has completed, so a bounded best-effort wait is the terminal
+            // lifecycle boundary for this invocation. The budget reserves this 500 ms
+            // slice even when the command itself was long-running.
+            const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
+            await settleWithin([
+                refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
+                Sentry.flush(releaseHealthTimeoutMs),
+            ], releaseHealthTimeoutMs);
+        });
         // Last, so it wins over anything the (skipped) command path would have
         // set: the re-exec'd child's status IS this invocation's result.
         if (reexecStatus !== null)

package/dist/utils/cli-network-lifecycle.d.ts

@@ -0,0 +1,4 @@
+export declare function isMonitorFastPathCommand(argv: readonly string[]): boolean;
+/** Skip process-wide network lifecycle work for hooks and detached monitor supervisors. */
+export declare function runGlobalNetworkLifecycle<T>(argv: readonly string[], operation: () => T): T | undefined;
+//# sourceMappingURL=cli-network-lifecycle.d.ts.map

package/dist/utils/cli-network-lifecycle.js

@@ -0,0 +1,11 @@
+const MONITOR_HIDDEN_NETWORK_BYPASS = new Set(["drain", "wait", "enabled", "_run"]);
+export function isMonitorFastPathCommand(argv) {
+    return argv[2] === "monitor" && MONITOR_HIDDEN_NETWORK_BYPASS.has(argv[3] ?? "");
+}
+/** Skip process-wide network lifecycle work for hooks and detached monitor supervisors. */
+export function runGlobalNetworkLifecycle(argv, operation) {
+    if (isMonitorFastPathCommand(argv))
+        return undefined;
+    return operation();
+}
+//# sourceMappingURL=cli-network-lifecycle.js.map

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

@@ -9,6 +9,7 @@
 // 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.
+import { redactUrlsInText } from "./redact-url.js";
 /** Upper bound on any redacted diagnostic — a message, not a payload dump. */
 export const REDACTED_TEXT_MAX_LENGTH = 1_000;
 /**
@@ -18,7 +19,7 @@ export const REDACTED_TEXT_MAX_LENGTH = 1_000;
  * their own fallback wording.
  */
 export function redactErrorText(text) {
-    return text
+    return redactUrlsInText(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]")

package/dist/utils/redact-url.d.ts

@@ -0,0 +1,14 @@
+/** Marker used when a value claims to be a URL but cannot be parsed safely. */
+export declare const REDACTED_URL = "[REDACTED]";
+/**
+ * Redact the values of secret-looking URL parameters while retaining URL
+ * structure and safe query values. An invalid URL or malformed encoded
+ * parameter name is replaced in full because its secret boundaries are
+ * unknowable.
+ */
+export declare function redactSensitiveUrl(value: string): string;
+/** Redact URLs embedded in an error or human-readable sentence. */
+export declare function redactUrlsInText(text: string): string;
+/** Clone a JSON-like value with all URL-valued fields and embedded URLs safe. */
+export declare function redactSensitiveUrls(value: unknown): unknown;
+//# sourceMappingURL=redact-url.d.ts.map

package/dist/utils/redact-url.js

@@ -0,0 +1,218 @@
+/** Marker used when a value claims to be a URL but cannot be parsed safely. */
+export const REDACTED_URL = "[REDACTED]";
+const EXACT_SECRET_PARAMETER_NAMES = new Set([
+    "key",
+    "apikey",
+    "api_key",
+    "x-api-key",
+    "xmcpkey",
+    "token",
+    "access_token",
+    "refresh_token",
+    "secret",
+    "client_secret",
+    "password",
+    "pass",
+    "pwd",
+    "auth",
+    "authorization",
+    "sig",
+    "signature",
+    "session",
+    "code",
+    "credential",
+    "credentials",
+    "authcode",
+    "authorizationcode",
+    "oauthcode",
+    "clientcode",
+    "verificationcode",
+    "confirmationcode",
+    "resetcode",
+    "activationcode",
+    "invitecode",
+    "devicecode",
+    "pairingcode",
+    "onetimecode",
+    "otpcode",
+    "auth_code",
+    "authorization_code",
+    "oauth_code",
+    "client_code",
+    "verification_code",
+    "confirmation_code",
+    "reset_code",
+    "activation_code",
+    "invite_code",
+    "device_code",
+    "pairing_code",
+    "one_time_code",
+    "otp_code",
+]);
+const UNAMBIGUOUS_SECRET_PARAMETER_SUFFIXES = [
+    "key",
+    "token",
+    "secret",
+    "password",
+    "signature",
+    "credential",
+    "credentials",
+];
+const AMBIGUOUS_SECRET_PARAMETER_SUFFIXES = ["pass", "pwd", "sig", "auth", "session"];
+const SECRET_PATH_LABEL = /^(?:access[_-]?token|refresh[_-]?token|id[_-]?token|api[_-]?key|x?mcpkey|client[_-]?secret|token|key|secret|password|pass|pwd|auth|authorization|sig|signature|credential|credentials|session)[=_-].+$/i;
+function hasParameterBoundaryBeforeSuffix(name, suffix) {
+    const suffixStart = name.length - suffix.length;
+    if (suffixStart <= 0)
+        return true;
+    return /[-_.]/.test(name[suffixStart - 1]) || /[A-Z]/.test(name[suffixStart]);
+}
+function isSecretParameterName(name) {
+    const normalized = name.toLowerCase();
+    return (EXACT_SECRET_PARAMETER_NAMES.has(normalized) ||
+        UNAMBIGUOUS_SECRET_PARAMETER_SUFFIXES.some((suffix) => normalized.endsWith(suffix)) ||
+        AMBIGUOUS_SECRET_PARAMETER_SUFFIXES.some((suffix) => normalized.endsWith(suffix) && hasParameterBoundaryBeforeSuffix(name, suffix)));
+}
+function isOpaqueCapabilitySegment(segment) {
+    if (SECRET_PATH_LABEL.test(segment))
+        return true;
+    const length = segment.length;
+    const hasLetter = /[A-Za-z]/.test(segment);
+    const hasDigit = /\d/.test(segment);
+    const isLongHex = length >= 24 && /^[A-Fa-f0-9]+$/.test(segment);
+    const isLongBase64Url = length >= 32 &&
+        /^[A-Za-z0-9_-]+$/.test(segment) &&
+        hasLetter &&
+        (hasDigit || /[A-Z_-]/.test(segment));
+    return (length >= 20 && hasLetter && hasDigit) || isLongHex || isLongBase64Url;
+}
+/** Mask opaque credential-like path segments while keeping ordinary routes. */
+function redactPathSegments(pathname) {
+    const segments = pathname.split("/");
+    const redacted = segments.map((segment) => {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch (error) {
+            if (error instanceof URIError)
+                return null;
+            throw error;
+        }
+        return isOpaqueCapabilitySegment(decoded) ? "REDACTED" : segment;
+    });
+    return redacted.some((segment) => segment === null) ? null : redacted.join("/");
+}
+/**
+ * Redact the values of secret-looking URL parameters while retaining URL
+ * structure and safe query values. An invalid URL or malformed encoded
+ * parameter name is replaced in full because its secret boundaries are
+ * unknowable.
+ */
+export function redactSensitiveUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (error) {
+        if (error instanceof TypeError)
+            return REDACTED_URL;
+        throw error;
+    }
+    const hasUserinfo = url.username !== "" || url.password !== "";
+    url.username = "";
+    url.password = "";
+    const pathname = redactPathSegments(url.pathname);
+    if (pathname === null)
+        return REDACTED_URL;
+    url.pathname = pathname;
+    const query = redactParameterList(url.search.slice(1));
+    if (query === null)
+        return REDACTED_URL;
+    url.search = query === "" ? "" : `?${query}`;
+    const fragment = redactFragment(url.hash.slice(1));
+    if (fragment === null)
+        return REDACTED_URL;
+    url.hash = fragment === "" ? "" : `#${fragment}`;
+    const serialized = url.toString();
+    if (!hasUserinfo)
+        return serialized;
+    const authorityStart = serialized.indexOf("://");
+    if (authorityStart === -1)
+        return serialized;
+    const hostStart = authorityStart + 3;
+    return `${serialized.slice(0, hostStart)}***@${serialized.slice(hostStart)}`;
+}
+/** Redact secret parameters in an ampersand-separated query or fragment. */
+function redactParameterList(raw) {
+    if (raw === "")
+        return "";
+    const parts = raw.split("&");
+    const redacted = [];
+    for (const part of parts) {
+        const equalsAt = part.indexOf("=");
+        const encodedName = equalsAt === -1 ? part : part.slice(0, equalsAt);
+        let name;
+        try {
+            name = decodeURIComponent(encodedName.replace(/\+/g, " "));
+        }
+        catch (error) {
+            if (error instanceof URIError)
+                return null;
+            throw error;
+        }
+        if (isSecretParameterName(name)) {
+            redacted.push(`${encodedName}=REDACTED`);
+        }
+        else {
+            redacted.push(part);
+        }
+    }
+    return redacted.join("&");
+}
+/** Redact query-like fields in both `#access_token=...` and `#/route?...`. */
+function redactFragment(fragment) {
+    if (fragment === "")
+        return "";
+    const queryStart = fragment.indexOf("?");
+    if (queryStart !== -1) {
+        const query = redactParameterList(fragment.slice(queryStart + 1));
+        return query === null ? null : `${fragment.slice(0, queryStart + 1)}${query}`;
+    }
+    if (fragment.includes("="))
+        return redactParameterList(fragment);
+    return fragment;
+}
+const URL_IN_TEXT = /\b[a-z][a-z\d+.-]*:\/\/[^\s<>"'`]+/gi;
+const TRAILING_SENTENCE_PUNCTUATION = /[),.;!?]+$/;
+/** Redact URLs embedded in an error or human-readable sentence. */
+export function redactUrlsInText(text) {
+    return text.replace(URL_IN_TEXT, (candidate) => {
+        const punctuation = TRAILING_SENTENCE_PUNCTUATION.exec(candidate)?.[0] ?? "";
+        const url = punctuation ? candidate.slice(0, -punctuation.length) : candidate;
+        return `${redactSensitiveUrl(url)}${punctuation}`;
+    });
+}
+const URL_PROPERTY = /(?:^|[-_.])(?:url|uri|endpoint)$/i;
+const CAMEL_URL_PROPERTY = /(?:Url|Uri|Endpoint)$/;
+const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:\/\//i;
+function isUrlProperty(key) {
+    return URL_PROPERTY.test(key) || CAMEL_URL_PROPERTY.test(key);
+}
+/** Clone a JSON-like value with all URL-valued fields and embedded URLs safe. */
+export function redactSensitiveUrls(value) {
+    if (typeof value === "string")
+        return redactUrlsInText(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactSensitiveUrls(item));
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        typeof item === "string" && isUrlProperty(key)
+            ? ABSOLUTE_URL.test(item)
+                ? redactSensitiveUrl(item)
+                : redactUrlsInText(item)
+            : redactSensitiveUrls(item),
+    ]));
+}
+//# sourceMappingURL=redact-url.js.map

package/package.json

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