modwright 0.1.0

package/bridges/cp2077-cet/README.md

@@ -0,0 +1,165 @@
+# cp2077-cet bridge
+
+The Cyberpunk 2077 Cyber Engine Tweaks bridge: ModWright's author-only verification mod. At
+load it feature-detects the CET sandbox; when a request reaches it, it runs the probes that
+request names and prints the result plus a `done` marker carrying the result's byte length. It
+is staged by `stageBridge(project, "cyberpunk2077")` (`src/core/bridge/stage.ts`) into
+`<project>/.modwright/bridge/cp2077-cet/`, and `deploy --variant withBridge` copies
+`ModWrightBridge` from there into the project's `cet` root
+(`bin/x64/plugins/cyber_engine_tweaks/mods/ModWrightBridge`).
+
+The protocol is implemented on the Node side in `src/core/bridge/`.
+
+## Two transports: files first, then console-armed and log-polled
+
+An in-game check (2026-09-08) ran `io.open` in the CET **console**: `io` is nil there (CET
+v1.37.1, game v3.0.80.51928). CET's changelog says that is by design and is not a fact about
+mods: 1.10 "stripped ImGui, json, io and dofile and such from console sandbox", in the same
+release that made mod pathing relative — "All pathing is now relative to mod (breaking change,
+includes all io functions, dofile() and such included)" (CET Nexus changelog, mod 107). Mods
+have `io`; the console does not. `cp2077.bridge.io` stays **unverified**, and the bridge's own
+capability line (`m.where()`'s `io`, which rides in every heartbeat and lands in the mod's own
+log) is what settles it. So:
+
+* **The file transport below stays first choice.** Whenever the bridge reports a live write
+  root, `bridge arm` writes the request there and `bridge poll` reads the result files, exactly
+  as for BG3.
+* **The console-and-log path is the fallback**, and it is what runs when the bridge
+  reports log-only. Both are tried on every arm and every poll, in that order.
+
+Reading that capability line is the first thing to do on a new install — it needs no game
+launch, because CET 1.9.1 ("Mods will now log to
+their own log files") means it is already in the newest `.log` under
+`bin/x64/plugins/cyber_engine_tweaks/mods/ModWrightBridge/`.
+
+* **Arming** — `bridge arm --game cyberpunk2077 --path <mod repo>` builds the same `Request`
+  it would for BG3, writes it into the write root when there is one, and always returns the
+  console line that hands it to the bridge:
+  `GetMod("ModWrightBridge").arm('<compact request JSON>')`, escaped for a Lua single-quoted
+  string. It records the nonce under `<project>/.modwright/bridge/pending/<id>.json`; a dry
+  run shows the line and records nothing. The Lua needed no change for this —
+  `init.lua`'s `armFn` → `Protocol.armFromString` already accepts that payload verbatim.
+* **Results** — a finished run writes `modwright_res_<id>.json` plus its `done` marker when it
+  can, and in log-only mode prints `[MODWRIGHT-RESULT] <json>` and then
+  `[MODWRIGHT-DONE] <json>` carrying the result's byte length. `bridge poll` checks the result
+  files first and then tails
+  the newest `.log` in the mod's own folder first (CET 1.9.1), then
+  `bin/x64/plugins/cyber_engine_tweaks/cyber_engine_tweaks.log` and `…/gamelog.log`, applies the same byte-length
+  completeness rule the file transport uses, matches the pending nonce, ignores lines older
+  than the arm, and says which file it read.
+* **Heartbeat** — written to `modwright_hb.json` every 2 s, or printed as
+  `[MODWRIGHT-HEARTBEAT] <json>` every 15 s in log-only mode. `bridge status` reads the file
+  first and the log lines second, judges freshness against whichever answered (15 s / 45 s),
+  and reports **`sandboxIo`** — the bridge's own `io` capability, which is the fact the whole
+  transport question turns on.
+* **`run_tests` can drive this game only when the sandbox has `io`.** It must run unattended:
+  against a file-writing bridge it arms and polls normally; against a log-only one it refuses
+  with `console-arm-required` naming the three-command flow instead.
+
+### The `io` write-root discovery
+
+Nothing on disk attests that CET's Lua sandbox has `io` at all (the first row of the probe
+catalogue), so at `onInit` the bridge tries three candidates in order —
+
+```
+modwright_hb.json
+mods/ModWrightBridge/modwright_hb.json
+plugins/cyber_engine_tweaks/mods/ModWrightBridge/modwright_hb.json
+```
+
+— keeps the first that opens **and accepts a write**, and reports the winner in every
+heartbeat's `writeRoot` with every failure string in `writeRootErrors`. ModWright polls the
+matching absolute directories under the install (`bridgeCandidateDirs`,
+`src/core/bridge/paths.ts`). If `io` turns out to be absent in the mod sandbox too, all three
+fail before they are tried and the bridge falls into the log-only mode described above.
+
+## protocolVersion
+
+**1** — the current value of `PROTOCOL_VERSION` in `src/core/bridge/types.ts`. The Lua defines
+the identical integer literal as `Protocol.PROTOCOL_VERSION` (`ModWrightBridge/protocol.lua`),
+"`protocolVersion` is an integer duplicated in the Lua and the Node constant, checked at arm
+time". `test/unit/bridge/cp2077-lua-parity.test.ts` asserts the two literals
+agree.
+
+## The tree
+
+```
+bridges/cp2077-cet/
+  bridge.json               # id, protocolVersion, version, deploy target, file list, sha256s
+  README.md                 # this file
+  ModWrightBridge/
+    init.lua                # registerForEvent onInit/onUpdate/onShutdown; returns the console table
+    protocol.lua            # write-root discovery, JSON framing, nonce arming, heartbeat, run loop
+    probes.lua              # the probe dispatch table
+```
+
+Three files. `init.lua` is CET's entry point and **must
+return a table** — knowledge fact `cp2077.process.cet-mods-sandboxed`, status `verified` on
+2.31 — so that `GetMod("ModWrightBridge")` is reachable from the console. The CET mods surveyed
+ship no manifest file, so none is invented.
+
+**How `init.lua` loads the other two comes from CET's changelog, not from a sibling on disk.**
+The CET mods surveyed have no second file. CET 1.10 made every mod path relative to the mod's
+own folder and `require` paths `/`-separated, and 1.9.1 deprecated `dofile` without removing
+it, so `init.lua` tries three routes in order — `require("protocol")`,
+`require("ModWrightBridge/protocol")`, `dofile("protocol.lua")` — reports the winner in the
+capability line, and, if all three fail, still returns a console table whose
+`status()`/`where()` print the three error strings. A CET mod that returns nothing cannot even
+be diagnosed.
+
+## The dispatch table
+
+Fenced with `-- MODWRIGHT-PROBE-TABLE-BEGIN` / `-- MODWRIGHT-PROBE-TABLE-END` in
+`probes.lua`, so the parity test reads only the table and never an id that appears in a
+comment. Thirteen ids, one per catalogue row, each carrying that row's own status word:
+
+| id | Status | If its call is missing |
+|---|---|---|
+| `cp2077.bridge.io` | unverified — the 2026-09-08 check ran in the console sandbox, which CET strips by design | `error` — and the bridge's own capability line says which case this install is in |
+| `cp2077.mod.loaded` | attested(engine) | — |
+| `cp2077.player.present` | attested(engine) | `error` if `Game` is absent |
+| `cp2077.item.equipped` | attested(engine) | — |
+| `cp2077.inventory.add` | attested(doc), **mutate** | `error`; skipped without `allowMutate` |
+| `cp2077.entity.tagged` | attested(engine) | — |
+| `cp2077.entity.components` | attested(engine) for the call; names unverified | `error` without `params.names` |
+| `cp2077.entity.transform` | attested(engine) for item objects; unverified for a sector prop | says which, in `evidence.attestationForThisCall` |
+| `cp2077.entity.appearance` | unverified (composite) | `skipped` without a baseline |
+| `cp2077.tweakdb.record` | unverified | `error` |
+| `cp2077.tweakdb.flat` | unverified | `error` |
+| `cp2077.interaction.present` | unverified (the component *name*) | `error` without `params.names` |
+| `cp2077.loot.roll` | **not designed** | always `unsupported` |
+
+Every probe result carries its row's `evidence.attestation` and `evidence.citation`, so the
+provenance of an answer travels with the answer.
+
+## The content banner
+
+`BRIDGE_BANNER` in `src/core/bridge/types.ts` (`"MODWRIGHT-BRIDGE-DO-NOT-SHIP"`) appears,
+verbatim, as the first line of every `.lua` file here. This is what lets
+`cp2077.history.bridge-never-ships` (`src/surfaces/cyberpunk2077/validators/bridge.ts`) catch a
+bridge file that reached a build output under a path that no longer says "ModWrightBridge" —
+e.g. flattened during packaging — not just one that still does.
+
+## Checking the Lua
+
+No Lua parser is vendored. Three checks:
+
+* `npm run bridge:lint` — shells to `luac -p` under 5.1 and 5.4 when either is on PATH, and
+  prints a one-line skip when neither is.
+* `test/unit/bridge/cp2077-lua-parity.test.ts` — reads the Lua as text: the dispatch-table keys
+  equal the catalogue's ids, every file carries the banner, the `PROTOCOL_VERSION` literals agree, and
+  `bridge.json` lists every file. It also runs `luac -p` when one is installed.
+* The CI job installing `lua5.1`/`lua5.4`.
+
+The Lua is kept inside the 5.1-compatible subset shipped CET mods use, and checked
+against both dialects — CET embeds a 5.4-era sol2, but nothing on disk pins which dialect
+features are available, so the intersection is the safe target.
+
+## What this bridge never does
+
+* It never observes: no CET listener API is attested, so `effect: "observe"` is `unsupported`
+  and `window.seconds` is ignored with a line in the result's `errors`.
+* It never calls anything that mutates except `Game.AddToInventory`, and only when the request
+  sets `allowMutate: true`. `m.probe()` from the console always passes `allowMutate: false`.
+* It never claims a `pass` for a call that is not there: an `unverified` row whose call is
+  missing returns `error` with a message naming what was missing and which check settles it.

