@hominis/fireforge 0.9.0

package/dist/src/utils/validation.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Checks whether a value is a string.
+ * @param value - Value to check
+ * @returns True if value is a string
+ */
+export declare function isString(value: unknown): value is string;
+/**
+ * Checks whether a value is a finite number (excludes NaN).
+ * @param value - Value to check
+ * @returns True if value is a finite number
+ */
+export declare function isNumber(value: unknown): value is number;
+/**
+ * Checks whether a value is a positive integer (greater than zero).
+ * @param value - Value to check
+ * @returns True if value is a positive integer
+ */
+export declare function isPositiveInteger(value: unknown): value is number;
+/**
+ * Checks whether a value is a boolean.
+ * @param value - Value to check
+ * @returns True if value is a boolean
+ */
+export declare function isBoolean(value: unknown): value is boolean;
+/**
+ * Checks whether a value is a non-null, non-array object.
+ * @param value - Value to check
+ * @returns True if value is a plain object
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Checks whether a value is an array.
+ * @param value - Value to check
+ * @returns True if value is an array
+ */
+export declare function isArray(value: unknown): value is unknown[];
+/**
+ * Asserts that a value is a string or throws.
+ * @param value - Value to check
+ * @param name - Name of the field for error messages
+ */
+export declare function assertString(value: unknown, name: string): asserts value is string;
+/**
+ * Asserts that a value is a non-null object or throws.
+ * @param value - Value to check
+ * @param name - Name of the field for error messages
+ */
+export declare function assertObject(value: unknown, name: string): asserts value is Record<string, unknown>;
+/**
+ * Validates a Firefox version string.
+ * Accepts formats like "146.0", "146.0.1", "140.0esr", "147.0b1"
+ */
+export declare function isValidFirefoxVersion(version: string): boolean;
+/**
+ * Validates a Firefox product string.
+ * Accepts: firefox, firefox-esr, firefox-beta
+ */
+export declare function isValidFirefoxProduct(product: string): boolean;
+/**
+ * Valid project license SPDX identifiers.
+ */
+export declare const PROJECT_LICENSES: readonly ["EUPL-1.2", "MPL-2.0", "0BSD", "GPL-2.0-or-later"];
+/**
+ * Validates a project license string.
+ */
+export declare function isValidProjectLicense(license: string): license is (typeof PROJECT_LICENSES)[number];
+/**
+ * Valid patch categories.
+ */
+export declare const PATCH_CATEGORIES: readonly ["branding", "ui", "privacy", "security", "infra"];
+/**
+ * Validates a patch category string.
+ */
+export declare function isValidPatchCategory(category: string): category is (typeof PATCH_CATEGORIES)[number];
+/**
+ * Checks whether a Firefox version string has an ESR suffix.
+ */
+export declare function isEsrVersion(version: string): boolean;
+/**
+ * Checks whether a Firefox version string is a beta version (e.g. "147.0b1").
+ */
+export declare function isBetaVersion(version: string): boolean;
+/**
+ * Infers the Firefox product type from a version string.
+ * Returns undefined if no clear inference can be made.
+ */
+export declare function inferProductFromVersion(version: string): 'firefox' | 'firefox-esr' | 'firefox-beta' | undefined;
+/**
+ * Validates that a Firefox product and version are compatible.
+ *
+ * Rules:
+ * - `firefox-esr` requires an ESR version (e.g. "140.0esr", "128.0.1esr").
+ * - `firefox-beta` requires a beta version (e.g. "147.0b1").
+ * - `firefox` (stable) rejects both ESR and beta version strings.
+ *
+ * @returns An error message if incompatible, or undefined if valid.
+ */
+export declare function validateFirefoxProductVersionCompatibility(version: string, product: string): string | undefined;
+/**
+ * Validates an application ID string.
+ * Accepts reverse-domain format like "org.example.browser"
+ */
+export declare function isValidAppId(appId: string): boolean;
+/**
+ * Checks if a value is defined (not undefined or null).
+ */
+export declare function isDefined<T>(value: T | undefined | null): value is T;
+/**
+ * Validates that a string is a legal CSS custom property identifier (the part after `--`).
+ *
+ * A valid CSS custom property name requires the ident portion to:
+ * - Be non-empty
+ * - Contain no whitespace or control characters
+ * - Contain no sequences that would break CSS syntax
+ * - Consist of printable, CSS-safe characters (letters, digits, hyphens, underscores, etc.)
+ *
+ * @returns An error message if invalid, or undefined if valid.
+ */
+export declare function validateTokenName(name: string): string | undefined;
+/**
+ * Normalizes a CSS custom property token name.
+ * Strips leading `--` if present, then always prepends `--`.
+ * This allows users to pass either `--my-token` or `my-token`.
+ *
+ * @throws InvalidArgumentError if the resulting name is not a valid CSS custom property.
+ */
+export declare function normalizeTokenName(name: string): string;
+/**
+ * Validates a patch name.
+ * @param name - The patch name to validate
+ * @returns Error message if invalid, undefined if valid
+ */
+export declare function validatePatchName(name: string): string | undefined;

