@creeperhost/modlens-mcp 1.6.19 → 1.6.21

package/dist/tools/runtime.js

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+import { CACHE_ROOT } from "../cache.js";
+import { RuntimeHub, RUNTIME_HELP } from "../runtime/hub.js";
+import { executeRuntime, runtimeRequest } from "../runtime/requests.js";
+import { localExecutionPlan } from "../runtime/guidance.js";
+export { runtimeToolSchema } from "../runtime/requests.js";
+export const runtimeHub = new RuntimeHub(join(CACHE_ROOT, "runtime"));
+export async function runtimeAction(raw) {
+    const request = runtimeRequest.parse(raw);
+    if (process.env.MCP_PORT) {
+        if (request.action === "help")
+            return { ...RUNTIME_HELP, localExecution: localExecutionPlan(request) };
+        // A remote tool supplies instructions, never executes paths on the user's PC.
+        return localExecutionPlan(request);
+    }
+    return executeRuntime(runtimeHub, request);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/tools/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/tools/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAuB,MAAM,wBAAwB,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AAEtE,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAmB;IACnD,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QACvB,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;YACzB,OAAO,EAAE,GAAG,YAAY,EAAE,cAAc,EAAE,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5E,8EAA8E;QAC9E,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC"}

package/dist/tools/source.d.ts

@@ -1,4 +1,4 @@
-export declare function getModSource(dbId: number, path?: string): Promise<string>;
+export declare function getModSource(dbId: number, path?: string, startLine?: number, maxLines?: number): Promise<string>;
 export declare function searchSource(query: string, dbId?: number, isRegex?: boolean, limit?: number): Promise<Array<{
     modId: string;
     modVersion: string;

package/dist/tools/source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/tools/source.ts"],"names":[],"mappings":"AA4BA,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB/E;AAED,wBAAsB,YAAY,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,UAAQ,EACf,KAAK,SAAK,GACX,OAAO,CAAC,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAejG;AAkCD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAaxF"}
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/tools/source.ts"],"names":[],"mappings":"AA4BA,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqBtH;AAED,wBAAsB,YAAY,CAC9B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,UAAQ,EACf,KAAK,SAAK,GACX,OAAO,CAAC,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAejG;AAkCD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAaxF"}

package/dist/tools/source.js

@@ -29,7 +29,7 @@ async function getDecompPath(dbId) {
     }
     throw new Error(`Decompile timed out for mod #${dbId}`);
 }
-export async function getModSource(dbId, path) {
+export async function getModSource(dbId, path, startLine, maxLines) {
     validateDbId(dbId);
     const decompPath = await getDecompPath(dbId);
     if (!path) {
@@ -46,6 +46,10 @@ export async function getModSource(dbId, path) {
         return entries.join("\n");
     }
     const content = await readFile(filePath, "utf8");
+    if (startLine !== undefined || maxLines !== undefined) {
+        const start = Math.max(0, (startLine ?? 1) - 1);
+        return content.split(/\r\n|\n|\r/).slice(start, start + (maxLines ?? 200)).join("\n");
+    }
     return content.slice(0, 50_000); // cap at 50KB
 }
 export async function searchSource(query, dbId, isRegex = false, limit = 50) {

package/dist/tools/source.js.map

@@ -1 +1 @@
-{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/tools/source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/tools/source.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creeperhost/modlens-mcp",
-  "version": "1.6.19",
+  "version": "1.6.21",
   "description": "MCP server for browsing, decompiling, and analyzing Minecraft mod JARs",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,7 @@
     "scripts/",
     "package.json",
     "README.md",
+    "RUNTIME.md",
     "TESTING.md",
     "LICENSE",
     "ATTRIBUTION.md"
@@ -29,12 +30,15 @@
   "scripts": {
     "postinstall": "prisma generate",
     "build": "npm run db:generate:sqlite && tsc && node scripts/build-template-db.mjs",
+    "build:agent": "node scripts/build-runtime-agent.mjs",
+    "test:runtime:native": "node scripts/test-runtime-native.mjs",
     "dev": "tsc --watch",
     "start": "node dist/server.js",
     "setup": "npm run build && node dist/setup.js",
     "test": "vitest run",
     "test:package": "node scripts/test-package.mjs",
     "test:minecraft:eras": "node scripts/test-minecraft-eras.mjs",
+    "test:primers:live": "node scripts/test-primers-live.mjs",
     "test:project:gradle": "node scripts/test-project-gradle.mjs",
     "test:project:http": "node scripts/test-project-http.mjs",
     "test:watch": "vitest",
@@ -61,12 +65,15 @@
     "better-sqlite3": "^12.11.1",
     "prisma": "^6.0.0",
     "smol-toml": "^1.6.1",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
     "@types/better-sqlite3": "^7.0.0",
     "@types/node": "^22.0.0",
+    "@types/turndown": "^5.0.6",
     "typescript": "^5.6.0",
     "vitest": "^4.1.6"
   },

package/scripts/build-runtime-agent.mjs

@@ -0,0 +1,64 @@
+import { mkdir, mkdtemp, readdir, writeFile, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const scratch = join(root, ".scratch");
+await mkdir(scratch, { recursive: true });
+// A clean output directory prevents removed/renamed classes leaking into the JAR.
+const build = await mkdtemp(join(scratch, "runtime-build-"));
+const output = join(root, "dist/runtime");
+const javaTool = (name) =>
+    process.env.JAVA_HOME
+        ? join(process.env.JAVA_HOME, "bin", name + (process.platform === "win32" ? ".exe" : ""))
+        : name;
+async function sources(dir) {
+    return (
+        await Promise.all(
+            (await readdir(dir, { withFileTypes: true })).map((e) =>
+                e.isDirectory()
+                    ? sources(join(dir, e.name))
+                    : e.name.endsWith(".java")
+                      ? [join(dir, e.name)]
+                      : [],
+            ),
+        )
+    ).flat();
+}
+try {
+    await mkdir(output, { recursive: true });
+    const version = execFileSync(javaTool("javac"), ["-version"], { encoding: "utf8" });
+    if (Number(/javac (\d+)/.exec(version)?.[1]) < 25)
+        throw new Error("Building the runtime agent requires JDK 25+. Set JAVA_HOME.");
+    const files = await sources(join(root, "runtime-agent/src"));
+    // javac argument files avoid Windows command length limits and handle spaces.
+    const args = ["--release", "25", "-d", build, ...files];
+    await writeFile(
+        join(build, "javac.args"),
+        args.map((a) => `"${a.replaceAll("\\", "/").replaceAll('"', '\\"')}"`).join("\n"),
+    );
+    execFileSync(javaTool("javac"), ["@" + join(build, "javac.args")], { stdio: "inherit" });
+    await writeFile(
+        join(build, "MANIFEST.MF"),
+        "Manifest-Version: 1.0\nPremain-Class: io.modlens.runtime.Agent\nCan-Redefine-Classes: false\nCan-Retransform-Classes: false\n\n",
+    );
+    execFileSync(
+        javaTool("jar"),
+        [
+            "--create",
+            "--file",
+            join(output, "modlens-agent.jar"),
+            "--manifest",
+            join(build, "MANIFEST.MF"),
+            "-C",
+            build,
+            "io",
+        ],
+        { stdio: "inherit" },
+    );
+    console.log("Built " + resolve(output, "modlens-agent.jar"));
+} finally {
+    if (dirname(resolve(build)) !== resolve(scratch)) throw new Error("Unexpected build cleanup path");
+    await rm(build, { recursive: true, force: true });
+}

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;