modwright 0.1.0

package/dist/core/bridge/stage.js

@@ -0,0 +1,100 @@
+import { existsSync, promises as fs } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+import { isDirectory, pathExists } from "../fsutil.js";
+import { parseProject } from "../project/schema.js";
+import { PROJECT_FILE } from "../project/types.js";
+import { executePlan, planCopy, planFile, planMkdir } from "../safety/index.js";
+const BRIDGE_DIR_BY_GAME = {
+    baldursgate3: "bg3-se",
+    cyberpunk2077: "cp2077-cet",
+};
+export function bridgeId(game) {
+    return BRIDGE_DIR_BY_GAME[game];
+}
+function findPackageRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (existsSync(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error(`bridge: could not find package.json above ${startDir}`);
+        dir = parent;
+    }
+}
+export function bridgesRootDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(findPackageRoot(here), "bridges");
+}
+export function bridgeSourceDir(game) {
+    return path.join(bridgesRootDir(), bridgeId(game));
+}
+export function stagedBridgeDir(projectRoot, game) {
+    return path.join(projectRoot, ".modwright", "bridge", bridgeId(game));
+}
+export async function bridgeDeployTarget(game) {
+    const manifestPath = path.join(bridgeSourceDir(game), "bridge.json");
+    const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    const d = manifest.deploy;
+    if (!d || typeof d.rootId !== "string" || typeof d.from !== "string" || typeof d.into !== "string" || typeof d.variant !== "string") {
+        throw new Error(`bridge stage: ${manifestPath} has no complete "deploy" block (rootId, from, into, variant).`);
+    }
+    const target = { rootId: d.rootId, from: d.from, into: d.into, variant: d.variant };
+    if (typeof d.locked === "boolean")
+        target.locked = d.locked;
+    if (typeof d.backup === "boolean")
+        target.backup = d.backup;
+    if (Array.isArray(d.prune))
+        target.prune = d.prune.filter((p) => typeof p === "string");
+    return target;
+}
+async function planDeployTargetRegistration(projectRoot, game) {
+    const projectFile = path.join(projectRoot, PROJECT_FILE);
+    if (!(await pathExists(projectFile)))
+        return { outcome: "no-project" };
+    const target = await bridgeDeployTarget(game);
+    const json = JSON.parse(await fs.readFile(projectFile, "utf8"));
+    const deploy = (json.deploy ?? { targets: [] });
+    const targets = (deploy.targets ?? []);
+    const present = targets.some((t) => t.rootId === target.rootId && (t.into ?? undefined) === target.into && (t.variant ?? undefined) === target.variant);
+    if (present)
+        return { outcome: "present" };
+    deploy.targets = [...targets, target];
+    json.deploy = deploy;
+    try {
+        parseProject(json);
+    }
+    catch (err) {
+        throw new Error(`bridge stage: adding the ${bridgeId(game)} deploy target would leave modwright.json invalid: ${err.message}`);
+    }
+    return { op: planFile(projectFile, `${JSON.stringify(json, null, 2)}\n`), outcome: "added" };
+}
+export async function planStageBridge(projectRoot, game) {
+    const from = bridgeSourceDir(game);
+    if (!(await isDirectory(from))) {
+        throw new Error(`bridge stage: ${from} does not exist yet — bridges/${bridgeId(game)}/ has no bridge content on disk to stage.`);
+    }
+    const to = stagedBridgeDir(projectRoot, game);
+    const registration = await planDeployTargetRegistration(projectRoot, game);
+    const operations = [planMkdir(path.dirname(to)), planCopy(from, to)];
+    if (registration.op)
+        operations.push(registration.op);
+    return {
+        purpose: registration.outcome === "added"
+            ? `stage the ${bridgeId(game)} bridge into .modwright/bridge/${bridgeId(game)} and register its withBridge deploy target`
+            : `stage the ${bridgeId(game)} bridge into .modwright/bridge/${bridgeId(game)}`,
+        operations,
+        backupRoot: path.join(projectRoot, ".modwright", "backups"),
+        deployTarget: registration.outcome,
+    };
+}
+export async function stageBridge(projectRoot, game, options = {}) {
+    const { deployTarget, ...plan } = await planStageBridge(projectRoot, game);
+    const report = await executePlan({ ...plan, backupRoot: path.join(projectRoot, ".modwright", "backups") }, {
+        mode: options.mode ?? "dry-run",
+        now: options.now,
+        confidence: { level: "high", assumptions: [], verifiedBy: [`bridges/${bridgeId(game)}/ on disk`] },
+    });
+    return { ...report, deployTarget };
+}

