@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/typecheck.js

@@ -1,433 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Whole-project TypeScript type checking driven by user-supplied
- * `jsconfig.json` paths. The engine behind the `fireforge typecheck`
- * command.
- *
- * Distinct from `patch-lint-checkjs.ts` (patch-hygiene): patchLint is
- * scoped, fireforge-controlled, and runs as part of `fireforge lint`.
- * This command runs whole projects with user-controlled compiler
- * options and is intended as a CI gate. The two share the Firefox
- * globals shim and suppressed-code list (via `typecheck-shim.ts`) so
- * a file that lints clean cannot fail typecheck for a reason the
- * operator could not have inferred from the docs.
- *
- * Loads the TypeScript compiler API via dynamic import so it is only
- * required when `typecheck.projects` is configured. TypeScript
- * remains a dev-dependency. If a user invokes `fireforge typecheck`
- * without installing it, the function returns a clear error pointing
- * at `npm install typescript`.
- */
-import { mkdir, readdir, rm } from 'node:fs/promises';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { toError } from '../utils/errors.js';
-import { pathExists } from '../utils/fs.js';
-import { sha256Hex } from '../utils/hash.js';
-import { verbose } from '../utils/logger.js';
-import { getPackageVersion } from '../utils/package-root.js';
-import { normalizePathSlashes } from '../utils/paths.js';
-import { withGeckoDomTypes } from './gecko-dom-types.js';
-import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
-/**
- * Sentinel string surfaced as a `TypecheckIssue.message` when the
- * project's jsconfig sets `checkJs: false`. Exported so tests can
- * pin the contract, since operators rely on it to spot opted-out projects
- * in CI logs.
- */
-export const CHECK_JS_DISABLED_NOTICE = 'Project sets "checkJs: false" — skipping (override the jsconfig to enable typecheck).';
-/**
- * Runs `fireforge typecheck` against every project listed in `cfg.projects`.
- *
- * Per-project flow:
- *   1. Read the jsconfig via the TS API. JSON parse / config-spec
- *      errors are surfaced as issues rather than thrown, because a single
- *      broken project must not abort the rest of the run.
- *   2. Compute final compiler options from the user's options. We
- *      only force `noEmit: true` (this is a typecheck, not a build).
- *      We honour `strict`, `target`, `lib`, `module`, `paths`,
- *      `include`, `exclude`. `allowJs` and `checkJs` default to
- *      `true` only when the user has not set them. If the user set
- *      `checkJs: false` we treat that as an explicit opt-out and
- *      skip the project with a single notice (see {@link CHECK_JS_DISABLED_NOTICE}).
- *   3. Inject the synthetic shim (built-in + optional extraShim) as
- *      a virtual root file that the custom CompilerHost serves.
- *   4. Build the program and collect semantic, syntactic, options,
- *      and global diagnostics. The patchLint flow only reads semantic +
- *      syntactic, which is fine for hygiene, but a CI gate needs the full
- *      set so misconfigured `lib`/`paths` entries fail loudly.
- *   5. Drop diagnostics whose code is in `SUPPRESSED_DIAGNOSTIC_CODES`
- *      and any diagnostic originating in the synthetic shim itself.
- *
- * @param projectRoot - Absolute project root. All paths in `cfg` are resolved against it.
- * @param cfg - Validated `typecheck` block from `fireforge.json`.
- * @returns One {@link TypecheckProjectResult} per entry in `cfg.projects`,
- *   in declared order. The CLI is responsible for printing the issues
- *   and computing the exit code.
- */
-export async function runTypecheck(projectRoot, cfg, runOptions = {}) {
-    // Dynamic import, so typescript stays a dev dependency. Same pattern
-    // as `patch-lint-checkjs.ts`. The empty-projects-array case is
-    // already rejected by config-validate, so we don't gate the import
-    // on `cfg.projects.length`.
-    let ts;
-    try {
-        ts = await import('typescript');
-    }
-    catch {
-        return cfg.projects.map((project) => ({
-            project,
-            issues: [
-                {
-                    file: '(typecheck)',
-                    line: 1,
-                    column: 1,
-                    code: 0,
-                    category: 'error',
-                    message: 'fireforge typecheck requires the "typescript" package. Run "npm install typescript" to enable type checking.',
-                    project,
-                },
-            ],
-            filesChecked: 0,
-        }));
-    }
-    // Compose the shim per project: the effective extraShim is the per-project
-    // override (a path, or `null` to opt out) when present, else the shared
-    // top-level extraShim. A project that narrows `lib`/`types` can opt out of
-    // a Gecko-lib shim hub that another project needs, so the composed shim is
-    // not injected identically everywhere. Compositions are cached by the
-    // resolved extraShim path so projects sharing a shim do not recompose it.
-    const shimCache = new Map();
-    const composeForProject = async (extraShim) => {
-        const key = extraShim ?? '';
-        const cached = shimCache.get(key);
-        if (cached !== undefined)
-            return cached;
-        const composed = await composeShimSource(projectRoot, extraShim, {
-            litTypes: cfg.litTypes,
-        });
-        if (composed.extraShimAppended) {
-            verbose(`typecheck: extra shim ${extraShim ?? ''} appended to Firefox globals shim`);
-        }
-        shimCache.set(key, composed.source);
-        return composed.source;
-    };
-    const results = [];
-    for (const projectPath of cfg.projects) {
-        const extraShim = resolveProjectExtraShim(cfg, projectPath);
-        let shimSource;
-        try {
-            shimSource = await composeForProject(extraShim);
-        }
-        catch (err) {
-            // A missing or unreadable shim fails only the project(s) that use it,
-            // not the whole run. Projects with a different (or no) shim still run.
-            const message = toError(err).message;
-            results.push({
-                project: projectPath,
-                issues: [
-                    {
-                        file: extraShim ?? '(typecheck)',
-                        line: 1,
-                        column: 1,
-                        code: 0,
-                        category: 'error',
-                        message,
-                        project: projectPath,
-                    },
-                ],
-                filesChecked: 0,
-            });
-            continue;
-        }
-        results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource, cfg.undefinedIdentifiers ?? 'warning', runOptions.noCache === true
-            ? undefined
-            : (runOptions.cacheDir ?? join(projectRoot, '.fireforge', 'typecheck'))));
-    }
-    return results;
-}
-/**
- * Resolves the effective extra shim for a single project: a `projectOverrides`
- * entry wins (a string path overrides, `null` opts out → `undefined`), else
- * the shared top-level `extraShim` applies.
- */
-function resolveProjectExtraShim(cfg, projectPath) {
-    const overrides = cfg.projectOverrides;
-    if (overrides && Object.hasOwn(overrides, projectPath)) {
-        const value = overrides[projectPath];
-        return value === null ? undefined : value;
-    }
-    return cfg.extraShim;
-}
-/** Runs typecheck for a single jsconfig path, isolating its failures. */
-async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource, undefinedIdentifiers = 'warning', cacheDir) {
-    const absConfig = resolve(projectRoot, projectPath);
-    if (!(await pathExists(absConfig))) {
-        return {
-            project: projectPath,
-            issues: [
-                {
-                    file: projectPath,
-                    line: 1,
-                    column: 1,
-                    code: 0,
-                    category: 'error',
-                    message: `jsconfig.json not found: ${projectPath} (resolved to ${absConfig})`,
-                    project: projectPath,
-                },
-            ],
-            filesChecked: 0,
-        };
-    }
-    // 1) Read the JSON config. ts.readConfigFile reports JSON-shape
-    // errors via the returned diagnostic. Missing files fall back to
-    // pathExists above, which gives a more directly actionable message.
-    const readResult = ts.readConfigFile(absConfig, (path) => ts.sys.readFile(path));
-    if (readResult.error) {
-        return {
-            project: projectPath,
-            issues: [diagnosticToIssue(ts, readResult.error, projectPath, projectPath)],
-            filesChecked: 0,
-        };
-    }
-    // 2) Parse the config content. This is what surfaces config-spec
-    // errors (unknown options, mismatched types in `compilerOptions`,
-    // bad `include` patterns, etc.), the TS5xxx codes. We surface them
-    // alongside semantic diagnostics so the operator sees the same
-    // output `tsc -p` would have produced.
-    const parsed = ts.parseJsonConfigFileContent(readResult.config, ts.sys, dirname(absConfig), 
-    /* existingOptions */ undefined, absConfig);
-    const issues = [];
-    for (const diag of parsed.errors) {
-        if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
-            continue;
-        issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
-    }
-    // 3) Honour explicit `checkJs: false`. The user has opted out for
-    // an IDE reason (likely "checkJs floods my workflow with non-actionable
-    // notes"). Flipping it on here would surface ~hundreds of issues that
-    // the operator already evaluated and rejected. Surface a single
-    // notice so it is visible in CI logs rather than silently passing.
-    const rawConfig = readResult.config;
-    if (rawConfig?.compilerOptions?.['checkJs'] === false) {
-        issues.push({
-            file: projectPath,
-            line: 1,
-            column: 1,
-            code: 0,
-            category: 'warning',
-            message: CHECK_JS_DISABLED_NOTICE,
-            project: projectPath,
-        });
-        return { project: projectPath, issues, filesChecked: parsed.fileNames.length };
-    }
-    // 4) Compute final compiler options. `noEmit: true` is forced, so we
-    // never write artifacts. `allowJs` / `checkJs` default to true
-    // *only* when unset (so a user can flip them off without us
-    // overriding). If the user set `allowJs: false` they're saying
-    // "don't even include JS in this typecheck", which is rare but
-    // legitimate (e.g. an isolated `.d.ts`-only project).
-    const options = {
-        ...parsed.options,
-        noEmit: true,
-        allowJs: parsed.options.allowJs ?? true,
-        checkJs: parsed.options.checkJs ?? true,
-        // Never the jsconfig's own incremental sidecar: a user jsconfig under
-        // `engine/` that sets `incremental` (or names a `tsBuildInfoFile`) would
-        // have this command drop a `.tsbuildinfo` inside the primary engine
-        // checkout, a second writer that invalidates a concurrent
-        // `fireforge test`'s engine fingerprint. FireForge's own build info
-        // lives under `.fireforge/typecheck/` instead (see below).
-        incremental: false,
-        // skipLibCheck is not forced. The user owns it via their jsconfig.
-    };
-    // `exactOptionalPropertyTypes` forbids assigning `undefined` to an
-    // optional `string`, so the sidecar path is dropped rather than unset.
-    delete options.tsBuildInfoFile;
-    // 5) The synthetic shim file. Use a project-rooted path with a
-    // hidden-style prefix so it is unlikely to collide with any real
-    // file, and never write it to disk. The CompilerHost below serves
-    // it from `shimSource` for `fileExists`/`readFile`/`getSourceFile`.
-    const projectDir = dirname(absConfig);
-    // Forward slashes on purpose: TypeScript normalizes every `fileName` it
-    // hands a CompilerHost, on every platform. A shim path carrying Windows
-    // separators never matches those callbacks, so the shim is not served (its
-    // globals report as undefined identifiers) and its own diagnostics are not
-    // filtered out below, so the pass reports failures that do not exist.
-    const shimPath = normalizePathSlashes(resolve(projectDir, `.fireforge-${SHIM_FILENAME}`));
-    const rootFiles = [...parsed.fileNames, shimPath];
-    const defaultHost = withGeckoDomTypes(ts, ts.createCompilerHost(options));
-    const host = {
-        ...defaultHost,
-        getSourceFile(fileName, languageVersion, onError, shouldCreate) {
-            if (fileName === shimPath) {
-                return ts.createSourceFile(fileName, shimSource, languageVersion, true);
-            }
-            return defaultHost.getSourceFile(fileName, languageVersion, onError, shouldCreate);
-        },
-        fileExists(fileName) {
-            if (fileName === shimPath)
-                return true;
-            return defaultHost.fileExists(fileName);
-        },
-        readFile(fileName) {
-            if (fileName === shimPath)
-                return shimSource;
-            return defaultHost.readFile(fileName);
-        },
-    };
-    // Incremental build info, keyed by everything outside the program's own
-    // files that can change a verdict: the composed shim, the TypeScript
-    // version, the compiler options, the undefined-identifier gate and the
-    // FireForge version. A change to any of them selects a different file,
-    // so a stale verdict is never replayed. Files inside the program are
-    // tracked by TypeScript's own per-file hashes in the build info.
-    const buildInfoFile = cacheDir === undefined
-        ? undefined
-        : await prepareBuildInfoFile(cacheDir, projectPath, {
-            shim: sha256Hex(shimSource),
-            typescript: ts.version,
-            fireforge: getPackageVersion(),
-            undefinedIdentifiers,
-            options,
-        });
-    let program;
-    let writeBuildInfo = () => undefined;
-    if (buildInfoFile === undefined) {
-        program = ts.createProgram(rootFiles, options, host);
-    }
-    else {
-        // Always check the entire project in root order. Restoring TypeScript's
-        // per-file semantic cache makes checkJs inference depend on the first
-        // invalidated importer and can both invent and hide diagnostics.
-        const builder = ts.createEmitAndSemanticDiagnosticsBuilderProgram(rootFiles, { ...options, incremental: true, tsBuildInfoFile: buildInfoFile }, withSourceFileVersions(host));
-        program = builder;
-        // Under noEmit, emit() writes the build info and nothing else.
-        writeBuildInfo = () => {
-            builder.emit();
-        };
-    }
-    // Collect the full diagnostic set. patchLint reads only semantic +
-    // syntactic, which is fine for hygiene but wrong for CI: a misconfigured
-    // `lib: ["es2015"]` or a missing `paths` target should fail
-    // typecheck loudly via getOptionsDiagnostics / getGlobalDiagnostics.
-    const allDiagnostics = [
-        ...program.getOptionsDiagnostics(),
-        ...program.getGlobalDiagnostics(),
-        ...program.getSyntacticDiagnostics(),
-        ...program.getSemanticDiagnostics(),
-    ];
-    for (const diag of allDiagnostics) {
-        if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
-            continue;
-        // Drop diagnostics that originate in the synthetic shim. Operators
-        // can't act on them and they would clutter CI logs.
-        if (diag.file?.fileName === shimPath)
-            continue;
-        if (UNDEFINED_IDENTIFIER_CODES.has(diag.code)) {
-            if (undefinedIdentifiers === 'off')
-                continue;
-            const issue = diagnosticToIssue(ts, diag, absConfig, projectPath);
-            issues.push({
-                ...issue,
-                category: undefinedIdentifiers,
-                message: `${issue.message} ${UNDEFINED_IDENTIFIER_HINT}`,
-            });
-            continue;
-        }
-        issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
-    }
-    writeBuildInfo();
-    verbose(`typecheck: ${projectPath} — analyzed ${parsed.fileNames.length} file(s), found ${issues.length} issue(s)`);
-    return {
-        project: projectPath,
-        issues,
-        filesChecked: parsed.fileNames.length,
-    };
-}
-/**
- * Stamps every source file with a content-hash version, which the
- * incremental builder requires and a plain compiler host never sets.
- * `ts.createIncrementalCompilerHost` does the same internally, but the
- * shim here is served by a custom host rather than read from disk.
- */
-function withSourceFileVersions(host) {
-    const getSourceFile = host.getSourceFile.bind(host);
-    return {
-        ...host,
-        getSourceFile(...args) {
-            const file = getSourceFile(...args);
-            if (file !== undefined) {
-                file.version = sha256Hex(file.text);
-            }
-            return file;
-        },
-    };
-}
-/**
- * Resolves the build-info path for one project and key, creating the cache
- * directory and removing the project's build info for any other key: a
- * shim or TypeScript change leaves the old file unreachable anyway.
- * @returns Absolute build-info path
- */
-async function prepareBuildInfoFile(cacheDir, projectPath, keyInputs) {
-    const slug = projectPath.replace(/[^A-Za-z0-9._-]+/g, '_');
-    const key = sha256Hex(JSON.stringify(keyInputs)).slice(0, 16);
-    const fileName = `${slug}-${key}.tsbuildinfo`;
-    await mkdir(cacheDir, { recursive: true });
-    for (const entry of await readdir(cacheDir)) {
-        if (entry !== fileName && entry.startsWith(`${slug}-`) && entry.endsWith('.tsbuildinfo')) {
-            await rm(join(cacheDir, entry), { force: true });
-        }
-    }
-    return join(cacheDir, fileName);
-}
-/**
- * Converts a TS Diagnostic to a TypecheckIssue. The `fallbackFile`
- * is used when the diagnostic carries no source file (typical for
- * options diagnostics). It is typically the absolute jsconfig path or
- * the project-relative form for surface-level errors. `project` is
- * threaded through so the CLI can group issues by project without
- * a second pass.
- */
-function diagnosticToIssue(ts, diag, fallbackFile, project) {
-    let file = fallbackFile;
-    let line = 1;
-    let column = 1;
-    if (diag.file) {
-        file = diag.file.fileName;
-        if (typeof diag.start === 'number') {
-            const lc = diag.file.getLineAndCharacterOfPosition(diag.start);
-            line = lc.line + 1;
-            column = lc.character + 1;
-        }
-    }
-    const message = typeof diag.messageText === 'string'
-        ? diag.messageText
-        : ts.flattenDiagnosticMessageText(diag.messageText, '\n');
-    // Suggestion + Message categories collapse to 'warning'. Only
-    // Error stays an error. This matches what the CLI then displays.
-    const category = diag.category === ts.DiagnosticCategory.Error ? 'error' : 'warning';
-    return {
-        file,
-        line,
-        column,
-        code: diag.code,
-        category,
-        message,
-        project,
-    };
-}
-/**
- * Converts an absolute path to a path relative to the project root,
- * for display in CLI output. Falls back to the absolute path when
- * the path lies outside the root (e.g. a `node_modules` symlinked
- * from elsewhere). Exposed for tests and the CLI.
- */
-export function relativeForDisplay(projectRoot, absoluteFile) {
-    if (!isAbsolute(absoluteFile))
-        return absoluteFile;
-    const rel = relative(projectRoot, absoluteFile);
-    if (rel === '' || rel.startsWith('..'))
-        return absoluteFile;
-    return rel;
-}

