@indigoai-us/hq-cli 5.108.1 → 5.108.3

package/dist/utils/qmd-query-document-error.js

@@ -0,0 +1,117 @@
+// src/utils/qmd-query-document-error.ts
+//
+// Classify a qmd failure caused by a MALFORMED QUERY DOCUMENT — qmd's `query`
+// subcommand rejected the caller's positional because, read as a multi-line
+// query document, its lines lack the required lex:/vec:/hyde:/intent:/expand:
+// prefix — rather than an hq-cli code defect. This is the caller's INPUT SHAPE,
+// not a bug HQ can fix in code, so the CLI surfaces an actionable, query-free
+// remedy and SKIPS Sentry capture. Sibling of qmd-llm-disabled-error.ts (HQ-CLI
+// 7688850003), qmd-module-missing-error.ts (HQ-CLI-Y) and
+// qmd-store-missing-error.ts (HQ-CLI-16): a failure that is NOT an hq-cli defect
+// is printed with an actionable message and never filed as a crash.
+//
+// HQ-CLI-1B (Sentry indigo-d0/hq-cli 7705711476): `hq search --mode hybrid`
+// maps to `qmd query`, which passes the caller's query byte-for-byte. Fleet
+// agents forward a whole Slack message (prose, a blank line, a Block Kit payload,
+// a fenced json block) as the query, so qmd received a MULTI-LINE positional and
+// parsed it as a query document; qmd 2.5.3 requires every line of a multi-line
+// document to carry a prefix (dist/cli/qmd.js:2210) and exited 1 with `Line 1 is
+// missing a lex:/vec:/hyde:/intent: prefix. Each line in a query document must
+// start with one.`. hq-cli had no classifier for that wording, so finishRunQmd
+// raised a plain QmdExitError that reached the boundary's final else and was
+// captured — 28 of the issue's 29 events. buildSearchArgs now normalises free
+// text to one line so the common case never reaches qmd multi-line; this
+// classifier is the backstop for a genuinely malformed structured document.
+//
+// The gate is deliberately narrow on TWO axes so it can neither be tripped by
+// user input nor silence a real bug, exactly as qmd-llm-disabled-error.ts
+// documents:
+//   1. CLASS: only a QmdQueryDocumentError (the typed subclass finishRunQmd
+//      raises for the query-document wording) qualifies — never a plain
+//      QmdExitError, even one whose message carries the same words.
+//   2. INVOCATION: only the `query` subcommand, the sole caller-driven read that
+//      parses a query document. Any other subcommand returns null and stays on
+//      the captured-error path.
+// The predicate reads qmd's OWN captured streams, never the synthesized message
+// (which embeds the caller's argv), so free text can never classify.
+/**
+ * qmd 2.5.3's query-DOCUMENT syntax diagnostics (dist/cli/qmd.js:2157-2217,
+ * parseStructuredQuery). The reported crash is the ":2210" wording; the whole
+ * FAMILY is matched — not one sentence — so a mixed-expand, duplicate-intent,
+ * empty-prefixed-line, intent-alone or embedded-newline document is classified
+ * too. Every phrase is unique to qmd's query-document parser, and only the
+ * `query` subcommand reaches it, so no other qmd failure emits any of them. Read
+ * from the exact pinned version (`@tobilu/qmd` 2.5.3, not a range).
+ */
+const QUERY_DOCUMENT_SYNTAX = new RegExp([
+    "is missing a lex:/vec:/hyde:/intent: prefix",
+    "Each line in a query document must start with one",
+    "query documents cannot mix expand with typed lines",
+    "only one intent: line is allowed per query document",
+    "intent: must include text",
+    "intent: cannot appear alone",
+    "contains a newline\\. Keep each query on a single line",
+    "\\((?:lex|vec|hyde):\\) must include text",
+    "expand: query must include text",
+].join("|"), "i");
+/** The caller-driven read whose positional qmd parses as a query DOCUMENT. */
+const QUERY_DOCUMENT_READS = new Set(["query"]);
+/**
+ * The actionable remedy shown to the caller. 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.
+ */
+export const QMD_QUERY_DOCUMENT_REMEDY = "Hybrid search was given a multi-line query, and qmd read it as a structured " +
+    "query document whose lines must each begin with a lex:, vec:, hyde:, or " +
+    "intent: prefix. Put your search terms on a single line, or prefix every line, " +
+    "then run the command again.";
+/**
+ * qmd's OWN captured streams (stderr then stdout), joined. The synthesized
+ * `message` is deliberately NOT consulted: it embeds the caller's qmd arguments,
+ * so reading it would let a user query for one of these phrases trip the
+ * classifier. A bare string is treated as captured text directly (test
+ * convenience). A value with no captured streams yields "".
+ */
+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 query-document
+ * syntax diagnostic — i.e. qmd's `query` parser rejected the positional as a
+ * malformed document. finishRunQmd calls this on the raw streams to type the
+ * condition {@link import('../lib/search-index/index.js').QmdQueryDocumentError}.
+ */
+export function isQmdQueryDocumentError(err) {
+    const text = capturedStreams(err);
+    if (!text)
+        return false;
+    return QUERY_DOCUMENT_SYNTAX.test(text);
+}
+/**
+ * If `err` is a caller-driven qmd query-document failure (a QmdQueryDocumentError
+ * from `hq search --mode hybrid`, i.e. the `query` read), return the actionable,
+ * input-free remedy; otherwise return `null`. Mirrors qmdLlmDisabledMessage /
+ * qmdModuleMissingMessage 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)".
+ */
+export function qmdQueryDocumentMessage(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "QmdQueryDocumentError")
+        return null;
+    const args = Array.isArray(record.args) ? record.args : [];
+    const subcommand = args[0];
+    if (typeof subcommand !== "string" || !QUERY_DOCUMENT_READS.has(subcommand))
+        return null;
+    return QMD_QUERY_DOCUMENT_REMEDY;
+}
+//# sourceMappingURL=qmd-query-document-error.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * True when `err` is a qmd working-directory-missing failure: it carries the
+ * QmdWorkdirMissingError name and an hq-populated `workdir`. Accepts either the
+ * thrown error or a bare `{ name, workdir }` probe object. A true result means
+ * the caller should print the classified remedy, exit non-zero, and SKIP Sentry
+ * capture.
+ */
+export declare function isQmdWorkdirMissingError(err: unknown): boolean;
+/**
+ * If `err` is a qmd working-directory-missing failure, return the actionable
+ * remedy; otherwise return `null`. Mirrors qmdStoreMissingMessage /
+ * qmdStoreUnopenableMessage 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". The working directory is read STRUCTURALLY from the error's own
+ * hq-populated `workdir` field, NEVER from qmd's output.
+ */
+export declare function qmdWorkdirMissingMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-workdir-missing-error.d.ts.map

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

