@hominis/fireforge 0.21.2 → 0.21.4

package/CHANGELOG.md

@@ -11,6 +11,8 @@
 ### Hardening
 
 - **Eval 0.21.0 release-gate fixes.** `export --dry-run` now performs the same supersede and cross-patch ownership checks as real export before calling a plan safe; `furnace deploy --dry-run` validates successful custom-component plans against projected jar.mn registrations; generated Furnace components and browser-chrome test scaffolds are strict-checkJs and lazy-custom-element ready; chrome-doc packaging xpcshell tests no longer trip component-orphan validation; supported optional config keys such as `firefox.sha256` print `(not set)` when absent; and Furnace manifest writes preserve existing top-level/component ordering while appending new entries predictably.
+- **Sparse export insertion before reserved ranges.** `fireforge export --order <N>` now creates the new patch at that exact unused order without renumbering later patches, so policy-owned queues can add `241-ui-new-feature.patch` while preserving exact reserved exceptions such as `900-infra-bindgen-basic-string-workaround.patch`. Positional `--before` / `--after` insertion still renumbers, but now refuses with a sparse `--order` suggestion when it would move a reserved patch.
+- **V1 readiness audit follow-ups.** `fireforge token coverage` now validates dirty/untracked Furnace token CSS as a token source file instead of ignoring it or counting its expected literal values as raw-color coverage debt. `furnace create --compose <tag>` auto-registers discovered engine widgets into `furnace.json#stock` in the same transaction as the new custom component, so a prior non-interactive `furnace scan` report is enough for compose authoring. `fireforge lint --max-warnings <n>` lets release gates enforce a warning budget (for example `fireforge lint --per-patch --max-warnings 0`) while keeping warnings advisory by default. README guidance now covers first-module `browser/modules/<binaryName>/moz.build` setup, direct `fireforge` binary equivalents for shells without `npx`, Watchman PATH expectations, and the intentionally narrow `patch tier --tier branding` surface.
 - **Override removal demotes back to stock.** Removing a Furnace override restores engine files, deletes the override workspace, clears override checksums, and re-adds the component to `stock` tracking instead of dropping it from `furnace.json`. Optional Furnace config fields, including `platformPrefixes`, are preserved across the write.
 - **Rename updates browser-chrome test bodies.** `furnace rename` now rewrites generated browser-chrome mochitest contents as well as filenames and `browser.toml`, preventing stale `waitForElement("<old>")` references after a component rename.
 - **UI build preflight is stricter.** `fireforge build --ui` now refuses before `mach build faster` when the current objdir lacks a completed launchable bundle, guiding fresh imports and partial builds through a full `fireforge build` first.
@@ -64,7 +66,7 @@
 
 ### Documentation
 
-- **README — mochitest timeouts vs Marionette.** The Test harness section documents long idle timeouts (~370s, `TEST_END: TIMEOUT`) on fork custom chrome, `--marionette-port` behaviour with xpcshell flavor, and pointers to fork-side prefs and investigation (for example Hominis `AGENT_RULES.md`).
+- **README — mochitest timeouts vs Marionette.** The Test harness section documents long idle timeouts (~370s, `TEST_END: TIMEOUT`) on fork custom chrome, `--marionette-port` behaviour with xpcshell flavor, and pointers to fork-side prefs and investigation.
 - **README — default test harness and macOS mochitest-chrome.** The README sections “Picking a test harness for `furnace create`”, “Test harness options”, and “Known upstream build issues” describe the browser-chrome default, macOS single-process idle timeout, explicit `--test-style=mochikit`, and `--with-tests` + `--xpcshell` resolution.
 
 ## 0.18.0

package/README.md

