@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/engine/index.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Having a Firefox engine and building it: acquiring the pinned source as a
+ * pristine repository, the workspaces commands build and test in, the host
+ * locks, `mach`, builds and their staleness, and running and packaging the
+ * browser.
+ */
+// The pin and the pristine repository
+export { sourceArchive } from './archive.js';
+export { pinKey } from './pin.js';
+export { ensurePristine, findPristine, installProjectEngine, listPristineTree, readPristineFiles, } from './pristine.js';
+// Workspaces and the pool
+export { addWorkspace, leaseWorkspace, listWorkspaces, removeWorkspace, repairWorkspace, } from './pool.js';
+export { engineLockPath, withEngineLock, withProjectWorkspace, } from './workspace.js';
+// Host configuration and locks
+export { withDisplay } from './hostLocks.js';
+// mach
+export { runMach } from './mach.js';
+export { withoutObjdir } from './mozconfig.js';
+// Builds and staleness
+export { bootstrap, build, ensureBuilt } from './build.js';
+export { readBuildBaseline } from './staleness.js';
+// Running, packaging, watching
+export { packageBrowser } from './package.js';
+export { runBrowser } from './run.js';
+export { watch } from './watch.js';

package/dist/src/engine/installManifests.js

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * How an engine source file reaches the built browser, read from the object
+ * directory's install manifests (`_build_manifests/install/*` and
+ * `faster/install_*`).
+ *
+ * A manifest is a version line followed by entries whose fields are
+ * separated by `\x1f`: type 1 installs a symlink to an absolute source, 2
+ * copies it, 7 preprocesses it, and 5 and 6 are the pattern forms of 1 and 2
+ * (`base`, `pattern`, `destination directory`). Outside Windows most chrome
+ * files of a development build are symlinks back into the engine, so an edit
+ * to one is already what the browser reads. `_test_files` is rewritten and
+ * installed by `mach test` itself on every run.
+ *
+ * Every answer errs toward "packaged": an entry whose install base is
+ * unknown, or a symlink that does not resolve to the source, counts as a copy.
+ */
+import { join } from 'node:path';
+import { listDir, pathInfo, readText, readTextIfExists, realPath, toPosixPath, } from '../kernel/fs.js';
+import { globToRegExp } from '../kernel/glob.js';
+const SEPARATOR = '\x1f';
+/** Entry types that carry no source file. */
+const SOURCELESS = new Set(['3', '4', '8']);
+/** The manifest `mach test` installs at the start of every run. */
+const TEST_MANIFEST = '_test_files';
+function parse(index, content, roots, manifest) {
+    for (const line of content.split('\n').slice(1)) {
+        const fields = line.split(SEPARATOR);
+        const [type = '', destination = '', source = ''] = fields;
+        if (SOURCELESS.has(type) || source === '')
+            continue;
+        const absolute = toPosixPath(source);
+        const root = roots.find((candidate) => absolute.startsWith(`${candidate}/`));
+        if (root === undefined)
+            continue;
+        const path = absolute.slice(root.length + 1);
+        const at = (relative) => manifest.base === undefined || relative === undefined
+            ? undefined
+            : join(manifest.base, relative);
+        if (type === '5' || type === '6') {
+            const pattern = fields[3] ?? '';
+            if (pattern.split('/').includes('..'))
+                continue;
+            index.patterns.push({
+                symlink: type === '5',
+                base: path,
+                pattern: globToRegExp(pattern),
+                destination: at(fields[4]),
+                atTest: manifest.atTest,
+            });
+            continue;
+        }
+        const installs = index.files.get(path) ?? [];
+        installs.push({ symlink: type === '1', destination: at(destination), atTest: manifest.atTest });
+        index.files.set(path, installs);
+    }
+}
+/**
+ * Reads the install manifests of an object directory.
+ *
+ * @param engineDir - The engine the object directory was built from
+ * @param objDir - The object directory
+ * @returns Undefined when it has no manifests, so nothing can be told
+ */
+export async function readInstallIndex(engineDir, objDir) {
+    const roots = [...new Set([toPosixPath(engineDir), toPosixPath(await realPath(engineDir))])];
+    const index = { files: new Map(), patterns: [] };
+    const readAll = async (directory, baseOf) => {
+        let read = 0;
+        for (const entry of await listDir(directory)) {
+            const { name } = entry;
+            if (entry.kind !== 'file' || name.startsWith('.') || name.endsWith('.track'))
+                continue;
+            if (name === 'Makefile')
+                continue;
+            const base = baseOf(name);
+            parse(index, await readText(join(directory, name)), roots, {
+                base: base === undefined ? undefined : join(objDir, base),
+                atTest: name === TEST_MANIFEST,
+            });
+            read += 1;
+        }
+        return read;
+    };
+    const build = await readAll(join(objDir, '_build_manifests', 'install'), (name) => name === TEST_MANIFEST || name === '_tests'
+        ? '_tests'
+        : name.startsWith('dist_')
+            ? `dist/${name.slice('dist_'.length)}`
+            : undefined);
+    // The faster backend names each manifest after its install base, which its Makefile lists.
+    const makefile = (await readTextIfExists(join(objDir, 'faster', 'Makefile'))) ?? '';
+    const bases = new Map([['unified_install_dist_bin', 'dist/bin']]);
+    for (const base of (/^INSTALL_MANIFESTS\s*=(.*)$/m.exec(makefile)?.[1] ?? '')
+        .trim()
+        .split(/\s+/)) {
+        if (base !== '')
+            bases.set(`install_${base.replaceAll('/', '_')}`, base);
+    }
+    const faster = await readAll(join(objDir, 'faster'), (name) => bases.get(name));
+    return build + faster > 0 ? index : undefined;
+}
+async function linksTo(destination, source) {
+    if (destination === undefined)
+        return false;
+    try {
+        if ((await pathInfo(destination))?.kind !== 'symlink')
+            return false;
+        return (await realPath(destination)) === (await realPath(source));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * How one engine file reaches the built browser.
+ *
+ * @param index - From {@link readInstallIndex}
+ * @param engineDir - The engine
+ * @param path - Engine-relative path
+ */
+export async function deliveryOf(index, engineDir, path) {
+    const installs = [...(index.files.get(path) ?? [])];
+    for (const pattern of index.patterns) {
+        if (!path.startsWith(`${pattern.base}/`))
+            continue;
+        const rest = path.slice(pattern.base.length + 1);
+        if (!pattern.pattern.test(rest))
+            continue;
+        installs.push({
+            symlink: pattern.symlink,
+            destination: pattern.destination === undefined ? undefined : join(pattern.destination, rest),
+            atTest: pattern.atTest,
+        });
+    }
+    if (installs.length === 0)
+        return 'unlisted';
+    if (installs.every((install) => install.atTest))
+        return 'at-test';
+    const source = join(engineDir, path);
+    for (const install of installs) {
+        if (install.atTest)
+            continue;
+        if (!install.symlink || !(await linksTo(install.destination, source)))
+            return 'packaged';
+    }
+    return 'live';
+}

package/dist/src/engine/mach.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The one way `mach` is run. Every caller (build, test, run, package,
+ * bootstrap) gets the same process handling: the interpreter the engine
+ * accepts, the resource-monitor guard, a process group that is torn down with
+ * the command, and output streamed line by line.
+ *
+ * The process tree belongs to the workspace for as long as `runMach` runs:
+ * a descendant that left mach's process group but runs from the engine or
+ * the object directory (a browser that started a session of its own) is
+ * still terminated when mach ends, so no process of the run outlives the
+ * caller's hold on the workspace.
+ *
+ * Output has two consumers that must not be confused. `onLine` receives every
+ * raw line, for a caller that classifies output. The operator sees every line
+ * on stderr: stdout belongs to the command's result.
+ */
+import { join } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists, realPath } from '../kernel/fs.js';
+import { info, warn } from '../kernel/log.js';
+import { run } from '../kernel/process/index.js';
+import { machErrorHints } from './machHints.js';
+import { machPython } from './python.js';
+import { installResourceGuard } from './resourceGuard.js';
+async function realPathIfExists(path) {
+    return (await exists(path)) ? realPath(path) : path;
+}
+/**
+ * Runs `mach <args>` in a workspace's engine.
+ *
+ * @param workspace - The workspace
+ * @param args - The mach command and its arguments
+ * @param options - See {@link MachOptions}
+ * @throws `engine-missing` when the engine has no `mach`, `python-not-found`
+ *   (exit code 7) when no Python mach accepts is installed
+ */
+export async function runMach(workspace, args, options = {}) {
+    const { engineDir } = workspace;
+    const mach = join(engineDir, 'mach');
+    if (!(await exists(mach))) {
+        throw new FireForgeError('engine-missing', `There is no mach in ${engineDir}`, {
+            exitCode: ExitCode.GENERAL_ERROR,
+            hint: 'Run "fireforge download", or "fireforge workspace repair <name>" for a pool workspace.',
+        });
+    }
+    const python = await machPython(engineDir);
+    const guard = await installResourceGuard(engineDir, {
+        objDirs: [workspace.releaseObjDir],
+        env: { ...process.env, ...options.env },
+    });
+    // A command line may name either spelling of a directory behind a symlink.
+    const roots = [engineDir, workspace.objDir, workspace.releaseObjDir];
+    const anchors = [...new Set([...roots, ...(await Promise.all(roots.map(realPathIfExists)))])];
+    const result = await run(python, [mach, ...args], {
+        cwd: engineDir,
+        env: { ...guard, ...options.env },
+        output: options.terminal === true ? 'inherit' : 'capture',
+        processGroup: true,
+        timeoutIsResult: true,
+        onLine: (line, stream) => {
+            options.onLine?.(line, stream);
+            info(line);
+        },
+        onProcessGroup: (owner) => {
+            owner.anchorTo(anchors);
+        },
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        ...(options.afterExit === undefined ? {} : { afterExit: options.afterExit }),
+    });
+    if (result.exitCode !== 0 && options.hints !== false) {
+        // mach's wrapper writes a subcommand's errors to either stream.
+        for (const hint of machErrorHints(`${result.stderr}\n${result.stdout}`))
+            warn(`Hint: ${hint}`);
+    }
+    return {
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        timedOut: result.timedOut,
+        outlived: result.outlived,
+    };
+}
+/**
+ * The failure of a `mach` command whose success the caller needs.
+ *
+ * @param command - What ran, such as `mach build`
+ * @param result - How it ended
+ * @param hint - What to do next
+ */
+export function machFailure(command, result, hint) {
+    const how = result.timedOut ? 'timed out' : `exited ${result.exitCode}`;
+    return new FireForgeError('mach-failed', `${command} ${how}`, {
+        exitCode: ExitCode.BUILD_ERROR,
+        ...(hint === undefined ? {} : { hint }),
+    });
+}

package/dist/src/engine/machHints.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Remedies for the mach and mozbuild failures whose own message does not say
+ * what to change. The list is deliberately short: a hint is added only for a
+ * failure whose cause is established, because a low-confidence hint teaches
+ * the operator to ignore all of them.
+ */
+const HINTS = [
+    {
+        pattern: /mozbuild\.preprocessor\.Preprocessor\.Error[\s\S]*?no preprocessor directives found/,
+        hint: 'A file registered under JS_PREFERENCE_PP_FILES contains no preprocessor directives. ' +
+            'Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.',
+    },
+    {
+        // mozbuild sorts StrictOrderingOnAppendList entries by `.lower()`, so an
+        // entry placed correctly by byte order can still be rejected. Its own
+        // message names the file and both entries; the hint supplies the rule.
+        pattern: /\bUnsortedError\b/,
+        hint: 'A moz.build list is out of order: mozbuild rejects the file while reading it, so ' +
+            'configure dies before any compile. Entries are compared CASE-INSENSITIVELY (mozbuild ' +
+            'lowercases before comparing), so uppercase does not sort before lowercase: ' +
+            '"PanelPaths.sys.mjs" belongs BEFORE "Panels.sys.mjs" ("panelp" < "panels"). ' +
+            'The mozbuild error above names the file and both entries; move the entry to the ' +
+            'position it names. "fireforge lint" checks list order before a build.',
+    },
+    {
+        // packager.py dereferences a None sink when the object directory's
+        // dist/ lacks pieces it assumes exist.
+        pattern: /packager\.py[\s\S]*?AttributeError: 'NoneType' object has no attribute 'open'|AttributeError: 'NoneType' object has no attribute 'open'[\s\S]*?packager\.py/,
+        hint: '"mach package" tripped a NoneType.open inside packager.py. That is almost always an ' +
+            'incomplete dist/ tree: packaging before a full "fireforge build" (not --ui) finished, ' +
+            'or after a build that failed late. Run "fireforge build" to completion, then ' +
+            '"fireforge package" again.',
+    },
+    {
+        // bindgen emits `pub type basic_string___self_view = ...<_CharT>;` into
+        // gecko-profiler's bindings.rs against some macOS libc++ SDKs, where
+        // `_CharT` is not in scope.
+        pattern: /cannot find type `_CharT` in this scope[\s\S]*?gecko-profiler-|gecko-profiler-[\s\S]*?cannot find type `_CharT` in this scope/,
+        hint: 'The Rust compile failed on a bindgen-generated `basic_string___self_view` alias in ' +
+            'gecko-profiler/bindings.rs. This is an upstream bindgen defect against some macOS ' +
+            'libc++ SDK versions. The project needs a change that strips the alias after generation: ' +
+            'remove any `pub type basic_string___self_view = …<_CharT>;` line from ' +
+            '`<objdir>/release/build/gecko-profiler-*/out/gecko/bindings.rs` before the Rust compile.',
+    },
+    {
+        // Configure's die() for a tool below the minimum the source declares.
+        // mach's own text names "./mach bootstrap", the wrong entry point here.
+        pattern: /\bversion [\d.]+ is too old\.?\s+At least version [\d.]+ is required/i,
+        hint: 'A toolchain component is older than the minimum this Firefox source declares, which is ' +
+            'typical after moving to a new Firefox version. Run "fireforge bootstrap" (not mach\'s ' +
+            'suggested "./mach bootstrap") to update the toolchain, then build again.',
+    },
+    {
+        // rust.configure names the minimum only further down its message.
+        pattern: /\b(?:Rust compiler|Cargo package manager) [\d.]+(?:[\w.-]*)? is too old/i,
+        hint: 'The Rust toolchain is older than the minimum this Firefox source declares, which is ' +
+            'typical after moving to a new Firefox version. Run "fireforge bootstrap" to update the ' +
+            'toolchain, then build again.',
+    },
+    {
+        // A failed `mach build` still prints its configure summary on the way
+        // out, which reads like a success banner.
+        pattern: /Config object not found by mach\.[\s\S]*?Configure complete!/,
+        hint: 'Ignore the trailing "Config object not found by mach. / Configure complete!" block: ' +
+            "that is mach's post-failure configure summary, printed after the build already failed. " +
+            'The real failure is the error above it.',
+    },
+];
+/**
+ * The known remedies for what a failed `mach` command wrote, in a stable
+ * order and without repeats. Pass both streams: mach's wrapper writes a
+ * subcommand's errors to either.
+ *
+ * @param output - Everything mach wrote
+ * @returns One paragraph per recognised failure; empty when none is recognised
+ */
+export function machErrorHints(output) {
+    return HINTS.filter(({ pattern }) => pattern.test(output)).map(({ hint }) => hint);
+}

package/dist/src/engine/mozconfig.js

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The engine's `mozconfig`, generated from the project's `configs/`
+ * templates: `common.mozconfig` (optional), then the platform's
+ * (`darwin.mozconfig`, `linux.mozconfig`, `win32.mozconfig`), with the
+ * project's identity substituted for `${name}`, `${vendor}`, `${appId}` and
+ * `${binaryName}`. FireForge places the object directory itself, so every
+ * workspace has it at the same relative path.
+ */
+import { join } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists, readTextIfExists, writeFileIfChanged } from '../kernel/fs.js';
+import { verbose } from '../kernel/log.js';
+import { OBJDIR_NAME } from './workspace.js';
+/** A `MOZ_OBJDIR` declaration in either spelling mach honours. */
+const MOZ_OBJDIR = /^\s*(?:mk_add_options\s+|export\s+)?MOZ_OBJDIR\s*=/m;
+/**
+ * A mozconfig template without its `MOZ_OBJDIR` declarations, which the
+ * generated mozconfig refuses because FireForge places the object directory
+ * itself. Undefined when the template declares none.
+ *
+ * @param text - The template's content
+ */
+export function withoutObjdir(text) {
+    const lines = text.split('\n');
+    const kept = lines.filter((line) => !MOZ_OBJDIR.test(line));
+    return kept.length === lines.length ? undefined : kept.join('\n');
+}
+/** The last `--with-branding=<path>` wins, as in any shell-evaluated mozconfig. */
+const WITH_BRANDING = /^\s*(?:ac_add_options\s+)?--with-branding\s*=\s*(\S+)/gm;
+function configError(message, hint) {
+    return new FireForgeError('mozconfig-invalid', message, {
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint,
+    });
+}
+/**
+ * The branding directory a mozconfig selects, or undefined when it names none.
+ *
+ * @param mozconfig - The mozconfig text
+ */
+export function brandingDirectory(mozconfig) {
+    return [...mozconfig.matchAll(WITH_BRANDING)].at(-1)?.[1]?.replaceAll('\\', '/');
+}
+/**
+ * Renders the mozconfig a workspace builds with, without writing it.
+ *
+ * @param workspace - The workspace; its project's `configs/` and identity are read
+ * @throws `mozconfig-invalid` (exit code 2) when the platform template is
+ *   missing or a template places the object directory
+ */
+export async function renderMozconfig(workspace) {
+    const { config, paths } = workspace.project;
+    const values = {
+        name: config.name,
+        vendor: config.vendor,
+        appId: config.appId,
+        binaryName: config.binaryName,
+    };
+    const template = async (file) => {
+        const text = await readTextIfExists(join(paths.configs, file));
+        if (text === undefined)
+            return undefined;
+        if (MOZ_OBJDIR.test(text)) {
+            throw configError(`configs/${file} sets MOZ_OBJDIR`, `Remove it: FireForge keeps the object directory at ${OBJDIR_NAME} inside every engine.`);
+        }
+        return text.replace(/\$\{(name|vendor|appId|binaryName)\}/g, (_, key) => values[key] ?? '');
+    };
+    const platformFile = `${process.platform}.mozconfig`;
+    const [common, platform] = [await template('common.mozconfig'), await template(platformFile)];
+    if (platform === undefined) {
+        throw configError(`configs/${platformFile} does not exist`, 'Create it with the mozconfig options this platform builds with (it may be empty).');
+    }
+    // Upstream composes the macOS bundle identifier as
+    // <distribution id>.<MOZ_MACBUNDLE_ID>, and branding carries only the last
+    // segment of the application id, so the rest travels here.
+    const distributionId = config.appId.slice(0, config.appId.lastIndexOf('.'));
+    return [
+        `# Generated by FireForge from configs/. Edit the templates, not this file.`,
+        `ac_add_options --with-distribution-id=${distributionId}`,
+        '',
+        ...(common === undefined ? [] : ['# configs/common.mozconfig', common.trimEnd(), '']),
+        `# configs/${platformFile}`,
+        platform.trimEnd(),
+        '',
+        `mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/${OBJDIR_NAME}`,
+        '',
+    ].join('\n');
+}
+/**
+ * Writes the engine's `mozconfig` when its content would change. An unchanged
+ * file keeps its modification time, which is what mach compares its
+ * configure output against: rewriting it would re-run configure on every build.
+ *
+ * @param workspace - The workspace
+ * @returns Whether the file was written
+ * @throws `mozconfig-invalid` (exit code 2), also when the selected branding
+ *   directory is not in the engine
+ */
+export async function writeMozconfig(workspace) {
+    const content = await renderMozconfig(workspace);
+    const branding = brandingDirectory(content);
+    if (branding !== undefined && !(await exists(join(workspace.engineDir, branding, 'moz.build')))) {
+        throw configError(`configs/ selects --with-branding=${branding}, and the engine has no ${branding}/moz.build`, 'Add the branding directory to the project, or correct the option: configure would fail on it much later.');
+    }
+    const written = await writeFileIfChanged(join(workspace.engineDir, 'mozconfig'), content);
+    if (!written)
+        verbose('mozconfig is unchanged.');
+    return written;
+}