package/bridges/cp2077-cet/bridge.json

@@ -0,0 +1,53 @@
+{
+  "id": "cp2077-cet",
+  "game": "cyberpunk2077",
+  "protocolVersion": 1,
+  "version": "0.1.0",
+  "modFolder": "ModWrightBridge",
+  "entryPoint": "ModWrightBridge/init.lua",
+  "banner": "MODWRIGHT-BRIDGE-DO-NOT-SHIP",
+  "transport": {
+    "primary": "file",
+    "fallback": "log",
+    "writeRootCandidates": [
+      "modwright_hb.json",
+      "mods/ModWrightBridge/modwright_hb.json",
+      "plugins/cyber_engine_tweaks/mods/ModWrightBridge/modwright_hb.json"
+    ],
+    "note": "The write root is DISCOVERED at onInit: the first candidate whose `io.open(candidate, \"w\")` succeeds wins, and the winner is reported in every heartbeat's `writeRoot`. The first candidate is the empty prefix, which since CET 1.10 (\"All pathing is now relative to mod\", CET Nexus changelog) means this mod's own folder — the directory ModWright polls first. Whether any candidate resolves is still `unverified`: the `io.open` check of 2026-09-08 was typed in the CET console, whose sandbox has io stripped by design (same changelog), so it tested the wrong half. If none does, the bridge prints each result as one `[MODWRIGHT-RESULT] <json>` line for `triage_logs` to recover."
+  },
+  "deploy": {
+    "rootId": "cet",
+    "from": ".modwright/bridge/cp2077-cet/ModWrightBridge",
+    "into": "ModWrightBridge",
+    "variant": "withBridge",
+    "locked": false,
+    "backup": true,
+    "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."
+  },
+  "sha256": {
+    "algorithm": "sha256",
+    "encoding": "hex",
+    "over": "the file's raw bytes, unmodified",
+    "paths": "POSIX-separated, relative to bridges/cp2077-cet/",
+    "regenerate": "python3 -c \"import hashlib,sys;print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())\" <path>",
+    "note": "Recomputed by hand whenever a file here changes; `bridge stage` (src/core/bridge/stage.ts) copies the tree verbatim and does not fill these in, and nothing in ModWright reads them yet. They exist so a staged or deployed copy can be compared against the source of truth by hand."
+  },
+  "files": [
+    {
+      "path": "ModWrightBridge/init.lua",
+      "sha256": "269528f9a81576f345ec1c679ace5331ae6ccfbb174d4d09efd09d3fb4fc91d8"
+    },
+    {
+      "path": "ModWrightBridge/probes.lua",
+      "sha256": "a9dc28d3fd949f353f17404366bd2bb329813b9ca639e06a9b51aa34c104fb7d"
+    },
+    {
+      "path": "ModWrightBridge/protocol.lua",
+      "sha256": "f4a59d07883ac9bcdb2da2d5d4cdcd3af42c322a40751515c551c9057ac24210"
+    }
+  ]
+}

