modwright 0.1.3 → 0.1.4

package/README.md

@@ -153,7 +153,7 @@ Epic paths where they apply. Override with `installPath` on any tool, or set
 | `deploy` | Copy a built mod into the game's mod roots as one write plan. It refuses an artifact the build did not produce or one older than its sources, prunes what a previous build left behind, and defers a file the running game holds locked. Every overwrite and delete is backed up first. |
 | `rollback` | List the deploy backups under a project's `.modwright/backups/`, or restore one, re-checking every file's hash first. |
 | `reload_plan` | Classify deployed changes into hot / hot-degraded / save-reload / restart / unknown, with the caveat for each and the single most conservative recommendation. |
-| `bridge` | The in-game bridge (BG3 Script Extender, Cyberpunk 2077 CET): `stage` the bridge into a project, check its heartbeat with `status`, `arm` a probe request and `poll` for its result. |
+| `bridge` | The in-game bridge (BG3 Script Extender, Cyberpunk 2077 CET): `stage` the bridge into a project, check its heartbeat with `status`, `arm` a probe request and `poll` for its result, and `remove` it from the game when you are done. |
 | `run_tests` | Run a mod's in-game test plan (`<mod>/tests/*.yaml`) through the bridge. Probe rows are armed and polled; manual rows become a checklist. Results are written back into the plan. |
 | `ledger` | Track claims and decisions across a fix (`<mod>/ledger/`). A claim moves `authored → checker-clean → built → verified \| contradicted`, and nothing is verified without evidence. |
 | `convert` | Run one registered conversion: BG3 lsx↔lsf and xml↔loca through divine, Cyberpunk cr2w↔json through WolvenKit CLI. Each one checks its own round trip. |
@@ -305,7 +305,7 @@ What it runs, and where it writes:
 - **The in-game bridges.** While a verification bridge is deployed and the
   game runs, anything that can write the bridge's request folder can run Lua
   in the game. There is no token. Deploy a bridge only while you verify,
-  remove it afterwards, and never ship it (the release validators block a
+  remove it afterwards (`bridge action=remove`), and never ship it (the release validators block a
   build that contains it). The bridge READMEs under `bridges/` describe each
   one's trust model.
 

package/bridges/bg3-se/README.md

@@ -93,8 +93,9 @@ from running again; they do not say who wrote it. So:
 
 - deploy the bridge only to a machine and a profile you control, and only while you are
   verifying a mod;
-- remove `Mods/ModWrightBridge` from the profile when you are done, before playing normally
-  or sharing the profile;
+- remove it when you are done, before playing normally or sharing the profile:
+  `bridge action=remove path=<project> mode=apply` deletes every folder the project's
+  `withBridge` targets deployed, with a backup (a dry run first shows which);
 - never ship it. `bg3.history.bridge-never-ships` blocks a release build that contains it.
 
 ## What this bridge never does

package/bridges/bg3-se/bridge.json

@@ -17,7 +17,7 @@
     "prune": [
       "ModWrightBridge/**"
     ],
-    "note": "The deploy target a shipped SE mod uses, verbatim: `bridge stage` adds it to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit. A deploy WITHOUT `--variant withBridge` prunes the folder back out, with backup."
+    "note": "The deploy target a shipped SE mod uses, verbatim: `bridge stage` adds it to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit. A deploy without `--variant withBridge` leaves an installed bridge where it is: a variant's prune runs only in a deploy that writes that variant. Take it out with `bridge action=remove path=<project> mode=apply` when you are done verifying (dry-run first; backed up)."
   },
   "sha256": {
     "algorithm": "sha256",

package/bridges/cp2077-cet/ModWrightBridge/probes.lua

@@ -1048,6 +1048,114 @@ Probes.handlers = {
             }
         end,
     },
