@creeperhost/modlens-mcp 1.6.19 → 1.6.21

package/scripts/test-runtime-minecraft.mjs

@@ -0,0 +1,190 @@
+// Optional real-client validation with an isolated game directory and demo mode.
+// Uses the explicitly supplied 26.3 manifest/client/assets; never reads user accounts/worlds.
+import { readFile, writeFile, mkdir, mkdtemp, stat, copyFile } from "node:fs/promises";
+import { join, delimiter, basename } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+import { RuntimeHub } from "../dist/runtime/hub.js";
+import { runtimeTestClient } from "./runtime-test-client.mjs";
+
+const env = process.env;
+for (const k of [
+    "JAVA_HOME",
+    "MODLENS_TEST_MC_MANIFEST",
+    "MODLENS_TEST_MC_CLIENT",
+    "MODLENS_TEST_MC_ASSETS",
+    "MODLENS_TEST_MAVEN_CACHE",
+])
+    if (!env[k]) throw new Error("Set " + k);
+const manifest = JSON.parse(await readFile(env.MODLENS_TEST_MC_MANIFEST, "utf8"));
+assert.equal(manifest.id, "26.3");
+const repo = fileURLToPath(new URL("..", import.meta.url));
+const root = await mkdtemp(join(tmpdir(), "modlens-minecraft-smoke-"));
+console.log("Evidence directory: " + root);
+const project = join(root, "project");
+await mkdir(join(project, "gradle/wrapper"), { recursive: true });
+await writeFile(join(project, "gradle/wrapper/gradle-wrapper.jar"), "fixture");
+const classpath = [env.MODLENS_TEST_MC_CLIENT];
+for (const lib of manifest.libraries) {
+    const osName = process.platform === "win32" ? "windows" : process.platform === "darwin" ? "osx" : "linux";
+    if (lib.rules) {
+        let allowed = false;
+        for (const rule of lib.rules)
+            if (!rule.os || rule.os.name === osName) allowed = rule.action === "allow";
+        if (!allowed) continue;
+    }
+    const native = lib.name.split(":")[3];
+    if (
+        native?.includes("natives-") &&
+        native !==
+            `natives-${process.platform === "win32" ? "windows" : process.platform === "darwin" ? "macos" : "linux"}${process.arch === "arm64" ? "-arm64" : ""}`
+    )
+        continue;
+    const [group, artifact, version] = lib.name.split(":");
+    const entry = lib.downloads?.artifact;
+    if (!entry) continue;
+    let path = join(env.MODLENS_TEST_MAVEN_CACHE, group, artifact, version, entry.sha1, basename(entry.path));
+    if (
+        !(await stat(path).then(
+            () => true,
+            () => false,
+        ))
+    ) {
+        path = join(root, "libraries", entry.path);
+        await mkdir(join(path, ".."), { recursive: true });
+        const r = await fetch(entry.url);
+        if (!r.ok) throw new Error("Download failed: " + entry.url);
+        const data = Buffer.from(await r.arrayBuffer());
+        assert.equal(createHash("sha1").update(data).digest("hex"), entry.sha1);
+        await writeFile(path, data);
+    }
+    classpath.push(path);
+}
+const hub = process.argv.includes("--helper")
+    ? runtimeTestClient(root)
+    : new RuntimeHub(
+          join(root, "bridge"),
+          env.MODLENS_TEST_AGENT_JAR ?? join(repo, "dist/runtime/modlens-agent.jar"),
+      );
+const setup = await hub.setup(project, "hidden");
+const args = [
+    "--enable-native-access=ALL-UNNAMED",
+    "--add-exports",
+    "java.base/jdk.internal.misc=ALL-UNNAMED",
+    "-Xmx2G",
+    ...(env.MODLENS_TEST_JVM_ARGS ? JSON.parse(env.MODLENS_TEST_JVM_ARGS) : []),
+    "-XX:ErrorFile=" + join(root, "hs_err_pid%p.log"),
+    ...setup.vmOptions.filter(
+        (option) => !process.argv.includes("--baseline") || !option.startsWith("-javaagent:"),
+    ),
+    "-cp",
+    classpath.join(delimiter),
+    manifest.mainClass,
+    "--username",
+    "ModLensTest",
+    "--version",
+    "26.3",
+    "--gameDir",
+    join(root, "game"),
+    "--assetsDir",
+    env.MODLENS_TEST_MC_ASSETS,
+    "--assetIndex",
+    env.MODLENS_TEST_MC_ASSET_INDEX ?? manifest.assetIndex.id,
+    "--uuid",
+    "00000000000000000000000000000001",
+    "--accessToken",
+    "0",
+    "--demo",
+    "--width",
+    "854",
+    "--height",
+    "480",
+];
+await mkdir(join(root, "game"), { recursive: true });
+await writeFile(
+    join(root, "java.args"),
+    args.map((a) => '"' + a.replaceAll("\\", "/").replaceAll('"', '\\"') + '"').join("\n"),
+);
+const child = spawn(
+    join(env.JAVA_HOME, "bin", process.platform === "win32" ? "java.exe" : "java"),
+    ["@" + join(root, "java.args")],
+    { cwd: join(root, "game"), windowsHide: true },
+);
+let log = "";
+child.stdout.on("data", (b) => {
+    log = (log + b).slice(-150000);
+});
+child.stderr.on("data", (b) => {
+    log = (log + b).slice(-150000);
+});
+const done = new Promise((ok) => child.once("exit", ok));
+async function wait(fn, ms = 90000) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        const r = await fn();
+        if (r) return r;
+        if (child.exitCode !== null)
+            throw new Error("Minecraft exited " + child.exitCode + "\n" + log.slice(-8000));
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new Error("Timed out waiting for Minecraft\n" + log.slice(-8000));
+}
+try {
+    if (process.argv.includes("--baseline")) {
+        await wait(() => log.includes("shulker_boxes.png-atlas"));
+        await new Promise((r) => setTimeout(r, 5000));
+        assert.equal(child.exitCode, null, "Uninstrumented baseline must remain alive after startup");
+        console.log("Uninstrumented Minecraft startup passed. " + root);
+    } else {
+        const session = await wait(async () =>
+            (await hub.list()).find(
+                (s) =>
+                    s.capabilities.minecraftHooks && s.capabilities.window && s.state.observation?.gameLoaded,
+            ),
+        );
+        await new Promise((r) => setTimeout(r, 1500)); // allow the startup overlay to fade
+        console.log("Connected Minecraft: " + JSON.stringify(session));
+        const frame = await hub.command(session.sessionId, { type: "screenshot" });
+        const artifact = await hub.artifact(session.sessionId, frame.artifact);
+        assert.equal(artifact.mimeType, "image/png");
+        await copyFile(artifact.path, join(root, "frame.png"));
+        await hub.command(session.sessionId, { type: "key", key: "TAB", down: true, holdMs: 100 });
+        await hub.command(session.sessionId, { type: "release_all" });
+        assert.equal(session.capabilities.jfr, true);
+        const allocations = await hub.command(session.sessionId, {
+            type: "allocations",
+            packagePrefix: "net.minecraft",
+            windowSeconds: 120,
+        });
+        const allocationArtifact = await hub.artifact(session.sessionId, allocations.artifact);
+        const report = JSON.parse(allocationArtifact.text);
+        assert.ok(report.matchedSamples > 0, "Expected Minecraft allocation samples with caller stacks");
+        await copyFile(allocationArtifact.path, join(root, "allocations.json"));
+        console.log("Minecraft 26.3 hidden client, screenshot, input and allocation report passed. " + root);
+    }
+} finally {
+    if (child.exitCode === null)
+        try {
+            await writeFile(
+                join(root, "threads.txt"),
+                execFileSync(
+                    join(env.JAVA_HOME, "bin", process.platform === "win32" ? "jcmd.exe" : "jcmd"),
+                    [String(child.pid), "Thread.print"],
+                    { timeout: 10000 },
+                ),
+            );
+        } catch (e) {
+            await writeFile(join(root, "thread-error.txt"), String(e) + "\n" + e.stderr);
+        }
+    await writeFile(join(root, "client.log"), log);
+    await writeFile(
+        join(root, "evidence.json"),
+        JSON.stringify({ sessions: await hub.list(), events: await hub.events() }, null, 2),
+    );
+    if (child.exitCode === null) child.kill();
+    await done;
+    await hub.close();
+}

