@indigoai-us/hq-cli 5.108.17 → 5.108.19

package/dist/startup-registration.js

@@ -0,0 +1,134 @@
+/**
+ * The command-registration recovery seam for the "install tree torn out from
+ * under a starting `hq`" condition (Sentry HQ-CLI-1G/1H/1J/1K).
+ *
+ * `runCli` registers commands as its last step before `program.parseAsync()` —
+ * the lazy command import or `import("./register-all.js")` and everything those
+ * pull in. That is the ONE place a module-resolution failure is provably safe to
+ * recover from: it is inside hq-cli's own graph, it runs before `parseAsync` and
+ * before the preAction hook, so no command action, telemetry, or stdin read has
+ * happened yet, and a single re-exec can therefore never run a command twice.
+ *
+ * This wraps the existing `register()` call with exactly that recovery, driven by
+ * the classifier / probe / settle wait / carrier in ./utils/install-tree-torn.ts.
+ * It changes nothing about WHICH modules are imported or in what order — only the
+ * failure handling around the existing imports. Dependency-injected in the house
+ * style of handleTopLevelError so the whole seam is unit-testable without real
+ * spawns, waits, or a real install tree.
+ */
+import { spawnSync } from "node:child_process";
+import { resolveRunningInstall } from "./utils/version-gate.js";
+import { updateLockPath } from "./utils/update-lock.js";
+import { classifyModuleNotFound, InstallTreeTornError, waitForInstallTreeSettled, } from "./utils/install-tree-torn.js";
+/**
+ * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
+ * from self-update's HQ_RESCUE_SELF_UPDATED so the two recovery paths cannot
+ * shadow each other.
+ */
+export const INSTALL_TREE_RECOVERY_GUARD_ENV = "HQ_INSTALL_TREE_RECOVERED";
+/** Operator override for the settle wait's deadline. */
+export const INSTALL_SETTLE_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_TIMEOUT_MS";
+/** Default settle deadline (ms). Overridable by {@link INSTALL_SETTLE_TIMEOUT_ENV}. */
+export const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90_000;
+/**
+ * The single dim, informational line emitted when — and only when — a wait
+ * actually happens. It tells a human why the command paused and is the e2e's
+ * synchronization point; it is never a remedy and never sets an error exit code.
+ */
+export const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish…";
+/** Resolve the settle deadline from the environment (0 = evaluate once; default on invalid). */
+export function resolveSettleTimeoutMs(env) {
+    const raw = env[INSTALL_SETTLE_TIMEOUT_ENV];
+    if (typeof raw !== "string" || raw.trim() === "")
+        return DEFAULT_INSTALL_SETTLE_TIMEOUT_MS;
+    if (!/^\d+$/.test(raw.trim()))
+        return DEFAULT_INSTALL_SETTLE_TIMEOUT_MS;
+    return Number.parseInt(raw.trim(), 10);
+}
+/**
+ * Register commands, recovering once from a torn-install module-resolution
+ * failure. On a clean registration this returns `{}` and touches nothing else.
+ * On a classified failure it waits (bounded) for the install to settle and
+ * re-execs the running install's own entrypoint once; a child (guarded), an
+ * unsettled wait, or a failed spawn each throws an {@link InstallTreeTornError}
+ * carrying bounded diagnostics so a genuinely broken install stays visible.
+ */
+export async function registerCommandsWithRecovery(args) {
+    const { register, argv, env, entryPath, stderr } = args;
+    const deps = args.deps ?? {};
+    try {
+        await register();
+        return {};
+    }
+    catch (err) {
+        const classified = classifyModuleNotFound(err);
+        // Not a module-resolution failure — rethrow the SAME object to the existing
+        // boundary, preserving today's behaviour exactly.
+        if (!classified)
+            throw err;
+        const packageRoot = resolvePackageRoot(deps);
+        // A child that already recovered must never wait or re-exec again: report
+        // once and let the boundary capture it.
+        if (env[INSTALL_TREE_RECOVERY_GUARD_ENV] === "1") {
+            throw new InstallTreeTornError({
+                cause: err,
+                classified,
+                packageRoot,
+                outcome: "guarded",
+                attempt: 2,
+                waitedMs: 0,
+                sawLock: false,
+                sawRetired: false,
+            });
+        }
+        stderr.write(`${INSTALL_TREE_WAIT_NOTICE}\n`);
+        const lockPath = (deps.lockPath ?? updateLockPath)();
+        const waitFor = deps.waitForSettled ?? waitForInstallTreeSettled;
+        const result = await waitFor({
+            target: classified.target,
+            packageRoot,
+            lockPath,
+            deadlineMs: resolveSettleTimeoutMs(env),
+        });
+        if (!result.settled) {
+            throw new InstallTreeTornError({
+                cause: err,
+                classified,
+                packageRoot,
+                outcome: "unsettled",
+                attempt: 1,
+                waitedMs: result.waitedMs,
+                sawLock: result.sawLock,
+                sawRetired: result.sawRetired,
+            });
+        }
+        const spawn = deps.spawn ?? spawnSync;
+        const execArgv = deps.execArgv ?? process.execArgv;
+        const child = spawn(process.execPath, [...execArgv, entryPath, ...argv.slice(2)], { stdio: "inherit", env: { ...env, [INSTALL_TREE_RECOVERY_GUARD_ENV]: "1" } });
+        if (child.error) {
+            throw new InstallTreeTornError({
+                cause: err,
+                classified,
+                packageRoot,
+                outcome: "reexec-failed",
+                attempt: 1,
+                waitedMs: result.waitedMs,
+                sawLock: result.sawLock,
+                sawRetired: result.sawRetired,
+            });
+        }
+        // A signal-killed child has status null; surface it as a failure exit rather
+        // than pretending the command completed (mirrors self-update's reexecHq).
+        return { reexecStatus: child.status ?? 1 };
+    }
+}
+/** Resolve the running install's package dir, tolerating any resolver failure. */
+function resolvePackageRoot(deps) {
+    try {
+        return (deps.resolveInstall ?? resolveRunningInstall)().packageRoot;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=startup-registration.js.map

package/dist/utils/install-tree-torn.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 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.
+ */
+/** The two loader-error `code`s that mean "a module could not be resolved". */
+export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND";
+/**
+ * The closed set of resolution-failure dialects, verified on Node v22.23.1 (the
+ * @sentry/node import-in-the-middle hook does not change the shapes):
+ *   - `esm-path`:    ESM importer, an absolute file (or legacyMainResolve dir)
+ *                    target — `err.url` set, or `Cannot find package '<abs>'…`.
+ *   - `esm-package`: ESM importer, a bare specifier — `Cannot find package
+ *                    '<name>' imported from <importer>`, no `err.url`.
+ *   - `cjs-path`:    CJS require of an absolute path — `Cannot find module
+ *                    '<abs>'` + `requireStack`.
+ *   - `cjs-package`: CJS require of a bare specifier — `Cannot find module
+ *                    '<name>'` + `requireStack`.
+ *   - `unknown`:     a module-not-found whose message did not parse; recovery
+ *                    still waits on the lock / retired-dir / quiet signals.
+ */
+export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "unknown";
+/**
+ * The missing thing, re-resolvable by the readiness probe:
+ *   - `path`:    an absolute filesystem path (a `.js` file, or a package dir).
+ *   - `package`: a bare package `name` resolvable from directory `from` upward.
+ *   - `unknown`: the message did not parse; treated as "present" by the probe so
+ *                readiness turns only on the lock / retired-dir / quiet signals.
+ */
+export type ModuleErrorTarget = {
+    kind: "path";
+    path: string;
+} | {
+    kind: "package";
+    name: string;
+    from: string;
+} | {
+    kind: "unknown";
+};
+export interface ClassifiedModuleError {
+    code: ModuleNotFoundCode;
+    dialect: ModuleErrorDialect;
+    /** The raw specifier the message named (absolute path or bare name), or "". */
+    specifier: string;
+    /** The importer the message named (from-clause or requireStack[0]), or "". */
+    importer: string;
+    target: ModuleErrorTarget;
+}
+/**
+ * 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 declare function packageNameOf(specifier: string): string;
+/**
+ * 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 declare function classifyModuleNotFound(err: unknown): ClassifiedModuleError | null;
+/** The filesystem surface the probe and wait use, injectable for hermetic tests. */
+export interface InstallTreeFs {
+    existsSync(p: string): boolean;
+    statSync(p: string): {
+        isDirectory(): boolean;
+    };
+    readFileSync(p: string, encoding: "utf-8"): string;
+    readdirSync(p: string): string[];
+}
+/**
+ * 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 declare function installTargetPresent(target: ModuleErrorTarget, fs?: InstallTreeFs): boolean;
+export interface WaitForInstallTreeSettledArgs {
+    target: ModuleErrorTarget;
+    /** The running install's package dir (from resolveRunningInstall), or null. */
+    packageRoot: string | null;
+    /** The shared update-lock path ($HOME/.hq/locks/cli-update.lock). */
+    lockPath: string;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    fs?: InstallTreeFs;
+    isPidAlive?: (pid: number) => boolean;
+    pollMs?: number;
+    quietMs?: number;
+    deadlineMs: number;
+}
+export interface WaitForInstallTreeSettledResult {
+    settled: boolean;
+    waitedMs: number;
+    /** A FRESH update lock held by another pid was observed at least once. */
+    sawLock: boolean;
+    /** An npm retired/staging sibling (`.hq-cli-<rand>`) was observed at least once. */
+    sawRetired: boolean;
+}
+/**
+ * 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 declare function waitForInstallTreeSettled(args: WaitForInstallTreeSettledArgs): Promise<WaitForInstallTreeSettledResult>;
+/** The recovery OUTCOME, which — not the dialect — decides capture. */
+export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed";
+export type InstallTreeTornDiagnostics = {
+    dialect: ModuleErrorDialect;
+    code: ModuleNotFoundCode;
+    specifier: string;
+    importer: string;
+    packageRoot: string;
+    outcome: InstallTreeTornOutcome;
+    attempt: 1 | 2;
+    waitedMs: number;
+    sawLock: boolean;
+    sawRetired: boolean;
+    node: string;
+};
+export interface InstallTreeTornInit {
+    /** The original loader error, carried unchanged as `cause`. */
+    cause: unknown;
+    classified: ClassifiedModuleError;
+    packageRoot: string | null;
+    outcome: InstallTreeTornOutcome;
+    attempt: 1 | 2;
+    waitedMs: number;
+    sawLock: boolean;
+    sawRetired: boolean;
+}
+/**
+ * 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 declare class InstallTreeTornError extends Error {
+    readonly diagnostics: InstallTreeTornDiagnostics;
+    constructor(init: InstallTreeTornInit);
+}
+export declare function isInstallTreeTornError(err: unknown): err is InstallTreeTornError;
+/** The exact Sentry `contexts` payload for a captured torn-install failure. */
+export declare function installTreeTornCaptureContext(err: InstallTreeTornError): {
+    contexts: {
+        install_tree_torn: InstallTreeTornDiagnostics;
+    };
+};
+/**
+ * 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 declare const INSTALL_TREE_TORN_REMEDY: string;
+/**
+ * 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 declare function installTreeTornStderrLine(err: InstallTreeTornError): string;
+//# sourceMappingURL=install-tree-torn.d.ts.map