@hominis/fireforge 0.47.1 → 0.49.0

package/dist/src/core/test-profile-files.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { InvalidArgumentError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { warn } from '../utils/logger.js';
+/** Prepares profile overlays and browser/port ownership preconditions. */
+export async function stageProfileFiles(projectRoot, files) {
+    const root = await mkdtemp(join(tmpdir(), 'fireforge-profile-overlay-'));
+    const top = new Set();
+    try {
+        for (const file of files) {
+            const separator = file.indexOf('=');
+            const source = file.slice(0, separator);
+            const dest = file.slice(separator + 1).replaceAll('\\', '/');
+            if (separator <= 0 ||
+                !dest ||
+                dest.startsWith('/') ||
+                dest.includes(':') ||
+                dest.split('/').some((part) => !part || part === '.' || part === '..')) {
+                throw new InvalidArgumentError('--profile-file requires source=relative/destination with no traversal.', '--profile-file');
+            }
+            const target = join(root, dest);
+            await mkdir(dirname(target), { recursive: true });
+            await copyFile(resolve(projectRoot, source), target);
+            top.add(dest.split('/')[0] ?? dest);
+        }
+        return {
+            root,
+            args: [...top].map((path) => `--extra-profile-file=${join(root, path)}`),
+            env: { FIREFORGE_PROFILE_MERGE_ROOT: root },
+        };
+    }
+    catch (error) {
+        await cleanupProfileFiles(root);
+        throw error;
+    }
+}
+/** Python startup overlay: allow merging ONLY the explicitly staged profile directories. */
+export const PROFILE_MERGE_PYTHON = `
+import os
+import shutil
+_fireforge_profile_root = os.environ.get("FIREFORGE_PROFILE_MERGE_ROOT")
+if _fireforge_profile_root and not getattr(shutil.copytree, "_fireforge_profile_merge", False):
+    _fireforge_copytree = shutil.copytree
+    def _fireforge_merge_copytree(src, dst, *args, **kwargs):
+        if os.path.realpath(src).startswith(os.path.realpath(_fireforge_profile_root) + os.sep):
+            # Python's recursive calls may supply dirs_exist_ok positionally.
+            if len(args) >= 5:
+                args = args[:4] + (True,) + args[5:]
+            else:
+                kwargs["dirs_exist_ok"] = True
+        return _fireforge_copytree(src, dst, *args, **kwargs)
+    _fireforge_merge_copytree._fireforge_profile_merge = True
+    shutil.copytree = _fireforge_merge_copytree
+`;
+/** Classifies the profile setup traceback separately from stale packaging. */
+export function classifyProfileArgumentFailure(output) {
+    if (!/copyExtraFilesToProfile/.test(output) || !/FileExistsError/.test(output))
+        return undefined;
+    return {
+        kind: 'harness-arguments',
+        note: 'profile directory collision; use --profile-file source=chrome/userChrome.css to merge into the existing profile',
+    };
+}
+/** Cleanup is independent of the harness verdict and cannot hide its primary error. */
+export async function cleanupProfileFiles(root) {
+    try {
+        await rm(root, { recursive: true, force: true });
+    }
+    catch (error) {
+        warn(`Could not remove staged profile files ${root}: ${toError(error).message}`);
+    }
+}

package/dist/src/core/test-stale-check.d.ts

@@ -27,8 +27,8 @@ export interface StaleBuildResult {
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
  * as an up-front warning when `--build` was not passed. The probe never
- * throws. Git failures and a missing baseline both degrade to `stale: false`
- * so a broken probe cannot block a test run.
+ * refuses a malformed persisted baseline. Git failures and a missing baseline
+ * degrade to `stale: false` because they provide no comparison anchor.
  *
  * @param projectRoot Root directory of the project.
  * @param engineDir Path to the engine directory.
@@ -52,11 +52,10 @@ export declare const FULL_SUITE_REQUEST = "(entire suite)";
  * `_tests/` support fixtures and hang rather than fail.
  *
  * Coverage semantics: an absent claim and `'full'` cover everything. A
- * scoped list covers a request path when the request equals a covered entry,
- * sits beneath a covered directory entry, or shares a manifest granule with
- * a covered entry (see {@link toManifestGranule}: a scoped `test --build`
- * packages the whole manifest directory, so a same-manifest sibling of a
- * covered file is packaged too). Both sides are normalized to forward
+ * scoped list covers a request path when the request equals a covered entry
+ * or sits beneath it. A file claim never widens to its containing directory:
+ * sibling files can belong to different manifests or harnesses, and a dot in
+ * a directory name does not make it a file. Both sides are normalized to forward
  * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
  * paths are POSIX by convention). A request with no paths is a full-suite
  * run and is never covered by a scoped list, so the

package/dist/src/core/test-stale-check.js

@@ -35,14 +35,14 @@ const STALE_PATHS_LIMIT = 10;
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
  * as an up-front warning when `--build` was not passed. The probe never
- * throws. Git failures and a missing baseline both degrade to `stale: false`
- * so a broken probe cannot block a test run.
+ * refuses a malformed persisted baseline. Git failures and a missing baseline
+ * degrade to `stale: false` because they provide no comparison anchor.
  *
  * @param projectRoot Root directory of the project.
  * @param engineDir Path to the engine directory.
  */
 export async function checkStaleBuildForTest(projectRoot, engineDir) {
-    const baseline = await readBuildBaseline(projectRoot);
+    const baseline = await readBuildBaseline(projectRoot, 'refuse');
     if (!baseline) {
         return { stale: false, changedPaths: [], truncated: 0, baseline: undefined };
     }
@@ -93,11 +93,10 @@ export const FULL_SUITE_REQUEST = '(entire suite)';
  * `_tests/` support fixtures and hang rather than fail.
  *
  * Coverage semantics: an absent claim and `'full'` cover everything. A
- * scoped list covers a request path when the request equals a covered entry,
- * sits beneath a covered directory entry, or shares a manifest granule with
- * a covered entry (see {@link toManifestGranule}: a scoped `test --build`
- * packages the whole manifest directory, so a same-manifest sibling of a
- * covered file is packaged too). Both sides are normalized to forward
+ * scoped list covers a request path when the request equals a covered entry
+ * or sits beneath it. A file claim never widens to its containing directory:
+ * sibling files can belong to different manifests or harnesses, and a dot in
+ * a directory name does not make it a file. Both sides are normalized to forward
  * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
  * paths are POSIX by convention). A request with no paths is a full-suite
  * run and is never covered by a scoped list, so the
@@ -114,29 +113,9 @@ export function findUncoveredRequestPaths(coverage, requestedPaths) {
     }
     return requestedPaths.filter((requested) => {
         const path = normalizeCoveragePath(requested);
-        const granule = toManifestGranule(path);
-        return !covered.some((c) => path === c || path.startsWith(`${c}/`) || granule === toManifestGranule(c));
+        return !covered.some((c) => path === c || path.startsWith(`${c}/`));
     });
 }
