@hominis/fireforge 0.9.0

package/dist/src/core/patch-manifest-io.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Manifest I/O: load, save, and add operations for patches.json.
+ */
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { validatePatchesManifest } from './patch-manifest-validate.js';
+/** Filename for the patches manifest */
+export const PATCHES_MANIFEST = 'patches.json';
+/**
+ * Loads and validates the patches manifest, returning full state information.
+ * @param patchesDir - Path to the patches directory
+ */
+export async function loadPatchesManifestState(patchesDir) {
+    const manifestPath = join(patchesDir, PATCHES_MANIFEST);
+    if (!(await pathExists(manifestPath))) {
+        return { exists: false, manifest: null, parseError: undefined };
+    }
+    try {
+        const manifest = validatePatchesManifest(await readJson(manifestPath));
+        return {
+            exists: true,
+            manifest,
+            parseError: undefined,
+        };
+    }
+    catch (error) {
+        return {
+            exists: true,
+            manifest: null,
+            parseError: toError(error),
+        };
+    }
+}
+/**
+ * Loads the patches manifest if it exists.
+ * @param patchesDir - Path to the patches directory
+ * @returns PatchesManifest or null if not found
+ */
+export async function loadPatchesManifest(patchesDir) {
+    const state = await loadPatchesManifestState(patchesDir);
+    return state.manifest;
+}
+/**
+ * Saves the patches manifest.
+ * @param patchesDir - Path to the patches directory
+ * @param manifest - Manifest to save
+ */
+export async function savePatchesManifest(patchesDir, manifest) {
+    const manifestPath = join(patchesDir, PATCHES_MANIFEST);
+    await writeJson(manifestPath, manifest);
+}
+/**
+ * Adds or updates a patch entry in the manifest.
+ * @param patchesDir - Path to the patches directory
+ * @param metadata - Patch metadata to add/update
+ * @param removeFilenames - Optional filenames to remove in the same read-modify-write cycle
+ */
+export async function addPatchToManifest(patchesDir, metadata, removeFilenames) {
+    const manifest = (await loadPatchesManifest(patchesDir)) ?? {
+        version: 1,
+        patches: [],
+    };
+    // Remove existing entry with same filename if present
+    manifest.patches = manifest.patches.filter((p) => p.filename !== metadata.filename);
+    // Remove superseded entries in the same cycle to avoid race conditions
+    if (removeFilenames && removeFilenames.length > 0) {
+        const removeSet = new Set(removeFilenames);
+        manifest.patches = manifest.patches.filter((p) => !removeSet.has(p.filename));
+    }
+    // Add new entry and sort by order
+    manifest.patches.push(metadata);
+    manifest.patches.sort((a, b) => a.order - b.order);
+    await savePatchesManifest(patchesDir, manifest);
+}
+//# sourceMappingURL=patch-manifest-io.js.map

package/dist/src/core/patch-manifest-query.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Query helpers: finding patches by file, integrity checks, version compat, stamping.
+ */
+import type { PatchesManifest, PatchInfo, PatchMetadata } from '../types/commands/index.js';
+/**
+ * Gets all file paths claimed by patches other than the excluded one.
+ * @param manifest - The patches manifest
+ * @param excludeFilename - Filename to exclude from collection
+ * @returns Set of file paths claimed by other patches
+ */
+export declare function getClaimedFiles(manifest: PatchesManifest, excludeFilename: string): Set<string>;
+/**
+ * Checks ESR version compatibility.
+ * @param patchVersion - Version the patch was created for
+ * @param currentVersion - Current project version
+ * @returns Warning message if versions differ, null if compatible
+ */
+export declare function checkVersionCompatibility(patchVersion: string, currentVersion: string): string | null;
+/**
+ * Finds all patches that affect a specific file.
+ * @param patchesDir - Path to the patches directory
+ * @param filePath - File path to search for
+ * @returns Patches affecting the file, sorted by order
+ */
+export declare function findPatchesAffectingFile(patchesDir: string, filePath: string): Promise<Array<{
+    patch: PatchInfo;
+    metadata: PatchMetadata;
+}>>;
+/**
+ * Validates that all patches can be applied successfully.
+ * Detects modification patches that reference files not in the source.
+ * @param patchesDir - Path to the patches directory
+ * @param engineDir - Path to the engine directory
+ * @returns Array of validation issues with details
+ */
+export declare function validatePatchIntegrity(patchesDir: string, engineDir: string): Promise<Array<{
+    filename: string;
+    message: string;
+    targetFile: string | null;
+}>>;
+/**
+ * Stamps multiple patches with a new `sourceEsrVersion` in a single
+ * manifest read-modify-write cycle.
+ * @param patchesDir - Path to the patches directory
+ * @param filenames - Patch filenames to update
+ * @param newVersion - Version string to set (e.g. "140.0esr")
+ */
+export declare function stampPatchVersions(patchesDir: string, filenames: string[], newVersion: string): Promise<void>;

