@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/commands/verify.js

@@ -1,335 +1,29 @@
 // SPDX-License-Identifier: EUPL-1.2
-/**
- * `fireforge verify`: read-only fsck for the patch queue.
- *
- * Combines the manifest consistency check (orphan files, missing entries,
- * files-affected mismatch, duplicate entries) with the cross-patch lint
- * rules (duplicate /dev/null creation, forward imports). Does not run
- * `planExport` per patch. That is out of scope because it
- * would couple verify to engine state and make the command too slow to be
- * useful as a pre-flight gate. Engine-level patch application issues are
- * still covered by the existing `fireforge doctor` and `fireforge import`
- * paths.
- *
- * Exits non-zero when any error-severity finding is reported so CI can
- * treat the output as pass/fail.
- */
-import { join } from 'node:path';
-import { Command } from 'commander';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { isGitRepository } from '../core/git.js';
-import { withPrivateGitIndex } from '../core/git-readonly-index.js';
-import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
-import { collectWorktreeModuleFiles, findUnresolvedSystemModuleImports, formatUnresolvedSystemModuleImports, } from '../core/module-resolution-preflight.js';
-import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
-import { loadPatchesManifest, validatePatchesManifestConsistency } from '../core/patch-manifest.js';
-import { evaluatePatchPolicy } from '../core/patch-policy.js';
-import { evaluatePatchPolicyContentForQueue } from '../core/patch-policy-content.js';
-import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
-import { buildPatchClaims } from '../core/status-classify.js';
-import { classifyFiles } from '../core/status-classify.js';
-import { GeneralError } from '../errors/base.js';
-import { pathExists, readText } from '../utils/fs.js';
-import { info, intro, outro, success, warn } from '../utils/logger.js';
-import { anyPatchInScope, isFilenameInScope, resolveVerifyScope, scopeLintIssues, scopePatches, } from './verify-scope.js';
-/**
- * Walks each patch body in the manifest, extracts the set of
- * component-shaped registration references it adds (widget paths
- * implied by jar.mn + customElements.js, and FTL paths implied by locale
- * jar.mn), and confirms every reference is either created by some
- * patch in the queue or present as a tracked file in engine/. Any
- * unreachable reference is a dangling-registration error: the patch
- * registers a file that nothing in the world supplies, which fails at
- * install time.
- */
-async function detectDanglingRegistrations(patchesDir, engineDir, patches, scope) {
-    // Aggregate the set of all paths any patch in the queue is responsible for
-    // (per `filesAffected`). Individual patch bodies are deliberately not
-    // parsed for new-file creations here: `filesAffected` is already the
-    // contract manifest callers rely on, and
-    // `validatePatchesManifestConsistency` has already ensured the two are in
-    // sync. Using that list keeps this validator fast.
-    const coveredByPatches = new Set();
-    for (const patch of patches) {
-        for (const file of patch.filesAffected) {
-            coveredByPatches.add(file);
-        }
-    }
-    // Every patch supplies targets; only the scoped ones are judged.
-    const issues = [];
-    for (const patch of scopePatches(patches, scope)) {
-        const patchPath = join(patchesDir, patch.filename);
-        if (!(await pathExists(patchPath)))
-            continue;
-        let body;
-        try {
-            body = await readText(patchPath);
-        }
-        catch {
-            // Bad file read is surfaced by the manifest consistency check
-            // already. Skipping here avoids double-reporting the same issue.
-            continue;
-        }
-        const refs = collectPatchRegistrationReferences(body);
-        if (refs.length === 0)
-            continue;
-        for (const ref of refs) {
-            if (coveredByPatches.has(ref.targetPath))
-                continue;
-            // Engine existence check: if the target file is already present in
-            // engine/ (upstream Firefox ships it, or a separate baseline branch
-            // has it), the registration is not dangling. "Is this tracked by git"
-            // cannot be probed without a git round-trip. Existence on disk is a
-            // close-enough proxy for verify's read-only context.
-            if (await pathExists(join(engineDir, ref.targetPath)))
-                continue;
-            issues.push({
-                patchFilename: patch.filename,
-                targetPath: ref.targetPath,
-                source: ref.source,
-            });
-        }
-    }
-    return issues;
-}
-function detectCrossPatchFileClaims(manifestPatches) {
-    const claims = buildPatchClaims(manifestPatches);
-    const results = [];
-    for (const [path, filenames] of claims) {
-        if (filenames.length > 1) {
-            results.push({ path, filenames });
-        }
-    }
-    return results;
-}
-async function detectWorktreeOwnershipDrift(projectRoot, engineDir, patchesDir, binaryName, scope) {
-    if (!(await pathExists(engineDir)) || !(await isGitRepository(engineDir))) {
-        return { unowned: [], patchOwnedDrift: [] };
-    }
-    const entries = await expandUntrackedDirectoryEntries(engineDir, await getWorkingTreeStatus(engineDir));
-    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-    const classified = await classifyFiles(entries, engineDir, patchesDir, binaryName, furnacePrefixes);
-    return {
-        // An unowned change belongs to no patch, so no --patches scope covers it.
-        unowned: [
-            ...new Set(classified
-                .filter((entry) => scope === undefined && entry.classification === 'unmanaged')
-                .map((entry) => entry.file)),
-        ].sort(),
-        patchOwnedDrift: [
-            ...new Set(classified
-                .filter((entry) => entry.classification === 'patch-owned-drift' &&
-                anyPatchInScope(scope, entry.owner === undefined ? [] : [entry.owner]))
-                .map((entry) => entry.file)),
-        ].sort(),
-    };
-}
-/** The warning groups for unowned changes and patch-owned drift. */
-function buildWorktreeDriftGroups(drift) {
-    const groups = [];
-    if (drift.unowned.length > 0) {
-        groups.push({
-            title: `Unowned worktree changes (${drift.unowned.length})`,
-            issues: drift.unowned.map((file) => `${file} is changed in engine/ but is not listed in any patch filesAffected entry`),
-            errorCount: 0,
-            warningCount: drift.unowned.length,
-        });
-    }
-    if (drift.patchOwnedDrift.length > 0) {
-        groups.push({
-            title: `Patch-owned worktree drift (${drift.patchOwnedDrift.length})`,
-            issues: drift.patchOwnedDrift.map((file) => `${file} is claimed by exactly one patch, but engine/ no longer matches that patch output`),
-            errorCount: 0,
-            warningCount: drift.patchOwnedDrift.length,
-        });
-    }
-    return groups;
-}
-/**
- * Collects the same queue-health findings reported by `fireforge verify`
- * without printing. Used by doctor recovery paths that need a read-only
- * "is this queue healthy?" decision before clearing stale state.
- *
- * @param projectRoot - Project root directory
- * @param scope - `verify --patches`: keep only the findings that name these
- *   patches (see verify-scope.ts). Omitted, every finding counts.
- */
-export async function collectPatchQueueHealth(projectRoot, scope) {
-    const paths = getProjectPaths(projectRoot);
-    const config = await loadConfig(projectRoot);
-    if (!(await pathExists(paths.patches))) {
-        return {
-            hasPatchesDirectory: false,
-            groups: [],
-            errorCount: 0,
-            warningCount: 0,
-        };
-    }
-    const groups = [];
-    let errorCount = 0;
-    let warningCount = 0;
-    const consistencyIssues = (await validatePatchesManifestConsistency(paths.patches)).filter((issue) => isFilenameInScope(scope, issue.filename));
-    if (consistencyIssues.length > 0) {
-        const issues = consistencyIssues.map((issue) => `[${issue.code}] ${issue.message}`);
-        groups.push({
-            title: `Manifest consistency issues (${consistencyIssues.length})`,
-            issues,
-            errorCount: consistencyIssues.length,
-            warningCount: 0,
-        });
-        errorCount += consistencyIssues.length;
-    }
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (manifest) {
-        const policyIssues = [
-            ...evaluatePatchPolicy(config, manifest),
-            ...(await evaluatePatchPolicyContentForQueue(config, projectRoot, paths.patches, manifest)),
-        ].filter((issue) => isFilenameInScope(scope, issue.filename));
-        if (policyIssues.length > 0) {
-            const policyErrors = policyIssues.filter((issue) => issue.severity === 'error').length;
-            const policyWarnings = policyIssues.length - policyErrors;
-            groups.push({
-                title: `Patch policy issues (${policyIssues.length})`,
-                issues: policyIssues.map((issue) => {
-                    const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
-                    return `${label} [${issue.code}] ${issue.filename}: ${issue.message}`;
-                }),
-                errorCount: policyErrors,
-                warningCount: policyWarnings,
-            });
-            errorCount += policyErrors;
-            warningCount += policyWarnings;
-        }
-        // Engine-aware module-resolution preflight. The queue-level
-        // `unregistered-system-module` rule only sees modules a patch NEWLY
-        // CREATES. This asks the same question of the engine, so an import ADDED
-        // to an existing module is named as text instead of surfacing later as a
-        // bare `xpcshell return code: -11` with zero output.
-        // Unscoped, the engine worktree joins in: an unexported chrome script
-        // importing an unexported, unregistered module crashes every objdir
-        // start before either file is in the queue. A scoped run never judges
-        // unmanaged files.
-        if (await pathExists(paths.engine)) {
-            const worktree = scope === undefined && (await isGitRepository(paths.engine))
-                ? await collectWorktreeModuleFiles(paths.engine)
-                : undefined;
-            const unresolved = await findUnresolvedSystemModuleImports(paths.engine, scopePatches(manifest.patches, scope).flatMap((patch) => patch.filesAffected), worktree);
-            if (unresolved.length > 0) {
-                groups.push({
-                    title: `Unresolvable system-module imports (${unresolved.length})`,
-                    issues: formatUnresolvedSystemModuleImports(unresolved),
-                    errorCount: unresolved.length,
-                    warningCount: 0,
-                });
-                errorCount += unresolved.length;
-            }
-        }
-        const crossClaims = detectCrossPatchFileClaims(manifest.patches).filter((claim) => anyPatchInScope(scope, claim.filenames));
-        if (crossClaims.length > 0) {
-            groups.push({
-                title: `Cross-patch filesAffected conflicts (${crossClaims.length})`,
-                issues: crossClaims.map((claim) => `${claim.path}  claimed by: ${claim.filenames.join(', ')}`),
-                errorCount: crossClaims.length,
-                warningCount: 0,
-            });
-            errorCount += crossClaims.length;
-        }
-    }
-    const ctx = await buildPatchQueueContext(paths.patches);
-    const lintIssues = scopeLintIssues(lintPatchQueue(ctx), scope);
-    if (lintIssues.length > 0) {
-        const lintErrors = lintIssues.filter((issue) => issue.severity === 'error').length;
-        const lintWarnings = lintIssues.filter((issue) => issue.severity === 'warning').length;
-        groups.push({
-            title: `Cross-patch lint issues (${lintIssues.length})`,
-            issues: lintIssues.map((issue) => {
-                const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARN' : 'NOTICE';
-                return `${label} ${formatPatchLintIssue(issue)}`;
-            }),
-            errorCount: lintErrors,
-            warningCount: lintWarnings,
-        });
-        errorCount += lintErrors;
-        warningCount += lintWarnings;
-    }
-    if (manifest) {
-        const worktreeDrift = await detectWorktreeOwnershipDrift(projectRoot, paths.engine, paths.patches, config.binaryName, scope);
-        const driftGroups = buildWorktreeDriftGroups(worktreeDrift);
-        groups.push(...driftGroups);
-        warningCount += driftGroups.reduce((sum, group) => sum + group.warningCount, 0);
-        const registrationIssues = await detectDanglingRegistrations(paths.patches, paths.engine, manifest.patches, scope);
-        if (registrationIssues.length > 0) {
-            groups.push({
-                title: `Dangling registration references (${registrationIssues.length})`,
-                issues: registrationIssues.map((issue) => `${issue.patchFilename}: registers ${issue.targetPath} via ${issue.source}, but no patch body or engine file supplies it`),
-                errorCount: registrationIssues.length,
-                warningCount: 0,
-            });
-            errorCount += registrationIssues.length;
-        }
-    }
-    return {
-        hasPatchesDirectory: true,
-        groups,
-        errorCount,
-        warningCount,
-    };
-}
-/**
- * Runs the `verify` command: manifest consistency + cross-patch lint.
- * Read-only. Exits non-zero on any error-severity finding.
- *
- * @param projectRoot - Project root directory
- * @param options - `patches`: the raw `--patches` values
- */
-export async function verifyCommand(projectRoot, options = {}) {
-    intro('FireForge Verify');
-    const scope = await resolveVerifyScope(getProjectPaths(projectRoot).patches, options.patches);
-    if (scope !== undefined) {
-        info(`Judging only: ${[...scope.patches].join(', ')}`);
-    }
-    // `verify` is read-only to the OPERATOR but not to git: the working-tree
-    // status probe refreshes (and rewrites) `engine/.git/index`, making this
-    // command a second writer of the primary checkout and invalidating a
-    // concurrent `fireforge test`'s engine fingerprint. A private index keeps
-    // every refresh off the primary checkout.
-    const health = await withPrivateGitIndex(getProjectPaths(projectRoot).engine, () => collectPatchQueueHealth(projectRoot, scope));
-    if (!health.hasPatchesDirectory) {
-        info('No patches directory. Nothing to verify.');
-        outro('Verify clean');
-        return;
-    }
-    for (const group of health.groups) {
-        warn(`${group.title}:`);
-        for (const issue of group.issues) {
-            warn(`  ${issue}`);
-        }
-    }
-    if (health.errorCount === 0 && health.warningCount === 0) {
-        success('Patch queue is consistent.');
-        outro('Verify clean');
-        return;
-    }
-    info(`\nVerify: ${health.errorCount} error(s), ${health.warningCount} warning(s)`);
-    if (health.errorCount > 0) {
-        outro('Verify failed');
-        throw new GeneralError(`fireforge verify found ${health.errorCount} error(s). Fix these before running export/import/rebase. Use "patch staged-dependency" for intentional staged imports, or preview "patch move-files" / "patch reorder --dry-run" / "re-export --files --dry-run" for ownership repairs.`);
-    }
-    outro('Verify passed with warnings');
-}
-/**
- * Registers the `verify` command on the CLI program.
- *
- * @param program - Commander root program
- * @param context - Shared CLI registration context
- */
-export function registerVerify(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('verify')
-        .description('Read-only fsck for the patch queue (manifest + cross-patch lint)')
-        .option('--patches <names...>', 'Judge only findings that name these patches (filename, stem, order number, manifest name, or slug; repeat, or separate with commas or whitespace). Queue-wide findings stay; unowned worktree changes drop out')
-        .action(withErrorHandling(async (options) => {
-        await verifyCommand(getProjectRoot(), options);
-    }));
-}
+import { defineCommand, lockOptions, lockWaitMs } from '../cli/command.js';
+import { verify as verifyStorage, verifyOutcome, withOwnedRead } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+export const verify = defineCommand({
+    name: 'verify',
+    summary: 'Check the integrity of where the owned changes are stored',
+    description: 'Patch mode: the manifest, every patch body, and that the queue replays onto the engine. ' +
+        'Source mode: every override record and owned file against the pristine repository.',
+    group: 'Daily',
+    options: { ...lockOptions },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const report = await withOwnedRead(project, { command: 'verify', waitMs: lockWaitMs(opts.waitLock) }, () => verifyStorage(project));
+        for (const problem of report.problems) {
+            const subject = problem.subject === undefined ? '' : `${problem.subject}: `;
+            ctx.out.line(`${problem.code}  ${subject}${problem.message}`);
+            if (problem.hint !== undefined)
+                ctx.out.line(`  ${problem.hint}`);
+        }
+        const outcome = verifyOutcome(report);
+        if ('sound' in outcome)
+            ctx.out.line(outcome.sound);
+        ctx.out.json({ ...report, pass: report.problems.length === 0 });
+        if ('failure' in outcome)
+            throw outcome.failure;
+    },
+});

package/dist/src/commands/version.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { defineCommand } from '../cli/command.js';
+import { cliVersion, packageVersion } from '../cli/version.js';
+export const version = defineCommand({
+    name: 'version',
+    summary: 'Print the FireForge version and build identity',
+    group: 'Diagnostics',
+    json: true,
+    run: async (ctx) => {
+        const build = await cliVersion();
+        ctx.out.line(build);
+        ctx.out.json({ version: await packageVersion(), build, node: process.version });
+    },
+});

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());
-    }));
-}
+    },
+});