@creeperhost/modlens-mcp 1.6.20 → 1.6.21

package/scripts/fixtures/mod-license-corpus.json

@@ -0,0 +1,154 @@
+[
+  {
+    "name": "ModMenu",
+    "version": "v6Xx3fbU",
+    "release": "11.0.4",
+    "hash": "a88e0d67c82b0434cbf56776c482587c275ed660f635d33f53ba485dfa30dcc3",
+    "license": "MIT",
+    "expected": "hosted_allowed",
+    "target": "com.terraformersmc.modmenu.ModMenu"
+  },
+  {
+    "name": "FerriteCore",
+    "version": "sOzRw3CG",
+    "release": "7.0.3-fabric",
+    "hash": "98c3ab1d5aab8f14b5d082d3f1a467727fd335f02d124555c94339761c4c18f2",
+    "license": "MIT",
+    "expected": "hosted_allowed",
+    "target": "malte0811.ferritecore.IPlatformHooks"
+  },
+  {
+    "name": "MouseTweaks",
+    "version": "9I21YYxf",
+    "release": "1.21-2.26.1-neoforge",
+    "hash": "68e6f4201c5de97b77929a7215c9552495696ca6a3bf3ae4eacc34e135f6cc8b",
+    "license": "BSD-3-Clause",
+    "expected": "hosted_allowed",
+    "target": "yalter.mousetweaks.Constants"
+  },
+  {
+    "name": "DynamicFPS",
+    "version": "LqevwKp5",
+    "release": "3.11.4",
+    "hash": "0929d2b9e164a08d25a7ba8a5f0750081b66dea9171cec52d2f0fdc792fc7e5e",
+    "license": "MIT",
+    "expected": "hosted_allowed",
+    "target": "architectury_inject_dynamicfps_common_96ad272d90fa4fcc8d67753a3449cf6d_48138490a95625983251b45ac7336d8a7e463234a1fad5dfdc4c144b1c5f439adynamicfps3114devjar.PlatformMethods"
+  },
+  {
+    "name": "Controlling",
+    "version": "FaNppCJJ",
+    "release": "19.0.5",
+    "hash": "cc525fb6b030d9e4d33176983f278919e17b33935e2ca568929bdfa98f2b44a0",
+    "license": "MIT",
+    "expected": "hosted_allowed",
+    "target": "com.blamejared.controlling.Controlling"
+  },
+  {
+    "name": "Clumps",
+    "version": "jo7lDoK4",
+    "release": "19.0.0.1",
+    "hash": "b524ccdace2ef8fd19f5b2074f7de1103ac5065c52553f064c00e098346c293e",
+    "license": "MIT",
+    "expected": "hosted_allowed",
+    "target": "com.blamejared.clumps.helper.IClumpedOrb"
+  },
+  {
+    "name": "AppleSkin",
+    "version": "uAKA6Laj",
+    "release": "3.0.9+mc1.21",
+    "hash": "38b48dd6231341c9f964ce6e42c57ec866c6cc8f72bec938390a59bafb3922df",
+    "license": "Unlicense",
+    "expected": "hosted_allowed",
+    "target": "squeek.appleskin.ModInfo"
+  },
+  {
+    "name": "Architectury",
+    "version": "1IiqEQGl",
+    "release": "13.0.11+neoforge",
+    "hash": "9cc92f2c09533fc5482c60f993bd891c655a0e32b637037cdcb7c2b23adedeeb",
+    "license": "LGPL-3.0-only",
+    "expected": "local_only",
+    "target": "architectury_inject_architectury_common_d9fb27da44a148dfa43566d20897d6de_f4ed98e062c0e85c5cc998c6fbbab16b146fa1f727cd0f469b44c896e896070earchitectury13011devjar.PlatformMethods"
+  },
+  {
+    "name": "ClothConfig",
+    "version": "izKINKFg",
+    "release": "15.0.140+neoforge",
+    "hash": "65e722e0d98431a07c45f8bdd8d529a217cc8c175fde1740248bd5c1b4f3c0d4",
+    "license": "LGPL-3.0-only",
+    "expected": "local_only",
+    "target": "architectury_inject_clothconfig_common_d551de04735c42148ec07a78c43007d1_c487a9cf12e7d5bea169da255b814f03602bdeb8b51cff67162252c24f285789clothconfig150140devjar.PlatformMethods"
+  },
+  {
+    "name": "ModernFix",
+    "version": "5HLHxQ2F",
+    "release": "5.27.24+mc1.21.1",
+    "hash": "e6e9446890f0feb3aab3f6e73ae18cb17575c370f232179fef7baa30e61538fe",
+    "license": "LGPL-3.0-only",
+    "expected": "local_only",
+    "target": "org.embeddedt.modernfix.ModernFix"
+  },
+  {
+    "name": "Spark",
+    "version": "v5qtqRQi",
+    "release": "1.10.124-neoforge-1.21.1",
+    "hash": "647e8a81afbe414dba1df4ba15fd06c5d32d4cb544e68828405e8e074c2e16db",
+    "license": "GPL-3.0-only",
+    "expected": "local_only",
+    "target": "me.lucko.spark.neoforge.NeoForgePlatformInfo"
+  },
+  {
+    "name": "Sodium",
+    "version": "uMOpc5uV",
+    "release": "mc1.21.1-0.8.13-neoforge",
+    "hash": "575d187b15328d7bddd8a9b1bee64333c22c14735f5780ec49eac0cd5503c08d",
+    "license": "LicenseRef-Polyform-Shield-1.0.0",
+    "expected": "local_only",
+    "target": "net.caffeinemc.mods.sodium.service.SodiumServiceModLocator"
+  },
+  {
+    "name": "Iris",
+    "version": "t3ruzodq",
+    "release": "1.8.12+1.21.1-neoforge",
+    "hash": "3e3f94d2d5cdcb8145c4385d521974aa2d8669b2cc212351f70cf06488182e83",
+    "license": "LGPL-3.0-only",
+    "expected": "local_only",
+    "target": "de.odysseus.ithaka.digraph.Digraph"
+  },
+  {
+    "name": "Lithium",
+    "version": "N08Z8wog",
+    "release": "mc1.21.1-0.15.4-fabric",
+    "hash": "92329d98c57f5a22091a0adb509fdb1d60113a5602c708b799b13134bad13baa",
+    "license": "LGPL-3.0-only",
+    "expected": "local_only",
+    "target": "net.caffeinemc.mods.lithium.api.inventory.LithiumCooldownReceivingInventory"
+  },
+  {
+    "name": "EntityCulling",
+    "version": "8w8FfUPs",
+    "release": "1.11.2",
+    "hash": "3983b981da4a0583c7e58184a8631a23e56cc3b81f4cb53491ca600382879b82",
+    "license": "LicenseRef-tr7zw-Protective-License",
+    "expected": "local_only",
+    "target": "com.logisticscraft.occlusionculling.DataProvider"
+  },
+  {
+    "name": "JourneyMap",
+    "version": "CtFE7hwT",
+    "release": "1.21.1-6.0.9+neoforge",
+    "hash": "9bd7734542233d5281750572f17a9258449e826650c081e9a67dc426262c2fde",
+    "license": "LicenseRef-All-Rights-Reserved",
+    "expected": "local_only",
+    "target": "earcut4j.Earcut"
+  },
+  {
+    "name": "FabricAPI",
+    "version": "Mys3P7lK",
+    "release": "0.116.17+1.21.1",
+    "hash": "79ac44b40780acbd884b34c50be1e39af682847e5f5cb3b1fddeeaa768dce800",
+    "license": "Apache-2.0",
+    "expected": "hosted_allowed"
+  }
+]

