@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/mach-known-noise-filter.d.ts

@@ -1,122 +0,0 @@
-/**
- * Terminal-echo filter for the known upstream mozsystemmonitor teardown
- * traceback.
- *
- * Headless test runs against recent engines can end with an
- * `AttributeError: 'SystemResourceMonitor' object has no attribute
- * 'stop_time'` traceback at harness teardown. That is upstream noise, and
- * it sits exactly where a reader looks for the failure summary. Real failure
- * lines already beat this traceback in classification. This filter closes
- * the presentation gap by collapsing the echoed traceback to one labeled
- * line.
- *
- * Scope is narrow on purpose:
- *   - Only the terminal echo is filtered. The captured stdout/stderr strings
- *     stay raw, because the classifier (`test-harness-crash.ts`) depends on
- *     the raw traceback for its green-summary override and secondary-noise
- *     detection.
- *   - Only the exact documented incident is collapsed, and every condition
- *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
- *     of the two known attributes (`stop_time`, `poll_interval`), and a
- *     `mozsystemmonitor/resourcemonitor.py` stack frame, and a
- *     previously-seen SUITE_END shutdown marker (shared across the run's
- *     stdout/stderr filter instances, where the marker usually lands on
- *     stdout while the traceback lands on stderr). A novel attribute, a novel
- *     exception type in resourcemonitor.py, or a pre-shutdown occurrence is
- *     echoed verbatim, always.
- *   - The hold buffer is bounded. On overflow the block is flushed verbatim
- *     and the filter returns to pass-through, so output is never lost.
- *
- * The collapse is test-only on purpose, not an oversight. Two reasons,
- * since from outside they read like one:
- *   1. Recognition requires a previously-seen SUITE_END shutdown marker, and
- *      `mach build` never prints one. Wiring the option into the build
- *      dispatch would therefore be a silent no-op.
- *   2. Relaxing that gate for builds would be wrong on its own terms. The
- *      marker is what separates teardown noise from a traceback raised while
- *      work was still happening. A build has no equivalent boundary, so
- *      FireForge cannot tell the known-cosmetic case from a real build-time
- *      failure and must not withhold the block.
- * The build path instead recognizes the signature and says so beside the
- * verbatim traceback. See {@link KNOWN_TEARDOWN_NOISE_BUILD_NOTE} and
- * `runProtectedMachBuild`.
- */
-/**
- * Whole-block recognition. Every signal must hold (see module doc). True
- * when captured output carries the documented mozsystemmonitor teardown
- * traceback.
- *
- * The echo filter below only affects what a human sees. The classifier
- * reads the raw capture, and it needs the same recognition to tell "the
- * suite finished clean and then upstream fell over at shutdown" from "the
- * suite did not finish". This is the same two-signal test the echo filter
- * applies: a novel attribute or a traceback from anywhere but
- * `resourcemonitor.py` is not this incident and must keep failing the run.
- *
- * The shutdown-marker precondition the echo filter adds is intentionally
- * omitted: at the classification layer the case that matters is exactly
- * the one where the teardown crash prevented the shutdown marker from
- * printing.
- *
- * Pure. Exported for the classifier and for direct unit testing.
- *
- * @param output - Raw captured stdout/stderr
- * @returns True when the recognized teardown traceback is present
- */
-export declare function hasKnownTeardownNoise(output: string): boolean;
-/**
- * True when a single line is the documented teardown family's
- * `AttributeError`.
- *
- * The line-level half of {@link hasKnownTeardownNoise}: the traceback frame
- * lives on a neighbouring line, so a per-line test cannot apply the
- * two-signal rule by itself. Callers pair this with
- * `hasKnownTeardownNoise(wholeOutput)` to recover the full recognition
- * ("this capture carries the incident, and this line is its header"), which
- * keeps the closed attribute allowlist (`stop_time`/`poll_interval`) doing
- * the same work it does everywhere else. A novel attribute is not this
- * incident and must stay a candidate failure.
- *
- * @param line - A single output line
- * @returns True when the line is the recognized teardown AttributeError
- */
-export declare function isKnownTeardownNoiseLine(line: string): boolean;
-/**
- * Shared across the stdout and stderr filter instances of one mach run:
- * SUITE_END typically arrives on stdout while the teardown traceback lands
- * on stderr, so the shutdown-seen flag must be visible to both. The two
- * pipes are independent, so a traceback can theoretically beat the marker
- * through. The block then prints verbatim, which is the correct failure
- * direction.
- */
-export interface TeardownNoiseContext {
-    shutdownSeen: boolean;
-}
-/** Fresh per-run context. Hand the same instance to both stream filters. */
-export declare function createTeardownNoiseContext(): TeardownNoiseContext;
-/**
- * Build-phase note for the same recognized signature. The build path does
- * not collapse the traceback (see the module doc's "test-only" note). It
- * prints verbatim and this line is added beside it, so one signature reads
- * the same in both phases without a build losing output it may need.
- */
-export declare const KNOWN_TEARDOWN_NOISE_BUILD_NOTE: string;
-/** One line replaces the whole recognized traceback block in the echo. */
-export declare const KNOWN_TEARDOWN_NOISE_ANNOTATION: string;
-/** Chunk-safe, line-buffered echo filter. See module doc. */
-export interface KnownTeardownNoiseFilter {
-    /** Feed a raw chunk. Returns the text to echo now (possibly empty). */
-    transform(chunk: string): string;
-    /** Flush any buffered residue verbatim (call after the stream closes). */
-    flush(): string;
-}
-/**
- * Creates a stateful filter for one output stream. Complete lines outside a
- * traceback pass straight through (only the trailing partial line is held
- * back). A `Traceback (most recent call last)` header switches to hold mode
- * until the block ends, then either the one-line annotation (recognized
- * signature after a seen shutdown marker) or the verbatim block (anything
- * else) is emitted. Pass the run's shared {@link TeardownNoiseContext} so
- * both stream filters see the same shutdown flag.
- */
-export declare function createKnownTeardownNoiseFilter(context?: TeardownNoiseContext): KnownTeardownNoiseFilter;

