@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,39 +0,0 @@
-/**
- * Escapes special regex characters in a string.
- */
-export declare function escapeRegex(str: string): string;
-/**
- * Returns true if the content contains any raw CSS color values (hex, rgb, hsl).
- */
-export declare function hasRawCssColors(content: string): boolean;
-/**
- * Strips JS single-line and multi-line comments from source code, replacing
- * comment bytes with spaces (newlines inside block comments are kept) so
- * both character offsets and line numbers are preserved. String literals are
- * preserved intact.
- *
- * Uses acorn's tokenizer, which understands regex literals. A pure-regex
- * implementation does not model them, so two adjacent slashes inside a regex
- * (the tail of `/https?:\/\//`) read as a `//` line comment and the rest of
- * the line is blanked, corrupting whatever lint pass consumes the stripped
- * text. The source is tokenized as a module, then as a script. Firefox
- * chrome sources can contain constructs acorn tokenizes under neither goal.
- * Those fall back to the regex-only strip, which handles strings but not
- * regex literals.
- */
-export declare function stripJsComments(source: string): string;
-/**
- * The tokenizer half of {@link stripJsComments}: the stripped source, or
- * `null` when acorn can tokenize it neither as a module nor as a script.
- *
- * Module first, then script, because chrome subscripts are scripts: a
- * legacy octal escape is a tokenizer error only under the module goal.
- * Callers that must not under-count when tokenizing fails (the code-line
- * size metric) read the `null` and pick their own fallback rather than the
- * regex-only strip, which can blank code.
- */
-export declare function stripJsCommentsParsed(source: string): string | null;
-/**
- * Counts the total number of raw CSS color values (hex, rgb, hsl) in content.
- */
-export declare function countRawCssColors(content: string): number;

package/dist/src/utils/regex.js

