@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/queue/status.js

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The queue's state as data, for the `status` and `verify` commands (which
+ * both modes share and which the `mode` layer wires): how the engine
+ * compares with the queue, and whether the stored queue is sound.
+ */
+import { join } from 'node:path';
+import { isRepository } from '../git/index.js';
+import { FireForgeError } from '../kernel/errors.js';
+import { listDir } from '../kernel/fs.js';
+import { patchProblems } from './apply.js';
+import { classifyEngine, projectQueue } from './baseline.js';
+import { policyProblems } from './placement.js';
+import { readQueue } from './queue.js';
+import { readSession } from './session.js';
+/**
+ * The engine against the queue baseline, path by path, and any paused session.
+ *
+ * @param project - A patch-mode project with an engine
+ */
+export async function queueStatus(project) {
+    const queue = await readQueue(project.paths.patches);
+    const projection = await projectQueue(project, queue);
+    const session = await readSession(project);
+    const filenames = new Map(queue.patches.map((patch) => [patch.name, patch.filename]));
+    const current = session?.patches[session.index];
+    return {
+        patches: queue.patches.length,
+        digest: queue.digest,
+        ...(projection.failure === undefined
+            ? {}
+            : { failure: { patch: projection.failure.patch, message: projection.failure.message } }),
+        ...(session === undefined
+            ? {}
+            : {
+                session: {
+                    kind: session.kind,
+                    done: Math.min(session.index, session.last + 1),
+                    total: session.last + 1,
+                    ...(current === undefined || session.index > session.last
+                        ? {}
+                        : {
+                            current: {
+                                patch: filenames.get(current.name) ?? current.name,
+                                status: current.status,
+                            },
+                        }),
+                    rejects: current?.rejects ?? [],
+                },
+            }),
+        paths: await classifyEngine(project, projection),
+    };
+}
+async function strayFiles(queue) {
+    const known = new Set(queue.patches.map((patch) => patch.path));
+    return (await listDir(queue.dir))
+        .filter((entry) => entry.kind === 'file' && entry.name.endsWith('.patch'))
+        .filter((entry) => !known.has(join(queue.dir, entry.name)))
+        .map((entry) => ({
+        code: 'stray-patch-file',
+        patch: entry.name,
+        message: `${entry.name} is not listed in patches.json; add it to the manifest or delete it.`,
+    }));
+}
+function bodyProblems(queue) {
+    return queue.patches.flatMap((patch) => {
+        if (patch.diff.files.length === 0) {
+            return [
+                {
+                    code: 'empty-patch',
+                    patch: patch.filename,
+                    message: `${patch.filename} changes no file.`,
+                },
+            ];
+        }
+        return patchProblems(patch.diff).map((problem) => ({
+            code: problem.reason.startsWith('path') ? 'unsafe-path' : 'binary-stub',
+            patch: patch.filename,
+            message: `${patch.filename}: ${problem.path} ${problem.reason}`,
+        }));
+    });
+}
+/**
+ * Checks the stored queue: the manifest reads, every listed body exists and
+ * parses, no stray patch files, no unsafe paths or content-less binary
+ * sections, the ordering half of `patchPolicy` holds, and (with an engine)
+ * the queue replays onto the engine's HEAD
+ * without any patch replacing an upstream file.
+ *
+ * @param project - A patch-mode project
+ */
+export async function verifyQueue(project) {
+    let queue;
+    try {
+        queue = await readQueue(project.paths.patches);
+    }
+    catch (error) {
+        if (!(error instanceof FireForgeError))
+            throw error;
+        return {
+            patches: 0,
+            problems: [{ code: error.code, message: error.message }],
+            replayed: false,
+        };
+    }
+    const problems = [
+        ...(await strayFiles(queue)),
+        ...bodyProblems(queue),
+        ...policyProblems(project.config.patchPolicy, queue.patches, queue.retired).map((message) => ({
+            code: 'patch-policy',
+            message,
+        })),
+    ];
+    if (!(await isRepository(project.paths.engine))) {
+        return { patches: queue.patches.length, problems, replayed: false };
+    }
+    const projection = await projectQueue(project, queue);
+    for (const step of projection.steps) {
+        for (const path of step.replaced) {
+            problems.push({
+                code: 'replaces-upstream-file',
+                patch: step.patch,
+                message: `${step.patch} creates ${path}, which upstream already has; re-export it so it modifies the file.`,
+            });
+        }
+    }
+    if (projection.failure !== undefined) {
+        const { patch, conflicts, message } = projection.failure;
+        const named = conflicts.map((conflict) => `${conflict.path} (${conflict.reason})`).join(', ');
+        problems.push({
+            code: 'does-not-apply',
+            patch,
+            message: `${patch} does not apply after the patches before it${named === '' ? `: ${message}` : `: ${named}`}`,
+        });
+    }
+    return { patches: queue.patches.length, problems, replayed: true };
+}

