modwright 0.1.0

package/dist/core/toolchain/specs.js

@@ -0,0 +1,351 @@
+import { homePath, localAppData } from "../fsutil.js";
+export const TOOL_SPECS = [
+    {
+        id: "divine",
+        label: "LSLib Divine (divine.exe)",
+        executables: ["divine.exe", "Divine.exe", "divine"],
+        candidates: [
+            "C:/ExportTool*/Tools/divine.exe",
+            "C:/ExportTool*/divine.exe",
+            homePath("LSLib*", "Tools", "divine.exe"),
+        ],
+        envVar: "MODWRIGHT_TOOL_DIVINE",
+        usedBy: ["baldursgate3"],
+        homepage: "https://github.com/Norbyte/lslib",
+        notes: "create-package silently writes an empty 48-byte package when any directory in the -s path " +
+            "starts with a dot (measured); stage BG3 builds outside dot-prefixed dirs. " +
+            "No CLI version flag exists (verified against Divine's CommandLineArguments.cs; " +
+            "`--version` answers `[FATAL] Unknown argument found: version.`). The PE and .NET " +
+            "assembly versions of Divine.exe and LSLib.dll are both 0.0.0.0 (measured), so " +
+            "the only version source is the ExportTool-vX.Y.Z zip name it was extracted from. " +
+            "Ships as a portable zip; no installer, no fixed path.",
+    },
+    {
+        id: "wolvenkit-cli",
+        label: "WolvenKit CLI",
+        executables: ["WolvenKit.CLI.exe", "WolvenKit.CLI"],
+        candidates: [
+            "C:/Cyberpunk2077Mod/WolvenKit.CLI/WolvenKit.CLI.exe",
+            localAppData("Programs", "WolvenKit*", "WolvenKit.CLI.exe"),
+        ],
+        envVar: "MODWRIGHT_TOOL_WOLVENKIT_CLI",
+        versionArgs: ["--version"],
+        versionPattern: /(\d+\.\d+(?:\.\d+)?)/,
+        usedBy: ["cyberpunk2077"],
+        homepage: "https://wiki.redmodding.org/wolvenkit/",
+        notes: "`--version` prints the bare version (verified on 8.20.0). " +
+            "Ships as a portable zip (WolvenKit.Console-<version>.zip), no installer, no fixed path.",
+    },
+    {
+        id: "blender",
+        label: "Blender",
+        executables: ["blender.exe", "blender"],
+        candidates: [
+            "C:/Program Files/Blender Foundation/Blender */blender.exe",
+            "C:/Program Files (x86)/Blender Foundation/Blender */blender.exe",
+            "C:/Program Files (x86)/Steam/steamapps/common/Blender/blender.exe",
+            "/usr/bin/blender",
+            "/snap/bin/blender",
+        ],
+        envVar: "MODWRIGHT_TOOL_BLENDER",
+        versionArgs: ["--version"],
+        versionPattern: /Blender\s+(\d+\.\d+(?:\.\d+)?)/,
+        usedBy: ["baldursgate3", "cyberpunk2077"],
+        homepage: "https://www.blender.org/download/",
+        notes: "`--version` output confirmed against Blender's official manual.",
+    },
+    {
+        id: "vgmstream",
+        label: "vgmstream-cli",
+        executables: ["vgmstream-cli.exe", "vgmstream-cli", "vgmstream_cli.exe", "vgmstream_cli"],
+        candidates: [
+            "C:/vgmstream/vgmstream-cli.exe",
+            homePath("vgmstream*", "vgmstream-cli.exe"),
+            "/usr/bin/vgmstream-cli",
+            "/usr/local/bin/vgmstream-cli",
+        ],
+        envVar: "MODWRIGHT_TOOL_VGMSTREAM",
+        versionArgs: ["-h"],
+        versionPattern: /vgmstream CLI decoder\s+(\S+)/,
+        usedBy: ["baldursgate3"],
+        homepage: "https://vgmstream.org/",
+        notes: "-h/-V print a version only when the binary was built with " +
+            "VGMSTREAM_VERSION set (most release builds are); a from-source build " +
+            "without it reports \"unknown version\" and this adapter reports \"unknown\".",
+    },
+    {
+        id: "sseedit",
+        label: "SSEEdit (xEdit for Skyrim SE)",
+        executables: ["SSEEdit64.exe", "SSEEdit.exe", "xEdit64.exe", "xEdit.exe"],
+        candidates: [
+            "C:/Modding/SSEEdit*/SSEEdit64.exe",
+            "C:/Modding/xEdit*/SSEEdit64.exe",
+            "C:/Games/SSEEdit*/SSEEdit64.exe",
+        ],
+        envVar: "MODWRIGHT_TOOL_SSEEDIT",
+        usedBy: ["skyrimse"],
+        homepage: "https://github.com/TES5Edit/TES5Edit",
+        notes: "No version flag is documented (the About dialog only). Unattended use: the check modes " +
+            "and `-qac -autoload <plugin> -autoexit`, whose exit code is the error/ITM/UDR count capped " +
+            "at 127. A fresh machine can still show the donation modal and a first-64-bit-start " +
+            "confirmation, so a first unattended run may hang; `-script:` with a missing path opens a " +
+            "file dialog rather than failing. The binary picks its game from its own filename, so an " +
+            "xEdit.exe that has not been renamed to SSEEdit needs `-sse`.",
+    },
+    {
+        id: "spriggit",
+        label: "Spriggit CLI",
+        executables: ["Spriggit.CLI.exe", "Spriggit.CLI", "spriggit"],
+        candidates: [homePath("Spriggit*", "Spriggit.CLI.exe"), "C:/Modding/Spriggit*/Spriggit.CLI.exe"],
+        envVar: "MODWRIGHT_TOOL_SPRIGGIT",
+        usedBy: ["skyrimse"],
+        homepage: "https://github.com/Mutagen-Modding/Spriggit",
+        notes: "Plugin <-> YAML/JSON for version control; a first-party Linux binary and a dotnet tool " +
+            "exist. No version flag documented: the `.spriggit` file and `spriggit-meta.json` record the " +
+            "package version instead. GPL-3.0: run as a tool, never linked.",
+    },
+    {
+        id: "bsarch",
+        label: "BSArch",
+        executables: ["bsarch.exe", "bsarch"],
+        candidates: ["C:/Modding/SSEEdit*/Tools/BSArchive/bsarch.exe", "C:/Modding/xEdit*/Tools/BSArchive/bsarch.exe", "C:/Games/SSEEdit*/Tools/BSArchive/bsarch.exe"],
+        envVar: "MODWRIGHT_TOOL_BSARCH",
+        usedBy: ["skyrimse"],
+        homepage: "https://github.com/TES5Edit/TES5Edit/tree/dev/Tools/BSArchive",
+        notes: "Ships inside xEdit's Tools/BSArchive. Prints `sVersion = '0.7'` in its help banner (the " +
+            "banner's argv is not sourced, so no probe is declared). Exit 1 only on an unhandled exception.",
+    },
+    {
+        id: "papyrus-compiler",
+        label: "Papyrus Compiler",
+        executables: ["PapyrusCompiler.exe"],
+        candidates: [
+            "C:/Program Files (x86)/Steam/steamapps/common/Skyrim Special Edition/Papyrus Compiler/PapyrusCompiler.exe",
+        ],
+        envVar: "MODWRIGHT_TOOL_PAPYRUS_COMPILER",
+        usedBy: ["skyrimse"],
+        homepage: "https://ck.uesp.net/wiki/Papyrus_Compiler_Reference",
+        notes: "Per-script invocation with -f=<flags> -i=<import dirs> -o=<output dir>; a version flag is " +
+            "not sourced. Lives under the game root once the Creation Kit is installed.",
+    },
+    {
+        id: "loot",
+        label: "LOOT",
+        executables: ["LOOT.exe", "loot"],
+        candidates: ["C:/Program Files/LOOT/LOOT.exe", localAppData("Programs", "LOOT", "LOOT.exe")],
+        envVar: "MODWRIGHT_TOOL_LOOT",
+        usedBy: ["skyrimse"],
+        homepage: "https://loot.github.io/",
+        notes: "`--game=\"Skyrim Special Edition\" --auto-sort` sorts and quits; the exit code is " +
+            "undocumented, and no version flag is documented on the CLI. Candidate paths are the " +
+            "installer's conventions, not verified.",
+    },
+    {
+        id: "creationkit",
+        label: "Creation Kit (Skyrim SE)",
+        executables: ["CreationKit.exe"],
+        candidates: ["C:/Program Files (x86)/Steam/steamapps/common/Skyrim Special Edition/CreationKit.exe"],
+        envVar: "MODWRIGHT_TOOL_CREATIONKIT",
+        usedBy: ["skyrimse"],
+        homepage: "https://ck.uesp.net/",
+        notes: "GUI only: detected and reported, never driven. Its PE FileVersion is the version; no CLI flag.",
+    },
+    {
+        id: "witchybnd",
+        label: "WitchyBND",
+        executables: ["WitchyBND.exe", "WitchyBND"],
+        candidates: [
+            "C:/Modding/WitchyBND*/WitchyBND.exe",
+            "C:/Games/WitchyBND*/WitchyBND.exe",
+            homePath("Downloads", "WitchyBND*", "WitchyBND.exe"),
+        ],
+        envVar: "MODWRIGHT_TOOL_WITCHYBND",
+        versionArgs: ["-v"],
+        versionPattern: /WitchyBND v(\d+(?:\.\d+)+)/,
+        usedBy: ["eldenring"],
+        homepage: "https://github.com/ividyon/WitchyBND",
+        notes: "Unpacks and repacks binders, DCX, TPF and params, and decrypts regulation.bin itself. " +
+            "Unattended use is `-p` (passive: no prompts or delays) or `-s` (silent, implies passive), " +
+            "with `-u`/`-r` pinning the direction; `-c` is recursive, not a CLI switch, and there is " +
+            "no --cli. Its round trip writes a `_witchy-<tag>.xml` sidecar the repack validates " +
+            "against. A second version axis, which no flag prints, is the newest regulation its " +
+            "bundled Paramdex can repack: Assets/Paramdex/ER/Upgrader/version.txt beside the exe. " +
+            "Its README warns against PARAM repacking for serious work; params are read-only here.",
+    },
+    {
+        id: "dsmsportable",
+        label: "DSMSPortable",
+        executables: ["DSMSPortable.exe"],
+        candidates: ["C:/Modding/DSMSPortable*/DSMSPortable.exe", homePath("Downloads", "DSMSPortable*", "DSMSPortable.exe")],
+        envVar: "MODWRIGHT_TOOL_DSMSPORTABLE",
+        usedBy: ["eldenring"],
+        homepage: "https://github.com/mountlover/DSMSPortable",
+        notes: "The one unattended param CLI: applies CSV and mass-edit scripts to regulation.bin, " +
+            "exports, diffs and upgrades params, and merges FMG/TPF/BND/HKS/EMEVD/TAE files. No " +
+            "version flag (VERSION is a literal in Program.cs, 1.9); needs the .NET 6 Desktop " +
+            "Runtime, and a negative exit code means it is missing. Its README's exit-code table " +
+            "(0 success .. 20 massedit parse error) is mapped in surfaces/eldenring/tools.ts. Last " +
+            "release 2024-07-01, absent from the community wiki's tool list: viable, not a safe default.",
+    },
+    {
+        id: "me3",
+        label: "me3 (mod loader CLI)",
+        executables: ["me3.exe", "me3"],
+        candidates: [localAppData("Programs", "me3", "bin", "me3.exe"), "C:/Program Files/me3/bin/me3.exe"],
+        envVar: "MODWRIGHT_TOOL_ME3",
+        versionArgs: ["--version"],
+        versionPattern: /me3 (\d+\.\d+\.\d+(?:[-+][\w.]+)?)/,
+        usedBy: ["eldenring"],
+        homepage: "https://github.com/garyttierney/me3",
+        notes: "The maintained loader, driven as a CLI: `me3 launch -p <profile.me3>`, `me3 info` " +
+            "(prints the profile and logs directories and whether Steam was found), " +
+            "`me3 profile create|list|show`. Candidate paths are guesses at the installer's layout, " +
+            "not verified; the installer registers .me3 files so the exe is normally on PATH.",
+    },
+    {
+        id: "dotnet",
+        label: ".NET SDK",
+        executables: ["dotnet.exe", "dotnet"],
+        candidates: ["C:/Program Files/dotnet/dotnet.exe", "/usr/bin/dotnet", "/usr/local/share/dotnet/dotnet"],
+        envVar: "MODWRIGHT_TOOL_DOTNET",
+        versionArgs: ["--version"],
+        versionPattern: /^\s*(\d+\.\d+\.\d+(?:-[\w.]+)?)/m,
+        usedBy: ["valheim", "stardewvalley", "nivalisnights"],
+        homepage: "https://dotnet.microsoft.com/download",
+        notes: "`dotnet build -c Release` compiles a BepInEx plugin (a net48 class library referencing " +
+            "BepInEx and the developer's own publicized game assemblies). `--version` prints the SDK " +
+            "version alone. Which SDK band a project needs is its global.json's business.",
+    },
+    {
+        id: "cpp2il",
+        label: "Cpp2IL",
+        executables: ["Cpp2IL.exe", "Cpp2IL"],
+        candidates: [],
+        envVar: "MODWRIGHT_TOOL_CPP2IL",
+        versionArgs: ["--version"],
+        versionPattern: /Version (\S+)/,
+        usedBy: ["nivalisnights"],
+        homepage: "https://github.com/SamboyCoding/Cpp2IL/releases",
+        notes: "Rebuilds dummy .NET assemblies from an IL2CPP game's GameAssembly.dll and global-metadata.dat. " +
+            "The Nivalis Nights index runs it with `--use-processor attributeanalyzer,attributeinjector " +
+            "--output-as dummydll`; without the attribute processors private [SerializeField] fields are " +
+            "missing and asset decoding goes wrong. It writes a Plugins folder into its " +
+            "working directory, so it is run from the cache, never from a repo. Tested: pre-release.21.",
+        managed: {
+            kind: "download",
+            version: "2022.1.0-pre-release.21",
+            license: "MIT",
+            fileName: { win32: "Cpp2IL.exe", other: "Cpp2IL" },
+            assets: [
+                { platform: "win32", arch: "x64", url: "https://github.com/SamboyCoding/Cpp2IL/releases/download/2022.1.0-pre-release.21/Cpp2IL-2022.1.0-pre-release.21-Windows.exe", sizeBytes: 15137811, sha256: "663fb432433b4371fd1ee0ebc321a8fff2a9aac5ac4230c843f9e03ddee4e04c" },
+                { platform: "win32", arch: "arm64", url: "https://github.com/SamboyCoding/Cpp2IL/releases/download/2022.1.0-pre-release.21/Cpp2IL-2022.1.0-pre-release.21-Windows-ARM64.exe", sizeBytes: 15585309, sha256: "8986f219b5992f9290cb13e1f49431756cbd8865f1cf1f5a38ba61acc27cc1fb" },
+                { platform: "linux", arch: "x64", url: "https://github.com/SamboyCoding/Cpp2IL/releases/download/2022.1.0-pre-release.21/Cpp2IL-2022.1.0-pre-release.21-Linux", sizeBytes: 17257994, sha256: "526998e593c52c029c5a6215c5c6c9f9d963706bfc409fc9ff80a95c4c500349" },
+                { platform: "linux", arch: "arm64", url: "https://github.com/SamboyCoding/Cpp2IL/releases/download/2022.1.0-pre-release.21/Cpp2IL-2022.1.0-pre-release.21-Linux-ARM64", sizeBytes: 16608573, sha256: "2d8e76b11f52fd85440ec60abf87d5c3455ea54f5104e0af51da15ba4440871b" },
+                { platform: "darwin", arch: "x64", url: "https://github.com/SamboyCoding/Cpp2IL/releases/download/2022.1.0-pre-release.21/Cpp2IL-2022.1.0-pre-release.21-OSX", sizeBytes: 16522622, sha256: "15faab020698512807f792aef32a89fe529d41d2cc03955dd3516f0519fe8f72" },
+                { platform: "darwin", arch: "arm64", url: "https://github.com/SamboyCoding/Cpp2IL/releases/download/2022.1.0-pre-release.21/Cpp2IL-2022.1.0-pre-release.21-OSX-ARM64", sizeBytes: 15719263, sha256: "6670ddb93f28d4e7f329251d2597d2abbc6ba23e46382f7ca7b5e437ec93606a" },
+            ],
+        },
+    },
+    {
+        id: "unitypy-python",
+        label: "Python with UnityPy and TypeTreeGeneratorAPI",
+        executables: ["python.exe", "python3", "python"],
+        candidates: [],
+        envVar: "MODWRIGHT_TOOL_UNITYPY_PYTHON",
+        versionArgs: ["-c", "import UnityPy, TypeTreeGeneratorAPI; print('UnityPy', UnityPy.__version__)"],
+        versionPattern: /UnityPy (\S+)/,
+        usedBy: ["nivalisnights"],
+        homepage: "https://github.com/K0lb3/UnityPy",
+        notes: "Any Python 3.8+ with `pip install UnityPy TypeTreeGeneratorAPI` (tested: UnityPy 1.25.3, " +
+            "TypeTreeGeneratorAPI 0.0.10, Python 3.14). A venv is the clean route: point " +
+            "MODWRIGHT_TOOL_UNITYPY_PYTHON at its python.exe. Runs assets/nivalisnights/extract_resources.py " +
+            "for the Nivalis Nights index.",
+        managed: {
+            kind: "python-venv",
+            version: "1.25.3",
+            license: "MIT (UnityPy, TypeTreeGeneratorAPI)",
+            pythonMin: [3, 8],
+            packages: ["UnityPy==1.25.3", "TypeTreeGeneratorAPI==0.0.10"],
+            constraints: [
+                "archspec==0.2.6", "astc-encoder-py==0.1.12", "attrs==26.1.0", "brotli==1.2.0", "etcpak==0.9.15",
+                "fmod_toolkit==0.1.3", "fsspec==2026.9.0", "lz4==4.4.5", "pillow==12.3.0", "pyfmodex==0.7.2",
+                "texture2ddecoder==1.0.6", "tpk_ar==0.2.4", "TypeTreeGeneratorAPI==0.0.10", "UnityPy==1.25.3",
+            ],
+            index: "https://pypi.org/simple",
+        },
+    },
+    {
+        id: "tcli",
+        label: "Thunderstore CLI (tcli)",
+        executables: ["tcli.exe", "tcli"],
+        candidates: [homePath(".dotnet", "tools", "tcli.exe"), homePath(".dotnet", "tools", "tcli")],
+        envVar: "MODWRIGHT_TOOL_TCLI",
+        usedBy: ["valheim"],
+        homepage: "https://github.com/thunderstore-io/thunderstore-cli",
+        notes: "Installed with `dotnet tool install -g tcli` into ~/.dotnet/tools. `tcli init|build|publish` " +
+            "over a thunderstore.toml; it assembles manifest.json and the zip and compiles nothing " +
+            "(\"any actual build actions ... must be performed separately\", tcli wiki, Building). Its own " +
+            "wiki shows `--version` on every verb and a `version` command, but the shape of that output " +
+            "was never read from a run, so nothing is probed rather than a pattern being guessed.",
+    },
+    {
+        id: "retoc",
+        label: "retoc (IoStore pack/unpack, Zen <-> Legacy)",
+        executables: ["retoc.exe", "retoc"],
+        candidates: ["C:/Modding/retoc*/retoc.exe", homePath("Downloads", "retoc*", "retoc.exe"), homePath(".cargo", "bin", "retoc.exe")],
+        envVar: "MODWRIGHT_TOOL_RETOC",
+        usedBy: ["subnautica2"],
+        homepage: "https://github.com/trumank/retoc",
+        notes: "The load-bearing tool for an IoStore game: `to-legacy` (Zen assets to a legacy pak, for " +
+            "inspection and editing) and `to-zen` (legacy pak to .utoc/.ucas the game mounts), plus " +
+            "info, list, verify, manifest, unpack, pack-raw, gen-script-objects; `--version` names the " +
+            "target engine (UE5_6 here) and `--aes-key` the key. v0.1.5 (2026-01-02). No version probe: " +
+            "not checked against the binary.",
+    },
+    {
+        id: "repak",
+        label: "repak (legacy .pak)",
+        executables: ["repak.exe", "repak"],
+        candidates: ["C:/Modding/repak*/repak.exe", homePath("Downloads", "repak*", "repak.exe"), homePath(".cargo", "bin", "repak.exe")],
+        envVar: "MODWRIGHT_TOOL_REPAK",
+        usedBy: ["subnautica2"],
+        homepage: "https://github.com/trumank/repak",
+        notes: "Legacy .pak only (versions 2-11, UE 4.0 to 5.3): info, list, hash-list, unpack, pack, get. " +
+            "Its default mount point ../../../ matches this game's. It cannot write compressed paks or " +
+            "an encrypted index, and it neither reads nor writes .utoc/.ucas, so it is the legacy half " +
+            "of a retoc pipeline. v0.2.3 (2026-01-02). No version probe: not checked against the binary.",
+    },
+    {
+        id: "uassetgui",
+        label: "UAssetGUI (UAssetAPI JSON round trip)",
+        executables: ["UAssetGUI.exe"],
+        candidates: ["C:/Modding/UAssetGUI*/UAssetGUI.exe", homePath("Downloads", "UAssetGUI*", "UAssetGUI.exe")],
+        envVar: "MODWRIGHT_TOOL_UASSETGUI",
+        usedBy: ["subnautica2"],
+        homepage: "https://github.com/atenfyr/UAssetGUI",
+        notes: "A .NET GUI with a CLI alongside it; UAssetAPI's JSON export/import is the cooked-asset " +
+            "analogue of the cr2w-json round trip and advertises binary equality. Needs a .usmap " +
+            "mappings file for a UE5 game, which only a running game can dump. As of 1.1.0 it embeds " +
+            "retoc for direct .utoc/.ucas access. No version probe: not checked against the binary.",
+    },
+    {
+        id: "stardewxnbhack",
+        label: "StardewXnbHack",
+        executables: ["StardewXnbHack.exe", "StardewXnbHack"],
+        candidates: [
+            "C:/Program Files/GOG Galaxy/Games/Stardew Valley/StardewXnbHack.exe",
+            "C:/Program Files (x86)/GOG Galaxy/Games/Stardew Valley/StardewXnbHack.exe",
+            "C:/Program Files (x86)/Steam/steamapps/common/Stardew Valley/StardewXnbHack.exe",
+            homePath(".steam", "steam", "steamapps", "common", "Stardew Valley", "StardewXnbHack"),
+            homePath("Library", "Application Support", "Steam", "steamapps", "common", "Stardew Valley", "StardewXnbHack"),
+        ],
+        envVar: "MODWRIGHT_TOOL_STARDEWXNBHACK",
+        usedBy: ["stardewvalley"],
+        homepage: "https://github.com/Pathoschild/StardewXnbHack",
+        notes: "Unpacks the game's Content/*.xnb into a 'Content (unpacked)' folder beside the game, in a " +
+            "form Content Patcher can already read; it is a second launcher for the installed game, not a " +
+            "converter, so it needs the game and lives in the game folder. It cannot repack, which is by " +
+            "design (Content Patcher edits assets in place). xnbcli is deliberately not listed: the wiki " +
+            "steers away from it.",
+    },
+];

