@kzheart_/mc-pilot 0.1.0

package/dist/download/VersionMatrix.js

@@ -0,0 +1,227 @@
+import { loadModVariantCatalogSync } from "./ModVariantCatalog.js";
+const VERSION_MATRIX = [
+    {
+        minecraftVersion: "1.21.4",
+        javaVersion: "21+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 170 },
+            purpur: { supported: true, latestBuild: 2406 },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: true, loaderVersion: "0.16.10", modVersion: "0.1.0", validation: "verified" },
+            forge: { supported: false, notes: "不支持此版本" },
+            neoforge: { supported: true, loaderVersion: "21.4.x", modVersion: "0.1.0" }
+        }
+    },
+    {
+        minecraftVersion: "1.21.1",
+        javaVersion: "21+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 119 },
+            purpur: { supported: true, latestBuild: 2324 },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: true, loaderVersion: "0.16.10", modVersion: "0.1.0", validation: "verified" },
+            forge: { supported: false, notes: "不支持此版本" },
+            neoforge: { supported: true, loaderVersion: "21.1.x", modVersion: "0.1.0" }
+        }
+    },
+    {
+        minecraftVersion: "1.20.4",
+        javaVersion: "17+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 496 },
+            purpur: { supported: true, latestBuild: 2176 },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: true, loaderVersion: "0.16.10", modVersion: "0.1.0" },
+            forge: { supported: true, loaderVersion: "49.0.49", modVersion: "0.1.0" },
+            neoforge: { supported: false, notes: "不支持此版本" }
+        }
+    },
+    {
+        minecraftVersion: "1.20.3",
+        javaVersion: "17+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: false },
+            purpur: { supported: false },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: true, loaderVersion: "0.16.10", modVersion: "0.1.0", validation: "verified" },
+            forge: { supported: false, notes: "当前未接入此 loader" },
+            neoforge: { supported: false, notes: "不支持此版本" }
+        }
+    },
+    {
+        minecraftVersion: "1.20.2",
+        javaVersion: "17+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 318 },
+            purpur: { supported: true, latestBuild: 2095 },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: true, loaderVersion: "0.16.10", modVersion: "0.1.0" },
+            forge: { supported: false, notes: "当前未接入此 loader" },
+            neoforge: { supported: false, notes: "不支持此版本" }
+        }
+    },
+    {
+        minecraftVersion: "1.20.1",
+        javaVersion: "17+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 196 },
+            purpur: { supported: true, latestBuild: 2062 },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: true, loaderVersion: "0.16.10", modVersion: "0.1.0" },
+            forge: { supported: true, loaderVersion: "47.x", modVersion: "0.1.0" },
+            neoforge: { supported: false, notes: "不支持此版本" }
+        }
+    },
+    {
+        minecraftVersion: "1.18.2",
+        javaVersion: "17+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 388 },
+            purpur: { supported: false },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: true, loaderVersion: "0.16.10", modVersion: "0.1.0", validation: "verified" },
+            forge: { supported: true, loaderVersion: "40.x", modVersion: "0.1.0" },
+            neoforge: { supported: false, notes: "不支持此版本" }
+        }
+    },
+    {
+        minecraftVersion: "1.16.5",
+        javaVersion: "8+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 794 },
+            purpur: { supported: false },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: false, notes: "当前未接入此版本 mod" },
+            forge: { supported: true, loaderVersion: "36.x", modVersion: "0.1.0" },
+            neoforge: { supported: false, notes: "不支持此版本" }
+        }
+    },
+    {
+        minecraftVersion: "1.12.2",
+        javaVersion: "8+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 1620 },
+            purpur: { supported: false },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: false, notes: "不支持此版本" },
+            forge: { supported: true, loaderVersion: "14.23.x", modVersion: "0.1.0" },
+            neoforge: { supported: false, notes: "不支持此版本" }
+        }
+    }
+];
+function overlayClientSupport(entry, loader) {
+    const catalog = loadModVariantCatalogSync();
+    const variant = catalog.variants.find((candidate) => candidate.minecraftVersion === entry.minecraftVersion && candidate.loader === loader);
+    if (!variant) {
+        return { ...entry.clients[loader] };
+    }
+    return {
+        supported: variant.support === "ready" || variant.support === "configured",
+        loaderVersion: variant.fabricLoaderVersion ?? variant.forgeVersion ?? variant.neoforgeVersion,
+        modVersion: variant.modVersion,
+        validation: variant.validation,
+        notes: variant.notes
+    };
+}
+export function getVersionMatrix() {
+    return VERSION_MATRIX.map((entry) => ({
+        minecraftVersion: entry.minecraftVersion,
+        javaVersion: entry.javaVersion,
+        servers: { ...entry.servers },
+        clients: {
+            fabric: overlayClientSupport(entry, "fabric"),
+            forge: overlayClientSupport(entry, "forge"),
+            neoforge: overlayClientSupport(entry, "neoforge")
+        }
+    }));
+}
+export function getSupportedMinecraftVersions() {
+    return VERSION_MATRIX.map((entry) => entry.minecraftVersion);
+}
+export function getMinecraftSupport(version) {
+    return VERSION_MATRIX.find((entry) => entry.minecraftVersion === version);
+}
+export function searchServerVersions(filter) {
+    const types = filter?.type ? [filter.type] : getServerTypes();
+    const entries = filter?.version ? VERSION_MATRIX.filter((entry) => entry.minecraftVersion === filter.version) : VERSION_MATRIX;
+    return types.flatMap((type) => entries.map((entry) => ({
+        type,
+        minecraftVersion: entry.minecraftVersion,
+        supported: entry.servers[type].supported,
+        latestBuild: entry.servers[type].latestBuild,
+        requiresBuildTools: entry.servers[type].requiresBuildTools
+    })));
+}
+export function searchClientVersions(filter) {
+    const loaders = filter?.loader ? [filter.loader] : getClientLoaders();
+    const entries = filter?.version ? VERSION_MATRIX.filter((entry) => entry.minecraftVersion === filter.version) : VERSION_MATRIX;
+    return loaders.flatMap((loader) => entries.map((entry) => {
+        const support = overlayClientSupport(entry, loader);
+        return {
+            loader,
+            minecraftVersion: entry.minecraftVersion,
+            supported: support.supported,
+            ...(support.loaderVersion ? { loaderVersion: support.loaderVersion } : {}),
+            ...(support.modVersion ? { modVersion: support.modVersion } : {}),
+            ...(support.validation ? { validation: support.validation } : {}),
+            ...(support.notes ? { notes: support.notes } : {}),
+            javaVersion: entry.javaVersion
+        };
+    }));
+}
+export function getServerVersionMatrix() {
+    return searchServerVersions();
+}
+export function getClientVersionMatrix() {
+    return searchClientVersions();
+}
+export function getServerVersionCatalog() {
+    return getServerTypes().reduce((catalog, type) => {
+        catalog[type] = VERSION_MATRIX
+            .filter((entry) => entry.servers[type].supported)
+            .map((entry) => ({
+            version: entry.minecraftVersion,
+            build: entry.servers[type].latestBuild != null ? String(entry.servers[type].latestBuild) : undefined,
+            requiresBuildTools: entry.servers[type].requiresBuildTools
+        }));
+        return catalog;
+    }, {
+        vanilla: [],
+        paper: [],
+        purpur: [],
+        spigot: []
+    });
+}
+export function getServerTypes() {
+    return ["vanilla", "paper", "purpur", "spigot"];
+}
+export function getClientLoaders() {
+    return ["fabric", "forge", "neoforge"];
+}

