@indigoai-us/hq-cli 5.101.2 → 5.101.3

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.101.3] — 2026-08-15
+
 ## [5.101.2] — 2026-08-15
 
 ### Fixed

package/dist/lib/search-index/index.d.ts

@@ -63,6 +63,22 @@ export declare class QmdExitError extends Error {
 export declare class QmdCollectionMissingError extends QmdExitError {
     name: string;
 }
+/**
+ * qmd's `collection add` exited non-zero because the requested name is ALREADY
+ * registered in qmd's YAML config under exactly that name — the idempotent,
+ * already-satisfied duplicate (qmd 2.5.3 prints `Collection '<name>' already
+ * exists.`). `collectionName` carries the parsed name so a caller can confirm
+ * the duplicate is the collection it was adding. Distinct from qmd's DIFFERENT
+ * path+pattern duplicate ("A collection already exists for this path and
+ * pattern:"), which names ANOTHER collection, carries no quoted-name form, and
+ * stays a plain {@link QmdExitError} so it keeps failing loud. HQ-CLI-Q
+ * (Sentry 7670823899).
+ */
+export declare class QmdCollectionExistsError extends QmdExitError {
+    readonly collectionName: string;
+    name: string;
+    constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, collectionName: string);
+}
 export type ResolveQmdBinOptions = {
     env?: Record<string, string | undefined>;
     isExecutable?: (candidate: string) => boolean;
@@ -241,7 +257,21 @@ export type ReconcileCollectionsOptions = {
     bin?: string;
     runner?: QmdProcessRunner;
 };
-/** Register expected collections that qmd does not yet know about. */
+/**
+ * Register expected collections that qmd does not yet know about, returning the
+ * collections this call actually created (a `collection add` that exited 0).
+ *
+ * A same-name idempotent duplicate — qmd already owns the exact requested name
+ * in its YAML config (`Collection '<name>' already exists.`), while the
+ * SQLite-backed `collection list` we derive `missing` from had diverged — is
+ * NOT a failure. Reconciliation still issues the `context add`, whose qmd-side
+ * resyncConfig re-syncs YAML into SQLite and heals the divergence that provoked
+ * the retry, then continues with later collections; such a pre-existing
+ * collection is excluded from the returned list. Every other qmd failure still
+ * propagates: the DIFFERENT path+pattern duplicate, a same-name duplicate that
+ * named a different collection, a missing collection, a `context add` failure,
+ * a missing/unbuilt qmd binary. HQ-CLI-Q (Sentry 7670823899).
+ */
 export declare function reconcileCollections(hqRoot: string, options?: ReconcileCollectionsOptions): SearchCollection[];
 export declare function listRegisteredCollections(hqRoot: string, options?: RunQmdOptions): Set<string>;
 export {};

package/dist/lib/search-index/index.js

@@ -42,6 +42,25 @@ export class QmdExitError extends Error {
 export class QmdCollectionMissingError extends QmdExitError {
     name = 'QmdCollectionMissingError';
 }
+/**
+ * qmd's `collection add` exited non-zero because the requested name is ALREADY
+ * registered in qmd's YAML config under exactly that name — the idempotent,
+ * already-satisfied duplicate (qmd 2.5.3 prints `Collection '<name>' already
+ * exists.`). `collectionName` carries the parsed name so a caller can confirm
+ * the duplicate is the collection it was adding. Distinct from qmd's DIFFERENT
+ * path+pattern duplicate ("A collection already exists for this path and
+ * pattern:"), which names ANOTHER collection, carries no quoted-name form, and
+ * stays a plain {@link QmdExitError} so it keeps failing loud. HQ-CLI-Q
+ * (Sentry 7670823899).
+ */
+export class QmdCollectionExistsError extends QmdExitError {
+    collectionName;
+    name = 'QmdCollectionExistsError';
+    constructor(message, args, status, stdout, stderr, collectionName) {
+        super(message, args, status, stdout, stderr);
+        this.collectionName = collectionName;
+    }
+}
 function isExecutable(candidate) {
     try {
         fs.accessSync(candidate, fs.constants.X_OK);
@@ -643,6 +662,18 @@ function finishRunQmd(result, bin, args) {
     if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(detail)) {
         throw new QmdCollectionMissingError(message, args, normalized.status, normalized.stdout, normalized.stderr);
     }
+    // qmd's same-name duplicate: `collection add` targeted a name YAML already
+    // owns (`Collection '<name>' already exists.`). Reconciliation treats this
+    // exact shape as already-satisfied (HQ-CLI-Q). The DIFFERENT path+pattern
+    // duplicate ("A collection already exists for this path and pattern:") names
+    // another collection and carries no quoted-name form, so it never matches and
+    // stays a plain QmdExitError. Colour is off under capture (qmd gates on
+    // isTTY) and any surrounding ANSI sits outside this substring, so the plain
+    // match is robust either way.
+    const alreadyExists = /Collection '([^']+)' already exists\./.exec(detail);
+    if (alreadyExists) {
+        throw new QmdCollectionExistsError(message, args, normalized.status, normalized.stdout, normalized.stderr, alreadyExists[1]);
+    }
     throw new QmdExitError(message, args, normalized.status, normalized.stdout, normalized.stderr);
 }
 /** Run qmd with captured output and typed failures. */
@@ -741,16 +772,41 @@ export function deriveCollections(hqRoot) {
     }
     return collections;
 }