package/dist/core/bridge/arm.js

@@ -0,0 +1,175 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import { executePlan, planFile } from "../safety/index.js";
+import { cetArmConsoleLine, cetArmSteps, compactRequestJson } from "./cet-console.js";
+import { buildPendingArm, pendingArmFile, planPruneExpiredPendingArms, planRecordPendingArm } from "./pending.js";
+import { bridgeFileNames } from "./paths.js";
+import { PROTOCOL_VERSION, bridgeRequestSchema } from "./types.js";
+import { bridgeStatus } from "./status.js";
+export function generateNonce() {
+    return crypto.randomBytes(8).toString("hex");
+}
+export function generateRequestId() {
+    return `req-${Date.now().toString(36)}-${crypto.randomBytes(4).toString("hex")}`;
+}
+export function buildRequest(opts) {
+    const now = opts.now ?? (() => new Date());
+    const issuedAt = now();
+    const armForMs = (opts.armForSeconds ?? 60) * 1000;
+    const grant = opts.grant ?? (opts.allowMutate ? ["session"] : undefined);
+    const allowMutate = grant ? grant.includes("session") : opts.allowMutate ?? false;
+    const request = {
+        protocolVersion: PROTOCOL_VERSION,
+        id: opts.id ?? generateRequestId(),
+        nonce: opts.nonce ?? generateNonce(),
+        issuedAt: issuedAt.toISOString(),
+        armedUntil: new Date(issuedAt.getTime() + armForMs).toISOString(),
+        game: opts.game,
+        allowMutate,
+        ...(grant ? { grant } : {}),
+        ...(opts.window ? { window: opts.window } : {}),
+        ...(opts.plan ? { plan: opts.plan } : {}),
+        probes: opts.probes,
+    };
+    return bridgeRequestSchema.parse(request);
+}
+export function planArmRequest(dirAbs, request) {
+    const files = bridgeFileNames(request.game);
+    const reqPath = path.join(dirAbs, files.request);
+    const markerPath = path.join(dirAbs, files.requestMarker);
+    const reqJson = `${JSON.stringify(request, null, 2)}\n`;
+    const marker = {
+        protocolVersion: PROTOCOL_VERSION,
+        id: request.id,
+        nonce: request.nonce,
+        bytes: Buffer.byteLength(reqJson, "utf8"),
+    };
+    return {
+        purpose: `arm bridge request ${request.id} (${request.game})`,
+        operations: [planFile(reqPath, reqJson), planFile(markerPath, `${JSON.stringify(marker, null, 2)}\n`)],
+    };
+}
+export async function armBridge(input) {
+    const status = await bridgeStatus(input.game, input.install, input.surface, { now: input.now, readFile: input.readFile });
+    if (status.found && !status.protocolVersionMatch) {
+        return {
+            game: input.game,
+            transport: input.game === "cyberpunk2077" ? "console" : "file",
+            status,
+            refused: { reason: "protocol-mismatch", message: status.message },
+        };
+    }
+    if (input.game === "cyberpunk2077")
+        return armCyberpunk(input, status);
+    const dir = status.dir ?? (status.candidates.length === 1 ? status.candidates[0] : undefined);
+    if (!dir) {
+        return {
+            game: input.game,
+            transport: "file",
+            status,
+            refused: {
+                reason: "unknown-write-root",
+                message: `No heartbeat was found and ${input.game} has more than one possible write root, so ModWright cannot tell ` +
+                    `which one the bridge will use. Launch the game once with the bridge deployed and staged, then retry.`,
+            },
+        };
+    }
+    const now = input.now ?? (() => new Date());
+    const request = buildRequest(input);
+    const plan = planArmRequest(dir, request);
+    if (input.projectRoot) {
+        const armedAt = now();
+        plan.operations.push(...planRecordPendingArm(input.projectRoot, buildPendingArm(request, undefined, armedAt, input.window?.seconds)).operations, ...(await planPruneExpiredPendingArms(input.projectRoot, input.game, armedAt)));
+    }
+    const confidence = {
+        level: status.found ? "high" : "medium",
+        assumptions: status.found
+            ? []
+            : [`No live heartbeat was seen; armed into the only possible directory for ${input.game} ahead of the bridge starting.`],
+        verifiedBy: status.found ? ["bridge heartbeat"] : [],
+    };
+    const write = await executePlan(input.projectRoot ? { ...plan, backupRoot: path.join(input.projectRoot, ".modwright", "backups") } : plan, { mode: input.mode ?? "dry-run", now: input.now, confidence });
+    return {
+        game: input.game,
+        transport: "file",
+        status,
+        dir,
+        request,
+        write,
+        ...(input.projectRoot && (input.mode ?? "dry-run") === "apply" ? { pendingFile: pendingArmFile(input.projectRoot, request.id) } : {}),
+    };
+}
+async function armCyberpunk(input, status) {
+    const now = input.now ?? (() => new Date());
+    const request = buildRequest(input);
+    const consoleLine = cetArmConsoleLine(request);
+    const fileDir = status.transport === "file" ? status.dir : undefined;
+    if (!fileDir && !input.console) {
+        return {
+            game: input.game,
+            transport: "console",
+            status,
+            request,
+            refused: {
+                reason: "console-arm-required",
+                message: `This bridge is not writing files ModWright can find (${status.sandboxIo === false ? "its capability line reports no io in the mod sandbox" : "no heartbeat file was found"}), ` +
+                    `so the request only reaches it when a human pastes one CET console line. This caller cannot wait ` +
+                    `for that. Run the "bridge" tool's "arm" action with the project path to get the line and record the nonce, ` +
+                    `paste it into the CET console, then "bridge poll".`,
+            },
+        };
+    }
+    if (!fileDir && !input.projectRoot) {
+        return {
+            game: input.game,
+            transport: "console",
+            status,
+            request,
+            refused: {
+                reason: "no-project-root",
+                message: `A console-armed Cyberpunk request records its pending nonce under <project>/.modwright/bridge/pending/ so ` +
+                    `"bridge poll" can match the result lines in the CET log. Pass the mod project's path.`,
+            },
+        };
+    }
+    const armedAt = now();
+    const mode = input.mode ?? "dry-run";
+    const operations = [
+        ...(fileDir ? planArmRequest(fileDir, request).operations : []),
+        ...(input.projectRoot
+            ? planRecordPendingArm(input.projectRoot, buildPendingArm(request, consoleLine, armedAt, input.window?.seconds)).operations
+            : []),
+        ...(input.projectRoot ? await planPruneExpiredPendingArms(input.projectRoot, input.game, armedAt) : []),
+    ];
+    const confidence = {
+        level: status.found ? "high" : "medium",
+        assumptions: [
+            ...(fileDir
+                ? [`The bridge reports a live write root, so the request was written there as well; if it never picks it up, paste the console line instead.`]
+                : [`The request reaches the bridge only when a human pastes the console line; ModWright cannot confirm that it was run.`]),
+            ...(status.found
+                ? []
+                : ["No heartbeat was found in either transport, so the bridge may not be loaded yet — the console line can still be pasted once it is."]),
+        ],
+        verifiedBy: status.found ? [`bridge heartbeat (${status.transport} transport)`] : [],
+    };
+    const write = await executePlan({
+        purpose: `arm bridge request ${request.id} (cyberpunk2077, ${fileDir ? "file + console" : "console"})`,
+        operations,
+        ...(input.projectRoot ? { backupRoot: path.join(input.projectRoot, ".modwright", "backups") } : {}),
+    }, { mode, now: input.now, confidence });
+    return {
+        game: input.game,
+        transport: fileDir ? "file" : "console",
+        status,
+        ...(fileDir ? { dir: fileDir } : {}),
+        request,
+        write,
+        console: {
+            consoleLine,
+            requestJson: compactRequestJson(request),
+            ...(mode === "apply" && input.projectRoot ? { pendingFile: pendingArmFile(input.projectRoot, request.id) } : {}),
+            steps: cetArmSteps(request, mode === "apply" && input.projectRoot ? pendingArmFile(input.projectRoot, request.id) : undefined, Boolean(fileDir)),
+        },
+    };
+}

