@hominis/fireforge 0.9.0

package/dist/src/core/firefox-cache.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Cache validation, invalidation, and download-to-cache logic.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { toError } from '../utils/errors.js';
+import { pathExists, readJson, removeFile, writeJson } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { validateArchiveMetadata } from './firefox-archive.js';
+import { downloadFile } from './firefox-download.js';
+/**
+ * Computes the SHA-256 hex digest of a file.
+ * @param filePath - Path to the file
+ */
+export async function sha256File(filePath) {
+    const hash = createHash('sha256');
+    const stream = createReadStream(filePath);
+    await pipeline(stream, hash);
+    return hash.digest('hex');
+}
+/**
+ * Ensures a valid cached archive exists, downloading it if needed.
+ * @param archive - Resolved archive descriptor
+ * @param cacheDir - Cache directory
+ * @param onProgress - Optional progress callback
+ */
+export async function ensureCachedArchive(archive, cacheDir, onProgress) {
+    if (await validateCachedArchive(archive, cacheDir)) {
+        return;
+    }
+    await invalidateArchiveCache(archive, cacheDir);
+    await downloadToCache(archive, cacheDir, onProgress);
+}
+/**
+ * Validates a cached archive using sidecar metadata and SHA-256 checksum.
+ * @param archive - Resolved archive descriptor
+ * @param cacheDir - Cache directory
+ * @returns True if the cache entry is valid
+ */
+async function validateCachedArchive(archive, cacheDir) {
+    const tarballPath = join(cacheDir, archive.filename);
+    const metadataPath = join(cacheDir, archive.metadataFilename);
+    if (!(await pathExists(tarballPath)) || !(await pathExists(metadataPath))) {
+        return false;
+    }
+    try {
+        const metadata = validateArchiveMetadata(await readJson(metadataPath));
+        if (metadata.product !== archive.product ||
+            metadata.archiveVersion !== archive.archiveVersion ||
+            metadata.url !== archive.url) {
+            return false;
+        }
+        if (metadata.contentLength !== undefined) {
+            const { stat } = await import('node:fs/promises');
+            const archiveStats = await stat(tarballPath);
+            if (archiveStats.size !== metadata.contentLength) {
+                return false;
+            }
+        }
+        if (metadata.sha256) {
+            const actualHash = await sha256File(tarballPath);
+            if (actualHash !== metadata.sha256) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch (error) {
+        verbose(`Cache validation failed for ${tarballPath}; treating cache entry as invalid: ${toError(error).message}`);
+        return false;
+    }
+}
+/**
+ * Downloads an archive to cache using an atomic temp file and sidecar metadata.
+ * @param archive - Resolved archive descriptor
+ * @param cacheDir - Cache directory
+ * @param onProgress - Optional progress callback
+ */
+async function downloadToCache(archive, cacheDir, onProgress) {
+    const tarballPath = join(cacheDir, archive.filename);
+    // Use a unique .part path so concurrent downloads for the same archive
+    // do not clobber each other's partial files.
+    const partPath = `${tarballPath}.part-${randomUUID()}`;
+    const metadataPath = join(cacheDir, archive.metadataFilename);
+    try {
+        const contentLength = await downloadFile(archive.url, partPath, onProgress);
+        await rename(partPath, tarballPath);
+        const sha256 = await sha256File(tarballPath);
+        await writeJson(metadataPath, {
+            requestedVersion: archive.requestedVersion,
+            product: archive.product,
+            archiveVersion: archive.archiveVersion,
+            url: archive.url,
+            ...(contentLength !== undefined ? { contentLength } : {}),
+            sha256,
+            downloadedAt: new Date().toISOString(),
+        });
+    }
+    catch (error) {
+        await removeFile(partPath);
+        await removeFile(tarballPath);
+        await removeFile(metadataPath);
+        throw error;
+    }
+}
+/**
+ * Removes cached tarball, metadata, and partial download files for an archive.
+ * @param archive - Resolved archive descriptor
+ * @param cacheDir - Cache directory
+ */
+export async function invalidateArchiveCache(archive, cacheDir) {
+    const tarballPath = join(cacheDir, archive.filename);
+    const metadataPath = join(cacheDir, archive.metadataFilename);
+    // Clean up any partial download files (may have unique suffixes from
+    // concurrent download attempts).
+    const partPrefix = `${archive.filename}.part`;
+    try {
+        const { readdir } = await import('node:fs/promises');
+        const entries = await readdir(cacheDir);
+        await Promise.all(entries
+            .filter((name) => name.startsWith(partPrefix))
+            .map((name) => removeFile(join(cacheDir, name))));
+    }
+    catch {
+        // Cache dir may not exist yet — that's fine.
+    }
+    await removeFile(tarballPath);
+    await removeFile(metadataPath);
+}
+//# sourceMappingURL=firefox-cache.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * Download with retry, stall detection, and progress tracking.
+ */
+/**
+ * Progress callback for download operations.
+ */
+export type ProgressCallback = (downloaded: number, total: number) => void;
+/**
+ * Fetches a URL with timeout and bounded retry for transient failures.
+ *
+ * Non-retryable errors (e.g. 404) are thrown immediately.
+ */
+export declare function fetchWithRetry(url: string): Promise<Response>;
+/**
+ * Downloads a file from a URL with progress tracking, timeout, and retry.
+ * @param url - URL to download
+ * @param destPath - Destination file path
+ * @param onProgress - Optional progress callback
+ * @returns The content-length if available, otherwise undefined
+ */
+export declare function downloadFile(url: string, destPath: string, onProgress?: ProgressCallback): Promise<number | undefined>;

package/dist/src/core/firefox-download.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Download with retry, stall detection, and progress tracking.
+ */
+import { createWriteStream } from 'node:fs';
+import { basename } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { DownloadError, VersionNotFoundError } from '../errors/download.js';
+/** Default request timeout in milliseconds (60 seconds). */
+const REQUEST_TIMEOUT_MS = 60_000;
+/** Maximum number of download attempts. */
+const MAX_ATTEMPTS = 3;
+/** HTTP status codes that are retryable. */
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+/** Base delay between retries in milliseconds. */
+const RETRY_BASE_DELAY_MS = 1_000;
+/** Stall detection timeout — abort if no data received for this duration (30 seconds). */
+const DOWNLOAD_STALL_TIMEOUT_MS = 30_000;
+/**
+ * Fetches a URL with timeout and bounded retry for transient failures.
+ *
+ * Non-retryable errors (e.g. 404) are thrown immediately.
+ */
+export async function fetchWithRetry(url) {
+    let lastError;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            controller.abort();
+        }, REQUEST_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, { signal: controller.signal });
+            if (response.status === 404) {
+                throw new VersionNotFoundError(basename(url).replace('.source.tar.xz', ''));
+            }
+            if (RETRYABLE_STATUS_CODES.has(response.status)) {
+                lastError = new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
+            }
+            else if (!response.ok) {
+                throw new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
+            }
+            else {
+                return response;
+            }
+        }
+        catch (error) {
+            if (error instanceof VersionNotFoundError || error instanceof DownloadError) {
+                throw error;
+            }
+            // Network / timeout errors are retryable
+            lastError = error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (attempt < MAX_ATTEMPTS - 1) {
+            await new Promise((resolve) => {
+                setTimeout(resolve, RETRY_BASE_DELAY_MS * (attempt + 1) ** 2);
+            });
+        }
+    }
+    if (lastError instanceof DownloadError) {
+        throw lastError;
+    }
+    throw new DownloadError(lastError instanceof Error ? lastError.message : 'Download failed after retries', url, lastError instanceof Error ? lastError : undefined);
+}
+/**
+ * Creates a Transform stream that aborts if no data is received within the stall timeout.
+ * The timer resets on each chunk. If it fires, the stream is destroyed with a DownloadError.
+ * @param url - URL being downloaded (for error messages)
+ * @param timeoutMs - Stall timeout in milliseconds
+ */
+function createStallDetector(url, timeoutMs = DOWNLOAD_STALL_TIMEOUT_MS) {
+    let timer;
+    const detector = new Transform({
+        transform(chunk, _encoding, callback) {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                detector.destroy(new DownloadError(`Download stalled: no data received for ${Math.round(timeoutMs / 1000)} seconds`, url));
+            }, timeoutMs);
+            callback(null, chunk);
+        },
+        flush(callback) {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            callback();
+        },
+    });
+    // Start the initial timer (covers the case where the first chunk never arrives).
+    timer = setTimeout(() => {
+        detector.destroy(new DownloadError(`Download stalled: no data received for ${Math.round(timeoutMs / 1000)} seconds`, url));
+    }, timeoutMs);
+    return detector;
+}
+/**
+ * Downloads a file from a URL with progress tracking, timeout, and retry.
+ * @param url - URL to download
+ * @param destPath - Destination file path
+ * @param onProgress - Optional progress callback
+ * @returns The content-length if available, otherwise undefined
+ */
+export async function downloadFile(url, destPath, onProgress) {
+    const response = await fetchWithRetry(url);
+    if (!response.body) {
+        throw new DownloadError('No response body received', url);
+    }
+    const totalSize = parseInt(response.headers.get('content-length') ?? '0', 10);
+    let downloadedSize = 0;
+    const fileStream = createWriteStream(destPath);
+    const nodeStream = Readable.fromWeb(response.body);
+    const stallDetector = createStallDetector(url);
+    if (onProgress && totalSize > 0) {
+        const progress = new Transform({
+            transform(chunk, _encoding, callback) {
+                downloadedSize += chunk.length;
+                onProgress(downloadedSize, totalSize);
+                callback(null, chunk);
+            },
+        });
+        await pipeline(nodeStream, stallDetector, progress, fileStream);
+    }
+    else {
+        await pipeline(nodeStream, stallDetector, fileStream);
+    }
+    return totalSize > 0 ? totalSize : undefined;
+}
+//# sourceMappingURL=firefox-download.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * Firefox source extraction and installed version detection.
+ */
+/**
+ * Extracts a tar.xz archive.
+ * @param archivePath - Path to the archive
+ * @param destDir - Destination directory
+ */
+export declare function extractTarXz(archivePath: string, destDir: string): Promise<void>;
+/**
+ * Gets the Firefox version from an existing source directory.
+ * @param engineDir - Path to the engine directory
+ * @returns Firefox version string
+ */
+export declare function getFirefoxVersion(engineDir: string): Promise<string | undefined>;
+/**
+ * Formats bytes into a human-readable string.
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 GB")
+ */
+export declare function formatBytes(bytes: number): string;