package/scripts/gradle/modlens-runtime.init.gradle

@@ -0,0 +1,17 @@
+// Opt-in launch only. Never instrument Gradle itself or every JavaExec task.
+gradle.projectsEvaluated {
+    def configFile = new File(gradle.rootProject.projectDir, '.modlens/runtime/launch.properties')
+    if (!configFile.isFile()) throw new GradleException('Call ModLens runtime.setup for this project first')
+    def config = new Properties()
+    configFile.withInputStream { config.load(it) }
+    def taskPath = config.getProperty('task')
+    if (!taskPath.startsWith(':')) taskPath = ':' + taskPath
+    def target = gradle.rootProject.tasks.findByPath(taskPath)
+    if (!(target instanceof JavaExec)) {
+        throw new GradleException("ModLens requires a JavaExec dev run task; ${taskPath} is ${target?.class?.name ?: 'missing'}. Use every returned vmOptions entry on the actual game launch instead.")
+    }
+    target.jvmArgs("-javaagent:${config.getProperty('agent')}=${config.getProperty('connection')}")
+    // Minecraft 26.3 client startup needs this even without the agent.
+    target.jvmArgs('-XX:StackShadowPages=32')
+    target.jvmArgs("-XX:ErrorFile=${new File(configFile.parentFile, 'hs_err_pid%p.log').absolutePath}")
+}