package/dist/src/core/wire-destroy.d.ts

@@ -1,25 +0,0 @@
-/**
- * browser-init.js: destroy expression in onUnload()/uninit().
- */
-/**
- * AST-based implementation: finds onUnload()/uninit() method body and
- * inserts the destroy block at the top (LIFO ordering).
- *
- * `marker` is prefixed to the generated comment so wire-generated edits
- * carry the patch-lint `// <MARKER>:` signature `lintModificationComments`
- * looks for.
- */
-export declare function addDestroyAST(content: string, expression: string, marker?: string): string;
-/**
- * Regex/line-based fallback implementation.
- */
-export declare function legacyAddDestroy(content: string, expression: string, marker?: string): string;
-/**
- * Adds a destroy expression to the top of onUnload() or uninit() in
- * browser-init.js (LIFO ordering, newest first).
- *
- * @param engineDir - Engine source root
- * @param expression - The destroy expression (e.g., "MyComponent.destroy()")
- * @returns true if added, false if already present
- */
-export declare function addDestroyToBrowserInit(engineDir: string, expression: string, marker?: string): Promise<boolean>;

package/dist/src/core/wire-destroy.js

@@ -1,126 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * browser-init.js: destroy expression in onUnload()/uninit().
- */
-import { join } from 'node:path';
-import MagicString from 'magic-string';
-import { GeneralError } from '../errors/base.js';
-import { BuildError } from '../errors/build.js';
-import { pathExists, readText, writeText } from '../utils/fs.js';
-import { escapeRegex } from '../utils/regex.js';
-import { asEstree, detectIndent, parseScript } from './ast-utils.js';
-import { isInternalInvariantFailure, withParserFallback } from './parser-fallback.js';
-import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
-const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
-const DEFAULT_MARKER = 'FIREFORGE:';
-/**
- * AST-based implementation: finds onUnload()/uninit() method body and
- * inserts the destroy block at the top (LIFO ordering).
- *
- * `marker` is prefixed to the generated comment so wire-generated edits
- * carry the patch-lint `// <MARKER>:` signature `lintModificationComments`
- * looks for.
- */
-export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
-    const name = extractNameFromExpression(expression);
-    // See wire-init.ts for the rationale: the template interpolates the
-    // expression verbatim, so a bare `Foo.bar` compiled to `Foo.bar;`
-    // (a property reference) instead of `Foo.bar();`. `coerceToCall`
-    // appends `()` when absent so the emitted block always invokes the
-    // teardown hook the operator asked for.
-    const callExpression = coerceToCall(expression);
-    const ast = parseScript(content);
-    const ms = new MagicString(content);
-    const body = findMethodBody(ast, ['onUnload', 'uninit']);
-    if (!body) {
-        throw new BuildError('Could not find onUnload/uninit method body via AST');
-    }
-    // Insert at top of method body (LIFO ordering)
-    // `noUncheckedIndexedAccess` makes this `Statement | undefined`. Narrow
-    // before casting rather than laundering the undefined through the cast.
-    const firstRaw = body.body[0];
-    const firstStmt = firstRaw ? asEstree(firstRaw) : undefined;
-    let insertPos;
-    let indent;
-    if (firstStmt) {
-        insertPos = firstStmt.start;
-        indent = detectIndent(content, firstStmt.start);
-    }
-    else {
-        // Empty method body: insert after opening {
-        insertPos = body.start + 1;
-        indent = '    ';
-    }
-    const block = [
-        `${indent}// ${marker} wire-destroy ${name}`,
-        `${indent}try {`,
-        `${indent}  if (typeof ${name} !== "undefined") {`,
-        `${indent}    ${callExpression};`,
-        `${indent}  }`,
-        `${indent}} catch (e) {`,
-        `${indent}  console.error("${name} destroy failed:", e);`,
-        `${indent}}`,
-    ].join('\n');
-    ms.appendRight(insertPos, block + '\n');
-    return ms.toString();
-}
-/**
- * Regex/line-based fallback implementation.
- */
-export function legacyAddDestroy(content, expression, marker = DEFAULT_MARKER) {
-    const name = extractNameFromExpression(expression);
-    // Match the AST path on the call-coercion contract so fallback vs AST
-    // emits identical blocks (see wire-init.ts).
-    const callExpression = coerceToCall(expression);
-    const lines = content.split('\n');
-    const destroyRegex = /\b(?:async\s+)?(onUnload|uninit)\s*[(:]/;
-    const found = findMethodBraceIndex(lines, destroyRegex, { requireBrace: true });
-    if (!found) {
-        throw new GeneralError('Could not find "onUnload" or "uninit" method in browser-init.js.\n' +
-            'FireForge was looking for a signature matching: \\b(?:async\\s+)?(onUnload|uninit)\\s*[(:]');
-    }
-    const insertIndex = found.braceIndex + 1;
-    const block = [
-        `    // ${marker} wire-destroy ${name}`,
-        `    try {`,
-        `      if (typeof ${name} !== "undefined") {`,
-        `        ${callExpression};`,
-        `      }`,
-        `    } catch (e) {`,
-        `      console.error("${name} destroy failed:", e);`,
-        `    }`,
-    ];
-    lines.splice(insertIndex, 0, ...block);
-    return lines.join('\n');
-}
-/**
- * Adds a destroy expression to the top of onUnload() or uninit() in
- * browser-init.js (LIFO ordering, newest first).
- *
- * @param engineDir - Engine source root
- * @param expression - The destroy expression (e.g., "MyComponent.destroy()")
- * @returns true if added, false if already present
- */
-export async function addDestroyToBrowserInit(engineDir, expression, marker = DEFAULT_MARKER) {
-    validateWireName(expression, 'destroy expression');
-    const filePath = join(engineDir, BROWSER_INIT_JS);
-    if (!(await pathExists(filePath))) {
-        throw new GeneralError(`${BROWSER_INIT_JS} not found in engine`);
-    }
-    const content = await readText(filePath);
-    // Idempotency check: look for the coerced (call) form because that is
-    // what the emitter writes. Matching against the raw input would miss a
-    // bare `X.destroy` invocation that coercion already persisted as
-    // `X.destroy()`.
-    const callExpression = coerceToCall(expression);
-    const destroyPattern = new RegExp(`(?:^|\\W)${escapeRegex(callExpression)}\\s*;?\\s*$`, 'm');
-    if (destroyPattern.test(content)) {
-        return false;
-    }
-    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression, marker), () => legacyAddDestroy(content, expression, marker), BROWSER_INIT_JS, isInternalInvariantFailure);
-    if (usedFallback) {
-        assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
-    }
-    await writeText(filePath, value);
-    return true;
-}

