@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/workspace.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { arg, defineCommand, lockOptions, opt } from '../cli/command.js';
+import { addWorkspace, removeWorkspace, repairWorkspace, } from '../engine/index.js';
+import { FireForgeError } from '../kernel/errors.js';
+import { listAllWorkspaces } from '../mode/index.js';
+import { hostPaths, loadProject } from '../project/index.js';
+/** The options of every command that works in a workspace. */
+export const workspaceOptions = {
+    workspace: opt.string('Source mode: use this pool workspace instead of the best free one ("fireforge workspace list" names them)', { valueName: 'name' }),
+    ...lockOptions,
+};
+/** The project the command was run in, or undefined outside one: the pool belongs to the host. */
+async function projectHere(ctx) {
+    try {
+        return await loadProject(ctx.cwd, ctx.env);
+    }
+    catch (error) {
+        if (error instanceof FireForgeError && error.code === 'project-not-found')
+            return undefined;
+        throw error;
+    }
+}
+function row(workspace) {
+    const state = workspace.holders.length > 0
+        ? `leased by PID ${workspace.holders.map((holder) => holder.pid).join(', ')}`
+        : 'free';
+    const last = workspace.lessee === undefined ? 'never leased' : `last used by ${workspace.lessee.root}`;
+    return `${workspace.name}  ${workspace.pin}  ${workspace.built ? 'built' : 'not built'}  ${state}  ${last}`;
+}
+const list = defineCommand({
+    name: 'list',
+    summary: 'List the workspaces of this host',
+    json: true,
+    run: async (ctx) => {
+        const { engine, pool } = await listAllWorkspaces(hostPaths(ctx.env), await projectHere(ctx));
+        if (engine !== undefined) {
+            const state = engine.holders.length > 0 ? `in use by PID ${engine.holders.join(', ')}` : 'free';
+            ctx.out.line(`engine  ${engine.path}  ${state}`);
+        }
+        for (const workspace of pool)
+            ctx.out.line(row(workspace));
+        if (engine === undefined && pool.length === 0)
+            ctx.out.line('The pool is empty.');
+        ctx.out.json({
+            engine: engine ?? null,
+            workspaces: pool.map((workspace) => ({
+                name: workspace.name,
+                path: workspace.dir,
+                pin: workspace.pin,
+                commit: workspace.commit,
+                built: workspace.built,
+                clonedFrom: workspace.clonedFrom ?? null,
+                lessee: workspace.lessee ?? null,
+                holders: workspace.holders.map((holder) => holder.pid),
+            })),
+        });
+    },
+});
+const add = defineCommand({
+    name: 'add',
+    summary: "Create a workspace on the project's Firefox",
+    description: 'Checks the pinned Firefox out of the pristine repository. With --from, clones the engine of ' +
+        'another workspace copy-on-write instead, with what is recorded about its content. Either way ' +
+        'the new workspace needs a full build: an object directory is tied to the path it was ' +
+        'configured at, so a build is never copied or moved to another workspace.',
+    args: { name: arg.string('Name of the new workspace') },
+    options: {
+        from: opt.string("Clone this workspace's engine, without its builds", { valueName: 'name' }),
+    },
+    json: true,
+    run: async (ctx, { name }, { from }) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const workspace = await addWorkspace(project.host, name, { pin: project.config.firefox, from });
+        ctx.out.line(`Created workspace "${workspace.name}" at ${workspace.dir}`);
+        ctx.out.line(from === undefined
+            ? 'It needs a full build before it is useful.'
+            : `The builds of "${from}" were not copied (a build cannot be moved to another path): it needs a full build.`);
+        ctx.out.json({
+            name: workspace.name,
+            path: workspace.dir,
+            pin: workspace.pin,
+            built: workspace.built,
+        });
+    },
+});
+const remove = defineCommand({
+    name: 'remove',
+    summary: 'Delete a workspace and its build',
+    args: { name: arg.string('The workspace') },
+    json: true,
+    run: async (ctx, { name }) => {
+        await removeWorkspace(hostPaths(ctx.env), name);
+        ctx.out.line(`Removed workspace "${name}"`);
+        ctx.out.json({ name, removed: true });
+    },
+});
+const repair = defineCommand({
+    name: 'repair',
+    summary: "Reset a workspace's engine to the pristine Firefox, keeping its build",
+    description: 'Restores every file of the engine, removes what was added, and forgets what was recorded ' +
+        "about the engine's content (materialized files, deployed components, test runs), so the " +
+        "next command that leases the workspace applies the project's source afresh. The object " +
+        'directory and the release build stay.',
+    args: { name: arg.string('The workspace') },
+    json: true,
+    run: async (ctx, { name }) => {
+        await repairWorkspace(hostPaths(ctx.env), name);
+        ctx.out.line(`Reset workspace "${name}" to the pristine source`);
+        ctx.out.json({ name, repaired: true });
+    },
+});
+export const workspace = defineCommand({
+    name: 'workspace',
+    summary: 'Manage the host pool of engine workspaces',
+    group: 'Engine',
+    subcommands: [list, add, remove, repair],
+});

