modwright 0.1.0 → 0.1.2

package/dist/server.js

@@ -7,6 +7,7 @@ import { describeProject, findProjectFile, loadProject } from "./core/project/in
 import { userDataDir } from "./core/home.js";
 import { applyDataFetch, applyManagedInstall, checkToolchain, featureReadiness, locateTool, planDataFetch, planDataMemory, planManagedInstall, planToolMemory, readinessSummary, TOOL_SPECS, toolsToLocate } from "./core/toolchain/index.js";
 import { loadUserConfig } from "./core/userconfig.js";
+import { describeNeeds, isProjectTrusted, planTrust, projectTrustNeeds, trustRefusal } from "./core/trust.js";
 import { runCompat } from "./core/compat/check.js";
 import { SignatureRegistry, triageLogs } from "./core/logs/index.js";
 import { buildContext, createValidatorRegistry, runValidators } from "./core/validate/index.js";
@@ -16,7 +17,6 @@ import { armBridge, bridgeCandidateDirs, bridgeStatus, cetLogCandidates, listPen
 import { runTestPlan } from "./core/testplan/index.js";
 import { applyBuildLedgerHook, applyClaimTransition, applyDecisionRecord, applyValidateLedgerHook, checkLedger, claimsFilePath, listClaims, loadClaims, loadDecisions, saveClaims, saveDecisions, showClaim, } from "./core/ledger/index.js";
 import { IndexStore, defaultCacheDir, findLegacyIndex, indexFile, legacyIndexHint, loadKnowledge, resolveIndexFile, searchFacts, } from "./core/knowledge/index.js";
-import { pathExists as fileExists } from "./core/fsutil.js";
 import { executePlan, listBackups, restoreBackup } from "./core/safety/index.js";
 import { readTextIfExists } from "./core/fsutil.js";
 import * as path from "node:path";
@@ -368,9 +368,11 @@ server.registerTool("check_toolchain", {
         "with data=<id> fetches a data folder ModWright can fetch (Stardew Valley's wiki pages) and remembers it; " +
         "action 'remember' records a tool's path in the " +
         "per-user config so every session finds it (no environment variable, no restart); " +
-        "'forget' drops it. Both are dry-run unless mode is 'apply'.",
+        "'forget' drops it. 'trust' records a project root (projectPath) as allowed to run its own toolchain overrides and " +
+        "exec build steps; until then an applied build, convert, template extract or index build that would run them is " +
+        "refused. 'untrust' removes it. All of these are dry-run unless mode is 'apply'.",
     inputSchema: {
-        action: z.enum(["check", "remember", "forget", "install"]).default("check").describe("check (default) reports; remember/forget change the per-user config; install fetches a pinned tool into ModWright's tools folder (dry-run shows the file, source, size and sha256 first), or with data a fetchable data folder (dry-run lists every URL first)."),
+        action: z.enum(["check", "remember", "forget", "install", "trust", "untrust"]).default("check").describe("check (default) reports; remember/forget change the per-user config; trust/untrust change the trusted-projects list for projectPath; install fetches a pinned tool into ModWright's tools folder (dry-run shows the file, source, size and sha256 first), or with data a fetchable data folder (dry-run lists every URL first)."),
         game: gameArg.optional().describe("Restrict to tools used by this game (check only)."),
         projectPath: z
             .string()
@@ -380,9 +382,47 @@ server.registerTool("check_toolchain", {
         toolPath: z.string().optional().describe("remember: absolute path to the executable, or the folder that directly holds it."),
         data: z.string().optional().describe("remember/forget/install: a data folder id instead of a tool, e.g. 'valheim.jotunn' (a Jotunn checkout) or 'stardewvalley.wiki' (saved wiki pages); check_toolchain game=<id> lists the ones a game reads."),
         dataPath: z.string().optional().describe("remember with data: absolute path to that folder. install with data: where to save it (default: ModWright's per-user data folder)."),
-        mode: z.enum(["dry-run", "apply"]).default("dry-run").describe("remember/forget: dry-run shows the config change; apply writes it (backing up the old file)."),
+        mode: z.enum(["dry-run", "apply"]).default("dry-run").describe("remember/forget/trust/untrust: dry-run shows the config change; apply writes it (backing up the old file)."),
     },
 }, async ({ action, game, projectPath, tool, toolPath, data, dataPath, mode }) => {
+    if (action === "trust" || action === "untrust") {
+        if (tool || toolPath || data || dataPath)
+            return fail(`${action} takes projectPath only.`);
+        if (!projectPath)
+            return fail(`${action} needs projectPath: the mod project's modwright.json or its folder.`);
+        let resolved;
+        try {
+            resolved = await resolveProject(projectPath);
+        }
+        catch (error) {
+            return fail(`Could not load project: ${error.message}`);
+        }
+        const planned = await planTrust(action, resolved.root, resolved.project.name);
+        if (!planned.ok)
+            return fail(planned.error);
+        const report = await executePlan(planned.plan, {
+            mode,
+            confidence: { level: "high", assumptions: ["The trusted-projects list is ModWright's own file; nothing in a game or a project is touched."] },
+        });
+        const needs = projectTrustNeeds(resolved.project);
+        return json({
+            action,
+            project: resolved.project.name,
+            root: planned.root,
+            mode,
+            applied: report.applied,
+            file: planned.file,
+            runs: { exec: needs.exec, toolchain: Object.fromEntries(needs.toolchain.map((id) => [id, resolved.project.toolchain?.[id]])) },
+            ...(planned.previous ? { previous: planned.previous } : {}),
+            operations: report.operations,
+            ...(report.backupDir ? { backupDir: report.backupDir } : {}),
+            note: report.applied
+                ? action === "trust"
+                    ? `Trusted. Applied builds, converts, extracts and index builds may now run this project's exec steps and toolchain overrides.`
+                    : `No longer trusted. Its exec steps and toolchain overrides are refused until it is trusted again.`
+                : `Dry run: nothing written. Read what it runs (runs) first; repeat with mode 'apply' to ${action} it.`,
+        });
+    }
     if ((action === "remember" || action === "forget") && data) {
         if (tool)
             return fail("Give either tool or data, not both.");
@@ -501,9 +541,12 @@ server.registerTool("check_toolchain", {
     }
     let projectOverrides;
     let project;
+    let projectRoot;
     if (projectPath) {
         try {
-            project = (await loadProject(projectPath)).project;
+            const loaded = await loadProject(projectPath);
+            project = loaded.project;
+            projectRoot = loaded.root;
             projectOverrides = project.toolchain;
         }
         catch (error) {
@@ -521,11 +564,13 @@ server.registerTool("check_toolchain", {
             if (spec && !located.has(id))
                 located.set(id, await locateTool(spec, { projectOverrides, probe: "trusted", userTools: userConfig.config.tools }));
         }
-        const indexBuilt = surface.index ? await fileExists(resolveIndexFile(surface.id).file) : undefined;
+        const indexBuilt = surface.index ? await pathExists(resolveIndexFile(surface.id).file) : undefined;
         features = featureReadiness(surface, [...located.values()], { ...(project ? { project } : {}), ...(indexBuilt !== undefined ? { indexBuilt } : {}), userData: userConfig.config.data });
     }
+    const trusted = projectRoot ? await isProjectTrusted(projectRoot) : undefined;
     return json({
         game: surfaceId,
+        ...(projectRoot ? { project: { root: projectRoot, trusted, ...(trusted ? {} : { note: "Not trusted: an applied build, convert, extract or index build refuses to run its exec steps or toolchain overrides until check_toolchain action=trust." }) } } : {}),
         ...(features ? { summary: readinessSummary(features), features } : {}),
         found: tools.filter((t) => t.found).length,
         missing: tools.filter((t) => !t.found).map((t) => t.id),
@@ -686,7 +731,7 @@ function getStore(gameId, reopen = false) {
             legacyStores.set(gameId, legacy);
         else
             legacyStores.delete(gameId);
-        pending = fileExists(file).then((exists) => (exists ? IndexStore.open(file) : undefined));
+        pending = pathExists(file).then((exists) => (exists ? IndexStore.open(file) : undefined));
         stores.set(gameId, pending);
     }
     return pending;
@@ -870,7 +915,12 @@ server.registerTool("build_index", {
             const file = (await pathExists(projectPath)) && projectPath.toLowerCase().endsWith(".json") ? projectPath : await findProjectFile(projectPath);
             if (!file)
                 return fail(`No modwright.json found at or above ${projectPath}.`);
-            toolOverrides = (await loadProject(file)).project.toolchain;
+            const loaded = await loadProject(file);
+            toolOverrides = loaded.project.toolchain;
+            const used = Object.keys(toolOverrides ?? {}).filter((id) => TOOL_SPECS.find((s) => s.id === id)?.usedBy.includes(surface.id));
+            if (used.length > 0 && !(await isProjectTrusted(loaded.root))) {
+                return fail(trustRefusal(loaded.root, `its modwright.json overrides the tool path(s) for ${used.join(", ")}`));
+            }
         }
         catch (error) {
             return fail(`Could not load project for tool overrides: ${error.message}`);
@@ -881,7 +931,7 @@ server.registerTool("build_index", {
     if (legacy) {
         return json({ game: surface.id, rebuilt: false, file: legacy.file, legacyIndex: legacy.file, note: `${legacyIndexHint(surface.id, legacy)} lookup already uses it. Pass force to build a fresh index in the new location instead.` });
     }
-    if (!force && (await fileExists(file))) {
+    if (!force && (await pathExists(file))) {
         const existing = await surface.index.info(install);
         if (!existing.stale)
             return json({ ...existing, note: "Index already exists; pass force to rebuild." });
@@ -960,7 +1010,10 @@ server.registerTool("validate", {
     });
     const findings = includeInfo ? report.findings : report.findings.filter((finding) => finding.severity !== "info");
     const blockingFiles = report.findings.filter((f) => f.severity === "block" && !f.suppressedBy).map((f) => f.file);
-    const ledger = await applyValidateLedgerHook(resolved.root, blockingFiles, changedFiles, "validate");
+    const narrowed = Boolean(ids?.length) || Boolean(groups?.length) || cheapOnly;
+    const ledger = narrowed
+        ? { skipped: true, applied: [], refused: [], reason: "a run narrowed by rule, groups or cheapOnly never promotes a claim; run the full set" }
+        : await applyValidateLedgerHook(resolved.root, blockingFiles, changedFiles, "validate");
     return json({
         ...report,
         findings: findings.slice(0, 200),
@@ -1025,7 +1078,13 @@ server.registerTool("build", {
     const ledger = mode === "apply" && !result.failed && result.manifestPath
         ? await applyBuildLedgerHook(resolved.root, result.manifestPath, "build")
         : { skipped: true, applied: [], refused: [] };
-    return json({ ...result, summary, ledger });
+    let trust;
+    if (mode === "dry-run") {
+        const what = describeNeeds(projectTrustNeeds(resolved.project));
+        if (what && !(await isProjectTrusted(resolved.root)))
+            trust = { trusted: false, note: trustRefusal(resolved.root, what) };
+    }
+    return json({ ...result, summary, ledger, ...(trust ? { trust } : {}) });
 });
 const RELOAD_PATH_LIMIT = 200;
 function trimReload(reload) {
@@ -1113,13 +1172,19 @@ server.registerTool("rollback", {
         "purpose, entry count, how many of those entries are junction pointers rather than content, and total " +
         "size. With a backupId it restores that backup: dry-run by default, and every file's sha256 is re-checked " +
         "against the manifest immediately before it is written back. A junction is recreated as a junction, never " +
-        "as a copy of what it pointed at.",
+        "as a copy of what it pointed at. A restore writes only under the project and the game's detected mod roots unless " +
+        "allowOutsideRoots is set.",
     inputSchema: {
         path: z.string().optional().describe("modwright.json path or a directory to search from. Default: current directory."),
         backupId: z.string().optional().describe("The stamp naming one backup directory under .modwright/backups (from this tool's own listing). Omit to list."),
         mode: z.enum(["dry-run", "apply"]).default("dry-run").describe("dry-run reports what would be restored without writing a byte."),
+        installPath: installPathArg,
+        allowOutsideRoots: z
+            .boolean()
+            .default(false)
+            .describe("Restore entries outside the project and the game's mod roots too. Off by default: a backup that names any other path is refused whole."),
     },
-}, async ({ path: start, backupId, mode }) => {
+}, async ({ path: start, backupId, mode, installPath, allowOutsideRoots }) => {
     const resolved = await projectOrFail(start);
     if ("isError" in resolved)
         return resolved;
@@ -1141,17 +1206,30 @@ server.registerTool("rollback", {
     if (!(await pathExists(backupDir))) {
         return fail(`No backup "${backupId}" under ${backupRoot}. Call rollback with no backupId to list what is there.`);
     }
+    let confineTo;
+    let noInstall = false;
+    if (!allowOutsideRoots) {
+        const surface = getSurface(resolved.project.game);
+        const install = surface ? await resolveInstall(surface, installPath).catch(() => undefined) : undefined;
+        noInstall = !install;
+        confineTo = [resolved.root, ...(surface && install ? surface.modRoots(install).map((r) => r.path) : [])];
+    }
     try {
-        const report = await restoreBackup(backupDir, { mode });
-        return json({ ...report, backupId, backupDir });
+        const report = await restoreBackup(backupDir, { mode, ...(confineTo ? { confineTo } : {}) });
+        const operations = report.operations.map(({ op, ...rest }) => ({
+            ...rest,
+            op: "content" in op ? { kind: op.kind, path: op.path, bytes: rest.sizeBytes } : op,
+        }));
+        return json({ ...report, operations, backupId, backupDir });
     }
     catch (error) {
-        return fail(`rollback failed: ${error.message}`);
+        const hint = noInstall ? " The game's install was not detected, so only the project counts; pass installPath to add its mod roots." : "";
+        return fail(`rollback failed: ${error.message}${hint}`);
     }
 });
 server.registerTool("reload_plan", {
     title: "Classify what a set of deployed paths needs to take effect",
-    description: "Map deployed paths to a reload recommendation — hot, hot-degraded, save-reload, restart or unknown — " +
+    description: "Map deployed paths to a reload recommendation — hot, hot-degraded, save-reload, restart or unknown (none when nothing was written) — " +
         "using the project's own reload.rules first and then the per-surface table, and reduce them to the single " +
         "most conservative answer with its caveats. An unmatched path is reported as unknown ('restart to be sure'), " +
         "never promoted. ModWright never launches the game and never sends a reload command; this is a " +
@@ -1566,15 +1644,24 @@ server.registerTool("convert", {
     },
 }, async ({ conversionId, source, dest, mode, verifyRoundTrip, path: projectPath }) => {
     let overrides;
-    if (projectPath) {
+    let projectTrust;
+    let backupRoot;
+    const projectStart = projectPath ?? (path.isAbsolute(dest) ? (await findProjectFile(path.dirname(dest))) : undefined);
+    if (projectStart) {
         try {
-            overrides = (await resolveProject(projectPath)).project.toolchain;
+            const resolved = await resolveProject(projectStart);
+            backupRoot = path.join(resolved.root, ".modwright", "backups");
+            if (projectPath) {
+                overrides = resolved.project.toolchain;
+                if (overrides && Object.keys(overrides).length > 0)
+                    projectTrust = { root: resolved.root, trusted: await isProjectTrusted(resolved.root) };
+            }
         }
         catch {
         }
     }
     try {
-        const report = await runConvert(conversionId, source, dest, { mode, verifyRoundTrip, locateTool: defaultTextLocateTool(overrides, mode === "apply" ? "all" : "none") });
+        const report = await runConvert(conversionId, source, dest, { mode, verifyRoundTrip, locateTool: defaultTextLocateTool(overrides, mode === "apply" ? "all" : "none", projectTrust), ...(backupRoot ? { backupRoot } : {}) });
         return json(report);
     }
     catch (error) {
@@ -1667,7 +1754,9 @@ server.registerTool("template", {
     catch (error) {
         return fail(`Could not load project: ${error.message}`);
     }
-    const locateTool = defaultTextLocateTool(resolved.project.toolchain, action === "extract" && mode === "apply" ? "all" : action === "extract" ? "none" : "trusted");
+    const overrides = resolved.project.toolchain;
+    const projectTrust = action === "extract" && overrides && Object.keys(overrides).length > 0 ? { root: resolved.root, trusted: await isProjectTrusted(resolved.root) } : undefined;
+    const locateTool = defaultTextLocateTool(overrides, action === "extract" && mode === "apply" ? "all" : action === "extract" ? "none" : "trusted", projectTrust);
     const templateGameVersion = async (surfaceId) => {
         const gameSurface = getSurface(surfaceId);
         if (!gameSurface)

package/dist/surfaces/cyberpunk2077/compat.js

@@ -210,11 +210,15 @@ const RULES = [
         requires: [],
         advisory: true,
         severity: "info",
-        note: "RED4ext plugins are locked to the game build. After a game patch, wait for RED4ext and its " +
-            "plugins to publish updated releases before assuming a mod is broken.",
+        note: "RED4ext plugins are tied to the game build they were compiled for. Before RED4ext 1.30.0 the " +
+            "loader itself refuses an unrecognized patch and no plugin loads; from 1.30.0 the loader runs on " +
+            "any build and skips each plugin pinned to another runtime (\"is incompatible with the current " +
+            "patch\" in red4ext.log), so a patch now breaks plugins one at a time. After a game patch, wait for " +
+            "RED4ext and its plugins to publish updated releases before assuming a mod is broken.",
         source: "https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-users/user-guide-troubleshooting " +
-            "(\"prone to breaking with every update\"); RED4ext itself refuses to run against a game patch " +
-            "it does not recognize (WopsS/RED4ext#33).",
+            "(\"prone to breaking with every update\"); RED4ext before 1.30.0 refuses a game patch it does " +
+            "not recognize (WopsS/RED4ext#33); 1.30.0 moved the check to each plugin's requested runtime " +
+            "(WopsS/RED4ext v1.30.0, src/dll/Systems/PluginSystem.cpp).",
     },
 ];
 export const cyberpunk2077Compat = {

package/dist/surfaces/cyberpunk2077/logs.js

@@ -137,8 +137,9 @@ const RED4EXT = [
         explain: "RED4ext refuses to run against this game build, so no native plugin loads at " +
             "all this launch. Everything downstream (TweakXL tweaks, ArchiveXL .xl files, " +
             "Codeware-dependent scripts) is dead, and none of them will say so.",
-        hint: "Update RED4ext to a release that supports this build, or roll the game back " +
-            "to the supported patch named on the following line.",
+        hint: "Update RED4ext (1.30.0 and later no longer refuse an unrecognized build; they " +
+            "check each plugin instead), or roll the game back to the supported patch named " +
+            "on the following line.",
         seenIn: [
             `${FIXTURES}/red4ext.synthetic.log`,
             "https://github.com/WopsS/RED4ext/issues/33",
@@ -222,7 +223,7 @@ const REDSCRIPT = [
             "or its data, not in compilation.",
         seenIn: [
             `${FIXTURES}/redscript_rCURRENT.ok.synthetic.log`,
-            "https://wiki.redmodding.org/redscript/help/troubleshooting",
+            "https://wiki.redmodding.org/scripting-cyberpunk/redscript/help/troubleshooting",
         ],
         extract: ["output"],
     },

package/dist/surfaces/cyberpunk2077/surface.js

@@ -59,7 +59,8 @@ export const cyberpunk2077 = {
                 extensions: [".archive", ".xl"],
                 ordered: true,
                 conflictScope: "opaque",
-                notes: "Loaded alphabetically; later names win on identical resource paths. " +
+                notes: "Loaded in ASCII order of filename (modlist.txt overrides it when present); on identical " +
+                    "resource paths the FIRST-loaded archive wins. " +
                     "A .xl sidecar is ArchiveXL and must keep the same base name as its .archive.",
             },
             {

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

@@ -169,6 +169,10 @@ const UNIQUE_IDS_EVIDENCE = [
     "cp2077.sectors.sector-json-file-uniqueness",
     "cp2077.toolchain.cli-convert-deserialize",
 ];
+function idSpace(jsonPath) {
+    const at = jsonPath.lastIndexOf(".Data.Chunks[");
+    return at === -1 ? "$" : jsonPath.slice(0, at);
+}
 async function checkUniqueIds(text, root, file) {
     const findings = [];
     for (const key of ["HandleId", "BufferId"]) {
@@ -177,13 +181,15 @@ async function checkUniqueIds(text, root, file) {
         for (const hit of hits) {
             if (typeof hit.value !== "string")
                 continue;
-            const list = byValue.get(hit.value) ?? [];
+            const spaceKey = `${idSpace(hit.jsonPath)}\u0000${hit.value}`;
+            const list = byValue.get(spaceKey) ?? [];
             list.push(hit);
-            byValue.set(hit.value, list);
+            byValue.set(spaceKey, list);
         }
-        for (const [value, list] of byValue) {
+        for (const [spaceKey, list] of byValue) {
             if (list.length < 2)
                 continue;
+            const value = spaceKey.slice(spaceKey.indexOf("\u0000") + 1);
             const lines = list.map((_, i) => lineOfOccurrence(text, `"${key}": "${value}"`, i)).filter((l) => l !== undefined);
             findings.push({
                 validatorId: "cp2077.vehicles.cr2w-unique-ids",

package/dist/surfaces/eldenring/loaders.js

@@ -117,7 +117,13 @@ export async function readModEngine2LoadOrder(install) {
     const configPath = path.join(gameDir(install), MODENGINE2_CONFIG);
     if (!(await pathExists(configPath)))
         return { configPath, entries: [] };
-    const config = parseModEngine2Config(await fs.readFile(configPath, "utf8"));
+    let config;
+    try {
+        config = parseModEngine2Config(await fs.readFile(configPath, "utf8"));
+    }
+    catch (err) {
+        return { configPath, entries: [], error: `${configPath}: ${err.message}` };
+    }
     const modDir = path.resolve(modengine2ModDir(install)).toLowerCase();
     const entries = [];
     let index = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modwright",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A game-agnostic MCP server for game modding, with per-game surfaces.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,10 @@
   },
   "license": "MIT",
   "author": "Jonathan Trachtenberg",
+  "homepage": "https://github.com/jtrachtenberg/modwright-community#readme",
+  "bugs": {
+    "url": "https://github.com/jtrachtenberg/modwright-community/issues"
+  },
   "keywords": [
     "mcp",
     "modding",

package/scaffolds/baldursgate3/new-project.yaml

@@ -19,10 +19,13 @@ inputs:
     name: version
     prompt: Initial version (semver-ish, major.minor.revision).
     default: "0.1.0"
+    # Interpolated raw into modwright.json; the same guard the Stardew scaffold carries.
+    pattern: "^(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)(?:\\.(?:0|[1-9][0-9]*))?(?:-(?:[a-zA-Z0-9]+[-.]?)+)?$"
   - type: string
     name: author
-    prompt: Author name.
+    prompt: Author name (no double quotes or backslashes — it is written into modwright.json as-is).
     default: "Unknown"
+    pattern: '^[^"\\\x00-\x1f]+$'
   # A project can keep its
   # LSLib divine path as a toolchain override in modwright.json; a fresh
   # project on the same machine needs the same line or its first build

package/scaffolds/cyberpunk2077/new-project.yaml

@@ -29,10 +29,13 @@ inputs:
     name: version
     prompt: Initial version (semver-ish, major.minor.revision).
     default: "0.1.0"
+    # Interpolated raw into modwright.json; the same guard the Stardew scaffold carries.
+    pattern: "^(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)(?:\\.(?:0|[1-9][0-9]*))?(?:-(?:[a-zA-Z0-9]+[-.]?)+)?$"
   - type: string
     name: author
-    prompt: Author name.
+    prompt: Author name (no double quotes or backslashes — it is written into modwright.json as-is).
     default: "Unknown"
+    pattern: '^[^"\\\x00-\x1f]+$'
   # Observed in practice (2026-09-12): the WolvenKit CLI override had to be
   # added to a fresh project by hand because the locator does not find a CLI
   # installed outside the usual places. The path is machine-specific and