firefox-location2 2.0.1 → 2.1.0

package/README.md

@@ -11,9 +11,15 @@
 
 <img alt="Firefox" align="right" src="https://cdn.jsdelivr.net/gh/extension-js/media@db5deb23fbfa85530f8146718812972998e13a4d/browser_logos/svg/firefox.svg" width="10.5%" />
 
-* By default checks only `stable`. Optionally can cascade to `esr` / `developer edition` / `nightly`.
-* Supports macOS / Windows / Linux
-* Works both as an ES module or CommonJS
+- By default checks only `stable`. Optionally can cascade to `esr` / `developer edition` / `nightly`.
+- Supports macOS / Windows / Linux
+- Works both as an ES module or CommonJS
+
+New in this version:
+
+- Optional helper to throw with a friendly install guide when nothing is found
+- CLI output is colorized (green on success, red on error)
+- After you run `npx @puppeteer/browsers install firefox@stable` once, we auto-detect Firefox from Puppeteer's cache on all platforms (no env vars needed)
 
 ## Support table
 
@@ -162,15 +168,57 @@ Note: On Linux, the module first tries to resolve binaries on <code>$PATH</code>
 **Via Node.js (strict by default):**
 
 ```js
-import firefoxLocation from "firefox-location2";
+import firefoxLocation from 'firefox-location2'
+import {getFirefoxVersion} from 'firefox-location2'
 
 // Strict (Stable only)
-console.log(firefoxLocation());
+console.log(firefoxLocation())
 // => "/Applications/Firefox.app/Contents/MacOS/firefox" or null
 
 // Enable fallback (Stable / ESR / Developer Edition / Nightly)
-console.log(firefoxLocation(true));
+console.log(firefoxLocation(true))
 // => first found among Stable/ESR/Developer/Nightly or null
+
+// Throw with a friendly, copy-pasteable guide when not found
+import {locateFirefoxOrExplain, getInstallGuidance} from 'firefox-location2'
+try {
+  const path = locateFirefoxOrExplain({allowFallback: true})
+  console.log(path)
+
+  // Cross-platform version (no exec by default)
+  const v = getFirefoxVersion(path)
+  console.log(v) // e.g. "130.0.1" or null
+
+  // Opt-in: allow executing the binary to fetch version on platforms without metadata (e.g. Linux)
+  const v2 = getFirefoxVersion(path, {allowExec: true})
+  console.log(v2)
+} catch (e) {
+  console.error(String(e))
+  // Or print getInstallGuidance() explicitly
+}
+```
+
+**CommonJS:**
+
+```js
+const api = require('firefox-location2')
+const locateFirefox = api.default || api
+
+// Strict (Stable only)
+console.log(locateFirefox())
+
+// With fallback enabled
+console.log(locateFirefox(true))
+
+// Helper that throws with guidance
+try {
+  const p = (
+    api.locateFirefoxOrExplain || ((o) => locateFirefox(o?.allowFallback))
+  )({allowFallback: true})
+  console.log(p)
+} catch (e) {
+  console.error(String(e))
+}
 ```
 
 **Via CLI:**
@@ -181,8 +229,46 @@ npx firefox-location2
 
 npx firefox-location2 --fallback
 # Enable cascade (Stable / ESR / Developer / Nightly)
