@hominis/fireforge 0.10.1 → 0.11.0

package/dist/src/core/furnace-registration-remove.js

@@ -1,16 +1,187 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Removal of custom element registrations from customElements.js.
- * Supports three removal strategies: standalone callback, single-line array, multi-line array.
+ *
+ * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
+ * locate and delete registration entries. The earlier implementation walked
+ * the file line-by-line with a 20-line scan bound for bracket matching, which
+ * only worked against Firefox's stock formatting and silently failed on any
+ * hand-reformatted customElements.js. AST-based bracket matching is format-
+ * agnostic by construction.
+ *
+ * Contract:
+ * - Idempotent: if the tag is not registered, the file is left unchanged.
+ * - Non-destructive on parse failure: if customElements.js cannot be parsed,
+ *   the file is left untouched rather than fall through to a line-based
+ *   heuristic that could delete the wrong range.
+ * - Two registration shapes are recognised:
+ *     (A) Standalone statement:
+ *           customElements.setElementCreationCallback("tag", ...);
+ *     (B) Entry inside a `for (... of [ ... ])` registration array:
+ *           ["tag", "chrome://..."]
+ *   Both are deleted together with any trailing comma and newline so the
+ *   resulting file is still valid JavaScript.
  */
 import { join } from 'node:path';
+import MagicString from 'magic-string';
 import { pathExists, readText, writeText } from '../utils/fs.js';
+import { parseScript, walkAST } from './ast-utils.js';
 import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
