@hominis/fireforge 0.9.0

package/dist/src/core/config-state.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Project state file management (.fireforge/state.json).
+ */
+import { ConfigError } from '../errors/config.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { warn } from '../utils/logger.js';
+import { isObject, isString } from '../utils/validation.js';
+import { getProjectPaths } from './config-paths.js';
+import { quarantineStateFile, withStateFileLock } from './state-file.js';
+function sanitizeProjectState(data) {
+    if (!isObject(data)) {
+        return {
+            state: {},
+            issues: ['the root value must be a JSON object'],
+            recoveredFields: [],
+        };
+    }
+    const state = {};
+    const issues = [];
+    const recoveredFields = [];
+    const stringFields = [
+        'brand',
+        'buildMode',
+        'lastBuild',
+        'downloadedVersion',
+        'baseCommit',
+    ];
+    for (const key of stringFields) {
+        const value = data[key];
+        if (value === undefined) {
+            continue;
+        }
+        if (!isString(value)) {
+            issues.push(`field "${key}" must be a string`);
+            continue;
+        }
+        if (key === 'buildMode' && !['dev', 'debug', 'release'].includes(value)) {
+            issues.push('field "buildMode" must be one of: dev, debug, release');
+            continue;
+        }
+        if (key === 'buildMode') {
+            state.buildMode = value;
+        }
+        else {
+            state[key] = value;
+        }
+        recoveredFields.push(key);
+    }
+    const pendingResolution = data['pendingResolution'];
+    if (pendingResolution !== undefined) {
+        if (isObject(pendingResolution) &&
+            isString(pendingResolution['patchFilename']) &&
+            isString(pendingResolution['originalError'])) {
+            state.pendingResolution = {
+                patchFilename: pendingResolution['patchFilename'],
+                originalError: pendingResolution['originalError'],
+            };
+            recoveredFields.push('pendingResolution');
+        }
+        else {
+            issues.push('field "pendingResolution" must be an object with string fields "patchFilename" and "originalError"');
+        }
+    }
+    return { state, issues, recoveredFields };
+}
+/**
+ * Validates a parsed project state object and returns a typed FireForgeState.
+ * @param data - Parsed JSON state data
+ * @returns Validated FireForgeState
+ */
+export function validateFireForgeState(data) {
+    const result = sanitizeProjectState(data);
+    if (result.issues.length > 0) {
+        throw new ConfigError(`Invalid FireForge state: ${result.issues.join('; ')}`);
+    }
+    return result.state;
+}
+async function recoverInvalidProjectState(statePath, result, alreadyLocked = false) {
+    const recover = async () => {
+        const quarantinedFile = await quarantineStateFile(statePath);
+        if (result.recoveredFields.length > 0) {
+            await writeJson(statePath, result.state);
+        }
+        const quarantineMessage = quarantinedFile
+            ? ` Quarantined the original file as ${quarantinedFile}.`
+            : '';
+        const recoveryMessage = result.recoveredFields.length > 0
+            ? ` Recovered valid field${result.recoveredFields.length === 1 ? '' : 's'}: ${result.recoveredFields.join(', ')}.`
+            : ' No valid state fields could be recovered; using defaults.';
+        warn(`State file (.fireforge/state.json) was invalid: ${result.issues.join('; ')}.${recoveryMessage}${quarantineMessage} ` +
+            'Run "fireforge doctor" to check project health.');
+        return result.state;
+    };
+    return alreadyLocked ? recover() : withStateFileLock(statePath, recover);
+}
+async function loadStateFromPath(statePath, alreadyLocked = false) {
+    if (!(await pathExists(statePath))) {
+        return {};
+    }
+    try {
+        const data = await readJson(statePath);
+        const result = sanitizeProjectState(data);
+        if (result.issues.length === 0) {
+            return result.state;
+        }
+        return await recoverInvalidProjectState(statePath, result, alreadyLocked);
+    }
+    catch (error) {
+        return await recoverInvalidProjectState(statePath, {
+            state: {},
+            issues: [`the file could not be parsed: ${toError(error).message}`],
+            recoveredFields: [],
+        }, alreadyLocked);
+    }
+}
+/**
+ * Loads the fireforge state, or returns defaults if it doesn't exist.
+ * @param root - Root directory of the project
+ * @returns FireForge state
+ */
+export async function loadState(root) {
+    const paths = getProjectPaths(root);
+    return loadStateFromPath(paths.state);
+}
+/**
+ * Saves the fireforge state.
+ * @param root - Root directory of the project
+ * @param state - State to save
+ */
+export async function saveState(root, state) {
+    const paths = getProjectPaths(root);
+    const validatedState = validateFireForgeState(state);
+    await withStateFileLock(paths.state, async () => {
+        await writeJson(paths.state, validatedState);
+    });
+}
+/**
+ * Updates specific fields in the fireforge state.
+ * @param root - Root directory of the project
+ * @param updates - Fields to update, or a transactional updater function
+ */
+export async function updateState(root, updates) {
+    const paths = getProjectPaths(root);
+    await withStateFileLock(paths.state, async () => {
+        const current = await loadStateFromPath(paths.state, true);
+        const nextState = typeof updates === 'function' ? updates(current) : { ...current, ...updates };
+        await writeJson(paths.state, validateFireForgeState(nextState));
+    });
+}
+//# sourceMappingURL=config-state.js.map