package/dist/src/config/edit.js

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Reading and editing single keys of `fireforge.json` through the schema: a
+ * key exists when the schema declares it, a value is typed by the key's
+ * schema, and the whole document is validated before anything is written.
+ * An edit rewrites only the changed value, so the file keeps its layout.
+ * `mode` is the one key an edit cannot change: it moves together with the
+ * `source` section and the project's files, which a single-key edit cannot do.
+ *
+ * A key is written the way validation reports paths: dotted names, array
+ * indices as `[2]` or `.2`, and a dictionary key that is not a plain word in
+ * brackets, as in `typecheck.projectOverrides["browser/jsconfig.json"]`.
+ */
+import { join } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { writeFile } from '../kernel/fs.js';
+import { isRecord, parseJson, stringifyJson, } from '../kernel/json.js';
+import { editJsonText } from '../kernel/json-edit.js';
+import { withLock } from '../kernel/lock.js';
+import { describeKeys } from '../kernel/schema.js';
+import { nearest } from '../kernel/text.js';
+import { CONFIG_FILE, readConfigDocument } from './load.js';
+import { configSchema } from './schema/index.js';
+import { modeKey } from './schema/source.js';
+const RESERVED_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+function unknownKey(key, why) {
+    const suggestion = nearest(key, describeKeys(configSchema).map((info) => info.path));
+    return new FireForgeError('config-unknown-key', `"${key}" ${why}`, {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+        hint: suggestion === undefined
+            ? 'docs/configuration.md lists the keys of fireforge.json.'
+            : `Did you mean "${suggestion}"?`,
+    });
+}
+/** The text of a bracketed, JSON-quoted key segment. */
+function quoted(key, body) {
+    let value;
+    try {
+        value = parseJson(`"${body}"`);
+    }
+    catch {
+        value = undefined;
+    }
+    if (typeof value !== 'string')
+        throw unknownKey(key, 'has a malformed quoted segment');
+    return value;
+}
+/** Splits a key into its segments, refusing a malformed or prototype-reaching one. */
+function segmentsOf(key) {
+    const segments = [];
+    let rest = key;
+    while (rest !== '') {
+        const match = /^\["((?:[^"\\]|\\.)*)"\]/.exec(rest) ??
+            /^\[(\d+)\]/.exec(rest) ??
+            (segments.length === 0 ? /^([^.[\]]+)/ : /^\.([^.[\]]+)/).exec(rest);
+        const segment = match?.[1];
+        if (match === null || segment === undefined)
+            throw unknownKey(key, 'is not a valid key path');
+        const name = match[0].startsWith('["') ? quoted(key, segment) : segment;
+        if (RESERVED_SEGMENTS.has(name))
+            throw unknownKey(key, `cannot name "${name}"`);
+        segments.push(name);
+        rest = rest.slice(match[0].length);
+    }
+    if (segments.length === 0)
+        throw unknownKey(key, 'is empty');
+    return segments;
+}
+/** The schema of the value a key path names, following object keys, dictionary keys and indices. */
+function schemaOf(key, segments) {
+    let current = configSchema;
+    for (const segment of segments) {
+        const structure = current.structure;
+        const { shape, element } = structure;
+        current =
+            shape === undefined ? element : Object.hasOwn(shape, segment) ? shape[segment] : undefined;
+        if (current === undefined)
+            throw unknownKey(key, 'is not a key of fireforge.json');
+    }
+    return current;
+}
+function describeKey(path, schema) {
+    return {
+        path,
+        type: schema.type,
+        doc: schema.doc,
+        required: !schema.isOptional && schema.fallback === undefined,
+        container: schema.structure.shape !== undefined,
+        defaultValue: schema.fallback?.value,
+    };
+}
+/** Every key `fireforge.json` declares, depth first, containers included. */
+export function configKeys() {
+    return describeKeys(configSchema).map((info) => describeKey(info.path, info.schema));
+}
+function valueAt(document, segments) {
+    let current = document;
+    for (const segment of segments) {
+        if (Array.isArray(current))
+            current = /^\d+$/.test(segment) ? current[Number(segment)] : undefined;
+        else if (isRecord(current) && Object.hasOwn(current, segment))
+            current = current[segment];
+        else
+            return undefined;
+    }
+    return current;
+}
+/**
+ * Reads one key from `fireforge.json` as written, beside its type,
+ * documentation and default.
+ *
+ * @param projectRoot - The project directory
+ * @param key - A key path such as `firefox.version`
+ * @throws `config-unknown-key` (exit code 8) for a key the schema does not declare
+ */
+export async function getConfigValue(projectRoot, key) {
+    const segments = segmentsOf(key);
+    const schema = schemaOf(key, segments);
+    const { document } = await readConfigDocument(projectRoot);
+    return { ...describeKey(key, schema), value: valueAt(document, segments) };
+}
+function issueLines(prefix, issues) {
+    return issues
+        .map((issue) => {
+        const path = issue.path === ''
+            ? prefix
+            : issue.path.startsWith('[') || prefix === ''
+                ? `${prefix}${issue.path}`
+                : `${prefix}.${issue.path}`;
+        return `"${path}" ${issue.message}`;
+    })
+        .join('\n  ');
+}
+function invalidValue(key, issues) {
+    return new FireForgeError('config-invalid-value', issueLines(key, issues), {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+    });
+}
+/**
+ * Turns command-line text into the value a key takes. JSON is read as JSON
+ * when the key accepts the result (`4`, `true`, `null`, `["a"]`), and the text
+ * stays a string otherwise, so a string key never turns `128` into a number.
+ *
+ * @param key - A key path
+ * @param text - The value as typed
+ * @throws `config-invalid-value` (exit code 8) when the key accepts neither reading
+ */
+export function coerceConfigValue(key, text) {
+    const schema = schemaOf(key, segmentsOf(key));
+    let parsed;
+    try {
+        parsed = parseJson(text);
+    }
+    catch {
+        parsed = undefined;
+    }
+    const asJson = parsed === undefined ? undefined : schema.validate(parsed);
+    if (asJson?.ok === true && parsed !== undefined)
+        return parsed;
+    const asText = schema.validate(text);
+    if (asText.ok)
+        return text;
+    const issues = asJson !== undefined && !asJson.ok && typeof parsed !== 'string'
+        ? asJson.issues
+        : asText.issues;
+    throw invalidValue(key, issues);
+}
+/** A copy of `document` with `value` at the key path, creating missing objects on the way. */
+function withValue(document, key, segments, value) {
+    const next = structuredClone(document);
+    let parent = next;
+    for (const [index, segment] of segments.entries()) {
+        const last = index === segments.length - 1;
+        if (Array.isArray(parent)) {
+            const position = /^\d+$/.test(segment) ? Number(segment) : Number.NaN;
+            if (!(position <= parent.length)) {
+                throw unknownKey(key, `names index ${segment} of a list of ${parent.length}`);
+            }
+            if (last)
+                parent[position] = value;
+            else
+                parent = parent[position] ??= {};
+        }
+        else if (isRecord(parent)) {
+            const object = parent;
+            if (last)
+                object[segment] = value;
+            else
+                parent = object[segment] ??= {};
+        }
+        else {
+            throw unknownKey(key, 'reaches inside a value that is not an object or a list');
+        }
+    }
+    return next;
+}
+/** The refusal to move a project to another mode by editing its `mode` key. */
+function modeSwitch(target) {
+    return new FireForgeError('config-mode-switch', `"mode" cannot be set to ${JSON.stringify(target)} with "config set": the mode changes together with the "source" section and the files that hold the owned changes`, {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+        hint: target === 'source'
+            ? 'Run "fireforge migrate --to-source" to convert a patch-mode project to source mode.'
+            : 'Run "fireforge export" to write the patch queue, then edit fireforge.json by hand: set "mode" to "patches" and remove "source" (docs/source-workflow.md, "Coming from patch mode, going back").',
+    });
+}
+/**
+ * Sets one key of `fireforge.json` from command-line text. The value is typed
+ * by the key's schema ({@link coerceConfigValue}), the whole resulting document
+ * must validate, and only the changed value is rewritten. Concurrent edits are
+ * serialised, so none is lost.
+ *
+ * @param projectRoot - The project directory
+ * @param key - A key path such as `build.jobs`
+ * @param text - The value as typed
+ * @throws `config-unknown-key`, `config-invalid-value`, or `config-mode-switch` for a
+ *   change of `mode` (exit code 8)
+ */
+export async function setConfigValue(projectRoot, key, text) {
+    const segments = segmentsOf(key);
+    const value = coerceConfigValue(key, text);
+    const lock = join(projectRoot, '.fireforge', 'config.lock');
+    return withLock(lock, { label: CONFIG_FILE, info: { command: 'config set' } }, async () => {
+        const current = await readConfigDocument(projectRoot);
+        if (key === 'mode' && value !== (current.document['mode'] ?? modeKey.fallback?.value)) {
+            throw modeSwitch(value);
+        }
+        const next = withValue(current.document, key, segments, value);
+        const result = configSchema.validate(next);
+        if (!result.ok)
+            throw invalidValue('', result.issues);
+        const edited = editJsonText(current.text, next) ?? stringifyJson(next);
+        const changed = edited !== current.text;
+        if (changed)
+            await writeFile(join(projectRoot, CONFIG_FILE), edited);
+        return { path: key, value, changed };
+    });
+}

