@hominis/fireforge 0.47.1 → 0.49.0

package/dist/src/core/typecheck.js

@@ -18,11 +18,15 @@
  * without installing it, the function returns a clear error pointing
  * at `npm install typescript`.
  */
-import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { mkdir, readdir, rm } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose } from '../utils/logger.js';
+import { getPackageVersion } from '../utils/package-root.js';
 import { normalizePathSlashes } from '../utils/paths.js';
+import { withGeckoDomTypes } from './gecko-dom-types.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 /**
  * Sentinel string surfaced as a `TypecheckIssue.message` when the
@@ -60,7 +64,7 @@ export const CHECK_JS_DISABLED_NOTICE = 'Project sets "checkJs: false" — skipp
  *   in declared order. The CLI is responsible for printing the issues
  *   and computing the exit code.
  */
-export async function runTypecheck(projectRoot, cfg) {
+export async function runTypecheck(projectRoot, cfg, runOptions = {}) {
     // Dynamic import, so typescript stays a dev dependency. Same pattern
     // as `patch-lint-checkjs.ts`. The empty-projects-array case is
     // already rejected by config-validate, so we don't gate the import
@@ -133,7 +137,9 @@ export async function runTypecheck(projectRoot, cfg) {
             });
             continue;
         }
-        results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource, cfg.undefinedIdentifiers ?? 'warning'));
+        results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource, cfg.undefinedIdentifiers ?? 'warning', runOptions.noCache === true
+            ? undefined
+            : (runOptions.cacheDir ?? join(projectRoot, '.fireforge', 'typecheck'))));
     }
     return results;
 }
@@ -151,7 +157,7 @@ function resolveProjectExtraShim(cfg, projectPath) {
     return cfg.extraShim;
 }
 /** Runs typecheck for a single jsconfig path, isolating its failures. */
-async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource, undefinedIdentifiers = 'warning') {
+async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource, undefinedIdentifiers = 'warning', cacheDir) {
     const absConfig = resolve(projectRoot, projectPath);
     if (!(await pathExists(absConfig))) {
         return {
@@ -223,12 +229,12 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         noEmit: true,
         allowJs: parsed.options.allowJs ?? true,
         checkJs: parsed.options.checkJs ?? true,
-        // No incremental sidecar, ever. A user jsconfig under `engine/` that sets
-        // `incremental` (or names a `tsBuildInfoFile`) would have this command
-        // drop a `.tsbuildinfo` inside the primary engine checkout: a second
-        // writer that invalidates a concurrent `fireforge test`'s engine
-        // fingerprint. This command emits nothing, so the sidecar buys nothing
-        // either.
+        // Never the jsconfig's own incremental sidecar: a user jsconfig under
+        // `engine/` that sets `incremental` (or names a `tsBuildInfoFile`) would
+        // have this command drop a `.tsbuildinfo` inside the primary engine
+        // checkout, a second writer that invalidates a concurrent
+        // `fireforge test`'s engine fingerprint. FireForge's own build info
+        // lives under `.fireforge/typecheck/` instead (see below).
         incremental: false,
         // skipLibCheck is not forced. The user owns it via their jsconfig.
     };
@@ -247,7 +253,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
     // filtered out below, so the pass reports failures that do not exist.
     const shimPath = normalizePathSlashes(resolve(projectDir, `.fireforge-${SHIM_FILENAME}`));
     const rootFiles = [...parsed.fileNames, shimPath];
-    const defaultHost = ts.createCompilerHost(options);
+    const defaultHost = withGeckoDomTypes(ts, ts.createCompilerHost(options));
     const host = {
         ...defaultHost,
         getSourceFile(fileName, languageVersion, onError, shouldCreate) {
@@ -267,7 +273,37 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
             return defaultHost.readFile(fileName);
         },
     };
-    const program = ts.createProgram(rootFiles, options, host);
+    // Incremental build info, keyed by everything outside the program's own
+    // files that can change a verdict: the composed shim, the TypeScript
+    // version, the compiler options, the undefined-identifier gate and the
+    // FireForge version. A change to any of them selects a different file,
+    // so a stale verdict is never replayed. Files inside the program are
+    // tracked by TypeScript's own per-file hashes in the build info.
+    const buildInfoFile = cacheDir === undefined
+        ? undefined
+        : await prepareBuildInfoFile(cacheDir, projectPath, {
+            shim: sha256Hex(shimSource),
+            typescript: ts.version,
+            fireforge: getPackageVersion(),
+            undefinedIdentifiers,
+            options,
+        });
+    let program;
+    let writeBuildInfo = () => undefined;
+    if (buildInfoFile === undefined) {
+        program = ts.createProgram(rootFiles, options, host);
+    }
+    else {
+        // Always check the entire project in root order. Restoring TypeScript's
+        // per-file semantic cache makes checkJs inference depend on the first
+        // invalidated importer and can both invent and hide diagnostics.
+        const builder = ts.createEmitAndSemanticDiagnosticsBuilderProgram(rootFiles, { ...options, incremental: true, tsBuildInfoFile: buildInfoFile }, withSourceFileVersions(host));
+        program = builder;
+        // Under noEmit, emit() writes the build info and nothing else.
+        writeBuildInfo = () => {
+            builder.emit();
+        };
+    }
     // Collect the full diagnostic set. patchLint reads only semantic +
     // syntactic, which is fine for hygiene but wrong for CI: a misconfigured
     // `lib: ["es2015"]` or a missing `paths` target should fail
@@ -298,6 +334,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         }
         issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
     }
