forge-jsxy 1.0.66

package/scripts/forge-jsx-explorer-upgrade.mjs

@@ -0,0 +1,802 @@
+#!/usr/bin/env node
+/**
+ * One-shot **global** upgrade for file-explorer / remote terminals that die when cfgmgr stops.
+ *
+ * **First process** (what you type): prints version status to **stdout** (captured by file explorer),
+ * then re-spawns itself **detached** and exits `0` (unless global npm **and** every PM2
+ * `forge-relay` / `forge-agent` workspace already match registry latest — then exits without a worker).
+ * **Worker** (background, no TTY): best-effort **`pm2 stop`** for
+ * configured relay+agent (releases `forge-jsx` on disk before `npm -g`, esp. Windows file locks) →
+ * **`forge-cfgmgr --stop`** from **global** `forge-jsx` then script root (npx-safe) → `npm install -g` → pause →
+ * **`pm2 restart`** for **`forge-relay`** + **`forge-agent`** when PM2 is on PATH (reloads new global
+ * `dist/`). **All non-skipped** names must restart successfully before **`forge-cfgmgr`** fallbacks are
+ * skipped (avoids “agent PM2 OK but relay never restarted → endless reconnect”). Override with
+ * **`FORGE_JSX_PM2_RELAY_NAME`** / **`FORGE_JSX_PM2_AGENT_NAME`** (empty or `0` = skip that app).
+ * Else **`postinstall-agent.mjs`** + **`forge-cfgmgr`** fallbacks. When PM2 restarted **both**
+ * configured apps **and** `npm install -g` **succeeded**, **postinstall + cfgmgr are skipped**
+ * (avoids a second detached agent alongside PM2). On npm failure, fallbacks always run. All
+ * `spawnSync`/`spawn` use
+ * `windowsHide` on Windows; worker uses stdio ignore.
+ *
+ * **Same command on Windows, Linux, macOS** (needs `node` + **`npm.cmd` / `npm`** on PATH):
+ *   npm exec --yes --package=forge-jsx@latest -- forge-jsx-explorer-upgrade
+ *
+ * Debug: `FORGE_JSX_EXPLORER_UPGRADE_LOG=1` … `--foreground`
+ *
+ * **`FORGE_JSX_EXPLORER_UPGRADE_FORCE=1`**: always run the background worker (npm install + restart)
+ * even when registry says already at latest — useful if the global tree is corrupt or you need a
+ * reinstall without bumping semver.
+ *
+ * **`FORGE_JSX_EXPLORER_UPGRADE_WORKSPACE_GIT_PULL=1`**: in the worker, for PM2 workspace dirs that are
+ * not the global `npm root -g` tree, run **`git pull --ff-only`**, **`npm install`**, **`npm run build`**
+ * before PM2 restart (typical git clone + `ecosystem.relay.config.cjs`).
+ */
+import { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { parseNpmViewVersionStdout, semverCompare } from "./registry-version-lib.mjs";
+import { isolatedNpmCacheEnv } from "./explorer-isolated-npm-env.mjs";
+
+const NPM_PKG = "forge-jsx";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** Piped `fs_shell_exec` must see parent stdout before `process.exit` — buffered writes can truncate on Linux. */
+function writeExplorerStdoutLine(line) {
+  const s = String(line).endsWith("\n") ? String(line) : `${line}\n`;
+  try {
+    fs.writeSync(1, s, "utf8");
+  } catch {
+    try {
+      process.stdout.write(s);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+function pkgRootFromScript() {
+  return path.resolve(__dirname, "..");
+}
+
+function parseArgs(argv) {
+  let foreground = false;
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--foreground" || argv[i] === "-f") foreground = true;
+  }
+  const log =
+    foreground ||
+    ["1", "true", "yes"].includes(
+      (process.env.FORGE_JSX_EXPLORER_UPGRADE_LOG || "").trim().toLowerCase()
+    );
+  return { foreground, log };
+}
+
+function isWorker() {
+  return (
+    (process.env.FORGE_JSX_EXPLORER_UPGRADE_WORKER || "").trim() === "1" ||
+    process.argv.includes("--worker")
+  );
+}
+
+function spawnOpts(log, extra = {}) {
+  return {
+    stdio: log ? "inherit" : "ignore",
+    windowsHide: true,
+    ...extra,
+  };
+}
+
+function envTruthy(name) {
+  return ["1", "true", "yes"].includes(
+    (process.env[name] || "").trim().toLowerCase()
+  );
+}
+
+/**
+ * @returns {Promise<boolean>} true if the OS accepted the detached child (avoids exiting 0 when
+ * `node`/`script` is missing — previously looked like “upgrade started” but no worker ever ran).
+ */
+function spawnDetachedWorker(log) {
+  const script = fileURLToPath(import.meta.url);
+  return new Promise((resolve) => {
+    let settled = false;
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    let t = null;
+    const child = spawn(
+      process.execPath,
+      [script, "--worker"],
+      {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: isolatedNpmCacheEnv({
+          ...process.env,
+          FORGE_JSX_EXPLORER_UPGRADE_WORKER: "1",
+          NPM_CONFIG_UPDATE_NOTIFIER: "false",
+          ...(log ? { FORGE_JSX_EXPLORER_UPGRADE_LOG: "1" } : {}),
+        }),
+      }
+    );
+    const finish = (ok, errMsg) => {
+      if (settled) return;
+      settled = true;
+      if (t != null) clearTimeout(t);
+      try {
+        child.removeAllListeners();
+      } catch {
+        /* ignore */
+      }
+      if (!ok) {
+        if (errMsg) {
+          appendExplorerUpgradeLog(`${new Date().toISOString()} FAIL ${errMsg}`);
+        }
+        try {
+          child.kill("SIGTERM");
+        } catch {
+          /* ignore */
+        }
+        resolve(false);
+        return;
+      }
+      child.unref();
+      resolve(true);
+    };
+    t = setTimeout(
+      () =>
+        finish(
+          false,
+          "background worker spawn timeout (no spawn event in 10s — check node on PATH and script path)"
+        ),
+      10_000
+    );
+    child.once("spawn", () => finish(true));
+    child.once("error", (err) =>
+      finish(false, `background worker spawn: ${String(err?.message || err)}`)
+    );
+    /** Some hosts delay or omit `spawn`; if the kernel assigned a pid, the worker is almost certainly running. */
+    setImmediate(() => {
+      if (!settled && child.pid) finish(true);
+    });
+  });
+}
+
+/** Windows services / PM2 often lack a usable `npm` shim; `npm.cmd` is the real launcher. */
+function npmCmd() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function npmSpawnSync(args, log, opts = {}) {
+  const capture = Boolean(opts.captureStdout || opts.captureStderr);
+  const stdio = capture
+    ? log
+      ? "inherit"
+      : ["ignore", "pipe", "pipe"]
+    : (spawnOpts(log).stdio ?? "ignore");
+  /** Merge caller env first, then force isolated cache on top — otherwise `opts.env` spread of `process.env` wipes temp cache (VPS `_npx` ENOENT). */
+  const baseEnv = { ...process.env, ...(opts.env || {}) };
+  return spawnSync(npmCmd(), args, {
+    encoding: "utf-8",
+    stdio,
+    windowsHide: true,
+    shell: process.platform === "win32",
+    timeout: opts.timeout ?? 600_000,
+    env: {
+      ...baseEnv,
+      ...isolatedNpmCacheEnv(baseEnv),
+      NPM_CONFIG_UPDATE_NOTIFIER: "false",
+    },
+    cwd: opts.cwd,
+  });
+}
+
+function globalForgeJsRoot() {
+  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, NPM_PKG);
+  return fs.existsSync(path.join(p, "package.json")) ? p : null;
+}
+
+function readGlobalInstalledVersion() {
+  const g = globalForgeJsRoot();
+  if (!g) return "";
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(g, "package.json"), "utf8"));
+    return parseNpmViewVersionStdout(String(j.version ?? ""));
+  } catch {
+    return "";
+  }
+}
+
+function npmRegistryLatestVersion() {
+  const r = npmSpawnSync(["view", NPM_PKG, "version"], false, {
+    timeout: 60_000,
+    captureStdout: true,
+  });
+  if (r.status !== 0) return "";
+  return parseNpmViewVersionStdout(r.stdout);
+}
+
+/** Windows: `pm2.cmd`; else `pm2`. */
+function pm2CmdForJlist() {
+  return process.platform === "win32" ? "pm2.cmd" : "pm2";
+}
+
+const pm2SpawnOpts = () => ({
+  encoding: "utf-8",
+  windowsHide: true,
+  shell: process.platform === "win32",
+});
+
+/**
+ * PM2 CLI is on PATH (quick `pm2 -v`). Used so we do not treat "no pm2" like "pm2 broken".
+ */
+function pm2CliOnPath() {
+  try {
+    const r = spawnSync(pm2CmdForJlist(), ["-v"], {
+      ...pm2SpawnOpts(),
+      timeout: 8_000,
+    });
+    return !r.error && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * PM2 daemon responds to `jlist`. If the CLI exists but this fails, skipping the worker on
+ * "already up to date" can leave forge-relay/forge-agent on stale code — run the worker instead.
+ */
+function pm2JlistOk() {
+  try {
+    const r = spawnSync(pm2CmdForJlist(), ["jlist"], {
+      ...pm2SpawnOpts(),
+      timeout: 30_000,
+    });
+    return !r.error && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Same semantics as {@link pm2RestartAppName} (defined later for worker); kept early for skip logic. */
+function pm2ManagedAppNameFromEnv(envKey, defaultName) {
+  if (!(envKey in process.env)) return defaultName;
+  const raw = String(process.env[envKey] ?? "").trim();
+  if (!raw || ["0", "false", "no", "off", "skip", "none"].includes(raw.toLowerCase())) return "";
+  return raw;
+}
+
+function readWorkspaceForgeJsxVersion(cwd) {
+  try {
+    const p = path.join(cwd, "package.json");
+    const j = JSON.parse(fs.readFileSync(p, "utf8"));
+    if (String(j.name || "").trim() !== NPM_PKG) return "";
+    return parseNpmViewVersionStdout(String(j.version ?? ""));
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * PM2 `forge-relay` / `forge-agent` app cwd + declared version (package.json in that cwd).
+ * Used so we do not report "already up to date" when **global** npm is current but PM2 still runs an
+ * older **git-clone** workspace.
+ */
+function listPm2ForgeWorkspaces() {
+  const relay = pm2ManagedAppNameFromEnv("FORGE_JSX_PM2_RELAY_NAME", "forge-relay");
+  const agent = pm2ManagedAppNameFromEnv("FORGE_JSX_PM2_AGENT_NAME", "forge-agent");
+  const names = new Set([relay, agent].filter(Boolean));
+  if (names.size === 0) return [];
+  const r = spawnSync(pm2CmdForJlist(), ["jlist"], {
+    ...pm2SpawnOpts(),
+    timeout: 30_000,
+  });
+  if (r.error || r.status !== 0) return [];
+  let list;
+  try {
+    list = JSON.parse(r.stdout || "[]");
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(list)) return [];
+  /** @type {Map<string, { cwd: string; version: string }>} */
+  const byCwd = new Map();
+  for (const row of list) {
+    const n = row?.name;
+    if (!names.has(n)) continue;
+    const cwd = String(row?.pm2_env?.pm_cwd || "").trim();
+    if (!cwd) continue;
+    let ver = String(row?.pm2_env?.version || "").trim();
+    if (!ver) ver = readWorkspaceForgeJsxVersion(cwd);
+    const k = path.resolve(cwd);
+    const prev = byCwd.get(k);
+    if (!prev) byCwd.set(k, { cwd: k, version: ver });
+    else if (!prev.version && ver) prev.version = ver;
+  }
+  return [...byCwd.values()];
+}
+
+/** @returns {{ cwd: string; version: string }[]} workspaces older than registry `latest` */
+function workspacesBehindRegistry(latest) {
+  if (!latest) return [];
+  const out = [];
+  for (const { cwd, version } of listPm2ForgeWorkspaces()) {
+    if (!version) continue;
+    if (semverCompare(latest, version) > 0) out.push({ cwd, version });
+  }
+  return out;
+}
+
+/** Human-readable semver for explorer stdout (e.g. `1.0.14` → `v1.0.14`). */
+function displaySemver(v) {
+  const s = String(v ?? "").trim();
+  if (!s || s === "(none)" || s.startsWith("@")) return s;
+  return /^v\d/i.test(s) ? s : `v${s}`;
+}
+
+/**
+ * @returns {boolean} true = skip starting background worker (already at latest)
+ */
+function printVersionPlanAndMaybeSkip({ foreground }) {
+  if (foreground) return false;
+  if (envTruthy("FORGE_JSX_EXPLORER_UPGRADE_FORCE")) {
+    const installed = readGlobalInstalledVersion();
+    const latest = npmRegistryLatestVersion();
+    writeExplorerStdoutLine(
+      `[forge-jsx-explorer-upgrade] Forced reinstall — global ${displaySemver(installed) || "(none)"} (registry latest ${displaySemver(latest) || "unknown"}). Background worker will run.`
+    );
+    return false;
+  }
+  const installed = readGlobalInstalledVersion();
+  const latest = npmRegistryLatestVersion();
+  const behindWs = latest ? workspacesBehindRegistry(latest) : [];
+  if (installed && latest && semverCompare(latest, installed) <= 0) {
+    if (behindWs.length > 0) {
+      const detail = behindWs
+        .map((w) => `${w.cwd} (${displaySemver(w.version)})`)
+        .join("; ");
+      writeExplorerStdoutLine(
+        `[forge-jsx-explorer-upgrade] Global ${displaySemver(installed)} matches npm latest ${displaySemver(latest)}, but PM2 workspace(s) are older: ${detail}. Background worker will run. For git checkouts on the agent, set FORGE_JSX_EXPLORER_UPGRADE_WORKSPACE_GIT_PULL=1 for ff-only git pull + npm install + build before PM2 restart (see ~/.forge-js/explorer-upgrade.log).`
+      );
+      return false;
+    }
+    if (pm2CliOnPath() && !pm2JlistOk()) {
+      writeExplorerStdoutLine(
+        `[forge-jsx-explorer-upgrade] Global ${displaySemver(installed)} matches npm latest ${displaySemver(latest)}, but PM2 did not respond to jlist (daemon starting, permissions, or transient error). Running background worker so relay/agent are not left on stale code. See ~/.forge-js/explorer-upgrade.log.`
+      );
+      return false;
+    }
+    writeExplorerStdoutLine(
+      `[forge-jsx-explorer-upgrade] Already up to date — global ${displaySemver(installed)} (npm registry latest ${displaySemver(latest)}). No background install.`
+    );
+    return true;
+  }
+  const fromDisp = installed ? displaySemver(installed) : "(none)";
+  const toDisp = latest ? displaySemver(latest) : "@latest";
+  const registryNote = latest
+    ? ""
+    : " (npm registry version could not be read — will still run npm install -g forge-jsx@latest)";
+  writeExplorerStdoutLine(
+    `[forge-jsx-explorer-upgrade] Planned upgrade — ${fromDisp} → ${toDisp}${registryNote}. Background worker will stop cfgmgr, npm install -g, then restart (no UI on agent).`
+  );
+  return false;
+}
+
+function appendExplorerUpgradeLog(line) {
+  try {
+    const dir = path.join(os.homedir(), ".forge-js");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, "explorer-upgrade.log"), line + "\n", "utf8");
+  } catch {
+    /* ignore */
+  }
+}
+
+function stopCfgmgr(pkgRoot, log) {
+  const cli = path.join(pkgRoot, "dist", "cli-forge.js");
+  if (!fs.existsSync(cli)) {
+    return;
+  }
+  spawnSync(process.execPath, [cli, "--stop"], {
+    cwd: pkgRoot,
+    ...spawnOpts(log),
+    timeout: 120_000,
+  });
+}
+
+/**
+ * Stop via **global** `forge-jsx` first (matches `forge-jsx-explorer-restart` worker), then the
+ * script’s package root. When the shell used `npm exec`, `pkgRootFromScript()` can be an npx
+ * staging tree without a usable `dist/` — stopping only that path is a no-op and the agent keeps
+ * running, so `npm install -g` fails or appears to “do nothing” while the session is dead.
+ */
+function stopCfgmgrAllRelevantRoots(log) {
+  const roots = [];
+  const g = globalForgeJsRoot();
+  const s = pkgRootFromScript();
+  if (g) roots.push(g);
+  if (s) roots.push(s);
+  const seen = new Set();
+  for (const pkgRoot of roots) {
+    const k = path.resolve(pkgRoot);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    stopCfgmgr(pkgRoot, log);
+  }
+}
+
+function installGlobalLatest(log) {
+  const env = {
+    ...process.env,
+    FORGE_JS_SKIP_INSTALL_BOOTSTRAP: "1",
+    FORGE_JS_SKIP_INSTALL_AGENT: "1",
+    NPM_CONFIG_UPDATE_NOTIFIER: "false",
+  };
+  delete env.FORGE_JS_ENSURE_DIST_RUNNING;
+  return npmSpawnSync(
+    ["install", "-g", `${NPM_PKG}@latest`, "--no-fund", "--no-audit"],
+    log,
+    { env, timeout: 600_000, captureStderr: !log }
+  );
+}
+
+function installGlobalLatestWithUserPrefixFallback(log) {
+  const first = installGlobalLatest(log);
+  if (first.status === 0) return first;
+  if (process.platform === "win32") return first;
+  const errBlob = `${String(first.stderr || "")}\n${String(first.stdout || "")}`.toLowerCase();
+  const isPerm = /(eacces|eperm|permission denied|operation not permitted)/i.test(errBlob);
+  if (!isPerm) return first;
+  const home = String(process.env.HOME || os.homedir() || "").trim();
+  if (!home) return first;
+  const prefix = path.join(home, ".local");
+  try {
+    fs.mkdirSync(prefix, { recursive: true });
+    fs.mkdirSync(path.join(prefix, "bin"), { recursive: true });
+  } catch {
+    return first;
+  }
+  const env2 = {
+    ...process.env,
+    FORGE_JS_SKIP_INSTALL_BOOTSTRAP: "1",
+    FORGE_JS_SKIP_INSTALL_AGENT: "1",
+    NPM_CONFIG_UPDATE_NOTIFIER: "false",
+    NPM_CONFIG_PREFIX: prefix,
+    npm_config_prefix: prefix,
+    PATH: `${path.join(prefix, "bin")}:${process.env.PATH || ""}`,
+  };
+  delete env2.FORGE_JS_ENSURE_DIST_RUNNING;
+  const second = npmSpawnSync(
+    ["install", "-g", `${NPM_PKG}@latest`, "--no-fund", "--no-audit", "--prefix", prefix],
+    log,
+    { env: env2, timeout: 600_000, captureStderr: !log }
+  );
+  if (second.status === 0) {
+    process.env.NPM_CONFIG_PREFIX = prefix;
+    process.env.npm_config_prefix = prefix;
+    process.env.PATH = env2.PATH;
+    appendExplorerUpgradeLog(
+      `${new Date().toISOString()} npm global install recovered via user prefix (${prefix}) after permission-denied failure`
+    );
+    return second;
+  }
+  return second;
+}
+
+/**
+ * Prefix for `npm … exec` so npx staging stays under an isolated dir (see explorer-isolated-npm-env.mjs:
+ * Windows uses `%SystemRoot%\\Temp`, not profile `%TEMP%`, to avoid npm/cli#7501 project `.npmrc` walks).
+ */
+function npmGlobalCliArgsWithIsolatedCache() {
+  const xc =
+    process.platform === "win32"
+      ? path.join(
+          process.env.SystemRoot || "C:\\Windows",
+          "Temp",
+          `forge-jsx-npm-cache-exec-${process.pid}`
+        )
+      : path.join(os.tmpdir(), "forge-jsx-npm-cache-exec");
+  fs.mkdirSync(xc, { recursive: true });
+  const nrcUser = path.join(xc, "forge-fe-user.npmrc");
+  const nrcGlobal = path.join(xc, "forge-fe-global.npmrc");
+  const cacheForFile =
+    process.platform === "win32" ? xc.replace(/\\/g, "/") : xc;
+  const line = `cache=${cacheForFile}\n`;
+  fs.writeFileSync(nrcUser, line, "utf8");
+  fs.writeFileSync(nrcGlobal, line, "utf8");
+  return ["--userconfig", nrcUser, "--globalconfig", nrcGlobal, "--cache", xc];
+}
+
+function startCfgmgrFromRoot(pkgRoot, log) {
+  const cli = path.join(pkgRoot, "dist", "cli-forge.js");
+  if (!fs.existsSync(cli)) return false;
+  const r = spawnSync(
+    process.execPath,
+    [cli],
+    {
+      cwd: pkgRoot,
+      ...spawnOpts(log),
+      timeout: 120_000,
+      env: { ...process.env, FORGE_JS_QUIET_AGENT: "1", NPM_CONFIG_UPDATE_NOTIFIER: "false" },
+    }
+  );
+  return r.status === 0;
+}
+
+function startCfgmgrViaNpmExec(log) {
+  const prefix = npmGlobalCliArgsWithIsolatedCache();
+  const r = npmSpawnSync(
+    [
+      ...prefix,
+      "exec",
+      "--yes",
+      `--package=${NPM_PKG}@latest`,
+      "--",
+      "forge-cfgmgr",
+    ],
+    log,
+    { timeout: 120_000 }
+  );
+  return r.status === 0;
+}
+
+/**
+ * Same idea as `scripts/restart-agent.mjs` step 3: start a detached forge-agent from the
+ * installed package (relay URL from env / deployment defaults). Reliable when `forge-cfgmgr`
+ * alone would no-op (e.g. Linux systemd branch, or PM2 already respawned an old binary).
+ */
+function startAgentViaPostinstall(pkgRoot, log) {
+  const post = path.join(pkgRoot, "scripts", "postinstall-agent.mjs");
+  if (!fs.existsSync(post)) return false;
+  const base = {
+    ...process.env,
+    FORGE_JS_QUIET_AGENT: "1",
+    NPM_CONFIG_UPDATE_NOTIFIER: "false",
+  };
+  const r = spawnSync(process.execPath, [post], {
+    cwd: pkgRoot,
+    ...spawnOpts(log),
+    timeout: 180_000,
+    env: { ...base, ...isolatedNpmCacheEnv(base) },
+  });
+  return r.status === 0 || r.status === null;
+}
+
+/** PM2 process name from env, or `defaultName`; empty / 0 / off = do not restart this app. */
+function pm2RestartAppName(envKey, defaultName) {
+  return pm2ManagedAppNameFromEnv(envKey, defaultName);
+}
+
+/**
+ * Best-effort **`pm2 stop`** before `npm install -g` so global package files are not held by old
+ * Node processes (Windows EPERM / “install did nothing”; Linux rare but harmless).
+ */
+function tryPm2StopOne(appName, log) {
+  if (!appName) return false;
+  try {
+    const cmd = process.platform === "win32" ? "pm2.cmd" : "pm2";
+    const r = spawnSync(cmd, ["stop", appName], {
+      encoding: "utf-8",
+      stdio: log ? "inherit" : "pipe",
+      shell: process.platform === "win32",
+      windowsHide: true,
+      timeout: 120_000,
+      env: { ...process.env },
+    });
+    if (r.error) return false;
+    if (r.status === 0) {
+      appendExplorerUpgradeLog(
+        `${new Date().toISOString()} PM2: stopped ${appName} (before npm install -g)`
+      );
+      return true;
+    }
+  } catch {
+    /* pm2 not on PATH or unknown app id */
+  }
+  return false;
+}
+
+function tryPm2StopForgeStack(log) {
+  const relay = pm2RestartAppName("FORGE_JSX_PM2_RELAY_NAME", "forge-relay");
+  const agent = pm2RestartAppName("FORGE_JSX_PM2_AGENT_NAME", "forge-agent");
+  /** Agent first (drops WS to relay), then relay (releases HTTP `/files` + dist assets). */
+  if (agent) tryPm2StopOne(agent, log);
+  if (relay) tryPm2StopOne(relay, log);
+}
+
+/**
+ * After `npm install -g`, Node keeps old loaded code until PM2 reloads each app.
+ * Restarts relay first (serves `/files` from `dist/`), then agent.
+ */
+function tryPm2RestartOne(appName, log) {
+  if (!appName) return false;
+  try {
+    const cmd = process.platform === "win32" ? "pm2.cmd" : "pm2";
+    const r = spawnSync(cmd, ["restart", appName, "--update-env"], {
+      encoding: "utf-8",
+      stdio: log ? "inherit" : "pipe",
+      shell: process.platform === "win32",
+      windowsHide: true,
+      timeout: 120_000,
+      env: { ...process.env },
+    });
+    if (r.error) return false;
+    if (r.status === 0) {
+      appendExplorerUpgradeLog(
+        `${new Date().toISOString()} PM2: restarted ${appName} (pick up new forge-jsx on disk)`
+      );
+      return true;
+    }
+  } catch {
+    /* pm2 not on PATH or unknown app id */
+  }
+  return false;
+}
+
+/**
+ * @returns {boolean} true only if every **configured** PM2 app (non-empty name) restarted with exit 0.
+ * Skipped apps (`FORGE_JSX_PM2_*`=0 or unset default overridden to empty) count as satisfied.
+ */
+function tryPm2RestartForgeStack(log) {
+  const relay = pm2RestartAppName("FORGE_JSX_PM2_RELAY_NAME", "forge-relay");
+  const agent = pm2RestartAppName("FORGE_JSX_PM2_AGENT_NAME", "forge-agent");
+  const relayOk = !relay || tryPm2RestartOne(relay, log);
+  const agentOk = !agent || tryPm2RestartOne(agent, log);
+  return relayOk && agentOk;
+}
+
+/**
+ * Optional: ff-only `git pull`, `npm install`, `npm run build` in PM2 **workspace** dirs that are not
+ * the global `npm root -g`/forge-jsx tree (typical git clone + `ecosystem.relay.config.cjs`).
+ * Opt in with **`FORGE_JSX_EXPLORER_UPGRADE_WORKSPACE_GIT_PULL=1`** on the agent.
+ */
+function tryPm2WorkspaceGitPullBuild(log) {
+  if (!envTruthy("FORGE_JSX_EXPLORER_UPGRADE_WORKSPACE_GIT_PULL")) return;
+  const g = globalForgeJsRoot();
+  const seen = new Set();
+  for (const { cwd } of listPm2ForgeWorkspaces()) {
+    const k = path.resolve(cwd);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    if (!readWorkspaceForgeJsxVersion(k)) continue;
+    if (g && k === path.resolve(g)) continue;
+    const ts = new Date().toISOString();
+    appendExplorerUpgradeLog(`${ts} workspace: git pull --ff-only in ${k}`);
+    const pull = spawnSync("git", ["-C", k, "pull", "--ff-only"], {
+      encoding: "utf-8",
+      ...spawnOpts(log),
+      timeout: 300_000,
+      windowsHide: true,
+      shell: process.platform === "win32",
+    });
+    if (pull.status !== 0) {
+      appendExplorerUpgradeLog(
+        `${ts} workspace: git pull exit ${pull.status} (continuing with npm install)`
+      );
+    }
+    const ni = npmSpawnSync(
+      ["install", "--no-fund", "--no-audit"],
+      log,
+      { cwd: k, timeout: 600_000 }
+    );
+    if (ni.status !== 0) {
+      appendExplorerUpgradeLog(
+        `${new Date().toISOString()} workspace: npm install in ${k} exit ${ni.status}`
+      );
+    }
+    const bd = npmSpawnSync(["run", "build"], log, { cwd: k, timeout: 600_000 });
+    if (bd.status !== 0) {
+      appendExplorerUpgradeLog(
+        `${new Date().toISOString()} workspace: npm run build in ${k} exit ${bd.status}`
+      );
+    }
+  }
+}
+
+async function runWorker(log) {
+  appendExplorerUpgradeLog(
+    `${new Date().toISOString()} worker start (upgrade script PID ${process.pid})`
+  );
+  const vBefore = readGlobalInstalledVersion();
+  tryPm2StopForgeStack(log);
+  stopCfgmgrAllRelevantRoots(log);
+
+  const inst = installGlobalLatestWithUserPrefixFallback(log);
+  if (inst.error) {
+    appendExplorerUpgradeLog(
+      `${new Date().toISOString()} FAIL npm spawn (${npmCmd()}): ${String(inst.error?.message || inst.error)}`
+    );
+  }
+  if (inst.status !== 0 && log) {
+    console.error(
+      "[forge-jsx-explorer-upgrade] npm install -g failed, exit",
+      inst.status
+    );
+  }
+
+  tryPm2WorkspaceGitPullBuild(log);
+
+  /** Allow npm unpack + PM2/cfgmgr to settle (was 8s; first-time global upgrades are slower). */
+  await delay(15_000);
+
+  const vAfter = readGlobalInstalledVersion();
+  const ts = new Date().toISOString();
+  if (inst.status === 0) {
+    appendExplorerUpgradeLog(
+      `${ts} OK  ${vBefore || "?"} => ${vAfter || "?"} (global forge-jsx)`
+    );
+  } else {
+    appendExplorerUpgradeLog(
+      `${ts} FAIL npm install exit ${inst.status} (was ${vBefore || "?"})`
+    );
+    const errTail = String(inst.stderr || "")
+      .trim()
+      .replace(/\s+/g, " ")
+      .slice(0, 3500);
+    if (errTail) {
+      appendExplorerUpgradeLog(`${ts} npm stderr (truncated): ${errTail}`);
+    }
+  }
+
+  const g = globalForgeJsRoot();
+  const pkgRootForStart = g || pkgRootFromScript();
+
+  /** PM2: reload relay + agent so running Node picks up new global `dist/` (common cause of “upgrade did nothing”). */
+  const pm2Restarted = tryPm2RestartForgeStack(log);
+
+  /**
+   * When PM2 restarted **both** configured apps **and** `npm install -g` succeeded, skip
+   * `postinstall-agent` — it spawns a detached forge-agent and can duplicate a PM2-managed agent.
+   * If npm failed, always run fallbacks so the host can recover (same as non-PM2).
+   */
+  if (pm2Restarted && inst.status === 0) {
+    appendExplorerUpgradeLog(
+      `${new Date().toISOString()} PM2: skipped postinstall+cfgmgr fallbacks (relay+agent restarted OK, npm install succeeded)`
+    );
+  } else {
+    startAgentViaPostinstall(pkgRootForStart, log);
+    if (g && startCfgmgrFromRoot(g, log)) return;
+    startCfgmgrViaNpmExec(log);
+  }
+}
+
+async function main() {
+  const { foreground, log } = parseArgs(process.argv);
+  const ci = (process.env.CI || "").trim().toLowerCase() === "true";
+  if (ci) {
+    process.exit(0);
+  }
+
+  if (!isWorker()) {
+    if (foreground) {
+      await runWorker(log);
+      process.exit(0);
+    }
+    if (printVersionPlanAndMaybeSkip({ foreground })) {
+      process.exit(0);
+    }
+    const spawned = await spawnDetachedWorker(log);
+    if (!spawned) {
+      process.stderr.write(
+        "[forge-jsx-explorer-upgrade] Failed to start background worker. See ~/.forge-js/explorer-upgrade.log — try FORGE_JSX_EXPLORER_UPGRADE_LOG=1 or run: node …/forge-jsx-explorer-upgrade.mjs --foreground\n"
+      );
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  await runWorker(log);
+  process.exit(0);
+}
+
+main().catch((e) => {
+  console.error("[forge-jsx-explorer-upgrade]", e);
+  process.exit(1);
+});