package/dist/src/register/files.js

@@ -0,0 +1,39 @@
+/**
+ * Reads through the edits made so far, so a plan can change one file in
+ * several steps and every step sees the previous one.
+ */
+export class EditSession {
+    files;
+    pending = new Map();
+    constructor(files) {
+        this.files = files;
+    }
+    /** The file's text as the plan leaves it so far, or undefined when it does not exist. */
+    async read(path) {
+        return this.pending.get(path) ?? this.files.read(path);
+    }
+    /** Whether the file exists, counting files the plan creates. */
+    async exists(path) {
+        return this.pending.has(path) || this.files.exists(path);
+    }
+    /** Records a file's new content. */
+    set(path, content) {
+        this.pending.set(path, content);
+    }
+    /** The edits in the order they were first made. */
+    edits() {
+        return [...this.pending].map(([path, content]) => ({ path, content }));
+    }
+}
+/**
+ * Writes the edits in order, as part of the caller's transaction: a plan
+ * lands whole or not at all.
+ *
+ * @param tx - The transaction the writes belong to
+ * @param files - Where the files live
+ * @param edits - A plan's edits
+ */
+export async function applyEdits(tx, files, edits) {
+    for (const edit of edits)
+        await files.write(tx, edit.path, edit.content);
+}

package/dist/src/register/index.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Build-manifest registration and chrome subscript wiring. Both plan their
+ * edits over `TrackedFiles` and change nothing until `applyEdits` runs.
+ */
+export { applyEdits } from './files.js';
+export { elementJarEntry, planRegister } from './register.js';
+export { planWire } from './wire.js';

package/dist/src/register/js.js

