modwright 0.1.0

package/dist/surfaces/cyberpunk2077/validators/xl.js

@@ -0,0 +1,308 @@
+import { parse as parseYaml } from "yaml";
+import { compareVersions } from "../../../core/compat/version.js";
+const ID = "cp2077.history.xl-manifest-lint";
+const GAME = "cyberpunk2077";
+const GROUPS = ["history"];
+const MOD_TYPES = ["garment", "vehicle", "packaging"];
+const SEVERITY = "warn";
+const EVIDENCE = [
+    "cp2077.archivexl.manifest-top-level-keys",
+    "cp2077.anims.archivexl.animconfig-vars-parser-bug",
+    "cp2077.anims.archivexl.animconfig-entity-list-parser-bug",
+    "cp2077.anims.archivexl.pr-merged-upstream",
+];
+const KNOWN_TOP_LEVEL_KEYS = new Set(["localization", "factories", "streaming", "resource", "animations", "player", "quest"]);
+const QUEST_EVIDENCE = ["cp2077.quests.scenes.archivexl-quest-phase-merge"];
+const PLAYER_EVIDENCE = ["cp2077.archivexl.bodytypes.player-bodytypes-key"];
+const ARCHIVEXL_ANIM_FIX_VERSION = "1.27.3";
+const KNOWN_BUGGY_ARCHIVEXL_VERSIONS = new Set(["1.27.0", "1.27.1", "1.28.0-beta.1"]);
+function isArchiveXLAnimConfigBuggy(version) {
+    const v = version.trim();
+    if (KNOWN_BUGGY_ARCHIVEXL_VERSIONS.has(v))
+        return true;
+    try {
+        return compareVersions(v, ARCHIVEXL_ANIM_FIX_VERSION) < 0;
+    }
+    catch {
+        return undefined;
+    }
+}
+function extensionOf(p) {
+    const idx = p.lastIndexOf(".");
+    return idx === -1 ? "" : p.slice(idx).toLowerCase();
+}
+function normalizeSlashes(p) {
+    return p.replace(/\\/g, "/").toLowerCase();
+}
+const PLAYER_FPP_TARGET_RE = /player_[mw]a_fpp(?:_ep1)?\.ent$/i;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function finding(file, message, evidence, fix) {
+    return { validatorId: ID, severity: SEVERITY, file, message, fix, evidence };
+}
+function lintLocalization(doc, file, out) {
+    const localization = doc.localization;
+    if (localization === undefined)
+        return;
+    if (!isRecord(localization)) {
+        out.push(finding(file, `"localization:" must be a mapping with an "onscreens" key.`, EVIDENCE));
+        return;
+    }
+    const onscreens = localization.onscreens;
+    if (onscreens === undefined) {
+        out.push(finding(file, `"localization:" has no "onscreens" key. The documented shape maps a language code (e.g. en-us) to a localization .json path.`, EVIDENCE));
+        return;
+    }
+    if (!isRecord(onscreens)) {
+        out.push(finding(file, `"localization: onscreens:" must be a mapping of language code -> .json path.`, EVIDENCE));
+        return;
+    }
+    for (const [lang, value] of Object.entries(onscreens)) {
+        if (typeof value !== "string" || !normalizeSlashes(value).endsWith(".json")) {
+            out.push(finding(file, `"localization: onscreens: ${lang}:" is ${JSON.stringify(value)}, which does not look like a .json path.`, EVIDENCE));
+        }
+    }
+}
+function lintPlayer(doc, file, out) {
+    const player = doc.player;
+    if (player === undefined)
+        return;
+    if (!isRecord(player)) {
+        out.push(finding(file, `"player:" must be a mapping with a "bodyTypes" key.`, PLAYER_EVIDENCE));
+        return;
+    }
+    const bodyTypes = player.bodyTypes;
+    if (bodyTypes === undefined) {
+        out.push(finding(file, `"player:" has no "bodyTypes" key (a non-empty list of body-tag names registered via ArchiveXL's player.bodyTypes).`, PLAYER_EVIDENCE));
+        return;
+    }
+    if (!isStringArray(bodyTypes) || bodyTypes.length === 0) {
+        out.push(finding(file, `"player: bodyTypes:" must be a non-empty list of body-tag name strings.`, PLAYER_EVIDENCE));
+    }
+}
+function lintFactories(doc, file, out) {
+    const factories = doc.factories;
+    if (factories === undefined)
+        return;
+    if (!Array.isArray(factories)) {
+        out.push(finding(file, `"factories:" must be a list of factory .csv paths.`, EVIDENCE));
+        return;
+    }
+    for (const entry of factories) {
+        if (typeof entry !== "string" || !normalizeSlashes(entry).endsWith(".csv")) {
+            out.push(finding(file, `"factories:" entry ${JSON.stringify(entry)} does not look like a .csv path. Every factories entry registers a factory csv resource (cp2077.archivexl.factories-csv-paths).`, EVIDENCE));
+        }
+    }
+}
+function lintStreaming(doc, file, out) {
+    const streaming = doc.streaming;
+    if (streaming === undefined)
+        return;
+    if (!isRecord(streaming)) {
+        out.push(finding(file, `"streaming:" must be a mapping with a "blocks" key.`, EVIDENCE));
+        return;
+    }
+    const blocks = streaming.blocks;
+    if (blocks === undefined) {
+        out.push(finding(file, `"streaming:" has no "blocks" key (a list of .streamingblock paths).`, EVIDENCE));
+        return;
+    }
+    if (!Array.isArray(blocks)) {
+        out.push(finding(file, `"streaming: blocks:" must be a list of .streamingblock paths.`, EVIDENCE));
+        return;
+    }
+    for (const entry of blocks) {
+        if (typeof entry !== "string" || !normalizeSlashes(entry).endsWith(".streamingblock")) {
+            out.push(finding(file, `"streaming: blocks:" entry ${JSON.stringify(entry)} does not look like a .streamingblock path.`, EVIDENCE));
+        }
+    }
+}
+function lintQuestPhases(doc, file, out) {
+    const quest = doc.quest;
+    if (quest === undefined)
+        return;
+    if (!isRecord(quest) || !Array.isArray(quest.phases)) {
+        out.push(finding(file, `"quest:" must be a mapping with a "phases" list of { path, parent } entries.`, QUEST_EVIDENCE));
+        return;
+    }
+    quest.phases.forEach((entry, i) => {
+        if (!isRecord(entry)) {
+            out.push(finding(file, `"quest: phases:" entry ${i + 1} must be a mapping with "path" and "parent".`, QUEST_EVIDENCE));
+            return;
+        }
+        const phasePath = typeof entry.path === "string" ? normalizeSlashes(entry.path) : "";
+        if (!phasePath.endsWith(".questphase")) {
+            out.push(finding(file, `"quest: phases:" entry ${i + 1} has path ${JSON.stringify(entry.path)}, which does not look like a .questphase path.`, QUEST_EVIDENCE));
+        }
+        const parent = typeof entry.parent === "string" ? normalizeSlashes(entry.parent) : "";
+        if (!parent.endsWith(".questphase") && !parent.endsWith(".quest")) {
+            out.push(finding(file, entry.parent === undefined
+                ? `"quest: phases:" entry ${i + 1} has no "parent" (the .quest or .questphase to merge into).`
+                : `"quest: phases:" entry ${i + 1} has parent ${JSON.stringify(entry.parent)}, which is neither a .questphase nor a .quest.`, QUEST_EVIDENCE));
+        }
+    });
+}
+function lintResourcePatch(doc, file, out) {
+    const resource = doc.resource;
+    if (resource === undefined)
+        return;
+    if (!isRecord(resource)) {
+        out.push(finding(file, `"resource:" must be a mapping with a "patch" key.`, EVIDENCE));
+        return;
+    }
+    const patch = resource.patch;
+    if (patch === undefined)
+        return;
+    if (!isRecord(patch)) {
+        out.push(finding(file, `"resource: patch:" must map a patch .ent path to a list of target .ent paths.`, EVIDENCE));
+        return;
+    }
+    for (const [patchKey, targets] of Object.entries(patch)) {
+        if (!normalizeSlashes(patchKey).endsWith(".ent")) {
+            out.push(finding(file, `"resource: patch:" key ${JSON.stringify(patchKey)} does not look like a patch .ent path.`, EVIDENCE));
+        }
+        if (!isStringArray(targets)) {
+            out.push(finding(file, `"resource: patch: ${patchKey}:" must be a list of target .ent paths.`, EVIDENCE));
+            continue;
+        }
+        if (targets.length === 0) {
+            out.push(finding(file, `"resource: patch: ${patchKey}:" lists no target .ent path. ArchiveXL rejects the entry ("Patch definition must have at least one target") and the patch .ent never attaches to anything.`, ["cp2077.archivexl.bodytypes.resource-patch-entry-needs-at-least-one-target"], `List the vanilla .ent path(s) this patch applies to (for a player body patch: the base\\ and ep1\\ player FPP entities per gender).`));
+            continue;
+        }
+        for (const target of targets) {
+            if (!normalizeSlashes(target).endsWith(".ent")) {
+                out.push(finding(file, `"resource: patch: ${patchKey}:" target ${JSON.stringify(target)} does not look like an .ent path.`, EVIDENCE));
+            }
+        }
+        const isPlayerFpp = targets.some((t) => PLAYER_FPP_TARGET_RE.test(normalizeSlashes(t)));
+        if (isPlayerFpp) {
+            const hasBase = targets.some((t) => normalizeSlashes(t).startsWith("base/"));
+            const hasEp1 = targets.some((t) => normalizeSlashes(t).startsWith("ep1/"));
+            if (!hasBase || !hasEp1) {
+                const missing = !hasBase ? "base\\" : "ep1\\";
+                const consequence = !hasBase
+                    ? "silently no-ops with no log line when Phantom Liberty is NOT installed (the ep1 template is a standalone copy, not an include; base\\ is the no-EP1 fallback)"
+                    : "silently no-ops with no log line when Phantom Liberty IS installed (the game loads the ep1\\ template instead of base\\)";
+                out.push(finding(file, `"resource: patch: ${patchKey}:" patches a player FPP entity but lists no ${missing} target. It ${consequence}. List both the base\\ and ep1\\ (both genders, as needed) template paths in the same target list.`, ["cp2077.anims.sets.patch-the-ep1-player-ent"], `Add the missing ${missing} target path to this patch entry's target list.`));
+            }
+        }
+    }
+}
+async function lintAnimations(doc, file, ctx, out) {
+    const animations = doc.animations;
+    if (animations === undefined)
+        return;
+    if (!Array.isArray(animations)) {
+        out.push(finding(file, `"animations:" must be a list of animation config entries.`, EVIDENCE));
+        return;
+    }
+    let usesRiskyForm = false;
+    let installedVersion;
+    let versionChecked = false;
+    animations.forEach((raw, i) => {
+        const entry = raw;
+        const label = `animations[${i}]`;
+        if (entry.entity === undefined)
+            out.push(finding(file, `${label} has no "entity:".`, EVIDENCE));
+        if (entry.set === undefined || typeof entry.set !== "string" || !normalizeSlashes(entry.set).endsWith(".anims")) {
+            out.push(finding(file, `${label}."set:" must be a .anims resource path.`, EVIDENCE));
+        }
+        if (entry.priority !== undefined && typeof entry.priority !== "number") {
+            out.push(finding(file, `${label}."priority:" must be a number when present.`, EVIDENCE));
+        }
+        const entityIsList = Array.isArray(entry.entity);
+        const hasVars = Array.isArray(entry.vars) && entry.vars.length > 0;
+        if (entityIsList || hasVars)
+            usesRiskyForm = true;
+    });
+    if (!usesRiskyForm)
+        return;
+    if (ctx.install && ctx.surface.compat) {
+        versionChecked = true;
+        try {
+            const components = await ctx.surface.compat.detectComponents(ctx.install);
+            installedVersion = components.find((c) => c.id === "archivexl")?.version;
+        }
+        catch {
+            installedVersion = undefined;
+        }
+    }
+    if (!versionChecked || installedVersion === undefined) {
+        out.push(finding(file, `"animations:" uses "vars:" and/or a list-form "entity:", but the installed ArchiveXL version could not be determined. Both forms are broken by a Config.cpp parser bug in ArchiveXL <= v1.27.1 and in v1.28.0-beta.1 (fixed in v1.27.3): "vars:" is silently dropped (the set mounts unconditionally on every matching weapon) and a list-form "entity:" is rejected outright. Confirm the installed ArchiveXL version, or use the "resource: patch:" ResourcePatch route instead, which is not subject to this bug.`, EVIDENCE));
+        return;
+    }
+    const buggy = isArchiveXLAnimConfigBuggy(installedVersion);
+    if (buggy === undefined) {
+        out.push(finding(file, `"animations:" uses "vars:" and/or a list-form "entity:", but the installed ArchiveXL version "${installedVersion}" does not parse as a comparable version, so it cannot be checked against the fix in v${ARCHIVEXL_ANIM_FIX_VERSION}.`, EVIDENCE));
+        return;
+    }
+    if (!buggy)
+        return;
+    animations.forEach((raw, i) => {
+        const entry = raw;
+        const label = `animations[${i}]`;
+        if (Array.isArray(entry.vars) && entry.vars.length > 0) {
+            out.push(finding(file, `${label} uses "vars:" to gate this set, but the installed ArchiveXL v${installedVersion} has the Config.cpp parser bug that tests the wrong YAML node (variablesNode.IsScalar() instead of variableNode.IsScalar()), so entry.variables stays empty and the set mounts UNCONDITIONALLY on every weapon/state sharing its animation names, not just the gated one. Fixed upstream in v${ARCHIVEXL_ANIM_FIX_VERSION}.`, ["cp2077.anims.archivexl.animconfig-vars-parser-bug", "cp2077.anims.archivexl.pr-merged-upstream"], `Upgrade ArchiveXL to >= v${ARCHIVEXL_ANIM_FIX_VERSION}, or mount this set via "resource: patch:" (an entAnimationSetupExtensionComponent carrying its own variableNames) instead, which is not subject to this bug.`));
+        }
+        if (Array.isArray(entry.entity)) {
+            out.push(finding(file, `${label} uses the list form of "entity:" (${entry.entity.length} paths), but the installed ArchiveXL v${installedVersion} has the Config.cpp parser bug where the "entity:" else-if branch repeats the scalar test instead of testing IsSequence(), so this whole entry is rejected as malformed and never mounts (no log line). Fixed upstream in v${ARCHIVEXL_ANIM_FIX_VERSION}.`, ["cp2077.anims.archivexl.animconfig-entity-list-parser-bug", "cp2077.anims.archivexl.pr-merged-upstream"], `Upgrade ArchiveXL to >= v${ARCHIVEXL_ANIM_FIX_VERSION}, or split this entry into one per entity path (each with a scalar "entity:"), or use "resource: patch:" instead.`));
+        }
+    });
+}
+export const xlManifestLintValidator = {
+    id: ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Lints an ArchiveXL .xl manifest: it parses as YAML, its top-level keys and their sub-shapes match the documented set, and an animations: entry avoids the ArchiveXL <= 1.27.1/1.28.0-beta.1 Config.cpp parser bugs.",
+    appliesTo(target, _project) {
+        return target.kind === "file" && extensionOf(target.path) === ".xl";
+    },
+    appliesToDescription: 'every file with a ".xl" extension (an ArchiveXL manifest)',
+    needs: { project: true, install: true },
+    cost: "edit",
+    severity: SEVERITY,
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        let text;
+        try {
+            text = await ctx.readText(file);
+        }
+        catch (err) {
+            return [finding(file, `Could not read this file: ${err.message}`, EVIDENCE)];
+        }
+        const cleaned = text.replace(/^\uFEFF/, "");
+        let doc;
+        try {
+            doc = parseYaml(cleaned);
+        }
+        catch (err) {
+            return [finding(file, `Cannot parse this ArchiveXL manifest as YAML: ${err.message}`, EVIDENCE)];
+        }
+        if (!isRecord(doc)) {
+            return [finding(file, "This ArchiveXL manifest's root must be a mapping of top-level keys.", EVIDENCE)];
+        }
+        const out = [];
+        for (const key of Object.keys(doc)) {
+            if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
+                out.push(finding(file, `Unknown top-level key "${key}:". The documented set is localization, factories, streaming, resource, animations, player, quest. ArchiveXL advertises other keys too (submesh visibility overrides, clothing visual tags, widget spawning) that this manifest does not use — if this is one of those, ModWright's knowledge base does not yet document its shape.`, EVIDENCE));
+            }
+        }
+        lintLocalization(doc, file, out);
+        lintPlayer(doc, file, out);
+        lintFactories(doc, file, out);
+        lintStreaming(doc, file, out);
+        lintResourcePatch(doc, file, out);
+        lintQuestPhases(doc, file, out);
+        await lintAnimations(doc, file, ctx, out);
+        return out;
+    },
+};
+export const XL_VALIDATORS = [xlManifestLintValidator];