@@ -1,109 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { tokenizer as acornTokenizer, tokTypes as acornTokTypes } from 'acorn';
-/**
- * Escapes special regex characters in a string.
- */
-export function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-/** Matches hex color values like #fff, #ff00ff, #ff00ff80 (longest-first alternation) */
-const CSS_HEX_COLOR = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/;
-/** Matches rgb() or rgba() function calls */
-const CSS_RGB_COLOR = /\brgba?\s*\(/;
-/** Matches hsl() or hsla() function calls */
-const CSS_HSL_COLOR = /\bhsla?\s*\(/;
-// Global variants for counting (cached to avoid re-creation per call)
-const CSS_HEX_COLOR_G = new RegExp(CSS_HEX_COLOR.source, 'g');
-const CSS_RGB_COLOR_G = new RegExp(CSS_RGB_COLOR.source, 'g');
-const CSS_HSL_COLOR_G = new RegExp(CSS_HSL_COLOR.source, 'g');
-/**
- * Returns true if the content contains any raw CSS color values (hex, rgb, hsl).
- */
-export function hasRawCssColors(content) {
-    return CSS_HEX_COLOR.test(content) || CSS_RGB_COLOR.test(content) || CSS_HSL_COLOR.test(content);
-}
-/**
- * Strips JS single-line and multi-line comments from source code, replacing
- * comment bytes with spaces (newlines inside block comments are kept) so
- * both character offsets and line numbers are preserved. String literals are
- * preserved intact.
- *
- * Uses acorn's tokenizer, which understands regex literals. A pure-regex
- * implementation does not model them, so two adjacent slashes inside a regex
- * (the tail of `/https?:\/\//`) read as a `//` line comment and the rest of
- * the line is blanked, corrupting whatever lint pass consumes the stripped
- * text. The source is tokenized as a module, then as a script. Firefox
- * chrome sources can contain constructs acorn tokenizes under neither goal.
- * Those fall back to the regex-only strip, which handles strings but not
- * regex literals.
- */
-export function stripJsComments(source) {
-    return stripJsCommentsParsed(source) ?? stripJsCommentsLegacy(source);
-}
-/**
- * The tokenizer half of {@link stripJsComments}: the stripped source, or
- * `null` when acorn can tokenize it neither as a module nor as a script.
- *
- * Module first, then script, because chrome subscripts are scripts: a
- * legacy octal escape is a tokenizer error only under the module goal.
- * Callers that must not under-count when tokenizing fails (the code-line
- * size metric) read the `null` and pick their own fallback rather than the
- * regex-only strip, which can blank code.
- */
-export function stripJsCommentsParsed(source) {
-    const comments = collectJsComments(source, 'module') ?? collectJsComments(source, 'script');
-    if (comments === null)
-        return null;
-    if (comments.length === 0)
-        return source;
-    const chars = source.split('');
-    for (const { start, end } of comments) {
-        for (let i = start; i < end; i++) {
-            if (chars[i] !== '\n' && chars[i] !== '\r') {
-                chars[i] = ' ';
-            }
-        }
-    }
-    return chars.join('');
-}
-/** Comment ranges of `source` under one parse goal, or `null` on a tokenizer error. */
-function collectJsComments(source, sourceType) {
-    const comments = [];
-    try {
-        const t = acornTokenizer(source, {
-            ecmaVersion: 'latest',
-            sourceType,
-            allowHashBang: true,
-            onComment: (_isBlock, _text, start, end) => {
-                comments.push({ start, end });
-            },
-        });
-        // Drive the tokenizer to EOF. We only care about onComment callbacks.
-        for (;;) {
-            const token = t.getToken();
-            if (token.type === acornTokTypes.eof)
-                break;
-        }
-    }
-    catch {
-        return null;
-    }
-    return comments;
-}
-/**
- * Pure-regex comment strip, used only when acorn cannot tokenize
- * the source (preprocessor directives, syntax errors). Strings survive.
- * Regex literals are not modeled, so `//` inside a regex blanks the rest
- * of the line.
- */
-function stripJsCommentsLegacy(source) {
-    return source.replace(/\/\/.*$|\/\*[\s\S]*?\*\/|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`/gm, (match) => (match.startsWith('/') ? ' '.repeat(match.length) : match));
-}
-/**
- * Counts the total number of raw CSS color values (hex, rgb, hsl) in content.
- */
-export function countRawCssColors(content) {
-    return ((content.match(CSS_HEX_COLOR_G)?.length ?? 0) +
-        (content.match(CSS_RGB_COLOR_G)?.length ?? 0) +
-        (content.match(CSS_HSL_COLOR_G)?.length ?? 0));
-}

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

@@ -1,25 +0,0 @@
-/**
- * The single awaitable delay used across FireForge.
- *
- * Callers use this rather than a private `sleep`/`delay` or an inline
- * `new Promise((resolve) => setTimeout(resolve, ms))`, because such copies
- * disagree on the one property that actually matters (whether the pending
- * timer holds the event loop open) and the disagreement is invisible at each
- * call site. Both behaviours live here, and callers state which one they need.
- *
- * The default is a ref'd timer, because the dangerous mistake is the other
- * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node
- * exit mid-grace and skip the escalation entirely.
- *
- * Built on the global `setTimeout` rather than `node:timers/promises`: the
- * suites that drive retry and grace-period logic use vitest fake timers,
- * which patch the global but not the promisified module, so the tidier
- * import would make every timing path untestable.
- * @param ms - Milliseconds to wait.
- * @param options - Pass `unref: true` when a pending delay must not keep the
- *   process alive (background probes, best-effort retries during shutdown).
- * @returns A promise that resolves once the delay has elapsed.
- */
-export declare function sleep(ms: number, options?: {
-    unref?: boolean;
-}): Promise<void>;

package/dist/src/utils/sleep.js

@@ -1,30 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * The single awaitable delay used across FireForge.
- *
- * Callers use this rather than a private `sleep`/`delay` or an inline
- * `new Promise((resolve) => setTimeout(resolve, ms))`, because such copies
- * disagree on the one property that actually matters (whether the pending
- * timer holds the event loop open) and the disagreement is invisible at each
- * call site. Both behaviours live here, and callers state which one they need.
- *
- * The default is a ref'd timer, because the dangerous mistake is the other
- * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node
- * exit mid-grace and skip the escalation entirely.
- *
- * Built on the global `setTimeout` rather than `node:timers/promises`: the
- * suites that drive retry and grace-period logic use vitest fake timers,
- * which patch the global but not the promisified module, so the tidier
- * import would make every timing path untestable.
- * @param ms - Milliseconds to wait.
- * @param options - Pass `unref: true` when a pending delay must not keep the
- *   process alive (background probes, best-effort retries during shutdown).
- * @returns A promise that resolves once the delay has elapsed.
- */
-export function sleep(ms, options) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, ms);
-        if (options?.unref === true)
-            timer.unref();
-    });
-}

package/dist/src/utils/stdio-drain.d.ts

@@ -1,28 +0,0 @@
-/**
- * Bounded stdio drain for delayed process exits.
- *
- * `process.exit()` discards whatever is still queued in an async writable,
- * and stdout is async when it is a pipe, with a 64 KiB kernel buffer on
- * macOS/Linux. The observed failure: `status --json --fail-on` writes a
- * 176 KB payload, the refusal makes `bin/fireforge.ts` exit non-zero, and a
- * piped consumer receives exactly 65 536 bytes. The bin entry point awaits
- * this helper before every delayed exit. The helper itself never calls
- * `process.exit` (the process-boundary test keeps that a bin-only right).
- */
-/**
- * The structural slice of `Writable` the drain wait needs. Accepted instead
- * of `NodeJS.WriteStream` so unit tests can drive synthetic streams.
- */
-export interface DrainableStream {
-    readonly destroyed: boolean;
-    readonly writableFinished: boolean;
-    readonly writableLength: number;
-    on(event: 'drain' | 'error' | 'close', listener: () => void): unknown;
-    off(event: 'drain' | 'error' | 'close', listener: () => void): unknown;
-}
-/**
- * Waits (bounded by `timeoutMs`) for every given stream (stdout and stderr
- * by default) to drain. Resolution is unconditional. The caller exits
- * either way, and the bound only decides how much queued output survives.
- */
-export declare function waitForStdioDrain(timeoutMs: number, streams?: readonly DrainableStream[]): Promise<void>;

package/dist/src/utils/stdio-drain.js

@@ -1,54 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Bounded stdio drain for delayed process exits.
- *
- * `process.exit()` discards whatever is still queued in an async writable,
- * and stdout is async when it is a pipe, with a 64 KiB kernel buffer on
- * macOS/Linux. The observed failure: `status --json --fail-on` writes a
- * 176 KB payload, the refusal makes `bin/fireforge.ts` exit non-zero, and a
- * piped consumer receives exactly 65 536 bytes. The bin entry point awaits
- * this helper before every delayed exit. The helper itself never calls
- * `process.exit` (the process-boundary test keeps that a bin-only right).
- */
-/** True when nothing the process is about to lose remains queued. */
-function isFlushed(stream) {
-    return stream.destroyed || stream.writableFinished || stream.writableLength === 0;
-}
-/**
- * Resolves once `stream` has drained its queued writes, and always within
- * `timeoutMs`. Never rejects: `'error'` and `'close'` (an EPIPE'd pipe,
- * whose error `installBrokenPipeHandler` already swallows) resolve
- * immediately, because a destroyed pipe can never drain and must not stall
- * the exit behind it.
- */
-function waitForStreamDrain(stream, timeoutMs) {
-    if (isFlushed(stream)) {
-        return Promise.resolve();
-    }
-    return new Promise((resolve) => {
-        const settle = () => {
-            clearTimeout(timer);
-            stream.off('drain', onDrain);
-            stream.off('error', settle);
-            stream.off('close', settle);
-            resolve();
-        };
-        const onDrain = () => {
-            if (isFlushed(stream)) {
-                settle();
-            }
-        };
-        const timer = setTimeout(settle, timeoutMs);
-        stream.on('drain', onDrain);
-        stream.on('error', settle);
-        stream.on('close', settle);
-    });
-}
-/**
- * Waits (bounded by `timeoutMs`) for every given stream (stdout and stderr
- * by default) to drain. Resolution is unconditional. The caller exits
- * either way, and the bound only decides how much queued output survives.
- */
-export async function waitForStdioDrain(timeoutMs, streams = [process.stdout, process.stderr]) {
-    await Promise.all(streams.map((stream) => waitForStreamDrain(stream, timeoutMs)));
-}

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

@@ -1,182 +0,0 @@
-import type { JsonObject, JsonValue } from '../types/json.js';
-/**
- * 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;
-/**
- * Parses a CLI flag value as a positive integer. Throws
- * {@link InvalidArgumentError} on NaN, non-integer, or non-positive input.
- *
- * Intended for use inside Commander `argParser` bodies where the raw input
- * arrives as a string. The default pattern (`parseInt(v, 10)`) silently
- * hands NaN to downstream planners, which then embed it into filenames and
- * orders instead of failing fast.
- *
- * Rejects leading-zero forms ("01"), decimals ("1.5"), whitespace, and
- * non-numeric garbage via a strict regex. Only the canonical representation
- * is accepted, so there is no ambiguity between what the user typed and what
- * the value becomes on disk.
- *
- * @param flagName - Flag name to include in the error (e.g. `--order`)
- * @param rawValue - Raw string value from Commander
- */
-export declare function parsePositiveIntegerFlag(flagName: string, rawValue: string): 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[];
-/**
- * Narrows a JSON value to a JSON object node (excludes arrays and `null`).
- *
- * Unlike {@link isObject} this accepts only values already known to be JSON
- * data, so the narrowed `JsonObject` keeps its concrete value contract.
- * Use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
- * @param value - JSON value to check
- * @returns True if value is a JSON object node
- */
-export declare function isJsonObject(value: JsonValue | undefined): value is JsonObject;
-/**
- * Validates a Firefox version string.
- * Accepts formats like "140.9.0", "140.9.1", "140.9.0esr", "147.0b1"
- */
-export declare function isValidFirefoxVersion(version: string): boolean;
-/**
- * Orders two Firefox version strings semantically: major, minor and patch
- * numerically, with a beta (`153.0b7`) before the release it precedes
- * (`153.0`). An `esr` suffix does not change the order: `153.3.0esr` and
- * `153.3.0` compare equal, since the product says which line it is. A
- * lexical sort, which this replaces in `rebase`, put `153.10.0esr` before
- * `153.2.0esr` and `99.0` after `140.0esr`. A string that is not a Firefox
- * version sorts after every one that is, then lexically.
- * @returns Negative when `a` is older, positive when newer, 0 when equal
- */
-export declare function compareFirefoxVersions(a: string, b: string): number;
-/**
- * Validates a release-candidate build directory name.
- * Accepts formats like "build1", "build2", "build12" (no leading zero).
- */
-export declare function isValidFirefoxCandidate(candidate: string): boolean;
-export declare const FIREFOX_PRODUCTS: readonly ["firefox", "firefox-esr", "firefox-beta", "firefox-devedition"];
-/**
- * Validates a Firefox product string.
- *
- * A type predicate, matching its sibling {@link isValidProjectLicense}.
- * Returning plain `boolean` would force `as FirefoxProduct` casts at the
- * call sites even though the `.includes` check is the runtime proof.
- */
-export declare const isValidFirefoxProduct: (value: string) => value is "firefox" | "firefox-esr" | "firefox-beta" | "firefox-devedition";
-/**
- * Builds a type predicate from a `readonly` tuple of allowed values.
- *
- * Deriving the type from the list, rather than declaring a union and
- * hand-maintaining a matching array, removes a whole class of drift: a
- * union can otherwise accept a stale allowlist with no compile error, and a
- * copy of the member list on the `fireforge.json` read path can silently
- * reject a newly added value.
- *
- * Returning a predicate rather than a boolean is what removes the `as`
- * casts: `.includes` is the runtime proof, so the caller should not have to
- * re-assert it. `ParsedRecord.stringEnum` (src/utils/parse.ts) consumes
- * exactly this shape.
- *
- * @param values - The allowed values, as a `readonly` tuple
- * @returns A type predicate narrowing a string to one of `values`
- */
-export declare function makeEnumGuard<const T extends readonly string[]>(values: T): (value: string) => value is T[number];
-/**
- * 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 const isValidProjectLicense: (value: string) => value is "EUPL-1.2" | "MPL-2.0" | "0BSD" | "GPL-2.0-or-later";
-/**
- * Valid patch categories.
- */
-export declare const PATCH_CATEGORIES: readonly ["branding", "ui", "privacy", "security", "infra"];
-/**
- * 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.9.0esr", "128.0.1esr").
- * - `firefox-beta` and `firefox-devedition` require 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 describeProductVersionIncompatibility(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;
-/**
- * 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 describeTokenNameProblem(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;
-/**
- * Normalizes a patch display name against its category:
- * strips a trailing `.patch` and any redundant `NNN-<category>-` /
- * `<category>-` prefixes, case-insensitively and repeatedly, mirroring
- * the filename slug pipeline's require-the-category-token rule. A bare
- * leading number is never stripped, so names like `2-step-verification`
- * survive intact. Falls back to the `.patch`-stripped stem when the
- * strip would empty the name.
- */
-export declare function normalizePatchDisplayName(name: string, category: string): string;
-/**
- * Validates a patch name.
- * @param name - The patch name to validate
- * @returns Error message if invalid, undefined if valid
- */
-export declare function describePatchNameProblem(name: string): string | undefined;