@indigoai-us/hq-cli 5.103.27 → 5.103.28

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

@@ -0,0 +1,130 @@
+// src/utils/qmd-module-missing-error.ts
+//
+// Classify a qmd failure caused by a MISSING JAVASCRIPT MODULE in qmd's own
+// bundled dependency tree — Node could not load a file qmd needs — as the
+// caller's INCOMPLETE INSTALL, not an hq-cli code defect. hq-cli ships qmd and
+// its dependencies, so a `Cannot find module …` from the qmd child means a
+// partial or interrupted global install (`npm i -g` / `pnpm add -g`) left some
+// files unwritten. That is the caller's install shape, not a bug HQ can fix in
+// code, so the CLI surfaces an actionable reinstall remedy and SKIPS Sentry
+// capture. Sibling of qmd-native-binding-error.ts (HQ-CLI-J, unbuilt
+// better-sqlite3), qmd-collection-missing-error.ts (HQ-CLI-S),
+// qmd-llm-disabled-error.ts (HQ-CLI 7688850003) and qmd-terminated-error.ts
+// (HQ-CLI 7677702704): a failure that is NOT an hq-cli defect is printed with an
+// actionable message and never filed as a crash.
+//
+// HQ-CLI-Y (Sentry 7690356976): a qmd child died with `Cannot find module
+// './stringifyComment.js'`, its `Require stack:` rooted at
+// /usr/lib/node_modules/@indigoai-us/hq-cli/node_modules/yaml/dist/stringify/… .
+// Two compounding defects filed it as a high-priority crash AND minted a NEW
+// permanent issue per child failure: finishRunQmd's generic message
+// interpolated the caller's whole argv (query, -c value, absolute paths) AND
+// embedded the child's RAW multi-line stderr, whose `    at <fn> (<file>:<line>)`
+// lines the Sentry Node SDK then parsed as REAL frames of the hq-cli process —
+// so grouping rode foreign frames and every distinct child failure split into
+// its own issue. Bounding the message (search-index/index.ts) fixes the
+// cardinality; this classifier closes the boundary so the broken-install
+// condition reaches the operator as an actionable reinstall, not an unfixable
+// crash.
+//
+// The gate is deliberately narrow on TWO axes, read ONLY from qmd's OWN captured
+// streams (never the synthesized message — even now that it names the subcommand
+// only, the message must never be the classification substrate), so a user
+// searching for the phrase "Cannot find module" can never trip it:
+//   1. RESOLUTION TOKEN: the module-resolution failure itself — `Cannot find
+//      module`, or the CJS/ESM `MODULE_NOT_FOUND` / `ERR_MODULE_NOT_FOUND` code.
+//   2. CORROBORATOR: a Node module-loader artifact a bare query cannot
+//      synthesize — a `Require stack:` header, a `node_modules/` path, or the
+//      ESM `imported from` clause. Either axis alone would be too loose.
+// The better-sqlite3 native-binding failure (HQ-CLI-J) carries neither
+// resolution token, so it does not match here and keeps its own narrower remedy
+// — and the top-level handler checks that classifier FIRST regardless of this
+// one, so the more-actionable approve-builds remedy always wins when both could.
+/** The module-resolution failure token. `MODULE_NOT_FOUND` covers the ESM
+ *  `ERR_MODULE_NOT_FOUND` code as a substring; `Cannot find module` is the CJS
+ *  loader's message text. */
+const MODULE_RESOLUTION_TOKEN = /cannot find module|MODULE_NOT_FOUND/i;
+/** A Node module-loader artifact a user's free-text query cannot synthesize. */
+const MODULE_LOADER_ARTIFACT = /Require stack:|node_modules[\\/]|imported from/i;
+/** qmd subcommands whose collection/query is chosen by the CALLER (read surface). */
+const CALLER_READS = new Set(["search", "vsearch", "query", "get"]);
+/**
+ * The actionable remedy shown to the operator. Input-free — nothing is
+ * interpolated from the error, the argv, or qmd's output — so there is no
+ * injection surface, matching the bounded-fingerprint discipline of its
+ * siblings. Names the concrete reinstall for both a global npm and a global
+ * pnpm install.
+ *
+ * Covers BOTH qmd origins deliberately, because they cannot be told apart at
+ * runtime: HQ_QMD_BIN is honoured verbatim, and it is also the seam a dev build
+ * (and this repo's e2e harness) uses to inject the bundled qmd, so a truthy
+ * HQ_QMD_BIN is NOT a reliable "external qmd" signal. A missing module is not an
+ * hq-cli code defect on either path, so the remedy — not the classification —
+ * carries the origin nuance: it names the bundled reinstall first, then the
+ * HQ_QMD_BIN case so an operator running their own qmd is pointed at that
+ * install rather than only at hq.
+ */
+export const QMD_MODULE_MISSING_REMEDY = "hq's local search index can't start: one of its bundled modules is missing, " +
+    "which means the hq install tree is incomplete — a partial or interrupted " +
+    "install can leave some dependencies unwritten. Reinstall hq and run the " +
+    "command again: for a global install run `npm i -g @indigoai-us/hq-cli` (or " +
+    "the pnpm equivalent, `pnpm add -g @indigoai-us/hq-cli`). If you point " +
+    "HQ_QMD_BIN at your own qmd, that install is missing the module instead — " +
+    "reinstall its dependencies, or unset HQ_QMD_BIN to use the bundled copy.";
+/**
+ * The qmd process's OWN captured diagnostic — stderr then stdout. Unlike
+ * qmd-native-binding-error.ts this NEVER falls back to the synthesized
+ * `message`: the message can carry the caller's query, so reading it would let
+ * free text trip the classifier. A value with no captured streams yields "". A
+ * bare string is treated as captured text directly (test convenience).
+ */
+function capturedStreams(err) {
+    if (typeof err === "string")
+        return err;
+    if (err === null || typeof err !== "object")
+        return "";
+    const record = err;
+    const stderr = typeof record.stderr === "string" ? record.stderr : "";
+    const stdout = typeof record.stdout === "string" ? record.stdout : "";
+    return stderr || stdout ? `${stderr}\n${stdout}` : "";
+}
+/**
+ * True when `err` carries, in qmd's OWN captured streams, a module-resolution
+ * failure corroborated by a Node module-loader artifact — i.e. qmd's dependency
+ * tree is incomplete on this machine. finishRunQmd calls this on the raw streams
+ * to type the condition {@link import('../lib/search-index/index.js').QmdModuleMissingError};
+ * a true result there means the caller should reinstall.
+ */
+export function isQmdModuleMissingError(err) {
+    const text = capturedStreams(err);
+    if (!text)
+        return false;
+    return MODULE_RESOLUTION_TOKEN.test(text) && MODULE_LOADER_ARTIFACT.test(text);
+}
+/**
+ * If `err` is a caller-driven qmd module-missing failure (a QmdModuleMissingError
+ * from `hq search` or its `vsearch`/`query`/`get` siblings), return the
+ * actionable, input-free reinstall remedy; otherwise return `null`. Mirrors
+ * qmdNativeBindingErrorMessage / qmdMissingCollectionMessage so the top-level
+ * handler branches the same way: a non-null result means print-and-skip-Sentry,
+ * null means "handle as usual (capture to Sentry)".
+ *
+ * Gated on the TYPED CLASS plus a caller-reads invocation allow-list: a
+ * module-missing raised by hq's OWN reconciliation (`collection list`, `context
+ * add`, …) points at a packaging fault hq itself could be responsible for, so it
+ * stays a captured internal error rather than being silenced as the user's
+ * install.
+ */
+export function qmdModuleMissingMessage(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "QmdModuleMissingError")
+        return null;
+    const args = Array.isArray(record.args) ? record.args : [];
+    const subcommand = args[0];
+    if (typeof subcommand !== "string" || !CALLER_READS.has(subcommand))
+        return null;
+    return QMD_MODULE_MISSING_REMEDY;
+}
+//# sourceMappingURL=qmd-module-missing-error.js.map

