@hominis/fireforge 0.9.0

package/dist/src/utils/parse.js

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Lightweight runtime object parsing and field extraction helpers.
+ *
+ * Reduces repetitive "validate unknown → cast" boilerplate across
+ * config validation, manifest parsing, and metadata validation.
+ */
+import { isArray, isNumber, isObject, isString } from './validation.js';
+/**
+ * A parsed record wrapper that provides typed field extraction
+ * with clear error messages. Construct via {@link parseObject}.
+ */
+export class ParsedRecord {
+    #data;
+    #label;
+    constructor(data, label) {
+        this.#data = data;
+        this.#label = label;
+    }
+    /**
+     * Extracts a required string field.
+     * @param key - Field name
+     * @returns The string value
+     * @throws Error if the field is missing or not a string
+     */
+    string(key) {
+        const value = this.#data[key];
+        if (!isString(value)) {
+            throw new Error(`${this.#label}.${key} must be a string`);
+        }
+        return value;
+    }
+    /**
+     * Extracts an optional string field.
+     * @param key - Field name
+     * @returns The string value or undefined
+     * @throws Error if the field is present but not a string
+     */
+    optionalString(key) {
+        const value = this.#data[key];
+        if (value === undefined)
+            return undefined;
+        if (!isString(value)) {
+            throw new Error(`${this.#label}.${key} must be a string`);
+        }
+        return value;
+    }
+    /**
+     * Extracts a required number field.
+     * @param key - Field name
+     * @returns The number value
+     * @throws Error if the field is missing or not a number
+     */
+    number(key) {
+        const value = this.#data[key];
+        if (!isNumber(value)) {
+            throw new Error(`${this.#label}.${key} must be a number`);
+        }
+        return value;
+    }
+    /**
+     * Extracts an optional number field.
+     * @param key - Field name
+     * @returns The number value or undefined
+     * @throws Error if the field is present but not a number
+     */
+    optionalNumber(key) {
+        const value = this.#data[key];
+        if (value === undefined)
+            return undefined;
+        if (!isNumber(value)) {
+            throw new Error(`${this.#label}.${key} must be a number`);
+        }
+        return value;
+    }
+    /**
+     * Extracts a required non-negative integer field.
+     * @param key - Field name
+     * @returns The integer value
+     * @throws Error if the field is missing, not a number, or negative
+     */
+    nonNegativeInteger(key) {
+        const value = this.#data[key];
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+            throw new Error(`${this.#label}.${key} must be a non-negative integer`);
+        }
+        return value;
+    }
+    /**
+     * Extracts an optional non-negative integer field.
+     * @param key - Field name
+     * @returns The integer value or undefined
+     * @throws Error if the field is present but not a non-negative integer
+     */
+    optionalNonNegativeInteger(key) {
+        const value = this.#data[key];
+        if (value === undefined)
+            return undefined;
+        if (!isNumber(value) || !Number.isInteger(value) || value < 0) {
+            throw new Error(`${this.#label}.${key} must be a non-negative integer`);
+        }
+        return value;
+    }
+    /**
+     * Extracts a required string field and validates it against a predicate.
+     * @param key - Field name
+     * @param predicate - Validation function
+     * @param allowed - Description of allowed values for the error message
+     * @returns The validated string value
+     */
+    stringEnum(key, predicate, allowed) {
+        const value = this.string(key);
+        if (!predicate(value)) {
+            throw new Error(`${this.#label}.${key} must be ${allowed}`);
+        }
+        return value;
+    }
+    /**
+     * Extracts a required string field and validates it with a custom check.
+     * @param key - Field name
+     * @param check - Validation function returning true if valid
+     * @param constraint - Description of the constraint for the error message
+     * @returns The validated string value
+     */
+    validatedString(key, check, constraint) {
+        const value = this.string(key);
+        if (!check(value)) {
+            throw new Error(`${this.#label}.${key} must be ${constraint}`);
+        }
+        return value;
+    }
+    /**
+     * Extracts a required array-of-strings field.
+     * @param key - Field name
+     * @returns The string array
+     * @throws Error if the field is missing or not an array of strings
+     */
+    stringArray(key) {
+        const value = this.#data[key];
+        if (!isArray(value) || !value.every(isString)) {
+            throw new Error(`${this.#label}.${key} must be an array of strings`);
+        }
+        return [...value];
+    }
+    /**
+     * Extracts a required nested object field.
+     * @param key - Field name
+     * @returns A new ParsedRecord wrapping the nested object
+     * @throws Error if the field is missing or not an object
+     */
+    object(key) {
+        const value = this.#data[key];
+        if (!isObject(value)) {
+            throw new Error(`${this.#label}.${key} must be an object`);
+        }
+        return new ParsedRecord(value, `${this.#label}.${key}`);
+    }
+    /**
+     * Extracts an optional nested object field.
+     * @param key - Field name
+     * @returns A new ParsedRecord wrapping the nested object, or undefined
+     * @throws Error if the field is present but not an object
+     */
+    optionalObject(key) {
+        const value = this.#data[key];
+        if (value === undefined)
+            return undefined;
+        if (!isObject(value)) {
+            throw new Error(`${this.#label}.${key} must be an object`);
+        }
+        return new ParsedRecord(value, `${this.#label}.${key}`);
+    }
+    /**
+     * Returns the raw value of a field without validation.
+     * @param key - Field name
+     */
+    raw(key) {
+        return this.#data[key];
+    }
+    /**
+     * Returns all keys in the underlying record.
+     */
+    keys() {
+        return Object.keys(this.#data);
+    }
+}
+/**
+ * Wraps an unknown value as a ParsedRecord after verifying it is an object.
+ * @param data - The unknown value to parse
+ * @param label - Label for error messages (e.g. "Config", "patches[0]")
+ * @returns A ParsedRecord for typed field extraction
+ * @throws Error if data is not a plain object
+ */
+export function parseObject(data, label) {
+    if (!isObject(data)) {
+        throw new Error(`${label} must be an object`);
+    }
+    return new ParsedRecord(data, label);
+}
+//# sourceMappingURL=parse.js.map

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

