@hominis/fireforge 0.9.0

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

@@ -0,0 +1,403 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { hasRawCssColors, stripJsComments } from '../utils/regex.js';
+import { loadFurnaceConfig } from './furnace-config.js';
+import { getLicenseHeader, hasAnyLicenseHeader } from './license-headers.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const JS_EXTENSIONS = ['.js', '.mjs', '.jsm'];
+/**
+ * Returns true if the filename looks like a JS/MJS/JSM file.
+ * Handles `.sys.mjs` as well.
+ */
+function isJsFile(file) {
+    return JS_EXTENSIONS.some((ext) => file.endsWith(ext));
+}
+/**
+ * Detects comment style from file extension for license header checks.
+ */
+export function commentStyleForFile(file) {
+    if (file.endsWith('.css'))
+        return 'css';
+    if (file.endsWith('.ftl'))
+        return 'hash';
+    if (isJsFile(file))
+        return 'js';
+    return null;
+}
+/**
+ * Extracts new-file paths from a unified diff by scanning for `new file mode` markers.
+ */
+export function detectNewFilesInDiff(diffContent) {
+    const newFiles = new Set();
+    const lines = diffContent.split('\n');
+    let currentFile = null;
+    for (const line of lines) {
+        if (line.startsWith('diff --git')) {
+            const match = /^diff --git a\/.+ b\/(.+)$/.exec(line);
+            currentFile = match?.[1] ?? null;
+            continue;
+        }
+        if (line.startsWith('new file mode') && currentFile) {
+            newFiles.add(currentFile);
+        }
+    }
+    return newFiles;
+}
+/**
+ * Extracts added lines per file from a unified diff.
+ * Returns a map of file path → array of added line contents (without the leading `+`).
+ */
+function extractAddedLinesPerFile(diffContent) {
+    const result = new Map();
+    const lines = diffContent.split('\n');
+    let currentFile = null;
+    let inHunk = false;
+    for (const line of lines) {
+        if (line.startsWith('diff --git')) {
+            const match = /^diff --git a\/.+ b\/(.+)$/.exec(line);
+            currentFile = match?.[1] ?? null;
+            inHunk = false;
+            continue;
+        }
+        if (line.startsWith('@@')) {
+            inHunk = true;
+            continue;
+        }
+        if (inHunk && currentFile && line.startsWith('+') && !line.startsWith('+++')) {
+            let arr = result.get(currentFile);
+            if (!arr) {
+                arr = [];
+                result.set(currentFile, arr);
+            }
+            arr.push(line.slice(1));
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// CSS lint (existing — now with severity)
+// ---------------------------------------------------------------------------
+/**
+ * Lints patched CSS files for raw color values and non-tokenized custom properties.
+ *
+ * @param repoDir - Absolute path to the engine (repository) directory
+ * @param affectedFiles - File paths (relative to repoDir) affected by the patch
+ * @returns Array of lint issues found
+ */
+export async function lintPatchedCss(repoDir, affectedFiles) {
+    const cssFiles = affectedFiles.filter((f) => f.endsWith('.css'));
+    if (cssFiles.length === 0)
+        return [];
+    // Load furnace config gracefully — skip token-prefix check if unavailable
+    let tokenPrefix;
+    let tokenAllowlist;
+    try {
+        const root = join(repoDir, '..');
+        const config = await loadFurnaceConfig(root);
+        if (config.tokenPrefix) {
+            tokenPrefix = config.tokenPrefix;
+            tokenAllowlist = new Set(config.tokenAllowlist ?? []);
+        }
+    }
+    catch (error) {
+        verbose(`Skipping furnace token-prefix lint hints because furnace.json could not be loaded: ${toError(error).message}`);
+    }
+    const issues = [];
+    for (const file of cssFiles) {
+        const filePath = join(repoDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const rawCss = await readText(filePath);
+        // Strip block comments before scanning
+        const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
+        // Check for raw color values
+        if (hasRawCssColors(cssContent)) {
+            issues.push({
+                file,
+                check: 'raw-color-value',
+                message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
+                severity: 'warning',
+            });
+        }
+        // Check for non-tokenized custom properties
+        if (tokenPrefix) {
+            const varPattern = /var\(\s*(--[\w-]+)/g;
+            let match;
+            while ((match = varPattern.exec(cssContent)) !== null) {
+                const prop = match[1];
+                if (prop && !prop.startsWith(tokenPrefix) && !tokenAllowlist?.has(prop)) {
+                    issues.push({
+                        file,
+                        check: 'token-prefix-violation',
+                        message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token or add to tokenAllowlist.`,
+                        severity: 'error',
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// License header lint
+// ---------------------------------------------------------------------------
+/**
+ * Checks new files for required license headers.
+ *
+ * @param repoDir - Absolute path to the engine directory
+ * @param newFiles - New file paths (relative to repoDir)
+ * @param config - Project configuration
+ * @returns Array of lint issues
+ */
+export async function lintNewFileHeaders(repoDir, newFiles, config) {
+    const license = config.license ?? 'MPL-2.0';
+    const issues = [];
+    for (const file of newFiles) {
+        const style = commentStyleForFile(file);
+        if (!style)
+            continue;
+        const filePath = join(repoDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const content = await readText(filePath);
+        const expectedHeader = getLicenseHeader(license, style);
+        if (!content.startsWith(expectedHeader)) {
+            issues.push({
+                file,
+                check: 'missing-license-header',
+                message: `New file is missing the required ${license} license header.`,
+                severity: 'error',
+            });
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// JS lint
+// ---------------------------------------------------------------------------
+/**
+ * Lints patched JS/MJS files for import conventions, file size, JSDoc, and
+ * observer topic naming.
+ *
+ * @param repoDir - Absolute path to the engine directory
+ * @param affectedFiles - File paths (relative to repoDir)
+ * @param newFiles - Set of files that are newly created in this patch
+ * @param config - Project configuration
+ * @returns Array of lint issues
+ */
+export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config) {
+    const jsFiles = affectedFiles.filter(isJsFile);
+    if (jsFiles.length === 0)
+        return [];
+    const issues = [];
+    const binaryName = config.binaryName.toLowerCase();
+    for (const file of jsFiles) {
+        const filePath = join(repoDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const content = await readText(filePath);
+        const isNew = newFiles.has(file);
+        const isSysMjs = file.endsWith('.sys.mjs');
+        // 1. Relative import check
+        const strippedContent = stripJsComments(content);
+        const relativeImportPattern = /(?:ChromeUtils\.import(?:ESModule)?|Cu\.import)\s*\(\s*["'](?:\.\.?\/)/gm;
+        const esRelativePattern = /\bimport\s+.*?\s+from\s+["'](?:\.\.?\/)/gm;
+        if (relativeImportPattern.test(strippedContent) || esRelativePattern.test(strippedContent)) {
+            issues.push({
+                file,
+                check: 'relative-import',
+                message: `Relative imports are not allowed. Use "resource:///modules/${config.binaryName}/" for .sys.mjs or "chrome://browser/content/" for subscripts.`,
+                severity: 'error',
+            });
+        }
+        // 2. File size check (new files only)
+        if (isNew) {
+            const lineCount = content.split('\n').length;
+            if (lineCount > 650) {
+                issues.push({
+                    file,
+                    check: 'file-too-large',
+                    message: `New file has ${lineCount} lines (recommended max: 650). Consider decomposing.`,
+                    severity: 'warning',
+                });
+            }
+        }
+        // 3. JSDoc on exports (new .sys.mjs files only)
+        if (isNew && isSysMjs) {
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i] ?? '';
+                if (/^export\s+(function|class|const|let|var)\s/.test(line)) {
+                    // Walk backwards to find JSDoc
+                    let hasJsDoc = false;
+                    for (let j = i - 1; j >= 0; j--) {
+                        const prev = (lines[j] ?? '').trim();
+                        if (prev === '')
+                            continue;
+                        if (prev.endsWith('*/')) {
+                            hasJsDoc = true;
+                        }
+                        break;
+                    }
+                    if (!hasJsDoc) {
+                        issues.push({
+                            file,
+                            check: 'missing-jsdoc',
+                            message: `Export at line ${i + 1} is missing a JSDoc comment with @param/@returns.`,
+                            severity: 'warning',
+                        });
+                    }
+                }
+            }
+        }
+        // 4. Observer topic naming
+        const topicPattern = /(?:addObserver|removeObserver|notifyObservers)\s*\([^)]*["']([^"']+)["']/g;
+        let topicMatch;
+        while ((topicMatch = topicPattern.exec(strippedContent)) !== null) {
+            const topic = topicMatch[1];
+            if (!topic)
+                continue;
+            // Only flag topics that contain the binaryName but don't follow convention
+            if (topic.toLowerCase().includes(binaryName) && !/^[\w]+-[a-z]+-[a-z]+/.test(topic)) {
+                issues.push({
+                    file,
+                    check: 'observer-topic-naming',
+                    message: `Observer topic "${topic}" should follow "${binaryName}-<noun>-<verb>" naming convention.`,
+                    severity: 'warning',
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Modification comment lint
+// ---------------------------------------------------------------------------
+/**
+ * Checks that modifications to existing (non-new) JS/MJS files include at
+ * least one `// BINARYNAME:` comment in the added lines.
+ *
+ * @param diffContent - Raw unified diff string
+ * @param config - Project configuration
+ * @returns Array of lint issues
+ */
+export function lintModificationComments(diffContent, config) {
+    const newFiles = detectNewFilesInDiff(diffContent);
+    const addedLines = extractAddedLinesPerFile(diffContent);
+    const issues = [];
+    const marker = `// ${config.binaryName.toUpperCase()}:`;
+    for (const [file, lines] of addedLines) {
+        // Only check JS/MJS files that are modifications (not new files)
+        if (!isJsFile(file) || newFiles.has(file))
+            continue;
+        const hasMarker = lines.some((line) => line.toUpperCase().includes(marker.toUpperCase()));
+        if (!hasMarker && lines.length > 0) {
+            issues.push({
+                file,
+                check: 'missing-modification-comment',
+                message: `Modified upstream file lacks a "${marker}" comment marking your changes.`,
+                severity: 'warning',
+            });
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Patch size lint (moved from export-shared.ts warnLargePatch)
+// ---------------------------------------------------------------------------
+/**
+ * Checks patch size and emits advisory warnings.
+ */
+export function lintPatchSize(filesAffected, lineCount) {
+    const issues = [];
+    if (filesAffected.length > 5) {
+        issues.push({
+            file: '(patch)',
+            check: 'large-patch-files',
+            message: `Patch affects ${filesAffected.length} files (recommended: ≤5). Consider splitting into smaller, focused patches.`,
+            severity: 'warning',
+        });
+    }
+    if (lineCount > 300) {
+        issues.push({
+            file: '(patch)',
+            check: 'large-patch-lines',
+            message: `Patch is ${lineCount} lines (recommended: ≤300). Consider splitting into smaller, focused patches.`,
+            severity: 'warning',
+        });
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Modified file header lint
+// ---------------------------------------------------------------------------
+/**
+ * Checks that modified (non-new) files with a supported extension still
+ * start with a recognized license header.
+ *
+ * @param repoDir - Engine root directory
+ * @param affectedFiles - All files affected by the patch
+ * @param newFiles - Set of newly created files (excluded from this check)
+ * @returns Warning-level lint issues for files missing any recognized header
+ */
+export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles) {
+    const issues = [];
+    for (const file of affectedFiles) {
+        if (newFiles.has(file))
+            continue;
+        const style = commentStyleForFile(file);
+        if (!style)
+            continue;
+        const filePath = join(repoDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const content = await readText(filePath);
+        if (!hasAnyLicenseHeader(content, style)) {
+            issues.push({
+                file,
+                check: 'modified-file-missing-header',
+                message: 'Modified upstream file appears to be missing a recognized license header.',
+                severity: 'warning',
+            });
+        }
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Runs all patch lint checks and returns combined issues.
+ *
+ * @param repoDir - Absolute path to the engine directory
+ * @param affectedFiles - File paths (relative to repoDir) affected by the patch
+ * @param diffContent - Raw unified diff string
+ * @param config - Project configuration
+ * @returns Array of all lint issues found
+ */
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config) {
+    const newFiles = detectNewFilesInDiff(diffContent);
+    const lineCount = diffContent.split('\n').length;
+    const [cssIssues, headerIssues, jsIssues, modifiedHeaderIssues] = await Promise.all([
+        lintPatchedCss(repoDir, affectedFiles),
+        lintNewFileHeaders(repoDir, [...newFiles], config),
+        lintPatchedJs(repoDir, affectedFiles, newFiles, config),
+        lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),
+    ]);
+    const modCommentIssues = lintModificationComments(diffContent, config);
+    const sizeIssues = lintPatchSize(affectedFiles, lineCount);
+    return [
+        ...sizeIssues,
+        ...cssIssues,
+        ...headerIssues,
+        ...modifiedHeaderIssues,
+        ...jsIssues,
+        ...modCommentIssues,
+    ];
+}
+//# sourceMappingURL=patch-lint.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * Filesystem-based lock for serializing patch directory mutations.
+ */
+/**
+ * Runs a patch directory mutation while holding an exclusive filesystem lock.
+ * This serializes filename allocation and manifest writes across parallel exports.
+ */
+export declare function withPatchDirectoryLock<T>(patchesDir: string, operation: () => Promise<T>): Promise<T>;

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

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Filesystem-based lock for serializing patch directory mutations.
+ */
+import { join } from 'node:path';
+import { PatchError } from '../errors/patch.js';
+import { toError } from '../utils/errors.js';
+import { withFileLock } from './file-lock.js';
+const PATCH_DIRECTORY_LOCK = '.fireforge-patches.lock';
+/**
+ * Runs a patch directory mutation while holding an exclusive filesystem lock.
+ * This serializes filename allocation and manifest writes across parallel exports.
+ */
+export async function withPatchDirectoryLock(patchesDir, operation) {
+    const lockDir = join(patchesDir, PATCH_DIRECTORY_LOCK);
+    return withFileLock(lockDir, operation, {
+        onTimeoutMessage: `Timed out waiting for another patch export to finish in ${patchesDir}.\n` +
+            `If no other fireforge process is running, the lock may be stale. ` +
+            `Remove it manually:\n  rm -rf "${lockDir}"`,
+        onStaleLockMessage: (ageMs) => `Removing stale patch lock (age: ${Math.round(ageMs / 1000)}s). ` +
+            'A previous fireforge process may have crashed.',
+    }).catch((error) => {
+        if (error instanceof PatchError) {
+            throw error;
+        }
+        throw new PatchError(toError(error).message);
+    });
+}
+//# sourceMappingURL=patch-lock.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Manifest consistency checks and rebuild/recovery operations.
+ */
+import type { PatchesManifest } from '../types/commands/index.js';
+/** Consistency issue codes for manifest validation. */
+export interface PatchManifestConsistencyIssue {
+    code: 'manifest-invalid' | 'manifest-missing' | 'missing-patch-file' | 'untracked-patch-file' | 'files-affected-mismatch' | 'duplicate-manifest-entry';
+    filename: string;
+    message: string;
+}
+/**
+ * Validates that patches.json and the patch directory describe the same patch set.
+ * @param patchesDir - Path to the patches directory
+ * @returns Consistency issues between manifest metadata and on-disk patch files
+ */
+export declare function validatePatchesManifestConsistency(patchesDir: string): Promise<PatchManifestConsistencyIssue[]>;
+/**
+ * Rebuilds patches.json from the patch files currently present on disk.
+ * Existing metadata is preserved when possible; missing entries are recovered
+ * from filename structure, patch contents, and file mtimes.
+ * @param patchesDir - Path to the patches directory
+ * @param fallbackSourceEsrVersion - ESR version to use for recovered entries
+ */
+export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string): Promise<PatchesManifest>;

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

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Manifest consistency checks and rebuild/recovery operations.
+ */
+import { stat } from 'node:fs/promises';
+import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
+import { loadPatchesManifestState, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
+import { inferPatchMetadataFromFilename } from './patch-manifest-validate.js';
+/**
+ * Validates that patches.json and the patch directory describe the same patch set.
+ * @param patchesDir - Path to the patches directory
+ * @returns Consistency issues between manifest metadata and on-disk patch files
+ */
+export async function validatePatchesManifestConsistency(patchesDir) {
+    const manifestState = await loadPatchesManifestState(patchesDir);
+    const patches = await discoverPatches(patchesDir);
+    const issues = [];
+    if (manifestState.parseError) {
+        issues.push({
+            code: 'manifest-invalid',
+            filename: PATCHES_MANIFEST,
+            message: `patches.json exists but could not be parsed: ${manifestState.parseError.message}`,
+        });
+        return issues;
+    }
+    if (!manifestState.exists) {
+        if (patches.length > 0) {
+            issues.push({
+                code: 'manifest-missing',
+                filename: PATCHES_MANIFEST,
+                message: `patches.json is missing while ${patches.length} patch file(s) exist.`,
+            });
+        }
+        return issues;
+    }
+    const manifest = manifestState.manifest;
+    if (!manifest) {
+        return issues;
+    }
+    const patchByFilename = new Map(patches.map((patch) => [patch.filename, patch]));
+    const seenManifestEntries = new Set();
+    for (const metadata of manifest.patches) {
+        if (seenManifestEntries.has(metadata.filename)) {
+            issues.push({
+                code: 'duplicate-manifest-entry',
+                filename: metadata.filename,
+                message: `patches.json contains duplicate metadata entries for ${metadata.filename}.`,
+            });
+            continue;
+        }
+        seenManifestEntries.add(metadata.filename);
+        const patch = patchByFilename.get(metadata.filename);
+        if (!patch) {
+            issues.push({
+                code: 'missing-patch-file',
+                filename: metadata.filename,
+                message: `${metadata.filename} is listed in patches.json but the patch file is missing.`,
+            });
+            continue;
+        }
+        const declaredFiles = normalizeFiles(metadata.filesAffected);
+        const actualFiles = normalizeFiles(await getAllTargetFilesFromPatch(patch.path));
+        if (!sameStringArray(declaredFiles, actualFiles)) {
+            issues.push({
+                code: 'files-affected-mismatch',
+                filename: metadata.filename,
+                message: `${metadata.filename} declares [${declaredFiles.join(', ')}] in patches.json ` +
+                    `but the patch file targets [${actualFiles.join(', ')}].`,
+            });
+        }
+        patchByFilename.delete(metadata.filename);
+    }
+    for (const orphanPatch of patchByFilename.values()) {
+        issues.push({
+            code: 'untracked-patch-file',
+            filename: orphanPatch.filename,
+            message: `${orphanPatch.filename} exists on disk but is not tracked in patches.json.`,
+        });
+    }
+    return issues;
+}
+/**
+ * Rebuilds patches.json from the patch files currently present on disk.
+ * Existing metadata is preserved when possible; missing entries are recovered
+ * from filename structure, patch contents, and file mtimes.
+ * @param patchesDir - Path to the patches directory
+ * @param fallbackSourceEsrVersion - ESR version to use for recovered entries
+ */
+export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion) {
+    const manifestState = await loadPatchesManifestState(patchesDir);
+    const existingEntries = new Map();
+    if (manifestState.manifest) {
+        for (const entry of manifestState.manifest.patches) {
+            existingEntries.set(entry.filename, entry);
+        }
+    }
+    const patches = await discoverPatches(patchesDir);
+    const rebuiltPatches = [];
+    const highestFiniteOrder = patches.reduce((highest, patch) => {
+        return Number.isFinite(patch.order) ? Math.max(highest, patch.order) : highest;
+    }, 0);
+    let nextRecoveredOrder = highestFiniteOrder + 1;
+    for (const patch of patches) {
+        const existing = existingEntries.get(patch.filename);
+        const filesAffected = normalizeFiles(await getAllTargetFilesFromPatch(patch.path));
+        const patchStats = await stat(patch.path);
+        const inferred = inferPatchMetadataFromFilename(patch.filename);
+        const recoveredOrder = Number.isFinite(patch.order) ? patch.order : nextRecoveredOrder++;
+        rebuiltPatches.push({
+            filename: patch.filename,
+            order: recoveredOrder,
+            category: existing?.category ?? inferred.category,
+            name: existing?.name ?? inferred.name,
+            description: existing?.description ??
+                `Recovered manifest entry for ${patch.filename}. Review description and ESR version.`,
+            createdAt: existing?.createdAt ?? new Date(patchStats.mtimeMs).toISOString(),
+            sourceEsrVersion: existing?.sourceEsrVersion ?? fallbackSourceEsrVersion,
+            filesAffected,
+        });
+    }
+    rebuiltPatches.sort((left, right) => left.order - right.order || left.filename.localeCompare(right.filename));
+    const rebuiltManifest = {
+        version: 1,
+        patches: rebuiltPatches,
+    };
+    await savePatchesManifest(patchesDir, rebuiltManifest);
+    return rebuiltManifest;
+}
+function normalizeFiles(files) {
+    return Array.from(new Set(files)).sort((left, right) => left.localeCompare(right));
+}
+function sameStringArray(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+//# sourceMappingURL=patch-manifest-consistency.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Manifest I/O: load, save, and add operations for patches.json.
+ */
+import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+/** Filename for the patches manifest */
+export declare const PATCHES_MANIFEST = "patches.json";
+/** Internal state returned by loadPatchesManifestState. */
+export interface LoadedManifestState {
+    exists: boolean;
+    manifest: PatchesManifest | null;
+    parseError: Error | undefined;
+}
+/**
+ * Loads and validates the patches manifest, returning full state information.
+ * @param patchesDir - Path to the patches directory
+ */
+export declare function loadPatchesManifestState(patchesDir: string): Promise<LoadedManifestState>;
+/**
+ * Loads the patches manifest if it exists.
+ * @param patchesDir - Path to the patches directory
+ * @returns PatchesManifest or null if not found
+ */
+export declare function loadPatchesManifest(patchesDir: string): Promise<PatchesManifest | null>;
+/**
+ * Saves the patches manifest.
+ * @param patchesDir - Path to the patches directory
+ * @param manifest - Manifest to save
+ */
+export declare function savePatchesManifest(patchesDir: string, manifest: PatchesManifest): Promise<void>;
+/**
+ * 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 declare function addPatchToManifest(patchesDir: string, metadata: PatchMetadata, removeFilenames?: string[]): Promise<void>;