+    writeBuildInfo();
     verbose(`typecheck: ${projectPath} — analyzed ${parsed.fileNames.length} file(s), found ${issues.length} issue(s)`);
     return {
         project: projectPath,
@@ -305,6 +342,43 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         filesChecked: parsed.fileNames.length,
     };
 }
+/**
+ * Stamps every source file with a content-hash version, which the
+ * incremental builder requires and a plain compiler host never sets.
+ * `ts.createIncrementalCompilerHost` does the same internally, but the
+ * shim here is served by a custom host rather than read from disk.
+ */
+function withSourceFileVersions(host) {
+    const getSourceFile = host.getSourceFile.bind(host);
+    return {
+        ...host,
+        getSourceFile(...args) {
+            const file = getSourceFile(...args);
+            if (file !== undefined) {
+                file.version = sha256Hex(file.text);
+            }
+            return file;
+        },
+    };
+}
+/**
+ * Resolves the build-info path for one project and key, creating the cache
+ * directory and removing the project's build info for any other key: a
+ * shim or TypeScript change leaves the old file unreachable anyway.
+ * @returns Absolute build-info path
+ */
+async function prepareBuildInfoFile(cacheDir, projectPath, keyInputs) {
+    const slug = projectPath.replace(/[^A-Za-z0-9._-]+/g, '_');
+    const key = sha256Hex(JSON.stringify(keyInputs)).slice(0, 16);
+    const fileName = `${slug}-${key}.tsbuildinfo`;
+    await mkdir(cacheDir, { recursive: true });
+    for (const entry of await readdir(cacheDir)) {
+        if (entry !== fileName && entry.startsWith(`${slug}-`) && entry.endsWith('.tsbuildinfo')) {
+            await rm(join(cacheDir, entry), { force: true });
+        }
+    }
+    return join(cacheDir, fileName);
+}
 /**
  * Converts a TS Diagnostic to a TypecheckIssue. The `fallbackFile`
  * is used when the diagnostic carries no source file (typical for

package/dist/src/errors/rebase.d.ts

@@ -31,3 +31,12 @@ export declare class NoRebaseSessionError extends RebaseError {
 export declare class CorruptRebaseSessionError extends RebaseError {
     constructor(sessionPath: string, reason: string);
 }
+/**
+ * Thrown by `rebase --dry-run` when the replay rejects at least one patch.
+ * A dry run that exited 0 regardless used to read as "the rebase is ready".
+ */
+export declare class RebaseDryRunRejectError extends RebaseError {
+    readonly rejected: readonly string[];
+    constructor(rejected: readonly string[]);
+    get userMessage(): string;
+}

package/dist/src/errors/rebase.js

@@ -49,3 +49,23 @@ export class CorruptRebaseSessionError extends RebaseError {
             'or delete the file to start over.');
     }
 }