-/**
- * Maps a normalized request/coverage path to the "manifest granule" the
- * packaged runtime actually staged: an extension-bearing basename (a test
- * FILE) maps to its containing directory, a directory (no dot in the
- * basename) maps to itself. Purely lexical: the directory-as-manifest
- * approximation holds because xpcshell/mochitest manifests live next to
- * their test files and a scoped `test --build` stages the whole manifest
- * directory into `obj-*`/`_tests/`, not single files. Caveat: a directory
- * whose basename contains a dot is misread as a file and mapped to its
- * parent, which widens (never narrows) the covered granule.
- */
-function toManifestGranule(path) {
-    const slash = path.lastIndexOf('/');
-    const base = slash === -1 ? path : path.slice(slash + 1);
-    if (!base.includes('.')) {
-        return path;
-    }
-    return slash === -1 ? '' : path.slice(0, slash);
-}
 /** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
 function normalizeCoveragePath(path) {
     return normalizePathSlashes(path.trim()).replace(/\/+$/, '');
@@ -196,9 +175,7 @@ export async function findChangedTestManifestsForPaths(engineDir, baseline, unco
         verbose(`Coverage refusal: manifest probe failed — ${toError(error).message}`);
         return [];
     }
-    const requestDirs = uncovered
-        .filter((p) => p !== FULL_SUITE_REQUEST)
-        .map((p) => toManifestGranule(normalizeCoveragePath(p)));
+    const requestDirs = uncovered.filter((p) => p !== FULL_SUITE_REQUEST).map(normalizeCoveragePath);
     const hits = changed.filter((path) => {
         if (!isTestManifestPath(path))
             return false;

package/dist/src/core/token-category.d.ts

@@ -5,32 +5,13 @@
  * agree on what "exists" means.
  */
 export declare function categoryHeaderExists(lines: string[], category: string): boolean;