@@ -0,0 +1,10 @@
+/** Converts Windows path separators to forward slashes for stable comparisons. */
+export declare function normalizePathSlashes(path: string): string;
+/** Checks whether a path is explicitly absolute on either POSIX or Windows. */
+export declare function isExplicitAbsolutePath(path: string): boolean;
+/** Resolves a candidate path and returns whether it stays within the given root. */
+export declare function isPathInsideRoot(root: string, candidate: string): boolean;
+/** Checks whether a relative path stays contained within an arbitrary root. */
+export declare function isContainedRelativePath(path: string): boolean;
+/** Converts a candidate path to a normalized root-relative path, rejecting escapes. */
+export declare function toRootRelativePath(root: string, candidate: string): string;

package/dist/src/utils/paths.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { isAbsolute, relative, resolve } from 'node:path';
+const WINDOWS_ABSOLUTE_PATH = /^[a-zA-Z]:[\\/]/;
+const RELATIVE_PATH_ROOT = resolve('/__fireforge_path_root__');
+/** Converts Windows path separators to forward slashes for stable comparisons. */
+export function normalizePathSlashes(path) {
+    return path.replace(/\\/g, '/');
+}
+/** Checks whether a path is explicitly absolute on either POSIX or Windows. */
+export function isExplicitAbsolutePath(path) {
+    return isAbsolute(path) || WINDOWS_ABSOLUTE_PATH.test(path);
+}
+/** Resolves a candidate path and returns whether it stays within the given root. */
+export function isPathInsideRoot(root, candidate) {
+    const resolvedRoot = resolve(root);
+    const resolvedCandidate = isExplicitAbsolutePath(candidate)
+        ? resolve(candidate)
+        : resolve(resolvedRoot, candidate);
+    const relativePath = relative(resolvedRoot, resolvedCandidate);
+    return (relativePath === '' ||
+        (!relativePath.startsWith('..') &&
+            !isAbsolute(relativePath) &&
+            !WINDOWS_ABSOLUTE_PATH.test(relativePath)));
+}
+/** Checks whether a relative path stays contained within an arbitrary root. */
+export function isContainedRelativePath(path) {
+    if (isExplicitAbsolutePath(path)) {
+        return false;
+    }
+    return isPathInsideRoot(RELATIVE_PATH_ROOT, path);
+}
+/** Converts a candidate path to a normalized root-relative path, rejecting escapes. */
+export function toRootRelativePath(root, candidate) {
+    const resolvedRoot = resolve(root);
+    const resolvedCandidate = isExplicitAbsolutePath(candidate)
+        ? resolve(candidate)
+        : resolve(resolvedRoot, candidate);
+    if (!isPathInsideRoot(resolvedRoot, resolvedCandidate)) {
+        throw new Error(`Path escapes root: ${candidate}`);
+    }
+    return normalizePathSlashes(relative(resolvedRoot, resolvedCandidate));
+}
+//# sourceMappingURL=paths.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * Supported operating system platforms.
+ */
+export type Platform = 'darwin' | 'linux' | 'win32';
+/**
+ * Supported CPU architectures.
+ */
+export type Arch = 'x64' | 'arm64';
+/**
+ * Gets the current operating system platform.
+ * @throws Error if running on an unsupported platform
+ */
+export declare function getPlatform(): Platform;
+/**
+ * Gets the current CPU architecture.
+ * @throws Error if running on an unsupported architecture
+ */
+export declare function getArch(): Arch;
+/**
+ * Gets the mozconfig filename for the current platform.
+ */
+export declare function getMozconfigName(): string;
+/**
+ * Checks if the current platform is macOS.
+ */
+export declare function isDarwin(): boolean;
+/**
+ * Checks if the current platform is Linux.
+ */
+export declare function isLinux(): boolean;
+/**
+ * Checks if the current platform is Windows.
+ */
+export declare function isWindows(): boolean;
+/**
+ * Gets the appropriate file extension for executables on the current platform.
+ */
+export declare function getExecutableExtension(): string;