+/**
+ * Thrown by `rebase --dry-run` when the replay rejects at least one patch.
+ * A dry run that exited 0 regardless used to read as "the rebase is ready".
+ */
+export class RebaseDryRunRejectError extends RebaseError {
+    rejected;
+    constructor(rejected) {
+        super(`Dry run: ${rejected.length} patch(es) would not apply: ${rejected.join(', ')}. ` +
+            'engine/ was not modified.');
+        this.rejected = rejected;
+    }
+    get userMessage() {
+        return (`Rebase Error: ${this.message}` +
+            remedies([
+                'The per-patch lines above name the files that did not apply',
+                'Run "fireforge rebase" to start the real rebase; it stops at the first reject for manual resolution',
+                'Later rejects may cascade from an earlier one; resolve in queue order',
+            ]));
+    }
+}

package/dist/src/index.d.ts

@@ -16,12 +16,14 @@
  * @packageDocumentation
  */
 export { loadConfig, validateConfig } from './core/config.js';
+export type { FindForwardRegistrationsOptions, ForwardRegistration, ForwardRegistrationKind, ForwardRegistrationScope, } from './core/forward-registrations.js';
+export { findForwardRegistrations } from './core/forward-registrations.js';
 export type { ApplyAllComponentsResult } from './core/furnace-apply.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
 export type { PatchSizeTierDecision } from './core/patch-lint.js';