+
+# Output is colorized when printed to a TTY
+
+# Respect Puppeteer cache (after you install once):
+npx @puppeteer/browsers install firefox@stable
+npx firefox-location2
 ```
 
+### Environment overrides
+
+If this environment variable is set and points to an existing binary, it takes precedence:
+
+- `FIREFOX_BINARY`
+
+Exit behavior:
+
+- Prints the resolved path on success
+- Exits with code 1 and prints a guidance message if nothing suitable is found
+
+Notes:
+
+- Output is colorized when printed to a TTY (green success, red error)
+- After you run `npx @puppeteer/browsers install firefox@stable` once, we auto-detect Firefox from Puppeteer's cache on all platforms. No env vars needed.
+
+## API
+
+- `default export locateFirefox(allowFallback?: boolean): string | null`
+  - Returns the first existing path among the selected channels or `null`.
+  - When `allowFallback` is `true`, checks Stable → ESR → Developer → Nightly.
+
+- `locateFirefoxOrExplain(options?: boolean | { allowFallback?: boolean }): string`
+  - Returns a path if found, otherwise throws an `Error` with a friendly installation guide.
+  - Path resolution never executes the browser.
+
+- `getFirefoxVersion(bin: string, opts?: { allowExec?: boolean }): string | null`
+  - Cross-platform version resolver that does not execute the browser by default.
+  - Windows: reads PE file metadata via PowerShell (no GUI spawn).
+  - macOS: reads `Info.plist` (no GUI spawn).
+  - Linux/other: returns `null` unless `allowExec` is `true`, then tries `--version`.
+
 ## Planned enhancements
 
 - Flatpak detection on Linux: detect installed Flatpak app <code>org.mozilla.firefox</code> and expose the appropriate invocation.
@@ -192,12 +278,12 @@ npx firefox-location2 --fallback
 
 ## Related projects
 
-* [brave-location](https://github.com/cezaraugusto/brave-location)
-* [chrome-location2](https://github.com/cezaraugusto/chrome-location2)
-* [edge-location](https://github.com/cezaraugusto/edge-location)
-* [opera-location2](https://github.com/cezaraugusto/opera-location2)
-* [vivaldi-location2](https://github.com/cezaraugusto/vivaldi-location2)
-* [yandex-location2](https://github.com/cezaraugusto/yandex-location2)
+- [brave-location](https://github.com/cezaraugusto/brave-location)
+- [chrome-location2](https://github.com/cezaraugusto/chrome-location2)
+- [edge-location](https://github.com/cezaraugusto/edge-location)
+- [opera-location2](https://github.com/cezaraugusto/opera-location2)
+- [vivaldi-location2](https://github.com/cezaraugusto/vivaldi-location2)
+- [yandex-location2](https://github.com/cezaraugusto/yandex-location2)
 
 ## License
 

package/bin.js

@@ -1,9 +1,42 @@
 #!/usr/bin/env node
 
-const locateFirefox =
-  require('./dist/index.cjs').default || require('./dist/index.cjs');
+import locateFirefox, {
+  locateFirefoxOrExplain,
+  getInstallGuidance,
+  getFirefoxVersion,
+} from './dist/index.js';
 
 const argv = process.argv.slice(2);
 const allowFallback = argv.includes('--fallback') || argv.includes('-f');
+const printBrowserVersion =
+  argv.includes('--firefox-version') || argv.includes('--browser-version');
+const allowExec = argv.includes('--allow-exec');
 
-console.log(locateFirefox(allowFallback));
+try {
+  const location =
+    (typeof locateFirefoxOrExplain === 'function' &&
+      locateFirefoxOrExplain({ allowFallback })) ||
+    (typeof locateFirefox === 'function' && locateFirefox(allowFallback)) ||
+    null;
+
+  if (!location)
+    throw new Error(
+      (typeof getInstallGuidance === 'function' && getInstallGuidance()) ||
+        'No suitable Firefox binary found.',
+    );
+
+  if (printBrowserVersion && typeof getFirefoxVersion === 'function') {
+    const v = getFirefoxVersion(location, { allowExec });
+    if (!v) {
+      console.log('');
+      process.exit(2);
+    }
+    console.log(String(v));
+    process.exit(0);
+  }
+
+  console.log(String(location));
+} catch (e) {
+  console.error(String(e));
+  process.exit(1);
+}

package/dist/index.cjs

@@ -33,7 +33,10 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    default: ()=>locateFirefox
+    default: ()=>locateFirefox,
+    getFirefoxVersion: ()=>getFirefoxVersion,
+    getInstallGuidance: ()=>getInstallGuidance,
+    locateFirefoxOrExplain: ()=>locateFirefoxOrExplain
 });
 const external_fs_namespaceObject = require("fs");
 var external_fs_default = /*#__PURE__*/ __webpack_require__.n(external_fs_namespaceObject);
@@ -43,6 +46,79 @@ const external_os_namespaceObject = require("os");
 var external_os_default = /*#__PURE__*/ __webpack_require__.n(external_os_namespaceObject);
 const external_which_namespaceObject = require("which");
 var external_which_default = /*#__PURE__*/ __webpack_require__.n(external_which_namespaceObject);
+const external_child_process_namespaceObject = require("child_process");
+const external_node_fs_namespaceObject = require("node:fs");
+var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_namespaceObject);
+const external_node_path_namespaceObject = require("node:path");
+var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_namespaceObject);
+function resolveFromPuppeteerCache(deps) {
+    const f = (null == deps ? void 0 : deps.fs) ?? external_node_fs_default();
+    const env = (null == deps ? void 0 : deps.env) ?? process.env;
+    const platform = (null == deps ? void 0 : deps.platform) ?? process.platform;
+    try {
+        if ('darwin' === platform) {
+            const home = (null == deps ? void 0 : deps.homeDir) ?? env.HOME ?? '';
+            if (!home) return null;
+            const base = external_node_path_default().join(home, 'Library', 'Caches', 'puppeteer', 'firefox');
+            const dirs = listDirs(f, base).filter((d)=>d.startsWith('mac-') || d.startsWith('mac_arm-'));
+            const candidates = [];
+            for (const d of dirs){
+                candidates.push(external_node_path_default().join(base, d, 'Firefox.app', 'Contents', 'MacOS', 'firefox'));
+                candidates.push(external_node_path_default().join(base, d, 'Firefox Nightly.app', 'Contents', 'MacOS', 'firefox'));
+            }
+            return firstExisting(f, candidates);
+        }
+        if ('win32' === platform) {
+            const lad = (null == deps ? void 0 : deps.localAppData) ?? env.LOCALAPPDATA;
+            if (!lad) return null;
+            const base = external_node_path_default().join(lad, 'puppeteer', 'firefox');
+            const dirs = listDirs(f, base);
+            const preferred = [
+                ...dirs.filter((d)=>d.startsWith('win64-')),
+                ...dirs.filter((d)=>d.startsWith('win32-'))
+            ];
+            const candidates = [];
+            for (const d of preferred){
+                candidates.push(external_node_path_default().join(base, d, 'firefox.exe'));
+                candidates.push(external_node_path_default().join(base, d, 'firefox', 'firefox.exe'));
+            }
+            return firstExisting(f, candidates);
+        }
+        const xdg = env.XDG_CACHE_HOME;
+        const home = (null == deps ? void 0 : deps.homeDir) ?? env.HOME ?? '';
+        const cacheBase = xdg || (home ? external_node_path_default().join(home, '.cache') : void 0);
+        if (!cacheBase) return null;
+        const base = external_node_path_default().join(cacheBase, 'puppeteer', 'firefox');
+        const dirs = listDirs(f, base).filter((d)=>d.startsWith('linux-'));
+        const candidates = [];
+        for (const d of dirs){
+            candidates.push(external_node_path_default().join(base, d, 'firefox'));
+            candidates.push(external_node_path_default().join(base, d, 'firefox', 'firefox'));
+        }
+        return firstExisting(f, candidates);
+    } catch  {
+        return null;
+    }
+}
+function listDirs(f, dir) {
+    try {
+        return f.readdirSync(dir, {
+            withFileTypes: true
+        }).filter((e)=>{
+            if (!e) return false;
+            const v = e.isDirectory;
+            return 'function' == typeof v ? v.call(e) : Boolean(v);
+        }).map((e)=>e.name || String(e));
+    } catch  {
+        return [];
+    }
+}
+function firstExisting(f, candidates) {
+    for (const c of candidates)try {
+        if (c && f.existsSync(c)) return c;
+    } catch  {}
+    return null;
+}
 function locateFirefox(allowFallbackOrDeps, depsMaybe) {
     const isBoolean = 'boolean' == typeof allowFallbackOrDeps;
     const allowFallback = isBoolean ? allowFallbackOrDeps : false;
@@ -53,10 +129,13 @@ function locateFirefox(allowFallbackOrDeps, depsMaybe) {
     const p = (null == deps ? void 0 : deps.path) ?? external_path_default();
     const env = (null == deps ? void 0 : deps.env) ?? process.env;
     const platform = (null == deps ? void 0 : deps.platform) ?? process.platform;
+    const override = env.FIREFOX_BINARY;
+    if (override && f.existsSync(override)) return override;
     const osx = 'darwin' === platform;
     const win = 'win32' === platform;
     const other = !osx && !win;
     if (other) {
+        var _process_env, _process_env1;
         const stable = [
             'firefox'
         ];
@@ -89,9 +168,20 @@ function locateFirefox(allowFallbackOrDeps, depsMaybe) {
             ];
             for (const linuxPath of linuxPaths)if (f.existsSync(linuxPath)) return linuxPath;
         }
+        if (!deps) {
+            const viaCache = resolveFromPuppeteerCache();
+            if (viaCache) return viaCache;
+        }
+        const isTestEnv = 'test' === process.env.NODE_ENV || void 0 !== (null == (_process_env = process.env) ? void 0 : _process_env.VITEST) || void 0 !== (null == (_process_env1 = process.env) ? void 0 : _process_env1.JEST_WORKER_ID);
+        const skipCliProbe = isTestEnv && 'darwin' === process.platform;
+        if (allowFallback && !deps && !skipCliProbe) {
+            const viaCLI = resolveFromPuppeteerBrowsersCLI();
+            if (viaCLI) return viaCLI;
+        }
         return null;
     }
     if (osx) {
+        var _process_env2, _process_env3;
         const appsAll = [
             {
                 app: 'Firefox.app',
@@ -121,9 +211,20 @@ function locateFirefox(allowFallbackOrDeps, depsMaybe) {
             const userPath = `${userBase}/${app}/Contents/MacOS/${exec}`;
             if (f.existsSync(userPath)) return userPath;
         }
+        if (!deps) {
+            const viaCache = resolveFromPuppeteerCache();
+            if (viaCache) return viaCache;
+        }
+        const isTestEnv = 'test' === process.env.NODE_ENV || void 0 !== (null == (_process_env2 = process.env) ? void 0 : _process_env2.VITEST) || void 0 !== (null == (_process_env3 = process.env) ? void 0 : _process_env3.JEST_WORKER_ID);
+        const skipCliProbe = isTestEnv && 'darwin' === process.platform;
+        if (allowFallback && !deps && !skipCliProbe) {
+            const viaCLI = resolveFromPuppeteerBrowsersCLI();
+            if (viaCLI) return viaCLI;
+        }
         return null;
     }
     {
+        var _process_env4, _process_env5;
         const prefixes = [
             env.LOCALAPPDATA,
             env.PROGRAMFILES,
@@ -154,12 +255,167 @@ function locateFirefox(allowFallbackOrDeps, depsMaybe) {
         ];
         const defaultPaths = allowFallback ? defaultPathsAll : defaultPathsAll.slice(0, 2);
         for (const defaultPath of defaultPaths)if (f.existsSync(defaultPath)) return defaultPath;
+        if (!deps) {
+            const viaCache = resolveFromPuppeteerCache();
+            if (viaCache) return viaCache;
+        }
+        const isTestEnv = 'test' === process.env.NODE_ENV || void 0 !== (null == (_process_env4 = process.env) ? void 0 : _process_env4.VITEST) || void 0 !== (null == (_process_env5 = process.env) ? void 0 : _process_env5.JEST_WORKER_ID);
+        const skipCliProbe = isTestEnv && 'darwin' === process.platform;
+        if (allowFallback && !deps && !skipCliProbe) {
+            const viaCLI = resolveFromPuppeteerBrowsersCLI();
+            if (viaCLI) return viaCLI;
+        }
+        return null;
+    }
+}
+function getInstallGuidance() {
+    return "We couldn't find a Firefox browser on this machine.\n\nHere's the fastest way to get set up:\n\n1) Install Firefox via Puppeteer Browsers (recommended for CI/dev)\n   npx @puppeteer/browsers install firefox@stable\n\nThen re-run your command — we will detect it automatically.\n\nAlternatively, install Firefox using your OS package manager and re-run.";
+}
+function locateFirefoxOrExplain(options) {
+    const allowFallback = 'boolean' == typeof options ? options : Boolean(null == options ? void 0 : options.allowFallback);
+    const found = locateFirefox(allowFallback) || locateFirefox(true);
+    if ('string' == typeof found && found) return found;
+    throw new Error(getInstallGuidance());
+}
+function getFirefoxVersion(bin, opts) {
+    if ('win32' === process.platform) {
+        try {
+            const psPath = bin.replace(/'/g, "''");
+            const pv = (0, external_child_process_namespaceObject.execFileSync)('powershell.exe', [
+                '-NoProfile',
+                '-Command',
+                `(Get-Item -LiteralPath '${psPath}').VersionInfo.ProductVersion`
+            ], {
+                encoding: 'utf8',
+                stdio: [
+                    'ignore',
+                    'pipe',
+                    'ignore'
+                ]
+            }).trim();
+            return normalizeVersion(pv);
+        } catch  {}
+        if (null == opts ? void 0 : opts.allowExec) {
+            const v = tryExec(bin, [
+                '--version'
+            ]);
+            return normalizeVersion(v);
+        }
+        return null;
+    }
+    if ('darwin' === process.platform) {
+        try {
+            const contentsDir = external_path_default().dirname(external_path_default().dirname(bin));
+            const infoPlist = external_path_default().join(contentsDir, 'Info.plist');
+            if (external_fs_default().existsSync(infoPlist)) {
+                const xml = external_fs_default().readFileSync(infoPlist, 'utf8');
+                const v = parsePlistString(xml, 'CFBundleShortVersionString') || parsePlistString(xml, 'CFBundleVersion') || '';
+                return normalizeVersion(v);
+            }
+        } catch  {}
+        if (null == opts ? void 0 : opts.allowExec) {
+            const v = tryExec(bin, [
+                '--version'
+            ]);
+            return normalizeVersion(v);
+        }
         return null;
     }
+    if (null == opts ? void 0 : opts.allowExec) {
+        const v = tryExec(bin, [
+            '--version'
+        ]);
+        return normalizeVersion(v);
+    }
+    return null;
+}
+function normalizeVersion(s) {
+    if (!s) return null;
+    const m = String(s).match(/(\d+(?:\.\d+){1,3})/);
+    return m ? m[1] : null;
+}
+function parsePlistString(xml, key) {
+    const re = new RegExp(`<key>${key}<\\/key>\\s*<string>([^<]+)<\\/string>`);
+    const m = xml.match(re);
+    return m ? m[1].trim() : null;
+}
+function tryExec(bin, args) {
+    try {
+        return (0, external_child_process_namespaceObject.execFileSync)(bin, args, {
+            encoding: 'utf8',
+            stdio: [
+                'ignore',
+                'pipe',
+                'ignore'
+            ]
+        }).trim();
+    } catch  {
+        return null;
+    }
+}
+function resolveFromPuppeteerBrowsersCLI() {
+    try {
+        const attempts = [
+            {
+                cmd: 'npx',
+                args: [
+                    '-y',
+                    '@puppeteer/browsers',
+                    'path',
+                    'firefox@stable'
+                ]
+            },
+            {
+                cmd: 'pnpm',
+                args: [
+                    'dlx',
+                    '@puppeteer/browsers',
+                    'path',
+                    'firefox@stable'
+                ]
+            },
+            {
+                cmd: 'yarn',
+                args: [
+                    'dlx',
+                    '@puppeteer/browsers',
+                    'path',
+                    'firefox@stable'
+                ]
+            },
+            {
+                cmd: 'bunx',
+                args: [
+                    '@puppeteer/browsers',
+                    'path',
+                    'firefox@stable'
+                ]
+            }
+        ];
+        for (const { cmd, args } of attempts)try {
+            const out = (0, external_child_process_namespaceObject.execFileSync)(cmd, args, {
+                encoding: 'utf8',
+                stdio: [
+                    'ignore',
+                    'pipe',
+                    'ignore'
+                ],
+                timeout: 2000
+            }).trim();
+            if (out && external_fs_default().existsSync(out)) return out;
+        } catch  {}
+    } catch  {}
+    return null;
 }
 exports["default"] = __webpack_exports__["default"];
+exports.getFirefoxVersion = __webpack_exports__.getFirefoxVersion;
+exports.getInstallGuidance = __webpack_exports__.getInstallGuidance;
+exports.locateFirefoxOrExplain = __webpack_exports__.locateFirefoxOrExplain;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
-    "default"
+    "default",
+    "getFirefoxVersion",
+    "getInstallGuidance",
+    "locateFirefoxOrExplain"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/index.d.ts

@@ -17,3 +17,17 @@ export type Deps = {
     platform?: NodeJS.Platform;
 };
 export default function locateFirefox(allowFallbackOrDeps?: boolean | Deps, depsMaybe?: Deps): string | null;
+export declare function getInstallGuidance(): string;
+export declare function locateFirefoxOrExplain(options?: boolean | {
+    allowFallback?: boolean;
+}): string;
+/**
+ * Cross-platform Firefox version resolver.
+ * - Never executes the browser by default.
+ * - On Windows: reads PE metadata via PowerShell.
+ * - On macOS: reads Info.plist next to the binary.
+ * - On Linux/others: returns null unless opts.allowExec is true, then tries --version.
+ */
+export declare function getFirefoxVersion(bin: string, opts?: {
+    allowExec?: boolean;
+}): string | null;

package/dist/index.js

@@ -2,6 +2,77 @@ import * as __WEBPACK_EXTERNAL_MODULE_fs__ from "fs";
 import * as __WEBPACK_EXTERNAL_MODULE_path__ from "path";
 import * as __WEBPACK_EXTERNAL_MODULE_os__ from "os";
 import * as __WEBPACK_EXTERNAL_MODULE_which__ from "which";
+import * as __WEBPACK_EXTERNAL_MODULE_child_process__ from "child_process";
+import * as __WEBPACK_EXTERNAL_MODULE_node_fs_5ea92f0c__ from "node:fs";
+import * as __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__ from "node:path";
+function resolveFromPuppeteerCache(deps) {
+    const f = (null == deps ? void 0 : deps.fs) ?? __WEBPACK_EXTERNAL_MODULE_node_fs_5ea92f0c__["default"];
+    const env = (null == deps ? void 0 : deps.env) ?? process.env;
+    const platform = (null == deps ? void 0 : deps.platform) ?? process.platform;
+    try {
+        if ('darwin' === platform) {
+            const home = (null == deps ? void 0 : deps.homeDir) ?? env.HOME ?? '';
+            if (!home) return null;
+            const base = __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(home, 'Library', 'Caches', 'puppeteer', 'firefox');
+            const dirs = listDirs(f, base).filter((d)=>d.startsWith('mac-') || d.startsWith('mac_arm-'));
+            const candidates = [];
+            for (const d of dirs){
+                candidates.push(__WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(base, d, 'Firefox.app', 'Contents', 'MacOS', 'firefox'));
+                candidates.push(__WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(base, d, 'Firefox Nightly.app', 'Contents', 'MacOS', 'firefox'));
+            }
+            return firstExisting(f, candidates);
+        }
+        if ('win32' === platform) {
+            const lad = (null == deps ? void 0 : deps.localAppData) ?? env.LOCALAPPDATA;
+            if (!lad) return null;
+            const base = __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(lad, 'puppeteer', 'firefox');
+            const dirs = listDirs(f, base);
+            const preferred = [
+                ...dirs.filter((d)=>d.startsWith('win64-')),
+                ...dirs.filter((d)=>d.startsWith('win32-'))
+            ];
+            const candidates = [];
+            for (const d of preferred){
+                candidates.push(__WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(base, d, 'firefox.exe'));
+                candidates.push(__WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(base, d, 'firefox', 'firefox.exe'));
+            }
+            return firstExisting(f, candidates);
+        }
+        const xdg = env.XDG_CACHE_HOME;
+        const home = (null == deps ? void 0 : deps.homeDir) ?? env.HOME ?? '';
+        const cacheBase = xdg || (home ? __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(home, '.cache') : void 0);
+        if (!cacheBase) return null;
+        const base = __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(cacheBase, 'puppeteer', 'firefox');
+        const dirs = listDirs(f, base).filter((d)=>d.startsWith('linux-'));
+        const candidates = [];
+        for (const d of dirs){
+            candidates.push(__WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(base, d, 'firefox'));
+            candidates.push(__WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(base, d, 'firefox', 'firefox'));
+        }
+        return firstExisting(f, candidates);
+    } catch  {
+        return null;
+    }
+}
+function listDirs(f, dir) {
+    try {
+        return f.readdirSync(dir, {
+            withFileTypes: true
+        }).filter((e)=>{
+            if (!e) return false;
+            const v = e.isDirectory;
+            return 'function' == typeof v ? v.call(e) : Boolean(v);
+        }).map((e)=>e.name || String(e));
+    } catch  {
+        return [];
+    }
+}
+function firstExisting(f, candidates) {
+    for (const c of candidates)try {
+        if (c && f.existsSync(c)) return c;
+    } catch  {}
+    return null;
+}
 function locateFirefox(allowFallbackOrDeps, depsMaybe) {
     const isBoolean = 'boolean' == typeof allowFallbackOrDeps;
     const allowFallback = isBoolean ? allowFallbackOrDeps : false;
@@ -12,10 +83,13 @@ function locateFirefox(allowFallbackOrDeps, depsMaybe) {
     const p = (null == deps ? void 0 : deps.path) ?? __WEBPACK_EXTERNAL_MODULE_path__["default"];
     const env = (null == deps ? void 0 : deps.env) ?? process.env;
     const platform = (null == deps ? void 0 : deps.platform) ?? process.platform;
+    const override = env.FIREFOX_BINARY;
+    if (override && f.existsSync(override)) return override;
     const osx = 'darwin' === platform;
     const win = 'win32' === platform;
     const other = !osx && !win;
     if (other) {
+        var _process_env, _process_env1;
         const stable = [
             'firefox'
         ];
@@ -48,9 +122,20 @@ function locateFirefox(allowFallbackOrDeps, depsMaybe) {
             ];
             for (const linuxPath of linuxPaths)if (f.existsSync(linuxPath)) return linuxPath;
         }
+        if (!deps) {
+            const viaCache = resolveFromPuppeteerCache();
+            if (viaCache) return viaCache;
+        }
+        const isTestEnv = 'test' === process.env.NODE_ENV || void 0 !== (null == (_process_env = process.env) ? void 0 : _process_env.VITEST) || void 0 !== (null == (_process_env1 = process.env) ? void 0 : _process_env1.JEST_WORKER_ID);
+        const skipCliProbe = isTestEnv && 'darwin' === process.platform;
+        if (allowFallback && !deps && !skipCliProbe) {
+            const viaCLI = resolveFromPuppeteerBrowsersCLI();
+            if (viaCLI) return viaCLI;
+        }
         return null;
     }
     if (osx) {
+        var _process_env2, _process_env3;
         const appsAll = [
             {
                 app: 'Firefox.app',
@@ -80,9 +165,20 @@ function locateFirefox(allowFallbackOrDeps, depsMaybe) {
             const userPath = `${userBase}/${app}/Contents/MacOS/${exec}`;
             if (f.existsSync(userPath)) return userPath;
         }
+        if (!deps) {
+            const viaCache = resolveFromPuppeteerCache();
+            if (viaCache) return viaCache;
+        }
+        const isTestEnv = 'test' === process.env.NODE_ENV || void 0 !== (null == (_process_env2 = process.env) ? void 0 : _process_env2.VITEST) || void 0 !== (null == (_process_env3 = process.env) ? void 0 : _process_env3.JEST_WORKER_ID);
+        const skipCliProbe = isTestEnv && 'darwin' === process.platform;
+        if (allowFallback && !deps && !skipCliProbe) {
+            const viaCLI = resolveFromPuppeteerBrowsersCLI();
+            if (viaCLI) return viaCLI;
+        }
         return null;
     }
     {
+        var _process_env4, _process_env5;
         const prefixes = [
             env.LOCALAPPDATA,
             env.PROGRAMFILES,
@@ -113,7 +209,156 @@ function locateFirefox(allowFallbackOrDeps, depsMaybe) {
         ];
         const defaultPaths = allowFallback ? defaultPathsAll : defaultPathsAll.slice(0, 2);
         for (const defaultPath of defaultPaths)if (f.existsSync(defaultPath)) return defaultPath;
+        if (!deps) {
+            const viaCache = resolveFromPuppeteerCache();
+            if (viaCache) return viaCache;
+        }
+        const isTestEnv = 'test' === process.env.NODE_ENV || void 0 !== (null == (_process_env4 = process.env) ? void 0 : _process_env4.VITEST) || void 0 !== (null == (_process_env5 = process.env) ? void 0 : _process_env5.JEST_WORKER_ID);
+        const skipCliProbe = isTestEnv && 'darwin' === process.platform;
+        if (allowFallback && !deps && !skipCliProbe) {
+            const viaCLI = resolveFromPuppeteerBrowsersCLI();
+            if (viaCLI) return viaCLI;
+        }
+        return null;
+    }
+}
+function getInstallGuidance() {
+    return "We couldn't find a Firefox browser on this machine.\n\nHere's the fastest way to get set up:\n\n1) Install Firefox via Puppeteer Browsers (recommended for CI/dev)\n   npx @puppeteer/browsers install firefox@stable\n\nThen re-run your command — we will detect it automatically.\n\nAlternatively, install Firefox using your OS package manager and re-run.";
+}
+function locateFirefoxOrExplain(options) {
+    const allowFallback = 'boolean' == typeof options ? options : Boolean(null == options ? void 0 : options.allowFallback);
+    const found = locateFirefox(allowFallback) || locateFirefox(true);
+    if ('string' == typeof found && found) return found;
+    throw new Error(getInstallGuidance());
+}
+function getFirefoxVersion(bin, opts) {
+    if ('win32' === process.platform) {
+        try {
+            const psPath = bin.replace(/'/g, "''");
+            const pv = (0, __WEBPACK_EXTERNAL_MODULE_child_process__.execFileSync)('powershell.exe', [
+                '-NoProfile',
+                '-Command',
+                `(Get-Item -LiteralPath '${psPath}').VersionInfo.ProductVersion`
+            ], {
+                encoding: 'utf8',
+                stdio: [
+                    'ignore',
+                    'pipe',
+                    'ignore'
+                ]
+            }).trim();
+            return normalizeVersion(pv);
+        } catch  {}
+        if (null == opts ? void 0 : opts.allowExec) {
+            const v = tryExec(bin, [
+                '--version'
+            ]);
+            return normalizeVersion(v);
+        }
+        return null;
+    }
+    if ('darwin' === process.platform) {
+        try {
+            const contentsDir = __WEBPACK_EXTERNAL_MODULE_path__["default"].dirname(__WEBPACK_EXTERNAL_MODULE_path__["default"].dirname(bin));
+            const infoPlist = __WEBPACK_EXTERNAL_MODULE_path__["default"].join(contentsDir, 'Info.plist');
+            if (__WEBPACK_EXTERNAL_MODULE_fs__["default"].existsSync(infoPlist)) {
+                const xml = __WEBPACK_EXTERNAL_MODULE_fs__["default"].readFileSync(infoPlist, 'utf8');
+                const v = parsePlistString(xml, 'CFBundleShortVersionString') || parsePlistString(xml, 'CFBundleVersion') || '';
+                return normalizeVersion(v);
+            }
+        } catch  {}
+        if (null == opts ? void 0 : opts.allowExec) {
+            const v = tryExec(bin, [
+                '--version'
+            ]);
+            return normalizeVersion(v);
+        }
         return null;
     }
+    if (null == opts ? void 0 : opts.allowExec) {
+        const v = tryExec(bin, [
+            '--version'
+        ]);
+        return normalizeVersion(v);
+    }
+    return null;
+}
+function normalizeVersion(s) {
+    if (!s) return null;
+    const m = String(s).match(/(\d+(?:\.\d+){1,3})/);
+    return m ? m[1] : null;
+}
+function parsePlistString(xml, key) {
+    const re = new RegExp(`<key>${key}<\\/key>\\s*<string>([^<]+)<\\/string>`);
+    const m = xml.match(re);
+    return m ? m[1].trim() : null;
+}
+function tryExec(bin, args) {
+    try {
+        return (0, __WEBPACK_EXTERNAL_MODULE_child_process__.execFileSync)(bin, args, {
+            encoding: 'utf8',
+            stdio: [
+                'ignore',
+                'pipe',
+                'ignore'
+            ]
+        }).trim();
+    } catch  {
+        return null;
+    }
+}
+function resolveFromPuppeteerBrowsersCLI() {
+    try {
+        const attempts = [
+            {
+                cmd: 'npx',
+                args: [
+                    '-y',
+                    '@puppeteer/browsers',
+                    'path',
+                    'firefox@stable'
+                ]
+            },
+            {
+                cmd: 'pnpm',
+                args: [
+                    'dlx',
+                    '@puppeteer/browsers',
+                    'path',
+                    'firefox@stable'
+                ]
+            },
+            {
+                cmd: 'yarn',
+                args: [
+                    'dlx',
+                    '@puppeteer/browsers',
+                    'path',
+                    'firefox@stable'
+                ]
+            },
+            {
+                cmd: 'bunx',
+                args: [
+                    '@puppeteer/browsers',
+                    'path',
+                    'firefox@stable'
+                ]
+            }
+        ];
+        for (const { cmd, args } of attempts)try {
+            const out = (0, __WEBPACK_EXTERNAL_MODULE_child_process__.execFileSync)(cmd, args, {
+                encoding: 'utf8',
+                stdio: [
+                    'ignore',
+                    'pipe',
+                    'ignore'
+                ],
+                timeout: 2000
+            }).trim();
+            if (out && __WEBPACK_EXTERNAL_MODULE_fs__["default"].existsSync(out)) return out;
+        } catch  {}
+    } catch  {}
+    return null;
 }
-export { locateFirefox as default };
+export { locateFirefox as default, getFirefoxVersion, getInstallGuidance, locateFirefoxOrExplain };

package/dist/resolve-puppeteer-cache.d.ts

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+type FsLike = Pick<typeof fs, 'existsSync' | 'readdirSync'>;
+type EnvLike = NodeJS.ProcessEnv;
+export declare function resolveFromPuppeteerCache(deps?: {
+    fs?: FsLike;
+    env?: EnvLike;
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+    localAppData?: string;
+}): string | null;
+export {};

package/package.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/cezaraugusto/firefox-location2.git"
   },
   "name": "firefox-location2",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Approximates the current location of the Firefox browser across platforms.",
   "homepage": "https://www.npmjs.com/package/firefox-location2",
   "type": "module",
@@ -26,13 +26,17 @@
   },
   "scripts": {
     "build": "rslib build",
-    "check": "biome check --write",
+    "check": "pnpm dlx @biomejs/biome@1.9.4 check --write",
     "dev": "rslib build --watch",
-    "format": "biome format --write",
-    "test": "vitest run",
+    "format": "pnpm dlx @biomejs/biome@1.9.4 format --write",
+    "test": "vitest run --pool vmForks --poolOptions.vmForks.singleFork",
     "prepublishOnly": "npm run build",
     "publish:provenance": "np patch --no-tests --any-branch --yolo --message 'release: %s' --provenance"
   },
+  "engines": {
+    "node": ">=18 <23"
+  },
+  "engineStrict": true,
   "publishConfig": {
     "provenance": true
   },