package/dist/src/core/config-validate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Config schema validation for fireforge.json.
+ */
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Validates a raw config object and returns a typed FireForgeConfig.
+ * @param data - Raw data to validate
+ * @returns Validated FireForgeConfig
+ * @throws Error if validation fails
+ */
+export declare function validateConfig(data: unknown): FireForgeConfig;

package/dist/src/core/config-validate.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Config schema validation for fireforge.json.
+ */
+import { ConfigError } from '../errors/config.js';
+import { verbose } from '../utils/logger.js';
+import { parseObject } from '../utils/parse.js';
+import { isContainedRelativePath } from '../utils/paths.js';
+import { isValidAppId, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
+import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
+/**
+ * Validates a raw config object and returns a typed FireForgeConfig.
+ * @param data - Raw data to validate
+ * @returns Validated FireForgeConfig
+ * @throws Error if validation fails
+ */
+export function validateConfig(data) {
+    let rec;
+    try {
+        rec = parseObject(data, 'Config');
+    }
+    catch {
+        throw new ConfigError('Config must be an object');
+    }
+    // Required string fields
+    const name = requireConfigString(rec, 'name');
+    const vendor = requireConfigString(rec, 'vendor');
+    const appId = requireConfigString(rec, 'appId');
+    const binaryName = requireConfigString(rec, 'binaryName');
+    if (binaryName.includes('..') || binaryName.includes('/') || binaryName.includes('\\')) {
+        throw new ConfigError('Config field "binaryName" must not contain path separators or ".."');
+    }
+    if (!isValidAppId(appId)) {
+        throw new ConfigError('Config field "appId" must be a valid reverse-domain identifier (e.g., "org.example.browser")');
+    }
+    // Firefox config
+    let firefoxRec;
+    try {
+        firefoxRec = rec.object('firefox');
+    }
+    catch {
+        throw new ConfigError('Config field "firefox" must be an object');
+    }
+    const firefoxVersion = requireConfigString(firefoxRec, 'version', 'firefox.version');
+    if (!isValidFirefoxVersion(firefoxVersion)) {
+        throw new ConfigError('Config field "firefox.version" must be a valid Firefox version (e.g., "145.0")');
+    }
+    const firefoxProduct = requireConfigString(firefoxRec, 'product', 'firefox.product');
+    const validProducts = ['firefox', 'firefox-esr', 'firefox-beta'];
+    if (!validProducts.includes(firefoxProduct)) {
+        throw new ConfigError(`Config field "firefox.product" must be one of: ${validProducts.join(', ')}`);
+    }
+    // Cross-field validation: product and version must be compatible
+    const compatError = validateFirefoxProductVersionCompatibility(firefoxVersion, firefoxProduct);
+    if (compatError) {
+        throw new ConfigError(compatError);
+    }
+    // Optional configs
+    const config = {
+        name,
+        vendor,
+        appId,
+        binaryName,
+        firefox: {
+            version: firefoxVersion,
+            product: firefoxProduct,
+        },
+    };
+    // Build
+    const buildRec = optionalConfigObject(rec, 'build');
+    if (buildRec) {
+        config.build = {};
+        const jobs = buildRec.raw('jobs');
+        if (jobs !== undefined) {
+            if (typeof jobs !== 'number' || !Number.isInteger(jobs) || jobs <= 0) {
+                throw new ConfigError('Config field "build.jobs" must be a positive integer');
+            }
+            config.build.jobs = jobs;
+        }
+    }
+    // Wire
+    const wireRec = optionalConfigObject(rec, 'wire');
+    if (wireRec) {
+        config.wire = {};
+        const subscriptDir = optionalConfigString(wireRec, 'subscriptDir', 'wire.subscriptDir');
+        if (subscriptDir !== undefined) {
+            if (!isContainedRelativePath(subscriptDir)) {
+                throw new ConfigError('Config field "wire.subscriptDir" must stay within engine/');
+            }
+            config.wire.subscriptDir = subscriptDir;
+        }
+    }
+    // License
+    const licenseRaw = rec.raw('license');
+    if (licenseRaw !== undefined) {
+        if (typeof licenseRaw !== 'string') {
+            throw new ConfigError('Config field "license" must be a string');
+        }
+        if (!isValidProjectLicense(licenseRaw)) {
+            throw new ConfigError(`Config field "license" must be one of: ${PROJECT_LICENSES.join(', ')}`);
+        }
+        config.license = licenseRaw;
+    }
+    // Warn on unknown root keys
+    const knownRootKeys = new Set(SUPPORTED_CONFIG_ROOT_KEYS);
+    for (const key of rec.keys()) {
+        if (!knownRootKeys.has(key)) {
+            verbose(`Unknown config key "${key}" in fireforge.json — it will be ignored.`);
+        }
+    }
+    return config;
+}
+// ── Internal helpers (wrap parseObject errors with ConfigError) ──
+function requireConfigString(rec, key, label) {
+    const value = rec.raw(key);
+    if (typeof value !== 'string') {
+        throw new ConfigError(`Config field "${label ?? key}" must be a string`);
+    }
+    return value;
+}
+function optionalConfigString(rec, key, label) {
+    const value = rec.raw(key);
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new ConfigError(`Config field "${label}" must be a string`);
+    }
+    return value;
+}
+function optionalConfigObject(rec, key) {
+    const value = rec.raw(key);
+    if (value === undefined)
+        return undefined;
+    try {
+        return rec.object(key);
+    }
+    catch {
+        throw new ConfigError(`Config field "${key}" must be an object`);
+    }
+}
+//# sourceMappingURL=config-validate.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * Project configuration — barrel module.
+ *
+ * Re-exports from focused sub-modules:
+ *   config-paths.ts    — constants and project path derivation
+ *   config-validate.ts — fireforge.json schema validation
+ *   config-mutate.ts   — immutable config mutation
+ *   config-state.ts    — state file management
+ */
+import type { FireForgeConfig } from '../types/config.js';
+export { mutateConfig } from './config-mutate.js';
+export { CONFIG_FILENAME, CONFIGS_DIR, ENGINE_DIR, FIREFORGE_DIR, getProjectPaths, PATCHES_DIR, SRC_DIR, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, saveState, updateState, validateFireForgeState } from './config-state.js';
+export { validateConfig } from './config-validate.js';
+/**
+ * Checks if a fireforge.json exists in the given directory.
+ * @param root - Root directory to check
+ * @returns True if fireforge.json exists
+ */
+export declare function configExists(root: string): Promise<boolean>;
+/**
+ * Loads and validates the fireforge.json configuration.
+ * @param root - Root directory of the project
+ * @returns Validated FireForgeConfig
+ * @throws Error if config doesn't exist or is invalid
+ */
+export declare function loadConfig(root: string): Promise<FireForgeConfig>;
+/**
+ * Writes a configuration to fireforge.json.
+ * @param root - Root directory of the project
+ * @param config - Configuration to write
+ */
+export declare function writeConfig(root: string, config: FireForgeConfig): Promise<void>;
+/**
+ * Writes a raw config document to fireforge.json.
+ * This is used by CLI `config --force`, where callers may intentionally write
+ * keys or value shapes outside the validated FireForgeConfig schema.
+ */
+export declare function writeConfigDocument(root: string, config: FireForgeConfig | Record<string, unknown>): Promise<void>;