package/dist/src/utils/validation.js

@@ -0,0 +1,250 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Type guards and validation utilities.
+ * Used to safely narrow types from unknown values.
+ */
+import { InvalidArgumentError } from '../errors/base.js';
+/**
+ * Checks whether a value is a string.
+ * @param value - Value to check
+ * @returns True if value is a string
+ */
+export function isString(value) {
+    return typeof value === 'string';
+}
+/**
+ * Checks whether a value is a finite number (excludes NaN).
+ * @param value - Value to check
+ * @returns True if value is a finite number
+ */
+export function isNumber(value) {
+    return typeof value === 'number' && !Number.isNaN(value);
+}
+/**
+ * Checks whether a value is a positive integer (greater than zero).
+ * @param value - Value to check
+ * @returns True if value is a positive integer
+ */
+export function isPositiveInteger(value) {
+    return isNumber(value) && Number.isInteger(value) && value > 0;
+}
+/**
+ * Checks whether a value is a boolean.
+ * @param value - Value to check
+ * @returns True if value is a boolean
+ */
+export function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+/**
+ * Checks whether a value is a non-null, non-array object.
+ * @param value - Value to check
+ * @returns True if value is a plain object
+ */
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Checks whether a value is an array.
+ * @param value - Value to check
+ * @returns True if value is an array
+ */
+export function isArray(value) {
+    return Array.isArray(value);
+}
+/**
+ * Asserts that a value is a string or throws.
+ * @param value - Value to check
+ * @param name - Name of the field for error messages
+ */
+export function assertString(value, name) {
+    if (!isString(value)) {
+        throw new InvalidArgumentError(`Expected ${name} to be a string, got ${typeof value}`, name);
+    }
+}
+/**
+ * Asserts that a value is a non-null object or throws.
+ * @param value - Value to check
+ * @param name - Name of the field for error messages
+ */
+export function assertObject(value, name) {
+    if (!isObject(value)) {
+        throw new InvalidArgumentError(`Expected ${name} to be an object, got ${typeof value}`, name);
+    }
+}
+/**
+ * Validates a Firefox version string.
+ * Accepts formats like "146.0", "146.0.1", "140.0esr", "147.0b1"
+ */
+export function isValidFirefoxVersion(version) {
+    // Stable/ESR: 146.0, 146.0.1, 140.0esr, 128.0.1esr
+    // Beta: 147.0b1, 147.0b2
+    return /^[1-9]\d{0,2}\.\d+(?:b[1-9]\d*|\.\d+(?:esr)?|esr)?$/.test(version);
+}
+/**
+ * Validates a Firefox product string.
+ * Accepts: firefox, firefox-esr, firefox-beta
+ */
+export function isValidFirefoxProduct(product) {
+    return ['firefox', 'firefox-esr', 'firefox-beta'].includes(product);
+}
+/**
+ * Valid project license SPDX identifiers.
+ */
+export const PROJECT_LICENSES = ['EUPL-1.2', 'MPL-2.0', '0BSD', 'GPL-2.0-or-later'];
+/**
+ * Validates a project license string.
+ */
+export function isValidProjectLicense(license) {
+    return PROJECT_LICENSES.includes(license);
+}
+/**
+ * Valid patch categories.
+ */
+export const PATCH_CATEGORIES = ['branding', 'ui', 'privacy', 'security', 'infra'];
+/**
+ * Validates a patch category string.
+ */
+export function isValidPatchCategory(category) {
+    return PATCH_CATEGORIES.includes(category);
+}
+/**
+ * Checks whether a Firefox version string has an ESR suffix.
+ */
+export function isEsrVersion(version) {
+    return /esr$/i.test(version);
+}
+/**
+ * Checks whether a Firefox version string is a beta version (e.g. "147.0b1").
+ */
+export function isBetaVersion(version) {
+    return /b\d+$/.test(version);
+}
+/**
+ * Infers the Firefox product type from a version string.
+ * Returns undefined if no clear inference can be made.
+ */
+export function inferProductFromVersion(version) {
+    if (isEsrVersion(version)) {
+        return 'firefox-esr';
+    }
+    if (isBetaVersion(version)) {
+        return 'firefox-beta';
+    }
+    return undefined;
+}
+/**
+ * Validates that a Firefox product and version are compatible.
+ *
+ * Rules:
+ * - `firefox-esr` requires an ESR version (e.g. "140.0esr", "128.0.1esr").
+ * - `firefox-beta` requires a beta version (e.g. "147.0b1").
+ * - `firefox` (stable) rejects both ESR and beta version strings.
+ *
+ * @returns An error message if incompatible, or undefined if valid.
+ */
+export function validateFirefoxProductVersionCompatibility(version, product) {
+    const versionIsEsr = isEsrVersion(version);
+    const versionIsBeta = isBetaVersion(version);
+    switch (product) {
+        case 'firefox-esr':
+            if (!versionIsEsr) {
+                return (`Product "firefox-esr" requires an ESR version (e.g. "128.0esr"), ` +
+                    `but got "${version}"`);
+            }
+            break;
+        case 'firefox-beta':
+            if (!versionIsBeta) {
+                return (`Product "firefox-beta" requires a beta version (e.g. "147.0b1"), ` +
+                    `but got "${version}"`);
+            }
+            break;
+        case 'firefox':
+            if (versionIsEsr) {
+                return (`Product "firefox" does not accept ESR versions. ` +
+                    `Use product "firefox-esr" with version "${version}", or remove the "esr" suffix`);
+            }
+            if (versionIsBeta) {
+                return (`Product "firefox" does not accept beta versions. ` +
+                    `Use product "firefox-beta" with version "${version}", or remove the beta suffix`);
+            }
+            break;
+    }
+    return undefined;
+}
+/**
+ * Validates an application ID string.
+ * Accepts reverse-domain format like "org.example.browser"
+ */
+export function isValidAppId(appId) {
+    return /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/.test(appId);
+}
+/**
+ * Checks if a value is defined (not undefined or null).
+ */
+export function isDefined(value) {
+    return value !== undefined && value !== null;
+}
+/**
+ * Validates that a string is a legal CSS custom property identifier (the part after `--`).
+ *
+ * A valid CSS custom property name requires the ident portion to:
+ * - Be non-empty
+ * - Contain no whitespace or control characters
+ * - Contain no sequences that would break CSS syntax
+ * - Consist of printable, CSS-safe characters (letters, digits, hyphens, underscores, etc.)
+ *
+ * @returns An error message if invalid, or undefined if valid.
+ */
+export function validateTokenName(name) {
+    // Strip leading -- for validation (callers may pass with or without)
+    const ident = name.replace(/^--/, '');
+    if (!ident) {
+        return 'Token name must not be empty';
+    }
+    if (/\s/.test(ident)) {
+        return `Token name must not contain whitespace: "${name}"`;
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(ident)) {
+        return `Token name must not contain control characters: "${name}"`;
+    }
+    if (ident.includes('*/')) {
+        return `Token name must not contain "*/" (would break CSS comments): "${name}"`;
+    }
+    // Reject characters that would break CSS declaration syntax
+    if (/[{}();!]/.test(ident)) {
+        return `Token name contains characters that would corrupt CSS syntax: "${name}"`;
+    }
+    return undefined;
+}
+/**
+ * Normalizes a CSS custom property token name.
+ * Strips leading `--` if present, then always prepends `--`.
+ * This allows users to pass either `--my-token` or `my-token`.
+ *
+ * @throws InvalidArgumentError if the resulting name is not a valid CSS custom property.
+ */
+export function normalizeTokenName(name) {
+    const error = validateTokenName(name);
+    if (error) {
+        throw new InvalidArgumentError(error, 'tokenName');
+    }
+    const stripped = name.replace(/^--/, '');
+    return `--${stripped}`;
+}
+/**
+ * Validates a patch name.
+ * @param name - The patch name to validate
+ * @returns Error message if invalid, undefined if valid
+ */
+export function validatePatchName(name) {
+    if (!name.trim())
+        return 'Name is required';
+    if (name.length > 50)
+        return 'Name must be 50 characters or less';
+    if (!/^[a-zA-Z0-9\-_ ]+$/.test(name))
+        return 'Name can only contain letters, numbers, hyphens, underscores, and spaces';
+    return undefined;
+}
+//# sourceMappingURL=validation.js.map

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@hominis/fireforge",
+  "version": "0.9.0",
+  "description": "FireForge — a build tool for customizing Firefox",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": null
+  },
+  "bin": {
+    "fireforge": "./dist/bin/fireforge.js"
+  },
+  "scripts": {
+    "fireforge": "tsx bin/fireforge.ts",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "clean": "node ./scripts/clean.mjs",
+    "lint": "eslint src/ bin/ scripts/ eslint.config.js vitest.config.ts",
+    "lint:ci": "eslint src/ bin/ scripts/ eslint.config.js vitest.config.ts --max-warnings 0",
+    "lint:fix": "eslint src/ bin/ scripts/ eslint.config.js vitest.config.ts --fix",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:package": "npm run pack:verify",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage && node ./scripts/check-coverage-thresholds.mjs",
+    "test:firefox-full": "node ./scripts/run-full-firefox-integration.mjs",
+    "pack:verify": "vitest run src/__tests__/wrapper-smoke.test.ts",
+    "pack:dry-run": "npm pack --dry-run --json --silent",
+    "format": "prettier --write --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\"",
+    "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\"",
+    "prepare": "node -e \"import('./scripts/prepare.mjs').catch((error) => { if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0); throw error; })\"",
+    "prepack": "npm run build",
+    "release:check": "npm run format:check && npm run lint:ci && npm run typecheck && npm run test:coverage && npm run pack:verify && npm run pack:dry-run",
+    "prepublishOnly": "npm run release:check"
+  },
+  "files": [
+    "dist/",
+    "!dist/**/*.test.*",
+    "!dist/**/__tests__/",
+    "!dist/**/test-utils/",
+    "!dist/**/*.js.map",
+    "templates/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "acorn": "^8.14.0",
+    "commander": "^14.0.0",
+    "estree-walker": "^3.0.3",
+    "magic-string": "^0.30.17",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "@types/estree": "^1.0.8",
+    "@types/node": "^25.5.2",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsdoc": "^62.9.0",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "fast-check": "^4.6.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "tsx": "^4.7.0",
+    "typescript": "~6.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vite": "^8.0.7",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "packageManager": "npm@11.12.1",
+  "license": "EUPL-1.2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/topfi/fireforge.git"
+  },
+  "homepage": "https://github.com/topfi/fireforge",
+  "bugs": {
+    "url": "https://github.com/topfi/fireforge/issues"
+  },
+  "keywords": [
+    "fireforge",
+    "firefox",
+    "browser",
+    "build-tool",
+    "customization",
+    "patch-workflow"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/templates/configs/common.mozconfig

@@ -0,0 +1,24 @@
+# Common mozconfig for ${name}
+# This file is merged with platform-specific configs
+
+# Application identity
+ac_add_options --with-app-name=${binaryName}
+ac_add_options --with-branding=browser/branding/${binaryName}
+export MOZ_APP_BASENAME=${binaryName}
+
+# Build options
+ac_add_options --enable-application=browser
+ac_add_options --enable-bootstrap
+
+# Optimization (override in platform configs as needed)
+ac_add_options --enable-optimize
+ac_add_options --disable-debug
+
+# Disable crash reporting
+ac_add_options --disable-crashreporter
+
+# Note: To disable telemetry, set MOZ_TELEMETRY_REPORTING= in your build environment
+# or configure runtime prefs in user.js
+
+# Disable features we don't need
+ac_add_options --disable-updater

package/templates/configs/darwin.mozconfig

@@ -0,0 +1,10 @@
+# macOS-specific mozconfig for ${name}
+
+# Note: MOZ_MACBUNDLE_ID must be set via branding/configure.sh, not mozconfig.
+# It is automatically set when using --with-branding.
+
+# Use system toolchain
+ac_add_options --with-macos-sdk=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
+
+# Code signing (disabled for development)
+# ac_add_options --enable-apple-silicon (uncomment for ARM builds)

package/templates/configs/linux.mozconfig

@@ -0,0 +1,12 @@
+# Linux-specific mozconfig for ${name}
+
+# Use system libraries where available
+ac_add_options --with-system-zlib
+ac_add_options --with-system-jpeg
+
+# PGO disabled by default (can enable for release builds)
+# ac_add_options --enable-lto=cross
+# ac_add_options --enable-profile-generate
+
+# Wayland support
+ac_add_options --enable-default-toolkit=cairo-gtk3-wayland

package/templates/configs/win32.mozconfig

@@ -0,0 +1,14 @@
+# Windows-specific mozconfig for ${name}
+
+# Use Visual Studio toolchain
+ac_add_options --host=x86_64-pc-mingw32
+ac_add_options --target=x86_64-pc-mingw32
+
+# Windows SDK
+# ac_add_options --with-windows-version=10.0.19041.0
+
+# Clang-cl
+ac_add_options --enable-clang-cl
+
+# Disable maintenance service
+ac_add_options --disable-maintenance-service

package/templates/licenses/0BSD.md

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) [year] [fullname]
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.