package/dist/surfaces/eldenring/binders.js

@@ -0,0 +1,111 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { parseXml } from "../../core/text/xml.js";
+export const BND4_HEADER_LENGTH = 0x40;
+export class Bnd4HeaderError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "Bnd4HeaderError";
+    }
+}
+function ascii(bytes, at, length) {
+    let s = "";
+    for (let i = 0; i < length; i++)
+        s += String.fromCharCode(bytes[at + i]);
+    return s;
+}
+export function parseBnd4Header(bytes) {
+    if (bytes.length < 4)
+        throw new Bnd4HeaderError("too-short", `only ${bytes.length} bytes`);
+    const magic = ascii(bytes, 0, 4);
+    if (magic !== "BND4")
+        throw new Bnd4HeaderError("bad-signature", `first four bytes are ${JSON.stringify(magic)}, not "BND4"`);
+    if (bytes.length < BND4_HEADER_LENGTH)
+        throw new Bnd4HeaderError("too-short", `only ${bytes.length} bytes; a BND4 header is ${BND4_HEADER_LENGTH}`);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const bigEndian = bytes[9] === 1;
+    const le = !bigEndian;
+    const header = {
+        bigEndian,
+        bitBigEndian: bytes[10] !== 1,
+        fileCount: view.getInt32(12, le),
+        headerSize: Number(view.getBigInt64(16, le)),
+        version: ascii(bytes, 24, 8).replace(/\0[\s\S]*$/, ""),
+        fileHeaderSize: Number(view.getBigInt64(32, le)),
+        headersEnd: Number(view.getBigInt64(40, le)),
+        unicode: bytes[48] === 1,
+        rawFormat: bytes[49],
+        extended: bytes[50],
+    };
+    if (header.headerSize !== BND4_HEADER_LENGTH)
+        throw new Bnd4HeaderError("bad-layout", `header size field is 0x${header.headerSize.toString(16)}, not 0x40`);
+    if (![0, 1, 4, 0x80].includes(header.extended))
+        throw new Bnd4HeaderError("bad-layout", `extended byte is 0x${header.extended.toString(16)}; SoulsFormats accepts 0, 1, 4 or 0x80`);
+    if (header.fileCount < 0)
+        throw new Bnd4HeaderError("bad-layout", `file count is ${header.fileCount}`);
+    return header;
+}
+export async function readBnd4Header(file) {
+    const handle = await fs.open(file, "r");
+    try {
+        const buf = new Uint8Array(BND4_HEADER_LENGTH);
+        const { bytesRead } = await handle.read(buf, 0, BND4_HEADER_LENGTH, 0);
+        return parseBnd4Header(buf.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function isBareBinderName(name) {
+    const ext = path.extname(name).toLowerCase();
+    return ext === ".bnd" || (ext.endsWith("bnd") && ext.length > 4);
+}
+export const SIDECAR_RE = /^_witchy-([a-z0-9]+)\.xml$/i;
+export function looksLikeBinderUnpackDir(name) {
+    return (/-(?:[a-z0-9_]*(?:bnd|bhd)|bnd4|tpf)(?:-dcx)?$/i.test(name) ||
+        /(?:^|-)regulation-bin(?:-dcx)?$/i.test(name) ||
+        /-dcx$/i.test(name) ||
+        /-unpacked$/i.test(name));
+}
+function child(el, tag) {
+    return el.children.find((c) => c.tag === tag);
+}
+export function parseWitchySidecar(xml) {
+    const root = parseXml(xml);
+    const text = (tag) => child(root, tag)?.text.trim();
+    const filesEl = child(root, "files");
+    const out = { tag: root.tag, files: [], hasFilesElement: filesEl !== undefined };
+    for (const key of ["game", "version", "format", "root", "compression"]) {
+        const v = text(key);
+        if (v !== undefined && v !== "")
+            out[key] = v;
+    }
+    for (const f of filesEl?.children ?? []) {
+        if (f.tag !== "file")
+            continue;
+        const p = child(f, "path");
+        if (!p)
+            continue;
+        const entry = { path: p.text };
+        const suffix = child(f, "suffix")?.text;
+        if (suffix)
+            entry.suffix = suffix;
+        const flags = child(f, "flags")?.text.trim();
+        if (flags)
+            entry.flags = flags;
+        const id = child(f, "id")?.text.trim();
+        if (id)
+            entry.id = id;
+        out.files.push(entry);
+    }
+    return out;
+}
+export function sidecarEntryPath(dir, entry) {
+    const rel = entry.path.replace(/\\/g, "/");
+    const ext = path.posix.extname(rel);
+    const stem = path.posix.basename(rel, ext);
+    const parent = path.posix.dirname(rel);
+    return path.join(dir, ...(parent === "." ? [] : parent.split("/")), `${stem}${entry.suffix ?? ""}${ext}`);
+}

package/dist/surfaces/eldenring/compat.js

@@ -0,0 +1,166 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { readPeFileVersion } from "../../core/compat/pe.js";
+import { pathExists, readTextIfExists } from "../../core/fsutil.js";
+import { locateTool, TOOL_SPECS } from "../../core/toolchain/index.js";
+import { gameDir, me3ProfilesDir } from "./loaders.js";
+import { SIGNATURES } from "./logs.js";
+import { readWitchyBndParamdexVersion } from "./tools.js";
+async function peVersionOf(file) {
+    if (!(await pathExists(file)))
+        return undefined;
+    try {
+        return await readPeFileVersion(file);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function latestModEngineLog(game) {
+    const dir = path.join(game, "modengine2", "logs");
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return undefined;
+    }
+    const logs = names.filter((n) => /^modengine_.*\.log$/i.test(n)).sort();
+    return logs.length > 0 ? path.join(dir, logs[logs.length - 1]) : undefined;
+}
+export function modEngineVersionFromLog(text) {
+    const banner = SIGNATURES.find((s) => s.id === "eldenring.modengine2.initializing");
+    for (const line of text.split(/\r?\n/, 200)) {
+        const m = banner.pattern.exec(line);
+        if (m?.groups?.version)
+            return m.groups.version;
+    }
+    return undefined;
+}
+export async function detectComponentsWith(install, options = {}) {
+    const game = gameDir(install);
+    const exe = path.join(game, "eldenring.exe");
+    const exeExists = await pathExists(exe);
+    const gameVersion = install.version ?? (await peVersionOf(exe));
+    const components = [
+        {
+            id: "game",
+            label: "Elden Ring",
+            kind: "game",
+            installed: exeExists,
+            ...(gameVersion !== undefined ? { version: gameVersion } : {}),
+            source: install.version ? "install record" : "Game/eldenring.exe PE file version (whether it equals the App Ver in the patch notes is unverified; the Regulation Ver is a third axis, readable only by decrypting regulation.bin)",
+            path: exe,
+        },
+    ];
+    const launcher = path.join(game, "modengine2_launcher.exe");
+    const me2Installed = await pathExists(launcher);
+    const me2Log = me2Installed ? await latestModEngineLog(game) : undefined;
+    const me2Text = me2Log ? await readTextIfExists(me2Log) : undefined;
+    const me2Version = me2Text ? modEngineVersionFromLog(me2Text) : undefined;
+    components.push({
+        id: "modengine2",
+        label: "Mod Engine 2",
+        kind: "loader",
+        installed: me2Installed,
+        ...(me2Version !== undefined ? { version: me2Version } : {}),
+        source: me2Version ? `${me2Log}: ModEngine version banner` : me2Installed ? "modengine2_launcher.exe present; no log banner read (not launched, or the log rotated out)" : "modengine2_launcher.exe not found beside the executable",
+        path: launcher,
+    });
+    const profilesDir = me3ProfilesDir();
+    let me3Exe;
+    let witchyExe;
+    if (options.locateTools !== false) {
+        const me3Spec = TOOL_SPECS.find((t) => t.id === "me3");
+        const witchySpec = TOOL_SPECS.find((t) => t.id === "witchybnd");
+        const [me3, witchy] = await Promise.all([me3Spec ? locateTool(me3Spec) : undefined, witchySpec ? locateTool(witchySpec) : undefined]);
+        if (me3?.found && me3.path)
+            me3Exe = me3.path;
+        if (witchy?.found && witchy.path)
+            witchyExe = witchy.path;
+        const me3Version = me3?.found && me3.version && me3.version !== "unknown" ? me3.version : undefined;
+        const profilesExist = await pathExists(profilesDir);
+        components.push({
+            id: "me3",
+            label: "me3",
+            kind: "loader",
+            installed: me3Exe !== undefined || profilesExist,
+            ...(me3Version !== undefined ? { version: me3Version } : {}),
+            source: me3Exe ? `${me3Exe} (me3 --version)` : profilesExist ? `${profilesDir} exists; the me3 executable was not located` : "no me3 executable located and no profiles directory",
+            ...(me3Exe ? { path: me3Exe } : {}),
+        });
+        const paramdexVersion = witchyExe ? await readWitchyBndParamdexVersion(witchyExe) : undefined;
+        components.push({
+            id: "witchybnd",
+            label: "WitchyBND",
+            kind: "tool",
+            installed: witchyExe !== undefined,
+            ...(witchy?.found && witchy.version && witchy.version !== "unknown" ? { version: witchy.version } : {}),
+            source: witchyExe ? `${witchyExe} (WitchyBND -v)${paramdexVersion ? `; its bundled Paramdex repacks regulations up to ${paramdexVersion} (Assets/Paramdex/ER/Upgrader/version.txt)` : ""}` : "not located",
+            ...(witchyExe ? { path: witchyExe } : {}),
+        });
+    }
+    else {
+        components.push({ id: "me3", label: "me3", kind: "loader", installed: await pathExists(profilesDir), source: "profiles directory only (tool location skipped)" });
+        components.push({ id: "witchybnd", label: "WitchyBND", kind: "tool", installed: false, source: "tool location skipped" });
+    }
+    const ersc = path.join(game, "SeamlessCoop", "ersc.dll");
+    const erscInstalled = await pathExists(ersc);
+    components.push({
+        id: "seamless-coop",
+        label: "Seamless Co-op",
+        kind: "mod",
+        installed: erscInstalled,
+        source: erscInstalled ? "Game/SeamlessCoop/ersc.dll present; its version is not on disk in a form read here (releases are titled by game version)" : "Game/SeamlessCoop/ersc.dll not found",
+        path: ersc,
+    });
+    return components;
+}
+export const RULES = [
+    {
+        id: "er-modengine2-archived",
+        game: "eldenring",
+        component: "modengine2",
+        requires: [],
+        advisory: true,
+        severity: "warn",
+        note: "Mod Engine 2 is discontinued: its last release (2.1.0, 2023-09-01) and the repository's archiving (2024-07-19) both predate the Shadow of the Erdtree DLC, so on any game newer than that it is untested by its authors; me3 is the maintained loader.",
+        source: "https://github.com/soulsmods/ModEngine2 (archive banner, releases)",
+    },
+    {
+        id: "er-modengine2-with-game",
+        game: "eldenring",
+        component: "modengine2",
+        requires: [{ component: "game" }],
+        advisory: true,
+        severity: "info",
+        versionGate: "game",
+        undeterminedSeverity: "info",
+        note: "The game's version here is its PE file version; whether it equals the App Ver the patch notes use (1.12 introduced the DLC) is unverified, so no floor is compared. If this game is 1.12 or newer, Mod Engine 2's last release never saw it.",
+        source: "ModWright research",
+    },
+    {
+        id: "er-seamless-coop-tracks-game",
+        game: "eldenring",
+        component: "seamless-coop",
+        requires: [{ component: "game" }],
+        advisory: true,
+        severity: "info",
+        note: "Seamless Co-op's releases are titled by the game version they update to (v2.0.1: 'Update to game ver 1.17'); after a game patch, check its releases page before launching, and note it must run through ersc_launcher.exe or Mod Engine 2, not a DLL injector.",
+        source: "https://github.com/LukeYui/EldenRingSeamlessCoopRelease releases",
+    },
+    {
+        id: "er-witchybnd-paramdex-axis",
+        game: "eldenring",
+        component: "witchybnd",
+        requires: [],
+        advisory: true,
+        severity: "info",
+        note: "WitchyBND refuses to repack a regulation newer than the newest version its bundled Paramdex knows (Assets/Paramdex/ER/Upgrader/version.txt, reported in this component's source); the game's Regulation Ver is a separate axis that only DSMSPortable (-P gamepath) or a decrypt can read, so compare the two by hand after a game patch.",
+        source: "WitchyBND changelog v2.1.1.0",
+    },
+];
+export const eldenringCompat = {
+    detectComponents: (install) => detectComponentsWith(install),
+    rules: RULES,
+};

package/dist/surfaces/eldenring/dcx.js

@@ -0,0 +1,49 @@
+import { promises as fs } from "node:fs";
+export const DCX_HEADER_LENGTH = 0x34;
+export const DCX_CODECS = ["DFLT", "EDGE", "KRAK", "ZSTD"];
+export class DcxHeaderError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "DcxHeaderError";
+    }
+}
+function ascii(bytes, at) {
+    return String.fromCharCode(bytes[at], bytes[at + 1], bytes[at + 2], bytes[at + 3]);
+}
+export function parseDcxHeader(bytes) {
+    if (bytes.length < 8)
+        throw new DcxHeaderError("too-short", `only ${bytes.length} bytes; a DCX header is ${DCX_HEADER_LENGTH}`);
+    const magic = ascii(bytes, 0);
+    if (magic === "DCP\0")
+        return { magic: "DCP", codec: ascii(bytes, 4) };
+    if (magic !== "DCX\0")
+        throw new DcxHeaderError("bad-signature", `first four bytes are ${JSON.stringify(magic)}, not "DCX\\0"`);
+    if (bytes.length < DCX_HEADER_LENGTH)
+        throw new DcxHeaderError("too-short", `only ${bytes.length} bytes; a DCX header is ${DCX_HEADER_LENGTH}`);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (ascii(bytes, 0x18) !== "DCS\0")
+        throw new DcxHeaderError("bad-layout", `no "DCS\\0" at 0x18`);
+    if (ascii(bytes, 0x24) !== "DCP\0")
+        throw new DcxHeaderError("bad-layout", `no "DCP\\0" at 0x24`);
+    return {
+        magic: "DCX",
+        variant: view.getUint32(0x04, false),
+        uncompressedSize: view.getUint32(0x1c, false),
+        compressedSize: view.getUint32(0x20, false),
+        codec: ascii(bytes, 0x28),
+        level: bytes[0x30],
+    };
+}
+export async function readDcxHeader(file) {
+    const handle = await fs.open(file, "r");
+    try {
+        const buf = new Uint8Array(DCX_HEADER_LENGTH);
+        const { bytesRead } = await handle.read(buf, 0, DCX_HEADER_LENGTH, 0);
+        return parseDcxHeader(buf.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/surfaces/eldenring/index.js

@@ -0,0 +1,13 @@
+export { eldenring } from "./surface.js";
+export { SIGNATURES } from "./logs.js";
+export { parseMe3Profile, parseMe3ProfileDetailed, parseModEngine2Config, readModEngine2LoadOrder, MODENGINE2_CONFIG, ME3_GAME_IDS, ME3_ELDENRING_IDS, ME3_PROFILE_VERSION, me3ProfilesDir } from "./loaders.js";
+export { parseParamdef, parseParamdefFieldDef, parseTdf, loadParamdex, findParamdef, checkFieldValue, ParamdefError, PARAMDEF_TYPES } from "./paramdef.js";
+export { parseDsmsCsv, parseWitchyParamXml, detectCsvDelimiter } from "./params.js";
+export { parseDcxHeader, readDcxHeader, DcxHeaderError, DCX_CODECS } from "./dcx.js";
+export { DSMSPORTABLE_EXIT_CODES, explainDsmsPortableExit, readWitchyBndParamdexVersion, witchyBndParamdexDir } from "./tools.js";
+export { PARAM_VALIDATORS, resolveParamdexDir, loadParamdexCached, clearParamdexCache, PARAMDEX_ENV } from "./validators/params.js";
+export { PROFILE_VALIDATORS } from "./validators/profiles.js";
+export { PACKAGE_VALIDATORS, PACKAGE_DIRECTORY_VOCABULARY } from "./validators/packages.js";
+export { BINDER_VALIDATORS } from "./validators/binders.js";
+export { parseBnd4Header, readBnd4Header, Bnd4HeaderError, parseWitchySidecar, sidecarEntryPath, looksLikeBinderUnpackDir, isBareBinderName } from "./binders.js";
+export { eldenringCompat, detectComponentsWith, modEngineVersionFromLog } from "./compat.js";