@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,248 +0,0 @@
-// 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 { elapsedSince } from '../utils/elapsed.js';
-import { ensureDir, pathExists, readText } from '../utils/fs.js';
-import { exec, execStream, executableExists } from '../utils/process.js';
-/**
- * Returns true when an archive member path could land outside the
- * extraction root: absolute (POSIX or Windows drive/backslash rooted) or
- * containing a `..` segment.
- */
-function isUnsafeArchivePath(path) {
-    if (path.startsWith('/') || path.startsWith('\\'))
-        return true;
-    if (/^[A-Za-z]:[\\/]/.test(path))
-        return true;
-    return path.split(/[\\/]/).includes('..');
-}
-/**
- * Returns true when an archive member path has a `.git` segment at any
- * depth (`.git`, `.git/config`, `foo/.git/hooks/pre-commit`). Such a member
- * lands inside the extraction root, so the traversal check passes it, but
- * the extracted tree is immediately turned into a git repository and
- * committed, and git honours a pre-seeded `.git/config` (`core.fsmonitor`,
- * `core.hooksPath`) or `.git/hooks/*` on that first commit. Only the `.git`
- * directory/file is rejected. `.gitmodules`, `.gitignore` and the like are
- * legitimate upstream files.
- */
-function hasGitSegment(path) {
-    return path.split(/[\\/]/).some((segment) => segment.toLowerCase() === '.git');
-}
-/**
- * Returns true when an archive member name must be rejected: an escaping
- * path, or a `.git` segment (see {@link hasGitSegment}). Link targets use
- * the narrower {@link isUnsafeArchivePath}: a target can only be reached
- * through a member name that was checked here.
- */
-function isUnsafeArchiveMemberName(name) {
-    return isUnsafeArchivePath(name) || hasGitSegment(name);
-}
-/**
- * Validates entry names from a `tar -tf` listing: escaping paths and
- * `.git` members are both rejected.
- * @param names - Listing lines (one member name per line)
- * @returns The first unsafe member name, or undefined when all are safe
- */
-export function findUnsafeArchiveEntryName(names) {
-    for (const raw of names) {
-        const name = raw.trim();
-        if (name.length === 0)
-            continue;
-        if (isUnsafeArchiveMemberName(name))
-            return name;
-    }
-    return undefined;
-}
-/**
- * Validates symlink and hardlink targets from a `tar -tvf` listing.
- *
- * A relative link target without `..` segments can only resolve inside the
- * extraction root, so only absolute or `..`-containing targets are rejected.
- * Symlinks are `l`-typed lines with a ` -> target` suffix (the last arrow is
- * taken, so a link whose own name contains ` -> ` still parses to its real
- * target). Hardlinks print ` link to target` on GNU tar and bsdtar alike.
- *
- * @param verboseLines - `tar -tvf` listing lines
- * @returns A description of the first unsafe link found, or undefined
- */
-export function findUnsafeArchiveLink(verboseLines) {
-    for (const line of verboseLines) {
-        if (line.startsWith('l')) {
-            const arrow = line.lastIndexOf(' -> ');
-            if (arrow !== -1) {
-                const target = line.slice(arrow + 4).trim();
-                if (isUnsafeArchivePath(target))
-                    return `symlink target: ${target}`;
-                continue;
-            }
-        }
-        const hardlink = line.lastIndexOf(' link to ');
-        if (hardlink !== -1) {
-            const target = line.slice(hardlink + 9).trim();
-            if (isUnsafeArchivePath(target))
-                return `hardlink target: ${target}`;
-        }
-    }
-    return undefined;
-}
-/**
- * Lists the archive and rejects members that could escape the extraction
- * root before anything is written to disk: absolute names, `..` traversal,
- * and symlink/hardlink targets that are absolute or `..`-escaping. Modern
- * GNU tar / bsdtar refuse most of these at extraction time. The preflight
- * makes the guarantee explicit and independent of the host tar's defaults.
- *
- * Two listings are needed because they answer different questions and
- * neither is safe to derive from the other: member names come from `-tf`,
- * where the whole line is the name, while link targets only appear in
- * `-tvf`. Names are not parsed out of the `-tvf` columns, on purpose: the
- * adjacent uname/gname fields are attacker-controlled in a crafted archive,
- * so a date-shaped owner name could shift the column boundary and hide an
- * absolute member name from the check. Each listing pass costs one full
- * decompression, so the two run concurrently and overlap almost perfectly
- * (CPU-bound on separate cores): on a 601 MB Firefox ESR source tarball the
- * preflight adds ~22 s to a ~58 s extraction, versus ~44 s if run
- * sequentially.
- */
-/**
- * Incremental line splitter for streamed listings. Keeps only the current
- * partial line in memory, so a 350k-entry Firefox listing costs O(longest
- * line), not O(listing).
- */
-function createLineScanner(onLine) {
-    let buffer = '';
-    return {
-        push(chunk) {
-            buffer += chunk;
-            let idx;
-            while ((idx = buffer.indexOf('\n')) !== -1) {
-                onLine(buffer.slice(0, idx));
-                buffer = buffer.slice(idx + 1);
-            }
-        },
-        flush() {
-            if (buffer.length > 0) {
-                onLine(buffer);
-                buffer = '';
-            }
-        },
-    };
-}
-/**
- * Runs one tar listing pass, streaming lines through `checkLine` and
- * returning the first unsafe finding (or undefined) plus the exit code.
- *
- * Streaming matters for safety, not just memory: a buffered `exec` collector
- * silently truncates at 50 MB, and a full Firefox `-tvf` listing already
- * sits in the 40-50 MB range, so a buffered implementation scans only the
- * head of the listing while reporting the archive safe. A crafted archive
- * could exploit that by padding benign entries first and hiding a
- * traversal name or absolute link target past the cap. Per-line streaming
- * scans every entry with bounded memory.
- */
-async function runListingScan(archivePath, tarFlag, checkLine) {
-    // LC_ALL=C keeps the -tvf column format stable for the link parse.
-    const listEnv = { LC_ALL: 'C', LANG: 'C' };
-    let unsafe;
-    let stderrTail = '';
-    const scanner = createLineScanner((line) => {
-        if (unsafe === undefined) {
-            unsafe = checkLine(line);
-        }
-    });
-    const exitCode = await execStream('tar', [tarFlag, archivePath], {
-        env: listEnv,
-        onStdout: (chunk) => {
-            scanner.push(chunk);
-        },
-        onStderr: (chunk) => {
-            // Keep a small diagnostic tail. The listing itself is the big stream.
-            stderrTail = (stderrTail + chunk).slice(-4096);
-        },
-    });
-    scanner.flush();
-    return { unsafe, exitCode, stderrTail };
-}
-async function preflightArchiveEntries(archivePath) {
-    const [nameScan, linkScan] = await Promise.all([
-        runListingScan(archivePath, '-tf', (line) => findUnsafeArchiveEntryName([line])),
-        runListingScan(archivePath, '-tvf', (line) => findUnsafeArchiveLink([line])),
-    ]);
-    if (nameScan.exitCode !== 0) {
-        throw new ExtractionError(archivePath, new Error(`tar -tf preflight exited with code ${nameScan.exitCode}:\n${nameScan.stderrTail}`));
-    }
-    if (nameScan.unsafe !== undefined) {
-        throw new ExtractionError(archivePath, new Error(`Archive rejected: member name could escape the extraction root or seed .git: ${nameScan.unsafe}`));
-    }
-    if (linkScan.exitCode !== 0) {
-        throw new ExtractionError(archivePath, new Error(`tar -tvf preflight exited with code ${linkScan.exitCode}:\n${linkScan.stderrTail}`));
-    }
-    if (linkScan.unsafe !== undefined) {
-        throw new ExtractionError(archivePath, new Error(`Archive rejected: link could escape the extraction root (${linkScan.unsafe})`));
-    }
-}
-/**
- * Extracts a tar.xz archive after a listing preflight that rejects
- * path-traversal member names and escaping link targets.
- * @param archivePath - Path to the archive
- * @param destDir - Destination directory
- */
-export async function extractTarXz(archivePath, destDir, onProgress) {
-    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 startedAt = Date.now();
-    onProgress?.(`Validating source archive entries (${elapsedSince(startedAt)} elapsed)...`);
-    const heartbeat = onProgress
-        ? setInterval(() => {
-            onProgress(`Extracting source archive (${elapsedSince(startedAt)} elapsed)...`);
-        }, 15_000)
-        : null;
-    heartbeat?.unref();
-    try {
-        await preflightArchiveEntries(archivePath);
-        onProgress?.(`Extracting source archive (${elapsedSince(startedAt)} elapsed)...`);
-        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}`));
-        }
-    }
-    finally {
-        if (heartbeat)
-            clearInterval(heartbeat);
-    }
-    onProgress?.(`Source archive extracted (${elapsedSince(startedAt)} elapsed)`);
-}
-/**
- * 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 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]}`;
-}

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

