@indigoai-us/hq-cli 5.291.0 → 5.293.0

package/dist/utils/staged-install.js

@@ -0,0 +1,296 @@
+/**
+ * Staged npm self-update: install the new hq-cli beside the running package,
+ * check that it starts, then swap it in with two renames.
+ *
+ * The in-place update moves the live package aside for the whole
+ * `npm install -g`, so anything that starts `hq` during the install finds no
+ * CLI on disk ("hq: command not found", MODULE_NOT_FOUND; outposts primary and
+ * 2, 5.290.0 -> 5.291.0). Here the live package stays in place until the new
+ * one is complete and has answered `--version`.
+ *
+ * Only a plain npm global layout is staged: `<prefix>/lib/node_modules/<pkg>`
+ * as a real directory, with bin links in `<prefix>/bin`. pnpm, Bun, Windows
+ * and linked checkouts keep the in-place update.
+ */
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CLI_NAME } from "../cli-version.js";
+import { runUpdateCommand } from "./version-gate.js";
+/** Set for the staging install; hq-cli's own postinstall skips itself on it. */
+export const STAGED_INSTALL_ENV = "HQ_STAGED_INSTALL";
+const PROBE_TIMEOUT_MS = 60_000;
+const POSTINSTALL_TIMEOUT_MS = 120_000;
+export function canStageInstall(install, platform = process.platform) {
+    if (platform === "win32" || install.manager !== "npm")
+        return false;
+    if (!install.prefix || !install.packageRoot)
+        return false;
+    if (path.resolve(install.packageRoot) !== path.resolve(install.prefix, "lib", "node_modules", CLI_NAME)) {
+        return false;
+    }
+    try {
+        const entry = fs.lstatSync(install.packageRoot);
+        return entry.isDirectory() && !entry.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function stagedNpmInstall(install, version, deps = {}) {
+    if (!canStageInstall(install, deps.platform)) {
+        return { ok: false, detail: "this hq-cli install is not a plain npm global install" };
+    }
+    const prefix = install.prefix;
+    const live = install.packageRoot;
+    const env = deps.env ?? process.env;
+    const run = deps.run ?? runUpdateCommand;
+    const rename = deps.rename ?? fs.renameSync;
+    const remove = deps.remove ?? ((target) => fs.rmSync(target, { recursive: true, force: true }));
+    const probe = deps.probeVersion ?? ((root) => probeHqVersion(root, env));
+    const postinstall = deps.runPostinstall ?? ((root) => runPackagePostinstall(root, env));
+    // Beside the live package, so both renames stay on one filesystem.
+    const tag = `${process.pid}-${randomBytes(8).toString("hex")}`;
+    const staging = path.join(path.dirname(live), `.hq-cli-staging-${tag}`);
+    const staged = path.join(staging, "lib", "node_modules", CLI_NAME);
+    const backup = path.join(path.dirname(live), `.hq-cli-backup-${tag}`);
+    let keepBackup = false;
+    try {
+        const result = run("npm", ["install", "-g", "--prefix", staging, `${CLI_NAME}@${version}`], { ...env, [STAGED_INSTALL_ENV]: "1" });
+        if (!result.ok)
+            return result;
+        const reported = probe(staged);
+        if (reported !== version) {
+            return {
+                ok: false,
+                detail: `the staged hq-cli reported ${reported ?? "no version"} instead of ${version}`,
+            };
+        }
+        try {
+            rename(live, backup);
+        }
+        catch (error) {
+            return { ok: false, detail: `could not move the running hq-cli aside: ${message(error)}` };
+        }
+        try {
+            rename(staged, live);
+        }
+        catch (error) {
+            try {
+                rename(backup, live);
+            }
+            catch (restoreError) {
+                keepBackup = true;
+                return {
+                    ok: false,
+                    detail: `could not move hq-cli ${version} into place (${message(error)}) or restore the previous install from ${backup} (${message(restoreError)})`,
+                };
+            }
+            return { ok: false, detail: `could not move hq-cli ${version} into place: ${message(error)}` };
+        }
+        if (!linkBins(prefix, live, readBins(backup), tag)) {
+            // `hq` does not reach the new package, so put the old one back.
+            try {
+                rename(live, staged);
+                rename(backup, live);
+            }
+            catch (error) {
+                keepBackup = true;
+                return {
+                    ok: false,
+                    detail: `could not link hq to hq-cli ${version} or restore the previous install from ${backup} (${message(error)})`,
+                };
+            }
+            return { ok: false, detail: `could not point ${path.join(prefix, "bin", "hq")} at hq-cli ${version}` };
+        }
+        try {
+            postinstall(live);
+        }
+        catch {
+            // npm runs this script as `... || true`; it never fails an install.
+        }
+        return { ok: true };
+    }
+    finally {
+        // Leftovers are hidden siblings npm ignores; they never change the result.
+        try {
+            remove(staging);
+        }
+        catch {
+            // best effort
+        }
+        if (!keepBackup) {
+            try {
+                remove(backup);
+            }
+            catch {
+                // best effort
+            }
+        }
+    }
+}
+/**
+ * Points `<prefix>/bin/<name>` at the live package for each bin it declares
+ * and removes hq-cli's links for bins the new version dropped. Existing npm
+ * links already point at the live path. A link into another package, or a
+ * regular file (someone's wrapper), is left alone.
+ *
+ * `hq` is settled first. If it does not resolve to a file, its link is put
+ * back as it was, no other bin is touched, and this returns false so the
+ * caller can restore the old package.
+ */
+function linkBins(prefix, live, previousBins, tag) {
+    const binDir = path.join(prefix, "bin");
+    const ownedByHqCli = (link) => {
+        try {
+            const target = path.resolve(binDir, fs.readlinkSync(link));
+            return target.startsWith(`${live}${path.sep}`);
+        }
+        catch {
+            return false;
+        }
+    };
+    const pointAt = (link, want) => {
+        const temporary = `${link}.hq-cli-${tag}`;
+        try {
+            fs.mkdirSync(binDir, { recursive: true });
+            fs.symlinkSync(want, temporary);
+            fs.renameSync(temporary, link);
+        }
+        catch {
+            try {
+                fs.rmSync(temporary, { force: true });
+            }
+            catch {
+                // A stray temporary link is harmless.
+            }
+        }
+    };
+    const linkBin = (name, target) => {
+        const link = path.join(binDir, name);
+        const want = path.relative(binDir, path.join(live, target));
+        try {
+            const existing = fs.lstatSync(link, { throwIfNoEntry: false });
+            if (existing && !existing.isSymbolicLink())
+                return;
+            if (existing && fs.readlinkSync(link) === want)
+                return;
+            if (existing && !ownedByHqCli(link))
+                return;
+        }
+        catch {
+            return;
+        }
+        pointAt(link, want);
+    };
+    const bins = readBins(live);
+    const hqLink = path.join(binDir, "hq");
+    const hqBefore = symlinkTarget(hqLink);
+    if (bins.hq)
+        linkBin("hq", bins.hq);
+    if (!resolvesToFile(hqLink)) {
+        const hqAfter = symlinkTarget(hqLink);
+        if (hqAfter !== hqBefore) {
+            if (hqBefore === null) {
+                try {
+                    fs.unlinkSync(hqLink);
+                }
+                catch {
+                    // Nothing to undo.
+                }
+            }
+            else {
+                pointAt(hqLink, hqBefore);
+            }
+        }
+        return false;
+    }
+    for (const [name, target] of Object.entries(bins)) {
+        if (name !== "hq")
+            linkBin(name, target);
+    }
+    for (const name of Object.keys(previousBins)) {
+        if (name in bins)
+            continue;
+        const link = path.join(binDir, name);
+        try {
+            if (fs.lstatSync(link).isSymbolicLink() && ownedByHqCli(link))
+                fs.unlinkSync(link);
+        }
+        catch {
+            // Already gone, or not ours to remove.
+        }
+    }
+    return true;
+}
+function symlinkTarget(link) {
+    try {
+        return fs.lstatSync(link).isSymbolicLink() ? fs.readlinkSync(link) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolvesToFile(link) {
+    try {
+        return fs.statSync(link).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function readBins(packageRoot) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        if (typeof pkg.bin === "string")
+            return { hq: pkg.bin };
+        if (pkg.bin && typeof pkg.bin === "object") {
+            return Object.fromEntries(Object.entries(pkg.bin).filter(([, target]) => typeof target === "string"));
+        }
+    }
+    catch {
+        // An unreadable manifest declares no bins.
+    }
+    return {};
+}
+function probeHqVersion(packageRoot, env) {
+    const bin = readBins(packageRoot).hq ?? "dist/index.js";
+    const result = spawnSync(process.execPath, [path.join(packageRoot, bin), "--version"], {
+        encoding: "utf8",
+        env: { ...env, HQ_NO_UPDATE_CHECK: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: PROBE_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    if (result.status !== 0)
+        return null;
+    const lines = (result.stdout ?? "").trim().split(/\r?\n/);
+    return lines[lines.length - 1]?.trim() || null;
+}
+function runPackagePostinstall(packageRoot, env) {
+    let script;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        script = pkg.scripts?.postinstall;
+    }
+    catch {
+        return;
+    }
+    if (typeof script !== "string" || script.trim() === "")
+        return;
+    const childEnv = { ...env };
+    delete childEnv[STAGED_INSTALL_ENV];
+    spawnSync(script, {
+        cwd: packageRoot,
+        env: childEnv,
+        shell: true,
+        stdio: "ignore",
+        timeout: POSTINSTALL_TIMEOUT_MS,
+        windowsHide: true,
+    });
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=staged-install.js.map

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

@@ -284,6 +284,21 @@ export { buildSpawnPlan, quoteForWindowsShell };
  */
 export declare function inOwnProcessGroup<T extends object>(options: T): T;
 declare function updateTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** The supervisor script the next install runs under. */
+export declare function updateSupervisorPath(): string;
+export interface DetachedUpdateSupervisor {
+    path: string;
+    dispose(): void;
+}
+/**
+ * Copies the supervisor to a temp dir and runs installs through the copy until
+ * disposed. The in-place self-update moves the whole hq-cli package aside
+ * before it starts the installer, and the supervisor ships inside that package
+ * (5.290.0-5.292.0 failed every npm global self-update with MODULE_NOT_FOUND).
+ * The script needs only Node builtins, so the copy runs on its own. Returns
+ * null when the copy cannot be made; the caller then keeps the bundled path.
+ */
+export declare function detachUpdateSupervisor(): DetachedUpdateSupervisor | null;
 /**
  * Where an install's output goes — the other half of surviving a killed parent.
  *

package/dist/utils/version-gate.js

@@ -30,7 +30,7 @@
 import { spawnSync } from "node:child_process";
 import { installPathCompatibilityEnabled } from "../lib/install-path-compatibility-flag.js";
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
-import { accessSync, closeSync, constants as fsConstants, existsSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
+import { accessSync, closeSync, constants as fsConstants, copyFileSync, existsSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -674,6 +674,50 @@ function updateTimeoutMs(env = process.env) {
  * compiled module for production and is directly runnable from source tests.
  */
 const UPDATE_COMMAND_SUPERVISOR = fileURLToPath(new URL("./update-command-supervisor.cjs", import.meta.url));
+/** Set while a self-update runs the installer through a copy of the supervisor. */
+let detachedSupervisor = null;
+/** The supervisor script the next install runs under. */
+export function updateSupervisorPath() {
+    return detachedSupervisor ?? UPDATE_COMMAND_SUPERVISOR;
+}
+/**
+ * Copies the supervisor to a temp dir and runs installs through the copy until
+ * disposed. The in-place self-update moves the whole hq-cli package aside
+ * before it starts the installer, and the supervisor ships inside that package
+ * (5.290.0-5.292.0 failed every npm global self-update with MODULE_NOT_FOUND).
+ * The script needs only Node builtins, so the copy runs on its own. Returns
+ * null when the copy cannot be made; the caller then keeps the bundled path.
+ */
+export function detachUpdateSupervisor() {
+    if (detachedSupervisor)
+        return null;
+    let dir;
+    try {
+        dir = mkdtempSync(path.join(os.tmpdir(), "hq-cli-update-supervisor-"));
+        const copy = path.join(dir, "update-command-supervisor.cjs");
+        copyFileSync(UPDATE_COMMAND_SUPERVISOR, copy);
+        detachedSupervisor = copy;
+        const tempDir = dir;
+        return {
+            path: copy,
+            dispose: () => {
+                if (detachedSupervisor === copy)
+                    detachedSupervisor = null;
+                try {
+                    rmSync(tempDir, { recursive: true, force: true });
+                }
+                catch {
+                    // Best-effort cleanup of a temp dir.
+                }
+            },
+        };
+    }
+    catch {
+        if (dir)
+            rmSync(dir, { recursive: true, force: true });
+        return null;
+    }
+}
 function readSupervisorSpawnError(errorMarker) {
     try {
         const value = JSON.parse(readFileSync(errorMarker, "utf-8"));
@@ -754,7 +798,7 @@ export function runSupervisedUpdateCommand(cmd, args, output, env) {
         // waits briefly, sends KILL to survivors, and waits for its direct child so
         // the completed result leaves no zombie behind.
         const result = spawnSync(process.execPath, [
-            UPDATE_COMMAND_SUPERVISOR,
+            updateSupervisorPath(),
             JSON.stringify({
                 cmd: plan.cmd,
                 args: plan.args,

package/package.json

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

package/scripts/mesh-daemon-if-stale.mjs

@@ -7,6 +7,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+// A staged self-update installs into a directory it is about to rename; it
+// runs this script again from the live path after the swap.
+if (process.env.HQ_STAGED_INSTALL === "1") process.exit(0);
+
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const cli = path.join(root, "dist", "index.js");
 if (!fs.existsSync(cli)) process.exit(0);