@indigoai-us/hq-cli 5.101.4 → 5.101.5

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [5.101.5] — 2026-08-17
+
+- No user-facing changes recorded.
+
 ## [5.101.4] — 2026-08-16
 
 - No user-facing changes recorded.

package/dist/main.js

@@ -65,6 +65,7 @@ import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
 import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.js";
+import { qmdMissingCollectionMessage } from "./utils/qmd-collection-missing-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
@@ -438,7 +439,21 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // Ordered FIRST so the narrow native-binding signature wins over the
         // broader environmental / transport / generic branches.
         const qmdMsg = qmdNativeBindingErrorMessage(err);
-        const envMsg = qmdMsg ? null : environmentalFsErrorMessage(err);
+        // A `hq search <query> -c <collection>` against a collection that is not
+        // indexed on THIS machine is the user's local index state, not an hq-cli
+        // defect — the remedy is an explicit `hq index sync`. finishRunQmd already
+        // types the condition QmdCollectionMissingError, but nothing caught it, so
+        // it fell through to the capture below; because the synthesized message
+        // embeds the caller's whole argv, each distinct query minted a brand-new
+        // permanent issue. Print an actionable line naming the missing collection
+        // and skip capture (HQ-CLI-S, Sentry 7672722729). Evaluated AFTER the
+        // native-binding check so that narrower signature keeps priority, and
+        // BEFORE the environmental / transport / generic branches. Scoped to
+        // caller-supplied reads (search/vsearch/query/get); a collection-missing
+        // raised by hq's OWN reconciliation (`collection add`/`context add`) names
+        // a collection hq built itself, so it stays a captured internal error.
+        const collectionMsg = qmdMsg ? null : qmdMissingCollectionMessage(err);
+        const envMsg = qmdMsg || collectionMsg ? null : environmentalFsErrorMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
         // with a ConnectTimeoutError / ECONNREFUSED / ENOTFOUND cause) is the
         // caller's connectivity, not an hq-cli defect. Before this branch it fell
@@ -449,10 +464,13 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // message that names the unreachable host, exit 1, and skip Sentry.
         // Ordered after the environmental check so a full disk keeps its exact
         // existing message.
-        const transportMsg = qmdMsg || envMsg ? null : networkTransportErrorMessage(err);
+        const transportMsg = qmdMsg || collectionMsg || envMsg ? null : networkTransportErrorMessage(err);
         if (qmdMsg) {
             deps.stderr.write(`hq: ${qmdMsg}\n`);
         }
