@itmetsam/samurai-framework 0.4.0 → 0.6.0

package/README.md

@@ -22,14 +22,14 @@ test("Visitor can sign in", async ({ page, env, secrets }) => {
 - **Network control.** Mock, block or modify requests; wait for requests, responses and network idle; read response bodies.
 - **Recorder building blocks.** Specs are parsed into steps and edited back with minimal diffs, and an engine records what a person does in the browser. The UI that ties them together is not built yet (see the [roadmap](docs/roadmap.md)).
 
-> **Status:** early. Firefox only, run from a checkout of this repository (not published to npm yet). See [what is still open](docs/roadmap.md).
+> **Status:** early. Firefox only. See [what is still open](docs/roadmap.md).
 
 ## Getting started
 
 ### 1. Requirements
 
 - [Node.js](https://nodejs.org) 26 or newer and [Bun](https://bun.sh) 1.3 or newer (CI uses these versions)
-- Firefox installed on the machine. It is found in the usual install locations on Linux, macOS and Windows.
+- Firefox, downloaded by the framework: run `npx samurai browsers install firefox` once in a project (`bun run dev browsers install firefox` in this checkout; see [Which browser runs](docs/pages-and-browsers.md#which-browser-runs)). The Firefox installed on the machine is not used.
 
 ### 2. Install
 

package/dist/api.d.ts

@@ -1,4 +1,5 @@
 export { test, describe } from "./runner/registry.js";
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
+export { defineStep, type StepDefinition, type StepResult, type StepRunInput, } from "./flows/steps/index.js";
 export type { TestFixtures } from "./types/test.js";

package/dist/api.js

@@ -1,3 +1,4 @@
 export { test, describe } from "./runner/registry.js";
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
+export { defineStep, } from "./flows/steps/index.js";

package/dist/browser/browser-finder.d.ts

@@ -1,2 +1,3 @@
 import type { SupportedBrowser } from "../types/browser.js";
+/** @deprecated Launches use the builds SAMURAI downloads (`samurai browsers install`); removed in a later major */
 export declare function findBrowser(browserName: SupportedBrowser): string;

package/dist/browser/browser-finder.js

@@ -7,6 +7,7 @@ const macBrowserPaths = {
     // chrome: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
     firefox: "/Applications/Firefox.app/Contents/MacOS/Firefox",
 };
+/** @deprecated Launches use the builds SAMURAI downloads (`samurai browsers install`); removed in a later major */
 export function findBrowser(browserName) {
     logger.verbose("Checking install location for %s", browserName);
     if (!supportedBrowsers.includes(browserName)) {

package/dist/browser/browser.d.ts

@@ -18,6 +18,12 @@ export declare const SESSION_CAPABILITIES: {
         };
     };
 };
+/** session.new got no reply in time */
+export declare class BrowserStartTimeoutError extends Error {
+    constructor(label: string, timeout: number);
+}
+/** Sends session.new with its own, longer timeout; `label` names the browser in the timeout error */
+export declare function startSession(connector: Pick<BiDiConnector, "send">, label: string, commandTimeout: number | undefined): Promise<void>;
 export declare const browserLaunchFlag: (browserName: SupportedBrowser, launchOptions: Partial<BrowserLaunchOptions>) => string[];
 /**
  * Stops what a failed launch started. A browser left running holds the profile (the next launch
@@ -28,6 +34,8 @@ export declare function abandonLaunch(browserProc: {
 }, biDiConnector: {
     kill(): void;
 } | undefined): void;
+/** Env added to a browser's process */
+export declare const browserLaunchEnv: (browserName: SupportedBrowser, appDataPath?: string) => Record<string, string>;
 export interface BrowserLaunchOptions {
     /** Which port to use for the WebDeveloper tools */
     port: number;

package/dist/browser/browser.js

@@ -1,9 +1,10 @@
 import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { findBrowser } from "./browser-finder.js";
+import { projectBrowser } from "../browsers/resolve.js";
 import path from "node:path";
-import { BiDiConnector } from "../transport/bidi-connection.js";
+import { BiDiConnector, DEFAULT_COMMAND_TIMEOUT, } from "../transport/bidi-connection.js";
+import { BiDiError } from "../transport/bidi-error.js";
 import Page from "./page.js";
 import { BrowserContext } from "./browser-context.js";
 import { validateEmulation } from "./emulation.js";
@@ -17,6 +18,27 @@ import { browsersDir, projectDir, readConfig } from "../config/config.js";
 export const SESSION_CAPABILITIES = {
     alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } },
 };
+/** session.new waits at least this long (ms): the first start after an install can take a while (macOS checks the new app) */
+const SESSION_START_TIMEOUT = 120_000;
+/** session.new got no reply in time */
+export class BrowserStartTimeoutError extends Error {
+    constructor(label, timeout) {
+        super(`${label} did not finish starting within ${Math.round(timeout / 1000)}s. The first start after an install can be slow; run again.`);
+        this.name = "BrowserStartTimeoutError";
+    }
+}
+/** Sends session.new with its own, longer timeout; `label` names the browser in the timeout error */
+export async function startSession(connector, label, commandTimeout) {
+    const timeout = Math.max(commandTimeout ?? DEFAULT_COMMAND_TIMEOUT, SESSION_START_TIMEOUT);
+    try {
+        await connector.send("session.new", { capabilities: SESSION_CAPABILITIES }, { timeout });
+    }
+    catch (err) {
+        if (err instanceof BiDiError && err.code === "timeout")
+            throw new BrowserStartTimeoutError(label, timeout);
+        throw err;
+    }
+}
 /** Time (ms) to wait for Firefox to answer browser.close before killing the process */
 const BROWSER_CLOSE_GRACE = 2000;
 const browserProfilePath = (browserName) => path.join(browsersDir(), "profiles", browserName, "user.js");
@@ -70,13 +92,15 @@ export function abandonLaunch(browserProc, biDiConnector) {
 // On macOS a spawned browser is attributed to the terminal, which is denied access to
 // ~/Library/Application Support/Firefox (profiles.ini). Point Firefox at a local app data dir instead.
 const browserAppDataPath = (browserName) => path.join(browsersDir(), "app-data", browserName);
-const browserLaunchEnv = (browserName) => {
-    const appDataPath = browserAppDataPath(browserName);
+/** Env added to a browser's process */
+export const browserLaunchEnv = (browserName, appDataPath = browserAppDataPath(browserName)) => {
     mkdirSync(appDataPath, { recursive: true });
     logger.debug("Using app data dir for %s: %s", browserName, appDataPath);
     switch (browserName) {
         case "firefox":
-            return { MOZ_APP_DATA: appDataPath };
+            // The project profile may have been opened by a newer Firefox (the system one, before 0.6);
+            // without this Firefox refuses to start on it
+            return { MOZ_APP_DATA: appDataPath, MOZ_ALLOW_DOWNGRADE: "1" };
     }
 };
 const browserProfiles = {
@@ -127,7 +151,7 @@ export class Browser {
     signal) {
         signal?.throwIfAborted();
         logger.verbose("Trying to launch browser %s", browserName);
-        const browserLocation = findBrowser(browserName);
+        const { executablePath: browserLocation, label } = await projectBrowser(browserName);
         logger.debug("Found browser install location at: %s", browserLocation);
         ensureBrowserProfile(browserName);
         logger.verbose("Trying to spawn %s process", browserName);
@@ -163,15 +187,12 @@ export class Browser {
                 try {
                     let url = urlMatch[0] + browserWsPath[browserName];
                     logger.verbose("Websocket URL match: %s", url);
-                    biDiConnector = await BiDiConnector.connect(url, {
-                        commandTimeout: await readCommandTimeout(),
-                    });
+                    const commandTimeout = await readCommandTimeout();
+                    biDiConnector = await BiDiConnector.connect(url, { commandTimeout });
                     logger.verbose("Starting new session");
                     const status = await biDiConnector.send("session.status", {});
                     logger.verbose("Session status", status);
-                    await biDiConnector.send("session.new", {
-                        capabilities: SESSION_CAPABILITIES,
-                    });
+                    await startSession(biDiConnector, label, commandTimeout);
                     logger.verbose("Session started successfully");
                     const downloadsDir = await prepareDownloadsDir(biDiConnector, path.resolve(projectDir(), (await readOptionalConfig("downloadsDir")) ?? "result/downloads"));
                     const browser = new Browser({

package/dist/browser/warm-up.d.ts

@@ -0,0 +1,14 @@
+import { type ResolvedBrowser } from "../browsers/resolve.js";
+import type { SupportedBrowser } from "../types/browser.js";
+import { type BrowserLaunchOptions } from "./browser.js";
+/** Written into a managed build's folder once it started there; its first start can be slow (macOS checks the new app) */
+export declare const LAUNCHED_STAMP = ".samurai-launched";
+/**
+ * Starts a managed build once, before its first real use, so that slow first start happens outside a test's
+ * timeout. A browser set by env or config, a stamped build, and an aborted run are skipped.
+ */
+export declare function warmUp(target: ResolvedBrowser, launch: () => Promise<{
+    close(): Promise<void>;
+}>, signal?: AbortSignal): Promise<void>;
+/** Resolves the project's browser (throws when it is missing) and warms a managed build up, headless */
+export declare function ensureWarm(name: SupportedBrowser, launchOptions?: Partial<BrowserLaunchOptions>, signal?: AbortSignal): Promise<void>;

package/dist/browser/warm-up.js

@@ -0,0 +1,37 @@
+import { existsSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { projectBrowser } from "../browsers/resolve.js";
+import logger from "../logger/index.js";
+import { Browser, BrowserStartTimeoutError, } from "./browser.js";
+/** Written into a managed build's folder once it started there; its first start can be slow (macOS checks the new app) */
+export const LAUNCHED_STAMP = ".samurai-launched";
+/**
+ * Starts a managed build once, before its first real use, so that slow first start happens outside a test's
+ * timeout. A browser set by env or config, a stamped build, and an aborted run are skipped.
+ */
+export async function warmUp(target, launch, signal) {
+    if (!target.buildDir)
+        return;
+    const stamp = path.join(target.buildDir, LAUNCHED_STAMP);
+    if (existsSync(stamp) || signal?.aborted)
+        return;
+    logger.verbose("First start of %s", target.label);
+    let browser;
+    try {
+        browser = await launch();
+    }
+    catch (err) {
+        if (signal?.aborted)
+            return;
+        if (err instanceof BrowserStartTimeoutError)
+            throw err;
+        throw new Error(`Could not start ${target.label} for the first time: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    await browser.close();
+    writeFileSync(stamp, new Date().toISOString());
+}
+/** Resolves the project's browser (throws when it is missing) and warms a managed build up, headless */
+export async function ensureWarm(name, launchOptions = {}, signal) {
+    await warmUp(await projectBrowser(name), async () => (await Browser.launch(name, { ...launchOptions, headless: true }, signal))
+        .browser, signal);
+}

package/dist/browsers/cache-dir.d.ts

@@ -0,0 +1,2 @@
+/** Where downloaded browsers live, shared by every project of this user: `SAMURAI_BROWSERS_PATH`, else the OS cache folder */
+export declare function browsersCacheDir(env?: Partial<NodeJS.ProcessEnv>, platform?: NodeJS.Platform, home?: string): string;

package/dist/browsers/cache-dir.js

@@ -0,0 +1,15 @@
+import { homedir } from "node:os";
+import path from "node:path";
+/** Where downloaded browsers live, shared by every project of this user: `SAMURAI_BROWSERS_PATH`, else the OS cache folder */
+export function browsersCacheDir(env = process.env, platform = process.platform, home = homedir()) {
+    if (env.SAMURAI_BROWSERS_PATH)
+        return path.resolve(env.SAMURAI_BROWSERS_PATH);
+    switch (platform) {
+        case "darwin":
+            return path.join(home, "Library", "Caches", "samurai", "browsers");
+        case "win32":
+            return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "samurai", "browsers");
+        default:
+            return path.join(env.XDG_CACHE_HOME || path.join(home, ".cache"), "samurai", "browsers");
+    }
+}

package/dist/browsers/downloader.d.ts

@@ -0,0 +1,23 @@
+/** Written into a build folder once its download and unpack finished; a folder without it is unfinished */
+export declare const COMPLETE_MARKER = ".samurai-complete";
+/** One build folder in the cache, as the downloader names it ("firefox", "chrome", "chromedriver") */
+export interface CachedBuild {
+    browser: string;
+    buildId: string;
+    dir: string;
+}
+/** What the store needs to fetch and find builds; tests pass a fake */
+export interface Downloader {
+    /** undefined: no builds exist for this OS and architecture */
+    platform(): string | undefined;
+    /** The folder a build is, or would be, unpacked into */
+    installDir(cacheDir: string, browser: string, buildId: string): string;
+    executablePath(cacheDir: string, browser: string, buildId: string): string;
+    install(cacheDir: string, browser: string, buildId: string, onProgress?: (done: number, total: number) => void): Promise<void>;
+    uninstall(cacheDir: string, browser: string, buildId: string): void;
+    /** Removes a build's folder (its marker first) and any archive a killed download left behind */
+    clean(cacheDir: string, browser: string, buildId: string): void;
+    list(cacheDir: string): CachedBuild[];
+}
+/** Downloads from Mozilla and Google with @puppeteer/browsers; `baseUrl` (tests only) points it elsewhere */
+export declare function puppeteerDownloader(baseUrl?: string | undefined): Downloader;

package/dist/browsers/downloader.js

@@ -0,0 +1,52 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { Browser as PuppeteerBrowser, Cache, detectBrowserPlatform, install, } from "@puppeteer/browsers";
+/** Written into a build folder once its download and unpack finished; a folder without it is unfinished */
+export const COMPLETE_MARKER = ".samurai-complete";
+/** Downloads from Mozilla and Google with @puppeteer/browsers; `baseUrl` (tests only) points it elsewhere */
+export function puppeteerDownloader(baseUrl = process.env.SAMURAI_BROWSERS_BASE_URL) {
+    const platform = () => {
+        const found = detectBrowserPlatform();
+        if (!found)
+            throw new Error(`No browser downloads for ${process.platform} ${process.arch}`);
+        return found;
+    };
+    const as = (browser) => browser;
+    return {
+        platform: () => detectBrowserPlatform(),
+        installDir: (cacheDir, browser, buildId) => new Cache(cacheDir).installationDir(as(browser), platform(), buildId),
+        executablePath: (cacheDir, browser, buildId) => new Cache(cacheDir).computeExecutablePath({
+            browser: as(browser),
+            platform: platform(),
+            buildId,
+        }),
+        async install(cacheDir, browser, buildId, onProgress) {
+            await install({
+                cacheDir,
+                browser: as(browser),
+                buildId,
+                platform: platform(),
+                ...(onProgress && { downloadProgressCallback: onProgress }),
+                ...(baseUrl && { baseUrl }),
+            });
+        },
+        uninstall: (cacheDir, browser, buildId) => new Cache(cacheDir).uninstall(as(browser), platform(), buildId),
+        clean(cacheDir, browser, buildId) {
+            const cache = new Cache(cacheDir);
+            const dir = cache.installationDir(as(browser), platform(), buildId);
+            // The marker goes first: a removal that stops halfway leaves a folder that reads as missing
+            rmSync(path.join(dir, COMPLETE_MARKER), { force: true });
+            rmSync(dir, { recursive: true, force: true });
+            // The archive is downloaded next to the build folders, as <buildId>-<file>
+            const root = cache.browserRoot(as(browser));
+            if (!existsSync(root))
+                return;
+            for (const entry of readdirSync(root))
+                if (entry.startsWith(`${buildId}-`))
+                    rmSync(path.join(root, entry), { recursive: true, force: true });
+        },
+        list: (cacheDir) => new Cache(cacheDir)
+            .getInstalledBrowsers()
+            .map((b) => ({ browser: b.browser, buildId: b.buildId, dir: b.path })),
+    };
+}

package/dist/browsers/index.d.ts

@@ -0,0 +1,6 @@
+export { browsersCacheDir } from "./cache-dir.js";
+export type { CachedBuild, Downloader } from "./downloader.js";
+export { ENV_PATH, type Override } from "./overrides.js";
+export { LAUNCHABLE, MANAGED_BROWSERS, PINNED, isManagedBrowser, type ManagedBrowser, } from "./pins.js";
+export { browserStatus, projectBrowser, projectExecutable, resolveBrowser, resolveExecutable, type ResolvedBrowser, } from "./resolve.js";
+export { BrowserNotInstalledError, installBrowser, listInstalled, managedBuildDir, managedExecutable, uninstallBrowser, type BrowserStatus, type InstalledBuild, type StoreOptions, } from "./store.js";

package/dist/browsers/index.js

@@ -0,0 +1,5 @@
+export { browsersCacheDir } from "./cache-dir.js";
+export { ENV_PATH } from "./overrides.js";
+export { LAUNCHABLE, MANAGED_BROWSERS, PINNED, isManagedBrowser, } from "./pins.js";
+export { browserStatus, projectBrowser, projectExecutable, resolveBrowser, resolveExecutable, } from "./resolve.js";
+export { BrowserNotInstalledError, installBrowser, listInstalled, managedBuildDir, managedExecutable, uninstallBrowser, } from "./store.js";

package/dist/browsers/overrides.d.ts

@@ -0,0 +1,17 @@
+import type { ManagedBrowser } from "./pins.js";
+/** A browser binary set on purpose, and where */
+export interface Override {
+    path: string;
+    from: "env" | "config";
+}
+/** Where the overrides come from; each defaults to the running process */
+export interface OverrideSources {
+    env?: Partial<NodeJS.ProcessEnv>;
+    /** `browserPaths` of samurai.config.ts */
+    browserPaths?: Partial<Record<ManagedBrowser, string>> | undefined;
+    /** What relative `browserPaths` resolve from */
+    projectDir?: string;
+}
+export declare const ENV_PATH: Record<ManagedBrowser, string>;
+/** The env variable, else the config's `browserPaths`; undefined: use the managed build */
+export declare function overrideOf(name: ManagedBrowser, { env, browserPaths, projectDir, }?: OverrideSources): Override | undefined;

package/dist/browsers/overrides.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+export const ENV_PATH = {
+    firefox: "SAMURAI_FIREFOX_PATH",
+    chrome: "SAMURAI_CHROME_PATH",
+};
+/** The env variable, else the config's `browserPaths`; undefined: use the managed build */
+export function overrideOf(name, { env = process.env, browserPaths, projectDir = process.cwd(), } = {}) {
+    const fromEnv = env[ENV_PATH[name]];
+    if (fromEnv)
+        return { path: path.resolve(fromEnv), from: "env" };
+    const fromConfig = browserPaths?.[name];
+    if (fromConfig)
+        return { path: path.resolve(projectDir, fromConfig), from: "config" };
+    return undefined;
+}

package/dist/browsers/pins.d.ts

@@ -0,0 +1,16 @@
+/** The browser builds this framework version downloads and launches. Bumped by hand in a release */
+export declare const PINNED: {
+    readonly firefox: {
+        readonly buildId: "stable_158.0";
+        readonly label: "Firefox 158.0";
+    };
+    readonly chrome: {
+        readonly buildId: "155.0.8059.79";
+        readonly label: "Chrome for Testing 155.0.8059.79";
+    };
+};
+export type ManagedBrowser = keyof typeof PINNED;
+export declare const MANAGED_BROWSERS: ManagedBrowser[];
+/** The managed browsers the framework can launch; Chrome joins when it can drive it */
+export declare const LAUNCHABLE: readonly ManagedBrowser[];
+export declare function isManagedBrowser(name: string): name is ManagedBrowser;

package/dist/browsers/pins.js

@@ -0,0 +1,14 @@
+/** The browser builds this framework version downloads and launches. Bumped by hand in a release */
+export const PINNED = {
+    firefox: { buildId: "stable_158.0", label: "Firefox 158.0" },
+    chrome: {
+        buildId: "155.0.8059.79",
+        label: "Chrome for Testing 155.0.8059.79",
+    },
+};
+export const MANAGED_BROWSERS = Object.keys(PINNED);
+/** The managed browsers the framework can launch; Chrome joins when it can drive it */
+export const LAUNCHABLE = ["firefox"];
+export function isManagedBrowser(name) {
+    return Object.prototype.hasOwnProperty.call(PINNED, name);
+}

package/dist/browsers/resolve.d.ts

@@ -0,0 +1,26 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+import { type OverrideSources } from "./overrides.js";
+import { type ManagedBrowser } from "./pins.js";
+import { type BrowserStatus, type StoreOptions } from "./store.js";
+/** The browser a launch uses, and how to name it */
+export interface ResolvedBrowser {
+    executablePath: string;
+    /** "Firefox 158.0" for the managed build, else "Firefox" */
+    label: string;
+    /** The managed build's folder; undefined when an env or config path is used instead */
+    buildDir?: string;
+}
+/** The browser a launch uses: the env path, else the config's `browserPaths`, else the pinned build. Never downloads */
+export declare function resolveBrowser(name: ManagedBrowser, sources?: OverrideSources & StoreOptions): ResolvedBrowser;
+/** The binary a launch uses; see `resolveBrowser` */
+export declare function resolveExecutable(name: ManagedBrowser, sources?: OverrideSources & StoreOptions): string;
+/** `resolveExecutable` for the active project */
+export declare function projectExecutable(name: ManagedBrowser): Promise<string>;
+/** `resolveBrowser` for the active project, with its config's `browserPaths` (none when the config can't be read) */
+export declare function projectBrowser(name: ManagedBrowser): Promise<ResolvedBrowser>;
+/** Every pinned browser's status for a project (default: the working directory); a config that can't be read gives no config overrides */
+export declare function browserStatus(options?: StoreOptions & {
+    projectDir?: string;
+    config?: SamuraiTestConfig;
+    env?: Partial<NodeJS.ProcessEnv>;
+}): Promise<BrowserStatus[]>;

package/dist/browsers/resolve.js

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+import { projectConfig, projectDir, readConfig } from "../config/config.js";
+import logger from "../logger/index.js";
+import { ENV_PATH, overrideOf } from "./overrides.js";
+import { MANAGED_BROWSERS, PINNED } from "./pins.js";
+import { managedBuildDir, managedExecutable, statusOf, } from "./store.js";
+/** The browser a launch uses: the env path, else the config's `browserPaths`, else the pinned build. Never downloads */
+export function resolveBrowser(name, sources = {}) {
+    const override = overrideOf(name, sources);
+    if (!override)
+        return {
+            executablePath: managedExecutable(name, sources),
+            label: PINNED[name].label,
+            buildDir: managedBuildDir(name, sources),
+        };
+    if (!existsSync(override.path))
+        throw new Error(override.from === "env"
+            ? `${ENV_PATH[name]} points to a missing file: ${override.path}`
+            : `browserPaths.${name} in samurai.config.ts points to a missing file: ${override.path}`);
+    return {
+        executablePath: override.path,
+        label: name.charAt(0).toUpperCase() + name.slice(1),
+    };
+}
+/** The binary a launch uses; see `resolveBrowser` */
+export function resolveExecutable(name, sources = {}) {
+    return resolveBrowser(name, sources).executablePath;
+}
+/** `resolveExecutable` for the active project */
+export async function projectExecutable(name) {
+    return (await projectBrowser(name)).executablePath;
+}
+/** `resolveBrowser` for the active project, with its config's `browserPaths` (none when the config can't be read) */
+export async function projectBrowser(name) {
+    let browserPaths;
+    try {
+        browserPaths = await readConfig("browserPaths");
+    }
+    catch (err) {
+        logger.debug("Could not read browserPaths from config", { err });
+    }
+    return resolveBrowser(name, { browserPaths, projectDir: projectDir() });
+}
+/** Every pinned browser's status for a project (default: the working directory); a config that can't be read gives no config overrides */
+export async function browserStatus(options = {}) {
+    const dir = options.projectDir ?? process.cwd();
+    let browserPaths;
+    try {
+        browserPaths = (await projectConfig({ ...options, projectDir: dir }))
+            .browserPaths;
+    }
+    catch (err) {
+        logger.debug("Could not read browserPaths from config", { err });
+    }
+    return MANAGED_BROWSERS.map((name) => statusOf(name, { ...options, browserPaths, projectDir: dir }));
+}

package/dist/browsers/store.d.ts

@@ -0,0 +1,52 @@
+import { COMPLETE_MARKER, type Downloader } from "./downloader.js";
+import { type Override, type OverrideSources } from "./overrides.js";
+import { type ManagedBrowser } from "./pins.js";
+export { COMPLETE_MARKER };
+export declare class BrowserNotInstalledError extends Error {
+    readonly browser: ManagedBrowser;
+    readonly label: string;
+    constructor(browser: ManagedBrowser, label: string);
+}
+export interface StoreOptions {
+    /** Default: `browsersCacheDir()` */
+    cacheDir?: string;
+    /** Default: @puppeteer/browsers */
+    downloader?: Downloader;
+}
+export interface BrowserStatus {
+    name: ManagedBrowser;
+    label: string;
+    buildId: string;
+    /** unavailable: no download exists for this OS and architecture */
+    state: "installed" | "missing" | "unavailable";
+    executablePath?: string;
+    /** Whether the framework can launch it yet */
+    launchable: boolean;
+    /** A path set on purpose, which launches use instead of the managed build */
+    override?: Override;
+}
+export interface InstalledBuild {
+    name: ManagedBrowser;
+    buildId: string;
+    dir: string;
+    sizeBytes: number;
+    /** Pinned by this framework version */
+    pinned: boolean;
+}
+/**
+ * Downloads the pinned build unless it is complete already; returns its executable. The download goes into a
+ * private staging folder and is moved into place once complete, so two installs at once do not break each other.
+ */
+export declare function installBrowser(name: ManagedBrowser, options?: StoreOptions & {
+    onProgress?: (done: number, total: number) => void;
+}): Promise<string>;
+/** The pinned build of `name`: whether it is there, and any path set instead of it */
+export declare function statusOf(name: ManagedBrowser, options?: StoreOptions & OverrideSources): BrowserStatus;
+/** The pinned build's executable; throws BrowserNotInstalledError when it isn't complete */
+export declare function managedExecutable(name: ManagedBrowser, options?: StoreOptions): string;
+/** The folder the pinned build of `name` is, or would be, installed in */
+export declare function managedBuildDir(name: ManagedBrowser, options?: StoreOptions): string;
+/** Removes a build (default: the pinned one); Chrome takes its chromedriver along */
+export declare function uninstallBrowser(name: ManagedBrowser, buildId?: string, options?: StoreOptions): void;
+/** Every Firefox and Chrome build in the cache, also those other framework versions pinned */
+export declare function listInstalled(options?: StoreOptions): InstalledBuild[];