@@ -36,7 +36,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 - **Python 3** (required by Firefox's `mach` build system).
 - **Git**
 - Platform build tools: Xcode on macOS, `build-essential` on Linux, Visual Studio Build Tools on Windows.
-- **Watchman** (optional, only required by `fireforge watch`). Install via `brew install watchman` (macOS), `dnf install watchman` (Fedora), or follow the upstream [Meta docs](https://facebook.github.io/watchman/). `fireforge doctor` surfaces a warning row when it is not on `PATH` so the dependency is visible during the usual onboarding sweep rather than at the watch-mode failure site. `fireforge watch` resolves watchman's absolute path via `which` / `where` and prepends its directory to the subprocess `PATH` it hands mach, so a homebrew-installed watchman at `/opt/homebrew/bin/watchman` (absent from the Node subprocess's default `PATH` on macOS) is still visible to `mach watch` without the operator having to re-export `PATH` manually. If `mach watch` reports `Operation not permitted` / `EPERM` on macOS, FireForge points at the usual privacy fix: grant Full Disk Access or Files and Folders access to the terminal/Codex app and watchman, then restart watchman with `watchman shutdown-server`.
+- **Watchman** (optional, only required by `fireforge watch`). Install via `brew install watchman` (macOS), `dnf install watchman` (Fedora), or follow the upstream [Meta docs](https://facebook.github.io/watchman/). `fireforge doctor` surfaces a warning row when it is not on `PATH`; build, run, package, and test workflows still work without Watchman. `fireforge watch` resolves watchman's absolute path via `which` / `where` and prepends its directory to the subprocess `PATH` it hands mach, so a homebrew-installed watchman at `/opt/homebrew/bin/watchman` (absent from the Node subprocess's default `PATH` on macOS) is still visible to `mach watch` without the operator having to re-export `PATH` manually. If `watchman` is installed but `fireforge watch` still refuses, make sure the same shell or automation environment that launches FireForge has Watchman on `PATH`. If `mach watch` reports `Operation not permitted` / `EPERM` on macOS, FireForge points at the usual privacy fix: grant Full Disk Access or Files and Folders access to the terminal/Codex app and watchman, then restart watchman with `watchman shutdown-server`.
 
 ### Setup
 
@@ -53,6 +53,8 @@ npx fireforge build               # build the browser
 npx fireforge run                 # launch it
 ```
 
+If your shell does not provide `npm` / `npx`, run the installed binary directly instead: `fireforge setup`, `fireforge download`, and so on when `fireforge` is on `PATH`, or `./node_modules/.bin/fireforge setup` from a project-local install.
+
 Your project now has `fireforge.json`, an `engine/` directory with Firefox source and a `patches/` directory with an empty `patches.json` manifest ready for your first customisation.
 
 #### Known upstream build issues
@@ -68,21 +70,23 @@ Your project now has `fireforge.json`, an `engine/` directory with Firefox sourc
 
 ```bash
 npx fireforge export browser/base/content/browser.js --name "custom-toolbar" --category ui
+# Direct binary equivalent:
+fireforge export browser/base/content/browser.js --name "custom-toolbar" --category ui
 ```
 
 3. Your patch is now in `patches/`.
 4. Reset and import to verify everything applies cleanly:
 
 ```bash
-npx fireforge reset --yes
-npx fireforge import              # --dry-run to preview without applying
+npx fireforge reset --yes         # or: fireforge reset --yes
+npx fireforge import              # or: fireforge import --dry-run
 ```
 
 5. When Mozilla releases a new version, update fireforge.json, re-download and rebase:
 
 ```bash
-npx fireforge download --force
-npx fireforge rebase
+npx fireforge download --force    # or: fireforge download --force
+npx fireforge rebase              # or: fireforge rebase
 ```
 
 `fireforge download` indexes the extracted Firefox source into a fresh git repository — a one-time 1–3 minute pass on a cold SSD, longer on slow or loaded disks. The monolithic `git add -A` is capped at 10 minutes by default and falls back to a per-directory chunked pass (30 minutes per chunk) when the cap hits. If indexing still times out, the command now raises `GitIndexingTimeoutError` with recovery guidance: extend the cap via `FIREFORGE_GIT_ADD_TIMEOUT_MS` (monolithic) and/or `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` (chunked) in milliseconds, e.g. `FIREFORGE_GIT_ADD_TIMEOUT_MS=1800000 fireforge download --force` for a 30-minute monolithic budget, then re-run `fireforge download --force` — the resume path picks up from the partial git state so the repeat is not wasted work.
@@ -146,6 +150,11 @@ Policy ranges are category-owned: a `ui` patch in the example must use `200-299`
 allowlist. `filenamePattern` must expose named captures `order`, `category`, and `slug`.
 `mutationMode` controls mutating commands: `"error"` refuses, `"warn"` prints warnings and
 continues, and `"force"` refuses unless the command supports and receives `--force-unsafe`.
+When a policy-owned queue has sparse category ranges before reserved exceptions, use
+`fireforge export <paths> --order 241 --category ui --name new-ui-feature` to create the exact
+unused order without renumbering later patches. Positional insertion with `--before` / `--after`
+still renumbers following patches, and policy enforcement refuses the operation if that would move a
+reserved exact exception such as `900-infra-bootstrap-workaround.patch`.
 Without `patchPolicy`, existing repositories keep the broad category and numeric ordering behavior.
 
 ### Importing patches
@@ -191,8 +200,10 @@ fireforge export browser/base/content/browser.js --dry-run
 # Same preview surface for the aggregate path
 fireforge export-all --name "all-changes" --category ui --dry-run
 
-# Insert a new patch at a specific position
-fireforge export browser/base/content/browser.js --order 3 --name "inserted" --category ui
+# Create a sparse patch at an exact unused order without renumbering later patches
+fireforge export browser/base/content/browser.js --order 241 --name "new-ui-feature" --category ui
+
+# Insert a new patch at a positional anchor, renumbering later patches
 fireforge export browser/base/content/browser.js --before 005-ui-sidebar.patch --name "prelim"
 
 # Restrict a re-export to a specific file subset
@@ -273,7 +284,7 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 `fireforge lint` runs automatically during export, export-all and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
 
-By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed — with tool-managed branding paths (`browser/branding/<binaryName>/`) excluded. A fresh-setup workspace carries a large generated branding diff that operators did not author directly, and letting it through tripped the patch-size and license-header rules on content that matches the `branding` bucket in `fireforge status`. When the exclusion fires the command prints a one-line note naming the excluded count so the filter is visible. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further — explicit-path mode does lint branding files (the operator's explicit request wins over the branding exclusion); the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
+By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed — with tool-managed branding paths (`browser/branding/<binaryName>/`) excluded. A fresh-setup workspace carries a large generated branding diff that operators did not author directly, and letting it through tripped the patch-size and license-header rules on content that matches the `branding` bucket in `fireforge status`. When the exclusion fires the command prints a one-line note naming the excluded count so the filter is visible. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further — explicit-path mode does lint branding files (the operator's explicit request wins over the branding exclusion); the three modes (aggregate, file-scoped, per-patch) are mutually exclusive. Warnings stay advisory by default; release gates that require a warning-clean queue should use `fireforge lint --per-patch --max-warnings 0`.
 
 | Check                                | Scope                                                                                                   | Severity                 |
 | ------------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------ |
@@ -365,6 +376,16 @@ fireforge register engine/browser/modules/mybrowser/MyStore.sys.mjs
 # Both support --dry-run to preview changes
 ```
 
+For the first module in a new `browser/modules/<binaryName>/` namespace, create `engine/browser/modules/<binaryName>/moz.build` before running `fireforge register`. The minimal manifest is:
+
+```python
+# SPDX-License-Identifier: MPL-2.0
+
+EXTRA_JS_MODULES += []
+```
+
+Also make sure `browser/modules/moz.build` references the namespace directory with `DIRS += ["<binaryName>"]`; `register` adds the module entry inside the namespace manifest, not the parent `DIRS` entry.
+
 <details>
 <summary>Wire options</summary>
 
@@ -412,6 +433,8 @@ fireforge furnace status                           # workspace vs engine drift
 fireforge furnace diff moz-button                  # unified diff against baseline
 ```
 
+`furnace scan` is read-only in non-interactive shells and reports which discovered widgets are already tracked. In interactive shells it can add selected discoveries to `furnace.json#stock`. `furnace create --compose <tag>` also consults the scan inventory: if `<tag>` is a discovered engine widget that is not yet in `stock`, create auto-adds it to `stock` in the same `furnace.json` write as the new custom component. Unknown compose targets still fail.
+
 `furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically — when apply wrote files during a build, the build prints a `Furnace: source → engine sync wrote N component(s) …` banner naming every component that was synced, so it is obvious whether engine/ was freshly updated. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
 
 ### Scaffolding top-level chrome documents
@@ -560,7 +583,7 @@ fireforge token add --category 'Colors — General' --mode static -- --my-color
 fireforge token add --category 'Colors — General' --mode static my-color   '#fff'   # bare-name form
 ```
 
-Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` does three more things in the same step so the file is owned end-to-end by tooling: it registers the tokens CSS path in `patchLint.rawColorAllowlist` (so raw color literals inside it are not flagged by `fireforge lint`); it adds the matching `skin/classic/browser/<binaryName>-tokens.css (../shared/<binaryName>-tokens.css)` entry to `browser/themes/shared/jar.inc.mn` (so `fireforge status` does not flag the file as unmanaged or unregistered); and it derives `tokenPrefix: --<binaryName>-` from `fireforge.json`'s `binaryName` so `fireforge token coverage` has a prefix to key off on the very first run. Projects that prefer a different prefix can override it in `furnace.json` after init.
+Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` does three more things in the same step so the file is owned end-to-end by tooling: it registers the tokens CSS path in `patchLint.rawColorAllowlist` (so raw color literals inside it are not flagged by `fireforge lint`); it adds the matching `skin/classic/browser/<binaryName>-tokens.css (../shared/<binaryName>-tokens.css)` entry to `browser/themes/shared/jar.inc.mn` (so `fireforge status` does not flag the file as unmanaged or unregistered); and it derives `tokenPrefix: --<binaryName>-` from `fireforge.json`'s `binaryName` so `fireforge token coverage` has a prefix to key off on the very first run. Projects that prefer a different prefix can override it in `furnace.json` after init. When only the tokens CSS file is dirty or untracked, `fireforge token coverage` validates it as a token source file and does not count its expected literal token values as raw-color coverage failures.
 
 ### Diff-scoped lint (`lint --since`)
 

package/dist/src/commands/download.js

@@ -269,7 +269,7 @@ export async function downloadCommand(projectRoot, options) {
         // CI job notes the expected duration. The progress callbacks below
         // still fire as usual; this is an additional up-front signal, not a
         // replacement.
-        info('Indexing downloaded source into git (one-time; typically 1–3 minutes on a ~600 MB Firefox tree)...');
+        info('Indexing downloaded source into git (one-time; typically 3–5 minutes on a ~600 MB Firefox tree)...');
         // Initialize git repository
         const gitSpinner = spinner('Initializing git repository (this may take a few minutes)...');
         let baseCommit;

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

@@ -24,6 +24,13 @@ export interface PlacementPlan {
  * slot to make room for a new patch at `requestedOrder`.
  */
 export declare function computePlacementPlan(manifestPatches: PatchMetadata[], newPatchCategory: PatchCategory, newPatchName: string, requestedOrder: number): PlacementPlan;
+/**
+ * Computes an exact sparse placement plan for `--order <N>`. Unlike
+ * positional insertion, this never renumbers existing patches: the order
+ * must be unused, and policy validation decides whether the requested
+ * category/order is allowed.
+ */
+export declare function computeExactPlacementPlan(manifestPatches: PatchMetadata[], newPatchCategory: PatchCategory, newPatchName: string, requestedOrder: number): PlacementPlan;
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
  */

package/dist/src/commands/export-flow.js

@@ -18,11 +18,18 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
+import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
 import { findPartialOwnershipOverlap } from './export-shared.js';
 function buildFilenameForPlacement(category, name, order, width) {
     const padded = String(order).padStart(Math.max(3, width), '0');
     return `${padded}-${category}-${sanitizeName(name)}.patch`;
 }
+function prefixWidthForPatches(manifestPatches, requestedOrder) {
+    return manifestPatches.reduce((width, patch) => {
+        const match = /^(\d+)-/.exec(patch.filename);
+        return Math.max(width, match?.[1]?.length ?? 3, String(requestedOrder).length);
+    }, 3);
+}
 function getSortedRenameEntries(renameMap) {
     return Array.from(renameMap.entries()).sort((a, b) => a[1].newOrder - b[1].newOrder);
 }
@@ -59,12 +66,7 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
     }
     const sorted = [...manifestPatches].sort((a, b) => a.order - b.order);
     const renameMap = new Map();
-    // Decide the canonical prefix width by inspecting the widest existing
-    // filename (falling back to 3). Keeps zero-padding consistent post-shift.
-    const prefixWidth = sorted.reduce((w, p) => {
-        const match = /^(\d+)-/.exec(p.filename);
-        return match ? Math.max(w, match[1]?.length ?? 3) : w;
-    }, 3);
+    const prefixWidth = prefixWidthForPatches(sorted, requestedOrder);
     // Every existing patch at requestedOrder or later shifts up by one.
     for (const patch of sorted) {
         if (patch.order >= requestedOrder) {
@@ -81,6 +83,27 @@ export function computePlacementPlan(manifestPatches, newPatchCategory, newPatch
         renameMap,
     };
 }
+/**
+ * Computes an exact sparse placement plan for `--order <N>`. Unlike
+ * positional insertion, this never renumbers existing patches: the order
+ * must be unused, and policy validation decides whether the requested
+ * category/order is allowed.
+ */
+export function computeExactPlacementPlan(manifestPatches, newPatchCategory, newPatchName, requestedOrder) {
+    if (!Number.isInteger(requestedOrder) || requestedOrder <= 0) {
+        throw new InvalidArgumentError(`--order must be a positive integer, got ${String(requestedOrder)}.`, '--order');
+    }
+    const occupied = manifestPatches.find((patch) => patch.order === requestedOrder);
+    if (occupied) {
+        throw new InvalidArgumentError(`--order ${String(requestedOrder)} is already occupied by ${occupied.filename}. ` +
+            'Choose an unused order or use --before/--after for positional insertion.', '--order');
+    }
+    return {
+        insertionOrder: requestedOrder,
+        newFilename: buildFilenameForPlacement(newPatchCategory, newPatchName, requestedOrder, prefixWidthForPatches(manifestPatches, requestedOrder)),
+        renameMap: new Map(),
+    };
+}
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
  */
@@ -95,7 +118,7 @@ export async function resolvePlacementPlan(patchesDir, options, category, name)
         if (!Number.isInteger(options.order) || options.order <= 0) {
             throw new InvalidArgumentError(`--order must be a positive integer, got ${String(options.order)}.`, '--order');
         }
-        targetOrder = options.order;
+        return computeExactPlacementPlan(existingPatches, category, name, options.order);
     }
     else if (options.before !== undefined) {
         const anchor = resolvePatchIdentifier(options.before, existingPatches);
@@ -202,6 +225,9 @@ export async function commitPlacementExport(input) {
             throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. Pass --force-unsafe to override.`, '--force-unsafe');
         }
         const originalManifest = await loadPatchesManifest(input.patchesDir);
+        if (originalManifest !== null) {
+            assertPlacementPreservesReservedRanges(currentPlan, originalManifest.patches, input.config, input.category);
+        }
         if (input.config !== undefined) {
             const renamed = originalManifest !== null
                 ? applyRenameMapToManifest(originalManifest, currentPlan.renameMap)

package/dist/src/commands/export-placement-policy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Policy-aware checks for export placement plans.
+ */
+import type { PatchCategory, PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+export interface PlacementPolicyPlan {
+    insertionOrder: number;
+    renameMap: ReadonlyMap<string, {
+        newFilename: string;
+        newOrder: number;
+    }>;
+}
+/** Refuses positional export plans that would renumber exact reserved patches. */
+export declare function assertPlacementPreservesReservedRanges(plan: PlacementPolicyPlan, manifestPatches: readonly PatchMetadata[], config: FireForgeConfig | undefined, category: PatchCategory): void;

package/dist/src/commands/export-placement-policy.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Policy-aware checks for export placement plans.
+ */
+import { InvalidArgumentError } from '../errors/base.js';
+function reservedRangeLabel(range) {
+    return `${String(range.from).padStart(3, '0')}-${String(range.to).padStart(3, '0')}`;
+}
+function findReservedRange(config, order) {
+    return (config.patchPolicy?.reservedRanges?.find((range) => order >= range.from && order <= range.to) ??
+        null);
+}
+function suggestSparseOrder(config, patches, category, insertionOrder) {
+    const ranges = (config.patchPolicy?.ranges ?? [])
+        .filter((range) => range.category === category)
+        .sort((a, b) => a.from - b.from || a.to - b.to);
+    const occupied = new Set(patches.map((patch) => patch.order));
+    for (const range of ranges) {
+        for (let order = Math.max(insertionOrder, range.from); order <= range.to; order++) {
+            if (!occupied.has(order) && findReservedRange(config, order) === null)
+                return order;
+        }
+    }
+    for (const range of ranges) {
+        for (let order = range.from; order <= range.to; order++) {
+            if (!occupied.has(order) && findReservedRange(config, order) === null)
+                return order;
+        }
+    }
+    return null;
+}
+/** Refuses positional export plans that would renumber exact reserved patches. */
+export function assertPlacementPreservesReservedRanges(plan, manifestPatches, config, category) {
+    if (config?.patchPolicy === undefined || plan.renameMap.size === 0)
+        return;
+    const byFilename = new Map(manifestPatches.map((patch) => [patch.filename, patch]));
+    for (const [filename, rename] of plan.renameMap) {
+        const patch = byFilename.get(filename);
+        if (!patch)
+            continue;
+        const reserved = findReservedRange(config, patch.order);
+        if (reserved === null)
+            continue;
+        const suggestion = suggestSparseOrder(config, manifestPatches, category, plan.insertionOrder);
+        const suggestionText = suggestion !== null
+            ? ` Use --order ${String(suggestion).padStart(3, '0')} to create the new patch in an unused ${category} slot without renumbering reserved patches.`
+            : ` Choose an unused order in the ${category} policy range or adjust patchPolicy.`;
+        throw new InvalidArgumentError(`Positional export would renumber reserved patch ${patch.filename} ` +
+            `from ${String(patch.order).padStart(3, '0')} to ${rename.newFilename} ` +
+            `(reserved range ${reservedRangeLabel(reserved)}).` +
+            suggestionText, 'export placement');
+    }
+}
+//# sourceMappingURL=export-placement-policy.js.map

package/dist/src/commands/export.js

@@ -21,6 +21,7 @@ import { pickDefined } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag } from '../utils/validation.js';
 import { commitPlacementExport, placementSummary, projectPlacementForLint, renderDryRunPreview, resolvePlacementPlan, } from './export-flow.js';
+import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
 import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
 async function collectExportFiles(paths, files) {
     const collectedFiles = new Set();
@@ -191,8 +192,11 @@ export async function exportCommand(projectRoot, files, options) {
                 throw new InvalidArgumentError('Placement flags (--order/--before/--after) cannot be combined with --supersede.', 'export placement');
             }
             placementPlan = await resolvePlacementPlan(paths.patches, options, selectedCategory, patchName);
-            const conflicts = await projectPlacementForLint(paths.patches, placementPlan, diff);
             const currentManifest = await loadPatchesManifest(paths.patches);
+            if (currentManifest !== null) {
+                assertPlacementPreservesReservedRanges(placementPlan, currentManifest.patches, config, selectedCategory);
+            }
+            const conflicts = await projectPlacementForLint(paths.patches, placementPlan, diff);
             const renamed = currentManifest !== null
                 ? applyRenameMapToManifest(currentManifest, placementPlan.renameMap)
                 : buildProjectedManifest(null, []);
@@ -397,7 +401,7 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('--supersede', 'Allow superseding multiple existing patches')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--dry-run', 'Print the export plan (including supersede preview) without writing')
-        .addOption(new Option('--order <N>', 'Place the new patch at this ordinal, shifting subsequent patches up').argParser((v) => parsePositiveIntegerFlag('--order', v)))
+        .addOption(new Option('--order <N>', 'Place the new patch at this exact unused order without renumbering existing patches').argParser((v) => parsePositiveIntegerFlag('--order', v)))
         .option('--before <anchor>', 'Place the new patch immediately before <anchor>')
         .option('--after <anchor>', 'Place the new patch immediately after <anchor>')
         .option('-y, --yes', 'Skip confirmation for placement renumbers (required for non-TTY)')

package/dist/src/commands/furnace/create-dry-run.d.ts

@@ -4,6 +4,7 @@ export interface DryRunPlanInput {
     localized: boolean;
     register: boolean;
     composes: string[] | undefined;
+    stockAdditions?: string[];
     /**
      * Feature-scoped Fluent bundle the component participates in (the same
      * value that will be written to `furnace.json`'s `sharedFtl`). When set,

package/dist/src/commands/furnace/create-dry-run.js

@@ -75,7 +75,7 @@ export function formatSuccessNote(args) {
  * `components/custom/` to match the wording of the real success note.
  */
 export function formatDryRunPlan(args) {
-    const { componentName, localized, register, composes, sharedFtl, testStyle, description, binaryName, } = args;
+    const { componentName, localized, register, composes, stockAdditions, sharedFtl, testStyle, description, binaryName, } = args;
     const componentFiles = [`${componentName}.mjs`, `${componentName}.css`];
     // A per-component .ftl is scaffolded only when the component does NOT
     // opt into a shared feature-scoped bundle. Mirrors writeComponentFiles.
@@ -92,6 +92,12 @@ export function formatDryRunPlan(args) {
     if (composes && composes.length > 0) {
         plan += `\n  composes: ${composes.join(', ')}`;
     }
+    if (stockAdditions && stockAdditions.length > 0) {
+        plan += `\n\nWould add discovered stock to furnace.json:`;
+        for (const name of stockAdditions) {
+            plan += `\n  ${name}`;
+        }
+    }
     if (sharedFtl) {
         plan += `\n  sharedFtl: ${sharedFtl}`;
     }

package/dist/src/commands/furnace/create-validation.d.ts

@@ -3,4 +3,4 @@ import type { FurnaceConfig } from '../../types/furnace.js';
 /**
  * Validates a proposed custom component against the current furnace config.
  */
-export declare function validateCreateAgainstConfig(config: FurnaceConfig, componentName: string, allowPrefixMismatch: FurnaceCreateOptions['allowPrefixMismatch'], composes: string[] | undefined): void;
+export declare function validateCreateAgainstConfig(config: FurnaceConfig, componentName: string, allowPrefixMismatch: FurnaceCreateOptions['allowPrefixMismatch'], composes: string[] | undefined, stockAdditions?: string[]): void;

package/dist/src/commands/furnace/create-validation.js

@@ -11,11 +11,12 @@ function checkNameConflict(config, name) {
     }
     return undefined;
 }
-function validateComposesTargets(config, componentName, composes) {
+function validateComposesTargets(config, componentName, composes, stockAdditions = []) {
     if (!composes || composes.length === 0)
         return;
     const known = new Set([
         ...config.stock,
+        ...stockAdditions,
         ...Object.keys(config.overrides),
         ...Object.keys(config.custom),
     ]);
@@ -42,7 +43,7 @@ function validateComposesTargets(config, componentName, composes) {
 /**
  * Validates a proposed custom component against the current furnace config.
  */
-export function validateCreateAgainstConfig(config, componentName, allowPrefixMismatch, composes) {
+export function validateCreateAgainstConfig(config, componentName, allowPrefixMismatch, composes, stockAdditions = []) {
     const conflict = checkNameConflict(config, componentName);
     if (conflict) {
         throw new FurnaceError(conflict, componentName);
@@ -54,6 +55,6 @@ export function validateCreateAgainstConfig(config, componentName, allowPrefixMi
             `Use a prefixed name (e.g. "${config.componentPrefix}${componentName}"), update ` +
             '`componentPrefix` in furnace.json, or pass --allow-prefix-mismatch to create the component anyway.', 'name');
     }
-    validateComposesTargets(config, componentName, composes);
+    validateComposesTargets(config, componentName, composes, stockAdditions);
 }
 //# sourceMappingURL=create-validation.js.map

package/dist/src/commands/furnace/create.js

@@ -7,7 +7,7 @@ import { resolveFtlChromeSubPath, tagNameToClassName } from '../../core/furnace-
 import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
-import { isComponentInEngine } from '../../core/furnace-scanner.js';
+import { isComponentInEngine, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
 import { registerTestManifest } from '../../core/manifest-register.js';
 import { validateSharedFtl } from '../../core/shared-ftl.js';
@@ -29,6 +29,26 @@ async function loadAuthoringFurnaceConfig(projectRoot) {
     }
     return createDefaultFurnaceConfig();
 }
+function knownComponentSet(config) {
+    return new Set([
+        ...config.stock,
+        ...Object.keys(config.overrides),
+        ...Object.keys(config.custom),
+    ]);
+}
+async function resolveComposeStockAdditions(args) {
+    const { engineDir, config, componentName, composes } = args;
+    if (!composes || composes.length === 0)
+        return [];
+    const known = knownComponentSet(config);
+    const unresolved = composes.filter((tag) => tag !== componentName && !known.has(tag));
+    if (unresolved.length === 0 || !(await pathExists(engineDir)))
+        return [];
+    const scanPaths = config.scanPaths && config.scanPaths.length > 0 ? config.scanPaths : undefined;
+    const discovered = await scanWidgetsDirectory(engineDir, undefined, scanPaths);
+    const discoveredTags = new Set(discovered.map((component) => component.tagName));
+    return unresolved.filter((tag, index) => discoveredTags.has(tag) && unresolved.indexOf(tag) === index);
+}
 /**
  * Validates a custom element tag name.
  * @returns Error message if invalid, undefined if valid
@@ -238,7 +258,13 @@ async function performCreateMutations(args) {
     let files;
     try {
         const freshConfig = await loadAuthoringFurnaceConfig(args.projectRoot);
-        validateCreateAgainstConfig(freshConfig, args.componentName, args.allowPrefixMismatch, args.composes);
+        const freshStockAdditions = await resolveComposeStockAdditions({
+            engineDir: args.paths.engine,
+            config: freshConfig,
+            componentName: args.componentName,
+            composes: args.composes,
+        });
+        validateCreateAgainstConfig(freshConfig, args.componentName, args.allowPrefixMismatch, args.composes, freshStockAdditions);
         if (await pathExists(args.componentDir)) {
             throw new FurnaceError(`Directory already exists: components/custom/${args.componentName}`, args.componentName);
         }
@@ -259,6 +285,11 @@ async function performCreateMutations(args) {
         if (args.sharedFtl) {
             customEntry.sharedFtl = args.sharedFtl;
         }
+        for (const name of freshStockAdditions) {
+            if (!freshConfig.stock.includes(name)) {
+                freshConfig.stock.push(name);
+            }
+        }
         freshConfig.custom[args.componentName] = customEntry;
         await snapshotFile(journal, args.furnacePaths.furnaceConfig);
         await writeFurnaceConfig(args.projectRoot, freshConfig);
@@ -352,7 +383,13 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // furnace.json behind.
     const config = await loadAuthoringFurnaceConfig(projectRoot);
     const composes = options.compose;
-    validateCreateAgainstConfig(config, componentName, options.allowPrefixMismatch, composes);
+    const stockAdditions = await resolveComposeStockAdditions({
+        engineDir: paths.engine,
+        config,
+        componentName,
+        composes,
+    });
+    validateCreateAgainstConfig(config, componentName, options.allowPrefixMismatch, composes, stockAdditions);
     // Check if it already exists in the engine source tree
     if (await pathExists(paths.engine)) {
         if (await isComponentInEngine(paths.engine, componentName)) {
@@ -407,6 +444,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
             localized,
             register,
             composes,
+            stockAdditions,
             // Spread rather than assign so the key is absent when sharedFtl is
             // undefined — the DryRunPlanInput type uses strict-optional shape.
             ...(sharedFtl !== undefined ? { sharedFtl } : {}),

package/dist/src/commands/lint.d.ts

@@ -46,6 +46,12 @@ export interface LintCommandOptions {
      * scope contracts are different.
      */
     perPatch?: boolean;
+    /**
+     * Maximum warning count tolerated before lint exits non-zero. Mirrors
+     * ESLint's `--max-warnings` shape for release gates that want advisory
+     * findings to become blocking without changing default CLI behavior.
+     */
+    maxWarnings?: number;
 }
 /**
  * Result of {@link applyAggregateLintIgnoreSuppression}.

package/dist/src/commands/lint.js

@@ -224,6 +224,10 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (options.onlyIntroduced && !options.since) {
         throw new GeneralError('--only-introduced requires --since <git-rev> so introduced-vs-cumulative can be distinguished.');
     }
+    if (options.maxWarnings !== undefined &&
+        (!Number.isInteger(options.maxWarnings) || options.maxWarnings < 0)) {
+        throw new GeneralError('--max-warnings must be a non-negative integer.');
+    }
     // `--per-patch` rescopes the diff from "aggregate engine state" to "each
     // patch's own filesAffected". Mixing in explicit file paths would produce
     // an ambiguous set — is the file list an additional filter, or does it
@@ -240,7 +244,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
     if (options.perPatch) {
-        await lintPerPatch(projectRoot, paths);
+        await lintPerPatch(projectRoot, paths, options);
         return;
     }
     // Load the config before resolving the diff so we can pass
@@ -367,6 +371,10 @@ export async function lintCommand(projectRoot, files, options = {}) {
             : '';
         throw new GeneralError(`Patch lint found ${failingErrors.length} ${options.onlyIntroduced ? 'introduced ' : ''}error(s). Fix these before exporting.${cumulativeSuppressed}`);
     }
+    if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
+        outro('Lint failed');
+        throw new GeneralError(`Patch lint found ${warnings.length} warning(s), exceeding --max-warnings ${options.maxWarnings}.`);
+    }
     // Notices are advisory and don't count as warnings — emitting "passed
     // with warnings" when only notices fired contradicts the preceding
     // `0 warning(s)` summary line and reads as a regression. Distinguish
@@ -398,7 +406,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
  * Sharing a loop would hide the distinction and force the caller to
  * decide semantics mid-function.
  */
-async function lintPerPatch(projectRoot, paths) {
+async function lintPerPatch(projectRoot, paths, options = {}) {
     const manifest = await loadPatchesManifest(paths.patches);
     if (!manifest || manifest.patches.length === 0) {
         info('No patches in manifest — nothing to lint per-patch.');
@@ -483,6 +491,10 @@ async function lintPerPatch(projectRoot, paths) {
         outro('Lint failed');
         throw new GeneralError(`Patch lint found ${errors.length} error(s) across ${linted} patch(es). Fix these before exporting.`);
     }
+    if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
+        outro('Lint failed');
+        throw new GeneralError(`Patch lint found ${warnings.length} warning(s) across ${linted} patch(es), exceeding --max-warnings ${options.maxWarnings}.`);
+    }
     if (warnings.length > 0) {
         outro('Lint passed with warnings');
     }
@@ -503,6 +515,7 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .option('--since <git-rev>', 'Tag issues as [introduced] or [cumulative] based on whether the file changed since <git-rev> (e.g. HEAD, a branch, a SHA)')
         .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
         .option('--per-patch', "Lint each patch in the queue as its own isolated diff. Rescopes patch-size rules so they fire against individual patches rather than the aggregate. Honours each patch's `lintIgnore` entries.")
+        .option('--max-warnings <n>', 'Fail when lint reports more than <n> warning(s); use 0 for warning-clean release gates.')
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
@@ -514,6 +527,13 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.perPatch !== undefined) {
             lintOptions.perPatch = options.perPatch;
         }
+        if (options.maxWarnings !== undefined) {
+            const maxWarnings = Number(options.maxWarnings);
+            if (!Number.isInteger(maxWarnings) || maxWarnings < 0) {
+                throw new GeneralError('--max-warnings must be a non-negative integer.');
+            }
+            lintOptions.maxWarnings = maxWarnings;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
 }

package/dist/src/commands/token-coverage.js

@@ -7,7 +7,7 @@ import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/g
 import { measureTokenCoverage } from '../core/token-coverage.js';
 import { getTokensCssPath } from '../core/token-manager.js';
 import { GeneralError } from '../errors/base.js';
-import { pathExists } from '../utils/fs.js';
+import { pathExists, readText } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 /**
  * Measures design token coverage across modified CSS files.
@@ -31,6 +31,9 @@ export async function tokenCoverageCommand(projectRoot) {
     // and the file-extension filter could not see the .css inside.
     const rawStatus = await getWorkingTreeStatus(paths.engine);
     const expandedStatus = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
+    const statusTokenCssFiles = expandedStatus
+        .filter((f) => f.file === tokensCssPath)
+        .map((f) => f.file);
     const statusCssFiles = expandedStatus
         .filter((f) => f.file.endsWith('.css') && f.file !== tokensCssPath)
         .map((f) => f.file);
@@ -44,11 +47,27 @@ export async function tokenCoverageCommand(projectRoot) {
     // De-dupe so a file that is both a custom deploy target AND modified is
     // scanned exactly once.
     const cssFiles = [...new Set([...statusCssFiles, ...furnaceCssFiles])];
-    if (cssFiles.length === 0) {
+    const tokenSourceFiles = [...new Set(statusTokenCssFiles)];
+    if (cssFiles.length === 0 && tokenSourceFiles.length === 0) {
         info('No modified CSS files');
         outro('Nothing to measure');
         return;
     }
+    const tokenPrefix = await resolveTokenPrefix(projectRoot, config.binaryName);
+    const tokenSourceResults = await validateTokenSourceFiles(paths.engine, tokenSourceFiles, tokenPrefix);
+    for (const result of tokenSourceResults) {
+        const detail = `${result.tokenDeclarations} token declaration${result.tokenDeclarations === 1 ? '' : 's'}`;
+        if (result.unknownDeclarations.length === 0) {
+            success(`${result.file}  token source valid (${detail})`);
+        }
+        else {
+            warn(`${result.file}  token source has ${result.unknownDeclarations.length} declaration${result.unknownDeclarations.length === 1 ? '' : 's'} outside prefix ${tokenPrefix}: ${result.unknownDeclarations.join(', ')}`);
+        }
+    }
+    if (cssFiles.length === 0) {
+        outro(`${tokenSourceResults.length} token source file${tokenSourceResults.length === 1 ? '' : 's'} validated`);
+        return;
+    }
     const report = await measureTokenCoverage(paths.engine, cssFiles);
     // Per-file breakdown
     for (const entry of report.files) {
@@ -73,6 +92,46 @@ export async function tokenCoverageCommand(projectRoot) {
     }
     outro(`${report.filesScanned} CSS file${report.filesScanned === 1 ? '' : 's'} scanned`);
 }
+async function resolveTokenPrefix(projectRoot, binaryName) {
+    try {
+        const furnaceConfig = await loadFurnaceConfig(projectRoot);
+        if (furnaceConfig.tokenPrefix) {
+            return furnaceConfig.tokenPrefix;
+        }
+    }
+    catch {
+        // Fall through to the convention used by furnace init. A broken
+        // furnace.json is already surfaced by collectFurnaceCustomCssFiles.
+    }
+    return `--${binaryName}-`;
+}
+async function validateTokenSourceFiles(engineDir, tokenSourceFiles, tokenPrefix) {
+    const results = [];
+    for (const file of tokenSourceFiles) {
+        const filePath = join(engineDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const css = (await readText(filePath)).replace(/\/\*[\s\S]*?\*\//g, '');
+        const declarations = new Set();
+        const declarationPattern = /(^|[;{\s])(--[\w-]+)\s*:/g;
+        let match;
+        while ((match = declarationPattern.exec(css)) !== null) {
+            const declaration = match[2];
+            if (declaration)
+                declarations.add(declaration);
+        }
+        const tokenDeclarations = [...declarations].filter((name) => name.startsWith(tokenPrefix));
+        const unknownDeclarations = [...declarations]
+            .filter((name) => !name.startsWith(tokenPrefix))
+            .sort();
+        results.push({
+            file,
+            tokenDeclarations: tokenDeclarations.length,
+            unknownDeclarations,
+        });
+    }
+    return results;
+}
 /**
  * Returns engine-relative `.css` paths deployed by every Furnace custom
  * component registered in `furnace.json`. Only files that actually exist

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

@@ -11,7 +11,7 @@ import type { FireForgeConfig } from '../types/config.js';
 /** Default patch filename contract used when a policy omits `filenamePattern`. */
 export declare const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = "^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$";
 /** Stable issue codes returned by patch policy evaluation. */
-export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | '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';
 /** A single patch policy validation finding. */
 export interface PatchPolicyIssue {
     code: PatchPolicyIssueCode;

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

@@ -260,6 +260,28 @@ function evaluateGaps(cfg, patches, severity) {
     }
     return issues;
 }
+function evaluateOrderCollisions(patches, severity) {
+    const byOrder = new Map();
+    for (const patch of patches) {
+        const matches = byOrder.get(patch.order) ?? [];
+        matches.push(patch);
+        byOrder.set(patch.order, matches);
+    }
+    const issues = [];
+    for (const [order, matches] of [...byOrder.entries()].sort((a, b) => a[0] - b[0])) {
+        if (matches.length <= 1)
+            continue;
+        const filenames = matches.map((patch) => patch.filename).sort((a, b) => a.localeCompare(b));
+        issues.push({
+            code: 'order-collision',
+            filename: String(order).padStart(3, '0'),
+            severity,
+            message: `patchPolicy requires unique numeric orders; order ${String(order).padStart(3, '0')} ` +
+                `is used by: ${filenames.join(', ')}.`,
+        });
+    }
+    return issues;
+}
 /** Evaluates an entire patch manifest against the configured policy. */
 export function evaluatePatchPolicy(config, manifest) {
     const cfg = policy(config);
@@ -267,6 +289,7 @@ export function evaluatePatchPolicy(config, manifest) {
         return [];
     const severity = issueSeverity(config);
     const issues = manifest.patches.flatMap((patch) => evaluatePatchMetadata(cfg, patch, severity));
+    issues.push(...evaluateOrderCollisions(manifest.patches, severity));
     issues.push(...evaluateGaps(cfg, manifest.patches, severity));
     return issues;
 }

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

@@ -70,7 +70,7 @@ export interface ExportOptions {
      * be superseded and which files caused the coverage.
      */
     dryRun?: boolean;
-    /** Place the new patch at a specific ordinal, shifting subsequent patches. */
+    /** Place the new patch at this exact unused order without renumbering existing patches. */
     order?: number;
     /** Place the new patch immediately before the named patch. */
     before?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.21.2",
+  "version": "0.21.4",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",