package/dist/src/engine/objdir.js

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What an object directory holds: the launchable browser, and where it was
+ * configured.
+ *
+ * An object directory belongs to the absolute path it was configured at and
+ * is never moved to another. `mach configure` regenerates only its own
+ * output (`config.status`, the make backend, the install manifests). What the
+ * build generated keeps naming the old source, and the build system has no
+ * reason to regenerate any of it:
+ *
+ *  - `.cargo/config.toml` names the vendored crates of the old source, and
+ *    build-script output names the old object directory as a link search
+ *    path, so cargo reads and links from the other workspace;
+ *  - cargo's dependency records are binary and length-prefixed, and some hold
+ *    absolute source paths;
+ *  - generated sources embed the paths, some in an escaped spelling a search
+ *    for the path does not find (`build/rust/mozbuild/buildconfig.rs` writes
+ *    `.` as `\u{2e}`);
+ *  - make's dependency files and the install tracking files list old
+ *    absolute paths, so staleness is judged by the other workspace's files
+ *    for as long as it exists.
+ *
+ * Rewriting what can be found leaves a build that silently depends on
+ * another workspace for the rest, so an object directory found at another
+ * path is discarded ({@link discardMovedObjdir}) and the build starts from
+ * nothing.
+ */
+import { join, resolve } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists, listDir, readTextIfExists, remove } from '../kernel/fs.js';
+import { isRecord, parseJson } from '../kernel/json.js';
+/**
+ * The launchable browser binary of an object directory: on macOS inside
+ * whichever `dist/*.app` holds it (the bundle's display name need not match
+ * the binary's), elsewhere `dist/bin/<binaryName>`.
+ *
+ * @param objDir - The object directory
+ * @param binaryName - The executable name from the project's configuration
+ * @returns Its absolute path, or undefined when the build has not produced it
+ */
+export async function findBrowserBinary(objDir, binaryName) {
+    const dist = join(objDir, 'dist');
+    const candidates = process.platform === 'darwin'
+        ? (await listDir(dist))
+            .filter((entry) => entry.kind === 'directory' && entry.name.endsWith('.app'))
+            .map((entry) => join(dist, entry.name, 'Contents', 'MacOS', binaryName))
+        : [join(dist, 'bin', process.platform === 'win32' ? `${binaryName}.exe` : binaryName)];
+    for (const candidate of candidates) {
+        if (await exists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * The launchable browser of a workspace's development build.
+ *
+ * @param workspace - The workspace
+ * @returns The binary's absolute path
+ * @throws `build-missing` (exit code 5) when the workspace has no completed build
+ */
+export async function requireBuilt(workspace) {
+    const binary = await findBrowserBinary(workspace.objDir, workspace.project.config.binaryName);
+    if (binary !== undefined)
+        return binary;
+    const partial = await exists(workspace.objDir);
+    throw new FireForgeError('build-missing', partial
+        ? `The build in ${workspace.objDir} has no launchable browser: it did not finish`
+        : `Nothing is built yet: ${workspace.objDir} does not exist`, { exitCode: ExitCode.BUILD_ERROR, hint: 'Run "fireforge build".' });
+}
+/**
+ * Where an object directory was configured, from its `mozinfo.json`.
+ *
+ * @param objDir - The object directory
+ * @returns Undefined when it was never configured, or records no paths
+ */
+async function readObjdirOrigin(objDir) {
+    const text = await readTextIfExists(join(objDir, 'mozinfo.json'));
+    if (text === undefined)
+        return undefined;
+    let mozinfo;
+    try {
+        mozinfo = parseJson(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(mozinfo))
+        return undefined;
+    const { topsrcdir, topobjdir, mozconfig } = mozinfo;
+    if (typeof topsrcdir !== 'string' || typeof topobjdir !== 'string')
+        return undefined;
+    return { topsrcdir, topobjdir, ...(typeof mozconfig === 'string' ? { mozconfig } : {}) };
+}
+/**
+ * The origin of a workspace's object directory when it was configured for
+ * another location: the workspace was cloned or moved since.
+ *
+ * @param workspace - The workspace
+ * @returns Undefined when the object directory is absent or belongs here
+ */
+export async function movedFrom(workspace) {
+    const origin = await readObjdirOrigin(workspace.objDir);
+    if (origin === undefined)
+        return undefined;
+    const here = resolve(origin.topsrcdir) === resolve(workspace.engineDir) &&
+        resolve(origin.topobjdir) === resolve(workspace.objDir);
+    return here ? undefined : origin;
+}
+/**
+ * Removes a workspace's object directory when it was configured for another
+ * location, so the next build configures and builds from nothing.
+ *
+ * @param workspace - The workspace
+ * @returns The source directory it was configured for, or undefined when the
+ *   object directory is absent or belongs here
+ */
+export async function discardMovedObjdir(workspace) {
+    const origin = await movedFrom(workspace);
+    if (origin === undefined)
+        return undefined;
+    await remove(workspace.objDir);
+    return resolve(origin.topsrcdir);
+}