package/dist/src/core/patch-manifest-query.js

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Query helpers: finding patches by file, integrity checks, version compat, stamping.
+ */
+import { readText } from '../utils/fs.js';
+import { fileExistsInHead } from './git-file-ops.js';
+import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
+import { loadPatchesManifest, savePatchesManifest } from './patch-manifest-io.js';
+import { isNewFileInPatch } from './patch-parse.js';
+/**
+ * Gets all file paths claimed by patches other than the excluded one.
+ * @param manifest - The patches manifest
+ * @param excludeFilename - Filename to exclude from collection
+ * @returns Set of file paths claimed by other patches
+ */
+export function getClaimedFiles(manifest, excludeFilename) {
+    const claimed = new Set();
+    for (const patch of manifest.patches) {
+        if (patch.filename === excludeFilename)
+            continue;
+        for (const file of patch.filesAffected) {
+            claimed.add(file);
+        }
+    }
+    return claimed;
+}
+/**
+ * Checks ESR version compatibility.
+ * @param patchVersion - Version the patch was created for
+ * @param currentVersion - Current project version
+ * @returns Warning message if versions differ, null if compatible
+ */
+export function checkVersionCompatibility(patchVersion, currentVersion) {
+    if (patchVersion === currentVersion) {
+        return null;
+    }
+    // Extract major version numbers
+    const patchMajor = parseInt(patchVersion.split('.')[0] ?? '0', 10);
+    const currentMajor = parseInt(currentVersion.split('.')[0] ?? '0', 10);
+    if (patchMajor !== currentMajor) {
+        return (`Patch was created for Firefox ${patchVersion}, ` +
+            `but current version is ${currentVersion}. ` +
+            `Major version mismatch may cause conflicts.`);
+    }
+    return (`Patch was created for Firefox ${patchVersion}, ` + `current version is ${currentVersion}.`);
+}
+/**
+ * Finds all patches that affect a specific file.
+ * @param patchesDir - Path to the patches directory
+ * @param filePath - File path to search for
+ * @returns Patches affecting the file, sorted by order
+ */
+export async function findPatchesAffectingFile(patchesDir, filePath) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return [];
+    const patches = await discoverPatches(patchesDir);
+    const results = [];
+    for (const metadata of manifest.patches) {
+        if (metadata.filesAffected.includes(filePath)) {
+            const patch = patches.find((p) => p.filename === metadata.filename);
+            if (patch) {
+                results.push({ patch, metadata });
+            }
+        }
+    }
+    // Sort by order
+    results.sort((a, b) => a.patch.order - b.patch.order);
+    return results;
+}
+/**
+ * Validates that all patches can be applied successfully.
+ * Detects modification patches that reference files not in the source.
+ * @param patchesDir - Path to the patches directory
+ * @param engineDir - Path to the engine directory
+ * @returns Array of validation issues with details
+ */
+export async function validatePatchIntegrity(patchesDir, engineDir) {
+    const issues = [];
+    const patches = await discoverPatches(patchesDir);
+    for (const patch of patches) {
+        // Check all files in the patch (supports multi-file patches)
+        const patchContent = await readText(patch.path);
+        const targetFiles = await getAllTargetFilesFromPatch(patch.path);
+        for (const targetFile of targetFiles) {
+            // Skip new-file sections — they don't need to exist in HEAD
+            if (isNewFileInPatch(patchContent, targetFile))
+                continue;
+            const existsInHead = await fileExistsInHead(engineDir, targetFile);
+            if (!existsInHead) {
+                issues.push({
+                    filename: patch.filename,
+                    message: `Modification patch for file that doesn't exist in source. Re-export with: fireforge export ${targetFile}`,
+                    targetFile,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Stamps multiple patches with a new `sourceEsrVersion` in a single
+ * manifest read-modify-write cycle.
+ * @param patchesDir - Path to the patches directory
+ * @param filenames - Patch filenames to update
+ * @param newVersion - Version string to set (e.g. "140.0esr")
+ */
+export async function stampPatchVersions(patchesDir, filenames, newVersion) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return;
+    const filenameSet = new Set(filenames);
+    let modified = false;
+    for (const patch of manifest.patches) {
+        if (filenameSet.has(patch.filename) && patch.sourceEsrVersion !== newVersion) {
+            patch.sourceEsrVersion = newVersion;
+            modified = true;
+        }
+    }
+    if (modified) {
+        await savePatchesManifest(patchesDir, manifest);
+    }
+}
+//# sourceMappingURL=patch-manifest-query.js.map

package/dist/src/core/patch-manifest-validate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Schema validation for patches.json manifest data.
+ */
+import type { PatchCategory, PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+/**
+ * Validates a single patch metadata entry from raw data.
+ * @param data - Raw data to validate
+ * @param index - Array index for error messages
+ * @returns Validated PatchMetadata
+ */
+export declare function validatePatchMetadata(data: unknown, index: number): PatchMetadata;
+/** Validates raw patches.json data and returns the typed manifest shape. */
+export declare function validatePatchesManifest(data: unknown): PatchesManifest;
+/**
+ * Infers patch metadata from a filename pattern.
+ * @param filename - Patch filename (e.g. "001-ui-toolbar.patch")
+ * @returns Inferred category and name
+ */
+export declare function inferPatchMetadataFromFilename(filename: string): {
+    category: PatchCategory;
+    name: string;
+};

package/dist/src/core/patch-manifest-validate.js

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Schema validation for patches.json manifest data.
+ */
+import { parseObject } from '../utils/parse.js';
+import { isArray, isObject, isValidFirefoxVersion, isValidPatchCategory, PATCH_CATEGORIES, } from '../utils/validation.js';
+/**
+ * Validates a single patch metadata entry from raw data.
+ * @param data - Raw data to validate
+ * @param index - Array index for error messages
+ * @returns Validated PatchMetadata
+ */
+export function validatePatchMetadata(data, index) {
+    const rec = parseObject(data, `patches[${index}]`);
+    const filename = rec.string('filename');
+    const name = rec.string('name');
+    const description = rec.string('description');
+    const createdAt = rec.string('createdAt');
+    const sourceEsrVersion = rec.string('sourceEsrVersion');
+    const order = rec.nonNegativeInteger('order');
+    const category = rec.stringEnum('category', (v) => isValidPatchCategory(v), `one of: ${PATCH_CATEGORIES.join(', ')}`);
+    if (!isValidFirefoxVersion(sourceEsrVersion)) {
+        throw new Error(`patches[${index}].sourceEsrVersion must be a valid Firefox version string`);
+    }
+    const filesAffected = rec.stringArray('filesAffected');
+    return {
+        filename,
+        order,
+        category,
+        name,
+        description,
+        createdAt,
+        sourceEsrVersion,
+        filesAffected,
+    };
+}
+/** Validates raw patches.json data and returns the typed manifest shape. */
+export function validatePatchesManifest(data) {
+    if (!isObject(data)) {
+        throw new Error('patches.json must be a JSON object');
+    }
+    if (data['version'] !== 1) {
+        throw new Error('patches.json version must be 1');
+    }
+    if (!isArray(data['patches'])) {
+        throw new Error('patches.json field "patches" must be an array');
+    }
+    return {
+        version: 1,
+        patches: data['patches'].map((patch, index) => validatePatchMetadata(patch, index)),
+    };
+}
+/**
+ * Infers patch metadata from a filename pattern.
+ * @param filename - Patch filename (e.g. "001-ui-toolbar.patch")
+ * @returns Inferred category and name
+ */
+export function inferPatchMetadataFromFilename(filename) {
+    const categorizedMatch = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(filename);
+    if (categorizedMatch?.[2] && categorizedMatch[3]) {
+        const category = categorizedMatch[2];
+        if (PATCH_CATEGORIES.includes(category)) {
+            return { category, name: categorizedMatch[3] };
+        }
+    }
+    const legacyMatch = /^(\d+)-(.+)\.patch$/.exec(filename);
+    if (legacyMatch?.[2]) {
+        return { category: 'infra', name: legacyMatch[2] };
+    }
+    return { category: 'infra', name: filename.replace(/\.patch$/, '') };
+}
+//# sourceMappingURL=patch-manifest-validate.js.map

package/dist/src/core/patch-manifest.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Patches manifest — re-exports from focused sub-modules.
+ *
+ * Callers should continue to import from this module; the internal split
+ * is an implementation detail.
+ */
+export type { PatchManifestConsistencyIssue } from './patch-manifest-consistency.js';
+export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { addPatchToManifest, loadPatchesManifest, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
+export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
+export { validatePatchesManifest } from './patch-manifest-validate.js';

package/dist/src/core/patch-manifest.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Patches manifest — re-exports from focused sub-modules.
+ *
+ * Callers should continue to import from this module; the internal split
+ * is an implementation detail.
+ */
+export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { addPatchToManifest, loadPatchesManifest, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
+export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
+export { validatePatchesManifest } from './patch-manifest-validate.js';
+//# sourceMappingURL=patch-manifest.js.map

package/dist/src/core/patch-parse.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure parsing functions for extracting information from patch files.
+ * All functions are synchronous and operate on string content.
+ */
+/**
+ * Extracts the order number from a patch filename.
+ * Expects format like "001-description.patch"
+ * @param filename - Patch filename
+ * @returns Order number, or Infinity if no prefix
+ */
+export declare function extractOrder(filename: string): number;
+/**
+ * Checks whether a specific file is a new-file addition within a patch.
+ * For multi-file patches, only inspects the section belonging to targetFile.
+ * @param patchContent - The full patch content
+ * @param targetFile - The file path to check
+ * @returns true if the patch creates targetFile as a new file
+ */
+export declare function isNewFileInPatch(patchContent: string, targetFile: string): boolean;
+/**
+ * Extracts affected file paths from a diff/patch content.
+ * @param diffContent - The diff content to parse
+ * @returns Array of file paths
+ */
+export declare function extractAffectedFiles(diffContent: string): string[];
+/**
+ * Parses hunks from a patch file for a specific target file.
+ * @param patchContent - The full patch content
+ * @param targetFile - The file path to extract hunks for
+ * @returns Array of hunk objects with line info and changes
+ */
+export declare function parseHunksForFile(patchContent: string, targetFile: string): Array<{
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    lines: string[];
+    noNewlineAtEnd: boolean;
+}>;
+/**
+ * Extracts conflicting file paths from git apply error message.
+ */
+export declare function extractConflictingFiles(error?: string): string[];

package/dist/src/core/patch-parse.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Pure parsing functions for extracting information from patch files.
+ * All functions are synchronous and operate on string content.
+ */
+/**
+ * Extracts the order number from a patch filename.
+ * Expects format like "001-description.patch"
+ * @param filename - Patch filename
+ * @returns Order number, or Infinity if no prefix
+ */
+export function extractOrder(filename) {
+    const match = /^(\d+)-/.exec(filename);
+    if (match?.[1]) {
+        return parseInt(match[1], 10);
+    }
+    return Infinity;
+}
+/**
+ * Checks whether a specific file is a new-file addition within a patch.
+ * For multi-file patches, only inspects the section belonging to targetFile.
+ * @param patchContent - The full patch content
+ * @param targetFile - The file path to check
+ * @returns true if the patch creates targetFile as a new file
+ */
+export function isNewFileInPatch(patchContent, targetFile) {
+    const lines = patchContent.split('\n');
+    let inTargetFile = false;
+    for (const line of lines) {
+        if (line.startsWith('diff --git')) {
+            const match = /^diff --git a\/.+ b\/(.+)$/.exec(line);
+            inTargetFile = match?.[1] === targetFile;
+            continue;
+        }
+        if (!inTargetFile)
+            continue;
+        // Found hunk header — stop scanning metadata for this file section
+        if (line.startsWith('@@'))
+            break;
+        if (line.startsWith('new file mode ')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Extracts affected file paths from a diff/patch content.
+ * @param diffContent - The diff content to parse
+ * @returns Array of file paths
+ */
+export function extractAffectedFiles(diffContent) {
+    const files = new Set();
+    const lines = diffContent.split('\n');
+    for (const line of lines) {
+        // Match "diff --git a/path/to/file b/path/to/file"
+        const diffMatch = /^diff --git a\/.+ b\/(.+)$/.exec(line);
+        if (diffMatch?.[1]) {
+            files.add(diffMatch[1]);
+            continue;
+        }
+        // Match "+++ b/path/to/file" for new files
+        const addMatch = /^\+\+\+ b\/(.+)$/.exec(line);
+        if (addMatch?.[1] && addMatch[1] !== '/dev/null') {
+            files.add(addMatch[1]);
+        }
+    }
+    return Array.from(files).sort();
+}
+/**
+ * Parses hunks from a patch file for a specific target file.
+ * @param patchContent - The full patch content
+ * @param targetFile - The file path to extract hunks for
+ * @returns Array of hunk objects with line info and changes
+ */
+export function parseHunksForFile(patchContent, targetFile) {
+    const hunks = [];
+    const lines = patchContent.split('\n');
+    let inTargetFile = false;
+    let currentHunk = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        // Check for diff header
+        if (line.startsWith('diff --git')) {
+            // Check if this is for our target file
+            const match = /^diff --git a\/.+ b\/(.+)$/.exec(line);
+            if (currentHunk) {
+                hunks.push(currentHunk);
+            }
+            inTargetFile = match?.[1] === targetFile;
+            currentHunk = null;
+            continue;
+        }
+        if (!inTargetFile)
+            continue;
+        // Check for hunk header
+        const hunkMatch = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+        if (hunkMatch) {
+            if (currentHunk) {
+                hunks.push(currentHunk);
+            }
+            currentHunk = {
+                oldStart: parseInt(hunkMatch[1] ?? '0', 10),
+                oldCount: parseInt(hunkMatch[2] ?? '1', 10),
+                newStart: parseInt(hunkMatch[3] ?? '0', 10),
+                newCount: parseInt(hunkMatch[4] ?? '1', 10),
+                lines: [],
+                noNewlineAtEnd: false,
+            };
+            continue;
+        }
+        // Collect hunk lines
+        if (currentHunk) {
+            if (line === '\') {
+                currentHunk.noNewlineAtEnd = true;
+            }
+            else if (line.startsWith('+') || line.startsWith('-') || line.startsWith(' ')) {
+                currentHunk.lines.push(line);
+            }
+        }
+    }
+    if (currentHunk) {
+        hunks.push(currentHunk);
+    }
+    return hunks;
+}
+/**
+ * Extracts conflicting file paths from git apply error message.
+ */
+export function extractConflictingFiles(error) {
+    if (!error)
+        return [];
+    const files = [];
+    const lines = error.split('\n');
+    for (const line of lines) {
+        // Match "error: patch failed: path/to/file:line"
+        const match = /error: patch failed: ([^:]+)/.exec(line);
+        if (match?.[1]) {
+            files.push(match[1]);
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=patch-parse.js.map

package/dist/src/core/patch-transform.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure content transformation functions for patch operations.
+ * These operate on file content strings without filesystem side effects.
+ */
+/**
+ * Extracts the complete file content from a "new file" patch.
+ * When targetFile is provided, only extracts content for that file
+ * (required for multi-file patches).
+ * @param patchPath - Path to the patch file
+ * @param targetFile - Optional target file to scope extraction to
+ * @returns The file content that the patch would create
+ */
+export declare function extractNewFileContent(patchPath: string, targetFile?: string): Promise<string>;
+/**
+ * Applies a patch's changes to content.
+ * @param content - Original content (null for new files)
+ * @param patchPath - Path to the patch file
+ * @param targetFile - The file path within the patch
+ * @returns Modified content
+ */
+export declare function applyPatchToContent(content: string | null, patchPath: string, targetFile: string): Promise<string>;