-/**
- * Scans a tokens CSS file for category header comments and returns the
- * category names in document order. Used to enrich the "category not
- * found" error body with concrete alternatives the operator can copy.
- *
- * Mirrors the shapes `findCategorySection` recognises:
- * - Single-line: `/* = Foo = *\/`
- * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
- *   closing `*\/`.
- *
- * This helper exists as a pure inspector. It never throws on malformed
- * headers and silently skips shapes it cannot parse.
- */
-/**
- * Category name declared by the banner starting at `index`, or `undefined`
- * when that line opens no banner.
- *
- * The single reader for both banner shapes, so the inventory walk, the
- * "available categories" error body and the section finder cannot drift on
- * what counts as a header.
- *
- * @param lines - Tokens CSS split into lines
- * @param index - 0-based line index to test
- * @returns The declared category name, or undefined
- */
-export declare function categoryBannerNameAt(lines: string[], index: number): string | undefined;
+export interface TokenCategorySection {
+    name: string;
+    categoryLine: number;
+    sectionEnd: number;
+}
+/** Parses category regions owned by the base root, including nested CSS rules. */
+export declare function parseTokenCategorySections(lines: string[]): TokenCategorySection[];
 /**
  * Asserts the category banner exists (or that creation was requested).
  * Throws a GeneralError naming the available categories and the

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

@@ -14,12 +14,6 @@ import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
-function singleLineBannerPattern(category) {
-    return new RegExp(`\\/\\*\\s*=+\\s*${escapeRegex(category)}\\s*=+\\s*\\*\\/`);
-}
-function multiLineBlockNameMatches(blockLine, category) {
-    return blockLine.replace(/^\s*\*\s*/, '').trim() === category;
-}
 /**
  * Body of the first `/* … *\/` comment on `line`, or `undefined` when the
  * line carries no closed block comment.
@@ -85,37 +79,8 @@ function singleLineBannerName(line) {
  * agree on what "exists" means.
  */
 export function categoryHeaderExists(lines, category) {
-    const singleLinePattern = singleLineBannerPattern(category);
-    for (const [i, line] of lines.entries()) {
-        if (singleLinePattern.test(line)) {
-            return true;
-        }
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (multiLineBlockNameMatches(blockLine, category)) {
-                    return true;
-                }
-                if (/\*\//.test(blockLine))
-                    break;
-            }
-        }
-    }
-    return false;
+    return parseTokenCategorySections(lines).some((section) => section.name === category);
 }
-/**
- * Scans a tokens CSS file for category header comments and returns the
- * category names in document order. Used to enrich the "category not
- * found" error body with concrete alternatives the operator can copy.
- *
- * Mirrors the shapes `findCategorySection` recognises:
- * - Single-line: `/* = Foo = *\/`
- * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
- *   closing `*\/`.
- *
- * This helper exists as a pure inspector. It never throws on malformed
- * headers and silently skips shapes it cannot parse.
- */
 /**
  * Category name declared by the banner starting at `index`, or `undefined`
  * when that line opens no banner.
@@ -128,7 +93,7 @@ export function categoryHeaderExists(lines, category) {
  * @param index - 0-based line index to test
  * @returns The declared category name, or undefined
  */