@@ -0,0 +1,217 @@
+import { usageError } from '../cli/command.js';
+import { FireForgeError, toError } from '../kernel/errors.js';
+import { escapeRegExp } from '../kernel/text.js';
+import { lineIndent, lineStart, parseJs, walkJs } from '../syntax/index.js';
+const GUARD = /typeof\s+\w+\s*!==\s*"undefined"/;
+const DANGEROUS_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+function invalid(label, value, rule) {
+    return usageError(`Invalid ${label} "${value}": ${rule}.`);
+}
+function refuseDangerous(label, value) {
+    for (const segment of value.replace(/\(\)$/, '').split('.')) {
+        if (DANGEROUS_SEGMENTS.has(segment)) {
+            throw invalid(label, value, `"${segment}" is not allowed as a property segment`);
+        }
+    }
+}
+/**
+ * Refuses a subscript name that could break out of the generated code, the
+ * jar.mn entry or the directory it names a file in.
+ *
+ * @param name - The subscript name, without `.js`
+ * @param label - What the value is called in the message
+ */
+export function validateWireName(name, label = 'subscript name') {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(name)) {
+        throw invalid(label, name, 'start with a letter or underscore and use only letters, digits, underscores and hyphens');
+    }
+    refuseDangerous(label, name);
+}
+/**
+ * Refuses an init or destroy expression that is not a dotted identifier
+ * chain with an optional `()`, since it is written into the browser as code.
+ *
+ * @param expression - Such as `MyFeature.init` or `MyFeature.init()`
+ * @param label - What the value is called in the message
+ */
+export function validateWireExpression(expression, label) {
+    if (!/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*(?:\(\))?$/.test(expression)) {
+        throw invalid(label, expression, 'use dotted identifiers (letters, digits, underscores, $), optionally ending in ()');
+    }
+    refuseDangerous(label, expression);
+}
+/** The expression as a call: `Foo.init` becomes `Foo.init()`. */
+export function asCall(expression) {
+    return expression.endsWith('()') ? expression : `${expression}()`;
+}
+function leadingName(expression) {
+    return /^[\w$]+/.exec(expression)?.[0] ?? expression;
+}
+function parseScript(content, file) {
+    try {
+        return parseJs(content, 'script').program;
+    }
+    catch (error) {
+        throw new FireForgeError('script-unparseable', `${file} cannot be parsed: ${toError(error).message}`, { hint: 'Fix the file first; FireForge does not edit a script it cannot parse.' });
+    }
+}
+function insertBlock(content, anchor, block) {
+    const lines = (indent) => block(indent).join('\n');
+    if (anchor.at === 'after') {
+        const indent = lineIndent(content, anchor.node.start);
+        return `${content.slice(0, anchor.node.end)}\n${lines(indent)}${content.slice(anchor.node.end)}`;
+    }
+    if (anchor.at === 'before') {
+        const position = lineStart(content, anchor.node.start);
+        const indent = lineIndent(content, anchor.node.start);
+        return `${content.slice(0, position)}${lines(indent)}\n${content.slice(position)}`;
+    }
+    const open = anchor.body.start + 1;
+    const indent = `${lineIndent(content, anchor.body.start)}  `;
+    return `${content.slice(0, open)}\n${lines(indent)}${content.slice(open)}`;
+}
+function guardedBlock(kind, expression, marker) {
+    const name = leadingName(expression);
+    return (i) => [
+        `// ${marker} wire-${kind} ${name}`,
+        'try {',
+        `  if (typeof ${name} !== "undefined") {`,
+        `    ${asCall(expression)};`,
+        '  }',
+        '} catch (e) {',
+        `  console.error("${name} ${kind} failed:", e);`,
+        '}',
+    ].map((line) => i + line);
+}
+/**
+ * The body of the function a property or class method of one of `names`
+ * holds, such as `onLoad() { ... }` in an object literal.
+ */
+function findMethodBody(program, names) {
+    let found;
+    walkJs(program, (node) => {
+        if (found === undefined &&
+            (node.type === 'Property' || node.type === 'MethodDefinition') &&
+            !node.computed &&
+            node.key.type === 'Identifier' &&
+            names.includes(node.key.name) &&
+            (node.value.type === 'FunctionExpression' || node.value.type === 'ArrowFunctionExpression') &&
+            node.value.body.type === 'BlockStatement') {
+            found = node.value.body;
+        }
+        return found === undefined;
+    });
+    return found;
+}
+/**
+ * Adds a guarded `loadSubScript` for `name` after the last existing one in
+ * browser-main.js, or at the end of the file's last block.
+ *
+ * @param content - browser-main.js
+ * @param name - The subscript, without `.js`
+ * @param marker - The comment marker the lint rules look for, such as `MYBROWSER:`
+ * @returns The new text, or undefined when the subscript is already loaded
+ */
+export function addSubscript(content, name, marker) {
+    if (content.includes(`content/${name}.js"`))
+        return undefined;
+    const program = parseScript(content, 'browser-main.js');
+    const loaders = [];
+    walkJs(program, (node) => {
+        if (node.type === 'TryStatement' &&
+            content.slice(node.start, node.end).includes('loadSubScript')) {
+            loaders.push(node);
+        }
+    });
+    const outermost = loaders.filter((inner) => !loaders.some((outer) => outer !== inner && outer.start <= inner.start && inner.end <= outer.end));
+    const last = outermost.at(-1);
+    const block = (i) => [
+        `// ${marker} wire-subscript ${name}`,
+        'try {',
+        `  Services.scriptloader.loadSubScript("chrome://browser/content/${name}.js", this);`,
+        '} catch (e) {',
+        `  console.error("Failed to load ${name}.js:", e);`,
+        '}',
+    ].map((line) => i + line);
+    if (last !== undefined)
+        return insertBlock(content, { at: 'after', node: last }, block);
+    const close = content.lastIndexOf('\n}');
+    if (close === -1) {
+        throw new FireForgeError('script-no-anchor', 'browser-main.js has no closing brace to insert before.', { hint: 'Add the subscript load to browser-main.js by hand.' });
+    }
+    return insertBlock(content, { at: 'before', node: { start: close + 1 } }, (i) => block(`${i}  `));
+}
+/** Whether the script calls `expression` anywhere; comments and strings never count. */
+function alreadyCalls(content, program, expression) {
+    const callee = expression.replace(/\(\)$/, '');
+    let found = false;
+    walkJs(program, (node) => {
+        if (node.type === 'CallExpression') {
+            const target = node.callee;
+            if (content.slice(target.start, target.end) === callee)
+                found = true;
+        }
+        return !found;
+    });
+    return found;
+}
+/** Whether `text` is the init block that `after` names: it guards on, or calls `init` of, that name. */
+function initBlockOf(text, name) {
+    const target = escapeRegExp(name);
+    return new RegExp(`(?<![\\w$.])typeof\\s+${target}(?![\\w$])|(?<![\\w$.])${target}\\.init\\(`).test(text);
+}
+/**
+ * Adds a guarded init call to `onLoad` in browser-init.js, after the block
+ * of the subscript `after` names, else after the last init block already
+ * there, else first.
+ *
+ * @param content - browser-init.js
+ * @param expression - `Name.init` or `Name.init()`
+ * @param options - `after` is a subscript name; `marker` is the comment marker
+ * @returns The new text, or undefined when the call is already there
+ */
+export function addInit(content, expression, options) {
+    const program = parseScript(content, 'browser-init.js');
+    if (alreadyCalls(content, program, expression))
+        return undefined;
+    const body = findMethodBody(program, ['onLoad']);
+    if (body === undefined) {
+        throw new FireForgeError('script-no-anchor', 'browser-init.js has no onLoad method.', {
+            hint: 'Add the init call to browser-init.js by hand.',
+        });
+    }
+    const statements = body.body;
+    const blocks = statements.filter((statement) => statement.type === 'TryStatement' && GUARD.test(content.slice(statement.start, statement.end)));
+    const named = options.after === undefined
+        ? undefined
+        : blocks.find((block) => initBlockOf(content.slice(block.start, block.end), options.after ?? ''));
+    const anchor = named ?? blocks.at(-1);
+    const first = statements[0];
+    const place = anchor !== undefined
+        ? { at: 'after', node: anchor }
+        : first !== undefined
+            ? { at: 'before', node: first }
+            : { at: 'first', body };
+    return insertBlock(content, place, guardedBlock('init', expression, options.marker));
+}
+/**
+ * Adds a guarded destroy call first in `onUnload` (or `uninit`) of
+ * browser-init.js, so teardown runs newest first.
+ *
+ * @param content - browser-init.js
+ * @param expression - `Name.destroy` or `Name.destroy()`
+ * @param marker - The comment marker
+ * @returns The new text, or undefined when the call is already there
+ */
+export function addDestroy(content, expression, marker) {
+    const program = parseScript(content, 'browser-init.js');
+    if (alreadyCalls(content, program, expression))
+        return undefined;
+    const body = findMethodBody(program, ['onUnload', 'uninit']);
+    if (body === undefined) {
+        throw new FireForgeError('script-no-anchor', 'browser-init.js has no onUnload or uninit method.', { hint: 'Add the destroy call to browser-init.js by hand.' });
+    }
+    const first = body.body[0];
+    const place = first !== undefined ? { at: 'before', node: first } : { at: 'first', body };
+    return insertBlock(content, place, guardedBlock('destroy', expression, marker));
+}