@@ -1,17 +0,0 @@
-/**
- * Result of normalizing Firefox's Mercurial ignore file for Git-backed
- * checkouts.
- */
-export type FirefoxIgnorefileCompatibilityResult = 'created' | 'existing' | 'skipped';
-/**
- * Ensures Firefox's mozlint ignorefile configuration can be parsed in
- * Git-backed source trees.
- *
- * Firefox's `tools/lint/ignorefile.yml` includes both `.gitignore` and
- * `.hgignore`. Source archives and some Git mirrors may omit `.hgignore`,
- * which makes `mach lint --fix <files>` fail before it reaches the scoped
- * linter. For FireForge-managed Git checkouts, copying `.gitignore` gives
- * mozlint the missing include and keeps the ignorefile linter's pattern
- * comparison equivalent without patching upstream lint configuration.
- */
-export declare function ensureFirefoxIgnorefileCompatibility(engineDir: string): Promise<FirefoxIgnorefileCompatibilityResult>;

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

@@ -1,30 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { pathExists, readText, writeText } from '../utils/fs.js';
-/**
- * Ensures Firefox's mozlint ignorefile configuration can be parsed in
- * Git-backed source trees.
- *
- * Firefox's `tools/lint/ignorefile.yml` includes both `.gitignore` and
- * `.hgignore`. Source archives and some Git mirrors may omit `.hgignore`,
- * which makes `mach lint --fix <files>` fail before it reaches the scoped
- * linter. For FireForge-managed Git checkouts, copying `.gitignore` gives
- * mozlint the missing include and keeps the ignorefile linter's pattern
- * comparison equivalent without patching upstream lint configuration.
- */
-export async function ensureFirefoxIgnorefileCompatibility(engineDir) {
-    const lintConfigPath = join(engineDir, 'tools', 'lint', 'ignorefile.yml');
-    if (!(await pathExists(lintConfigPath))) {
-        return 'skipped';
-    }
-    const hgignorePath = join(engineDir, '.hgignore');
-    if (await pathExists(hgignorePath)) {
-        return 'existing';
-    }
-    const gitignorePath = join(engineDir, '.gitignore');
-    if (!(await pathExists(gitignorePath))) {
-        return 'skipped';
-    }
-    await writeText(hgignorePath, await readText(gitignorePath));
-    return 'created';
-}

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