package/dist/download/client/Arm64LwjglPatcher.d.ts

@@ -0,0 +1,5 @@
+export interface Arm64PatchDependencies {
+    fetchImpl?: typeof fetch;
+}
+export declare function needsArm64Patch(): boolean;
+export declare function applyArm64LwjglPatch(runtimeRoot: string, versionId: string, dependencies?: Arm64PatchDependencies): Promise<string | null>;

package/dist/download/client/Arm64LwjglPatcher.js

@@ -0,0 +1,153 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { MinecraftFolder } from "@xmcl/core";
+const LWJGL_ARM64_PATCH = {
+    patchVersion: "3.3.1",
+    jars: {
+        "org.lwjgl:lwjgl": { path: "org/lwjgl/lwjgl/3.3.1/lwjgl-3.3.1.jar", url: "https://repo1.maven.org/maven2/org/lwjgl/lwjgl/3.3.1/lwjgl-3.3.1.jar", sha1: "ae58664f88e18a9bb2c77b063833ca7aaec484cb", size: 0 },
+        "org.lwjgl:lwjgl-jemalloc": { path: "org/lwjgl/lwjgl-jemalloc/3.3.1/lwjgl-jemalloc-3.3.1.jar", url: "https://repo1.maven.org/maven2/org/lwjgl/lwjgl-jemalloc/3.3.1/lwjgl-jemalloc-3.3.1.jar", sha1: "a817bcf213db49f710603677457567c37d53e103", size: 0 },
+        "org.lwjgl:lwjgl-openal": { path: "org/lwjgl/lwjgl-openal/3.3.1/lwjgl-openal-3.3.1.jar", url: "https://repo1.maven.org/maven2/org/lwjgl/lwjgl-openal/3.3.1/lwjgl-openal-3.3.1.jar", sha1: "2623a6b8ae1dfcd880738656a9f0243d2e6840bd", size: 0 },
+        "org.lwjgl:lwjgl-opengl": { path: "org/lwjgl/lwjgl-opengl/3.3.1/lwjgl-opengl-3.3.1.jar", url: "https://repo1.maven.org/maven2/org/lwjgl/lwjgl-opengl/3.3.1/lwjgl-opengl-3.3.1.jar", sha1: "831a5533a21a5f4f81bbc51bb13e9899319b5411", size: 0 },
+        "org.lwjgl:lwjgl-stb": { path: "org/lwjgl/lwjgl-stb/3.3.1/lwjgl-stb-3.3.1.jar", url: "https://repo1.maven.org/maven2/org/lwjgl/lwjgl-stb/3.3.1/lwjgl-stb-3.3.1.jar", sha1: "b119297cf8ed01f247abe8685857f8e7fcf5980f", size: 0 },
+        "org.lwjgl:lwjgl-tinyfd": { path: "org/lwjgl/lwjgl-tinyfd/3.3.1/lwjgl-tinyfd-3.3.1.jar", url: "https://repo1.maven.org/maven2/org/lwjgl/lwjgl-tinyfd/3.3.1/lwjgl-tinyfd-3.3.1.jar", sha1: "0ff1914111ef2e3e0110ef2dabc8d8cdaad82347", size: 0 },
+        "org.lwjgl:lwjgl-glfw": { path: "org/glavo/hmcl/mmachina/lwjgl-glfw/3.3.1-mmachina.1/lwjgl-glfw-3.3.1-mmachina.1.jar", url: "https://repo1.maven.org/maven2/org/glavo/hmcl/mmachina/lwjgl-glfw/3.3.1-mmachina.1/lwjgl-glfw-3.3.1-mmachina.1.jar", sha1: "e9a101bca4fa30d26b21b526ff28e7c2d8927f1b", size: 0 }
+    },
+    natives: {
+        "org.lwjgl:lwjgl": { path: "org/lwjgl/lwjgl/3.3.1/lwjgl-3.3.1-natives-macos-arm64.jar", url: "https://libraries.minecraft.net/org/lwjgl/lwjgl/3.3.1/lwjgl-3.3.1-natives-macos-arm64.jar", sha1: "71d0d5e469c9c95351eb949064497e3391616ac9", size: 0 },
+        "org.lwjgl:lwjgl-jemalloc": { path: "org/lwjgl/lwjgl-jemalloc/3.3.1/lwjgl-jemalloc-3.3.1-natives-macos-arm64.jar", url: "https://libraries.minecraft.net/org/lwjgl/lwjgl-jemalloc/3.3.1/lwjgl-jemalloc-3.3.1-natives-macos-arm64.jar", sha1: "e577b87d8ad2ade361aaea2fcf226c660b15dee8", size: 0 },
+        "org.lwjgl:lwjgl-openal": { path: "org/lwjgl/lwjgl-openal/3.3.1/lwjgl-openal-3.3.1-natives-macos-arm64.jar", url: "https://libraries.minecraft.net/org/lwjgl/lwjgl-openal/3.3.1/lwjgl-openal-3.3.1-natives-macos-arm64.jar", sha1: "23d55e7490b57495320f6c9e1936d78fd72c4ef8", size: 0 },
+        "org.lwjgl:lwjgl-opengl": { path: "org/lwjgl/lwjgl-opengl/3.3.1/lwjgl-opengl-3.3.1-natives-macos-arm64.jar", url: "https://libraries.minecraft.net/org/lwjgl/lwjgl-opengl/3.3.1/lwjgl-opengl-3.3.1-natives-macos-arm64.jar", sha1: "eafe34b871d966292e8db0f1f3d6b8b110d4e91d", size: 0 },
+        "org.lwjgl:lwjgl-stb": { path: "org/lwjgl/lwjgl-stb/3.3.1/lwjgl-stb-3.3.1-natives-macos-arm64.jar", url: "https://libraries.minecraft.net/org/lwjgl/lwjgl-stb/3.3.1/lwjgl-stb-3.3.1-natives-macos-arm64.jar", sha1: "fcf073ed911752abdca5f0b00a53cfdf17ff8e8b", size: 0 },
+        "org.lwjgl:lwjgl-tinyfd": { path: "org/lwjgl/lwjgl-tinyfd/3.3.1/lwjgl-tinyfd-3.3.1-natives-macos-arm64.jar", url: "https://libraries.minecraft.net/org/lwjgl/lwjgl-tinyfd/3.3.1/lwjgl-tinyfd-3.3.1-natives-macos-arm64.jar", sha1: "972ecc17bad3571e81162153077b4d47b7b9eaa9", size: 0 },
+        "org.lwjgl:lwjgl-glfw": { path: "org/lwjgl/lwjgl-glfw/3.3.1/lwjgl-glfw-3.3.1-natives-macos-arm64.jar", url: "https://libraries.minecraft.net/org/lwjgl/lwjgl-glfw/3.3.1/lwjgl-glfw-3.3.1-natives-macos-arm64.jar", sha1: "cac0d3f712a3da7641fa174735a5f315de7ffe0a", size: 0 }
+    }
+};
+export function needsArm64Patch() {
+    return os.arch() === "arm64" && os.platform() === "darwin";
+}
+async function downloadJar(entry, minecraft, fetchImpl) {
+    const localPath = minecraft.getLibraryByPath(entry.path);
+    try {
+        await access(localPath);
+        return localPath;
+    }
+    catch {
+        console.error(`[MCT]   Downloading ${path.basename(entry.path)}...`);
+        const response = await fetchImpl(entry.url);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${entry.url}`);
+        }
+        await mkdir(path.dirname(localPath), { recursive: true });
+        await writeFile(localPath, Buffer.from(await response.arrayBuffer()));
+        return localPath;
+    }
+}
+export async function applyArm64LwjglPatch(runtimeRoot, versionId, dependencies = {}) {
+    if (!needsArm64Patch()) {
+        return null;
+    }
+    const fetchImpl = dependencies.fetchImpl ?? fetch;
+    const minecraft = MinecraftFolder.from(runtimeRoot);
+    const nativesDir = minecraft.getNativesRoot(versionId);
+    // Walk version JSON chain to detect old LWJGL 3.2.x
+    let targetJsonPath = minecraft.getVersionJson(versionId);
+    let needsJsonPatch = false;
+    for (let depth = 0; depth < 5; depth++) {
+        const raw = await readFile(targetJsonPath, "utf-8").catch(() => null);
+        if (!raw) {
+            break;
+        }
+        const json = JSON.parse(raw);
+        if ((json.libraries || []).some((lib) => lib.name?.startsWith("org.lwjgl:lwjgl:3.2"))) {
+            needsJsonPatch = true;
+            break;
+        }
+        if ((json.libraries || []).some((lib) => lib.name?.startsWith("org.lwjgl:lwjgl:3.3"))) {
+            break;
+        }
+        if (!json.inheritsFrom) {
+            break;
+        }
+        targetJsonPath = minecraft.getVersionJson(json.inheritsFrom);
+    }
+    if (!needsJsonPatch) {
+        return null;
+    }
+    console.error("[MCT] Applying LWJGL 3.3.1 arm64 patch (based on HMCL NativePatcher)...");
+    const { open, walkEntriesGenerator, openEntryReadStream } = await import("@xmcl/unzip");
+    const { createWriteStream } = await import("node:fs");
+    const { pipeline } = await import("node:stream");
+    const { promisify } = await import("node:util");
+    const pipelineAsync = promisify(pipeline);
+    // 1. Download and extract arm64 natives
+    await mkdir(nativesDir, { recursive: true });
+    for (const [libKey, entry] of Object.entries(LWJGL_ARM64_PATCH.natives)) {
+        const localJar = await downloadJar(entry, minecraft, fetchImpl).catch((e) => { console.error(`[MCT]   Skip ${libKey}: ${e.message}`); return null; });
+        if (!localJar) {
+            continue;
+        }
+        const zip = await open(localJar, { lazyEntries: true, autoClose: false });
+        for await (const zipEntry of walkEntriesGenerator(zip)) {
+            const name = zipEntry.fileName;
+            if (!name.endsWith(".dylib") || name.endsWith("/")) {
+                continue;
+            }
+            const dest = path.join(nativesDir, path.basename(name));
+            await pipelineAsync(await openEntryReadStream(zip, zipEntry), createWriteStream(dest));
+        }
+    }
+    // 2. Download Java JARs
+    for (const [libKey, entry] of Object.entries(LWJGL_ARM64_PATCH.jars)) {
+        await downloadJar(entry, minecraft, fetchImpl).catch((e) => console.error(`[MCT]   Skip ${libKey}: ${e.message}`));
+    }
+    // 3. Patch vanilla version JSON to swap LWJGL 3.2.x -> 3.3.1
+    let curJsonPath = minecraft.getVersionJson(versionId);
+    for (let depth = 0; depth < 5; depth++) {
+        const raw = await readFile(curJsonPath, "utf-8").catch(() => null);
+        if (!raw) {
+            break;
+        }
+        const json = JSON.parse(raw);
+        const hasOldLwjgl = (json.libraries || []).some((lib) => lib.name?.startsWith("org.lwjgl:lwjgl:3.2"));
+        if (hasOldLwjgl) {
+            const newLibraries = [];
+            for (const lib of json.libraries) {
+                const name = lib.name || "";
+                const parts = name.split(":");
+                const baseKey = parts.slice(0, 2).join(":");
+                if (!(baseKey in LWJGL_ARM64_PATCH.jars) && !(baseKey in LWJGL_ARM64_PATCH.natives)) {
+                    newLibraries.push(lib);
+                    continue;
+                }
+                const newLib = { ...lib };
+                if ((baseKey in LWJGL_ARM64_PATCH.jars) && lib.downloads?.artifact) {
+                    const jarEntry = LWJGL_ARM64_PATCH.jars[baseKey];
+                    const newName = baseKey === "org.lwjgl:lwjgl-glfw"
+                        ? "org.glavo.hmcl.mmachina:lwjgl-glfw:3.3.1-mmachina.1"
+                        : `${baseKey}:3.3.1`;
+                    newLib.name = newName;
+                    newLib.downloads = { ...lib.downloads, artifact: { path: jarEntry.path, sha1: jarEntry.sha1, size: jarEntry.size, url: jarEntry.url } };
+                }
+                if ((baseKey in LWJGL_ARM64_PATCH.natives) && lib.downloads?.classifiers?.["natives-macos"]) {
+                    const nativeEntry = LWJGL_ARM64_PATCH.natives[baseKey];
+                    newLib.downloads = {
+                        ...newLib.downloads,
+                        classifiers: { "natives-macos": { path: nativeEntry.path, sha1: nativeEntry.sha1, size: nativeEntry.size, url: nativeEntry.url } }
+                    };
+                }
+                newLibraries.push(newLib);
+            }
+            json.libraries = newLibraries;
+            await writeFile(curJsonPath, JSON.stringify(json, null, 2), "utf-8");
+            break;
+        }
+        if (!json.inheritsFrom) {
+            break;
+        }
+        curJsonPath = minecraft.getVersionJson(json.inheritsFrom);
+    }
+    await writeFile(path.join(nativesDir, ".arm64-patched"), "3.3.1");
+    console.error("[MCT] arm64 LWJGL 3.3.1 patch applied");
+    return nativesDir;
+}

package/dist/download/client/ClientDownloader.d.ts

@@ -0,0 +1,42 @@
+import type { CommandContext } from "../../util/context.js";
+import { CacheManager } from "../CacheManager.js";
+import { detectJava } from "../JavaDetector.js";
+import type { LoaderType } from "../types.js";
+import { prepareManagedFabricRuntime } from "./FabricRuntimeDownloader.js";
+export interface DownloadClientOptions {
+    loader?: LoaderType;
+    version?: string;
+    dir?: string;
+    name?: string;
+    wsPort?: number;
+    server?: string;
+    instanceDir?: string;
+    metaDir?: string;
+    librariesDir?: string;
+    assetsDir?: string;
+    nativesDir?: string;
+    java?: string;
+}
+export interface DownloadClientDependencies {
+    cacheManager?: CacheManager;
+    detectJavaImpl?: typeof detectJava;
+    fetchImpl?: typeof fetch;
+    prepareManagedRuntimeImpl?: typeof prepareManagedFabricRuntime;
+}
+export declare function downloadClientMod(context: CommandContext, options: DownloadClientOptions, dependencies?: DownloadClientDependencies): Promise<{
+    downloaded: boolean;
+    variantId: string;
+    minecraftVersion: string;
+    loader: LoaderType;
+    javaCommand: string;
+    javaVersion: number | undefined;
+    clientRootDir: string;
+    minecraftDir: string;
+    modsDir: string;
+    jar: string;
+    cachePath: string;
+    clientName: string;
+    launchCommandConfigured: boolean;
+    runtimeRootDir: string | undefined;
+    runtimeVersionId: string | undefined;
+}>;

package/dist/download/client/ClientDownloader.js

@@ -0,0 +1,233 @@
+import { access, mkdir } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { DEFAULT_WS_PORT_BASE, loadConfig, writeConfig } from "../../util/config.js";
+import { MctError } from "../../util/errors.js";
+import { CacheManager } from "../CacheManager.js";
+import { copyFileIfMissing, downloadFile } from "../DownloadUtils.js";
+import { detectJava } from "../JavaDetector.js";
+import { findVariantByVersionAndLoader, getDefaultVariant, getModArtifactFileName, loadModVariantCatalog } from "../ModVariantCatalog.js";
+import { prepareManagedFabricRuntime } from "./FabricRuntimeDownloader.js";
+const GITHUB_RELEASE_BASE_URL = process.env.MCT_MOD_DOWNLOAD_BASE_URL || "https://github.com/kzheart/mc-pilot/releases/download";
+function ensureSupportedVariant(variant) {
+    if (variant.loader !== "fabric") {
+        throw new MctError({
+            code: "UNSUPPORTED_LOADER",
+            message: `Loader ${variant.loader} is not implemented yet`
+        }, 4);
+    }
+    if (!variant.fabricLoaderVersion || !variant.yarnMappings) {
+        throw new MctError({
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} is not buildable yet`,
+            details: {
+                support: variant.support,
+                validation: variant.validation
+            }
+        }, 4);
+    }
+}
+async function resolveArtifact(context, variant, cacheManager, fetchImpl = fetch) {
+    const artifactFileName = getModArtifactFileName(variant);
+    const gradleModule = variant.gradleModule ?? `version-${variant.minecraftVersion}`;
+    const buildArtifactPath = path.join(context.cwd, "client-mod", gradleModule, "build", "libs", artifactFileName);
+    const cacheArtifactPath = cacheManager.getModFile(artifactFileName);
+    // 1. Check local build artifact
+    try {
+        await access(buildArtifactPath);
+        await copyFileIfMissing(buildArtifactPath, cacheArtifactPath);
+        return { sourcePath: buildArtifactPath, cachePath: cacheArtifactPath, artifactFileName, source: "local-build" };
+    }
+    catch { }
+    // 2. Check cache
+    try {
+        await access(cacheArtifactPath);
+        return { sourcePath: cacheArtifactPath, cachePath: cacheArtifactPath, artifactFileName, source: "cache" };
+    }
+    catch { }
+    // 3. Download from GitHub Releases
+    const modVersion = variant.modVersion ?? "0.1.0";
+    const releaseTag = `v${modVersion}`;
+    const downloadUrl = `${GITHUB_RELEASE_BASE_URL}/${releaseTag}/${artifactFileName}`;
+    try {
+        await downloadFile(downloadUrl, cacheArtifactPath, fetchImpl);
+        return { sourcePath: cacheArtifactPath, cachePath: cacheArtifactPath, artifactFileName, source: "github-release" };
+    }
+    catch (error) {
+        throw new MctError({
+            code: "ARTIFACT_NOT_FOUND",
+            message: `Could not find mod artifact for ${variant.id}. Tried local build, cache, and GitHub Releases.`,
+            details: {
+                localBuild: buildArtifactPath,
+                cache: cacheArtifactPath,
+                downloadUrl,
+                downloadError: error instanceof Error ? error.message : String(error)
+            }
+        }, 4);
+    }
+}
+function resolveLaunchRuntimePaths(context, options) {
+    const runtimePaths = {
+        instanceDir: options.instanceDir,
+        metaDir: options.metaDir,
+        librariesDir: options.librariesDir,
+        assetsDir: options.assetsDir,
+        nativesDir: options.nativesDir
+    };
+    const requiredEntries = Object.entries({
+        instanceDir: runtimePaths.instanceDir,
+        metaDir: runtimePaths.metaDir,
+        librariesDir: runtimePaths.librariesDir,
+        assetsDir: runtimePaths.assetsDir
+    });
+    const providedRequired = requiredEntries.filter(([, value]) => Boolean(value));
+    if (providedRequired.length === 0) {
+        return undefined;
+    }
+    const missing = requiredEntries
+        .filter(([, value]) => !value)
+        .map(([key]) => key);
+    if (missing.length > 0) {
+        throw new MctError({
+            code: "INVALID_PARAMS",
+            message: "Client runtime directories must be configured together",
+            details: {
+                missing
+            }
+        }, 4);
+    }
+    return {
+        instanceDir: path.resolve(context.cwd, runtimePaths.instanceDir),
+        metaDir: path.resolve(context.cwd, runtimePaths.metaDir),
+        librariesDir: path.resolve(context.cwd, runtimePaths.librariesDir),
+        assetsDir: path.resolve(context.cwd, runtimePaths.assetsDir),
+        ...(runtimePaths.nativesDir
+            ? {
+                nativesDir: path.resolve(context.cwd, runtimePaths.nativesDir)
+            }
+            : {})
+    };
+}
+function buildLaunchCommand(context, runtimePaths, variant) {
+    return [
+        process.execPath,
+        path.join(context.cwd, "scripts", "launch-fabric-client.mjs"),
+        "--instance-dir",
+        runtimePaths.instanceDir,
+        "--meta-dir",
+        runtimePaths.metaDir,
+        "--libraries-dir",
+        runtimePaths.librariesDir,
+        "--assets-dir",
+        runtimePaths.assetsDir,
+        ...(runtimePaths.nativesDir ? ["--natives-dir", runtimePaths.nativesDir] : []),
+        "--minecraft-version",
+        variant.minecraftVersion,
+        "--fabric-loader-version",
+        variant.fabricLoaderVersion ?? "0.16.10"
+    ];
+}
+function buildManagedLaunchCommand(context, runtimeRootDir, versionId, gameDir) {
+    return [
+        process.execPath,
+        path.join(context.cwd, "scripts", "launch-fabric-client.mjs"),
+        "--runtime-root",
+        runtimeRootDir,
+        "--version-id",
+        versionId,
+        "--game-dir",
+        gameDir
+    ];
+}
+async function ensureJavaReady(variant, detectJavaImpl, command) {
+    const result = await detectJavaImpl(command ?? "java");
+    const requiredVersion = variant.javaVersion ?? 17;
+    if (!result.available) {
+        throw new MctError({
+            code: "JAVA_NOT_FOUND",
+            message: `Java ${requiredVersion}+ is required for ${variant.id}`,
+            details: {
+                command: result.command
+            }
+        }, 4);
+    }
+    if ((result.majorVersion ?? 0) < requiredVersion) {
+        throw new MctError({
+            code: "JAVA_VERSION_TOO_LOW",
+            message: `Java ${requiredVersion}+ is required for ${variant.id}`,
+            details: {
+                detected: result.majorVersion,
+                command: result.command
+            }
+        }, 4);
+    }
+    return result;
+}
+export async function downloadClientMod(context, options, dependencies = {}) {
+    const loader = options.loader ?? "fabric";
+    const cacheManager = dependencies.cacheManager ?? new CacheManager();
+    const detectJavaImpl = dependencies.detectJavaImpl ?? detectJava;
+    const fetchImpl = dependencies.fetchImpl ?? fetch;
+    const prepareManagedRuntimeImpl = dependencies.prepareManagedRuntimeImpl ?? prepareManagedFabricRuntime;
+    const catalog = await loadModVariantCatalog();
+    const variant = options.version
+        ? findVariantByVersionAndLoader(catalog, options.version, loader)
+        : getDefaultVariant(catalog);
+    if (!variant) {
+        throw new MctError({
+            code: "VARIANT_NOT_FOUND",
+            message: `No mod variant found for ${options.version ?? "default"} / ${loader}`
+        }, 4);
+    }
+    ensureSupportedVariant(variant);
+    const java = await ensureJavaReady(variant, detectJavaImpl, options.java);
+    const artifact = await resolveArtifact(context, variant, cacheManager, fetchImpl);
+    const clientRootDir = path.resolve(context.cwd, options.dir ?? "./client");
+    const minecraftDir = path.join(clientRootDir, "minecraft");
+    const modsDir = path.join(minecraftDir, "mods");
+    await mkdir(minecraftDir, { recursive: true });
+    await mkdir(modsDir, { recursive: true });
+    const targetJarPath = path.join(modsDir, artifact.artifactFileName);
+    await copyFileIfMissing(artifact.sourcePath, targetJarPath);
+    const clientName = options.name ?? "default";
+    const latestConfig = await loadConfig(context.configPath, context.cwd);
+    const configuredClient = latestConfig.clients[clientName] ?? {};
+    const runtimePaths = resolveLaunchRuntimePaths(context, options);
+    const managedRuntime = runtimePaths
+        ? undefined
+        : await prepareManagedRuntimeImpl(variant, clientRootDir, { fetchImpl });
+    const generatedLaunchCommand = runtimePaths
+        ? buildLaunchCommand(context, runtimePaths, variant)
+        : buildManagedLaunchCommand(context, managedRuntime.runtimeRootDir, managedRuntime.versionId, managedRuntime.gameDir);
+    latestConfig.clients[clientName] = {
+        ...configuredClient,
+        version: variant.minecraftVersion,
+        wsPort: options.wsPort ?? configuredClient.wsPort ?? DEFAULT_WS_PORT_BASE,
+        server: options.server ?? configuredClient.server ?? "localhost:25565",
+        workingDir: path.relative(context.cwd, minecraftDir) || ".",
+        env: {
+            ...configuredClient.env,
+            MCT_CLIENT_MOD_VARIANT: variant.id,
+            MCT_CLIENT_MOD_JAR: path.relative(context.cwd, targetJarPath)
+        },
+        ...(generatedLaunchCommand ? { launchCommand: generatedLaunchCommand } : {})
+    };
+    await writeConfig(context.configPath, context.cwd, latestConfig);
+    return {
+        downloaded: true,
+        variantId: variant.id,
+        minecraftVersion: variant.minecraftVersion,
+        loader: variant.loader,
+        javaCommand: java.command,
+        javaVersion: java.majorVersion,
+        clientRootDir,
+        minecraftDir,
+        modsDir,
+        jar: targetJarPath,
+        cachePath: artifact.cachePath,
+        clientName,
+        launchCommandConfigured: Boolean(generatedLaunchCommand),
+        runtimeRootDir: managedRuntime?.runtimeRootDir,
+        runtimeVersionId: managedRuntime?.versionId
+    };
+}

package/dist/download/client/FabricRuntimeDownloader.d.ts

@@ -0,0 +1,10 @@
+import type { ModVariant } from "../types.js";
+export interface PrepareFabricRuntimeDependencies {
+    fetchImpl?: typeof fetch;
+}
+export interface PreparedFabricRuntime {
+    runtimeRootDir: string;
+    gameDir: string;
+    versionId: string;
+}
+export declare function prepareManagedFabricRuntime(variant: ModVariant, clientRootDir: string, dependencies?: PrepareFabricRuntimeDependencies): Promise<PreparedFabricRuntime>;