@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,1372 +0,0 @@
-/**
- * Command option types for CLI commands.
- */
-import type { FirefoxProduct, ProjectLicense } from '../config.js';
-import type { PatchCategory, PatchSizeShare } from './patches.js';
-/**
- * `--dry-run`: print the planned change and exit without writing anything.
- *
- * Twenty-four option types spelled this field with five different doc
- * comments for one behaviour. The contract is uniform and load-bearing (a
- * dry run must perform every check the real run does and then write
- * nothing), so it is stated once.
- */
-export interface DryRunnable {
-    /** Print the planned change without writing anything. */
-    dryRun?: boolean;
-}
-/**
- * `--yes`: answer the confirmation prompt non-interactively.
- *
- * Required for non-TTY runs, where there is no prompt to answer. It waives
- * the prompt only, never a safety gate. Flags that waive a refusal are
- * spelled `--force*` and live on their own types.
- */
-export interface Confirmable {
-    /** Skip the confirmation prompt. Required for non-TTY runs. */
-    yes?: boolean;
-}
-/**
- * `--force-unsafe`: proceed past a refusal the command would otherwise raise.
- *
- * Distinct from {@link Confirmable}: this waives a correctness gate (a
- * projected-lint failure, a patchPolicy violation), not a prompt.
- */
-export interface UnsafeOverridable {
-    /** Bypass refusals the command would otherwise raise. */
-    forceUnsafe?: boolean;
-}
-/**
- * `--wait-lock [seconds]` for commands that take the ENGINE SESSION lock.
- *
- * Parsed at the CLI layer (`true` for the bare flag, meaning 60 seconds) and
- * consumed there to bound the wait. The command implementation ignores it.
- */
-export interface EngineLockWaitable {
-    /** Parsed `--wait-lock [seconds]` value. `true` means the 60-second default. */
-    waitLock?: number | boolean;
-}
-/**
- * `--wait-lock [seconds]` for commands that mutate patch metadata under the
- * PATCH DIRECTORY lock.
- *
- * Separate from {@link EngineLockWaitable}: the two flags share a
- * spelling but bound different locks, and a reader needs to know which one a
- * command contends for.
- */
-export interface PatchLockWaitable {
-    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
-    waitLock?: number | boolean;
-}
-/**
- * Options for the setup command.
- */
-export interface SetupOptions {
-    /** Browser name */
-    name?: string;
-    /** Vendor/company name */
-    vendor?: string;
-    /** Application ID (reverse-domain format) */
-    appId?: string;
-    /** Binary name (executable name) */
-    binaryName?: string;
-    /** Firefox version to base on */
-    firefoxVersion?: string;
-    /** Firefox product type (firefox, firefox-esr, firefox-beta, firefox-devedition) */
-    product?: FirefoxProduct;
-    /** Overwrite existing configuration without prompting */
-    force?: boolean;
-    /** Project license SPDX identifier */
-    license?: ProjectLicense;
-}
-/**
- * Options for the download command.
- */
-export interface DownloadOptions {
-    /** Force re-download, deleting existing engine/ */
-    force?: boolean;
-    /** With `force`: skip the confirmation for an engine with changes to lose */
-    yes?: boolean;
-}
-/**
- * Options for the source command.
- */
-export interface SourceSetOptions {
-    /** Firefox version to set */
-    version: string;
-    /** Firefox product type */
-    product: FirefoxProduct;
-    /** Optional pinned SHA-256 for the resolved source archive */
-    sha256?: string;
-    /** Clear any existing pinned SHA-256 */
-    clearSha256?: boolean;
-    /** Optional release-candidate build directory (e.g. "build2") */
-    candidate?: string;
-    /** Clear any existing release-candidate build directory */
-    clearCandidate?: boolean;
-}
-/**
- * Options for the build command.
- */
-export interface BuildOptions extends EngineLockWaitable {
-    /** Wait for the objdir browser before deploying/building. */
-    waitBrowser?: number | boolean;
-    /** Also write the run log here, outside `.fireforge/logs/` retention. */
-    keepLog?: string;
-    /** Fast UI-only rebuild */
-    ui?: boolean;
-    /** Number of parallel jobs */
-    jobs?: number;
-    /** Brand to build (stable, esr, etc.) */
-    brand?: string;
-    /**
-     * When a mozinfo mismatch is detected that looks like a safe path
-     * relocation (same structure, different prefix), patch mozinfo paths
-     * in place and run `mach configure` rather than aborting with a
-     * full-rebuild instruction. Falls back to the original abort message
-     * for any mismatch the rewriter cannot prove safe.
-     */
-    rewriteMozinfo?: boolean;
-    /**
-     * Refuse the build (rather than warn) when it would overwrite engine
-     * content recorded in neither a patch body nor the pristine baseline.
-     * The default is a loud warning, because an interactive
-     * operator often means to discard the drift. A scripted gate on a
-     * multi-session checkout wants the hard stop.
-     */
-    refuseUnexportedDrift?: boolean;
-}
-/**
- * Options for the export command.
- */
-export interface ExportOptions extends EngineLockWaitable {
-    /** Name/description for the patch */
-    name?: string;
-    /** Category classification */
-    category?: PatchCategory;
-    /** Detailed description of what the patch does */
-    description?: string;
-    /** Allow superseding multiple existing patches without confirmation */
-    supersede?: boolean;
-    /** Skip patch lint checks (downgrade errors to warnings) */
-    skipLint?: boolean;
-    /**
-     * Print the computed export plan without writing anything. With
-     * `--supersede`, the dry-run output includes which existing patches would
-     * be superseded and which files caused the coverage.
-     */
-    dryRun?: boolean;
-    /** 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;
-    /** Place the new patch immediately after the named patch. */
-    after?: string;
-    /**
-     * Skip the confirmation prompt when placement forces a renumber of more
-     * than one existing patch. Required for non-TTY runs that use placement
-     * flags.
-     */
-    yes?: boolean;
-    /** Bypass cross-patch lint refusal for projected placement state. */
-    forceUnsafe?: boolean;
-    /** Exclude furnace-managed file paths from the export. */
-    excludeFurnace?: boolean;
-    /**
-     * Export the deployed engine copy even when the `components/` source
-     * changed since the last furnace apply. Without this flag the export is
-     * refused so a stale deployed copy cannot silently land in the patch.
-     */
-    allowStaleFurnace?: boolean;
-    /**
-     * Acknowledge that the export will create cross-patch ownership overlap
-     * with existing non-superseded patches. Without this flag, `export`
-     * refuses when one or more `filesAffected` are already claimed by
-     * another patch, because the resulting queue fails `verify` immediately.
-     */
-    allowOverlap?: boolean;
-    /**
-     * Force a tier override on the new patch's `PatchMetadata.tier`. Only
-     * `"branding"` is currently recognised. Commander rejects other values
-     * before the handler runs. Use when a branding patch legitimately
-     * touches a non-allowlisted sibling that `isBrandingOnlyPatch` cannot
-     * reach (a fork-specific theme override under `browser/themes/<name>/`,
-     * a vendor-specific icon resource, etc.).
-     */
-    tier?: 'branding';
-    /**
-     * Lint check IDs to suppress on this patch. Writes to
-     * `PatchMetadata.lintIgnore`. Repeatable on the CLI, and each occurrence
-     * appends to the list. Useful when a patch is advisory-noisy by nature
-     * (a cohesive branding bundle, an auto-generated manifest) and a
-     * specific check does not apply, but `--skip-lint` is too coarse a
-     * hammer.
-     */
-    lintIgnore?: string[];
-}
-/**
- * Options for the reset command.
- */
-export interface ResetOptions extends Confirmable {
-    /** Show what would be reset without doing it */
-    dryRun?: boolean;
-}
-/**
- * Options for the discard command.
- */
-export interface DiscardOptions extends Confirmable {
-    /**
-     * Restore to pristine upstream (HEAD) instead of the patch-applied
-     * baseline, deleting patch-created files.
-     */
-    toUpstream?: boolean;
-    /** Show what would be discarded without doing it */
-    dryRun?: boolean;
-}
-/**
- * Options for the package command.
- */
-export interface PackageOptions {
-    /** Brand to package */
-    brand?: string;
-}
-/**
- * Options for the import command.
- */
-export interface ImportOptions {
-    /**
-     * Answer the engine-drift prompt non-interactively. Unlike `force`,
-     * this does not waive the patch-integrity gate.
-     */
-    yes?: boolean;
-    /** Specific patches to apply (by name) */
-    patches?: string[];
-    /** Continue applying patches even if one fails */
-    continue?: boolean;
-    /** Force import even when engine HEAD has drifted from base commit */
-    force?: boolean;
-    /**
-     * Apply patches only up to and including this patch (by name or ordinal).
-     * Subsequent patches are left unapplied. Useful for bisection and curated
-     * rebuild workflows.
-     */
-    until?: string;
-    /** Preview which patches would be applied without modifying the engine */
-    dryRun?: boolean;
-}
-/**
- * Options for the re-export command.
- */
-export interface ReExportOptions extends EngineLockWaitable {
-    /** Re-export all patches */
-    all?: boolean;
-    /** Scan directories for new/removed files and update filesAffected */
-    scan?: boolean;
-    /**
-     * Explicit engine-relative files to add while scanning. Unlike broad
-     * `--scan`, this does not collect adjacent files from the same directory.
-     * Requires `--scan`. A `<patch>:<path>` entry names its owning patch, which
-     * a call with several target patches requires; selected patches without
-     * an entry then refresh scan-less.
-     */
-    scanFiles?: string[];
-    /**
-     * Path to a JSON manifest containing bulk scan assignments:
-     * `{ "assignments": [{ "patch": "<patch>", "files": ["path"] }] }`.
-     * Requires `--scan`. Mutually exclusive with positional patches, `--all`,
-     * `--scan-file`, and `--files`.
-     */
-    scanFilesManifest?: string;
-    /**
-     * Restrict the re-exported patch's filesAffected to this explicit list.
-     * Files currently in the patch but not in this list are dropped (shrink).
-     * Files in this list but not currently in the patch are added. Mutually
-     * exclusive with `--scan` and `--all`. Applies to a single target patch
-     * at a time.
-     */
-    files?: string[];
-    /** Show what would change without writing */
-    dryRun?: boolean;
-    /** Skip patch lint checks (downgrade errors to warnings) */
-    skipLint?: boolean;
-    /** Skip confirmation prompt on shrink (required for non-TTY) */
-    yes?: boolean;
-    /**
-     * Explicitly allow `--files` to remove paths that are currently owned by
-     * the patch. Without this acknowledgement, non-dry-run shrinks are refused
-     * before the interactive/`--yes` confirmation path.
-     */
-    allowShrink?: boolean;
-    /**
-     * Export the deployed engine copy even when the `components/` source
-     * changed since the last furnace apply. Without this flag the re-export
-     * is refused so a stale deployed copy cannot silently land in the patch.
-     */
-    allowStaleFurnace?: boolean;
-    /** Bypass cross-patch lint refusal on projected shrink state */
-    forceUnsafe?: boolean;
-    /**
-     * After every selected patch re-exports cleanly, stamp each re-exported
-     * patch's `sourceEsrVersion` in `patches.json` to the current
-     * `firefox.version` from `fireforge.json`. Opt-in because the default
-     * contract of `re-export` is "refresh the patch body and filesAffected".
-     * Version stamping is normally a `rebase` responsibility. Use this when
-     * re-exporting after a manual Firefox bump that did not go through
-     * `rebase`.
-     */
-    stamp?: boolean;
-    /**
-     * Force a tier override on the selected patch(es). Only `"branding"` is
-     * currently recognised. Mutually exclusive with `--all`, since mass
-     * tier changes are virtually always footguns: different patches in
-     * the queue have different shapes.
-     */
-    tier?: 'branding';
-    /**
-     * Lint check IDs to suppress, appended (union) to the patch's existing
-     * `lintIgnore` list. De-duplicated. Mutually exclusive with `--all`. To
-     * remove an entry or clear the list, use `fireforge patch lint-ignore`,
-     * which has explicit `--add` / `--remove` / `--clear` modes.
-     */
-    lintIgnore?: string[];
-    /**
-     * Refuse (non-zero exit, patch not written) a scan-less re-export when
-     * unmanaged files exist adjacent to the patch's ownership, instead of
-     * warning. Gate-driven workflows use this so a freshly created file
-     * beside a patch's owned files cannot be silently left out of the
-     * refreshed body. Beside `--scan` it judges the neighbours the scan did
-     * not adopt. Mutually exclusive with `--files`, which sets filesAffected
-     * explicitly.
-     */
-    refuseAdjacentUnmanaged?: boolean;
-    /**
-     * Bypass per-patch lint result cache reads and writes for this invocation
-     * (`--no-cache`). The cache is what lets a repeat re-export of an unchanged
-     * patch skip the checkJs program build entirely.
-     */
-    noCache?: boolean;
-    /**
-     * Refuse (non-zero exit, patch not written) a re-export whose refreshed
-     * body would add or drop lines, in a file the patch already owns, that
-     * the old patch body did not carry.
-     * This is the multi-session guard against silently capturing another
-     * session's uncommitted edits in files the patch already owns. The drift preview
-     * always prints. This flag turns it into a hard stop. Beside `--scan` it
-     * guards the files each patch already owns (adopted files count as
-     * expected). Mutually exclusive with `--files`.
-     */
-    refuseForeignDrift?: boolean;
-    /**
-     * Engine-relative files whose drift is expected (`--expect`, repeatable).
-     * Requires `--refuse-foreign-drift`. The content-based drift detector
-     * cannot tell the exporting session's own slice edits from another
-     * session's, so a slice export under the refusal flag names its intended
-     * files here: drift confined to expected files proceeds, drift anywhere
-     * else still refuses.
-     */
-    expect?: string[];
-    /**
-     * Engine-relative files that are an approved unmanaged exception
-     * (`--expect-unmanaged`, repeatable). Requires
-     * `--refuse-adjacent-unmanaged`. The adjacency refusal is all-or-nothing
-     * without it: a project with a reviewed, intentionally unmanaged path
-     * beside a patch's ownership has to drop the flag entirely and hand-read
-     * the notice, which is a weaker belt than the one being disarmed.
-     * Approved paths are still listed. They are carved out of the refusal
-     * rather than hidden.
-     */
-    expectUnmanaged?: string[];
-    /**
-     * Engine-relative files this session created and will adopt with its next
-     * export (`--expect-new`, repeatable). Requires
-     * `--refuse-adjacent-unmanaged`. Lets the owners of a new file's
-     * registration re-export first while a peer's unmanaged neighbour still
-     * refuses. The path must be changed in engine/ and owned by no patch.
-     */
-    expectNew?: string[];
-    /**
-     * Reviewed ignore list for `--refuse-adjacent-unmanaged`
-     * (`--adjacent-ignore`, repeatable): an engine-relative path, or a glob
-     * whose `*` stays within one segment (`**` is refused). Matches are
-     * reported, never refused.
-     */
-    adjacentIgnore?: string[];
-    /**
-     * Explicitly retire named files in a scan-less export: an absent file the
-     * patch created, or a patch-modified upstream file whose engine copy is
-     * back at HEAD.
-     */
-    expectRemoved?: string[];
-    /**
-     * Where a refused `--scan` adoption writes its one `--from`-ready
-     * declaration report (`--declarations-out`). Defaults to
-     * `.fireforge/declarations/`.
-     */
-    declarationsOut?: string;
-    /**
-     * `--hunks-from <diff>`: export each named file as the patch's current
-     * body plus only the hunks in this diff, leaving every other session's
-     * edits in the file out.
-     */
-    hunksFrom?: string;
-    /**
-     * `--exclude-hunks <diff>`: export each named file as the working tree
-     * minus the hunks in this diff.
-     */
-    excludeHunks?: string;
-}
-/**
- * Options for the `fireforge patch tier` subcommand. Sets or clears the
- * `PatchMetadata.tier` field on a single patch without rewriting the
- * `.patch` file body. The manifest is the only thing that changes.
- */
-export interface PatchTierOptions extends Confirmable, DryRunnable, PatchLockWaitable {
-    /** Force the named tier on the patch. Only `"branding"` is recognised. */
-    tier?: 'branding';
-    /** Remove the `tier` override entirely, restoring auto-detection. */
-    clear?: boolean;
-}
-/**
- * Options for the `fireforge patch lint-ignore` subcommand. Modes are
- * mutually exclusive: exactly one of `add`, `remove`, or `clear` must
- * be set per invocation.
- */
-export interface PatchLintIgnoreOptions extends Confirmable, DryRunnable, PatchLockWaitable {
-    /** Lint check IDs to add to the patch's `lintIgnore` list (union, de-duped). */
-    add?: string[];
-    /** Lint check IDs to remove from the patch's `lintIgnore` list. */
-    remove?: string[];
-    /** Drop the `lintIgnore` field entirely. */
-    clear?: boolean;
-    /**
-     * With `add`: write `{ rule, max, reason }` ceiling entries instead of
-     * bare IDs. Only the measured size rules accept one. Requires `reason`.
-     */
-    max?: number;
-    /** Why the ceiling exists. Required with `max` or a `<rule>=<max>` add. */
-    reason?: string;
-    /** With a ceiling on `large-patch-lines`: the share it bounds. */
-    share?: PatchSizeShare;
-    /**
-     * Add every entry in a JSON file under one lock hold: an array of
-     * entries, or a lint report whose ceilings for the patch are rebaselined.
-     */
-    from?: string;
-}
-/**
- * Options for the `fireforge patch staged-dependency` subcommand. Modes are
- * mutually exclusive: add a declaration, remove one or more matching
- * declarations, or clear all staged dependencies from the patch.
- */
-export interface PatchStagedDependencyOptions extends Confirmable, DryRunnable, PatchLockWaitable {
-    /** Add a staged dependency declaration. */
-    add?: boolean;
-    /** Remove matching staged dependency declarations. */
-    remove?: boolean;
-    /** Drop the stagedDependencies field entirely. */
-    clear?: boolean;
-    /**
-     * Declaration shape: `import` (forward import, the default when unset) or
-     * `registration` (jar.mn packaging line, customElements or actor
-     * registration). Registration entries use `line` instead of `specifier`.
-     */
-    kind?: string;
-    /** Declaring file path relative to engine/. */
-    file?: string;
-    /** Exact import specifier as it appears in source (`kind: import`). */
-    specifier?: string;
-    /**
-     * Registration/packaging line as the patch adds it, compared
-     * whitespace-trimmed (`kind: registration`).
-     */
-    line?: string;
-    /** Later-created file path relative to engine/. */
-    creates?: string;
-    /** Optional exact patch filename expected to create `creates`. */
-    owner?: string;
-    /** Optional human-readable rationale stored with the declaration. */
-    reason?: string;
-    /**
-     * JSON file of declarations to add in one call (`--add` only): a
-     * `lint --per-patch --report` document or a plain array of declarations.
-     */
-    from?: string;
-}
-/**
- * Options for the `patch split` command.
- */
-export interface PatchSplitOptions extends Confirmable, PatchLockWaitable, UnsafeOverridable {
-    /** Files to move out of the source patch (engine-relative). */
-    files: string[];
-    /** Name for the new patch (used in its filename slug). */
-    name: string;
-    /** Category for the new patch. Defaults to the source patch's category. */
-    category?: string;
-    /** Description for the new patch. */
-    description?: string;
-    /** Exact sparse order for the new patch (mutually exclusive with before/after). */
-    order?: number;
-    /** Place the new patch before this patch identifier. */
-    before?: string;
-    /** Place the new patch after this patch identifier (default: the source). */
-    after?: string;
-    /** Preview without writing. */
-    dryRun?: boolean;
-    /** Skip per-patch lint of the projected bodies. */
-    skipLint?: boolean;
-    /** Where a refusal writes its one `--from`-ready declaration report. */
-    declarationsOut?: string;
-    /** Write the committed old-to-new filename map of renumbered patches here as JSON. */
-    mapOut?: string;
-}
-/**
- * Options for the `fireforge patch move-files` subcommand. Without
- * `--create` it is preview-only: it validates an ownership transfer and
- * prints the explicit `re-export --files` commands needed to perform it.
- * With `--create --order <n>` the target patch is created at that order
- * and the files move into it as one split-style transaction.
- */
-export interface PatchMoveFilesOptions extends Confirmable, PatchLockWaitable, UnsafeOverridable {
-    /** File paths relative to engine/ to move from the source patch to the target patch. */
-    file?: string[];
-    /** Create the target patch (transactional bootstrap of a split). Requires `order`. */
-    create?: boolean;
-    /** Exact sparse order for the created patch. Only valid with `create`. */
-    order?: number;
-    /** Category for the created patch. Defaults to the source patch's. */
-    category?: string;
-    /** Description for the created patch. */
-    description?: string;
-    /** Preview the create+move without writing. */
-    dryRun?: boolean;
-    /** Skip per-patch lint of the projected bodies. */
-    skipLint?: boolean;
-    /** Where a refusal writes its one `--from`-ready declaration report. */
-    declarationsOut?: string;
-    /**
-     * New engine files no patch owns, adopted into the destination in the
-     * same transaction (engine-relative, repeatable).
-     */
-    scanFile?: string[];
-    /**
-     * Allow the move to empty the source: re-point the declarations it owns
-     * to the destination and retire its slot. Not valid with `create`.
-     */
-    retireEmpty?: boolean;
-}
-/**
- * Options for the rebase command.
- */
-export interface RebaseOptions {
-    /**
-     * Seconds to wait for the patch directory lock. The rebase loop rewrites
-     * patch bodies under that lock.
-     */
-    waitLock?: number | boolean;
-    /** Resume a previously interrupted rebase session */
-    continue?: boolean;
-    /** Cancel the current rebase session and restore engine */
-    abort?: boolean;
-    /** Show what would happen without modifying anything */
-    dryRun?: boolean;
-    /** Maximum fuzz factor for git apply (default 3) */
-    maxFuzz?: number;
-    /** Skip dirty-tree confirmation prompt */
-    yes?: boolean;
-}
-/**
- * Options for the run command.
- */
-export interface RunOptions {
-    /** Additional arguments to pass to the browser */
-    args?: string[];
-    /** Launch with this profile directory, passed to Firefox as `-profile`. */
-    profile?: string;
-    /**
-     * Launch with a fresh temporary profile, removed when the run ends.
-     * Implied by `smokeExit` unless `profile` is given.
-     */
-    tempProfile?: boolean;
-    /**
-     * Pass `-purgecaches` with a named `profile`, so Firefox discards the
-     * profile's startup cache (compiled chrome scripts) before it runs. A UI
-     * build keeps the build id the cache is keyed on, so a kept profile would
-     * otherwise run the chrome scripts an earlier build cached. Default
-     * `true`; `--no-purge-caches` sets `false`. Fresh temporary profiles and
-     * mach's own profile-default (cleaned before every run) have no cache to
-     * purge.
-     */
-    purgeCaches?: boolean;
-    /**
-     * Enable smoke-run mode. Launches the browser, streams the console,
-     * sends SIGTERM to the whole process group after `smokeExit` seconds,
-     * and applies the smoke exit contract:
-     *  - `0`: clean window (no unallowed error lines).
-     *  - `ExitCode.SMOKE_EXIT_FAILURE` (12): one or more console lines
-     *    matched the error heuristic and were not covered by the allowlist.
-     *  - `ExitCode.SMOKE_LAUNCH_FAILURE` (13): the browser exited with a
-     *    non-clean status before the smoke window elapsed (a launch-side
-     *    failure we cannot observe as a console line, such as a crash
-     *    before console wiring, or a missing profile), or exited before the
-     *    window with no browser console output at all (a launch that never
-     *    reached a window, such as a profile in a startup-crash streak).
-     *
-     * POSIX only (process-group semantics do not map cleanly onto Windows).
-     * `runSmokeExit` rejects the flag up front on `win32`.
-     */
-    smokeExit?: number;
-    /**
-     * Repeatable regex patterns that mark a matching console line as
-     * benign. Matches are still counted for the summary but do not drive
-     * the smoke-run exit code.
-     */
-    consoleAllow?: string[];
-    /**
-     * Path to a newline-delimited allowlist regex file. Blank lines and
-     * `#` comments are ignored. Each remaining line is compiled as a
-     * regex and appended to the active allowlist.
-     */
-    consoleAllowFile?: string;
-    /**
-     * Mirror the captured console output to this file path so agents can
-     * inspect the raw stream after smoke-exit returns.
-     */
-    captureConsole?: string;
-    /**
-     * Launch the browser with `--headless` (forwarded to the binary via
-     * `mach run`). Primarily for smoke mode on shared desktops: a headed
-     * smoke window absorbs live keyboard/mouse input, and the resulting
-     * console errors contaminate the capture and can fail the run.
-     */
-    headless?: boolean;
-}
-/**
- * Options for the test command.
- */
-export interface TestOptions extends EngineLockWaitable {
-    /** Queue behind a browser using this objdir; bare flag means 60 seconds. */
-    waitBrowser?: number | boolean;
-    /** Queue behind the mochitest/Marionette port holder. */
-    waitPort?: number | boolean;
-    /**
-     * The `--wait-browser`/`--wait-port` budgets the pre-lock pass already
-     * spent (and stripped from `waitBrowser`/`waitPort`). The first in-lock
-     * check probes once; a check that follows work this invocation did under
-     * the lock (its pre-test build, or an earlier run of a `--repeat` or
-     * `--negative-control` sequence) waits them out again, because refusing
-     * there throws that work away.
-     */
-    spentWaits?: {
-        waitBrowser?: number | boolean;
-        waitPort?: number | boolean;
-    };
-    /** Also write the run log here, outside `.fireforge/logs/` retention. */
-    keepLog?: string;
-    /** Forward mochitest's `--restart-between-tests` (mochitest dispatch only). */
-    restartBetweenTests?: boolean;
-    /** Copy a file into the profile at a relative destination (repeatable source=destination). */
-    profileFile?: string[];
-    /** Run tests in headless mode */
-    headless?: boolean;
-    /**
-     * Pass mozbuild's full verbosity through for the TEST phase by unsetting
-     * the coding-agent markers it quiets output on. Off by default, because
-     * that quieting is worth keeping for builds.
-     */
-    fullOutput?: boolean;
-    /** Run incremental UI build before testing */
-    build?: boolean;
-    /**
-     * Run the scoped pre-test build (packaging exactly the requested paths,
-     * MIXED harnesses allowed) and exit without dispatching tests. One
-     * ~10-minute build then covers both an xpcshell and a browser-chrome
-     * half of a slice. Run each harness afterwards without `--build`.
-     * Emits `FIREFORGE-VERDICT: PASS` on success.
-     */
-    buildOnly?: boolean;
-    /**
-     * Refuse, before the build, instead of dropping any earlier packaging
-     * claim. Scoped builds keep earlier paths by default while each path's own
-     * staging inputs and `engine/mozconfig` are unchanged; this flag makes a
-     * drop fail-closed. Valid only with `--build`/`--build-only` and explicit
-     * paths. See `src/core/coverage-extend.ts`.
-     */
-    extendCoverage?: boolean;
-    /**
-     * Forwarded to the PRE-TEST build: refuse (rather than warn) when that
-     * build would overwrite engine content recorded in neither a patch body
-     * nor the pristine baseline. Same meaning as `fireforge build`'s flag of
-     * the same name. A scripted `test --build` is exactly the shape the
-     * multi-session hazard shows up in, so it must be able to arm the
-     * refusal too. Valid only with `--build`/`--build-only`.
-     */
-    refuseUnexportedDrift?: boolean;
-    /**
-     * Which components the pre-test build deploys: `all` (default), `reached`
-     * (only those a requested test reaches) or `none`. `false` is
-     * `--no-furnace-apply`, the same as `none`. Valid only with
-     * `--build`/`--build-only`.
-     */
-    furnaceApply?: boolean | 'all' | 'reached' | 'none';
-    /** Forward mach's pathless auto-selection mode. Valid only with no explicit paths. */
-    auto?: boolean;
-    /**
-     * Run a marionette preflight before tests. Reports PASS/FAIL in under a
-     * minute. When test paths are supplied, a FAIL aborts before mach test is
-     * spawned. When no paths are supplied, runs the preflight only and exits.
-     */
-    doctor?: boolean;
-    /**
-     * Extra arguments forwarded verbatim to `mach test` (repeatable). Escape
-     * valve for upstream xpcshell/mochitest flags that FireForge does not
-     * model directly. Order relative to other flags is preserved, and
-     * passthrough values appear after `--headless` if both are set.
-     */
-    machArg?: string[];
-    /**
-     * Override the Marionette control port (default 2828) used by the
-     * stale-browser probe, the `--doctor` preflight, and (unless mach args set
-     * `--flavor=xpcshell` / `xpcshell-tests`) auto-forwarded mach flags:
-     * `--setpref=marionette.port=<n>` for the browser listener and
-     * `--marionette=127.0.0.1:<n>` for the mochitest harness client. Omits the
-     * client flag when `--mach-arg` already passes `--marionette`. Set when a
-     * stale process holds the default port or CI uses another port.
-     */
-    marionettePort?: number;
-    /** Kill a recognized stale browser process holding the Marionette port, then continue. */
-    killStaleMarionette?: boolean;
-    /**
-     * Terminate harness helper processes (`xpcshell` httpd, `pywebsocket`,
-     * `ssltunnel`, `moz-http2`) that survived an earlier run in this
-     * project's objdir. The census itself runs on every test dispatch and is
-     * report-only. This flag opts into the kill. Survivors slow later runs
-     * without appearing in their output, so the visibility is the default and
-     * the termination is the choice. `test.reapOrphans: "reap"` in
-     * `fireforge.json` makes it the repo's default.
-     */
-    reapOrphans?: boolean;
-    /**
-     * Path to write the harness process-group id to, rewritten on every mach
-     * spawn (each retry attempt and shard) and removed when the run ends under
-     * FireForge's control. mach runs as its own process-group leader, so a
-     * supervisor's kill of its own group never reaches it; a supervisor that
-     * had to SIGKILL FireForge takes the whole harness tree afterwards with
-     * `kill -- -<pgid>`. The file survives exactly that case, by design.
-     */
-    pgidFile?: string;
-    /** Permit tests against packageable engine edits newer than the last successful build. */
-    allowStaleBuild?: boolean;
-    /**
-     * Permit tests despite `components.conf` changes that only a full
-     * `fireforge build` compiles into the StaticComponents table. The
-     * packaged child process will resolve the old table. For operators who
-     * rebuilt out-of-band and accept the risk. Distinct from
-     * `allowStaleBuild`, which only accepts stale packaged content.
-     */
-    allowStaleComponents?: boolean;
-    /** Run the configured short harness canary. `true` means use `fireforge.json`'s test.canaryPath. */
-    canary?: string | boolean;
-    /**
-     * Retry budget for recognized harness crashes (resource-monitor
-     * tracebacks, pre-test no-output hangs, post-green shutdown re-entry).
-     * 0 disables retries. Defaults to {@link DEFAULT_HARNESS_RETRIES} at the
-     * command layer.
-     */
-    harnessRetries?: number;
-    /**
-     * Force dispatch through the generic `mach test` command instead of the
-     * suite-specific `mach xpcshell-test` / `mach mochitest` commands a
-     * single-suite run auto-selects. Escape hatch for the rare case where a
-     * suite-specific command misbehaves. On a healthy host the generic command
-     * is equivalent. The default (auto suite dispatch) skips the mozlog
-     * resource monitor that crashes `mach test` on a broken host.
-     */
-    genericMachTest?: boolean;
-    /**
-     * Commander negation flag for `--no-shard`. When false, multiple test
-     * paths run in one combined mach invocation. By default they shard into
-     * sequential single-file harness runs with an aggregate report.
-     */
-    shard?: boolean;
-    /**
-     * Project-relative (or absolute) artifact path published to the harness
-     * run as `<BINARYNAME>_PERF_SAMPLE_JSON`, for downstream perf-budget
-     * checkers that consume a sample artifact after the run.
-     */
-    perfSamples?: string;
-    /**
-     * Seeded isolated path-argument order for mochitest runs. `true` draws a
-     * fresh seed; a number replays the shard permutation. Native mach
-     * `--shuffle` within a shard remains unseeded. Also exported as
-     * `FIREFORGE_SHUFFLE_SEED` for custom task code and recorded on the verdict.
-     */
-    shuffle?: number | boolean;
-    /**
-     * Run the same selection this many times under one engine-lock hold (the
-     * pre-test build, when requested, runs once). Each run prints a
-     * `FIREFORGE-RUN:` line; the verdict aggregates them with `runs=<p>/<n>`.
-     */
-    repeat?: number;
-    /**
-     * Project-relative path of a reviewed `git diff` against `engine/` or
-     * `components/` sources, applied after the pre-test build and before each
-     * dispatch, and restored byte-exact before the lock is released. The
-     * verdict carries `control=caught|missed|inconclusive`. See
-     * `src/core/negative-control.ts`.
-     */
-    negativeControl?: string;
-    /**
-     * Let a browser run proceed when the mochitest server or Marionette port
-     * is held by something that is not this checkout's own, relying on the
-     * engine harness's busy-port fallback. Same as `test.mochitestPorts: "auto"`.
-     */
-    autoPorts?: boolean;
-    /**
-     * Hold the engine session lock shared for a build-less run with auto
-     * ports, so peers' build-less runs overlap. Same as `test.lockMode: "shared"`.
-     */
-    sharedLock?: boolean;
-    /** Run shards on this many harness instances at once (requires auto ports). */
-    jobs?: number;
-    /** Dispatch n files per mach invocation, judged per file from the raw log. */
-    shardSize?: number;
-    /** Write per-file results (mozlog raw log) as JSON to this path. */
-    results?: string;
-}
-/**
- * Options for the furnace apply command.
- */
-export interface FurnaceApplyOptions extends DryRunnable {
-    /** Proceed despite baseVersion drift (stale overrides) */
-    force?: boolean;
-    /** Watch component directories and re-apply on changes */
-    watch?: boolean;
-    /**
-     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
-     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
-     * engine session lock, so one flag governs both.
-     */
-    waitLockSeconds?: number;
-}
-/**
- * `--wait-lock` budget for a furnace command that takes only Furnace's own
- * lock (`.fireforge/furnace.lock`, via `runFurnaceMutation`): `create`,
- * `remove`, `rename`, `refresh`, `scan`, `override`, `preview` and the
- * `chrome-doc` pair. Without it the flag was accepted and ignored on those
- * commands, so their lock budget came only from `FIREFORGE_WAIT_LOCK`.
- */
-export interface FurnaceLockWaitable {
-    /**
-     * Resolved `--wait-lock` budget in seconds, or undefined for the default
-     * (`FIREFORGE_WAIT_LOCK`, else the furnace lock's own 30 s).
-     */
-    waitLockSeconds?: number;
-}
-/**
- * Options for the furnace preview command.
- */
-export interface FurnacePreviewOptions extends FurnaceLockWaitable {
-    /** Force reinstall Storybook dependencies */
-    install?: boolean;
-}
-/**
- * Options for the furnace deploy command.
- */
-export interface FurnaceDeployOptions extends DryRunnable {
-    /** Proceed despite baseVersion drift (stale overrides) */
-    force?: boolean;
-    /** Skip the validation step (apply only, no accessibility/compatibility checks) */
-    skipValidate?: boolean;
-    /**
-     * The patch being exported (`--owner`). A deployed file the deploy would
-     * overwrite that another patch owns refuses the whole deploy.
-     */
-    owner?: string;
-    /**
-     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
-     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
-     * engine session lock, so one flag governs both.
-     */
-    waitLockSeconds?: number;
-}
-/**
- * Options for the furnace refresh command.
- */
-export interface FurnaceRefreshOptions extends DryRunnable, FurnaceLockWaitable {
-    /** Refresh all overrides in a single batch */
-    all?: boolean;
-    /** Conflict resolution strategy for automated use (ours = keep local, theirs = accept upstream) */
-    strategy?: 'ours' | 'theirs';
-    /** Reset the override's baseline to the current engine HEAD, skipping three-way merge */
-    resetBase?: boolean;
-}
-/**
- * Options for the furnace rename command.
- */
-export interface FurnaceRenameOptions extends DryRunnable, FurnaceLockWaitable {
-}
-/**
- * Options for the furnace sync command.
- */
-export interface FurnaceSyncOptions extends DryRunnable {
-    /** Conflict resolution strategy for three-way merge (ours = keep local, theirs = accept upstream) */
-    strategy?: 'ours' | 'theirs';
-    /**
-     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
-     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
-     * engine session lock, so one flag governs both.
-     */
-    waitLockSeconds?: number;
-}
-/**
- * Options for the furnace validate command.
- */
-export interface FurnaceValidateOptions {
-    /** Auto-fix registration issues (missing jar.mn entries, customElements.js registration) */
-    fix?: boolean;
-    /** Write one schemaVersion-1 JSON document to stdout instead of the human report. */
-    json?: boolean;
-    /** Fail when more than this many warnings remain after `validationExceptions`. */
-    maxWarnings?: number;
-}
-/**
- * Options for the furnace override command.
- */
-export interface FurnaceOverrideOptions extends FurnaceLockWaitable {
-    /** Override type: css-only or full */
-    type?: 'css-only' | 'full';
-    /** Description of the override */
-    description?: string;
-}
-/**
- * Options for the furnace remove command: the confirmation mixin plus the
- * furnace lock budget.
- */
-export interface FurnaceRemoveOptions extends Confirmable, FurnaceLockWaitable {
-}
-/**
- * Options for the furnace create command.
- */
-export interface FurnaceCreateOptions extends FurnaceLockWaitable {
-    /** Component description */
-    description?: string;
-    /**
-     * Engine-relative directory the test scaffold writes into, instead of
-     * the default `browser/base/content/test/<binaryName>/` (browser-chrome)
-     * or `browser/base/content/test/<binaryName>-xpcshell/<component>/`
-     * (xpcshell). Must stay under `browser/base/content/test/` so the
-     * manifest registration keeps working. Not supported for
-     * `--test-style=mochikit` (that harness lives in the upstream
-     * toolkit/content/tests/widgets tree).
-     */
-    testDir?: string;
-    /** Include Fluent l10n support */
-    localized?: boolean;
-    /** Register in customElements.js (default: true) */
-    register?: boolean;
-    /** Scaffold Mochitest directory and register in moz.build */
-    withTests?: boolean;
-    /**
-     * Scaffold an xpcshell test harness (headless, no tabbrowser) instead of
-     * browser-chrome. Required for forks without a `tabbrowser` (storage-only
-     * code, observer-driven modules). Implies `withTests` when set. Writes an
-     * `xpcshell.toml` + `test_<name>.js` under
-     * `engine/browser/base/content/test/<binary-name>-xpcshell/` and leaves
-     * moz.build registration to the operator (add the directory to
-     * `XPCSHELL_TESTS_MANIFESTS`).
-     */
-    xpcshell?: boolean;
-    /**
-     * Test harness style to scaffold when `--with-tests` is set.
-     *
-     * - `browser-chrome` (default when `--with-tests` is set without
-     *   `--test-style`): browser mochitest scaffold. Requires a working
-     *   `tabbrowser`. Prefer this for interactive chrome/widget coverage
-     *   (including on macOS).
-     * - `mochikit`: opt-in MochiKit test at
-     *   `engine/toolkit/content/tests/widgets/test_<tag>.html` that loads
-     *   the component via `chrome://global/`. Use when the top-level chrome
-     *   document lacks a `tabbrowser`. On macOS the toolkit mochitest-chrome
-     *   flavor can be unreliable (long idle timeout).
-     * - `xpcshell`: equivalent to setting `--xpcshell`. Headless, storage-only.
-     */
-    testStyle?: 'mochikit' | 'browser-chrome' | 'xpcshell';
-    /** Stock component tag names composed internally by this component */
-    compose?: string[];
-    /**
-     * Participate in a pre-existing feature-scoped Fluent bundle at this
-     * path (as used by `insertFTLIfNeeded`, e.g. `browser/mybrowser-dock.ftl`)
-     * instead of scaffolding a per-component `.ftl`. Implies `localized`.
-     * Persists onto the furnace.json entry so validation and apply skip the
-     * per-component paths.
-     */
-    sharedFtl?: string;
-    /**
-     * Show the planned file set and furnace.json changes without writing
-     * anything. All validation that does not require disk writes (tag name
-     * shape, name conflicts, engine pre-existence, `--compose` targets, cycle
-     * detection, prefix warning) runs before the plan is emitted, so a
-     * dry-run faithfully previews the real command's outcome.
-     */
-    dryRun?: boolean;
-    /**
-     * Bypass the configured `componentPrefix` check for the supplied name.
-     * Without this flag, a name that does not start with the prefix is
-     * rejected before any files are written, so a prefix-mismatched
-     * component cannot leave behind a half-scaffolded state. Pass this
-     * flag only when you know the prefix mismatch is intentional, e.g.
-     * creating an experimental component whose name intentionally breaks
-     * the fork's convention.
-     */
-    allowPrefixMismatch?: boolean;
-}
-/**
- * Options for the wire command.
- */
-export interface WireOptions {
-    init?: string;
-    destroy?: string;
-    dom?: string;
-    dryRun?: boolean;
-    after?: string;
-    subscriptDir?: string;
-    /**
-     * Chrome document the DOM fragment's `#include` is inserted into, relative
-     * to engine/. Defaults to the first entry of
-     * `furnace.json.tokenHostDocuments` when set, otherwise
-     * `browser/base/content/browser.xhtml`.
-     */
-    target?: string;
-}
-/**
- * Options for the register command.
- */
-export interface RegisterOptions {
-    dryRun?: boolean;
-    after?: string;
-    /** Scaffold a missing manifest (moz.build / xpcshell.toml) and wire the parent chain. */
-    createManifest?: boolean;
-}
-/**
- * Options for the patch delete command.
- */
-export interface PatchDeleteOptions extends Confirmable, DryRunnable, PatchLockWaitable {
-    /** Bypass the hard refusal when later patches depend on the target. */
-    forceUnsafe?: boolean;
-    /** Also delete the engine files the patch creates that are still on disk. */
-    deleteCreated?: boolean;
-}
-/**
- * Options for the `fireforge patch retire` subcommand: `patch delete` that
- * keeps the removed patch's order as a retired slot in `patches.json`.
- */
-export interface PatchRetireOptions extends PatchDeleteOptions {
-    /** Optional human-readable rationale stored on the retired slot. */
-    reason?: string;
-}
-/**
- * Options for the `fireforge patch stage` subcommand: stage the named
- * patches' files and only their `patches.json` rows in the project index.
- */
-export type PatchStageOptions = DryRunnable & PatchLockWaitable;
-/**
- * Options for the `fireforge patch reserve` subcommand: hold an order
- * number for a patch not exported yet, or release the hold.
- */
-export interface PatchReserveOptions extends DryRunnable, PatchLockWaitable {
-    /** Category the reserved patch will carry (required to reserve). */
-    category?: string;
-    /** Who holds the reservation (required to reserve). */
-    owner?: string;
-    /** Optional human-readable rationale stored on the reserved slot. */
-    reason?: string;
-    /** Release the reservation at the order instead of creating one. */
-    release?: boolean;
-}
-/**
- * Options for the `fireforge patch rename` subcommand. Updates the patch's
- * filename, manifest `name`, and (optionally) `description` atomically
- * without rewriting the `.patch` file body. Companion to `re-export --files`
- * for the case where the body is already correct but the patch's identity
- * describes a pre-shrink scope.
- */
-export interface PatchRenameOptions extends Confirmable, DryRunnable, PatchLockWaitable, UnsafeOverridable {
-    /**
-     * New human-readable name. Sanitised the same way `export --name`
-     * sanitises into the filename slug (lowercase, non-alphanumerics
-     * collapsed to `-`, length-capped). The patch's `name` field stores
-     * the raw value. The filename uses the sanitised slug. Optional when
-     * `--category`/`--order`/`--description` carry the change.
-     */
-    to?: string;
-    /**
-     * New category (validated against configured categories). Rewrites
-     * the filename prefix and the manifest row in one transaction, so
-     * recategorising does not require `patch delete` + fresh export.
-     */
-    category?: string;
-    /**
-     * Move the patch to this exact unused sparse order. Collisions refuse
-     * with a pointer to `patch reorder` (which renumbers siblings). An
-     * order change is projected through cross-patch lint first.
-     */
-    order?: number;
-    /**
-     * Replacement description. Omit to leave the description unchanged
-     * (intentional: operators frequently want to relabel the slug
-     * without touching the description).
-     */
-    description?: string;
-}
-/**
- * Options for the patch reorder command.
- */
-export interface PatchReorderOptions extends PatchLockWaitable {
-    to?: number;
-    before?: string;
-    after?: string;
-    /**
-     * Shift a run of patches up by this many orders (`--shift <n> --from
-     * <order> [--through <order>]`) instead of moving one patch.
-     */
-    shift?: number;
-    /** First order of the run `shift` moves. */
-    from?: number;
-    /** Last order of the run `shift` moves (default: the end of the run). */
-    through?: number;
-    /** Write the committed old-to-new filename map here as JSON. */
-    mapOut?: string;
-    yes?: boolean;
-    dryRun?: boolean;
-    forceUnsafe?: boolean;
-}
-/**
- * Options for the patch compact command.
- */
-export interface PatchCompactOptions extends Confirmable, DryRunnable, PatchLockWaitable, UnsafeOverridable {
-}
-/**
- * Options for the status command.
- */
-export interface StatusOptions {
-    raw?: boolean;
-    /**
-     * Report the engine-session lock instead of file status:
-     * holder pid, the command it is running, how long it has held the lock,
-     * and how many waiters are queued behind it. Read-only: it never
-     * acquires the lock, so it is safe to run while a build or test holds
-     * it, which is when an operator usually asks.
-     */
-    lock?: boolean;
-    unmanaged?: boolean;
-    /**
-     * Render a flat file→owning-patch ownership table instead of the three-
-     * bucket classification. Sources the path list from the manifest's
-     * `filesAffected` per patch and flags any path claimed by more than one
-     * patch as an ownership conflict.
-     */
-    ownership?: boolean;
-    /**
-     * Print the recorded test-packaging coverage of the last build baseline
-     * (scope, timestamp, recording invocation) and exit. Read-only, and the
-     * counterpart to the out-of-coverage test refusal.
-     */
-    testCoverage?: boolean;
-    /** Output machine-readable JSON instead of human-readable text. */
-    json?: boolean;
-    /**
-     * With `--json`: emit only the summary counts (plus the offending
-     * files per fail-set classification when the `--check`/`--fail-on`
-     * policy is active), omitting the per-file `files[]` payload that
-     * grows with the queue. Refused without `--json`.
-     */
-    summary?: boolean;
-    /**
-     * With `--json` (and composing with `--summary`), append an additive
-     * `ownership` block (the flat path→owning-patch rows plus
-     * managed/unmanaged/conflict counts) so a gate reads ownership,
-     * classification, and the check verdict from one scan instead of three
-     * back-to-back `status` invocations. This is a modifier rather than a
-     * mode: exit semantics are unchanged, so ownership conflicts still fail
-     * only the human `--ownership` mode. Refused without `--json`.
-     */
-    includeOwnership?: boolean;
-    /**
-     * Exit non-zero when any classification in the fail policy is
-     * non-empty (default policy: unmanaged, patch-owned-drift, conflict).
-     * Composes with the default view and `--json`. Refused alongside
-     * `--raw`/`--unmanaged`/`--ownership`/`--test-coverage`.
-     */
-    check?: boolean;
-    /**
-     * Comma-separated classification list replacing the default `--check`
-     * policy. Implies `--check`. Unknown values refuse, naming the valid
-     * classification set. `ownership-conflict` (a path claimed by more than
-     * one patch) is accepted beside the file classifications.
-     */
-    failOn?: string;
-    /**
-     * Comma-separated classification list that never fails `--check`,
-     * removed from the fail set. Implies `--check`. Naming a class in both
-     * `failOn` and `allow` refuses.
-     */
-    allow?: string;
-    /**
-     * With `allow`: fail on every present classification that neither
-     * `failOn` nor `allow` names, so a classification added by a later
-     * FireForge fails closed. Implies `--check`.
-     */
-    failOnUnknown?: boolean;
-    /**
-     * Judge only these patches (`--patches`, each value may be a comma
-     * list): files they own or claim and ownership rows naming them.
-     */
-    patches?: string[];
-}
-/**
- * Options for the token add command.
- */
-export interface TokenAddOptions {
-    /**
-     * Required for a base declaration. Optional under
-     * {@link TokenAddOptions.variant}, which routes into a `:root<selector>`
-     * block where no category applies.
-     */
-    category?: string;
-    mode: string;
-    description?: string;
-    darkValue?: string;
-    dryRun?: boolean;
-    /** Declare the category banner in the tokens CSS when it does not exist yet. */
-    createCategory?: boolean;
-    /**
-     * Attribute selector fragment (e.g. `[data-skin=precision]` or
-     * `[data-private]`) routing the declaration into a `:root<variant>` block.
-     */
-    variant?: string;
-}
-/**
- * Options for the doctor command.
- */
-export interface DoctorOptions {
-    /**
-     * Seconds to wait for the patch directory lock. This command can mutate
-     * the patch manifest under that lock.
-     */
-    waitLock?: number | boolean;
-    /**
-     * Rebuild patches.json from the on-disk patch files, preserving every
-     * field the patch bodies cannot express. Refused when patches.json exists
-     * but cannot be parsed, unless `allowMetadataLoss` is also set.
-     */
-    repairPatchesManifest?: boolean;
-    /**
-     * Repair only the `filesAffected` lists that disagree with their patch
-     * body. Narrower than `repairPatchesManifest`: it rewrites one field on the
-     * drifted rows and leaves every other row byte-identical, and it needs no
-     * project config, so it works on a project whose fireforge.json is broken.
-     */
-    repairFilesAffected?: boolean;
-    /**
-     * Accept the whole-manifest metadata reinvention that rebuilding an
-     * unparseable patches.json implies. Only meaningful with
-     * `repairPatchesManifest`.
-     */
-    allowMetadataLoss?: boolean;
-    /**
-     * Project what a requested repair would change and write nothing. Refused
-     * without a repair flag rather than accepted as a silent no-op.
-     */
-    dryRun?: boolean;
-    /**
-     * Clear a stale `pendingResolution` marker, but only after the same
-     * read-only queue health checks used by `fireforge verify` report no
-     * error-severity findings.
-     */
-    clearResolution?: boolean;
-    /**
-     * Opt-in repair path for furnace-specific checks. When true, doctor will:
-     * - clear stale `.fireforge/furnace-state.json` entries whose component is
-     *   no longer in `furnace.json`,
-     * - run `applyAllComponents` to reconcile any engine drift,
-     * - clear the `pendingRepair` marker on success.
-     * Mirrors `repairPatchesManifest` in that the repair is only attempted when
-     * the caller explicitly asks for it, so a read-only `doctor` run stays cheap
-     * and side-effect-free.
-     */
-    repairFurnace?: boolean;
-    /** Run extra post-rebase checks for common Firefox registration surfaces. */
-    postRebaseAudit?: boolean;
-}
-/** Options controlling how the lint command filters and tags its output. */
-export interface LintCommandOptions {
-    /**
-     * When set, tag each issue as `introduced` or `cumulative` based on
-     * whether its file changed since this git revision (e.g. `HEAD`, a
-     * branch name, or a SHA). Issues are not filtered and the full set
-     * still prints, but a diff-scoped summary makes it easy to see which
-     * errors the current task introduced.
-     */
-    since?: string;
-    /**
-     * When set together with {@link since}, scope the exit code to issues
-     * tagged `introduced`. Cumulative pre-existing errors still print, so the
-     * operator sees the full queue state, but do not fail lint. This is for a
-     * branch whose own diff is clean but whose repo carries unrelated
-     * `raw-color` / license-header errors from older patches.
-     *
-     * Requires {@link since}: without a revision to diff against there is no
-     * distinction between introduced and cumulative, so the flag is rejected
-     * up-front rather than silently ignored.
-     */
-    onlyIntroduced?: boolean;
-    /**
-     * Lint each patch in the queue as its own isolated diff, rather than the
-     * aggregate `git diff HEAD` across all applied patches.
-     *
-     * On a repo where `import` or `rebase` has just applied the full queue,
-     * the aggregate diff sums every patch's changes, and the patch-size
-     * advisory rules (`large-patch-lines`, `large-patch-files`) fire against
-     * that sum, reporting "Patch is 37529 lines" for a queue of
-     * individually-fine patches. `--per-patch` rescopes the diff to each patch's own
-     * `filesAffected`, honours the patch's own `lintIgnore`, and runs the
-     * cross-patch rules once over the whole queue so queue-level findings
-     * still surface.
-     *
-     * Positional file arguments change meaning under this flag: they are PATCH
-     * selectors resolved like {@link patches} entries, not engine file paths.
-     */
-    perPatch?: boolean;
-    /**
-     * Restrict `--per-patch` to a named subset of the queue (by filename,
-     * filename ± `.patch`, or manifest `name`). Lets a change that touches a
-     * handful of patches run the per-patch gate over just those instead of
-     * the full ~90-patch queue. Only valid with {@link perPatch}. Queue-level
-     * findings (policy, cross-patch) are scoped to files the subset touches.
-     */
-    patches?: string[];
-    /**
-     * 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;
-    /**
-     * Bypass per-patch lint cache reads and writes. Accepted in aggregate mode
-     * for CLI consistency, but only `--per-patch` currently uses the cache.
-     */
-    noCache?: boolean;
-    /**
-     * With `--per-patch`, write a machine-readable JSON report (schemaVersion
-     * 1: per-patch lineCount, filesAffected, tier, thresholds, issues, and
-     * lintIgnore-suppressed issues) to this path. Requires
-     * {@link perPatch}.
-     */
-    report?: string;
-    /**
-     * With `--per-patch`: `'full'` (default) prints every NOTICE line;
-     * `'summary'` prints one line per check with its count and patch count.
-     * Errors and warnings always print in full.
-     */
-    notices?: 'summary' | 'full';
-}