package/dist/core/bridge/status.js

@@ -0,0 +1,97 @@
+import { CET_LOG_HEARTBEAT_FRESH_MS, cetLogCandidates, cetSandboxIo, readCetHeartbeat } from "./cet-log.js";
+import { HEARTBEAT_FRESH_MS, locateBridge } from "./locate.js";
+import { PROTOCOL_VERSION } from "./types.js";
+export async function bridgeStatus(game, install, surface, deps = {}) {
+    if (game === "cyberpunk2077")
+        return cetLogStatus(install, surface, deps);
+    const located = await locateBridge(game, install, surface, deps);
+    if (!located.heartbeat) {
+        return {
+            game,
+            transport: "file",
+            candidates: located.candidates,
+            found: false,
+            freshness: "absent",
+            expectedProtocolVersion: PROTOCOL_VERSION,
+            message: "No heartbeat found in any candidate directory — the bridge is not deployed, or the game has not run since deploy.",
+        };
+    }
+    const ageMs = located.ageMs ?? Number.POSITIVE_INFINITY;
+    const fresh = ageMs <= HEARTBEAT_FRESH_MS;
+    const protocolVersionMatch = located.heartbeat.protocolVersion === PROTOCOL_VERSION;
+    const message = !protocolVersionMatch
+        ? `Heartbeat reports protocolVersion ${located.heartbeat.protocolVersion}, ModWright expects ${PROTOCOL_VERSION}. ` +
+            `Re-run "bridge stage", then "deploy --variant withBridge".`
+        : fresh
+            ? "Bridge heartbeat is fresh and protocol versions match."
+            : `Heartbeat is stale (${Math.round(ageMs / 1000)}s old) — the game is probably not running, or the bridge crashed. Check the SE/CET log.`;
+    return {
+        game,
+        transport: "file",
+        candidates: located.candidates,
+        found: true,
+        dir: located.dir,
+        heartbeat: located.heartbeat,
+        ageMs: located.ageMs,
+        freshness: fresh ? "fresh" : "stale",
+        expectedProtocolVersion: PROTOCOL_VERSION,
+        protocolVersionMatch,
+        message,
+    };
+}
+async function cetLogStatus(install, surface, deps) {
+    const logCandidates = await cetLogCandidates(install, surface);
+    const now = deps.now ?? (() => new Date());
+    const located = await locateBridge("cyberpunk2077", install, surface, deps);
+    const fromLog = await readCetHeartbeat(logCandidates, { now: deps.now });
+    const useFile = located.heartbeat !== undefined &&
+        (fromLog === undefined || Date.parse(located.heartbeat.at) >= Date.parse(fromLog.heartbeat.at));
+    const candidates = [...located.candidates, ...logCandidates];
+    if (!located.heartbeat && !fromLog) {
+        return {
+            game: "cyberpunk2077",
+            transport: "log",
+            candidates,
+            found: false,
+            freshness: "absent",
+            expectedProtocolVersion: PROTOCOL_VERSION,
+            message: `No heartbeat file in ${located.candidates.join(" or ")} and no [MODWRIGHT-HEARTBEAT] line in ` +
+                `${logCandidates.join(" or ")} — the bridge is not deployed, the game has not run since deploy, or its output ` +
+                `lands somewhere none of those cover. Read the bridge's own m.where() capability line to tell those apart.`,
+        };
+    }
+    const heartbeat = useFile ? located.heartbeat : fromLog.heartbeat;
+    const transport = useFile ? "file" : "log";
+    const where = useFile ? located.dir : fromLog.file;
+    const freshMs = useFile ? HEARTBEAT_FRESH_MS : CET_LOG_HEARTBEAT_FRESH_MS;
+    const ageMs = now().getTime() - Date.parse(heartbeat.at);
+    const fresh = ageMs <= freshMs;
+    const protocolVersionMatch = heartbeat.protocolVersion === PROTOCOL_VERSION;
+    const sandboxIo = cetSandboxIo(heartbeat);
+    const ioNote = sandboxIo === true
+        ? `The bridge's own sandbox HAS io (capability line), so the file transport is live.`
+        : sandboxIo === false
+            ? `The bridge's own sandbox has NO io (capability line), so it is running log-only and results come back as [MODWRIGHT-RESULT] lines.`
+            :
+                `The heartbeat does not say whether the bridge's sandbox has io; run m.where() in the CET console to find out.`;
+    const message = !protocolVersionMatch
+        ? `The heartbeat (${transport} transport, ${where}) reports protocolVersion ${heartbeat.protocolVersion}, ModWright expects ${PROTOCOL_VERSION}. ` +
+            `Re-run "bridge stage", then "deploy --variant withBridge".`
+        : fresh
+            ? `Bridge heartbeat is fresh (${transport} transport, ${where}) and protocol versions match. ${ioNote}`
+            : `The newest heartbeat (${transport} transport, ${where}) is ${Math.round(ageMs / 1000)}s old — the game is probably not running, or the bridge stopped ticking. ${ioNote}`;
+    return {
+        game: "cyberpunk2077",
+        transport,
+        candidates,
+        found: true,
+        ...(useFile ? { dir: located.dir } : { logFile: fromLog.file }),
+        ...(sandboxIo === undefined ? {} : { sandboxIo }),
+        heartbeat,
+        ageMs,
+        freshness: fresh ? "fresh" : "stale",
+        expectedProtocolVersion: PROTOCOL_VERSION,
+        protocolVersionMatch,
+        message,
+    };
+}

