@hominis/fireforge 0.49.2 → 0.50.0

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

@@ -51,6 +51,23 @@ export interface PatchResult {
      */
     autoResolvedOriginals?: Map<string, Uint8Array>;
 }
+/**
+ * A size waiver with a ceiling, one form of a `PatchMetadata.lintIgnore`
+ * entry. The named size rule stays suppressed while its measurement is at
+ * or below `max` and fires again past it, so a waived file cannot grow
+ * without bound. Only the measured size rules (`file-too-large`,
+ * `large-patch-lines`, `large-patch-files`) accept a ceiling.
+ */
+export interface LintIgnoreCeiling {
+    /** Size rule check ID the waiver applies to. */
+    rule: string;
+    /** Largest measurement (lines or files) the waiver still suppresses. */
+    max: number;
+    /** Why the waiver exists. Required so the ceiling is reviewable. */
+    reason: string;
+}
+/** One `PatchMetadata.lintIgnore` entry: a bare check ID or a ceiling waiver. */
+export type LintIgnoreEntry = string | LintIgnoreCeiling;
 /**
  * Extended patch information with metadata.
  */
@@ -91,8 +108,11 @@ export interface PatchMetadata {
      * listed here still run normally. An entry for an unknown check ID is a
      * no-op: the metadata documents the intent to suppress even if the check
      * is later renamed or removed.
+     *
+     * An entry may instead be a {@link LintIgnoreCeiling}, which waives a size
+     * rule only up to a measured maximum.
      */
-    lintIgnore?: string[];
+    lintIgnore?: LintIgnoreEntry[];
     /**
      * Optional per-patch threshold-tier override for the `large-patch-lines`
      * rule. Exists for branding patches that must touch a small number of
@@ -171,6 +191,26 @@ export interface PatchStagedRegistration {
     /** Optional human-readable rationale for the staged dependency. */
     reason?: string;
 }
+/**
+ * A staged-dependency declaration a lint finding proposes: the arguments of
+ * one `patch staged-dependency <patch> --add` call.
+ */
+export interface PatchLintStagedDeclaration {
+    /** Patch that must carry the declaration. */
+    patch: string;
+    /** Declaration kind (`--kind`). */
+    kind: 'import' | 'registration';
+    /** Declaring file path relative to engine/. */
+    file: string;
+    /** Import specifier (`kind: import`). */
+    specifier?: string;
+    /** Registration line as the patch adds it (`kind: registration`). */
+    line?: string;
+    /** Later-created file path relative to engine/. */
+    creates: string;
+    /** Later patch that creates it. */
+    owner: string;
+}
 /**
  * Schema for patches/patches.json file.
  */
@@ -179,6 +219,27 @@ export interface PatchesManifest {
     version: 1;
     /** Array of patch metadata entries */
     patches: PatchMetadata[];
+    /**
+     * Order numbers a `patch retire` emptied on purpose. A retired slot has no
+     * `.patch` file and no row in `patches`, so apply, export, lint and rebase
+     * never see it; only the `patchPolicy.allowGaps: false` gap check reads it,
+     * as an occupied order. A patch that later takes the same order fills the
+     * slot, and the slot is dropped on that write.
+     */
+    retired?: PatchRetiredSlot[];
+}
+/** One placeholder left by `patch retire`. */
+export interface PatchRetiredSlot {
+    /** The order number the retired patch held. */
+    order: number;
+    /** Category of the retired patch, kept so the slot stays in its range. */
+    category: PatchCategory;
+    /** Filename of the retired patch, for the audit trail only. */
+    filename: string;
+    /** ISO timestamp of the retirement. */
+    retiredAt: string;
+    /** Optional human-readable rationale. */
+    reason?: string;
 }
 /**
  * Summary of import operation with continue mode.
@@ -221,6 +282,13 @@ export interface PatchLintIssue {
      * rename-sensitive fingerprint.
      */
     patches?: string[];
