@hominis/fireforge 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -53,6 +53,7 @@
 - Override `baseVersion` drift now blocks `apply` and `deploy` by default instead of warning and continuing. Pass `--force` to override, or use `furnace refresh` to update the baseline.
 - Post-apply consistency check verifies that `customElements.js` and `jar.mn` entries match what was deployed.
 - Engine-side content hashes are cached in the furnace state file, making drift detection faster for the common no-change case.
+- Branding file writes are now content-aware: re-running setup with the same configuration no longer bumps file timestamps, avoiding unnecessary `config.status` reconfiguration during incremental builds.
 - `build` and `test --build` now share the same preparation pipeline including Furnace apply, so incremental test builds no longer run against stale component state.
 - `furnace remove` on an override now restores every overridden engine file to its Firefox baseline instead of leaving deployed files behind.
 - Scanner results are cached by content hash within a process, avoiding redundant parsing during scan-status-apply sequences.
@@ -63,6 +64,9 @@
 
 ### Bug fixes
 
+- `fireforge setup` now writes an initial `patches/patches.json` (with `version: 1`) when creating a new project. Previously, setup created the `patches/` directory but not the manifest, causing `fireforge doctor` to fail the "Patch manifest consistency" check on a fresh project. Re-running `setup --force` on an existing project preserves the current manifest.
+- The full Firefox integration test script (`scripts/run-full-firefox-integration.mjs`) now uses `--yes` instead of `--force` when invoking `fireforge discard`, matching the actual CLI flag. This was the sole cause of integration test failures in the discard and recovery workflow steps.
+- The integration test's cleanup loop now uses direct git operations (`git checkout` for tracked files, `git clean` for untracked) instead of routing through `fireforge discard`, which could not handle untracked branding files introduced by the build.
 - `furnace refresh` now correctly advances the per-override `baseCommit` to the engine HEAD after a successful merge, preventing phantom conflicts on subsequent refreshes.
 - `furnace rename` uses the correct file-removal function for FTL files.
 - `furnace remove` now parses browser.toml sections properly, cleaning up metadata keys below the section header instead of leaving stale fragments.
@@ -77,6 +81,10 @@
 
 ### Internal
 
+- The full Firefox integration script now accepts `FIREFORGE_FULL_FIREFOX_VERSION` to override the Firefox version used during the test run, decoupling the test from the version baked into `fireforge.json`.
+- The integration test now verifies that `obj-*/dist/bin/` exists after a build reports success, detecting cases where mach masks a build failure with exit code 0.
+- The integration test cleanup loop now uses direct git operations (`checkout` / `clean`) instead of routing through `fireforge discard`, correctly handling untracked branding files introduced by the build.
+- New unit tests from a full local Firefox integration run: Python version resolution skips candidates above mach's `MAX_PYTHON_VERSION_TO_CONSIDER` and falls through to a compatible version; fresh-project manifest consistency returns zero issues for the empty manifest that `setup` now writes; bootstrap soft-failure detection catches the `urllib.error.HTTPError: HTTP Error 403` pattern observed in real `mach bootstrap` output.
 - CLI command registration is now driven by a declarative manifest instead of hand-listed calls.
 - Doctor checks are a declarative registry with per-check `run`, `skipIf`, and `fix` fields.
 - New shared destructive-op framework handles confirmation, `--dry-run`, `--yes`/`--force-unsafe`, and audit logging for the patch mutation commands.
@@ -86,7 +94,7 @@
 - The `re-export --files` path extracted into `src/commands/re-export-files.ts` to keep `re-export.ts` under the line limit.
 - `max-lines` and `max-lines-per-function` ESLint rules promoted from `warn` to `error`.
 - Doctor check ordering dependencies documented in the registry comment.
-- Default Firefox version bumped to ESR 146.
+- Default Firefox version bumped to ESR 140.9.0.
 
 ### Packaging
 

package/README.md

