@indigoai-us/hq-cli 5.299.0 → 5.301.0

package/dist/lib/mesh/live/daemon/work-subscribe.d.ts

@@ -3,9 +3,9 @@
  * Owns live-cache.json writes. Presence publish stays on PresenceClient.
  */
 import type { IClientOptions } from "mqtt";
+import type { MeshMqttEventClient } from "./mqtt-events.js";
 import { type PersonalCredentialsFetcher } from "./credentials.js";
-export interface WorkCacheMqtt {
-    on(event: string, handler: (...args: any[]) => void): unknown;
+export interface WorkCacheMqtt extends MeshMqttEventClient {
     subscribe(topic: string, opts: {
         qos: 0 | 1;
     }, cb?: (err?: Error | null) => void): unknown;

package/dist/utils/self-update.js

@@ -748,7 +748,7 @@ async function updateAndReexec(argv, flavor, known, deps) {
             console.error(chalk.dim(`  Or repair the install: hq rescue`));
         }
         console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
-        await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result.code, env, flavor.noun === "rescue");
+        await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result, env, flavor.noun === "rescue");
         return { action: "update-failed", latest };
     }
     if (installSnapshot)
@@ -801,10 +801,52 @@ async function updateAndReexec(argv, flavor, known, deps) {
     console.error(chalk.dim(`✓ hq-cli updated to ${latest}.`));
     return { action: "reexec", reexecStatus: status, latest };
 }
