@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -3,7 +3,7 @@ import { type RollbackJournal } from './furnace-rollback.js';
 /**
  * The signal names the lifecycle wrapper knows how to react to. Spelled out
  * as a literal union (rather than `NodeJS.Signals`) so the public type
- * surface does not depend on the NodeJS global namespace — consumers of
+ * surface does not depend on the NodeJS global namespace. Consumers of
  * FireForge's published scoped npm package may compile against tsconfigs
  * that omit `@types/node`.
  */
@@ -36,9 +36,9 @@ export interface FurnaceOperationContext {
      * Bodies that catch-and-restore on their own (the `furnace/*` command
      * bodies, `furnace-apply`) call this from their catch block after the
      * restore, then re-throw. Without it the wrapper would restore the same
-     * journal again on the way out — harmless for the file writes, which are
-     * rename-based and converge, but it would race a second `pendingRepair`
-     * write against the state-file lock.
+     * journal again on the way out. That is harmless for the file writes,
+     * which are rename-based and converge, but it would race a second
+     * `pendingRepair` write against the state-file lock.
      */
     markRolledBack(): void;
 }
@@ -49,7 +49,7 @@ export interface RunFurnaceMutationOptions {
      * Used by dry-run paths where no engine mutation occurs.
      *
      * Note: a dry-run can overlap with a real mutation because it does not
-     * acquire the lock. This is safe because dry-runs only read; however, a
+     * acquire the lock. This is safe because dry-runs only read. However, a
      * dry-run that starts before a real mutation and finishes after it may
      * observe partially-written engine state. Accept this trade-off so that
      * concurrent dry-runs never block each other or a real apply.
@@ -58,11 +58,11 @@ export interface RunFurnaceMutationOptions {
     /**
      * Override the default 30 s furnace-lock timeout.
      *
-     * Set from the caller's resolved `--wait-lock` budget, so ONE flag governs
+     * Set from the caller's resolved `--wait-lock` budget, so one flag governs
      * both locks a furnace mutation takes. Before that it was declared and
      * never passed: `furnace deploy --wait-lock 1800` waited 1800 s for the
      * engine session lock and then met `.fireforge/furnace.lock` with a fixed
-     * 30 s, which is the worst shape a budget can have — it pays the whole
+     * 30 s, which is the worst shape a budget can have: it pays the whole
      * wait and still refuses. When absent, {@link sessionWaitLockMs} supplies
      * the session-wide budget so the twelve furnace mutators that declare no
      * flag are covered too.
@@ -78,7 +78,7 @@ export interface RunFurnaceMutationOptions {
 /**
  * Converts a resolved `--wait-lock` budget in seconds into the
  * {@link RunFurnaceMutationOptions} slice that applies it to the furnace
- * lock. Undefined in, empty out — so the caller can spread it
+ * lock. Undefined in, empty out, so the caller can spread it
  * unconditionally without assigning `undefined` under
  * `exactOptionalPropertyTypes`.
  *
@@ -94,7 +94,7 @@ export declare function waitLockMutationOptions(waitLockSeconds: number | undefi
  * Returns true while a signal-driven rollback is in progress. The bin entry
  * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot
  * trigger a second rollback that races the first. Exposed for the bin shim
- * (and the test suite); production callers should not need it.
+ * (and the test suite). Production callers should not need it.
  */
 export declare function isSignalRollbackInFlight(): boolean;
 /**
@@ -105,7 +105,7 @@ export declare function isSignalRollbackInFlight(): boolean;
 export declare function rollbackActiveOperationsForSignal(signal: FurnaceShutdownSignal): Promise<void>;
 /**
  * Resolves the path of the lock directory used to serialize furnace mutations
- * for a given project root. Exposed for tests; production callers should not
+ * for a given project root. Exposed for tests. Production callers should not
  * touch this directly.
  */
 export declare function getFurnaceLockPath(root: string): string;
@@ -119,10 +119,10 @@ export declare function getFurnaceLockPath(root: string): string;
  * restructure control flow through the engine's rollback path for a
  * cosmetic gain.
  *
- * The ordering is the part worth centralising: `markRolledBack()` MUST run
+ * The ordering is the part worth centralising: `markRolledBack()` must run
  * before the restore, so a restore that itself fails does not leave the
- * lifecycle wrapper replaying the same journal on the way out. And the
- * ORIGINAL error is rethrown unless the rollback is what failed — the
+ * lifecycle wrapper replaying the same journal on the way out. The
+ * original error is rethrown unless the rollback is what failed: the
  * operator needs to know what went wrong, and separately whether the engine
  * could be put back.
  *
@@ -130,7 +130,7 @@ export declare function getFurnaceLockPath(root: string): string;
  * @param journal - Rollback journal this body populated
  * @param error - The error the body threw
  * @param options - Project root, pending-repair tag, and message fragments
- * @returns Never — always throws
+ * @returns Never, because it always throws
  */
 export declare function completeJournalRollback(ctx: FurnaceOperationContext, journal: RollbackJournal, error: unknown, options: {
     projectRoot: string;
@@ -144,11 +144,11 @@ export declare function completeJournalRollback(ctx: FurnaceOperationContext, jo
  * Forcibly removes the furnace lock directory for every active operation.
  *
  * The bin-layer signal handler calls `process.exit` after rollback, which
- * short-circuits Node's normal unwinding — `withFileLock`'s `finally { rm
- * }` never runs, so the lock directory survives the process. The next
+ * short-circuits Node's normal unwinding, so `withFileLock`'s `finally { rm
+ * }` never runs and the lock directory survives the process. The next
  * FireForge command then has to either wait out the staleness window or
  * have the operator remove the lock manually. This sweeper runs inside
- * the signal-handler pipeline BEFORE `process.exit`, so the lock is gone
+ * the signal-handler pipeline before `process.exit`, so the lock is gone
  * by the time the next command starts.
  *
  * Errors are logged and swallowed: we do not want a slow I/O failure at
@@ -161,7 +161,7 @@ export declare function forceReleaseFurnaceLocksForActiveOperations(): Promise<v
  * Runs a furnace-mutating body under the apply-wide lock and registers it
  * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents
  * two `furnace apply`/`deploy`/`create`/etc. runs from racing on the engine
- * working copy; the CLI entrypoint's global signal handlers consult this
+ * working copy. The CLI entrypoint's global signal handlers consult this
  * registry and invoke rollback (writing a `pendingRepair` marker when needed)
  * if the user hits Ctrl+C mid-run.
  *
@@ -169,7 +169,7 @@ export declare function forceReleaseFurnaceLocksForActiveOperations(): Promise<v
  * the lock entirely (concurrent dry-runs are safe and shouldn't block each
  * other).
  *
- * The body receives a {@link FurnaceOperationContext}; it must call
+ * The body receives a {@link FurnaceOperationContext}. It must call
  * `ctx.registerJournal(journal)` once it has constructed its rollback journal.
  * Bodies that don't manage a journal directly (e.g. apply, which delegates to
  * `applyAllComponents`) can pass an internal callback through.
@@ -189,6 +189,7 @@ export declare function recordFurnaceRollbackFailure(root: string, operation: Fu
  * cases that exercise the signal pathway. Not exported from the package
  * entry point.
  *
- * @internal Exported only so tests can reach it; not part of the public surface.
+ * @internal Exported only so tests can reach it. Not part of the public
+ * surface.
  */
 export declare function __resetFurnaceOperationStateForTests(): void;

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

@@ -14,7 +14,7 @@ const FURNACE_LOCK_FILENAME = 'furnace.lock';
 /**
  * Converts a resolved `--wait-lock` budget in seconds into the
  * {@link RunFurnaceMutationOptions} slice that applies it to the furnace
- * lock. Undefined in, empty out — so the caller can spread it
+ * lock. Undefined in, empty out, so the caller can spread it
  * unconditionally without assigning `undefined` under
  * `exactOptionalPropertyTypes`.
  *
@@ -33,7 +33,7 @@ export function waitLockMutationOptions(waitLockSeconds) {
  * already has it.
  *
  * Must stay synchronous and must be called before the caller's first
- * await — that is what makes the claim atomic against the signal handler.
+ * await. That is what makes the claim atomic against the signal handler.
  *
  * @param operation - The in-flight operation to claim
  * @returns True when the caller now owns the rollback
@@ -52,7 +52,7 @@ let signalRollbackInFlight = false;
  * Returns true while a signal-driven rollback is in progress. The bin entry
  * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot
  * trigger a second rollback that races the first. Exposed for the bin shim
- * (and the test suite); production callers should not need it.
+ * (and the test suite). Production callers should not need it.
  */
 export function isSignalRollbackInFlight() {
     return signalRollbackInFlight;
@@ -60,7 +60,7 @@ export function isSignalRollbackInFlight() {
 /**
  * Rolls back every in-flight furnace operation and writes a pendingRepair
  * marker for each. The bin entry point installs SIGINT/SIGTERM handlers that
- * call this and then exit; calling it directly from inside the library would
+ * call this and then exit. Calling it directly from inside the library would
  * violate the "process.exit only in bin" invariant. The function is also
  * exposed under this name so the test suite can exercise the teardown path
  * without going through `process.emit` / `process.exit`.
@@ -91,8 +91,9 @@ export async function rollbackActiveOperationsForSignal(signal) {
     // Snapshot the active operations so we don't race with `runFurnaceMutation`
     // clearing slots during normal completion. Filter completed bodies so a
     // body sitting in its finally-block cleanup window is not counted as live
-    // work — this would mis-trigger the rollback banner for plain `fireforge
-    // run` (which never registers a mutation but can receive SIGTERM).
+    // work. Counting it would mis-trigger the rollback banner for plain
+    // `fireforge run` (which never registers a mutation but can receive
+    // SIGTERM).
     const snapshot = [...activeOperations.values()].filter((op) => !op.completed);
     if (snapshot.length === 0) {
         // Nothing to roll back. Stay silent so commands that never mutated (run,
@@ -124,9 +125,9 @@ export async function rollbackActiveOperationsForSignal(signal) {
             }
         }
         if (!op.journal) {
-            // The body had not yet handed us a journal — nothing to roll back. We
-            // still write a marker because the body may have started mutating the
-            // engine before reaching the registerJournal call.
+            // The body had not yet handed us a journal, so there is nothing to
+            // roll back. We still write a marker because the body may have started
+            // mutating the engine before reaching the registerJournal call.
             const cleanupSuffix = cleanupErrors.length > 0 ? `; cleanup errors: ${cleanupErrors.join('; ')}` : '';
             await persistPendingRepair(op.root, op.kind, `interrupted by ${signal} before any state was captured${cleanupSuffix}`).catch((error) => {
                 warn(`Could not persist pending-repair marker: ${toError(error).message}`);
@@ -190,7 +191,7 @@ async function rollbackOperationForThrow(operation) {
     }
     if (!operation.journal) {
         // Nothing was captured, so there is nothing to restore. Unlike the signal
-        // path we do NOT write a pendingRepair marker here: a body that threw
+        // path we do not write a pendingRepair marker here: a body that threw
         // before registering a journal is overwhelmingly a refusal raised during
         // pre-flight (a validation failure, a missing file), and marking the root
         // as needing repair would block every later furnace mutation behind a
@@ -243,7 +244,7 @@ async function persistPendingRepair(root, operation, reason) {
 }
 /**
  * Resolves the path of the lock directory used to serialize furnace mutations
- * for a given project root. Exposed for tests; production callers should not
+ * for a given project root. Exposed for tests. Production callers should not
  * touch this directly.
  */
 export function getFurnaceLockPath(root) {
@@ -259,10 +260,10 @@ export function getFurnaceLockPath(root) {
  * restructure control flow through the engine's rollback path for a
  * cosmetic gain.
  *
- * The ordering is the part worth centralising: `markRolledBack()` MUST run
+ * The ordering is the part worth centralising: `markRolledBack()` must run
  * before the restore, so a restore that itself fails does not leave the
- * lifecycle wrapper replaying the same journal on the way out. And the
- * ORIGINAL error is rethrown unless the rollback is what failed — the
+ * lifecycle wrapper replaying the same journal on the way out. The
+ * original error is rethrown unless the rollback is what failed: the
  * operator needs to know what went wrong, and separately whether the engine
  * could be put back.
  *
@@ -270,7 +271,7 @@ export function getFurnaceLockPath(root) {
  * @param journal - Rollback journal this body populated
  * @param error - The error the body threw
  * @param options - Project root, pending-repair tag, and message fragments
- * @returns Never — always throws
+ * @returns Never, because it always throws
  */
 export async function completeJournalRollback(ctx, journal, error, options) {
     // This body owns its rollback end to end, so tell the lifecycle wrapper
@@ -289,11 +290,11 @@ export async function completeJournalRollback(ctx, journal, error, options) {
  * Forcibly removes the furnace lock directory for every active operation.
  *
  * The bin-layer signal handler calls `process.exit` after rollback, which
- * short-circuits Node's normal unwinding — `withFileLock`'s `finally { rm
- * }` never runs, so the lock directory survives the process. The next
+ * short-circuits Node's normal unwinding, so `withFileLock`'s `finally { rm
+ * }` never runs and the lock directory survives the process. The next
  * FireForge command then has to either wait out the staleness window or
  * have the operator remove the lock manually. This sweeper runs inside
- * the signal-handler pipeline BEFORE `process.exit`, so the lock is gone
+ * the signal-handler pipeline before `process.exit`, so the lock is gone
  * by the time the next command starts.
  *
  * Errors are logged and swallowed: we do not want a slow I/O failure at
@@ -305,9 +306,9 @@ export async function forceReleaseFurnaceLocksForActiveOperations() {
     const paths = new Set([...activeOperations.values()].map((op) => getFurnaceLockPath(op.root)));
     for (const lockPath of paths) {
         // Ownership-checked, like every other release path. The bare `rm` this
-        // replaced would delete a lock a DIFFERENT process had acquired in the
-        // window between our operation dying and this sweep running — the exact
-        // race `releaseLock`'s PID verification was added to close, reopened
+        // replaced would delete a lock a different process had acquired in the
+        // window between our operation dying and this sweep running. That is the
+        // exact race `releaseLock`'s PID verification was added to close, reopened
         // here because the sweeper has no acquisition token to check.
         const removed = await releaseLockIfOwned(lockPath);
         verbose(removed
@@ -319,7 +320,7 @@ export async function forceReleaseFurnaceLocksForActiveOperations() {
  * Runs a furnace-mutating body under the apply-wide lock and registers it
  * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents
  * two `furnace apply`/`deploy`/`create`/etc. runs from racing on the engine
- * working copy; the CLI entrypoint's global signal handlers consult this
+ * working copy. The CLI entrypoint's global signal handlers consult this
  * registry and invoke rollback (writing a `pendingRepair` marker when needed)
  * if the user hits Ctrl+C mid-run.
  *
@@ -327,7 +328,7 @@ export async function forceReleaseFurnaceLocksForActiveOperations() {
  * the lock entirely (concurrent dry-runs are safe and shouldn't block each
  * other).
  *
- * The body receives a {@link FurnaceOperationContext}; it must call
+ * The body receives a {@link FurnaceOperationContext}. It must call
  * `ctx.registerJournal(journal)` once it has constructed its rollback journal.
  * Bodies that don't manage a journal directly (e.g. apply, which delegates to
  * `applyAllComponents`) can pass an internal callback through.
@@ -356,10 +357,10 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
     const token = nextOperationToken++;
     const operation = { root, kind, cleanups: [] };
     const lockPath = getFurnaceLockPath(root);
-    // An explicit budget wins; otherwise the session-wide one applies. Naming
-    // the lock in the refusal is load-bearing: a mutation takes two, and a
-    // message that says only "timed out" sends the operator to raise a budget
-    // that was already large enough for the OTHER lock.
+    // An explicit budget wins. Otherwise the session-wide one applies. Naming
+    // the lock in the refusal matters: a mutation takes two, and a message
+    // that says only "timed out" sends the operator to raise a budget that
+    // was already large enough for the other lock.
     const timeoutMs = options.lockTimeoutMs ?? sessionWaitLockMs();
     const lockOptions = {
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
@@ -374,10 +375,10 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
     return withFileLock(lockPath, async () => {
         // Everything the body does from here is serialized only by the furnace
         // lock, so confirm we are actually inside it before registering as a
-        // live mutation. The owner record is deliberately best-effort in
-        // `withFileLock` (a live holder can legitimately have no readable PID),
-        // so the PID half only tightens the check when a record is present —
-        // asserting on its existence would fire on a lock we really do hold.
+        // live mutation. The owner record is best-effort in `withFileLock`
+        // (a live holder can legitimately have no readable PID), so the PID
+        // half only tightens the check when a record is present. Asserting on
+        // its existence would fire on a lock we really do hold.
         const lockStatus = await readLockStatus(lockPath);
         assert(lockStatus.held, 'furnace lock held before the mutation body runs');
         assert(lockStatus.holder === undefined || lockStatus.holder.pid === process.pid, () => `furnace lock is owned by this process ` +
@@ -401,8 +402,8 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
             // so it gets the same treatment. A bare finally here would
             // deregister the operation and mark it completed, removing it from
             // the signal handler's view too, so a body that threw outside its
-            // own catch — notably anywhere in `applyAllComponents` outside its
-            // two per-component try blocks — would leave the checkout torn with
+            // own catch (notably anywhere in `applyAllComponents` outside its
+            // two per-component try blocks) would leave the checkout torn with
             // no marker.
             //
             // This runs inside the withFileLock callback, so the furnace lock is
@@ -433,7 +434,8 @@ export async function recordFurnaceRollbackFailure(root, operation, reason) {
  * cases that exercise the signal pathway. Not exported from the package
  * entry point.
  *
- * @internal Exported only so tests can reach it; not part of the public surface.
+ * @internal Exported only so tests can reach it. Not part of the public
+ * surface.
  */
 export function __resetFurnaceOperationStateForTests() {
     activeOperations.clear();

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

@@ -3,14 +3,14 @@
  * `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.
+ * because the error class matters here and is not merely 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.
+ * Four sites are not routed through this helper: `furnace list`,
+ * `furnace status`, `furnace init`, and `verify`. Each informs rather than
+ * refuses, and each says so at its own site. `furnace validate` refusing is
+ * the intended line between inspecting and validating.
  */
 import type { FurnaceConfig } from '../types/furnace.js';
 import type { ProjectPaths } from '../types/index.js';
@@ -18,8 +18,8 @@ import type { ProjectPaths } from '../types/index.js';
 export interface FurnacePreconditionOptions {
     /**
      * Appended to the engine-missing refusal, e.g.
-     * `' to scaffold a chrome-doc.'`. The base message ends WITHOUT
-     * punctuation so the suffix reads as one sentence; callers passing nothing
+     * `' to scaffold a chrome-doc.'`. The base message ends without
+     * punctuation so the suffix reads as one sentence. Callers passing nothing
      * get a plain full stop.
      */
     engineMissingSuffix?: string;
@@ -48,7 +48,7 @@ export declare function assertFurnaceEngineReady(projectRoot: string, options?:
     paths: ProjectPaths;
 }>;
 /**
- * Asserts the full Furnace ladder — engine checkout, then `furnace.json` —
+ * 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

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

@@ -4,14 +4,14 @@
  * `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.
+ * because the error class matters here and is not merely 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.
+ * Four sites are not routed through this helper: `furnace list`,
+ * `furnace status`, `furnace init`, and `verify`. Each informs rather than
+ * refuses, and each says so at its own site. `furnace validate` refusing is
+ * the intended line between inspecting and validating.
  */
 import { FurnaceError } from '../errors/furnace.js';
 import { pathExists } from '../utils/fs.js';
@@ -47,7 +47,7 @@ export async function assertFurnaceEngineReady(projectRoot, options = {}) {
     return { paths };
 }
 /**
- * Asserts the full Furnace ladder — engine checkout, then `furnace.json` —
+ * 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

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

@@ -90,12 +90,12 @@ export async function refreshOverrideFile(options) {
     const oursContent = await readText(overridePath);
     const baseContent = await getFileContentAtRef(engineDir, engineRelPath, baseCommit);
     if (baseContent === null) {
-        // File didn't exist at baseCommit — this is a new file introduced by the override
+        // File didn't exist at baseCommit: this is a new file introduced by the override
         return { fileName, status: 'new-file' };
     }
     const theirsContent = await getFileContentAtRef(engineDir, engineRelPath, 'HEAD');
     if (theirsContent === null) {
-        // File was removed upstream — no merge needed, keep the override as-is
+        // File was removed upstream, so no merge is needed. Keep the override as-is
         return { fileName, status: 'unchanged' };
     }
     // If upstream hasn't changed, nothing to merge

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

@@ -12,7 +12,7 @@
  *
  * Matches any of:
  *   1. `setElementCreationCallback("tag"` / `setElementCreationCallback('tag'`
- *   2. Single-line array entry: `["tag", "..."]` — column 0 only, comments allowed after
+ *   2. Single-line array entry: `["tag", "..."]` (column 0 only, comments allowed after)
  *   3. Multi-line array entry: `"tag",` on its own line, optional trailing `//` comment
  */
 export declare function isTagAlreadyRegistered(content: string, tagName: string): boolean;
@@ -38,7 +38,7 @@ export interface RegistrationWriteOptions {
  * ```
  *
  * New entries are inserted in alphabetical order relative to existing entries.
- * This operation is idempotent — if the tag is already registered the file is
+ * This operation is idempotent: if the tag is already registered the file is
  * left unchanged.
  *
  * @param engineDir - Path to the Firefox engine source root

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

@@ -23,7 +23,7 @@ import { validateRegistrationPlacement, validateTagName } from './furnace-regist
  *
  * Matches any of:
  *   1. `setElementCreationCallback("tag"` / `setElementCreationCallback('tag'`
- *   2. Single-line array entry: `["tag", "..."]` — column 0 only, comments allowed after
+ *   2. Single-line array entry: `["tag", "..."]` (column 0 only, comments allowed after)
  *   3. Multi-line array entry: `"tag",` on its own line, optional trailing `//` comment
  */
 export function isTagAlreadyRegistered(content, tagName) {
@@ -234,8 +234,8 @@ function addRegistrationAST(content, tagName, modulePath, isESModule, markerComm
  * fails. Finds the last existing `["tag", "path"],` line in the appropriate
  * block and inserts the new entry after it in alphabetical order.
  *
- * This is intentionally less precise than the AST approach — it does not
- * validate indentation or multi-line format — but it is robust against
+ * This is intentionally less precise than the AST approach (it does not
+ * validate indentation or multi-line format), but it is robust against
  * upstream syntax changes that break the parser.
  */
 function addRegistrationRegexFallback(content, tagName, modulePath, isESModule, markerComment) {
@@ -297,7 +297,7 @@ function hasRecognizableRegistrationLoop(content) {
  * ```
  *
  * New entries are inserted in alphabetical order relative to existing entries.
- * This operation is idempotent — if the tag is already registered the file is
+ * This operation is idempotent: if the tag is already registered the file is
  * left unchanged.
  *
  * @param engineDir - Path to the Firefox engine source root
@@ -312,13 +312,13 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
     const content = await readText(filePath);
     // Idempotency: check column-0 of each array entry rather than a literal
     // substring match. A previous apply may have written this entry with
-    // trailing marker comments (see `options.markerComment`); matching on the
+    // trailing marker comments (see `options.markerComment`). Matching on the
     // full line would then miss it and insert a duplicate on re-apply, which
     // throws NotSupportedError at every window-load.
     if (isTagAlreadyRegistered(content, tagName)) {
         return;
     }
-    // Validate upfront — tag name errors must not fall through to the regex fallback.
+    // Validate upfront. Tag name errors must not fall through to the regex fallback.
     validateTagName(tagName);
     const isESModule = modulePath.endsWith('.mjs');
     // Cheap pre-flight: the AST walker assumes the file contains at least one
@@ -326,7 +326,7 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
     // right-hand side, and (for ESM tags) at least one such loop inside a
     // `document.addEventListener("DOMContentLoaded", ...)` block. If either
     // assumption is violated the AST path errors with a confusing
-    // "Could not find DOMContentLoaded block" message — fail fast here with
+    // "Could not find DOMContentLoaded block" message, so fail fast here with
     // actionable guidance instead.
     if (!hasRecognizableRegistrationLoop(content)) {
         throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} does not contain a recognizable registration loop; refusing to mutate. ` +
@@ -342,7 +342,7 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
     }
     catch (error) {
         if (error instanceof FurnaceError) {
-            // AST structural errors (missing DOMContentLoaded block, etc.) — try regex fallback
+            // AST structural errors (missing DOMContentLoaded block, etc.): try regex fallback
             warn(`AST-based registration failed for ${tagName}: ${error.message}. ` +
                 'Falling back to regex-based insertion. Please report this so the AST parser can be updated.');
             try {
@@ -396,7 +396,7 @@ export async function validateCustomElementRegistration(engineDir, tagName, modu
         addRegistrationAST(content, tagName, modulePath, isESModule);
     }
     catch {
-        // Validation only — if AST fails, try regex to see if the entry could be placed
+        // Validation only: if AST fails, try regex to see if the entry could be placed
         addRegistrationRegexFallback(content, tagName, modulePath, isESModule);
     }
 }

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

@@ -4,8 +4,8 @@
  * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
  * 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.
+ * silently on a hand-reformatted customElements.js. AST-based bracket
+ * matching does not depend on the file's formatting.
  *
  * Contract:
  * - Idempotent: if the tag is not registered, the file is left unchanged.
@@ -23,10 +23,10 @@
 /**
  * Removes a custom element registration from customElements.js.
  *
- * This operation is idempotent — if the tag is not registered or the file
+ * This operation is idempotent: if the tag is not registered or the file
  * does not exist, nothing happens. If the file exists but cannot be parsed,
  * the file is left unchanged rather than fall back to a line-based
- * heuristic; a corrupted customElements.js is a doctor problem, not
+ * heuristic. A corrupted customElements.js is a doctor problem, not
  * something `furnace remove` should "helpfully" edit around.
  *
  * @param engineDir - Path to the Firefox engine source root

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

@@ -5,8 +5,8 @@
  * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
  * 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.
+ * silently on a hand-reformatted customElements.js. AST-based bracket
+ * matching does not depend on the file's formatting.
  *
  * Contract:
  * - Idempotent: if the tag is not registered, the file is left unchanged.
@@ -49,7 +49,7 @@ function expandRemovalRange(content, start, end) {
     }
     // Consume a trailing inline comment up to end-of-line so we do not leave
     // the comment marooned on its own line. A leading inline comment is left
-    // alone — it may belong to the next entry.
+    // alone, because it may belong to the next entry.
     while (expandedEnd < content.length &&
         (content[expandedEnd] === ' ' || content[expandedEnd] === '\t')) {
         expandedEnd++;
@@ -88,7 +88,7 @@ function expandRemovalRange(content, start, end) {
 }
 /**
  * Returns true if `node` represents a `[tag, module]` entry inside a
- * registration array — i.e. an `ArrayExpression` whose first element is a
+ * registration array, i.e. an `ArrayExpression` whose first element is a
  * string literal equal to `tagName`. Callers still have to verify the
  * parent is the outer registration array so we do not accidentally delete
  * an arbitrary user-owned `["moz-card", ...]` literal elsewhere in the file.
@@ -176,10 +176,10 @@ function collectRemovalRanges(ast, content, tagName) {
 /**
  * Removes a custom element registration from customElements.js.
  *
- * This operation is idempotent — if the tag is not registered or the file
+ * This operation is idempotent: if the tag is not registered or the file
  * does not exist, nothing happens. If the file exists but cannot be parsed,
  * the file is left unchanged rather than fall back to a line-based
- * heuristic; a corrupted customElements.js is a doctor problem, not
+ * heuristic. A corrupted customElements.js is a doctor problem, not
  * something `furnace remove` should "helpfully" edit around.
  *
  * @param engineDir - Path to the Firefox engine source root

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

@@ -25,8 +25,8 @@ 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
+ * 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.
  *

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

@@ -33,8 +33,8 @@ export function validateTagName(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
+ * 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.
  *