-/** Register expected collections that qmd does not yet know about. */
+/**
+ * Register expected collections that qmd does not yet know about, returning the
+ * collections this call actually created (a `collection add` that exited 0).
+ *
+ * A same-name idempotent duplicate — qmd already owns the exact requested name
+ * in its YAML config (`Collection '<name>' already exists.`), while the
+ * SQLite-backed `collection list` we derive `missing` from had diverged — is
+ * NOT a failure. Reconciliation still issues the `context add`, whose qmd-side
+ * resyncConfig re-syncs YAML into SQLite and heals the divergence that provoked
+ * the retry, then continues with later collections; such a pre-existing
+ * collection is excluded from the returned list. Every other qmd failure still
+ * propagates: the DIFFERENT path+pattern duplicate, a same-name duplicate that
+ * named a different collection, a missing collection, a `context add` failure,
+ * a missing/unbuilt qmd binary. HQ-CLI-Q (Sentry 7670823899).
+ */
 export function reconcileCollections(hqRoot, options = {}) {
     const runOptions = { bin: options.bin, runner: options.runner, cwd: hqRoot };
     const registered = listRegisteredCollections(hqRoot, runOptions);
     const missing = deriveCollections(hqRoot).filter((collection) => !registered.has(collection.name));
+    const created = [];
     for (const collection of missing) {
-        runQmd(['collection', 'add', collection.path, '--name', collection.name, '--mask', collection.mask], runOptions);
+        try {
+            runQmd(['collection', 'add', collection.path, '--name', collection.name, '--mask', collection.mask], runOptions);
+            created.push(collection);
+        }
+        catch (error) {
+            // Only the exact same-name duplicate for THIS collection is already
+            // satisfied. Anything else — including a same-name duplicate that names a
+            // different collection — stays fatal.
+            if (!(error instanceof QmdCollectionExistsError) || error.collectionName !== collection.name)
+                throw error;
+        }
         runQmd(['context', 'add', `qmd://${collection.name}`, collection.context], runOptions);
     }
-    return missing;
+    return created;
 }
 export function listRegisteredCollections(hqRoot, options = {}) {
     const result = runQmd(['collection', 'list'], { ...options, cwd: options.cwd ?? hqRoot });

package/dist/main.d.ts

@@ -5,6 +5,11 @@
 import "./node-preflight.js";
 import "./node-network-compat.js";
 import { Sentry } from "./sentry.js";
+export type StreamErrorDependencies = {
+    stderr: Pick<typeof process.stderr, "write">;
+    exit: (code: number) => void;
+};
+export declare function handleStreamError(err: NodeJS.ErrnoException, deps?: StreamErrorDependencies): void;
 export declare function runCli(): Promise<void>;
 export type TopLevelErrorDependencies = {
     sentry: Pick<typeof Sentry, "captureException">;

package/dist/main.js

@@ -83,19 +83,47 @@ import { isPackageRootResolutionError, packageRootCaptureContext, } from "./util
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 /** Hard upper bound for non-user-visible release-health finalization. */
 const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
-// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
-// the pipe early. This covers the ASYNC path — an 'error' event emitted on the
-// stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
-// console.log inside a command) is handled in the top-level catch below; both
-// share `isEpipe` (HQ-6B).
-const onPipeError = (err) => {
+const defaultStreamErrorDependencies = {
+    stderr: process.stderr,
+    exit: (code) => process.exit(code),
+};
+// Handle an 'error' event on process.stdout/stderr without turning a benign
+// machine-state condition into a Sentry fatal.
+//   - EPIPE: a downstream reader closed the pipe early (`hq … | head`,
+//     `source <(hq …)`, a parent that exited) — a clean exit 0, no capture. The
+//     SYNCHRONOUS path (a `write EPIPE` thrown straight out of console.log) is
+//     handled in the top-level catch below; both share `isEpipe` (HQ-6B).
+//   - ENOSPC / EDQUOT / EROFS: a full disk, exhausted quota, or read-only mount
+//     (e.g. stdout redirected to a file that fills up) — the user's machine,
+//     not an hq-cli defect. Print one actionable line (best-effort; the same
+//     disk may reject it) and exit 1 WITHOUT rethrowing, so it never becomes an
+//     uncaughtException that ships a fatal (HQ-CLI-R). sentry.ts's
+//     path-independent beforeSend also drops it, covering the buffered-write
+//     route that never surfaces here.
+//   - Anything else: rethrow — an unknown stream failure must stay loud.
+// Exported in dependency-injectable form (mirroring handleTopLevelError) so the
+// process boundary stays unit-testable through the ./main.js import seam.
+export function handleStreamError(err, deps = defaultStreamErrorDependencies) {
     if (isEpipe(err)) {
-        process.exit(0);
+        deps.exit(0);
+        return;
+    }
+    const envMessage = environmentalFsErrorMessage(err);
+    if (envMessage) {
+        try {
+            deps.stderr.write(`hq: ${envMessage}\n`);
+        }
+        catch {
+            // The same full disk / read-only mount can reject this write too; there
+            // is nothing more to surface, but we still exit non-zero below.
+        }
+        deps.exit(1);
+        return;
     }
     throw err;
-};
-process.stdout.on("error", onPipeError);
-process.stderr.on("error", onPipeError);
+}
+process.stdout.on("error", (err) => handleStreamError(err));
+process.stderr.on("error", (err) => handleStreamError(err));
 initSentry();
 const program = new Command();
 program

package/dist/sentry.js

@@ -5,6 +5,7 @@ import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
 import { isEpipe } from "./utils/epipe.js";
+import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -18,6 +19,17 @@ import { isEpipe } from "./utils/epipe.js";
 export function epipeAwareBeforeSend(event, hint) {
     if (isEpipe(hint?.originalException))
         return null;
+    // Path-independent belt for environmental filesystem failures (ENOSPC /
+    // EDQUOT / EROFS — a full disk, exhausted quota, or read-only mount, e.g.
+    // stdout redirected to a file that fills up). These are the user's machine,
+    // never an hq-cli defect, and can surface by several routes: a synchronous
+    // throw through the top-level boundary, a rethrow from the stdout/stderr
+    // 'error' listener, or a buffered-write uncaughtException that never reaches
+    // either. handleTopLevelError already prints an actionable message for the
+    // boundary route; dropping the event here suppresses the fatal regardless of
+    // route, while the CLI still exits non-zero. HQ-CLI-R (Sentry 7671416365).
+    if (environmentalFsErrorMessage(hint?.originalException))
+        return null;
     return beforeSend(event, hint);
 }
 export function initSentry() {

package/package.json

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