package/scripts/test-runtime-native.mjs

@@ -0,0 +1,120 @@
+// Real SDL smoke test. Set JAVA_HOME (25+) and MODLENS_SDL_CLASSPATH to the
+// lwjgl + lwjgl-sdl Java JARs and matching native JARs. No game/account needed.
+import { mkdtemp, mkdir, writeFile, readFile } from "node:fs/promises";
+import { join, delimiter } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn, execFileSync } from "node:child_process";
+import assert from "node:assert/strict";
+import { fileURLToPath } from "node:url";
+import { RuntimeHub } from "../dist/runtime/hub.js";
+
+if (!process.env.JAVA_HOME || !process.env.MODLENS_SDL_CLASSPATH)
+    throw new Error("Set JAVA_HOME and MODLENS_SDL_CLASSPATH.");
+const repo = fileURLToPath(new URL("..", import.meta.url));
+const root = await mkdtemp(join(tmpdir(), "modlens-sdl-smoke-"));
+const project = join(root, "project");
+await mkdir(join(project, "gradle/wrapper"), { recursive: true });
+await writeFile(join(project, "gradle/wrapper/gradle-wrapper.jar"), "fixture");
+const agent = join(repo, "dist/runtime/modlens-agent.jar");
+const hub = new RuntimeHub(join(root, "bridge"), agent);
+const bin = (n) => join(process.env.JAVA_HOME, "bin", n + (process.platform === "win32" ? ".exe" : ""));
+execFileSync(
+    bin("javac"),
+    ["-cp", agent, "-d", root, join(repo, "runtime-agent/test/io/modlens/runtime/NativeSmoke.java")],
+    { stdio: "inherit" },
+);
+const setup = await hub.setup(project, "hidden");
+const child = spawn(
+    bin("java"),
+    [
+        "--enable-native-access=ALL-UNNAMED",
+        setup.vmOption,
+        "-cp",
+        [root, agent, process.env.MODLENS_SDL_CLASSPATH].join(delimiter),
+        "io.modlens.runtime.NativeSmoke",
+        root,
+    ],
+    { windowsHide: true },
+);
+let log = "";
+child.stdout.on("data", (b) => {
+    log += b;
+});
+child.stderr.on("data", (b) => {
+    log += b;
+});
+const exited = new Promise((ok, fail) => {
+    child.on("exit", (code) => ok(code));
+    child.on("error", fail);
+});
+async function wait(fn, ms = 10000) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        const r = await fn();
+        if (r) return r;
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    throw new Error("Timed out\n" + log + "\n" + JSON.stringify(await hub.events()));
+}
+try {
+    const s = await wait(async () =>
+        (await hub.list()).find((s) => s.capabilities.inputBackend === "lwjgl-sdl3"),
+    );
+    assert.equal(s.state.mode, "hidden");
+    assert.equal(s.capabilities.window, true);
+    await hub.command(s.sessionId, { type: "key", key: "W", down: true, holdMs: 150 });
+    await wait(() => log.includes("RELEASE"));
+    await hub.command(s.sessionId, { type: "text", text: "hello 世界" });
+    await hub.command(s.sessionId, { type: "mouse_move", x: 12, y: -5, relative: true });
+    await hub.command(s.sessionId, { type: "mouse_button", button: 1, down: true, holdMs: 100 });
+    await hub.command(s.sessionId, { type: "scroll", x: 0, y: 1 });
+    for (const marker of ["KEY 26", "TEXT hello 世界", "MOTION", "BUTTON", "SCROLL"])
+        await wait(() => log.includes(marker));
+    const threads = await hub.command(s.sessionId, { type: "threads" });
+    assert.match(threads.artifact, /\.txt$/);
+    const recording = await hub.command(s.sessionId, { type: "recording" });
+    assert.match(recording.artifact, /\.jfr$/);
+    assert.match((await hub.artifact(s.sessionId, threads.artifact)).text, /ModLens telemetry/);
+    const recorded = await hub.artifact(s.sessionId, recording.artifact);
+    assert.equal((await readFile(recorded.path)).subarray(0, 3).toString(), "FLR");
+    const allocations = await hub.command(s.sessionId, {
+        type: "allocations",
+        packagePrefix: "io.modlens.runtime.NativeSmoke",
+        windowSeconds: 30,
+        limit: 20,
+    });
+    const report = JSON.parse((await hub.artifact(s.sessionId, allocations.artifact)).text);
+    assert.ok(report.matchedSamples > 0, "Expected real JFR allocation samples for the workload");
+    assert.ok(report.hotspots.some((h) => h.site.includes("NativeSmoke.allocateFixture")));
+    assert.ok(report.hotspots.every((h) => h.site.startsWith("io.modlens.runtime.NativeSmoke.")));
+    const noMatch = await hub.command(s.sessionId, {
+        type: "allocations",
+        packagePrefix: "no.such.mod",
+        windowSeconds: 30,
+        limit: 20,
+    });
+    const empty = JSON.parse((await hub.artifact(s.sessionId, noMatch.artifact)).text);
+    assert.equal(empty.matchedSamples, 0);
+    assert.deepEqual(empty.hotspots, []);
+    console.log("Allocation hotspot report matched " + report.matchedSamples + " real samples.");
+    await hub.command(s.sessionId, { type: "mode", mode: "observe" });
+    await hub.command(s.sessionId, { type: "key", key: "TAB", down: true, holdMs: 100 });
+    await hub.command(s.sessionId, { type: "mode", mode: "interactive" });
+    await assert.rejects(
+        hub.command(s.sessionId, { type: "key", key: "W", down: true, holdMs: 100 }),
+        /interactive mode/,
+    );
+    await hub.command(s.sessionId, { type: "mode", mode: "hidden" });
+    await hub.command(s.sessionId, { type: "release_all" });
+    await writeFile(join(root, "finish"), "done");
+    assert.equal(await exited, 0, log);
+    await wait(async () => (await hub.events()).events.some((e) => e.type === "uncaught_exception"));
+    await writeFile(
+        join(root, "evidence.json"),
+        JSON.stringify({ sessions: await hub.list(), events: await hub.events(), log }, null, 2),
+    );
+    console.log("SDL runtime smoke passed. Evidence: " + root);
+} finally {
+    if (child.exitCode === null) child.kill();
+    await hub.close();
+}