@@ -26,7 +26,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 
 - **Quality checks** `fireforge lint` catches fork-specific issues (raw colours, missing licence headers, relative imports, large patches, cross-patch ordering problems) before you export. `fireforge verify` runs a read-only integrity check over the whole patch queue. `fireforge doctor` diagnoses project health including Furnace component validation.
 
-- **Built and validated against real Firefox code** Developed by editing a real Firefox ESR codebase, learning from existing patch tools, observing the breakages and edge cases that surfaced, and turning those findings into a realistic test suite. In-repo tests are thus grounded in actual development scenarios. Full end-to-end runs are currently only run locally, as they require about 30 GB of disk and significant compute for the full build.
+- **Built and validated against real Firefox code** Developed by editing a real Firefox ESR codebase, learning from existing patch tools, observing the breakages and edge cases that surfaced, and turning those findings into a realistic test suite. In-repo tests are thus grounded in actual development scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Github Actions will be added soonishlyTM.
 
 ## Quick Start
 
@@ -52,7 +52,7 @@ npx fireforge build               # build the browser
 npx fireforge run                 # launch it
 ```
 
-Your project now has `fireforge.json`, an `engine/` directory with Firefox source, and a `patches/` directory ready for your first customisation.
+Your project now has `fireforge.json`, an `engine/` directory with Firefox source, and a `patches/` directory with an empty `patches.json` manifest ready for your first customisation.
 
 ### Workflow Overview
 
@@ -172,7 +172,7 @@ This re-exports the fixed patch and continues applying the remaining stack.
       "name": "custom-logo",
       "description": "Replaces default Firefox branding with custom logo",
       "createdAt": "2025-01-15T10:30:00Z",
-      "sourceEsrVersion": "146.0esr",
+      "sourceEsrVersion": "140.9.0esr",
       "filesAffected": ["browser/branding/official/logo.png"]
     }
   ]
@@ -303,7 +303,7 @@ fireforge furnace diff moz-button                  # unified diff against baseli
   "binaryName": "mybrowser",
   "license": "EUPL-1.2",
   "firefox": {
-    "version": "146.0esr",
+    "version": "140.9.0esr",
     "product": "firefox-esr"
   },
   "build": { "jobs": 8 },

package/dist/src/commands/setup-support.js

@@ -3,6 +3,7 @@ import { cpus } from 'node:os';
 import { join } from 'node:path';
 import { group, select, text } from '@clack/prompts';
 import { getProjectPaths, writeConfig } from '../core/config.js';
+import { PATCHES_MANIFEST, savePatchesManifest } from '../core/patch-manifest-io.js';
 import { CancellationError, InvalidArgumentError } from '../errors/base.js';
 import { ensureDir, pathExists, readText, writeText } from '../utils/fs.js';
 import { cancel } from '../utils/logger.js';
@@ -63,7 +64,7 @@ export function validateSetupOptions(options) {
         throw new InvalidArgumentError('Binary name must start with a letter and contain only lowercase letters, numbers, and hyphens', '--binary-name');
     }
     if (options.firefoxVersion !== undefined && !isValidFirefoxVersion(options.firefoxVersion)) {
-        throw new InvalidArgumentError('Invalid Firefox version format (e.g., 146.0, 146.0esr, or 147.0b1)', '--firefox-version');
+        throw new InvalidArgumentError('Invalid Firefox version format (e.g., 140.9.0, 140.9.0esr, or 147.0b1)', '--firefox-version');
     }
     if (options.product !== undefined) {
         resolveFirefoxProduct(options.product, '--product');
@@ -127,10 +128,10 @@ async function promptSetupInputs(options) {
             ? Promise.resolve(options.firefoxVersion)
             : text({
                 message: 'Firefox version to base on',
-                placeholder: '146.0esr',
+                placeholder: '140.9.0esr',
                 validate: (value) => {
                     if (value && !isValidFirefoxVersion(value)) {
-                        return 'Invalid Firefox version format (e.g., 146.0, 146.0esr, or 147.0b1)';
+                        return 'Invalid Firefox version format (e.g., 140.9.0, 140.9.0esr, or 147.0b1)';
                     }
                     return undefined;
                 },
@@ -141,7 +142,7 @@ async function promptSetupInputs(options) {
             }
             const effectiveVersion = (typeof results.firefoxVersion === 'string' && results.firefoxVersion.trim()) ||
                 options.firefoxVersion ||
-                '146.0esr';
+                '140.9.0esr';
             const inferredProduct = inferProductFromVersion(effectiveVersion);
             if (inferredProduct) {
                 return Promise.resolve(inferredProduct);
@@ -183,7 +184,8 @@ async function promptSetupInputs(options) {
     const finalAppId = (typeof project.appId === 'string' ? project.appId.trim() : '') ||
         `org.${sanitizedName}.browser`;
     const finalBinaryName = (typeof project.binaryName === 'string' ? project.binaryName.trim() : '') || sanitizedName;
-    const finalFirefoxVersion = (typeof project.firefoxVersion === 'string' ? project.firefoxVersion.trim() : '') || '146.0esr';
+    const finalFirefoxVersion = (typeof project.firefoxVersion === 'string' ? project.firefoxVersion.trim() : '') ||
+        '140.9.0esr';
     if (!isValidAppId(finalAppId)) {
         throw new InvalidArgumentError(`Derived appId "${finalAppId}" is invalid.`, 'appId');
     }
@@ -250,6 +252,10 @@ export async function writeSetupProjectFiles(projectRoot, config) {
     await ensureDir(paths.configs);
     await ensureDir(paths.fireforgeDir);
     await writeConfig(projectRoot, config);
+    const manifestPath = join(paths.patches, PATCHES_MANIFEST);
+    if (!(await pathExists(manifestPath))) {
+        await savePatchesManifest(paths.patches, { version: 1, patches: [] });
+    }
     const gitignorePath = join(projectRoot, '.gitignore');
     const requiredIgnores = ['node_modules/', 'dist/', 'engine/', '.fireforge/'];
     if (await pathExists(gitignorePath)) {

package/dist/src/core/branding.js

@@ -2,7 +2,7 @@
 import { join } from 'node:path';
 import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
-import { copyDir, pathExists, readText, writeText } from '../utils/fs.js';
+import { copyDir, pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 /**
  * Error thrown when branding operations fail.
@@ -49,7 +49,7 @@ export async function setupBranding(engineDir, config) {
  */
 async function createConfigureScript(brandingDir, config) {
     const configureShPath = join(brandingDir, 'configure.sh');
-    await writeText(configureShPath, buildConfigureScriptContent(config));
+    await writeTextIfChanged(configureShPath, buildConfigureScriptContent(config));
 }
 function buildConfigureScriptContent(config) {
     return `# This Source Code Form is subject to the terms of the Mozilla Public
