modwright 0.1.2 → 0.1.4

package/dist/core/writes/index.js

@@ -0,0 +1,206 @@
+import { listMods } from "../mods.js";
+const VALUE_CHARS = 200;
+export function shortValue(value) {
+    if (value === undefined)
+        return undefined;
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    if (text === undefined)
+        return undefined;
+    if (text.length <= VALUE_CHARS)
+        return value;
+    return `${text.slice(0, VALUE_CHARS)}…`;
+}
+export async function collectWrites(surface, install, options = {}) {
+    const collection = {
+        writers: [],
+        coverage: { modsScanned: 0, writesFound: 0, rootsScanned: [], errors: [], unitNotes: [] },
+    };
+    if (!surface.extractWrites)
+        return collection;
+    const listOptions = { fileLimit: 20000 };
+    if (options.rootIds)
+        listOptions.rootIds = options.rootIds;
+    const { mods, roots } = await listMods(surface, install, listOptions);
+    const rootById = new Map(roots.map((r) => [r.id, r]));
+    const scannedRoots = new Set();
+    const byWriter = new Map();
+    const scanned = new Set();
+    for (const mod of mods) {
+        const root = rootById.get(mod.rootId);
+        if (!root)
+            continue;
+        let extraction;
+        try {
+            extraction = await surface.extractWrites(mod, root, install);
+        }
+        catch (error) {
+            collection.coverage.errors.push({ writerId: mod.id, file: mod.path, error: error.message });
+            continue;
+        }
+        if (!extraction)
+            continue;
+        scannedRoots.add(root.id);
+        if (extraction.writes.length === 0)
+            scanned.add(mod.id);
+        if (extraction.unitNote && !collection.coverage.unitNotes.includes(extraction.unitNote)) {
+            collection.coverage.unitNotes.push(extraction.unitNote);
+        }
+        for (const err of extraction.errors)
+            collection.coverage.errors.push({ writerId: mod.id, ...err });
+        for (const write of extraction.writes) {
+            const writerId = write.unit ? `${mod.id}/${write.unit}` : mod.id;
+            scanned.add(writerId);
+            let writer = byWriter.get(writerId);
+            if (!writer) {
+                writer = { writerId, name: write.unit ?? mod.name, rootId: mod.rootId, writes: [] };
+                const state = write.unit ? extraction.unitStates?.[write.unit] : undefined;
+                const inactive = state?.inactive ?? extraction.inactive;
+                const identity = state?.identity ?? extraction.identity;
+                if (inactive)
+                    writer.inactive = inactive;
+                if (identity)
+                    writer.identity = identity;
+                byWriter.set(writerId, writer);
+            }
+            writer.writes.push(write);
+            collection.coverage.writesFound++;
+        }
+    }
+    collection.writers = [...byWriter.values()];
+    collection.coverage.modsScanned = scanned.size;
+    const inactive = collection.writers.filter((w) => w.inactive).length;
+    if (inactive > 0)
+        collection.coverage.inactiveWriters = inactive;
+    collection.coverage.rootsScanned = [...scannedRoots];
+    return collection;
+}
+function groupByKey(collection, keep) {
+    const byKey = new Map();
+    for (const writer of collection.writers) {
+        for (const write of writer.writes) {
+            if (!keep(write))
+                continue;
+            const k = write.key.toLowerCase();
+            let entry = byKey.get(k);
+            if (!entry) {
+                entry = { key: write.key, keyKind: write.keyKind, contested: false, writers: [] };
+                byKey.set(k, entry);
+            }
+            const row = {
+                writerId: writer.writerId,
+                name: writer.name,
+                op: write.op,
+                file: write.file,
+                certainty: write.certainty,
+            };
+            const value = shortValue(write.value);
+            if (value !== undefined)
+                row.value = value;
+            if (write.line !== undefined)
+                row.line = write.line;
+            if (write.condition !== undefined)
+                row.condition = write.condition;
+            if (writer.inactive)
+                row.inactive = writer.inactive;
+            if (writer.identity)
+                row.identity = writer.identity;
+            entry.writers.push(row);
+        }
+    }
+    for (const entry of byKey.values()) {
+        const live = entry.writers.filter((w) => !w.inactive);
+        const writers = new Set(live.map((w) => w.identity ?? w.writerId));
+        if (writers.size < 2)
+            continue;
+        if (new Set(live.map((w) => JSON.stringify([w.op, w.value]))).size === 1) {
+            entry.agree = true;
+            continue;
+        }
+        if (live.every((w) => w.op === "append" || w.op === "remove")) {
+            const items = (op) => new Set(live.filter((w) => w.op === op).flatMap((w) => (Array.isArray(w.value) ? w.value : [w.value])).map((v) => JSON.stringify(v)));
+            const appended = items("append");
+            entry.contested = [...items("remove")].some((v) => appended.has(v));
+            continue;
+        }
+        entry.contested = true;
+    }
+    return byKey;
+}
+export function whoTouches(collection, query, limit = 50) {
+    const q = query.trim().toLowerCase();
+    const all = groupByKey(collection, () => true);
+    const pick = (matchedBy, keys) => {
+        keys.sort((a, b) => Number(b.contested) - Number(a.contested) || a.key.localeCompare(b.key));
+        const result = { query, matchedBy, keys: keys.slice(0, limit) };
+        if (keys.length > limit)
+            result.omittedKeys = keys.length - limit;
+        return result;
+    };
+    const exact = all.get(q);
+    if (exact) {
+        const under = [...all.entries()].filter(([k]) => k !== q && isUnder(k, q)).map(([, v]) => v);
+        return pick("exact", [exact, ...under]);
+    }
+    const prefixed = [...all.entries()].filter(([k]) => isUnder(k, q)).map(([, v]) => v);
+    if (prefixed.length > 0)
+        return pick("prefix", prefixed);
+    const containing = [...all.entries()].filter(([k]) => k.includes(q)).map(([, v]) => v);
+    if (containing.length > 0)
+        return pick("substring", containing);
+    return { query, matchedBy: "none", keys: [] };
+}
+function isUnder(key, parent) {
+    if (!key.startsWith(parent) || key.length === parent.length)
+        return false;
+    const next = key[parent.length];
+    return next === "." || next === "#" || next === "/";
+}
+export function whatTouches(collection, modQuery, limit = 100) {
+    const q = modQuery.trim().toLowerCase();
+    const exact = collection.writers.filter((w) => w.writerId.toLowerCase() === q || w.name.toLowerCase() === q);
+    const matches = exact.length > 0 ? exact : collection.writers.filter((w) => w.writerId.toLowerCase().includes(q) || w.name.toLowerCase().includes(q));
+    const byKey = groupByKey(collection, () => true);
+    return matches.map((writer) => {
+        const sharedWith = [];
+        const seen = new Set();
+        for (const write of writer.writes) {
+            const k = write.key.toLowerCase();
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            const entry = byKey.get(k);
+            if (!entry?.contested)
+                continue;
+            const others = [...new Set(entry.writers.filter((w) => w.writerId !== writer.writerId).map((w) => w.name))];
+            if (others.length > 0)
+                sharedWith.push({ key: entry.key, others });
+        }
+        const summary = {
+            writerId: writer.writerId,
+            name: writer.name,
+            rootId: writer.rootId,
+            writeCount: writer.writes.length,
+            sharedWith,
+            writes: writer.writes.slice(0, limit).map((w) => ({ ...w, value: shortValue(w.value) })),
+        };
+        if (writer.writes.length > limit)
+            summary.omittedWrites = writer.writes.length - limit;
+        return summary;
+    });
+}
+export function duplicateCopies(collection) {
+    const byIdentity = new Map();
+    for (const writer of collection.writers) {
+        if (!writer.identity || writer.inactive)
+            continue;
+        const names = byIdentity.get(writer.identity) ?? [];
+        names.push(writer.name);
+        byIdentity.set(writer.identity, names);
+    }
+    return [...byIdentity].filter(([, names]) => names.length > 1).map(([identity, writers]) => ({ identity, writers: writers.sort() }));
+}
+export function contestedKeys(collection, limit = 100) {
+    const keys = [...groupByKey(collection, () => true).values()].filter((k) => k.contested);
+    keys.sort((a, b) => new Set(b.writers.map((w) => w.writerId)).size - new Set(a.writers.map((w) => w.writerId)).size || a.key.localeCompare(b.key));
+    return { total: keys.length, keys: keys.slice(0, limit) };
+}