-export function categoryBannerNameAt(lines, index) {
+function categoryBannerNameAt(lines, index) {
     const line = lines[index] ?? '';
     const extracted = singleLineBannerName(line);
     if (extracted !== undefined)
@@ -149,13 +114,40 @@ export function categoryBannerNameAt(lines, index) {
     return undefined;
 }
 function discoverCategoryHeaders(lines) {
-    const categories = new Set();
-    for (let i = 0; i < lines.length; i++) {
-        const name = categoryBannerNameAt(lines, i);
-        if (name !== undefined)
-            categories.add(name);
+    return [...new Set(parseTokenCategorySections(lines).map((section) => section.name))];
+}
+/** Parses category regions owned by the base root, including nested CSS rules. */
+export function parseTokenCategorySections(lines) {
+    const bounds = findBaseRootBounds(lines);
+    if (bounds === undefined || bounds.close === -1)
+        return [];
+    const masked = maskCommentLines(lines);
+    const sections = [];
+    let current;
+    let bodyStarted = false;
+    for (let index = bounds.open + 1; index < bounds.close; index++) {
+        const line = lines[index] ?? '';
+        const name = categoryBannerNameAt(lines, index);
+        const boundary = name !== undefined || isSingleLineBannerLine(line);
+        if (!boundary) {
+            if ((masked[index] ?? '').trim())
+                bodyStarted = true;
+            continue;
+        }
+        // A decorative rule immediately after a named header belongs to that
+        // header. A later rule, after declarations, ends its section.
+        if (name === undefined && current && !bodyStarted)
+            continue;
+        if (current)
+            current.sectionEnd = index;
+        current = undefined;
+        if (name !== undefined) {
+            current = { name, categoryLine: index, sectionEnd: bounds.close };
+            bodyStarted = false;
+            sections.push(current);
+        }
     }
-    return [...categories];
+    return sections;
 }
 /**
  * Asserts the category banner exists (or that creation was requested).
@@ -204,30 +196,9 @@ export function declareCategoryBanner(lines, category, tokensCssPath) {
 }
 /** Locates and bounds the named category section. Throws when absent. */
 export function findCategorySection(lines, category, tokensCssPath) {
-    const singleLinePattern = singleLineBannerPattern(category);
-    let categoryLine = -1;
-    for (const [i, line] of lines.entries()) {
-        // Check single-line format: /* = Category = */
-        if (singleLinePattern.test(line)) {
-            categoryLine = i;
-            break;
-        }
-        // Check multi-line format: line opens a block comment with === but does not close it
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (multiLineBlockNameMatches(blockLine, category)) {
-                    categoryLine = i;
-                    break;
-                }
-                if (/\*\//.test(blockLine))
-                    break;
-            }
-            if (categoryLine !== -1)
-                break;
-        }
-    }
-    if (categoryLine === -1) {
+    const sections = parseTokenCategorySections(lines);
+    const section = sections.find((entry) => entry.name === category);
+    if (section === undefined) {
         const discoveredCategories = discoverCategoryHeaders(lines);
         const available = discoveredCategories.length > 0
             ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
@@ -236,45 +207,46 @@ export function findCategorySection(lines, category, tokensCssPath) {
             `${available}\n\n` +
             'Add a header by hand inside the :root block (format: "/* = My Category = */") or re-run "fireforge furnace init --force" to re-seed the default categories.');
     }
-    // Find the end of this category section (next section header or closing })
-    // Skip past the current header block first
-    let scanStart = categoryLine + 1;
-    for (let i = categoryLine + 1; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (/^\s*\/\*\s*=/.test(line) || /^\s*\*\s*=/.test(line) || /^\s*\*\//.test(line)) {
-            scanStart = i + 1;
-            continue;
-        }
-        break;
-    }
-    let sectionEnd = lines.length;
-    for (let i = scanStart; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (isSingleLineBannerLine(line) ||
-            (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) ||
-            /^\s*\}/.test(line)) {
-            sectionEnd = i;
-            break;
-        }
-    }
-    return { categoryLine, sectionEnd };
+    return { categoryLine: section.categoryLine, sectionEnd: section.sectionEnd };
 }
 /** 0-based open/close line indices of the base `:root {` block. */
 export function findBaseRootBounds(lines) {
     const open = lines.findIndex((line) => /:root\s*\{/.test(line));
     if (open === -1)
         return undefined;
-    for (let i = open + 1; i < lines.length; i++) {
-        if (/^\s*\}/.test(lines[i] ?? '')) {
-            return { open, close: i };
+    const masked = maskCommentLines(lines);
+    let depth = 0;
+    for (let i = open; i < lines.length; i++) {
+        // Ignore braces in CSS strings (including data URLs).
+        const code = (masked[i] ?? '').replace(/(["'])(?:\\.|(?!\1).)*\1/g, '');
+        for (const char of code) {
+            if (char === '{')
+                depth++;
+            if (char === '}' && --depth === 0)
+                return { open, close: i };
         }
     }
     return { open, close: -1 };
 }
 /** Masks block-comment content per line so declarations inside comments never match. */
 export function maskCommentLines(lines) {
-    const masked = lines.join('\n').replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
-    return masked.split('\n');
+    const source = lines.join('\n');
+    const parts = [];
+    let cursor = 0;
+    for (;;) {
+        const open = source.indexOf('/*', cursor);
+        if (open === -1)
+            break;
+        const close = source.indexOf('*/', open + 2);
+        // An unfinished edit has no complete comment to mask. Searching only
+        // once prevents restarting a regex at every repeated comment opener.
+        if (close === -1)
+            break;
+        parts.push(source.slice(cursor, open), source.slice(open, close + 2).replace(/[^\n]/g, ' '));
+        cursor = close + 2;
+    }
+    parts.push(source.slice(cursor));
+    return parts.join('').split('\n');
 }
 /**
  * Finds an existing declaration of `tokenName` inside the base `:root`
@@ -288,38 +260,13 @@ export function findTokenDeclarationInRoot(lines, tokenName) {
     if (bounds === undefined || bounds.close === -1)
         return undefined;
     const masked = maskCommentLines(lines);
+    const sections = parseTokenCategorySections(lines);
     const declPattern = new RegExp(`^\\s*${escapeRegex(tokenName)}\\s*:`);
     for (let i = bounds.open + 1; i < bounds.close; i++) {
         if (!declPattern.test(masked[i] ?? ''))
             continue;
-        const category = findSectionNameAbove(lines, i);
+        const category = sections.find((section) => i > section.categoryLine && i < section.sectionEnd)?.name;
         return category === undefined ? { line: i + 1 } : { line: i + 1, category };
     }
     return undefined;
 }
-/** Nearest category banner name above `lineIndex`, if any. */
-function findSectionNameAbove(lines, lineIndex) {
-    const singleLinePattern = /\/\*\s*=+\s*(.+?)\s*=+\s*\*\//;
-    for (let i = lineIndex - 1; i >= 0; i--) {
-        const line = lines[i] ?? '';
-        const singleMatch = singleLinePattern.exec(line);
-        if (singleMatch?.[1]) {
-            const extracted = singleMatch[1].trim();
-            if (extracted.length > 0 && !/^=+$/.test(extracted))
-                return extracted;
-            continue;
-        }
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (/\*\//.test(blockLine))
-                    break;
-                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
-                if (trimmed.length === 0 || /^=+$/.test(trimmed))
-                    continue;
-                return trimmed;
-            }
-        }
-    }
-    return undefined;
-}

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

@@ -8,12 +8,12 @@
  * categories a project actually has, so the only way to name one correctly
  * was to hand-parse a neighbouring `= Category =` banner out of the file.
  * This module is that report. It reuses the banner and
- * `:root`-bounds primitives from `token-category.ts` rather than parsing
+ * category-region model from `token-category.ts` rather than parsing
  * tokens CSS a second way: two readers that disagree on what a banner is
  * would put `token list` and `token add` in different sections of the same
  * file.
  */
-import { categoryBannerNameAt, findBaseRootBounds, maskCommentLines } from './token-category.js';
+import { findBaseRootBounds, maskCommentLines, parseTokenCategorySections, } from './token-category.js';
 /** Matches a custom-property declaration and captures its name and value. */
 const DECLARATION_PATTERN = /^\s*(--[A-Za-z0-9_-]+)\s*:\s*([^;]*);?/;
 /**
@@ -32,14 +32,18 @@ export function collectTokenInventory(lines) {
     if (bounds === undefined || bounds.close === -1)
         return [];
     const masked = maskCommentLines(lines);
+    const sections = parseTokenCategorySections(lines);
+    const headers = new Map(sections.map((section) => [section.categoryLine, section]));
     const groups = [];
     let current;
+    let sectionEnd = bounds.close;
     for (let i = bounds.open + 1; i < bounds.close; i++) {
-        // Banners are read from the raw lines: `maskCommentLines` blanks comment
-        // bodies, which is exactly what a banner is.
-        const banner = categoryBannerNameAt(lines, i);
-        if (banner !== undefined) {
-            current = { category: banner, tokens: [] };
+        if (i >= sectionEnd)
+            current = undefined;
+        const section = headers.get(i);
+        if (section !== undefined) {
+            current = { category: section.name, tokens: [] };
+            sectionEnd = section.sectionEnd;
             groups.push(current);
             continue;
         }
@@ -48,6 +52,7 @@ export function collectTokenInventory(lines) {
             continue;
         if (current === undefined) {
             current = { category: null, tokens: [] };
+            sectionEnd = bounds.close;
             groups.push(current);
         }
         current.tokens.push({ name: match[1], line: i + 1, value: (match[2] ?? '').trim() });

package/dist/src/core/toolchain-preflight.d.ts

@@ -27,6 +27,12 @@
  */
 /** Tools the preflight knows how to probe. */
 export type ToolchainTool = 'cbindgen' | 'rustc';
+/**
+ * Resolves the mach state directory the same way mach itself does:
+ * `$MOZBUILD_STATE_PATH`, else `~/.mozbuild` (same resolution as
+ * `mach-resource-shim.ts`).
+ */
+export declare function mozbuildStateDir(): string;
 /** One probed candidate binary for a tool. */
 export interface ToolchainCandidate {
     /** Binary path (or bare name for the PATH candidate). */

package/dist/src/core/toolchain-preflight.js

@@ -37,7 +37,7 @@ import { verbose } from '../utils/logger.js';
  * `$MOZBUILD_STATE_PATH`, else `~/.mozbuild` (same resolution as
  * `mach-resource-shim.ts`).
  */
-function mozbuildStateDir() {
+export function mozbuildStateDir() {
     return process.env['MOZBUILD_STATE_PATH'] ?? join(homedir(), '.mozbuild');
 }
 /** Where each tool's minimum is declared inside the Firefox tree. */

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

@@ -26,6 +26,16 @@ import type { TypecheckProjectResult } from '../types/typecheck.js';
  * in CI logs.
  */
 export declare const CHECK_JS_DISABLED_NOTICE = "Project sets \"checkJs: false\" \u2014 skipping (override the jsconfig to enable typecheck).";
+/** Run-level options for {@link runTypecheck}. */
+export interface RunTypecheckOptions {
+    /**
+     * Directory for the per-project incremental build info. Defaults to
+     * `<projectRoot>/.fireforge/typecheck`.
+     */
+    cacheDir?: string;
+    /** Build every project from scratch and write no build info. */
+    noCache?: boolean;
+}
 /**
  * Runs `fireforge typecheck` against every project listed in `cfg.projects`.
  *
@@ -55,7 +65,7 @@ export declare const CHECK_JS_DISABLED_NOTICE = "Project sets \"checkJs: false\"
  *   in declared order. The CLI is responsible for printing the issues
  *   and computing the exit code.
  */
-export declare function runTypecheck(projectRoot: string, cfg: TypecheckConfig): Promise<TypecheckProjectResult[]>;
+export declare function runTypecheck(projectRoot: string, cfg: TypecheckConfig, runOptions?: RunTypecheckOptions): Promise<TypecheckProjectResult[]>;
 /**
  * Converts an absolute path to a path relative to the project root,
  * for display in CLI output. Falls back to the absolute path when