@@ -69,7 +69,7 @@ async function updateBrandProperties(brandingDir, config) {
         warn('brand.properties not found in branding directory — browser will use default strings');
         return;
     }
-    await writeText(propsPath, buildBrandPropertiesContent(config));
+    await writeTextIfChanged(propsPath, buildBrandPropertiesContent(config));
 }
 function buildBrandPropertiesContent(config) {
     return `# This Source Code Form is subject to the terms of the Mozilla Public
@@ -90,7 +90,7 @@ async function updateBrandFtl(brandingDir, config) {
         warn('brand.ftl not found in branding directory — browser will use default strings');
         return;
     }
-    await writeText(ftlPath, buildBrandFtlContent(config));
+    await writeTextIfChanged(ftlPath, buildBrandFtlContent(config));
 }
 function buildBrandFtlContent(config) {
     return `# This Source Code Form is subject to the terms of the Mozilla Public
@@ -128,7 +128,7 @@ async function patchMozConfigure(engineDir, config) {
         throw new BrandingError('Could not find MOZ_APP_VENDOR imply_option in browser/moz.configure');
     }
     content = content.replace(vendorRegex, buildMozConfigureVendorLine(config));
-    await writeText(mozConfigurePath, content);
+    await writeTextIfChanged(mozConfigurePath, content);
 }
 function buildMozConfigureVendorLine(config) {
     return `imply_option("MOZ_APP_VENDOR", "${escapeString(config.vendor)}")`;

package/dist/src/core/firefox.d.ts

@@ -11,7 +11,7 @@ export type { ProgressCallback } from './firefox-download.js';
 export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
 /**
  * Gets the download URL for a Firefox source tarball.
- * @param version - Firefox version (e.g., "146.0esr")
+ * @param version - Firefox version (e.g., "140.9.0esr")
  * @param product - Firefox product type
  * @returns Full URL to the source tarball
  */

package/dist/src/core/firefox.js

@@ -17,7 +17,7 @@ export { resolveArchive } from './firefox-archive.js';
 export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
 /**
  * Gets the download URL for a Firefox source tarball.
- * @param version - Firefox version (e.g., "146.0esr")
+ * @param version - Firefox version (e.g., "140.9.0esr")
  * @param product - Firefox product type
  * @returns Full URL to the source tarball
  */

package/dist/src/core/furnace-version-drift.d.ts

@@ -10,9 +10,9 @@
  * This module is deliberately pure and string-only: it does no I/O and does
  * not parse Firefox version components. Comparing by string equality is
  * sufficient because `fireforge.json` stores a canonical version string
- * (e.g. `"146.0esr"`) and overrides are created with exactly that string
+ * (e.g. `"140.9.0esr"`) and overrides are created with exactly that string
  * copied from `forgeConfig.firefox.version`. Any string mismatch is worth
- * surfacing — even "140.0" vs "146.0esr" is a real drift signal.
+ * surfacing — even "140.0" vs "140.9.0esr" is a real drift signal.
  *
  * The result is advisory: apply/deploy emit warnings but do not fail, and
  * status reports drift alongside the component overview. Nothing here

package/dist/src/core/furnace-version-drift.js

@@ -11,9 +11,9 @@
  * This module is deliberately pure and string-only: it does no I/O and does
  * not parse Firefox version components. Comparing by string equality is
  * sufficient because `fireforge.json` stores a canonical version string
- * (e.g. `"146.0esr"`) and overrides are created with exactly that string
+ * (e.g. `"140.9.0esr"`) and overrides are created with exactly that string
  * copied from `forgeConfig.firefox.version`. Any string mismatch is worth
- * surfacing — even "140.0" vs "146.0esr" is a real drift signal.
+ * surfacing — even "140.0" vs "140.9.0esr" is a real drift signal.
  *
  * The result is advisory: apply/deploy emit warnings but do not fail, and
  * status reports drift alongside the component overview. Nothing here

package/dist/src/core/patch-manifest-query.d.ts

@@ -43,6 +43,6 @@ export declare function validatePatchIntegrity(patchesDir: string, engineDir: st
  * manifest read-modify-write cycle.
  * @param patchesDir - Path to the patches directory
  * @param filenames - Patch filenames to update
- * @param newVersion - Version string to set (e.g. "146.0esr")
+ * @param newVersion - Version string to set (e.g. "140.9.0esr")
  */
 export declare function stampPatchVersions(patchesDir: string, filenames: string[], newVersion: string): Promise<void>;

package/dist/src/core/patch-manifest-query.js

@@ -103,7 +103,7 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
  * manifest read-modify-write cycle.
  * @param patchesDir - Path to the patches directory
  * @param filenames - Patch filenames to update
- * @param newVersion - Version string to set (e.g. "146.0esr")
+ * @param newVersion - Version string to set (e.g. "140.9.0esr")
  */
 export async function stampPatchVersions(patchesDir, filenames, newVersion) {
     const manifest = await loadPatchesManifest(patchesDir);

package/dist/src/types/commands/patches.d.ts

@@ -47,7 +47,7 @@ export interface PatchMetadata {
     description: string;
     /** ISO timestamp of when the patch was created */
     createdAt: string;
-    /** ESR version the patch was created against (e.g., "146.0esr") */
+    /** ESR version the patch was created against (e.g., "140.9.0esr") */
     sourceEsrVersion: string;
     /** Array of file paths affected by this patch */
     filesAffected: string[];

package/dist/src/types/config.d.ts

@@ -6,7 +6,7 @@ export type FirefoxProduct = 'firefox' | 'firefox-esr' | 'firefox-beta';
  * Firefox version configuration.
  */
 export interface FirefoxConfig {
-    /** Firefox release version (e.g., "146.0esr") */
+    /** Firefox release version (e.g., "140.9.0esr") */
     version: string;
     /** Firefox product type */
     product: FirefoxProduct;

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

@@ -57,6 +57,14 @@ export declare function readText(path: string): Promise<string>;
  * @param content - Content to write
  */
 export declare function writeText(path: string, content: string): Promise<void>;
+/**
+ * Writes text to a file only when the content has actually changed.
+ * Prevents unnecessary mtime bumps that can trigger downstream rebuilds.
+ * @param path - Path to text file
+ * @param content - Content to write
+ * @returns true if the file was written, false if content was already up to date
+ */
+export declare function writeTextIfChanged(path: string, content: string): Promise<boolean>;
 /**
  * Writes content atomically using a temp-file-and-rename strategy.
  * Temp files are created in the destination directory so rename stays atomic.

package/dist/src/utils/fs.js

@@ -112,6 +112,23 @@ export async function readText(path) {
 export async function writeText(path, content) {
     await writeFileAtomic(path, content);
 }
+/**
+ * Writes text to a file only when the content has actually changed.
+ * Prevents unnecessary mtime bumps that can trigger downstream rebuilds.
+ * @param path - Path to text file
+ * @param content - Content to write
+ * @returns true if the file was written, false if content was already up to date
+ */
+export async function writeTextIfChanged(path, content) {
+    if (await pathExists(path)) {
+        const existing = await readText(path);
+        if (existing === content) {
+            return false;
+        }
+    }
+    await writeText(path, content);
+    return true;
+}
 /**
  * Writes content atomically using a temp-file-and-rename strategy.
  * Temp files are created in the destination directory so rename stays atomic.

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

@@ -66,7 +66,7 @@ export declare function assertString(value: unknown, name: string): asserts valu
 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", "146.0esr", "147.0b1"
+ * Accepts formats like "140.9.0", "140.9.1", "140.9.0esr", "147.0b1"
  */
 export declare function isValidFirefoxVersion(version: string): boolean;
 /**
@@ -107,7 +107,7 @@ export declare function inferProductFromVersion(version: string): 'firefox' | 'f
  * Validates that a Firefox product and version are compatible.
  *
  * Rules:
- * - `firefox-esr` requires an ESR version (e.g. "146.0esr", "128.0.1esr").
+ * - `firefox-esr` requires an ESR version (e.g. "140.9.0esr", "128.0.1esr").
  * - `firefox-beta` requires a beta version (e.g. "147.0b1").
  * - `firefox` (stable) rejects both ESR and beta version strings.
  *

package/dist/src/utils/validation.js

@@ -97,10 +97,10 @@ export function assertObject(value, name) {
 }
 /**
  * Validates a Firefox version string.
- * Accepts formats like "146.0", "146.0.1", "146.0esr", "147.0b1"
+ * Accepts formats like "140.9.0", "140.9.1", "140.9.0esr", "147.0b1"
  */
 export function isValidFirefoxVersion(version) {
-    // Stable/ESR: 146.0, 146.0.1, 146.0esr, 128.0.1esr
+    // Stable/ESR: 140.9.0, 140.9.1, 140.9.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);
 }
@@ -160,7 +160,7 @@ export function inferProductFromVersion(version) {
  * Validates that a Firefox product and version are compatible.
  *
  * Rules:
- * - `firefox-esr` requires an ESR version (e.g. "146.0esr", "128.0.1esr").
+ * - `firefox-esr` requires an ESR version (e.g. "140.9.0esr", "128.0.1esr").
  * - `firefox-beta` requires a beta version (e.g. "147.0b1").
  * - `firefox` (stable) rejects both ESR and beta version strings.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",