firefox-location2 2.0.0 → 2.0.4

package/README.md

@@ -11,13 +11,19 @@
 
 <img alt="Firefox" align="right" src="https://cdn.jsdelivr.net/gh/extension-js/media@db5deb23fbfa85530f8146718812972998e13a4d/browser_logos/svg/firefox.svg" width="10.5%" />
 
-* Finds Firefox in the following channel order: `stable` / `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
 
-This table lists the default locations where Firefox is typically installed for each supported platform and channel. The package checks these paths (in order) and returns the first one found. 
+This table lists the default locations where Firefox is typically installed for each supported platform and channel. By default, only the Stable channel is checked. When fallback is enabled, the package checks these paths (in order) and returns the first one found.
 
 <table>
   <thead>
@@ -153,28 +159,91 @@ This table lists the default locations where Firefox is typically installed for
   </tbody>
 </table>
 
-Returns the first existing path found, or <code>null</code> if none are found.
+Returns the first existing path found (given selected channels), or <code>null</code> if none are found.
 
 Note: On Linux, the module first tries to resolve binaries on <code>$PATH</code> (using <code>which</code>) for the common channels listed above, then falls back to checking common filesystem locations like <code>/usr/bin/firefox</code>, <code>/usr/local/bin/firefox</code>, <code>/snap/bin/firefox</code>, and <code>/opt/firefox/firefox</code>.
 
 ## Usage
 
-**Via Node.js:**
+**Via Node.js (strict by default):**
 
 ```js
-import firefoxLocation from "firefox-location2";
+import firefoxLocation from 'firefox-location2'
+
+// Strict (Stable only)
+console.log(firefoxLocation())
+// => "/Applications/Firefox.app/Contents/MacOS/firefox" or null
+
+// Enable fallback (Stable / ESR / Developer Edition / Nightly)
+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)
+} 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))
 
