@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/watch.js

@@ -1,220 +1,22 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { delimiter, dirname } from 'node:path';
-import { Command } from 'commander';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { assertEngineExists } from '../core/engine-precondition.js';
-import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
-import { generateMozconfig, hasBuildArtifacts, hasRunnableBundle, watchWithOutput, } from '../core/mach.js';
-import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
-import { GeneralError } from '../errors/base.js';
-import { BuildError } from '../errors/build.js';
-import { toError } from '../utils/errors.js';
-import { info, intro, outro, spinner, verbose } from '../utils/logger.js';
-import { exec, findExecutable } from '../utils/process.js';
-const WATCHMAN_PROBE_TIMEOUT_MS = 5000;
-/**
- * Probes watchman by running `watchman --version`. A binary that exists
- * in PATH but cannot respond (corrupt install, server crashed mid-session,
- * permission denied on the state directory) would otherwise surface as a
- * confusing mid-watch failure. Returns the trimmed version string when
- * the probe succeeds. Throws a {@link GeneralError} with actionable
- * remediation when it does not.
- */
-async function probeWatchman() {
-    try {
-        const result = await exec('watchman', ['--version'], {
-            timeout: WATCHMAN_PROBE_TIMEOUT_MS,
+import { defineCommand, lockWaitMs } from '../cli/command.js';
+import { deployComponents, watch as watchWorkspace, withWorkspace } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+import { workspaceOptions } from './workspace.js';
+export const watch = defineCommand({
+    name: 'watch',
+    summary: 'Rebuild front-end files as the project changes (mach watch)',
+    description: 'Needs watchman and a completed build. Edits of the engine are rebuilt by mach; edits of a ' +
+        "source-mode project's owned files and of the components are brought into the workspace's " +
+        'engine first. The workspace stays held until the watch is stopped.',
+    group: 'Daily',
+    options: { ...workspaceOptions },
+    run: async (ctx, _args, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const waitMs = lockWaitMs(opts.waitLock);
+        await withWorkspace(project, { command: 'watch', workspace: opts.workspace, waitMs }, async (workspace) => {
+            await deployComponents(workspace, { waitMs });
+            await watchWorkspace(workspace, { env: ctx.env });
         });
-        if (result.exitCode !== 0) {
-            throw new GeneralError(`Watchman is installed but "watchman --version" exited ${result.exitCode}.\n\n` +
-                (result.stderr.trim() ? `Output:\n${result.stderr.trim()}\n\n` : '') +
-                'Re-install or repair watchman, then rerun "fireforge watch".');
-        }
-        const version = result.stdout.trim();
-        if (!version) {
-            throw new GeneralError('Watchman is installed but "watchman --version" produced no output. ' +
-                'Re-install or repair watchman, then rerun "fireforge watch".');
-        }
-        return version;
-    }
-    catch (error) {
-        if (error instanceof GeneralError)
-            throw error;
-        throw new GeneralError(`Watchman is installed but did not respond within ${WATCHMAN_PROBE_TIMEOUT_MS}ms.\n\n` +
-            `Underlying cause: ${toError(error).message}\n\n` +
-            'Common fixes:\n' +
-            '  - Restart watchman: "watchman shutdown-server" then retry\n' +
-            "  - Check filesystem permissions on watchman's state directory\n" +
-            '  - Re-install watchman if the binary is corrupt');
-    }
-}
-/**
- * Builds remediation guidance for objdirs configured before watchman was available.
- * @returns User-facing configure-time watchman guidance
- */
-function buildWatchmanConfigureTimeMessage() {
-    return ('Watch mode cannot use the current obj-* build because watchman was not available when Firefox was configured.\n\n' +
-        'Install watchman, delete the current obj-* directory, run "fireforge build" again, then retry "fireforge watch".');
-}
-function hasWatchPermissionFailure(output) {
-    return /Operation not permitted|EPERM|EACCES/i.test(output);
-}
-/**
- * Builds the generic unsupported-watch failure message.
- *
- * @param exitCode - Exit code returned by `mach watch`
- * @param watchmanPath - Optional absolute path to the resolved watchman
- *   binary, surfaced in the guidance so the operator can see whether
- *   FireForge actually found one.
- * @returns User-facing failure guidance
- */
-function buildUnsupportedWatchMessage(exitCode, watchmanPath, output = '') {
-    const watchmanLine = watchmanPath
-        ? `  - FireForge resolved watchman at ${watchmanPath} and prepended its directory to the mach subprocess PATH. If mach still did not see it, ensure that path is stable between runs.\n`
-        : '';
-    const permissionLine = hasWatchPermissionFailure(output)
-        ? '  - macOS may be blocking watchman or Terminal/Codex from reading the engine directory. Grant Full Disk Access or Files and Folders access to your terminal app and watchman, then restart watchman with "watchman shutdown-server".\n'
-        : '';
-    return (`Watch failed with exit code ${exitCode}. Check the output above for details.\n\n` +
-        'Common causes:\n' +
-        '  - watchman is not installed or not in PATH right now\n' +
-        '  - watchman was installed only after the current obj-* directory was configured; delete obj-* and rebuild\n' +
-        permissionLine +
-        '  - mach watch is unsupported in the current objdir or build environment\n' +
-        watchmanLine +
-        '\n' +
-        'If the failure referenced `watch-project` / `FasterBuildException: timed out`, watchman is likely reachable via `which watchman` from your shell but missing from the subprocess PATH. FireForge now prepends the resolved watchman directory automatically; confirm your watchman install is on a stable path (e.g. /opt/homebrew/bin/watchman on macOS).');
-}
-/**
- * Detects the Firefox-side output produced when watchman was missing at configure time.
- * @param output - Combined stdout and stderr from the watch run
- * @returns True when the output matches the configure-time watchman failure mode
- */
-function hasConfigureTimeWatchmanFailure(output) {
-    return (/watchman/i.test(output) &&
-        /(configure time|configured|configuration time|when (?:this|the current) build was configured)/i.test(output));
-}
-/**
- * Runs the watch command for auto-rebuilding.
- * @param projectRoot - Root directory of the project
- */
-export async function watchCommand(projectRoot) {
-    intro('FireForge Watch');
-    // Load configuration
-    const config = await loadConfig(projectRoot);
-    const paths = getProjectPaths(projectRoot);
-    // Check if engine exists
-    await assertEngineExists(paths.engine);
-    // Resolve the watchman binary to an absolute path up-front so we can (a)
-    // refuse fast when it is missing and (b) prepend its directory to the mach
-    // subprocess PATH. On macOS, `which watchman` from an interactive shell
-    // returns `/opt/homebrew/bin/watchman`, but the Node subprocess PATH
-    // frequently omits `/opt/homebrew/bin`, so the shell probe passes and
-    // mach's `watch-project` call then times out on its own failed PATH
-    // lookup. Threading the directory through the subprocess env fixes it.
-    const watchmanPath = await findExecutable('watchman');
-    if (!watchmanPath) {
-        throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
-            'Install watchman first, then rerun "fireforge watch".');
-    }
-    // Verify watchman actually responds: a binary that is in PATH but
-    // unable to respond (broken install, crashed server, bad state dir
-    // permissions) would otherwise surface as a confusing mid-build failure
-    // instead of an actionable preflight error.
-    await probeWatchman();
-    // Check for build artifacts before starting watch
-    // The mismatch rung rejects copied or relocated obj-* dirs whose mozinfo
-    // metadata (topsrcdir, topobjdir, mozconfig) still points at a different
-    // source tree. mach watch against stale metadata produces confusing errors.
-    const buildCheck = await hasBuildArtifacts(paths.engine);
-    assertBuildArtifacts(paths.engine, buildCheck, {
-        label: 'Watch mode',
-        requirement: 'Watch mode requires a completed build.',
-        remediation: "Run 'fireforge build' first to create the initial build, then run 'fireforge watch'.",
-        requireExisting: true,
-    });
-    // Report bundle state alongside the "Using build artifacts..." banner
-    // so an operator watching a mid-build tree can see why `fireforge run`
-    // would refuse right now while watch is still going. Watch remains
-    // permissive (it exists to drive rebuilds), so this is informational.
-    // The `hasBuildArtifacts` check already passed at this point, so
-    // `objDir` is always defined.
-    const bundleCheck = buildCheck.objDir
-        ? await hasRunnableBundle(paths.engine, config.binaryName, buildCheck.objDir)
-        : { runnable: false };
-    const bundleSuffix = bundleCheck.runnable
-        ? ' (bundle: runnable)'
-        : ' (bundle: pending — watch will rebuild)';
-    info(`Using build artifacts from ${buildCheck.objDir}/${bundleSuffix}`);
-    // Advisory: warn when Furnace components have drifted since the last
-    // apply so the user doesn't launch watch-mode builds with stale
-    // components baked in. Mirrors the check in `fireforge run`: without
-    // it, users editing a component then running `watch` would see their
-    // change never surface in the rebuilt browser.
-    await warnIfFurnaceStale(projectRoot);
-    // Generate mozconfig (in case it's not up to date)
-    const mozconfigSpinner = spinner('Generating mozconfig...');
-    try {
-        await generateMozconfig(paths.configs, paths.engine, config);
-        mozconfigSpinner.stop('mozconfig generated');
-    }
-    catch (error) {
-        mozconfigSpinner.error('Failed to generate mozconfig');
-        throw error;
-    }
-    info('Starting watch mode...');
-    info('Press Ctrl+C to stop\n');
-    // Compose the subprocess env: start from the parent process env, then
-    // prepend the resolved watchman directory to PATH so the mach subprocess
-    // sees the same binary the probe just validated. Without it, a watchman
-    // install under `/opt/homebrew/bin` is absent from the PATH Node inherits
-    // on spawn and `mach watch` fails at the `watch-project` subscription
-    // step.
-    const watchmanDir = dirname(watchmanPath);
-    const existingPath = process.env['PATH'] ?? '';
-    const pathSegments = existingPath.split(delimiter).filter((segment) => segment.length > 0);
-    // Both arms filter identically. The cast this replaced laundered
-    // `string | undefined` on one arm while the other built the annotated shape
-    // honestly.
-    const baseEnv = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value !== undefined)
-            baseEnv[key] = value;
-    }
-    const watchmanEnv = pathSegments.includes(watchmanDir)
-        ? baseEnv
-        : {
-            ...baseEnv,
-            PATH: [watchmanDir, ...pathSegments].join(delimiter),
-        };
-    verbose(`watch: resolved watchman at ${watchmanPath}; forwarding directory in subprocess PATH.`);
-    let result;
-    try {
-        result = await watchWithOutput(paths.engine, { env: watchmanEnv });
-    }
-    catch (error) {
-        throw new BuildError('Watch process failed to start', 'mach watch', error instanceof Error ? error : undefined);
-    }
-    // On Ctrl+C the bin signal handler waits for the mach child to shut
-    // down (waitForActiveChildShutdown) before exiting, so this continuation
-    // can run and whitelist the SIGINT exit code, though the bin may still
-    // win the race and terminate first. Both outcomes are acceptable.
-    if (result.exitCode !== 0 && result.exitCode !== 130) {
-        const combinedOutput = `${result.stdout}\n${result.stderr}`;
-        if (hasConfigureTimeWatchmanFailure(combinedOutput)) {
-            throw new GeneralError(buildWatchmanConfigureTimeMessage());
-        }
-        // 130 is SIGINT (Ctrl+C), which is expected
-        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode, watchmanPath, combinedOutput), 'mach watch');
-    }
-    outro('Watch mode stopped');
-}
-/** Registers the watch command on the CLI program. */
-export function registerWatch(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('watch')
-        .description('Watch for changes and auto-rebuild')
-        .action(withErrorHandling(async () => {
-        await watchCommand(getProjectRoot());
-    }));
-}
+    },
+});