package/scripts/test-runtime-remote.mjs

@@ -0,0 +1,209 @@
+// HTTP MCP -> local CLI -> persistent companion -> real instrumented SDL JVM.
+// Set JAVA_HOME (25+) and MODLENS_SDL_CLASSPATH, after building server and agent.
+import assert from "node:assert/strict";
+import { spawn, execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, writeFile, readFile, access } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer } from "node:net";
+import { once } from "node:events";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+if (!process.env.JAVA_HOME || !process.env.MODLENS_SDL_CLASSPATH)
+    throw new Error("Set JAVA_HOME and MODLENS_SDL_CLASSPATH");
+const repo = fileURLToPath(new URL("..", import.meta.url));
+const root = await mkdtemp(join(tmpdir(), "modlens-runtime-remote-"));
+console.log("Evidence: " + root);
+const listener = createServer();
+listener.listen(0, "127.0.0.1");
+await once(listener, "listening");
+const port = listener.address().port;
+await new Promise((resolve) => listener.close(resolve));
+const remoteEnv = {
+    ...process.env,
+    MCP_PORT: String(port),
+    MCP_HOST: "127.0.0.1",
+    MODLENS_AUTO_EMBED: "0",
+    MODLENS_CACHE_ROOT: join(root, "remote-cache"),
+    MODLENS_HOME: join(root, "remote-home"),
+    DATABASE_URL: `file:${join(root, "unused.db")}`,
+};
+const localEnv = {
+    ...process.env,
+    MCP_PORT: String(port),
+    MODLENS_CACHE_ROOT: join(root, "local-cache"),
+    MODLENS_HOME: join(root, "local-home"),
+};
+const server = spawn(process.execPath, [join(repo, "dist/server.js")], {
+    cwd: root,
+    env: remoteEnv,
+    stdio: ["ignore", "ignore", "pipe"],
+    windowsHide: true,
+});
+let serverLog = "";
+server.stderr.on("data", (b) => (serverLog += b));
+const serverDone = once(server, "exit");
+const client = new Client({ name: "runtime-remote-smoke", version: "1.0.0" });
+const cli = (args) =>
+    JSON.parse(
+        execFileSync(process.execPath, [join(repo, "dist/launcher.js"), "--runtime", ...args], {
+            cwd: root,
+            env: localEnv,
+            encoding: "utf8",
+            timeout: 45000,
+        }),
+    );
+async function local(request) {
+    const file = join(root, "request.json");
+    await writeFile(file, JSON.stringify(request));
+    return cli(["--request-file", file]);
+}
+async function plan(request) {
+    const response = await client.callTool({ name: "runtime", arguments: request });
+    assert.ok(!response.isError, JSON.stringify(response));
+    const result = JSON.parse(response.content[0].text);
+    assert.equal(result.executed, false);
+    assert.equal(result.execution, "local_helper_required");
+    assert.ok(result.invocation.arguments.includes("--runtime"));
+    return result;
+}
+async function throughRemote(request) {
+    return local((await plan(request)).request);
+}
+async function wait(fn, ms = 30000) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        const value = await fn();
+        if (value) return value;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    throw new Error("Timed out\n" + serverLog);
+}
+let game,
+    gameDone,
+    gameLog = "";
+try {
+    await wait(() => serverLog.includes("listening on"));
+    await client.connect(new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${port}/mcp`)));
+    assert.match(client.getInstructions(), /local.*helper/);
+    const project = join(root, "local project with spaces");
+    await mkdir(join(project, "gradle/wrapper"), { recursive: true });
+    await writeFile(join(project, "gradle/wrapper/gradle-wrapper.jar"), "fixture");
+    const setupPlan = await plan({ action: "setup", projectDir: project, mode: "hidden" });
+    await assert.rejects(access(join(project, ".modlens")), "Remote planning must not change local files");
+    const setup = await local(setupPlan.request);
+    assert.equal(setup.state, "configured");
+    await assert.rejects(
+        access(join(root, "local-home", "data/modlens.db")),
+        "Helper must not bootstrap a source database",
+    );
+    await assert.rejects(
+        access(join(root, "remote-cache/runtime")),
+        "Remote server must not start a runtime bridge",
+    );
+    const agent = join(repo, "dist/runtime/modlens-agent.jar");
+    const java = (name) =>
+        join(process.env.JAVA_HOME, "bin", name + (process.platform === "win32" ? ".exe" : ""));
+    execFileSync(
+        java("javac"),
+        ["-cp", agent, "-d", root, join(repo, "runtime-agent/test/io/modlens/runtime/NativeSmoke.java")],
+        { stdio: "inherit" },
+    );
+    game = spawn(
+        java("java"),
+        [
+            "--enable-native-access=ALL-UNNAMED",
+            setup.vmOption,
+            "-cp",
+            [root, agent, process.env.MODLENS_SDL_CLASSPATH].join(delimiter),
+            "io.modlens.runtime.NativeSmoke",
+            root,
+        ],
+        { windowsHide: true },
+    );
+    game.stdout.on("data", (b) => (gameLog += b));
+    game.stderr.on("data", (b) => (gameLog += b));
+    gameDone = once(game, "exit");
+    const session = await wait(async () =>
+        (await local({ action: "sessions" })).find((s) => s.capabilities.inputBackend === "lwjgl-sdl3"),
+    );
+    const key = await throughRemote({
+        action: "command",
+        sessionId: session.sessionId,
+        command: { type: "key", key: "W", down: true, holdMs: 150 },
+    });
+    assert.equal(key.state, "event_delivered");
+    const allocation = await throughRemote({
+        action: "command",
+        sessionId: session.sessionId,
+        command: { type: "allocations", packagePrefix: "io.modlens.runtime.NativeSmoke" },
+    });
+    const report = await throughRemote({
+        action: "artifact",
+        sessionId: session.sessionId,
+        artifactName: allocation.artifact,
+    });
+    assert.ok(JSON.parse(report.text).hotspots.some((h) => h.site.includes("allocateFixture")));
+    assert.ok(
+        cli(["sessions"]).some((s) => s.sessionId === session.sessionId),
+        "CLI invocations must share the same live session",
+    );
+    cli(["stop"]);
+    await local({ action: "status" });
+    await wait(async () =>
+        (await local({ action: "sessions" })).find((s) => s.sessionId === session.sessionId),
+    );
+    const threads = await throughRemote({
+        action: "command",
+        sessionId: session.sessionId,
+        command: { type: "threads" },
+    });
+    assert.match(
+        (
+            await throughRemote({
+                action: "artifact",
+                sessionId: session.sessionId,
+                artifactName: threads.artifact,
+            })
+        ).text,
+        /ModLens telemetry/,
+    );
+    await writeFile(join(root, "finish"), "done");
+    assert.equal((await gameDone)[0], 0, gameLog);
+    const events = await wait(async () => {
+        const result = await local({ action: "events" });
+        return result.events.some((e) => e.type === "uncaught_exception") && result;
+    });
+    assert.match(gameLog, /KEY 26/);
+    await writeFile(
+        join(root, "evidence.json"),
+        JSON.stringify({ session, report: JSON.parse(report.text), events, gameLog }, null, 2),
+    );
+    cli(["stop"]);
+    await wait(async () => {
+        try {
+            await access(join(root, "local-cache/runtime/bridge.lock"));
+            return false;
+        } catch {
+            return true;
+        }
+    });
+    assert.equal(cli(["stop"]).state, "not_running");
+    console.log(
+        "PASS: remote MCP guidance, local helper setup, persistent session, real JVM input, allocation report, crash events, and clean stop",
+    );
+} finally {
+    if (game && game.exitCode === null) {
+        game.kill();
+        await gameDone;
+    }
+    try {
+        cli(["stop"]);
+    } catch {}
+    await client.close();
+    server.kill();
+    await serverDone;
+    await writeFile(join(root, "server.log"), serverLog);
+}

package/scripts/update-license-templates.mjs

@@ -0,0 +1,14 @@
+// Refresh reviewed standard texts from SPDX. Review and commit changes before deploying.
+import { writeFile } from "node:fs/promises";
+const ids = ["0BSD", "Unlicense", "MIT", "ISC", "BSD-2-Clause", "BSD-3-Clause", "Apache-2.0", "LGPL-3.0-only", "GPL-3.0-only", "CC-BY-NC-SA-4.0"];
+const entries = await Promise.all(ids.map(async id => {
+    const url = `https://raw.githubusercontent.com/spdx/license-list-data/v3.27.0/json/details/${id}.json`;
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`${id}: ${response.status}`);
+    const data = await response.json();
+    return [id, { name: data.name, text: data.licenseText, source: url }];
+}));
+await writeFile(new URL("../src/license-templates.ts", import.meta.url),
+    "// SPDX License List 3.27.0 standard texts; see scripts/update-license-templates.mjs.\n" +
+    "// SPDX data: https://github.com/spdx/license-list-data (CC0-1.0).\n" +
+    `export const licenseTemplates: Record<string, { name: string; text: string; source: string }> = ${JSON.stringify(Object.fromEntries(entries), null, 2)};\n`);