@@ -0,0 +1,78 @@
+// src/utils/qmd-workdir-missing-error.ts
+//
+// Classify a qmd spawn failure caused by a MISSING WORKING DIRECTORY — the
+// directory the qmd child was told to run in (`cwd`, always the resolved hq
+// root at the qmd call sites) does not exist — rather than an hq-cli code
+// defect or a genuinely missing qmd. This is the caller's LOCAL filesystem (a
+// deleted tree, a `--hq-root` pointing at a directory that is not there), not a
+// bug HQ can fix in code, so the CLI surfaces an actionable remedy and SKIPS
+// Sentry capture. Sibling of qmd-store-missing-error.ts (HQ-CLI-16, a missing
+// STORE directory) and qmd-store-unopenable-error.ts (HQ-CLI-18): a failure
+// that is NOT an hq-cli defect is printed with an actionable message and never
+// filed as a crash.
+//
+// HQ-CLI-1A (Sentry indigo-d0/hq-cli 7705642434): `hq index status --hq-root
+// /home/ec2-user/hq` spawned the bundled qmd as `<node interpreter> <qmd
+// launcher>`, and spawnSync failed with `spawnSync /usr/bin/node ENOENT`. On
+// Linux, spawnSync reports ENOENT with `path`/`syscall` set to the COMMAND both
+// when the command is missing AND when chdir into `cwd` fails — two distinct
+// causes with byte-identical text. finishRunQmd was handed only the qmd
+// launcher path, so it blamed a THIRD path Node never faulted
+// (`QmdBinaryMissingError: Unable to execute qmd at …/@tobilu/qmd/bin/qmd`) with
+// a remedy (`Install @tobilu/qmd`) that cannot fix either real cause, and — with
+// no boundary branch for it — the misattributed error was captured as a crash.
+// finishRunQmd now disambiguates at the failure site: when the ENOENT is a
+// missing working directory it raises the typed carrier this module classifies.
+//
+// Classification is STRUCTURAL — the typed carrier's own `name` plus its
+// hq-populated `workdir` field, NEVER a text match on qmd's output or the
+// caller's argv — so a search query or a document body can never trip it, and
+// the class need not be imported here (avoiding a cycle with the module that
+// defines it). Reading `name`/`workdir` off the error object also lets the
+// top-level boundary, which reconstructs typed carriers structurally, branch on
+// it the same way it does the sibling qmd errors.
+/**
+ * True when `err` is a qmd working-directory-missing failure: it carries the
+ * QmdWorkdirMissingError name and an hq-populated `workdir`. Accepts either the
+ * thrown error or a bare `{ name, workdir }` probe object. A true result means
+ * the caller should print the classified remedy, exit non-zero, and SKIP Sentry
+ * capture.
+ */
+export function isQmdWorkdirMissingError(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const record = err;
+    return (record.name === "QmdWorkdirMissingError" &&
+        typeof record.workdir === "string" &&
+        record.workdir.length > 0);
+}
+/**
+ * The actionable remedy, naming the working directory that does not exist. The
+ * directory is an hq-DERIVED value — the resolved `cwd` (the hq root) the qmd
+ * child was handed — never caller argv/query or upstream free text, so the line
+ * stays input-free. Deliberately does NOT suggest reinstalling qmd (the reported
+ * misattribution's dead-end remedy) or `hq index sync` (reconciliation runs the
+ * same spawn and would hit the identical failure, a dead-end loop): the only fix
+ * is to make the working directory exist.
+ */
+function remedyMessage(workdir) {
+    return (`hq's working directory (${workdir}) does not exist, so its local search index ` +
+        "could not run there. This is your machine's filesystem, not an hq bug: " +
+        "re-create that directory, or re-run with --hq-root pointing at a directory " +
+        "that exists.");
+}
+/**
+ * If `err` is a qmd working-directory-missing failure, return the actionable
+ * remedy; otherwise return `null`. Mirrors qmdStoreMissingMessage /
+ * qmdStoreUnopenableMessage 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". The working directory is read STRUCTURALLY from the error's own
+ * hq-populated `workdir` field, NEVER from qmd's output.
+ */
+export function qmdWorkdirMissingMessage(err) {
+    if (!isQmdWorkdirMissingError(err))
+        return null;
+    const record = err;
+    return remedyMessage(record.workdir);
+}
+//# sourceMappingURL=qmd-workdir-missing-error.js.map

