modwright 0.1.0

package/dist/core/testplan/run.js

@@ -0,0 +1,389 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import { armBridge, bridgeStatus, pollForResult, resolveGrant, ALL_TIERS } from "../bridge/index.js";
+import { executePlan, planFile, planMkdir } from "../safety/index.js";
+import { checkRowProbes, rowProbeKinds, worstAttestation } from "./check.js";
+import { loadTestPlans, resolveTestPlan, saveTestPlan } from "./load.js";
+import { isChecklistOnly } from "./types.js";
+import { applyClaimTransition, evidenceDir, loadClaims, saveClaims } from "../ledger/index.js";
+const ROW_PROBE_SEPARATOR = "::";
+const SETUP_MARKER = "setup::";
+function prefixedProbeId(rowId, probeId, setup = false) {
+    return `${rowId}${ROW_PROBE_SEPARATOR}${setup ? SETUP_MARKER : ""}${probeId}`;
+}
+function splitPrefixedProbeId(id) {
+    const at = id.indexOf(ROW_PROBE_SEPARATOR);
+    if (at === -1)
+        return undefined;
+    const rowId = id.slice(0, at);
+    let rest = id.slice(at + ROW_PROBE_SEPARATOR.length);
+    let setup = false;
+    if (rest.startsWith(SETUP_MARKER)) {
+        setup = true;
+        rest = rest.slice(SETUP_MARKER.length);
+    }
+    return { rowId, probeId: rest, setup };
+}
+function selectRows(plan, rowIds, gates) {
+    let rows = plan.rows;
+    if (rowIds && rowIds.length > 0) {
+        const set = new Set(rowIds);
+        rows = rows.filter((r) => set.has(r.id));
+    }
+    if (gates && gates.length > 0) {
+        const set = new Set(gates);
+        rows = rows.filter((r) => set.has(r.gate));
+    }
+    return rows;
+}
+function verdictFromProbeResults(results) {
+    if (results.length === 0)
+        return "skipped";
+    if (results.some((r) => r.status === "error" || r.status === "unsupported"))
+        return "blocked";
+    if (results.some((r) => r.status === "skipped"))
+        return "skipped";
+    if (results.every((r) => r.status === "pass"))
+        return "verified";
+    return "contradicted";
+}
+function generateRunId(now) {
+    return `run-${now().getTime().toString(36)}-${crypto.randomBytes(4).toString("hex")}`;
+}
+function sha256(text) {
+    return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+const STALE_LAUNCH_ROUTE = {
+    baldursgate3: {
+        confirmedRoute: "Confirmed route: a Steam launch option of --skip-launcher, with a normal steam://rungameid/1086940 " +
+            "launch (a direct bg3.exe --skip-launcher invocation was also tried and works).",
+        readinessTest: "bridge status reports a fresh heartbeat once the game has reached the main menu or a save is loaded.",
+    },
+    cyberpunk2077: {
+        confirmedRoute: "No non-interactive launch route is confirmed for Cyberpunk 2077; start the game normally.",
+        readinessTest: "bridge status reports a fresh heartbeat once CET has finished loading (a save, or the main menu).",
+    },
+};
+function staleHeartbeatLaunchBlock(game, message) {
+    const route = STALE_LAUNCH_ROUTE[game];
+    return {
+        reason: "stale-heartbeat",
+        message: `run_tests refuses to arm on a stale heartbeat: ${message}`,
+        confirmedRoute: route.confirmedRoute,
+        readinessTest: route.readinessTest,
+        caveat: "ModWright never launches the game itself and never sends a reload command — start it by hand, then re-run run_tests.",
+    };
+}
+function alreadyVerified(row) {
+    return row.status === "verified";
+}
+export async function runTestPlan(input) {
+    const now = input.now ?? (() => new Date());
+    const runId = generateRunId(now);
+    const loaded = await resolveTestPlan(input.project, input.plan);
+    if (!loaded) {
+        const { plans } = await loadTestPlans(input.project);
+        throw new Error(`No test plan "${input.plan}" found. Known plan ids: ${plans.map((p) => p.plan.planId).join(", ") || "(none — check modwright.json's testPlans, or the default tests/*.yaml)"}`);
+    }
+    const { plan, path: planPath } = loaded;
+    const game = plan.game;
+    const selected = selectRows(plan, input.rows, input.gates);
+    const automatable = selected.filter((r) => !isChecklistOnly(r));
+    const manual = selected.filter((r) => isChecklistOnly(r));
+    const status = input.install
+        ? await bridgeStatus(game, input.install, input.surface, { now: input.now })
+        : { found: false, freshness: "absent", message: "No install was given, so bridge status could not be checked." };
+    const results = [];
+    const checklist = [];
+    let armed;
+    let refusedToArm;
+    let launchBlock;
+    let bridgeResult;
+    const rowRefusals = new Map();
+    const runnable = [];
+    for (const row of automatable) {
+        const refusals = checkRowProbes(row, game);
+        if (refusals.length > 0) {
+            rowRefusals.set(row.id, refusals);
+        }
+        else {
+            runnable.push(row);
+        }
+    }
+    const combinedProbes = [];
+    const overflowRowIds = new Set();
+    for (const row of runnable) {
+        const setupProbes = row.setup ?? [];
+        const rowProbes = row.probe.probes;
+        if (combinedProbes.length + setupProbes.length + rowProbes.length > 64) {
+            overflowRowIds.add(row.id);
+            continue;
+        }
+        for (const probe of setupProbes) {
+            combinedProbes.push({ ...probe, id: prefixedProbeId(row.id, probe.id, true) });
+        }
+        for (const probe of rowProbes) {
+            combinedProbes.push({ ...probe, id: prefixedProbeId(row.id, probe.id) });
+        }
+    }
+    const includedRunnable = runnable.filter((r) => !overflowRowIds.has(r.id));
+    const policyMode = input.policyMode ?? (input.allowMutate ? "workbench" : input.project.project.bridge?.policy?.mode ?? "verify");
+    const declaredGrant = input.project.project.bridge?.policy?.grant;
+    const anySetup = includedRunnable.some((r) => (r.setup?.length ?? 0) > 0);
+    const grantSet = new Set(resolveGrant(policyMode, declaredGrant));
+    if (input.allowMutate || anySetup)
+        grantSet.add("session");
+    const grant = ALL_TIERS.filter((t) => grantSet.has(t));
+    const deprecations = [];
+    if (input.allowMutate) {
+        deprecations.push('allowMutate is deprecated: it was mapped to grant:["session"]. Set bridge.policy.mode: workbench in modwright.json, or pass policyMode: "workbench", instead.');
+    }
+    const windowSeconds = Math.max(input.window?.seconds ?? 0, ...includedRunnable.map((r) => r.probe?.window?.seconds ?? 0), 0);
+    if (combinedProbes.length > 0 && input.mode === "apply") {
+        if (!input.install) {
+            refusedToArm = { reason: "no-install", message: "No install was given, so run_tests cannot arm the bridge." };
+        }
+        else if (status.found && status.freshness === "stale") {
+            refusedToArm = { reason: "stale-heartbeat", message: status.message };
+            launchBlock = staleHeartbeatLaunchBlock(game, status.message);
+        }
+        else {
+            const armResult = await armBridge({
+                game,
+                install: input.install,
+                surface: input.surface,
+                probes: combinedProbes,
+                grant,
+                window: windowSeconds > 0 ? { seconds: windowSeconds } : undefined,
+                plan: { planId: plan.planId, planPath, runId },
+                mode: "apply",
+                now: input.now,
+            });
+            if (armResult.refused) {
+                refusedToArm = armResult.refused;
+            }
+            else if (armResult.request && armResult.dir) {
+                armed = {
+                    id: armResult.request.id,
+                    nonce: armResult.request.nonce,
+                    armedUntil: armResult.request.armedUntil,
+                    probeCount: combinedProbes.length,
+                };
+                const outcome = await pollForResult({
+                    game,
+                    dirs: [armResult.dir],
+                    id: armResult.request.id,
+                    nonce: armResult.request.nonce,
+                    probeCount: combinedProbes.length,
+                    windowSeconds,
+                    timeoutMs: input.timeoutSeconds ? input.timeoutSeconds * 1000 : undefined,
+                    now: input.now,
+                    sleep: input.sleep,
+                });
+                if (outcome.status === "complete") {
+                    bridgeResult = outcome.result;
+                }
+                else {
+                    refusedToArm = { reason: `poll-timeout-${outcome.reason}`, message: outcome.message };
+                }
+            }
+        }
+    }
+    else if (combinedProbes.length > 0) {
+        armed = {
+            id: `${runId}-preview`,
+            nonce: "0".repeat(16),
+            armedUntil: new Date(now().getTime() + 60_000).toISOString(),
+            probeCount: combinedProbes.length,
+        };
+    }
+    let evidencePath;
+    let evidenceSha256;
+    if (bridgeResult && input.mode === "apply") {
+        const dir = evidenceDir(input.project.root, runId);
+        const file = path.join(dir, "result.json");
+        const json = `${JSON.stringify(bridgeResult, null, 2)}\n`;
+        await executePlan({ purpose: `archive run_tests result ${runId}`, operations: [planMkdir(dir), planFile(file, json)], backupRoot: path.join(input.project.root, ".modwright", "backups") }, { mode: "apply", now: input.now, confidence: { level: "high", assumptions: [], verifiedBy: ["bridge result"] } });
+        evidencePath = path.relative(input.project.root, file).split(path.sep).join("/");
+        evidenceSha256 = sha256(json);
+    }
+    const probesByRow = new Map();
+    const setupByRow = new Map();
+    if (bridgeResult) {
+        for (const probeResult of bridgeResult.probes) {
+            const split = splitPrefixedProbeId(probeResult.id);
+            if (!split)
+                continue;
+            const target = split.setup ? setupByRow : probesByRow;
+            const list = target.get(split.rowId) ?? [];
+            list.push({ ...probeResult, id: split.probeId });
+            target.set(split.rowId, list);
+        }
+    }
+    const ledgerTransitions = [];
+    const loadedClaims = await loadClaims(input.project.root);
+    let claimsState = loadedClaims.claims;
+    const claimsFileExists = loadedClaims.exists;
+    for (const row of selected) {
+        if (isChecklistOnly(row)) {
+            results.push({ rowId: row.id, gate: row.gate, manual: true, probeStatuses: [], observed: row.observed, status: row.status, evidence: row.evidence, claim: row.claim });
+            if (!alreadyVerified(row)) {
+                checklist.push({
+                    rowId: row.id,
+                    gate: row.gate,
+                    title: row.title,
+                    preconditions: row.preconditions,
+                    steps: row.steps,
+                    expected: row.expected,
+                    reason: "manual row",
+                });
+            }
+            continue;
+        }
+        const refusals = rowRefusals.get(row.id);
+        if (refusals && refusals.length > 0) {
+            results.push({ rowId: row.id, gate: row.gate, manual: false, probeStatuses: [], observed: undefined, status: "blocked", refusals, claim: row.claim });
+            checklist.push({
+                rowId: row.id,
+                gate: row.gate,
+                title: row.title,
+                preconditions: row.preconditions,
+                steps: row.steps,
+                expected: row.expected,
+                reason: `probe refused: ${refusals.map((r) => r.reason).join("; ")}`,
+            });
+            continue;
+        }
+        if (overflowRowIds.has(row.id)) {
+            results.push({ rowId: row.id, gate: row.gate, manual: false, probeStatuses: [], observed: undefined, status: "blocked", claim: row.claim });
+            checklist.push({
+                rowId: row.id,
+                gate: row.gate,
+                title: row.title,
+                preconditions: row.preconditions,
+                steps: row.steps,
+                expected: row.expected,
+                reason: "not run: this row's probes would push the combined request past the 64-probe protocol ceiling; re-run with fewer rows selected.",
+            });
+            continue;
+        }
+        if (input.mode !== "apply" || !bridgeResult) {
+            const reason = refusedToArm ? `bridge did not run: ${refusedToArm.message}` : "dry-run: not executed";
+            results.push({ rowId: row.id, gate: row.gate, manual: false, probeStatuses: [], observed: row.observed, status: row.status, claim: row.claim });
+            checklist.push({ rowId: row.id, gate: row.gate, title: row.title, preconditions: row.preconditions, steps: row.steps, expected: row.expected, reason });
+            continue;
+        }
+        const probeResults = probesByRow.get(row.id) ?? [];
+        const setupResults = setupByRow.get(row.id) ?? [];
+        const setupKinds = (row.setup ?? []).map((p) => p.kind);
+        const setupFailed = setupResults.some((r) => r.status !== "pass");
+        const verdict = setupFailed ? "blocked" : verdictFromProbeResults(probeResults);
+        const attestation = worstAttestation(rowProbeKinds(row));
+        const capped = verdict === "verified" && attestation === "unverified";
+        const finalStatus = capped ? "authored" : verdict;
+        const evidence = evidencePath && evidenceSha256 && (finalStatus === "verified" || finalStatus === "contradicted")
+            ? { runId, resultPath: evidencePath, resultSha256: evidenceSha256, observedAt: bridgeResult.finishedAt }
+            : row.evidence;
+        results.push({
+            rowId: row.id,
+            gate: row.gate,
+            manual: false,
+            probeStatuses: probeResults,
+            ...(setupResults.length > 0 ? { setupStatuses: setupResults } : {}),
+            observed: probeResults.map((p) => p.observed),
+            status: finalStatus,
+            evidence,
+            capped,
+            ...(setupKinds.length > 0 ? { verifiedWithSetup: setupKinds } : {}),
+            claim: row.claim,
+        });
+        if (finalStatus !== "verified") {
+            checklist.push({
+                rowId: row.id,
+                gate: row.gate,
+                title: row.title,
+                preconditions: row.preconditions,
+                steps: row.steps,
+                expected: row.expected,
+                reason: setupFailed
+                    ? `setup did not complete: ${setupResults.filter((r) => r.status !== "pass").map((r) => `${r.id} ${r.status}`).join(", ")}`
+                    : capped
+                        ? `probe kind is unverified — a pass cannot promote past "authored" without human corroboration`
+                        : `result: ${finalStatus}`,
+            });
+        }
+        if (row.claim && claimsFileExists && (finalStatus === "verified" || finalStatus === "contradicted") && evidence) {
+            const claimEvidence = {
+                runId,
+                planId: plan.planId,
+                rowId: row.id,
+                probeId: probeResults[0]?.id ?? row.id,
+                probeKind: rowProbeKinds(row)[0] ?? "unknown",
+                resultPath: evidence.resultPath,
+                resultSha256: evidence.resultSha256,
+                observedAt: evidence.observedAt,
+                observed: probeResults.map((p) => p.observed),
+                ...(setupKinds.length > 0 ? { verifiedWithSetup: setupKinds } : {}),
+            };
+            const existing = claimsState.find((c) => c.id === row.claim);
+            const transition = applyClaimTransition({
+                claims: claimsState,
+                id: row.claim,
+                to: finalStatus,
+                tool: "run_tests",
+                by: input.by ?? "run_tests",
+                now: input.now,
+                evidence: [claimEvidence],
+            });
+            ledgerTransitions.push({
+                claimId: row.claim,
+                from: existing?.status ?? "(new)",
+                to: finalStatus,
+                ok: transition.ok,
+                refusal: transition.refusal,
+            });
+            if (transition.ok)
+                claimsState = transition.claims;
+        }
+    }
+    if (ledgerTransitions.some((t) => t.ok) && input.mode === "apply") {
+        await saveClaims(input.project.root, claimsState, { mode: "apply", now: input.now });
+    }
+    if (input.mode === "apply") {
+        const byRowId = new Map(results.map((r) => [r.rowId, r]));
+        const updatedPlan = {
+            ...plan,
+            rows: plan.rows.map((row) => {
+                const result = byRowId.get(row.id);
+                if (!result)
+                    return row;
+                return { ...row, observed: result.observed, status: result.status, evidence: result.evidence };
+            }),
+        };
+        await saveTestPlan(planPath, updatedPlan, { mode: "apply", now: input.now, backupRoot: path.join(input.project.root, ".modwright", "backups") });
+    }
+    const checklistLineCount = checklist.reduce((n, entry) => n + 1 + entry.preconditions.length + entry.steps.length, 0);
+    const next = input.mode === "dry-run"
+        ? `Nothing was armed. Re-run with { mode: "apply" } to arm the bridge for ${includedRunnable.length} automatable row(s) and print the same checklist.`
+        : refusedToArm
+            ? `run_tests did not complete: ${refusedToArm.message}`
+            : `Ran ${includedRunnable.length} automatable row(s); ${checklist.length} row(s) need the printed checklist.`;
+    return {
+        plan: { planId: plan.planId, path: planPath, title: plan.title, game },
+        runId,
+        policy: { mode: policyMode, grant },
+        ...(deprecations.length > 0 ? { deprecations } : {}),
+        rowsTotal: selected.length,
+        automatedCount: automatable.length,
+        manualCount: manual.length,
+        heartbeat: { found: status.found, freshness: status.freshness, message: status.message },
+        armed,
+        refusedToArm,
+        launchBlock,
+        results,
+        checklist,
+        checklistLineCount,
+        ledger: { transitions: ledgerTransitions },
+        next,
+    };
+}

package/dist/core/testplan/types.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { bridgeGameSchema, probeSchema } from "../bridge/types.js";
+const iso8601Schema = z.string().refine((s) => !Number.isNaN(Date.parse(s)), {
+    message: "must be a parseable ISO 8601 timestamp",
+});
+export const testPlanRowStatusSchema = z.enum(["authored", "verified", "contradicted", "blocked", "skipped"]);
+export const testPlanEvidenceSchema = z
+    .object({
+    runId: z.string().min(1),
+    resultPath: z.string().min(1),
+    resultSha256: z.string().regex(/^[0-9a-f]{64}$/, "must be a 64-character hex sha256"),
+    observedAt: iso8601Schema,
+})
+    .strict();
+export const testPlanProbeRequestSchema = z
+    .object({
+    window: z.object({ seconds: z.number().nonnegative() }).strict().optional(),
+    allowMutate: z.boolean().default(false),
+    probes: z.array(probeSchema).min(1).max(64),
+})
+    .strict();
+export const testPlanRowSchema = z
+    .object({
+    id: z.string().min(1),
+    gate: z.string().min(1),
+    title: z.string().min(1),
+    preconditions: z.array(z.string().min(1)).default([]),
+    steps: z.array(z.string().min(1)).default([]),
+    expected: z.string().min(1),
+    probe: testPlanProbeRequestSchema.optional(),
+    setup: z.array(probeSchema).min(1).max(64).optional(),
+    manual: z.boolean().default(false),
+    claim: z.string().min(1).optional(),
+    observed: z.unknown().optional(),
+    status: testPlanRowStatusSchema.default("authored"),
+    evidence: testPlanEvidenceSchema.optional(),
+})
+    .strict();
+export const testPlanFixtureSchema = z
+    .object({
+    save: z.string().optional(),
+    notes: z.string().optional(),
+})
+    .strict();
+export const testPlanSchema = z
+    .object({
+    planId: z.string().min(1),
+    title: z.string().min(1),
+    game: bridgeGameSchema,
+    fixture: testPlanFixtureSchema.optional(),
+    rows: z.array(testPlanRowSchema).min(1),
+})
+    .strict();
+export function isChecklistOnly(row) {
+    return row.manual || !row.probe;
+}
+function formatPath(segments) {
+    if (segments.length === 0)
+        return "(root)";
+    let out = "";
+    for (const segment of segments) {
+        out += typeof segment === "number" ? `[${segment}]` : out ? `.${segment}` : segment;
+    }
+    return out;
+}
+export function parseTestPlan(raw) {
+    const result = testPlanSchema.safeParse(raw);
+    if (result.success)
+        return result.data;
+    const rawRows = Array.isArray(raw?.rows) ? (raw.rows) : [];
+    const lines = result.error.issues.map((issue) => {
+        const [first, second, ...rest] = issue.path;
+        if (first === "rows" && typeof second === "number") {
+            const rawRow = rawRows[second];
+            const rowId = typeof rawRow?.id === "string" ? rawRow.id : `#${second}`;
+            const field = rest.length > 0 ? ` ${formatPath(rest)}` : "";
+            return `rows[${second}] (id=${rowId})${field}: ${issue.message}`;
+        }
+        return `${formatPath(issue.path)}: ${issue.message}`;
+    });
+    throw new Error(`Invalid test plan:\n${lines.join("\n")}`);
+}

package/dist/core/text/converters/bg3.js

@@ -0,0 +1,50 @@
+function argv(action, sourceAbs, destAbs) {
+    return ["-g", "bg3", "-a", action, "-s", sourceAbs, "-d", destAbs];
+}
+export const LSX_TO_LSF = {
+    id: "bg3.lsx-to-lsf",
+    surface: "baldursgate3",
+    from: ".lsx",
+    to: ".lsf",
+    toolId: "divine",
+    inverse: "bg3.lsf-to-lsx",
+    roundTrip: "reverse-and-field-diff",
+    diffKind: "lsx",
+    argv: (s, d) => argv("convert-resource", s, d),
+    describe: (s, d) => `divine -g bg3 -a convert-resource -s ${s} -d ${d}`,
+};
+export const LSF_TO_LSX = {
+    id: "bg3.lsf-to-lsx",
+    surface: "baldursgate3",
+    from: ".lsf",
+    to: ".lsx",
+    toolId: "divine",
+    inverse: "bg3.lsx-to-lsf",
+    roundTrip: "forward-and-byte-compare",
+    argv: (s, d) => argv("convert-resource", s, d),
+    describe: (s, d) => `divine -g bg3 -a convert-resource -s ${s} -d ${d}`,
+};
+export const XML_TO_LOCA = {
+    id: "bg3.xml-to-loca",
+    surface: "baldursgate3",
+    from: ".xml",
+    to: ".loca",
+    toolId: "divine",
+    inverse: "bg3.loca-to-xml",
+    roundTrip: "reverse-and-field-diff",
+    diffKind: "loca-xml",
+    argv: (s, d) => argv("convert-loca", s, d),
+    describe: (s, d) => `divine -g bg3 -a convert-loca -s ${s} -d ${d}`,
+};
+export const LOCA_TO_XML = {
+    id: "bg3.loca-to-xml",
+    surface: "baldursgate3",
+    from: ".loca",
+    to: ".xml",
+    toolId: "divine",
+    inverse: "bg3.xml-to-loca",
+    roundTrip: "forward-and-byte-compare",
+    argv: (s, d) => argv("convert-loca", s, d),
+    describe: (s, d) => `divine -g bg3 -a convert-loca -s ${s} -d ${d}`,
+};
+export const BG3_CONVERTERS = [LSX_TO_LSF, LSF_TO_LSX, XML_TO_LOCA, LOCA_TO_XML];

package/dist/core/text/converters/cyberpunk.js

@@ -0,0 +1,36 @@
+import * as path from "node:path";
+function argv(action, sourceAbs, destDirAbs) {
+    return ["convert", action, sourceAbs, "-o", destDirAbs];
+}
+function expectedOutputName(action, sourceAbs) {
+    const base = path.basename(sourceAbs);
+    return action === "serialize" ? `${base}.json` : base.replace(/\.json$/i, "");
+}
+export const CR2W_TO_JSON = {
+    id: "cp2077.cr2w-to-json",
+    surface: "cyberpunk2077",
+    from: "CR2W",
+    to: ".json",
+    toolId: "wolvenkit-cli",
+    inverse: "cp2077.json-to-cr2w",
+    roundTrip: "forward-and-byte-compare",
+    argv: (s, d) => argv("serialize", s, d),
+    describe: (s, d) => `WolvenKit.CLI convert serialize ${s} -o ${d}`,
+    destinationKind: "output-directory",
+    expectedOutputName: (s) => expectedOutputName("serialize", s),
+};
+export const JSON_TO_CR2W = {
+    id: "cp2077.json-to-cr2w",
+    surface: "cyberpunk2077",
+    from: ".json",
+    to: "CR2W",
+    toolId: "wolvenkit-cli",
+    inverse: "cp2077.cr2w-to-json",
+    roundTrip: "reverse-and-field-diff",
+    diffKind: "cr2w-json",
+    argv: (s, d) => argv("deserialize", s, d),
+    describe: (s, d) => `WolvenKit.CLI convert deserialize ${s} -o ${d}`,
+    destinationKind: "output-directory",
+    expectedOutputName: (s) => expectedOutputName("deserialize", s),
+};
+export const CYBERPUNK_CONVERTERS = [CR2W_TO_JSON, JSON_TO_CR2W];