@@ -1,66 +0,0 @@
-/**
- * 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 { ArchiveIntegrityOptions } from './firefox-cache.js';
-import type { ProgressCallback } from './firefox-download.js';
-export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
-/**
- * Lifecycle phase reported by {@link downloadFirefoxSource}. The download
- * CLI command uses this to swap spinners between the bytes-on-the-wire phase
- * and the silent tar-xz decompression phase that follows: a single spinner
- * covering both sticks at "Downloading Firefox … 100%" and makes first-run
- * setup look hung precisely when the archive is already on disk and `tar` is
- * the long pole.
- */
-export type FirefoxSourcePhase = 'download' | 'extract';
-/** Callback fired at phase transitions during {@link downloadFirefoxSource}. */
-export type FirefoxSourcePhaseCallback = (phase: FirefoxSourcePhase) => void;
-export type FirefoxSourceProgressCallback = (message: string) => void;
-/**
- * Sweeps orphaned working directories left behind by interrupted downloads
- * (`<engine>.tmp-*` from extraction, `<engine>.replacement-*` from --force
- * replacement). Both hold multi-GB partial trees, are worthless after the
- * owning process died, and nothing else ever reclaimed them. Does not
- * touch `<engine>.backup-*`: a backup may hold the operator's previous
- * engine after a failed forced replacement and is their recovery copy, so
- * callers should surface its existence instead.
- *
- * @returns names of the directories that were removed
- */
-export declare function sweepOrphanedEngineWorkDirs(destDir: string): Promise<string[]>;
-/** Inputs for {@link downloadFirefoxSource}. */
-export interface DownloadFirefoxSourceOptions {
-    /** Firefox version to fetch, e.g. `140.9.0esr`. */
-    version: string;
-    /** Product channel the version belongs to. */
-    product: FirefoxProduct;
-    /** Directory the extracted source tree is moved into. */
-    destDir: string;
-    /** Directory holding downloaded tarballs between runs. */
-    cacheDir: string;
-    /** Called with byte progress for the whole transfer. */
-    onProgress?: ProgressCallback | undefined;
-    /** Called when the run moves from downloading to extracting. */
-    onPhase?: FirefoxSourcePhaseCallback | undefined;
-    /** Expected archive checksum, verified after download when supplied. */
-    expectedSha256?: string | undefined;
-    /** Called with byte progress within the current phase. */
-    onPhaseProgress?: FirefoxSourceProgressCallback | undefined;
-    /**
-     * Release-candidate build directory (e.g. `build2`), resolving the archive
-     * under `candidates/` instead of `releases/`.
-     */
-    candidate?: string | undefined;
-    /** Integrity-check defaults for unpinned downloads. */
-    integrity?: ArchiveIntegrityOptions | undefined;
-}
-/**
- * Downloads and extracts Firefox source.
- *
- * @param options - See {@link DownloadFirefoxSourceOptions}.
- */
-export declare function downloadFirefoxSource(options: DownloadFirefoxSourceOptions): Promise<void>;

