@hominis/fireforge 0.15.6 → 0.15.8

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

@@ -4,9 +4,9 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
-import { isExplicitAbsolutePath } from '../utils/paths.js';
-import { isArray, isBoolean, isObject, isString } from '../utils/validation.js';
+import { isArray, isObject, isString } from '../utils/validation.js';
 import { FIREFORGE_DIR } from './config.js';
+import { parseCustomConfig } from './furnace-config-custom.js';
 import { validateRuntimeVariables, validateTokenHostDocuments } from './furnace-config-tokens.js';
 import { resolveFtlDir } from './furnace-constants.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
@@ -89,43 +89,6 @@ function parseOverrideConfig(data, name) {
         ...(isString(data['baseCommit']) ? { baseCommit: data['baseCommit'] } : {}),
     };
 }
-/**
- * Validates a custom component config object.
- * @param data - Raw data to validate
- * @param name - Component name for error messages
- */
-function parseCustomConfig(data, name) {
-    if (!isString(data['description'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.description" must be a string`);
-    }
-    if (!isString(data['targetPath'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must be a string`);
-    }
-    if (data['targetPath'].includes('..') || data['targetPath'].includes('\0')) {
-        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not contain ".." or null bytes (path traversal)`);
-    }
-    if (isExplicitAbsolutePath(data['targetPath'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not be an absolute path`);
-    }
-    if (!isBoolean(data['register'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.register" must be a boolean`);
-    }
-    if (!isBoolean(data['localized'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.localized" must be a boolean`);
-    }
-    if (data['composes'] !== undefined) {
-        parseStringArray(data['composes'], `${name}.composes`);
-    }
-    return {
-        description: data['description'],
-        targetPath: data['targetPath'],
-        register: data['register'],
-        localized: data['localized'],
-        ...(data['composes'] !== undefined
-            ? { composes: parseStringArray(data['composes'], `${name}.composes`) }
-            : {}),
-    };
-}
 /** The current (and only) config schema version. */
 const CURRENT_CONFIG_VERSION = 1;
 /**

package/dist/src/core/furnace-validate-accessibility.d.ts

@@ -1,6 +1,13 @@
-import type { ValidationIssue } from '../types/furnace.js';
+import type { CustomComponentConfig, ValidationIssue } from '../types/furnace.js';
 /**
  * Validates accessibility patterns in a component's .mjs file.
  * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
+ *
+ * @param customConfig - When the component is custom, its matching entry
+ *   from `furnace.json`. Used to skip the `no-keyboard-handler` warning
+ *   when the component declares keyboard coverage either explicitly
+ *   (`keyboardCovered: true`) or via `composes` naming a native-interactive
+ *   inner element. Optional so stock/override callers and test fixtures
+ *   without config in scope can continue to call without changes.
  */
-export declare function validateAccessibility(componentDir: string, tagName: string): Promise<ValidationIssue[]>;
+export declare function validateAccessibility(componentDir: string, tagName: string, customConfig?: CustomComponentConfig): Promise<ValidationIssue[]>;

package/dist/src/core/furnace-validate-accessibility.js

@@ -1,12 +1,19 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasGenericInteractiveElement, hasPositiveTabindex, hasTemplateClickHandler, hasTemplateClickOnSyntheticInteractive, hasTemplateKeyboardHandler, hasUnlabelledFormInput, } from './furnace-validate-helpers.js';
+import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasGenericInteractiveElement, hasPositiveTabindex, hasTemplateClickHandler, hasTemplateClickOnSyntheticInteractive, hasTemplateKeyboardHandler, hasUnlabelledFormInput, isKeyboardCoveredByComposition, } from './furnace-validate-helpers.js';
 /**
  * Validates accessibility patterns in a component's .mjs file.
  * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
+ *
+ * @param customConfig - When the component is custom, its matching entry
+ *   from `furnace.json`. Used to skip the `no-keyboard-handler` warning
+ *   when the component declares keyboard coverage either explicitly
+ *   (`keyboardCovered: true`) or via `composes` naming a native-interactive
+ *   inner element. Optional so stock/override callers and test fixtures
+ *   without config in scope can continue to call without changes.
  */
-export async function validateAccessibility(componentDir, tagName) {
+export async function validateAccessibility(componentDir, tagName, customConfig) {
     const mjsPath = join(componentDir, `${tagName}.mjs`);
     if (!(await pathExists(mjsPath)))
         return [];
@@ -22,8 +29,15 @@ export async function validateAccessibility(componentDir, tagName) {
     // platform, so a duplicate keyboard handler would usually double-fire.
     // Only flag synthetic markup (e.g. `<div @click>`) where the activation
     // path has to be wired manually.
+    //
+    // A wrapper component whose `composes` entry lists a native-interactive
+    // tag (or that sets `keyboardCovered: true`) is treated the same way:
+    // activation flows through the inner element and a duplicate handler on
+    // the wrapper would either no-op or fire twice alongside the child's
+    // built-in keyboard path.
     const hasClickOnSynthetic = hasTemplateClickOnSyntheticInteractive(content);
-    if (hasClickOnSynthetic && !hasKeyboardHandler) {
+    const keyboardCovered = isKeyboardCoveredByComposition(customConfig);
+    if (hasClickOnSynthetic && !hasKeyboardHandler && !keyboardCovered) {
         issues.push(createIssue(tagName, 'warning', 'no-keyboard-handler', 'Interactive element has @click but no keyboard event handler (@keydown/@keypress/@keyup).'));
     }
     if (containsHardcodedTemplateText(content)) {

package/dist/src/core/furnace-validate-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, FurnaceConfig, ValidationIssue } from '../types/furnace.js';
+import type { ComponentType, CustomComponentConfig, FurnaceConfig, ValidationIssue } from '../types/furnace.js';
 /** Creates a normalized validation issue object. */
 export declare function createIssue(component: string, severity: ValidationIssue['severity'], check: ValidationIssue['check'], message: string): ValidationIssue;
 /** Detects whether template or script content assigns an ARIA role. */
@@ -13,6 +13,18 @@ export declare function hasUnlabelledFormInput(content: string): boolean;
 export declare function hasTemplateClickHandler(content: string): boolean;
 /** Detects Lit-style template keyboard handlers. */
 export declare function hasTemplateKeyboardHandler(content: string): boolean;
+/**
+ * Returns true when `customConfig` declares that the component's keyboard
+ * activation path is covered by a wrapped native-interactive inner element,
+ * either through an explicit opt-out (`keyboardCovered: true`) or by
+ * composing a tag that lives in {@link NATIVE_CLICK_INTERACTIVE_TAGS}.
+ *
+ * Uses `.some` rather than `.every` so that a wrapper composing e.g.
+ * `['moz-button', 'my-tooltip']` still skips the warning: the keyboard
+ * activation path flows through the button, even if other composed
+ * children are synthetic.
+ */
+export declare function isKeyboardCoveredByComposition(customConfig: CustomComponentConfig | undefined): boolean;
 /**
  * Returns true when `content` has at least one `@click=${...}` handler on a
  * *synthetic* interactive element (e.g. `<div @click>`), which lacks native

package/dist/src/core/furnace-validate-helpers.js

@@ -76,6 +76,25 @@ const NATIVE_CLICK_INTERACTIVE_TAGS = new Set([
     'moz-radio-group',
     'moz-menulist',
 ]);
+/**
+ * Returns true when `customConfig` declares that the component's keyboard
+ * activation path is covered by a wrapped native-interactive inner element,
+ * either through an explicit opt-out (`keyboardCovered: true`) or by
+ * composing a tag that lives in {@link NATIVE_CLICK_INTERACTIVE_TAGS}.
+ *
+ * Uses `.some` rather than `.every` so that a wrapper composing e.g.
+ * `['moz-button', 'my-tooltip']` still skips the warning: the keyboard
+ * activation path flows through the button, even if other composed
+ * children are synthetic.
+ */
+export function isKeyboardCoveredByComposition(customConfig) {
+    if (!customConfig)
+        return false;
+    if (customConfig.keyboardCovered === true)
+        return true;
+    const composes = customConfig.composes ?? [];
+    return composes.some((tag) => NATIVE_CLICK_INTERACTIVE_TAGS.has(tag));
+}
 /**
  * Returns true when `content` has at least one `@click=${...}` handler on a
  * *synthetic* interactive element (e.g. `<div @click>`), which lacks native

package/dist/src/core/furnace-validate-registration.d.ts

@@ -35,10 +35,12 @@ export declare function validateJarMnEntries(root: string, config: FurnaceConfig
  * linked in at least one chrome host document. Without the link, tokens
  * silently resolve to nothing at runtime.
  *
- * Forks with multiple chrome host documents (e.g. `mybrowser.xhtml` beside
- * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
- * furnace.json; the warning fires only when NONE of the configured
- * documents link the tokens CSS.
+ * Scan set is the union of (a) the configured `tokenHostDocuments` (or
+ * the upstream default when unset) and (b) any `browser/base/content/*.xhtml`
+ * document that references `tagName` — the auto-detection path catches
+ * forks that mount components from a replacement chrome document without
+ * having configured `tokenHostDocuments`. The warning fires only when
+ * NONE of the documents in the final scan set link the tokens CSS.
  */
 export declare function validateTokenLink(componentDir: string, tagName: string, root: string, tokenPrefix?: string, tokenHostDocuments?: string[]): Promise<ValidationIssue[]>;
 /**

package/dist/src/core/furnace-validate-registration.js

@@ -211,15 +211,73 @@ export async function validateJarMnEntries(root, config) {
  * `tokenHostDocuments` is not configured in furnace.json.
  */
 const DEFAULT_TOKEN_HOST_DOCUMENTS = ['browser/base/content/browser.xhtml'];
+/**
+ * Directory scanned for additional chrome host documents that mount the
+ * component under audit. Kept narrow (top-level `browser/base/content/`)
+ * so the auto-detection stays cheap and only triggers on the well-known
+ * location forks use for replacement chrome documents.
+ */
+const AUTO_DETECT_HOST_DIR = 'browser/base/content';
+/**
+ * Scans `browser/base/content/*.xhtml` for chrome documents that reference
+ * `tagName`. Returned paths are engine-relative and deduplicated against
+ * `already`, so callers can merge them with the caller-configured set
+ * without producing double entries in warning output.
+ *
+ * Motivating case: a fork that mounts a custom element from its own
+ * top-level chrome document (e.g. `mybrowser.xhtml`) without setting
+ * `tokenHostDocuments`. The stock `browser.xhtml` was the only thing
+ * scanned, so the tokens CSS link in the ACTUAL host document went
+ * unnoticed and the warning false-fired.
+ *
+ * @param engineDir Absolute engine root.
+ * @param tagName Custom element tag the CSS belongs to.
+ * @param already Paths already in the scan set (POSIX, engine-relative).
+ */
+async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
+    const contentDir = join(engineDir, AUTO_DETECT_HOST_DIR);
+    if (!(await pathExists(contentDir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(contentDir);
+    }
+    catch {
+        return [];
+    }
+    const alreadySet = new Set(already);
+    const detected = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.xhtml'))
+            continue;
+        const relPath = `${AUTO_DETECT_HOST_DIR}/${entry}`;
+        if (alreadySet.has(relPath))
+            continue;
+        const absPath = join(contentDir, entry);
+        let content;
+        try {
+            content = await readText(absPath);
+        }
+        catch {
+            continue;
+        }
+        if (content.includes(tagName)) {
+            detected.push(relPath);
+        }
+    }
+    return detected;
+}
 /**
  * Validates that components using design tokens have the tokens CSS
  * linked in at least one chrome host document. Without the link, tokens
  * silently resolve to nothing at runtime.
  *
- * Forks with multiple chrome host documents (e.g. `mybrowser.xhtml` beside
- * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
- * furnace.json; the warning fires only when NONE of the configured
- * documents link the tokens CSS.
+ * Scan set is the union of (a) the configured `tokenHostDocuments` (or
+ * the upstream default when unset) and (b) any `browser/base/content/*.xhtml`
+ * document that references `tagName` — the auto-detection path catches
+ * forks that mount components from a replacement chrome document without
+ * having configured `tokenHostDocuments`. The warning fires only when
+ * NONE of the documents in the final scan set link the tokens CSS.
  */
 export async function validateTokenLink(componentDir, tagName, root, tokenPrefix, tokenHostDocuments) {
     const issues = [];
@@ -233,7 +291,7 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
     if (!cssContent.includes(tokenPrefix))
         return issues;
     const { engine: engineDir } = getProjectPaths(root);
-    const hostDocuments = tokenHostDocuments && tokenHostDocuments.length > 0
+    const configuredHosts = tokenHostDocuments && tokenHostDocuments.length > 0
         ? tokenHostDocuments
         : DEFAULT_TOKEN_HOST_DOCUMENTS;
     let tokensCssFile;
@@ -247,6 +305,8 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
         warn(`Could not resolve token CSS link target for ${tagName} during validation: ${reason}`);
         return issues;
     }
+    const autoDetected = await autoDetectTokenHostDocuments(engineDir, tagName, configuredHosts);
+    const hostDocuments = [...configuredHosts, ...autoDetected];
     const checkedDocuments = [];
     let anyLinks = false;
     for (const relDocPath of hostDocuments) {
@@ -268,7 +328,7 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
             component: tagName,
             severity: 'warning',
             check: 'missing-token-link',
-            message: `Component uses ${tokenPrefix}* tokens but none of the configured chrome host documents (${docsList}) link ${tokensCssFile}. Tokens will silently resolve to nothing. Configure additional hosts via furnace.json "tokenHostDocuments" if needed.`,
+            message: `Component uses ${tokenPrefix}* tokens but none of the scanned chrome host documents (${docsList}) link ${tokensCssFile}. Tokens will silently resolve to nothing. Configure additional hosts via furnace.json "tokenHostDocuments" if needed.`,
         });
     }
     return issues;

package/dist/src/core/furnace-validate-structure.js

@@ -39,14 +39,18 @@ export async function validateStructure(componentDir, tagName, type, customConfi
     // Localized custom components must have a {tag}.ftl file. Without one,
     // apply silently deploys nothing for the locale and the runtime
     // localization payload is empty, which is hard to spot in review.
-    if (type === 'custom' && customConfig?.localized) {
+    //
+    // Components that declare `sharedFtl` participate in a pre-existing
+    // feature-scoped bundle, so there is no per-component .ftl to require —
+    // the shared file is owned by whoever authored the feature bundle.
+    if (type === 'custom' && customConfig?.localized && !customConfig.sharedFtl) {
         const ftlPath = join(componentDir, `${tagName}.ftl`);
         if (!(await pathExists(ftlPath))) {
             issues.push({
                 component: tagName,
                 severity: 'error',
                 check: 'missing-ftl',
-                message: `Component is marked localized: true but ${tagName}.ftl is missing. Create the file or set localized: false in furnace.json.`,
+                message: `Component is marked localized: true but ${tagName}.ftl is missing. Create the file, set localized: false in furnace.json, or switch to sharedFtl.`,
             });
         }
     }

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

@@ -37,10 +37,13 @@ function buildOverrideVersionDriftIssues(config, currentVersion, tagName) {
 export async function validateComponent(componentDir, tagName, type, config, root, options) {
     const issues = [];
     // Pass the matching custom config so structure validation can enforce
-    // the .ftl-when-localized invariant. Non-custom validations ignore the
+    // the .ftl-when-localized invariant and accessibility validation can
+    // recognize wrapper-over-native components (via `composes` or an
+    // explicit `keyboardCovered` opt-out). Non-custom validations ignore the
     // parameter, so this is a no-op for stock and override components.
-    issues.push(...(await validateStructure(componentDir, tagName, type, type === 'custom' ? config?.custom[tagName] : undefined)));
-    issues.push(...(await validateAccessibility(componentDir, tagName)));
+    const customConfigForTag = type === 'custom' ? config?.custom[tagName] : undefined;
+    issues.push(...(await validateStructure(componentDir, tagName, type, customConfigForTag)));
+    issues.push(...(await validateAccessibility(componentDir, tagName, customConfigForTag)));
     issues.push(...(await validateCompatibility(componentDir, tagName, type, config, root)));
     if (root && config && type === 'override') {
         const forgeConfig = await loadConfig(root);

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

@@ -27,3 +27,47 @@ export interface BuildArtifactCheck {
 export declare function hasBuildArtifacts(engineDir: string): Promise<BuildArtifactCheck>;
 /** Builds a user-facing explanation when detected build artifacts belong to another workspace. */
 export declare function buildArtifactMismatchMessage(engineDir: string, buildCheck: BuildArtifactCheck, commandName: string): string | undefined;
+/**
+ * Outcome of an in-place mozinfo.json rewrite attempt. A successful rewrite
+ * returns the paths written; a refused rewrite returns a human-readable
+ * reason so the build flow can surface it alongside the original mismatch
+ * message before falling back to the clean-rebuild instruction.
+ */
+export interface MozinfoRewriteResult {
+    /** Whether mozinfo.json was patched in place. */
+    rewritten: boolean;
+    /** Reason the rewrite was refused (populated when `rewritten === false`). */
+    reason?: string;
+    /** New `topsrcdir` value written to disk (populated on success). */
+    newTopsrcdir?: string;
+    /** New `topobjdir` value written to disk (populated on success). */
+    newTopobjdir?: string;
+    /** New `mozconfig` value written to disk (populated on success when it lived inside topsrcdir). */
+    newMozconfig?: string;
+}
+/**
+ * Safe-relocation rewriter for mozinfo.json under the active obj-* tree.
+ *
+ * Firefox build artefacts bake the topsrcdir into many generated files
+ * (Makefiles, config.status, backend.mk, .deps dependency files — anything
+ * produced by `mach configure`). A fresh `mach configure` rebuilds those
+ * from the top, so the rewriter only needs to patch the one file `mach`
+ * reads to learn where its checkout actually lives. Once mozinfo.json
+ * agrees with the on-disk layout, `mach configure` regenerates the rest.
+ *
+ * Safety rules — the rewrite is refused when any of them are violated:
+ *   - `topsrcdir` and `topobjdir` must both be present and non-empty.
+ *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`; a non-in-tree
+ *     objdir means the previous workspace was configured differently,
+ *     so a blind prefix-rewrite could point mach at the wrong tree.
+ *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`; if it
+ *     is not, the objDir name itself changed and we cannot prove safety.
+ *
+ * When any rule trips, the caller should fall back to the clean-rebuild
+ * instruction — that's always a correct (if expensive) recovery path.
+ *
+ * @param engineDir Absolute path to the current engine checkout.
+ * @param objDir Name of the obj-* directory to rewrite against.
+ * @returns Result object; callers inspect `rewritten` and surface `reason`.
+ */
+export declare function attemptMozinfoRewrite(engineDir: string, objDir: string): Promise<MozinfoRewriteResult>;

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

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 import { toError } from '../utils/errors.js';
-import { pathExists, readJson } from '../utils/fs.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { isObject, isString } from '../utils/validation.js';
 function validateBuildMozinfo(data) {
@@ -112,6 +112,107 @@ export function buildArtifactMismatchMessage(engineDir, buildCheck, commandName)
     }
     return (`${commandName} cannot use copied or relocated build artifacts whose metadata still points at a different Firefox workspace.\n\n` +
         `${details.join('\n')}\n\n` +
-        'Delete the stale obj-* directory in this workspace and run "fireforge build" again so mach regenerates build metadata for the current checkout.');
+        'Delete the stale obj-* directory in this workspace and run "fireforge build" again so mach regenerates build metadata for the current checkout.\n' +
+        'If the workspace was simply moved (same tree, different prefix), "fireforge build --rewrite-mozinfo" will patch mozinfo.json paths in place and run mach configure instead of scrubbing the whole tree.');
+}
+/**
+ * Safe-relocation rewriter for mozinfo.json under the active obj-* tree.
+ *
+ * Firefox build artefacts bake the topsrcdir into many generated files
+ * (Makefiles, config.status, backend.mk, .deps dependency files — anything
+ * produced by `mach configure`). A fresh `mach configure` rebuilds those
+ * from the top, so the rewriter only needs to patch the one file `mach`
+ * reads to learn where its checkout actually lives. Once mozinfo.json
+ * agrees with the on-disk layout, `mach configure` regenerates the rest.
+ *
+ * Safety rules — the rewrite is refused when any of them are violated:
+ *   - `topsrcdir` and `topobjdir` must both be present and non-empty.
+ *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`; a non-in-tree
+ *     objdir means the previous workspace was configured differently,
+ *     so a blind prefix-rewrite could point mach at the wrong tree.
+ *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`; if it
+ *     is not, the objDir name itself changed and we cannot prove safety.
+ *
+ * When any rule trips, the caller should fall back to the clean-rebuild
+ * instruction — that's always a correct (if expensive) recovery path.
+ *
+ * @param engineDir Absolute path to the current engine checkout.
+ * @param objDir Name of the obj-* directory to rewrite against.
+ * @returns Result object; callers inspect `rewritten` and surface `reason`.
+ */
+export async function attemptMozinfoRewrite(engineDir, objDir) {
+    const mozinfoPath = join(engineDir, objDir, 'mozinfo.json');
+    if (!(await pathExists(mozinfoPath))) {
+        return { rewritten: false, reason: 'mozinfo.json not found in obj directory' };
+    }
+    let raw;
+    try {
+        raw = await readJson(mozinfoPath);
+    }
+    catch (error) {
+        return { rewritten: false, reason: `mozinfo.json is unreadable: ${toError(error).message}` };
+    }
+    if (!isObject(raw)) {
+        return { rewritten: false, reason: 'mozinfo.json is not a JSON object' };
+    }
+    let mozinfo;
+    try {
+        mozinfo = validateBuildMozinfo(raw);
+    }
+    catch (error) {
+        return { rewritten: false, reason: toError(error).message };
+    }
+    const oldSrc = mozinfo.topsrcdir;
+    const oldObj = mozinfo.topobjdir;
+    if (!oldSrc || !oldObj) {
+        return {
+            rewritten: false,
+            reason: 'mozinfo.json is missing topsrcdir or topobjdir; cannot rewrite safely',
+        };
+    }
+    const oldSrcResolved = resolve(oldSrc);
+    const oldObjResolved = resolve(oldObj);
+    const insideTree = oldObjResolved === oldSrcResolved ||
+        oldObjResolved.startsWith(oldSrcResolved + sep) ||
+        oldObjResolved.startsWith(oldSrcResolved + '/');
+    if (!insideTree) {
+        return {
+            rewritten: false,
+            reason: `topobjdir (${oldObjResolved}) is not inside topsrcdir (${oldSrcResolved}) — rewrite would change workspace layout`,
+        };
+    }
+    const relativeObj = relative(oldSrcResolved, oldObjResolved).split(sep).join('/');
+    if (relativeObj !== objDir) {
+        return {
+            rewritten: false,
+            reason: `mozinfo objdir "${relativeObj}" does not match detected objdir "${objDir}" — rewrite would change the obj directory name`,
+        };
+    }
+    const newSrc = resolve(engineDir);
+    const newObj = resolve(engineDir, objDir);
+    const patched = { ...raw, topsrcdir: newSrc, topobjdir: newObj };
+    let newMozconfig;
+    if (mozinfo.mozconfig) {
+        const oldMozconfigResolved = resolve(mozinfo.mozconfig);
+        if (oldMozconfigResolved === oldSrcResolved ||
+            oldMozconfigResolved.startsWith(oldSrcResolved + sep) ||
+            oldMozconfigResolved.startsWith(oldSrcResolved + '/')) {
+            const rel = relative(oldSrcResolved, oldMozconfigResolved);
+            newMozconfig = resolve(newSrc, rel);
+            patched['mozconfig'] = newMozconfig;
+        }
+        // A mozconfig living outside the old topsrcdir is left as-is — it
+        // probably points at a shared configuration file the user kept in
+        // place across the relocation. A relocated checkout that also moved
+        // its mozconfig will still fail configure; operator can re-point
+        // with `MOZCONFIG=…` or run a full clean rebuild.
+    }
+    await writeJson(mozinfoPath, patched);
+    return {
+        rewritten: true,
+        newTopsrcdir: newSrc,
+        newTopobjdir: newObj,
+        ...(newMozconfig ? { newMozconfig } : {}),
+    };
 }
 //# sourceMappingURL=mach-build-artifacts.js.map

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

@@ -1,4 +1,5 @@
-export { type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
+import { type SmokeLineCallback, type SmokeRunResult } from '../utils/process.js';
+export { attemptMozinfoRewrite, type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, type MozinfoRewriteResult, } from './mach-build-artifacts.js';
 export { generateMozconfig, type MozconfigVariables } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
 /**
@@ -79,6 +80,31 @@ export declare function buildUI(engineDir: string): Promise<number>;
  * @returns Exit code
  */
 export declare function run(engineDir: string, args?: string[]): Promise<number>;
+/**
+ * Options for {@link runMachSmoke}.
+ */
+export interface RunMachSmokeOptions {
+    env?: Record<string, string>;
+    smokeTimeoutMs: number;
+    killGraceMs?: number;
+    onStdoutLine?: SmokeLineCallback;
+    onStderrLine?: SmokeLineCallback;
+    mirror?: {
+        stdout?: NodeJS.WritableStream;
+        stderr?: NodeJS.WritableStream;
+    };
+}
+/**
+ * Launches `mach run` under the smoke-run wrapper: streams line-by-line,
+ * enforces a deadline by SIGTERMing the whole process group, and returns
+ * the captured output alongside a `timedOut` flag.
+ *
+ * Unlike {@link run}, this variant does NOT inherit stdio. The child
+ * stdout/stderr are piped back through the line callbacks so the caller
+ * can scan for `JavaScript error:` / `console.error:` without coupling
+ * the runner to chrome-specific pattern logic.
+ */
+export declare function runMachSmoke(args: string[], engineDir: string, options: RunMachSmokeOptions): Promise<SmokeRunResult>;
 /**
  * Creates a distribution package.
  * @param engineDir - Path to the engine directory

package/dist/src/core/mach.js

@@ -3,11 +3,11 @@ import { join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
-import { exec, execInherit, execInheritCapture, execStream } from '../utils/process.js';
+import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
-export { buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
+export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
 /**
@@ -165,6 +165,30 @@ export async function buildUI(engineDir) {
 export async function run(engineDir, args = []) {
     return runMach(['run', ...args], engineDir, { inherit: true });
 }
+/**
+ * Launches `mach run` under the smoke-run wrapper: streams line-by-line,
+ * enforces a deadline by SIGTERMing the whole process group, and returns
+ * the captured output alongside a `timedOut` flag.
+ *
+ * Unlike {@link run}, this variant does NOT inherit stdio. The child
+ * stdout/stderr are piped back through the line callbacks so the caller
+ * can scan for `JavaScript error:` / `console.error:` without coupling
+ * the runner to chrome-specific pattern logic.
+ */
+export async function runMachSmoke(args, engineDir, options) {
+    const python = await getPython(engineDir);
+    await ensureMach(engineDir);
+    const machPath = join(engineDir, 'mach');
+    return execSmokeRun(python, [machPath, ...args], {
+        cwd: engineDir,
+        ...(options.env ? { env: options.env } : {}),
+        smokeTimeoutMs: options.smokeTimeoutMs,
+        ...(options.killGraceMs !== undefined ? { killGraceMs: options.killGraceMs } : {}),
+        ...(options.onStdoutLine ? { onStdoutLine: options.onStdoutLine } : {}),
+        ...(options.onStderrLine ? { onStderrLine: options.onStderrLine } : {}),
+        ...(options.mirror ? { mirror: options.mirror } : {}),
+    });
+}
 /**
  * Creates a distribution package.
  * @param engineDir - Path to the engine directory

package/dist/src/core/shared-ftl.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Structural rules for the `sharedFtl` field on a custom component.
+ *
+ * Both the `--shared-ftl` CLI flag path (`furnace create`) and the
+ * furnace.json parser apply the same rules — extracting them here
+ * avoids drift between the two entry points and lets the `.mjs`
+ * template generator assume the value is safe to interpolate verbatim.
+ */
+/**
+ * Outcome of {@link validateSharedFtl}. `ok: true` carries the trimmed
+ * (operator-safe) value; `ok: false` carries a human-readable message
+ * suitable for throwing as a `FurnaceError` or `InvalidArgumentError`.
+ */
+export type SharedFtlValidation = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a candidate `sharedFtl` value. Returns the trimmed value
+ * when well-formed, or a structured reason when not. Callers throw the
+ * error type appropriate to their context (CLI vs config parser).
+ */
+export declare function validateSharedFtl(raw: unknown, context: {
+    localized: boolean;
+}): SharedFtlValidation;

package/dist/src/core/shared-ftl.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Structural rules for the `sharedFtl` field on a custom component.
+ *
+ * Both the `--shared-ftl` CLI flag path (`furnace create`) and the
+ * furnace.json parser apply the same rules — extracting them here
+ * avoids drift between the two entry points and lets the `.mjs`
+ * template generator assume the value is safe to interpolate verbatim.
+ */
+/**
+ * Characters that must not appear in `sharedFtl`:
+ *  - Backticks close the MJS template literal the scaffold writes.
+ *  - `\` is a path-escape we do not want to interpret.
+ *  - `${` opens a template expression and turns the FTL path into
+ *    executable code.
+ */
+const UNSAFE_CHARS = /[`\\]|\$\{/;
+/**
+ * Validates a candidate `sharedFtl` value. Returns the trimmed value
+ * when well-formed, or a structured reason when not. Callers throw the
+ * error type appropriate to their context (CLI vs config parser).
+ */
+export function validateSharedFtl(raw, context) {
+    if (typeof raw !== 'string') {
+        return { ok: false, reason: 'must be a string when set' };
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        return { ok: false, reason: 'must not be empty' };
+    }
+    if (UNSAFE_CHARS.test(value)) {
+        return {
+            ok: false,
+            reason: 'must not contain backticks, backslashes, or ${ (would break the generated .mjs)',
+        };
+    }
+    if (!context.localized) {
+        return { ok: false, reason: 'requires localized to be true' };
+    }
+    return { ok: true, value };
+}
+//# sourceMappingURL=shared-ftl.js.map