+/**
+ * Expands `[start, end)` to consume a trailing comma and any whitespace up
+ * to (and including) the next newline. This keeps the surrounding file
+ * layout stable: deleting a list entry should not leave a dangling comma
+ * behind, and deleting an expression statement should not leave a blank
+ * line where the statement used to be.
+ */
+function expandRemovalRange(content, start, end) {
+    let expandedEnd = end;
+    // Walk past horizontal whitespace so a trailing comma is reachable even
+    // when the source has `[...]  ,` or similar.
+    while (expandedEnd < content.length &&
+        (content[expandedEnd] === ' ' || content[expandedEnd] === '\t')) {
+        expandedEnd++;
+    }
+    if (content[expandedEnd] === ',') {
+        expandedEnd++;
+    }
+    else if (content[expandedEnd] === ';') {
+        expandedEnd++;
+    }
+    // Consume a trailing inline comment up to end-of-line so we do not leave
+    // the comment marooned on its own line. A leading inline comment is left
+    // alone — it may belong to the next entry.
+    while (expandedEnd < content.length &&
+        (content[expandedEnd] === ' ' || content[expandedEnd] === '\t')) {
+        expandedEnd++;
+    }
+    if (content[expandedEnd] === '/' && content[expandedEnd + 1] === '/') {
+        while (expandedEnd < content.length && content[expandedEnd] !== '\n') {
+            expandedEnd++;
+        }
+    }
+    if (content[expandedEnd] === '\n') {
+        expandedEnd++;
+    }
+    // Also consume leading whitespace on the line the removal starts on, so
+    // indentation does not survive as a blank-looking line.
+    let expandedStart = start;
+    while (expandedStart > 0) {
+        const prev = content[expandedStart - 1];
+        if (prev === ' ' || prev === '\t') {
+            expandedStart--;
+            continue;
+        }
+        break;
+    }
+    // If the removal now starts at the beginning of a line and the preceding
+    // line is blank, consume that blank line as well. This matches the older
+    // line-based implementation's "eat one leading blank" behaviour so that
+    // removing a callback block from between two blank-line-separated
+    // sections does not leave a doubled-up gap behind.
+    if (expandedStart > 0 &&
+        content[expandedStart - 1] === '\n' &&
+        expandedStart >= 2 &&
+        content[expandedStart - 2] === '\n') {
+        expandedStart--;
+    }
+    return { start: expandedStart, end: expandedEnd };
+}
+/**
+ * Returns true if `node` represents a `[tag, module]` entry inside a
+ * registration array — i.e. an `ArrayExpression` whose first element is a
+ * string literal equal to `tagName`. Callers still have to verify the
+ * parent is the outer registration array so we do not accidentally delete
+ * an arbitrary user-owned `["moz-card", ...]` literal elsewhere in the file.
+ */
+function isEntryArrayFor(node, tagName) {
+    if (!node || node.type !== 'ArrayExpression')
+        return false;
+    const [first] = node.elements;
+    if (!first || first.type !== 'Literal')
+        return false;
+    const literal = first;
+    return literal.value === tagName;
+}
+/**
+ * Returns true if `call` is `customElements.setElementCreationCallback(tagName, ...)`
+ * (optionally prefixed with `lazy.` or similar member chain). We only match
+ * the property name rather than the full callee chain so unusual-but-valid
+ * receivers (`lazy.customElements…`, `this.customElements…`) still count.
+ */
+function isStandaloneCallbackCallFor(call, tagName) {
+    if (call.callee.type !== 'MemberExpression')
+        return false;
+    const prop = call.callee.property;
+    if (prop.type !== 'Identifier' || prop.name !== 'setElementCreationCallback')
+        return false;
+    const [tagArg] = call.arguments;
+    if (!tagArg || tagArg.type !== 'Literal')
+        return false;
+    return tagArg.value === tagName;
+}
+/**
+ * Walks the AST and collects every removal range for `tagName`. Ancestor
+ * tracking lets us tell an "entry" array from a random `["moz-foo", ...]`
+ * literal (only direct children of the outer registration `ArrayExpression`
+ * are entries) and lets us lift a `setElementCreationCallback` call up to
+ * its enclosing statement.
+ */
+function collectRemovalRanges(ast, content, tagName) {
+    const ranges = [];
+    const ancestors = [];
+    walkAST(ast, {
+        enter(node) {
+            // Entry array: [tag, module] inside the outer for-of array literal.
+            // The immediate parent must be an ArrayExpression (the registration
+            // list) whose own grandparent is the `for (...) of <array>` loop.
+            if (node.type === 'ArrayExpression' && isEntryArrayFor(node, tagName)) {
+                const parent = ancestors[ancestors.length - 1];
+                const grandparent = ancestors[ancestors.length - 2];
+                if (parent &&
+                    parent.type === 'ArrayExpression' &&
+                    grandparent &&
+                    grandparent.type === 'ForOfStatement') {
+                    ranges.push(expandRemovalRange(content, node.start, node.end));
+                }
+            }
+            // Standalone call: customElements.setElementCreationCallback(tag, …)
+            if (node.type === 'CallExpression') {
+                const call = node;
+                if (isStandaloneCallbackCallFor(call, tagName)) {
+                    // Find the enclosing statement so we can delete `call(...);` as
+                    // a unit, not just the call expression body.
+                    let enclosing = null;
+                    for (let i = ancestors.length - 1; i >= 0; i--) {
+                        const ancestor = ancestors[i];
+                        if (!ancestor)
+                            continue;
+                        if (ancestor.type === 'ExpressionStatement' ||
+                            ancestor.type === 'VariableDeclaration') {
+                            enclosing = ancestor;
+                            break;
+                        }
+                    }
+                    const target = enclosing ?? call;
+                    ranges.push(expandRemovalRange(content, target.start, target.end));
+                }
+            }
+            ancestors.push(node);
+        },
+        leave() {
+            ancestors.pop();
+        },
+    });
+    return ranges;
+}
 /**
  * Removes a custom element registration from customElements.js.
  *
- * This operation is idempotent — if the tag is not registered or the file does
- * not exist, nothing happens.
+ * This operation is idempotent — if the tag is not registered or the file
+ * does not exist, nothing happens. If the file exists but cannot be parsed,
+ * the file is left unchanged rather than fall back to a line-based
+ * heuristic; a corrupted customElements.js is a doctor problem, not
+ * something `furnace remove` should "helpfully" edit around.
  *
  * @param engineDir - Path to the Firefox engine source root
  * @param tagName - Custom element tag name to remove
@@ -20,70 +191,33 @@ export async function removeCustomElementRegistration(engineDir, tagName) {
     if (!(await pathExists(filePath))) {
         return;
     }
-    let content = await readText(filePath);
-    const lines = content.split('\n');
-    // Strategy 1: Remove standalone callback block (setElementCreationCallback("tagName" …))
-    const callbackLine = lines.findIndex((l) => l.includes(`setElementCreationCallback("${tagName}"`));
-    if (callbackLine !== -1) {
-        let endLine = callbackLine;
-        for (let i = callbackLine + 1; i < lines.length; i++) {
-            const line = lines[i];
-            if (line === undefined)
-                continue;
-            if (/^\s*\}\);/.test(line)) {
-                endLine = i;
-                break;
-            }
-        }
-        let startLine = callbackLine;
-        const precedingLine = lines[startLine - 1];
-        if (startLine > 0 && precedingLine !== undefined && precedingLine.trim() === '') {
-            startLine--;
-        }
-        lines.splice(startLine, endLine - startLine + 1);
-        content = lines.join('\n');
-        await writeText(filePath, content);
+    const content = await readText(filePath);
+    // Cheap pre-check: if the tag literal never appears in the file there is
+    // nothing to remove and we avoid the cost of parsing a large file on the
+    // hot path of a no-op remove.
+    if (!content.includes(`"${tagName}"`) && !content.includes(`'${tagName}'`)) {
         return;
     }
-    // Strategy 2: Remove single-line array entry  ["tagName", "..."],
-    const singleLineIdx = lines.findIndex((l) => new RegExp(`^\\s*\\["${tagName}",\\s*"[^"]*"\\],?\\s*$`).test(l));
-    if (singleLineIdx !== -1) {
-        lines.splice(singleLineIdx, 1);
-        content = lines.join('\n');
-        await writeText(filePath, content);
+    let ast;
+    try {
+        ast = parseScript(content);
+    }
+    catch {
         return;
     }
-    // Strategy 3: Remove multi-line array entry where "tagName", is on its own line
-    const multiLineTagIdx = lines.findIndex((l) => new RegExp(`^\\s*"${tagName}",\\s*$`).test(l));
-    if (multiLineTagIdx !== -1) {
-        // Scan backwards from the tag line to find the opening [ (bounded to 20 lines)
-        let startLine = multiLineTagIdx;
-        const scanLimit = Math.max(0, multiLineTagIdx - 20);
-        for (let i = multiLineTagIdx - 1; i >= scanLimit; i--) {
-            const line = lines[i];
-            if (line !== undefined && /^\s*\[$/.test(line)) {
-                startLine = i;
-                break;
-            }
-        }
-        const openIndent = (lines[startLine] ?? '').match(/^(\s*)/)?.[1]?.length ?? 0;
-        // Scan forwards from the tag line to find the closing ],
-        let endLine = multiLineTagIdx;
-        for (let i = multiLineTagIdx + 1; i < lines.length; i++) {
-            const line = lines[i];
-            if (line !== undefined && /^\s*\],?\s*$/.test(line)) {
-                const closeIndent = line.match(/^(\s*)/)?.[1]?.length ?? 0;
-                if (closeIndent === openIndent) {
-                    endLine = i;
-                    break;
-                }
-            }
-        }
-        lines.splice(startLine, endLine - startLine + 1);
-        content = lines.join('\n');
-        await writeText(filePath, content);
+    const ranges = collectRemovalRanges(ast, content, tagName);
+    if (ranges.length === 0) {
         return;
     }
-    // Tag not found in any form — idempotent no-op
+    // Apply all removals in a single MagicString pass. MagicString tracks
+    // original offsets so the ranges do not need to be sorted or reversed.
+    const ms = new MagicString(content);
+    for (const range of ranges) {
+        ms.remove(range.start, range.end);
+    }
+    const next = ms.toString();
+    if (next !== content) {
+        await writeText(filePath, next);
+    }
 }
 //# sourceMappingURL=furnace-registration-remove.js.map

package/dist/src/core/furnace-registration-validate.d.ts

@@ -2,8 +2,20 @@
  * Shared validation for furnace custom element registration placement.
  * Used after both AST and legacy code paths to avoid duplicating logic.
  */