package/dist/src/core/firefox.js

@@ -1,121 +0,0 @@
-// 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 { readdir, rename } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-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 { formatBytes, getFirefoxVersion } from './firefox-extract.js';
-/**
- * Classifies an extraction failure as archive corruption (invalidate the
- * cache and re-download) versus an environmental problem (keep the cached
- * archive so the retry can reuse it). Environmental signatures are the
- * conservative list. Anything unrecognized is treated as corruption so a
- * genuinely bad archive can never survive in the cache.
- */
-function isLikelyArchiveCorruptionError(error) {
-    const message = toError(error).message;
-    const code = getNodeErrorCode(error);
-    if (code === 'ENOSPC' || code === 'EACCES' || code === 'EPERM' || code === 'EDQUOT') {
-        return false;
-    }
-    if (/No space left on device|Permission denied|Disk quota exceeded/i.test(message)) {
-        return false;
-    }
-    // Missing tar binary / preflight refusing an unsafe archive both carry
-    // ExtractionError text that names the condition. A missing tar is
-    // environmental, an unsafe-entry rejection indicts the archive.
-    if (/"tar" command was not found/i.test(message)) {
-        return false;
-    }
-    return true;
-}
-/**
- * Sweeps orphaned working directories left behind by interrupted downloads
- * (`<engine>.tmp-*` from extraction, `<engine>.replacement-*` from --force
- * replacement). Both hold multi-GB partial trees, are worthless after the
- * owning process died, and nothing else ever reclaimed them. Does not
- * touch `<engine>.backup-*`: a backup may hold the operator's previous
- * engine after a failed forced replacement and is their recovery copy, so
- * callers should surface its existence instead.
- *
- * @returns names of the directories that were removed
- */
-export async function sweepOrphanedEngineWorkDirs(destDir) {
-    const parent = dirname(destDir);
-    const enginePrefixTmp = `${basename(destDir)}.tmp-`;
-    const enginePrefixReplacement = `${basename(destDir)}.replacement-`;
-    let entries;
-    try {
-        entries = await readdir(parent);
-    }
-    catch {
-        // An unreadable parent directory holds no sweepable work dirs. The sweep is
-        // best-effort housekeeping and must never fail the download it follows.
-        return [];
-    }
-    const removed = [];
-    for (const name of entries) {
-        if (name.startsWith(enginePrefixTmp) || name.startsWith(enginePrefixReplacement)) {
-            await removeDir(join(parent, name));
-            removed.push(name);
-        }
-    }
-    return removed;
-}
-/**
- * Downloads and extracts Firefox source.
- *
- * @param options - See {@link DownloadFirefoxSourceOptions}.
- */
-export async function downloadFirefoxSource(options) {
-    const { version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress, candidate, integrity, } = options;
-    const archive = resolveArchive(version, product, candidate);
-    const tarballPath = join(cacheDir, archive.filename);
-    // Ensure cache directory exists
-    await ensureDir(cacheDir);
-    onPhase?.('download');
-    await ensureCachedArchive(archive, cacheDir, onProgress, expectedSha256, onPhaseProgress, integrity);
-    // Extract to a unique temporary directory so concurrent downloads for
-    // the same destination do not clobber each other.
-    onPhase?.('extract');
-    const tempDir = `${destDir}.tmp-${randomUUID()}`;
-    try {
-        await extractTarXz(tarballPath, tempDir, onPhaseProgress);
-    }
-    catch (error) {
-        await removeDir(tempDir);
-        // Only throw away the ~600 MB cached archive when the failure indicts
-        // the archive, not the environment. ENOSPC, a permission problem in
-        // destDir, or tar disappearing mid-run leaves a perfectly good download
-        // that a retry can reuse without a full re-fetch.
-        if (isLikelyArchiveCorruptionError(error)) {
-            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 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);
-    }
-}