package/dist/core/toolchain/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/userconfig.js

@@ -0,0 +1,66 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+import { userConfigDir, userDataDir } from "./home.js";
+import { planFile, planMkdir } from "./safety/index.js";
+export const USER_CONFIG_SCHEMA_VERSION = 1;
+const toolEntrySchema = z.object({
+    path: z.string().min(1),
+    installedBy: z.enum(["user", "modwright"]).default("user"),
+    version: z.string().optional(),
+    sha256: z.string().optional(),
+    source: z.string().optional(),
+    rememberedAt: z.string().optional(),
+});
+const dataEntrySchema = z.object({
+    path: z.string().min(1),
+    rememberedAt: z.string().optional(),
+});
+const userConfigSchema = z.object({
+    schemaVersion: z.literal(USER_CONFIG_SCHEMA_VERSION),
+    tools: z.record(toolEntrySchema).default({}),
+    data: z.record(dataEntrySchema).default({}),
+});
+export function emptyUserConfig() {
+    return { schemaVersion: USER_CONFIG_SCHEMA_VERSION, tools: {}, data: {} };
+}
+export async function resolveDataDir(id, envVar, options = {}) {
+    const fromEnv = (options.env ?? process.env)[envVar];
+    if (fromEnv)
+        return { path: fromEnv, source: "env" };
+    const remembered = (await loadUserConfig(options.configFile)).config.data[id];
+    return remembered ? { path: remembered.path, source: "user" } : undefined;
+}
+export function userConfigFile() {
+    return path.join(userConfigDir(), "config.json");
+}
+export async function loadUserConfig(file = userConfigFile()) {
+    let text;
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch (error) {
+        const missing = error.code === "ENOENT";
+        return { config: emptyUserConfig(), file, exists: !missing, problems: missing ? [] : [`${file} could not be read: ${error.message}`] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text.replace(/^/, ""));
+    }
+    catch (error) {
+        return { config: emptyUserConfig(), file, exists: true, problems: [`${file} is not valid JSON (${error.message}); it is ignored until fixed.`] };
+    }
+    const parsed = userConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        return { config: emptyUserConfig(), file, exists: true, problems: [`${file} does not match schemaVersion ${USER_CONFIG_SCHEMA_VERSION} (${issues}); it is ignored until fixed.`] };
+    }
+    return { config: parsed.data, file, exists: true, problems: [] };
+}
+export function userConfigWritePlan(config, purpose, file = userConfigFile()) {
+    return {
+        purpose,
+        operations: [planMkdir(path.dirname(file)), planFile(file, JSON.stringify(config, null, 2) + "\n")],
+        backupRoot: path.join(userDataDir(), "backups"),
+    };
+}