package/dist/utils/sentry-fingerprint.js

@@ -84,6 +84,13 @@ const KNOWN_ERROR_NAMES = new Set([
     "QmdModuleMissingError",
     "QmdStoreMissingError",
     "QmdStoreUnopenableError",
+    "QmdQueryDocumentError",
+    "QmdModelDownloadError",
+    // Shares the `Qmd` prefix the qmd branch keys on. The boundary now SUPPRESSES
+    // capture for this class, so it should never reach a capture route — allow-
+    // listed defensively so a future capture path cannot mint an unbounded group
+    // (HQ-CLI-1A).
+    "QmdWorkdirMissingError",
 ]);
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.108.1",
+  "version": "5.108.3",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -11,6 +11,7 @@
     "dist",
     "!dist/**/*.map",
     "assets/scaffold",
+    "assets/mesh-daemon",
     "CHANGELOG.md"
   ],
   "scripts": {
@@ -35,10 +36,12 @@
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",
+    "ajv": "^8.20.0",
     "better-sqlite3": "^12.11.1",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "js-yaml": "^4.1.0",
+    "mqtt": "5.15.2",
     "open": "^10.1.0",
     "semver": "^7.6.3",
     "simple-git": "^3.27.0",
@@ -52,6 +55,7 @@
     "@types/node": "^22.0.0",
     "@types/semver": "^7.5.8",
     "@vitest/coverage-v8": "4.1.6",
+    "aedes": "1.1.2",
     "aws-sdk-client-mock": "^4.1.0",
     "eslint": "^10.5.0",
     "husky": "^9.1.7",