package/dist/src/core/forward-registrations.d.ts

@@ -1,33 +0,0 @@
-/**
- * Public, queue-level entry point to the `forward-registration` census.
- *
- * A consumer that keeps its own audit (a ratchet baseline over forward
- * edges, say) runs the rule's own predicate here instead of mirroring it.
- * Lives apart from the rule module because it builds the queue context,
- * which imports the rule back.
- */
-import type { FireForgeConfig } from '../types/config.js';
-import type { ForwardRegistration, ForwardRegistrationScope } from './patch-lint-forward-registration-extended.js';
-/** Options for {@link findForwardRegistrations}. */
-export interface FindForwardRegistrationsOptions {
-    /**
-     * Which carriers to check. Defaults to `'extended'` (every carrier the
-     * rule can resolve), since a census wants the whole picture whatever the
-     * lint gate is configured to enforce.
-     */
-    scope?: ForwardRegistrationScope;
-    /** Project config, for the queue's patchPolicy ordering context. Optional. */
-    config?: FireForgeConfig;
-}
-/**
- * Lists every undeclared forward registration in a patch queue: a line a
- * patch adds (to a test manifest, jar.mn, moz.build or customElements.js)
- * that names a file only a later-ordered patch creates. Each record carries
- * the paste-and-run `patch staged-dependency` command that declares it.
- *
- * @param patchesDir - The project's `patches/` directory
- * @param options - Scope and optional config
- * @returns One record per (patch, carrier file, created file)
- */
-export declare function findForwardRegistrations(patchesDir: string, options?: FindForwardRegistrationsOptions): Promise<ForwardRegistration[]>;
-export type { ForwardRegistration, ForwardRegistrationKind, ForwardRegistrationScope, } from './patch-lint-forward-registration-extended.js';

package/dist/src/core/forward-registrations.js

@@ -1,16 +0,0 @@
-import { buildPatchQueueContext } from './patch-lint-cross.js';
-import { collectForwardRegistrations } from './patch-lint-forward-registration.js';
-/**
- * Lists every undeclared forward registration in a patch queue: a line a
- * patch adds (to a test manifest, jar.mn, moz.build or customElements.js)
- * that names a file only a later-ordered patch creates. Each record carries
- * the paste-and-run `patch staged-dependency` command that declares it.
- *
- * @param patchesDir - The project's `patches/` directory
- * @param options - Scope and optional config
- * @returns One record per (patch, carrier file, created file)
- */
-export async function findForwardRegistrations(patchesDir, options = {}) {
-    const ctx = await buildPatchQueueContext(patchesDir, options.config);
-    return collectForwardRegistrations(ctx, options.scope ?? 'extended');
-}

package/dist/src/core/furnace-apply-dry-run.d.ts