-/** Regex for valid custom element tag names. */
+/**
+ * Regex for valid custom element tag names. A valid name is lowercase, starts
+ * with a letter, and contains one or more hyphen-separated groups where each
+ * group is a non-empty alphanumeric run. Consecutive hyphens and trailing
+ * hyphens are both rejected. Kept in sync with the HTML custom element spec
+ * requirement that a name contain at least one hyphen.
+ *
+ * A single shared constant is used by every furnace authoring path
+ * (`furnace create`, `furnace override`, and the AST registration helper) so
+ * that a name accepted by one command cannot be rejected by another.
+ */
 export declare const CUSTOM_ELEMENT_TAG_PATTERN: RegExp;
+/** Human-readable description of the tag-name rules, for CLI error messages. */
+export declare const CUSTOM_ELEMENT_TAG_RULES = "must be lowercase, start with a letter, and use hyphens to separate non-empty alphanumeric groups (e.g., \"my-widget\")";
 /**
  * Validates that a tag name conforms to custom element naming requirements.
  * @throws FurnaceError if the tag name is invalid

package/dist/src/core/furnace-registration-validate.js

@@ -4,15 +4,27 @@
  * Used after both AST and legacy code paths to avoid duplicating logic.
  */
 import { FurnaceError } from '../errors/furnace.js';
