@creeperhost/modlens-mcp 1.6.18 → 1.6.20

package/scripts/gradle/modlens.init.gradle

@@ -0,0 +1,154 @@
+// Apply without modifying a project: ./gradlew -I /path/to/modlens.init.gradle :modlensExport
+// ModDevGradle 2.x adapter plus a generic Java source-set compile-classpath exporter.
+import groovy.json.JsonOutput
+import java.security.MessageDigest
+import java.security.SecureRandom
+import java.nio.file.Files
+import java.nio.file.StandardCopyOption
+import java.nio.file.StandardOpenOption
+import java.nio.file.FileAlreadyExistsException
+import java.util.zip.ZipEntry
+import java.util.zip.ZipOutputStream
+import org.gradle.api.GradleException
+import org.gradle.api.plugins.JavaPluginExtension
+import org.gradle.api.provider.Provider
+
+def sha256 = { File file ->
+    def md = MessageDigest.getInstance('SHA-256')
+    file.withInputStream { input ->
+        byte[] buffer = new byte[65536]
+        int count
+        while ((count = input.read(buffer)) != -1) md.update(buffer, 0, count)
+    }
+    md.digest().encodeHex().toString()
+}
+
+gradle.projectsEvaluated {
+    allprojects { p ->
+        def javaExtension = p.extensions.findByType(JavaPluginExtension)
+        if (javaExtension == null) return
+        String selected = p.findProperty('modlensSourceSet')?.toString() ?: 'main'
+        def sourceSet = javaExtension.sourceSets.findByName(selected)
+        if (sourceSet == null) {
+            // A sibling module may not have the source set selected for the requested module.
+            p.tasks.register('modlensExport') {
+                doLast { throw new GradleException("Unknown ModLens source set '${selected}' in ${p.path}") }
+            }
+            return
+        }
+        boolean moddev = p.plugins.hasPlugin('net.neoforged.moddev') || p.plugins.hasPlugin('net.neoforged.moddev.legacyforge')
+        def artifactsTask = moddev ? p.tasks.findByName('createMinecraftArtifacts') : null
+        if (moddev && artifactsTask == null) throw new GradleException('ModLens requires a ModDevGradle version with createMinecraftArtifacts (2.x).')
+
+        p.tasks.register('modlensExport') { task ->
+            group = 'modlens'
+            description = 'Export the resolved compile environment for local or remote ModLens.'
+            // Gradle resolves/builds the actual compilation inputs, including AT processing.
+            dependsOn(sourceSet.compileClasspath)
+            if (artifactsTask != null) dependsOn(artifactsTask)
+            // This task accesses the evaluated model and is intentionally not configuration-cache compatible.
+            notCompatibleWithConfigurationCache('ModLens exports the evaluated compile classpath and modding task outputs.')
+            doLast {
+                File output = p.layout.buildDirectory.dir("modlens/${selected}").get().asFile
+                output.mkdirs()
+                def artifacts = []
+                def files = []
+                def byFile = [:]
+                def addArtifact = { File file, String kind, String sourceFor ->
+                    if (!file.isFile()) throw new GradleException("Missing ModLens artifact: ${file.name}")
+                    String path = "artifacts/${artifacts.size()}.jar"
+                    def info = [path: path, name: file.name, sha256: sha256(file), size: file.length(), kind: kind]
+                    if (sourceFor != null) info.sourceFor = sourceFor
+                    artifacts.add(info)
+                    files.add(file)
+                    if (kind == 'classpath') byFile[file.canonicalPath] = path
+                    path
+                }
+                sourceSet.compileClasspath.files.eachWithIndex { File file, int index ->
+                    if (!file.exists()) throw new GradleException("Compile classpath entry does not exist: ${file.name}")
+                    if (file.isDirectory()) {
+                        // Project dependencies often expose class directories instead of JARs.
+                        File jar = new File(output, "directory-${index}.jar")
+                        def entries = p.fileTree(file).matching { include '**/*.class'; include '**/*.java' }.files.sort { a, b ->
+                            file.toPath().relativize(a.toPath()).toString() <=> file.toPath().relativize(b.toPath()).toString()
+                        }
+                        jar.withOutputStream { stream ->
+                            def zip = new ZipOutputStream(stream)
+                            entries.each { entry ->
+                                def name = file.toPath().relativize(entry.toPath()).toString().replace('\\', '/')
+                                def ze = new ZipEntry(name); ze.time = 0
+                                zip.putNextEntry(ze); entry.withInputStream { zip << it }; zip.closeEntry()
+                            }
+                            zip.finish()
+                        }
+                        addArtifact(jar, 'classpath', null)
+                    } else if (file.name.endsWith('.jar')) {
+                        addArtifact(file, 'classpath', null)
+                    } else {
+                        throw new GradleException("Unsupported compile classpath entry: ${file.name}")
+                    }
+                }
+                if (artifacts.empty) throw new GradleException('Compile classpath is empty; there is no dependency environment to export.')
+
+                def transforms = []
+                if (artifactsTask != null) {
+                    // Bind sources to the binary actually selected by the compile classpath, not a guessed cache path.
+                    def binaryPaths = ['gameJarArtifact', 'gameJarWithSourcesArtifact'].collect { property ->
+                        artifactsTask.hasProperty(property) ? artifactsTask.property(property).orNull?.asFile?.canonicalPath : null
+                    }.findAll { it != null && byFile.containsKey(it) }
+                    if (binaryPaths.empty) throw new GradleException('ModLens cannot locate ModDevGradle Minecraft output on this source set compile classpath. Select a mod-enabled source set.')
+                    def sourceFile = artifactsTask.hasProperty('gameSourcesArtifact') ? artifactsTask.gameSourcesArtifact.orNull?.asFile : null
+                    if (sourceFile?.isFile()) binaryPaths.each { path -> addArtifact(sourceFile, 'sources', byFile[path]) }
+                    if (artifactsTask.hasProperty('accessTransformers')) {
+                        artifactsTask.accessTransformers.files.each { File file -> transforms.add([name: file.name, sha256: sha256(file)]) }
+                    }
+                }
+                def neo = p.extensions.findByName('neoForge') ?: p.extensions.findByName('legacyForge')
+                def propertyText = { String name -> p.findProperty(name)?.toString() ?: '' }
+                String loaderVersion = propertyText('neo_version') ?: propertyText('forge_version')
+                if (neo != null && neo.hasProperty('version')) {
+                    def version = neo.version
+                    loaderVersion = (version instanceof Provider ? version.orNull : version)?.toString() ?: loaderVersion
+                }
+                String mappings = propertyText('modlensMappings')
+                if (!mappings && neo != null && neo.hasProperty('parchment') && neo.parchment.enabled.getOrElse(false)) {
+                    mappings = "parchment:${neo.parchment.minecraftVersion.orNull ?: ''}:${neo.parchment.mappingsVersion.orNull ?: ''}"
+                }
+                if (!mappings) mappings = moddev ? 'toolchain-prepared (official names where applicable)' : 'compile-classpath'
+                def manifest = [format: 'modlens-project-v1', project: "${p.rootProject.name}${p.path}", sourceSet: selected,
+                    toolchain: moddev ? 'moddevgradle' : 'gradle-compile-classpath',
+                    minecraftVersion: propertyText('minecraft_version') ?: propertyText('modlensMinecraftVersion'),
+                    loaderVersion: loaderVersion, mappings: mappings,
+                    javaVersion: p.tasks.named(sourceSet.compileJavaTaskName).get().options.release.orNull ?: javaExtension.toolchain.languageVersion.orNull?.asInt() ?: Integer.parseInt(org.gradle.api.JavaVersion.current().majorVersion),
+                    transformations: transforms, artifacts: artifacts]
+                File temporary = new File(output, 'environment.zip.tmp')
+                temporary.withOutputStream { stream ->
+                    def zip = new ZipOutputStream(stream)
+                    def metadata = new ZipEntry('manifest.json'); metadata.time = 0
+                    zip.putNextEntry(metadata); zip.write(JsonOutput.toJson(manifest).getBytes('UTF-8')); zip.closeEntry()
+                    artifacts.eachWithIndex { artifact, index ->
+                        def entry = new ZipEntry(artifact.path); entry.time = 0
+                        zip.putNextEntry(entry); files[index].withInputStream { zip << it }; zip.closeEntry()
+                    }
+                    zip.finish()
+                }
+                File destination = new File(output, 'environment.zip')
+                Files.move(temporary.toPath(), destination.toPath(), StandardCopyOption.REPLACE_EXISTING)
+                File keyFile = new File(p.projectDir, '.gradle/modlens/project-key.txt')
+                keyFile.parentFile.mkdirs()
+                if (!keyFile.exists()) {
+                    byte[] key = new byte[32]; new SecureRandom().nextBytes(key)
+                    // CREATE_NEW prevents concurrent exports from silently replacing a project key.
+                    try { Files.write(keyFile.toPath(), (key.encodeHex().toString() + '\n').getBytes('UTF-8'), StandardOpenOption.CREATE_NEW) }
+                    catch (FileAlreadyExistsException ignored) { }
+                    keyFile.setReadable(false, false); keyFile.setWritable(false, false)
+                    keyFile.setReadable(true, true); keyFile.setWritable(true, true)
+                }
+                if (!(keyFile.text.trim() ==~ /[a-f0-9]{64}/)) throw new GradleException('Invalid existing ModLens project key; expected 64 lowercase hex characters.')
+                logger.lifecycle("ModLens bundle: ${destination}")
+                logger.lifecycle("ModLens private key file: ${keyFile}")
+                logger.lifecycle('Re-export and import after changing dependencies, mappings or access transformers.')
+            }
+        }
+    }
+}

