@creeperhost/modlens-mcp 1.6.20 → 1.6.22

package/scripts/test-mod-licenses-live.mjs

@@ -0,0 +1,86 @@
+// Opt-in regression against real, immutable release JARs and live evidence APIs.
+// Downloads test artifacts only; no credentials, ingestion or bulk source export.
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import AdmZip from 'adm-zip';
+import { inspectModLicense } from '../dist/mod-license.js';
+
+const root = resolve('.scratch/license-live');
+await mkdir(root, { recursive: true });
+const cases = [
+    { name: 'JEI', version: 'JhEb3Vl1', hash: 'a9418a15032d1653b4776763f2df7c54544a1c2314fe1c4269ba60d9bb51a204', license: 'MIT', target: 'mezz.jei.common.Constants' },
+    { name: 'Jade', version: 'yd8FKCmx', hash: '067bb4b007e1d6f6b79f0afe99c91252aa825472b99a76d33a60d24442f9e92d', license: 'CC-BY-NC-SA-4.0', target: 'snownee.jade.Jade' },
+    { name: 'Embeddium', version: 'UTbfe5d1', hash: 'eed3d1325f2acc2fd4e69bb495e5ccb91d962126ac5330f0582ebc2a3daf47fb', license: 'LGPL-3.0-only', target: 'org.embeddedt.embeddium.api.EmbeddiumConstants' },
+];
+if (process.argv.includes('--corpus')) {
+    cases.push(...JSON.parse(await readFile(new URL('./fixtures/mod-license-corpus.json', import.meta.url), 'utf8')));
+}
+const outcomes = [];
+const digest = data => createHash('sha256').update(data).digest('hex');
+for (const item of cases) {
+    const outcome = { name: item.name, version: item.version, expected: item.expected ?? 'hosted_allowed' };
+    outcomes.push(outcome);
+    try {
+    const jar = join(root, `${item.name}.jar`);
+    let data = await readFile(jar).catch(() => null);
+    if (!data || digest(data) !== item.hash) {
+        const response = await fetch(`https://api.modrinth.com/v2/version/${item.version}`, { headers: { 'User-Agent': 'modlens-mcp/license-regression' } });
+        assert.equal(response.status, 200);
+        const version = await response.json();
+        const url = new URL(version.files.find(f => f.primary)?.url ?? version.files[0].url);
+        assert.equal(url.origin, 'https://cdn.modrinth.com');
+        const download = await fetch(url, { redirect: 'error' });
+        assert.equal(download.status, 200);
+        data = Buffer.from(await download.arrayBuffer());
+        assert.equal(digest(data), item.hash, `${item.name} exact artifact`);
+        await writeFile(jar, data);
+    }
+    const decision = await inspectModLicense(jar);
+    await writeFile(join(root, `${item.name}.decision.json`), JSON.stringify(decision, null, 2));
+    Object.assign(outcome, { actual: decision.disposition, license: decision.selectedLicense, origin: decision.selectedOrigin, reason: decision.reason, notices: decision.notices.length });
+    assert.equal(decision.disposition, outcome.expected, `${item.name}: ${decision.reason}`);
+    if (decision.disposition === 'hosted_allowed') {
+        assert.equal(decision.selectedLicense, item.license);
+        assert.ok(decision.notices.length);
+    }
+    if (item.name === 'Jade') assert.equal(decision.conditions.noncommercialOnly, true);
+    if (item.name === 'Embeddium') {
+        assert.ok(decision.conditions.sourceArchive?.includes('87d1a75'));
+        assert.ok(decision.notices.some(n => n.name.includes('COPYING.LESSER')));
+        assert.ok(decision.notices.some(n => n.name.startsWith('dependency/')));
+        const response = await fetch(decision.conditions.sourceArchive, { method: 'HEAD' });
+        assert.equal(response.status, 200, 'complete corresponding-source archive is available');
+    }
+    if (process.argv.includes('--http') && decision.disposition === 'hosted_allowed' && item.target) {
+        const bundle = new AdmZip();
+        bundle.addFile('artifacts/0.jar', data);
+        bundle.addFile('manifest.json', Buffer.from(JSON.stringify({ format: 'modlens-project-v1', project: `license-${item.name}:`, sourceSet: 'main',
+            toolchain: 'gradle-compile-classpath', minecraftVersion: '', loaderVersion: '', mappings: 'compile-classpath', javaVersion: 21, transformations: [],
+            artifacts: [{ path: 'artifacts/0.jar', name: `${item.name}.jar`, size: data.length, sha256: item.hash, kind: 'classpath' }] })));
+        const bundlePath = join(root, `${item.name}.zip`), keyPath = join(root, `${item.name}.key`);
+        await writeFile(bundlePath, bundle.toBuffer());
+        await writeFile(keyPath, createHash('sha256').update(`disposable-test-${item.hash}`).digest('hex'));
+        const child = spawn(process.execPath, ['scripts/test-project-http.mjs', bundlePath, keyPath, item.target], { stdio: 'inherit',
+            env: { ...process.env, MODLENS_TEST_EXPECTED_LICENSE: item.license } });
+        const [code] = await once(child, 'exit');
+        assert.equal(code, 0, `${item.name} real HTTP hosted source path`);
+        outcome.http = 'passed';
+    } else if (process.argv.includes('--http')) {
+        outcome.http = decision.disposition === 'hosted_allowed' ? 'not run: no root class target' : 'not run: local-only decision';
+    }
+    outcome.passed = true;
+    console.log(`PASS: ${item.name}: ${decision.disposition}, ${decision.selectedLicense ?? 'no selected licence'} from ${decision.selectedOrigin ?? 'no selected origin'}, ${decision.notices.length} complete notices`);
+    } catch (error) {
+        outcome.passed = false;
+        outcome.error = error instanceof Error ? error.message : String(error);
+        console.error(`FAIL: ${item.name}: ${outcome.error}`);
+    }
+}
+const summary = { checkedAt: new Date().toISOString(), total: outcomes.length, passed: outcomes.filter(o => o.passed).length, failed: outcomes.filter(o => !o.passed).length, outcomes };
+await writeFile(join(root, process.argv.includes('--corpus') ? 'corpus-results.json' : 'baseline-results.json'), JSON.stringify(summary, null, 2));
+console.log(`Licence corpus: ${summary.passed}/${summary.total} passed; ${summary.failed} failed.`);
+if (summary.failed) process.exitCode = 1;

