@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/core/patch-policy.d.ts

@@ -9,7 +9,7 @@
 import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig, PatchPolicyConfig, PatchPolicyRange } from '../types/config.js';
 /** Stable issue codes returned by patch policy evaluation. */
-export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap';
+export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap' | 'upstream-allowlist' | 'add-only' | 'scope' | 'reserved-document-missing';
 /** A single patch policy validation finding. */
 export interface PatchPolicyIssue {
     code: PatchPolicyIssueCode;
@@ -30,6 +30,15 @@ export interface PatchPolicyEnforcementInput {
      * `patch move-files --create`).
      */
     hints?: Partial<Record<PatchPolicyIssueCode, string>>;
+    /**
+     * Patch filenames whose findings this mutation answers for. When set, only
+     * issues attributed to these rows are enforced: queue-level findings
+     * (order collisions, numeric gaps) and other patches' findings are left to
+     * `verify` and `lint --per-patch`. For mutations that change only the
+     * scoped rows' contents (`re-export`), so one patch's stale row cannot fail
+     * an unrelated patch refreshed in the same call.
+     */
+    scope?: readonly string[];
 }
 /** Returns valid categories for prompts and CLI validation under the config. */
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];
@@ -49,8 +58,12 @@ export declare function categoryRangeLabel(ranges: readonly PatchPolicyRange[],
  */
 export declare function categoryRangeForOrder(cfg: PatchPolicyConfig, category: string, order: number): PatchPolicyRange | null;
 /** Evaluates an entire patch manifest against the configured policy. */
-export declare function evaluatePatchPolicy(config: FireForgeConfig, manifest: PatchesManifest): PatchPolicyIssue[];
-/** Builds a sorted manifest snapshot from projected patch metadata. */
+export declare function evaluatePatchPolicy(config: Pick<FireForgeConfig, 'patchPolicy'>, manifest: PatchesManifest): PatchPolicyIssue[];
+/**
+ * Builds a sorted manifest snapshot from projected patch metadata. Retired
+ * slots of `current` carry over unless a projected patch fills them, so a
+ * projection judges gaps the way the written manifest will.
+ */
 export declare function buildProjectedManifest(current: PatchesManifest | null, patches: PatchMetadata[]): PatchesManifest;
 /** Applies a filename/order rename projection to a manifest without mutating it. */
 export declare function applyRenameMapToManifest(manifest: PatchesManifest, renameMap: ReadonlyMap<string, {
@@ -59,5 +72,9 @@ export declare function applyRenameMapToManifest(manifest: PatchesManifest, rena
 }>): PatchesManifest;
 /** Enforces patch policy according to the configured mutation mode. */
 export declare function enforcePatchPolicy(input: PatchPolicyEnforcementInput): void;
-/** Allocates the next available order inside the configured ranges for a category. */
-export declare function allocatePolicyOrder(config: FireForgeConfig, patches: readonly PatchMetadata[], category: string): number | null;
+/**
+ * Allocates the next available order inside the configured ranges for a
+ * category. Orders in `reserved` (`patch reserve`) are skipped: they are
+ * held for their owner's export.
+ */
+export declare function allocatePolicyOrder(config: FireForgeConfig, patches: readonly PatchMetadata[], category: string, reserved?: ReadonlySet<number>): number | null;

package/dist/src/core/patch-policy.js

@@ -12,6 +12,7 @@ import { warn } from '../utils/logger.js';
 import { PATCH_CATEGORIES } from '../utils/validation.js';
 import { rewriteStagedDependencyOwners } from './patch-manifest-io.js';
 import { formatOrderRange, formatPatchOrder } from './patch-parse.js';
+import { manifestWithRetiredSlots, reservedOrderSet, retiredOrderSet } from './patch-retired.js';
 /** Default patch filename contract used when a policy omits `filenamePattern`. */
 const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = '^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$';
 function policy(config) {
@@ -222,7 +223,7 @@ function evaluatePatchMetadata(cfg, patch, severity) {
     }
     return issues;
 }
-function evaluateGaps(cfg, patches, severity) {
+function evaluateGaps(cfg, patches, severity, retiredOrders = new Set()) {
     if (cfg.allowGaps !== false)
         return [];
     const issues = [];
@@ -243,7 +244,11 @@ function evaluateGaps(cfg, patches, severity) {
         const last = occupied[occupied.length - 1];
         const missing = [];
         for (let order = first; order <= last; order++) {
-            if (!occupiedSet.has(order) && reservedRangeForOrder(cfg, order) === null) {
+            // A retired slot (`patch retire`) or a reservation (`patch reserve`)
+            // is an occupied order with no patch behind it, so it is not a gap.
+            if (!occupiedSet.has(order) &&
+                !retiredOrders.has(order) &&
+                reservedRangeForOrder(cfg, order) === null) {
                 missing.push(order);
             }
         }
@@ -290,18 +295,22 @@ export function evaluatePatchPolicy(config, manifest) {
     const severity = mutationMode(config) === 'warn' ? 'warning' : 'error';
     const issues = manifest.patches.flatMap((patch) => evaluatePatchMetadata(cfg, patch, severity));
     issues.push(...evaluateOrderCollisions(manifest.patches, severity));
-    issues.push(...evaluateGaps(cfg, manifest.patches, severity));
+    // Retired and reserved slots are both spent orders with no patch behind
+    // them: neither is a gap.
+    const placeholders = new Set([...retiredOrderSet(manifest), ...reservedOrderSet(manifest)]);
+    issues.push(...evaluateGaps(cfg, manifest.patches, severity, placeholders));
     return issues;
 }
-/** Builds a sorted manifest snapshot from projected patch metadata. */
+/**
+ * Builds a sorted manifest snapshot from projected patch metadata. Retired
+ * slots of `current` carry over unless a projected patch fills them, so a
+ * projection judges gaps the way the written manifest will.
+ */
 export function buildProjectedManifest(current, patches) {
     const next = patches
         .map((patch) => ({ ...patch, filesAffected: [...patch.filesAffected] }))
         .sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-    return {
-        version: current?.version ?? 1,
-        patches: next,
-    };
+    return manifestWithRetiredSlots(current, next);
 }
 /** Applies a filename/order rename projection to a manifest without mutating it. */
 export function applyRenameMapToManifest(manifest, renameMap) {
@@ -325,7 +334,8 @@ export function applyRenameMapToManifest(manifest, renameMap) {
 export function enforcePatchPolicy(input) {
     if (policy(input.config) === undefined)
         return;
-    const issues = evaluatePatchPolicy(input.config, input.manifest);
+    const scope = input.scope === undefined ? undefined : new Set(input.scope);
+    const issues = evaluatePatchPolicy(input.config, input.manifest).filter((issue) => scope === undefined || scope.has(issue.filename));
     if (issues.length === 0)
         return;
     const mode = mutationMode(input.config);
@@ -350,8 +360,12 @@ export function enforcePatchPolicy(input) {
         : '';
     throw new InvalidArgumentError(`${input.command} would violate patchPolicy:\n${details.join('\n')}${suffix}`, mode === 'force' ? '--force-unsafe' : 'patchPolicy');
 }
-/** Allocates the next available order inside the configured ranges for a category. */
-export function allocatePolicyOrder(config, patches, category) {
+/**
+ * Allocates the next available order inside the configured ranges for a
+ * category. Orders in `reserved` (`patch reserve`) are skipped: they are
+ * held for their owner's export.
+ */
+export function allocatePolicyOrder(config, patches, category, reserved = new Set()) {
     const cfg = policy(config);
     if (!cfg)
         return null;
@@ -360,7 +374,7 @@ export function allocatePolicyOrder(config, patches, category) {
         .sort((a, b) => a.from - b.from || a.to - b.to);
     if (ranges.length === 0)
         return null;
-    const occupied = new Set(patches.map((patch) => patch.order));
+    const occupied = new Set([...patches.map((patch) => patch.order), ...reserved]);
     const highestInRanges = patches.reduce((highest, patch) => {
         if (!ranges.some((range) => patch.order >= range.from && patch.order <= range.to)) {
             return highest;

package/dist/src/core/patch-retired.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Retired order slots: the placeholders `patch retire` leaves in
+ * `patches.json#retired` so a patch can leave the queue without opening a
+ * numeric gap or renumbering its successors.
+ *
+ * A slot is not a patch. It has no `.patch` file and no row in `patches`,
+ * so everything that applies, exports, lints or rebases the queue walks past
+ * it without knowing it exists. The one reader is the
+ * `patchPolicy.allowGaps: false` gap check, which counts a retired order as
+ * occupied. A patch that later takes the same order fills the slot, and
+ * {@link carryRetiredSlots} drops it on that write, so the manifest never
+ * holds a slot and a patch at one order.
+ *
+ * Reserved slots (`patch reserve`) follow the same rules: a placeholder for
+ * an order a session has claimed but not exported yet, counted as occupied
+ * by the gap check and filled (and dropped) by the export that lands on it.
+ */
+import type { PatchesManifest, PatchMetadata, PatchReservedSlot, PatchRetiredSlot } from '../types/commands/index.js';
+/**
+ * The retired slots of `current` that no patch in `patches` occupies, or
+ * undefined when none remain. Every manifest write that rebuilds the
+ * `patches` list routes the slots through here, so a slot survives the
+ * rewrite and a filled one does not.
+ *
+ * @param current - Manifest the slots come from (null or slot-free: none)
+ * @param patches - The rows the written manifest will hold
+ */
+export declare function carryRetiredSlots(current: Pick<PatchesManifest, 'retired'> | null | undefined, patches: readonly Pick<PatchMetadata, 'order'>[]): PatchRetiredSlot[] | undefined;
+/**
+ * Reserved twin of {@link carryRetiredSlots}: the reservations of `current`
+ * that no patch in `patches` has filled yet.
+ *
+ * @param current - Manifest the slots come from
+ * @param patches - The rows the written manifest will hold
+ */
+export declare function carryReservedSlots(current: Pick<PatchesManifest, 'reserved'> | null | undefined, patches: readonly Pick<PatchMetadata, 'order'>[]): PatchReservedSlot[] | undefined;
+/**
+ * Builds a manifest from `patches` that keeps `current`'s unfilled retired
+ * and reserved slots. Each key is omitted entirely when no slot remains, so
+ * a queue that never retired or reserved anything writes the same JSON as
+ * before.
+ *
+ * @param current - Manifest the slots come from
+ * @param patches - The rows the written manifest will hold
+ */
+export declare function manifestWithRetiredSlots(current: Pick<PatchesManifest, 'retired' | 'reserved'> | null | undefined, patches: PatchMetadata[]): PatchesManifest;
+/** The set of order numbers held by retired slots. */
+export declare function retiredOrderSet(manifest: Pick<PatchesManifest, 'retired'>): Set<number>;
+/** The set of order numbers held by reserved slots. */
+export declare function reservedOrderSet(manifest: Pick<PatchesManifest, 'reserved'>): Set<number>;
+/**
+ * The reservation at `order`, if any.
+ *
+ * @param manifest - Manifest to search (null: none)
+ * @param order - Order number
+ */
+export declare function reservationAt(manifest: Pick<PatchesManifest, 'reserved'> | null | undefined, order: number): PatchReservedSlot | undefined;

package/dist/src/core/patch-retired.js

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Retired order slots: the placeholders `patch retire` leaves in
+ * `patches.json#retired` so a patch can leave the queue without opening a
+ * numeric gap or renumbering its successors.
+ *
+ * A slot is not a patch. It has no `.patch` file and no row in `patches`,
+ * so everything that applies, exports, lints or rebases the queue walks past
+ * it without knowing it exists. The one reader is the
+ * `patchPolicy.allowGaps: false` gap check, which counts a retired order as
+ * occupied. A patch that later takes the same order fills the slot, and
+ * {@link carryRetiredSlots} drops it on that write, so the manifest never
+ * holds a slot and a patch at one order.
+ *
+ * Reserved slots (`patch reserve`) follow the same rules: a placeholder for
+ * an order a session has claimed but not exported yet, counted as occupied
+ * by the gap check and filled (and dropped) by the export that lands on it.
+ */
+/**
+ * The retired slots of `current` that no patch in `patches` occupies, or
+ * undefined when none remain. Every manifest write that rebuilds the
+ * `patches` list routes the slots through here, so a slot survives the
+ * rewrite and a filled one does not.
+ *
+ * @param current - Manifest the slots come from (null or slot-free: none)
+ * @param patches - The rows the written manifest will hold
+ */
+export function carryRetiredSlots(current, patches) {
+    const slots = current?.retired;
+    if (slots === undefined || slots.length === 0)
+        return undefined;
+    const occupied = new Set(patches.map((patch) => patch.order));
+    const kept = slots
+        .filter((slot) => !occupied.has(slot.order))
+        .map((slot) => ({ ...slot }))
+        .sort((a, b) => a.order - b.order);
+    return kept.length > 0 ? kept : undefined;
+}
+/**
+ * Reserved twin of {@link carryRetiredSlots}: the reservations of `current`
+ * that no patch in `patches` has filled yet.
+ *
+ * @param current - Manifest the slots come from
+ * @param patches - The rows the written manifest will hold
+ */
+export function carryReservedSlots(current, patches) {
+    const slots = current?.reserved;
+    if (slots === undefined || slots.length === 0)
+        return undefined;
+    const occupied = new Set(patches.map((patch) => patch.order));
+    const kept = slots
+        .filter((slot) => !occupied.has(slot.order))
+        .map((slot) => ({ ...slot }))
+        .sort((a, b) => a.order - b.order);
+    return kept.length > 0 ? kept : undefined;
+}
+/**
+ * Builds a manifest from `patches` that keeps `current`'s unfilled retired
+ * and reserved slots. Each key is omitted entirely when no slot remains, so
+ * a queue that never retired or reserved anything writes the same JSON as
+ * before.
+ *
+ * @param current - Manifest the slots come from
+ * @param patches - The rows the written manifest will hold
+ */
+export function manifestWithRetiredSlots(current, patches) {
+    const retired = carryRetiredSlots(current, patches);
+    const reserved = carryReservedSlots(current, patches);
+    return {
+        version: 1,
+        patches,
+        ...(retired !== undefined ? { retired } : {}),
+        ...(reserved !== undefined ? { reserved } : {}),
+    };
+}
+/** The set of order numbers held by retired slots. */
+export function retiredOrderSet(manifest) {
+    return new Set((manifest.retired ?? []).map((slot) => slot.order));
+}
+/** The set of order numbers held by reserved slots. */
+export function reservedOrderSet(manifest) {
+    return new Set((manifest.reserved ?? []).map((slot) => slot.order));
+}
+/**
+ * The reservation at `order`, if any.
+ *
+ * @param manifest - Manifest to search (null: none)
+ * @param order - Order number
+ */
+export function reservationAt(manifest, order) {
+    return manifest?.reserved?.find((slot) => slot.order === order);
+}

package/dist/src/core/patch-subset.d.ts

@@ -0,0 +1,16 @@
+import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+/**
+ * Resolves a `--patches <name…>` subset against the manifest, matching each
+ * requested name tolerantly (exact filename, filename ± `.patch`, the bare
+ * order number, the manifest `name` field, or the slug). Accepts repeated
+ * values and comma lists. Throws listing the available patches when a
+ * requested name matches none, so a typo fails loud rather than silently
+ * judging nothing.
+ *
+ * @param manifest - The loaded patch manifest
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ * @param refusalHint - Sentence inserted into the no-match refusal, naming
+ *   what the caller's flag selects
+ * @returns The matching manifest rows, de-duplicated, in request order
+ */
+export declare function selectPatchSubset(manifest: PatchesManifest, requested: readonly string[], refusalHint?: string): PatchMetadata[];

package/dist/src/core/patch-subset.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The `--patches <name…>` subset resolver shared by `lint --per-patch`,
+ * `status` and `verify`. One matcher, so a name that selects a patch in
+ * one gate selects the same patch in the others.
+ */
+import { GeneralError } from '../errors/base.js';
+/** Every spelling an operator may use for one patch. */
+function patchAliases(p) {
+    const aliases = new Set([p.filename, p.filename.replace(/\.patch$/, ''), p.name]);
+    // The bare order number, both as the manifest records it and as the
+    // filename spells it (`2` and `002`). The refusal message offers stems,
+    // and an operator reading `102-ui-canvas-tiles.patch` in a lint finding
+    // reaches for `102` first.
+    aliases.add(String(p.order));
+    const match = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(p.filename);
+    if (match?.[1])
+        aliases.add(match[1]);
+    if (match?.[2] && match[3]) {
+        aliases.add(`${match[2]}-${match[3]}`);
+        aliases.add(match[3]);
+    }
+    return aliases;
+}
+function matchesPatch(p, name) {
+    const aliases = patchAliases(p);
+    const stem = name.replace(/\.patch$/, '');
+    return aliases.has(name) || aliases.has(stem) || aliases.has(`${stem}.patch`);
+}
+/**
+ * Resolves a `--patches <name…>` subset against the manifest, matching each
+ * requested name tolerantly (exact filename, filename ± `.patch`, the bare
+ * order number, the manifest `name` field, or the slug). Accepts repeated
+ * values and comma lists. Throws listing the available patches when a
+ * requested name matches none, so a typo fails loud rather than silently
+ * judging nothing.
+ *
+ * @param manifest - The loaded patch manifest
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ * @param refusalHint - Sentence inserted into the no-match refusal, naming
+ *   what the caller's flag selects
+ * @returns The matching manifest rows, de-duplicated, in request order
+ */
+export function selectPatchSubset(manifest, requested, refusalHint = '') {
+    const normalizedRequests = requested
+        .flatMap((entry) => entry.split(','))
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    const selected = [];
+    const seen = new Set();
+    for (const name of normalizedRequests) {
+        const found = manifest.patches.filter((p) => matchesPatch(p, name));
+        if (found.length === 0) {
+            const available = manifest.patches.map((p) => p.filename).join(', ');
+            throw new GeneralError(`No patch in the queue matches "${name}".${refusalHint ? ` ${refusalHint}` : ''} ` +
+                `Available patches: ${available}`);
+        }
+        for (const p of found) {
+            if (!seen.has(p.filename)) {
+                seen.add(p.filename);
+                selected.push(p);
+            }
+        }
+    }
+    return selected;
+}

package/dist/src/core/preflight-wait.d.ts

@@ -1,2 +1,22 @@
 /** Waits for a busy browser or port without changing or terminating its owner. */
 export declare function waitForPreflight(action: () => Promise<void>, seconds?: number): Promise<void>;
+/**
+ * Spends a `--wait-browser`/`--wait-port` budget BEFORE the engine session
+ * lock is taken, so a run queued behind a busy browser or port does not
+ * hold the lock (and every peer's build, test and re-export behind it)
+ * while it does nothing. The caller re-checks once under the lock.
+ *
+ * Never refuses on its own: when the budget runs out the run still joins
+ * the lock queue, and the single check under the lock decides. A peer's
+ * test run that holds the lock legitimately keeps its browser alive until
+ * it releases, and refusing here would turn that ordinary queue into a
+ * refusal the old in-lock wait never produced. Never terminates anything
+ * either: nothing is owned before the lock is won. A refusal whose note is
+ * in `clearNotes` (a stale browser the run is allowed to reap under the
+ * lock) counts as clear.
+ *
+ * @param action - The preflight probe, which throws `PreflightRefusalError` while busy
+ * @param seconds - The wait budget
+ * @param clearNotes - Refusal classes that do not need waiting out
+ */
+export declare function waitBeforeLock(action: () => Promise<void>, seconds: number | undefined, clearNotes?: readonly string[]): Promise<void>;

package/dist/src/core/preflight-wait.js

@@ -22,3 +22,41 @@ export async function waitForPreflight(action, seconds) {
         }
     }
 }
+/**
+ * Spends a `--wait-browser`/`--wait-port` budget BEFORE the engine session
+ * lock is taken, so a run queued behind a busy browser or port does not
+ * hold the lock (and every peer's build, test and re-export behind it)
+ * while it does nothing. The caller re-checks once under the lock.
+ *
+ * Never refuses on its own: when the budget runs out the run still joins
+ * the lock queue, and the single check under the lock decides. A peer's
+ * test run that holds the lock legitimately keeps its browser alive until
+ * it releases, and refusing here would turn that ordinary queue into a
+ * refusal the old in-lock wait never produced. Never terminates anything
+ * either: nothing is owned before the lock is won. A refusal whose note is
+ * in `clearNotes` (a stale browser the run is allowed to reap under the
+ * lock) counts as clear.
+ *
+ * @param action - The preflight probe, which throws `PreflightRefusalError` while busy
+ * @param seconds - The wait budget
+ * @param clearNotes - Refusal classes that do not need waiting out
+ */
+export async function waitBeforeLock(action, seconds, clearNotes = []) {
+    try {
+        await waitForPreflight(async () => {
+            try {
+                await action();
+            }
+            catch (error) {
+                if (error instanceof PreflightRefusalError && clearNotes.includes(error.note))
+                    return;
+                throw error;
+            }
+        }, seconds);
+    }
+    catch (error) {
+        if (!(error instanceof PreflightRefusalError))
+            throw error;
+        info(`Still busy after the ${seconds ?? 0}-second wait; joining the lock queue and re-checking once under the lock.`);
+    }
+}

package/dist/src/core/rebase-from-version.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Resolves the "from" side of a `fireforge rebase` source move.
+ *
+ * The rebase target is the working `firefox.version` pin, which
+ * `fireforge source set` has already moved. The tree the queue was last
+ * applied to is the previous pin: the `firefox` block of `fireforge.json`
+ * as committed in the project repository. Patch `sourceVersion` stamps are
+ * a poor stand-in: patches untouched since an older hop keep their older
+ * stamp, so the oldest stamp can trail the real previous tree by several
+ * releases. The stamps are only the fallback, for a project that is not a
+ * git checkout or whose committed pin already equals the target.
+ */
+import type { FirefoxProduct } from '../types/config.js';
+/** A `firefox.version` / `firefox.product` pair. */
+export interface FirefoxPin {
+    version: string;
+    product?: FirefoxProduct;
+}
+/** Where the rebase's "from" label came from. */
+export interface RebaseFromVersion extends FirefoxPin {
+    /** `committed-pin`: the project's committed `fireforge.json`; `patch-stamps`: the oldest stamp. */
+    origin: 'committed-pin' | 'patch-stamps';
+}
+/** Tally of the queue's `sourceVersion` stamps, oldest first. */
+export interface PatchStampSpread {
+    versions: string[];
+    counts: Map<string, number>;
+}
+/**
+ * Reads the `firefox` pin from `fireforge.json` as committed at the project
+ * repository's HEAD. `HEAD:./fireforge.json` resolves relative to the
+ * project root, so a project nested inside a larger repository works too.
+ * Returns `undefined` when there is no repository, no commit, no committed
+ * config, or no valid pin in it.
+ */
+export declare function readCommittedFirefoxPin(projectRoot: string): Promise<FirefoxPin | undefined>;
+/** Counts the queue's stamps and orders them semantically (a lexical sort put 153.10.0esr before 153.2.0esr). */
+export declare function tallyPatchStamps(stamps: readonly string[]): PatchStampSpread;
+/** `"317 at 153.0esr, 5 at 153.3.0esr"`. */
+export declare function formatPatchStampSpread(spread: PatchStampSpread): string;
+/**
+ * Picks the rebase's "from": the committed pin when it differs from the
+ * target, otherwise the oldest patch stamp (`oldestStampProduct` is that
+ * stamp's recorded product, when any patch carries one).
+ */
+export declare function resolveRebaseFromVersion(target: string, committed: FirefoxPin | undefined, spread: PatchStampSpread, oldestStampProduct: FirefoxProduct | undefined): RebaseFromVersion;

package/dist/src/core/rebase-from-version.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Resolves the "from" side of a `fireforge rebase` source move.
+ *
+ * The rebase target is the working `firefox.version` pin, which
+ * `fireforge source set` has already moved. The tree the queue was last
+ * applied to is the previous pin: the `firefox` block of `fireforge.json`
+ * as committed in the project repository. Patch `sourceVersion` stamps are
+ * a poor stand-in: patches untouched since an older hop keep their older
+ * stamp, so the oldest stamp can trail the real previous tree by several
+ * releases. The stamps are only the fallback, for a project that is not a
+ * git checkout or whose committed pin already equals the target.
+ */
+import { exec } from '../utils/process.js';
+import { compareFirefoxVersions, isObject, isValidFirefoxProduct, isValidFirefoxVersion, } from '../utils/validation.js';
+/**
+ * Reads the `firefox` pin from `fireforge.json` as committed at the project
+ * repository's HEAD. `HEAD:./fireforge.json` resolves relative to the
+ * project root, so a project nested inside a larger repository works too.
+ * Returns `undefined` when there is no repository, no commit, no committed
+ * config, or no valid pin in it.
+ */
+export async function readCommittedFirefoxPin(projectRoot) {
+    const result = await exec('git', ['show', 'HEAD:./fireforge.json'], { cwd: projectRoot }).catch(() => undefined);
+    if (result?.exitCode !== 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return undefined;
+    }
+    const firefox = isObject(parsed) ? parsed['firefox'] : undefined;
+    if (!isObject(firefox))
+        return undefined;
+    const version = firefox['version'];
+    if (typeof version !== 'string' || !isValidFirefoxVersion(version))
+        return undefined;
+    const product = firefox['product'];
+    return typeof product === 'string' && isValidFirefoxProduct(product)
+        ? { version, product }
+        : { version };
+}
+/** Counts the queue's stamps and orders them semantically (a lexical sort put 153.10.0esr before 153.2.0esr). */
+export function tallyPatchStamps(stamps) {
+    const counts = new Map();
+    for (const stamp of stamps)
+        counts.set(stamp, (counts.get(stamp) ?? 0) + 1);
+    return { versions: [...counts.keys()].sort(compareFirefoxVersions), counts };
+}
+/** `"317 at 153.0esr, 5 at 153.3.0esr"`. */
+export function formatPatchStampSpread(spread) {
+    return spread.versions.map((v) => `${spread.counts.get(v)} at ${v}`).join(', ');
+}
+/**
+ * Picks the rebase's "from": the committed pin when it differs from the
+ * target, otherwise the oldest patch stamp (`oldestStampProduct` is that
+ * stamp's recorded product, when any patch carries one).
+ */
+export function resolveRebaseFromVersion(target, committed, spread, oldestStampProduct) {
+    if (committed !== undefined && committed.version !== target) {
+        return { ...committed, origin: 'committed-pin' };
+    }
+    const oldest = spread.versions[0] ?? target;
+    return {
+        version: oldest,
+        ...(oldestStampProduct !== undefined ? { product: oldestStampProduct } : {}),
+        origin: 'patch-stamps',
+    };
+}

package/dist/src/core/run-log.d.ts

@@ -43,8 +43,34 @@ export declare function getRunLogDir(projectRoot: string): string;
  * @returns The sink, or undefined when no log could be opened
  */
 export declare function openRunLog(projectRoot: string, command: string, now?: Date): Promise<RunLog | undefined>;
+/**
+ * Tees a run log into a caller-chosen copy (`--keep-log`,
+ * {@link LOG_KEEP_ENV_VAR}) that retention never prunes.
+ *
+ * `.fireforge/logs/` keeps twenty logs per command kind for EVERY session
+ * on the checkout, so on a shared checkout a log named by a verdict line
+ * can be gone within the hour, and a failure recorded only by its log path
+ * cannot be read later. The copy is written live, line for line with the
+ * same redaction, rather than copied at the end: a killed run keeps what it
+ * had written, like the primary log does.
+ *
+ * The primary path stays the one `log=` names. When the primary could not
+ * be opened the copy stands in for it.
+ *
+ * @param log - The primary run log, if one opened
+ * @param flag - The `--keep-log` value, if any
+ * @param command - Command kind, naming a copy that has no primary
+ * @returns A sink writing to both, or whichever one opened
+ */
+export declare function keepRunLogCopy(log: RunLog | undefined, flag: string | undefined, command: string): Promise<RunLog | undefined>;
 /** Installs (or clears, with `undefined`) the run log for this process. */
 export declare function setActiveRunLog(log: RunLog | undefined): void;
+/**
+ * The 1-based line of the active run log the next write starts on.
+ * Redaction rewrites within a line and never adds or drops one, so the
+ * number holds for the file on disk.
+ */
+export declare function activeRunLogLine(): number;
 /** Absolute path of the active run log, or undefined when none is open. */
 export declare function getActiveRunLogPath(): string | undefined;
 /** Appends to the active run log. A no-op when none is open. */