package/scripts/project-upload.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Transfer a Gradle export over MCP without exposing a local filesystem path to the server.
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { readFile, open, stat } from 'node:fs/promises';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const [endpoint, bundlePath, keyFile] = process.argv.slice(2);
+if (!endpoint || !bundlePath || !keyFile || process.argv.length !== 5) {
+    console.error('Usage: node scripts/project-upload.mjs <https://host/mcp> <environment.zip> <project-key.txt>');
+    process.exit(1);
+}
+const url = new URL(endpoint);
+if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+    throw new Error('Use HTTPS for remote project uploads (HTTP is allowed only on loopback).');
+}
+if (url.username || url.password || url.search || url.hash) throw new Error('Endpoint must not contain credentials, query parameters or a fragment. Use MODLENS_AUTH_TOKEN for proxy authentication.');
+const projectKey = (await readFile(keyFile, 'utf8')).trim();
+if (!/^[a-f0-9]{64}$/.test(projectKey)) throw new Error('Invalid project key file');
+const size = (await stat(bundlePath)).size;
+if (!size || size > 512 * 1024 * 1024) throw new Error('Bundle must contain 1 byte to 512 MiB');
+const hash = createHash('sha256');
+for await (const chunk of createReadStream(bundlePath)) hash.update(chunk);
+const client = new Client({ name: 'modlens-project-upload', version: '1.0.0' });
+const transport = new StreamableHTTPClientTransport(url, { requestInit: {
+    // Never follow redirects carrying the private project capability in the request body.
+    redirect: 'error',
+    headers: process.env.MODLENS_AUTH_TOKEN ? { Authorization: `Bearer ${process.env.MODLENS_AUTH_TOKEN}` } : {},
+} });
+let uploadId;
+try {
+    await client.connect(transport);
+    const call = async (args) => {
+        const response = await client.callTool({ name: 'project', arguments: { ...args, projectKey } }, undefined, { timeout: 300_000 });
+        const text = response.content?.filter(c => c.type === 'text').map(c => c.text).join('\n');
+        if (response.isError) throw new Error(text || 'Project upload failed');
+        return JSON.parse(text);
+    };
+    const begin = await call({ action: 'upload_begin', size, sha256: hash.digest('hex') });
+    uploadId = begin.uploadId;
+    const file = await open(bundlePath, 'r');
+    try {
+        let offset = 0;
+        while (offset < size) {
+            const bytes = Buffer.alloc(Math.min(begin.chunkBytes, size - offset));
+            const { bytesRead } = await file.read(bytes, 0, bytes.length, offset);
+            if (bytesRead !== bytes.length) throw new Error('Bundle changed during upload; re-export it.');
+            // Retrying an acknowledged range is checked byte-for-byte by the server.
+            let result;
+            for (let attempt = 0; attempt < 3; attempt++) {
+                try { result = await call({ action: 'upload_chunk', uploadId, offset, data: bytes.toString('base64') }); break; }
+                catch (error) { if (attempt === 2) throw error; }
+            }
+            if (result.offset !== offset + bytes.length) throw new Error('Unexpected upload offset');
+            offset = result.offset;
+        }
+    } finally { await file.close(); }
+    let result;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try { result = await call({ action: 'upload_finish', uploadId }); break; }
+        catch (error) { if (attempt === 2) throw error; }
+    }
+    console.log(JSON.stringify(result, null, 2));
+    await call({ action: 'upload_abort', uploadId }); // receipt no longer needed
+    uploadId = undefined;
+} catch (error) {
+    if (uploadId) {
+        try { await client.callTool({ name: 'project', arguments: { action: 'upload_abort', projectKey, uploadId } }); } catch { }
+    }
+    // Do not print transport objects or request bodies, which contain the project capability.
+    console.error(`Project upload failed: ${String(error.message).split(projectKey).join('[redacted]')}`);
+    process.exitCode = 1;
+} finally { await client.close(); }