package/dist/core/bridge/types.js

@@ -0,0 +1,145 @@
+import { z } from "zod";
+export const PROTOCOL_VERSION = 1;
+export const BRIDGE_BANNER = "MODWRIGHT-BRIDGE-DO-NOT-SHIP";
+export const bridgeGameSchema = z.enum(["baldursgate3", "cyberpunk2077"]);
+export const bridgeTierSchema = z.enum(["read", "observe", "session", "persist", "process"]);
+export const ALL_TIERS = ["read", "observe", "session", "persist", "process"];
+export const MUTATION_TIER = "session";
+export function resolveGrant(mode, declared) {
+    const set = new Set(mode === "workbench" ? ["read", "observe", "session"] : ["read", "observe"]);
+    for (const tier of declared ?? [])
+        set.add(tier);
+    return ALL_TIERS.filter((tier) => set.has(tier));
+}
+export function grantAllowsMutation(grant, allowMutate) {
+    if (grant && grant.includes(MUTATION_TIER))
+        return true;
+    return allowMutate === true;
+}
+export const probeContextSchema = z.enum(["server", "client", "cet"]);
+export const probeEffectSchema = z.enum(["read", "observe", "mutate"]);
+export const probeExpectOpSchema = z.enum(["eq", "ne", "gte", "lte", "contains", "absent"]);
+export const probeExpectSchema = z
+    .object({
+    op: probeExpectOpSchema,
+    value: z.unknown(),
+})
+    .strict();
+export const probeSchema = z
+    .object({
+    id: z.string().min(1),
+    kind: z.string().min(1),
+    context: probeContextSchema,
+    effect: probeEffectSchema,
+    params: z.record(z.unknown()),
+    expect: probeExpectSchema.optional(),
+    settleSeconds: z.number().nonnegative().optional(),
+    note: z.string().optional(),
+})
+    .strict();
+const iso8601Schema = z.string().refine((s) => !Number.isNaN(Date.parse(s)), {
+    message: "must be a parseable ISO 8601 timestamp",
+});
+export const REQUEST_ID_PATTERN = /^[a-z0-9-]{8,64}$/;
+export const NONCE_PATTERN = /^[0-9a-f]{16}$/;
+export const bridgePlanRefSchema = z
+    .object({
+    planId: z.string().min(1),
+    planPath: z.string().min(1),
+    runId: z.string().min(1),
+})
+    .strict();
+export const bridgeRequestSchema = z
+    .object({
+    protocolVersion: z.literal(PROTOCOL_VERSION),
+    id: z.string().regex(REQUEST_ID_PATTERN, `must match ${REQUEST_ID_PATTERN}`),
+    nonce: z.string().regex(NONCE_PATTERN, `must match ${NONCE_PATTERN} (16 hex characters)`),
+    issuedAt: iso8601Schema,
+    armedUntil: iso8601Schema,
+    game: bridgeGameSchema,
+    allowMutate: z.boolean().default(false),
+    grant: z.array(bridgeTierSchema).optional(),
+    window: z.object({ seconds: z.number().nonnegative() }).strict().optional(),
+    plan: bridgePlanRefSchema.optional(),
+    probes: z.array(probeSchema).min(1).max(64),
+})
+    .strict();
+export const bridgeMarkerSchema = z
+    .object({
+    protocolVersion: z.literal(PROTOCOL_VERSION),
+    id: z.string().min(1),
+    nonce: z.string().min(1),
+    bytes: z.number().int().nonnegative(),
+})
+    .strict();
+export const probeResultStatusSchema = z.enum(["pass", "fail", "error", "skipped", "unsupported"]);
+export const probeResultSchema = z
+    .object({
+    id: z.string().min(1),
+    kind: z.string().min(1),
+    status: probeResultStatusSchema,
+    observed: z.unknown(),
+    evidence: z.record(z.unknown()),
+    error: z.string().optional(),
+    ranAt: iso8601Schema,
+})
+    .strict();
+export const disarmReasonSchema = z.enum([
+    "expired",
+    "nonce-mismatch",
+    "already-consumed",
+    "protocol-mismatch",
+    "mutation-not-allowed",
+    "wrong-game",
+]);
+export const bridgeInfoSchema = z
+    .object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    protocolVersion: z.number().int(),
+    context: z.string().min(1),
+    runtimeVersion: z.string().optional(),
+    gameVersion: z.string().optional(),
+})
+    .strict();
+export const bridgeResultSchema = z
+    .object({
+    protocolVersion: z.number().int(),
+    id: z.string().min(1),
+    nonce: z.string().min(1),
+    startedAt: iso8601Schema,
+    finishedAt: iso8601Schema,
+    complete: z.literal(true),
+    bridge: bridgeInfoSchema,
+    degraded: z.object({ osiris: z.boolean(), reason: z.string() }).strict().optional(),
+    disarm: z.object({ reason: disarmReasonSchema, detail: z.string() }).strict().optional(),
+    probes: z.array(probeResultSchema),
+    errors: z.array(z.string()),
+})
+    .strict();
+export const bridgeDoneSchema = z
+    .object({
+    protocolVersion: z.number().int(),
+    id: z.string().min(1),
+    nonce: z.string().min(1),
+    bytes: z.number().int().nonnegative(),
+    probeCount: z.number().int().nonnegative(),
+})
+    .strict();
+export const bridgeHeartbeatStateSchema = z.enum(["idle", "running", "disarmed"]);
+export const bridgeHeartbeatSchema = z
+    .object({
+    protocolVersion: z.number().int(),
+    bridge: bridgeInfoSchema,
+    at: iso8601Schema,
+    uptimeMs: z.number().nonnegative(),
+    state: bridgeHeartbeatStateSchema,
+    lastRequestId: z.string().optional(),
+    lastResultId: z.string().optional(),
+    writeRoot: z.string(),
+    writeRootErrors: z.array(z.string()).optional(),
+    osirisDegraded: z.boolean().optional(),
+    gameState: z.string().optional(),
+    commandLine: z.array(z.string()).optional(),
+})
+    .strict();

