@creeperhost/modlens-mcp 1.6.17 → 1.6.19

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

@@ -0,0 +1,217 @@
+// Exercise the packed CLI as an npx consumer, outside the source checkout.
+// Run after `npm run build`, or pass a tarball / release-artifact directory.
+import assert from "node:assert/strict";
+import { spawn, execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, delimiter } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const root = mkdtempSync(join(tmpdir(), "modlens-package-test-"));
+const consumer = join(root, "consumer");
+mkdirSync(consumer);
+writeFileSync(join(consumer, "package.json"), JSON.stringify({ name: "package-smoke-consumer", private: true }));
+writeFileSync(join(root, "npmrc"), "");
+const npm = process.env.npm_execpath ?? (process.platform === "win32"
+    ? join(dirname(process.execPath), "node_modules/npm/bin/npm-cli.js")
+    : realpathSync(join(dirname(process.execPath), "npm")));
+assert.ok(existsSync(npm), "Run this test via npm run test:package");
+const env = Object.fromEntries(Object.entries(process.env).filter(([key]) =>
+    !/^(DATABASE_URL|MODLENS_.*|MCP_PORT|DEBUG|NODE_OPTIONS|NODE_PATH|PATH)$/i.test(key)));
+Object.assign(env, {
+    PATH: `${dirname(process.execPath)}${delimiter}${process.env.PATH ?? process.env.Path ?? ""}`,
+    npm_config_cache: join(root, "cache"),
+    npm_config_userconfig: join(root, "npmrc"),
+    npm_config_update_notifier: "false",
+    npm_config_audit: "false",
+    npm_config_fund: "false",
+    MODLENS_AUTO_EMBED: "0",
+    MODLENS_CACHE_ROOT: join(root, "modlens-cache"),
+});
+
+function start(args, home) {
+    const child = spawn(process.execPath, [npm, ...args], {
+        cwd: consumer, env: { ...env, MODLENS_HOME: home }, stdio: ["pipe", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+    });
+    let output = "";
+    child.stdout.on("data", data => { output += data; });
+    child.stderr.on("data", data => { output += data; });
+    const done = new Promise((resolveDone, reject) => {
+        child.on("error", reject);
+        child.on("close", (code, signal) => resolveDone({ code, signal }));
+    });
+    return { child, done, output: () => output };
+}
+
+async function stop(run) {
+    if (run.child.exitCode !== null || run.child.signalCode !== null) return;
+    if (process.platform === "win32") {
+        // Only terminate the process tree created by this test.
+        try { execFileSync("taskkill.exe", ["/pid", String(run.child.pid), "/T", "/F"], { stdio: "ignore" }); } catch {}
+    } else {
+        try { process.kill(-run.child.pid, "SIGTERM"); } catch (error) {
+            if (error.code !== "ESRCH") throw error;
+        }
+    }
+    await deadline(run.done, 10_000, "test process shutdown");
+}
+
+async function deadline(promise, ms, label) {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Timed out: ${label}`)), ms);
+        })]);
+    } finally { clearTimeout(timer); }
+}
+
+let passed = false;
+try {
+    let tarball;
+    if (process.argv[2]) {
+        tarball = resolve(process.argv[2]);
+        if (statSync(tarball).isDirectory()) {
+            const files = readdirSync(tarball).filter(file => file.endsWith(".tgz"));
+            assert.equal(files.length, 1, "Expected one package tarball");
+            tarball = join(tarball, files[0]);
+        }
+    } else {
+        const pack = JSON.parse(execFileSync(process.execPath, [npm, "pack", "--json", "--pack-destination", root], {
+            env, encoding: "utf8", timeout: 60_000,
+        }));
+        tarball = join(root, pack[0].filename);
+    }
+    console.log(`Testing ${tarball} on ${process.version} (${process.platform}/${process.arch})`);
+    const args = ["exec", "--yes", "--foreground-scripts", "--package", tarball, "--", "modlens-mcp"];
+
+    const setup = start([...args, "--setup"], join(root, "setup-home"));
+    try {
+        await deadline(new Promise((resolvePrompt, reject) => {
+            const inspect = () => {
+                if (setup.output().includes("Choose a setup profile")) resolvePrompt();
+            };
+            setup.child.stdout.on("data", inspect);
+            setup.child.stderr.on("data", inspect);
+            setup.done.then(result => reject(new Error(`Setup exited before prompting: ${JSON.stringify(result)}\n${setup.output()}`)), reject);
+        }), 180_000, "fresh npx install and setup prompt");
+        setup.child.stdin.write("\x03"); // Cancel the wizard before saving configuration.
+        assert.equal((await deadline(setup.done, 15_000, "setup cancellation")).code, 0, setup.output());
+        console.log("PASS: fresh npx install and interactive setup prompt");
+    } catch (error) {
+        writeFileSync(join(root, "setup.log"), setup.output());
+        throw error;
+    } finally { await stop(setup); }
+
+    const installs = readdirSync(join(root, "cache/_npx"))
+        .map(dir => join(root, "cache/_npx", dir, "node_modules/@creeperhost/modlens-mcp"))
+        .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");
+    async function checkServer() {
+        const run = start(args, dataHome);
+        const pending = new Map();
+        let buffer = "";
+        let id = 0;
+        run.child.stdout.on("data", data => {
+            buffer += data;
+            while (buffer.includes("\n")) {
+                const newline = buffer.indexOf("\n");
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (!line) continue;
+                try {
+                    const message = JSON.parse(line);
+                    const waiter = pending.get(message.id);
+                    if (waiter) {
+                        pending.delete(message.id);
+                        if (message.error) waiter.reject(new Error(JSON.stringify(message.error)));
+                        else waiter.resolve(message.result);
+                    }
+                } catch (error) { for (const waiter of pending.values()) waiter.reject(error); }
+            }
+        });
+        run.done.then(result => {
+            for (const waiter of pending.values()) waiter.reject(new Error(`MCP exited: ${JSON.stringify(result)}\n${run.output()}`));
+        });
+        function send(message) { run.child.stdin.write(JSON.stringify({ jsonrpc: "2.0", ...message }) + "\n"); }
+        function request(method, params) {
+            return deadline(new Promise((resolveRequest, reject) => {
+                const requestId = ++id;
+                pending.set(requestId, { resolve: resolveRequest, reject });
+                send({ id: requestId, method, params });
+            }), 30_000, method);
+        }
+        try {
+            const initialized = await request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "package-smoke", version: "1.0.0" } });
+            assert.ok(initialized.serverInfo);
+            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);
+            return run.output();
+        } finally { await stop(run); }
+    }
+
+    const first = await checkServer();
+    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");
+
+    // Check the actual installed client/adapter with dates, BLOBs, and transactions.
+    // Use a child so Windows releases the native .node file before cleanup.
+    function checkDatabase(mode) {
+        execFileSync(process.execPath, ["--input-type=module", "-e", `
+            import assert from 'node:assert/strict';
+            const { getDb, disconnect } = await import(process.argv[1]);
+            const db = await getDb();
+            try {
+                const bytes = new Uint8Array([0, 1, 127, 128, 255]);
+                if (process.argv[2] === 'create') {
+                    const doc = await db.docEntry.create({ data: { title: 'Package smoke', url: 'https://example.invalid', embedding: bytes } });
+                    assert.deepEqual(doc.embedding, bytes);
+                    assert.ok(doc.createdAt instanceof Date);
+                    await db.$transaction(async tx => { await tx.docEntry.update({ where: { id: doc.id }, data: { summary: 'committed' } }); });
+                    await assert.rejects(db.$transaction(async tx => {
+                        await tx.docEntry.update({ where: { id: doc.id }, data: { summary: 'rolled back' } });
+                        throw new Error('rollback sentinel');
+                    }), /rollback sentinel/);
+                }
+                const saved = await db.docEntry.findFirstOrThrow({ where: { title: 'Package smoke' } });
+                assert.equal(saved.summary, 'committed');
+                assert.deepEqual(saved.embedding, bytes);
+            } finally { await disconnect(); }
+        `, pathToFileURL(join(installed, "dist/db.js")).href, mode], {
+            cwd: consumer, env: { ...env, DATABASE_URL: `file:${database}` }, timeout: 30_000, stdio: "pipe",
+        });
+    }
+    checkDatabase("create");
+    console.log("PASS: installed Prisma client/adapter CRUD, binary data, dates, commit and rollback");
+
+    const second = await checkServer();
+    assert.doesNotMatch(second, /First run/);
+    checkDatabase("read");
+    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 });
+    else console.error(`Package test artifacts retained at ${root}`);
+}