@hominis/fireforge 0.49.1 → 0.50.0

package/dist/src/core/token-lint.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge token lint`: structural checks over the design-token system.
+ *
+ * - `token-lockstep`: a themed override block (the dark `@media` mirror, a
+ *   `:root[variant]` block) declares only tokens the base `:root` declares.
+ *   An override with no base is a token that exists only in one theme, so
+ *   every other theme resolves it to nothing.
+ * - `token-undeclared`: a `var(--<prefix>…)` reference in the tokens CSS or
+ *   in a CSS file the patch queue touches names a token no block of the
+ *   tokens CSS declares. Same-file declarations, `furnace.json`
+ *   `tokenAllowlist` and `runtimeVariables` are exempt, matching the
+ *   `token-prefix-violation` rule's notion of a runtime channel.
+ *
+ * Built on `token-category.ts`'s base-block and comment-mask primitives, so
+ * this report and `token add` agree on which block is the base.
+ */
+import { findBaseRootBounds, maskCommentLines } from './token-category.js';
+const DECLARATION = /(?:^|[{;\s])(--[A-Za-z0-9_-]+)\s*:/g;
+function selectorBefore(text) {
+    const selector = text.slice(Math.max(text.lastIndexOf('}'), text.lastIndexOf(';')) + 1).trim();
+    return selector.length > 0 ? selector.replace(/\s+/g, ' ') : '(block)';
+}
+/**
+ * Every custom-property declaration in a CSS file with the selector trail
+ * of the block holding it, outermost first, joined with ` > `.
+ */
+function collectDeclarations(lines) {
+    const masked = maskCommentLines(lines);
+    const trail = [];
+    const found = [];
+    let pending = '';
+    for (const [index, line] of masked.entries()) {
+        for (const match of line.matchAll(DECLARATION)) {
+            found.push({
+                name: match[1] ?? '',
+                line: index + 1,
+                block: trail.length > 0 ? trail.join(' > ') : '(file scope)',
+            });
+        }
+        for (const char of line) {
+            if (char === '{') {
+                trail.push(selectorBefore(pending));
+                pending = '';
+            }
+            else if (char === '}') {
+                trail.pop();
+                pending = '';
+            }
+            else {
+                pending += char;
+            }
+        }
+        pending += '\n';
+    }
+    return found;
+}
+/** Every custom property the tokens CSS declares, in any block. */
+export function collectDeclaredTokenNames(lines) {
+    return new Set(collectDeclarations(lines).map((declaration) => declaration.name));
+}
+/**
+ * Themed override declarations of `tokenPrefix` tokens that the base
+ * `:root` block does not declare.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param tokensCssPath - Engine-relative path, for the findings
+ * @param tokenPrefix - Only tokens with this prefix are held to lockstep;
+ *   a themed block may still override platform properties
+ */
+export function lintTokenLockstep(lines, tokensCssPath, tokenPrefix) {
+    const bounds = findBaseRootBounds(lines);
+    if (bounds === undefined)
+        return [];
+    const close = bounds.close === -1 ? lines.length : bounds.close;
+    const declarations = collectDeclarations(lines);
+    const inBase = (line) => line - 1 >= bounds.open && line - 1 <= close;
+    const base = new Set(declarations.filter((d) => inBase(d.line)).map((d) => d.name));
+    return declarations
+        .filter((d) => !inBase(d.line) && d.name.startsWith(tokenPrefix) && !base.has(d.name))
+        .map((d) => ({
+        check: 'token-lockstep',
+        file: tokensCssPath,
+        line: d.line,
+        token: d.name,
+        message: `${d.name} is declared in ${d.block} but not in the base :root block, so every other ` +
+            'theme resolves it to nothing. Declare the base value first (fireforge token add), ' +
+            'or drop the override.',
+    }));
+}
+/**
+ * `var(--<prefix>…)` references naming a token the tokens CSS never
+ * declares.
+ *
+ * @param file - Engine-relative path, for the findings
+ * @param css - The file's content
+ * @param tokenPrefix - Only references with this prefix are checked
+ * @param declared - {@link collectDeclaredTokenNames} of the tokens CSS
+ * @param exempt - `tokenAllowlist` and `runtimeVariables` names
+ */
+export function lintUndeclaredTokenReferences(file, css, tokenPrefix, declared, exempt) {
+    const lines = css.split('\n');
+    const local = collectDeclaredTokenNames(lines);
+    const findings = [];
+    const seen = new Set();
+    for (const [index, line] of maskCommentLines(lines).entries()) {
+        for (const match of line.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/g)) {
+            const name = match[1] ?? '';
+            if (!name.startsWith(tokenPrefix) || declared.has(name) || local.has(name))
+                continue;
+            if (exempt.has(name) || seen.has(name))
+                continue;
+            seen.add(name);
+            findings.push({
+                check: 'token-undeclared',
+                file,
+                line: index + 1,
+                token: name,
+                message: `var(${name}) names a token the tokens CSS does not declare, so it resolves to ` +
+                    'nothing. Add the token, fix the name, or list a runtime channel in furnace.json ' +
+                    'runtimeVariables.',
+            });
+        }
+    }
+    return findings;
+}

package/dist/src/core/tree-guard.js

@@ -51,6 +51,9 @@ export const TREE_COMMAND_VERDICTS = {
     lint: 'allowed',
     typecheck: 'allowed',
     verify: 'allowed',
+    // Its furnace-validate and token-coverage steps are commands a tree
+    // refuses. Run the allowed gates one by one in a tree.
+    check: 'refused',
     furnace: 'refused',
     // No nesting. `tree list` inside a tree is pointless but harmless, and
     // the subcommand check below allows only `list`.

package/dist/src/core/typecheck-shim.d.ts

@@ -24,7 +24,7 @@ export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
  * `declare var` redeclarations to the first declaration, the typed
  * consumer declaration wins over the loose fallback here.
  */
-export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harness shim (loose baseline) \u2500\u2500\ndeclare var TestUtils: any;\ndeclare var BrowserTestUtils: any;\ndeclare var SpecialPowers: any;\ndeclare var EventUtils: any;\ndeclare var SimpleTest: any;\ndeclare var Assert: any;\ndeclare var gTestPath: string;\ndeclare var content: any;\ndeclare function add_task(task: (...args: any[]) => any): any;\ndeclare function add_setup(task: (...args: any[]) => any): any;\ndeclare function ok(condition: any, message?: string): void;\ndeclare function is(actual: any, expected: any, message?: string): void;\ndeclare function isnot(actual: any, expected: any, message?: string): void;\ndeclare function todo(condition: any, message?: string): void;\ndeclare function todo_is(actual: any, expected: any, message?: string): void;\ndeclare function info(message: string): void;\ndeclare function registerCleanupFunction(callback: (...args: any[]) => any): void;\ndeclare function waitForExplicitFinish(): void;\ndeclare function finish(): void;\ndeclare function do_get_profile(): any;\ndeclare function run_test(): any;\n\n";
+export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harness shim (loose baseline) \u2500\u2500\ndeclare var TestUtils: any;\ndeclare var BrowserTestUtils: any;\ndeclare var SpecialPowers: any;\ndeclare var EventUtils: any;\ndeclare var SimpleTest: any;\ndeclare var Assert: any;\ndeclare var gTestPath: string;\ndeclare var content: any;\ndeclare function add_task(task: (...args: any[]) => any): any;\ndeclare function add_setup(task: (...args: any[]) => any): any;\ndeclare function ok(condition: any, message?: string): void;\ndeclare function is(actual: any, expected: any, message?: string): void;\ndeclare function isnot(actual: any, expected: any, message?: string): void;\ndeclare function todo(condition: any, message?: string): void;\ndeclare function todo_is(actual: any, expected: any, message?: string): void;\ndeclare function todo_isnot(actual: any, expected: any, message?: string): void;\ndeclare function info(message: string): void;\ndeclare function registerCleanupFunction(callback: (...args: any[]) => any): void;\ndeclare function waitForExplicitFinish(): void;\ndeclare function finish(): void;\ndeclare function do_get_profile(): any;\ndeclare function run_test(): any;\n\n";
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass
  * and the whole-project typecheck command. Each is a known false

package/dist/src/core/typecheck-shim.js

@@ -43,7 +43,9 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  * - `const lazy = {};` + `ChromeUtils.defineESModuleGetters(lazy, { ... })`
  *   populates `lazy` at runtime, so we declare it as `Record<string, any>`.
  * - `Services.obs`, `Services.prefs`, etc. are XPCOM service accessors.
- * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts.
+ * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts. `Cu` alone is
+ *   typed (`CuShim`, the members of `nsIXPCComponents_Utils`), so an
+ *   unknown `Cu.*` member is an error rather than a runtime TypeError.
  * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
  *   content scripts wired via `browser.js`.
  * - Dynamic `import("resource:-…")` / `import("chrome:-…")` under patch
@@ -72,7 +74,92 @@ interface ChromeUtilsShim {
   predictRemoteTypeForURI(uri: string | object | null, options?: object): string | null;
 }
 declare var ChromeUtils: ChromeUtilsShim;
-declare var Cu: any;
+// Components.utils (js/xpconnect/idl/xpccomponents.idl, nsIXPCComponents_Utils,
+// Firefox 153). Every member is listed with loose (any) jsval parameters and
+// results, so Xray-waived and cloned objects keep their expandos, but the
+// member set is closed: a call to a member Cu does not have (Cu.now() is
+// ChromeUtils.now()) is a typecheck error instead of a runtime TypeError.
+// Extensible via interface merging, same as ChromeUtilsShim.
+interface CuShim {
+  QueryInterface(iid: any): any;
+  printStderr(message: string): void;
+  reportError(error: any, stack?: any): void;
+  readonly Sandbox: { new (principal: any, options?: any): any; (principal: any, options?: any): any };
+  evalInSandbox(
+    source: string,
+    sandbox: any,
+    version?: any,
+    filename?: string,
+    lineNo?: number,
+    enforceFilenameRestrictions?: boolean
+  ): any;
+  getUAWidgetScope(principal: any): any;
+  getSandboxMetadata(sandbox: any): any;
+  setSandboxMetadata(sandbox: any, metadata: any): void;
+  setSandboxLocaleOverride(sandbox: any, locale: string): void;
+  setSandboxTimezoneOverride(sandbox: any, timezone: string): void;
+  isESModuleLoaded(resourceURI: string): boolean;
+  importGlobalProperties(propertyList: any): void;
+  getWeakReference(obj: any): { get(): any };
+  forceGC(): void;
+  forceCC(listener?: any): void;
+  createCCLogger(): any;
+  finishCC(): void;
+  ccSlice(budget: number): void;
+  getMaxCCSliceTimeSinceClear(): number;
+  clearMaxCCTime(): void;
+  forceShrinkingGC(): void;
+  schedulePreciseGC(callback: any): void;
+  schedulePreciseShrinkingGC(callback: any): void;
+  unlinkGhostWindows(): void;
+  intentionallyLeak(): void;
+  getJSTestingFunctions(): any;
+  getFunctionSourceLocation(func: any): any;
+  callFunctionWithAsyncStack(func: any, stack: any, asyncCause: string): any;
+  getGlobalForObject(obj: any): any;
+  isProxy(obj: any): boolean;
+  exportFunction(func: any, scope: any, options?: any): any;
+  createObjectIn(scope: any, options?: any): any;
+  makeObjectPropsNormal(obj: any): void;
+  isDeadWrapper(obj: any): boolean;
+  isRemoteProxy(val: any): boolean;
+  recomputeWrappers(obj?: any): void;
+  setWantXrays(scope: any): void;
+  dispatch(runnable: any, scope?: any): void;
+  readonly isInAutomation: boolean;
+  exitIfInAutomation(): void;
+  crashIfNotInAutomation(): void;
+  setGCZeal(zeal: number): void;
+  nukeSandbox(obj: any): void;
+  blockScriptForGlobal(global: any): void;
+  unblockScriptForGlobal(global: any): void;
+  isOpaqueWrapper(obj: any): boolean;
+  isXrayWrapper(obj: any): boolean;
+  waiveXrays(val: any): any;
+  unwaiveXrays(val: any): any;
+  getClassName(obj: any, unwrap: boolean): string;
+  getIncumbentGlobal(callback?: any): any;
+  getDebugName(obj: any): string;
+  getWatchdogTimestamp(category: string): number;
+  getJSEngineTelemetryValue(): any;
+  cloneInto(value: any, scope: any, options?: any): any;
+  getWebIDLCallerPrincipal(): any;
+  getObjectPrincipal(obj: any): any;
+  getRealmLocation(obj: any): string;
+  readUTF8File(file: any): string;
+  readUTF8URI(url: any): string;
+  createSpellChecker(): any;
+  createCommandLine(args: string[], workingDir: any, state: number): any;
+  createCommandParams(): any;
+  createLoadContext(): any;
+  createPrivateLoadContext(): any;
+  createPersistentProperties(): any;
+  createDocumentEncoder(contentType: string): any;
+  createHTMLCopyEncoder(): any;
+  readonly loadedESModules: string[];
+  getModuleImportStack(location: string): string;
+}
+declare var Cu: CuShim;
 declare var Ci: any;
 declare var Cc: any;
 declare var Cr: any;
@@ -159,6 +246,7 @@ declare function is(actual: any, expected: any, message?: string): void;
 declare function isnot(actual: any, expected: any, message?: string): void;
 declare function todo(condition: any, message?: string): void;
 declare function todo_is(actual: any, expected: any, message?: string): void;
+declare function todo_isnot(actual: any, expected: any, message?: string): void;
 declare function info(message: string): void;
 declare function registerCleanupFunction(callback: (...args: any[]) => any): void;
 declare function waitForExplicitFinish(): void;

package/dist/src/index.d.ts

@@ -22,10 +22,15 @@ export type { ApplyAllComponentsResult } from './core/furnace-apply.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
-export type { PatchSizeTierDecision } from './core/patch-lint.js';
-export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
+export type { PatchSizeThresholds, PatchSizeTierDecision } from './core/patch-lint.js';
+export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, isTestFile, resolvePatchSizeTier, } from './core/patch-lint.js';
+export type { CodeLineCount } from './core/patch-lint-code-lines.js';
+export { countCodeLines } from './core/patch-lint-code-lines.js';
+export type { ResolvedFileSizeTier } from './core/patch-lint-file-size.js';
+export { resolveFileSizeThresholds } from './core/patch-lint-file-size.js';
+export type { ResolvedPatchFilesTier } from './core/patch-lint-size-thresholds.js';
 export type { AddTokenOptions, AddTokenResult, TokenMode } from './core/token-manager.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';
-export type { ApplyResult, BuildConfig, ComponentType, CustomComponentConfig, DryRunAction, FireForgeConfig, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, ProjectLicense, StepError, ValidationIssue, WireConfig, } from './types/index.js';
+export type { ApplyResult, BuildConfig, ComponentType, CustomComponentConfig, DryRunAction, FireForgeConfig, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, PatchLintFileSizeThresholds, PatchLintFileSizeTier, ProjectLicense, StepError, ValidationIssue, WireConfig, } from './types/index.js';

package/dist/src/index.js

@@ -21,7 +21,9 @@ export { findForwardRegistrations } from './core/forward-registrations.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
-export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
+export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, isTestFile, resolvePatchSizeTier, } from './core/patch-lint.js';
+export { countCodeLines } from './core/patch-lint-code-lines.js';
+export { resolveFileSizeThresholds } from './core/patch-lint-file-size.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
-export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceLockWaitable, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceRenameOptions, FurnaceSyncOptions, FurnaceValidateOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchRetireOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { ImportSummary, LintIgnoreCeiling, LintIgnoreEntry, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchLintStagedDeclaration, PatchMetadata, PatchResult, PatchRetiredSlot, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
 export type { DoctorCheck, TokenCoverageFileEntry, TokenCoverageReport } from './project.js';

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

@@ -111,6 +111,8 @@ export interface SourceSetOptions {
 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 */
@@ -263,7 +265,9 @@ export interface ReExportOptions extends EngineLockWaitable {
     /**
      * Explicit engine-relative files to add while scanning. Unlike broad
      * `--scan`, this does not collect adjacent files from the same directory.
-     * Requires `--scan` and exactly one target patch.
+     * 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[];
     /**
@@ -343,11 +347,13 @@ export interface ReExportOptions extends EngineLockWaitable {
     noCache?: boolean;
     /**
      * Refuse (non-zero exit, patch not written) a re-export whose refreshed
-     * body would absorb engine lines not present in the old patch body.
+     * 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. Mutually
-     * exclusive with `--scan` and `--files`.
+     * 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;
     /**
@@ -370,7 +376,26 @@ export interface ReExportOptions extends EngineLockWaitable {
      * rather than hidden.
      */
     expectUnmanaged?: string[];
-    /** Explicitly retire named absent patch-created files in a scan-less export. */
+    /**
+     * 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[];
 }
 /**
@@ -396,6 +421,13 @@ export interface PatchLintIgnoreOptions extends Confirmable, DryRunnable, PatchL
     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`. */
