@hominis/fireforge 0.38.0 → 0.40.0

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

@@ -107,6 +107,15 @@ function findVariantBlockInsertionPoint(lines) {
     }
     return lines.length;
 }
+/**
+ * True when a top-level `:root<variant>` block exists in `lines`. Used by
+ * the override path to write theme-attribute blocks only when the scaffold
+ * already declares them — `insertVariantDeclaration` would otherwise create
+ * the block, which is only wanted for the explicit `--variant` flow.
+ */
+export function variantBlockExists(lines, variant) {
+    return findVariantBlock(lines, variant) !== null;
+}
 /** True when the `:root<variant>` block already declares `tokenName`. */
 export function variantBlockHasToken(lines, variant, tokenName) {
     const block = findVariantBlock(lines, variant);

package/dist/src/core/tree-cow.d.ts

@@ -0,0 +1,18 @@
+/** Runs a clone command; throws on non-zero exit. */
+export type CloneExecutor = (command: string, args: string[]) => Promise<void>;
+/** How this host can materialise a tree. */
+export type CowCapability = 'clonefile' | 'reflink' | 'none';
+/** Per-platform `cp` argv prefix for a CoW copy of one entry. */
+export declare function cowCopyArgs(capability: Exclude<CowCapability, 'none'>): string[];
+/**
+ * Probes CoW support in `dir` by cloning a tiny probe file there.
+ * Non-darwin/linux platforms report 'none' without probing.
+ */
+export declare function detectCowSupport(dir: string, platform?: NodeJS.Platform, executor?: CloneExecutor): Promise<CowCapability>;
+/**
+ * Copies one directory entry (file or directory, recursively) from
+ * `sourcePath` to `destinationPath` using the given capability —
+ * clonefile/reflink when available, a plain physical copy under
+ * 'none' (the `--force-copy` path; the CALLER gates on the flag).
+ */
+export declare function cloneEntry(capability: CowCapability, sourcePath: string, destinationPath: string, platform?: NodeJS.Platform, executor?: CloneExecutor): Promise<void>;

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

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Copy-on-write cloning for `fireforge tree` (FORGE G15).
+ *
+ * Capability is probed BY DOING — a tiny `cp -c` (APFS clonefile) or
+ * `cp --reflink=always` (btrfs/XFS) in the actual destination directory —
+ * so the verdict is truthful for the volume the trees will live on. A
+ * filesystem without CoW support REFUSES honestly; `--force-copy` opts
+ * into a full physical copy but is never implied (a Firefox tree can be
+ * tens of gigabytes).
+ *
+ * The exec layer is injected so unit tests assert the exact `cp` argv per
+ * platform without touching the filesystem.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { exec } from '../utils/process.js';
+const defaultExecutor = async (command, args) => {
+    const result = await exec(command, args);
+    if (result.exitCode !== 0) {
+        throw new Error(`${command} ${args.join(' ')} failed (exit ${String(result.exitCode)}): ${result.stderr}`);
+    }
+};
+/** Per-platform `cp` argv prefix for a CoW copy of one entry. */
+export function cowCopyArgs(capability) {
+    return capability === 'clonefile' ? ['-c', '-R', '-p'] : ['--reflink=always', '-a'];
+}
+/**
+ * Probes CoW support in `dir` by cloning a tiny probe file there.
+ * Non-darwin/linux platforms report 'none' without probing.
+ */
+export async function detectCowSupport(dir, platform = process.platform, executor = defaultExecutor) {
+    if (platform !== 'darwin' && platform !== 'linux')
+        return 'none';
+    const capability = platform === 'darwin' ? 'clonefile' : 'reflink';
+    let probeDir;
+    try {
+        probeDir = await mkdtemp(join(dir, '.fireforge-cow-probe-'));
+        const src = join(probeDir, 'src');
+        const dst = join(probeDir, 'dst');
+        await writeFile(src, 'probe');
+        const flag = capability === 'clonefile' ? '-c' : '--reflink=always';
+        await executor('cp', [flag, src, dst]);
+        return capability;
+    }
+    catch (error) {
+        verbose(`CoW probe in ${dir} failed: ${toError(error).message}`);
+        return 'none';
+    }
+    finally {
+        if (probeDir !== undefined) {
+            await rm(probeDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+}
+/**
+ * Copies one directory entry (file or directory, recursively) from
+ * `sourcePath` to `destinationPath` using the given capability —
+ * clonefile/reflink when available, a plain physical copy under
+ * 'none' (the `--force-copy` path; the CALLER gates on the flag).
+ */
+export async function cloneEntry(capability, sourcePath, destinationPath, platform = process.platform, executor = defaultExecutor) {
+    const args = capability === 'none'
+        ? platform === 'darwin'
+            ? ['-R', '-p']
+            : ['-a']
+        : cowCopyArgs(capability);
+    await executor('cp', [...args, sourcePath, destinationPath]);
+}

package/dist/src/core/tree-guard.d.ts

@@ -0,0 +1,35 @@
+import { type TreeMarker } from './tree-store.js';
+/**
+ * Per-command verdicts. `allowed` runs unconditionally; `refused` never
+ * runs in a tree; `conditional` consults `TREE_CONDITIONAL_CHECKS` with
+ * the invoked subcommand chain and parsed options.
+ */
+export declare const TREE_COMMAND_VERDICTS: Readonly<Record<string, 'allowed' | 'refused' | 'conditional'>>;
+interface ConditionalInput {
+    /** Subcommand chain below the top-level command (e.g. ['staged-dependency']). */
+    subcommands: readonly string[];
+    /** Merged options of the ACTION command (leaf). */
+    options: Readonly<Record<string, unknown>>;
+    /** Positional args of the action command. */
+    args: readonly unknown[];
+}
+/**
+ * Throws when `commandName` (with its subcommand chain and options) must
+ * not run inside the tree described by `marker`. Exported for the
+ * preAction hook in cli.ts and for the guard tests.
+ */
+export declare function enforceTreeGuard(marker: TreeMarker, commandName: string, input: ConditionalInput): void;
+/**
+ * Commander preAction hook body: locates the enclosing tree (if any) and
+ * enforces the verdict table for the invoked command chain.
+ */
+export declare function runTreeGuardHook(rootCommandName: string | undefined, actionCommand: {
+    name: () => string;
+    optsWithGlobals: () => Record<string, unknown>;
+    args: unknown[];
+    parent: {
+        name: () => string;
+        parent: unknown;
+    } | null;
+}): Promise<void>;
+export {};

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

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Read-only guard for verification trees (FORGE G15).
+ *
+ * A tree is a snapshot: its `patches/` and `components/` are copies with
+ * no merge-back model, so any command that mutates project or engine
+ * state must run in the primary tree. Enforcement is DEFAULT-DENY via an
+ * explicit verdict table over every top-level command — a newly added
+ * command is refused inside trees until its author classifies it (the
+ * drift test in `tree-guard.test.ts` fails otherwise) — and lives in ONE
+ * commander `preAction` hook installed by `createProgram()`, so the
+ * guard fires no matter how the cwd ended up inside a tree (`tree exec`
+ * or a plain `cd`).
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { readTreeMarker } from './tree-store.js';
+/**
+ * Per-command verdicts. `allowed` runs unconditionally; `refused` never
+ * runs in a tree; `conditional` consults `TREE_CONDITIONAL_CHECKS` with
+ * the invoked subcommand chain and parsed options.
+ */
+export const TREE_COMMAND_VERDICTS = {
+    setup: 'refused',
+    source: 'refused',
+    download: 'refused',
+    bootstrap: 'refused',
+    import: 'refused',
+    resolve: 'refused',
+    build: 'refused',
+    run: 'refused',
+    status: 'allowed',
+    reset: 'refused',
+    discard: 'refused',
+    export: 'conditional',
+    'export-all': 'conditional',
+    're-export': 'refused',
+    patch: 'refused',
+    rebase: 'refused',
+    package: 'refused',
+    watch: 'refused',
+    // Deferred with the objdir clone: obj-* embeds absolute primary paths.
+    test: 'refused',
+    config: 'conditional',
+    doctor: 'conditional',
+    register: 'refused',
+    wire: 'refused',
+    token: 'refused',
+    lint: 'allowed',
+    typecheck: 'allowed',
+    verify: 'allowed',
+    furnace: 'refused',
+    // No nesting; `tree list` inside a tree is pointless but harmless — the
+    // subcommand check below allows only `list`.
+    tree: 'conditional',
+};
+/** The command set named in refusal messages. */
+const ALLOWED_SUMMARY = 'Verification trees support: status, lint, typecheck, verify, doctor (read-only), ' +
+    'config (read), export --dry-run, and export-all --dry-run.';
+const TREE_CONDITIONAL_CHECKS = {
+    // Exports write patches/ + patches.json; only the dry-run preview is a read.
+    export: ({ options }) => options['dryRun'] === true,
+    'export-all': ({ options }) => options['dryRun'] === true,
+    // `config` with no positional value prints; with a value it writes.
+    config: ({ args }) => args.filter((a) => typeof a === 'string').length <= 1,
+    // Doctor reads unless a repair flag is set.
+    doctor: ({ options }) => options['repairFurnace'] !== true && options['fix'] !== true,
+    // No tree lifecycle inside a tree; `tree list` is the only read.
+    tree: ({ subcommands }) => subcommands[0] === 'list',
+};
+/**
+ * Throws when `commandName` (with its subcommand chain and options) must
+ * not run inside the tree described by `marker`. Exported for the
+ * preAction hook in cli.ts and for the guard tests.
+ */
+export function enforceTreeGuard(marker, commandName, input) {
+    const verdict = TREE_COMMAND_VERDICTS[commandName] ?? 'refused';
+    if (verdict === 'allowed')
+        return;
+    const conditional = TREE_CONDITIONAL_CHECKS[commandName];
+    if (verdict === 'conditional' && conditional && conditional(input))
+        return;
+    throw new GeneralError(`This is a FireForge verification tree ("${marker.name}", created from ${marker.primaryRoot}). ` +
+        `"${[commandName, ...input.subcommands].join(' ')}" mutates project or engine state and must run in the primary tree. ` +
+        ALLOWED_SUMMARY);
+}
+/**
+ * Commander preAction hook body: locates the enclosing tree (if any) and
+ * enforces the verdict table for the invoked command chain.
+ */
+export async function runTreeGuardHook(rootCommandName, actionCommand) {
+    // Resolve the top-level command and subcommand chain from the action
+    // command's parent links (commander nests subcommands).
+    const chain = [];
+    let node = actionCommand;
+    while (node && node.parent) {
+        chain.unshift(node.name());
+        node = node.parent;
+    }
+    const [commandName, ...subcommands] = chain;
+    if (commandName === undefined || commandName === rootCommandName)
+        return;
+    const marker = await (async () => {
+        let current = resolve(process.cwd());
+        for (let depth = 0; depth < 50; depth++) {
+            if (existsSync(join(current, 'fireforge.json'))) {
+                return readTreeMarker(current);
+            }
+            const parent = dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        return undefined;
+    })();
+    if (!marker)
+        return;
+    enforceTreeGuard(marker, commandName, {
+        subcommands,
+        options: actionCommand.optsWithGlobals(),
+        args: actionCommand.args,
+    });
+}

package/dist/src/core/tree-store.d.ts

@@ -0,0 +1,53 @@
+import { type CowCapability } from './tree-cow.js';
+/** `.fireforge/tree.json` — identifies a directory as a verification tree. */
+export interface TreeMarker {
+    schemaVersion: 1;
+    name: string;
+    primaryRoot: string;
+    createdAt: string;
+    engineHead: string | null;
+    patchesFingerprint: string | null;
+}
+/** One row of `tree list`. */
+export interface TreeListEntry {
+    name: string;
+    path: string;
+    createdAt: string;
+    staleness: 'fresh' | 'stale (engine advanced)' | 'stale (patches changed)' | 'unknown';
+}
+/** Absolute trees directory for a primary root. */
+export declare function getTreesDir(primaryRoot: string): string;
+/** Serialises tree create/remove against each other (primary-side sidecar lock). */
+export declare function withTreeLifecycleLock<T>(primaryRoot: string, operation: () => Promise<T>): Promise<T>;
+/** Reads the tree marker for a project root, or undefined when not a tree. */
+export declare function readTreeMarker(root: string): Promise<TreeMarker | undefined>;
+/** Current primary-side snapshot identity (engine HEAD + patches.json hash). */
+export declare function computePrimaryFingerprint(primaryRoot: string): Promise<{
+    engineHead: string | null;
+    patchesFingerprint: string | null;
+}>;
+/** Validates a tree name: one path segment, no traversal. */
+export declare function assertValidTreeName(name: string): void;
+/**
+ * Materialises the tree at `treeRoot` from `primaryRoot` using
+ * `capability` ('none' = plain copy, already gated on --force-copy by
+ * the caller). The engine tree is cloned whole and its `obj-*` build
+ * directories removed afterwards — CoW removal is cheap, and per-entry
+ * recursion into a Firefox tree is fragile. A fresh `.fireforge/` is
+ * created with only `state.json` (when present) and the tree marker.
+ */
+export declare function cloneTree(args: {
+    primaryRoot: string;
+    treeRoot: string;
+    name: string;
+    capability: CowCapability;
+    createdAt: string;
+}): Promise<TreeMarker>;
+/** Lists trees with staleness against the current primary state. */
+export declare function listTrees(primaryRoot: string): Promise<TreeListEntry[]>;
+/**
+ * Removes one tree. Refuses when a live process holds the tree's build
+ * or engine-session lock, and never deletes a path outside the trees
+ * directory (containment check before `rm -rf`).
+ */
+export declare function removeTree(primaryRoot: string, name: string): Promise<void>;

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

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Verification-tree storage and lifecycle for `fireforge tree` (FORGE G15).
+ *
+ * A tree is a FULL project-root CoW snapshot under
+ * `.fireforge/trees/<name>` — `getProjectRoot()` walks up from cwd, so
+ * every read command (status, lint, typecheck, verify, doctor,
+ * `export --dry-run`) runs inside the tree unmodified and its build /
+ * engine-session locks key on the tree root automatically. Trees are
+ * snapshots by design: there is no merge-back model, mutation commands
+ * are refused via the tree marker (see `tree-guard.ts`), and refresh is
+ * `tree remove` + `tree create`.
+ */
+import { createHash } from 'node:crypto';
+import { readdir, readFile, rm } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { withFileLock } from './file-lock.js';
+import { git } from './git-base.js';
+import { cloneEntry } from './tree-cow.js';
+const TREE_MARKER_FILENAME = 'tree.json';
+const TREES_DIRNAME = 'trees';
+/**
+ * Top-level entries never cloned into a tree: per-tree state must start
+ * clean (`.fireforge/`), locks are never inherited, the destructive-
+ * operation audit log stays primary-only, and dependency dirs are
+ * neither needed nor cheap.
+ */
+function isExcludedRootEntry(name) {
+    return (name === '.fireforge' ||
+        name === 'node_modules' ||
+        name === '.fireforge-history.jsonl' ||
+        name.endsWith('.lock'));
+}
+/** Absolute trees directory for a primary root. */
+export function getTreesDir(primaryRoot) {
+    return join(primaryRoot, '.fireforge', TREES_DIRNAME);
+}
+/** Serialises tree create/remove against each other (primary-side sidecar lock). */
+export async function withTreeLifecycleLock(primaryRoot, operation) {
+    return withFileLock(join(primaryRoot, '.fireforge', 'trees.lock'), operation, {
+        timeoutMs: 30_000,
+        onTimeoutMessage: 'Another fireforge tree create/remove is in progress. Wait for it to finish, then retry.',
+    });
+}
+/** Reads the tree marker for a project root, or undefined when not a tree. */
+export async function readTreeMarker(root) {
+    const markerPath = join(root, '.fireforge', TREE_MARKER_FILENAME);
+    if (!(await pathExists(markerPath)))
+        return undefined;
+    try {
+        const raw = await readJson(markerPath);
+        if (raw.schemaVersion !== 1 || typeof raw.name !== 'string')
+            return undefined;
+        return raw;
+    }
+    catch (error) {
+        verbose(`Unreadable tree marker at ${markerPath}: ${String(error)}`);
+        return undefined;
+    }
+}
+/** Current primary-side snapshot identity (engine HEAD + patches.json hash). */
+export async function computePrimaryFingerprint(primaryRoot) {
+    let engineHead;
+    try {
+        engineHead = (await git(['rev-parse', 'HEAD'], join(primaryRoot, 'engine'))).trim();
+    }
+    catch {
+        engineHead = null;
+    }
+    const patchesJson = join(primaryRoot, 'patches', 'patches.json');
+    const patchesFingerprint = (await pathExists(patchesJson))
+        ? createHash('sha256')
+            .update(await readFile(patchesJson))
+            .digest('hex')
+        : null;
+    return { engineHead, patchesFingerprint };
+}
+/** Validates a tree name: one path segment, no traversal. */
+export function assertValidTreeName(name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes('..')) {
+        throw new GeneralError(`Invalid tree name "${name}". Use a single path segment of letters, digits, ".", "_" or "-".`);
+    }
+}
+/**
+ * Materialises the tree at `treeRoot` from `primaryRoot` using
+ * `capability` ('none' = plain copy, already gated on --force-copy by
+ * the caller). The engine tree is cloned whole and its `obj-*` build
+ * directories removed afterwards — CoW removal is cheap, and per-entry
+ * recursion into a Firefox tree is fragile. A fresh `.fireforge/` is
+ * created with only `state.json` (when present) and the tree marker.
+ */
+export async function cloneTree(args) {
+    const { primaryRoot, treeRoot, name, capability, createdAt } = args;
+    const { mkdir, cp } = await import('node:fs/promises');
+    await mkdir(treeRoot, { recursive: true });
+    for (const entry of await readdir(primaryRoot)) {
+        if (isExcludedRootEntry(entry))
+            continue;
+        await cloneEntry(capability, join(primaryRoot, entry), join(treeRoot, entry));
+    }
+    // A cloned objdir embeds absolute topsrcdir/topobjdir paths back into
+    // the PRIMARY tree (mach-build-artifacts.ts parses exactly those), so
+    // in-tree builds/tests would silently operate against the primary —
+    // remove the clones; `tree` is read-verification only in 0.40.0.
+    const engineDir = join(treeRoot, 'engine');
+    if (await pathExists(engineDir)) {
+        for (const entry of await readdir(engineDir)) {
+            if (entry.startsWith('obj-')) {
+                await rm(join(engineDir, entry), { recursive: true, force: true });
+            }
+        }
+        // Defensive: never inherit a mid-operation git index lock.
+        await rm(join(engineDir, '.git', 'index.lock'), { force: true });
+    }
+    await mkdir(join(treeRoot, '.fireforge'), { recursive: true });
+    const stateJson = join(primaryRoot, '.fireforge', 'state.json');
+    if (await pathExists(stateJson)) {
+        await cp(stateJson, join(treeRoot, '.fireforge', 'state.json'));
+    }
+    const { engineHead, patchesFingerprint } = await computePrimaryFingerprint(primaryRoot);
+    const marker = {
+        schemaVersion: 1,
+        name,
+        primaryRoot,
+        createdAt,
+        engineHead,
+        patchesFingerprint,
+    };
+    await writeJson(join(treeRoot, '.fireforge', TREE_MARKER_FILENAME), marker);
+    return marker;
+}
+/** Lists trees with staleness against the current primary state. */
+export async function listTrees(primaryRoot) {
+    const treesDir = getTreesDir(primaryRoot);
+    if (!(await pathExists(treesDir)))
+        return [];
+    const current = await computePrimaryFingerprint(primaryRoot);
+    const entries = [];
+    for (const name of (await readdir(treesDir)).sort((a, b) => a.localeCompare(b))) {
+        if (name.endsWith('.lock'))
+            continue;
+        const path = join(treesDir, name);
+        const marker = await readTreeMarker(path);
+        if (!marker) {
+            entries.push({ name, path, createdAt: '(no marker)', staleness: 'unknown' });
+            continue;
+        }
+        const staleness = marker.engineHead !== current.engineHead
+            ? 'stale (engine advanced)'
+            : marker.patchesFingerprint !== current.patchesFingerprint
+                ? 'stale (patches changed)'
+                : 'fresh';
+        entries.push({ name, path, createdAt: marker.createdAt, staleness });
+    }
+    return entries;
+}
+/** Uses `kill(pid, 0)` — no signal sent, just an existence check. */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the live holder PID of a mkdir-style lock directory, if any.
+ * Reads the lock's `pid` file directly (line 1 = PID — the format
+ * `file-lock.ts` documents as stable) instead of exporting file-lock
+ * internals.
+ */
+async function liveLockHolder(lockPath) {
+    try {
+        const pidLine = (await readFile(join(lockPath, 'pid'), 'utf-8')).split('\n')[0] ?? '';
+        const pid = parseInt(pidLine.trim(), 10);
+        if (Number.isFinite(pid) && isProcessAlive(pid))
+            return pid;
+    }
+    catch {
+        // No lock / unreadable pid file — treat as not held.
+    }
+    return undefined;
+}
+/**
+ * Removes one tree. Refuses when a live process holds the tree's build
+ * or engine-session lock, and never deletes a path outside the trees
+ * directory (containment check before `rm -rf`).
+ */
+export async function removeTree(primaryRoot, name) {
+    assertValidTreeName(name);
+    const treesDir = getTreesDir(primaryRoot);
+    const treeRoot = resolve(treesDir, name);
+    if (!treeRoot.startsWith(treesDir + sep) || basename(treeRoot) !== name) {
+        throw new GeneralError(`Refusing to remove "${name}": resolved path escapes the trees directory.`);
+    }
+    if (!(await pathExists(treeRoot))) {
+        throw new GeneralError(`No verification tree named "${name}" exists under ${treesDir}.`);
+    }
+    for (const lockPath of [
+        join(treeRoot, '.fireforge-build.lock'),
+        join(treeRoot, '.fireforge', 'engine-session.lock'),
+    ]) {
+        const holder = await liveLockHolder(lockPath);
+        if (holder !== undefined) {
+            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${String(holder)}) holds ${lockPath}. ` +
+                'Wait for it to finish, then retry.');
+        }
+    }
+    await rm(treeRoot, { recursive: true, force: true });
+}

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

@@ -11,6 +11,20 @@
  */
 /** Filename used for the synthetic Firefox-globals shim source file. */
 export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
+/**
+ * Loose declarations for Firefox test-harness globals (mochitest
+ * browser-chrome and xpcshell), appended AFTER the composed
+ * Firefox-globals + consumer shim when `patchLint.checkJsTestFiles`
+ * extends the checkJs pass to patch-adopted test scripts (FORGE G5).
+ * Deliberately `any`-typed — the pragmatic posture matches the main
+ * shim. A consumer that wants TYPED harness members (so e.g. a call to
+ * a method the harness does not declare fails at the patch boundary)
+ * declares them in `patchLint.checkJsTestShim`; because that shim
+ * composes BEFORE this baseline and TypeScript resolves conflicting
+ * `declare var` redeclarations to the FIRST declaration, the typed
+ * consumer declaration wins over the loose fallback here.
+ */
+export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harness shim (loose baseline) \u2500\u2500\ndeclare var TestUtils: any;\ndeclare var BrowserTestUtils: any;\ndeclare var SpecialPowers: any;\ndeclare var EventUtils: any;\ndeclare var SimpleTest: any;\ndeclare var Assert: any;\ndeclare var gTestPath: string;\ndeclare var content: any;\ndeclare function add_task(task: (...args: any[]) => any): any;\ndeclare function add_setup(task: (...args: any[]) => any): any;\ndeclare function ok(condition: any, message?: string): void;\ndeclare function is(actual: any, expected: any, message?: string): void;\ndeclare function isnot(actual: any, expected: any, message?: string): void;\ndeclare function todo(condition: any, message?: string): void;\ndeclare function todo_is(actual: any, expected: any, message?: string): void;\ndeclare function info(message: string): void;\ndeclare function registerCleanupFunction(callback: (...args: any[]) => any): void;\ndeclare function waitForExplicitFinish(): void;\ndeclare function finish(): void;\ndeclare function do_get_profile(): any;\ndeclare function run_test(): any;\n\n";
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass
  * and the whole-project typecheck command. Each is a known false
@@ -24,6 +38,19 @@ export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
  * reason the operator couldn't infer from the docs.
  */
 export declare const SUPPRESSED_DIAGNOSTIC_CODES: ReadonlySet<number>;
+/**
+ * Undefined-free-identifier codes, split out of
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES} (FORGE F12). Unconditional
+ * suppression let a module reference a name with no import or declaration
+ * anywhere and still typecheck with 0 errors — the failure then surfaced
+ * as a runtime `ReferenceError`. Both flows now report these at a
+ * configurable severity (default `'warning'`: visible without breaking
+ * gates; genuine shim gaps are silenced by adding the global to
+ * `extraShim`, or per-run via the `'off'` setting).
+ */
+export declare const UNDEFINED_IDENTIFIER_CODES: ReadonlySet<number>;
+/** Hint appended to reported undefined-identifier diagnostics. */
+export declare const UNDEFINED_IDENTIFIER_HINT: string;
 /**
  * Result of {@link composeShimSource}: the source body to feed into
  * the TS host plus a flag indicating whether the user-supplied extra

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

@@ -128,6 +128,44 @@ declare var Localization: LocalizationShim;
 declare module 'resource:*';
 declare module 'chrome:*';
 
+`;
+/**
+ * Loose declarations for Firefox test-harness globals (mochitest
+ * browser-chrome and xpcshell), appended AFTER the composed
+ * Firefox-globals + consumer shim when `patchLint.checkJsTestFiles`
+ * extends the checkJs pass to patch-adopted test scripts (FORGE G5).
+ * Deliberately `any`-typed — the pragmatic posture matches the main
+ * shim. A consumer that wants TYPED harness members (so e.g. a call to
+ * a method the harness does not declare fails at the patch boundary)
+ * declares them in `patchLint.checkJsTestShim`; because that shim
+ * composes BEFORE this baseline and TypeScript resolves conflicting
+ * `declare var` redeclarations to the FIRST declaration, the typed
+ * consumer declaration wins over the loose fallback here.
+ */
+export const TEST_HARNESS_SHIM = `
+// ── FireForge test-harness shim (loose baseline) ──
+declare var TestUtils: any;
+declare var BrowserTestUtils: any;
+declare var SpecialPowers: any;
+declare var EventUtils: any;
+declare var SimpleTest: any;
+declare var Assert: any;
+declare var gTestPath: string;
+declare var content: any;
+declare function add_task(task: (...args: any[]) => any): any;
+declare function add_setup(task: (...args: any[]) => any): any;
+declare function ok(condition: any, message?: string): void;
+declare function is(actual: any, expected: any, message?: string): void;
+declare function isnot(actual: any, expected: any, message?: string): void;
+declare function todo(condition: any, message?: string): void;
+declare function todo_is(actual: any, expected: any, message?: string): void;
+declare function info(message: string): void;
+declare function registerCleanupFunction(callback: (...args: any[]) => any): void;
+declare function waitForExplicitFinish(): void;
+declare function finish(): void;
+declare function do_get_profile(): any;
+declare function run_test(): any;
+
 `;
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass
@@ -146,11 +184,26 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
     2306, // File '{0}' is not a module.
     2305, // Module '{0}' has no exported member '{1}'.
     2792, // Cannot find module '{0}'. Did you mean to set the 'moduleResolution' option...
-    2304, // Cannot find name '{0}'. (for globals we missed in the shim)
-    2552, // Cannot find name '{0}'. Did you mean '{1}'?
     2580, // Cannot find name '{0}'. Do you need to install type definitions...
     7016, // Could not find a declaration file for module '{0}'.
 ]);
+/**
+ * Undefined-free-identifier codes, split out of
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES} (FORGE F12). Unconditional
+ * suppression let a module reference a name with no import or declaration
+ * anywhere and still typecheck with 0 errors — the failure then surfaced
+ * as a runtime `ReferenceError`. Both flows now report these at a
+ * configurable severity (default `'warning'`: visible without breaking
+ * gates; genuine shim gaps are silenced by adding the global to
+ * `extraShim`, or per-run via the `'off'` setting).
+ */
+export const UNDEFINED_IDENTIFIER_CODES = new Set([
+    2304, // Cannot find name '{0}'.
+    2552, // Cannot find name '{0}'. Did you mean '{1}'?
+]);
+/** Hint appended to reported undefined-identifier diagnostics. */
+export const UNDEFINED_IDENTIFIER_HINT = '(undefined identifier — import or declare it, add the global to the extra shim, ' +
+    'or tune the "undefinedIdentifiers" setting)';
 /** Matches a lone triple-slash `/// <reference path="…" />` directive line. */
 const TRIPLE_SLASH_REFERENCE = /^\s*\/\/\/\s*<reference\s+path\s*=\s*["']([^"']+)["']\s*\/?>\s*$/;
 /**
@@ -211,8 +264,9 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
  */
 export async function composeShimSource(projectRoot, extraShimPath) {
+    const base = FIREFOX_GLOBALS_SHIM;
     if (!extraShimPath) {
-        return { source: FIREFOX_GLOBALS_SHIM, extraShimAppended: false };
+        return { source: base, extraShimAppended: false };
     }
     const absoluteShim = resolve(projectRoot, extraShimPath);
     if (!(await pathExists(absoluteShim))) {
@@ -222,7 +276,7 @@ export async function composeShimSource(projectRoot, extraShimPath) {
     const extra = await readText(absoluteShim);
     const inlinedExtra = await inlineTripleSlashReferences(extra, dirname(absoluteShim), new Set([absoluteShim]));
     return {
-        source: `${FIREFOX_GLOBALS_SHIM}\n// ── extraShim: ${extraShimPath} ──\n${inlinedExtra}`,
+        source: `${base}\n// ── extraShim: ${extraShimPath} ──\n${inlinedExtra}`,
         extraShimAppended: true,
     };
 }