+        else if (collectionMsg) {
+            deps.stderr.write(`hq: ${collectionMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }

package/dist/utils/qmd-collection-missing-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * If `err` is a caller-driven "collection not found" from `hq search` (or its
+ * `get` sibling), return an actionable, query-free remedy naming the missing
+ * collection; otherwise return `null`. Mirrors qmdNativeBindingErrorMessage /
+ * environmentalFsErrorMessage / networkTransportErrorMessage so the top-level
+ * handler can branch on it the same way: a non-null result means
+ * print-and-skip-Sentry, null means "handle as usual (capture to Sentry)".
+ */
+export declare function qmdMissingCollectionMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-collection-missing-error.d.ts.map

package/dist/utils/qmd-collection-missing-error.js

@@ -0,0 +1,95 @@
+// src/utils/qmd-collection-missing-error.ts
+//
+// Classify a "collection not found" qmd failure that came from a caller-supplied
+// READ — `hq search`, its `--mode` siblings (vsearch/query), or `hq search get`
+// — as the user's LOCAL index state, not an hq-cli code defect. The collection
+// the caller named is simply not indexed on this machine; the remedy is an
+// explicit `hq index sync`, so the CLI prints an actionable line and SKIPS
+// Sentry capture. Sibling of qmd-native-binding-error.ts (HQ-CLI-J, unbuilt
+// bindings), environmental-error.ts (HQ-CLI-2, full disk), and
+// network-transport-error.ts (HQ-CLI-G, connectivity): a failure that is NOT an
+// hq-cli defect is printed with an actionable message and never filed as a crash.
+//
+// HQ-CLI-S (Sentry 7672722729): `hq search <query> -c <collection>` against a
+// collection that isn't indexed locally made qmd exit 1 with `Collection not
+// found: <collection>`. finishRunQmd already classifies that wording into the
+// dedicated QmdCollectionMissingError subclass, but nothing caught it, so it
+// unwound to the top-level handler's final else and was captured. Worse, the
+// synthesized message interpolates the caller's whole argv, so each distinct
+// query minted a brand-new permanent issue. This classifier closes that boundary.
+//
+// The gate is deliberately narrow on TWO axes so it can neither be tripped by
+// user input nor silence a real bug:
+//   1. CLASS: only a QmdCollectionMissingError (the typed subclass finishRunQmd
+//      raises for the collection-not-found wording) qualifies — never a plain
+//      QmdExitError, a native-binding failure, or any other error.
+//   2. INVOCATION: only qmd's caller-supplied-collection READS — `search`,
+//      `vsearch`, `query`, `get` — qualify. A collection-missing raised by hq's
+//      OWN reconciliation (`collection add`/`collection list`, `context add`)
+//      names a collection hq constructed itself, so a not-found there is an
+//      internal inconsistency worth reporting: it must keep crashing and
+//      capturing, so the classifier returns null for those invocations.
+//
+// The collection name is read STRUCTURALLY from the error's own `args` (the
+// token after `-c`/`--collection`), never by parsing qmd's stderr, and the
+// caller's free-text query (args[1]) is never echoed — the same unbounded-
+// fingerprint discipline that motivated the fix. The name is itself a
+// user-supplied `-c` value, so before it is interpolated it is passed through
+// redactErrorText — the same credential-redaction + control-character-flattening
+// + length-bounding chain the generic error path uses — so a newline, terminal
+// escape sequence, credential-like token, or oversized value can neither forge a
+// second `hq:` line nor leak; if nothing survives redaction the message falls
+// back to the name-free variant.
+import { redactErrorText } from "./redact-error-text.js";
+/** qmd subcommands whose collection is chosen by the CALLER (a read surface). */
+const CALLER_COLLECTION_READS = new Set(["search", "vsearch", "query", "get"]);
+/**
+ * The two-pronged, factual remedy. `hq index sync` builds the collections HQ can
+ * derive from this local root; `hq index collections` shows what is actually
+ * registered (covering a name that maps to a company not present here, which
+ * sync will never create). Neither claims the named collection will appear.
+ */
+function remedyMessage(collection) {
+    return collection
+        ? `No local search collection named '${collection}'. Run 'hq index sync' to build it, or 'hq index collections' to see what is registered.`
+        : "No local search collection was found for that query. Run 'hq index sync' to build the local index, or 'hq index collections' to see what is registered.";
+}
+/** The collection name the caller passed after `-c`/`--collection`, or null. */
+function collectionFromArgs(args) {
+    for (let i = 0; i < args.length - 1; i += 1) {
+        if (args[i] === "-c" || args[i] === "--collection") {
+            const value = args[i + 1];
+            if (typeof value === "string" && value.length > 0)
+                return value;
+        }
+    }
+    return null;
+}
+/**
+ * If `err` is a caller-driven "collection not found" from `hq search` (or its
+ * `get` sibling), return an actionable, query-free remedy naming the missing
+ * collection; otherwise return `null`. Mirrors qmdNativeBindingErrorMessage /
+ * environmentalFsErrorMessage / networkTransportErrorMessage so the top-level
+ * handler can branch on it the same way: a non-null result means
+ * print-and-skip-Sentry, null means "handle as usual (capture to Sentry)".
+ */
+export function qmdMissingCollectionMessage(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "QmdCollectionMissingError")
+        return null;
+    const args = Array.isArray(record.args) ? record.args : [];
+    const subcommand = args[0];
+    if (typeof subcommand !== "string" || !CALLER_COLLECTION_READS.has(subcommand)) {
+        return null;
+    }
+    const rawCollection = collectionFromArgs(args);
+    // The name is a user-supplied `-c` value: redact + flatten + bound it before
+    // printing so it cannot forge a second `hq:` line, emit terminal escapes, or
+    // leak a credential-shaped token. redactErrorText returns "" when nothing
+    // survives, in which case we fall back to the name-free variant.
+    const collection = rawCollection ? redactErrorText(rawCollection) || null : null;
+    return remedyMessage(collection);
+}
+//# sourceMappingURL=qmd-collection-missing-error.js.map

package/package.json

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