headfox-js 0.1.1 → 0.1.12

package/README.md

@@ -79,27 +79,48 @@ const browser = await firefox.connect(server.wsEndpoint());
 
 ## Browser source
 
-By default, `headfox-js` downloads the currently maintained Camoufox-compatible browser bundles.
+By default, `headfox-js` downloads the official Camoufox browser bundles from `daijro/camoufox`.
 
 You can override the release source when you need to test a different fork or future Headfox-native releases:
 
 ```bash
 HEADFOX_JS_RELEASE_REPO=owner/repo
-HEADFOX_JS_ASSET_PREFIXES=headfox,camoufox
+HEADFOX_JS_RELEASE_TAG=v135.0.1-beta.24
 ```
 
 Useful env vars:
 
 - `HEADFOX_JS_RELEASE_REPO`
+- `HEADFOX_JS_RELEASE_TAG`
+- `HEADFOX_JS_ASSET_NAME`
 - `HEADFOX_JS_ASSET_PREFIXES`
 - `HEADFOX_JS_CACHE_DIR`
 
 Legacy compatibility env vars are still accepted:
 
 - `CAMOUFOX_JS_RELEASE_REPO`
+- `CAMOUFOX_JS_RELEASE_TAG`
+- `CAMOUFOX_JS_ASSET_NAME`
 - `CAMOUFOX_JS_ASSET_PREFIXES`
 - `CAMOUFOX_JS_CACHE_DIR`
 
+For deterministic installs in Docker or CI, pin a known tag and let `headfox-js` pick the matching platform asset:
+
+```bash
+HEADFOX_JS_RELEASE_REPO=daijro/camoufox
+HEADFOX_JS_RELEASE_TAG=v135.0.1-beta.24
+npx headfox-js fetch
+```
+
+If you need a custom fork with irregular asset names, set both the tag and exact asset name:
+
+```bash
+HEADFOX_JS_RELEASE_REPO=CloverLabsAI/camoufox
+HEADFOX_JS_RELEASE_TAG=webrtc-ip-by-context
+HEADFOX_JS_ASSET_NAME=roverfox-webrtc-fix.zip
+npx headfox-js fetch
+```
+
 ## Optional WebGL data support
 
 For best fingerprint fidelity, `headfox-js` will use the bundled WebGL sampling database when the optional SQLite dependency is available.

package/dist/pkgman.d.ts

@@ -1,11 +1,21 @@
 import type { PathLike } from "node:fs";
 import type { Writable } from "node:stream";
 export declare const OS_NAME: "mac" | "win" | "lin";
+export declare const DEFAULT_RELEASE_REPO = "daijro/camoufox";
+export declare function resolveReleaseRepo(): string;
+export declare function resolveReleaseTag(): string | undefined;
+export declare function resolveAssetName(): string | undefined;
+export declare function resolveAssetPrefixes(): string[];
 export declare const INSTALL_DIR: string;
 export declare const LOCAL_DATA: PathLike;
 export declare const OS_ARCH_MATRIX: {
     [key: string]: string[];
 };