package/dist/src/core/wire-dom-fragment.d.ts

@@ -1,44 +0,0 @@
-/**
- * Top-level chrome document: DOM fragment insertion.
- *
- * Default target is `browser/base/content/browser.xhtml`. Forks that replace
- * browser.xhtml with a custom top-level chrome document pass the replacement
- * path in via `targetPath`. The insertion logic is shape-agnostic (looks for
- * `#include browser-sets.inc`, then falls back to `<html:body>`), so any
- * browser.xhtml-shaped xhtml works.
- */
-export declare const DEFAULT_DOM_TARGET = "browser/base/content/browser.xhtml";
-/**
- * Tokenizer-based implementation for DOM fragment insertion.
- */
-export declare function addDomFragmentTokenized(content: string, includeDirective: string): string;
-/**
- * Dry-run precheck for `addDomFragment`. Reads the resolved chrome document
- * and verifies it either already contains the `#include` directive (the
- * idempotent-skip case) or offers a locatable insertion point via
- * {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}. Throws the
- * same `Could not find insertion point in chrome document` error the real
- * run would throw when neither condition holds.
- *
- * Without it, `wire --dry-run` previews a plausible mutation plan while the
- * real run throws on the same arguments, because only the real run called
- * the insertion helpers.
- */
-export declare function probeDomFragmentInsertionPoint(engineDir: string, domFilePath: string, targetPath?: string): Promise<void>;
-/**
- * Inserts a `#include` directive for an `.inc.xhtml` file into the top-level
- * chrome document (default: `browser/base/content/browser.xhtml`), before
- * `#include browser-sets.inc`.
- *
- * If the file's content was previously inlined (detected by root element id=),
- * the inlined block is automatically replaced with the `#include` directive.
- *
- * @param engineDir - Engine source root
- * @param domFilePath - Path to the `.inc.xhtml` file relative to engine root
- * @param targetPath - Chrome document to insert into, relative to engine
- *   root. Defaults to {@link DEFAULT_DOM_TARGET}. Forks that replace
- *   browser.xhtml with a custom top-level chrome document pass the
- *   replacement path here.
- * @returns true if inserted, false if already present
- */
-export declare function addDomFragment(engineDir: string, domFilePath: string, targetPath?: string): Promise<boolean>;