package/dist/src/core/config.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Project configuration — barrel module.
+ *
+ * Re-exports from focused sub-modules:
+ *   config-paths.ts    — constants and project path derivation
+ *   config-validate.ts — fireforge.json schema validation
+ *   config-mutate.ts   — immutable config mutation
+ *   config-state.ts    — state file management
+ */
+import { ConfigError, ConfigNotFoundError } from '../errors/config.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { getProjectPaths } from './config-paths.js';
+import { validateConfig } from './config-validate.js';
+// ---- re-exports ----
+export { mutateConfig } from './config-mutate.js';
+export { CONFIG_FILENAME, CONFIGS_DIR, ENGINE_DIR, FIREFORGE_DIR, getProjectPaths, PATCHES_DIR, SRC_DIR, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, saveState, updateState, validateFireForgeState } from './config-state.js';
+export { validateConfig } from './config-validate.js';
+// ---- config I/O (stays here because it bridges paths + validation) ----
+/**
+ * Checks if a fireforge.json exists in the given directory.
+ * @param root - Root directory to check
+ * @returns True if fireforge.json exists
+ */
+export async function configExists(root) {
+    const paths = getProjectPaths(root);
+    return pathExists(paths.config);
+}
+/**
+ * Loads and validates the fireforge.json configuration.
+ * @param root - Root directory of the project
+ * @returns Validated FireForgeConfig
+ * @throws Error if config doesn't exist or is invalid
+ */
+export async function loadConfig(root) {
+    const paths = getProjectPaths(root);
+    if (!(await pathExists(paths.config))) {
+        throw new ConfigNotFoundError(paths.config);
+    }
+    try {
+        const data = await readJson(paths.config);
+        return validateConfig(data);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            throw error;
+        }
+        throw new ConfigError(`Invalid fireforge.json at ${paths.config}: ${toError(error).message}`);
+    }
+}
+/**
+ * Writes a configuration to fireforge.json.
+ * @param root - Root directory of the project
+ * @param config - Configuration to write
+ */
+export async function writeConfig(root, config) {
+    await writeConfigDocument(root, config);
+}
+/**
+ * Writes a raw config document to fireforge.json.
+ * This is used by CLI `config --force`, where callers may intentionally write
+ * keys or value shapes outside the validated FireForgeConfig schema.
+ */
+export async function writeConfigDocument(root, config) {
+    const paths = getProjectPaths(root);
+    await writeJson(paths.config, config);
+}
+//# sourceMappingURL=config.js.map