package/dist/src/core/mach-known-noise-filter.js

@@ -1,257 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Terminal-echo filter for the known upstream mozsystemmonitor teardown
- * traceback.
- *
- * Headless test runs against recent engines can end with an
- * `AttributeError: 'SystemResourceMonitor' object has no attribute
- * 'stop_time'` traceback at harness teardown. That is upstream noise, and
- * it sits exactly where a reader looks for the failure summary. Real failure
- * lines already beat this traceback in classification. This filter closes
- * the presentation gap by collapsing the echoed traceback to one labeled
- * line.
- *
- * Scope is narrow on purpose:
- *   - Only the terminal echo is filtered. The captured stdout/stderr strings
- *     stay raw, because the classifier (`test-harness-crash.ts`) depends on
- *     the raw traceback for its green-summary override and secondary-noise
- *     detection.
- *   - Only the exact documented incident is collapsed, and every condition
- *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
- *     of the two known attributes (`stop_time`, `poll_interval`), and a
- *     `mozsystemmonitor/resourcemonitor.py` stack frame, and a
- *     previously-seen SUITE_END shutdown marker (shared across the run's
- *     stdout/stderr filter instances, where the marker usually lands on
- *     stdout while the traceback lands on stderr). A novel attribute, a novel
- *     exception type in resourcemonitor.py, or a pre-shutdown occurrence is
- *     echoed verbatim, always.
- *   - The hold buffer is bounded. On overflow the block is flushed verbatim
- *     and the filter returns to pass-through, so output is never lost.
- *
- * The collapse is test-only on purpose, not an oversight. Two reasons,
- * since from outside they read like one:
- *   1. Recognition requires a previously-seen SUITE_END shutdown marker, and
- *      `mach build` never prints one. Wiring the option into the build
- *      dispatch would therefore be a silent no-op.
- *   2. Relaxing that gate for builds would be wrong on its own terms. The
- *      marker is what separates teardown noise from a traceback raised while
- *      work was still happening. A build has no equivalent boundary, so
- *      FireForge cannot tell the known-cosmetic case from a real build-time
- *      failure and must not withhold the block.
- * The build path instead recognizes the signature and says so beside the
- * verbatim traceback. See {@link KNOWN_TEARDOWN_NOISE_BUILD_NOTE} and
- * `runProtectedMachBuild`.
- */
-const TRACEBACK_HEADER_PATTERN = /^Traceback \(most recent call last\)/;
-const CHAINED_EXCEPTION_CONNECTOR_PATTERN = /^(?:During handling of the above exception, another exception occurred:|The above exception was the direct cause of the following exception:)\s*$/;
-/**
- * Closed allowlist of the documented teardown family's attributes:
- * `stop_time` and `poll_interval` (the same mozsystemmonitor init failure
- * `test-harness-crash.ts` already classifies as recognized noise). Any other
- * missing attribute is a new upstream defect and must print verbatim.
- */
-const KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN = /AttributeError: 'SystemResourceMonitor' object has no attribute '(?:stop_time|poll_interval)'/;
-const RESOURCEMONITOR_FRAME_PATTERN = /mozsystemmonitor[/\\]resourcemonitor\.py/;
-/**
- * Shutdown marker: the harness's SUITE_END line. Matches the shape
- * `test-harness-crash.ts` keys its summary parsing on (module-private
- * there, and duplicated here with this cross-reference rather than
- * exported).
- */
-const SHUTDOWN_MARKER_PATTERN = /\bSUITE_END\b/;
-/**
- * Whole-block recognition. Every signal must hold (see module doc). True
- * when captured output carries the documented mozsystemmonitor teardown
- * traceback.
- *
- * The echo filter below only affects what a human sees. The classifier
- * reads the raw capture, and it needs the same recognition to tell "the
- * suite finished clean and then upstream fell over at shutdown" from "the
- * suite did not finish". This is the same two-signal test the echo filter
- * applies: a novel attribute or a traceback from anywhere but
- * `resourcemonitor.py` is not this incident and must keep failing the run.
- *
- * The shutdown-marker precondition the echo filter adds is intentionally
- * omitted: at the classification layer the case that matters is exactly
- * the one where the teardown crash prevented the shutdown marker from
- * printing.
- *
- * Pure. Exported for the classifier and for direct unit testing.
- *
- * @param output - Raw captured stdout/stderr
- * @returns True when the recognized teardown traceback is present
- */
-export function hasKnownTeardownNoise(output) {
-    return (KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN.test(output) &&
-        RESOURCEMONITOR_FRAME_PATTERN.test(output));
-}
-/**
- * True when a single line is the documented teardown family's
- * `AttributeError`.
- *
- * The line-level half of {@link hasKnownTeardownNoise}: the traceback frame
- * lives on a neighbouring line, so a per-line test cannot apply the
- * two-signal rule by itself. Callers pair this with
- * `hasKnownTeardownNoise(wholeOutput)` to recover the full recognition
- * ("this capture carries the incident, and this line is its header"), which
- * keeps the closed attribute allowlist (`stop_time`/`poll_interval`) doing
- * the same work it does everywhere else. A novel attribute is not this
- * incident and must stay a candidate failure.
- *
- * @param line - A single output line
- * @returns True when the line is the recognized teardown AttributeError
- */
-export function isKnownTeardownNoiseLine(line) {
-    return KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN.test(line);
-}
-/** Fresh per-run context. Hand the same instance to both stream filters. */
-export function createTeardownNoiseContext() {
-    return { shutdownSeen: false };
-}
-/**
- * Build-phase note for the same recognized signature. The build path does
- * not collapse the traceback (see the module doc's "test-only" note). It
- * prints verbatim and this line is added beside it, so one signature reads
- * the same in both phases without a build losing output it may need.
- */
-export const KNOWN_TEARDOWN_NOISE_BUILD_NOTE = '[FireForge] The mozsystemmonitor traceback above is the known upstream ' +
-    'SystemResourceMonitor AttributeError — cosmetic, and not a build failure. It is left ' +
-    'verbatim here (unlike a test run, which collapses it); see docs/testing.md.';
-/** One line replaces the whole recognized traceback block in the echo. */
-export const KNOWN_TEARDOWN_NOISE_ANNOTATION = '[FireForge] Known upstream mozsystemmonitor teardown noise (SystemResourceMonitor ' +
-    'AttributeError at harness shutdown) — not a test failure. See docs/testing.md.\n';
-/** Bounds on the held traceback block before flushing verbatim. */
-const HOLD_LINE_LIMIT = 100;
-const HOLD_BYTE_LIMIT = 16 * 1024;
-/**
- * Creates a stateful filter for one output stream. Complete lines outside a
- * traceback pass straight through (only the trailing partial line is held
- * back). A `Traceback (most recent call last)` header switches to hold mode
- * until the block ends, then either the one-line annotation (recognized
- * signature after a seen shutdown marker) or the verbatim block (anything
- * else) is emitted. Pass the run's shared {@link TeardownNoiseContext} so
- * both stream filters see the same shutdown flag.
- */
-export function createKnownTeardownNoiseFilter(context = createTeardownNoiseContext()) {
-    /** Partial (no trailing newline yet) input line. */
-    let partial = '';
-    /** Held traceback lines (each with its newline) while in hold mode. */
-    let held = [];
-    let heldBytes = 0;
-    /**
-     * State machine:
-     *   'pass':   outside any traceback, so lines echo through.
-     *   'inside': between a Traceback header and its closing exception line.
-     *   'closed': saw the closing `SomeError: …` line, still holding in
-     *             case a chained-exception connector continues the block
-     *             (the real fixture chains two tracebacks, so the whole
-     *             chain must be evaluated as one block or the second half
-     *             would print raw after the annotation).
-     */
-    let state = 'pass';
-    const resetHold = () => {
-        const block = held.join('');
-        held = [];
-        heldBytes = 0;
-        state = 'pass';
-        return block;
-    };
-    const releaseHeld = () => {
-        const block = resetHold();
-        if (block.length === 0)
-            return '';
-        return context.shutdownSeen && hasKnownTeardownNoise(block)
-            ? KNOWN_TEARDOWN_NOISE_ANNOTATION
-            : block;
-    };
-    const hold = (line) => {
-        held.push(line);
-        heldBytes += line.length;
-        if (held.length > HOLD_LINE_LIMIT || heldBytes > HOLD_BYTE_LIMIT) {
-            // Pathological block: flush verbatim rather than risk withholding
-            // output. Do not attempt recognition on oversized blocks.
-            return { out: resetHold(), overflowed: true };
-        }
-        return { out: '', overflowed: false };
-    };
-    const processLine = (line) => {
-        const content = line.replace(/\r?\n$/, '');
-        if (state === 'pass') {
-            if (TRACEBACK_HEADER_PATTERN.test(content)) {
-                state = 'inside';
-                return hold(line).out;
-            }
-            if (SHUTDOWN_MARKER_PATTERN.test(content))
-                context.shutdownSeen = true;
-            return line;
-        }
-        if (state === 'inside') {
-            const isContinuation = content.trim().length === 0 ||
-                /^[ \t]/.test(content) ||
-                TRACEBACK_HEADER_PATTERN.test(content);
-            const { out, overflowed } = hold(line);
-            // The first unindented line is the closing `SomeError: …` line. Keep
-            // holding in case a chained connector extends the block.
-            if (!overflowed && !isContinuation) {
-                state = 'closed';
-            }
-            return out;
-        }
-        // state === 'closed': only a blank line, a chained-exception connector,
-        // or another Traceback header continues the block.
-        if (content.trim().length === 0 || CHAINED_EXCEPTION_CONNECTOR_PATTERN.test(content)) {
-            return hold(line).out;
-        }
-        if (TRACEBACK_HEADER_PATTERN.test(content)) {
-            const { out, overflowed } = hold(line);
-            if (!overflowed)
-                state = 'inside';
-            return out;
-        }
-        return releaseHeld() + processLineInPass(line);
-    };
-    // Re-dispatch a line through pass-mode handling after a block release.
-    // The line that ended the block may itself start a new traceback.
-    const processLineInPass = (line) => {
-        const content = line.replace(/\r?\n$/, '');
-        if (TRACEBACK_HEADER_PATTERN.test(content)) {
-            state = 'inside';
-            return hold(line).out;
-        }
-        if (SHUTDOWN_MARKER_PATTERN.test(content))
-            context.shutdownSeen = true;
-        return line;
-    };
-    return {
-        transform(chunk) {
-            let out = '';
-            let buffer = partial + chunk;
-            partial = '';
-            let newlineIndex = buffer.indexOf('\n');
-            while (newlineIndex !== -1) {
-                const line = buffer.slice(0, newlineIndex + 1);
-                buffer = buffer.slice(newlineIndex + 1);
-                out += processLine(line);
-                newlineIndex = buffer.indexOf('\n');
-            }
-            partial = buffer;
-            return out;
-        },
-        flush() {
-            let out = '';
-            if (state !== 'pass') {
-                // A stream that closes mid-block: fold the trailing partial line in
-                // and evaluate. The final exception line is often the last thing
-                // printed, without a trailing newline.
-                if (partial.length > 0) {
-                    held.push(partial);
-                    partial = '';
-                }
-                out += releaseHeld();
-            }
-            out += partial;
-            partial = '';
-            return out;
-        },
-    };
-}