+    /**
+     * For a `forward-import` or `forward-registration` finding: the staged
+     * declarations that would discharge it, one per later creator. The same
+     * records the printed `patch staged-dependency --add` commands carry, in
+     * the shape `patch staged-dependency --from` reads back.
+     */
+    stagedDeclarations?: PatchLintStagedDeclaration[];
     /** Severity: errors block export, warnings are advisory, notices are informational (not counted) */
     severity: 'error' | 'warning' | 'notice';
     /**
@@ -232,4 +300,10 @@ export interface PatchLintIssue {
      *   introduced by the current task.
      */
     tag?: 'introduced' | 'cumulative';
+    /**
+     * The value a size rule measured (lines for `file-too-large` and
+     * `large-patch-lines`, files for `large-patch-files`). A lintIgnore
+     * ceiling compares against it, and `lint --report` carries it.
+     */
+    measurement?: number;
 }

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

@@ -54,6 +54,22 @@ export interface TestConfig {
      * verdict line. `--reap-orphans` is the per-invocation equivalent.
      */
     reapOrphans?: 'report' | 'reap';
+    /**
+     * `fixed` (the default) refuses a browser run while the mochitest server
+     * or Marionette port is held. `auto` lets a run proceed when the holder is
+     * not this checkout's own and the engine's mochitest harness can fall back
+     * to a free port itself, so sibling checkouts can run browser suites at
+     * once. `--auto-ports` is the per-invocation equivalent.
+     */
+    mochitestPorts?: 'fixed' | 'auto';
+}
+/** Patch history log settings stored in fireforge.json. */
+export interface HistoryConfig {
+    /**
+     * Project-relative path of the append-only patch history log. Defaults to
+     * `.fireforge/history.jsonl`, outside the tracked patch queue.
+     */
+    path?: string;
 }
 /** A single external executable required by a project-specific toolchain. */
 export interface ExternalToolRequirement {
@@ -104,6 +120,35 @@ export interface PatchPolicyReservedRange {
     /** Exact patch exceptions allowed in this reserved range. */
     allowed: PatchPolicyReservedAllowedPatch[];
 }
+/**
+ * One `patchPolicy.upstreamAllowlist` entry in object form. The string form
+ * is shorthand for `{ path }`.
+ */
+export interface PatchPolicyUpstreamAllowEntry {
+    /** Engine-relative path glob (`*` within a segment, `**` across segments). */
+    path: string;
+    /**
+     * Registration-only mode: a patch may only add lines to a matching file
+     * (no removals, no deletion), and every non-blank added line must carry
+     * `marker` (or `patchPolicy.addOnlyMarker`), case-insensitively.
+     */
+    addOnly?: boolean;
+    /** Marker an added line must contain. Overrides `patchPolicy.addOnlyMarker`. */
+    marker?: string;
+}
+/**
+ * Limits the files a class of patch may touch, e.g. a `-tests` patch to test
+ * directories and test manifests. A rule applies to a patch when every
+ * selector it sets matches. At least one selector is required.
+ */
+export interface PatchPolicyScopeRule {
+    /** Applies to patches in this category. */
+    category?: string;
+    /** Applies to patches whose filename matches this regular expression. */
+    filenamePattern?: string;
+    /** Engine-relative path globs every file the patch touches must match. */
+    files: string[];
+}
 /**
  * Optional project-specific patch queue policy. When absent, FireForge keeps
  * its historical broad category + numeric ordering behaviour.
@@ -121,6 +166,21 @@ export interface PatchPolicyConfig {
     ranges: PatchPolicyRange[];
     /** Reserved exception ranges. */
     reservedRanges?: PatchPolicyReservedRange[];
+    /**
+     * Globs naming the upstream files a non-reserved patch may modify. A file
+     * counts as upstream when no patch in the queue creates it. Unset: no
+     * restriction.
+     */
+    upstreamAllowlist?: Array<string | PatchPolicyUpstreamAllowEntry>;
+    /** Default marker for `addOnly` allowlist entries that set none. */
+    addOnlyMarker?: string;
+    /** File-scope rules per patch class (category and/or filename pattern). */
+    scopeRules?: PatchPolicyScopeRule[];
+    /**
+     * Require every reserved allowlist entry's `adr` and `documentation` path
+     * to exist under the project root. Default false.
+     */
+    verifyDocumentPaths?: boolean;
 }
 /**
  * Main fireforge.json configuration schema.
@@ -142,6 +202,8 @@ export interface FireForgeConfig {
     buildAudit?: BuildAuditConfig;
     /** Test command defaults */
     test?: TestConfig;