package/dist/src/commands/wire.js

@@ -1,350 +1,61 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join, relative } from 'node:path';
-import { Command } from 'commander';
-import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript, } from '../core/browser-wire.js';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { furnaceConfigExists as checkFurnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
-import { consumeParserFallbackEvents } from '../core/parser-fallback.js';
-import { DEFAULT_DOM_TARGET, probeDomFragmentInsertionPoint } from '../core/wire-dom-fragment.js';
-import { coerceToCall, validateWireName as validateWireExpression } from '../core/wire-utils.js';
-import { InvalidArgumentError } from '../errors/base.js';
-import { toError } from '../utils/errors.js';
-import { pathExists } from '../utils/fs.js';
-import { info, intro, outro, success, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
-import { isContainedRelativePath, isExplicitAbsolutePath, isPathInsideRoot, stripEnginePrefix, toRootRelativePath, } from '../utils/paths.js';
-import { normalizePathSlashes } from '../utils/paths.js';
-const BROWSER_BASE_DIR = 'browser/base';
-function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPath, options) {
-    info('[dry-run] Would wire subscript:');
-    info(`  source: ${subscriptDir}/${name}.js`);
-    info(`  browser-main.js: loadSubScript("chrome://browser/content/${name}.js")`);
-    if (options.init) {
-        // Show the coerced form so the preview matches the emitted block.
-        // Echoing the raw input ("X.init") does not reflect that the real run
-        // writes `X.init();` to browser-init.js.
-        info(`  browser-init.js: ${coerceToCall(options.init)}`);
-    }
-    if (options.destroy) {
-        info(`  browser-init.js onUnload(): ${coerceToCall(options.destroy)}`);
-    }
-    if (domFilePath) {
-        const includePath = normalizePathSlashes(relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)));
-        info(`  ${domTargetPath}: #include ${includePath}`);
-    }
-    const relPath = normalizePathSlashes(relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)));
-    info(`  jar.mn: content/browser/${name}.js (${relPath}/${name}.js)`);
-    outro('Dry run complete');
-}
-/**
- * Resolves the chrome document the `#include` directive is inserted into.
- *
- * Preference order:
- *   1. `--target <path>` CLI flag (explicit caller intent)
- *   2. First entry of `furnace.json.tokenHostDocuments` (fork-configured
- *      chrome doc list, already consumed by the missing-token-link
- *      validator and the doctor check)
- *   3. `browser/base/content/browser.xhtml` (upstream default)
- *
- * Step 2 is silent: a missing or invalid furnace.json falls through to the
- * upstream default rather than surfacing a warning, because forks that don't
- * use furnace shouldn't have to configure anything.
- */
-async function resolveDomTargetPath(projectRoot, explicit) {
-    if (explicit !== undefined) {
-        return explicit;
-    }
-    if (await checkFurnaceConfigExists(projectRoot)) {
-        try {
-            const furnaceConfig = await loadFurnaceConfig(projectRoot);
-            const first = furnaceConfig.tokenHostDocuments?.[0];
-            if (first !== undefined && first.length > 0) {
-                return first;
-            }
-        }
-        catch {
-            // Fall through to the default. A broken furnace.json should not block
-            // the wire command. The doctor surfaces that issue separately.
-        }
-    }
-    return DEFAULT_DOM_TARGET;
-}
-/**
- * Validates a subscript name supplied on the command line. Subscripts are
- * resolved into filenames under the subscript directory and registered in
- * jar.mn by this name, so any path separator or `..` segment would let
- * the caller write outside the intended directory or corrupt the manifest.
- * Mirrors the validation already applied to setup's binaryName and furnace
- * custom component targetPath.
- */
-function validateWireName(name) {
-    if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(name)) {
-        throw new InvalidArgumentError(`Subscript name "${name}" is invalid. ` +
-            'Names must start with a letter or underscore and contain only letters, digits, underscores, or hyphens. ' +
-            'Path separators and parent-directory segments are not permitted.', 'name');
-    }
-}
-/**
- * Asserts that the resolved chrome document both exists on disk and exposes
- * an insertion anchor (`#include browser-sets.inc` or `<html:body>`) that
- * `addDomFragment` can splice into. Fires in dry-run and real-run mode
- * alike, so the preview and execution agree on whether the target is
- * wireable before any disk mutations happen. Running it only on the real
- * branch lets the dry-run produce a plausible-looking plan the real run then
- * refuses with `Could not find insertion point in chrome document`.
- */
-async function assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath) {
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(join(paths.engine, domTargetPath)))) {
-        throw new InvalidArgumentError(`Chrome document not found in engine: ${domTargetPath}\n` +
-            'Set "tokenHostDocuments" in furnace.json (first entry is used by wire) ' +
-            'or pass --target <path>.', 'target');
-    }
-    try {
-        await probeDomFragmentInsertionPoint(paths.engine, domFilePath, domTargetPath);
-    }
-    catch (probeError) {
-        throw new InvalidArgumentError(`${toError(probeError).message}\n` +
-            `The resolved chrome document ${domTargetPath} does not expose an insertion anchor ` +
-            'that `fireforge wire` recognises (`#include browser-sets.inc` or `<html:body>`). ' +
-            'Add one of those anchors to the chrome doc, or target a document that has them via ' +
-            '`--target <path>`.', 'target');
-    }
-}
-async function resolveWireSubscriptDir(projectRoot, options) {
-    let subscriptDir = DEFAULT_BROWSER_SUBSCRIPT_DIR;
-    try {
-        const config = await loadConfig(projectRoot);
-        if (config.wire?.subscriptDir) {
-            subscriptDir = config.wire.subscriptDir;
-        }
-    }
-    catch (error) {
-        warn(`Using default wire.subscriptDir because fireforge.json could not be loaded: ${toError(error).message}`);
-    }
-    if (options.subscriptDir) {
-        if (!isContainedRelativePath(options.subscriptDir)) {
-            throw new InvalidArgumentError(`Subscript directory must stay within engine/: ${options.subscriptDir}`, 'subscriptDir');
-        }
-        subscriptDir = options.subscriptDir;
-    }
-    return subscriptDir;
-}
-async function ensureSubscriptSourceExists(projectRoot, subscriptDir, name, dryRun) {
-    const paths = getProjectPaths(projectRoot);
-    const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);
-    if (!(await pathExists(subscriptPath))) {
-        if (dryRun) {
-            info(`Note: ${subscriptDir}/${name}.js does not exist yet — the real wire command will require it before writing. Create the file before re-running without --dry-run.`);
-        }
-        else {
-            throw new InvalidArgumentError(`Subscript file not found: ${subscriptDir}/${name}.js\n` +
-                'Create the file in engine/ before wiring.', 'name');
-        }
-    }
-}
-/**
- * Validates the `--dom` fragment argument and computes its engine-root-
- * relative path. Accepts absolute, repo-root-relative (`engine/...`), and
- * engine-relative inputs. Rejects missing files and paths escaping
- * engine/. Returns undefined when `--dom` was not supplied.
- */
-async function resolveDomFragmentPath(projectRoot, dom) {
-    // Validate the DOM fragment file exists and compute its path relative to
-    // the engine root. Accepts three shapes:
-    //  - Absolute paths (`/project/engine/browser/base/content/foo.inc.xhtml`)
-    //  - Repo-root-relative forms (`engine/browser/base/content/foo.inc.xhtml`)
-    //  - Engine-relative forms (`browser/base/content/foo.inc.xhtml`)
-    //
-    // Without the engine-prefix normalization, an `engine/…`-prefixed relative
-    // path from the repo root double-roots through
-    // `toRootRelativePath(engineDir, …)`: `resolve(engineDir, 'engine/…')`
-    // lands at `engineDir/engine/…`, still "inside" engineDir but named as a
-    // second-level `engine/…` entry, and the computed `#include` then reads
-    // `../../../engine/browser/base/content/foo.inc.xhtml`. Absolute inputs are
-    // already handled correctly by `toRootRelativePath`, so the prefix is only
-    // stripped when the input is relative.
-    if (!dom)
-        return undefined;
-    {
-        const paths = getProjectPaths(projectRoot);
-        const domCandidate = isExplicitAbsolutePath(dom) ? dom : stripEnginePrefix(dom);
-        // `pathExists` resolves relative paths against CWD, so an
-        // engine-relative `domCandidate` (e.g.
-        // `browser/base/content/foo.inc.xhtml`) would be probed inside the
-        // operator's shell directory rather than the engine root and fail "DOM
-        // fragment file not found" even when the file is sitting at
-        // engine/<path>. Mirror `register.ts`: probe the absolute path as-is,
-        // otherwise join with `paths.engine` first. The `isPathInsideRoot` /
-        // `toRootRelativePath` calls below keep operating on `domCandidate`
-        // because they internally resolve relative candidates against the engine
-        // root, matching the probe path built here.
-        const domProbePath = isExplicitAbsolutePath(domCandidate)
-            ? domCandidate
-            : join(paths.engine, domCandidate);
-        if (!(await pathExists(domProbePath))) {
-            throw new InvalidArgumentError(`DOM fragment file not found: ${dom}`, 'dom');
-        }
-        if (!isPathInsideRoot(paths.engine, domCandidate)) {
-            throw new InvalidArgumentError(`DOM fragment file must stay within engine/: ${dom}`, 'dom');
-        }
-        return toRootRelativePath(paths.engine, domCandidate);
-    }
-}
-/**
- * Builds the wireSubscript option bag from the command flags, omitting
- * every key whose flag is absent (exactOptionalPropertyTypes) and the
- * defaults the lower layer already assumes.
- */
-function buildWireSubscriptOptions(options, domFilePath, domTargetPath, subscriptDir) {
-    return {
-        ...(options.init !== undefined ? { init: options.init } : {}),
-        ...(options.destroy !== undefined ? { destroy: options.destroy } : {}),
-        ...(domFilePath !== undefined ? { domFilePath } : {}),
-        ...(domFilePath !== undefined && domTargetPath !== DEFAULT_DOM_TARGET ? { domTargetPath } : {}),
-        ...(options.after !== undefined ? { after: options.after } : {}),
-        ...(subscriptDir !== DEFAULT_BROWSER_SUBSCRIPT_DIR ? { subscriptDir } : {}),
-        dryRun: false,
-    };
-}
-/**
- * Surfaces any regex parser fallbacks the wiring run consumed, so the
- * operator knows which files were mutated by the regex path rather than
- * the AST path.
- */
-function reportParserFallbacks() {
-    const parserFallbacks = consumeParserFallbackEvents();
-    if (parserFallbacks.length > 0) {
-        const contexts = [...new Set(parserFallbacks.map((event) => event.context))];
-        info(`Legacy parser fallback was used for ${contexts.length} file${contexts.length === 1 ? '' : 's'}: ${contexts.join(', ')}`);
-    }
-}
-/**
- * Prints the per-mutation success/skip rows for a completed (non-dry-run)
- * wire invocation.
- */
-function reportWireResult(result, name, options, domFilePath, domTargetPath) {
-    if (result.subscriptAdded) {
-        success(`Added loadSubScript for ${name}.js to browser-main.js`);
-    }
-    else {
-        info(`${name}.js already registered in browser-main.js (skipped)`);
-    }
-    if (options.init) {
-        if (result.initAdded) {
-            success(`Added init expression to browser-init.js onLoad()`);
-        }
-        else {
-            info(`Init expression already present in browser-init.js (skipped)`);
-        }
-    }
-    if (options.destroy) {
-        if (result.destroyAdded) {
-            success(`Added destroy expression to browser-init.js onUnload()`);
-        }
-        else {
-            info(`Destroy expression already present in browser-init.js (skipped)`);
-        }
-    }
-    if (domFilePath) {
-        if (result.domInserted) {
-            success(`Inserted #include directive into ${domTargetPath}`);
-        }
-        else {
-            info(`#include directive already present in ${domTargetPath} (skipped)`);
-        }
-    }
-    if (result.jarMnResult.skipped) {
-        info(`${name}.js already registered in jar.mn (skipped)`);
-    }
-    else {
-        success(`Registered ${name}.js in ${result.jarMnResult.manifest}`);
-    }
-}
-/**
- * Wires a chrome subscript into the browser.
- *
- * @param projectRoot - Root directory of the project
- * @param name - Subscript name (without .js extension)
- * @param options - Command options
- */
-export async function wireCommand(projectRoot, name, options = {}) {
-    intro('Wire');
-    validateWireName(name);
-    if (options.after !== undefined) {
-        // --after references an existing init block by its subscript name, so
-        // it must follow the same naming rules as `name` itself. Without this
-        // check, a caller could sneak a path-traversal segment in through
-        // --after and have it forwarded unchanged to the lookup layer.
-        validateWireName(options.after);
-    }
-    // Validate init/destroy expressions before the dry-run/real fork so both
-    // paths enforce the same contract. Validating only inside
-    // `addInitToBrowserInit`/`addDestroyToBrowserInit` (the real-execution
-    // path) lets `--dry-run --init 'void 0'` succeed and render a plausible
-    // preview even though the real run rejects the same arguments.
-    if (options.init !== undefined) {
-        validateWireExpression(options.init, 'init expression');
-    }
-    if (options.destroy !== undefined) {
-        validateWireExpression(options.destroy, 'destroy expression');
-    }
-    consumeParserFallbackEvents();
-    const subscriptDir = await resolveWireSubscriptDir(projectRoot, options);
-    const domFilePath = await resolveDomFragmentPath(projectRoot, options.dom);
-    // Resolve the chrome document the `#include` directive will land in. Only
-    // consulted when `--dom` is supplied, but resolved here anyway so the
-    // dry-run plan can print the target accurately.
-    //
-    // `stripEnginePrefix` is applied so
-    // `--target engine/browser/base/browser.xhtml` and
-    // `--target browser/base/browser.xhtml` are treated identically, matching
-    // the `--dom` normalization above. Absolute `--target` paths stay absolute
-    // (the containment check downstream rejects them).
-    const normalizedTarget = options.target !== undefined && !isExplicitAbsolutePath(options.target)
-        ? stripEnginePrefix(options.target)
-        : options.target;
-    if (normalizedTarget !== undefined && !isContainedRelativePath(normalizedTarget)) {
-        throw new InvalidArgumentError(`Target chrome document must stay within engine/: ${options.target ?? ''}`, 'target');
-    }
-    const domTargetPath = await resolveDomTargetPath(projectRoot, normalizedTarget);
-    if (domFilePath) {
-        await assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath);
-    }
-    // Verify the subscript file exists in engine/, skipping for dry-run:
-    // preview is meant to show the mutation plan without requiring the
-    // subscript to already exist, matching the "plan before write" pattern
-    // setup scripts rely on.
-    //
-    // The check stays advisory rather than fatal in dry-run because
-    // "wire first, create file after" is a legitimate use of preview. But a
-    // dry-run over a typo would otherwise produce a plausible plan and the
-    // real command then refuse with `Subscript file not found`. The info line
-    // surfaces the mismatch in preview mode.
-    await ensureSubscriptSourceExists(projectRoot, subscriptDir, name, options.dryRun ?? false);
-    if (options.dryRun) {
-        printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, domTargetPath, options);
-        return;
-    }
-    const result = await wireSubscript(projectRoot, name, buildWireSubscriptOptions(options, domFilePath, domTargetPath, subscriptDir));
-    reportParserFallbacks();
-    reportWireResult(result, name, options, domFilePath, domTargetPath);
-    outro('Wiring complete');
-}
-/** Registers the wire command on the CLI program. */
-export function registerWire(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('wire <name>')
-        .description('Wire a chrome subscript into the browser')
-        .option('--init <expression>', 'Init expression for browser-init.js onLoad()')
-        .option('--destroy <expression>', 'Destroy expression for browser-init.js onUnload()')
-        .option('--dom <file>', 'XHTML fragment file to insert into the chrome document')
-        .option('--dry-run', 'Show what would be changed without writing')
-        .option('--after <name>', 'Insert init block after the block for this name')
-        .option('--subscript-dir <dir>', 'Subscript directory relative to engine/ (default: browser/base/content)')
-        .option('--target <path>', 'Chrome document to insert --dom into, relative to engine/ ' +
-        '(default: first entry of furnace.json tokenHostDocuments, else browser/base/content/browser.xhtml)')
-        .action(withErrorHandling(async (name, options) => {
-        await wireCommand(getProjectRoot(), name, pickDefined(options));
-    }));
-}
+import { arg, defineCommand, lockOptions, lockWaitMs, opt } from '../cli/command.js';
+import { markerComment } from '../config/index.js';
+import { editTracked, enginePathOf, trackedFiles } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+import { applyEdits, planWire } from '../register/index.js';
+export const wire = defineCommand({
+    name: 'wire',
+    summary: 'Wire a chrome subscript into the browser',
+    description: 'Loads <name>.js from browser-main.js, optionally calls init from onLoad and destroy from ' +
+        'onUnload in browser-init.js, optionally #includes a DOM fragment into the top-level chrome ' +
+        'document, and registers the script in browser/base/jar.mn. Every edit is planned before ' +
+        'any is written. Where scripts live and the chrome document are the wire.subscriptDir and ' +
+        'wire.domTarget keys of fireforge.json.',
+    group: 'Authoring',
+    args: { name: arg.string('Subscript name, without .js') },
+    options: {
+        init: opt.string('Expression called from onLoad, such as Feature.init', {
+            valueName: 'expression',
+        }),
+        destroy: opt.string('Expression called from onUnload, such as Feature.destroy', {
+            valueName: 'expression',
+        }),
+        dom: opt.string('DOM fragment (.inc.xhtml) to #include into the chrome document', {
+            valueName: 'path',
+        }),
+        after: opt.string('Subscript whose init block the new init block follows', {
+            valueName: 'name',
+        }),
+        dryRun: opt.flag('Show the planned edits without writing'),
+        ...lockOptions,
+    },
+    json: true,
+    run: async (ctx, { name }, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const { config } = project;
+        const files = await trackedFiles(project, { declare: true });
+        const plan = await planWire(files, {
+            name,
+            subscriptDir: config.wire.subscriptDir,
+            marker: `${markerComment(config)}:`,
+            requireSubscript: !opts.dryRun,
+            init: opts.init,
+            destroy: opts.destroy,
+            after: opts.after,
+            dom: opts.dom === undefined
+                ? undefined
+                : { file: enginePathOf(project, opts.dom), target: config.wire.domTarget },
+        });
+        if (!opts.dryRun) {
+            await editTracked(project, { label: `wiring ${name}`, command: 'wire', waitMs: lockWaitMs(opts.waitLock) }, (tx) => applyEdits(tx, files, plan.edits));
+        }
+        const verb = opts.dryRun ? 'Would change' : 'Changed';
+        for (const step of plan.steps) {
+            ctx.out.line(step.present
+                ? `Already in place: ${step.path}: ${step.change}`
+                : `${verb} ${step.path}: ${step.change}`);
+        }
+        ctx.out.json({ name, dryRun: opts.dryRun, steps: plan.steps.map((step) => ({ ...step })) });
+    },
+});