@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/commands/re-export-lint.js

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Hoisted + cached lint context for `re-export` (FORGE J1).
+ *
+ * The per-patch loop used to rebuild the whole patch-queue context AND a
+ * fresh queue-wide checkJs TypeScript program for every patch — ~37 s of
+ * fixed setup per patch (measured on a 290-patch consumer queue), so an
+ * N-patch re-export cost N×37 s. This module:
+ *
+ * - builds the queue context and the {@link PerRunCheckJs} program
+ *   controller ONCE per invocation (`buildReExportLintContext`) and slices
+ *   per-patch findings out of it (the FORGE I3 shape `move-files`/`split`
+ *   already use, plus the program-level hoist `lint --per-patch` has);
+ * - reuses the existing per-patch lint RESULT cache
+ *   (`.fireforge/lint-cache/per-patch-v1.json`) across invocations —
+ *   re-export lints the identical input `lint --per-patch` does (the
+ *   fresh `git diff HEAD` of the owned files), and the key already
+ *   hashes engine HEAD, per-file content, patch body, config, shims, and
+ *   ownership, so a repeat single re-export is a warm hit (~4 s instead
+ *   of ~41 s). `--no-cache` opts out; run-level checkJs globals are
+ *   never cached (FORGE F5) and are emitted once per invocation;
+ * - keeps the in-memory queue context honest after each write
+ *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
+ *   against the just-refreshed body instead of the stale one.
+ */
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/lint-cache.js';
+import { buildPatchQueueContext, countNonBinaryDiffLines, detectNewFilesInDiff, lintExportedPatch, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { invalidateNewFileCreatorsCache } from '../core/patch-lint-cross.js';
+import { extractAddedLinesPerFile } from '../core/patch-lint-diff.js';
+import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
+import { pathExists } from '../utils/fs.js';
+import { info } from '../utils/logger.js';
+import { reportPatchLintOutcome } from './export-shared.js';
+import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
+/** Builds the once-per-invocation lint context (FORGE J1). */
+export async function buildReExportLintContext(projectRoot, paths, config, noCache) {
+    const patchQueueCtx = (await pathExists(paths.patches))
+        ? await buildPatchQueueContext(paths.patches, config)
+        : undefined;
+    const checkJs = patchQueueCtx
+        ? buildPerRunCheckJs(projectRoot, paths, config, patchQueueCtx)
+        : undefined;
+    const cache = noCache ? undefined : await loadPerPatchLintCache(projectRoot);
+    const engineHeadSha = cache ? await getPerPatchLintCacheHeadSha(paths.engine) : undefined;
+    return {
+        projectRoot,
+        paths,
+        config,
+        patchQueueCtx,
+        checkJs,
+        cache,
+        engineHeadSha,
+        cacheDirty: false,
+        reusedCacheEntries: 0,
+        globalsEmitted: false,
+    };
+}
+/** The checkJs-relevant files this fresh diff creates. */
+function checkJsFilesInDiff(diffContent, checkJs) {
+    const files = new Set();
+    for (const f of detectNewFilesInDiff(diffContent)) {
+        if (checkJs.isRelevant(f))
+            files.add(f);
+    }
+    return files;
+}
+/**
+ * Lints one re-exported patch body using the hoisted context: cache hit →
+ * replay the stored issues through the shared reporter (returns `null`);
+ * miss → lint with the queue-wide program's pre-attributed slices (or a
+ * per-patch build when the fresh diff creates files the hoisted program
+ * never saw — the `--scan` adoption case) and return the payload for
+ * {@link storeReExportLintResult}. Throws exactly like `runPatchLint` on
+ * errors (unless `skipLint`).
+ *
+ * The cache key is built over the PROJECTED metadata (current
+ * filesAffected, merged lintIgnore, effective tier) so `--tier` /
+ * `--lint-ignore` flags change the key. The entry itself is stored AFTER
+ * the body write (the key hashes the on-disk `.patch` file, which this
+ * very run is about to rewrite — a pre-write store could never match a
+ * later run).
+ */
+export async function lintReExportedPatch(args) {
+    const { lintCtx, patch, projectedMetadata, existingFiles, diffContent } = args;
+    const { paths, config, patchQueueCtx, checkJs, cache } = lintCtx;
+    // Tier notice, identical to runPatchLint's head — surfaced on both the
+    // cached and fresh paths so the governing tier is never silent.
+    const tierDecision = resolvePatchSizeTier(existingFiles, args.patchTier);
+    if (tierDecision.tier === 'branding') {
+        info(tierDecision.source === 'explicit'
+            ? 'Lint: branding threshold tier applied via patches.json `tier: "branding"` opt-in.'
+            : 'Lint: branding threshold tier applied (patch is all under browser/branding/ plus registration siblings).');
+    }
+    // Run-level checkJs globals surface exactly once per invocation, never
+    // from the cache (FORGE F5). On an all-warm run this is a cheap probe,
+    // not a program build.
+    let globalIssues = [];
+    if (checkJs && !lintCtx.globalsEmitted) {
+        lintCtx.globalsEmitted = true;
+        globalIssues = await checkJs.getGlobal();
+    }
+    if (cache && patchQueueCtx) {
+        const cacheKey = await buildPerPatchLintCacheKey({
+            projectRoot: lintCtx.projectRoot,
+            engineDir: paths.engine,
+            patchesDir: paths.patches,
+            patch: projectedMetadata,
+            existingFiles,
+            config,
+            queueContext: patchQueueCtx,
+            ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
+        });
+        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
+        if (cached) {
+            lintCtx.reusedCacheEntries++;
+            reportPatchLintOutcome([...globalIssues, ...cached.issues], args.skipLint);
+            return null;
+        }
+    }
+    const lintOptions = {};
+    const suppressedIssues = [];
+    lintOptions.onSuppressed = (suppressed) => suppressedIssues.push(...suppressed);
+    if (checkJs) {
+        const created = checkJsFilesInDiff(diffContent, checkJs);
+        const allKnown = [...created].every((f) => checkJs.resolutionSet.has(f));
+        if (allKnown) {
+            // Slice this patch's findings out of the one queue-wide program.
+            lintOptions.precomputedCheckJs = await checkJs.sliceFor(created);
+        }
+        else {
+            // Fresh `--scan` adoption created checkJs-relevant files the hoisted
+            // program has never seen — fall back to a per-patch build with the
+            // usual report scope so nothing is silently unchecked (FORGE F5).
+            lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
+        }
+    }
+    else if (patchQueueCtx) {
+        lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
+    }
+    const issues = await lintExportedPatch(paths.engine, existingFiles, diffContent, config, patchQueueCtx, args.ignoreChecks, args.patchTier, lintOptions);
+    reportPatchLintOutcome([...globalIssues, ...issues], args.skipLint);
+    return {
+        issues,
+        suppressed: suppressedIssues,
+        lineCount: countNonBinaryDiffLines(diffContent).textLines,
+    };
+}
+/**
+ * Stores a fresh lint result AFTER the body write, keying against the
+ * just-written `.patch` file and the refreshed queue context — the state
+ * a later identical invocation will observe (call
+ * {@link refreshQueueCtxEntry} first).
+ */
+export async function storeReExportLintResult(lintCtx, patchFilename, projectedMetadata, existingFiles, result) {
+    const { cache, patchQueueCtx, paths, config } = lintCtx;
+    if (!cache || !patchQueueCtx)
+        return;
+    const cacheKey = await buildPerPatchLintCacheKey({
+        projectRoot: lintCtx.projectRoot,
+        engineDir: paths.engine,
+        patchesDir: paths.patches,
+        patch: projectedMetadata,
+        existingFiles,
+        config,
+        queueContext: patchQueueCtx,
+        ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
+    });
+    setCachedPerPatchLintIssues(cache, patchFilename, cacheKey, result.issues, result.suppressed, result.lineCount);
+    lintCtx.cacheDirty = true;
+}
+/**
+ * Refreshes the in-memory queue entry for a just-rewritten patch so later
+ * iterations (and later cache keys) lint against the new body instead of
+ * the stale one. The on-disk write is the authority; this mirrors it.
+ */
+export function refreshQueueCtxEntry(lintCtx, patchFilename, diffContent) {
+    const ctx = lintCtx.patchQueueCtx;
+    if (!ctx)
+        return;
+    const entry = ctx.entries.find((e) => e.filename === patchFilename);
+    if (!entry)
+        return;
+    entry.diff = diffContent;
+    const newFilePaths = detectNewFilesInDiff(diffContent);
+    const addedLinesByFile = extractAddedLinesPerFile(diffContent);
+    const newFiles = new Map();
+    const modifiedFileAdditions = new Map();
+    for (const [file, lines] of addedLinesByFile) {
+        if (newFilePaths.has(file)) {
+            // A created file's content IS its added lines.
+            newFiles.set(file, lines.join('\n'));
+        }
+        else {
+            modifiedFileAdditions.set(file, lines.join('\n'));
+        }
+    }
+    entry.newFiles = newFiles;
+    entry.modifiedFileAdditions = modifiedFileAdditions;
+    invalidateNewFileCreatorsCache(ctx);
+}
+/** Persists cache writes and reports reuse, once after the loop. */
+export async function finishReExportLint(lintCtx) {
+    if (lintCtx.cache && lintCtx.cacheDirty) {
+        await savePerPatchLintCache(lintCtx.projectRoot, lintCtx.cache);
+    }
+    if (lintCtx.reusedCacheEntries > 0) {
+        info(`Reused lint cache for ${lintCtx.reusedCacheEntries} patch${lintCtx.reusedCacheEntries === 1 ? '' : 'es'}.`);
+    }
+}

package/dist/src/commands/re-export-options.js

@@ -77,6 +77,17 @@ export function validateReExportOptionCombinations(patches, options) {
             throw new InvalidArgumentError('--scan-files selects patches from its manifest and cannot be combined with positional patches or --all.', '--scan-files');
         }
     }