package/dist/src/core/firefox-extract.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Firefox source extraction and installed version detection.
+ */
+import { join } from 'node:path';
+import { ExtractionError } from '../errors/download.js';
+import { ensureDir, pathExists } from '../utils/fs.js';
+import { exec, executableExists } from '../utils/process.js';
+/**
+ * Extracts a tar.xz archive.
+ * @param archivePath - Path to the archive
+ * @param destDir - Destination directory
+ */
+export async function extractTarXz(archivePath, destDir) {
+    if (!(await executableExists('tar'))) {
+        throw new ExtractionError(archivePath, new Error('The "tar" command was not found. Please install tar (or ensure it is on your PATH) and try again.'));
+    }
+    await ensureDir(destDir);
+    const result = await exec('tar', ['-xf', archivePath, '-C', destDir]);
+    if (result.exitCode !== 0) {
+        throw new ExtractionError(archivePath, new Error(`tar exited with code ${result.exitCode}:\n${result.stderr}`));
+    }
+}
+/**
+ * Gets the Firefox version from an existing source directory.
+ * @param engineDir - Path to the engine directory
+ * @returns Firefox version string
+ */
+export async function getFirefoxVersion(engineDir) {
+    const versionPath = join(engineDir, 'browser', 'config', 'version.txt');
+    if (!(await pathExists(versionPath))) {
+        return undefined;
+    }
+    const { readText } = await import('../utils/fs.js');
+    const version = await readText(versionPath);
+    return version.trim();
+}
+/**
+ * Formats bytes into a human-readable string.
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 GB")
+ */
+export function formatBytes(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB'];
+    let size = bytes;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(1)} ${units[unitIndex]}`;
+}
+//# sourceMappingURL=firefox-extract.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * Firefox source download, extraction, and cache management.
+ *
+ * Re-exports from focused sub-modules and provides the top-level
+ * {@link downloadFirefoxSource} orchestrator.
+ */
+import type { FirefoxProduct } from '../types/config.js';
+import type { ProgressCallback } from './firefox-download.js';
+export { resolveArchive } from './firefox-archive.js';
+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., "140.0esr")
+ * @param product - Firefox product type
+ * @returns Full URL to the source tarball
+ */
+export declare function getDownloadUrl(version: string, product?: FirefoxProduct): string;
+/**
+ * Gets the filename for a Firefox source tarball.
+ * @param version - Firefox version
+ * @param product - Firefox product type
+ * @returns Tarball filename
+ */
+export declare function getTarballFilename(version: string, product?: FirefoxProduct): string;
+/**
+ * Downloads and extracts Firefox source.
+ * @param version - Firefox version to download
+ * @param product - Firefox product type
+ * @param destDir - Destination directory for extracted source
+ * @param cacheDir - Directory to store downloaded tarball
+ * @param onProgress - Optional progress callback
+ */
+export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback): Promise<void>;

package/dist/src/core/firefox.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Firefox source download, extraction, and cache management.
+ *
+ * Re-exports from focused sub-modules and provides the top-level
+ * {@link downloadFirefoxSource} orchestrator.
+ */
+import { randomUUID } from 'node:crypto';
+import { rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensureDir, removeDir } from '../utils/fs.js';
+import { resolveArchive } from './firefox-archive.js';
+import { ensureCachedArchive, invalidateArchiveCache } from './firefox-cache.js';
+import { extractTarXz } from './firefox-extract.js';
+// ── Re-exports (preserve public API) ──
+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., "140.0esr")
+ * @param product - Firefox product type
+ * @returns Full URL to the source tarball
+ */
+export function getDownloadUrl(version, product = 'firefox') {
+    return resolveArchive(version, product).url;
+}
+/**
+ * Gets the filename for a Firefox source tarball.
+ * @param version - Firefox version
+ * @param product - Firefox product type
+ * @returns Tarball filename
+ */
+export function getTarballFilename(version, product = 'firefox') {
+    return resolveArchive(version, product).filename;
+}
+/**
+ * Downloads and extracts Firefox source.
+ * @param version - Firefox version to download
+ * @param product - Firefox product type
+ * @param destDir - Destination directory for extracted source
+ * @param cacheDir - Directory to store downloaded tarball
+ * @param onProgress - Optional progress callback
+ */
+export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress) {
+    const archive = resolveArchive(version, product);
+    const tarballPath = join(cacheDir, archive.filename);
+    // Ensure cache directory exists
+    await ensureDir(cacheDir);
+    await ensureCachedArchive(archive, cacheDir, onProgress);
+    // Extract to a unique temporary directory so concurrent downloads for
+    // the same destination do not clobber each other.
+    const tempDir = `${destDir}.tmp-${randomUUID()}`;
+    try {
+        await extractTarXz(tarballPath, tempDir);
+    }
+    catch (error) {
+        await removeDir(tempDir);
+        await invalidateArchiveCache(archive, cacheDir);
+        throw error;
+    }
+    // Firefox source extracts to a subdirectory (e.g., firefox-140.0/)
+    // Find it dynamically since ESR versions may have different naming
+    const { readdir } = await import('node:fs/promises');
+    const entries = await readdir(tempDir, { withFileTypes: true });
+    const extractedSubdir = entries.find((entry) => entry.isDirectory() && entry.name.startsWith('firefox-'));
+    if (extractedSubdir) {
+        const extractedDir = join(tempDir, extractedSubdir.name);
+        await removeDir(destDir);
+        await rename(extractedDir, destDir);
+        await removeDir(tempDir);
+    }
+    else {
+        // If no subdirectory, the temp dir is the source
+        await removeDir(destDir);
+        await rename(tempDir, destDir);
+    }
+}
+//# sourceMappingURL=firefox.js.map

package/dist/src/core/furnace-apply-helpers.d.ts

@@ -0,0 +1,21 @@
+import type { CustomComponentConfig, DryRunAction, OverrideComponentConfig, StepError } from '../types/furnace.js';
+import { type RollbackJournal } from './furnace-rollback.js';
+/** Computes stable checksums for the source files that define a component. */
+export declare function computeComponentChecksums(componentDir: string): Promise<Record<string, string>>;
+/** Compares current component file checksums against the previously recorded state. */
+export declare function hasComponentChanged(componentDir: string, previousChecksums: Record<string, string>): Promise<boolean>;
+/** Applies a custom component into the engine tree and captures registration step errors. */
+export declare function applyCustomComponent(engineDir: string, name: string, componentDir: string, config: CustomComponentConfig, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
+    affectedPaths: string[];
+    stepErrors: StepError[];
+    actions?: DryRunAction[];
+}>;
+/** Applies an override component by copying its matching files onto the engine tree. */
+export declare function applyOverrideComponent(engineDir: string, name: string, componentDir: string, config: OverrideComponentConfig, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
+    affectedPaths: string[];
+    actions?: DryRunAction[];
+}>;
+/** Extracts per-component checksums from the flattened state-file checksum map. */
+export declare function extractComponentChecksums(allChecksums: Record<string, string> | undefined, type: string, name: string): Record<string, string>;
+/** Prefixes component checksums so they can be stored in the flattened state format. */
+export declare function prefixChecksums(checksums: Record<string, string>, type: string, name: string): Record<string, string>;