+export declare function buildAssetPattern(prefixes: string[], osName: "mac" | "win" | "lin", arch: string): RegExp;
+export declare function parseVersionParts(...sources: Array<string | undefined | null>): {
+    version: string;
+    release: string;
+} | null;
 declare class Version {
     release: string;
     version?: string;
@@ -20,11 +30,21 @@ declare class Version {
     static isSupportedPath(path: PathLike): boolean;
     static buildMinMax(): [Version, Version];
 }
+type GitHubAsset = {
+    name: string;
+    browser_download_url: string;
+};
+type GitHubRelease = {
+    name?: string;
+    tag_name?: string;
+    assets: GitHubAsset[];
+};
 export declare class GitHubDownloader {
     githubRepo: string;
     apiUrl: string;
-    constructor(githubRepo: string);
-    checkAsset(asset: any): any;
+    releaseTag?: string;
+    constructor(githubRepo: string, releaseTag?: string);
+    checkAsset(asset: GitHubAsset, _release: GitHubRelease): any;
     missingAssetError(): void;
     getAsset({ retries }?: {
         retries: number;
@@ -35,9 +55,10 @@ export declare class HeadfoxFetcher extends GitHubDownloader {
     _version_obj?: Version;
     pattern: RegExp;
     _url?: string;
+    assetNameOverride?: string;
     constructor();
     init(): Promise<void>;
-    checkAsset(asset: any): [Version, string] | null;
+    checkAsset(asset: GitHubAsset, release: GitHubRelease): [Version, string] | null;
     missingAssetError(): void;
     static getPlatformArch(): string;
     fetchLatest(): Promise<void>;

package/dist/pkgman.js

@@ -24,18 +24,33 @@ if (!(process.platform in OS_MAP)) {
     throw new UnsupportedOS(`OS ${process.platform} is not supported`);
 }
 export const OS_NAME = OS_MAP[process.platform];
-const RELEASE_REPO = process.env.HEADFOX_JS_RELEASE_REPO ??
-    process.env.CAMOUFOX_JS_RELEASE_REPO ??
-    "CloverLabsAI/camoufox";
-const CACHE_DIR_NAME = process.env.HEADFOX_JS_CACHE_DIR ??
-    process.env.CAMOUFOX_JS_CACHE_DIR ??
-    "headfox";
-const ASSET_PREFIXES = Array.from(new Set((process.env.HEADFOX_JS_ASSET_PREFIXES ??
-    process.env.CAMOUFOX_JS_ASSET_PREFIXES ??
-    "camoufox,headfox")
-    .split(",")
-    .map((value) => value.trim())
-    .filter(Boolean)));
+export const DEFAULT_RELEASE_REPO = "daijro/camoufox";
+function readEnvValue(...names) {
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function resolveReleaseRepo() {
+    return (readEnvValue("HEADFOX_JS_RELEASE_REPO", "CAMOUFOX_JS_RELEASE_REPO") ??
+        DEFAULT_RELEASE_REPO);
+}
+export function resolveReleaseTag() {
+    return readEnvValue("HEADFOX_JS_RELEASE_TAG", "CAMOUFOX_JS_RELEASE_TAG");
+}
+export function resolveAssetName() {
+    return readEnvValue("HEADFOX_JS_ASSET_NAME", "CAMOUFOX_JS_ASSET_NAME");
+}
+export function resolveAssetPrefixes() {
+    return Array.from(new Set((readEnvValue("HEADFOX_JS_ASSET_PREFIXES", "CAMOUFOX_JS_ASSET_PREFIXES") ?? "camoufox,headfox")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean)));
+}
+const CACHE_DIR_NAME = readEnvValue("HEADFOX_JS_CACHE_DIR", "CAMOUFOX_JS_CACHE_DIR") ?? "headfox";
 const APP_BUNDLE_CANDIDATES = ["Headfox.app", "Camoufox.app"];
 const currentDir = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
 export const INSTALL_DIR = userCacheDir(CACHE_DIR_NAME);
@@ -51,6 +66,28 @@ const LAUNCH_FILE_CANDIDATES = {
     mac: ["../MacOS/headfox", "../MacOS/camoufox"],
     lin: ["headfox-bin", "camoufox-bin"],
 };
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function buildAssetPattern(prefixes, osName, arch) {
+    return new RegExp(`(?:${prefixes.map(escapeRegex).join("|")})-(.+)-(.+)-${escapeRegex(osName)}\\.${escapeRegex(arch)}\\.zip$`, "i");
+}
+export function parseVersionParts(...sources) {
+    const pattern = /(\d+(?:\.\d+){0,2})-((?:alpha|beta|rc)\.\d+)/i;
+    for (const source of sources) {
+        if (!source) {
+            continue;
+        }
+        const match = source.match(pattern);
+        if (match) {
+            return {
+                version: match[1],
+                release: match[2].toLowerCase(),
+            };
+        }
+    }
+    return null;
+}
 function installMissingMessage(product = "Headfox") {
     return `${product} is not installed at ${INSTALL_DIR}. Please run \`headfox-js fetch\` to install.`;
 }
@@ -139,11 +176,15 @@ const [VERSION_MIN, VERSION_MAX] = Version.buildMinMax();
 export class GitHubDownloader {
     githubRepo;
     apiUrl;
-    constructor(githubRepo) {
+    releaseTag;
+    constructor(githubRepo, releaseTag) {
         this.githubRepo = githubRepo;
-        this.apiUrl = `https://api.github.com/repos/${githubRepo}/releases`;
+        this.releaseTag = releaseTag;
+        this.apiUrl = releaseTag
+            ? `https://api.github.com/repos/${githubRepo}/releases/tags/${encodeURIComponent(releaseTag)}`
+            : `https://api.github.com/repos/${githubRepo}/releases`;
     }
-    checkAsset(asset) {
+    checkAsset(asset, _release) {
         return asset.browser_download_url;
     }
     missingAssetError() {
@@ -167,10 +208,13 @@ export class GitHubDownloader {
         if (!response || !response.ok) {
             throw new Error(`Failed to fetch releases from ${this.apiUrl} after ${retries} attempts`);
         }
-        const releases = await response.json();
+        const releaseData = await response.json();
+        const releases = Array.isArray(releaseData)
+            ? releaseData
+            : [releaseData];
         for (const release of releases) {
             for (const asset of release.assets) {
-                const data = this.checkAsset(asset);
+                const data = this.checkAsset(asset, release);
                 if (data) {
                     return data;
                 }
@@ -184,25 +228,47 @@ export class HeadfoxFetcher extends GitHubDownloader {
     _version_obj;
     pattern;
     _url;
+    assetNameOverride;
     constructor() {
-        super(RELEASE_REPO);
+        super(resolveReleaseRepo(), resolveReleaseTag());
         this.arch = HeadfoxFetcher.getPlatformArch();
-        this.pattern = new RegExp(`(?:${ASSET_PREFIXES.join("|")})-(.+)-(.+)-${OS_NAME}\\.${this.arch}\\.zip`);
+        this.assetNameOverride = resolveAssetName();
+        this.pattern = buildAssetPattern(resolveAssetPrefixes(), OS_NAME, this.arch);
     }
     async init() {
         await this.fetchLatest();
     }
-    checkAsset(asset) {
-        const match = asset.name.match(this.pattern);
-        if (!match)
+    checkAsset(asset, release) {
+        if (this.assetNameOverride && asset.name !== this.assetNameOverride) {
+            return null;
+        }
+        if (!this.assetNameOverride && !asset.name.match(this.pattern)) {
             return null;
-        const version = new Version(match[2], match[1]);
-        if (!version.isSupported())
+        }
+        const versionData = parseVersionParts(asset.name, release.name, release.tag_name);
+        if (!versionData) {
+            if (this.assetNameOverride) {
+                throw new MissingRelease(`Configured asset "${asset.name}" was found in ${this.githubRepo}, but headfox-js could not infer its browser version from the asset or release metadata.`);
+            }
             return null;
+        }
+        const version = new Version(versionData.release, versionData.version);
+        if (!version.isSupported()) {
+            if (this.assetNameOverride) {
+                throw new UnsupportedVersion(`Configured asset "${asset.name}" resolved to unsupported browser release v${version.fullString}. Supported range: (${CONSTRAINTS.asRange()}).`);
+            }
+            return null;
+        }
         return [version, asset.browser_download_url];
     }
     missingAssetError() {
-        throw new MissingRelease(`No matching release found for ${OS_NAME} ${this.arch} in the supported range: (${CONSTRAINTS.asRange()}). Please update the library.`);
+        const location = this.releaseTag
+            ? `${this.githubRepo} release tag "${this.releaseTag}"`
+            : this.githubRepo;
+        if (this.assetNameOverride) {
+            throw new MissingRelease(`Could not find configured asset "${this.assetNameOverride}" in ${location}.`);
+        }
+        throw new MissingRelease(`No matching release asset found in ${location} for ${OS_NAME} ${this.arch} in the supported range: (${CONSTRAINTS.asRange()}). Set HEADFOX_JS_RELEASE_TAG to pin a known working release when using custom forks.`);
     }
     static getPlatformArch() {
         const platArch = os.arch().toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "headfox-js",
-	"version": "0.1.1",
+	"version": "0.1.12",
 	"description": "TypeScript launcher and Playwright tooling for Headfox, currently powered by Camoufox-compatible browser bundles.",
 	"license": "MPL-2.0",
 	"type": "module",