-export { countNonBinaryDiffLines, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
+export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
 export type { AddTokenOptions, AddTokenResult, TokenMode } from './core/token-manager.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';

package/dist/src/index.js

@@ -17,10 +17,11 @@
  * @packageDocumentation
  */
 export { loadConfig, validateConfig } from './core/config.js';
+export { findForwardRegistrations } from './core/forward-registrations.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
-export { countNonBinaryDiffLines, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
+export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';

package/dist/src/types/commands/options.d.ts

@@ -85,6 +85,8 @@ export interface SetupOptions {
 export interface DownloadOptions {
     /** Force re-download, deleting existing engine/ */
     force?: boolean;
+    /** With `force`: skip the confirmation for an engine with changes to lose */
+    yes?: boolean;
 }
 /**
  * Options for the source command.
@@ -107,6 +109,8 @@ export interface SourceSetOptions {
  * Options for the build command.
  */
 export interface BuildOptions extends EngineLockWaitable {
+    /** Wait for the objdir browser before deploying/building. */
+    waitBrowser?: number | boolean;
     /** Fast UI-only rebuild */
     ui?: boolean;
     /** Number of parallel jobs */
@@ -366,6 +370,8 @@ export interface ReExportOptions extends EngineLockWaitable {
      * rather than hidden.
      */
     expectUnmanaged?: string[];
+    /** Explicitly retire named absent patch-created files in a scan-less export. */
+    expectRemoved?: string[];
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -497,6 +503,13 @@ export interface RebaseOptions {
 export interface RunOptions {
     /** Additional arguments to pass to the browser */
     args?: string[];
+    /** Launch with this profile directory, passed to Firefox as `-profile`. */
+    profile?: string;
+    /**
+     * Launch with a fresh temporary profile, removed when the run ends.
+     * Implied by `smokeExit` unless `profile` is given.
+     */
+    tempProfile?: boolean;
     /**
      * Enable smoke-run mode. Launches the browser, streams the console,
      * sends SIGTERM to the whole process group after `smokeExit` seconds,
@@ -542,6 +555,12 @@ export interface RunOptions {
  * Options for the test command.
  */
 export interface TestOptions extends EngineLockWaitable {
+    /** Queue behind a browser using this objdir; bare flag means 60 seconds. */
+    waitBrowser?: number | boolean;
+    /** Queue behind the mochitest/Marionette port holder. */
+    waitPort?: number | boolean;
+    /** Copy a file into the profile at a relative destination (repeatable source=destination). */
+    profileFile?: string[];
     /** Run tests in headless mode */
     headless?: boolean;
     /**
@@ -666,9 +685,10 @@ export interface TestOptions extends EngineLockWaitable {
      */
     perfSamples?: string;
     /**
-     * Seeded file-order shuffle for mochitest runs. `true` draws a fresh seed;
-     * a number replays one. Forwarded as mach `--shuffle` with the seed
-     * exported as `FIREFORGE_SHUFFLE_SEED` and stamped on the verdict line.
+     * Seeded isolated path-argument order for mochitest runs. `true` draws a
+     * fresh seed; a number replays the shard permutation. Native mach
+     * `--shuffle` within a shard remains unseeded. Also exported as
+     * `FIREFORGE_SHUFFLE_SEED` for custom task code and recorded on the verdict.
      */
     shuffle?: number | boolean;
 }
@@ -1115,4 +1135,10 @@ export interface LintCommandOptions {
      * {@link perPatch}.
      */
     report?: string;
+    /**
+     * With `--per-patch`: `'full'` (default) prints every NOTICE line;
+     * `'summary'` prints one line per check with its count and patch count.
+     * Errors and warnings always print in full.
+     */
+    notices?: 'summary' | 'full';
 }

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

@@ -355,6 +355,16 @@ export interface PatchLintConfig {
      * scope for the per-patch tier.
      */
     prettier?: PatchLintSeverityGate;
+    /**
+     * Which carriers the `forward-registration` queue rule checks for a line
+     * that names a file only a later patch creates. `'support-files'` (the
+     * default) checks test-manifest `support-files`. `'extended'` also checks
+     * jar.mn pair lines, moz.build path tokens, test-manifest sections and
+     * `head`, and customElements.js chrome URLs resolved through the queue's
+     * own jar.mn lines. Opt-in: a queue that predates the wider rule can carry
+     * such edges, and a new error on install would red its gate.
+     */
+    forwardRegistration?: 'support-files' | 'extended';
     /** Enforce JSDoc on class-method exports in patch-owned .sys.mjs files. Default: 'off'. */
     jsdocClassMethods?: PatchLintSeverityGate;
     /** Require ≥1 assertion in any patch-touched browser_*.js test file (new or modified). Default: 'off'. */

package/dist/src/utils/assert.js

@@ -11,13 +11,8 @@
  * says the opposite: nothing the operator could have done would have
  * prevented it.
  *
- * Every check routes through a helper here rather than being open-coded
- * as `if (!condition) throw`. An inline throw adds a
- * permanently-uncovered branch to every function it appears in, and the
- * per-module coverage floors in `scripts/check-coverage-thresholds.mjs`
- * would pay for it in ~40 places. Routed through a call, the branch lives
- * here once and is covered here once, and the `complexity` ceiling in
- * `eslint.config.js` does not see it at all.
+ * Shared helpers provide consistent classification and TypeScript narrowing,
+ * and keep expensive failure descriptions lazy on successful paths.
  *
  * This module is a leaf: it imports the error class and nothing else, per
  * the dependency-direction note in `src/utils/errors.ts`.

package/dist/src/utils/child-env.d.ts

@@ -1,8 +1,5 @@
 /**
  * Environment construction for spawned children.
- *
- * Its own module rather than a helper inside `process.ts` only because that
- * file sits on a 500-line budget. The logic belongs to the exec layer.
  */
 /** The `env` / `envUnset` slice of exec options this module needs. */
 interface ChildEnvOptions {

package/dist/src/utils/child-env.js

@@ -1,9 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Environment construction for spawned children.
- *
- * Its own module rather than a helper inside `process.ts` only because that
- * file sits on a 500-line budget. The logic belongs to the exec layer.
  */
 /**
  * The child's environment: `process.env`, with `env` merged over it, then

package/dist/src/utils/concurrency.d.ts

@@ -1,8 +1,8 @@
 /**
  * Bounded-concurrency helpers shared by commands that fan out per-file IO
  * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). Kept tiny: one order-preserving mapper, no
- * queues, no cancellation.
+ * the dry-run purity guard). On failure, stop scheduling new items and await
+ * every started operation before rejecting, so callers can safely clean up.
  */
 /** Maps items with at most `limit` in-flight promises. Preserves order. */
 export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/src/utils/concurrency.js

@@ -1,21 +1,32 @@
 /**
  * Bounded-concurrency helpers shared by commands that fan out per-file IO
  * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). Kept tiny: one order-preserving mapper, no
- * queues, no cancellation.
+ * the dry-run purity guard). On failure, stop scheduling new items and await
+ * every started operation before rejecting, so callers can safely clean up.
  */
 /** Maps items with at most `limit` in-flight promises. Preserves order. */
 export async function mapWithConcurrency(items, limit, fn) {
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw new RangeError('Concurrency limit must be a positive integer');
+    }
     const results = new Array(items.length);
     let next = 0;
+    const state = {};
     const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-        for (;;) {
+        while (!state.failure) {
             const index = next++;
             if (index >= items.length)
                 return;
-            results[index] = await fn(items[index], index);
+            try {
+                results[index] = await fn(items[index], index);
+            }
+            catch (error) {
+                state.failure ??= { error };
+            }
         }
     });
     await Promise.all(workers);
+    if (state.failure)
+        throw state.failure.error;
     return results;
 }

package/dist/src/utils/fs.js

@@ -99,7 +99,17 @@ export async function isSymlink(path) {
  */
 export async function copyFile(src, dest) {
     await ensureParentDir(dest);
-    await fsCopyFile(src, dest);
+    // Never follow a destination symlink or truncate a shared hardlink:
+    // build/deploy copies must not write through into components/ or a peer.
+    const tempPath = createAtomicTempPath(dest);
+    try {
+        await fsCopyFile(src, tempPath);
+        await renameWithRetries(tempPath, dest);
+        await syncParentDir(dest);
+    }
+    finally {
+        await rm(tempPath, { force: true });
+    }
 }
 /**
  * Reads a JSON file and parses it.

package/dist/src/utils/options.d.ts

@@ -89,7 +89,22 @@ export declare function resolveWaitLockSeconds(value: string | number | boolean
  */
 export declare function sessionWaitLockMs(): number | undefined;
 /**
- * Recursively gives every command in the tree a `--wait-lock` flag: the
+ * Registers `--wait-lock [seconds]` on a command that takes no lock, so a
+ * scripted sequence can blanket-append the flag without hitting a usage
+ * error. A command that rejects it with "unknown option" kills the whole
+ * sequence with a usage error instead of a lock message.
+ *
+ * The flag is accepted and ignored here, never silently repurposed, and
+ * the help text says so, so nobody reads its presence as evidence that this
+ * command waits for anything.
+ *
+ * The value is parsed and validated exactly as the honoring variant does:
+ * `--wait-lock nonsense` must still be a usage error everywhere, or the
+ * uniformity would be a lie.
+ */
+export declare function addAcceptedWaitLockOption(command: Command): Command;
+/**
+ * Recursively gives every leaf command in the tree a `--wait-lock` flag: the
  * honoring registration where one already exists, the accept-and-ignore
  * one everywhere else.
  */

package/dist/src/utils/options.js

@@ -182,7 +182,7 @@ export function sessionWaitLockMs() {
  * `--wait-lock nonsense` must still be a usage error everywhere, or the
  * uniformity would be a lie.
  */
-function addAcceptedWaitLockOption(command) {
+export function addAcceptedWaitLockOption(command) {
     return command.option('--wait-lock [seconds]', 'Accepted for scripting uniformity and ignored: this command takes no FireForge lock', commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
 }
 /**
@@ -194,13 +194,15 @@ function hasWaitLockOption(command) {
     return command.options.some((option) => option.long === '--wait-lock');
 }
 /**
- * Recursively gives every command in the tree a `--wait-lock` flag: the
+ * Recursively gives every leaf command in the tree a `--wait-lock` flag: the
  * honoring registration where one already exists, the accept-and-ignore
  * one everywhere else.
  */
 export function ensureWaitLockOptionEverywhere(command) {
     for (const sub of command.commands) {
-        if (!hasWaitLockOption(sub))
+        // Commander groups otherwise capture a trailing leaf option before the
+        // action can see it. Register the uniform flag only on actionable leaves.
+        if (sub.commands.length === 0 && !hasWaitLockOption(sub))
             addAcceptedWaitLockOption(sub);
         ensureWaitLockOptionEverywhere(sub);
     }

package/dist/src/utils/paths.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { isAbsolute, relative, resolve } from 'node:path';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 const WINDOWS_ABSOLUTE_PATH = /^[a-zA-Z]:[\\/]/;
 const RELATIVE_PATH_ROOT = resolve('/__fireforge_path_root__');
 /**
@@ -55,7 +55,8 @@ export function isPathInsideRoot(root, candidate) {
         : resolve(resolvedRoot, candidate);
     const relativePath = relative(resolvedRoot, resolvedCandidate);
     return (relativePath === '' ||
-        (!relativePath.startsWith('..') &&
+        (relativePath !== '..' &&
+            !relativePath.startsWith(`..${sep}`) &&
             !isAbsolute(relativePath) &&
             !WINDOWS_ABSOLUTE_PATH.test(relativePath)));
 }

package/dist/src/utils/process-group.d.ts

@@ -1,6 +1,5 @@
 /**
- * Process-group kill and post-run sweep helpers for the exec layer. Split
- * out of `process.ts` to keep that file within the per-file line budget.
+ * Process-group kill and post-run sweep helpers for the exec layer.
  * Spawn-based rather than `exec`-based so the two modules do not import
  * each other cyclically.
  */

package/dist/src/utils/process-group.js

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Process-group kill and post-run sweep helpers for the exec layer. Split
- * out of `process.ts` to keep that file within the per-file line budget.
+ * Process-group kill and post-run sweep helpers for the exec layer.
  * Spawn-based rather than `exec`-based so the two modules do not import
  * each other cyclically.
  */

package/dist/src/utils/process-input.d.ts

@@ -0,0 +1,27 @@
+/** Options for {@link execWithInput}. */
+export interface ExecWithInputOptions {
+    /** Working directory for the command */
+    cwd?: string;
+    /** Environment variables merged over `process.env` */
+    env?: Record<string, string>;
+}
+/** Result of {@link execWithInput}: stdout stays raw bytes. */
+export interface ExecBufferResult {
+    /** Standard output, uncapped and undecoded */
+    stdout: Buffer;
+    /** Standard error, decoded as UTF-8 */
+    stderr: string;
+    /** Process exit code */
+    exitCode: number;
+}
+/**
+ * Runs a command, writes `input` to its stdin, and returns stdout as raw
+ * bytes. For batch protocols (`git cat-file --batch`) whose framing counts
+ * bytes: the decoded, 50 MB-capped collector `exec` uses would corrupt
+ * both. The caller bounds the input, and so the output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param input - Bytes written to stdin, which is then closed
+ * @param options - Execution options
+ */
+export declare function execWithInput(command: string, args: string[], input: string | Buffer, options?: ExecWithInputOptions): Promise<ExecBufferResult>;

package/dist/src/utils/process-input.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Stdin-fed command execution with byte-exact stdout.
+ */
+import { spawn } from 'node:child_process';
+import { buildChildEnv } from './child-env.js';
+import { exitCodeFromClose } from './process.js';
+/**
+ * Runs a command, writes `input` to its stdin, and returns stdout as raw
+ * bytes. For batch protocols (`git cat-file --batch`) whose framing counts
+ * bytes: the decoded, 50 MB-capped collector `exec` uses would corrupt
+ * both. The caller bounds the input, and so the output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param input - Bytes written to stdin, which is then closed
+ * @param options - Execution options
+ */
+export async function execWithInput(command, args, input, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: buildChildEnv(options),
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (chunk) => {
+            out.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            err.push(chunk);
+        });
+        // A child that exits before reading all of stdin (a bad ref, say) makes
+        // the write fail with EPIPE. The close handler reports the real outcome.
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(input);
+        child.on('error', reject);
+        child.on('close', (code, signal) => {
+            resolve({
+                stdout: Buffer.concat(out),
+                stderr: Buffer.concat(err).toString('utf8'),
+                exitCode: exitCodeFromClose(code, signal),
+            });
+        });
+    });
+}

package/dist/src/utils/process.d.ts

@@ -104,6 +104,8 @@ export interface ProcessGroupOptions {
      */
     postCloseSweep?: () => Promise<void>;
 }
+/** A child's exit code, with a signal death mapped to 128 + its number. */
+export declare function exitCodeFromClose(code: number | null, signal: NodeJS.Signals | null): number;
 /**
  * Executes a command and returns its output.
  * @param command - Command to execute
@@ -148,8 +150,9 @@ export declare function execStream(command: string, args: string[], options?: St
  * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
  * wait for, and returns the handle that deregisters it.
  *
- * @returns `settle()`. Call from both the child's `close` and `error`
- *   handlers so a dead child never holds the shutdown wait open
+ * @returns `settle()`. Call after child closure and required teardown finish.
+ *   An abort's `error` event does not prove closure; do not settle there.
+ *   A failed start may settle when no live child or teardown remains.
  */
 export declare function trackChildClosure(): {
     settle: () => void;