package/dist/src/utils/platform.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { arch, platform } from 'node:os';
+import { GeneralError } from '../errors/base.js';
+/**
+ * Gets the current operating system platform.
+ * @throws Error if running on an unsupported platform
+ */
+export function getPlatform() {
+    const p = platform();
+    if (p === 'darwin' || p === 'linux' || p === 'win32') {
+        return p;
+    }
+    throw new GeneralError(`Unsupported platform: ${p}. FireForge supports darwin, linux, and win32.`);
+}
+/**
+ * Gets the current CPU architecture.
+ * @throws Error if running on an unsupported architecture
+ */
+export function getArch() {
+    const a = arch();
+    if (a === 'x64' || a === 'arm64') {
+        return a;
+    }
+    throw new GeneralError(`Unsupported architecture: ${a}. FireForge supports x64 and arm64.`);
+}
+/**
+ * Gets the mozconfig filename for the current platform.
+ */
+export function getMozconfigName() {
+    return `${getPlatform()}.mozconfig`;
+}
+/**
+ * Checks if the current platform is macOS.
+ */
+export function isDarwin() {
+    return platform() === 'darwin';
+}
+/**
+ * Checks if the current platform is Linux.
+ */
+export function isLinux() {
+    return platform() === 'linux';
+}
+/**
+ * Checks if the current platform is Windows.
+ */
+export function isWindows() {
+    return platform() === 'win32';
+}
+/**
+ * Gets the appropriate file extension for executables on the current platform.
+ */
+export function getExecutableExtension() {
+    return isWindows() ? '.exe' : '';
+}
+//# sourceMappingURL=platform.js.map

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