+    -- Workbench probes: session-tier mutations that put the world into a testable state, so
+    -- a common setup is a catalogue row rather than hand-written Lua each time. Listed in
+    -- Probes.MUTATING_KINDS below and gated on the `session` tier like the other mutating rows.
+
+    -- attested 2026-10-04: this row ran live and the entity appeared. The call:
+    --   exEntitySpawner.Spawn('base\characters\entities\gang\gang__wraith_ma.ent',
+    --                         Game.GetPlayer():GetWorldTransform(), '')
+    -- returned a userdata handle, and Game.FindEntityByID(handle) resolved the entity.
+    -- Despawn takes the RESOLVED object, not the handle, and the handle does not persist across
+    -- bridge calls, so a despawn belongs in the same cp2077.lua.eval as its spawn.
+    ["cp2077.world.spawn"] = {
+        attestation = "attested 2026-10-04 (ran live; the entity appeared)",
+        citation = "exEntitySpawner.Spawn(entPath, GetPlayer():GetWorldTransform(), appearance), a CET-added native (RTTIExtender.cpp)",
+        effect = "mutate",
+        mutates = true,
+        run = function(probe)
+            local p = params(probe)
+            if p.entPath == nil then
+                return errored("params.entPath is required, e.g. \"base\\characters\\entities\\gang\\gang__wraith_ma.ent\"")
+            end
+            local entPath = tostring(p.entPath)
+            local appearance = p.appearance ~= nil and tostring(p.appearance) or ""
+            if not have("Game") then return absent("the `Game` global", "design §8 step 4") end
+            local pl = player()
+            if pl == nil then return failed("Game.GetPlayer() returned nil — load a save first", nil, { entPath = entPath }) end
+
+            local spawner
+            local okG = pcall(function() spawner = exEntitySpawner end)
+            if not okG or spawner == nil then
+                return missingAttested("`exEntitySpawner`", "exEntitySpawner.Spawn", { entPath = entPath })
+            end
+
+            local transform
+            local okT, e = pcall(function() transform = pl:GetWorldTransform() end)
+            if not okT then return errored("GetPlayer():GetWorldTransform() raised: " .. tostring(e), { entPath = entPath }) end
+
+            local handle
+            local okS, e2 = pcall(function() handle = exEntitySpawner.Spawn(entPath, transform, appearance) end)
+            local evidence = {
+                entPath = entPath,
+                appearance = appearance,
+                spawnedAtPlayerTransform = true,
+                note = "spawned at the player's own transform: the player is inside the entity until they separate. " ..
+                    "The entity arrives after this call returns, so `resolved` is normally false here. " ..
+                    "The id handle does not persist across bridge calls; despawn within one eval (cp2077.lua.eval) or re-find the entity.",
+            }
+            if not okS then return errored("exEntitySpawner.Spawn raised: " .. tostring(e2), evidence) end
+            evidence.handle = handle ~= nil and tostring(handle) or nil
+            if handle == nil then return failed("exEntitySpawner.Spawn returned nil for \"" .. entPath .. "\"", nil, evidence) end
+            local ent
+            pcall(function() ent = Game.FindEntityByID(handle) end)
+            evidence.resolved = ent ~= nil
+            return ok(tostring(handle), evidence)
+        end,
+    },
+
+    -- attested 2026-10-04: a teleport to x+4 moved the player by exactly that.
+    --   Game.GetTeleportationFacility():Teleport(GetPlayer(), Vector4, EulerAngles)
+    ["cp2077.player.teleport"] = {
+        attestation = "attested 2026-10-04 (ran live, read back)",
+        citation = "Game.GetTeleportationFacility():Teleport(player, Vector4, EulerAngles), from the CET wiki",
+        effect = "mutate",
+        mutates = true,
+        run = function(probe)
+            local p = params(probe)
+            local x, y, z = tonumber(p.x), tonumber(p.y), tonumber(p.z)
+            if x == nil or y == nil or z == nil then
+                return errored("params.x, params.y and params.z (numbers) are required")
+            end
+            local yaw = tonumber(p.yaw) or 0.0
+            if not have("Game") then return absent("the `Game` global", "design §8 step 4") end
+            local pl = player()
+            if pl == nil then return failed("Game.GetPlayer() returned nil — load a save first") end
+            local evidence = {
+                x = x, y = y, z = z, yaw = yaw,
+                call = "Game.GetTeleportationFacility():Teleport(player, Vector4.new(x,y,z,1), EulerAngles.new(0,0,yaw))",
+                note = "the call and the Vector4/EulerAngles construction from the CET wiki; confirmed live 2026-10-04.",
+            }
+            local okTp, e = pcall(function()
+                Game.GetTeleportationFacility():Teleport(pl, Vector4.new(x, y, z, 1.0), EulerAngles.new(0.0, 0.0, yaw))
+            end)
+            if not okTp then return errored("Teleport raised: " .. tostring(e), evidence) end
+            return ok(true, evidence)
+        end,
+    },
+
+    -- attested 2026-10-04: the level followed 15 -> 16 -> 15, read back each time.
+    --   Game.SetLevel(kind, n, 1)   (kind defaults to "Level")
+    ["cp2077.player.level"] = {
+        attestation = "attested 2026-10-04 (ran live, read back)",
+        citation = "Game.SetLevel(kind, level, 1), from the CET wiki",
+        effect = "mutate",
+        mutates = true,
+        run = function(probe)
+            local p = params(probe)
+            local lvl = tonumber(p.level)
+            if lvl == nil then return errored("params.level (a number) is required") end
+            local kind = p.kind ~= nil and tostring(p.kind) or "Level"
+            if not have("Game") then return absent("the `Game` global", "design §8 step 4") end
+            local evidence = {
+                level = lvl, kind = kind, call = "Game.SetLevel(kind, level, 1)",
+                note = "from the CET wiki; confirmed live 2026-10-04 (level read back).",
+            }
+            local okL, e = pcall(function() Game.SetLevel(kind, lvl, 1) end)
+            if not okL then return errored("Game.SetLevel raised: " .. tostring(e), evidence) end
+            return ok(true, evidence)
+        end,
+    },
 }
 -- MODWRIGHT-PROBE-TABLE-END
 