package/dist/utils/sentry-fingerprint.js

@@ -65,13 +65,84 @@ const DEFAULT_GROUPING = "{{ default }}";
  * request identifier spliced into the name — could otherwise mint an unbounded
  * number of groups DESPITE the bounded discriminator. The finite-cardinality
  * promise must hold for the WHOLE key, so any name outside this set collapses to
- * FALLBACK_ERROR_NAME. The only first-party error carrying `rpcCode`/`status`
- * is IntegrationsCliError; add a name here only when a new bounded carrier
+ * FALLBACK_ERROR_NAME. IntegrationsCliError carries `rpcCode`/`status`; the Qmd*
+ * errors carry a process EXIT CODE in `status` and are fingerprinted on the
+ * dedicated qmd branch below (allow-listed here so their names appear verbatim
+ * rather than collapsing). Add a name here only when a new bounded carrier
  * genuinely warrants its own family of groups.
  */
-const KNOWN_ERROR_NAMES = new Set(["IntegrationsCliError"]);
+const KNOWN_ERROR_NAMES = new Set([
+    "IntegrationsCliError",
+    // qmd process failures — all extend QmdExitError except QmdBinaryMissingError,
+    // which shares the `Qmd` prefix the qmd branch keys on (HQ-CLI-Y, 7690356976).
+    "QmdExitError",
+    "QmdBinaryMissingError",
+    "QmdCollectionMissingError",
+    "QmdCollectionExistsError",
+    "QmdTerminatedError",
+    "QmdLlmDisabledError",
+    "QmdModuleMissingError",
+]);
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";
+/**
+ * The CLOSED set of qmd subcommands worth their own group — the surfaces hq
+ * drives (caller reads plus reconciliation). Anything else, including a missing
+ * or non-string args[0], collapses to `qmd:other`, so the subcommand axis is
+ * finite no matter what argv qmd was handed (a query value can never reach it).
+ */
+const KNOWN_QMD_SUBCOMMANDS = new Set([
+    "search", "vsearch", "query", "get",
+    "collection", "context", "embed", "status", "update", "cleanup",
+]);
+/**
+ * The small set of qmd process EXIT CODES worth their own group. qmd exits 1 for
+ * a general error; any other numeric code collapses to `exit:other`, so the
+ * exit-code axis stays finite. A signalled child (`status` null) never reaches
+ * this set — it groups by its signal instead (see {@link qmdDispositionToken}).
+ */
+const KNOWN_QMD_EXIT_CODES = new Set([1, 2]);
+/**
+ * qmd child TERMINATION SIGNALS worth their own group. A signalled qmd child
+ * (QmdTerminatedError: `status` null, `signal` set) carries no exit code, so
+ * without a signal axis every native crash would collapse into one `exit:other`
+ * bucket — merging the distinct failures (SIGSEGV vs SIGABRT vs SIGBUS) the
+ * termination policy deliberately keeps on separate reporting paths. Bounded:
+ * any signal outside this closed set collapses to `signal:other`, so the axis
+ * stays finite no matter what killed the child.
+ */
+const KNOWN_QMD_SIGNALS = new Set([
+    "SIGSEGV", "SIGABRT", "SIGBUS", "SIGILL", "SIGFPE",
+    "SIGKILL", "SIGTERM", "SIGINT", "SIGHUP", "SIGQUIT",
+]);
+/** The bounded qmd subcommand token (`qmd:<sub>`), read only from args[0]. */
+function qmdSubcommandToken(args) {
+    const first = Array.isArray(args) ? args[0] : undefined;
+    return typeof first === "string" && KNOWN_QMD_SUBCOMMANDS.has(first)
+        ? `qmd:${first}`
+        : "qmd:other";
+}
+/** The bounded qmd exit-code token (`exit:<code>`), read only from `status`. */
+function qmdExitToken(status) {
+    return typeof status === "number" &&
+        Number.isInteger(status) &&
+        KNOWN_QMD_EXIT_CODES.has(status)
+        ? `exit:${status}`
+        : "exit:other";
+}
+/**
+ * The bounded qmd DISPOSITION token — the fingerprint's fourth component. A
+ * signalled child (a non-empty `signal` string, `status` null) groups by
+ * `signal:<name>` from the closed allow-list so distinct native crashes stay in
+ * distinct groups; an ordinary exit groups by `exit:<code>`. Both inputs are
+ * bounded, so the axis stays finite regardless of what qmd reported.
+ */
+function qmdDispositionToken(status, signal) {
+    if (typeof signal === "string" && signal.length > 0) {
+        return KNOWN_QMD_SIGNALS.has(signal) ? `signal:${signal}` : "signal:other";
+    }
+    return qmdExitToken(status);
+}
 /**
  * Return a bounded `event.fingerprint` array for `err`, or `null` when `err`
  * carries no discriminator from the closed allowlist (in which case the caller
@@ -98,6 +169,28 @@ export function sentryFingerprintFor(err) {
     const rawName = typeof record.name === "string" && record.name.length > 0 ? record.name : null;
     if (rawName === null)
         return null;
+    // qmd process failures carry a PROCESS EXIT CODE in `status` (never an HTTP
+    // status) plus a subcommand in args[0]. Fingerprint them on a dedicated,
+    // fully-bounded key BEFORE the HTTP-status branch so an exit code is never read
+    // as an HTTP status, and so grouping is one group per (subcommand, disposition)
+    // instead of one per query — the cardinality blow-up that minted a new
+    // permanent issue per qmd child failure (HQ-CLI-Y, Sentry 7690356976). The
+    // fourth component is the DISPOSITION: an ordinary exit groups by `exit:<code>`,
+    // while a signalled child (QmdTerminatedError: status null, signal set) groups
+    // by `signal:<name>` so distinct native crashes (SIGSEGV/SIGABRT/SIGBUS) stay
+    // in distinct groups rather than collapsing into one `exit:other`. Keyed on the
+    // `Qmd` name prefix; the name is still bounded to the closed allowlist, so an
+    // unexpected Qmd* name collapses to FALLBACK_ERROR_NAME while keeping the
+    // bounded qmd discriminators.
+    if (rawName.startsWith("Qmd")) {
+        const qmdName = KNOWN_ERROR_NAMES.has(rawName) ? rawName : FALLBACK_ERROR_NAME;
+        return [
+            DEFAULT_GROUPING,
+            qmdName,
+            qmdSubcommandToken(record.args),
+            qmdDispositionToken(record.status, record.signal),
+        ];
+    }
     const name = KNOWN_ERROR_NAMES.has(rawName) ? rawName : FALLBACK_ERROR_NAME;
     const rpcCode = record.rpcCode;
     if (typeof rpcCode === "number" && Number.isInteger(rpcCode)) {

package/package.json

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