@hominis/fireforge 0.18.10 → 0.18.11

package/README.md

@@ -24,7 +24,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 
 - **Design token management** Track CSS custom property coverage across your modified files.
 
-- **Quality checks** `fireforge lint` catches fork-specific issues (raw colours, missing licence headers, relative imports, large patches, cross-patch ordering problems) before you export. `fireforge verify` runs a read-only integrity check over the whole patch queue. `fireforge doctor` diagnoses project health including Furnace component validation.
+- **Quality checks** `fireforge lint` catches fork-specific issues (raw colours, missing licence headers, relative imports, large patches, cross-patch ordering problems) before you export. `fireforge typecheck` runs CI-grade JS type checking against project-supplied jsconfig.json files (web components, chrome scripts) — separate from `lint`'s patch-hygiene checkJs pass. `fireforge verify` runs a read-only integrity check over the whole patch queue. `fireforge doctor` diagnoses project health including Furnace component validation.
 
 - **Built and validated against real Firefox code** Developed by editing a real Firefox ESR codebase, learning from existing patch tools, observing the breakages and edge cases that surfaced and turning those findings into a realistic test suite. In-repo tests are thus grounded in actual development scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Github Actions will be added soonishlyTM.
 
@@ -57,7 +57,7 @@ Your project now has `fireforge.json`, an `engine/` directory with Firefox sourc
 
 #### Known upstream build issues
 