package/dist/src/core/mach-mozconfig.d.ts

@@ -1,57 +0,0 @@
-import type { FireForgeConfig } from '../types/config.js';
-/**
- * Template variables for mozconfig generation.
- */
-export interface MozconfigVariables {
-    name: string;
-    vendor: string;
-    appId: string;
-    binaryName: string;
-}
-/**
- * Extracts the `--with-branding=<path>` value from a rendered mozconfig
- * body. Returns `undefined` when no directive is present, and callers treat
- * that as "mozconfig is missing branding", which is itself an actionable
- * configuration error.
- *
- * Exported for testing.
- */
-export declare function extractWithBrandingPath(mozconfigContent: string): string | undefined;
-/**
- * Extracts the objdir name a mozconfig declares: the single trailing path
- * segment, which is what the `obj-*` scan enumerates.
- *
- * `@TOPSRCDIR@` and a leading `./` are both spellings of "beside the
- * source", which is the only arrangement FireForge's scan can see anyway.
- * An absolute path outside the engine directory reduces to its basename and
- * simply will not match a candidate, which is the correct outcome. A
- * declaration that names something the scan cannot see must not select
- * anything.
- *
- * Returns undefined when nothing is declared. Exported for testing.
- */
-export declare function extractMozObjdirName(mozconfigContent: string): string | undefined;
-/**
- * Preflights the just-written mozconfig against the branding tree FireForge
- * set up. A drift between the two is silent-corruption territory: the
- * build runs, `mach configure` reads the stale directory name out of
- * mozconfig, and then the recursive make backend errors out with a "path
- * does not exist" message that names the branding dir the mozconfig
- * referenced. By parsing the mozconfig here and comparing to
- * `config.binaryName`, we turn that into a single-line actionable error
- * before `mach` runs.
- *
- * @param engineDir Path to the engine directory (the branding tree lives here)
- * @param mozconfigPath Path to the mozconfig just written
- * @param config FireForge configuration (reads `binaryName`)
- * @throws BrandingMozconfigMismatchError on drift or missing directive
- */
-export declare function assertBrandingMozconfigAgreement(engineDir: string, mozconfigPath: string, config: FireForgeConfig): Promise<void>;
-/**
- * Generates a mozconfig file from templates.
- * @param configsDir - Path to the configs directory
- * @param engineDir - Path to the engine directory
- * @param config - FireForge configuration
- * @returns Whether engine/mozconfig was rewritten (its content changed)
- */
-export declare function generateMozconfig(configsDir: string, engineDir: string, config: FireForgeConfig): Promise<boolean>;

