modwright 0.1.0

package/dist/surfaces/stardewvalley/validators/manifest.js

@@ -0,0 +1,221 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { ENTRY_DLL_RE, MANIFEST_FIELDS, parseManifest, PROJECT_VERSION_TOKEN, SEMANTIC_VERSION_RE, SEMANTIC_VERSION_RUNTIME_RE, SLUG_RE, SLUG_RUNTIME_RE, UPDATE_KEY_RE } from "../mods.js";
+const EVIDENCE = ["stardewvalley.smapi.manifest.validation-order", "stardewvalley.smapi.manifest.published-json-schema"];
+const APPLIES = "every manifest.json under a project source";
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isManifest(target, project) {
+    if (target.kind !== "file" || path.basename(target.path).toLowerCase() !== "manifest.json")
+        return false;
+    return project.sources.some((s) => s.exists && isWithin(s.absPath, target.path));
+}
+async function load(ctx, id, file) {
+    let text;
+    try {
+        text = await ctx.readText(file);
+    }
+    catch (err) {
+        return { validatorId: id, severity: "block", file, message: `manifest.json could not be read: ${err.message}`, evidence: EVIDENCE };
+    }
+    try {
+        return parseManifest(text);
+    }
+    catch (err) {
+        return { validatorId: id, severity: "block", file, message: `manifest.json is not valid JSON: ${err.message}; SMAPI reports the mod as "parsing its manifest failed".`, fix: "Check it at smapi.io/json with the Manifest format.", evidence: EVIDENCE };
+    }
+}
+const isFinding = (v) => v.validatorId !== undefined;
+const str = (v) => (typeof v === "string" ? v : undefined);
+const blank = (v) => typeof v !== "string" || v.trim().length === 0;
+function rule(id, summary, severity, evidence, run) {
+    const ownsParseFailure = id === "parses";
+    return {
+        id: `stardewvalley.manifest.${id}`,
+        game: "stardewvalley",
+        groups: ["packaging"],
+        modTypes: ["packaging"],
+        summary,
+        appliesTo: isManifest,
+        appliesToDescription: APPLIES,
+        needs: { project: true },
+        cost: "edit",
+        severity,
+        evidence,
+        async run(ctx) {
+            if (ctx.target.kind !== "file")
+                return [];
+            const m = await load(ctx, this.id, ctx.target.path);
+            if (isFinding(m))
+                return ownsParseFailure ? [m] : [];
+            return run(ctx, m, ctx.target.path, this.id);
+        },
+    };
+}
+const parses = rule("parses", "manifest.json parses as a JSON object (SMAPI's reader accepts comments and trailing commas; ModWright does too). The one rule that reports an unreadable or unparseable manifest; the rest stay quiet, since this one blocks.", "block", EVIDENCE, () => []);
+const requiredFields = rule("required-fields", "Name, UniqueID and Version are present (SMAPI: 'manifest is missing required fields'), with Version = \"0.0.0\" counting as missing; Author and Description, which only the schema requires, warn.", "block", [...EVIDENCE, "stardewvalley.smapi.manifest.version-zero-counts-as-missing"], (_ctx, m, file, rid) => {
+    const missing = [];
+    if (blank(m.Name))
+        missing.push("Name");
+    const version = str(m.Version);
+    if (m.Version === undefined || m.Version === null || version === "0.0.0")
+        missing.push("Version");
+    if (blank(m.UniqueID))
+        missing.push("UniqueID");
+    const findings = [];
+    if (missing.length > 0) {
+        findings.push({
+            validatorId: rid,
+            severity: "block",
+            file,
+            message: `manifest is missing required fields (${missing.join(", ")})${version === "0.0.0" ? "; SMAPI treats Version \"0.0.0\" as absent" : ""}.`,
+            fix: "Set the field; the mod is not loaded without it.",
+            evidence: EVIDENCE,
+        });
+    }
+    for (const f of ["Author", "Description"]) {
+        if (blank(m[f]))
+            findings.push({ validatorId: rid, severity: "warn", file, message: `manifest has no ${f}; SMAPI loads the mod, but the published schema (and smapi.io/json) requires it, and the log's mod list shows it.`, evidence: EVIDENCE });
+    }
+    return findings;
+});
+const entryOrContentPack = rule("entry-or-content-pack", "Exactly one of EntryDll (a C# mod) and ContentPackFor (a content pack) is set; ContentPackFor carries its UniqueID; EntryDll is a plain .dll file name.", "block", [...EVIDENCE, "stardewvalley.smapi.manifest.entrydll-xor-contentpackfor", "stardewvalley.smapi.manifest.contentpackfor-shape"], (_ctx, m, file, rid) => {
+    const hasDll = !blank(m.EntryDll);
+    const cpf = m.ContentPackFor;
+    const hasCpf = cpf !== undefined && cpf !== null;
+    const findings = [];
+    if (hasDll && hasCpf)
+        findings.push({ validatorId: rid, severity: "block", file, message: "manifest sets both EntryDll and ContentPackFor, which are mutually exclusive.", fix: "A C# mod keeps EntryDll; a content pack keeps ContentPackFor.", evidence: EVIDENCE });
+    else if (!hasDll && !hasCpf)
+        findings.push({ validatorId: rid, severity: "block", file, message: "manifest has no EntryDll or ContentPackFor field; must specify one.", fix: 'A content pack for Content Patcher uses "ContentPackFor": { "UniqueID": "Pathoschild.ContentPatcher" }.', evidence: EVIDENCE });
+    if (hasCpf) {
+        const uid = cpf && typeof cpf === "object" ? cpf.UniqueID : undefined;
+        if (blank(uid))
+            findings.push({ validatorId: rid, severity: "block", file, message: "manifest declares ContentPackFor without its required UniqueID field.", evidence: EVIDENCE });
+        else if (!SLUG_RE.test(uid))
+            findings.push({ validatorId: rid, severity: "block", file, message: `ContentPackFor.UniqueID "${uid}" is not a valid mod id (letters, numbers, underscores, periods, or hyphens).`, evidence: EVIDENCE });
+    }
+    if (hasDll) {
+        const dll = str(m.EntryDll);
+        if (/[<>:"/\\|?*\u0000-\u001f]/.test(dll))
+            findings.push({ validatorId: rid, severity: "block", file, message: `manifest has invalid filename '${dll}' for the EntryDll field.`, evidence: EVIDENCE });
+        else if (!ENTRY_DLL_RE.test(dll))
+            findings.push({ validatorId: rid, severity: "warn", file, message: `EntryDll "${dll}" does not match the schema's pattern (a bare file name ending in .dll); SMAPI resolves it relative to the mod folder.`, evidence: EVIDENCE });
+    }
+    return findings;
+});
+const entryDllExists = rule("entrydll-exists", "The file EntryDll names exists in the mod folder; SMAPI skips the mod with \"its DLL '...' doesn't exist\" otherwise.", "block", [...EVIDENCE, "stardewvalley.smapi.manifest.entrydll-must-exist"], async (ctx, m, file, rid) => {
+    const dll = str(m.EntryDll);
+    if (!dll || dll.trim().length === 0 || /[<>:"/\\|?*]/.test(dll))
+        return [];
+    const target = path.join(path.dirname(file), dll);
+    if (await ctx.exists(target))
+        return [];
+    let csproj = false;
+    try {
+        csproj = (await fs.readdir(path.dirname(file))).some((n) => n.toLowerCase().endsWith(".csproj"));
+    }
+    catch {
+        csproj = false;
+    }
+    if (csproj) {
+        return [{ validatorId: rid, severity: "info", file, message: `EntryDll names "${dll}", which is not beside this manifest; a .csproj is, so the DLL is the build's output and SMAPI reads the deployed copy (the build package assembles that folder, manifest.json beside the DLL, when it deploys or zips), not this folder.`, evidence: EVIDENCE }];
+    }
+    return [
+        {
+            validatorId: rid,
+            severity: "block",
+            file,
+            message: `EntryDll names "${dll}", and ${target} does not exist; SMAPI skips the mod because its DLL '${dll}' doesn't exist.`,
+            fix: "Build the mod (the DLL is the build's output), or correct EntryDll to the built file's name.",
+            evidence: EVIDENCE,
+            related: [target],
+        },
+    ];
+});
+const uniqueId = rule("uniqueid", "UniqueID is a slug: letters, numbers, underscores, periods or hyphens (PathUtilities.IsSlug); reverse-domain form is the convention.", "block", [...EVIDENCE, "stardewvalley.smapi.manifest.uniqueid-format"], (_ctx, m, file, rid) => {
+    const id = str(m.UniqueID);
+    if (id === undefined || id.trim().length === 0 || SLUG_RE.test(id))
+        return [];
+    if (SLUG_RUNTIME_RE.test(id))
+        return [{ validatorId: rid, severity: "warn", file, message: `UniqueID "${id}" uses letters outside ASCII; SMAPI's IsSlug accepts any Unicode letter, so the mod loads, but the published schema (and smapi.io/json) rejects it and other mods' tooling may too.`, fix: "Prefer ASCII: YourName.YourProjectName.", evidence: EVIDENCE }];
+    return [{ validatorId: rid, severity: "block", file, message: `manifest specifies an invalid ID "${id}" (IDs must only contain letters, numbers, underscores, periods, or hyphens).`, fix: "Use YourName.YourProjectName.", evidence: EVIDENCE }];
+});
+const version = rule("version", `Version is a semantic version as SMAPI parses it (major.minor[.patch][-prerelease]) or the literal ${PROJECT_VERSION_TOKEN} the build package substitutes.`, "block", [...EVIDENCE, "stardewvalley.smapi.manifest.semantic-version-pattern", "stardewvalley.smapi.manifest.project-version-token"], (_ctx, m, file, rid) => {
+    const v = m.Version;
+    if (v === undefined || v === null)
+        return [];
+    if (typeof v !== "string")
+        return [{ validatorId: rid, severity: "block", file, message: `Version is ${JSON.stringify(v)}, not a string.`, evidence: EVIDENCE }];
+    if (v === PROJECT_VERSION_TOKEN || v === "0.0.0" || SEMANTIC_VERSION_RE.test(v))
+        return [];
+    if (SEMANTIC_VERSION_RUNTIME_RE.test(v))
+        return [{ validatorId: rid, severity: "warn", file, message: `Version "${v}" carries build metadata (+...); SMAPI's SemanticVersionReader parses it and the mod loads, but the published schema (and smapi.io/json) rejects it.`, fix: 'Drop the +metadata; use e.g. "1.0.0" or "1.2.0-beta.1".', evidence: EVIDENCE }];
+    return [{ validatorId: rid, severity: "block", file, message: `Version "${v}" is not a semantic version SMAPI accepts (major.minor[.patch][-prerelease], no build metadata).`, fix: 'Use e.g. "1.0.0" or "1.2.0-beta.1".', evidence: EVIDENCE }];
+});
+const dependencies = rule("dependencies", "Every Dependencies entry is an object with a slug UniqueID, an optional MinimumVersion that parses, and an optional boolean IsRequired.", "block", [...EVIDENCE, "stardewvalley.smapi.manifest.dependencies-shape"], (_ctx, m, file, rid) => {
+    if (m.Dependencies === undefined || m.Dependencies === null)
+        return [];
+    if (!Array.isArray(m.Dependencies))
+        return [{ validatorId: rid, severity: "block", file, message: "Dependencies is not a list.", evidence: EVIDENCE }];
+    const findings = [];
+    m.Dependencies.forEach((d, i) => {
+        if (!d || typeof d !== "object") {
+            findings.push({ validatorId: rid, severity: "block", file, message: `manifest has a null or non-object dependency at index ${i}.`, evidence: EVIDENCE });
+            return;
+        }
+        const r = d;
+        if (blank(r.UniqueID))
+            findings.push({ validatorId: rid, severity: "block", file, message: `manifest dependency ${i + 1} has no UniqueID.`, evidence: EVIDENCE });
+        else if (!SLUG_RE.test(r.UniqueID))
+            findings.push({ validatorId: rid, severity: "block", file, message: `manifest dependency "${r.UniqueID}" is not a valid mod id (letters, numbers, underscores, periods, or hyphens).`, evidence: EVIDENCE });
+        if (r.MinimumVersion !== undefined && (typeof r.MinimumVersion !== "string" || !SEMANTIC_VERSION_RE.test(r.MinimumVersion)))
+            findings.push({ validatorId: rid, severity: "block", file, message: `dependency "${r.UniqueID}" has MinimumVersion ${JSON.stringify(r.MinimumVersion)}, not a semantic version.`, evidence: EVIDENCE });
+        if (r.IsRequired !== undefined && typeof r.IsRequired !== "boolean")
+            findings.push({ validatorId: rid, severity: "warn", file, message: `dependency "${r.UniqueID}" has IsRequired ${JSON.stringify(r.IsRequired)}; it is a boolean (optional dependencies are loaded first when installed, ignored otherwise).`, evidence: EVIDENCE });
+    });
+    return findings;
+});
+const updateKeys = rule("update-keys", "Each UpdateKeys entry is Site:ID (Nexus, ModDrop, CurseForge, Chucklefish) or GitHub:owner/repo, with an optional @subkey; none at all is noted, since SMAPI's own 'No update keys' warning group lists such mods.", "warn", [...EVIDENCE, "stardewvalley.smapi.manifest.update-keys", "stardewvalley.smapi.manifest.update-subkeys"], (_ctx, m, file, rid) => {
+    const keys = m.UpdateKeys;
+    if (keys === undefined || keys === null || (Array.isArray(keys) && keys.length === 0)) {
+        return [{ validatorId: rid, severity: "info", file, message: "manifest has no UpdateKeys, so SMAPI cannot tell players about updates (its 'No update keys' warning group will list the mod).", fix: 'Add e.g. "UpdateKeys": ["Nexus:1234"] once the mod has a page.', evidence: EVIDENCE }];
+    }
+    if (!Array.isArray(keys))
+        return [{ validatorId: rid, severity: "warn", file, message: "UpdateKeys is not a list.", evidence: EVIDENCE }];
+    const findings = [];
+    for (const k of keys) {
+        if (typeof k !== "string" || !UPDATE_KEY_RE.test(k))
+            findings.push({ validatorId: rid, severity: "warn", file, message: `UpdateKeys entry ${JSON.stringify(k)} is not Chucklefish:ID, Nexus:ID, GitHub:owner/repo, ModDrop:ID or CurseForge:ID (optionally @subkey); SMAPI's update check ignores it.`, evidence: EVIDENCE });
+    }
+    return findings;
+});
+const extraFields = rule("extra-fields", "Fields outside the manifest's declared set are noted, including a mis-cased known field: SMAPI keeps the unknown ones in ExtraFields (legal), while the published schema's additionalProperties: false rejects them at smapi.io/json; the runtime is authoritative, so all of it is info.", "info", [...EVIDENCE, "stardewvalley.smapi.manifest.fields"], (_ctx, m, file, rid) => {
+    const extras = Object.keys(m.extraFields);
+    if (extras.length === 0)
+        return [];
+    const knownLower = new Map(MANIFEST_FIELDS.map((f) => [f.toLowerCase(), f]));
+    const miscased = extras.filter((e) => knownLower.has(e.toLowerCase()));
+    const findings = [];
+    for (const e of miscased) {
+        findings.push({ validatorId: rid, severity: "info", file, message: `manifest field "${e}" is not "${knownLower.get(e.toLowerCase())}"; SMAPI's JSON reader still binds it to the known field, but the published schema is case-sensitive, so spell it as documented.`, evidence: EVIDENCE });
+    }
+    const other = extras.filter((e) => !knownLower.has(e.toLowerCase()));
+    if (other.length > 0)
+        findings.push({ validatorId: rid, severity: "info", file, message: `manifest has fields SMAPI does not define (${other.join(", ")}); they land in ExtraFields and are ignored, but smapi.io/json's schema rejects them.`, evidence: EVIDENCE });
+    return findings;
+});
+const minimumVersions = rule("minimum-versions", "MinimumApiVersion and MinimumGameVersion, when set, are semantic versions; SMAPI refuses the mod with 'it needs SMAPI x or later' / 'it needs Stardew Valley x or later' when they exceed the running versions.", "block", [...EVIDENCE, "stardewvalley.smapi.manifest.minimum-versions"], (_ctx, m, file, rid) => {
+    const findings = [];
+    for (const f of ["MinimumApiVersion", "MinimumGameVersion"]) {
+        const v = m[f];
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v !== "string" || !SEMANTIC_VERSION_RE.test(v))
+            findings.push({ validatorId: rid, severity: "block", file, message: `${f} ${JSON.stringify(v)} is not a semantic version.`, evidence: EVIDENCE });
+    }
+    return findings;
+});
+export const MANIFEST_VALIDATORS = [parses, requiredFields, entryOrContentPack, entryDllExists, uniqueId, version, minimumVersions, dependencies, updateKeys, extraFields];

package/dist/surfaces/subnautica2/compat.js

@@ -0,0 +1,138 @@
+import * as path from "node:path";
+import { readPeFileVersion } from "../../core/compat/pe.js";
+import { localAppData, pathExists, readTextIfExists } from "../../core/fsutil.js";
+import { SIGNATURES } from "./logs.js";
+const WIN64 = ["Subnautica2", "Binaries", "Win64"];
+const SHIPPING_EXE = "Subnautica2-Win64-Shipping.exe";
+export function versionsFromLog(text) {
+    const engine = SIGNATURES.find((s) => s.id === "subnautica2.unreal.engine-version");
+    const project = SIGNATURES.find((s) => s.id === "subnautica2.unreal.project-version");
+    const out = {};
+    for (const line of text.split(/\r?\n/, 4000)) {
+        if (out.engine === undefined) {
+            const m = engine.pattern.exec(line);
+            if (m?.groups) {
+                out.engine = m.groups.engine;
+                out.changelist = m.groups.changelist;
+            }
+        }
+        if (out.projectVersion === undefined) {
+            const m = project.pattern.exec(line);
+            if (m?.groups)
+                out.projectVersion = m.groups.version;
+        }
+        if (out.engine !== undefined && out.projectVersion !== undefined)
+            break;
+    }
+    return out;
+}
+export function defaultLogPath() {
+    return localAppData("Subnautica2", "Saved", "Logs", "Subnautica2.log");
+}
+export async function detectComponentsWith(install, options = {}) {
+    const win64 = path.join(install.root, ...WIN64);
+    const exe = path.join(win64, SHIPPING_EXE);
+    const exeExists = await pathExists(exe);
+    const logPath = options.logPath === undefined ? defaultLogPath() : options.logPath;
+    const logText = logPath ? await readTextIfExists(logPath) : undefined;
+    const fromLog = logText ? versionsFromLog(logText) : {};
+    let peVersion;
+    if (exeExists && !install.version && !fromLog.projectVersion) {
+        try {
+            peVersion = await readPeFileVersion(exe);
+        }
+        catch {
+            peVersion = undefined;
+        }
+    }
+    const gameVersion = install.version ?? fromLog.projectVersion ?? peVersion;
+    const gameSource = install.version ? "install record" : fromLog.projectVersion ? `${logPath}: LogNetVersion: Set ProjectVersion (with changelist ${fromLog.changelist ?? "unknown"})` : peVersion ? `${SHIPPING_EXE} PE file version (the ProjectVersion is preferred when a log exists)` : "no log and no readable executable";
+    const components = [
+        { id: "game", label: "Subnautica 2", kind: "game", installed: exeExists, ...(gameVersion !== undefined ? { version: gameVersion } : {}), source: gameSource, path: exe },
+        {
+            id: "engine",
+            label: "Unreal Engine",
+            kind: "framework",
+            installed: exeExists,
+            ...(fromLog.engine !== undefined ? { version: fromLog.engine } : {}),
+            source: fromLog.engine ? `${logPath}: LogInit: Engine Version` : "the game log's LogInit: Engine Version line, not found",
+        },
+    ];
+    const proxy = path.join(win64, "dwmapi.dll");
+    const experimentalDll = path.join(win64, "ue4ss", "UE4SS.dll");
+    const stableDll = path.join(win64, "UE4SS.dll");
+    const hasProxy = await pathExists(proxy);
+    const hasExperimental = await pathExists(experimentalDll);
+    const hasStable = await pathExists(stableDll);
+    components.push({
+        id: "ue4ss",
+        label: "UE4SS",
+        kind: "loader",
+        installed: hasProxy || hasExperimental || hasStable,
+        source: hasExperimental ? "ue4ss/UE4SS.dll beside the executable (the experimental layout); its version is not read, since the release is a rolling tag" : hasStable ? "UE4SS.dll directly beside the executable (the stable 3.0.x layout)" : hasProxy ? "dwmapi.dll proxy beside the executable, with no UE4SS.dll found" : "no dwmapi.dll proxy or UE4SS.dll beside the executable",
+        ...(hasExperimental ? { path: experimentalDll } : hasStable ? { path: stableDll } : hasProxy ? { path: proxy } : {}),
+    });
+    components.push({ id: "ue4ss-stable-layout", label: "UE4SS in the stable 3.0.x layout", kind: "loader", installed: hasStable && !hasExperimental, source: "UE4SS.dll directly under Binaries/Win64 with no ue4ss/ folder" });
+    components.push({ id: "ue4ss-proxy-only", label: "dwmapi.dll proxy with no UE4SS.dll", kind: "loader", installed: hasProxy && !hasExperimental && !hasStable, source: "dwmapi.dll present, neither UE4SS.dll location exists" });
+    return components;
+}
+export const RULES = [
+    {
+        id: "sn2-ue4ss-needs-experimental",
+        game: "subnautica2",
+        component: "ue4ss",
+        requires: [],
+        advisory: true,
+        severity: "warn",
+        note: "Unreal 5.6 support exists only in UE4SS's experimental-latest prerelease, a rolling build under a fixed tag; the latest tagged stable (v3.0.1, 2025-02-14) tops out at UE 5.3, so a UE4SS taken from the stable release will not work here and no version can be pinned.",
+        source: "https://github.com/UE4SS-RE/RE-UE4SS/releases/tag/experimental-latest",
+    },
+    {
+        id: "sn2-ue4ss-stable-layout",
+        game: "subnautica2",
+        component: "ue4ss-stable-layout",
+        requires: [],
+        advisory: true,
+        severity: "block",
+        note: "UE4SS.dll sits directly beside the executable, which is the stable 3.0.x layout; the experimental builds that support Unreal 5.6 keep everything but the proxy under a ue4ss/ subfolder, so this is almost certainly a stable build that cannot run this game.",
+        source: "experimental-latest release notes: 'All UE4SS files ... now reside in a ue4ss subfolder next to your game executable'",
+    },
+    {
+        id: "sn2-ue4ss-proxy-without-dll",
+        game: "subnautica2",
+        component: "ue4ss-proxy-only",
+        requires: [],
+        advisory: true,
+        severity: "block",
+        note: "A dwmapi.dll proxy is beside the executable but no UE4SS.dll is in either layout; the proxy loads nothing and every UE4SS mod is inert.",
+        source: "https://docs.ue4ss.com/dev/installation-guide.html",
+    },
+    {
+        id: "sn2-mods-break-every-patch",
+        game: "subnautica2",
+        component: "ue4ss",
+        requires: [{ component: "game" }],
+        advisory: true,
+        severity: "warn",
+        versionGate: "game",
+        undeterminedSeverity: "warn",
+        note: "Every Subnautica 2 patch can break mods, and the developer's own hotfix notes tell players to disable mods before launching; with a roughly six-week cadence this is the steady state, so re-verify mods after each update.",
+        source: "https://unknownworlds.com/en/news/subnautica-2-buddy-system-hotfix-1",
+    },
+    {
+        id: "sn2-engine-version-drives-tooling",
+        game: "subnautica2",
+        component: "engine",
+        requires: [],
+        advisory: true,
+        severity: "info",
+        versionGate: "engine",
+        undeterminedSeverity: "info",
+        note: "The engine version (5.6.1 on the launch build) is the input to every tool choice: which UE4SS build, retoc's --version target (UE5_6), FModel's UE Version setting, and which mappings file matches.",
+        source: "local Subnautica2.log 'LogInit: Engine Version: 5.6.1-113109+++Project+SN2-Release-Hotfix-Live'",
+    },
+];
+export const subnautica2Compat = {
+    detectComponents: (install) => detectComponentsWith(install),
+    rules: RULES,
+};

package/dist/surfaces/subnautica2/index.js

@@ -0,0 +1,5 @@
+export { subnautica2, PROJECT_DIR, SHIPPING_EXE } from "./surface.js";
+export { SIGNATURES } from "./logs.js";
+export { subnautica2Compat, detectComponentsWith, versionsFromLog } from "./compat.js";
+export { readPakFooter, readPakInfo, parsePakFooter, parseFString, readUtocHeader, parseUtocHeader, tripletsIn, hasPrioritySuffix, GAME_MOUNT_POINT, PAK_MAGIC, UTOC_MAGIC } from "./paks.js";
+export { PACKAGING_VALIDATORS } from "./validators/packaging.js";

package/dist/surfaces/subnautica2/logs.js

@@ -0,0 +1,129 @@
+const FIXTURE = "test/fixtures/logs/subnautica2/real/Subnautica2.head.log";
+const PRE = String.raw `^(?:\[\d{4}\.\d{2}\.\d{2}-\d{2}\.\d{2}\.\d{2}:\d{3}\]\[\s*\d+\])?`;
+function re(body) {
+    return new RegExp(PRE + body);
+}
+export const SIGNATURES = [
+    {
+        id: "subnautica2.unreal.engine-version",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "version",
+        pattern: re(String.raw `LogInit: Engine Version: (?<engine>\d+\.\d+\.\d+)-(?<changelist>\d+)\+\+\+(?<branch>\S+)`),
+        explain: "The Unreal Engine point release and changelist the build runs on; UE4SS support is decided by this line.",
+        seenIn: [FIXTURE],
+        extract: ["engine", "changelist", "branch"],
+    },
+    {
+        id: "subnautica2.uwe.changelist",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "version",
+        pattern: re(String.raw `LogUWE: Changelist: (?<changelist>\d+)`),
+        explain: "The game's own changelist; mods break across these, and the developer says so.",
+        seenIn: [FIXTURE],
+        extract: ["changelist"],
+    },
+    {
+        id: "subnautica2.unreal.project-version",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "version",
+        pattern: re(String.raw `LogNetVersion: Set ProjectVersion to (?<version>\d+(?:\.\d+)*)`),
+        explain: "The project version the network layer checks; two builds with different versions will not play together.",
+        seenIn: [FIXTURE],
+        extract: ["version"],
+    },
+    {
+        id: "subnautica2.unreal.toc-loaded",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `LogIoDispatcher: Display: Toc loaded : (?<toc>\S+), Id=(?<id>[0-9a-f]+), Order=(?<order>\d+), EntryCount=(?<entries>\d+)`),
+        explain: "An IoStore table of contents was read: which .utoc, at what order, with how many entries. A mod's .utoc appears here or it did not mount.",
+        seenIn: [FIXTURE],
+        extract: ["toc", "order", "entries"],
+    },
+    {
+        id: "subnautica2.unreal.container-mounted",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "success",
+        pattern: re(String.raw `LogPakFile: Display: Mounted IoStore container "(?<container>[^"]+)"`),
+        explain: "An IoStore container mounted; the game's own and any mod's.",
+        seenIn: [FIXTURE],
+        extract: ["container"],
+    },
+    {
+        id: "subnautica2.unreal.pak-mounted",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `LogPakFile: Display: Mounted Pak file '(?<pak>[^']+)', mount point: '(?<mount>[^']+)'`),
+        explain: "A .pak mounted, with its mount point; a mod pak with the wrong mount point mounts and delivers nothing.",
+        seenIn: [FIXTURE],
+        extract: ["pak", "mount"],
+    },
+    {
+        id: "subnautica2.unreal.plugin-mounted",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `LogPluginManager: Mounting (?<kind>Project|Engine) plugin (?<plugin>\S+)`),
+        explain: "An Unreal plugin mounted; a DLC-style content plugin dropped under Mods/ shows up here without any loader.",
+        seenIn: [FIXTURE],
+        extract: ["kind", "plugin"],
+    },
+    {
+        id: "subnautica2.unreal.crash-guid",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "crash",
+        pattern: re(String.raw `\s*(?:LogInit: )?Session CrashGUID >\s+(?<guid>UECC-\S+)`),
+        explain: "The session's crash GUID, printed at startup; it names the crash report folder if this session crashes.",
+        seenIn: [FIXTURE],
+        extract: ["guid"],
+    },
+    {
+        id: "subnautica2.eos.anticheat-not-available",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `LogEOSSDK: LogEOSAntiCheat: \[AntiCheatClient\] Anti-cheat client not available`),
+        explain: "The EOS anti-cheat client was not started for this launch: the bootstrapper was not used. Present in the build, inert on this launch; whether co-op engages it is unresolved.",
+        seenIn: [FIXTURE],
+    },
+    {
+        id: "subnautica2.uwe.ai-error",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "warn",
+        category: "script",
+        pattern: re(String.raw `LogUWEAI: Error: (?<message>.+)$`),
+        explain: "The game's own AI system logging an error; a clean vanilla launch prints these too, so it is noise unless a mod touches AI.",
+        seenIn: [FIXTURE],
+        extract: ["message"],
+        systemImpact: false,
+    },
+    {
+        id: "subnautica2.unreal.rhi-pipeline-error",
+        game: "subnautica2",
+        sources: ["game"],
+        severity: "warn",
+        category: "resource",
+        pattern: re(String.raw `LogRHI: Error: Failed to create (?<kind>\w+) pipeline with hash (?<hash>[0-9A-F]+)`),
+        explain: "A graphics pipeline state failed to build; driver-side noise seen on a clean vanilla run, not a mod system failing.",
+        seenIn: [FIXTURE],
+        extract: ["kind", "hash"],
+        systemImpact: false,
+    },
+];