-const SELF_UPDATE_ERROR_CLASSES = new Set(["MODULE_NOT_FOUND", "EACCES", "EEXIST"]);
-async function captureSelfUpdateOutcome(action, fromVersion, targetVersion, installFlavor, code, env, flushBeforeExit) {
+const SELF_UPDATE_ERROR_CLASSES = new Set([
+    "MODULE_NOT_FOUND",
+    "ENOENT",
+    "EACCES",
+    "EEXIST",
+    "E404",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "EPERM",
+    "ETARGET",
+    "ETIMEDOUT",
+]);
+function selfUpdateErrorReason(code, failureKind) {
+    switch (code) {
+        case "MODULE_NOT_FOUND":
+            return "module_missing";
+        case "ENOENT":
+            return "program_not_found";
+        case "EACCES":
+        case "EPERM":
+            return "permission_denied";
+        case "EEXIST":
+            return "file_collision";
+        case "E404":
+            return "npm_package_not_found";
+        case "ETARGET":
+            return "npm_target_unavailable";
+        case "EAI_AGAIN":
+        case "ECONNREFUSED":
+        case "ECONNRESET":
+        case "ENOTFOUND":
+            return "registry_network_error";
+        case "ETIMEDOUT":
+            return "timed_out";
+        default:
+            if (failureKind === "package_manager_exit")
+                return "package_manager_exit";
+            return code ? "other_error" : "unknown";
+    }
+}
+async function captureSelfUpdateOutcome(action, fromVersion, targetVersion, installFlavor, failure, env, flushBeforeExit) {
     if (isCliTelemetryDisabled(env))
         return;
+    const code = failure?.diagnosticCode ?? failure?.code;
     const error = new Error(action === "update-failed" ? "Self-update failed" : "Self-update ineffective");
     // This event needs no stack: frames would expose the machine's install path.
     error.stack = undefined;
@@ -814,7 +856,12 @@ async function captureSelfUpdateOutcome(action, fromVersion, targetVersion, inst
             from_version: fromVersion,
             target_version: targetVersion,
             install_flavor: installFlavor,
-            error_class: code && SELF_UPDATE_ERROR_CLASSES.has(code) ? code : "other",
+            error_class: code && SELF_UPDATE_ERROR_CLASSES.has(code)
+                ? code
+                : failure?.failureKind === "package_manager_exit"
+                    ? "package_manager_exit"
+                    : "other",
+            error_reason: selfUpdateErrorReason(code, failure?.failureKind),
         },
     });
     if (flushBeforeExit) {

package/dist/utils/staged-npm-install.d.ts

@@ -0,0 +1,16 @@
+export type StagedInstallResult = {
+    ok: boolean;
+    detail?: string;
+    code?: string;
+};
+export type StagedInstallRunner = (command: string, args: string[], env?: NodeJS.ProcessEnv) => StagedInstallResult;
+/**
+ * Build hq-cli in a space-free temporary npm prefix, then replace the package
+ * and its executable links under the real prefix only after npm succeeds.
+ * Existing files are held beside their destinations until activation completes,
+ * so failed installs and failed activation restore the prior working tree.
+ */
+export declare function installNpmPackageStaged(prefix: string, packageSpec: string, runner: StagedInstallRunner, platform?: NodeJS.Platform, activate?: typeof activateStagedNpmPackage): StagedInstallResult;
+/** Atomically replace a package already built under a temporary npm prefix. */
+export declare function activateStagedNpmPackage(prefix: string, stagePrefix: string, platform?: NodeJS.Platform): StagedInstallResult;
+//# sourceMappingURL=staged-npm-install.d.ts.map

package/dist/utils/staged-npm-install.js

@@ -0,0 +1,264 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const PACKAGE_NAME = "@indigoai-us/hq-cli";
+const RANDOM_HEX_BYTES = 6;
+function packageRoot(prefix, platform) {
+    const modules = platform === "win32"
+        ? path.join(prefix, "node_modules")
+        : path.join(prefix, "lib", "node_modules");
+    return path.join(modules, "@indigoai-us", "hq-cli");
+}
+function binsFromPackageJson(packageDir) {
+    const parsed = JSON.parse(readFileSync(path.join(packageDir, "package.json"), "utf8"));
+    if (parsed.name !== PACKAGE_NAME)
+        throw new Error("staged npm package name did not match hq-cli");
+    const bins = typeof parsed.bin === "string"
+        ? { hq: parsed.bin }
+        : parsed.bin && typeof parsed.bin === "object" && !Array.isArray(parsed.bin)
+            ? parsed.bin
+            : {};
+    for (const [name, target] of Object.entries(bins)) {
+        if (!name || name === "." || name === ".." || /[\\/]/.test(name)) {
+            throw new Error(`invalid executable name in staged package: ${name}`);
+        }
+        if (typeof target !== "string" || path.isAbsolute(target)) {
+            throw new Error(`invalid executable target in staged package: ${name}`);
+        }
+        const resolved = path.resolve(packageDir, target);
+        if (resolved !== packageDir && !resolved.startsWith(`${packageDir}${path.sep}`)) {
+            throw new Error(`executable target escapes staged package: ${name}`);
+        }
+    }
+    return bins;
+}
+function oldBinNames(packageDir) {
+    try {
+        return Object.keys(binsFromPackageJson(packageDir));
+    }
+    catch {
+        return [];
+    }
+}
+function temporaryRoot() {
+    const candidates = [os.tmpdir(), process.platform === "win32" ? `${process.env.SystemDrive ?? "C:"}\\Temp` : "/tmp"];
+    const root = candidates.find((candidate) => !/\s/.test(candidate) && existsSync(candidate));
+    if (!root)
+        throw new Error("no writable temporary directory without spaces is available");
+    return mkdtempSync(path.join(root, "hq-cli-update-"));
+}
+function randomSuffix() {
+    return randomBytes(RANDOM_HEX_BYTES).toString("hex");
+}
+function bestEffortRemove(target) {
+    if (!target)
+        return;
+    try {
+        rmSync(target, { recursive: true, force: true });
+    }
+    catch (error) {
+        console.warn("[hq-cli-update] could not remove staged install artifact", {
+            path: target,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Build hq-cli in a space-free temporary npm prefix, then replace the package
+ * and its executable links under the real prefix only after npm succeeds.
+ * Existing files are held beside their destinations until activation completes,
+ * so failed installs and failed activation restore the prior working tree.
+ */
+export function installNpmPackageStaged(prefix, packageSpec, runner, platform = process.platform, activate = activateStagedNpmPackage) {
+    let stagePrefix;
+    try {
+        stagePrefix = temporaryRoot();
+        const npmResult = runner("npm", ["install", "-g", "--prefix", stagePrefix, packageSpec], { ...process.env, HQ_STAGED_INSTALL: "1" });
+        if (!npmResult.ok)
+            return npmResult;
+        const activation = activate(prefix, stagePrefix, platform);
+        if (activation.ok || activation.code !== "EACCES" || platform === "win32")
+            return activation;
+        // A spaced, root-owned npm prefix must still be buildable without passing
+        // that prefix to npm/node-gyp. Re-run only the filesystem activation as
+        // root; the package build remains in the space-free user-owned temp path.
+        const elevated = runner("sudo", [
+            "-n",
+            "npm",
+            "exec",
+            "--",
+            process.execPath,
+            fileURLToPath(import.meta.url),
+            "--activate",
+            prefix,
+            stagePrefix,
+            platform,
+        ]);
+        return elevated.ok
+            ? { ok: true }
+            : {
+                ...elevated,
+                detail: elevated.detail ?? "could not activate the staged npm install with sudo",
+            };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+            code: error?.code,
+        };
+    }
+    finally {
+        bestEffortRemove(stagePrefix);
+    }
+}
+/** Atomically replace a package already built under a temporary npm prefix. */
+export function activateStagedNpmPackage(prefix, stagePrefix, platform = process.platform) {
+    let candidatePackage;
+    let stagedBins;
+    let backupBins;
+    let backupPackage;
+    let packageBackedUp = false;
+    let packageActivated = false;
+    const backedUpBins = [];
+    const activatedBins = [];
+    try {
+        const stagedPackage = packageRoot(stagePrefix, platform);
+        const targetPackage = packageRoot(prefix, platform);
+        const stageBinDir = platform === "win32" ? stagePrefix : path.join(stagePrefix, "bin");
+        const targetBinDir = platform === "win32" ? prefix : path.join(prefix, "bin");
+        const bins = binsFromPackageJson(stagedPackage);
+        const suffix = randomSuffix();
+        const targetScopeDir = path.dirname(targetPackage);
+        mkdirSync(targetScopeDir, { recursive: true });
+        mkdirSync(targetBinDir, { recursive: true });
+        candidatePackage = path.join(targetScopeDir, `.hq-cli-next-${suffix}`);
+        cpSync(stagedPackage, candidatePackage, { recursive: true, verbatimSymlinks: true });
+        stagedBins = path.join(targetBinDir, `.hq-cli-bins-next-${suffix}`);
+        backupBins = path.join(targetBinDir, `.hq-cli-bins-backup-${suffix}`);
+        mkdirSync(stagedBins);
+        mkdirSync(backupBins);
+        backupPackage = path.join(targetScopeDir, `.hq-cli-backup-${suffix}`);
+        const names = new Set([...Object.keys(bins), ...oldBinNames(targetPackage)]);
+        for (const name of names) {
+            const entry = bins[name];
+            if (entry === undefined)
+                continue;
+            const executable = path.join(targetPackage, entry);
+            if (platform === "win32") {
+                for (const extension of ["", ".cmd", ".ps1"]) {
+                    const stagedFile = path.join(stageBinDir, `${name}${extension}`);
+                    if (!existsSync(stagedFile))
+                        continue;
+                    const stagedText = readFileSync(stagedFile, "utf8");
+                    const relocated = stagedText
+                        .split(stagePrefix).join(prefix)
+                        .split(stagePrefix.replace(/\\/g, "/")).join(prefix.replace(/\\/g, "/"));
+                    writeFileSync(path.join(stagedBins, `${name}${extension}`), relocated, {
+                        mode: extension === ".cmd" || extension === "" ? 0o755 : 0o644,
+                    });
+                }
+            }
+            else {
+                const stagedFile = path.join(stageBinDir, name);
+                if (!existsSync(stagedFile))
+                    throw new Error(`npm did not create the ${name} executable link`);
+                if (!existsSync(executable))
+                    throw new Error(`staged executable target is missing for ${name}`);
+                symlinkSync(path.relative(targetBinDir, executable), path.join(stagedBins, name));
+            }
+        }
+        if (existsSync(targetPackage)) {
+            renameSync(targetPackage, backupPackage);
+            packageBackedUp = true;
+        }
+        renameSync(candidatePackage, targetPackage);
+        packageActivated = true;
+        for (const name of names) {
+            for (const extension of platform === "win32" ? ["", ".cmd", ".ps1"] : [""]) {
+                const filename = `${name}${extension}`;
+                const target = path.join(targetBinDir, filename);
+                const staged = path.join(stagedBins, filename);
+                if (existsSync(target) || lstatExists(target)) {
+                    const backup = path.join(backupBins, filename);
+                    renameSync(target, backup);
+                    backedUpBins.push({ target, backup });
+                }
+                if (existsSync(staged) || lstatExists(staged)) {
+                    renameSync(staged, target);
+                    activatedBins.push(target);
+                }
+            }
+        }
+        bestEffortRemove(packageBackedUp ? backupPackage : undefined);
+        bestEffortRemove(backupBins);
+        return { ok: true };
+    }
+    catch (error) {
+        for (const target of activatedBins.reverse())
+            bestEffortRemove(target);
+        for (const item of backedUpBins.reverse()) {
+            if (existsSync(item.backup) || lstatExists(item.backup)) {
+                try {
+                    renameSync(item.backup, item.target);
+                }
+                catch (restoreError) {
+                    console.error("[hq-cli-update] could not restore previous executable link", {
+                        path: item.target,
+                        error: restoreError instanceof Error ? restoreError.message : String(restoreError),
+                    });
+                }
+            }
+        }
+        if (packageActivated)
+            bestEffortRemove(packageRoot(prefix, platform));
+        if (packageBackedUp && backupPackage && existsSync(backupPackage)) {
+            try {
+                renameSync(backupPackage, packageRoot(prefix, platform));
+            }
+            catch (restoreError) {
+                console.error("[hq-cli-update] could not restore previous package", {
+                    path: packageRoot(prefix, platform),
+                    error: restoreError instanceof Error ? restoreError.message : String(restoreError),
+                });
+            }
+        }
+        return {
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+            code: error?.code,
+        };
+    }
+    finally {
+        bestEffortRemove(candidatePackage);
+        bestEffortRemove(stagedBins);
+        bestEffortRemove(backupBins);
+        if (!packageBackedUp)
+            bestEffortRemove(backupPackage);
+    }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === "--activate") {
+    const [prefix, stagePrefix, platform] = process.argv.slice(3);
+    if (!prefix || !stagePrefix) {
+        console.error("usage: staged-npm-install.js --activate <prefix> <stage-prefix> [platform]");
+        process.exit(2);
+    }
+    else {
+        const result = activateStagedNpmPackage(prefix, stagePrefix, platform || process.platform);
+        if (!result.ok)
+            console.error(result.detail ?? "staged npm activation failed");
+        process.exit(result.ok ? 0 : 1);
+    }
+}
+function lstatExists(target) {
+    try {
+        lstatSync(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=staged-npm-install.js.map

package/dist/utils/update-command-supervisor.cjs

@@ -3,6 +3,18 @@
 const { spawn: nativeSpawn } = require("node:child_process");
 const fs = require("node:fs");
 
+const KNOWN_NPM_ERROR_CODES = new Set([
+  "E404",
+  "EACCES",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENOTFOUND",
+  "EPERM",
+  "ETARGET",
+  "ETIMEDOUT",
+]);
+
 function windowsTaskkillArgs(pid) {
   return ["/PID", String(pid), "/T", "/F"];
 }
@@ -24,6 +36,14 @@ function writeMarker(filename, contents, log) {
   }
 }
 
+function npmErrorCodeFromLine(line) {
+  const escape = String.fromCharCode(0x1b);
+  const plainLine = line.replace(new RegExp(`${escape}\\[[0-9;]*m`, "g"), "").trim();
+  const match = /^npm\s+(?:ERR!|error)\s+code\s+([A-Z0-9_]{1,32})$/i.exec(plainLine);
+  const code = match && match[1].toUpperCase();
+  return code && KNOWN_NPM_ERROR_CODES.has(code) ? code : undefined;
+}
+
 /**
  * Spawn and supervise one package-manager update. On POSIX the detached child
  * is its own process-group leader, so signals reach the leader and every
@@ -50,6 +70,31 @@ function runUpdateSupervisor(config, dependencies = {}) {
   let timedOut = false;
   let childClosed = false;
   let treeTerminationConfirmed = false;
+  let stderrLineBuffer = "";
+  let diagnosticRecorded = false;
+
+  function inspectNpmStderrLine(line) {
+    if (diagnosticRecorded || !config.diagnosticMarker) return;
+    const code = npmErrorCodeFromLine(line);
+    if (!code) return;
+    writeMarker(config.diagnosticMarker, code, log);
+    diagnosticRecorded = true;
+  }
+
+  function inspectNpmStderrChunk(chunk) {
+    if (diagnosticRecorded || !config.diagnosticMarker) return;
+    const lines = `${stderrLineBuffer}${chunk.toString("utf8")}`.split(/\r?\n/);
+    stderrLineBuffer = lines.pop() || "";
+    for (const line of lines) inspectNpmStderrLine(line);
+    if (stderrLineBuffer.length > 128) {
+      stderrLineBuffer = stderrLineBuffer.slice(-128);
+    }
+  }
+
+  function flushNpmStderrLine() {
+    if (stderrLineBuffer) inspectNpmStderrLine(stderrLineBuffer);
+    stderrLineBuffer = "";
+  }
 
   function clear(timer) {
     if (timer !== undefined) clearTimer(timer);
@@ -141,7 +186,7 @@ function runUpdateSupervisor(config, dependencies = {}) {
   try {
     child = spawn(config.cmd, config.args, {
       detached: true,
-      stdio: ["ignore", "inherit", "inherit"],
+      stdio: ["ignore", "inherit", config.diagnosticMarker ? "pipe" : "inherit"],
       shell: config.shell,
     });
   } catch (error) {
@@ -156,6 +201,7 @@ function runUpdateSupervisor(config, dependencies = {}) {
   });
   child.once("close", (code) => {
     childClosed = true;
+    flushNpmStderrLine();
     if (!timedOut) {
       finish(code === 0 ? 0 : (code ?? 1));
       return;
@@ -163,6 +209,12 @@ function runUpdateSupervisor(config, dependencies = {}) {
     if (treeTerminationConfirmed) timeoutAfterReap();
   });
 
+  if (config.diagnosticMarker && child.stderr) {
+    child.stderr.on("data", inspectNpmStderrChunk);
+    child.stderr.on("end", flushNpmStderrLine);
+    child.stderr.pipe(process.stderr);
+  }
+
   deadlineTimer = setTimer(() => {
     if (finished) return;
     timedOut = true;

package/dist/utils/version-gate.d.ts

@@ -256,6 +256,9 @@ export type UpdateResult = {
     ok: boolean;
     detail?: string;
     code?: string;
+    /** Sanitized installer error code for diagnostics; never drives retry or exit behavior. */
+    diagnosticCode?: string;
+    failureKind?: "package_manager_exit";
 };
 type UpdateRunner = (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
 export { buildSpawnPlan, quoteForWindowsShell };
@@ -323,6 +326,10 @@ export interface InstallOutput {
     stdio: ("ignore" | "inherit" | number)[];
     /** Captured stderr tail, or "" when output was inherited by a terminal. */
     stderrTail: () => string;
+    /** Allowlisted npm error code from captured stderr, when output was captured. */
+    diagnosticCode: () => string | undefined;
+    /** Supervisor marker used to inspect npm errors while forwarding terminal stderr. */
+    diagnosticMarker?: string;
     /** Private side-channel from the supervisor, kept out of installer output. */
     timeoutMarker: string;
     /** Private spawn-error side-channel that preserves the prior result contract. */
@@ -414,6 +421,7 @@ interface EnforceUpdateDeps {
      * returns nothing still exercises the success path.
      */
     checkConvergence?: (targetVersion: string) => boolean | void;
+    installNpmPackageStaged?: typeof import("./staged-npm-install.js").installNpmPackageStaged;
 }
 /**
  * Hard enforcement when the server says we're below `minVersion`. Print a