@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared precondition ladder for the Furnace command family: engine exists,
+ * `furnace.json` exists.
+ *
+ * Kept separate from the `GeneralError` ladder in `engine-precondition.ts`
+ * because the error CLASS is load-bearing here, not cosmetic: `FurnaceError`
+ * carries its own `userMessage` and exit code 9, so a helper raising
+ * `GeneralError` would silently change both.
+ *
+ * Deliberately NOT routed through this helper — each informs rather than
+ * refuses, and each says so at its own site: `furnace list`,
+ * `furnace status`, `furnace init`, and `verify`. `furnace validate`
+ * refusing is the intended line between inspecting and validating.
+ */
+import { FurnaceError } from '../errors/furnace.js';
+import { pathExists } from '../utils/fs.js';
+import { getProjectPaths } from './config-paths.js';
+import { furnaceConfigExists, loadFurnaceConfig } from './furnace-config.js';
+/**
+ * Asserts that a specific engine directory exists, raising a `FurnaceError`.
+ *
+ * The path-taking form, for core helpers that already hold `engineDir` and
+ * have no project root to derive it from.
+ *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Optional message tailoring
+ */
+export async function assertFurnaceEngineDirReady(engineDir, options = {}) {
+    if (!(await pathExists(engineDir))) {
+        throw new FurnaceError(`Engine directory not found. Run "fireforge download" first${options.engineMissingSuffix ?? '.'}`);
+    }
+}
+/**
+ * Asserts that the engine checkout exists, raising a `FurnaceError`.
+ *
+ * The engine rung on its own, for the Furnace commands that scaffold or
+ * mutate component sources without needing `furnace.json` to exist yet.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Optional message tailoring
+ * @returns Resolved project paths, so callers do not re-derive them
+ */
+export async function assertFurnaceEngineReady(projectRoot, options = {}) {
+    const paths = getProjectPaths(projectRoot);
+    await assertFurnaceEngineDirReady(paths.engine, options);
+    return { paths };
+}
+/**
+ * Asserts the full Furnace ladder — engine checkout, then `furnace.json` —
+ * and returns the loaded config so callers do not read it a second time.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Optional message tailoring
+ * @returns Resolved project paths and the loaded furnace config
+ */
+export async function assertFurnaceReady(projectRoot, options = {}) {
+    const { paths } = await assertFurnaceEngineReady(projectRoot, options);
+    // `loadFurnaceConfig` refuses on its own with a fuller message, but the
+    // probe stays: it produces the shorter, action-first refusal the command
+    // layer has always shown for "you have not set Furnace up yet", which is a
+    // different situation from "your furnace.json is unreadable".
+    if (!(await furnaceConfigExists(projectRoot))) {
+        throw new FurnaceError('No furnace.json found. Run "fireforge furnace create" or "fireforge furnace override" to get started.');
+    }
+    return { paths, config: await loadFurnaceConfig(projectRoot) };
+}

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

@@ -2,16 +2,15 @@
  * Removal of custom element registrations from customElements.js.
  *
  * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
- * locate and delete registration entries. The earlier implementation walked
- * the file line-by-line with a 20-line scan bound for bracket matching, which
- * only worked against Firefox's stock formatting and silently failed on any
- * hand-reformatted customElements.js. AST-based bracket matching is format-
- * agnostic by construction.
+ * locate and delete registration entries. A line-by-line scan with a bounded
+ * bracket match only works against Firefox's stock formatting and fails
+ * silently on a hand-reformatted customElements.js; AST-based bracket
+ * matching is format-agnostic by construction.
  *
  * Contract:
  * - Idempotent: if the tag is not registered, the file is left unchanged.
  * - Non-destructive on parse failure: if customElements.js cannot be parsed,
- *   the file is left untouched rather than fall through to a line-based
+ *   the file is left untouched rather than falling through to a line-based
  *   heuristic that could delete the wrong range.
  * - Two registration shapes are recognised:
  *     (A) Standalone statement:

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

@@ -3,16 +3,15 @@
  * Removal of custom element registrations from customElements.js.
  *
  * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