package/scripts/test-minecraft-eras.mjs

@@ -0,0 +1,202 @@
+/** Live MCP compatibility checks. Uses public downloads and an isolated database/cache. */
+import assert from "node:assert/strict";
+import { appendFile, copyFile, cp, mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const repository = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const arguments_ = process.argv.slice(2);
+const runMods = !arguments_.length || arguments_.includes("--mods");
+const selectedVersions = arguments_.filter(arg => arg !== "--mods");
+const versions = selectedVersions.length ? selectedVersions : runMods && arguments_.length ? [] : [
+    "b1.7.3", "1.2.5", "1.5.2", "1.6.4", "1.7.10", "1.8.9", "1.12.2",
+    "1.13.2", "1.16.5", "1.18.2", "1.20.1", "1.20.6", "1.21.1", "26.1.2",
+];
+const root = await mkdtemp(join(tmpdir(), "modlens-minecraft-eras-"));
+const cache = join(root, "cache");
+await mkdir(cache, { recursive: true });
+if (process.env.MODLENS_TEST_ARTIFACT_CACHE) {
+    for (const directory of ["mc-jars", "mappings", "tools", "jdk"]) {
+        await cp(join(process.env.MODLENS_TEST_ARTIFACT_CACHE, directory), join(cache, directory), { recursive: true }).catch(error => {
+            if (error.code !== "ENOENT") throw error;
+        });
+    }
+}
+await copyFile(join(repository, "prisma/backends/template.db"), join(root, "database.db"));
+
+// An explicit read-only seed can avoid re-downloading the analysis tools.
+if (process.env.MODLENS_TEST_TOOL_CACHE) {
+    await mkdir(join(cache, "tools"), { recursive: true });
+    for (const name of ["mcsrc-indexer.jar", "vineflower.jar", "tiny-remapper.jar", "SpecialSource.jar"]) {
+        await copyFile(join(process.env.MODLENS_TEST_TOOL_CACHE, name), join(cache, "tools", name)).catch(error => {
+            if (error.code !== "ENOENT") throw error;
+        });
+    }
+}
+const environment = Object.fromEntries(Object.entries(process.env).filter(([key, value]) =>
+    typeof value === "string" && !/TOKEN|API_KEY|SECRET|^(MCP_|DATABASE_URL$|MODLENS_|OLLAMA_|AUTO_)/i.test(key),
+));
+Object.assign(environment, {
+    DATABASE_URL: `file:${join(root, "database.db").replaceAll("\\", "/")}`,
+    MODLENS_HOME: join(root, "home"), MODLENS_CACHE_ROOT: cache,
+    MODLENS_AUTO_EMBED: "0", MODLENS_AUTO_GRAPH: "0", OLLAMA_URL: "http://127.0.0.1:1",
+});
+const client = new Client({ name: "minecraft-era-validation", version: "1.0" });
+const transport = new StdioClientTransport({
+    command: process.execPath, args: [join(repository, "dist/server.js")],
+    cwd: root, env: environment, stderr: "pipe",
+});
+const errors = [];
+const results = [];
+let serverLog = "";
+transport.stderr?.on("data", data => { serverLog += data; });
+console.log(`Evidence: ${root}`);
+
+async function call(name, args, validate, expectError = false) {
+    const start = Date.now();
+    const result = { name, args };
+    try {
+        const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 300_000 });
+        const text = response.content.filter(item => item.type === "text").map(item => item.text).join("\n");
+        let data;
+        try { data = JSON.parse(text); } catch { data = text; }
+        if (args.action === "search_class" && typeof data === "string") data = data.split("\n").filter(Boolean);
+        assert.equal(response.isError === true, expectError, text);
+        validate?.(data);
+        result.passed = true;
+        return data;
+    } catch (error) {
+        result.passed = false;
+        result.error = error.message;
+        throw error;
+    } finally {
+        result.elapsedMs = Date.now() - start;
+        results.push(result);
+        await appendFile(join(root, "results.jsonl"), JSON.stringify(result) + "\n");
+        console.log(`${result.passed ? "PASS" : "FAIL"} ${args.version ?? ""} ${name}.${args.action} (${result.elapsedMs}ms)${result.error ? `: ${result.error.slice(0, 220)}` : ""}`);
+    }
+}
+
+try {
+    await client.connect(transport);
+    await call("mc_versions", { action: "list_mc", type: "all" }, rows => {
+        for (const version of versions) assert.ok(rows.some(row => row.id === version), `Version list omits ${version}`);
+    }).catch(error => errors.push({ version: "catalog", error: error.message }));
+    for (const version of versions) {
+        try {
+            const classes = await call("mc_source", { action: "search_class", version, query: "Minecraft" }, rows => {
+                assert.ok(rows.some(name => /(?:^|\/)Minecraft$/.test(name)), "No named Minecraft class found");
+            });
+            const className = classes.find(name => /(?:^|\/)Minecraft$/.test(name));
+            await call("mc_source", { action: "get_source", version, className, maxLines: 20 }, text => {
+                assert.equal(typeof text, "string");
+                assert.match(text, /(?:package|import) net\.minecraft\./);
+            });
+            await call("mc_source", { action: "class_members", version, className }, data => {
+                assert.ok(data.methods.length > 5, "Missing class methods");
+                assert.ok(data.fields.length > 5, "Missing class fields");
+            });
+            await call("mc_source", { action: "bytecode", version, className }, text => {
+                assert.equal(typeof text, "string");
+                assert.match(text, /Minecraft/);
+                assert.match(text, /descriptor:/);
+            });
+            await call("mc_source", { action: "inheritance", version, className }, data => {
+                assert.equal(data.className, className);
+                assert.ok(data.superClass);
+            });
+            if (version === "1.5.2") {
+                for (const [className, method] of [
+                    ["net/minecraft/server/MinecraftServer", "tick"],
+                    ["net/minecraft/src/IntegratedServer", "tickIntegrated"],
+                ]) await call("mc_source", { action: "class_members", version, className }, data => {
+                    assert.ok(data.methods.some(entry => entry.name === method), `Lost explicit mapping for ${className}.${method}`);
+                });
+            }
+        } catch (error) {
+            errors.push({ version, error: error.message });
+        }
+    }
+    if (runMods) {
+        await call("mod", { action: "get" }, text => assert.match(text, /modId or dbId is required/), true);
+        const mods = [
+            { project: 73488, version: "1.6.4", loader: "forge", name: "Waila" },
+            { project: 73488, version: "1.7.10", loader: "forge", name: "Waila" },
+            { project: 238222, version: "1.8.9", loader: "forge", name: "JEI" },
+            { project: 238222, version: "1.12.2", loader: "forge", name: "JEI" },
+            { project: 238222, version: "1.16.5", loader: "forge", name: "JEI" },
+            { project: "AANobbMI", version: "1.16.5", loader: "fabric", name: "Sodium" },
+            { project: 238222, version: "1.20.1", loader: "forge", name: "JEI" },
+            { project: 238222, version: "1.21.1", loader: "neoforge", name: "JEI" },
+        ];
+        for (const mod of mods) {
+            try {
+                const infoArgs = { modId: mod.project, mcVersionFilter: mod.version, loader: mod.loader };
+                const before = await call("mod", { action: "stats" });
+                const info = await call("modpacks_ch", { action: "mod_info", ...infoArgs }, data => {
+                    assert.ok(data.versions.length, `No ${mod.name} versions for ${mod.version}/${mod.loader}`);
+                    assert.equal(data.versionLimit, 20);
+                    assert.ok(data.versions.length <= data.versionLimit);
+                    assert.ok(data.versions.every(version => version.loaders.includes(mod.loader)), "Accepted an unverified loader");
+                });
+                const compatibilityAlias = await call("modpacks_ch", { action: "ftb_mod_info", ...infoArgs });
+                assert.deepEqual(compatibilityAlias, info);
+                if (mod.name === "Waila" && mod.version === "1.7.10") {
+                    await call("platform", { action: "search", query: "Waila", mcVersion: mod.version, loader: "forge", limit: 5 }, data => {
+                        assert.ok(data.results.some(hit => String(hit.projectId) === String(mod.project)), "Loader-filtered search omitted Waila");
+                        assert.ok(data.results.every(hit => hit.loaders.includes("forge")), "Search returned an unverified loader");
+                    });
+                    await call("modpacks_ch", { action: "mod_info", ...infoArgs, loader: "fabric", limit: 1 }, data => {
+                        assert.deepEqual(data.versions, [], "Accepted a Forge-only release for Fabric");
+                    });
+                }
+                await call("mod", { action: "stats" }, data => assert.equal(data.total, before.total, "Metadata inspection ingested candidate files"));
+                const downloaded = await call("modpacks_ch", { action: "download_mod", ...infoArgs }, data => {
+                    assert.ok(data.modId > 0, "Download did not produce an ingested mod");
+                });
+                const dbId = downloaded.modId;
+                await call("mod", { action: "get", dbId }, data => {
+                    assert.equal(data.id, dbId, "Returned the wrong database record");
+                    assert.equal(data.loader, mod.loader);
+                    assert.ok(data.modId && data.modId !== "unknown");
+                    assert.ok(data.version && !data.version.includes("${"), "Unresolved version placeholder");
+                });
+                const files = await call("mod_jar", { action: "list_files", modId: dbId });
+                const englishPath = files.entries.find(path => /(?:^|\/)lang\/en_us\.(json|lang)$/i.test(path));
+                const languageFile = englishPath ? await call("mod_jar", { action: "get_file", modId: dbId, path: englishPath }) : undefined;
+                const emptyLanguage = languageFile && (languageFile.data
+                    ? Object.keys(languageFile.data).length === 0 : !languageFile.raw?.trim());
+                await call("mod_jar", { action: "lang", modId: dbId }, data => {
+                    if (emptyLanguage) assert.equal(data.total, 0, "Invented translations for an empty language file");
+                    else if (englishPath) assert.ok(data.total > 0, "Existing language file was not read");
+                    else assert.equal(data.found, false, "Reported language entries for a JAR without English translations");
+                });
+                await call("mod", { action: "reindex", dbId });
+                const query = mod.name === "JEI" ? "JustEnoughItems" : mod.name;
+                const classes = await call("mod_bytecode", { action: "search_class", dbId, query });
+                const className = classes.find(name => !name.includes("$"));
+                assert.ok(className, "No matching mod class found");
+                await call("mod_bytecode", { action: "class_members", dbId, className }, data => {
+                    assert.equal(data.className, className);
+                    assert.ok(data.methods.length, "No methods returned for mod class");
+                });
+                await call("mod_bytecode", { action: "bytecode", dbId, className }, text => assert.match(text, /descriptor:/));
+                await call("mod", { action: "decompile_class", dbId, className }, text => {
+                    assert.match(text, /package /);
+                    assert.ok(text.includes(className.split("/").at(-1)), "Decompiled the wrong class");
+                });
+            } catch (error) {
+                errors.push({ version: `${mod.name} ${mod.version}/${mod.loader}`, error: error.message });
+            }
+        }
+    }
+} finally {
+    await client.close();
+    await writeFile(join(root, "server.log"), serverLog);
+    await writeFile(join(root, "summary.json"), JSON.stringify({ versions, results, errors }, null, 2));
+}
+console.log(`${results.filter(row => row.passed).length}/${results.length} checks passed; ${errors.length} failing versions/catalogs. Evidence: ${root}`);
+if (errors.length) process.exitCode = 1;