-/** Regex for valid custom element tag names. */
-export const CUSTOM_ELEMENT_TAG_PATTERN = /^[a-z][a-z0-9]*-[a-z0-9-]*$/;
+/**
+ * Regex for valid custom element tag names. A valid name is lowercase, starts
+ * with a letter, and contains one or more hyphen-separated groups where each
+ * group is a non-empty alphanumeric run. Consecutive hyphens and trailing
+ * hyphens are both rejected. Kept in sync with the HTML custom element spec
+ * requirement that a name contain at least one hyphen.
+ *
+ * A single shared constant is used by every furnace authoring path
+ * (`furnace create`, `furnace override`, and the AST registration helper) so
+ * that a name accepted by one command cannot be rejected by another.
+ */
+export const CUSTOM_ELEMENT_TAG_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
+/** Human-readable description of the tag-name rules, for CLI error messages. */
+export const CUSTOM_ELEMENT_TAG_RULES = 'must be lowercase, start with a letter, and use hyphens to separate non-empty alphanumeric groups (e.g., "my-widget")';
 /**
  * Validates that a tag name conforms to custom element naming requirements.
  * @throws FurnaceError if the tag name is invalid
  */
 export function validateTagName(tagName) {
     if (!CUSTOM_ELEMENT_TAG_PATTERN.test(tagName)) {
-        throw new FurnaceError(`Invalid tag name "${tagName}": must contain a hyphen and match /^[a-z][a-z0-9]*-[a-z0-9-]*$/`, tagName);
+        throw new FurnaceError(`Invalid tag name "${tagName}": ${CUSTOM_ELEMENT_TAG_RULES}`, tagName);
     }
 }
 /**

package/dist/src/core/furnace-registration.d.ts

@@ -1,16 +1,34 @@
 export { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
-export { addCustomElementRegistration, removeCustomElementRegistration, } from './furnace-registration-ast.js';
+export { addCustomElementRegistration, removeCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
 /**
  * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
  * component's files.
  *
- * Entry format (3-space indent, spaces not tabs):
+ * ## Assumed jar.mn format
+ *
+ * Firefox's `toolkit/content/jar.mn` uses a stable format that has not
+ * changed in the custom-element era (Firefox 90+). The entry format is:
+ *
  * ```
  *    content/global/elements/{file}  (widgets/{tagName}/{file})
  * ```
  *
- * New entries are inserted in alphabetical order relative to existing
- * `content/global/elements/` entries. The operation is idempotent.
+ * - **Indent**: detected dynamically from the nearest existing
+ *   `content/global/elements/` line. Falls back to 3 spaces when no
+ *   reference line exists.
+ * - **Insertion point**: identified by existing lines matching the regex
+ *   `^\s+content\/global\/elements\/([^.]+)\.` — new entries are inserted
+ *   in alphabetical order relative to these.
+ * - **Fallback**: if no `content/global/elements/` line exists (empty
+ *   project), looks for any `content/global/` line and inserts after it.
+ * - **Idempotency**: entries already present (checked by exact path match
+ *   on `content/global/elements/{file}` with a trailing whitespace or
+ *   end-of-line boundary) are skipped.
+ *
+ * If Firefox upstream changes the jar.mn section ordering or switches to a
+ * different resource registration mechanism, the preflight validation in
+ * `validateJarMnEntries` will catch the format mismatch before any writes
+ * occur.
  *
  * @param engineDir - Path to the Firefox engine source root
  * @param tagName - Custom element tag name
@@ -27,3 +45,8 @@ export declare function addJarMnEntries(engineDir: string, tagName: string, file
  * @param tagName - Custom element tag name whose entries should be removed
  */
 export declare function removeJarMnEntries(engineDir: string, tagName: string): Promise<void>;
