modwright 0.1.0

package/dist/surfaces/subnautica2/paks.js

@@ -0,0 +1,173 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+export const PAK_MAGIC = 0x5a6f12e1;
+export const PAK_VERSION_MAJOR_NAMES = {
+    0: "Unknown",
+    1: "Initial",
+    2: "NoTimestamps",
+    3: "CompressionEncryption",
+    4: "IndexEncryption",
+    5: "RelativeChunkOffsets",
+    6: "DeleteRecords",
+    7: "EncryptionKeyGuid",
+    8: "FNameBasedCompression",
+    9: "FrozenIndex",
+    10: "PathHashIndex",
+    11: "Fnv64BugFix",
+};
+export const GAME_MOUNT_POINT = "../../../";
+const FOOTER_SCAN_BYTES = 256;
+export class PakError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "PakError";
+    }
+}
+export function parsePakFooter(tail, fileSize) {
+    if (tail.length < 44)
+        throw new PakError("too-short", `only ${tail.length} bytes; a pak footer is at least 44`);
+    const view = new DataView(tail.buffer, tail.byteOffset, tail.byteLength);
+    const tailStart = fileSize - tail.length;
+    let best;
+    for (let i = 0; i + 24 <= tail.length; i++) {
+        if (view.getUint32(i, true) !== PAK_MAGIC)
+            continue;
+        const versionMajor = view.getUint32(i + 4, true);
+        if (versionMajor < 1 || versionMajor > 11)
+            continue;
+        const indexOffset = Number(view.getBigUint64(i + 8, true));
+        const indexSize = Number(view.getBigUint64(i + 16, true));
+        if (versionMajor >= 4 && i < 1)
+            continue;
+        const magicOffset = tailStart + i;
+        const footerStart = magicOffset - (versionMajor >= 7 ? 16 : 0) - (versionMajor >= 4 ? 1 : 0);
+        if (indexOffset >= footerStart || indexOffset + indexSize > footerStart)
+            continue;
+        const encryptedIndex = versionMajor >= 4 ? tail[i - 1] === 1 : false;
+        best = { versionMajor, versionName: PAK_VERSION_MAJOR_NAMES[versionMajor] ?? String(versionMajor), indexOffset, indexSize, encryptedIndex, fileSize, magicOffset };
+    }
+    if (!best)
+        throw new PakError("no-magic", "no pak footer magic (0x5A6F12E1) with a plausible index behind it in the last bytes of the file");
+    return best;
+}
+export async function readPakFooter(file) {
+    const handle = await fs.open(file, "r");
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(FOOTER_SCAN_BYTES, size);
+        const buf = new Uint8Array(length);
+        const { bytesRead } = await handle.read(buf, 0, length, size - length);
+        return parsePakFooter(buf.subarray(0, bytesRead), size);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function parseFString(bytes, at = 0) {
+    if (bytes.length < at + 4)
+        throw new PakError("bad-index", "index shorter than a string length");
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const len = view.getInt32(at, true);
+    if (len === 0)
+        return { value: "", length: 4 };
+    if (len < 0) {
+        const units = -len;
+        if (bytes.length < at + 4 + units * 2)
+            throw new PakError("bad-index", "UTF-16 string runs past the index");
+        const chars = [];
+        for (let i = 0; i < units; i++) {
+            const c = view.getUint16(at + 4 + i * 2, true);
+            if (c === 0)
+                break;
+            chars.push(c);
+        }
+        return { value: String.fromCharCode(...chars), length: 4 + units * 2 };
+    }
+    if (len > 4096)
+        throw new PakError("bad-index", `string length ${len} is not a mount point; the index is probably encrypted or damaged`);
+    if (bytes.length < at + 4 + len)
+        throw new PakError("bad-index", "string runs past the index");
+    const raw = bytes.subarray(at + 4, at + 4 + len);
+    const nul = raw.indexOf(0);
+    return { value: Buffer.from(nul >= 0 ? raw.subarray(0, nul) : raw).toString("utf8"), length: 4 + len };
+}
+export async function readPakInfo(file) {
+    const footer = await readPakFooter(file);
+    if (footer.encryptedIndex)
+        return { ...footer };
+    const handle = await fs.open(file, "r");
+    try {
+        const length = Math.min(4 + 4096, footer.indexSize);
+        const buf = new Uint8Array(length);
+        const { bytesRead } = await handle.read(buf, 0, length, footer.indexOffset);
+        return { ...footer, mountPoint: parseFString(buf.subarray(0, bytesRead)).value };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export const UTOC_MAGIC = "-==--==--==--==-";
+export const UTOC_VERSION_NAMES = {
+    0: "Invalid",
+    1: "Initial",
+    2: "DirectoryIndex",
+    3: "PartitionSize",
+    4: "PerfectHash",
+    5: "PerfectHashWithOverflow",
+    6: "OnDemandMetaData",
+    7: "RemovedOnDemandMetaData",
+    8: "ReplaceIoChunkHashWithIoHash",
+};
+export const UTOC_HEADER_READ = 28;
+export class UtocError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "UtocError";
+    }
+}
+export function parseUtocHeader(bytes) {
+    if (bytes.length < UTOC_HEADER_READ)
+        throw new UtocError("too-short", `only ${bytes.length} bytes; a TOC header starts with ${UTOC_HEADER_READ}`);
+    const magic = Buffer.from(bytes.subarray(0, 16)).toString("latin1");
+    if (magic !== UTOC_MAGIC)
+        throw new UtocError("bad-magic", `first 16 bytes are ${JSON.stringify(magic)}, not the IoStore TOC magic`);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const version = bytes[16];
+    return { version, versionName: UTOC_VERSION_NAMES[version] ?? String(version), headerSize: view.getUint32(20, true), entryCount: view.getUint32(24, true) };
+}
+export async function readUtocHeader(file) {
+    const handle = await fs.open(file, "r");
+    try {
+        const buf = new Uint8Array(UTOC_HEADER_READ);
+        const { bytesRead } = await handle.read(buf, 0, UTOC_HEADER_READ, 0);
+        return parseUtocHeader(buf.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export const TRIPLET_EXTENSIONS = [".pak", ".utoc", ".ucas"];
+export async function tripletsIn(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const byStem = new Map();
+    for (const e of entries) {
+        if (!e.isFile())
+            continue;
+        const ext = path.extname(e.name).toLowerCase();
+        if (!TRIPLET_EXTENSIONS.includes(ext))
+            continue;
+        const stem = e.name.slice(0, -ext.length);
+        const key = stem.toLowerCase();
+        const t = byStem.get(key) ?? { stem, present: {} };
+        t.present[ext] = path.join(dir, e.name);
+        byStem.set(key, t);
+    }
+    return [...byStem.values()];
+}
+export function hasPrioritySuffix(stem) {
+    return /_p$/i.test(stem);
+}

package/dist/surfaces/subnautica2/surface.js

@@ -0,0 +1,151 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { localAppData, pathExists } from "../../core/fsutil.js";
+import { findInSteam } from "../../core/steam.js";
+import { dedupeByRoot, logs, roots } from "../../core/surfaceutil.js";
+import { subnautica2Compat } from "./compat.js";
+import { SIGNATURES } from "./logs.js";
+import { PACKAGING_VALIDATORS } from "./validators/packaging.js";
+export const PROJECT_DIR = "Subnautica2";
+export const SHIPPING_EXE = path.join(PROJECT_DIR, "Binaries", "Win64", "Subnautica2-Win64-Shipping.exe");
+export const subnautica2 = {
+    id: "subnautica2",
+    name: "Subnautica 2",
+    aliases: ["subnautica2", "sn2"],
+    summary: "Unreal Engine 5.6 (IoStore). Pak mods under Content/Paks/~mods, blueprint mods under " +
+        "LogicMods, UE4SS Lua/C++ mods, and loader-free DLC plugins under Mods/; no official mod support.",
+    async detect() {
+        const installs = [];
+        const override = process.env.MODWRIGHT_SUBNAUTICA2_ROOT;
+        if (override && (await pathExists(override))) {
+            installs.push({ gameId: "subnautica2", root: override, source: "env" });
+        }
+        for (const root of await findInSteam(["Subnautica2"])) {
+            if (await pathExists(path.join(root, SHIPPING_EXE))) {
+                installs.push({ gameId: "subnautica2", root, source: "steam" });
+            }
+        }
+        return dedupeByRoot(installs);
+    },
+    modRoots(install) {
+        const project = path.join(install.root, PROJECT_DIR);
+        const paks = path.join(project, "Content", "Paks");
+        return roots([
+            {
+                id: "paks",
+                label: "Pak mods (~mods)",
+                path: path.join(paks, "~mods"),
+                layout: "file",
+                extensions: [".pak", ".utoc", ".ucas"],
+                ordered: true,
+                conflictScope: "opaque",
+                notes: "Loaded in name order, later wins; a _P suffix forces priority. On this IoStore-only " +
+                    "game a mod is complete only as a .pak + .utoc + .ucas triplet with mount point " +
+                    "../../../; a lone legacy .pak mounts and delivers nothing. The folder does not exist " +
+                    "on a fresh install and is a community convention no source confirms this game honours.",
+            },
+            {
+                id: "logicmods",
+                label: "Blueprint mods (LogicMods)",
+                path: path.join(paks, "LogicMods"),
+                layout: "directory",
+                conflictScope: "opaque",
+                notes: "One folder per mod holding the full triplet named after the folder (the modkit's " +
+                    "layout, unlike generic UE4SS docs' loose paks). Needs UE4SS's BPModLoaderMod.",
+            },
+            {
+                id: "ue4ss",
+                label: "UE4SS mods",
+                path: path.join(project, "Binaries", "Win64", "ue4ss", "Mods"),
+                layout: "directory",
+                ordered: true,
+                conflictScope: "isolated",
+                notes: "Each subdirectory is one mod with Scripts/main.lua and/or dlls/main.dll; enablement " +
+                    "is mods.txt ('ModName : 1') plus the enabled.txt convention. This is the experimental " +
+                    "UE4SS layout; a stable 3.0.x UE4SS keeps Mods/ directly under Binaries/Win64 and does " +
+                    "not support Unreal 5.6.",
+            },
+            {
+                id: "dlcplugins",
+                label: "DLC-style content plugins (Mods/)",
+                path: path.join(project, "Mods"),
+                layout: "directory",
+                conflictScope: "isolated",
+                notes: "Content-only plugins the engine loads with no external loader (the modkit's route). " +
+                    "The modkit README spells the parent 'Subnautica 2' with a space where every observed " +
+                    "path has none; confirm on a real install before relying on this path.",
+            },
+        ]);
+    },
+    async loadOrder(install) {
+        const modsDir = path.join(install.root, PROJECT_DIR, "Binaries", "Win64", "ue4ss", "Mods");
+        const file = path.join(modsDir, "mods.txt");
+        if (!(await pathExists(file)))
+            return [];
+        const text = await fs.readFile(file, "utf8");
+        const entries = [];
+        let index = 0;
+        for (const raw of text.split(/\r?\n/)) {
+            const line = raw.trim();
+            if (!line || line.startsWith(";") || line.startsWith("#"))
+                continue;
+            const m = /^(?<name>[^:]+?)\s*:\s*(?<flag>[01])\s*$/.exec(line);
+            if (!m?.groups)
+                continue;
+            const name = m.groups.name;
+            const exists = await pathExists(path.join(modsDir, name));
+            entries.push({ index: index++, name, enabled: m.groups.flag === "1", ...(exists ? { modId: `ue4ss:${name}` } : {}) });
+        }
+        return entries;
+    },
+    loadOrderFile(install) {
+        return path.join(install.root, PROJECT_DIR, "Binaries", "Win64", "ue4ss", "Mods", "mods.txt");
+    },
+    logs(install) {
+        const saved = localAppData("Subnautica2", "Saved", "Logs");
+        return logs([
+            {
+                id: "game",
+                label: "Unreal game log",
+                candidates: [path.join(saved, "Subnautica2.log"), path.join(saved, "Subnautica2-backup-*.log")],
+                notes: "One new file per launch (the previous one becomes Subnautica2-backup-<local stamp>.log). " +
+                    "The first several hundred lines carry no timestamp prefix, and that is where the pak " +
+                    "mounts and plugin list are; later lines are [UTC stamp][frame]Category: Verbosity: " +
+                    "message, with the Verbosity token omitted at the default Log level.",
+            },
+            {
+                id: "ue4ss",
+                label: "UE4SS log",
+                candidates: [path.join(install.root, PROJECT_DIR, "Binaries", "Win64", "ue4ss", "UE4SS.log"), path.join(install.root, PROJECT_DIR, "Binaries", "Win64", "UE4SS.log")],
+                rootId: "ue4ss",
+                notes: "Only exists once UE4SS is installed and has run; the experimental layout keeps it under ue4ss/.",
+            },
+        ]);
+    },
+    async explainMissing(install) {
+        const reasons = {};
+        const ue4ssDll = path.join(install.root, PROJECT_DIR, "Binaries", "Win64", "ue4ss", "UE4SS.dll");
+        const dwmapi = path.join(install.root, PROJECT_DIR, "Binaries", "Win64", "dwmapi.dll");
+        if (!(await pathExists(ue4ssDll)) && !(await pathExists(dwmapi))) {
+            reasons.ue4ss = "UE4SS is not installed beside the shipping executable (no ue4ss/UE4SS.dll or dwmapi.dll proxy), so no UE4SS.log exists. Only an experimental UE4SS build supports Unreal 5.6.";
+        }
+        else {
+            reasons.ue4ss = "UE4SS is present but has not written a log since it was installed; launch once.";
+        }
+        reasons.game = "The game writes Subnautica2.log on every launch under LocalAppData; its absence means the game has not been launched on this account.";
+        return reasons;
+    },
+    logSignatures: SIGNATURES,
+    validators: PACKAGING_VALIDATORS,
+    compat: subnautica2Compat,
+    processNames: ["Subnautica2-Win64-Shipping.exe"],
+    guidance: "An IoStore-only Unreal 5.6 game with no official mod support: a legacy .pak alone delivers " +
+        "nothing, a pak mod is a .pak/.utoc/.ucas triplet, and every patch can break mods (the " +
+        "developer says so). UE4SS must be an experimental build for Unreal 5.6 and is DLL injection " +
+        "into a game whose build carries an EOS anti-cheat bootstrapper, inert on a plain launch and " +
+        "unresolved for co-op; the loader-free DLC-plugin route under Mods/ avoids both. Only a Steam " +
+        "install with the shipping executable present, or MODWRIGHT_SUBNAUTICA2_ROOT, is detected. A " +
+        "project declares its folders by source kind: 'paks' (triplets bound for ~mods), 'logicmods' " +
+        "(one folder per mod), 'ue4ss' (the Mods folder). " +
+        "Nothing here has run against an installed game.",
+};

package/dist/surfaces/subnautica2/validators/packaging.js

@@ -0,0 +1,298 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { pathExists } from "../../../core/fsutil.js";
+import { GAME_MOUNT_POINT, hasPrioritySuffix, PakError, readPakInfo, readUtocHeader, TRIPLET_EXTENSIONS, tripletsIn, UtocError } from "../paks.js";
+export const PAKS_SOURCE_KIND = "paks";
+export const LOGICMODS_SOURCE_KIND = "logicmods";
+export const UE4SS_SOURCE_KIND = "ue4ss";
+const TRIPLET_EVIDENCE = ["subnautica2.game.iostore-only-paks", "subnautica2.ue5.iostore-utoc-ucas-split"];
+const NAME_EVIDENCE = ["subnautica2.modding.logicmods-is-folder-per-mod"];
+const MOUNT_EVIDENCE = ["subnautica2.game.pak-mount-point", "subnautica2.ue5.mount-order-and-mount-point", "subnautica2.ue5.pak-footer-and-index-head"];
+const UTOC_EVIDENCE = ["subnautica2.ue5.iostore-utoc-ucas-split", "subnautica2.ue5.utoc-header"];
+const PRIORITY_EVIDENCE = ["subnautica2.ue5.patch-pak-p-suffix", "subnautica2.ue5.tilde-mods-is-a-convention"];
+const UE4SS_EVIDENCE = ["subnautica2.ue4ss.mod-folder-and-mods-txt", "subnautica2.ue4ss.shared-folder-and-enabled-txt"];
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+const containerSources = (project) => project.sources.filter((s) => s.exists && (s.kind === PAKS_SOURCE_KIND || s.kind === LOGICMODS_SOURCE_KIND));
+const appliesToContainers = (target, project) => target.kind === "project" && containerSources(project).length > 0;
+const CONTAINER_APPLIES = `the project, when it has a source of kind "${PAKS_SOURCE_KIND}" or "${LOGICMODS_SOURCE_KIND}"`;
+async function tripletDirs(project) {
+    const out = [];
+    for (const s of containerSources(project)) {
+        if (s.kind === PAKS_SOURCE_KIND) {
+            out.push({ sourceId: s.id, kind: s.kind, dir: s.absPath });
+            continue;
+        }
+        const entries = await fs.readdir(s.absPath, { withFileTypes: true });
+        for (const e of entries)
+            if (e.isDirectory())
+                out.push({ sourceId: s.id, kind: s.kind, dir: path.join(s.absPath, e.name), modName: e.name });
+    }
+    return out;
+}
+const triplet = {
+    id: "subnautica2.paks.triplet",
+    game: "subnautica2",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "Every packed mod ships all three of .pak, .utoc and .ucas under one stem; a lone legacy .pak mounts and delivers nothing on this IoStore-only game, and a .utoc without its .ucas has no data.",
+    appliesTo: appliesToContainers,
+    appliesToDescription: CONTAINER_APPLIES,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: TRIPLET_EVIDENCE,
+    async run(ctx) {
+        const findings = [];
+        for (const d of await tripletDirs(ctx.project)) {
+            for (const t of await tripletsIn(d.dir)) {
+                const missing = TRIPLET_EXTENSIONS.filter((ext) => !t.present[ext]);
+                if (missing.length === 0)
+                    continue;
+                const have = TRIPLET_EXTENSIONS.filter((ext) => t.present[ext]);
+                const file = t.present[have[0]];
+                const lonePak = have.length === 1 && have[0] === ".pak";
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file,
+                    message: lonePak
+                        ? `${t.stem}.pak in "${d.sourceId}" has no ${t.stem}.utoc or ${t.stem}.ucas beside it; on this IoStore-only game a legacy pak mounts and delivers nothing.`
+                        : `${t.stem} in "${d.sourceId}" is missing ${missing.join(" and ")}; the game needs the .pak, .utoc and .ucas together (the .utoc describes the container, the .ucas holds the data).`,
+                    fix: lonePak ? "Convert the pak with `retoc to-zen` (targeting UE5_6) so the .utoc/.ucas pair is produced, and ship all three." : "Ship the whole triplet the packaging step produced; nothing in it is optional.",
+                    evidence: TRIPLET_EVIDENCE,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const nameAgreement = {
+    id: "subnautica2.logicmods.name-agreement",
+    game: "subnautica2",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "In LogicMods/<Mod>/ the packed files are <Mod>.pak/.utoc/.ucas, named after the folder as the modkit's README requires; a folder with a differently named triplet, or with none, is silently skipped.",
+    appliesTo: (target, project) => target.kind === "project" && project.sources.some((s) => s.exists && s.kind === LOGICMODS_SOURCE_KIND),
+    appliesToDescription: `the project, when it has a source of kind "${LOGICMODS_SOURCE_KIND}"`,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: NAME_EVIDENCE,
+    async run(ctx) {
+        const findings = [];
+        for (const s of ctx.project.sources) {
+            if (!s.exists || s.kind !== LOGICMODS_SOURCE_KIND)
+                continue;
+            const entries = await fs.readdir(s.absPath, { withFileTypes: true });
+            for (const e of entries) {
+                const full = path.join(s.absPath, e.name);
+                if (!e.isDirectory()) {
+                    if (TRIPLET_EXTENSIONS.includes(path.extname(e.name).toLowerCase())) {
+                        findings.push({ validatorId: this.id, severity: "block", file: full, message: `${e.name} sits directly in LogicMods source "${s.id}"; on this game LogicMods is one folder per mod (LogicMods/<Mod>/<Mod>.pak), not loose paks.`, fix: `Move it into LogicMods/${path.basename(e.name, path.extname(e.name))}/ with its .utoc and .ucas.`, evidence: NAME_EVIDENCE });
+                    }
+                    continue;
+                }
+                const triplets = await tripletsIn(full);
+                if (triplets.length === 0) {
+                    findings.push({ validatorId: this.id, severity: "warn", file: full, message: `LogicMods folder ${e.name}/ in "${s.id}" holds no .pak/.utoc/.ucas; the blueprint mod loader finds nothing to mount.`, evidence: NAME_EVIDENCE });
+                    continue;
+                }
+                for (const t of triplets) {
+                    if (t.stem.toLowerCase() === e.name.toLowerCase())
+                        continue;
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: Object.values(t.present)[0],
+                        message: `${t.stem}.* in LogicMods/${e.name}/ does not carry the folder's name; the modkit's README says the packaged files must be named after the mod folder (${e.name}.pak, ${e.name}.utoc, ${e.name}.ucas), and a rename is a silent failure.`,
+                        fix: `Rename the three files to ${e.name}.pak/.utoc/.ucas, or the folder to ${t.stem}/.`,
+                        evidence: NAME_EVIDENCE,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+function isContainerFile(ext) {
+    return (target, project) => {
+        if (target.kind !== "file" || path.extname(target.path).toLowerCase() !== ext)
+            return false;
+        return containerSources(project).some((s) => isWithin(s.absPath, target.path));
+    };
+}
+const mountPoint = {
+    id: "subnautica2.paks.mount-point",
+    game: "subnautica2",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: `A .pak's footer is readable and its index begins with the mount point ${GAME_MOUNT_POINT}, the one the shipped containers use; any other mount point mounts cleanly and resolves nothing.`,
+    appliesTo: isContainerFile(".pak"),
+    appliesToDescription: `every .pak under a "${PAKS_SOURCE_KIND}" or "${LOGICMODS_SOURCE_KIND}" source`,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: MOUNT_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        try {
+            const info = await readPakInfo(file);
+            if (info.encryptedIndex) {
+                return [{ validatorId: this.id, severity: "warn", file, message: `${name} has an encrypted index (pak version ${info.versionMajor}, ${info.versionName}), so its mount point cannot be read here; the game's own containers are unencrypted and it registers no key for a mod's.`, fix: "Repack without index encryption (repak and retoc both write unencrypted by default).", evidence: MOUNT_EVIDENCE }];
+            }
+            if (info.mountPoint === GAME_MOUNT_POINT)
+                return [];
+            return [
+                {
+                    validatorId: this.id,
+                    severity: "block",
+                    file,
+                    message: `${name} mounts at ${JSON.stringify(info.mountPoint)} (pak version ${info.versionMajor}, ${info.versionName}); the game's containers mount at ${JSON.stringify(GAME_MOUNT_POINT)}, and a pak with another mount point mounts without error and delivers files at paths nothing asks for.`,
+                    fix: `Repack with the mount point ${GAME_MOUNT_POINT} (repak's default; UnrealPak's is not).`,
+                    evidence: MOUNT_EVIDENCE,
+                },
+            ];
+        }
+        catch (err) {
+            const reason = err instanceof PakError ? err.reason : "unreadable";
+            return [{ validatorId: this.id, severity: "block", file, message: `${name} has no readable pak footer (${reason}): ${err.message}.`, fix: "The file is not a pak or is truncated; repack it.", evidence: MOUNT_EVIDENCE }];
+        }
+    },
+};
+const utocHeader = {
+    id: "subnautica2.utoc.header",
+    game: "subnautica2",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "A .utoc starts with the IoStore TOC magic and a known TOC version; a file named .utoc that does not is not a container the game can open.",
+    appliesTo: isContainerFile(".utoc"),
+    appliesToDescription: `every .utoc under a "${PAKS_SOURCE_KIND}" or "${LOGICMODS_SOURCE_KIND}" source`,
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: UTOC_EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const name = path.basename(file);
+        try {
+            const h = await readUtocHeader(file);
+            if (h.version === 0)
+                return [{ validatorId: this.id, severity: "block", file, message: `${name} carries TOC version 0 (Invalid).`, evidence: UTOC_EVIDENCE }];
+            if (h.entryCount === 0)
+                return [{ validatorId: this.id, severity: "warn", file, message: `${name} (TOC version ${h.version}, ${h.versionName}) lists no chunks; the container is empty.`, evidence: UTOC_EVIDENCE }];
+            return [];
+        }
+        catch (err) {
+            const reason = err instanceof UtocError ? err.reason : "unreadable";
+            return [{ validatorId: this.id, severity: "block", file, message: `${name} has no IoStore TOC header (${reason}): ${err.message}.`, fix: "Produce the .utoc/.ucas pair with `retoc to-zen`; a renamed or truncated file is not a container.", evidence: UTOC_EVIDENCE }];
+        }
+    },
+};
+const prioritySuffix = {
+    id: "subnautica2.paks.priority-suffix",
+    game: "subnautica2",
+    groups: ["packaging"],
+    modTypes: ["packaging"],
+    summary: "A _P suffix is Epic's patch-priority marker and is noted; a mod shipped both with and without the suffix has a dead copy; otherwise load order among ~mods paks is alphabetical, later wins.",
+    appliesTo: (target, project) => target.kind === "project" && project.sources.some((s) => s.exists && s.kind === PAKS_SOURCE_KIND),
+    appliesToDescription: `the project, when it has a source of kind "${PAKS_SOURCE_KIND}"`,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: PRIORITY_EVIDENCE,
+    async run(ctx) {
+        const findings = [];
+        for (const s of ctx.project.sources) {
+            if (!s.exists || s.kind !== PAKS_SOURCE_KIND)
+                continue;
+            const triplets = await tripletsIn(s.absPath);
+            const stems = new Set(triplets.map((t) => t.stem.toLowerCase()));
+            for (const t of triplets) {
+                if (!hasPrioritySuffix(t.stem))
+                    continue;
+                const file = Object.values(t.present)[0];
+                const bare = t.stem.slice(0, -2);
+                if (stems.has(bare.toLowerCase())) {
+                    findings.push({ validatorId: this.id, severity: "warn", file, message: `${t.stem} and ${bare} are both in "${s.id}"; the _P copy takes priority and the other is a dead duplicate.`, fix: "Ship one of them.", evidence: PRIORITY_EVIDENCE });
+                }
+                else {
+                    findings.push({ validatorId: this.id, severity: "info", file, message: `${t.stem} carries the _P suffix, which the engine's mounting system uses to give it priority over other paks regardless of name order.`, evidence: PRIORITY_EVIDENCE });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const UE4SS_SHARED = "shared";
+const ue4ssModShape = {
+    id: "subnautica2.ue4ss.mod-shape",
+    game: "subnautica2",
+    groups: ["packaging"],
+    modTypes: ["packaging", "gameplay-tweak"],
+    summary: "Each UE4SS mod folder has scripts/main.lua or dlls/main.dll, and is enabled by a mods.txt line (or an enabled.txt); a mods.txt entry with no folder does nothing.",
+    appliesTo: (target, project) => target.kind === "project" && project.sources.some((s) => s.exists && s.kind === UE4SS_SOURCE_KIND),
+    appliesToDescription: `the project, when it has a source of kind "${UE4SS_SOURCE_KIND}"`,
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: UE4SS_EVIDENCE,
+    async run(ctx) {
+        const findings = [];
+        for (const s of ctx.project.sources) {
+            if (!s.exists || s.kind !== UE4SS_SOURCE_KIND)
+                continue;
+            const modsTxt = path.join(s.absPath, "mods.txt");
+            const listed = new Map();
+            const hasModsTxt = await pathExists(modsTxt);
+            if (hasModsTxt) {
+                const text = await ctx.readText(modsTxt);
+                text.split(/\r?\n/).forEach((raw, i) => {
+                    const line = raw.trim();
+                    if (!line || line.startsWith(";") || line.startsWith("#"))
+                        return;
+                    const m = /^([^:]+?)\s*:\s*([01])\s*$/.exec(line);
+                    if (!m) {
+                        findings.push({ validatorId: this.id, severity: "warn", file: modsTxt, line: i + 1, message: `mods.txt line ${i + 1} is not "ModName : 1" or "ModName : 0": "${line}".`, evidence: UE4SS_EVIDENCE });
+                        return;
+                    }
+                    listed.set(m[1].toLowerCase(), { name: m[1], enabled: m[2] === "1" });
+                });
+            }
+            const entries = await fs.readdir(s.absPath, { withFileTypes: true });
+            const folders = entries.filter((e) => e.isDirectory() && e.name.toLowerCase() !== UE4SS_SHARED);
+            for (const [key, { name, enabled }] of listed) {
+                if (!folders.some((f) => f.name.toLowerCase() === key)) {
+                    findings.push({ validatorId: this.id, severity: enabled ? "warn" : "info", file: modsTxt, message: `mods.txt ${enabled ? "enables" : "lists"} "${name}", and no folder of that name exists in "${s.id}"; UE4SS loads nothing for it.`, evidence: UE4SS_EVIDENCE });
+                }
+            }
+            for (const f of folders) {
+                const dir = path.join(s.absPath, f.name);
+                const inner = await fs.readdir(dir, { withFileTypes: true });
+                const lower = new Map(inner.map((i) => [i.name.toLowerCase(), i]));
+                const hasLua = lower.get("scripts")?.isDirectory() && (await pathExists(path.join(dir, lower.get("scripts").name, "main.lua")));
+                const hasDll = lower.get("dlls")?.isDirectory() && (await pathExists(path.join(dir, lower.get("dlls").name, "main.dll")));
+                if (!hasLua && !hasDll) {
+                    findings.push({ validatorId: this.id, severity: "warn", file: dir, message: `UE4SS mod folder ${f.name}/ in "${s.id}" has neither scripts/main.lua nor dlls/main.dll; the loader finds no entry point.`, fix: "A Lua mod needs scripts/main.lua; a C++ mod needs dlls/main.dll.", evidence: UE4SS_EVIDENCE });
+                }
+                const entry = listed.get(f.name.toLowerCase())?.enabled;
+                const enabledTxt = lower.has("enabled.txt");
+                if (entry === undefined && !enabledTxt) {
+                    findings.push({ validatorId: this.id, severity: "warn", file: dir, message: `UE4SS mod folder ${f.name}/ in "${s.id}" is ${hasModsTxt ? "not listed in mods.txt" : "present but there is no mods.txt"} and has no enabled.txt, so UE4SS will not load it.`, fix: `Add "${f.name} : 1" to mods.txt.`, evidence: UE4SS_EVIDENCE });
+                }
+                else if (entry === false && !enabledTxt) {
+                    findings.push({ validatorId: this.id, severity: "info", file: dir, message: `UE4SS mod folder ${f.name}/ in "${s.id}" is disabled in mods.txt ("${f.name} : 0").`, evidence: UE4SS_EVIDENCE });
+                }
+            }
+        }
+        return findings;
+    },
+};
+export const PACKAGING_VALIDATORS = [triplet, nameAgreement, mountPoint, utocHeader, prioritySuffix, ue4ssModShape];