-- **macOS 15 (Darwin 25+) — `gecko-profiler` bindgen error `cannot find type _CharT in this scope`.** An Apple toolchain update changed `std::__CharT_pointer` to `_CharT_pointer` in the libc++ headers Firefox's bindgen walks, so `toolkit/library/rust/target-objects` fails during `mach build` even on a clean `fireforge bootstrap`. This is an upstream Firefox issue, not a FireForge bug. Two workarounds: pin Xcode's command line tools to a pre-September-2025 release via `xcode-select --install` / [Apple developer downloads](https://developer.apple.com/download/all/), or apply a one-line bindgen-basic-string-workaround patch (Hominis ships one in its patch queue). If you interrupt the resulting `fireforge build` and re-run `fireforge doctor`, the download/engine state is unaffected — the failure is isolated to the Rust compile phase.
+- **macOS 15 (Darwin 25+) — `gecko-profiler` bindgen error `cannot find type _CharT in this scope`.** An Apple toolchain update changed `std::__CharT_pointer` to `_CharT_pointer` in the libc++ headers Firefox's bindgen walks, so `toolkit/library/rust/target-objects` fails during `mach build` even on a clean `fireforge bootstrap`. This is an upstream Firefox issue, not a FireForge bug. Two workarounds: pin Xcode's command line tools to a pre-September-2025 release via `xcode-select --install` / [Apple developer downloads](https://developer.apple.com/download/all/), or apply a one-line bindgen-basic-string-workaround patch (a downstream consumer may ship one in its patch queue). If you interrupt the resulting `fireforge build` and re-run `fireforge doctor`, the download/engine state is unaffected — the failure is isolated to the Rust compile phase.
 
 ### Workflow Overview
 
@@ -255,7 +255,20 @@ By default, a standalone `fireforge lint` (no arguments) lints the **aggregate**
 
 **JSDoc validation** uses AST-based analysis (Acorn) to validate exported APIs in patch-owned `.sys.mjs` files. A file is "patch-owned" if it was newly created by the current diff or by an existing patch in the queue. Functions must document every `@param` (names must match) and include `@returns` when the function returns a value. Exported constants and classes require a JSDoc block.
 
-**Optional `checkJs` pass.** Enable a TypeScript-esque bastardization of type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these. This pass solely focuses on type errors within the patch-owned code itself (mismatched JSDoc types, wrong argument counts, unreachable code, etc.).
+**Optional `checkJs` pass.** Enable a TypeScript-esque bastardization of type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these. This pass solely focuses on type errors within the patch-owned code itself (mismatched JSDoc types, wrong argument counts, unreachable code, etc.). Projects that need to extend the built-in shim (e.g. for `MozLitElement`, `MozXULElement`, or fork-specific component bases) can point at an additional `.d.ts` via `"patchLint": { "checkJsExtraShim": "tools/types/<fork>-globals.d.ts" }`; the file is concatenated to the built-in shim — augment, don't redeclare.
+
+**Whole-project type checking — `fireforge typecheck`.** `patchLint.checkJs` is patch-hygiene: scoped to patch-owned `.sys.mjs`, suppresses module-resolution noise, and runs every time `fireforge lint` runs. `fireforge typecheck` is the CI-grade complement: it runs whole projects you point at via `typecheck.projects` in `fireforge.json`, honours each jsconfig's strictness/include/exclude/`paths`, and is intended as a CI gate. The two are complementary; the recommended setup is `fireforge lint` on every patch export and `fireforge typecheck` on CI for the project-level baseline.
+
+```jsonc
+{
+  "typecheck": {
+    "projects": ["components/custom/jsconfig.json", "engine/browser/base/content/jsconfig.json"],
+    "extraShim": "tools/types/<fork>-globals.d.ts",
+  },
+}
+```
+
+The command resolves each `projects` entry through TypeScript's own config parser (`readConfigFile` + `parseJsonConfigFileContent`), so `paths` mappings, `include`/`exclude` globs, and `lib` settings all behave the same as `tsc --noEmit -p <path>`. FireForge forces `noEmit: true` and defaults `allowJs`/`checkJs` to `true` only when the user has not set them — explicit `"checkJs": false` in a jsconfig is honoured (one notice, no diagnostics) so the IDE-noise opt-out remains an opt-out. The same `FIREFOX_GLOBALS_SHIM` and the same eight suppressed diagnostic codes (2304 / 2305 / 2306 / 2307 / 2552 / 2580 / 2792 / 7016 — module-resolution + global-name noise) apply, so a file that lints clean cannot fail typecheck for an inferable-only-from-source reason. Pass `--project <path>` for a one-off run against a single jsconfig (replaces the configured list, preserves `extraShim`). Exits non-zero on any error-severity diagnostic; warnings print but do not fail. TypeScript stays a dev-dependency — install it (`npm i -D typescript`) before running. The command does not honour `--since` or any patch-diff filter: it is whole-project by design.
 
 **Optional `jsdocClassMethods` enforcement.** Set `"patchLint": { "jsdocClassMethods": "warning" | "error" }` in `fireforge.json` to extend JSDoc validation to class-method exports inside patch-owned `.sys.mjs` files. Every public method (instance and static), parameter-bearing constructor, getter, and setter must carry a leading JSDoc block; `@param` names must match the parameter list, and `@returns` is required when a method returns a value (getters and setters are exempt from `@returns`). Methods whose name starts with `_` or `#`, methods carrying `@private` or `@internal` in their JSDoc, and zero-parameter constructors are exempt. Defaults to `"off"`, so upgrading is a no-op until the knob is set.
 
@@ -667,10 +680,10 @@ The summary block reports two allowlist counters so operators can tell whether a
 A feature with multiple components (e.g. an eight-component dock) typically wants one shared `.ftl` per feature rather than eight per-component stubs. `furnace create <tag> --localized --shared-ftl <chrome-uri>` participates in an existing feature-scoped bundle:
 
 ```bash
-fireforge furnace create hominis-dock-button --localized --shared-ftl browser/hominis-dock.ftl
+fireforge furnace create mybrowser-dock-button --localized --shared-ftl browser/mybrowser-dock.ftl
 ```
 
-The generated `.mjs` calls `insertFTLIfNeeded("browser/hominis-dock.ftl")` instead of the per-component path. No `<tag>.ftl` stub is written. The `furnace.json` `custom` entry carries a new `sharedFtl` field so apply, validate, and remove all honour the participation:
+The generated `.mjs` calls `insertFTLIfNeeded("browser/mybrowser-dock.ftl")` instead of the per-component path. No `<tag>.ftl` stub is written. The `furnace.json` `custom` entry carries a new `sharedFtl` field so apply, validate, and remove all honour the participation:
 
 - `furnace apply` does not copy a per-component `.ftl` into the FTL tree nor add a locale `jar.mn` entry — the shared file is registered by whoever owns the feature bundle.
 - `furnace remove` early-returns from the locale `jar.mn` cleanup, so dropping our component's reference does not orphan the bundle for every other participant.
@@ -685,9 +698,9 @@ The generated `.mjs` calls `insertFTLIfNeeded("browser/hominis-dock.ftl")` inste
 When the wrapped inner element is hand-authored or is a non-stock `moz-*` widget that does not appear in `composes`, the explicit `keyboardCovered: true` field on the component's `furnace.json` entry forces the same skip:
 
 ```json
-"hominis-dock-button": {
+"mybrowser-dock-button": {
   "description": "Dock button wrapper",
-  "targetPath": "components/custom/hominis-dock-button",
+  "targetPath": "components/custom/mybrowser-dock-button",
   "register": true,
   "localized": false,
   "composes": ["moz-button"],

package/dist/src/commands/doctor.js

@@ -337,7 +337,7 @@ const DOCTOR_CHECKS = [
                     for (const filename of repaired.recoveredFilenames) {
                         // 2026-04-24 eval Finding 6: the repair path used to tell the
                         // operator to hand-edit patches.json, which contradicts the
-                        // README + Hominis docs that treat the manifest as
+                        // README + downstream docs that treat the manifest as
                         // FireForge-owned. Point at the existing `re-export` /
                         // `export` workflow instead so the fix stays inside the tool:
                         // re-exporting the same files with an explicit `--description`

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

@@ -81,7 +81,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         return value;
     })
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
-        .option('--shared-ftl <path>', 'Participate in an existing feature-scoped .ftl at this path (e.g. "browser/hominis-dock.ftl"); skips the per-component .ftl scaffold (implies --localized)')
+        .option('--shared-ftl <path>', 'Participate in an existing feature-scoped .ftl at this path (e.g. "browser/mybrowser-dock.ftl"); skips the per-component .ftl scaffold (implies --localized)')
         .option('--dry-run', 'Show the planned file set and furnace.json changes without writing')
         .option('--allow-prefix-mismatch', 'Create the component even when its name does not start with the configured `componentPrefix` in furnace.json. Without this flag the command refuses to write anything on a prefix mismatch.')
         .action(withErrorHandling(async (name, options) => {

package/dist/src/commands/manifest.js

@@ -21,6 +21,7 @@ import { registerSetup } from './setup.js';
 import { registerStatus } from './status.js';
 import { registerTest } from './test.js';
 import { registerToken } from './token.js';
+import { registerTypecheck } from './typecheck.js';
 import { registerVerify } from './verify.js';
 import { registerWatch } from './watch.js';
 import { registerWire } from './wire.js';
@@ -53,6 +54,7 @@ export const COMMAND_MANIFEST = [
     { name: 'wire', group: 'workflow', register: registerWire },
     { name: 'token', group: 'components', register: registerToken },
     { name: 'lint', group: 'diagnostics', register: registerLint },
+    { name: 'typecheck', group: 'diagnostics', register: registerTypecheck },
     { name: 'verify', group: 'diagnostics', register: registerVerify },
     { name: 'furnace', group: 'components', register: registerFurnace },
 ];

package/dist/src/commands/package.js

@@ -57,7 +57,7 @@ export async function packageCommand(projectRoot, options) {
         // only, so a targeted hint translator could not see the failure text.
         // The captured stderr is fed through `explainMachError` below so
         // recognised failure modes (notably the `packager.py` NoneType trip
-        // the evaluator hit on `hominis/`) get an actionable hint prepended
+        // the evaluator hit on `mybrowser/`) get an actionable hint prepended
         // to the raw mach output the operator already saw.
         result = await machPackageCapture(paths.engine);
     }

package/dist/src/commands/test.js

@@ -41,7 +41,7 @@ function hasStaleBuildArtifactsSignal(output) {
     // that are always a stale-artifact symptom. The earlier pattern also
     // matched `resource:///modules/distribution.sys.mjs`, which surfaced on
     // real packaging / module-resolution failures too (e.g. a fork's
-    // `HominisStore.sys.mjs` missing from the installed app dir after a
+    // `MyBrowserStore.sys.mjs` missing from the installed app dir after a
     // successful build). That false-positive pushed operators toward
     // "rebuild" advice for what was actually a module-registration issue.
     return (/chrome:\/\/branding\/locale\/brand\.properties/i.test(output) ||
@@ -49,8 +49,8 @@ function hasStaleBuildArtifactsSignal(output) {
 }
 /**
  * Fork-module-not-registered signal. 2026-04-21 eval Finding #14:
- * a hominis test failed with `Failed to load resource:///modules/hominis/
- * HominisStore.sys.mjs`. The branding pattern happened to also match
+ * a fork's test failed with `Failed to load resource:///modules/mybrowser/
+ * MyBrowserStore.sys.mjs`. The branding pattern happened to also match
  * because the test harness printed a branding warning during its
  * teardown, and the stale-build branch won by precedence — telling the
  * operator to rebuild when the real fix is to register the module in
@@ -126,8 +126,8 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
         throw new GeneralError(buildUnknownTestMessage(normalizedPaths));
     }
     // Fork-owned module load failures must beat the branding stale-build
-    // branch: 2026-04-21 eval (Finding #14) saw a hominis test fail with
-    // `Failed to load resource:///modules/hominis/HominisStore.sys.mjs`
+    // branch: 2026-04-21 eval (Finding #14) saw a fork's test fail with
+    // `Failed to load resource:///modules/mybrowser/MyBrowserStore.sys.mjs`
     // while the harness teardown printed a branding warning that the old
     // stale-build pattern matched, so the operator was told to rebuild
     // when the real fix is to register the missing module.
@@ -140,7 +140,7 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     // But the stale-build check is now narrower — it no longer matches
     // `resource:///modules/distribution.sys.mjs` alone, which was producing
     // false-positive rebuild advice on fork-custom module-load failures
-    // (the eval saw this for `HominisStore.sys.mjs`). Cases that once
+    // (the eval saw this for `MyBrowserStore.sys.mjs`). Cases that once
     // landed on `distribution.sys.mjs` fall through to xpcshell-appdir,
     // which is the more useful diagnosis in practice for `Failed to load
     // resource:///modules/…`.
@@ -253,13 +253,13 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         : undefined;
     const effectivePort = options.marionettePort ?? forwardedPort;
     // Stale-browser probe: an interrupted earlier test run can leave a
-    // Firefox/ForgeFresh/Hominis instance listening on the Marionette
+    // Firefox/ForgeFresh/fork instance listening on the Marionette
     // control port, which breaks the next mach test launch with a
     // bind error that points nowhere near the real cause. Raise a
     // targeted refusal up front instead of letting mach surface the
     // generic bind failure. 2026-04-21 eval (Finding #20): a stale
     // `-marionette` process from `fresh/` poisoned a later test run in
-    // the sibling `hominis/` workspace.
+    // the sibling `mybrowser/` workspace.
     await assertMarionettePortAvailable(effectivePort, { binaryName: projectConfig.binaryName });
     // `--doctor` runs a short marionette handshake probe. When test paths are
     // supplied the probe gates the mach test invocation (a FAIL bails out). When

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

@@ -0,0 +1,52 @@
+/**
+ * `fireforge typecheck` — whole-project TypeScript type checking
+ * driven by user-supplied jsconfig.json paths.
+ *
+ * Distinct from `patchLint.checkJs`: that pass is patch-hygiene
+ * (scoped to patch-owned `.sys.mjs`, run automatically by
+ * `fireforge lint`); this command is CI-grade — it runs whole
+ * projects with the user's own compiler options and is intended as
+ * a CI gate. The two share their Firefox-globals shim and the same
+ * suppressed-diagnostic set so a file that lints clean cannot fail
+ * typecheck for a reason the operator could not have inferred from
+ * the docs.
+ *
+ * Exits non-zero on any error-severity diagnostic. Warnings print
+ * but do not fail. Designed for CI use.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+import type { TypecheckConfig } from '../types/config.js';
+import type { TypecheckProjectResult } from '../types/typecheck.js';
+/** Command-line options Commander forwards from `fireforge typecheck`. */
+export interface TypecheckCommandOptions {
+    /**
+     * Override `typecheck.projects` with a single jsconfig.json path
+     * for one-off verification. Replaces (does not augment) the config
+     * — useful to re-run a single project after fixing one of its
+     * issues without waiting for the full set.
+     */
+    project?: string;
+}
+/**
+ * Resolves the project list to type-check. `--project` wins over
+ * config; if neither is set, throws a clear error pointing at both
+ * paths to a fix (add the config field or pass --project).
+ */
+export declare function resolveTypecheckProjects(configTypecheck: TypecheckConfig | undefined, override: string | undefined): TypecheckConfig;
+/**
+ * Top-level entry point invoked by the registered Commander action.
+ * Loads config, resolves projects, runs typecheck, prints the result,
+ * and throws `GeneralError` to set a non-zero exit on errors.
+ */
+export declare function typecheckCommand(projectRoot: string, options: TypecheckCommandOptions): Promise<void>;
+/**
+ * Prints all issues, computes the per-project + total counts, and
+ * throws on errors. Extracted so it can be exercised directly by
+ * the CLI test without spawning a child process.
+ */
+export declare function reportResults(projectRoot: string, results: ReadonlyArray<TypecheckProjectResult>): void;
+/**
+ * Registers the `typecheck` command on the CLI program.
+ */
+export declare function registerTypecheck(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/typecheck.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge typecheck` — whole-project TypeScript type checking
+ * driven by user-supplied jsconfig.json paths.
+ *
+ * Distinct from `patchLint.checkJs`: that pass is patch-hygiene
+ * (scoped to patch-owned `.sys.mjs`, run automatically by
+ * `fireforge lint`); this command is CI-grade — it runs whole
+ * projects with the user's own compiler options and is intended as
+ * a CI gate. The two share their Firefox-globals shim and the same
+ * suppressed-diagnostic set so a file that lints clean cannot fail
+ * typecheck for a reason the operator could not have inferred from
+ * the docs.
+ *
+ * Exits non-zero on any error-severity diagnostic. Warnings print
+ * but do not fail. Designed for CI use.
+ */
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { relativeForDisplay, runTypecheck } from '../core/typecheck.js';
+import { GeneralError } from '../errors/base.js';
+import { info, intro, outro, success, warn } from '../utils/logger.js';
+/**
+ * Resolves the project list to type-check. `--project` wins over
+ * config; if neither is set, throws a clear error pointing at both
+ * paths to a fix (add the config field or pass --project).
+ */
+export function resolveTypecheckProjects(configTypecheck, override) {
+    if (override !== undefined) {
+        if (override.trim() === '') {
+            throw new GeneralError('--project requires a non-empty path');
+        }
+        return {
+            projects: [override],
+            ...(configTypecheck?.extraShim !== undefined ? { extraShim: configTypecheck.extraShim } : {}),
+        };
+    }
+    if (!configTypecheck) {
+        throw new GeneralError('No typecheck configuration found. Add a "typecheck": { "projects": [...] } block to ' +
+            'fireforge.json, or pass --project <path> for a one-off run.');
+    }
+    return configTypecheck;
+}
+/**
+ * Formats a single issue for CLI display. `[<project>] <file>:<line>:<col> TS<code> <message>`
+ * matches the format `tsc -p` produces with `--pretty false`, so output
+ * piped into editor jump-lists works without per-tool tweaks.
+ */
+function formatIssue(projectRoot, issue) {
+    const file = relativeForDisplay(projectRoot, issue.file);
+    const codeLabel = issue.code > 0 ? ` TS${String(issue.code)}` : '';
+    return `[${issue.project}] ${file}:${String(issue.line)}:${String(issue.column)}${codeLabel} ${issue.message}`;
+}
+/**
+ * Top-level entry point invoked by the registered Commander action.
+ * Loads config, resolves projects, runs typecheck, prints the result,
+ * and throws `GeneralError` to set a non-zero exit on errors.
+ */
+export async function typecheckCommand(projectRoot, options) {
+    intro('FireForge typecheck');
+    // Validate project is initialised. `loadConfig` throws on missing
+    // fireforge.json — withErrorHandling at the CLI layer renders the
+    // resulting `ConfigNotFoundError` cleanly, so we don't need to
+    // re-wrap.
+    getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    const cfg = resolveTypecheckProjects(config.typecheck, options.project);
+    info(`Running typecheck across ${String(cfg.projects.length)} project(s): ${cfg.projects.join(', ')}`);
+    const results = await runTypecheck(projectRoot, cfg);
+    reportResults(projectRoot, results);
+}
+/**
+ * Prints all issues, computes the per-project + total counts, and
+ * throws on errors. Extracted so it can be exercised directly by
+ * the CLI test without spawning a child process.
+ */
+export function reportResults(projectRoot, results) {
+    let totalErrors = 0;
+    let totalWarnings = 0;
+    for (const result of results) {
+        const errors = result.issues.filter((i) => i.category === 'error');
+        const warnings = result.issues.filter((i) => i.category === 'warning');
+        totalErrors += errors.length;
+        totalWarnings += warnings.length;
+        for (const issue of warnings)
+            warn(formatIssue(projectRoot, issue));
+        for (const issue of errors)
+            warn(formatIssue(projectRoot, issue));
+    }
+    const summary = `Typecheck: ${String(totalErrors)} error(s), ${String(totalWarnings)} warning(s) across ${String(results.length)} project(s)`;
+    if (totalErrors === 0) {
+        success(summary);
+        outro(totalWarnings > 0 ? 'Typecheck passed with warnings' : 'Typecheck passed');
+        return;
+    }
+    info(summary);
+    outro('Typecheck failed');
+    throw new GeneralError(`Typecheck found ${String(totalErrors)} error(s) across ${String(results.length)} project(s).`);
+}
+/**
+ * Registers the `typecheck` command on the CLI program.
+ */
+export function registerTypecheck(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('typecheck')
+        .description('Run TypeScript type checking against project-owned jsconfig.json files (CI-grade, whole-project)')
+        .option('--project <path>', 'Override typecheck.projects with a single jsconfig.json path (one-off run)')
+        .action(withErrorHandling(async (options) => {
+        const opts = {};
+        if (options.project !== undefined) {
+            opts.project = options.project;
+        }
+        await typecheckCommand(getProjectRoot(), opts);
+    }));
+}
+//# sourceMappingURL=typecheck.js.map

package/dist/src/core/config-paths.d.ts

@@ -17,9 +17,9 @@ export declare const CONFIGS_DIR = "configs";
 /** Name of the source directory */
 export declare const SRC_DIR = "src";
 /** Supported top-level fireforge.json keys backed by the current schema. */
-export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire", "patchLint", "markerComment"];
+export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire", "patchLint", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

package/dist/src/core/config-paths.js

@@ -28,6 +28,7 @@ export const SUPPORTED_CONFIG_ROOT_KEYS = [
     'license',
     'wire',
     'patchLint',
+    'typecheck',
     'markerComment',
 ];
 /** Supported config paths that can be read or set without --force. */
@@ -46,10 +47,14 @@ export const SUPPORTED_CONFIG_PATHS = [
     'wire.subscriptDir',
     'patchLint',
     'patchLint.checkJs',
+    'patchLint.checkJsExtraShim',
     'patchLint.rawColorAllowlist',
     'patchLint.jsdocClassMethods',
     'patchLint.testAssertionFloor',
     'patchLint.chromeScriptJsDoc',
+    'typecheck',
+    'typecheck.projects',
+    'typecheck.extraShim',
     'markerComment',
 ];
 /**

package/dist/src/core/config-validate.js

@@ -131,6 +131,11 @@ export function validateConfig(data) {
     if (patchLintRec) {
         config.patchLint = parsePatchLintBlock(patchLintRec);
     }
+    // Typecheck (top-level, distinct from patchLint — see TypecheckConfig docs).
+    const typecheckRec = optionalConfigObject(rec, 'typecheck');
+    if (typecheckRec) {
+        config.typecheck = parseTypecheckBlock(typecheckRec);
+    }
     // Warn on unknown root keys
     const knownRootKeys = new Set(SUPPORTED_CONFIG_ROOT_KEYS);
     for (const key of rec.keys()) {
@@ -213,6 +218,10 @@ function parsePatchLintBlock(rec) {
         }
         out.checkJs = checkJs;
     }
+    const checkJsExtraShim = rec.raw('checkJsExtraShim');
+    if (checkJsExtraShim !== undefined) {
+        out.checkJsExtraShim = parseShimPath(checkJsExtraShim, 'patchLint.checkJsExtraShim');
+    }
     const rawColorAllowlist = rec.raw('rawColorAllowlist');
     if (rawColorAllowlist !== undefined) {
         if (!Array.isArray(rawColorAllowlist) ||
@@ -235,4 +244,59 @@ function parsePatchLintBlock(rec) {
     }
     return out;
 }
+/**
+ * Validates a path field that should point at a project-relative `.d.ts`
+ * file. Shared between `patchLint.checkJsExtraShim` and
+ * `typecheck.extraShim` so both fields reject the same absolute-path /
+ * traversal / empty-string inputs with consistent error messages. The
+ * file's existence is intentionally not checked here — that lives at
+ * the engine layer where a missing file produces a typed runtime error
+ * pointing at the actual command, rather than blocking config reads
+ * for unrelated commands.
+ */
+function parseShimPath(raw, label) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new ConfigError(`Config field "${label}" must be a non-empty string`);
+    }
+    if (!isContainedRelativePath(raw)) {
+        throw new ConfigError(`Config field "${label}" must be a project-relative path`);
+    }
+    return raw;
+}
+/**
+ * Validates the optional top-level `typecheck` block. Empty `projects`
+ * is rejected because a silent no-op for `fireforge typecheck` is a
+ * footgun — operators set the block expecting it to do something. Each
+ * project path must be a contained relative path so `--project` / CLI
+ * scripts can't escape the project root.
+ */
+function parseTypecheckBlock(rec) {
+    const projectsRaw = rec.raw('projects');
+    if (projectsRaw === undefined) {
+        throw new ConfigError('Config field "typecheck.projects" is required when "typecheck" is set');
+    }
+    if (!Array.isArray(projectsRaw)) {
+        throw new ConfigError('Config field "typecheck.projects" must be an array of strings');
+    }
+    if (projectsRaw.length === 0) {
+        throw new ConfigError('Config field "typecheck.projects" must not be empty');
+    }
+    const projects = [];
+    for (let i = 0; i < projectsRaw.length; i++) {
+        const entry = projectsRaw[i];
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            throw new ConfigError(`Config field "typecheck.projects[${String(i)}]" must be a non-empty string`);
+        }
+        if (!isContainedRelativePath(entry)) {
+            throw new ConfigError(`Config field "typecheck.projects[${String(i)}]" must be a project-relative path`);
+        }
+        projects.push(entry);
+    }
+    const out = { projects };
+    const extraShim = rec.raw('extraShim');
+    if (extraShim !== undefined) {
+        out.extraShim = parseShimPath(extraShim, 'typecheck.extraShim');
+    }
+    return out;
+}
 //# sourceMappingURL=config-validate.js.map

package/dist/src/core/mach-build-artifacts.d.ts

@@ -50,8 +50,8 @@ export interface RunnableBundleCheck {
  *
  * Platform layout:
  * - macOS: `<objDir>/dist/*.app/Contents/MacOS/<binaryName>` (the `.app`
- *   display casing can differ from `binaryName` — e.g. `Hominis.app` for
- *   binary `hominis`, so we enumerate the `*.app` bundles rather than
+ *   display casing can differ from `binaryName` — e.g. `MyBrowser.app` for
+ *   binary `mybrowser`, so we enumerate the `*.app` bundles rather than
  *   compute the name.
  * - Linux: `<objDir>/dist/bin/<binaryName>`.
  * - Windows: `<objDir>/dist/bin/<binaryName>.exe`.

package/dist/src/core/mach-build-artifacts.js

@@ -108,8 +108,8 @@ export async function hasBuildArtifacts(engineDir) {
  *
  * Platform layout:
  * - macOS: `<objDir>/dist/*.app/Contents/MacOS/<binaryName>` (the `.app`
- *   display casing can differ from `binaryName` — e.g. `Hominis.app` for
- *   binary `hominis`, so we enumerate the `*.app` bundles rather than
+ *   display casing can differ from `binaryName` — e.g. `MyBrowser.app` for
+ *   binary `mybrowser`, so we enumerate the `*.app` bundles rather than
  *   compute the name.
  * - Linux: `<objDir>/dist/bin/<binaryName>`.
  * - Windows: `<objDir>/dist/bin/<binaryName>.exe`.

package/dist/src/core/mach-error-hints.js

@@ -40,19 +40,18 @@ export const MACH_ERROR_HINTS = [
         // inside gecko-profiler's generated `bindings.rs`, but `_CharT` is
         // not in scope where the alias lands — so the Rust compile fails
         // with "cannot find type `_CharT`". The symptom is obscure and the
-        // fix is external: Hominis ships
-        // `990-infra-bindgen-basic-string-workaround.patch` in its patch
-        // queue, which strips the offending alias line post-generation.
-        // This hint surfaces the workaround pointer alongside the raw
-        // bindgen output so operators don't have to reverse-engineer the
-        // failure.
+        // fix is external: a downstream consumer's patch queue may ship
+        // `990-infra-bindgen-basic-string-workaround.patch`, which strips
+        // the offending alias line post-generation. This hint surfaces the
+        // workaround pointer alongside the raw bindgen output so operators
+        // don't have to reverse-engineer the failure.
         pattern: /cannot find type `_CharT` in this scope[\s\S]*?gecko-profiler-|gecko-profiler-[\s\S]*?cannot find type `_CharT` in this scope/,
         hint: 'The Rust compile failed on a bindgen-generated `basic_string___self_view` alias in ' +
             'gecko-profiler/bindings.rs. This is an upstream bindgen output bug against some ' +
             'macOS libc++ SDK versions and needs a post-generation patch to strip the alias. ' +
             'The known-working workaround is the `990-infra-bindgen-basic-string-workaround.patch` ' +
-            "Hominis ships in its patch queue — import the equivalent into your fork's patches/, " +
-            'then re-run "fireforge import" + "fireforge build". If you do not use Hominis\' queue, ' +
+            "shipped by some downstream patch queues — import the equivalent into your fork's patches/, " +
+            'then re-run "fireforge import" + "fireforge build". If your fork does not carry such a patch, ' +
             'apply the following post-process to the generated file before the Rust compile: ' +
             'remove any `pub type basic_string___self_view = …<_CharT>;` line from ' +
             '`<objdir>/release/build/gecko-profiler-*/out/gecko/bindings.rs`.',

package/dist/src/core/marionette-port.js

@@ -3,7 +3,7 @@
  * Marionette port probe.
  *
  * Gecko's Marionette control channel binds `127.0.0.1:2828` when a
- * Firefox / ForgeFresh / Hominis instance is launched with
+ * Firefox / ForgeFresh / fork instance is launched with
  * `-marionette`. The `fireforge test` harness spawns the browser with
  * that flag, so any test run needs the port to be free at start.
  *
@@ -42,7 +42,7 @@ const BROWSER_BASENAMES = new Set([
     'firefox-bin',
     'firefox-esr',
     'forgefresh',
-    'hominis',
+    'mybrowser',
     'thunderbird',
 ]);
 /**
@@ -53,8 +53,8 @@ const BROWSER_BASENAMES = new Set([
  * warning.
  *
  * Includes the operator-provided `binaryName` from `fireforge.json`
- * so a fork that ships under a custom name (e.g. Hominis'
- * `hominis-nightly`) is still recognised as a browser.
+ * so a fork that ships under a custom name (e.g.
+ * `mybrowser-nightly`) is still recognised as a browser.
  */
 function isBrowserHolder(holder, binaryName) {
     if (/\s-marionette(?:\s|$)/.test(holder.commandLine)) {

package/dist/src/core/patch-lint-checkjs.d.ts

@@ -8,7 +8,10 @@
  * how to fix it.
  *
  * Separated from `patch-lint.ts` to keep both files within the
- * project's per-file line budget.
+ * project's per-file line budget. The shim itself and the suppressed
+ * diagnostic code list now live in `typecheck-shim.ts` and are shared
+ * with the whole-project `fireforge typecheck` command — keeping a
+ * single source of truth for the Firefox-globals coverage.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 /**
@@ -16,6 +19,15 @@ import type { PatchLintIssue } from '../types/commands/index.js';
  *
  * @param repoDir - Absolute path to the engine (repository) directory
  * @param patchOwnedFiles - Set of patch-owned `.sys.mjs` file paths (relative to repoDir)
+ * @param extraShimPath - Optional project-relative path to an additional
+ *   `.d.ts` file whose contents are concatenated to the built-in
+ *   Firefox-globals shim. Sourced from `patchLint.checkJsExtraShim`.
+ *   Resolved against `projectRoot` (one level up from `repoDir` is the
+ *   wrong root — patches sit inside `engine/` while the shim lives at
+ *   the project root, so the caller passes both).
+ * @param projectRoot - Absolute project root for resolving `extraShimPath`.
+ *   Defaults to `repoDir` for back-compat with callers that don't
+ *   pass an extra shim (no resolution actually happens in that case).
  * @returns Array of lint issues from TS diagnostics
  */
-export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>): Promise<PatchLintIssue[]>;
+export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>, extraShimPath?: string, projectRoot?: string): Promise<PatchLintIssue[]>;