+    /** Patch history log settings */
+    history?: HistoryConfig;
     /** Optional project-specific external toolchains checked by doctor. */
     externalToolchains?: ExternalToolchainConfig[];
     /** Project license SPDX identifier */
@@ -154,6 +216,8 @@ export interface FireForgeConfig {
     patchPolicy?: PatchPolicyConfig;
     /** Typecheck command configuration (CI-grade, whole-project) */
     typecheck?: TypecheckConfig;
+    /** `fireforge check`: the composed static gate's policy and project steps */
+    check?: CheckConfig;
     /**
      * Project marker prefix appended to lines FireForge writes into
      * upstream Firefox source files (e.g. the `customElements.js` tag list).
@@ -162,6 +226,45 @@ export interface FireForgeConfig {
      */
     markerComment?: string;
 }
+/** The built-in steps of `fireforge check`, in table order. */
+export declare const CHECK_BUILTIN_STEPS: readonly ["status", "verify", "lint", "typecheck", "furnace-validate", "token-coverage"];
+/** One built-in `fireforge check` step name. */
+export type CheckBuiltinStep = (typeof CHECK_BUILTIN_STEPS)[number];
+/**
+ * A project command `fireforge check` runs beside its built-in steps
+ * (`check.extraSteps[]`): an audit FireForge does not ship.
+ */
+export interface CheckExtraStep {
+    /** Unique step name shown in the table (lowercase, digits and dashes). */
+    name: string;
+    /** Shell command line, run with `/bin/sh -c` (`cmd.exe /c` on Windows). */
+    command: string;
+    /** Project-relative working directory. Defaults to the project root. */
+    cwd?: string;
+    /** Seconds before the step is killed and fails. Unbounded when unset. */
+    timeout?: number;
+}
+/** Configuration for `fireforge check`. Every field is optional. */
+export interface CheckConfig {
+    /** Built-in steps this project never runs. */
+    skip?: CheckBuiltinStep[];
+    /**
+     * The status step's `--check` policy: `--fail-on`, `--allow` and
+     * `--fail-on-unknown`. Unset runs the default `status --check` policy.
+     */
+    status?: {
+        failOn?: string[];
+        allow?: string[];
+        failOnUnknown?: boolean;
+    };
+    /** `--max-warnings` for the lint and furnace-validate steps. */
+    maxWarnings?: {
+        lint?: number;
+        furnace?: number;
+    };
+    /** Project commands run as further steps. */
+    extraSteps?: CheckExtraStep[];
+}
 /**
  * Configuration for the `fireforge typecheck` command. Distinct from
  * `patchLint.checkJs`: patch-lint runs every time `fireforge lint` runs
@@ -297,6 +400,37 @@ export interface PatchLintFileSizeThresholds {
     /** Test files. Defaults: notice 1200, warning 1400, error 1600. */
     test?: PatchLintFileSizeTier;
 }
+/** What `file-too-large` counts: every line, or only lines that carry code. */
+export type PatchLintFileSizeMetric = 'raw' | 'code';
+/**
+ * What `large-patch-lines` counts: every non-binary line of the unified
+ * diff, or only the added lines that carry code.
+ */
+export type PatchLintPatchSizeMetric = 'diff' | 'addedCode';
+/**
+ * Overrides for one patch-size tier. `lines` drives `large-patch-lines`,
+ * `files` drives `large-patch-files`. Each is a `notice`/`warning`/`error`
+ * triple shaped like {@link PatchLintFileSizeTier}, merged over the
+ * defaults and validated `notice <= warning <= error`.
+ */
+export interface PatchLintPatchSizeTier {
+    lines?: PatchLintFileSizeTier;
+    files?: PatchLintFileSizeTier;
+}
+/**
+ * Overrides for the patch-size thresholds, per tier.
+ *
+ * Module constants until 0.50.0. The defaults are the old constants: lines
+ * general 800/1500/3000, test 1500/3000/6000, branding 8000/18000/30000;
+ * files warn above 5 (general, test) or 60 (branding). The files triple has
+ * no notice or error band by default: an unset `files.notice` follows the
+ * effective `files.warning`, and an unset `files.error` never fires.
+ */
+export interface PatchLintPatchSizeThresholds {
+    general?: PatchLintPatchSizeTier;
+    test?: PatchLintPatchSizeTier;
+    branding?: PatchLintPatchSizeTier;
+}
 /**
  * Configuration for patch lint rules.
  */