- * locate and delete registration entries. The earlier implementation walked
- * the file line-by-line with a 20-line scan bound for bracket matching, which
- * only worked against Firefox's stock formatting and silently failed on any
- * hand-reformatted customElements.js. AST-based bracket matching is format-
- * agnostic by construction.
+ * locate and delete registration entries. A line-by-line scan with a bounded
+ * bracket match only works against Firefox's stock formatting and fails
+ * silently on a hand-reformatted customElements.js; AST-based bracket
+ * matching is format-agnostic by construction.
  *
  * Contract:
  * - Idempotent: if the tag is not registered, the file is left unchanged.
  * - Non-destructive on parse failure: if customElements.js cannot be parsed,
- *   the file is left untouched rather than fall through to a line-based
+ *   the file is left untouched rather than falling through to a line-based
  *   heuristic that could delete the wrong range.
  * - Two registration shapes are recognised:
  *     (A) Standalone statement:
@@ -32,7 +31,7 @@ import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
  * to (and including) the next newline. This keeps the surrounding file
  * layout stable: deleting a list entry should not leave a dangling comma
  * behind, and deleting an expression statement should not leave a blank
- * line where the statement used to be.
+ * line where the statement stood.
  */
 function expandRemovalRange(content, start, end) {
     let expandedEnd = end;

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

@@ -21,6 +21,19 @@ export declare const CUSTOM_ELEMENT_TAG_RULES = "must be lowercase, start with a
  * @throws FurnaceError if the tag name is invalid
  */
 export declare function validateTagName(tagName: string): void;
+/**
+ * Returns why `tagName` is invalid, or `undefined` when it is fine.
+ *
+ * The message-returning half of {@link validateTagName}, for callers that
+ * must not throw — specifically clack `validate` callbacks, which expect a
+ * returned string and re-prompt on it. Passing the THROWING form to one
+ * makes an invalid tag name escape clack's validation loop as a
+ * `FurnaceError`, killing the prompt instead of showing the rule inline.
+ *
+ * @param tagName - Candidate custom element tag name
+ * @returns The rule violation, or undefined when the name is valid
+ */
+export declare function describeTagNameProblem(tagName: string): string | undefined;
 /**
  * Validates that a registration entry landed in the correct block
  * (Pattern A = loadSubScript, Pattern B = DOMContentLoaded/importESModule).

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

@@ -24,9 +24,28 @@ export const CUSTOM_ELEMENT_TAG_RULES = 'must be lowercase, start with a letter,
  * @throws FurnaceError if the tag name is invalid
  */
 export function validateTagName(tagName) {
+    const problem = describeTagNameProblem(tagName);
+    if (problem !== undefined) {
+        throw new FurnaceError(problem, tagName);
+    }
+}
+/**
+ * Returns why `tagName` is invalid, or `undefined` when it is fine.
+ *
+ * The message-returning half of {@link validateTagName}, for callers that
+ * must not throw — specifically clack `validate` callbacks, which expect a
+ * returned string and re-prompt on it. Passing the THROWING form to one
+ * makes an invalid tag name escape clack's validation loop as a
+ * `FurnaceError`, killing the prompt instead of showing the rule inline.
+ *
+ * @param tagName - Candidate custom element tag name
+ * @returns The rule violation, or undefined when the name is valid
+ */
+export function describeTagNameProblem(tagName) {
     if (!CUSTOM_ELEMENT_TAG_PATTERN.test(tagName)) {
-        throw new FurnaceError(`Invalid tag name "${tagName}": ${CUSTOM_ELEMENT_TAG_RULES}`, tagName);
+        return `Invalid tag name "${tagName}": ${CUSTOM_ELEMENT_TAG_RULES}`;
     }
+    return undefined;
 }
 /**
  * Validates that a registration entry landed in the correct block

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

@@ -81,12 +81,11 @@ export interface StaleJarMnEntry {
     line: string;
 }
 /**
- * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)`
- * whose workspace source file no longer exists (0.34.0 field report: a
- * renamed component helper left the old line pointing at a deleted file,
- * and every build failed at packaging). Only tags in `managedTags`
- * (furnace-managed custom components) are inspected so upstream lines are
- * never touched.
+ * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)` whose
+ * workspace source file no longer exists — a renamed component helper
+ * otherwise leaves the old line pointing at a deleted file and every build
+ * fails at packaging. Only tags in `managedTags` (furnace-managed custom
+ * components) are inspected, so upstream lines are never touched.
  */
 export declare function findStaleJarMnEntries(engineDir: string, customDir: string, managedTags: readonly string[]): Promise<StaleJarMnEntry[]>;
 /**

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

@@ -223,12 +223,11 @@ export async function removeJarMnEntries(engineDir, tagName) {
     const lines = content.split('\n');
     // Match by the SOURCE MAPPING segment `(widgets/<tagName>/...)` so every
     // line the component registered is removed regardless of the target
-    // basename — a helper `.mjs` whose name does not start with the tag
-    // (e.g. a renamed `foo-utils.mjs`) used to survive the remove pass and
-    // leave a stale registration that broke packaging (0.34.0 field
-    // report). The legacy target-path match is kept as an OR for lines
-    // written by older FireForge versions without a source mapping. Word
-    // boundaries keep "moz-card" from matching "moz-card-group".
+    // basename — a helper `.mjs` whose name does not start with the tag (e.g.
+    // a renamed `foo-utils.mjs`) otherwise survives the remove pass and leaves
+    // a stale registration that breaks packaging. The legacy target-path match
+    // is kept as an OR for lines written before the source mapping existed.
+    // Word boundaries keep "moz-card" from matching "moz-card-group".
     const sourcePattern = new RegExp(`\\(widgets/${escapeRegex(tagName)}/`);
     const legacyTargetPattern = new RegExp(`content/global/elements/${escapeRegex(tagName)}\\.`);
     const filtered = lines.filter((line) => !sourcePattern.test(line) && !legacyTargetPattern.test(line));
@@ -239,12 +238,11 @@ export async function removeJarMnEntries(engineDir, tagName) {
 }
 const WIDGET_SOURCE_MAPPING_PATTERN = /\(widgets\/([^/)]+)\/([^)]+)\)/;
 /**
- * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)`
- * whose workspace source file no longer exists (0.34.0 field report: a
- * renamed component helper left the old line pointing at a deleted file,
- * and every build failed at packaging). Only tags in `managedTags`
- * (furnace-managed custom components) are inspected so upstream lines are
- * never touched.
+ * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)` whose
+ * workspace source file no longer exists — a renamed component helper
+ * otherwise leaves the old line pointing at a deleted file and every build
+ * fails at packaging. Only tags in `managedTags` (furnace-managed custom
+ * components) are inspected, so upstream lines are never touched.
  */
 export async function findStaleJarMnEntries(engineDir, customDir, managedTags) {
     const filePath = join(engineDir, JAR_MN);

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

@@ -92,14 +92,14 @@ async function restoreFile(filePath, snapshot) {
         return;
     }
     await mkdir(dirname(filePath), { recursive: true });
-    // Write to a sibling temp file and atomically rename it over the target.
-    // A direct writeFile would race with any in-flight write by the body (e.g. a
+    // Write to a sibling temp file and atomically rename it over the target. A
+    // direct writeFile would race with any in-flight write by the body (e.g. a
     // signal-handler-driven rollback landing on top of a still-running
-    // `writeFile('corrupted')` from the body), producing interleaved byte
-    // sequences like `"pristined"` where the first 8 bytes come from the
-    // rollback write and the trailing byte from the body write. rename(2) is
-    // atomic within a filesystem, so either the body's write or the rollback's
-    // rename wins outright and the target is never left in a hybrid state.
+    // `writeFile('corrupted')`), producing interleaved byte sequences like
+    // `"pristined"` where the first 8 bytes come from the rollback write and
+    // the trailing byte from the body write. rename(2) is atomic within a
+    // filesystem, so either write wins outright and the target is never left
+    // in a hybrid state.
     const tempPath = `${filePath}.rollback-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     try {
         await writeFile(tempPath, snapshot.content ?? new Uint8Array());

package/dist/src/core/furnace-scanner.d.ts

@@ -1,4 +1,5 @@
 import type { ScannedComponent } from '../types/furnace.js';
+/** Path to the widgets directory within the engine source tree */
 /**
  * Additional Firefox source directories known to contain MozLitElement
  * components. Used by `--deep` scan mode to discover components beyond

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

@@ -6,9 +6,8 @@ import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { asEstree, getNodeSource, parseScript, walkAST } from './ast-utils.js';
-import { CUSTOM_ELEMENTS_JS, FTL_DIR } from './furnace-constants.js';
+import { CUSTOM_ELEMENTS_JS, FTL_DIR, WIDGETS_DIR } from './furnace-constants.js';
 /** Path to the widgets directory within the engine source tree */
-const WIDGETS_DIR = 'toolkit/content/widgets';
 /**
  * Additional Firefox source directories known to contain MozLitElement
  * components. Used by `--deep` scan mode to discover components beyond

package/dist/src/core/furnace-stale-export.d.ts

@@ -2,21 +2,21 @@
  * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
  *
  * Exports capture the DEPLOYED engine copies of furnace-managed files, not
- * the `components/` sources. Editing a component source and re-exporting
- * its owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
+ * the `components/` sources. Editing a component source and re-exporting its
+ * owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
  * exports the stale deployed copy — per-patch lint then flags the old line
- * count and the patch body lags the source. This gate detects that
- * sequence by comparing component source directories against the checksums
- * recorded at the last apply (`FurnaceState.appliedChecksums`) — the same
- * signal `warnIfFurnaceStale` uses for run/watch — and refuses the export
- * unless the operator passes `--allow-stale-furnace`.
+ * count and the patch body lags the source. This gate detects that sequence
+ * by comparing component source directories against the checksums recorded
+ * at the last apply (`FurnaceState.appliedChecksums`) — the same signal
+ * `warnIfFurnaceStale` uses for run/watch — and refuses the export unless
+ * the operator passes `--allow-stale-furnace`.
  *
  * Checksum-based on purpose: git checkouts and `furnace refresh` churn
  * mtimes without content changes, so an mtime comparison would misfire.
  *
- * Probe failures (broken furnace config, missing state) degrade to a
- * verbose log and an empty result — a broken furnace setup must never
- * block non-furnace patch work.
+ * Probe failures (broken furnace config, missing state) degrade to a verbose
+ * log and an empty result — a broken furnace setup must never block
+ * non-furnace patch work.
  */
 /** One furnace component whose source drifted from its deployed copy. */
 export interface StaleFurnaceComponent {

package/dist/src/core/furnace-stale-export.js

@@ -3,21 +3,21 @@
  * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
  *
  * Exports capture the DEPLOYED engine copies of furnace-managed files, not
- * the `components/` sources. Editing a component source and re-exporting
- * its owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
+ * the `components/` sources. Editing a component source and re-exporting its
+ * owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
  * exports the stale deployed copy — per-patch lint then flags the old line
- * count and the patch body lags the source. This gate detects that
- * sequence by comparing component source directories against the checksums
- * recorded at the last apply (`FurnaceState.appliedChecksums`) — the same
- * signal `warnIfFurnaceStale` uses for run/watch — and refuses the export
- * unless the operator passes `--allow-stale-furnace`.
+ * count and the patch body lags the source. This gate detects that sequence
+ * by comparing component source directories against the checksums recorded
+ * at the last apply (`FurnaceState.appliedChecksums`) — the same signal
+ * `warnIfFurnaceStale` uses for run/watch — and refuses the export unless
+ * the operator passes `--allow-stale-furnace`.
  *
  * Checksum-based on purpose: git checkouts and `furnace refresh` churn
  * mtimes without content changes, so an mtime comparison would misfire.
  *
- * Probe failures (broken furnace config, missing state) degrade to a
- * verbose log and an empty result — a broken furnace setup must never
- * block non-furnace patch work.
+ * Probe failures (broken furnace config, missing state) degrade to a verbose
+ * log and an empty result — a broken furnace setup must never block
+ * non-furnace patch work.
  */
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';

package/dist/src/core/furnace-state-persist.d.ts

@@ -4,22 +4,20 @@
  * There are exactly two sanctioned ways checksums land in
  * furnace-state.json:
  *
- *  1. The BATCH path inside `applyAllComponents` (persistState: true),
- *     which replaces `appliedChecksums` wholesale — correct only when the
- *     run covered every component.
+ *  1. The BATCH path inside `applyAllComponents` (persistState: true), which
+ *     replaces `appliedChecksums` wholesale — correct only when the run
+ *     covered every component.
  *  2. The per-component MERGE in this module, which rewrites only the
  *     `<type>/<name>/…` keys of the component that was applied.
  *
  * Every targeted (named) apply/deploy MUST use path 2 with
  * `persistState: false`. Routing a named run through the batch path wipes
  * every other component's checksum state: the batch loops filter to the
- * named component, so the wholesale replace persists a state file
- * containing only that component. Downstream, `diffDeletedFiles` and
+ * named component, so the wholesale replace persists a state file containing
+ * only that component. Downstream, `diffDeletedFiles` and
  * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
  * components' stale engine files become undetectable by apply AND by
- * `furnace validate` (2026-07-05 review, finding F1 — `furnace apply
- * <name>` had exactly this bug while `furnace deploy <name>` documented
- * and avoided it).
+ * `furnace validate`.
  */
 import { type ApplyAllComponentsResult } from './furnace-apply.js';
 import { type getFurnacePaths } from './furnace-config.js';

package/dist/src/core/furnace-state-persist.js

@@ -5,22 +5,20 @@
  * There are exactly two sanctioned ways checksums land in
  * furnace-state.json:
  *
- *  1. The BATCH path inside `applyAllComponents` (persistState: true),
- *     which replaces `appliedChecksums` wholesale — correct only when the
- *     run covered every component.
+ *  1. The BATCH path inside `applyAllComponents` (persistState: true), which
+ *     replaces `appliedChecksums` wholesale — correct only when the run
+ *     covered every component.
  *  2. The per-component MERGE in this module, which rewrites only the
  *     `<type>/<name>/…` keys of the component that was applied.
  *
  * Every targeted (named) apply/deploy MUST use path 2 with
  * `persistState: false`. Routing a named run through the batch path wipes
  * every other component's checksum state: the batch loops filter to the
- * named component, so the wholesale replace persists a state file
- * containing only that component. Downstream, `diffDeletedFiles` and
+ * named component, so the wholesale replace persists a state file containing
+ * only that component. Downstream, `diffDeletedFiles` and
  * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
  * components' stale engine files become undetectable by apply AND by
- * `furnace validate` (2026-07-05 review, finding F1 — `furnace apply
- * <name>` had exactly this bug while `furnace deploy <name>` documented
- * and avoided it).
+ * `furnace validate`.
  */
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';

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

@@ -3,6 +3,8 @@ 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 componentDir - Directory holding the component's sources
+ * @param tagName - Custom element tag name, used to locate `<tagName>.mjs`
  * @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
@@ -11,3 +13,23 @@ import type { CustomComponentConfig, ValidationIssue } from '../types/furnace.js
  *   without config in scope can continue to call without changes.
  */
 export declare function validateAccessibility(componentDir: string, tagName: string, customConfig?: CustomComponentConfig): Promise<ValidationIssue[]>;
+/**
+ * Detects hardcoded user-visible template text that should usually be
+ * localized.
+ *
+ * Scoped to three positive contexts rather than scanning the whole file,
+ * because a bare `>…<` regex catches JS comparisons (`if (x > 0 && y <
+ * 100)`), diagnostic strings (`console.error("Failed <id> lookup")`), and
+ * identifier literals that are never shown to a user. Only matches that
+ * actually enter a UI render path count:
+ *
+ *   1. Content inside a Lit `` html`…` `` tagged template literal.
+ *   2. The string literal on the RHS of `.textContent = "…"` or
+ *      `.innerHTML = "…"`.
+ *   3. The string literal assigned to an XUL-widget `label=`,
+ *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
+ *
+ * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
+ * findings (matches the pre-existing escape hatch).
+ */
+export declare function containsHardcodedTemplateText(content: string): boolean;