package/dist/core/bridge/validate.js

@@ -0,0 +1,107 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { walk } from "../fsutil.js";
+import { BRIDGE_BANNER } from "./types.js";
+const GROUPS = ["history"];
+const MOD_TYPES = ["packaging"];
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+function pathNamesBridge(relPosix) {
+    const lower = relPosix.toLowerCase();
+    return /(^|\/)modwrightbridge(\/|$)/.test(lower) || lower.includes(".modwright/bridge/");
+}
+const BANNER_SCAN_EXTENSIONS = new Set([".lua", ".json", ".txt", ".md"]);
+function extensionOf(p) {
+    const idx = p.lastIndexOf(".");
+    return idx === -1 ? "" : p.slice(idx).toLowerCase();
+}
+async function readFirstKB(absPath) {
+    let handle;
+    try {
+        handle = await fs.open(absPath, "r");
+    }
+    catch {
+        return "";
+    }
+    try {
+        const buf = Buffer.alloc(1024);
+        const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+        return buf.subarray(0, bytesRead).toString("utf8");
+    }
+    catch {
+        return "";
+    }
+    finally {
+        await handle.close();
+    }
+}
+function isProjectTarget(target) {
+    return target.kind === "project";
+}
+export function bridgeNeverShipValidator(opts) {
+    return {
+        id: opts.id,
+        game: opts.game,
+        groups: GROUPS,
+        modTypes: MOD_TYPES,
+        summary: "Blocks a build whose build.outDir or build.staging already contains the ModWright bridge — a " +
+            "ModWrightBridge/ path, a .modwright/bridge/ path, or the bridge's content banner in a file's first KB. " +
+            "The bridge is author-only and must never reach a dist build.",
+        appliesTo: isProjectTarget,
+        appliesToDescription: "the whole project: build.outDir and build.staging, when they already exist on disk",
+        needs: { project: true },
+        cost: "build",
+        severity: "block",
+        evidence: opts.evidence,
+        async run(ctx) {
+            const project = ctx.project;
+            const findings = [];
+            const roots = [];
+            if (project.build?.outDirExists && project.build.absOutDir) {
+                roots.push({ label: "build.outDir", abs: project.build.absOutDir });
+            }
+            if (project.build?.absStaging) {
+                roots.push({ label: "build.staging", abs: project.build.absStaging });
+            }
+            for (const root of roots) {
+                const { files, truncated } = await walk(root.abs, { limit: 50_000 });
+                for (const rel of files) {
+                    const relPosix = toPosix(rel);
+                    const abs = path.join(root.abs, rel);
+                    const pathHit = pathNamesBridge(relPosix);
+                    let bannerHit = false;
+                    if (!pathHit && BANNER_SCAN_EXTENSIONS.has(extensionOf(rel))) {
+                        bannerHit = (await readFirstKB(abs)).includes(BRIDGE_BANNER);
+                    }
+                    if (!pathHit && !bannerHit)
+                        continue;
+                    findings.push({
+                        validatorId: opts.id,
+                        severity: "block",
+                        file: abs,
+                        message: pathHit
+                            ?
+                                `"${relPosix}" is under ${root.label} (${root.abs}) and is part of the ModWright bridge. The bridge ` +
+                                    `is author-only and must never reach a dist build.`
+                            : `"${relPosix}" is under ${root.label} (${root.abs}) and carries the ModWright bridge's content banner ` +
+                                `in its first KB, even though its path does not name the bridge folder — it looks like bridge ` +
+                                `content that reached the build output under a different path (e.g. flattened during packaging).`,
+                        fix: `Remove ".modwright/bridge/" from this build's sources and re-run without --variant withBridge, or rebuild after "deploy" (no variant) has pruned it back out.`,
+                        evidence: opts.evidence,
+                    });
+                }
+                if (truncated) {
+                    findings.push({
+                        validatorId: opts.id,
+                        severity: "info",
+                        file: root.abs,
+                        message: `${root.label} has more files than this scan's limit; the bridge-never-ships scan may be incomplete for it.`,
+                        evidence: opts.evidence,
+                    });
+                }
+            }
+            return findings;
+        },
+    };
+}

