@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/furnace/index.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { Command, Option } from 'commander';
 import { withEngineSessionLock } from '../../core/engine-session-lock.js';
-import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
 import { furnaceApplyCommand } from './apply.js';
 import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
 import { furnaceChromeDocRemoveCommand } from './chrome-doc-remove.js';
@@ -19,6 +19,18 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
+import { parseMaxWarnings } from './validate-report.js';
+/**
+ * Splits the raw `--wait-lock` value off a furnace leaf's parsed options and
+ * resolves it into `waitLockSeconds` (flag, else `FIREFORGE_WAIT_LOCK`, else
+ * undefined) for the furnace lock `runFurnaceMutation` takes. Used by the
+ * leaves that take only Furnace's lock, where the flag used to be accepted
+ * and ignored.
+ */
+function withFurnaceLockBudget(options) {
+    const { waitLock, ...rest } = options;
+    return pickDefined({ ...rest, waitLockSeconds: resolveWaitLockSeconds(waitLock) });
+}
 async function runEngineLockedFurnaceCommand(context, command, operation, waitLockSeconds) {
     const projectRoot = context.getProjectRoot();
     await withEngineSessionLock(projectRoot, command, () => operation(projectRoot), {
@@ -51,16 +63,24 @@ function registerFurnaceApplyCommand(furnace, context) {
 function registerFurnaceDeployCommand(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
     const deploy = furnace
-        .command('deploy [name]')
-        .description('Apply components and validate in one step')
+        .command('deploy [names...]')
+        .description('Apply components and validate in one step (name several to deploy them under one lock hold)')
         .option('--dry-run', 'Show what would be changed without writing (reads may overlap concurrent mutations)')
         .option('--force', 'Proceed despite baseVersion drift (stale overrides)')
-        .option('--skip-validate', 'Skip the validation step (apply only)');
-    addWaitLockOption(deploy).action(withErrorHandling(async (name, options) => {
+        .option('--skip-validate', 'Skip the validation step (apply only)')
+        .addHelpText('after', [
+        '',
+        'Deploy registers every .mjs and .css file in a custom component directory in',
+        'toolkit/content/jar.mn, including extra modules beside the main one (e.g.',
+        'components/custom/<tag>/<tag>-rows.mjs). Add the file to the directory and run',
+        '`fireforge furnace deploy <tag>` instead of writing the jar.mn line by hand; a line',
+        'that already exists anywhere in jar.mn is kept and never duplicated.',
+    ].join('\n'));
+    addWaitLockOption(deploy).action(withErrorHandling(async (names, options) => {
         const { waitLock, ...rest } = options ?? {};
         const waitLockSeconds = resolveWaitLockSeconds(waitLock);
         const parsed = pickDefined({ ...rest, waitLockSeconds });
-        const run = (projectRoot) => furnaceDeployCommand(projectRoot, name, parsed);
+        const run = (projectRoot) => furnaceDeployCommand(projectRoot, names, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
@@ -103,15 +123,15 @@ function registerFurnaceInfoCommands(furnace, context) {
     }));
     registerFurnaceApplyCommand(furnace, context);
     registerFurnaceDeployCommand(furnace, context);
-    furnace
+    const scan = furnace
         .command('scan')
         .description('Scan engine for available components. Report-only by default: persist the discovered ' +
         'inventory into the stock section of furnace.json with --track (or the interactive ' +
         'prompt); deploy/validate consume the inventory from there.')
         .option('--deep', 'Search additional Firefox directories beyond the default widgets path')
-        .option('--track', 'Persist every discovered untracked component into the stock section of furnace.json (non-interactive)')
-        .action(withErrorHandling(async (options) => {
-        await furnaceScanCommand(getProjectRoot(), pickDefined(options));
+        .option('--track', 'Persist every discovered untracked component into the stock section of furnace.json (non-interactive)');
+    addWaitLockOption(scan).action(withErrorHandling(async (options) => {
+        await furnaceScanCommand(getProjectRoot(), withFurnaceLockBudget(options));
     }));
     furnace
         .command('init')
@@ -122,7 +142,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         .action(withErrorHandling(async (options) => {
         await furnaceInitCommand(getProjectRoot(), options);
     }));
-    furnace
+    const create = furnace
         .command('create [name]')
         .description('Create a new custom component')
         .option('-d, --description <desc>', 'Component description')
@@ -140,9 +160,9 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
         .option('--shared-ftl <path>', 'Participate in an existing feature-scoped .ftl at this path (e.g. "browser/mybrowser-dock.ftl"); skips the per-component .ftl scaffold (implies --localized)')
         .option('--dry-run', 'Show the planned file set and furnace.json changes without writing')
-        .option('--allow-prefix-mismatch', 'Create the component even when its name does not start with the configured `componentPrefix` in furnace.json. Without this flag the command refuses to write anything on a prefix mismatch.')
-        .action(withErrorHandling(async (name, options) => {
-        await furnaceCreateCommand(getProjectRoot(), name, options);
+        .option('--allow-prefix-mismatch', 'Create the component even when its name does not start with the configured `componentPrefix` in furnace.json. Without this flag the command refuses to write anything on a prefix mismatch.');
+    addWaitLockOption(create).action(withErrorHandling(async (name, options) => {
+        await furnaceCreateCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
     registerChromeDocCommands(furnace, context);
 }
@@ -151,23 +171,23 @@ function registerChromeDocCommands(furnace, context) {
     const chromeDoc = furnace
         .command('chrome-doc')
         .description('Scaffold top-level chrome documents (xhtml + js + css + ftl + jar.mn)');
-    chromeDoc
+    const chromeDocCreate = chromeDoc
         .command('create <name>')
         .description('Scaffold a new top-level chrome document')
         .option('--no-titlebar', 'Frameless overlay-style document (omits titlebar-buttonbox)')
         .option('--browser-window', 'Emit the browser.xhtml-like main-window skeleton (<html id="main-window"> with windowtype/chromehidden/persist root attributes platform C++ reads before scripts run) for the document configured as the fork\'s main browser window; implies the titlebar markup')
         .option('--with-tests', 'Scaffold an xpcshell packaging-verification test that probes XCurProcD/chrome/browser/... directly (bypasses the xpcshell chrome:// URI limitation).')
-        .option('--dry-run', 'Show the chrome-doc scaffold plan without writing')
-        .action(withErrorHandling(async (name, options) => {
-        await furnaceChromeDocCreateCommand(getProjectRoot(), name, pickDefined(options));
+        .option('--dry-run', 'Show the chrome-doc scaffold plan without writing');
+    addWaitLockOption(chromeDocCreate).action(withErrorHandling(async (name, options) => {
+        await furnaceChromeDocCreateCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
-    chromeDoc
+    const chromeDocRemove = chromeDoc
         .command('remove <name>')
         .description('Remove a scaffolded top-level chrome document')
         .option('-y, --yes', 'Skip confirmation')
-        .option('--dry-run', 'Show the chrome-doc removal plan without writing')
-        .action(withErrorHandling(async (name, options) => {
-        await furnaceChromeDocRemoveCommand(getProjectRoot(), name, pickDefined(options));
+        .option('--dry-run', 'Show the chrome-doc removal plan without writing');
+    addWaitLockOption(chromeDocRemove).action(withErrorHandling(async (name, options) => {
+        await furnaceChromeDocRemoveCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
 }
 /**
@@ -178,12 +198,13 @@ function registerChromeDocCommands(furnace, context) {
  */
 function registerFurnaceModifyCommands(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    furnace
+    const override = furnace
         .command('override [names...]')
         .description('Fork one or more existing components for modification')
         .addOption(new Option('-t, --type <type>', 'Override type').choices(['css-only', 'full']))
-        .option('-d, --description <desc>', 'Description')
-        .action(withErrorHandling(async (names, options) => {
+        .option('-d, --description <desc>', 'Description');
+    addWaitLockOption(override).action(withErrorHandling(async (names, rawOptions) => {
+        const options = withFurnaceLockBudget(rawOptions);
         if (names.length <= 1) {
             await furnaceOverrideCommand(getProjectRoot(), names[0], options);
         }
@@ -198,26 +219,29 @@ function registerFurnaceModifyCommands(furnace, context) {
         .action(withErrorHandling(async (options) => {
         await furnaceListCommand(getProjectRoot(), options);
     }));
-    furnace
+    const remove = furnace
         .command('remove <name>')
         .description('Remove a component from the workspace')
-        .option('-y, --yes', 'Skip confirmation')
-        .action(withErrorHandling(async (name, options) => {
-        await furnaceRemoveCommand(getProjectRoot(), name, options);
+        .option('-y, --yes', 'Skip confirmation');
+    addWaitLockOption(remove).action(withErrorHandling(async (name, options) => {
+        await furnaceRemoveCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
-    furnace
+    const preview = furnace
         .command('preview')
         .description('Start component preview (Storybook)')
-        .option('--install', 'Force reinstall Storybook dependencies')
-        .action(withErrorHandling(async (options) => {
-        await furnacePreviewCommand(getProjectRoot(), options);
+        .option('--install', 'Force reinstall Storybook dependencies');
+    addWaitLockOption(preview).action(withErrorHandling(async (options) => {
+        await furnacePreviewCommand(getProjectRoot(), withFurnaceLockBudget(options));
     }));
     furnace
         .command('validate [name]')
         .description('Run accessibility and compatibility checks')
         .option('--fix', 'Auto-fix registration issues (missing jar.mn entries, customElements.js)')
+        .option('--json', 'Write the result as one JSON document (findings, excepted findings, stale exceptions, verdict) to stdout')
+        .option('--max-warnings <n>', 'Fail when more than <n> warnings remain after furnace.json validationExceptions (0 for a warning-clean gate)')
         .action(withErrorHandling(async (name, options) => {
-        await furnaceValidateCommand(getProjectRoot(), name, pickDefined(options ?? {}));
+        const { maxWarnings, ...rest } = options ?? {};
+        await furnaceValidateCommand(getProjectRoot(), name, pickDefined({ ...rest, maxWarnings: parseMaxWarnings(maxWarnings) }));
     }));
     furnace
         .command('diff [name]')
@@ -225,21 +249,22 @@ function registerFurnaceModifyCommands(furnace, context) {
         .action(withErrorHandling(async (name) => {
         await furnaceDiffCommand(getProjectRoot(), name);
     }));
-    furnace
+    const refresh = furnace
         .command('refresh [name]')
         .description('Merge upstream Firefox changes into overrides (three-way merge)')
         .option('--dry-run', 'Show what would change without modifying files')
         .option('-a, --all', 'Refresh all overrides in a single batch')
         .addOption(new Option('-s, --strategy <strategy>', 'Auto-resolve conflicts (ours = keep local, theirs = accept upstream)').choices(['ours', 'theirs']))
-        .option('--reset-base', 'Reset baseline to current engine HEAD (skips three-way merge, recovers from missing baseCommit)')
-        .action(withErrorHandling(async (name, options) => {
-        await furnaceRefreshCommand(getProjectRoot(), name, pickDefined(options));
+        .option('--reset-base', 'Reset baseline to current engine HEAD (skips three-way merge, recovers from missing baseCommit)');
+    addWaitLockOption(refresh).action(withErrorHandling(async (name, options) => {
+        await furnaceRefreshCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
-    furnace
+    const rename = furnace
         .command('rename <old-name> <new-name>')
         .description('Rename a component (updates files, config, and registrations)')
-        .action(withErrorHandling(async (oldName, newName) => {
-        await furnaceRenameCommand(getProjectRoot(), oldName, newName);
+        .option('--dry-run', 'Show the planned file moves, furnace.json change and engine registration edits without writing');
+    addWaitLockOption(rename).action(withErrorHandling(async (oldName, newName, options) => {
+        await furnaceRenameCommand(getProjectRoot(), oldName, newName, withFurnaceLockBudget(options));
     }));
     registerFurnaceSyncCommand(furnace, context);
 }

package/dist/src/commands/furnace/init.js

@@ -2,7 +2,7 @@
 import { stat } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, posix } from 'node:path';
 import { text } from '@clack/prompts';
-import { getProjectPaths, loadConfig, mutateConfig, writeConfig } from '../../core/config.js';
+import { getProjectPaths, loadConfig, loadRawConfigDocument, mutateConfig, validateConfig, withConfigFileLock, writeConfigDocument, } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
 import { createDefaultFurnaceConfig, furnaceConfigExists, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { DEFAULT_LICENSE } from '../../core/license-headers.js';
@@ -239,14 +239,21 @@ async function scaffoldTokensCss(projectRoot) {
     // `fireforge lint` after a `token add` fails on raw-color-value issues for
     // tokens the operator just created. The add is idempotent, so re-running
     // `furnace init --force` does not duplicate the entry.
+    // The edit seeds from the raw document under the config lock, like
+    // `fireforge config`: a validated round-trip would drop keys written with
+    // `config --force`, and an unlocked one could lose a concurrent write.
     try {
         const existingAllowlist = forgeConfig.patchLint?.rawColorAllowlist ?? [];
         if (!existingAllowlist.includes(tokensCssPath)) {
-            const updatedConfig = mutateConfig(forgeConfig, 'patchLint.rawColorAllowlist', [
-                ...existingAllowlist,
-                tokensCssPath,
-            ]);
-            await writeConfig(projectRoot, updatedConfig);
+            await withConfigFileLock(projectRoot, async () => {
+                const raw = await loadRawConfigDocument(projectRoot);
+                const current = validateConfig(raw).patchLint?.rawColorAllowlist ?? [];
+                if (current.includes(tokensCssPath))
+                    return;
+                const updated = mutateConfig(raw, 'patchLint.rawColorAllowlist', [...current, tokensCssPath], true);
+                validateConfig(updated);
+                await writeConfigDocument(projectRoot, updated);
+            });
             info(`Added ${tokensCssPath} to patchLint.rawColorAllowlist`);
         }
     }

package/dist/src/commands/furnace/override.js

@@ -6,7 +6,7 @@ import { getProjectPaths, loadConfig, loadState } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
 import { getFurnacePaths, writeFurnaceConfig } from '../../core/furnace-config.js';
 import { resolveFtlDir } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -160,7 +160,7 @@ async function performOverrideMutations(args) {
                 subject: `component "${args.componentName}"`,
             });
         }
-    });
+    }, waitLockMutationOptions(args.waitLockSeconds));
 }
 /**
  * Throws if `componentName` is already classified as something `override`
@@ -322,6 +322,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
         ftlDir,
         firefoxVersion: forgeConfig.firefox.version,
         ...(state.baseCommit ? { baseCommit: state.baseCommit } : {}),
+        waitLockSeconds: options.waitLockSeconds,
     });
     // --- Success ---
     note(`Files copied to components/overrides/${componentName}/:\n` +
@@ -421,6 +422,7 @@ export async function furnaceBatchOverrideCommand(projectRoot, names, options =
                 ftlDir,
                 firefoxVersion: forgeConfig.firefox.version,
                 ...(state.baseCommit ? { baseCommit: state.baseCommit } : {}),
+                waitLockSeconds: options.waitLockSeconds,
             });
             succeeded.push(componentName);
         }

package/dist/src/commands/furnace/preview.js

@@ -2,7 +2,7 @@
 import { join } from 'node:path';
 import { applyAllComponents } from '../../core/furnace-apply.js';
 import { updateFurnaceState } from '../../core/furnace-config.js';
-import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { restoreRollbackJournal } from '../../core/furnace-rollback.js';
 import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
@@ -224,7 +224,7 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
     // entrypoint's global signal handlers consulting the lifecycle registry.
     // The body's own try/catch + teardown path handles the normal exit case
     // (mach storybook returns or throws).
-    await runFurnaceMutation(projectRoot, 'preview-teardown', async (ctx) => {
+    const mutate = async (ctx) => {
         // Register the stories cleanup as an extra teardown hook so the signal
         // handler can wipe the staged stories directory in addition to the
         // journal restore.
@@ -336,7 +336,8 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
             // holds and downstream formatters always see a message/stack pair.
             throw toError(primaryError);
         }
-    });
+    };
+    await runFurnaceMutation(projectRoot, 'preview-teardown', mutate, waitLockMutationOptions(options.waitLockSeconds));
     if (previewResult &&
         previewResult.exitCode !== 0 &&
         previewResult.exitCode !== 130 &&

package/dist/src/commands/furnace/refresh.js

@@ -6,7 +6,7 @@ import { getOverrideEngineTargetPath } from '../../core/furnace-apply-helpers.js
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { resolveFtlDir } from '../../core/furnace-constants.js';
 import { isComponentSourceFile } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { refreshOverrideFile } from '../../core/furnace-refresh.js';
 import { createRollbackJournal, restoreRollbackJournal, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -165,7 +165,7 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
             }
             throw error;
         }
-    }, { dryRun });
+    }, { dryRun, ...waitLockMutationOptions(options.waitLockSeconds) });
     return { results, currentVersion };
 }
 /**

package/dist/src/commands/furnace/remove.js

@@ -6,7 +6,7 @@ import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { resolveFtlDir, xpcshellTestParentDir } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { createRollbackJournal, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { isGitRepository } from '../../core/git.js';
 import { deregisterTestManifest } from '../../core/moz-manifest-register.js';
@@ -343,7 +343,7 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
     // rollback pathway.
     const paths = getProjectPaths(projectRoot);
     await requireGitEngineForRemove(type, name, paths.engine);
-    await runFurnaceMutation(projectRoot, 'remove-rollback', async (ctx) => {
+    const mutate = async (ctx) => {
         const journal = createRollbackJournal();
         ctx.registerJournal(journal);
         try {
@@ -408,7 +408,8 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                 subject: `component "${name}"`,
             });
         }
-    });
+    };
+    await runFurnaceMutation(projectRoot, 'remove-rollback', mutate, waitLockMutationOptions(options.waitLockSeconds));
     info(`Removed "${name}" from furnace.json`);
     outro('Component removed');
 }

package/dist/src/commands/furnace/rename-dry-run.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `furnace rename --dry-run`: the plan a rename would carry out, rendered
+ * from reads only. A rename edits three engine registration files besides
+ * moving the component, and before this none of those edits was visible
+ * until it had run.
+ */
+import type { FurnaceConfig } from '../../types/furnace.js';
+/** Inputs for {@link renderRenamePlan}. */
+export interface RenamePlanInput {
+    config: FurnaceConfig;
+    oldName: string;
+    newName: string;
+    /** Workspace directory of the component being renamed. */
+    oldDir: string;
+    /** On-disk directory label: `custom` or `overrides`. */
+    componentDirLabel: 'custom' | 'overrides';
+    engineDir: string;
+    /** Project marker a freshly added registration line would carry. */
+    markerComment: string | undefined;
+}
+/**
+ * Renders the rename plan: workspace file moves, the furnace.json re-key,
+ * and, for a custom component, every engine edit the real run would make
+ * (registrations only when the component is registered).
+ *
+ * @param input - See {@link RenamePlanInput}
+ * @returns The plan as display lines joined by newlines
+ */
+export declare function renderRenamePlan(input: RenamePlanInput): Promise<string>;

package/dist/src/commands/furnace/rename-dry-run.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `furnace rename --dry-run`: the plan a rename would carry out, rendered
+ * from reads only. A rename edits three engine registration files besides
+ * moving the component, and before this none of those edits was visible
+ * until it had run.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isComponentSourceFile, JAR_MN, resolveFtlChromeSubPath, resolveFtlDir, resolveFtlLocaleJarMnPath, } from '../../core/furnace-constants.js';
+import { hasLocaleFtlJarMnEntry } from '../../core/furnace-registration.js';
+import { isTagAlreadyRegistered } from '../../core/furnace-registration-ast.js';
+import { pathExists, readText } from '../../utils/fs.js';
+import { renameComponentFileName, renameTagInDescription } from './rename-helpers.js';
+/** Plan lines for the workspace move and the furnace.json re-key. */
+async function workspaceLines(input) {
+    const { config, oldName, newName, oldDir, componentDirLabel } = input;
+    const lines = [
+        `Workspace: components/${componentDirLabel}/${oldName}/ → components/${componentDirLabel}/${newName}/`,
+    ];
+    const entries = (await readdir(oldDir, { withFileTypes: true }))
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .sort();
+    for (const fileName of entries) {
+        const renamed = renameComponentFileName(fileName, oldName, newName);
+        const rewrite = isComponentSourceFile(fileName) ? ' (tag and class references rewritten)' : '';
+        lines.push(`  ${fileName}${renamed === fileName ? '' : ` → ${renamed}`}${rewrite}`);
+    }
+    const entry = config.custom[oldName] ?? config.overrides[oldName];
+    lines.push(`furnace.json: "${oldName}" → "${newName}"`);
+    if (entry) {
+        const description = renameTagInDescription(entry.description, oldName, newName);
+        if (description !== entry.description) {
+            lines.push(`  description: "${entry.description}" → "${description}"`);
+        }
+    }
+    return lines;
+}
+/** Plan line for the customElements.js registration. */
+async function customElementsLine(input) {
+    const { engineDir, oldName, newName, markerComment } = input;
+    const path = join(engineDir, 'toolkit/content/customElements.js');
+    if (!(await pathExists(path)))
+        return undefined;
+    const content = await readText(path);
+    const oldRegistered = isTagAlreadyRegistered(content, oldName);
+    if (isTagAlreadyRegistered(content, newName)) {
+        return `customElements.js: "${newName}" is already registered${oldRegistered ? `; remove the "${oldName}" entry` : ''}`;
+    }
+    if (oldRegistered) {
+        return `customElements.js: rewrite the "${oldName}" entry in place as "${newName}" (position and marker comments kept)`;
+    }
+    const marker = markerComment !== undefined ? ` marked // ${markerComment}:` : '';
+    return `customElements.js: add a "${newName}" entry${marker}`;
+}
+/** Plan line for the toolkit/content/jar.mn widget lines. */
+async function jarLine(input) {
+    const { engineDir, oldName, newName, oldDir } = input;
+    const path = join(engineDir, JAR_MN);
+    if (!(await pathExists(path)))
+        return undefined;
+    const oldLines = (await readText(path))
+        .split('\n')
+        .filter((line) => line.includes(`(widgets/${oldName}/`)).length;
+    const newFiles = (await readdir(oldDir, { withFileTypes: true }))
+        .filter((entry) => entry.isFile() && /\.(?:mjs|css)$/.test(entry.name))
+        .map((entry) => renameComponentFileName(entry.name, oldName, newName))
+        .sort();
+    return (`${JAR_MN}: replace ${oldLines} "${oldName}" line(s) with ` +
+        (newFiles.length > 0 ? newFiles.join(', ') : 'none (no .mjs/.css files)'));
+}
+/** Plan lines for the deployed .ftl and its locale jar.mn line. */
+async function localeLines(input, componentConfig) {
+    const { config, engineDir, oldName, newName } = input;
+    if (!componentConfig.localized)
+        return [];
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
+    const lines = [];
+    if (await pathExists(join(engineDir, ftlDir, `${oldName}.ftl`))) {
+        lines.push(`${ftlDir}/${oldName}.ftl → ${newName}.ftl`);
+    }
+    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
+    if (chromeSubPath === undefined || localeJarRel === undefined)
+        return lines;
+    const present = await hasLocaleFtlJarMnEntry(engineDir, localeJarRel, oldName, chromeSubPath);
+    if (componentConfig.sharedFtl !== undefined) {
+        lines.push(`${localeJarRel}: no per-component line (sharedFtl: ${componentConfig.sharedFtl})` +
+            (present ? `; remove the stale "${oldName}.ftl" line` : ''));
+    }
+    else {
+        lines.push(present
+            ? `${localeJarRel}: re-point the "${oldName}.ftl" line to "${newName}.ftl"`
+            : `${localeJarRel}: no "${oldName}.ftl" line to re-point (left unchanged)`);
+    }
+    return lines;
+}
+/**
+ * Renders the rename plan: workspace file moves, the furnace.json re-key,
+ * and, for a custom component, every engine edit the real run would make
+ * (registrations only when the component is registered).
+ *
+ * @param input - See {@link RenamePlanInput}
+ * @returns The plan as display lines joined by newlines
+ */
+export async function renderRenamePlan(input) {
+    const lines = await workspaceLines(input);
+    const componentConfig = input.config.custom[input.oldName];
+    if (!componentConfig || !(await pathExists(input.engineDir))) {
+        return lines.join('\n');
+    }
+    lines.push('Engine:');
+    const engineLines = componentConfig.register
+        ? [
+            await customElementsLine(input),
+            await jarLine(input),
+            ...(await localeLines(input, componentConfig)),
+        ].filter((line) => line !== undefined)
+        : ['registrations untouched (register: false)'];
+    if (await pathExists(join(input.engineDir, componentConfig.targetPath))) {
+        engineLines.push(`remove the stale deployed directory ${componentConfig.targetPath}/`);
+    }
+    lines.push(...engineLines.map((line) => `  ${line}`));
+    lines.push('Test scaffolds named after the old tag are renamed when present.');
+    return lines.join('\n');
+}

package/dist/src/commands/furnace/rename-helpers.d.ts

@@ -3,6 +3,13 @@ import type { FurnaceConfig } from '../../types/furnace.js';
  * Applies a component rename to scaffold-owned filenames only.
  */
 export declare function renameComponentFileName(fileName: string, oldName: string, newName: string): string;
+/**
+ * Rewrites whole-tag mentions of the old name in a component description,
+ * so a rename does not carry a description that still names the old tag.
+ * Boundary-aware like the source rewrite: `moz-panel` inside
+ * `moz-panel-group` is left alone.
+ */
+export declare function renameTagInDescription(description: string, oldName: string, newName: string): string;
 /**
  * Re-keys a custom component config entry and same-config compose references.
  */

package/dist/src/commands/furnace/rename-helpers.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { updateFurnaceState } from '../../core/furnace-config.js';
+import { escapeRegex } from '../../utils/regex.js';
 /**
  * Applies a component rename to scaffold-owned filenames only.
  */
@@ -11,6 +12,15 @@ export function renameComponentFileName(fileName, oldName, newName) {
     }
     return fileName;
 }
+/**
+ * Rewrites whole-tag mentions of the old name in a component description,
+ * so a rename does not carry a description that still names the old tag.
+ * Boundary-aware like the source rewrite: `moz-panel` inside
+ * `moz-panel-group` is left alone.
+ */
+export function renameTagInDescription(description, oldName, newName) {
+    return description.replace(new RegExp(`(?<![\\w-])${escapeRegex(oldName)}(?![\\w-])`, 'g'), newName);
+}
 /**
  * Re-keys a custom component config entry and same-config compose references.
  */
@@ -20,6 +30,7 @@ export function updateConfigForCustomRename(config, oldName, newName) {
         return;
     config.custom[newName] = {
         ...oldConfig,
+        description: renameTagInDescription(oldConfig.description, oldName, newName),
         targetPath: oldConfig.targetPath.replace(new RegExp(`(^|/)${oldName}$`), `$1${newName}`),
     };
     // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- idiomatic key removal from config record
@@ -37,7 +48,10 @@ export function updateConfigForOverrideRename(config, oldName, newName) {
     const oldConfig = config.overrides[oldName];
     if (!oldConfig)
         return;
-    config.overrides[newName] = { ...oldConfig };
+    config.overrides[newName] = {
+        ...oldConfig,
+        description: renameTagInDescription(oldConfig.description, oldName, newName),
+    };
     // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- idiomatic key removal from config record
     delete config.overrides[oldName];
 }

package/dist/src/commands/furnace/rename-registrations.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Engine registration edits for `furnace rename`: the customElements.js
+ * entry (rewritten in place, keeping its marker comments), the
+ * toolkit/content/jar.mn widget lines, the deployed `.ftl`, and the locale
+ * jar.mn line (re-pointed only when one existed, never for `sharedFtl`).
+ */
+import { type RollbackJournal } from '../../core/furnace-rollback.js';
+import type { CustomComponentConfig } from '../../types/furnace.js';
+/**
+ * The project marker (`// <MARKER>:`) a registration line written by the
+ * rename carries, resolved exactly as `furnace apply` resolves it. An
+ * unreadable fireforge.json degrades to no marker rather than failing the
+ * rename.
+ */
+export declare function loadMarkerComment(projectRoot: string): Promise<string | undefined>;
+/** Inputs for {@link updateEngineRegistrations}. */
+export interface UpdateEngineRegistrationsOptions {
+    /** Absolute path to the engine checkout. */
+    engineDir: string;
+    /** Tag name being renamed away from. */
+    oldName: string;
+    /** Tag name being renamed to. */
+    newName: string;
+    /** Workspace directory holding the renamed component's files. */
+    newDir: string;
+    /** Engine-relative directory localized components deploy their `.ftl` into. */
+    ftlDir: string;
+    /** The renamed component's furnace.json entry (`localized`, `sharedFtl`). */
+    componentConfig: CustomComponentConfig;
+    /** Project marker for a registration line the rename has to add fresh. */
+    markerComment: string | undefined;
+    /** Rollback journal every write is recorded in. */
+    journal: RollbackJournal;
+}
+/**
+ * Re-points the engine-side registrations (customElements.js, jar.mn, and
+ * the localized `.ftl` entries) from the old tag name to the new one.
+ *
+ * @param options - See {@link UpdateEngineRegistrationsOptions}
+ */
+export declare function updateEngineRegistrations(options: UpdateEngineRegistrationsOptions): Promise<void>;