+    reason?: string;
 }
 /**
  * Options for the `fireforge patch staged-dependency` subcommand. Modes are
@@ -430,6 +462,11 @@ export interface PatchStagedDependencyOptions extends Confirmable, DryRunnable,
     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.
@@ -510,6 +547,16 @@ export interface RunOptions {
      * 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,
@@ -520,7 +567,9 @@ export interface RunOptions {
      *  - `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).
+     *    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`.
@@ -559,6 +608,10 @@ export interface TestOptions extends EngineLockWaitable {
     waitBrowser?: number | boolean;
     /** Queue behind the mochitest/Marionette port holder. */
     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 */
@@ -580,13 +633,11 @@ export interface TestOptions extends EngineLockWaitable {
      */
     buildOnly?: boolean;
     /**
-     * Union the paths this build packages onto the recorded coverage claim
-     * instead of REPLACING it, so successive scoped builds accumulate and an
-     * earlier slice's build-less runs stay covered. Valid only with
-     * `--build`/`--build-only` and explicit paths. Refused fail-closed unless
-     * the build anchor is unchanged: same engine HEAD, same `engine/mozconfig`,
-     * and every previously fingerprinted packageable file byte-identical. See
-     * `src/core/coverage-extend.ts`.
+     * 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;
     /**
@@ -598,6 +649,12 @@ export interface TestOptions extends EngineLockWaitable {
      * that could not arm the refusal. Valid only with `--build`/`--build-only`.
      */
     refuseUnexportedDrift?: boolean;
+    /**
+     * `false` under `--no-furnace-apply`: the pre-test build skips the Furnace
+     * apply and packages engine/ as it stands. Valid only with
+     * `--build`/`--build-only`.
+     */
+    furnaceApply?: boolean;
     /** Forward mach's pathless auto-selection mode. Valid only with no explicit paths. */
     auto?: boolean;
     /**
@@ -691,6 +748,26 @@ export interface TestOptions extends EngineLockWaitable {
      * `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;
 }
 /**
  * Options for the furnace apply command.
@@ -707,10 +784,24 @@ export interface FurnaceApplyOptions extends DryRunnable {
      */
     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 {
+export interface FurnacePreviewOptions extends FurnaceLockWaitable {
     /** Force reinstall Storybook dependencies */
     install?: boolean;
 }
@@ -732,7 +823,7 @@ export interface FurnaceDeployOptions extends DryRunnable {
 /**
  * Options for the furnace refresh command.
  */
-export interface FurnaceRefreshOptions extends DryRunnable {
+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) */
@@ -740,6 +831,11 @@ export interface FurnaceRefreshOptions extends DryRunnable {
     /** 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.
  */
@@ -759,25 +855,30 @@ export interface FurnaceSyncOptions extends DryRunnable {
 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 {
+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. `--yes` is the only flag it takes,
- * so the type is the confirmation mixin under a command-specific name.
+ * Options for the furnace remove command: the confirmation mixin plus the
+ * furnace lock budget.
  */
-export type FurnaceRemoveOptions = Confirmable;
+export interface FurnaceRemoveOptions extends Confirmable, FurnaceLockWaitable {
+}
 /**
  * Options for the furnace create command.
  */
-export interface FurnaceCreateOptions {
+export interface FurnaceCreateOptions extends FurnaceLockWaitable {
     /** Component description */
     description?: string;
     /**
@@ -884,6 +985,14 @@ export interface PatchDeleteOptions extends Confirmable, DryRunnable, PatchLockW
     /** Bypass the hard refusal when later patches depend on the target. */
     forceUnsafe?: 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 rename` subcommand. Updates the patch's
  * filename, manifest `name`, and (optionally) `description` atomically
@@ -991,9 +1100,27 @@ export interface StatusOptions {
     /**
      * Comma-separated classification list replacing the default `--check`
      * policy. Implies `--check`. Unknown values refuse, naming the valid
-     * classification set.
+     * 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.