package/dist/core/build/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export { runBuild } from "./run.js";
+export { isGuardedPath } from "./stage.js";
+export { crc32, createZip } from "./zip.js";
+export { directoryEntry, fileEntry, pathEntries, pathEntry, sha256Bytes, sha256File } from "./manifest.js";
+export { resolveOutDirPath, resolveSourceOrStagePath, resolveStageId, stageStepOutputDir, } from "./paths.js";

package/dist/core/build/manifest.js

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import { createReadStream, promises as fs } from "node:fs";
+import * as path from "node:path";
+import { isDirectory, walk } from "../fsutil.js";
+export function sha256File(absPath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(absPath);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolve(hash.digest("hex")));
+        stream.on("error", reject);
+    });
+}
+export function sha256Bytes(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+export async function fileEntry(absPath) {
+    const stat = await fs.stat(absPath);
+    return { path: absPath, sha256: await sha256File(absPath), sizeBytes: stat.size };
+}
+export async function directoryEntry(absDir) {
+    const walked = await walk(absDir, { limit: 200_000 });
+    const files = [];
+    let totalBytes = 0;
+    for (const rel of walked.files) {
+        const abs = path.join(absDir, rel);
+        const stat = await fs.stat(abs);
+        const sha256 = await sha256File(abs);
+        files.push({ path: toPosix(rel), sha256, sizeBytes: stat.size });
+        totalBytes += stat.size;
+    }
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const treeSha256 = sha256Bytes(Buffer.from(files.map((f) => `${f.path}:${f.sha256}`).join("\n"), "utf8"));
+    return { path: absDir, sha256: treeSha256, sizeBytes: totalBytes, files, treeSha256 };
+}
+export async function pathEntry(absPath) {
+    return (await isDirectory(absPath)) ? directoryEntry(absPath) : fileEntry(absPath);
+}
+export async function pathEntries(absPaths) {
+    const out = [];
+    for (const p of absPaths)
+        out.push(await pathEntry(p));
+    return out;
+}

package/dist/core/build/paths.js

@@ -0,0 +1,32 @@
+import * as path from "node:path";
+function substituteVersion(raw, version) {
+    return raw.split("${version}").join(version);
+}
+function substituteStage(raw, ctx) {
+    return substituteVersion(raw.split("${stage}").join(ctx.stageRoot), ctx.version);
+}
+export function resolveSourceOrStagePath(raw, ctx) {
+    if (raw.includes("${stage}"))
+        return substituteStage(raw, ctx);
+    const withVersion = substituteVersion(raw, ctx.version);
+    return path.isAbsolute(withVersion) ? withVersion : path.join(ctx.projectRoot, withVersion);
+}
+export function resolveOutDirPath(raw, ctx) {
+    const withVersion = substituteVersion(raw, ctx.version);
+    if (withVersion.includes("${stage}"))
+        return substituteStage(withVersion, ctx);
+    return path.isAbsolute(withVersion) ? withVersion : path.join(ctx.outDirAbs, withVersion);
+}
+export function resolveStageId(raw, ctx) {
+    if (!raw)
+        return ctx.stageRoot;
+    if (raw.includes("${stage}"))
+        return substituteStage(raw, ctx);
+    return path.join(ctx.stageRoot, substituteVersion(raw, ctx.version));
+}
+export function stageStepOutputDir(stageRoot, id, into) {
+    return into ? path.join(stageRoot, id, into) : path.join(stageRoot, id);
+}
+export function resolvedToolNote(location) {
+    return location.found && location.path ? ` [runs ${location.path}, from ${location.source ?? "unknown"}]` : " [tool not located]";
+}