@@ -1138,7 +1246,13 @@ end
 --- The ids allowed to mutate anything: the inventory row it always had, and
 --- (since 2026-09-11) the eval row. Named
 --- as a constant so the gate below reads as the rule it enforces.
-Probes.MUTATING_KINDS = { ["cp2077.inventory.add"] = true, ["cp2077.lua.eval"] = true }
+Probes.MUTATING_KINDS = {
+    ["cp2077.inventory.add"] = true,
+    ["cp2077.lua.eval"] = true,
+    ["cp2077.world.spawn"] = true,
+    ["cp2077.player.teleport"] = true,
+    ["cp2077.player.level"] = true,
+}
 
 --- Run one probe. NEVER throws: one probe failing can never abort the batch, and a handler
 --- that raises is reported as `error` with the raised message.

package/bridges/cp2077-cet/README.md

@@ -167,8 +167,9 @@ the request grants the `session` tier. There is no token. The nonce and the requ
 only stop a consumed or stale request from running again; they do not say who wrote it. So:
 
 - deploy the bridge only to an install you control, and only while you are verifying a mod;
-- remove `bin/x64/plugins/cyber_engine_tweaks/mods/ModWrightBridge` when you are done,
-  before playing normally;
+- remove it when you are done, before playing normally:
+  `bridge action=remove path=<project> mode=apply` deletes every folder the project's
+  `withBridge` targets deployed, with a backup (a dry run first shows which);
 - never ship it. `cp2077.history.bridge-never-ships` blocks a release build that contains it.
 
 ## What this bridge never does

package/bridges/cp2077-cet/bridge.json

@@ -26,7 +26,7 @@
     "prune": [
       "ModWrightBridge/**"
     ],