package/dist/src/config/index.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge.json`: its schema (the single source of its types, validation,
+ * key paths and key documentation), loading, and editing one key at a time.
+ */
+export { coerceConfigValue, configKeys, getConfigValue, setConfigValue } from './edit.js';
+export { CONFIG_FILE, loadConfig, readConfigDocument } from './load.js';
+export { upgradeConfig } from './previous.js';
+export { CHECK_STEPS } from './schema/check.js';
+export { FIREFOX_PRODUCTS, inferFirefoxProduct, } from './schema/firefox.js';
+export { ARTIFACTS_PLACEHOLDER } from './schema/gate.js';
+export { DEFAULT_LICENSE, markerComment, PROJECT_LICENSES } from './schema/identity.js';
+export { configSchema } from './schema/index.js';
+export { fileSizeBands, LINT_RULE_IDS, matchesPropertyName, patchSizeBands, } from './schema/lint.js';
+export { PROJECT_MODES } from './schema/source.js';

package/dist/src/config/load.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** Reading `fireforge.json`: the raw document and the validated configuration. */
+import { join } from 'node:path';
+import { ExitCode, FireForgeError, toError } from '../kernel/errors.js';
+import { readTextIfExists } from '../kernel/fs.js';
+import { isRecord, parseJson } from '../kernel/json.js';
+import { configSchema } from './schema/index.js';
+/** The configuration file's name at the project root. */
+export const CONFIG_FILE = 'fireforge.json';
+/**
+ * Reads `fireforge.json` as a JSON object without validating it, for editing.
+ *
+ * @param projectRoot - The directory holding the file
+ * @returns The document and its text as on disk
+ * @throws `config-missing` or `config-invalid` (exit code 2)
+ */
+export async function readConfigDocument(projectRoot) {
+    const path = join(projectRoot, CONFIG_FILE);
+    const text = await readTextIfExists(path);
+    if (text === undefined) {
+        throw new FireForgeError('config-missing', `${path} does not exist`, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            hint: 'Run "fireforge setup" to create a project.',
+        });
+    }
+    let document;
+    try {
+        document = parseJson(text, { source: path });
+    }
+    catch (error) {
+        throw new FireForgeError('config-invalid', toError(error).message, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            cause: error,
+        });
+    }
+    if (!isRecord(document)) {
+        throw new FireForgeError('config-invalid', `${path} must hold a JSON object`, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            hint: 'Restore fireforge.json from version control.',
+        });
+    }
+    return { document, text };
+}
+/**
+ * Loads and validates `fireforge.json`, with defaults applied. Every problem
+ * in the file is reported at once, each by its key path; an unknown key names
+ * the nearest known one.
+ *
+ * @param projectRoot - The directory holding the file
+ * @throws `config-missing` or `config-invalid` (exit code 2)
+ */
+export async function loadConfig(projectRoot) {
+    const { document } = await readConfigDocument(projectRoot);
+    return configSchema.parse(document, {
+        source: join(projectRoot, CONFIG_FILE),
+        code: 'config-invalid',
+        exitCode: ExitCode.CONFIG_ERROR,
+    });
+}