package/dist/index.js

@@ -116,7 +116,6 @@ class Supervisor {
     swapQueued = false;
     closing = false;
     initializeRaw;
-    initializeId;
     initializedSeen = false;
     routes = new Map();
     serverRequests = new Map();
@@ -151,7 +150,6 @@ class Supervisor {
         const active = this.active;
         if (msg.method === "initialize" && msg.id !== undefined && msg.id !== null) {
             this.initializeRaw = raw;
-            this.initializeId = msg.id;
         }
         else if (msg.method === "notifications/initialized") {
             this.initializedSeen = true;

package/dist/server.js

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { pathExists, tail } from "./core/fsutil.js";
-import { describeProject, findProjectFile, loadProject } from "./core/project/index.js";
+import { describeProject, findProjectFile, loadProject, locateProjectFile } from "./core/project/index.js";
 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";
@@ -14,6 +14,7 @@ import { buildContext, createValidatorRegistry, runValidators } from "./core/val
 import { runBuild } from "./core/build/index.js";
 import { classifyReload, detectRedHotTools, runDeploy } from "./core/deploy/index.js";
 import { armBridge, bridgeCandidateDirs, bridgeStatus, cetLogCandidates, listPendingArms, PROTOCOL_VERSION as BRIDGE_PROTOCOL_VERSION, pollCyberpunk, pollForResult, probeSchema as bridgeProbeSchema, readPendingArm, stageBridge } from "./core/bridge/index.js";
+import { removeBridge } from "./core/bridge/remove.js";
 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";
@@ -22,6 +23,8 @@ import { readTextIfExists } from "./core/fsutil.js";
 import * as path from "node:path";
 import { promises as fs } from "node:fs";
 import { crossCheckIdentities, findConflicts, listMods, sharedIdentities } from "./core/mods.js";
+import { buildOwnershipIndex, lookupOwnership, managerConflicts } from "./core/ownership/index.js";
+import { collectWrites, contestedKeys, duplicateCopies, whatTouches, whoTouches } from "./core/writes/index.js";
 import { resolveLogs, resolveRoots } from "./core/surfaceutil.js";
 import { SURFACES, getSurface, installGameVersion, resolveInstall, surfaceIds } from "./surfaces/index.js";
 import { CONVERTERS, convert as runConvert, defaultLocateTool as defaultTextLocateTool, extractTemplate, fieldDiff, getTemplate, invalidateTemplate, listTemplates, } from "./core/text/index.js";
@@ -183,8 +186,12 @@ server.registerTool("find_conflicts", {
         installPath: installPathArg,
         rootIds: z.array(z.string()).optional().describe("Restrict to these mod root ids."),
         limit: z.number().int().positive().default(100).describe("Max conflicts to return."),
+        mo2Instance: z
+            .string()
+            .optional()
+            .describe("A portable Mod Organizer 2 instance (its folder or ModOrganizer.ini); global instances are found automatically."),
     },
-}, async ({ game, installPath, rootIds, limit }) => {
+}, async ({ game, installPath, rootIds, limit, mo2Instance }) => {
     const surface = getSurface(game);
     if (!surface)
         return fail(`Unknown game "${game}". Known: ${surfaceIds().join(", ")}`);
@@ -202,10 +209,22 @@ server.registerTool("find_conflicts", {
         identityUnreadableCount = scanned.unreadable.length;
         identityUnreadable = scanned.unreadable.slice(0, IDENTITY_UNREADABLE_LIMIT);
     }
+    let managed;
+    if (surface.managedDataDir !== undefined) {
+        const index = await buildOwnershipIndex(surface, install, mo2Instance ? { mo2Instance } : {});
+        const mo2 = index.sources.find((src) => src.id === "mo2");
+        if (mo2?.active) {
+            const found = managerConflicts(index, limit);
+            managed = { source: mo2.detail, total: found.total, conflicts: found.conflicts };
+            if (found.total > limit)
+                managed.truncated = true;
+        }
+    }
     return json({
         game: surface.id,
         modsAnalyzed: mods.length,
         conflictCount: conflicts.length,
+        managerConflicts: managed,
         skippedRoots,
         suppressedNoiseFiles,
         truncated: conflicts.length > limit,
@@ -215,10 +234,108 @@ server.registerTool("find_conflicts", {
         identityUnreadable,
         identityUnreadableTruncated: identityUnreadableCount > IDENTITY_UNREADABLE_LIMIT ? true : undefined,
         note: "File-level analysis, and only for roots where mods share one deploy tree. " +
-            "See skippedRoots for what was excluded and why.",
+            "See skippedRoots for what was excluded and why." +
+            (managed
+                ? " managerConflicts are between Mod Organizer 2's mod folders, each with the winner the game sees and the mods it overrides."
+                : ""),
         guidance: surface.guidance,
     });
 });
+server.registerTool("owner_of", {
+    title: "Which mod owns this file",
+    description: "Say which installed mod a file comes from, and which copy the game actually sees when several provide it. " +
+        "Accepts absolute paths, paths relative to the game folder, a trailing part of a path (SKSE/Plugins/foo.dll), " +
+        "or a bare file name — e.g. a DLL named in a crash log, a path from triage_logs. Sources: the game's own mod " +
+        "roots (a mod folder owns what is under it), Mod Organizer 2 (the active profile's mod folders in priority " +
+        "order, plus Overwrite; for games where the mapping is known), and Vortex deployment manifests. Each result " +
+        "says how the winner was decided; `sources` says what each source could see, and `unattributedRoots` lists " +
+        "loose-file folders whose files no source can attribute. Files inside packed archives are not indexed yet.",
+    inputSchema: {
+        game: gameArg,
+        installPath: installPathArg,
+        paths: z.array(z.string().min(1)).min(1).max(50).describe("Files to attribute."),
+        mo2Instance: z
+            .string()
+            .optional()
+            .describe("A portable Mod Organizer 2 instance (its folder or ModOrganizer.ini); global instances are found automatically."),
+        limit: z.number().int().positive().max(200).default(20).describe("Max matches per path (a bare file name can match many)."),
+    },
+}, async ({ game, installPath, paths, mo2Instance, limit }) => {
+    const surface = getSurface(game);
+    if (!surface)
+        return fail(`Unknown game "${game}". Known: ${surfaceIds().join(", ")}`);
+    const install = await resolveInstall(surface, installPath);
+    if (!install)
+        return fail(`No install detected for ${surface.name}.`);
+    const index = await buildOwnershipIndex(surface, install, mo2Instance ? { mo2Instance } : {});
+    return json({
+        game: surface.id,
+        install: install.root,
+        sources: index.sources,
+        indexedPaths: index.entries.size,
+        unattributedRoots: index.unattributedRoots.length > 0 ? index.unattributedRoots : undefined,
+        results: paths.map((p) => lookupOwnership(index, p, limit)),
+        note: "Owners come only from what is on disk: a mod folder, a manager's own records. Nothing is inferred from " +
+            "file names. A path no mod claims is reported as such, with the likely reasons.",
+    });
+});
+server.registerTool("who_touches", {
+    title: "Which mods write this record or asset",
+    description: "Read every installed mod's data and report who writes a given key — at the level the game merges on, not the " +
+        "file level: a TweakDB record or flat (Cyberpunk 2077, TweakXL YAML and .tweak files), a stats entry or field " +
+        "(Baldur's Gate 3, inside paks and unpacked mods), an asset or data entry/field (Stardew Valley Content Patcher " +
+        "packs, Includes followed). Give `key` for who writes it (a record returns its flats too; an asset its entries), " +
+        "`mod` for everything one mod writes and where another mod writes the same key, or neither for every key two or " +
+        "more mods contend for. This says who touches a key, not who wins: the winner depends on the game's load order. " +
+        "Writes behind a Content Patcher When, or with {{tokens}}, are marked conditional.",
+    inputSchema: {
+        game: gameArg,
+        installPath: installPathArg,
+        key: z.string().min(1).optional().describe("A record, flat, stats entry, asset or entry, e.g. Items.Preset_Masamune_Default, stats:Projectile_Fireball, Data/Objects#128."),
+        mod: z.string().min(1).optional().describe("A mod (or unit) id or name, for what it writes."),
+        rootIds: z.array(z.string()).optional().describe("Restrict to these mod root ids."),
+        limit: z.number().int().positive().max(500).default(50).describe("Max keys (or writes per mod) to return."),
+    },
+}, async ({ game, installPath, key, mod, rootIds, limit }) => {
+    const surface = getSurface(game);
+    if (!surface)
+        return fail(`Unknown game "${game}". Known: ${surfaceIds().join(", ")}`);
+    const install = await resolveInstall(surface, installPath);
+    if (!install)
+        return fail(`No install detected for ${surface.name}.`);
+    if (!surface.extractWrites) {
+        return json({
+            game: surface.id,
+            supported: false,
+            note: `No write-set extraction for ${surface.name} yet (supported: Cyberpunk 2077 tweaks, Baldur's Gate 3 stats, Stardew Valley Content Patcher).`,
+        });
+    }
+    const collection = await collectWrites(surface, install, rootIds ? { rootIds } : {});
+    const { errors, ...coverage } = collection.coverage;
+    const copies = duplicateCopies(collection);
+    const result = key
+        ? { mode: "key", ...whoTouches(collection, key, limit) }
+        : mod
+            ? { mode: "mod", query: mod, writers: whatTouches(collection, mod, limit) }
+            : { mode: "contested", ...contestedKeys(collection, limit) };
+    return json({
+        game: surface.id,
+        install: install.root,
+        coverage: {
+            ...coverage,
+            writers: collection.writers.length,
+            errorCount: errors.length,
+            errors: errors.slice(0, 25),
+        },
+        ...(copies.length > 0 ? { duplicateCopies: copies } : {}),
+        ...result,
+        note: "Static: read from the mods' files, never from the running game. 'contested' means two or more mods write the " +
+            "key and not only by appending; which one the game ends up with depends on load order, which this tool does " +
+            "not decide. A mod the game does not load (marked 'inactive') is listed but never contests, and copies of one " +
+            "mod ('duplicateCopies') count once: the game loads one of them. Code that writes at runtime (redscript, CET, " +
+            "SMAPI C# mods, Script Extender Lua) is not seen here.",
+    });
+});
 server.registerTool("load_order", {
     title: "Read load order",
     description: "Read the game's explicit load order and cross-check it against what is " +
@@ -340,9 +457,7 @@ server.registerTool("project_info", {
 }, async ({ path: start }) => {
     const from = start ?? process.cwd();
     try {
-        const file = (await pathExists(from)) && from.toLowerCase().endsWith(".json")
-            ? from
-            : await findProjectFile(from);
+        const file = await locateProjectFile(from);
         if (!file) {
             return json({
                 found: false,
@@ -601,7 +716,11 @@ server.registerTool("triage_logs", {
         "which failed and why, with the first error's explanation and usual fix. Pass the " +
         "returned offsets and offsetKeys back as offsets/offsetKeys for incremental triage after " +
         "the next launch (the keys let a re-created log of identical size be read again). " +
-        "Stale and zero-byte logs are reported as such rather than trusted.",
+        "Stale and zero-byte logs are reported as such rather than trusted. Where a framework " +
+        "logs who did what (SMAPI's 'X edited Data/Objects', TweakXL's file read order, ArchiveXL " +
+        "merges and localization overwrites, Red Hot Tools' missing resources), the verdict's " +
+        "`attribution` groups those lines by subject, contested subjects first: the log's own answer " +
+        "to 'which mod is doing this'. Pass attributionFor to narrow it to one asset, record or mod.",
     inputSchema: {
         game: gameArg,
         installPath: installPathArg,
@@ -619,15 +738,20 @@ server.registerTool("triage_logs", {
             .describe("Per log id file identities (offsetKeys) from the same previous result."),
         maxLines: z.number().int().positive().max(20000).optional(),
         includeFindings: z.boolean().default(true),
+        attributionFor: z
+            .string()
+            .optional()
+            .describe("Keep only attribution entries whose subject, actor or content pack contains this text " +
+            "(case-insensitive): an asset or record for 'who touched this', a mod name for 'what did it touch'."),
     },
-}, async ({ game, installPath, since, offsets, offsetKeys, maxLines, includeFindings }) => {
+}, async ({ game, installPath, since, offsets, offsetKeys, maxLines, includeFindings, attributionFor }) => {
     const surface = getSurface(game);
     if (!surface)
         return fail(`Unknown game "${game}". Known: ${surfaceIds().join(", ")}`);
     const install = await resolveInstall(surface, installPath);
     if (!install)
         return fail(`No install detected for ${surface.name}.`);
-    const verdict = await triageLogs(surface, install, registry, { since, offsets, offsetKeys, maxLines });
+    const verdict = await triageLogs(surface, install, registry, { since, offsets, offsetKeys, maxLines }, { attributionFor });
     return json({
         ...verdict,
         signatureCount: registry.forGame(surface.id).length,
@@ -677,7 +801,7 @@ server.registerTool("load_order_diff", {
         const stamp = new Date().toISOString().replace(/[:.]/g, "-");
         let snapshotDir = path.join(userDataDir(), "snapshots");
         if (projectPath) {
-            const projectFile = (await pathExists(projectPath)) && projectPath.toLowerCase().endsWith(".json") ? projectPath : await findProjectFile(projectPath);
+            const projectFile = await locateProjectFile(projectPath);
             if (!projectFile)
                 return fail(`No modwright.json found at or above ${projectPath}.`);
             snapshotDir = path.join(path.dirname(path.resolve(projectFile)), ".modwright", "snapshots");
@@ -912,7 +1036,7 @@ server.registerTool("build_index", {
     let toolOverrides;
     if (projectPath) {
         try {
-            const file = (await pathExists(projectPath)) && projectPath.toLowerCase().endsWith(".json") ? projectPath : await findProjectFile(projectPath);
+            const file = await locateProjectFile(projectPath);
             if (!file)
                 return fail(`No modwright.json found at or above ${projectPath}.`);
             const loaded = await loadProject(file);
@@ -1278,10 +1402,13 @@ server.registerTool("bridge", {
         "(dry-run by default for both; refuses on a protocolVersion mismatch rather than guessing). 'poll': wait for " +
         "that request's result up to a budget of max(15s, 3s x probe count) + window, capped at 300s, " +
         "reporting one of four named timeout outcomes rather than a bare 'timed out' — plus, on the CET log transport, " +
-        "'truncated' when the result line was cut mid-write. Test-plan execution is run_tests; claims are the " +
+        "'truncated' when the result line was cut mid-write. 'remove': take a deployed bridge back out of the game " +
+        "(every folder the project's withBridge deploy targets name), backed up under the project; dry-run by default. " +
+        "A deploy without the withBridge variant leaves an installed bridge in place. " +
+        "Test-plan execution is run_tests; claims are the " +
         "ledger tool.",
     inputSchema: {
-        action: z.enum(["status", "arm", "poll", "stage"]),
+        action: z.enum(["status", "arm", "poll", "stage", "remove"]),
         game: z
             .enum(BRIDGE_GAMES)
             .optional()
@@ -1312,12 +1439,18 @@ server.registerTool("bridge", {
         timeoutSeconds: z.number().positive().max(300).optional().describe("'poll': override the computed budget; still capped at 300s."),
     },
 }, async ({ action, game, installPath, path: start, mode, probes, armForSeconds, grant, allowMutate, windowSeconds, planId, planPath, runId, id, nonce, probeCount, timeoutSeconds }) => {
+    const planFields = { planId, planPath, runId };
+    const givenPlan = Object.entries(planFields).filter(([, v]) => v !== undefined);
+    if (givenPlan.length > 0 && givenPlan.length < 3) {
+        const missing = Object.entries(planFields).filter(([, v]) => v === undefined).map(([k]) => k);
+        return fail(`planId, planPath and runId go together; ${missing.join(" and ")} ${missing.length === 1 ? "is" : "are"} missing.`);
+    }
     let projectGame;
     let projectRoot;
     if (start) {
         try {
             const from = start;
-            const file = (await pathExists(from)) && from.toLowerCase().endsWith(".json") ? from : await findProjectFile(from);
+            const file = await locateProjectFile(from);
             if (!file)
                 return fail(`No modwright.json found at or above ${from}.`);
             const loaded = await loadProject(file);
@@ -1346,6 +1479,38 @@ server.registerTool("bridge", {
             return fail(`bridge stage failed: ${error.message}`);
         }
     }
+    if (action === "remove") {
+        if (!start)
+            return fail('bridge remove requires "path" (the project whose deployed bridge to remove).');
+        const surfaceId = game ?? projectGame;
+        const removeSurface = surfaceId ? getSurface(surfaceId) : undefined;
+        if (!removeSurface)
+            return fail(`Could not determine the game for ${start}; pass game explicitly.`);
+        const install = await resolveInstall(removeSurface, installPath);
+        if (!install)
+            return fail(`No install detected for ${removeSurface.name}.`);
+        try {
+            const resolved = await loadProject(start);
+            const report = await removeBridge(resolved, removeSurface.modRoots(install), { mode });
+            const toRemove = report.removals.filter((r) => r.action === "remove").length;
+            return json({
+                action,
+                game: removeSurface.id,
+                project: resolved.project.name,
+                ...report,
+                note: report.removals.length === 0
+                    ? "The project has no withBridge deploy target: nothing to remove."
+                    : toRemove === 0
+                        ? "No deployed bridge folder was found: nothing to remove."
+                        : report.applied
+                            ? `Removed ${toRemove} bridge folder(s); the backup is under the project's .modwright/backups (rollback restores it).`
+                            : `Dry run: ${toRemove} bridge folder(s) would be removed, with a backup. Repeat with mode 'apply'.`,
+            });
+        }
+        catch (error) {
+            return fail(`bridge remove failed: ${error.message}`);
+        }
+    }
     const gameId = game ?? projectGame;
     if (!gameId)
         return fail('bridge status/arm/poll requires "game" (or a "path" to a project that names one).');
@@ -1618,7 +1783,7 @@ const TEMPLATE_SURFACES = ["baldursgate3", "cyberpunk2077"];
 const TEMPLATE_PERMISSIONS = ["never-redistribute", "maintainer-own", "declared-dependency"];
 async function resolveProject(start) {
     const from = start ?? process.cwd();
-    const file = (await pathExists(from)) && from.toLowerCase().endsWith(".json") ? from : await findProjectFile(from);
+    const file = await locateProjectFile(from);
     if (!file)
         throw new NoProjectError(`No modwright.json found at or above ${from}.`);
     return loadProject(file);

package/dist/surfaces/baldursgate3/surface.js

@@ -6,6 +6,7 @@ import { dedupeByRoot, logs, roots } from "../../core/surfaceutil.js";
 import { bg3Index } from "./index/index.js";
 import { scanModIdentities as scanBg3ModIdentities } from "./identity.js";
 import { SIGNATURES } from "./logs.js";
+import { extractBg3Writes } from "./writes.js";
 import { describeModSettingsDiff, diffModSettings, parseModSettings } from "./modsettings.js";
 import { BRIDGE_VALIDATORS } from "./validators/bridge.js";
 import { FILE_VALIDATORS } from "./validators/files.js";
@@ -112,6 +113,8 @@ export const baldursgate3 = {
         };
     },
     logSignatures: SIGNATURES,
+    extractWrites: (mod, root) => extractBg3Writes(mod, root),
+    looseUnitOf: (rootId, rel) => (rootId === "loose" ? /^(?:Mods|Public|Generated\/Public)\/([^/]+)\//i.exec(rel)?.[1] : undefined),
     index: bg3Index,
     validators: [
         ...ITEM_VALIDATORS,

package/dist/surfaces/baldursgate3/validators/story.js

@@ -228,8 +228,9 @@ const osirisNamingConvention = {
         const base = path.posix.basename(lower(ctx.target.path), ".txt");
         if (!/^[a-z0-9]+(_[a-z0-9]+){2,}$/i.test(base)) {
             findings.push(finding(osirisNamingConvention.id, "info", ctx.target.path, `Goal file name '${path.basename(ctx.target.path)}' does not obviously follow the Act_Region_Situation convention. ` +
-                `This is a naming convention, not a known build failure — no fact in knowledge/baldursgate3/ confirms a missing ` +
-                `prefix disables the story component (still an open question), so this stays informational.`, osirisNamingConvention.evidence));
+                `This is a naming convention, not a known build failure: LSLib's story compiler only warns on a name missing ` +
+                `its DB/PROC/QRY prefix (bg3.dialogue.osiris-goals.prefix-convention-is-a-compiler-warning-in-lslib), ` +
+                `so this stays informational.`, osirisNamingConvention.evidence));
         }
         const text = stripBom(await ctx.readText(ctx.target.path)).replace(/\r\n/g, "\n");
         const badPrefixRe = /\b(?!DB_|QRY_|PROC_)([A-Za-z][A-Za-z0-9_]*)\s*\(/g;
@@ -482,7 +483,6 @@ const questAddQuestCloseDiscouraged = {
         return goal.questAddClose.map((occ) => finding(questAddQuestCloseDiscouraged.id, "info", targetPath, `${occ.name}(...) is used here. The documentation recommends relying on QuestUpdate instead of manually adding/closing quests.`, questAddQuestCloseDiscouraged.evidence, { line: occ.line }));
     },
 };
-const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 function collectOrigins(doc) {
     const origins = [];
     for (const region of doc.regions) {