-    "note": "The deploy target `bridge stage` adds to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit; paste it in yourself only if you want it there before staging. A deploy WITHOUT `--variant withBridge` prunes the folder back out, with backup."
+    "note": "The deploy target `bridge stage` adds to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit; paste it in yourself only if you want it there before staging. A deploy without `--variant withBridge` leaves an installed bridge where it is: a variant's prune runs only in a deploy that writes that variant. Take it out with `bridge action=remove path=<project> mode=apply` when you are done verifying (dry-run first; backed up)."
   },
   "sha256": {
     "algorithm": "sha256",
@@ -43,7 +43,7 @@
     },
     {
       "path": "ModWrightBridge/probes.lua",
-      "sha256": "169a31b158edcefda6721c3b90656c59fd9f7d7bf928a96d03ef3645a5eb1991"
+      "sha256": "759015ac7c1167faecbc5d29e91f567d7c45446164544ad7d72029c115a60df6"
     },
     {
       "path": "ModWrightBridge/protocol.lua",

package/dist/core/bridge/remove.js

@@ -0,0 +1,48 @@
+import * as path from "node:path";
+import { pathExists } from "../fsutil.js";
+import { escapesRoot } from "../project/outside-root.js";
+import { executePlan, planDelete } from "../safety/index.js";
+export const BRIDGE_VARIANT = "withBridge";
+export async function planRemoveBridge(project, roots) {
+    const removals = [];
+    const operations = [];
+    for (const target of project.project.deploy?.targets ?? []) {
+        if (target.variant !== BRIDGE_VARIANT || !target.into)
+            continue;
+        const base = { rootId: target.rootId, into: target.into };
+        if (escapesRoot(target.into)) {
+            removals.push({ ...base, action: "outside-root" });
+            continue;
+        }
+        const root = roots.find((r) => r.id === target.rootId);
+        if (!root) {
+            removals.push({ ...base, action: "unknown-root" });
+            continue;
+        }
+        const dest = path.join(root.path, target.into);
+        if (await pathExists(dest)) {
+            operations.push(planDelete(dest));
+            removals.push({ ...base, path: dest, action: "remove" });
+        }
+        else {
+            removals.push({ ...base, path: dest, action: "absent" });
+        }
+    }
+    return {
+        plan: {
+            purpose: `remove the deployed bridge of ${project.project.name}`,
+            operations,
+            backupRoot: path.join(project.root, ".modwright", "backups"),
+        },
+        removals,
+    };
+}
+export async function removeBridge(project, roots, options = {}) {
+    const { plan, removals } = await planRemoveBridge(project, roots);
+    const report = await executePlan(plan, {
+        mode: options.mode ?? "dry-run",
+        ...(options.now ? { now: options.now } : {}),
+        confidence: { level: "high", assumptions: [], verifiedBy: ["the project's withBridge deploy targets", "the game's mod roots"] },
+    });
+    return { ...report, removals };
+}

package/dist/core/testplan/registry.js

@@ -355,6 +355,39 @@ const CP2077_PROBES = [
             "loot-container template does carry a gameTargetingComponent), and whether the game marks TSF_* isExec. Never " +
             "run in game; stays unverified until a live run exercises it.",
     },
+    {
+        kind: "cp2077.world.spawn",
+        game: "cyberpunk2077",
+        context: "cet",
+        effect: "mutate",
+        status: "attested",
+        summary: "Spawn an entity from a resource path at the player's transform (exEntitySpawner.Spawn), returning the entity id handle; Game.FindEntityByID resolves it.",
+        citation: "cp2077.world.spawn; exEntitySpawner is a CET-added native (RTTIExtender.cpp); attested 2026-10-04",
+        paramsSchema: z.object({ entPath: str(), appearance: z.string().optional() }).strict(),
+        evidence: "Ran live 2026-10-04 (request req-muugz1b6-94911e04, game 3.0.80.51928): spawning base\\characters\\entities\\gang\\gang__wraith_ma.ent returned a handle and the NPC appeared where the player stood. Game.FindEntityByID(handle) in the same call returned nothing: the entity arrives after the call returns, so resolved:false is the normal result, not a failure.",
+    },
+    {
+        kind: "cp2077.player.teleport",
+        game: "cyberpunk2077",
+        context: "cet",
+        effect: "mutate",
+        status: "attested",
+        summary: "Teleport the player to a world position (Game.GetTeleportationFacility():Teleport). Optional yaw.",
+        citation: "cp2077.player.teleport (CET wiki); attested 2026-10-04",
+        paramsSchema: z.object({ x: z.number(), y: z.number(), z: z.number(), yaw: z.number().optional() }).strict(),
+        evidence: "Ran live 2026-10-04 (request req-muugz2is-a30b1095, game 3.0.80.51928): a teleport to x+4 moved the player from -2249.30,2790.43,7.00 to -2245.30,2790.43,7.01, read back through cp2077.lua.eval.",
+    },
+    {
+        kind: "cp2077.player.level",
+        game: "cyberpunk2077",
+        context: "cet",
+        effect: "mutate",
+        status: "attested",
+        summary: "Set a player progression level (Game.SetLevel(kind, n, 1)); kind defaults to \"Level\".",
+        citation: "cp2077.player.level (CET wiki); attested 2026-10-04",
+        paramsSchema: z.object({ level: z.number().int(), kind: z.string().optional() }).strict(),
+        evidence: "Ran live 2026-10-04 (requests req-muugz2is-a30b1095 and req-muugz457-1ded47cb, game 3.0.80.51928): Game.SetLevel(\"Level\", n, 1) moved the player level 15 to 16 and back to 15, each read back with StatsSystem.GetStatValue(player, gamedataStatType.Level).",
+    },
 ];
 export const PROBE_CATALOG = [...BG3_PROBES, ...CP2077_PROBES];
 const BY_KIND = new Map(PROBE_CATALOG.map((entry) => [entry.kind, entry]));