package/scripts/test-package.mjs

@@ -113,6 +113,36 @@ try {
     assert.equal(initScript, join(installed, "scripts/gradle/modlens.init.gradle"));
     assert.ok(statSync(initScript).size > 0, "Gradle exporter must ship in the npm package");
     assert.ok(statSync(join(installed, "scripts/project-upload.mjs")).size > 0, "Remote uploader must ship in the npm package");
+    assert.ok(statSync(join(installed, "dist/runtime/modlens-agent.jar")).size > 0, "Optional runtime agent must ship prebuilt");
+    assert.ok(statSync(join(installed, "scripts/gradle/modlens-runtime.init.gradle")).size > 0, "Runtime launch integration must ship");
+    assert.ok(statSync(join(installed, "RUNTIME.md")).size > 0, "Runtime instructions must ship");
+    assert.ok(statSync(join(installed, "dist/license-templates.js")).size > 0, "License reference data must ship");
+    const localModRequest = join(root, "local-mod-request.json");
+    writeFileSync(localModRequest, JSON.stringify({ localJarPath: join(root, "not-opened.jar"), sha256: "a".repeat(64), className: "example.Fixture", acceptedLocalDecompilation: false }));
+    assert.throws(() => execFileSync(process.execPath, [join(installed, "dist/launcher.js"), "--local-mod", "--request-file", localModRequest], {
+        env: { ...env, MODLENS_HOME: join(root, "local-mod-home"), MCP_PORT: "9999" }, encoding: "utf8", stdio: "pipe", timeout: 30000,
+    }), error => error.status === 1 && String(error.stderr).includes("User acceptance required"));
+    assert.ok(!existsSync(join(root, "local-mod-home", "data")), "Local helper must not bootstrap a hosted database");
+    console.log("PASS: installed local decompilation helper refuses execution without user acceptance");
+    const runtimeHome=join(root,"runtime-only-home");
+    const runtimeEnv={...env,MODLENS_HOME:runtimeHome,MODLENS_CACHE_ROOT:join(root,"runtime-only-cache"),MCP_PORT:"9999"};
+    const runtime=(...arguments_)=>JSON.parse(execFileSync(process.execPath,[join(installed,"dist/launcher.js"),"--runtime",...arguments_],{env:runtimeEnv,encoding:"utf8",timeout:30000}));
+    const runtimeProject=join(root,"runtime project");
+    mkdirSync(join(runtimeProject,"gradle/wrapper"),{recursive:true});
+    writeFileSync(join(runtimeProject,"gradle/wrapper/gradle-wrapper.jar"),"fixture");
+    const runtimeRequest=join(root,"runtime-request.json");
+    writeFileSync(runtimeRequest,JSON.stringify({action:"setup",projectDir:runtimeProject,mode:"hidden"}));
+    try {
+        assert.ok(runtime("help").execution.includes("Remote MCP"));
+        const configuredRuntime = runtime("--request-file",runtimeRequest);
+        assert.equal(configuredRuntime.state,"configured");
+        assert.deepEqual(configuredRuntime.vmOptions,[configuredRuntime.vmOption,"-XX:StackShadowPages=32"]);
+        assert.equal(runtime("status").projects.length,1);
+        assert.deepEqual(runtime("sessions"),[]);
+        assert.ok(!existsSync(join(runtimeHome,"data")),"Runtime helper must not create a source database");
+        assert.ok(!existsSync(join(runtimeHome,".env")),"Runtime helper must not create MCP configuration");
+    } finally {runtime("stop");}
+    console.log("PASS: installed runtime helper setup, persistence and stop without local MCP/database setup");
     const keyFile = join(root, "project-key.txt");
     writeFileSync(keyFile, "a".repeat(64));
     assert.deepEqual(JSON.parse(execFileSync(process.execPath, [join(installed, "dist/launcher.js"), "--project", "list", `--key-file=${keyFile}`], { env, encoding: "utf8" })), []);
@@ -181,6 +211,20 @@ try {
             assert.ok(initialized.serverInfo);
             send({ method: "notifications/initialized" });
             const list = await request("tools/list", {});
+            assert.ok(list.tools.some(tool => tool.name === "runtime" && tool.description.includes("setup")), "AI must discover runtime setup through MCP");
+            assert.match(initialized.instructions, /runtime/);
+            assert.ok(list.tools.some(tool => tool.name === "report_issue"), "AI must discover GitHub issue reporting");
+            const issueDraft = await request("tools/call", { name: "report_issue", arguments: {
+                action: "prepare", title: "Package test fixture", summary: "A synthetic report; do not publish.",
+            } });
+            assert.ok(!issueDraft.isError);
+            const issuePlan = JSON.parse(issueDraft.content[0].text);
+            assert.equal(issuePlan.executed, false);
+            assert.equal(issuePlan.state, "draft_prepared");
+            assert.equal(issuePlan.repository.repo, "modlens-mcp");
+            const runtimeHelp = await request("tools/call", { name: "runtime", arguments: { action: "help" } });
+            assert.ok(!runtimeHelp.isError);
+            assert.match(runtimeHelp.content[0].text, /26\.3/);
             assert.ok(list.tools.some(tool => tool.name === "mod"));
             assert.ok(list.tools.some(tool => tool.name === "project"));
             const stats = await request("tools/call", { name: "mod", arguments: { action: "stats" } });

package/scripts/test-project-http.mjs

@@ -11,6 +11,8 @@ import { once } from 'node:events';
 import AdmZip from 'adm-zip';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { licenseTemplates } from '../dist/license-templates.js';
+import { ElicitRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 
 const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const root = await mkdtemp(join(tmpdir(), 'modlens-http-smoke-'));
@@ -28,14 +30,22 @@ if (!process.argv[2]) {
     const jar = new AdmZip();
     jar.addFile('example/Target.class', Buffer.from('test class entry'));
     jar.addFile('example/Target.java', Buffer.from('package example; public class Target { public int counter; }'));
+    jar.addFile('LICENSE', Buffer.from(licenseTemplates['0BSD'].text));
     // An incompressible payload exercises multiple full upload chunks.
     jar.addFile('payload.bin', randomBytes(2 * 1024 * 1024));
     const bytes = jar.toBuffer();
     const bundle = new AdmZip();
     bundle.addFile('artifacts/0.jar', bytes);
+    const restricted = new AdmZip();
+    restricted.addFile('LICENSE', Buffer.from('All Rights Reserved'));
+    restricted.addFile('example/Restricted.class', Buffer.from('restricted class fixture'));
+    restricted.addFile('example/Restricted.java', Buffer.from('RESTRICTED_SOURCE_MUST_STAY_LOCAL'));
+    const restrictedBytes = restricted.toBuffer();
+    bundle.addFile('artifacts/1.jar', restrictedBytes);
     bundle.addFile('manifest.json', Buffer.from(JSON.stringify({ format: 'modlens-project-v1', project: 'http-smoke:', sourceSet: 'main',
         toolchain: 'gradle-compile-classpath', minecraftVersion: '', loaderVersion: '', mappings: 'compile-classpath', javaVersion: 21, transformations: [],
-        artifacts: [{ path: 'artifacts/0.jar', name: 'prepared.jar', size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex'), kind: 'classpath' }] })));
+        artifacts: [{ path: 'artifacts/0.jar', name: 'prepared.jar', size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex'), kind: 'classpath' },
+            { path: 'artifacts/1.jar', name: 'restricted.jar', size: restrictedBytes.length, sha256: createHash('sha256').update(restrictedBytes).digest('hex'), kind: 'classpath' }] })));
     await writeFile(bundlePath, bundle.toBuffer());
 }
 const env = { ...process.env, MCP_PORT: String(port), MCP_HOST: '127.0.0.1', MODLENS_AUTO_EMBED: '0',
@@ -44,7 +54,9 @@ const server = spawn(process.execPath, [join(repo, 'dist/server.js')], { cwd: ro
 let logs = '';
 server.stderr.on('data', b => { logs += b; });
 const stopped = once(server, 'exit');
-const client = new Client({ name: 'project-http-test', version: '1.0.0' });
+const client = new Client({ name: 'project-http-test', version: '1.0.0' }, { capabilities: { elicitation: { form: {} } } });
+let acceptLocal = true;
+client.setRequestHandler(ElicitRequestSchema, async () => acceptLocal ? { action: 'accept', content: { acceptLocal: true } } : { action: 'decline' });
 let passed = false;
 try {
     await new Promise((resolveReady, reject) => {
@@ -69,6 +81,37 @@ try {
     const source = await call('source', { className: target });
     assert.ok(!source.isError, JSON.stringify(source));
     assert.ok(JSON.parse(source.content[0].text).source.length > 0);
+    const complianceBlock = source.content.find(c => c.type === 'text' && c.text.includes('licenseCompliance'));
+    assert.ok(complianceBlock, 'required license notices must accompany source');
+    assert.ok(JSON.parse(source.content[0].text).source.split(/\r?\n/).length <= 200);
+    if (process.env.MODLENS_TEST_EXPECTED_LICENSE) {
+        const compliance = JSON.parse(complianceBlock.text).licenseCompliance[0];
+        assert.equal(compliance.license, process.env.MODLENS_TEST_EXPECTED_LICENSE);
+        assert.equal(compliance.conditions.outputLicense, compliance.license);
+        assert.ok(compliance.notices.every(n => n.licenseText.length > 0));
+        assert.ok(compliance.modifiedAt);
+        if (compliance.license === 'LGPL-3.0-only') assert.ok(compliance.conditions.sourceArchive);
+        if (compliance.license === 'CC-BY-NC-SA-4.0') assert.equal(compliance.conditions.noncommercialOnly, true);
+    }
+    if (!process.argv[2]) {
+        assert.ok(source.content.some(c => c.type === 'text' && c.text.includes('licenseCompliance')), 'required license notices must accompany source');
+        const restricted = await call('source', { className: 'example.Restricted' });
+        const fallback = JSON.parse(restricted.content[0].text);
+        assert.equal(fallback.licenseReview.disposition, 'local_only');
+        assert.equal(fallback.local.requiresUserConsent, true);
+        assert.ok(!JSON.stringify(restricted).includes('RESTRICTED_SOURCE_MUST_STAY_LOCAL'));
+        const searched = await call('search', { query: 'RESTRICTED_SOURCE' });
+        assert.deepEqual(JSON.parse(searched.content[0].text).results, []);
+        const consent = () => client.callTool({ name: 'mod_license', arguments: {
+            action: 'local_plan', projectKey: key, environmentId: imported.environmentId, className: 'example.Restricted',
+        } });
+        const accepted = JSON.parse((await consent()).content[0].text).local;
+        assert.equal(accepted.executed, false);
+        assert.equal(accepted.request.acceptedLocalDecompilation, true);
+        assert.equal(accepted.requiresUserConsent, false);
+        acceptLocal = false;
+        assert.equal(JSON.parse((await consent()).content[0].text).declined, true);
+    }
     if (process.argv[5]) {
         const members = await call('members', { className: target });
         assert.ok(!members.isError, JSON.stringify(members));
@@ -88,7 +131,7 @@ try {
     assert.equal(large.status, 413);
     assert.ok(!logs.includes(key), 'server logs must redact project key');
     assert.ok(!logs.includes('SENSITIVE_PAYLOAD'), 'server logs must redact upload bytes');
-    console.log(`PASS: HTTP upload, ${imported.classCount} classes, source query, project isolation, host-path rejection, body limits and log redaction`);
+    console.log(`PASS: HTTP upload, ${imported.classCount} classes, source query and complete notices, project isolation, host-path rejection, body limits and log redaction${process.argv[2] ? '' : ', restricted-source gating and local consent'}`);
     passed = true;
 } finally {
     await client.close();

package/scripts/test-runtime-gradle.mjs

@@ -0,0 +1,107 @@
+// Validates the same wrapper/init-script path used by MCP and IntelliJ.
+// Requires JAVA_HOME (25+) and MODLENS_TEST_GRADLE_HOME (a Gradle 9.6 distribution).
+import { mkdtemp, mkdir, writeFile, readdir, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import assert from "node:assert/strict";
+import { RuntimeHub } from "../dist/runtime/hub.js";
+import { runtimeTestClient } from "./runtime-test-client.mjs";
+
+const gradleHome = process.env.MODLENS_TEST_GRADLE_HOME;
+const javaHome = process.env.JAVA_HOME;
+if (!gradleHome || !javaHome) throw new Error("Set JAVA_HOME and MODLENS_TEST_GRADLE_HOME");
+const root = await mkdtemp(join(tmpdir(), "modlens-runtime-gradle-"));
+const project = join(root, "project with spaces");
+await mkdir(join(project, "src/main/java"), { recursive: true });
+await writeFile(join(project, "settings.gradle"), "rootProject.name = 'runtime-smoke'\n");
+await writeFile(join(project, "gradle.properties"), "org.gradle.daemon=false\n");
+await writeFile(
+    join(project, "build.gradle"),
+    `
+plugins { id 'java' }
+tasks.register('runClient', JavaExec) {
+    classpath = sourceSets.main.runtimeClasspath
+    mainClass = 'Fixture'
+    args 'agent'
+}
+tasks.register('plainRun', JavaExec) {
+    classpath = sourceSets.main.runtimeClasspath
+    mainClass = 'Fixture'
+    args 'plain'
+}
+`,
+);
+await writeFile(
+    join(project, "src/main/java/Fixture.java"),
+    `
+public class Fixture {
+    public static void main(String[] args) throws Exception {
+        long count = java.lang.management.ManagementFactory.getRuntimeMXBean().getInputArguments()
+            .stream().filter(s -> s.startsWith("-javaagent:") && s.contains(".modlens")).count();
+        if (count != (args[0].equals("agent") ? 1 : 0)) throw new AssertionError("agent count " + count);
+        System.out.println("AGENT_COUNT=" + count);
+        var vmArgs = java.lang.management.ManagementFactory.getRuntimeMXBean().getInputArguments();
+        boolean hasShadowOption = vmArgs.stream().anyMatch(s -> s.startsWith("-XX:StackShadowPages="));
+        if (hasShadowOption != args[0].equals("agent")) throw new AssertionError("Stack setting leaked or missing: " + vmArgs);
+        if (count == 1) {
+            String shadowPages = java.lang.management.ManagementFactory.getPlatformMXBean(
+                com.sun.management.HotSpotDiagnosticMXBean.class).getVMOption("StackShadowPages").getValue();
+            if (!shadowPages.equals("32")) throw new AssertionError("Effective StackShadowPages=" + shadowPages);
+            System.out.println("STACK_SHADOW_PAGES=" + shadowPages);
+        }
+        if (count == 1) Thread.sleep(4000);
+    }
+}
+`,
+);
+const launcher = (await readdir(join(gradleHome, "lib"))).find((n) =>
+    /^gradle-gradle-cli-main-.*\.jar$/.test(n),
+);
+if (!launcher) throw new Error("Expected a Gradle 9.6 distribution");
+const java = join(javaHome, "bin", process.platform === "win32" ? "java.exe" : "java");
+execFileSync(java, ["-jar", join(gradleHome, "lib", launcher), "--no-daemon", "--offline", "wrapper"], {
+    cwd: project,
+    stdio: "inherit",
+    timeout: 120000,
+});
+const hub = process.argv.includes("--helper")
+    ? runtimeTestClient(root)
+    : new RuntimeHub(join(root, "bridge"));
+try {
+    const setup = await hub.setup(project, "hidden");
+    const init = join(project, ".modlens/runtime/init.gradle");
+    const plain = execFileSync(
+        java,
+        [
+            "-jar",
+            join(gradleHome, "lib", launcher),
+            "--no-daemon",
+            "--offline",
+            "--no-configuration-cache",
+            "-I",
+            init,
+            "plainRun",
+        ],
+        { cwd: project, encoding: "utf8", timeout: 120000 },
+    );
+    assert.match(plain, /AGENT_COUNT=0/);
+    await hub.launch(setup.projectId, javaHome);
+    const deadline = Date.now() + 120000;
+    let done;
+    while (Date.now() < deadline) {
+        const events = (await hub.events()).events;
+        done = events.find((e) => e.type === "launch_log");
+        if (done) break;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    assert.ok(done, "Gradle launch did not finish");
+    assert.match(done.data.text, /AGENT_COUNT=1/);
+    assert.match(done.data.text, /STACK_SHADOW_PAGES=32/);
+    assert.match(done.data.text, /BUILD SUCCESSFUL/);
+    assert.equal((await hub.list()).length, 1, "Only the game task should register");
+    assert.match(await readFile(setup.runConfiguration, "utf8"), /--init-script/);
+    console.log("Gradle optional agent launch passed. Evidence: " + root);
+} finally {
+    await hub.close();
+}

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();
+}