-console.log(firefoxLocation());
-// /Applications/Firefox.app/Contents/MacOS/firefox
+// 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:**
 
 ```bash
 npx firefox-location2
-# /Applications/Firefox.app/Contents/MacOS/firefox
+# Strict (Stable only)
+
+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.
+
 ## Planned enhancements
 
 - Flatpak detection on Linux: detect installed Flatpak app <code>org.mozilla.firefox</code> and expose the appropriate invocation.
@@ -184,12 +253,12 @@ npx firefox-location2
 
 ## Related projects
 
-* [chrome-location2](https://github.com/hughsk/chrome-location2)
-* [edge-location](https://github.com/cezaraugusto/edge-location)
-* [firefox-location](https://github.com/hughsk/firefox-location)
-* [brave-location](https://github.com/cezaraugusto/brave-location)
-* [vivaldi-location](https://github.com/jandrey/vivaldi-location)
-* [opera-location](https://github.com/jandrey/opera-location)
+- [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,6 +1,26 @@
 #!/usr/bin/env node
 
-const locateFirefox =
-  require('./dist/index.cjs').default || require('./dist/index.cjs');
+import locateFirefox, {
+  locateFirefoxOrExplain,
+  getInstallGuidance,
+} from './dist/index.js';
 
-console.log(locateFirefox());
+const argv = process.argv.slice(2);
+const allowFallback = argv.includes('--fallback') || argv.includes('-f');
+
+try {
+  const result =
+    typeof locateFirefoxOrExplain === 'function'
+      ? locateFirefoxOrExplain({ allowFallback })
+      : locateFirefox(allowFallback);
+
+  if (!result)
+    throw new Error(
+      (typeof getInstallGuidance === 'function' && getInstallGuidance()) ||
+        'No suitable Firefox binary found.',
+    );
+  console.log(String(result));
+} catch (e) {
+  console.error(String(e));
+  process.exit(1);
+}

package/dist/index.cjs

@@ -33,7 +33,9 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    default: ()=>locateFirefox
+    getInstallGuidance: ()=>getInstallGuidance,
+    default: ()=>locateFirefox,
+    locateFirefoxOrExplain: ()=>locateFirefoxOrExplain
 });
 const external_fs_namespaceObject = require("fs");
 var external_fs_default = /*#__PURE__*/ __webpack_require__.n(external_fs_namespaceObject);
@@ -43,45 +45,143 @@ 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);
-function locateFirefox(deps) {
+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;
+    const deps = isBoolean ? depsMaybe : allowFallbackOrDeps;
     const f = (null == deps ? void 0 : deps.fs) ?? external_fs_default();
     const w = (null == deps ? void 0 : deps.which) ?? external_which_default();
     const o = (null == deps ? void 0 : deps.os) ?? external_os_default();
     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) {
-        const candidates = [
-            'firefox',
+        var _process_env, _process_env1;
+        const stable = [
+            'firefox'
+        ];
+        const fallbacks = [
             'firefox-esr',
             'firefox-developer-edition',
             'firefox-devedition',
             'firefox-nightly'
         ];
+        const candidates = allowFallback ? [
+            ...stable,
+            ...fallbacks
+        ] : stable;
         for (const cmd of candidates)try {
             const resolved = w.sync(cmd);
             if (resolved) return resolved;
         } catch (_) {}
-        const linuxPaths = [
-            '/usr/bin/firefox',
-            '/usr/local/bin/firefox',
-            '/usr/lib/firefox/firefox',
-            '/snap/bin/firefox',
-            '/opt/firefox/firefox',
-            '/usr/local/firefox/firefox',
-            p.join(o.homedir(), 'bin', 'firefox'),
-            p.join(o.homedir(), 'Downloads', 'firefox', 'firefox'),
-            p.join(o.homedir(), '.local', 'share', 'flatpak', 'exports', 'bin', 'org.mozilla.firefox'),
-            '/var/lib/flatpak/exports/bin/org.mozilla.firefox'
-        ];
-        for (const linuxPath of linuxPaths)if (f.existsSync(linuxPath)) return linuxPath;
+        if (allowFallback) {
+            const linuxPaths = [
+                '/usr/bin/firefox',
+                '/usr/local/bin/firefox',
+                '/usr/lib/firefox/firefox',
+                '/snap/bin/firefox',
+                '/opt/firefox/firefox',
+                '/usr/local/firefox/firefox',
+                p.join(o.homedir(), 'bin', 'firefox'),
+                p.join(o.homedir(), 'Downloads', 'firefox', 'firefox'),
+                p.join(o.homedir(), '.local', 'share', 'flatpak', 'exports', 'bin', 'org.mozilla.firefox'),
+                '/var/lib/flatpak/exports/bin/org.mozilla.firefox'
+            ];
+            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) {
-        const apps = [
+        var _process_env2, _process_env3;
+        const appsAll = [
             {
                 app: 'Firefox.app',
                 exec: 'firefox'
@@ -99,6 +199,9 @@ function locateFirefox(deps) {
                 exec: 'firefox'
             }
         ];
+        const apps = allowFallback ? appsAll : [
+            appsAll[0]
+        ];
         const systemBase = '/Applications';
         const userBase = p.join(o.homedir(), 'Applications');
         for (const { app, exec } of apps){
@@ -107,25 +210,39 @@ function locateFirefox(deps) {
             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,
             env['PROGRAMFILES(X86)']
         ].filter(Boolean);
-        const suffixes = [
+        const suffixesAll = [
             p.join('Mozilla Firefox', 'firefox.exe'),
             p.join('Mozilla Firefox ESR', 'firefox.exe'),
             p.join('Mozilla Firefox Developer Edition', 'firefox.exe'),
             p.join('Firefox Nightly', 'firefox.exe')
         ];
+        const suffixes = allowFallback ? suffixesAll : [
+            suffixesAll[0]
+        ];
         for (const prefix of prefixes)for (const suffix of suffixes){
             const exePath = p.join(prefix, suffix);
             if (f.existsSync(exePath)) return exePath;
         }
-        const defaultPaths = [
+        const defaultPathsAll = [
             'C:\\Program Files\\Mozilla Firefox\\firefox.exe',
             'C:\\Program Files (x86)\\Mozilla Firefox\\firefox.exe',
             'C:\\Program Files\\Mozilla Firefox ESR\\firefox.exe',
@@ -135,13 +252,91 @@ function locateFirefox(deps) {
             'C:\\Program Files\\Firefox Nightly\\firefox.exe',
             'C:\\Program Files (x86)\\Firefox Nightly\\firefox.exe'
         ];
+        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 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.getInstallGuidance = __webpack_exports__.getInstallGuidance;
+exports.locateFirefoxOrExplain = __webpack_exports__.locateFirefoxOrExplain;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
-    "default"
+    "default",
+    "getInstallGuidance",
+    "locateFirefoxOrExplain"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/index.d.ts

@@ -16,4 +16,8 @@ export type Deps = {
     env?: NodeJS.ProcessEnv;
     platform?: NodeJS.Platform;
 };
-export default function locateFirefox(deps?: Deps): string | null;
+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;

package/dist/index.js

@@ -2,45 +2,141 @@ 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";
-function locateFirefox(deps) {
+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;
+    const deps = isBoolean ? depsMaybe : allowFallbackOrDeps;
     const f = (null == deps ? void 0 : deps.fs) ?? __WEBPACK_EXTERNAL_MODULE_fs__["default"];
     const w = (null == deps ? void 0 : deps.which) ?? __WEBPACK_EXTERNAL_MODULE_which__["default"];
     const o = (null == deps ? void 0 : deps.os) ?? __WEBPACK_EXTERNAL_MODULE_os__["default"];
     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) {
-        const candidates = [
-            'firefox',
+        var _process_env, _process_env1;
+        const stable = [
+            'firefox'
+        ];
+        const fallbacks = [
             'firefox-esr',
             'firefox-developer-edition',
             'firefox-devedition',
             'firefox-nightly'
         ];
+        const candidates = allowFallback ? [
+            ...stable,
+            ...fallbacks
+        ] : stable;
         for (const cmd of candidates)try {
             const resolved = w.sync(cmd);
             if (resolved) return resolved;
         } catch (_) {}
-        const linuxPaths = [
-            '/usr/bin/firefox',
-            '/usr/local/bin/firefox',
-            '/usr/lib/firefox/firefox',
-            '/snap/bin/firefox',
-            '/opt/firefox/firefox',
-            '/usr/local/firefox/firefox',
-            p.join(o.homedir(), 'bin', 'firefox'),
-            p.join(o.homedir(), 'Downloads', 'firefox', 'firefox'),
-            p.join(o.homedir(), '.local', 'share', 'flatpak', 'exports', 'bin', 'org.mozilla.firefox'),
-            '/var/lib/flatpak/exports/bin/org.mozilla.firefox'
-        ];
-        for (const linuxPath of linuxPaths)if (f.existsSync(linuxPath)) return linuxPath;
+        if (allowFallback) {
+            const linuxPaths = [
+                '/usr/bin/firefox',
+                '/usr/local/bin/firefox',
+                '/usr/lib/firefox/firefox',
+                '/snap/bin/firefox',
+                '/opt/firefox/firefox',
+                '/usr/local/firefox/firefox',
+                p.join(o.homedir(), 'bin', 'firefox'),
+                p.join(o.homedir(), 'Downloads', 'firefox', 'firefox'),
+                p.join(o.homedir(), '.local', 'share', 'flatpak', 'exports', 'bin', 'org.mozilla.firefox'),
+                '/var/lib/flatpak/exports/bin/org.mozilla.firefox'
+            ];
+            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) {
-        const apps = [
+        var _process_env2, _process_env3;
+        const appsAll = [
             {
                 app: 'Firefox.app',
                 exec: 'firefox'
@@ -58,6 +154,9 @@ function locateFirefox(deps) {
                 exec: 'firefox'
             }
         ];
+        const apps = allowFallback ? appsAll : [
+            appsAll[0]
+        ];
         const systemBase = '/Applications';
         const userBase = p.join(o.homedir(), 'Applications');
         for (const { app, exec } of apps){
@@ -66,25 +165,39 @@ function locateFirefox(deps) {
             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,
             env['PROGRAMFILES(X86)']
         ].filter(Boolean);
-        const suffixes = [
+        const suffixesAll = [
             p.join('Mozilla Firefox', 'firefox.exe'),
             p.join('Mozilla Firefox ESR', 'firefox.exe'),
             p.join('Mozilla Firefox Developer Edition', 'firefox.exe'),
             p.join('Firefox Nightly', 'firefox.exe')
         ];
+        const suffixes = allowFallback ? suffixesAll : [
+            suffixesAll[0]
+        ];
         for (const prefix of prefixes)for (const suffix of suffixes){
             const exePath = p.join(prefix, suffix);
             if (f.existsSync(exePath)) return exePath;
         }
-        const defaultPaths = [
+        const defaultPathsAll = [
             'C:\\Program Files\\Mozilla Firefox\\firefox.exe',
             'C:\\Program Files (x86)\\Mozilla Firefox\\firefox.exe',
             'C:\\Program Files\\Mozilla Firefox ESR\\firefox.exe',
@@ -94,8 +207,82 @@ function locateFirefox(deps) {
             'C:\\Program Files\\Firefox Nightly\\firefox.exe',
             'C:\\Program Files (x86)\\Firefox Nightly\\firefox.exe'
         ];
+        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;
     }
 }
-export { locateFirefox as default };
+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 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, 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.0",
+  "version": "2.0.4",
   "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
   },