package/dist/core/validate/context.js

@@ -0,0 +1,139 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { pathExists, walk } from "../fsutil.js";
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+export function isExcludedByGlobs(res, relSource, relProject) {
+    if (res.length === 0)
+        return false;
+    const candidates = new Set();
+    for (const rel of [relSource, relProject]) {
+        if (!rel)
+            continue;
+        const parts = rel.split("/");
+        for (let i = 1; i <= parts.length; i++)
+            candidates.add(parts.slice(0, i).join("/"));
+    }
+    for (const c of candidates)
+        if (res.some((re) => re.test(c)))
+            return true;
+    return false;
+}
+export function globToRegExp(glob) {
+    return new RegExp(`^${globBody(glob.replace(/\\/g, "/"))}$`, "i");
+}
+const SEP = "[\\\\/]";
+const NOT_SEP = "[^\\\\/]";
+function globBody(g) {
+    let out = "";
+    for (let i = 0; i < g.length; i++) {
+        const c = g[i];
+        if (c === "*") {
+            if (g[i + 1] === "*") {
+                i++;
+                if (g[i + 1] === "/") {
+                    i++;
+                    out += `(?:.*${SEP})?`;
+                }
+                else if (out.endsWith(SEP) && i === g.length - 1) {
+                    out = `${out.slice(0, -SEP.length)}(?:${SEP}.*)?`;
+                }
+                else {
+                    out += ".*";
+                }
+            }
+            else {
+                out += `${NOT_SEP}*`;
+            }
+        }
+        else if (c === "/") {
+            out += SEP;
+        }
+        else if (c === "?") {
+            out += NOT_SEP;
+        }
+        else if (c === "{") {
+            const close = g.indexOf("}", i + 1);
+            if (close === -1) {
+                out += "\\{";
+                continue;
+            }
+            const alternatives = g.slice(i + 1, close).split(",");
+            out += `(?:${alternatives.map(globBody).join("|")})`;
+            i = close;
+        }
+        else if ("\\^$.|+()[]{}".includes(c)) {
+            out += `\\${c}`;
+        }
+        else {
+            out += c;
+        }
+    }
+    return out;
+}
+export function buildContext(inputs) {
+    const { project, surface, install, store, changedFiles, listFilesOverride } = inputs;
+    const textCache = new Map();
+    const existsCache = new Map();
+    function readText(absPath) {
+        let cached = textCache.get(absPath);
+        if (!cached) {
+            cached = fs.readFile(absPath, "utf8");
+            textCache.set(absPath, cached);
+        }
+        return cached;
+    }
+    function exists(absPath) {
+        let cached = existsCache.get(absPath);
+        if (!cached) {
+            cached = pathExists(absPath);
+            existsCache.set(absPath, cached);
+        }
+        return cached;
+    }
+    async function lookup(kind, params) {
+        if (!store || !surface.index) {
+            throw new Error(`ValidationContext.lookup: no vanilla index open for "${surface.id}". A validator declaring ` +
+                `needs.index is never invoked without one — this call means a rule called lookup() despite not ` +
+                `declaring that need, or the runner failed to honour it.`);
+        }
+        return surface.index.query(store, kind, params);
+    }
+    const toRelative = (absPath) => toPosix(path.relative(project.root, absPath));
+    const toAbsolute = (relPath) => path.join(project.root, relPath);
+    async function listFiles() {
+        if (listFilesOverride)
+            return listFilesOverride;
+        const excludeRes = (project.build?.exclude ?? []).map(globToRegExp);
+        const isExcluded = (abs, sourceRoot) => isExcludedByGlobs(excludeRes, sourceRoot ? toPosix(path.relative(sourceRoot, abs)) : toRelative(abs), toRelative(abs));
+        const out = [];
+        for (const source of project.sources) {
+            if (!source.exists)
+                continue;
+            let isFile;
+            try {
+                isFile = (await fs.stat(source.absPath)).isFile();
+            }
+            catch {
+                continue;
+            }
+            if (isFile) {
+                if (!isExcluded(source.absPath))
+                    out.push(source.absPath);
+                continue;
+            }
+            const walked = await walk(source.absPath, { limit: 20_000 });
+            for (const rel of walked.files) {
+                const abs = path.join(source.absPath, rel);
+                if (!isExcluded(abs, source.absPath))
+                    out.push(abs);
+            }
+        }
+        return out;
+    }
+    function forTarget(target) {
+        return { project, surface, install, store, changedFiles, target, readText, exists, lookup };
+    }
+    return { project, surface, install, store, changedFiles, listFiles, forTarget, toRelative, toAbsolute };
+}