@@ -348,6 +482,34 @@ export interface PatchLintConfig {
      * Unset fields keep the built-in defaults.
      */
     fileSizeThresholds?: PatchLintFileSizeThresholds;
+    /**
+     * What `file-too-large` counts. `'raw'` (the default) counts every line
+     * the way `wc -l` does. `'code'` counts the lines left non-blank once
+     * comments are blanked, so JSDoc and blank lines stop counting.
+     */
+    fileSizeMetric?: PatchLintFileSizeMetric;
+    /**
+     * Per-tier overrides for `large-patch-lines` and `large-patch-files`.
+     * Unset fields keep the built-in defaults.
+     */
+    patchSizeThresholds?: PatchLintPatchSizeThresholds;
+    /**
+     * What `large-patch-lines` counts. `'diff'` (the default) counts every
+     * non-binary line of the unified diff. `'addedCode'` counts added lines
+     * that are neither blank nor comment, judged on each file's post-image,
+     * skips lines inside Furnace `@fireforge-include` spans, and counts test
+     * files against the test tier and everything else against the general
+     * tier inside a mixed patch.
+     */
+    patchSizeMetric?: PatchLintPatchSizeMetric;
+    /**
+     * Globs naming registration files (`jar.mn`, `moz.build`, manifests)
+     * that count toward neither `large-patch-lines` nor `large-patch-files`.
+     * A glob without a `/` matches the basename, one with a `/` matches the
+     * engine-relative path. `*` stays within a path segment, `**` crosses
+     * segments. Default: none.
+     */
+    patchSizeRegistrationFiles?: string[];
     /**
      * Run the project's Prettier over patch-owned `.sys.mjs` modules, from
      * inside `engine/` so the engine's own `.prettierrc*`/`.prettierignore`
@@ -387,6 +549,36 @@ export interface PatchLintConfig {
      * and fail the other. Default: 'warning'.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
+    /**
+     * Token scales enforced over CSS files a patch creates (`token-scale`).
+     * Each scale names properties whose values must resolve to its tokens.
+     * Default unset: no scale is enforced.
+     */
+    tokenScales?: PatchLintTokenScale[];
+}
+/**
+ * One `patchLint.tokenScales[]` entry: a property family (spacing, type,
+ * radius, opacity, z-index, …) whose declared values must be tokens on one
+ * scale.
+ */
+export interface PatchLintTokenScale {
+    /** CSS properties governed (exact names, or a `*`-suffixed prefix such as `padding*`). */
+    properties: string[];
+    /** Custom-property prefix of the scale's tokens, e.g. `--mybrowser-space-`. */
+    prefix: string;
+    /**
+     * Literal value atoms accepted without a token (`0`, `auto`, `1px`).
+     * `*` is a wildcard, so `*%` accepts any percentage. CSS-wide keywords
+     * (`inherit`, `initial`, `unset`, `revert`, `revert-layer`) are always
+     * accepted.
+     */
+    allowLiterals?: string[];
+    /**
+     * Further custom properties accepted besides `prefix` (exact names, or a
+     * `*`-suffixed prefix such as `--moz-*`), for reviewed upstream or recipe
+     * tokens.
+     */
+    allow?: string[];
 }
 /**
  * Build modes for mach.

package/dist/src/types/config.js

@@ -1,3 +1,12 @@
+/** The built-in steps of `fireforge check`, in table order. */
+export const CHECK_BUILTIN_STEPS = [
+    'status',
+    'verify',
+    'lint',
+    'typecheck',
+    'furnace-validate',
+    'token-coverage',
+];
 /**
  * Build modes for mach.
  *

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

@@ -103,6 +103,24 @@ export interface CustomComponentConfig {
      */
     sharedFtl?: string;
 }