+/**
+ * Validates that jar.mn entries *could* be added without writing anything.
+ * Used by dry-run to surface structural problems early.
+ */
+export declare function validateJarMnEntries(engineDir: string, tagName: string, files: string[]): Promise<void>;

package/dist/src/core/furnace-registration.js

@@ -2,21 +2,57 @@
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
+/** Escapes special regex characters in a literal string. */
+function escapeForRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Detects the indentation used by existing `content/global/elements/` lines
+ * in jar.mn. Falls back to 3 spaces (the historical Firefox convention) when
+ * no reference line is found.
+ */
+function detectJarMnIndent(lines) {
+    for (const line of lines) {
+        const match = /^(\s+)content\/global\/elements\//.exec(line);
+        if (match?.[1]) {
+            return match[1];
+        }
+    }
+    return '   ';
+}
 // Re-export everything from the AST module so existing imports keep working
 export { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
-export { addCustomElementRegistration, removeCustomElementRegistration, } from './furnace-registration-ast.js';
+export { addCustomElementRegistration, removeCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
 import { JAR_MN } from './furnace-constants.js';
 /**
  * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
  * component's files.
  *
- * Entry format (3-space indent, spaces not tabs):
+ * ## Assumed jar.mn format
+ *
+ * Firefox's `toolkit/content/jar.mn` uses a stable format that has not
+ * changed in the custom-element era (Firefox 90+). The entry format is:
+ *
  * ```
  *    content/global/elements/{file}  (widgets/{tagName}/{file})
  * ```
  *
- * New entries are inserted in alphabetical order relative to existing
- * `content/global/elements/` entries. The operation is idempotent.
+ * - **Indent**: detected dynamically from the nearest existing
+ *   `content/global/elements/` line. Falls back to 3 spaces when no
+ *   reference line exists.
+ * - **Insertion point**: identified by existing lines matching the regex
+ *   `^\s+content\/global\/elements\/([^.]+)\.` — new entries are inserted
+ *   in alphabetical order relative to these.
+ * - **Fallback**: if no `content/global/elements/` line exists (empty
+ *   project), looks for any `content/global/` line and inserts after it.
+ * - **Idempotency**: entries already present (checked by exact path match
+ *   on `content/global/elements/{file}` with a trailing whitespace or
+ *   end-of-line boundary) are skipped.
+ *
+ * If Firefox upstream changes the jar.mn section ordering or switches to a
+ * different resource registration mechanism, the preflight validation in
+ * `validateJarMnEntries` will catch the format mismatch before any writes
+ * occur.
  *
  * @param engineDir - Path to the Firefox engine source root
  * @param tagName - Custom element tag name
@@ -29,12 +65,14 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     }
     let content = await readText(filePath);
     const lines = content.split('\n');
-    // Filter to files not already registered
-    const newFiles = files.filter((f) => !content.includes(`content/global/elements/${f}`));
+    // Filter to files not already registered. Use a word-boundary-aware
+    // check so that "moz-card.css" does not match "moz-card-group.css".
+    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeForRegex(f)}(?:\\s|$)`, 'm').test(content));
     if (newFiles.length === 0)
         return;
-    // Build new entry lines
-    const newEntries = newFiles.map((f) => `   content/global/elements/${f}  (widgets/${tagName}/${f})`);
+    // Build new entry lines using the indent detected from existing entries.
+    const indent = detectJarMnIndent(lines);
+    const newEntries = newFiles.map((f) => `${indent}content/global/elements/${f}  (widgets/${tagName}/${f})`);
     // Find insertion point among existing content/global/elements/ lines
     const elementLinePattern = /^\s+content\/global\/elements\/([^.]+)\./;
     let insertIndex = -1;
@@ -64,7 +102,11 @@ export async function addJarMnEntries(engineDir, tagName, files) {
         }
     }
     if (insertIndex === -1) {
-        throw new FurnaceError('Could not find insertion point in jar.mn for element entries', tagName);
+        const nonEmpty = lines.some((line) => line.trim().length > 0);
+        if (!nonEmpty) {
+            throw new FurnaceError('jar.mn is empty or contains only whitespace. It may be malformed — verify the engine was downloaded correctly.', tagName);
+        }
+        throw new FurnaceError('Could not find a content/global/ section in jar.mn for element entries. The file may be malformed.', tagName);
     }
     lines.splice(insertIndex, 0, ...newEntries);
     content = lines.join('\n');
@@ -86,11 +128,51 @@ export async function removeJarMnEntries(engineDir, tagName) {
     }
     let content = await readText(filePath);
     const lines = content.split('\n');
-    const pattern = `content/global/elements/${tagName}.`;
-    const filtered = lines.filter((line) => !line.includes(pattern));
+    // Use a regex with word boundary so "moz-card" does not match "moz-card-group".
+    const pattern = new RegExp(`content/global/elements/${escapeForRegex(tagName)}\\.`);
+    const filtered = lines.filter((line) => !pattern.test(line));
     if (filtered.length === lines.length)
         return;
     content = filtered.join('\n');
     await writeText(filePath, content);
 }
+/**
+ * Validates that jar.mn entries *could* be added without writing anything.
+ * Used by dry-run to surface structural problems early.
+ */
+export async function validateJarMnEntries(engineDir, tagName, files) {
+    const filePath = join(engineDir, JAR_MN);
+    if (!(await pathExists(filePath))) {
+        throw new FurnaceError('jar.mn not found in engine', tagName);
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeForRegex(f)}(?:\\s|$)`, 'm').test(content));
+    if (newFiles.length === 0)
+        return;
+    const elementLinePattern = /^\s+content\/global\/elements\/([^.]+)\./;
+    let hasInsertionPoint = false;
+    for (const line of lines) {
+        if (elementLinePattern.test(line)) {
+            hasInsertionPoint = true;
+            break;
+        }
+    }
+    if (!hasInsertionPoint) {
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            if (line !== undefined && /^\s+content\/global\//.test(line)) {
+                hasInsertionPoint = true;
+                break;
+            }
+        }
+    }
+    if (!hasInsertionPoint) {
+        const nonEmpty = lines.some((line) => line.trim().length > 0);
+        if (!nonEmpty) {
+            throw new FurnaceError('jar.mn is empty or contains only whitespace. It may be malformed — verify the engine was downloaded correctly.', tagName);
+        }
+        throw new FurnaceError('Could not find a content/global/ section in jar.mn for element entries. The file may be malformed.', tagName);
+    }
+}
 //# sourceMappingURL=furnace-registration.js.map

package/dist/src/core/furnace-rollback.d.ts

@@ -6,11 +6,22 @@ interface FileSnapshot {
 export interface RollbackJournal {
     files: Map<string, FileSnapshot>;
     createdDirs: Set<string>;
+    /** Paths that were skipped during snapshotDir because they are symlinks. */
+    skippedSymlinks: Set<string>;
 }
 /** Creates an empty rollback journal for tracking touched files and created directories. */
 export declare function createRollbackJournal(): RollbackJournal;
 /** Records a directory that should be removed if the operation later rolls back. */
 export declare function recordCreatedDir(journal: RollbackJournal, dirPath: string): void;
+/**
+ * Recursively snapshots every file under a directory tree so a later rollback
+ * can restore deleted files. Skips symlinks to avoid following them out of the
+ * tree. The directory itself is not recorded as "created" — callers that
+ * intend to delete and restore the directory should record it explicitly.
+ *
+ * Safe to call on a missing path: it returns without recording anything.
+ */
+export declare function snapshotDir(journal: RollbackJournal, dirPath: string): Promise<void>;
 /** Snapshots a file once so rollback can restore its previous contents or absence. */
 export declare function snapshotFile(journal: RollbackJournal, filePath: string): Promise<void>;
 /** Restores all snapshotted files and removes directories created during the operation. */