package/dist/core/validate/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { createValidatorRegistry } from "./registry.js";
+export { buildContext, globToRegExp, isExcludedByGlobs } from "./context.js";
+export { applySuppressions, findMatchingSuppression, loadSuppressions } from "./suppressions.js";
+export { runValidators } from "./run.js";

package/dist/core/validate/registry.js

@@ -0,0 +1,58 @@
+import { idPrefixFor } from "../knowledge/facts.js";
+class DefaultValidatorRegistry {
+    byId = new Map();
+    byGame = new Map();
+    register(game, validators) {
+        const prefix = idPrefixFor(game);
+        for (const v of validators) {
+            if (this.byId.has(v.id)) {
+                throw new Error(`ValidatorRegistry.register: duplicate validator id "${v.id}". Ids are never renamed or merged — ` +
+                    `pick a new slug or fix the double registration.`);
+            }
+            if (v.game !== game) {
+                throw new Error(`ValidatorRegistry.register: validator "${v.id}" declares game "${v.game}" but was registered under "${game}".`);
+            }
+            if (!v.id.startsWith(prefix)) {
+                throw new Error(`ValidatorRegistry.register: validator id "${v.id}" does not start with "${prefix}", the id prefix ` +
+                    `game "${game}" requires ("<game>.<group>.<slug>" with the ` +
+                    `short game prefix the knowledge base and log signatures already use).`);
+            }
+        }
+        for (const v of validators)
+            this.byId.set(v.id, v);
+        const existing = this.byGame.get(game) ?? [];
+        this.byGame.set(game, [...existing, ...validators]);
+    }
+    forGame(game) {
+        return this.byGame.get(game) ?? [];
+    }
+    forGroup(group, game) {
+        return this.pool(game).filter((v) => v.groups.includes(group));
+    }
+    cheap(game) {
+        return this.pool(game).filter((v) => v.cost === "edit");
+    }
+    select(filter) {
+        let pool = this.pool(filter.game);
+        if (filter.groups && filter.groups.length > 0) {
+            const groups = new Set(filter.groups);
+            pool = pool.filter((v) => v.groups.some((g) => groups.has(g)));
+        }
+        if (filter.cheapOnly)
+            pool = pool.filter((v) => v.cost === "edit");
+        if (filter.ids && filter.ids.length > 0) {
+            const ids = new Set(filter.ids);
+            pool = pool.filter((v) => ids.has(v.id));
+        }
+        return pool;
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    pool(game) {
+        return game ? this.forGame(game) : [...this.byId.values()];
+    }
+}
+export function createValidatorRegistry() {
+    return new DefaultValidatorRegistry();
+}