@@ -1,12 +0,0 @@
-/**
- * Dry-run action planning for custom-component apply. Extracted from
- * `furnace-apply-helpers.ts` so the apply path and its dry-run mirror each
- * stay within the per-file line budget. Consumed only by that module.
- */
-import type { ComponentApplyContext, CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
-import { type DirectoryEntry } from './furnace-dir-entry.js';
-/** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
-export declare function buildCustomDryRunActions(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, config: CustomComponentConfig, targetDir: string, entries: DirectoryEntry[]): Promise<{
-    actions: DryRunAction[];
-    stepErrors: StepError[];
-}>;

package/dist/src/core/furnace-apply-dry-run.js

@@ -1,99 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Dry-run action planning for custom-component apply. Extracted from
- * `furnace-apply-helpers.ts` so the apply path and its dry-run mirror each
- * stay within the per-file line budget. Consumed only by that module.
- */
-import { join } from 'node:path';
-import { toError } from '../utils/errors.js';
-import { pathExists } from '../utils/fs.js';
-import { describeLocaleFtlJarMnRegistration, describeSharedFtlPrune } from './furnace-apply-ftl.js';
-import { describeFragmentExpansion } from './furnace-css-fragments.js';
-import { isRegularFile } from './furnace-dir-entry.js';
-import { validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
-/** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
-export async function buildCustomDryRunActions(ctx, config, targetDir, entries) {
-    const { engineDir, name, componentDir, ftlDir } = ctx;
-    const actions = [];
-    const stepErrors = [];
-    for (const entry of entries) {
-        if (!isRegularFile(entry))
-            continue;
-        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
-            continue;
-        const fragmentNote = await describeFragmentExpansion(join(componentDir, entry.name));
-        actions.push({
-            component: name,
-            action: fragmentNote ? 'expand-fragments' : 'copy',
-            source: join(componentDir, entry.name),
-            target: join(targetDir, entry.name),
-            description: `Copy ${entry.name} to ${config.targetPath}${fragmentNote}`,
-        });
-    }
-    // Per-component .ftl handling is skipped when the component opts into a
-    // shared feature-scoped bundle via `sharedFtl`. The shared file is
-    // registered (and copied) by whoever owns the feature bundle, so
-    // emitting a copy-ftl / register-jar action here would duplicate (or
-    // later orphan) the entry.
-    if (config.localized && !config.sharedFtl) {
-        const ftlFile = `${name}.ftl`;
-        const ftlSrc = join(componentDir, ftlFile);
-        if (await pathExists(ftlSrc)) {
-            actions.push({
-                component: name,
-                action: 'copy-ftl',
-                source: ftlSrc,
-                target: join(engineDir, ftlDir, ftlFile),
-                description: `Copy ${ftlFile} to ${ftlDir}`,
-            });
-            const localeAction = describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile);
-            if (localeAction) {
-                actions.push(localeAction);
-            }
-        }
-    }
-    // A sharedFtl widget owns its strings via the shared bundle. Surface the
-    // removal of any dangling per-widget locale jar.mn entry so the dry-run
-    // plan matches what apply will do (and explains the unblocked build).
-    const pruneAction = await describeSharedFtlPrune(ctx, config);
-    if (pruneAction) {
-        actions.push(pruneAction);
-    }
-    if (config.register) {
-        try {
-            const modulePath = `chrome://global/content/elements/${name}.mjs`;
-            await validateCustomElementRegistration(engineDir, name, modulePath);
-        }
-        catch (error) {
-            stepErrors.push({
-                step: 'customElements.js registration',
-                error: toError(error).message,
-            });
-        }
-        actions.push({
-            component: name,
-            action: 'register-ce',
-            description: `Register ${name} in customElements.js (DOMContentLoaded block)`,
-        });
-    }
-    const copiedFileNames = entries
-        .filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
-        .map((entry) => entry.name);
-    if (copiedFileNames.length > 0) {
-        try {
-            await validateJarMnInsertionForFiles(engineDir, name, copiedFileNames);
-        }
-        catch (error) {
-            stepErrors.push({
-                step: 'jar.mn registration',
-                error: toError(error).message,
-            });
-        }
-        actions.push({
-            component: name,
-            action: 'register-jar',
-            description: `Add ${copiedFileNames.join(', ')} to jar.mn`,
-        });
-    }
-    return { actions, stepErrors };
-}