@@ -0,0 +1,80 @@
+/**
+ * Result of executing a command.
+ */
+export interface ExecResult {
+    /** Standard output content */
+    stdout: string;
+    /** Standard error content */
+    stderr: string;
+    /** Process exit code */
+    exitCode: number;
+}
+/**
+ * Options for command execution.
+ */
+export interface ExecOptions {
+    /** Working directory for the command */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Executes a command and returns its output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Execution result with stdout, stderr, and exit code
+ */
+export declare function exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+/**
+ * Callback for streaming output.
+ */
+export type StreamCallback = (data: string) => void;
+/**
+ * Options for streaming command execution.
+ */
+export interface StreamOptions extends ExecOptions {
+    /** Callback for stdout data */
+    onStdout?: StreamCallback;
+    /** Callback for stderr data */
+    onStderr?: StreamCallback;
+}
+/**
+ * Executes a command and streams its output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Exit code of the process
+ */
+export declare function execStream(command: string, args: string[], options?: StreamOptions): Promise<number>;
+/**
+ * Executes a command and inherits stdio (shows output directly).
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Exit code of the process
+ */
+export declare function execInherit(command: string, args: string[], options?: ExecOptions): Promise<number>;
+/**
+ * Executes a command while inheriting stdin, streaming stdout/stderr live,
+ * and capturing the emitted output for diagnostics.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Execution result with stdout, stderr, and exit code
+ */
+export declare function execInheritCapture(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+/**
+ * Finds an executable in the system PATH.
+ * @param name - Name of the executable
+ * @returns Full path to the executable, or undefined if not found
+ */
+export declare function findExecutable(name: string): Promise<string | undefined>;
+/**
+ * Checks if an executable exists in the system PATH.
+ * @param name - Name of the executable
+ * @returns True if the executable exists
+ */
+export declare function executableExists(name: string): Promise<boolean>;

package/dist/src/utils/process.js

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { spawn } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+// 50 MB cap per stream to prevent OOM — large toolchain builds (e.g. Firefox, Chromium)
+// can easily blow past this, so we truncate rather than let the buffer grow unbounded.
+const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
+function createStreamCollector(mirror) {
+    const chunks = [];
+    let totalLength = 0;
+    let truncated = false;
+    return {
+        onData: (data) => {
+            const chunk = data.toString();
+            mirror?.write(chunk);
+            if (truncated)
+                return;
+            const remaining = MAX_OUTPUT_SIZE - totalLength;
+            if (chunk.length > remaining) {
+                chunks.push(chunk.slice(0, remaining));
+                chunks.push('\n[truncated — output exceeded 50 MB]');
+                totalLength = MAX_OUTPUT_SIZE;
+                truncated = true;
+            }
+            else {
+                chunks.push(chunk);
+                totalLength += chunk.length;
+            }
+        },
+        getText: () => chunks.join(''),
+    };
+}
+function exitCodeFromClose(code, signal) {
+    if (code !== null) {
+        return code;
+    }
+    if (signal) {
+        const signalNumber = osConstants.signals[signal];
+        if (typeof signalNumber === 'number') {
+            return 128 + signalNumber;
+        }
+    }
+    return 1;
+}
+/**
+ * Executes a command and returns its output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Execution result with stdout, stderr, and exit code
+ */
+export async function exec(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: options.timeout,
+        });
+        const out = createStreamCollector();
+        const err = createStreamCollector();
+        child.stdout.on('data', out.onData);
+        child.stderr.on('data', err.onData);
+        child.on('error', (error) => {
+            reject(error);
+        });
+        child.on('close', (code, signal) => {
+            resolve({
+                stdout: out.getText(),
+                stderr: err.getText(),
+                exitCode: exitCodeFromClose(code, signal),
+            });
+        });
+    });
+}
+/**
+ * Executes a command and streams its output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Exit code of the process
+ */
+export async function execStream(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: options.timeout,
+        });
+        child.stdout.on('data', (data) => {
+            options.onStdout?.(data.toString());
+        });
+        child.stderr.on('data', (data) => {
+            options.onStderr?.(data.toString());
+        });
+        child.on('error', (error) => {
+            reject(error);
+        });
+        child.on('close', (code, signal) => {
+            resolve(exitCodeFromClose(code, signal));
+        });
+    });
+}
+/**
+ * Executes a command and inherits stdio (shows output directly).
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Exit code of the process
+ */
+export async function execInherit(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            stdio: 'inherit',
+            timeout: options.timeout,
+        });
+        child.on('error', (error) => {
+            reject(error);
+        });
+        child.on('close', (code, signal) => {
+            resolve(exitCodeFromClose(code, signal));
+        });
+    });
+}
+/**
+ * Executes a command while inheriting stdin, streaming stdout/stderr live,
+ * and capturing the emitted output for diagnostics.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Execution result with stdout, stderr, and exit code
+ */
+export async function execInheritCapture(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            stdio: ['inherit', 'pipe', 'pipe'],
+            timeout: options.timeout,
+        });
+        const out = createStreamCollector(process.stdout);
+        const err = createStreamCollector(process.stderr);
+        child.stdout.on('data', out.onData);
+        child.stderr.on('data', err.onData);
+        child.on('error', (error) => {
+            reject(error);
+        });
+        child.on('close', (code, signal) => {
+            resolve({
+                stdout: out.getText(),
+                stderr: err.getText(),
+                exitCode: exitCodeFromClose(code, signal),
+            });
+        });
+    });
+}
+/**
+ * Finds an executable in the system PATH.
+ * @param name - Name of the executable
+ * @returns Full path to the executable, or undefined if not found
+ */
+export async function findExecutable(name) {
+    const command = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const result = await exec(command, [name]);
+        if (result.exitCode === 0 && result.stdout.trim()) {
+            // Return the first line (first match)
+            return result.stdout.trim().split('\n')[0];
+        }
+        return undefined;
+    }
+    catch (error) {
+        void error;
+        return undefined;
+    }
+}
+/**
+ * Checks if an executable exists in the system PATH.
+ * @param name - Name of the executable
+ * @returns True if the executable exists
+ */
+export async function executableExists(name) {
+    const path = await findExecutable(name);
+    return path !== undefined;
+}
+//# sourceMappingURL=process.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Escapes special regex characters in a string.
+ */
+export declare function escapeRegex(str: string): string;
+/** Matches hex color values like #fff, #ff00ff, #ff00ff80 (longest-first alternation) */
+export declare const CSS_HEX_COLOR: RegExp;
+/** Matches rgb() or rgba() function calls */
+export declare const CSS_RGB_COLOR: RegExp;
+/** Matches hsl() or hsla() function calls */
+export declare const CSS_HSL_COLOR: RegExp;
+/**
+ * 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 them
+ * with spaces of equal length to preserve character offsets. String literals
+ * (single-quoted, double-quoted, and template) are preserved intact.
+ */
+export declare function stripJsComments(source: string): string;
+/**
+ * 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

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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) */
+export 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 */
+export const CSS_RGB_COLOR = /\brgba?\s*\(/;
+/** Matches hsl() or hsla() function calls */
+export 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 them
+ * with spaces of equal length to preserve character offsets. String literals
+ * (single-quoted, double-quoted, and template) are preserved intact.
+ */
+export function stripJsComments(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));
+}
+//# sourceMappingURL=regex.js.map