@heroiclands/package-build 0.6.0 → 3.0.0

package/engine/code-fences.mjs

@@ -0,0 +1,311 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Where **code** lives in a markdown body, so a rewriter can leave it alone.
+ *
+ * A code block is verbatim: its contents are shown to the reader exactly as
+ * written. Every build-time rewriter that pattern-matches a body therefore has
+ * to know where code is — otherwise a source listing that happens to contain
+ * the rewriter's syntax is silently corrupted. Wikilink conversion met this as
+ * `[[0]]` inside a fence being turned into a link (#1505), and it depended on
+ * the surrounding literal's shape (`[[1,2],[3,4]]` survived), so the corruption
+ * looked arbitrary.
+ *
+ * Three forms are recognised, which is every form the content tree uses:
+ *
+ * - **Fenced blocks** — three or more backticks or tildes, closed by the same
+ *   character at least as long, or by the end of the document. A longer fence
+ *   contains a shorter one, so a markdown sample can quote a code sample. The
+ *   opening line, info string and all, is part of the block.
+ * - **Indented blocks** — four columns past the enclosing context, following a
+ *   blank line (an indent cannot interrupt a paragraph).
+ * - **Inline spans** — a run of backticks closed by a run of equal length,
+ *   within one paragraph.
+ *
+ * The fence syntax is the one `expandContentTables` already reads, and
+ * this module owns it now so the two can never disagree.
+ *
+ * **Known limits.** This is a scanner, not a markdown parser, and it errs
+ * towards treating something as code — a false positive leaves an author's text
+ * as written, a false negative rewrites it. List nesting is tracked only to the
+ * innermost open marker, so an indented block inside a deeply nested list may be
+ * read as list prose; a backslash-escaped backtick still counts as a span
+ * delimiter; and HTML blocks are not code (they are not verbatim in markdown
+ * either). None of these can turn code into a link — the failure this exists to
+ * prevent.
+ */
+
+/** A fence line, capturing its indent, its marker, and its info string. */
+export const FENCE_LINE = /^([ \t]*)(`{3,}|~{3,})[ \t]*([^\r\n]*)$/;
+
+/** A list item's opening line, capturing the indent and the marker itself. */
+const LIST_MARKER = /^([ \t]*)(?:[-*+]|\d{1,9}[.)])(?:[ \t]+|$)/;
+
+/** A line's leading whitespace. */
+const LEADING = /^[ \t]*/;
+
+/**
+ * The column a run of leading whitespace reaches, tabs expanded to four.
+ *
+ * @param {string} space - Leading whitespace only.
+ * @returns {number} The column the first non-space character sits at.
+ */
+function column(space) {
+    let col = 0;
+    for (const ch of space) col = ch === "\t" ? col + 4 - (col % 4) : col + 1;
+    return col;
+}
+
+/**
+ * Every code region in a markdown body, as character offsets into it.
+ *
+ * @param {string | null | undefined} markdown - The body (frontmatter already
+ *   stripped). An absent body has no code in it.
+ * @param {object} [options]
+ * @param {boolean} [options.spans=true] - Include inline code spans. Set false
+ *   to consider only block-level code.
+ * @returns {Array<{start: number, end: number}>} Non-overlapping regions, in
+ *   source order. `end` is exclusive.
+ */
+export function codeRegions(markdown, { spans = true } = {}) {
+    const src = String(markdown ?? "");
+    if (!src) return [];
+    const lines = src.split("\n");
+
+    // Where each line begins, so a region can be reported in the caller's own
+    // coordinates rather than in lines.
+    const at = [];
+    let offset = 0;
+    for (const line of lines) {
+        at.push(offset);
+        offset += line.length + 1;
+    }
+    const through = (first, last) => ({
+        start: at[first],
+        end: at[last] + lines[last].length,
+    });
+
+    const regions = [];
+    // The content column of the innermost open list item: an indented block
+    // has to clear *that*, not column zero, or every list continuation would
+    // read as code.
+    let listColumn = null;
+    // The start of the document counts as a blank line, so a body that opens
+    // with an indented sample is still code.
+    let afterBlank = true;
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+
+        const fence = FENCE_LINE.exec(line);
+        if (fence) {
+            const marker = fence[2];
+            const closer = new RegExp(
+                `^[ \\t]*${marker[0]}{${marker.length},}[ \\t]*$`,
+            );
+            let close = i + 1;
+            while (close < lines.length && !closer.test(lines[close])) close++;
+            // An unclosed fence runs to the end of the document.
+            regions.push(through(i, Math.min(close, lines.length - 1)));
+            i = close;
+            afterBlank = false;
+            continue;
+        }
+
+        if (line.trim() === "") {
+            afterBlank = true;
+            continue;
+        }
+
+        const indent = column(LEADING.exec(line)[0]);
+        const codeColumn = (listColumn ?? 0) + 4;
+        if (afterBlank && indent >= codeColumn) {
+            // The block runs to the last line still indented that far; blank
+            // lines inside it belong to it, trailing ones do not.
+            let last = i;
+            for (let j = i + 1; j < lines.length; j++) {
+                if (lines[j].trim() === "") continue;
+                if (column(LEADING.exec(lines[j])[0]) < codeColumn) break;
+                last = j;
+            }
+            regions.push(through(i, last));
+            i = last;
+            afterBlank = false;
+            continue;
+        }
+
+        const marker = LIST_MARKER.exec(line);
+        if (marker) {
+            listColumn = column(marker[0]);
+        } else if (listColumn !== null && indent < listColumn) {
+            // Prose back at the outer margin closes the list.
+            listColumn = null;
+        }
+        afterBlank = false;
+    }
+
+    if (spans) regions.push(...codeSpans(src, regions));
+    regions.sort((a, b) => a.start - b.start);
+    return regions;
+}
+
+/**
+ * The inline code spans outside the block-level regions already found.
+ *
+ * A run of _n_ backticks opens a span that the next run of exactly _n_ closes.
+ * A run with no partner is a literal backtick, and a span cannot cross a blank
+ * line — both are CommonMark's rules, and both are what an author expects when
+ * a stray backtick appears in prose.
+ *
+ * @param {string} src - The body.
+ * @param {Array<{start: number, end: number}>} blocks - Block-level regions.
+ * @returns {Array<{start: number, end: number}>} The spans, in source order.
+ */
+function codeSpans(src, blocks) {
+    const runs = [];
+    const backticks = /`+/g;
+    let run;
+    while ((run = backticks.exec(src)) !== null) {
+        if (!inside(blocks, run.index)) {
+            runs.push({ start: run.index, length: run[0].length });
+        }
+    }
+
+    const spans = [];
+    for (let i = 0; i < runs.length; i++) {
+        const open = runs[i];
+        let close = i + 1;
+        while (close < runs.length && runs[close].length !== open.length) {
+            close++;
+        }
+        if (close >= runs.length) continue; // no partner: a literal backtick
+        const end = runs[close].start + runs[close].length;
+        if (/\n[ \t]*\n/.test(src.slice(open.start, end))) continue;
+        spans.push({ start: open.start, end });
+        i = close;
+    }
+    return spans;
+}
+
+/**
+ * Is this offset inside one of the regions?
+ *
+ * @param {Array<{start: number, end: number}>} regions - Sorted regions.
+ * @param {number} offset - A character offset.
+ * @returns {boolean}
+ */
+function inside(regions, offset) {
+    for (const region of regions) {
+        if (offset < region.start) return false;
+        if (offset < region.end) return true;
+    }
+    return false;
+}
+
+/**
+ * The offset argument of a `String.prototype.replace` callback.
+ *
+ * The callback is handed `(match, ...groups, offset, source)`, plus a groups
+ * object when the pattern has named groups — so the offset is found from the
+ * end, not by counting captures the caller might change.
+ *
+ * @param {Array<unknown>} args - The callback's own arguments.
+ * @returns {number} The match's offset into the source.
+ */
+function offsetOf(args) {
+    const last = args[args.length - 1];
+    return typeof last === "string" ?
+            args[args.length - 2]
+        :   args[args.length - 3];
+}
+
+/**
+ * `String.prototype.replace`, skipping anything inside code.
+ *
+ * A match inside a code region is returned as it was written, so the block
+ * stays verbatim; the replacer is not called for it at all, which matters when
+ * it records a side effect (an unresolved link, say).
+ *
+ * @param {string} markdown - The body.
+ * @param {RegExp} pattern - A **global** pattern to rewrite.
+ * @param {(...args: Array<any>) => string} replacer - As `replace` takes.
+ * @param {object} [options] - Passed to {@link codeRegions}.
+ * @returns {string} The rewritten body.
+ */
+export function replaceOutsideCode(markdown, pattern, replacer, options) {
+    const src = String(markdown ?? "");
+    const regions = codeRegions(src, options);
+    if (regions.length === 0) return src.replace(pattern, replacer);
+    return src.replace(pattern, (...args) =>
+        inside(regions, offsetOf(args)) ? args[0] : replacer(...args),
+    );
+}
+
+/**
+ * `String.prototype.matchAll`, skipping anything inside code.
+ *
+ * @param {string} markdown - The body.
+ * @param {RegExp} pattern - A **global** pattern to search for.
+ * @param {object} [options] - Passed to {@link codeRegions}.
+ * @returns {Array<RegExpMatchArray>} The matches outside code, in source order.
+ */
+export function matchAllOutsideCode(markdown, pattern, options) {
+    const src = String(markdown ?? "");
+    const regions = codeRegions(src, options);
+    return [...src.matchAll(pattern)].filter(
+        (match) => !inside(regions, match.index),
+    );
+}
+
+/**
+ * Run `transform` over a whole Markdown body while leaving code untouched.
+ *
+ * {@link replaceOutsideCode} is the right tool when the caller has a pattern.
+ * This is for the other shape: a transform that rewrites the **whole** body — a
+ * link rewriter, a path fixer — and must simply never see code. Each code run is
+ * stashed and replaced with a `\u0000<index>\u0000` sentinel; a NUL never occurs
+ * in Markdown source, so the sentinel cannot collide with prose and survives the
+ * transform unchanged before being restored.
+ *
+ * **Which runs count as code is {@link codeRegions}' rule, not a second copy of
+ * it.** The knowledgebase build carried its own regex once, and it was weaker in
+ * two ways that both corrupted the one page whose subject *is* link syntax — so
+ * its examples were exactly the input a looser rule mangles (SoHL#1665). A
+ * single-backtick span was allowed to cross newlines, so one odd backtick paired
+ * with another paragraphs away and every span after it paired wrongly: prose was
+ * masked as code while real spans were left exposed. And only three-backtick
+ * fences were recognised, so a four-backtick example holding a three-backtick
+ * block — the documented "fences of any length" case (#1505) — leaked its
+ * contents.
+ *
+ * @param {string} body - The markdown body.
+ * @param {(masked: string) => string} transform - Applied to the masked body.
+ * @returns {string} The transformed body, with every code run restored verbatim.
+ */
+export function protectCode(body, transform) {
+    const src = String(body ?? "");
+    const stash = [];
+    let masked = "";
+    let last = 0;
+    for (const region of codeRegions(src)) {
+        const index = stash.push(src.slice(region.start, region.end)) - 1;
+        masked += src.slice(last, region.start) + `\u0000${index}\u0000`;
+        last = region.end;
+    }
+    masked += src.slice(last);
+    return transform(masked).replace(
+        /\u0000(\d+)\u0000/g,
+        (_m, i) => stash[Number(i)],
+    );
+}

package/engine/compendiums.mjs

@@ -0,0 +1,353 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Compendium pack library — compile / unpack / clean LevelDB packs.
+ *
+ * Wraps `@foundryvtt/foundryvtt-cli` over the packs a consuming repository
+ * declares:
+ *   - {@link compilePacks}: generates each pack's per-entry JSON from the
+ *     `assets/content/` Markdown into `build/packs-json/<name>/` (via
+ *     generate.mjs), then builds LevelDB from it; no committed JSON, no vault.
+ *   - {@link unpackPacks}: extracts a compiled pack back to per-entry JSON,
+ *     rebuilding folder paths.
+ *   - {@link cleanPacks}: normalizes/strips extracted JSON.
+ *
+ * **This module has no import-time side effects.** It creates no directories,
+ * reads no manifest, configures no logger, and parses no argv — every path and
+ * pack list is a parameter, defaulted from the resolved build configuration
+ * (#1508), which a caller may replace wholesale to compile another package's
+ * tree. Those side effects belong to the command
+ * line that drives it (`bin/build-compendiums.mjs`), so the library can be
+ * imported by another repository's build, or by a test, without a stray
+ * `build/` tree appearing or the shared `loglevel` singleton being
+ * reconfigured (#1507). In particular, a *module* repository ships
+ * `module.json` rather than `system.template.json`, so importing must not
+ * depend on the latter existing.
+ *
+ * @module
+ */
+
+import fs from "fs";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import log from "loglevel";
+import path from "path";
+import { compilePack, extractPack } from "@foundryvtt/foundryvtt-cli";
+import { generatePacksJson, packJsonDir } from "./generate.mjs";
+// The one slug rule — see `./content-slug.mjs`. This module carried a copy
+// that stripped only the *first* straight apostrophe (a string argument, not a
+// pattern), never a curly one, and dropped non-ASCII letters rather than
+// transliterating them: `Kûrbúl Helm` filed itself as `k-rb-l-helm`.
+import { slugify } from "./content-slug.mjs";
+import { verifyPackSceneLevels } from "./scene-levels.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+
+/* ----------------------------------------- */
+/*  Compile Packs                            */
+/* ----------------------------------------- */
+
+/**
+ * Generates each pack's per-entry JSON from `assets/content/` into
+ * `build/packs-json/<name>/`, then builds the LevelDB output from it. No
+ * committed JSON and no vault access. Destination: `<stageDest>/<name>/`.
+ *
+ * @param {object} opts
+ * @param {object} [opts.config]         The resolved build configuration, which
+ *     the two path arguments below default from. Supplying one is how a caller
+ *     compiles a package other than this repository's (#1508).
+ * @param {string[]} [opts.sourcePacks]  Every pack compiled from the content
+ *     tree, in compile order. Defaults to the configured pack directories.
+ * @param {string} [opts.stageDest]      Directory the LevelDB packs are built
+ *     into, one subdirectory per pack. Defaults to the configured stage.
+ * @param {string} [opts.packName]       Restrict the run to a single pack.
+ * @throws {Error} If pack JSON generation reported any error. Packs compiled
+ *     from incomplete or empty JSON ship blank or short compendiums, and the
+ *     omission is invisible until a player looks for content that is not there
+ *     (#1502) — so this is fatal, not a warning, and the caller is expected to
+ *     turn it into a failing exit code.
+ * @throws {Error} If a compiled pack ships a Scene that has lost its embedded
+ *     Level (#1538). Fatal for the same reason: Foundry reads a missing Level
+ *     record as "no levels" and persists that on the next world launch, so the
+ *     map image is gone before anyone notices it was ever at risk. See
+ *     {@link verifyPackSceneLevels}.
+ */
+export async function compilePacks({
+    config = loadPackConfig(),
+    sourcePacks = config.packDirectories,
+    stageDest = config.paths.stage,
+    packName,
+} = {}) {
+    const packNames = sourcePacks.filter(
+        (name) => !packName || name === packName,
+    );
+
+    // Generate the per-entry JSON from the content tree into the build-only
+    // JSON intermediate. The package-id guard runs first, inside this call,
+    // before any pack is written.
+    const errors = await generatePacksJson({ only: packName, config });
+    if (errors > 0) {
+        throw new Error(
+            `Pack JSON generation reported ${errors} error(s); refusing to ` +
+                `compile packs from incomplete output.`,
+        );
+    }
+
+    for (const name of packNames) {
+        const source = packJsonDir(name, config);
+        if (!fs.existsSync(source)) {
+            log.error(`Pack ${name}: generated JSON not found at ${source}.`);
+            continue;
+        }
+
+        const stage = path.join(stageDest, name);
+        log.info(`Pack ${name}: compiling to LevelDB at ${stage}`);
+        await compilePack(source, stage, {
+            recursive: true,
+            log: false,
+            transformEntry: cleanPackEntry,
+        });
+
+        // A Scene's map image lives on an embedded Level, stored under its own
+        // LevelDB key. Nothing in Foundry ties the two together on read: a
+        // missing Level record only warns, and the next world launch persists
+        // the emptied `levels` array — so the map is lost for good and the
+        // only symptom is a blank battlemap (#1538). Assert it on the bytes
+        // just written, which is the one place the compendium CLI's write path
+        // is observable.
+        const problems = await verifyPackSceneLevels(stage);
+        if (problems.length) {
+            throw new Error(
+                `Pack ${name}: ${problems.length} Scene/Level integrity ` +
+                    `problem(s) in the compiled pack:\n  ` +
+                    problems.join("\n  "),
+            );
+        }
+    }
+    log.info("Pack compilation complete.");
+}
+
+/* ----------------------------------------- */
+/*  Clean Packs                              */
+/* ----------------------------------------- */
+
+/**
+ * Removes unwanted flags, permissions, and other data from entries before extracting or compiling.
+ * @param {object} data                           Data for a single entry to clean.
+ * @param {object} [options={}]
+ * @param {boolean} [options.clearSourceId=true]  Should the core sourceId flag be deleted.
+ * @param {number} [options.ownership=0]          Value to reset default ownership to.
+ * @param {string} [options.lastModifiedBy]       The stamped author id. Defaults to
+ *     the configured one — the same value `buildStats` stamps, so a compiled
+ *     entry and a re-cleaned one never disagree (#1508).
+ */
+function cleanPackEntry(
+    data,
+    {
+        clearSourceId = true,
+        ownership = 0,
+        lastModifiedBy = loadPackConfig().stats.lastModifiedBy,
+    } = {},
+) {
+    if (data.ownership) data.ownership = { default: ownership };
+    if (clearSourceId) {
+        delete data._stats?.compendiumSource;
+        delete data.flags?.core?.sourceId;
+    }
+    delete data.flags?.importSource;
+    delete data.flags?.exportSource;
+    if (data._stats?.lastModifiedBy)
+        data._stats.lastModifiedBy = lastModifiedBy;
+
+    // Remove empty entries in flags
+    if (!data.flags) data.flags = {};
+    Object.entries(data.flags).forEach(([key, contents]) => {
+        if (Object.keys(contents).length === 0) delete data.flags[key];
+    });
+
+    if (data.effects)
+        data.effects.forEach((i) =>
+            cleanPackEntry(i, { clearSourceId: false }),
+        );
+    if (data.items)
+        data.items.forEach((i) => cleanPackEntry(i, { clearSourceId: false }));
+    if (data.pages)
+        data.pages.forEach((i) => cleanPackEntry(i, { ownership: -1 }));
+    if (data.system?.description)
+        data.system.description = cleanString(data.system.description);
+    if (data.system?.biography)
+        data.system.biography = cleanString(data.system.biography);
+    if (data.system?.textReference)
+        data.system.textReference = cleanString(data.system.textReference);
+    if (data.system?.notes) data.system.notes = cleanString(data.system.notes);
+    if (data.label) data.label = cleanString(data.label);
+    if (data.name) data.name = cleanString(data.name);
+}
+
+/**
+ * Removes invisible whitespace characters and normalizes single- and double-quotes.
+ * @param {string} str  The string to be cleaned.
+ * @returns {string}    The cleaned string.
+ */
+function cleanString(str) {
+    return str
+        .replace(/\u2060/gu, "")
+        .replace(/[‘’]/gu, "'")
+        .replace(/[“”]/gu, '"');
+}
+
+/**
+ * Cleans and formats source JSON files, removing unnecessary permissions and flags and adding the proper spacing.
+ * @param {object} opts
+ * @param {object} [opts.config]       The resolved build configuration, which
+ *                                     `packDest` defaults from.
+ * @param {string} [opts.packDest]     Directory holding the extracted per-entry
+ *                                     JSON, one subdirectory per pack.
+ * @param {string} [opts.packName]     Name of pack to clean. If none provided, all packs will be cleaned.
+ * @param {string} [opts.entryName]    Name of a specific entry to clean.
+ *
+ * - `npm run build:clean` - Clean all source JSON files.
+ * - `npm run build:clean -- classes` - Only clean the source files for the specified compendium.
+ * - `npm run build:clean -- classes Barbarian` - Only clean a single item from the specified compendium.
+ */
+export async function cleanPacks({
+    config = loadPackConfig(),
+    packDest = config.paths.unpack,
+    packName,
+    entryName,
+} = {}) {
+    entryName = entryName?.toLowerCase();
+
+    const folders = fs
+        .readdirSync(packDest, { withFileTypes: true })
+        .filter(
+            (file) =>
+                file.isDirectory() && (!packName || packName === file.name),
+        );
+
+    /**
+     * Walk through directories to find JSON files.
+     * @param {string} directoryPath
+     * @yields {string}
+     */
+    async function* _walkDir(directoryPath) {
+        const directory = await readdir(directoryPath, { withFileTypes: true });
+        for (const entry of directory) {
+            const entryPath = path.join(directoryPath, entry.name);
+            if (path.extname(entry.name) === ".json") yield entryPath;
+        }
+    }
+
+    for (const folder of folders) {
+        log.info(`Cleaning pack ${folder.name}`);
+        for await (const src of _walkDir(path.join(packDest, folder.name))) {
+            const json = JSON.parse(await readFile(src, { encoding: "utf8" }));
+            if (entryName && entryName !== json.name.toLowerCase()) continue;
+            if (!json._id || !json._key) {
+                log.info(
+                    `Failed to clean \x1b[31m${src}\x1b[0m, must have _id and _key.`,
+                );
+                continue;
+            }
+            cleanPackEntry(json);
+            fs.rmSync(src, { force: true });
+            writeFile(src, `${JSON.stringify(json, null, 2)}\n`, {
+                mode: 0o664,
+            });
+        }
+    }
+}
+
+/* ----------------------------------------- */
+/*  Unpack Packs                             */
+/* ----------------------------------------- */
+
+/**
+ * Extracts compiled LevelDB packs back to per-entry JSON, rebuilding the folder
+ * hierarchy as directories.
+ *
+ * @param {object} opts
+ * @param {Array<{name: string}>} opts.packs  The packs the shipped Foundry
+ *     package declares — the manifest's `packs` array.
+ * @param {object} [opts.config]       The resolved build configuration, which
+ *                                     the two directories below default from.
+ * @param {string} [opts.stageDest]    Directory holding the compiled LevelDB
+ *                                     packs, one subdirectory per pack.
+ * @param {string} [opts.packDest]     Directory the extracted JSON is written
+ *                                     to, one subdirectory per pack.
+ * @param {string} [opts.packName]     Restrict the run to a single pack.
+ * @param {string} [opts.entryName]    Restrict the run to a single entry.
+ */
+export async function unpackPacks({
+    packs,
+    config = loadPackConfig(),
+    stageDest = config.paths.stage,
+    packDest = config.paths.unpack,
+    packName,
+    entryName,
+}) {
+    entryName = entryName?.toLowerCase();
+
+    // Determine which source packs to process.
+    const selected = packs.filter((p) => !packName || p.name === packName);
+
+    for (const packInfo of selected) {
+        const src = path.join(stageDest, packInfo.name);
+        const dest = path.join(packDest, packInfo.name);
+        log.info(`Extracting pack ${packInfo.name}`);
+
+        const folders = {};
+        const containers = {};
+        await extractPack(src, dest, {
+            log: false,
+            transformEntry: (e) => {
+                if (e._key.startsWith("!folders"))
+                    folders[e._id] = {
+                        name: slugify(e.name),
+                        folder: e.folder,
+                    };
+                return false;
+            },
+        });
+        const buildPath = (collection, entry, parentKey) => {
+            let parent = collection[entry[parentKey]];
+            entry.path = entry.name;
+            while (parent) {
+                entry.path = path.join(parent.name, entry.path);
+                parent = collection[parent[parentKey]];
+            }
+        };
+        Object.values(folders).forEach((f) => buildPath(folders, f, "folder"));
+
+        await extractPack(src, dest, {
+            log: true,
+            transformEntry: (entry) => {
+                if (entryName && entryName !== entry.name.toLowerCase())
+                    return false;
+                cleanPackEntry(entry);
+            },
+            transformName: (entry) => {
+                if (entry._id in folders)
+                    return path.join(
+                        "folder_",
+                        folders[entry._id].path,
+                        ".json",
+                    );
+                const outputName = slugify(entry.name);
+                const parent =
+                    containers[entry.system?.container] ??
+                    folders[entry.folder];
+                return path.join(parent?.path ?? "", `${outputName}.json`);
+            },
+        });
+    }
+}