+    if (options.refuseAdjacentUnmanaged === true && (options.scan || options.files !== undefined)) {
+        throw new InvalidArgumentError('--refuse-adjacent-unmanaged applies to the scan-less path only and cannot be combined with --scan or --files (those set filesAffected explicitly).', '--refuse-adjacent-unmanaged');
+    }
+    if (options.refuseForeignDrift === true && (options.scan || options.files !== undefined)) {
+        throw new InvalidArgumentError('--refuse-foreign-drift applies to the scan-less path only and cannot be combined with --scan or --files (those explicitly capture the current engine state).', '--refuse-foreign-drift');
+    }
+    if (options.expect !== undefined &&
+        options.expect.length > 0 &&
+        options.refuseForeignDrift !== true) {
+        throw new InvalidArgumentError('--expect names files whose drift is expected under --refuse-foreign-drift and has no effect without it. Pass --refuse-foreign-drift, or drop --expect.', '--expect');
+    }
     const usingTierFlag = options.tier !== undefined;
     const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
     if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {

package/dist/src/commands/re-export-register.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI registration for `fireforge re-export`.
+ *
+ * Split out of `re-export.ts` in 0.41.0. That file was the only one in `src/`
+ * carrying a file-level `eslint-disable max-lines` — it measured 526 against
+ * the 500 cap with the rule suppressed — and its own suppression comment named
+ * this block as the obvious thing to move ("splitting register plumbing is
+ * unrelated to this fix"). Moving it drops the file under the cap and removes
+ * the suppression.
+ *
+ * §7 of the quality survey forbids folding `re-export-files.ts` back INTO the
+ * orchestrator; this splits in the other direction, matching the existing
+ * `re-export-scan.ts` / `re-export-options.ts` boundary.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+/** Registers the re-export command on the CLI program. */
+export declare function registerReExport(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/re-export-register.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * CLI registration for `fireforge re-export`.
+ *
+ * Split out of `re-export.ts` in 0.41.0. That file was the only one in `src/`
+ * carrying a file-level `eslint-disable max-lines` — it measured 526 against
+ * the 500 cap with the rule suppressed — and its own suppression comment named
+ * this block as the obvious thing to move ("splitting register plumbing is
+ * unrelated to this fix"). Moving it drops the file under the cap and removes
+ * the suppression.
+ *
+ * §7 of the quality survey forbids folding `re-export-files.ts` back INTO the
+ * orchestrator; this splits in the other direction, matching the existing
+ * `re-export-scan.ts` / `re-export-options.ts` boundary.
+ */
+import { Command, Option } from 'commander';
+import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds, stringListOption, } from '../utils/options.js';
+import { reExportCommand } from './re-export.js';
+/** Registers the re-export command on the CLI program. */
+export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
+    const reExport = program
+        .command('re-export [patches...]')
+        .description('Refresh existing patch bodies (and filesAffected with --scan) from the current engine ' +
+        'state. Does NOT change sourceVersion/sourceProduct by default — use --stamp or run ' +
+        'rebase for source metadata stamping.')
+        .option('-a, --all', 'Re-export all patches')
+        .option('-s, --scan', 'Scan directories for new/removed files and update filesAffected')
+        .option('--scan-file <path>', 'With --scan, add this explicit engine-relative file to one target patch without collecting adjacent files. Repeatable.', ...stringListOption())
+        .option('--scan-files <manifest>', 'With --scan, bulk-assign generated files from a JSON manifest: {"assignments":[{"patch":"002-name.patch","files":["path"]}]}. Selects patches from the manifest.')
+        .option('--files <paths>', 'Restrict the re-exported filesAffected to this comma-separated list (single target patch only)', (value) => value
+        .split(',')
+        .map((v) => v.trim())
+        .filter((v) => v.length > 0))
+        .option('--refuse-adjacent-unmanaged', 'Refuse a scan-less re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Mutually exclusive with --scan and --files.')
+        .option('--refuse-foreign-drift', "Refuse a scan-less re-export (non-zero exit, patch not written) when the refreshed body would absorb engine lines not present in the old patch body — protects multi-session checkouts from silently capturing another session's uncommitted edits. Mutually exclusive with --scan and --files.")
+        .option('--expect <path>', "With --refuse-foreign-drift, name an engine-relative file whose drift is this session's intended edit: drift confined to --expect files proceeds, drift anywhere else still refuses. Repeatable.", ...stringListOption())
+        .option('--dry-run', 'Show what would change without writing')
+        .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
+        .option('--no-cache', 'Bypass per-patch lint result cache reads and writes for this re-export')
+        .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
+        .option('--allow-shrink', 'Allow --files to remove paths currently owned by the patch. Required before --yes can bypass the shrink confirmation.')
+        .option('-y, --yes', 'Skip confirmation prompts (required for non-TTY destructive writes)')
+        .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
+        .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceVersion/sourceProduct in patches.json to firefox.version/firefox.product from fireforge.json. No effect on a partial run.")
+        .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
+        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', ...stringListOption());
+    addWaitLockOption(reExport).action(withErrorHandling(async (patches, options) => {
+        const { tier, lintIgnore, scanFile, scanFiles, cache, expect, ...rest } = options;
+        const projectRoot = getProjectRoot();
+        await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, {
+            ...pickDefined(rest),
+            ...(scanFile !== undefined && scanFile.length > 0 ? { scanFiles: scanFile } : {}),
+            ...(scanFiles !== undefined ? { scanFilesManifest: scanFiles } : {}),
+            ...(tier !== undefined ? { tier: tier } : {}),
+            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
+            ...(expect !== undefined && expect.length > 0 ? { expect } : {}),
+            ...(cache === false ? { noCache: true } : {}),
+        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+    }));
+}

package/dist/src/commands/re-export-scan.js

@@ -9,10 +9,13 @@ import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFi
 import { getClaimedFiles } from '../core/patch-manifest.js';
 import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
 import { isContainedRelativePath, normalizePathSlashes, stripEnginePrefix, } from '../utils/paths.js';
 const SCAN_ADD_COUNT_THRESHOLD = 3;
+/** Concurrency bound for existence probes (matches the classify/lint pools). */
+const PATH_PROBE_CONCURRENCY = 8;
 const SCAN_DIR_COUNT_THRESHOLD = 2;
 /** Normalizes repeatable `--scan-file` inputs into safe engine-relative paths. */
 export function normalizeScanFiles(scanFiles) {
@@ -70,11 +73,18 @@ async function scanPatchFilesTargeted(args) {
     const currentSet = new Set(currentFilesAffected);
     const claimedByOthers = getClaimedFiles(manifest, patchFilename);
     const added = [];
+    // Phase-split for bounded concurrency: the sync claimed-by-others check
+    // first (first offender in argument order, as before), then pooled
+    // existence probes with the refusal chosen by ordered iteration so the
+    // FIRST missing file in argument order is named deterministically.
     for (const file of scanFiles) {
         if (claimedByOthers.has(file)) {
             throw new InvalidArgumentError(`--scan-file path is already claimed by another patch: ${file}`, '--scan-file');
         }
-        if (!(await pathExists(join(engineDir, file)))) {
+    }
+    const exists = await mapWithConcurrency(scanFiles, PATH_PROBE_CONCURRENCY, (file) => pathExists(join(engineDir, file)));
+    for (const [index, file] of scanFiles.entries()) {
+        if (exists[index] !== true) {
             throw new InvalidArgumentError(`--scan-file path not found in engine/: ${file}`, '--scan-file');
         }
         if (!currentSet.has(file))
@@ -84,12 +94,8 @@ async function scanPatchFilesTargeted(args) {
     return reportScanResult(currentFilesAffected, patchFilename, isDryRun, added.sort(), removed);
 }
 async function findRemovedFiles(files, engineDir) {
-    const removed = [];
-    for (const file of files) {
-        if (!(await pathExists(join(engineDir, file))))
-            removed.push(file);
-    }
-    return removed.sort();
+    const exists = await mapWithConcurrency(files, PATH_PROBE_CONCURRENCY, (file) => pathExists(join(engineDir, file)));
+    return files.filter((_, index) => exists[index] !== true).sort();
 }
 function reportScanResult(currentFilesAffected, patchFilename, isDryRun, added, removed) {
     for (const f of added)

package/dist/src/commands/re-export-single.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Single-patch refresh core for `fireforge re-export`, split out of
+ * `re-export.ts` (at the per-file line budget after the FORGE J1/J2
+ * hoisted-lint and foreign-drift wiring). The orchestrator loop calls
+ * {@link reExportSinglePatchWithIndexLockRetry} per selected patch.
+ */
+import { getProjectPaths } from '../core/config.js';
+import type { PatchesManifest, PatchMetadata, ReExportOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import type { AdjacentUnmanagedContext } from './re-export-adjacent.js';
+import type { ForeignDriftContext } from './re-export-drift.js';
+import { type ReExportLintContext } from './re-export-lint.js';
+/**
+ * Retries a single patch re-export exactly once when the failure is
+ * transient git `index.lock` contention (an external git process holding
+ * the engine repo's index). The retry re-enters `reExportSinglePatch`
+ * from the top, so it re-reads clean state; a second lock failure
+ * propagates to the loop's honest "N of M" accounting.
+ */
+export declare function reExportSinglePatchWithIndexLockRetry(patch: PatchMetadata, paths: ReturnType<typeof getProjectPaths>, manifest: PatchesManifest, options: ReExportOptions, isDryRun: boolean, config: FireForgeConfig, adjacentCtx: AdjacentUnmanagedContext, driftCtx: ForeignDriftContext, lintCtx: ReExportLintContext): Promise<boolean>;

package/dist/src/commands/re-export-single.js

@@ -0,0 +1,261 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Single-patch refresh core for `fireforge re-export`, split out of
+ * `re-export.ts` (at the per-file line budget after the FORGE J1/J2
+ * hoisted-lint and foreign-drift wiring). The orchestrator loop calls
+ * {@link reExportSinglePatchWithIndexLockRetry} per selected patch.
+ */
+import { getProjectPaths } from '../core/config.js';
+import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
+import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
+import { updatePatchAndMetadata } from '../core/patch-export.js';
+import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
+import { isGitIndexLockConflict } from '../errors/git.js';
+import { info, success, warn } from '../utils/logger.js';
+import { findMissingFiles, reportAdjacentUnmanagedFiles } from './re-export-adjacent.js';
+import { reportForeignDrift } from './re-export-drift.js';
+import { lintReExportedPatch, refreshQueueCtxEntry, storeReExportLintResult, } from './re-export-lint.js';
+import { assertScanAdoptionsHaveNoForwardImports, assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, scanPatchFilesForReExport, } from './re-export-scan.js';
+const GIT_INDEX_LOCK_RETRY_MS = 300;
+/**
+ * Retries a single patch re-export exactly once when the failure is
+ * transient git `index.lock` contention (an external git process holding
+ * the engine repo's index). The retry re-enters `reExportSinglePatch`
+ * from the top, so it re-reads clean state; a second lock failure
+ * propagates to the loop's honest "N of M" accounting.
+ */
+export async function reExportSinglePatchWithIndexLockRetry(patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx) {
+    try {
+        return await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx);
+    }
+    catch (error) {
+        if (!isGitIndexLockConflict(error)) {
+            throw error;
+        }
+        warn(`${patch.filename}: git index.lock contention detected — retrying once after ${String(GIT_INDEX_LOCK_RETRY_MS)} ms...`);
+        await new Promise((resolve) => setTimeout(resolve, GIT_INDEX_LOCK_RETRY_MS));
+        return await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx);
+    }
+}
+async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx) {
+    let currentFilesAffected = [...patch.filesAffected];
+    // --- Scan for new/removed files ---
+    if (options.scan) {
+        const scanResult = await scanPatchFilesForReExport({
+            currentFilesAffected,
+            engineDir: paths.engine,
+            manifest,
+            patchFilename: patch.filename,
+            isDryRun,
+            ...(options.scanFiles !== undefined ? { scanFiles: options.scanFiles } : {}),
+        });
+        // Forward-import gate at adoption time (runs in dry-run too): refuse
+        // to adopt unmanaged files that import modules created by LATER
+        // patches — the after-the-fact lint failure this leaves behind is the
+        // field-reported footgun. Applies to broad --scan, --scan-file, and
+        // the --scan-files bulk assignments alike.
+        await assertScanAdoptionsHaveNoForwardImports({
+            patchesDir: paths.patches,
+            engineDir: paths.engine,
+            patchFilename: patch.filename,
+            added: scanResult.added,
+        });
+        if (options.scanFiles === undefined) {
+            const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+            const proceed = await confirmBroadScanAdditions({
+                patchFilename: patch.filename,
+                added: scanResult.added,
+                isDryRun,
+                yes: options.yes === true,
+                isInteractive,
+            });
+            if (!proceed) {
+                return false;
+            }
+        }
+        currentFilesAffected = scanResult.updated;
+    }
+    else if (options.files === undefined) {
+        // Finding #16: when neither `--scan` nor `--files` is set and some
+        // of the manifest's claimed files no longer exist on disk, the
+        // re-export silently writes a refreshed body whose filesAffected
+        // still names the vanished paths. That is the documented contract,
+        // but it is also a footgun — a later `verify` then fails on
+        // manifest-consistency with no obvious trigger. Emit one advisory
+        // warning up-front when we can detect the drift cheaply, so the
+        // operator has a chance to re-run with `--scan` or `--files`
+        // before the stale filesAffected lands in patches.json.
+        const args = { patch, paths, manifest, currentFilesAffected, ctx: adjacentCtx };
+        if (await reportAdjacentUnmanagedFiles(args))
+            return false;
+    }
+    // --- Explicit file-subset path ---
+    // When --files is given, the target filesAffected is authoritative — drop
+    // anything not in the list, add anything new. This is the surgical repair
+    // primitive that replaces hand-editing patches.json; the user has already
+    // acknowledged via confirmDestructive (done in the caller) that any drop
+    // is intentional.
+    if (options.files !== undefined) {
+        const requested = [...new Set(options.files)].sort();
+        currentFilesAffected = requested;
+        const removed = patch.filesAffected.filter((f) => !requested.includes(f));
+        const added = requested.filter((f) => !patch.filesAffected.includes(f));
+        for (const f of added)
+            info(`  + ${f}`);
+        for (const f of removed)
+            info(`  - ${f}`);
+    }
+    // Stale-furnace-source gate (0.37.0 item 4): re-export captures deployed
+    // engine copies, so a component source edited after the last furnace
+    // apply would land in the patch as its OLD deployed content. Refuse (or
+    // warn under --allow-stale-furnace) before diffing. Runs in dry-run too
+    // so the failure surfaces early.
+    await enforceFreshFurnaceSources(paths.root, currentFilesAffected, options.allowStaleFurnace === true, 're-export');
+    const missingFiles = await findMissingFiles(paths.engine, currentFilesAffected);
+    if (missingFiles.length === currentFilesAffected.length) {
+        warn(`Skipped ${patch.filename}: all affected files missing`);
+        warn(`Missing files: ${missingFiles.join(', ')}`);
+        return false;
+    }
+    if (missingFiles.length > 0) {
+        warn(`${patch.filename}: missing files will be skipped: ${missingFiles.join(', ')}`);
+    }
+    const missingSet = new Set(missingFiles);
+    const existingFiles = currentFilesAffected.filter((f) => !missingSet.has(f));
+    const diffContent = await getDiffForFilesAgainstHead(paths.engine, existingFiles);
+    assertScanFileAdditionsHaveDiffHunks({
+        diffContent,
+        patchFilename: patch.filename,
+        previousFilesAffected: patch.filesAffected,
+        scanFiles: options.scanFiles,
+    });
+    if (!diffContent.trim()) {
+        warn(`Skipped ${patch.filename}: no changes (files unchanged from HEAD)`);
+        return false;
+    }
+    // Foreign-drift preview + optional hard stop (FORGE J2): show which
+    // payload lines are about to enter the body that the old body did not
+    // carry — the case where a concurrent session's uncommitted edits in
+    // OWNED files would be silently absorbed. Always previews (including
+    // dry-run and --scan); refuses only under --refuse-foreign-drift.
+    if (await reportForeignDrift({
+        patch,
+        patchesDir: paths.patches,
+        newDiffContent: diffContent,
+        ctx: driftCtx,
+    })) {
+        return false;
+    }
+    const { updates, ignoreChecks, effectiveTier, existingIgnoreSet, flagIgnoreSet } = computeReExportUpdates(patch, options, currentFilesAffected);
+    enforcePatchPolicy({
+        config,
+        manifest: buildProjectedManifest(manifest, manifest.patches.map((entry) => entry.filename === patch.filename ? { ...entry, ...updates } : entry)),
+        command: 're-export',
+        forceUnsafe: options.forceUnsafe === true,
+    });
+    // Lint against the ONCE-per-invocation hoisted context (queue context +
+    // queue-wide checkJs program + per-patch result cache) instead of
+    // rebuilding ~37 s of setup for every patch in the loop (FORGE J1).
+    const projectedMetadata = { ...patch, ...updates };
+    const lintResult = await lintReExportedPatch({
+        lintCtx,
+        patch,
+        projectedMetadata,
+        existingFiles,
+        diffContent,
+        ...(options.skipLint !== undefined ? { skipLint: options.skipLint } : {}),
+        ...(ignoreChecks !== undefined ? { ignoreChecks } : {}),
+        ...(effectiveTier !== undefined ? { patchTier: effectiveTier } : {}),
+    });
+    if (isDryRun) {
+        info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
+        if (effectiveTier !== undefined && effectiveTier !== patch.tier) {
+            info(`[dry-run] ${patch.filename}: tier would become ${effectiveTier}`);
+        }
+        const addedIgnores = [...flagIgnoreSet].filter((id) => !existingIgnoreSet.has(id));
+        if (addedIgnores.length > 0) {
+            info(`[dry-run] ${patch.filename}: lintIgnore would gain ${addedIgnores.join(', ')}`);
+        }
+    }
+    else {
+        await commitRefreshedPatch({
+            patch,
+            paths,
+            manifest,
+            options,
+            config,
+            lintCtx,
+            diffContent,
+            updates,
+            projectedMetadata,
+            existingFiles,
+            lintResult,
+        });
+    }
+    return true;
+}
+/**
+ * Writes the refreshed body + manifest row atomically under the patch
+ * directory lock (a split write would let a concurrent queue mutation
+ * leave body and `filesAffected` disagreeing), then keeps the run's
+ * in-memory state honest: the queue context entry is refreshed and the
+ * fresh lint result is stored keyed against the just-written body — the
+ * state a repeat invocation will observe (FORGE J1) — and the in-memory
+ * manifest row mirrors the on-disk write for later loop iterations
+ * (notably `--all --scan`, where `getClaimedFiles` reads this manifest).
+ */
+async function commitRefreshedPatch(args) {
+    const { patch, paths, manifest, options, config, lintCtx, diffContent, updates } = args;
+    await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, updates, undefined, {
+        config,
+        command: 're-export',
+        forceUnsafe: options.forceUnsafe === true,
+    });
+    refreshQueueCtxEntry(lintCtx, patch.filename, diffContent);
+    if (args.lintResult !== null) {
+        await storeReExportLintResult(lintCtx, patch.filename, args.projectedMetadata, args.existingFiles, args.lintResult);
+    }
+    const patchIndex = manifest.patches.findIndex((pm) => pm.filename === patch.filename);
+    if (patchIndex !== -1) {
+        const existingEntry = manifest.patches[patchIndex];
+        if (existingEntry) {
+            manifest.patches[patchIndex] = {
+                ...existingEntry,
+                ...updates,
+            };
+        }
+    }
+    success(`Re-exported ${patch.filename}`);
+}
+/**
+ * Threads the patch's own `lintIgnore` list through so the per-patch
+ * suppression honoured by export/export-all is also honoured here — a
+ * re-export could otherwise not refresh an advisory-noisy but intentional
+ * patch without the blunt `--skip-lint`. The paired `patch.tier` threads
+ * the explicit branding-threshold opt-in the same way. The CLI flags
+ * `--tier` and `--lint-ignore` participate with append/union semantics
+ * (explicit removal lives on `fireforge patch lint-ignore`), computed
+ * before the lint pass so the new intent takes effect on this invocation.
+ */
+function computeReExportUpdates(patch, options, currentFilesAffected) {
+    const existingIgnoreSet = new Set(patch.lintIgnore ?? []);
+    const flagIgnoreSet = new Set(options.lintIgnore ?? []);
+    const mergedIgnoreSet = new Set([...existingIgnoreSet, ...flagIgnoreSet]);
+    const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
+    const updates = {
+        filesAffected: currentFilesAffected,
+    };
+    if (options.tier !== undefined) {
+        updates.tier = options.tier;
+    }
+    if (effectiveLintIgnore !== undefined && flagIgnoreSet.size > 0) {
+        updates.lintIgnore = effectiveLintIgnore;
+    }
+    return {
+        updates,
+        ignoreChecks: effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined,
+        effectiveTier: options.tier ?? patch.tier,
+        existingIgnoreSet,
+        flagIgnoreSet,
+    };
+}

package/dist/src/commands/re-export.d.ts

@@ -1,5 +1,3 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
 import type { ReExportOptions } from '../types/commands/index.js';
 /**
  * Runs the re-export command to regenerate existing patches from current engine state.
@@ -8,5 +6,3 @@ import type { ReExportOptions } from '../types/commands/index.js';
  * @param options - Re-export options
  */
 export declare function reExportCommand(projectRoot: string, patches: string[], options: ReExportOptions): Promise<void>;
-/** Registers the re-export command on the CLI program. */
-export declare function registerReExport(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;