package/dist/src/core/file-lock.d.ts

@@ -0,0 +1,11 @@
+export interface FileLockOptions {
+    timeoutMs?: number;
+    pollMs?: number;
+    staleMs?: number;
+    onTimeoutMessage?: string;
+    onStaleLockMessage?: (ageMs: number) => string | undefined;
+}
+/** Derives the sibling lock-directory path used to guard a file-based resource. */
+export declare function createSiblingLockPath(filePath: string, suffix?: string): string;
+/** Runs an async operation while holding a directory lock, with stale-lock recovery. */
+export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/src/core/file-lock.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { mkdir, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { ensureDir } from '../utils/fs.js';
+import { verbose, warn } from '../utils/logger.js';
+const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
+const DEFAULT_LOCK_POLL_MS = 50;
+const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Derives the sibling lock-directory path used to guard a file-based resource. */
+export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
+    return `${filePath}${suffix}`;
+}
+async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
+    try {
+        const lockStat = await stat(lockPath);
+        const ageMs = Date.now() - lockStat.mtimeMs;
+        if (ageMs <= staleMs) {
+            return false;
+        }
+        const staleMessage = onStaleLockMessage?.(ageMs);
+        if (staleMessage) {
+            warn(staleMessage);
+        }
+        await rm(lockPath, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        verbose(`Stale lock check failed for ${lockPath}: ${toError(error).message}`);
+        return true;
+    }
+}
+/** Runs an async operation while holding a directory lock, with stale-lock recovery. */
+export async function withFileLock(lockPath, operation, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+    const pollMs = options.pollMs ?? DEFAULT_LOCK_POLL_MS;
+    const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
+    const deadline = Date.now() + timeoutMs;
+    let attemptedStaleRecovery = false;
+    await ensureDir(dirname(lockPath));
+    for (;;) {
+        try {
+            await mkdir(lockPath);
+            break;
+        }
+        catch (error) {
+            const isAlreadyLocked = typeof error === 'object' &&
+                error !== null &&
+                'code' in error &&
+                typeof error.code === 'string' &&
+                error.code === 'EEXIST';
+            if (!isAlreadyLocked) {
+                throw error;
+            }
+            if (!attemptedStaleRecovery) {
+                attemptedStaleRecovery = true;
+                if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(options.onTimeoutMessage ??
+                    `Timed out waiting for file lock ${lockPath}. Remove the lock directory if it is stale.`, { cause: error });
+            }
+            await sleep(pollMs);
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        await rm(lockPath, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=file-lock.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * Archive metadata validation and archive identity resolution.
+ */
+import type { FirefoxProduct } from '../types/config.js';
+/**
+ * Resolved archive descriptor for URL generation and cache storage.
+ */
+export interface ResolvedArchive {
+    requestedVersion: string;
+    product: FirefoxProduct;
+    archiveVersion: string;
+    url: string;
+    filename: string;
+    metadataFilename: string;
+}
+/**
+ * Sidecar metadata stored alongside a cached archive.
+ */
+export interface ArchiveMetadata {
+    requestedVersion: string;
+    product: FirefoxProduct;
+    archiveVersion: string;
+    url: string;
+    contentLength?: number | undefined;
+    sha256?: string | undefined;
+    downloadedAt: string;
+}
+/**
+ * Validates raw JSON data as ArchiveMetadata.
+ * @param data - Unknown data to validate
+ * @returns Validated ArchiveMetadata
+ */
+export declare function validateArchiveMetadata(data: unknown): ArchiveMetadata;
+/**
+ * Resolves archive identity for URL generation and cache storage.
+ * @param version - Requested Firefox version
+ * @param product - Firefox product type
+ * @returns Resolved archive descriptor
+ */
+export declare function resolveArchive(version: string, product?: FirefoxProduct): ResolvedArchive;

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

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Archive metadata validation and archive identity resolution.
+ */
+import { ConfigError } from '../errors/config.js';
+import { parseObject } from '../utils/parse.js';
+import { isValidFirefoxProduct } from '../utils/validation.js';
+/**
+ * Base URL for Firefox releases on archive.mozilla.org.
+ */
+const ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox/releases';
+/**
+ * Validates raw JSON data as ArchiveMetadata.
+ * @param data - Unknown data to validate
+ * @returns Validated ArchiveMetadata
+ */
+export function validateArchiveMetadata(data) {
+    const rec = parseObject(data, 'Archive metadata');
+    const requestedVersion = rec.string('requestedVersion');
+    const product = rec.stringEnum('product', (v) => isValidFirefoxProduct(v), 'a supported Firefox product');
+    const archiveVersion = rec.string('archiveVersion');
+    const url = rec.string('url');
+    const downloadedAt = rec.string('downloadedAt');
+    const contentLength = rec.optionalNonNegativeInteger('contentLength');
+    const sha256 = rec.optionalString('sha256');
+    return {
+        requestedVersion,
+        product,
+        archiveVersion,
+        url,
+        downloadedAt,
+        ...(contentLength !== undefined ? { contentLength } : {}),
+        ...(sha256 !== undefined ? { sha256 } : {}),
+    };
+}
+/**
+ * Resolves archive identity for URL generation and cache storage.
+ * @param version - Requested Firefox version
+ * @param product - Firefox product type
+ * @returns Resolved archive descriptor
+ */
+export function resolveArchive(version, product = 'firefox') {
+    // Reject versions containing path traversal characters
+    if (version.includes('/') || version.includes('..') || version.includes('\\')) {
+        throw new ConfigError(`Invalid Firefox version "${version}": contains disallowed characters`, 'firefox.version');
+    }
+    // ESR status is determined solely by the product field. Config validation
+    // ensures product and version are consistent, so we never need to infer
+    // ESR from the version string independently.
+    const cleanVersion = version.replace(/esr$/i, '');
+    const isEsr = product === 'firefox-esr';
+    const archiveVersion = isEsr ? `${cleanVersion}esr` : cleanVersion;
+    const safeProduct = product.replace(/[^a-z0-9-]/gi, '-');
+    return {
+        requestedVersion: version,
+        product,
+        archiveVersion,
+        url: `${ARCHIVE_BASE_URL}/${archiveVersion}/source/firefox-${archiveVersion}.source.tar.xz`,
+        filename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz`,
+        metadataFilename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz.json`,
+    };
+}
+//# sourceMappingURL=firefox-archive.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * Cache validation, invalidation, and download-to-cache logic.
+ */
+import type { ResolvedArchive } from './firefox-archive.js';
+import type { ProgressCallback } from './firefox-download.js';
+/**
+ * Computes the SHA-256 hex digest of a file.
+ * @param filePath - Path to the file
+ */
+export declare function sha256File(filePath: string): Promise<string>;
+/**
+ * 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 declare function ensureCachedArchive(archive: ResolvedArchive, cacheDir: string, onProgress?: ProgressCallback): Promise<void>;
+/**
+ * Removes cached tarball, metadata, and partial download files for an archive.
+ * @param archive - Resolved archive descriptor
+ * @param cacheDir - Cache directory
+ */
+export declare function invalidateArchiveCache(archive: ResolvedArchive, cacheDir: string): Promise<void>;