@hominis/fireforge 0.50.0 → 0.52.0

package/dist/src/commands/patch/staged-dependency.js

@@ -13,6 +13,7 @@ import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 import { stagedDependencyDelta } from './staged-dependency-batch.js';
 import { applyMode, countStagedEntries, dependencyLabel, importView, registrationView, } from './staged-dependency-entries.js';
 import { runBatchAdd } from './staged-dependency-from.js';
+import { selectRemovalEntries } from './staged-dependency-remove.js';
 import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
 /** Joins the names of the missing flags for error attribution. */
 function missingFlagList(pairs) {
@@ -85,90 +86,27 @@ function requireRegistrationOptions(options) {
         dependency.reason = options.reason;
     return dependency;
 }
-/**
- * Resolves the `--remove` target for forward-imports:
- * `--file` + `--specifier` suffice when they identify at most one staged
- * entry. `--creates` is inferred from a unique match, an ambiguous match
- * refuses with the candidate list, and no match falls through to the
- * honest "no staged forward-import matched" summary.
- */
-function resolveImportRemovalTarget(options, staged) {
-    if (!options.file || !options.specifier) {
-        throw new InvalidArgumentError('--remove requires --file and --specifier; --creates is only needed to disambiguate when several staged entries share them.', missingFlagList([
-            ['--file', options.file],
-            ['--specifier', options.specifier],
-        ]));
-    }
-    if (options.creates) {
-        return requireForwardImportOptions(options);
-    }
-    const { file, specifier } = options;
-    const candidates = (staged?.forwardImports ?? []).filter((entry) => entry.file === file &&
-        entry.specifier === specifier &&
-        (options.owner === undefined || entry.owner === options.owner));
-    const single = candidates.length === 1 ? candidates[0] : undefined;
-    if (single !== undefined) {
-        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
-        return { ...single };
-    }
-    if (candidates.length > 1) {
-        const list = candidates
-            .map((entry) => `  - ${dependencyLabel('import', importView(entry))}`)
-            .join('\n');
-        throw new GeneralError(`--remove matches ${candidates.length} staged forward-imports on this patch; ` +
-            `pass --creates to pick one:\n${list}`);
-    }
-    return { file, specifier, creates: '(no match)' };
-}
-/** Registration twin of {@link resolveImportRemovalTarget}, keyed on `--line`. */
-function resolveRegistrationRemovalTarget(options, staged) {
-    if (!options.file || !options.line) {
-        throw new InvalidArgumentError('--remove --kind registration requires --file and --line; --creates is only needed to disambiguate when several staged entries share them.', missingFlagList([
-            ['--file', options.file],
-            ['--line', options.line],
-        ]));
-    }
-    if (options.creates) {
-        return requireRegistrationOptions(options);
-    }
-    const { file, line } = options;
-    const candidates = (staged?.registrations ?? []).filter((entry) => entry.file === file &&
-        entry.line === line &&
-        (options.owner === undefined || entry.owner === options.owner));
-    const single = candidates.length === 1 ? candidates[0] : undefined;
-    if (single !== undefined) {
-        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
-        return { ...single };
-    }
-    if (candidates.length > 1) {
-        const list = candidates
-            .map((entry) => `  - ${dependencyLabel('registration', registrationView(entry))}`)
-            .join('\n');
-        throw new GeneralError(`--remove matches ${candidates.length} staged registrations on this patch; ` +
-            `pass --creates to pick one:\n${list}`);
-    }
-    return { file, line, creates: '(no match)' };
-}
 /**
  * Renders a one-line summary of a staged-dependency metadata change.
  */
-function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, target) {
+function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, targets) {
     const noun = kind === 'import' ? 'staged forward-import' : 'staged registration';
     if (mode === 'clear') {
         return beforeCount === 0
             ? 'stagedDependencies was already empty — no change'
             : `cleared ${beforeCount} staged dependency declaration(s)`;
     }
-    if (!target)
+    const label = targets.map((target) => dependencyLabel(kind, target)).join('; ');
+    if (targets.length === 0)
         return 'stagedDependencies unchanged';
     if (mode === 'add') {
         return afterCount === beforeCount
-            ? `${noun} already present: ${dependencyLabel(kind, target)}`
-            : `added ${noun}: ${dependencyLabel(kind, target)}`;
+            ? `${noun} already present: ${label}`
+            : `added ${noun}: ${label}`;
     }
     return afterCount === beforeCount
-        ? `no ${noun} matched: ${dependencyLabel(kind, target)}`
-        : `removed ${beforeCount - afterCount} ${noun} declaration(s): ${dependencyLabel(kind, target)}`;
+        ? `no ${noun} matched: ${label}`
+        : `removed ${beforeCount - afterCount} ${noun} declaration(s): ${label}`;
 }
 /**
  * Runs the metadata-only staged-dependency mutation command.
@@ -191,35 +129,34 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     // entries.
     const { paths, manifest } = await requirePatchQueue(projectRoot);
     const targetPatch = requirePatchTarget(identifier, manifest.patches);
-    const importDependency = mode === 'clear' || kind !== 'import'
-        ? undefined
-        : mode === 'add'
-            ? requireForwardImportOptions(options)
-            : resolveImportRemovalTarget(options, targetPatch.stagedDependencies);
-    const registrationDependency = mode === 'clear' || kind !== 'registration'
-        ? undefined
-        : mode === 'add'
-            ? requireRegistrationOptions(options)
-            : resolveRegistrationRemovalTarget(options, targetPatch.stagedDependencies);
+    const importDependency = mode === 'add' && kind === 'import' ? requireForwardImportOptions(options) : undefined;
+    const registrationDependency = mode === 'add' && kind === 'registration' ? requireRegistrationOptions(options) : undefined;
     // Shape-check --add declarations against the loaded queue: a
     // patch-name-shaped --creates/--file is refused now instead of surfacing
     // later as an undischargeable staged-dependency-unused.
-    if (mode === 'add') {
-        const added = importDependency ?? registrationDependency;
-        if (added !== undefined) {
-            validateStagedDependencyAdd(added, manifest.patches);
-        }
-    }
-    const target = importDependency !== undefined
-        ? importView(importDependency)
-        : registrationDependency !== undefined
-            ? registrationView(registrationDependency)
-            : undefined;
+    const added = importDependency ?? registrationDependency;
+    if (added !== undefined) {
+        validateStagedDependencyAdd(added, manifest.patches);
+    }
+    const targets = mode === 'remove'
+        ? selectRemovalEntries(kind, options, targetPatch.stagedDependencies)
+        : importDependency !== undefined
+            ? [importView(importDependency)]
+            : registrationDependency !== undefined
+                ? [registrationView(registrationDependency)]
+                : [];
+    const applyKind = (entries, own, toView, addition) => {
+        if (!own)
+            return [...entries];
+        if (mode !== 'remove')
+            return applyMode(entries, mode, targets[0], toView, addition);
+        return targets.reduce((remaining, target) => applyMode(remaining, 'remove', target, toView, undefined), [...entries]);
+    };
     const applyToStaged = (staged) => {
         if (mode === 'clear')
             return {};
-        const forwardImports = applyMode(staged?.forwardImports ?? [], kind === 'import' ? mode : 'add', kind === 'import' ? target : undefined, importView, importDependency);
-        const registrations = applyMode(staged?.registrations ?? [], kind === 'registration' ? mode : 'add', kind === 'registration' ? target : undefined, registrationView, registrationDependency);
+        const forwardImports = applyKind(staged?.forwardImports ?? [], kind === 'import', importView, importDependency);
+        const registrations = applyKind(staged?.registrations ?? [], kind === 'registration', registrationView, registrationDependency);
         return {
             ...(forwardImports.length > 0 ? { forwardImports } : {}),
             ...(registrations.length > 0 ? { registrations } : {}),
@@ -227,7 +164,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     };
     const existing = targetPatch.stagedDependencies;
     const projected = applyToStaged(existing);
-    const summary = describeStagedDependencyChange(countStagedEntries(existing), countStagedEntries(projected), mode, kind, target);
+    const summary = describeStagedDependencyChange(countStagedEntries(existing), countStagedEntries(projected), mode, kind, targets);
     if (isDryRun) {
         info(`[dry-run] ${targetPatch.filename}: ${summary}.`);
         outro('Dry run complete — no changes made');
@@ -247,7 +184,12 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     }
     const before = result.before.stagedDependencies;
     const after = result.after.stagedDependencies;
-    info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, target)}.`);
+    info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, targets)}.`);
+    if (mode === 'remove' && countStagedEntries(after) === countStagedEntries(before)) {
+        // The selection matched when the queue was read; a peer removed the
+        // entries before the locked write. Still a miss, so still a refusal.
+        throw new InvalidArgumentError(`${targetPatch.filename}: the selected staged declaration(s) were already gone when the manifest was written.`, '--remove');
+    }
     await appendHistoryBestEffort(paths.patches, {
         operation: 'patch-staged-dependency',
         // Only the delta: the whole list on both sides grew the log
@@ -275,13 +217,13 @@ export function registerPatchStagedDependency(parent, context) {
         .command('staged-dependency <name>')
         .description('Edit PatchMetadata.stagedDependencies on a single patch (no .patch body rewrite).')
         .option('--add', 'Add a staged dependency declaration')
-        .option('--remove', 'Remove matching staged dependency declaration(s)')
+        .option('--remove', 'Remove matching staged dependency declaration(s); a selection that matches nothing exits 8')
         .option('--clear', 'Drop the stagedDependencies field entirely')
         .option('--kind <kind>', 'Declaration shape: "import" (forward import, the default) or "registration" (jar.mn packaging line, customElements or actor registration)')
         .option('--file <path>', 'Declaring file path relative to engine/')
         .option('--specifier <specifier>', 'Exact import specifier as it appears in source (--kind import)')
-        .option('--line <text>', 'Registration/packaging line as the patch adds it, compared whitespace-trimmed (--kind registration)')
-        .option('--creates <path>', 'Later-created file path relative to engine/')
+        .option('--line <text>', 'Registration/packaging line as the patch adds it, compared whitespace-insensitively (--kind registration)')
+        .option('--creates <path>', 'Later-created file path relative to engine/ (with --remove and no --file: removes every declaration for that path)')
         .option('--owner <patch>', 'Exact later patch filename expected to create --creates')
         .option('--reason <text>', 'Human-readable rationale stored with the declaration (with --from: the default for entries without one)')
         .option('--from <json-file>', 'Add every declaration in a JSON file under one lock hold (--add only): a "lint --per-patch --report" ' +

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

@@ -93,6 +93,11 @@ export declare function reportAdjacentUnmanagedFiles(args: {
     manifest: PatchesManifest;
     currentFilesAffected: readonly string[];
     ctx: AdjacentUnmanagedContext;
+    /**
+     * Set beside `--scan`: the scan has already reconciled missing files and
+     * adopted what it was asked to, so only the neighbours it left are judged.
+     */
+    afterScan?: boolean;
 }): Promise<boolean>;
 /**
  * End-of-run accounting for `--expect-new` and `--adjacent-ignore`.

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Scan-less re-export adjacency advisory.
+ * Re-export adjacency advisory.
  *
  * A plain `re-export` keeps the manifest's filesAffected unchanged, so a
  * brand-new file an author just created beside a patch's owned files is
@@ -8,7 +8,8 @@
  * files, filters out tool-managed paths (branding, furnace) so the notice
  * names only genuinely unmanaged candidates, and, under
  * `--refuse-adjacent-unmanaged`, lets the caller turn the notice into a
- * non-zero refusal.
+ * non-zero refusal. Beside `--scan` it judges the files the scan did not
+ * adopt, so a targeted `--scan-file` adoption keeps the belt.
  *
  * Split out of re-export.ts to keep that file inside the max-lines budget.
  * Exports helpers consumed by re-export.ts, no registrar.
@@ -197,7 +198,7 @@ function reportAdmitted(patchFilename, groups) {
  */
 export async function reportAdjacentUnmanagedFiles(args) {
     const { patch, paths, manifest, currentFilesAffected, ctx } = args;
-    const missingFiles = await findMissingFiles(paths.engine, currentFilesAffected);
+    const missingFiles = args.afterScan === true ? [] : await findMissingFiles(paths.engine, currentFilesAffected);
     if (missingFiles.length > 0) {
         warn(`${patch.filename}: some files in patches.json no longer exist on disk ` +
             `(${missingFiles.join(', ')}). Without --scan, re-export keeps the manifest's ` +

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

@@ -1,4 +1,5 @@
 import type { PatchesManifest } from '../types/commands/index.js';
+import { type DryRunPurityScope } from './re-export-purity-scope.js';
 /** Loads and validates a `re-export --scan-files` assignment manifest. */
 export declare function loadScanFilesAssignments(manifestPath: string, manifest: PatchesManifest): Promise<Map<string, string[]>>;
 /**
@@ -13,6 +14,6 @@ export declare function loadScanFilesAssignments(manifestPath: string, manifest:
  * violation surfaces the violation with the original error as `cause`.
  * No-op outside dry-run.
  */
-export declare function withDryRunPurityGuard<T>(engineDir: string, patchesDir: string, isDryRun: boolean, operation: () => Promise<T>): Promise<T>;
+export declare function withDryRunPurityGuard<T>(engineDir: string, patchesDir: string, isDryRun: boolean, operation: () => Promise<T>, scope?: DryRunPurityScope): Promise<T>;
 /** Serializes dry-run re-export git inspection against the same project tree. */
 export declare function withDryRunReExportLock<T>(fireforgeDir: string, isDryRun: boolean, operation: () => Promise<T>): Promise<T>;

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

@@ -11,6 +11,7 @@ import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { sha256Hex } from '../utils/hash.js';
 import { isObject } from '../utils/validation.js';
+import { describeForeignWriters, fingerprintScopedDryRunState, } from './re-export-purity-scope.js';
 import { normalizeEngineRelativeInput } from './re-export-scan.js';
 /** Concurrency bound for patch-body hashing (matches the classify/lint pools). */
 const PATCH_HASH_CONCURRENCY = 8;
@@ -161,10 +162,14 @@ async function fingerprintDryRunState(engineDir, patchesDir) {
  * violation surfaces the violation with the original error as `cause`.
  * No-op outside dry-run.
  */
-export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, operation) {
+export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, operation, scope) {
     if (!isDryRun)
         return operation();
-    const before = await fingerprintDryRunState(engineDir, patchesDir);
+    const fingerprint = () => scope === undefined
+        ? fingerprintDryRunState(engineDir, patchesDir)
+        : fingerprintScopedDryRunState(engineDir, patchesDir, scope);
+    const startedAt = Date.now();
+    const before = await fingerprint();
     let result;
     let operationError;
     let failed = false;
@@ -177,7 +182,7 @@ export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, ope
     }
     let after;
     try {
-        after = await fingerprintDryRunState(engineDir, patchesDir);
+        after = await fingerprint();
     }
     catch (fingerprintError) {
         // The post-run fingerprint failing must not swallow the dry run's own
@@ -195,10 +200,20 @@ export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, ope
         .sort()
         .filter((key) => before.get(key) !== after.get(key));
     if (touched.length > 0) {
-        throw new GeneralError(`[dry-run] invariant violated: this dry run modified ${touched.join(', ')}. ` +
-            'This is a FireForge bug — please report it, and inspect the listed state ' +
-            '(e.g. `git status` in engine/ and your patches/ diff) before trusting it.' +
-            (failed ? ` The dry run also failed: ${toError(operationError).message}` : ''), operationError);
+        const also = failed ? ` The dry run also failed: ${toError(operationError).message}` : '';
+        const writers = await describeForeignWriters(patchesDir, startedAt);
+        if (writers.length > 0) {
+            throw new GeneralError(`[dry-run] ${touched.join(', ')} changed during this dry run, written by another ` +
+                `writer: ${writers.join('; ')}. The preview raced that write; rerun it once the ` +
+                `writer is done.${also}`, operationError);
+        }
+        throw new GeneralError(`[dry-run] invariant violated: ${touched.join(', ')} changed during this dry run. No ` +
+            'other FireForge command recorded a write in that window, so either another writer ' +
+            '(an editor, an agent or a git command in engine/) changed it, or this is a FireForge ' +
+            'bug. Rerun the dry run; if it repeats on a quiet tree, please report it, and inspect ' +
+            'the listed state (e.g. `git status` in engine/ and your patches/ diff) before ' +
+            'trusting it.' +
+            also, operationError);
     }
     if (failed)
         throw operationError;

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

@@ -0,0 +1,35 @@
+import { type ParsedHunk } from '../core/patch-parse.js';
+/** Which hunk mode a re-export runs in, and the diff naming the hunks. */
+export interface HunkSelection {
+    mode: 'include' | 'exclude';
+    diffPath: string;
+    flag: '--hunks-from' | '--exclude-hunks';
+}
+/** The selection a re-export's options ask for, if any. */
+export declare function hunkSelectionOf(options: {
+    hunksFrom?: string;
+    excludeHunks?: string;
+}): HunkSelection | undefined;
+/** Splits a diff into its raw per-file sections, keyed by target path. */
+export declare function splitRawSections(diff: string): Map<string, string>;
+/**
+ * Applies `hunks` to `content` by context, forward or reversed. A hunk
+ * whose context is not found refuses, naming it.
+ */
+export declare function applyHunksByContext(content: string, hunks: readonly ParsedHunk[], reverse: boolean, file: string): string;
+/**
+ * Builds the re-export body for a hunk-selected run: named files from the
+ * selected hunks, the rest from the old body (`--hunks-from`) or the normal
+ * working-tree diff (`--exclude-hunks`).
+ *
+ * @param args.normalDiff - The diff a plain re-export would write
+ * @param args.oldBody - The patch's current body
+ * @param args.files - The files the refreshed patch owns
+ */
+export declare function buildHunkSelectedDiff(args: {
+    engineDir: string;
+    selection: HunkSelection;
+    oldBody: string;
+    normalDiff: string;
+    files: readonly string[];
+}): Promise<string>;

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

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `re-export --hunks-from <diff>` and `--exclude-hunks <diff>`: export a
+ * file by hunk rather than as a whole.
+ *
+ * Re-export captures a file's working-tree content against engine HEAD, so
+ * on a shared engine a peer's unexported line in the same manifest or chrome
+ * document landed in the exporting patch, and the only way out was for the
+ * peer to park its hunk by hand. These two modes build the file's new
+ * content from the hunks a session names:
+ *
+ *  - `--hunks-from`: the patch's current body for the file (HEAD with the
+ *    old section applied) plus only the named hunks. Files the diff does
+ *    not name keep their old section.
+ *  - `--exclude-hunks`: the working tree minus the named hunks. Files the
+ *    diff does not name export as usual.
+ *
+ * Hunks are placed by their context, searched outward from the line their
+ * header names, so a diff taken before a peer's edit above it still applies.
+ * The synthetic content is diffed against HEAD by git itself, on a
+ * throwaway index, so the section is byte-for-byte what a plain re-export
+ * would write for that content.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { git } from '../core/git-base.js';
+import { getFileContentAtRef, listTrackedInHead } from '../core/git-file-ops.js';
+import { mintDisposableGitIndex } from '../core/git-readonly-index.js';
+import { parseDiffGitHeader, parseDiffSections, } from '../core/patch-parse.js';
+import { applyPatchTextToContent } from '../core/patch-transform.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { PatchError } from '../errors/patch.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { normalizeEngineRelativeInput } from './re-export-scan.js';
+/** The selection a re-export's options ask for, if any. */
+export function hunkSelectionOf(options) {
+    if (options.hunksFrom !== undefined) {
+        return { mode: 'include', diffPath: options.hunksFrom, flag: '--hunks-from' };
+    }
+    if (options.excludeHunks !== undefined) {
+        return { mode: 'exclude', diffPath: options.excludeHunks, flag: '--exclude-hunks' };
+    }
+    return undefined;
+}
+/** Splits a diff into its raw per-file sections, keyed by target path. */
+export function splitRawSections(diff) {
+    const sections = new Map();
+    let path;
+    let lines = [];
+    const flush = () => {
+        if (path !== undefined)
+            sections.set(path, `${lines.join('\n')}\n`);
+    };
+    for (const line of diff.split('\n')) {
+        const header = parseDiffGitHeader(line);
+        if (header) {
+            flush();
+            path = header.targetPath;
+            lines = [line];
+        }
+        else if (path !== undefined) {
+            lines.push(line);
+        }
+    }
+    flush();
+    for (const [key, text] of sections)
+        sections.set(key, text.replace(/\n+$/, '\n'));
+    return sections;
+}
+/** The old and new line blocks a hunk replaces, swapped when reversed. */
+function hunkBlocks(hunk, reverse) {
+    const oldLines = [];
+    const newLines = [];
+    for (const line of hunk.lines) {
+        const marker = line[0];
+        const text = line.slice(1);
+        if (marker === ' ' || marker === '-')
+            oldLines.push(text);
+        if (marker === ' ' || marker === '+')
+            newLines.push(text);
+    }
+    return reverse ? { from: newLines, to: oldLines } : { from: oldLines, to: newLines };
+}
+function matchesAt(lines, block, at) {
+    if (at < 0 || at + block.length > lines.length)
+        return false;
+    return block.every((line, index) => lines[at + index] === line);
+}
+/** The match of `block` nearest `expected`, at or after `floor`. */
+function findBlock(lines, block, expected, floor) {
+    for (let distance = 0; distance <= lines.length; distance++) {
+        for (const at of distance === 0 ? [expected] : [expected - distance, expected + distance]) {
+            if (at >= floor && matchesAt(lines, block, at))
+                return at;
+        }
+    }
+    return undefined;
+}
+/**
+ * Applies `hunks` to `content` by context, forward or reversed. A hunk
+ * whose context is not found refuses, naming it.
+ */
+export function applyHunksByContext(content, hunks, reverse, file) {
+    const endsWithNewline = content.endsWith('\n') || content === '';
+    const lines = content === '' ? [] : content.replace(/\n$/, '').split('\n');
+    let offset = 0;
+    let floor = 0;
+    for (const hunk of hunks) {
+        const { from, to } = hunkBlocks(hunk, reverse);
+        const start = (reverse ? hunk.newStart : hunk.oldStart) - (from.length === 0 ? 0 : 1);
+        const expected = Math.max(0, start + offset);
+        const at = from.length === 0 ? expected : findBlock(lines, from, expected, floor);
+        if (at === undefined) {
+            throw new PatchError(`The hunk @@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@ ` +
+                `does not ${reverse ? 'match the working tree' : 'apply to the patch body'} of ${file}: ` +
+                `its ${reverse ? 'new' : 'old'}-side lines were not found.`);
+        }
+        lines.splice(at, from.length, ...to);
+        offset += to.length - from.length + (at - expected);
+        floor = at + to.length;
+    }
+    if (lines.length === 0)
+        return '';
+    return `${lines.join('\n')}${endsWithNewline ? '\n' : ''}`;
+}
+/**
+ * Diffs `content` for `file` against engine HEAD the way a re-export would,
+ * on a throwaway index so the shared one never moves.
+ */
+async function diffContentAgainstHead(engineDir, file, content, tracked) {
+    const index = await mintDisposableGitIndex(engineDir);
+    if (index === undefined) {
+        throw new GeneralError(`Cannot build a private git index in ${engineDir} to diff the hunk-selected ${file}.`);
+    }
+    const scratch = await mkdtemp(join(tmpdir(), 'fireforge-hunks-'));
+    try {
+        const temp = join(scratch, 'content');
+        await writeFile(temp, content);
+        const blob = (await git(['hash-object', '-w', '--path', file, '--', temp], engineDir)).trim();
+        const mode = tracked
+            ? ((await git(['ls-tree', 'HEAD', '--', file], engineDir)).split(/\s/)[0] ?? '100644')
+            : '100644';
+        await git(['update-index', '--add', '--cacheinfo', `${mode},${blob},${file}`], engineDir, {
+            env: index.env,
+        });
+        return await git(['diff', '--binary', '--cached', 'HEAD', '--', file], engineDir, {
+            env: index.env,
+        });
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+        await index.dispose();
+    }
+}
+/** Reads and checks the hunk diff: text sections for files the patch owns. */
+async function readSelection(selection, owned) {
+    if (!(await pathExists(selection.diffPath))) {
+        throw new InvalidArgumentError(`${selection.flag} ${selection.diffPath} does not exist.`, selection.flag);
+    }
+    const sections = parseDiffSections(await readText(selection.diffPath));
+    if (sections.length === 0) {
+        throw new InvalidArgumentError(`${selection.flag} ${selection.diffPath} holds no "diff --git" section.`, selection.flag);
+    }
+    const ownedSet = new Set(owned);
+    const byFile = new Map();
+    for (const section of sections) {
+        const file = normalizeEngineRelativeInput(section.targetPath, selection.flag);
+        if (section.isBinary || section.sourcePath !== section.targetPath) {
+            throw new InvalidArgumentError(`${selection.flag}: the section for ${file} is binary or a rename; only text hunks can be selected.`, selection.flag);
+        }
+        if (!ownedSet.has(file)) {
+            throw new InvalidArgumentError(`${selection.flag}: ${file} is not a file this patch owns.`, selection.flag);
+        }
+        byFile.set(file, section);
+    }
+    return byFile;
+}
+/**
+ * Builds the re-export body for a hunk-selected run: named files from the
+ * selected hunks, the rest from the old body (`--hunks-from`) or the normal
+ * working-tree diff (`--exclude-hunks`).
+ *
+ * @param args.normalDiff - The diff a plain re-export would write
+ * @param args.oldBody - The patch's current body
+ * @param args.files - The files the refreshed patch owns
+ */
+export async function buildHunkSelectedDiff(args) {
+    const { engineDir, selection, oldBody, normalDiff, files } = args;
+    const named = await readSelection(selection, files);
+    const tracked = await listTrackedInHead(engineDir, [...named.keys()]);
+    const fallback = splitRawSections(selection.mode === 'include' ? oldBody : normalDiff);
+    const out = [];
+    for (const file of [...files].sort()) {
+        const section = named.get(file);
+        if (section === undefined) {
+            const raw = fallback.get(file);
+            if (raw !== undefined)
+                out.push(raw);
+            continue;
+        }
+        const head = tracked.has(file) ? await getFileContentAtRef(engineDir, file) : null;
+        let content;
+        if (selection.mode === 'include') {
+            const base = applyPatchTextToContent(head, oldBody, file);
+            content = applyHunksByContext(base, section.hunks, false, file);
+        }
+        else {
+            const worktree = join(engineDir, file);
+            const current = (await pathExists(worktree)) ? await readText(worktree) : '';
+            content = applyHunksByContext(current, section.hunks, true, file);
+        }
+        if (head !== null && content === head)
+            continue;
+        const diff = await diffContentAgainstHead(engineDir, file, content, tracked.has(file));
+        if (diff.trim())
+            out.push(diff.endsWith('\n') ? diff : `${diff}\n`);
+    }
+    return out.join('');
+}

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

@@ -103,12 +103,37 @@ function validateExpectedRemovalUsage(patches, options) {
         throw new InvalidArgumentError('--expect-removed requires explicit selected patches and the scan-less path (no --scan, --files, or --all).', '--expect-removed');
     }
 }
+/**
+ * `--hunks-from` and `--exclude-hunks` rebuild one patch's files from named
+ * hunks, so they take exactly one explicit patch and no flag that sets the
+ * file list another way.
+ */
+function validateHunkSelectionUsage(patches, options) {
+    if (options.hunksFrom !== undefined && options.excludeHunks !== undefined) {
+        throw new InvalidArgumentError('--hunks-from and --exclude-hunks are alternatives; pass one.', '--hunks-from');
+    }
+    const flag = options.hunksFrom !== undefined
+        ? '--hunks-from'
+        : options.excludeHunks !== undefined
+            ? '--exclude-hunks'
+            : undefined;
+    if (flag === undefined)
+        return;
+    if (patches.length !== 1 ||
+        options.all ||
+        options.scan ||
+        options.files !== undefined ||
+        options.scanFilesManifest !== undefined) {
+        throw new InvalidArgumentError(`${flag} rebuilds one patch's files from named hunks: pass exactly one patch, without --scan, --files or --all.`, flag);
+    }
+}
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export function validateReExportOptionCombinations(patches, options) {
     // First: a swallowed flag would otherwise surface as whichever
     // combination error it happens to trip, naming the wrong problem.
     validatePathFlagValues(options);
     validateExpectedRemovalUsage(patches, options);
+    validateHunkSelectionUsage(patches, options);
     if (options.files !== undefined) {
         if (options.all || options.scan) {
             throw new InvalidArgumentError('--files cannot be combined with --scan or --all.', '--files');
@@ -140,8 +165,10 @@ 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');
+    // Beside --scan the belt judges the neighbours the scan did not adopt;
+    // --files replaces the file list outright, so there is nothing to judge.
+    if (options.refuseAdjacentUnmanaged === true && options.files !== undefined) {
+        throw new InvalidArgumentError('--refuse-adjacent-unmanaged cannot be combined with --files (it sets filesAffected explicitly).', '--refuse-adjacent-unmanaged');
     }
     // Beside --scan the belt covers the files each patch already owns; the
     // files a scan adopts are the run's stated intent. --files replaces the

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

@@ -0,0 +1,18 @@
+import type { PatchMetadata } from '../types/commands/index.js';
+/** What a scoped dry run could touch: the patches it was asked about. */
+export interface DryRunPurityScope {
+    /** The selected patches. */
+    patches: readonly PatchMetadata[];
+}
+/**
+ * Fingerprints exactly the state a scoped `re-export --dry-run` could
+ * disturb. Every key names what it covers, so a violation reads as the
+ * path that moved.
+ */
+export declare function fingerprintScopedDryRunState(engineDir: string, patchesDir: string, scope: DryRunPurityScope): Promise<Map<string, string>>;
+/**
+ * Names whoever else wrote during the dry run: history records from other
+ * invocations since it started, and a live holder of the engine-session
+ * lock (which a dry run no longer takes). Empty when there is no evidence.
+ */
+export declare function describeForeignWriters(patchesDir: string, sinceMs: number): Promise<string[]>;