modwright 0.1.0

package/dist/core/validate/run.js

@@ -0,0 +1,131 @@
+import { locateTool, TOOL_SPECS } from "../toolchain/index.js";
+import { applySuppressions, loadSuppressions } from "./suppressions.js";
+function describeErr(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function exceptionFinding(v, target, projectFile, err) {
+    const where = target.kind === "file" ? ` on ${target.path}` : "";
+    return {
+        validatorId: v.id,
+        severity: "warn",
+        file: target.kind === "file" ? target.path : projectFile,
+        message: `Validator "${v.id}" threw while running${where}: ${describeErr(err)}`,
+        evidence: v.evidence,
+    };
+}
+function toolLocator(projectOverrides) {
+    const cache = new Map();
+    return (id) => {
+        let cached = cache.get(id);
+        if (!cached) {
+            const spec = TOOL_SPECS.find((s) => s.id === id);
+            cached = spec
+                ?
+                    locateTool(spec, { projectOverrides, probe: "trusted" })
+                : Promise.resolve({
+                    id,
+                    label: id,
+                    found: false,
+                    usedBy: [],
+                    hint: `"${id}" is not a known tool id in ModWright's toolchain catalog (see core/toolchain/specs.ts).`,
+                });
+            cache.set(id, cached);
+        }
+        return cached;
+    };
+}
+export async function runValidators(registry, ctx, options = {}) {
+    const start = Date.now();
+    const game = ctx.surface.id;
+    const validators = registry.select({ game, groups: options.groups, cheapOnly: options.cheapOnly, ids: options.ids });
+    const suppressionFile = await loadSuppressions(ctx.project.root);
+    const locate = toolLocator(ctx.project.project.toolchain);
+    async function unmetNeedsReason(v) {
+        const reasons = [];
+        if (v.needs.index && !ctx.store) {
+            reasons.push(`no vanilla index built for ${game} — run build_index`);
+        }
+        if (v.needs.install && !ctx.install) {
+            reasons.push(`no ${game} install located`);
+        }
+        if (v.needs.toolchain && v.needs.toolchain.length > 0) {
+            for (const toolId of v.needs.toolchain) {
+                const loc = await locate(toolId);
+                if (!loc.found)
+                    reasons.push(loc.hint ? `${toolId} not found (${loc.hint})` : `${toolId} not found`);
+            }
+        }
+        return reasons.length > 0 ? reasons.join("; ") : undefined;
+    }
+    const fileTargetPaths = options.changedOnly && ctx.changedFiles && ctx.changedFiles.length > 0 ? ctx.changedFiles : await ctx.listFiles();
+    const targets = [
+        ...fileTargetPaths.map((p) => ({ kind: "file", path: p })),
+        { kind: "project" },
+    ];
+    const ran = [];
+    const skipped = [];
+    const findings = [];
+    const timings = {};
+    for (const v of validators) {
+        const unmet = await unmetNeedsReason(v);
+        if (unmet) {
+            skipped.push({ id: v.id, reason: unmet });
+            continue;
+        }
+        let applicable = false;
+        let elapsed = 0;
+        for (const target of targets) {
+            let applies;
+            try {
+                applies = v.appliesTo(target, ctx.project);
+            }
+            catch (err) {
+                findings.push(exceptionFinding(v, target, ctx.project.file, err));
+                continue;
+            }
+            if (!applies)
+                continue;
+            applicable = true;
+            const vctx = ctx.forTarget(target);
+            const t0 = Date.now();
+            try {
+                findings.push(...(await v.run(vctx)));
+            }
+            catch (err) {
+                findings.push(exceptionFinding(v, target, ctx.project.file, err));
+            }
+            finally {
+                elapsed += Date.now() - t0;
+            }
+        }
+        if (applicable) {
+            ran.push(v.id);
+            timings[v.id] = elapsed;
+        }
+        else {
+            skipped.push({ id: v.id, reason: `no file matched: ${v.appliesToDescription}` });
+        }
+    }
+    const { findings: withSuppressions, suppressedCount } = applySuppressions(findings, suppressionFile.suppressions, ctx.toRelative, ctx.install?.version);
+    const counts = { block: 0, warn: 0, info: 0 };
+    let blocking = false;
+    for (const f of withSuppressions) {
+        if (f.suppressedBy)
+            continue;
+        counts[f.severity]++;
+        if (f.severity === "block")
+            blocking = true;
+    }
+    return {
+        project: ctx.project.project.name,
+        game,
+        ran,
+        skipped,
+        findings: withSuppressions,
+        counts,
+        blocking,
+        suppressed: suppressedCount,
+        durationMs: Date.now() - start,
+        timings,
+    };
+}

package/dist/core/validate/suppressions.js

@@ -0,0 +1,91 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+import { compareVersions, isDifferentVersionAxis } from "../compat/version.js";
+import { globToRegExp } from "./context.js";
+import { SUPPRESSIONS_FILE, SUPPRESSIONS_SCHEMA_VERSION } from "./types.js";
+const suppressionSchema = z
+    .object({
+    validatorId: z.string().min(1),
+    file: z.string().min(1).optional(),
+    reason: z.string().min(1),
+    addedBy: z.string().min(1),
+    addedOn: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'addedOn must be an ISO date, "YYYY-MM-DD"'),
+    expiresAfterVersion: z.string().min(1).optional(),
+})
+    .strict();
+const suppressionFileSchema = z
+    .object({
+    schemaVersion: z.literal(SUPPRESSIONS_SCHEMA_VERSION),
+    suppressions: z.array(suppressionSchema),
+})
+    .strict();
+const EMPTY = { schemaVersion: SUPPRESSIONS_SCHEMA_VERSION, suppressions: [] };
+export async function loadSuppressions(projectRoot) {
+    const file = path.join(projectRoot, SUPPRESSIONS_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return EMPTY;
+        throw new Error(`${file}: could not read: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${file}: invalid JSON: ${err.message}`);
+    }
+    const result = suppressionFileSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        throw new Error(`${file}: does not match the suppressions schema: ${issues}`);
+    }
+    return result.data;
+}
+const toPosix = (p) => p.split(/[\\/]/).join("/");
+function fileMatches(pattern, relFile) {
+    if (pattern === undefined)
+        return true;
+    const re = globToRegExp(pattern);
+    if (re.test(relFile))
+        return true;
+    const parts = relFile.split("/");
+    for (let i = 1; i < parts.length; i++) {
+        if (re.test(parts.slice(i).join("/")))
+            return true;
+    }
+    return false;
+}
+function isExpired(s, installedVersion) {
+    if (!s.expiresAfterVersion || !installedVersion)
+        return false;
+    if (isDifferentVersionAxis(s.expiresAfterVersion, installedVersion))
+        return false;
+    try {
+        return compareVersions(installedVersion, s.expiresAfterVersion) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function findMatchingSuppression(finding, suppressions, toRelative, installedVersion) {
+    const rel = path.isAbsolute(finding.file) ? toRelative(finding.file) : toPosix(finding.file);
+    return suppressions.find((s) => s.validatorId === finding.validatorId && fileMatches(s.file, rel) && !isExpired(s, installedVersion));
+}
+export function applySuppressions(findings, suppressions, toRelative, installedVersion) {
+    let suppressedCount = 0;
+    const out = findings.map((f) => {
+        const match = findMatchingSuppression(f, suppressions, toRelative, installedVersion);
+        if (!match)
+            return f;
+        suppressedCount++;
+        return { ...f, suppressedBy: match };
+    });
+    return { findings: out, suppressedCount };
+}

package/dist/core/validate/types.js

@@ -0,0 +1,2 @@
+export const SUPPRESSIONS_FILE = ".modwright/suppressions.json";
+export const SUPPRESSIONS_SCHEMA_VERSION = 1;

package/dist/core/yamledit.js

@@ -0,0 +1,51 @@
+import { isDeepStrictEqual } from "node:util";
+import { isMap, isScalar, isSeq, parse, parseDocument, stringify } from "yaml";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeNode(doc, node, value) {
+    if (isMap(node) && isPlainObject(value)) {
+        for (const pair of [...node.items]) {
+            const key = isScalar(pair.key) ? pair.key.value : pair.key;
+            if (typeof key !== "string" || !(key in value) || value[key] === undefined)
+                node.delete(pair.key);
+        }
+        for (const [key, child] of Object.entries(value)) {
+            if (child === undefined)
+                continue;
+            const existing = node.get(key, true);
+            node.set(key, existing !== undefined ? mergeNode(doc, existing, child) : doc.createNode(child));
+        }
+        return node;
+    }
+    if (isSeq(node) && Array.isArray(value)) {
+        value.forEach((child, i) => {
+            const existing = node.items[i];
+            node.items[i] = existing !== undefined && existing !== null ? mergeNode(doc, existing, child) : doc.createNode(child);
+        });
+        node.items.length = value.length;
+        return node;
+    }
+    if (isScalar(node) && (value === null || typeof value !== "object")) {
+        if (node.value !== value)
+            node.value = value;
+        return node;
+    }
+    return doc.createNode(value);
+}
+export function stringifyPreserving(existingText, value, options = {}) {
+    const fresh = stringify(value, options);
+    if (existingText === undefined)
+        return fresh;
+    try {
+        const doc = parseDocument(existingText);
+        if (doc.errors.length > 0)
+            return fresh;
+        doc.contents = mergeNode(doc, doc.contents, value);
+        const out = doc.toString(options);
+        return isDeepStrictEqual(parse(out), parse(fresh)) ? out : fresh;
+    }
+    catch {
+        return fresh;
+    }
+}

package/dist/index.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { promises as fs, watchFile, unwatchFile } from "node:fs";
+import * as path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SERVER_ENTRY = process.env.MODWRIGHT_SERVER_ENTRY ?? path.join(here, "server.js");
+const STAMP_FILE = process.env.MODWRIGHT_BUILD_STAMP ?? path.join(here, ".build-stamp");
+const STAMP_POLL_MS = Number(process.env.MODWRIGHT_STAMP_POLL_MS ?? 2000);
+const RETIRE_GRACE_MS = Number(process.env.MODWRIGHT_RETIRE_GRACE_MS ?? 30_000);
+const INIT_TIMEOUT_MS = 20_000;
+const RESTART_BASE_MS = Number(process.env.MODWRIGHT_RESTART_BASE_MS ?? 500);
+const RESTART_MAX_DELAY_MS = 30_000;
+const MAX_RESTART_ATTEMPTS = 8;
+const SUPERVISOR_INIT_ID = "modwright-supervisor-initialize";
+function log(msg) {
+    process.stderr.write(`[modwright supervisor] ${msg}\n`);
+}
+function idKey(id) {
+    return `${typeof id}:${String(id)}`;
+}
+class LineSplitter {
+    buffer = "";
+    decoder = new StringDecoder("utf8");
+    push(chunk, onLine) {
+        this.buffer += this.decoder.write(chunk);
+        for (;;) {
+            const nl = this.buffer.indexOf("\n");
+            if (nl === -1)
+                return;
+            const line = this.buffer.slice(0, nl).replace(/\r$/, "");
+            this.buffer = this.buffer.slice(nl + 1);
+            if (line.trim().length > 0)
+                onLine(line);
+        }
+    }
+}
+function parse(line) {
+    try {
+        const value = JSON.parse(line);
+        return value && typeof value === "object" ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+class ServerProcess {
+    child;
+    generation;
+    pending = new Set();
+    retired = false;
+    exited = false;
+    splitter = new LineSplitter();
+    listeners = new Set();
+    constructor(generation) {
+        this.generation = generation;
+        this.child = spawn(process.execPath, [SERVER_ENTRY], { stdio: ["pipe", "pipe", "inherit"] });
+        this.child.stdout.on("data", (chunk) => {
+            this.splitter.push(chunk, (line) => {
+                const msg = parse(line);
+                if (!msg)
+                    return;
+                for (const l of this.listeners)
+                    l(msg, line);
+            });
+        });
+        this.child.on("exit", () => {
+            this.exited = true;
+        });
+    }
+    onMessage(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    send(raw) {
+        if (this.exited || !this.child.stdin || this.child.stdin.destroyed)
+            return false;
+        this.child.stdin.write(`${raw}\n`);
+        return true;
+    }
+    kill() {
+        if (this.exited)
+            return;
+        try {
+            this.child.stdin?.end();
+        }
+        catch {
+        }
+        setTimeout(() => {
+            if (!this.exited)
+                this.child.kill();
+        }, 2000).unref();
+    }
+}
+class Supervisor {
+    active;
+    generation = 0;
+    swapping = false;
+    swapQueued = false;
+    closing = false;
+    initializeRaw;
+    initializeId;
+    initializedSeen = false;
+    routes = new Map();
+    serverRequests = new Map();
+    stdinSplitter = new LineSplitter();
+    lastStamp;
+    restartFailures = 0;
+    restartTimer;
+    async start() {
+        this.active = this.spawnServer();
+        process.stdin.on("data", (chunk) => {
+            this.stdinSplitter.push(chunk, (line) => this.fromClient(line));
+        });
+        process.stdin.on("end", () => this.shutdown());
+        process.stdin.on("close", () => this.shutdown());
+        process.on("SIGTERM", () => this.shutdown());
+        process.on("SIGINT", () => this.shutdown());
+        this.lastStamp = await readStamp();
+        watchFile(STAMP_FILE, { interval: STAMP_POLL_MS, persistent: false }, () => {
+            void this.onStampChange();
+        });
+    }
+    spawnServer() {
+        const server = new ServerProcess(++this.generation);
+        server.onMessage((msg, raw) => this.fromServer(server, msg, raw));
+        server.child.on("exit", (code, signal) => this.onServerExit(server, code, signal));
+        return server;
+    }
+    fromClient(raw) {
+        const msg = parse(raw);
+        if (!msg)
+            return;
+        const active = this.active;
+        if (msg.method === "initialize" && msg.id !== undefined && msg.id !== null) {
+            this.initializeRaw = raw;
+            this.initializeId = msg.id;
+        }
+        else if (msg.method === "notifications/initialized") {
+            this.initializedSeen = true;
+        }
+        if (msg.method === undefined && msg.id !== undefined && msg.id !== null) {
+            const key = idKey(msg.id);
+            const target = this.serverRequests.get(key);
+            this.serverRequests.delete(key);
+            (target ?? active)?.send(raw);
+            return;
+        }
+        if (msg.method === "notifications/cancelled") {
+            const requestId = msg.params?.requestId;
+            if (requestId !== undefined) {
+                const target = this.routes.get(idKey(requestId));
+                if (target) {
+                    target.send(raw);
+                    return;
+                }
+            }
+        }
+        if (!active || active.exited) {
+            if (msg.id !== undefined && msg.id !== null && msg.method !== undefined) {
+                const response = {
+                    jsonrpc: "2.0",
+                    id: msg.id,
+                    error: {
+                        code: -32000,
+                        message: this.restartTimer !== undefined || this.swapping
+                            ? "ModWright's server process is not running; a restart is in progress, retry shortly."
+                            : "ModWright's server process is not running and could not be restarted; rebuild ModWright or restart the MCP client.",
+                    },
+                };
+                process.stdout.write(`${JSON.stringify(response)}\n`);
+            }
+            return;
+        }
+        if (msg.id !== undefined && msg.id !== null && msg.method !== undefined) {
+            const key = idKey(msg.id);
+            this.routes.set(key, active);
+            active.pending.add(key);
+        }
+        active.send(raw);
+    }
+    fromServer(server, msg, raw) {
+        if (msg.id !== undefined && msg.id !== null && msg.method === undefined) {
+            if (msg.id === SUPERVISOR_INIT_ID)
+                return;
+            if (server === this.active)
+                this.restartFailures = 0;
+            const key = idKey(msg.id);
+            this.routes.delete(key);
+            server.pending.delete(key);
+            process.stdout.write(`${raw}\n`);
+            if (server.retired && server.pending.size === 0)
+                server.kill();
+            return;
+        }
+        if (msg.id !== undefined && msg.id !== null && msg.method !== undefined) {
+            this.serverRequests.set(idKey(msg.id), server);
+        }
+        process.stdout.write(`${raw}\n`);
+    }
+    onServerExit(server, code, signal) {
+        for (const key of server.pending) {
+            const route = this.routes.get(key);
+            if (route !== server)
+                continue;
+            this.routes.delete(key);
+            const [type, ...rest] = key.split(":");
+            const idText = rest.join(":");
+            const id = type === "number" ? Number(idText) : idText;
+            const response = {
+                jsonrpc: "2.0",
+                id,
+                error: { code: -32000, message: `ModWright server process exited (code ${code ?? "null"}, signal ${signal ?? "none"}) before answering this request; a replacement is being started, retry shortly.` },
+            };
+            process.stdout.write(`${JSON.stringify(response)}\n`);
+        }
+        server.pending.clear();
+        if (this.closing || server.retired || server !== this.active)
+            return;
+        log(`server exited unexpectedly (code ${code ?? "null"}, signal ${signal ?? "none"}); restarting`);
+        this.scheduleRestart("server exit");
+    }
+    scheduleRestart(reason) {
+        if (this.closing || this.restartTimer !== undefined)
+            return;
+        if (this.restartFailures >= MAX_RESTART_ATTEMPTS) {
+            log(`giving up after ${this.restartFailures} failed restarts; the next build will try again`);
+            return;
+        }
+        const delay = Math.min(RESTART_BASE_MS * 2 ** this.restartFailures, RESTART_MAX_DELAY_MS);
+        this.restartFailures += 1;
+        this.restartTimer = setTimeout(() => {
+            this.restartTimer = undefined;
+            void this.swap(reason);
+        }, delay);
+        this.restartTimer.unref();
+    }
+    async onStampChange() {
+        const stamp = await readStamp();
+        if (stamp === undefined || stamp === this.lastStamp)
+            return;
+        this.lastStamp = stamp;
+        this.restartFailures = 0;
+        if (this.restartTimer !== undefined) {
+            clearTimeout(this.restartTimer);
+            this.restartTimer = undefined;
+        }
+        await this.swap(`build stamp ${stamp.trim()}`);
+    }
+    async swap(reason) {
+        if (this.closing)
+            return;
+        if (this.swapping) {
+            this.swapQueued = true;
+            return;
+        }
+        this.swapping = true;
+        try {
+            const previous = this.active;
+            const next = this.spawnServer();
+            if (this.initializeRaw !== undefined) {
+                const ok = await this.replayInitialize(next);
+                if (!ok) {
+                    next.kill();
+                    if (previous && !previous.exited) {
+                        log(`new server (generation ${next.generation}) failed its handshake; keeping the current one`);
+                    }
+                    else {
+                        log(`new server (generation ${next.generation}) failed its handshake and no live server remains; retrying`);
+                        this.active = undefined;
+                        this.scheduleRestart(reason);
+                    }
+                    return;
+                }
+            }
+            this.active = next;
+            log(`swapped to server generation ${next.generation} (${reason})`);
+            if (previous && previous !== next) {
+                previous.retired = true;
+                if (previous.pending.size === 0)
+                    previous.kill();
+                else
+                    setTimeout(() => previous.kill(), RETIRE_GRACE_MS).unref();
+            }
+            if (this.initializedSeen) {
+                process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" })}\n`);
+            }
+        }
+        finally {
+            this.swapping = false;
+            if (this.swapQueued) {
+                this.swapQueued = false;
+                void this.swap("queued change");
+            }
+        }
+    }
+    replayInitialize(server) {
+        return new Promise((resolve) => {
+            const original = parse(this.initializeRaw);
+            const replay = { ...original, id: SUPERVISOR_INIT_ID };
+            let settled = false;
+            const finish = (ok) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                off();
+                resolve(ok);
+            };
+            const off = server.onMessage((msg) => {
+                if (msg.id === SUPERVISOR_INIT_ID) {
+                    if (msg.error) {
+                        finish(false);
+                        return;
+                    }
+                    server.send(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
+                    finish(true);
+                }
+            });
+            server.child.once("exit", () => finish(false));
+            const timer = setTimeout(() => finish(false), INIT_TIMEOUT_MS);
+            if (!server.send(JSON.stringify(replay)))
+                finish(false);
+        });
+    }
+    shutdown() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        if (this.restartTimer !== undefined)
+            clearTimeout(this.restartTimer);
+        unwatchFile(STAMP_FILE);
+        this.active?.kill();
+        setTimeout(() => process.exit(0), 2500).unref();
+    }
+}
+async function readStamp() {
+    try {
+        return await fs.readFile(STAMP_FILE, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+async function packageRoot() {
+    for (let dir = here;; dir = path.dirname(dir)) {
+        try {
+            await fs.access(path.join(dir, "package.json"));
+            return dir;
+        }
+        catch {
+            if (path.dirname(dir) === dir)
+                throw new Error("modwright: no package.json above the entry point");
+        }
+    }
+}
+const cli = process.argv[2];
+if (cli === "tool") {
+    process.argv.splice(2, 1);
+    const { pathToFileURL } = await import("node:url");
+    await import(pathToFileURL(path.join(await packageRoot(), "scripts", "mw-tool.mjs")).href);
+}
+else if (cli === "--version" || cli === "-v") {
+    const pkg = JSON.parse(await fs.readFile(path.join(await packageRoot(), "package.json"), "utf8"));
+    process.stdout.write(`${pkg.version}\n`);
+}
+else if (cli === "--help" || cli === "-h" || cli === "help") {
+    process.stdout.write([
+        "ModWright: a game-agnostic MCP server for game modding.",
+        "",
+        "  modwright                 run the MCP server on stdio (what an MCP client starts)",
+        "  modwright tool list       list the tools; `tool call <tool> key=value ...` calls one from a shell",
+        "  modwright --version       print the version",
+        "",
+        "Register it with an MCP client, e.g.:  claude mcp add modwright -- npx -y modwright",
+        "",
+    ].join("\n"));
+}
+else if (cli !== undefined) {
+    process.stderr.write(`modwright: unknown argument "${cli}" (try --help)\n`);
+    process.exit(2);
+}
+else if (process.env.MODWRIGHT_NO_HOT_RELOAD === "1") {
+    await import("./server.js");
+}
+else {
+    await new Supervisor().start();
+}