+/** A reviewed `furnace validate` finding (`furnace.json#validationExceptions[]`). */
+export interface FurnaceValidationException {
+    /** Component tag name the finding is reported on. */
+    component: string;
+    /** The finding's check name, as `furnace validate` prints it in brackets. */
+    check: string;
+    /** Why the finding is accepted. Required: the entry is the review record. */
+    reason: string;
+}
+/**
+ * `furnace validate` checks that run only when `furnace.json#optInChecks`
+ * names them. `icon-button-label`: an icon-only `<moz-button>` (an
+ * `iconsrc` or an `icon` type, no `label` and no text content) carries
+ * neither `data-l10n-id` nor `aria-label`.
+ */
+export declare const FURNACE_OPT_IN_CHECKS: readonly ["icon-button-label"];
+/** One opt-in check name. */
+export type FurnaceOptInCheck = (typeof FURNACE_OPT_IN_CHECKS)[number];
 /**
  * The furnace.json schema.
  */
@@ -161,6 +179,17 @@ export interface FurnaceConfig {
      * Unset disables jsconfig maintenance.
      */
     typecheckJsconfig?: string;
+    /**
+     * Reviewed `furnace validate` findings. Each entry suppresses every
+     * finding of `check` on `component`, and `furnace validate` reports an
+     * entry that no longer matches anything as a stale-exception warning.
+     */
+    validationExceptions?: FurnaceValidationException[];
+    /**
+     * Opt-in `furnace validate` checks (see {@link FURNACE_OPT_IN_CHECKS}).
+     * Unset runs only the default checks.
+     */
+    optInChecks?: FurnaceOptInCheck[];
     /** Stock components tracked for preview */
     stock: string[];
     /** Override components */
@@ -234,6 +263,15 @@ export interface StepError {
      */
     advisory?: boolean;
 }
+/**
+ * Why `applyAllComponents` skipped a component, so a summary can say more
+ * than "skipped". `already-current`: the source is unchanged since the last
+ * recorded apply and the engine copy still matches it (fragment expansions
+ * included), so there was nothing to write. The apply state is shared by
+ * every session on the checkout, so the recorded apply may be another
+ * session's, e.g. a peer's `test --build`.
+ */
+export type ApplySkipKind = 'already-current';
 /**
  * Result of applying all components to the engine source tree.
  */
@@ -246,10 +284,14 @@ export interface ApplyResult {
         /** Non-fatal registration step errors */
         stepErrors?: StepError[];
     }>;
-    /** Components that were skipped (e.g., no changes) */
+    /**
+     * Components that were skipped (e.g., no changes). `kind` names the
+     * reason for summaries; `reason` is the stable free-text form.
+     */
     skipped: Array<{
         name: string;
         reason: string;
+        kind?: ApplySkipKind;
     }>;
     /** Components that failed to apply */
     errors: Array<{

package/dist/src/types/furnace.js

@@ -1,3 +1,10 @@
+/**
+ * `furnace validate` checks that run only when `furnace.json#optInChecks`
+ * names them. `icon-button-label`: an icon-only `<moz-button>` (an
+ * `iconsrc` or an `icon` type, no `label` and no text content) carries
+ * neither `data-l10n-id` nor `aria-label`.
+ */
+export const FURNACE_OPT_IN_CHECKS = ['icon-button-label'];
 /**
  * Operations that can leave a pending-repair marker when they fail to roll
  * back cleanly. The marker is consumed by `fireforge doctor`, which either

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

@@ -1,5 +1,5 @@
 /**
  * Re-exports all type definitions.
  */
-export type { BuildConfig, FireForgeConfig, FirefoxConfig, FirefoxProduct, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
+export type { BuildConfig, FireForgeConfig, FirefoxConfig, FirefoxProduct, PatchLintFileSizeThresholds, PatchLintFileSizeTier, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
 export type { ApplyResult, ComponentType, CustomComponentConfig, DryRunAction, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, StepError, ValidationIssue, } from './furnace.js';

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

@@ -13,7 +13,9 @@ import type { Command } from 'commander';
  * @param obj - Object to filter
  * @returns The same object with every `undefined`-valued key removed
  */
-export declare function pickDefined<T extends object>(obj: T): {
+export declare function pickDefined<T extends object>(obj: T): DefinedProps<T>;
+/** `T` with every property optional and `undefined` removed: what {@link pickDefined} returns. */
+export type DefinedProps<T> = {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
 /**
@@ -74,11 +76,11 @@ export declare function resolveWaitLockSeconds(value: string | number | boolean
  * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
  * session lock and then `.fireforge/furnace.lock`. Only the first had a
  * budget, so a contended deploy died on the file lock's fixed 30 s while
- * its operator believed a much larger budget was in force. Threading the
- * flag reaches the three furnace commands that declare it. This reaches
- * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
- * `override`, `chrome-doc`, …), which have no flag to thread but are just
- * as contended.
+ * its operator believed a much larger budget was in force. Every furnace
+ * leaf that takes the furnace lock threads its own `--wait-lock` into it;
+ * this is the fallback when the flag is absent, and the only budget for
+ * callers that do not thread one (doctor's furnace repair, the
+ * pre-build apply).
  *
  * Env-only: a flag belongs to one invocation and is passed
  * explicitly where it applies, while the environment is exactly the place a
@@ -109,6 +111,32 @@ export declare function addAcceptedWaitLockOption(command: Command): Command;
  * one everywhere else.
  */
 export declare function ensureWaitLockOptionEverywhere(command: Command): void;
+/**
+ * True for a token that reads as a path rather than a number: it has a
+ * path separator or a file extension, or is `.`/`..`. A bare word such as
+ * `nonsense` is not path-shaped, so `--wait-lock nonsense` stays the usage
+ * error it always was.
+ */
+export declare function isPathShapedArgument(token: string): boolean;
+/**
+ * Rewrites a command's option tokens so a path-shaped argument after a
+ * numeric optional-value flag is an operand, and the flag takes its
+ * default.
+ *
+ * Commander binds the next non-dash token to an optional value, so
+ * `fireforge test --build --wait-lock browser_x.js` failed with
+ * "--wait-lock must be an integer in 1..3600 (got "browser_x.js")": the
+ * help says the value is optional, and the obvious spelling refused. The
+ * released flag moves to the end of the option section (before any `--`),
+ * where nothing follows it, so commander reads it bare. Operands keep their
+ * relative order. The value of a required-value option (`--mach-arg
+ * --wait-lock`) is never mistaken for a flag.
+ *
+ * @param argv - The tokens commander passes to `parseOptions`
+ * @param requiredValueFlags - This command's flags that always take a value
+ * @returns The rewritten tokens
+ */
+export declare function releasePathShapedValues(argv: readonly string[], requiredValueFlags: ReadonlySet<string>): string[];
 /**
  * Registers the shared `--wait-lock [seconds]` flag on a lock-taking
  * command (the engine session lock for engine-mutating commands, the patch

package/dist/src/utils/options.js

@@ -151,11 +151,11 @@ export function resolveWaitLockSeconds(value) {
  * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
  * session lock and then `.fireforge/furnace.lock`. Only the first had a
  * budget, so a contended deploy died on the file lock's fixed 30 s while
- * its operator believed a much larger budget was in force. Threading the
- * flag reaches the three furnace commands that declare it. This reaches
- * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
- * `override`, `chrome-doc`, …), which have no flag to thread but are just
- * as contended.
+ * its operator believed a much larger budget was in force. Every furnace
+ * leaf that takes the furnace lock threads its own `--wait-lock` into it;
+ * this is the fallback when the flag is absent, and the only budget for
+ * callers that do not thread one (doctor's furnace repair, the
+ * pre-build apply).
  *
  * Env-only: a flag belongs to one invocation and is passed
  * explicitly where it applies, while the environment is exactly the place a
@@ -204,9 +204,90 @@ export function ensureWaitLockOptionEverywhere(command) {
         // action can see it. Register the uniform flag only on actionable leaves.
         if (sub.commands.length === 0 && !hasWaitLockOption(sub))
             addAcceptedWaitLockOption(sub);
+        releasePathShapedOptionalValues(sub);
         ensureWaitLockOptionEverywhere(sub);
     }
 }
+/**
+ * Optional-value flags whose value is a number and therefore never a path.
+ * `--canary [path]` is the counter-example that must stay out: its value IS
+ * a path.
+ */
+const NUMERIC_OPTIONAL_VALUE_FLAGS = new Set([
+    '--wait-lock',
+    '--wait-browser',
+    '--wait-port',
+    '--shuffle',
+]);
+/**
+ * True for a token that reads as a path rather than a number: it has a
+ * path separator or a file extension, or is `.`/`..`. A bare word such as
+ * `nonsense` is not path-shaped, so `--wait-lock nonsense` stays the usage
+ * error it always was.
+ */
+export function isPathShapedArgument(token) {
+    if (/^\d+(?:\.\d+)?$/.test(token))
+        return false;
+    return token === '.' || token === '..' || /[\\/]/.test(token) || /\.[A-Za-z][\w-]*$/.test(token);
+}
+/**
+ * Rewrites a command's option tokens so a path-shaped argument after a
+ * numeric optional-value flag is an operand, and the flag takes its
+ * default.
+ *
+ * Commander binds the next non-dash token to an optional value, so
+ * `fireforge test --build --wait-lock browser_x.js` failed with
+ * "--wait-lock must be an integer in 1..3600 (got "browser_x.js")": the
+ * help says the value is optional, and the obvious spelling refused. The
+ * released flag moves to the end of the option section (before any `--`),
+ * where nothing follows it, so commander reads it bare. Operands keep their
+ * relative order. The value of a required-value option (`--mach-arg
+ * --wait-lock`) is never mistaken for a flag.
+ *
+ * @param argv - The tokens commander passes to `parseOptions`
+ * @param requiredValueFlags - This command's flags that always take a value
+ * @returns The rewritten tokens
+ */
+export function releasePathShapedValues(argv, requiredValueFlags) {
+    const kept = [];
+    const released = [];
+    let index = 0;
+    for (; index < argv.length; index += 1) {
+        const token = argv[index] ?? '';
+        if (token === '--')
+            break;
+        const next = argv[index + 1];
+        if (requiredValueFlags.has(token) && next !== undefined) {
+            kept.push(token, next);
+            index += 1;
+            continue;
+        }
+        if (NUMERIC_OPTIONAL_VALUE_FLAGS.has(token) &&
+            next !== undefined &&
+            !next.startsWith('-') &&
+            isPathShapedArgument(next)) {
+            released.push(token);
+            continue;
+        }
+        kept.push(token);
+    }
+    return [...kept, ...released, ...argv.slice(index)];
+}
+/**
+ * Installs {@link releasePathShapedValues} on `command` when it registers
+ * any numeric optional-value flag.
+ */
+function releasePathShapedOptionalValues(command) {
+    const flags = command.options.filter((option) => option.long !== undefined && NUMERIC_OPTIONAL_VALUE_FLAGS.has(option.long));
+    if (flags.length === 0)
+        return;
+    const requiredValueFlags = new Set(command.options
+        .filter((option) => option.required)
+        .flatMap((option) => [option.long, option.short])
+        .filter((flag) => flag !== undefined));
+    const parseOptions = command.parseOptions.bind(command);
+    command.parseOptions = (argv) => parseOptions(releasePathShapedValues(argv, requiredValueFlags));
+}
 /**
  * Registers the shared `--wait-lock [seconds]` flag on a lock-taking
  * command (the engine session lock for engine-mutating commands, the patch

package/dist/src/utils/path-glob.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal path globs for policy config: `*` matches within one path segment,
+ * `?` one character of a segment, and `**` any number of whole segments
+ * (`a/**` is everything under `a/`, `**\/x` is `x` in any directory). A
+ * pattern is anchored at both ends against an engine-relative POSIX path;
+ * there is no basename-anywhere matching, so `*.toml` matches only top-level
+ * files and `**\/*.toml` matches them everywhere.
+ *
+ * Hand-rolled because the policy surface needs exactly this much and the
+ * package keeps its dependency list short.
+ */
+/** Compiles one glob to an anchored regular expression. */
+export declare function globToRegExp(glob: string): RegExp;
+/** True when `path` matches at least one of `globs`. */
+export declare function matchesAnyGlob(path: string, globs: readonly string[]): boolean;