@indigoai-us/hq-cli 5.108.17 → 5.108.19

package/dist/utils/install-tree-torn.js

@@ -0,0 +1,359 @@
+/**
+ * Detection and bounded, recovery-safe reporting for the "install tree torn out
+ * from under a starting `hq`" condition (Sentry HQ-CLI-1G/1H/1J/1K —
+ * 7713386011, 7713482655, 7713783135, 7714501738).
+ *
+ * hq-cli resolves most of its module graph lazily INSIDE `runCli` (the lazy
+ * command module or `import("./register-all.js")`, plus everything those pull in
+ * — nested `@aws-sdk/*`, `js-yaml`, `@indigoai-us/hq-cloud`). An EXTERNAL global
+ * reinstall — the outpost `hq-cli-update` systemd timer every 6h, the agent
+ * boxes' `self_update`, the desktop app — renames the installed package dir
+ * aside (`.hq-cli-<rand>`), recreates it empty, and re-extracts it file by file
+ * over ~16s. A process that started just before that rename resolves its
+ * deferred imports against a directory that no longer holds them and dies with
+ * ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND. None of those writers is the process's
+ * OWN updater (the version-gate and self-updater install synchronously under the
+ * shared lock and never overlap their own imports), so hq-cli cannot stop them —
+ * but it CAN detect the condition at the one seam where it is provably
+ * side-effect free (the registration phase, before `parseAsync` and before the
+ * preAction hook), wait (bounded) for the install to settle, and re-run itself
+ * once on the settled tree.
+ *
+ * This module is the reusable core of that recovery: a STRUCTURAL, closed
+ * classifier for the loader-error dialects Node raises; a readiness probe that
+ * re-resolves the missing target exactly as Node's resolver does; a bounded
+ * settle wait keyed on the same signals the writer leaves behind; and the typed
+ * carrier + boundary helpers (house style of package-root-diagnostics.ts) that
+ * keep a genuinely-broken install VISIBLE in Sentry with bounded, hq-derived
+ * diagnostics. The recovery seam that drives them lives in
+ * ../startup-registration.ts; version-gate.ts / self-update.ts / update-lock.ts
+ * are only READ (their exported symbols), never modified.
+ */
+import * as nodeFs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLI_NAME } from "../cli-version.js";
+import { boundedDiagnosticValue } from "./package-root-diagnostics.js";
+import { isLockStale } from "./update-lock.js";
+/** Byte caps for the (hq-derived, path-shaped) diagnostic strings. */
+const SPECIFIER_BYTES = 256;
+const IMPORTER_BYTES = 256;
+const PACKAGE_ROOT_BYTES = 256;
+const ESM_PACKAGE_RE = /^Cannot find package '([^']+)' imported from (.+)$/s;
+const CJS_MODULE_RE = /^Cannot find module '([^']+)'/s;
+const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)$/s;
+/**
+ * Reduce a bare specifier to its PACKAGE name: `@scope/name/sub` → `@scope/name`,
+ * `name/sub` → `name`, `name` → `name`. This is the unit the readiness probe
+ * re-resolves (Node looks up `node_modules/<package>/package.json`, never the
+ * subpath, when it raises the bare-specifier dialects).
+ */
+export function packageNameOf(specifier) {
+    const parts = specifier.split("/");
+    if (specifier.startsWith("@"))
+        return parts.slice(0, 2).join("/");
+    return parts[0] ?? specifier;
+}
+/**
+ * Classify a thrown value as a module-resolution failure and extract the missing
+ * target, or return `null` for anything that is not one. The decision is
+ * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND` or
+ * `MODULE_NOT_FOUND` — no argv, env, or free text is ever consulted, and any
+ * other error (including an import-time throw of another class) returns `null`
+ * so it is rethrown to the existing boundary unchanged.
+ */
+export function classifyModuleNotFound(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    const code = record.code;
+    if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND")
+        return null;
+    const message = typeof record.message === "string" ? record.message : "";
+    // (a) ESM path — `err.url` is a `file:` URL. This is checked first because the
+    // ESM path message ALSO matches the imported-from dialect (d); the url is the
+    // authoritative resolved target.
+    if (typeof record.url === "string" && record.url.startsWith("file:")) {
+        const target = fileURLToPath(record.url);
+        const importer = ESM_MODULE_IMPORTED_RE.exec(message)?.[2] ?? "";
+        return { code, dialect: "esm-path", specifier: target, importer, target: { kind: "path", path: target } };
+    }
+    // (b) ESM `Cannot find package '<spec>' imported from <importer>`. `<spec>` is
+    // a bare name for the ordinary case, or an ABSOLUTE `<dir>/index.js` token for
+    // the legacyMainResolve variant (a package dir that exists but has no usable
+    // package.json/main) — the latter is a path target.
+    const esmPkg = ESM_PACKAGE_RE.exec(message);
+    if (esmPkg) {
+        const spec = esmPkg[1];
+        const importer = esmPkg[2];
+        if (path.isAbsolute(spec)) {
+            return { code, dialect: "esm-path", specifier: spec, importer, target: { kind: "path", path: spec } };
+        }
+        return {
+            code,
+            dialect: "esm-package",
+            specifier: spec,
+            importer,
+            target: { kind: "package", name: spec, from: path.dirname(importer) },
+        };
+    }
+    // (c) CJS `Cannot find module '<spec>'` (+ Require stack). Absolute → a path
+    // target; bare → the package the require named, resolved from requireStack[0].
+    if (code === "MODULE_NOT_FOUND") {
+        const cjs = CJS_MODULE_RE.exec(message);
+        if (cjs) {
+            const spec = cjs[1];
+            const requireStack = Array.isArray(record.requireStack) ? record.requireStack : [];
+            const importer = typeof requireStack[0] === "string" ? requireStack[0] : "";
+            if (path.isAbsolute(spec)) {
+                return { code, dialect: "cjs-path", specifier: spec, importer, target: { kind: "path", path: spec } };
+            }
+            return {
+                code,
+                dialect: "cjs-package",
+                specifier: spec,
+                importer,
+                target: { kind: "package", name: packageNameOf(spec), from: path.dirname(importer) },
+            };
+        }
+    }
+    // (d) ESM `Cannot find module '<abs>' imported from <importer>` WITHOUT a url
+    // (defensive — the url arm normally wins). The specifier is the resolved
+    // absolute path.
+    const esmMod = ESM_MODULE_IMPORTED_RE.exec(message);
+    if (esmMod) {
+        const spec = esmMod[1];
+        return { code, dialect: "esm-path", specifier: spec, importer: esmMod[2], target: { kind: "path", path: spec } };
+    }
+    // (e) A module-not-found whose message did not parse — still recover, keyed on
+    // the lock / retired-dir / quiet signals only.
+    return { code, dialect: "unknown", specifier: "", importer: "", target: { kind: "unknown" } };
+}
+const nodeInstallTreeFs = {
+    existsSync: (p) => nodeFs.existsSync(p),
+    statSync: (p) => nodeFs.statSync(p),
+    readFileSync: (p, encoding) => nodeFs.readFileSync(p, encoding),
+    readdirSync: (p) => nodeFs.readdirSync(p),
+};
+/** Liveness probe with update-lock.ts's semantics (ESRCH dead, EPERM alive). */
+function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Whether the missing target is now present on disk — the readiness signal the
+ * settle wait polls. It re-resolves the SAME step Node's resolver took:
+ *   - `path`:    the file must exist; a directory target must additionally hold
+ *                a `package.json` (the legacyMainResolve case).
+ *   - `package`: walk from `from` toward the filesystem root and return true as
+ *                soon as `<dir>/node_modules/<name>/package.json` exists — the
+ *                exact ancestor walk `getPackageJSONURL` performs, done WITHOUT
+ *                `createRequire` so an ESM-only / export-conditioned package
+ *                cannot false-negative.
+ *   - `unknown`: true (readiness turns on the other signals).
+ * Any filesystem error reads as "not present" rather than throwing.
+ */
+export function installTargetPresent(target, fs = nodeInstallTreeFs) {
+    try {
+        if (target.kind === "unknown")
+            return true;
+        if (target.kind === "path") {
+            if (!fs.existsSync(target.path))
+                return false;
+            try {
+                if (fs.statSync(target.path).isDirectory()) {
+                    return fs.existsSync(path.join(target.path, "package.json"));
+                }
+            }
+            catch {
+                return false;
+            }
+            return true;
+        }
+        // package: ancestor walk from `from`.
+        let dir = path.resolve(target.from);
+        for (;;) {
+            const manifest = path.join(dir, "node_modules", target.name, "package.json");
+            if (fs.existsSync(manifest))
+                return true;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return false;
+            dir = parent;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** The scope/leaf split of CLI_NAME, e.g. `@indigoai-us` / `hq-cli`. */
+function cliNameParts() {
+    const slash = CLI_NAME.indexOf("/");
+    if (slash === -1)
+        return { scope: null, leaf: CLI_NAME };
+    return { scope: CLI_NAME.slice(0, slash), leaf: CLI_NAME.slice(slash + 1) };
+}
+/** Whether a FRESH update lock is held by a DIFFERENT live pid (blocks readiness). */
+function freshForeignLockHeld(lockPath, nowMs, isPidAlive, fs) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockPath, "utf-8");
+    }
+    catch {
+        return false; // no lock (ENOENT) or unreadable — not a fresh foreign holder
+    }
+    if (isLockStale(raw, nowMs, isPidAlive))
+        return false;
+    try {
+        const info = JSON.parse(raw);
+        if (info.pid === process.pid)
+            return false; // our own lock never blocks us
+    }
+    catch {
+        return false; // isLockStale already treats unparseable as stale, unreachable
+    }
+    return true;
+}
+/** Whether an npm retired/staging sibling (`.<leaf>-*`) sits beside packageRoot. */
+function retiredSiblingPresent(packageRoot, fs) {
+    const { leaf } = cliNameParts();
+    const stagingPrefix = `.${leaf}-`;
+    const parent = path.dirname(packageRoot);
+    const entries = fs.readdirSync(parent); // caller treats a throw as "not ready"
+    return entries.some((entry) => entry.startsWith(stagingPrefix));
+}
+/** Whether packageRoot's own manifest is healthy (`name === CLI_NAME`). */
+function packageRootHealthy(packageRoot, fs) {
+    const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
+    return manifest.name === CLI_NAME;
+}
+/**
+ * Poll until the install tree has been continuously READY for `quietMs`, or the
+ * `deadlineMs` passes. READY means: (i) no FRESH update lock held by another pid,
+ * (ii) the missing target is present, and — when `packageRoot` is known —
+ * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and
+ * (iv) no `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem
+ * error makes its condition "not ready" rather than throwing. `deadlineMs === 0`
+ * evaluates readiness exactly once (no waiting); otherwise the whole wait is
+ * bounded, so the caller can never hang.
+ */
+export async function waitForInstallTreeSettled(args) {
+    const now = args.now ?? Date.now;
+    const sleep = args.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const fs = args.fs ?? nodeInstallTreeFs;
+    const isPidAlive = args.isPidAlive ?? defaultIsPidAlive;
+    const pollMs = args.pollMs ?? 250;
+    const quietMs = args.quietMs ?? 1500;
+    const deadlineMs = args.deadlineMs;
+    const start = now();
+    let readySince = null;
+    let sawLock = false;
+    let sawRetired = false;
+    for (;;) {
+        const t = now();
+        const foreignLock = freshForeignLockHeld(args.lockPath, t, isPidAlive, fs);
+        if (foreignLock)
+            sawLock = true;
+        let ready = !foreignLock && installTargetPresent(args.target, fs);
+        if (ready && args.packageRoot) {
+            try {
+                if (!packageRootHealthy(args.packageRoot, fs))
+                    ready = false;
+            }
+            catch {
+                ready = false;
+            }
+            if (ready) {
+                try {
+                    if (retiredSiblingPresent(args.packageRoot, fs)) {
+                        sawRetired = true;
+                        ready = false;
+                    }
+                }
+                catch {
+                    ready = false;
+                }
+            }
+        }
+        if (ready) {
+            if (readySince === null)
+                readySince = t;
+        }
+        else {
+            readySince = null;
+        }
+        const waitedMs = t - start;
+        if (ready && (deadlineMs === 0 || t - readySince >= quietMs)) {
+            return { settled: true, waitedMs, sawLock, sawRetired };
+        }
+        if (waitedMs >= deadlineMs) {
+            return { settled: false, waitedMs, sawLock, sawRetired };
+        }
+        await sleep(pollMs);
+    }
+}
+/** The fixed, input-free carrier message (grouping cardinality stays bounded). */
+const INSTALL_TREE_TORN_MESSAGE = "hq-cli install tree was being rewritten while this command started";
+/**
+ * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
+ * diagnostics. Fixed `name`/`message` (no argv, path, or free text in either),
+ * `cause` = the original loader error, and a bounded `diagnostics` object whose
+ * only interpolated strings are the hq-derived specifier/importer/packageRoot,
+ * each capped. Mirrors PackageRootResolutionError's construction discipline.
+ */
+export class InstallTreeTornError extends Error {
+    diagnostics;
+    constructor(init) {
+        super(INSTALL_TREE_TORN_MESSAGE);
+        this.name = "InstallTreeTornError";
+        this.cause = init.cause;
+        this.diagnostics = {
+            dialect: init.classified.dialect,
+            code: init.classified.code,
+            specifier: boundedDiagnosticValue(init.classified.specifier, SPECIFIER_BYTES),
+            importer: boundedDiagnosticValue(init.classified.importer, IMPORTER_BYTES),
+            packageRoot: boundedDiagnosticValue(init.packageRoot ?? "", PACKAGE_ROOT_BYTES),
+            outcome: init.outcome,
+            attempt: init.attempt,
+            waitedMs: init.waitedMs,
+            sawLock: init.sawLock,
+            sawRetired: init.sawRetired,
+            node: process.version,
+        };
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export function isInstallTreeTornError(err) {
+    return err instanceof InstallTreeTornError;
+}
+/** The exact Sentry `contexts` payload for a captured torn-install failure. */
+export function installTreeTornCaptureContext(err) {
+    return { contexts: { install_tree_torn: err.diagnostics } };
+}
+/**
+ * The fixed, input-free operator remedy. It names the likely writers (so a
+ * human knows this was not their command's fault) and the reinstall commands,
+ * and interpolates NOTHING — the only per-event value is the bounded specifier
+ * appended by {@link installTreeTornStderrLine}.
+ */
+export const INSTALL_TREE_TORN_REMEDY = "the hq-cli install was being updated by another process (the box's hq-cli-update " +
+    "timer, the desktop app, or another hq command) while this command started. " +
+    "Re-run your command; if it keeps failing, reinstall with " +
+    "`npm i -g @indigoai-us/hq-cli` (or `pnpm add -g @indigoai-us/hq-cli`).";
+/**
+ * The single actionable stderr line for a captured torn-install failure: the
+ * fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv.
+ */
+export function installTreeTornStderrLine(err) {
+    const specifier = err.diagnostics.specifier;
+    return specifier
+        ? `${INSTALL_TREE_TORN_REMEDY} (missing: ${specifier})`
+        : INSTALL_TREE_TORN_REMEDY;
+}
+//# sourceMappingURL=install-tree-torn.js.map

package/dist/utils/sentry-fingerprint.js

@@ -91,6 +91,18 @@ const KNOWN_ERROR_NAMES = new Set([
     // listed defensively so a future capture path cannot mint an unbounded group
     // (HQ-CLI-1A).
     "QmdWorkdirMissingError",
+    // A torn-install failure the bounded settle-wait + single re-exec could not
+    // recover (HQ-CLI-1G/1H/1J/1K). Fingerprinted on its own branch below by the
+    // bounded `diagnostics.outcome`, so the whole family groups into ≤3 issues.
+    "InstallTreeTornError",
+]);
+/**
+ * The CLOSED set of InstallTreeTornError recovery outcomes worth their own
+ * group. Anything else collapses to `outcome:other`, so the axis stays finite;
+ * the carrier's message is fixed, so this outcome IS the only discriminator.
+ */
+const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
+    "guarded", "unsettled", "reexec-failed",
 ]);
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";
@@ -200,6 +212,20 @@ export function sentryFingerprintFor(err) {
             qmdDispositionToken(record.status, record.signal),
         ];
     }
+    // A torn-install failure carries neither an rpcCode nor an HTTP status; its
+    // only bounded discriminator is the recovery `diagnostics.outcome`. Keyed
+    // BEFORE the rpc/status branches so the family groups into ≤3 predictable
+    // issues (guarded / unsettled / reexec-failed) rather than one fungible bucket.
+    if (rawName === "InstallTreeTornError") {
+        const diagnostics = record.diagnostics;
+        const outcome = diagnostics !== null && typeof diagnostics === "object"
+            ? diagnostics.outcome
+            : undefined;
+        const token = typeof outcome === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(outcome)
+            ? `outcome:${outcome}`
+            : "outcome:other";
+        return [DEFAULT_GROUPING, "InstallTreeTornError", token];
+    }
     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.108.17",
+  "version": "5.108.19",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -31,7 +31,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.11",
+    "@indigoai-us/hq-cloud": "~6.16.23",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",