package/dist/core/bridge/cet-console.js

@@ -0,0 +1,26 @@
+import { CET_DONE_TAG, CET_RESULT_TAG } from "./cet-log.js";
+export const CET_CONSOLE_MOD = "ModWrightBridge";
+export function compactRequestJson(request) {
+    return JSON.stringify(request).replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+export function luaSingleQuoted(value) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+export function cetArmConsoleLine(request) {
+    return `GetMod("${CET_CONSOLE_MOD}").arm('${luaSingleQuoted(compactRequestJson(request))}')`;
+}
+export function cetArmSteps(request, pendingFile, alsoWrittenAsFile = false) {
+    return [
+        ...(alsoWrittenAsFile
+            ? [
+                `The request was also written as a file into the write root this bridge reported, so it may be picked up on its own within a second — poll first, and only paste the line below if nothing comes back.`,
+            ]
+            : []),
+        `Open the CET console (~) with a save loaded and paste the line in "consoleLine" exactly as it is, on one line.`,
+        `The bridge prints "[ModWrightBridge] armed by hand" and then, when the probes finish, one ${CET_RESULT_TAG} line ` +
+            `followed by one ${CET_DONE_TAG} line.`,
+        `Close the console if any probe reads pose, animation or equipment: the weapon drops into the holstered pose while the console is open.`,
+        `Then run bridge poll — id "${request.id}"${pendingFile ? ` (recorded in ${pendingFile})` : ""} — which tails the CET log for those two lines.`,
+        `The request stays armed until ${request.armedUntil}; after that the bridge refuses it with disarm.reason "expired".`,
+    ];
+}