package/dist/server.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";
@@ -1401,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()
@@ -1475,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).');

package/knowledge/cyberpunk2077/cet.natives.yaml

@@ -0,0 +1,48 @@
+game: cyberpunk2077
+topic: cet.natives
+title: CET-added native functions used to set up a test (spawn, teleport, level)
+facts:
+  - id: cp2077.cet.natives.exentityspawner-spawn-despawn
+    claim: "`exEntitySpawner` is a native that CET adds. `exEntitySpawner.Spawn(entPath, transform,
+      appearance)` spawns an entity from a resource path (backslash form, e.g.
+      `base\\characters\\entities\\gang\\gang__wraith_ma.ent`) at the given WorldTransform and
+      returns an entity id handle (userdata); `Game.FindEntityByID(handle)` resolves it to the
+      entity object. `exEntitySpawner.Despawn(entity)` despawns it, and takes the resolved object,
+      not the id handle."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - cet
+      - native
+      - spawn
+      - despawn
+      - workbench
+      - exentityspawner
+    detail: "Backs the probe cp2077.world.spawn. Two caveats from the 2026-09-12 run: spawning at the
+      player's own transform puts the player inside the spawned entity until they separate; and the
+      id handle does not survive across bridge calls (each cp2077.lua.eval is a fresh state), so a
+      despawn or respawn has to resolve the entity within the same call. No call is known that turns
+      a stored id string back into a live EntityID. CET's WorldFunctionalTests
+      (SpawnEntity/DespawnEntity) is the other spawn native it adds; this fact is about
+      exEntitySpawner, the one exercised. On 2026-10-04 the spawned entity appeared, but
+      `Game.FindEntityByID(handle)` in the same call returned nothing: the entity arrives after
+      `Spawn` returns, so resolve it in a later call."
+  - id: cp2077.cet.natives.teleport-and-setlevel-work-from-cet
+    claim: From CET Lua, `Game.GetTeleportationFacility():Teleport(Game.GetPlayer(), Vector4.new(x, y,
+      z, 1), EulerAngles.new(0, 0, yaw))` moves the player to that position, and
+      `Game.SetLevel("Level", n, 1)` sets the player level; both take effect at once. The level
+      reads back as `Game.GetStatsSystem():GetStatValue(Game.GetPlayer():GetEntityID(),
+      gamedataStatType.Level)`.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - cet
+      - native
+      - teleport
+      - level
+      - workbench
+    detail: Backs the probes cp2077.player.teleport and cp2077.player.level. The teleport's z settled
+      0.01 above the target, which is the ground under the player. A save that has been teleported
+      or levelled this way should not be kept.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modwright",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A game-agnostic MCP server for game modding, with per-game surfaces.",
   "type": "module",
   "main": "dist/index.js",