extension 3.7.0 → 3.8.0

package/README.md

@@ -137,6 +137,45 @@ npx extension@latest dev --chromium-binary "/Applications/Google Chrome.app/Cont
 npx extension@latest dev --gecko-binary "/Applications/Firefox.app/Contents/MacOS/firefox"
 ```
 
+### Managed browser binaries
+
+Use Extension.js commands to install/remove managed browser binaries:
+
+```bash
+# Install into Extension.js managed cache
+npx extension@latest install --browser=chromium
+npx extension@latest install --browser=firefox
+
+# Show managed cache root
+npx extension@latest install --where
+
+# Show managed path for a specific browser
+npx extension@latest install --where --browser=firefox
+
+# Remove one browser binary
+npx extension@latest uninstall chromium
+
+# Remove all managed browser binaries
+npx extension@latest uninstall --all
+
+# Show managed cache root
+npx extension@latest uninstall --where
+
+# Show managed path(s) for target browser(s)
+npx extension@latest uninstall --where --browser=chromium
+```
+
+`uninstall` only removes binaries from the Extension.js managed cache root (or `EXT_BROWSERS_CACHE_DIR` when set). It does not remove browser installations that were installed elsewhere (for example, system browsers or custom paths outside the managed cache).
+
+`edge` note for Linux: Playwright channel installs may require a privileged interactive session (`sudo` prompt). If channel install cannot proceed but a system Edge binary is already present, Extension.js will use that existing binary. Otherwise, install Edge system-wide first and then run Extension.js with `--browser=edge` (or use `chromium`).
+
+Default managed cache locations are stable and human-readable:
+- macOS: `~/Library/Caches/extension.js/browsers`
+- Linux: `~/.cache/extension.js/browsers` (or `$XDG_CACHE_HOME/extension.js/browsers`)
+- Windows: `%LOCALAPPDATA%\\extension.js\\browsers`
+
+If you want a custom path, set `EXT_BROWSERS_CACHE_DIR` to a clean location (for example, `EXT_BROWSERS_CACHE_DIR=/tmp/extension.js/browsers-dev`).
+
 ## Sponsors
 
 <div align="center">

package/dist/cli-lib/messages.d.ts

@@ -13,6 +13,8 @@ export declare const commandDescriptions: {
     readonly start: "Builds and starts the extension in production mode";
     readonly preview: "Previews the extension in production mode without building";
     readonly build: "Builds the extension for packaging/distribution";
+    readonly install: "Installs a managed browser binary into Extension.js cache";
+    readonly uninstall: "Removes managed browser binaries from Extension.js cache";
 };
 export declare function unhandledError(err: unknown): string;
 export declare function updateFailed(err: any): string;
@@ -33,7 +35,7 @@ export declare function programAIHelp(): string;
 export type ProgramAIHelpJSON = {
     version: string;
     commands: Array<{
-        name: 'create' | 'dev' | 'start' | 'preview' | 'build';
+        name: 'create' | 'dev' | 'start' | 'preview' | 'build' | 'install' | 'uninstall';
         summary: string;
         supportsSourceInspection: boolean;
     }>;

package/dist/cli.cjs

@@ -85,7 +85,9 @@ var __webpack_exports__ = {};
         dev: 'Starts the development server with hot reloading',
         start: 'Builds and starts the extension in production mode',
         preview: 'Previews the extension in production mode without building',
-        build: 'Builds the extension for packaging/distribution'
+        build: 'Builds the extension for packaging/distribution',
+        install: 'Installs a managed browser binary into Extension.js cache',
+        uninstall: 'Removes managed browser binaries from Extension.js cache'
     };
     function unhandledError(err) {
         const message = err instanceof Error ? err.stack || err.message : 'string' == typeof err ? err : fmt.truncate(err);
@@ -129,6 +131,18 @@ Available Commands
 - ${code('extension build ' + messages_arg('[project-path|remote-url]'))}
   ${commandDescriptions.build}
 
+- ${code('extension install ' + messages_arg('--browser <chrome|chromium|edge|firefox|chromium-based|gecko-based|firefox-based|all>'))}
+  ${commandDescriptions.install}
+
+- ${code('extension install --where')}
+  Prints the managed browser cache root (or browser install path(s) when --browser is provided)
+
+- ${code('extension uninstall ' + messages_arg('<chrome|chromium|edge|firefox> | --all'))}
+  ${commandDescriptions.uninstall}
+
+- ${code('extension uninstall --where')}
+  Prints the managed browser cache root (or browser install path(s) when --browser/--all is provided)
+
 Common Options
 - ${code('--browser')} ${messages_arg('<chrome|edge|firefox|chromium|chromium-based|gecko-based|firefox-based>')} Target browser/engine (default: chromium)
 - ${code('--profile')} ${messages_arg('<path|boolean>')}        Browser profile configuration
@@ -376,6 +390,16 @@ Cross-Browser Compatibility
                     name: 'build',
                     summary: commandDescriptions.build,
                     supportsSourceInspection: false
+                },
+                {
+                    name: 'install',
+                    summary: commandDescriptions.install,
+                    supportsSourceInspection: false
+                },
+                {
+                    name: 'uninstall',
+                    summary: commandDescriptions.uninstall,
+                    supportsSourceInspection: false
                 }
             ],
             globalOptions: [
@@ -406,7 +430,9 @@ Cross-Browser Compatibility
                         'start',
                         'preview',
                         'build',
-                        'create'
+                        'create',
+                        'install',
+                        'uninstall'
                     ],
                     notes: [
                         '--source supports URL fallback to --starting-url or https://example.com',
@@ -443,7 +469,11 @@ Cross-Browser Compatibility
                 'extension --ai-help',
                 'extension --ai-help --format json',
                 'extension dev ./my-ext --source https://example.com --source-format json',
-                'extension dev ./my-ext --logs=info --log-format=json'
+                'extension dev ./my-ext --logs=info --log-format=json',
+                'extension install chromium',
+                'extension install --where',
+                'extension uninstall --where',
+                'extension uninstall --all'
             ]
         };
     }
@@ -1316,6 +1346,125 @@ Cross-Browser Compatibility
             });
         });
     }
+    function resolveManagedBrowsersCacheRoot() {
+        const explicit = String(process.env.EXT_BROWSERS_CACHE_DIR || '').trim();
+        if (explicit) return external_node_path_default().resolve(explicit);
+        const isWin = 'win32' === process.platform;
+        const isMac = 'darwin' === process.platform;
+        if (isWin) {
+            const local = String(process.env.LOCALAPPDATA || '').trim();
+            if (local) return external_node_path_default().join(local, 'extension.js', 'browsers');
+            const userProfile = String(process.env.USERPROFILE || '').trim();
+            if (userProfile) return external_node_path_default().join(userProfile, 'AppData', 'Local', 'extension.js', 'browsers');
+            return external_node_path_default().resolve(process.cwd(), '.cache', 'extension.js', 'browsers');
+        }
+        if (isMac) {
+            const home = String(process.env.HOME || '').trim();
+            if (home) return external_node_path_default().join(home, 'Library', 'Caches', 'extension.js', 'browsers');
+            return external_node_path_default().resolve(process.cwd(), '.cache', 'extension.js', 'browsers');
+        }
+        const xdg = String(process.env.XDG_CACHE_HOME || '').trim();
+        if (xdg) return external_node_path_default().join(xdg, 'extension.js', 'browsers');
+        const home = String(process.env.HOME || '').trim();
+        if (home) return external_node_path_default().join(home, '.cache', 'extension.js', 'browsers');
+        return external_node_path_default().resolve(process.cwd(), '.cache', 'extension.js', 'browsers');
+    }
+    function normalizeInstallVendor(vendor) {
+        const value = String(vendor).trim().toLowerCase();
+        if ('chromium-based' === value) return 'chromium';
+        if ('gecko-based' === value || 'firefox-based' === value) return 'firefox';
+        if ('chrome' === value || 'chromium' === value || 'edge' === value || 'firefox' === value) return value;
+        return 'chromium';
+    }
+    function registerInstallCommand(program, telemetry) {
+        program.command('install').arguments('[browser-name]').usage('install [browser-name] [--browser <name>] [--where]').description(commandDescriptions.install).option('--browser <chrome | chromium | edge | firefox | chromium-based | gecko-based | firefox-based | all>', 'specify browser(s) to install. Supports comma-separated values and `all`.').option('--where', 'print the resolved managed browser cache root').action(async function(browserArg, options) {
+            const startedAt = Date.now();
+            const selectedBrowser = options.browser || browserArg || 'chromium';
+            const browserList = vendors(selectedBrowser);
+            validateVendorsOrExit(browserList, (invalid, supported)=>{
+                console.error(unsupportedBrowserFlag(invalid, supported));
+            });
+            telemetry.track('cli_command_start', {
+                command: 'install',
+                vendors: browserList,
+                where: Boolean(options.where)
+            });
+            try {
+                if (options.where) {
+                    const root = resolveManagedBrowsersCacheRoot();
+                    if (options.browser || browserArg) for (const browser of browserList)console.log(external_node_path_default().join(root, normalizeInstallVendor(browser)));
+                    else console.log(root);
+                } else {
+                    const { extensionInstall } = await import("extension-install");
+                    for (const browser of browserList)await extensionInstall({
+                        browser
+                    });
+                }
+                telemetry.track('cli_command_finish', {
+                    command: 'install',
+                    duration_ms: Date.now() - startedAt,
+                    success: true,
+                    exit_code: 0
+                });
+            } catch (err) {
+                telemetry.track('cli_command_finish', {
+                    command: 'install',
+                    duration_ms: Date.now() - startedAt,
+                    success: false,
+                    exit_code: 1
+                });
+                throw err;
+            }
+        });
+        program.command('uninstall').usage('uninstall <browser-name> | uninstall --all | uninstall --where').description(commandDescriptions.uninstall).option('--browser <browser-name>', 'browser to uninstall').option('--all', 'remove all managed browser binaries').option('--where', 'print the resolved managed browser cache root').argument('[browser-name]').action(async function(browserArg, { browser, all, where }) {
+            const startedAt = Date.now();
+            const target = browserArg || browser;
+            telemetry.track('cli_command_start', {
+                command: 'uninstall',
+                browser: target,
+                all: Boolean(all),
+                where: Boolean(where)
+            });
+            try {
+                if (where) {
+                    const root = resolveManagedBrowsersCacheRoot();
+                    if (all) for (const browser of [
+                        'chrome',
+                        'chromium',
+                        'edge',
+                        'firefox'
+                    ])console.log(external_node_path_default().join(root, browser));
+                    else if (target) {
+                        const list = vendors(target);
+                        validateVendorsOrExit(list, (invalid, supported)=>{
+                            console.error(unsupportedBrowserFlag(invalid, supported));
+                        });
+                        for (const browser of list)console.log(external_node_path_default().join(root, normalizeInstallVendor(browser)));
+                    } else console.log(root);
+                } else {
+                    const { extensionUninstall } = await import("extension-install");
+                    await extensionUninstall({
+                        browser: target,
+                        all
+                    });
+                }
+                telemetry.track('cli_command_finish', {
+                    command: 'uninstall',
+                    duration_ms: Date.now() - startedAt,
+                    success: true,
+                    exit_code: 0
+                });
+            } catch (err) {
+                telemetry.track('cli_command_finish', {
+                    command: 'uninstall',
+                    duration_ms: Date.now() - startedAt,
+                    success: false,
+                    exit_code: 1
+                });
+                throw err;
+            }
+        });
+    }
     const cliPackageJson = getCliPackageJson();
     function developVersion() {
         try {
@@ -1345,6 +1494,7 @@ Cross-Browser Compatibility
     registerStartCommand(extensionJs, telemetry_cli_telemetry);
     registerPreviewCommand(extensionJs, telemetry_cli_telemetry);
     registerBuildCommand(extensionJs, telemetry_cli_telemetry);
+    registerInstallCommand(extensionJs, telemetry_cli_telemetry);
     extensionJs.on('option:ai-help', function() {
         const format = resolveAIHelpFormatFromArgv(process.argv).trim().toLowerCase();
         if ('json' === format) {

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerInstallCommand(program: Command, telemetry: any): void;

package/package.json

@@ -33,7 +33,7 @@
     "extension": "./bin/extension.cjs"
   },
   "name": "extension",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Create cross-browser extensions with no build configuration.",
   "homepage": "https://extension.js.org/",
   "bugs": {
@@ -90,8 +90,9 @@
     "@types/chrome": "^0.1.33",
     "@types/node": "^25.2.0",
     "@types/webextension-polyfill": "0.12.4",
-    "extension-create": "^3.7.0",
-    "extension-develop": "^3.7.0",
+    "extension-create": "3.8.0",
+    "extension-develop": "3.8.0",
+    "extension-install": "3.8.0",
     "commander": "^14.0.3",
     "pintor": "0.3.0",
     "semver": "^7.7.3",