package/scripts/runtime-test-client.mjs

@@ -0,0 +1,36 @@
+// Test adapter: run the same fixture through separate CLI processes instead of
+// importing RuntimeHub. Each call reconnects to the persistent companion.
+import { writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+
+export function runtimeTestClient(root) {
+    const launcher = fileURLToPath(new URL("../dist/launcher.js", import.meta.url));
+    const env = { ...process.env, MODLENS_CACHE_ROOT: join(root, "helper-cache") };
+    const run = (args) =>
+        JSON.parse(
+            execFileSync(process.execPath, [launcher, "--runtime", ...args], {
+                env,
+                encoding: "utf8",
+                timeout: 45000,
+            }),
+        );
+    async function request(body) {
+        const file = join(root, `helper-${randomUUID()}.json`);
+        await writeFile(file, JSON.stringify(body));
+        return run(["--request-file", file]);
+    }
+    return {
+        setup: (projectDir, mode, gradleTask, minecraftHooks) =>
+            request({ action: "setup", projectDir, mode, gradleTask, minecraftHooks }),
+        list: () => request({ action: "sessions" }),
+        events: (afterCursor, waitMs, sessionId) =>
+            request({ action: "events", afterCursor, waitMs, sessionId }),
+        command: (sessionId, command) => request({ action: "command", sessionId, command }),
+        artifact: (sessionId, artifactName) => request({ action: "artifact", sessionId, artifactName }),
+        launch: (projectId, javaHome) => request({ action: "launch", projectId, javaHome }),
+        close: async () => run(["stop"]),
+    };
+}

package/scripts/test-hosted-policy.mjs

@@ -0,0 +1,123 @@
+// Real transports, synthetic source only: no Minecraft download or decompilation.
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } 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";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const root = await mkdtemp(join(tmpdir(), "modlens-hosted-test-"));
+const entry = fileURLToPath(new URL("../dist/server.js", import.meta.url));
+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 endpoint = new URL(`http://127.0.0.1:${port}/mcp`);
+const secret = randomBytes(32).toString("hex");
+const env = { ...process.env, MCP_PORT: String(port), MCP_HOST: "127.0.0.1", MODLENS_HOME: root,
+    MODLENS_CACHE_ROOT: join(root, "cache"), DATABASE_URL: `file:${join(root, "usage.db")}`,
+    MODLENS_HOSTED_LIMITS: "1", MODLENS_HOSTED_PROXY_SECRET: secret, MODLENS_HOSTED_SOURCE_LINES: "200",
+    MODLENS_HOSTED_DAILY_BYTES: "15000", MODLENS_HOSTED_PERIOD_BYTES: "100000",
+    MODLENS_HOSTED_DAILY_REQUESTS: "1000", MODLENS_HOSTED_MINUTE_REQUESTS: "120",
+    MODLENS_HOSTED_RESPONSE_BYTES: "131072", MODLENS_AUTO_EMBED: "0", MODLENS_AUTO_GRAPH: "0" };
+const source = Array.from({ length: 600 }, (_, i) => `// Synthetic fixture line ${i + 1}`).join("\n");
+const fixtureDir = join(env.MODLENS_CACHE_ROOT, "mc-decompiled-named", "1.21.1", "example");
+await mkdir(fixtureDir, { recursive: true });
+await writeFile(join(fixtureDir, "Fixture.java"), source);
+const headers = user => ({ "x-modlens-proxy-secret": secret, "x-modlens-user-id": user });
+let server, exited;
+const clients = [];
+async function start() {
+    let logs = "";
+    server = spawn(process.execPath, [entry], { cwd: root, env, stdio: ["ignore", "ignore", "pipe"], windowsHide: true });
+    exited = once(server, "exit");
+    server.stderr.on("data", data => { logs += data; });
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Startup timed out: ${logs}`)), 15000);
+        const ready = () => {
+            if (logs.includes("listening on")) { clearTimeout(timer); server.stderr.off("data", ready); resolve(); }
+        };
+        server.stderr.on("data", ready);
+        server.once("error", reject);
+        server.once("exit", () => { clearTimeout(timer); reject(new Error(`Server exited: ${logs}`)); });
+        ready();
+    });
+}
+async function connect(user) {
+    const client = new Client({ name: "hosted-policy-test", version: "1" });
+    clients.push(client);
+    const transport = new StreamableHTTPClientTransport(endpoint, { requestInit: { headers: headers(user) } });
+    await client.connect(transport);
+    return { client, transport };
+}
+const read = (client, startLine = 1) => client.callTool({ name: "mc_source", arguments: {
+    action: "get_source", version: "1.21.1", className: "example.Fixture", startLine, maxLines: 10000,
+} });
+let passed = false;
+try {
+    await start();
+    const unauthorized = await fetch(endpoint, { method: "POST", headers: { "x-modlens-user-id": "spoof" }, body: "{}" });
+    assert.equal(unauthorized.status, 401);
+    const { client, transport } = await connect("developer-a");
+    const listed = await client.listTools();
+    assert.ok(listed.tools.some(t => t.name === "report_issue"), "Hosted users must discover issue reporting");
+    const reporter = await connect("issue-reporter");
+    const preparedIssue = await reporter.client.callTool({ name: "report_issue", arguments: {
+        action: "prepare", title: "Hosted test fixture", summary: "Synthetic report; never submit.",
+    } });
+    assert.ok(!preparedIssue.isError, JSON.stringify(preparedIssue));
+    const issuePlan = JSON.parse(preparedIssue.content[0].text);
+    assert.equal(issuePlan.state, "draft_prepared");
+    assert.equal(issuePlan.executed, false);
+    assert.equal(issuePlan.repository.url, "https://github.com/CreeperHost/modlens-mcp");
+    const mc = listed.tools.find(t => t.name === "mc_source");
+    assert.ok(mc.inputSchema.properties.action.enum.includes("bytecode"));
+    for (const action of ["decompile", "get_paths", "index", "decompile_status"]) {
+        assert.ok(!mc.inputSchema.properties.action.enum.includes(action), action);
+    }
+    assert.ok(listed.tools.some(t => t.name === "mc_data"));
+    assert.ok(listed.tools.find(t => t.name === "mod_bytecode").inputSchema.properties.startLine);
+    const denied = await client.callTool({ name: "mc_source", arguments: { action: "get_paths", version: "1.21.1" } });
+    assert.ok(denied.isError);
+    const wrongOwner = await fetch(endpoint, { headers: { ...headers("developer-b"), "mcp-session-id": transport.sessionId, accept: "text/event-stream" } });
+    assert.equal(wrongOwner.status, 404);
+    const first = await read(client);
+    assert.ok(!first.isError, JSON.stringify(first));
+    assert.equal(first.content[0].text, source.split("\n").slice(0, 200).join("\n"));
+    const second = await read(client, 201);
+    assert.ok(!second.isError, JSON.stringify(second));
+    assert.equal(second.content[0].text, source.split("\n").slice(200, 400).join("\n"));
+    const exhausted = await read(client, 401);
+    assert.ok(exhausted.isError);
+    assert.ok(!JSON.stringify(exhausted).includes("Synthetic fixture"));
+    const reconnected = await connect("developer-a");
+    assert.ok((await read(reconnected.client)).isError, "reconnect must retain quota");
+    for (const c of clients.splice(0)) await c.close();
+    server.kill(); await exited;
+    await start();
+    const restarted = await connect("developer-a");
+    assert.ok((await read(restarted.client)).isError, "restart must retain quota");
+    const different = await connect("developer-b");
+    assert.ok(!(await read(different.client)).isError, "separate verified accounts have separate allowances");
+    const local = new Client({ name: "hosted-local-test", version: "1" });
+    clients.push(local);
+    await local.connect(new StdioClientTransport({ command: process.execPath, args: [entry], cwd: root,
+        env: { ...env, MCP_PORT: "" }, stderr: "pipe" }));
+    const localResult = await read(local);
+    assert.ok(!localResult.isError, JSON.stringify(localResult));
+    assert.equal(localResult.content[0].text, source, "local source access remains unrestricted");
+    passed = true;
+    console.log("PASS: hosted discovery, authentication, account/session binding, source paging, cumulative release limits, reconnect/restart persistence and unrestricted local access");
+} finally {
+    for (const client of clients) await client.close().catch(() => {});
+    if (server && server.exitCode === null) { server.kill(); await exited; }
+    if (passed) await rm(root, { recursive: true, force: true });
+    else console.error(`Fixture retained for debugging: ${root}`);
+}

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