package/dist/src/core/mach-mozconfig.js

@@ -1,166 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { MozconfigError } from '../errors/build.js';
-import { pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { normalizePathSlashes } from '../utils/paths.js';
-import { getPlatform } from '../utils/platform.js';
-import { BrandingMozconfigMismatchError, splitAppId } from './branding.js';
-/**
- * Replaces template variables in a string.
- * @param content - Content with ${variable} placeholders
- * @param variables - Variables to substitute
- * @returns Content with variables replaced
- */
-function replaceVariables(content, variables) {
-    return content
-        .replace(/\$\{name\}/g, variables.name)
-        .replace(/\$\{vendor\}/g, variables.vendor)
-        .replace(/\$\{appId\}/g, variables.appId)
-        .replace(/\$\{binaryName\}/g, variables.binaryName);
-}
-/**
- * Matches an `--with-branding=<path>` directive anywhere in a rendered
- * mozconfig. The directive form is the one mach reads, and an optional
- * `ac_add_options` prefix is the on-disk convention. `m` flag anchors the
- * search per-line so a multi-line mozconfig with older directives earlier
- * in the file doesn't confuse the extractor. We pick the last match
- * because mach itself takes the last-write-wins semantics of shell
- * configuration for overlapping `ac_add_options` calls.
- */
-const WITH_BRANDING_PATTERN = /^\s*(?:ac_add_options\s+)?--with-branding\s*=\s*(\S+)/gm;
-/**
- * Extracts the `--with-branding=<path>` value from a rendered mozconfig
- * body. Returns `undefined` when no directive is present, and callers treat
- * that as "mozconfig is missing branding", which is itself an actionable
- * configuration error.
- *
- * Exported for testing.
- */
-export function extractWithBrandingPath(mozconfigContent) {
-    const matches = [...mozconfigContent.matchAll(WITH_BRANDING_PATTERN)];
-    const last = matches.at(-1);
-    return last?.[1];
-}
-/**
- * Matches a `MOZ_OBJDIR=<path>` declaration in a mozconfig. Both spellings
- * mach honours are accepted (`mk_add_options MOZ_OBJDIR=…`, the documented
- * one, and a bare `export MOZ_OBJDIR=…`), and the value may be quoted.
- * Last-write-wins for the same reason as {@link WITH_BRANDING_PATTERN}: a
- * mozconfig is shell.
- */
-const MOZ_OBJDIR_PATTERN = /^\s*(?:mk_add_options\s+|export\s+)?MOZ_OBJDIR\s*=\s*["']?([^"'\s#]+)/gm;
-/**
- * Extracts the objdir name a mozconfig declares: the single trailing path
- * segment, which is what the `obj-*` scan enumerates.
- *
- * `@TOPSRCDIR@` and a leading `./` are both spellings of "beside the
- * source", which is the only arrangement FireForge's scan can see anyway.
- * An absolute path outside the engine directory reduces to its basename and
- * simply will not match a candidate, which is the correct outcome. A
- * declaration that names something the scan cannot see must not select
- * anything.
- *
- * Returns undefined when nothing is declared. Exported for testing.
- */
-export function extractMozObjdirName(mozconfigContent) {
-    const matches = [...mozconfigContent.matchAll(MOZ_OBJDIR_PATTERN)];
-    const raw = matches.at(-1)?.[1];
-    if (raw === undefined)
-        return undefined;
-    const trimmed = raw.replace(/\/+$/, '');
-    const segment = trimmed.split('/').at(-1);
-    return segment !== undefined && segment.length > 0 ? segment : undefined;
-}
-/**
- * Preflights the just-written mozconfig against the branding tree FireForge
- * set up. A drift between the two is silent-corruption territory: the
- * build runs, `mach configure` reads the stale directory name out of
- * mozconfig, and then the recursive make backend errors out with a "path
- * does not exist" message that names the branding dir the mozconfig
- * referenced. By parsing the mozconfig here and comparing to
- * `config.binaryName`, we turn that into a single-line actionable error
- * before `mach` runs.
- *
- * @param engineDir Path to the engine directory (the branding tree lives here)
- * @param mozconfigPath Path to the mozconfig just written
- * @param config FireForge configuration (reads `binaryName`)
- * @throws BrandingMozconfigMismatchError on drift or missing directive
- */
-export async function assertBrandingMozconfigAgreement(engineDir, mozconfigPath, config) {
-    const mozconfigContent = await readText(mozconfigPath);
-    const found = extractWithBrandingPath(mozconfigContent);
-    const expected = `browser/branding/${config.binaryName}`;
-    if (!found) {
-        throw new BrandingMozconfigMismatchError(expected, '(no --with-branding directive)', 'mozconfig-missing-branding');
-    }
-    // Normalise both sides to forward slashes before compare. Windows-edited
-    // configs can carry backslash path separators that the build would treat
-    // as literal characters in a repo-relative path.
-    const normalizedFound = normalizePathSlashes(found);
-    if (normalizedFound !== expected) {
-        throw new BrandingMozconfigMismatchError(expected, found, 'name-mismatch');
-    }
-    // Last line of defence: even with matching names, a missing branding tree
-    // means the scaffold step hasn't run. Preflight here so the operator
-    // doesn't pay for a configure-through-build cycle to discover it.
-    const brandingMozBuild = join(engineDir, expected, 'moz.build');
-    if (!(await pathExists(brandingMozBuild))) {
-        throw new BrandingMozconfigMismatchError(expected, found, 'branding-dir-missing');
-    }
-}
-/**
- * Generates a mozconfig file from templates.
- * @param configsDir - Path to the configs directory
- * @param engineDir - Path to the engine directory
- * @param config - FireForge configuration
- * @returns Whether engine/mozconfig was rewritten (its content changed)
- */
-export async function generateMozconfig(configsDir, engineDir, config) {
-    const platform = getPlatform();
-    const commonPath = join(configsDir, 'common.mozconfig');
-    const platformPath = join(configsDir, `${platform}.mozconfig`);
-    const outputPath = join(engineDir, 'mozconfig');
-    const variables = {
-        name: config.name,
-        vendor: config.vendor,
-        appId: config.appId,
-        binaryName: config.binaryName,
-    };
-    let content = '';
-    // Bundle identity: branding configure.sh carries only the leaf of appId
-    // (see splitAppId in branding.ts, and upstream composes the mac bundle id
-    // as <distribution-id>.<MOZ_MACBUNDLE_ID>). The prefix travels here so the
-    // two halves can never drift apart.
-    const { distributionId } = splitAppId(config.appId);
-    content +=
-        `# FireForge identity (generated from fireforge.json appId)\n` +
-            `ac_add_options --with-distribution-id=${distributionId}\n\n`;
-    // Read common config if it exists
-    if (await pathExists(commonPath)) {
-        const commonContent = await readText(commonPath);
-        content += `# Common configuration\n${replaceVariables(commonContent, variables)}\n\n`;
-    }
-    // Read platform-specific config
-    if (!(await pathExists(platformPath))) {
-        throw new MozconfigError(`Platform mozconfig not found: ${platformPath}`);
-    }
-    const platformContent = await readText(platformPath);
-    content += `# Platform configuration (${platform})\n${replaceVariables(platformContent, variables)}`;
-    // Write-if-changed: `mozconfig` is a mach configure input, so its mtime,
-    // not its content, is what `config.status` compares against.
-    // Rewriting a byte-identical file on every build-capable invocation made
-    // mach re-run `configure` plus backend regeneration ("Backend config
-    // changed; N files touched") on every run, each run re-arming the next.
-    // Only touch the file when the rendered content actually differs.
-    const wrote = await writeTextIfChanged(outputPath, content);
-    if (!wrote) {
-        verbose(`mozconfig already up to date (content unchanged): ${outputPath}`);
-    }
-    // Preflight: the mozconfig we just wrote must reference the branding
-    // directory FireForge actually set up. Catching the drift here (after the
-    // write, before anything consumes mozconfig) keeps `generateMozconfig`
-    // the single source of truth for both the render and the sanity-check.
-    await assertBrandingMozconfigAgreement(engineDir, outputPath, config);
-    return wrote;
-}

package/dist/src/core/mach-python.d.ts

@@ -1,19 +0,0 @@
-/**
- * Resets the resolved Python executable. Primarily useful for testing.
- *
- * @internal Exported only so tests can reach it. Not part of the public
- * surface.
- */
-export declare function resetResolvedPython(): void;
-/**
- * Dynamically resolves the python executable and ensures it is available.
- * Checks the Python version range declared by engine/mach when available.
- * @throws PythonNotFoundError if no suitable python is installed
- */
-export declare function ensurePython(engineDir?: string): Promise<void>;
-/**
- * Gets the resolved Python executable name.
- * @param engineDir - Optional engine directory for engine-specific Python requirements
- * @returns The resolved Python executable name
- */
-export declare function getPython(engineDir?: string): Promise<string>;