package/scripts/test-package.mjs

@@ -30,9 +30,9 @@ Object.assign(env, {
     MODLENS_CACHE_ROOT: join(root, "modlens-cache"),
 });
 
-function start(args, home) {
+function start(args, home, extraEnv = {}) {
     const child = spawn(process.execPath, [npm, ...args], {
-        cwd: consumer, env: { ...env, MODLENS_HOME: home }, stdio: ["pipe", "pipe", "pipe"],
+        cwd: consumer, env: { ...env, MODLENS_HOME: home, ...extraEnv }, stdio: ["pipe", "pipe", "pipe"],
         detached: process.platform !== "win32",
     });
     let output = "";
@@ -109,14 +109,41 @@ try {
         .filter(dir => existsSync(join(dir, "package.json")));
     assert.equal(installs.length, 1);
     const installed = installs[0];
+    const initScript = execFileSync(process.execPath, [join(installed, "dist/launcher.js"), "--gradle-init-script"], { env, encoding: "utf8" }).trim();
+    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");
+    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" })), []);
     const require = createRequire(join(installed, "package.json"));
     const adapterRequire = createRequire(require.resolve("@prisma/adapter-better-sqlite3"));
     assert.equal(require.resolve("better-sqlite3"), adapterRequire.resolve("better-sqlite3"), "Prisma must share the v12 driver");
     assert.match(require("better-sqlite3/package.json").version, /^12\./);
 
     const dataHome = join(root, "server-home");
+    // Deterministic upstream responses still exercise the installed Markdown dependencies,
+    // MCP argument schema, error flag, database writes, and reads after restart.
+    const primerFetchFixture = join(root, "primer-fetch-fixture.mjs");
+    writeFileSync(primerFetchFixture, `
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = async (input, init) => {
+            const url = String(input);
+            if (url === 'https://docs.neoforged.net/package-primer-missing') return new Response('missing', { status: 404 });
+            if (url === 'https://docs.neoforged.net/package-primer') return new Response(
+                '<article><h1>Package migration guide</h1><pre class="language-java"><code>' +
+                '<div class="token-line"><span>update();</span><br></div><div class="token-line"><span>finish();</span><br></div></code></pre>' +
+                '<p>Detailed instructions for migration and keeping code examples readable.</p><h2>Final section</h2></article>',
+                { headers: { 'content-type': 'text/html' } });
+            if (url.includes('misode/mcmeta/summary/versions/data.json')) return Response.json([
+                { id: '1.21.1', data_version: 3955 }, { id: '1.21.5', data_version: 4325 }
+            ]);
+            if (url.endsWith('/api/tags')) return new Response(null, { status: 503 });
+            return originalFetch(input, init);
+        };
+    `);
     async function checkServer() {
-        const run = start(args, dataHome);
+        const run = start(args, dataHome, { NODE_OPTIONS: `--import=${pathToFileURL(primerFetchFixture).href}` });
         const pending = new Map();
         let buffer = "";
         let id = 0;
@@ -155,9 +182,79 @@ try {
             send({ method: "notifications/initialized" });
             const list = await request("tools/list", {});
             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" } });
             assert.ok(!stats.isError, JSON.stringify(stats));
             assert.equal(JSON.parse(stats.content.find(item => item.type === "text").text).total, 0);
+            const primerTool = list.tools.find(tool => tool.name === "primers");
+            assert.ok(primerTool.inputSchema.properties.refresh, "Packaged primer tool must expose cache refresh");
+            for (const field of ["includeContent", "maxChars", "cursor"]) {
+                assert.ok(primerTool.inputSchema.properties[field], `Packaged primer tool must expose ${field}`);
+            }
+            const decode = response => JSON.parse(response.content.find(item => item.type === "text").text);
+            const primerCall = arguments_ => request("tools/call", { name: "primers", arguments: arguments_ });
+            const saved = await primerCall({ action: "ingest", entries: [{
+                fromVersion: "1.21.1", toVersion: "1.21.5", title: "Package primer", url: "https://docs.neoforged.net/package-primer",
+            }] });
+            assert.ok(!saved.isError, JSON.stringify(saved));
+            const primerId = decode(saved).primers[0].id;
+            const page = await primerCall({ action: "get", id: primerId, maxLines: 3 });
+            assert.ok(!page.isError, JSON.stringify(page));
+            assert.equal(decode(page).contentStatus, "ready");
+            assert.match(decode(page).content, /# Package migration guide/);
+            assert.equal(decode(page).nextStartLine, 4);
+            const tail = decode(await primerCall({ action: "get", id: primerId, startLine: 4 }));
+            assert.match(tail.content, /update\(\);\nfinish\(\);/);
+            assert.match(tail.content, /## Final section/);
+            assert.equal(tail.nextStartLine, null);
+            const longContent = "# Long migration guide\n\n" + "x".repeat(2500) + "😀\nEnd.";
+            const added = decode(await primerCall({ action: "ingest", entries: [{
+                fromVersion: "1.21.5", toVersion: "26.1", title: "Long package primer",
+                url: "https://docs.neoforged.net/package-primer-long", content: longContent,
+            }] }));
+            const rangeArgs = { action: "by_version", fromVersion: "1.21.1", toVersion: "26.1", modloader: "neoforge" };
+            const metadata = decode(await primerCall(rangeArgs));
+            assert.equal(metadata.count, 2);
+            assert.ok(metadata.primers.every(primer => !("content" in primer)));
+            const chunks = new Map();
+            let cursor;
+            let pages = 0;
+            do {
+                const response = await primerCall({ ...rangeArgs, includeContent: true, maxChars: 1000, ...(cursor ? { cursor } : {}) });
+                assert.ok(!response.isError, JSON.stringify(response));
+                const bundle = decode(response);
+                assert.equal(bundle.count, 2);
+                assert.ok(bundle.contentChars <= 1000);
+                for (const primer of bundle.primers) chunks.set(primer.id, (chunks.get(primer.id) ?? "") + primer.content);
+                cursor = bundle.nextCursor;
+                assert.ok(++pages < 10);
+            } while (cursor);
+            assert.equal(chunks.get(added.primers[0].id), longContent);
+            assert.match(chunks.get(primerId), /update\(\);\nfinish\(\);/);
+            const cliRange = JSON.parse(execFileSync(process.execPath, [join(installed, "dist/cli.js"),
+                "primers", "by-version", "1.21.1", "26.1", "--modloader=neoforge", "--include-content", "--fetch-content=false"], {
+                env: { ...env, DATABASE_URL: `file:${join(dataHome, "data/modlens.db")}` }, encoding: "utf8", timeout: 30_000,
+            }));
+            assert.equal(cliRange.count, 2);
+            assert.equal(cliRange.nextCursor, null);
+            assert.equal(cliRange.primers.find(primer => primer.id === added.primers[0].id).content, longContent);
+            assert.equal((await primerCall({ ...rangeArgs, includeContent: true, cursor: "invalid" })).isError, true);
+            const failed = await primerCall({ action: "ingest", entries: [{
+                fromVersion: "1.21.1", toVersion: "1.21.5", title: "Missing primer",
+                url: "https://docs.neoforged.net/package-primer-missing", fetchContent: true,
+            }] });
+            assert.equal(failed.isError, true, "Requested content fetch failures must be MCP errors");
+            assert.equal(decode(failed).failed, 1);
+            const missing = decode(await primerCall({ action: "ingest", entries: [{
+                fromVersion: "1.21.1", toVersion: "1.21.5", title: "Missing bundled primer",
+                url: "https://docs.neoforged.net/package-primer-missing",
+            }] }));
+            const partial = await primerCall({ ...rangeArgs, includeContent: true });
+            assert.equal(partial.isError, true, "Bundle fetch failures must be MCP errors with successful content retained");
+            assert.equal(decode(partial).failed, 1);
+            assert.equal(decode(partial).primers.filter(primer => primer.contentStatus === "ready").length, 2);
+            await primerCall({ action: "delete", id: added.primers[0].id });
+            await primerCall({ action: "delete", id: missing.primers[0].id });
             return run.output();
         } finally { await stop(run); }
     }
@@ -166,7 +263,7 @@ try {
     assert.match(first, /First run/);
     const database = join(dataHome, "data/modlens.db");
     assert.ok(statSync(database).size > 0);
-    console.log("PASS: first-run SQLite bootstrap, MCP handshake, tools/list, database stats");
+    console.log("PASS: first-run SQLite bootstrap, MCP handshake, primer bundles/pagination/errors, CLI ranges, database stats");
 
     // Check the actual installed client/adapter with dates, BLOBs, and transactions.
     // Use a child so Windows releases the native .node file before cleanup.
@@ -204,6 +301,9 @@ try {
     console.log("PASS: second npx run preserves existing database contents");
     passed = true;
 } finally {
-    if (passed) rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 300 });
+    if (passed) {
+        assert.equal(dirname(resolve(root)), resolve(tmpdir()), "Cleanup must stay within the test temp directory");
+        rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 300 });
+    }
     else console.error(`Package test artifacts retained at ${root}`);
 }