@indigoai-us/hq-cli 5.297.0 → 5.299.0

package/dist/utils/self-update.js

@@ -131,6 +131,236 @@ function isPathInside(candidate, parent) {
     const relative = path.relative(path.resolve(parent), path.resolve(candidate));
     return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 }
+function readNpmBinMap(packageRoot) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        if (manifest.bin === undefined)
+            return {};
+        const entries = typeof manifest.bin === "string"
+            ? [["hq", manifest.bin]]
+            : manifest.bin && typeof manifest.bin === "object" && !Array.isArray(manifest.bin)
+                ? Object.entries(manifest.bin)
+                : null;
+        if (!entries)
+            return null;
+        const bins = {};
+        for (const [name, target] of entries) {
+            if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\") ||
+                typeof target !== "string" || target.length === 0 || path.isAbsolute(target) ||
+                !isPathInside(path.resolve(packageRoot, target), packageRoot)) {
+                return null;
+            }
+            bins[name] = target;
+        }
+        return bins;
+    }
+    catch {
+        return null;
+    }
+}
+function symlinkTargetIsInsidePackage(linkPath, target, packageRoot) {
+    return isPathInside(path.resolve(path.dirname(linkPath), target), packageRoot);
+}
+function snapshotNpmBinLinks(prefix, packageRoot) {
+    if (process.platform === "win32")
+        return [];
+    const binMap = readNpmBinMap(packageRoot);
+    if (!binMap)
+        return [];
+    const binDirectory = path.join(prefix, "bin");
+    const links = [];
+    for (const name of Object.keys(binMap)) {
+        const linkPath = path.join(binDirectory, name);
+        try {
+            if (!fs.lstatSync(linkPath).isSymbolicLink())
+                continue;
+            const target = fs.readlinkSync(linkPath);
+            const resolved = fs.realpathSync(linkPath);
+            if (!isPathInside(resolved, packageRoot))
+                continue;
+            links.push({ path: linkPath, target });
+        }
+        catch {
+            // A missing or dangling entry was not a working npm bin link to snapshot.
+        }
+    }
+    return links;
+}
+function restoreNpmBinLinks(snapshot) {
+    if (!snapshot.npmBinDirectory || !snapshot.npmBinPackageRoot || !snapshot.npmBinLinks?.length)
+        return true;
+    if (process.platform === "win32")
+        return true;
+    let restored = true;
+    for (const bin of snapshot.npmBinLinks) {
+        if (path.dirname(bin.path) !== snapshot.npmBinDirectory) {
+            reportBinLinkConflict(bin.path, "the saved path is outside the npm bin directory");
+            restored = false;
+            continue;
+        }
+        let existing;
+        let existingTarget;
+        try {
+            existing = fs.lstatSync(bin.path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                reportBinLinkConflict(bin.path, errorMessage(error));
+                restored = false;
+                continue;
+            }
+        }
+        if (existing) {
+            if (!existing.isSymbolicLink()) {
+                reportBinLinkConflict(bin.path, "a regular file owns this command name");
+                restored = false;
+                continue;
+            }
+            const currentTarget = fs.readlinkSync(bin.path);
+            existingTarget = currentTarget;
+            if (!symlinkTargetIsInsidePackage(bin.path, currentTarget, snapshot.npmBinPackageRoot)) {
+                reportBinLinkConflict(bin.path, "the existing symlink points outside hq-cli");
+                restored = false;
+                continue;
+            }
+            try {
+                if (currentTarget === bin.target &&
+                    isPathInside(fs.realpathSync(bin.path), snapshot.npmBinPackageRoot))
+                    continue;
+            }
+            catch {
+                // A dangling link into the package is safe to replace with the snapshot.
+            }
+        }
+        if (!symlinkTargetIsInsidePackage(bin.path, bin.target, snapshot.npmBinPackageRoot)) {
+            reportBinLinkConflict(bin.path, "the saved npm link target is outside the restored hq-cli package");
+            restored = false;
+            continue;
+        }
+        const temporary = `${bin.path}.hq-cli-restore-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            fs.mkdirSync(snapshot.npmBinDirectory, { recursive: true });
+            if (!existing) {
+                // Creating the link directly is deliberately no-clobber: if another
+                // tool claimed the command name after lstat, EEXIST preserves it.
+                fs.symlinkSync(bin.target, bin.path);
+            }
+            else {
+                fs.symlinkSync(bin.target, temporary);
+                const current = fs.lstatSync(bin.path);
+                if (!current.isSymbolicLink() || fs.readlinkSync(bin.path) !== existingTarget) {
+                    throw new Error("the bin entry changed while it was being restored");
+                }
+                fs.renameSync(temporary, bin.path);
+            }
+            try {
+                if (!isPathInside(fs.realpathSync(bin.path), snapshot.npmBinPackageRoot)) {
+                    throw new Error("restored link does not resolve into the restored hq-cli package");
+                }
+            }
+            catch (error) {
+                fs.rmSync(bin.path, { force: true });
+                throw error;
+            }
+        }
+        catch (error) {
+            fs.rmSync(temporary, { force: true });
+            reportBinLinkConflict(bin.path, errorMessage(error));
+            restored = false;
+        }
+    }
+    return restored;
+}
+function reportBinLinkConflict(linkPath, reason) {
+    console.error(chalk.yellow(`⚠ Could not restore hq-cli bin link at ${linkPath}; left it untouched (${reason}).`));
+}
+function reportForeignNpmBin(linkPath, reason) {
+    console.error(chalk.yellow(`⚠ Leaving hq-cli bin entry at ${linkPath} untouched; another tool owns it (${reason}).`));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function verifyOrRepairNpmBins(prefix, packageRoot) {
+    if (process.platform === "win32")
+        return { ok: true };
+    let livePackageRoot;
+    try {
+        livePackageRoot = fs.realpathSync(packageRoot);
+    }
+    catch (error) {
+        return { ok: false, detail: `the installed hq-cli package is missing: ${errorMessage(error)}` };
+    }
+    const bins = readNpmBinMap(livePackageRoot);
+    if (!bins || typeof bins.hq !== "string" || bins.hq.length === 0) {
+        return { ok: false, detail: "the installed hq-cli package does not declare a valid hq bin" };
+    }
+    const binDirectory = path.join(prefix, "bin");
+    for (const [name, target] of Object.entries(bins)) {
+        const linkPath = path.join(binDirectory, name);
+        const expected = path.resolve(livePackageRoot, target);
+        let existing;
+        let existingTarget;
+        try {
+            existing = fs.lstatSync(linkPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                return { ok: false, detail: `could not inspect ${linkPath}: ${errorMessage(error)}` };
+            }
+        }
+        if (existing) {
+            if (!existing.isSymbolicLink()) {
+                if (name === "hq") {
+                    return { ok: false, detail: `cannot repair ${linkPath}: a regular file owns this command name` };
+                }
+                reportForeignNpmBin(linkPath, "a regular file owns this command name");
+                continue;
+            }
+            const currentTarget = fs.readlinkSync(linkPath);
+            existingTarget = currentTarget;
+            if (!symlinkTargetIsInsidePackage(linkPath, currentTarget, livePackageRoot)) {
+                if (name === "hq") {
+                    return { ok: false, detail: `cannot repair ${linkPath}: the existing symlink points outside hq-cli` };
+                }
+                reportForeignNpmBin(linkPath, "the existing symlink points outside hq-cli");
+                continue;
+            }
+            try {
+                if (fs.realpathSync(linkPath) === expected && fs.statSync(linkPath).isFile())
+                    continue;
+            }
+            catch {
+                // Missing and dangling hq-cli links are repaired below.
+            }
+        }
+        const temporary = `${linkPath}.hq-cli-repair-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            fs.mkdirSync(binDirectory, { recursive: true });
+            const targetPath = path.relative(binDirectory, expected);
+            if (!existing) {
+                // A direct symlink create does not replace a file that appeared after
+                // lstat; EEXIST is surfaced as an update failure instead.
+                fs.symlinkSync(targetPath, linkPath);
+            }
+            else {
+                fs.symlinkSync(targetPath, temporary);
+                const current = fs.lstatSync(linkPath);
+                if (!current.isSymbolicLink() || fs.readlinkSync(linkPath) !== existingTarget) {
+                    throw new Error("the bin entry changed while it was being repaired");
+                }
+                fs.renameSync(temporary, linkPath);
+            }
+            if (fs.realpathSync(linkPath) !== expected || !fs.statSync(linkPath).isFile()) {
+                throw new Error("repaired link does not resolve to its declared package bin");
+            }
+        }
+        catch (error) {
+            fs.rmSync(temporary, { force: true });
+            return { ok: false, detail: `could not repair ${linkPath}: ${errorMessage(error)}` };
+        }
+    }
+    return { ok: true };
+}
 function isInsideNodeModules(candidate) {
     const segments = path.resolve(candidate).replace(/\\/g, "/").split("/").filter(Boolean);
     const index = process.platform === "win32"
@@ -159,8 +389,14 @@ function snapshotPathsAreSafe(snapshot) {
         snapshot.movedPath,
         snapshot.resolvedTarget,
         snapshot.publicLinkPath,
+        snapshot.npmBinPackageRoot,
     ].filter((value) => value !== undefined);
-    return paths.every(isInsideNodeModules);
+    if (!paths.every(isInsideNodeModules))
+        return false;
+    if (snapshot.npmBinLinks?.some((bin) => !snapshot.npmBinDirectory || path.dirname(bin.path) !== snapshot.npmBinDirectory ||
+        !isPathInside(bin.path, snapshot.npmBinDirectory)))
+        return false;
+    return true;
 }
 function snapshotInstall(install, renamePath = fs.renameSync) {
     const packageRoot = install.packageRoot;
@@ -200,6 +436,9 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
         const pnpmPublicLinkPath = publicLink?.path ?? (entry.isSymbolicLink() ? packageRoot : undefined);
         if (backupKind === "pnpm-public-link" && !pnpmPublicLinkPath)
             return null;
+        const npmBinLinks = backupKind === "package" && install.manager === "npm" && install.prefix
+            ? snapshotNpmBinLinks(install.prefix, sourcePath)
+            : undefined;
         movedPath = backupKind === "pnpm-public-link" ? pnpmPublicLinkPath : sourcePath;
         backupPath = path.join(path.dirname(movedPath), `.hq-cli-backup-${process.pid}-${randomBytes(8).toString("hex")}`);
         renamePath(movedPath, backupPath);
@@ -215,6 +454,9 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
             publicLinkTarget: backupKind === "pnpm-public-link"
                 ? publicLink?.target ?? symlinkTarget
                 : publicLink?.target,
+            npmBinDirectory: npmBinLinks ? path.join(install.prefix, "bin") : undefined,
+            npmBinPackageRoot: npmBinLinks ? sourcePath : undefined,
+            npmBinLinks,
         };
     }
     catch {
@@ -260,7 +502,7 @@ function restoreInstall(snapshot, renamePath = fs.renameSync) {
             fs.mkdirSync(path.dirname(snapshot.publicLinkPath), { recursive: true });
             fs.symlinkSync(snapshot.publicLinkTarget, snapshot.publicLinkPath, process.platform === "win32" ? "junction" : "dir");
         }
-        return true;
+        return restoreNpmBinLinks(snapshot);
     }
     catch {
         reportFailedRestore(snapshot);
@@ -458,6 +700,11 @@ async function updateAndReexec(argv, flavor, known, deps) {
         else {
             result = runner(plan.cmd, plan.args, updateEnv);
         }
+        if (result.ok && !staged && install.manager === "npm" && install.prefix && install.packageRoot) {
+            const bins = verifyOrRepairNpmBins(install.prefix, install.packageRoot);
+            if (!bins.ok)
+                result = bins;
+        }
         if (!result.ok && installSnapshot) {
             restoredAfterFailure = restoreInstall(installSnapshot, renamePath);
             if (restoredAfterFailure)

package/dist/utils/staged-install.js

@@ -89,7 +89,7 @@ export function stagedNpmInstall(install, version, deps = {}) {
             }
             return { ok: false, detail: `could not move hq-cli ${version} into place: ${message(error)}` };
         }
-        if (!linkBins(prefix, live, readBins(backup), tag)) {
+        if (!linkBins(prefix, live, readBins(backup), tag, rename)) {
             // `hq` does not reach the new package, so put the old one back.
             try {
                 rename(live, staged);
@@ -99,10 +99,10 @@ export function stagedNpmInstall(install, version, deps = {}) {
                 keepBackup = true;
                 return {
                     ok: false,
-                    detail: `could not link hq to hq-cli ${version} or restore the previous install from ${backup} (${message(error)})`,
+                    detail: `could not verify or relink every declared hq-cli bin for ${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}` };
+            return { ok: false, detail: `could not verify or relink every declared hq-cli bin for ${version}` };
         }
         try {
             postinstall(live);
@@ -136,11 +136,11 @@ export function stagedNpmInstall(install, version, deps = {}) {
  * 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.
+ * `hq` must resolve into the live package or the caller restores the old
+ * package. Other declared bins owned by another tool are left alone and warned
+ * about; bins we own or need to create must resolve into the live package.
  */
-function linkBins(prefix, live, previousBins, tag) {
+function linkBins(prefix, live, previousBins, tag, rename) {
     const binDir = path.join(prefix, "bin");
     const ownedByHqCli = (link) => {
         try {
@@ -156,7 +156,7 @@ function linkBins(prefix, live, previousBins, tag) {
         try {
             fs.mkdirSync(binDir, { recursive: true });
             fs.symlinkSync(want, temporary);
-            fs.renameSync(temporary, link);
+            rename(temporary, link);
         }
         catch {
             try {
@@ -185,30 +185,70 @@ function linkBins(prefix, live, previousBins, tag) {
         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) {
+    if (typeof bins.hq !== "string" || bins.hq.length === 0)
+        return false;
+    const foreignBins = new Set();
+    for (const [name, target] of Object.entries(bins)) {
+        if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\"))
+            return false;
+        const targetPath = path.resolve(live, target);
+        if (!targetPath.startsWith(`${path.resolve(live)}${path.sep}`) || !resolvesToFile(targetPath))
+            return false;
+        const link = path.join(binDir, name);
+        try {
+            const existing = fs.lstatSync(link, { throwIfNoEntry: false });
+            if (existing && (!existing.isSymbolicLink() || !ownedByHqCli(link))) {
+                if (name === "hq")
+                    return false;
+                foreignBins.add(name);
+                console.error(`⚠ Leaving hq-cli bin entry at ${link} untouched; another tool owns it.`);
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    const changedBins = [];
+    const linkAndRecord = (name, target) => {
+        const link = path.join(binDir, name);
+        const before = symlinkTarget(link);
+        linkBin(name, target);
+        const after = symlinkTarget(link);
+        if (after !== before)
+            changedBins.push({ link, before });
+    };
+    const rollbackBinChanges = () => {
+        for (const change of changedBins.reverse()) {
+            const current = symlinkTarget(change.link);
+            if (current === null || !ownedByHqCli(change.link))
+                continue;
+            if (change.before === null) {
                 try {
-                    fs.unlinkSync(hqLink);
+                    fs.unlinkSync(change.link);
                 }
                 catch {
-                    // Nothing to undo.
+                    // The staged update still fails; preserve the best-effort rollback result.
                 }
             }
             else {
-                pointAt(hqLink, hqBefore);
+                pointAt(change.link, change.before);
             }
         }
+    };
+    const hqLink = path.join(binDir, "hq");
+    linkAndRecord("hq", bins.hq);
+    if (!resolvesToPackageBin(hqLink, live, bins.hq)) {
+        rollbackBinChanges();
         return false;
     }
     for (const [name, target] of Object.entries(bins)) {
-        if (name !== "hq")
-            linkBin(name, target);
+        if (name === "hq" || foreignBins.has(name))
+            continue;
+        linkAndRecord(name, target);
+        if (!resolvesToPackageBin(path.join(binDir, name), live, target)) {
+            rollbackBinChanges();
+            return false;
+        }
     }
     for (const name of Object.keys(previousBins)) {
         if (name in bins)
@@ -240,6 +280,16 @@ function resolvesToFile(link) {
         return false;
     }
 }
+function resolvesToPackageBin(link, packageRoot, target) {
+    try {
+        return fs.lstatSync(link).isSymbolicLink() &&
+            fs.realpathSync(link) === fs.realpathSync(path.resolve(packageRoot, target)) &&
+            fs.statSync(link).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 function readBins(packageRoot) {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));

package/package.json

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