@hominis/fireforge 0.18.9 → 0.18.11

package/dist/src/commands/patch/rename.js

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch rename <name>` — relabels a patch's filename, manifest
+ * `name`, and (optionally) `description` without rewriting the `.patch`
+ * file body.
+ *
+ * Companion to `re-export --files <subset>`. Re-export shrinks the body
+ * + `filesAffected`, but leaves the patch's identity describing the
+ * pre-shrink scope. Before this verb existed, the only workaround for
+ * that drift was `delete` + re-export, which briefly removed the patch
+ * from the queue (any forward-import dependent would refuse the
+ * re-export until the deleted patch's siblings were rewritten).
+ *
+ * The filename rename and the manifest mutation happen under the patch
+ * directory lock so concurrent exports cannot allocate the new
+ * filename, and a filesystem rename failure rolls back before the
+ * manifest is touched.
+ */
+import { rename as fsRename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { sanitizeName } from '../../core/patch-export.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifest, resolvePatchIdentifier, savePatchesManifest, } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+import { pickDefined } from '../../utils/options.js';
+/**
+ * Pulls the ordinal-string + category prefix out of a patch filename so
+ * the rename keeps the existing ordinal padding verbatim. Returning the
+ * literal substring (rather than recomputing from the parsed integer)
+ * avoids any chance of the new filename's ordinal differing from the
+ * old by a leading-zero count.
+ */
+function splitPatchFilename(filename) {
+    const m = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(filename);
+    if (!m?.[1] || !m[2] || !m[3])
+        return null;
+    return { ordinalStr: m[1], category: m[2], slug: m[3] };
+}
+/**
+ * Performs the rename's transactional core under the patch directory
+ * lock: re-reads the manifest, re-checks for filename collisions,
+ * renames the `.patch` file on disk (when applicable), writes the
+ * updated manifest, and appends a history entry. Filesystem rename
+ * happens before the manifest save so an interrupted run never leaves
+ * the manifest pointing at a missing file; a manifest-save failure
+ * rolls the filesystem rename back.
+ */
+async function commitRenameUnderLock(input) {
+    const { patchesDir, target, newFilename, newName, newDescription, filenameChanging, nameChanging, descriptionChanging, } = input;
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const fresh = await loadPatchesManifest(patchesDir);
+        if (!fresh) {
+            throw new GeneralError('Manifest disappeared between resolution and rename.');
+        }
+        const idx = fresh.patches.findIndex((p) => p.filename === target.filename);
+        if (idx === -1) {
+            throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during rename. Re-run after investigating.`);
+        }
+        const before = fresh.patches[idx];
+        if (!before) {
+            throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during rename.`);
+        }
+        if (filenameChanging) {
+            const collisionInLock = fresh.patches.find((p) => p.filename === newFilename && p.filename !== target.filename);
+            if (collisionInLock) {
+                throw new InvalidArgumentError(`Cannot rename to "${newFilename}" — a different patch claimed that filename concurrently.`, 'patch rename');
+            }
+            const oldPath = join(patchesDir, target.filename);
+            const newPath = join(patchesDir, newFilename);
+            if (await pathExists(newPath)) {
+                throw new InvalidArgumentError(`Cannot rename: ${newFilename} already exists on disk. Resolve manually before retrying.`, 'patch rename');
+            }
+            await fsRename(oldPath, newPath);
+            fresh.patches[idx] = {
+                ...before,
+                filename: newFilename,
+                name: newName,
+                ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
+            };
+            try {
+                await savePatchesManifest(patchesDir, fresh);
+            }
+            catch (saveError) {
+                try {
+                    await fsRename(newPath, oldPath);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore ${target.filename} after manifest write failure: ${toError(rollbackError).message}`);
+                }
+                throw saveError;
+            }
+        }
+        else {
+            fresh.patches[idx] = {
+                ...before,
+                ...(nameChanging ? { name: newName } : {}),
+                ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
+            };
+            await savePatchesManifest(patchesDir, fresh);
+        }
+        try {
+            await appendHistory(patchesDir, {
+                operation: 'patch-rename',
+                args: {
+                    oldFilename: target.filename,
+                    newFilename,
+                    oldName: target.name,
+                    newName,
+                    ...(descriptionChanging ? { oldDescription: target.description, newDescription } : {}),
+                },
+                ...(input.yes === true ? { yes: true } : {}),
+                result: 'ok',
+            });
+        }
+        catch (historyError) {
+            warn(`History log append failed after patch rename committed (${newFilename}): ${toError(historyError).message}`);
+        }
+    });
+}
+/**
+ * Runs the `patch rename` command: relabels filename + manifest entry
+ * for a single patch atomically.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (`--to <new-name>` is required)
+ */
+export async function patchRenameCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch rename (dry run)' : 'FireForge patch rename');
+    if (options.to === undefined || options.to.trim() === '') {
+        throw new InvalidArgumentError('Specify --to <new-name>. The new name is sanitised into the filename slug the same way `export --name` is.', 'patch rename');
+    }
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const target = resolvePatchIdentifier(identifier, manifest.patches);
+    if (!target) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
+    }
+    const split = splitPatchFilename(target.filename);
+    if (!split) {
+        throw new GeneralError(`Cannot rename ${target.filename}: filename does not match the expected {ordinal}-{category}-{slug}.patch convention. Re-export the patch instead.`);
+    }
+    const newSlug = sanitizeName(options.to);
+    if (newSlug === '') {
+        throw new InvalidArgumentError('--to must contain at least one alphanumeric character after sanitisation.', 'patch rename');
+    }
+    const newFilename = `${split.ordinalStr}-${split.category}-${newSlug}.patch`;
+    const filenameChanging = newFilename !== target.filename;
+    const nameChanging = options.to !== target.name;
+    const descriptionChanging = options.description !== undefined && options.description !== target.description;
+    if (!filenameChanging && !nameChanging && !descriptionChanging) {
+        info(`${target.filename}: name and description already match — nothing to change.`);
+        outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch rename (no-op)');
+        return;
+    }
+    // Pre-flight collision check against the manifest snapshot we already
+    // loaded. The authoritative check happens again inside the lock to
+    // close the TOCTOU window — surface a helpful error here when the
+    // collision is obvious so the operator does not get surprised by a
+    // late refusal after a confirmation prompt.
+    if (filenameChanging) {
+        const collision = manifest.patches.find((p) => p.filename === newFilename && p.filename !== target.filename);
+        if (collision) {
+            throw new InvalidArgumentError(`Cannot rename to "${newFilename}" — a different patch already uses that filename.`, 'patch rename');
+        }
+    }
+    const summary = [];
+    if (filenameChanging) {
+        summary.push(`rename ${target.filename} → ${newFilename}`);
+    }
+    if (nameChanging) {
+        summary.push(`name: "${target.name}" → "${options.to}"`);
+    }
+    if (descriptionChanging) {
+        summary.push(`description: "${target.description || '(none)'}" → "${options.description ?? '(none)'}"`);
+    }
+    const decision = await confirmDestructive({
+        operation: 'patch-rename',
+        title: `Rename ${target.filename}`,
+        summary,
+        yes: options.yes === true,
+        dryRun: isDryRun,
+        conflicts: null,
+    });
+    if (decision === 'dry-run') {
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    if (decision === 'cancelled') {
+        outro('Rename cancelled');
+        return;
+    }
+    await commitRenameUnderLock({
+        patchesDir: paths.patches,
+        target,
+        newFilename,
+        newName: options.to,
+        ...(options.description !== undefined ? { newDescription: options.description } : {}),
+        filenameChanging,
+        nameChanging,
+        descriptionChanging,
+        ...(options.yes === true ? { yes: true } : {}),
+    });
+    if (filenameChanging) {
+        info(`${target.filename} → ${newFilename}`);
+    }
+    else {
+        info(`${target.filename}: metadata updated.`);
+    }
+    outro('Patch rename complete');
+}
+/**
+ * Registers the `patch rename` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchRename(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('rename <name>')
+        .description('Rename a patch: filename + manifest name (and optional description) update without rewriting the .patch body.')
+        .requiredOption('--to <new-name>', 'New human-readable name (sanitised into the filename slug)')
+        .option('--description <text>', 'Replacement description (omit to leave description unchanged)')
+        .option('--dry-run', 'Show what would change without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (name, options) => {
+        await patchRenameCommand(getProjectRoot(), name, pickDefined(options));
+    }));
+}
+//# sourceMappingURL=rename.js.map

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/license-headers.d.ts

@@ -29,6 +29,11 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  * standard MPL header — operators were forced to `--skip-lint` over a real
  * false positive.
  *
+ * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
+ * leading the file are tolerated — Mozilla's canonical layout puts those
+ * on lines 1–2 with the MPL header on lines 3+, which the raw
+ * `startsWith` check would otherwise miss.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */