@loontail/minecraft-kit 0.2.0

package/dist/cli/index.js

@@ -0,0 +1,5010 @@
+#!/usr/bin/env node
+import process2 from 'process';
+import os from 'os';
+import { LRUCache } from 'lru-cache';
+import path from 'path';
+import { createWriteStream, createReadStream } from 'fs';
+import { pipeline } from 'stream/promises';
+import yauzl from 'yauzl';
+import crypto2 from 'crypto';
+import fs from 'fs/promises';
+import { Readable } from 'stream';
+import pLimit from 'p-limit';
+import { Buffer as Buffer$1 } from 'buffer';
+import { spawn } from 'child_process';
+
+// src/core/logger.ts
+var silentLogger = {
+  log() {
+  }
+};
+
+// src/constants/platform.ts
+var NODE_PLATFORM_TO_MOJANG_OS = {
+  win32: "windows",
+  darwin: "osx",
+  linux: "linux"
+};
+var NODE_ARCH_TO_MOJANG_ARCH = {
+  x64: "x64",
+  ia32: "x86",
+  arm64: "arm64"
+};
+var RUNTIME_PLATFORM_KEYS = {
+  windows: { x64: "windows-x64", x86: "windows-x86", arm64: "windows-arm64" },
+  osx: { x64: "mac-os", arm64: "mac-os-arm64", x86: "mac-os" },
+  linux: { x64: "linux", x86: "linux-i386", arm64: "linux" }
+};
+
+// src/core/errors.ts
+var MinecraftKitError = class extends Error {
+  name = "MinecraftKitError";
+  /** Stable discriminator. */
+  code;
+  /** Structured context; safe to serialize. */
+  context;
+  constructor(code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.code = code;
+    this.context = Object.freeze({ ...options.context ?? {} });
+  }
+  /** JSON-friendly representation. */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+      cause: this.cause instanceof Error ? { name: this.cause.name, message: this.cause.message } : this.cause
+    };
+  }
+};
+function isMinecraftKitError(e) {
+  return e instanceof MinecraftKitError;
+}
+
+// src/core/system.ts
+function detectSystem(input = {}) {
+  const platform = input.platform ?? process.platform;
+  const arch = input.arch ?? process.arch;
+  const osVersion = input.osVersion ?? os.release();
+  const mojangOs = NODE_PLATFORM_TO_MOJANG_OS[platform];
+  const mojangArch = NODE_ARCH_TO_MOJANG_ARCH[arch];
+  if (mojangOs === void 0 || mojangArch === void 0) {
+    throw new MinecraftKitError(
+      "RUNTIME_UNSUPPORTED_PLATFORM",
+      `Unsupported platform/arch combination: ${platform}/${arch}`,
+      { context: { platform, arch: String(arch) } }
+    );
+  }
+  return { os: mojangOs, arch: mojangArch, osVersion };
+}
+
+// src/constants/defaults.ts
+var HTTP_TIMEOUT_MS = 3e4;
+var HTTP_RETRY_MAX = 4;
+var HTTP_RETRY_BACKOFF_BASE_MS = 500;
+var HTTP_RETRY_BACKOFF_CAP_MS = 3e4;
+var DOWNLOAD_CONCURRENCY = 32;
+var CACHE_TTL_MS = 5 * 6e4;
+var CACHE_MAX_ENTRIES = 256;
+var USER_AGENT = "minecraft-kit/0.1";
+var DEFAULT_LAUNCHER_NAME = "minecraft-kit";
+var DEFAULT_LAUNCHER_VERSION = "0.1.0";
+var DEFAULT_MIN_MB = 1024;
+var DEFAULT_MAX_MB = 4096;
+var DEFAULT_KILL_GRACE_MS = 5e3;
+var MAX_PROCESSOR_STDERR_LINES = 20;
+var SPAWNER_MAX_LINE_BYTES = 64 * 1024;
+
+// src/http/cache.ts
+function createMemoryCache(options = {}) {
+  const cache = new LRUCache({
+    max: options.maxEntries ?? CACHE_MAX_ENTRIES,
+    ttl: options.ttlMs ?? CACHE_TTL_MS
+  });
+  return {
+    get(key) {
+      const wrapped = cache.get(key);
+      return wrapped === void 0 ? void 0 : wrapped.value;
+    },
+    set(key, value, ttlMs) {
+      const wrapped = { value };
+      if (ttlMs === void 0) {
+        cache.set(key, wrapped);
+      } else {
+        cache.set(key, wrapped, { ttl: ttlMs });
+      }
+    },
+    delete(key) {
+      cache.delete(key);
+    },
+    clear() {
+      cache.clear();
+    }
+  };
+}
+
+// src/http/client.ts
+var TIMEOUT_REASON = /* @__PURE__ */ Symbol("http-timeout");
+var FetchHttpClient = class {
+  async request(url, options = {}) {
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? HTTP_TIMEOUT_MS;
+    const onParentAbort = () => controller.abort(options.signal?.reason);
+    if (options.signal) {
+      if (options.signal.aborted) {
+        controller.abort(options.signal.reason);
+      } else {
+        options.signal.addEventListener("abort", onParentAbort, { once: true });
+      }
+    }
+    const timer = setTimeout(() => controller.abort(TIMEOUT_REASON), timeoutMs);
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "GET",
+        headers: { "user-agent": USER_AGENT, ...options.headers ?? {} },
+        signal: controller.signal,
+        redirect: "follow"
+      });
+    } catch (cause) {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onParentAbort);
+      if (controller.signal.reason === TIMEOUT_REASON) {
+        throw new MinecraftKitError("NETWORK_TIMEOUT", `Request timed out: ${url}`, {
+          cause,
+          context: { url, timeoutMs }
+        });
+      }
+      if (options.signal?.aborted) {
+        throw new MinecraftKitError("NETWORK_ABORTED", `Request aborted: ${url}`, {
+          cause,
+          context: { url }
+        });
+      }
+      throw new MinecraftKitError("NETWORK_HTTP_ERROR", `Network request failed: ${url}`, {
+        cause,
+        context: { url }
+      });
+    }
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onParentAbort);
+    if (!response.ok) {
+      throw new MinecraftKitError("NETWORK_HTTP_ERROR", `HTTP ${response.status} for ${url}`, {
+        context: { url, httpStatus: response.status }
+      });
+    }
+    return new FetchHttpResponse(response, url);
+  }
+};
+var FetchHttpResponse = class {
+  constructor(response, url) {
+    this.response = response;
+    this.status = response.status;
+    this.url = url;
+    const headers = {};
+    response.headers.forEach((value, key) => {
+      headers[key.toLowerCase()] = value;
+    });
+    this.headers = headers;
+  }
+  response;
+  status;
+  headers;
+  url;
+  async text() {
+    return this.response.text();
+  }
+  async json() {
+    return await this.response.json();
+  }
+  async bytes() {
+    const buf = await this.response.arrayBuffer();
+    return new Uint8Array(buf);
+  }
+  async *stream() {
+    const body = this.response.body;
+    if (!body) {
+      const buf = await this.bytes();
+      yield buf;
+      return;
+    }
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) return;
+        if (value) yield value;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
+
+// src/constants/files.ts
+var VERSIONS_DIR = "versions";
+var LIBRARIES_DIR = "libraries";
+var ASSETS_DIR = "assets";
+var ASSETS_OBJECTS_DIR = "assets/objects";
+var ASSETS_INDEXES_DIR = "assets/indexes";
+var ASSETS_VIRTUAL_DIR = "assets/virtual";
+var ASSETS_LEGACY_DIR = "assets/virtual/legacy";
+var ASSETS_RESOURCES_DIR = "resources";
+var ASSETS_LOG_CONFIGS_DIR = "assets/log_configs";
+var RUNTIMES_DIR = "runtime";
+var NATIVES_DIR_NAME = "natives";
+var FORGE_INSTALLERS_DIR = "forge-installers";
+var JAVA_EXECUTABLE = {
+  windows: "bin/javaw.exe",
+  linux: "bin/java",
+  /** Note: macOS uses an extra `jre.bundle/Contents/Home/` prefix above this. */
+  osx: "bin/java"
+};
+var MAC_RUNTIME_PREFIX = "jre.bundle/Contents/Home";
+
+// src/core/paths.ts
+var targetPaths = {
+  versionsDir: (root) => path.join(root, VERSIONS_DIR),
+  versionDir: (root, versionId) => path.join(root, VERSIONS_DIR, versionId),
+  versionJar: (root, versionId) => path.join(root, VERSIONS_DIR, versionId, `${versionId}.jar`),
+  versionJson: (root, versionId) => path.join(root, VERSIONS_DIR, versionId, `${versionId}.json`),
+  librariesDir: (root) => path.join(root, LIBRARIES_DIR),
+  libraryFile: (root, libraryPath) => path.join(root, LIBRARIES_DIR, libraryPath),
+  assetIndex: (root, indexId) => path.join(root, ASSETS_INDEXES_DIR, `${indexId}.json`),
+  assetObject: (root, hash) => path.join(root, ASSETS_OBJECTS_DIR, hash.slice(0, 2), hash),
+  assetVirtual: (root, virtualPath) => path.join(root, ASSETS_VIRTUAL_DIR, virtualPath),
+  assetLegacy: (root, virtualPath) => path.join(root, ASSETS_LEGACY_DIR, virtualPath),
+  assetResource: (root, virtualPath) => path.join(root, ASSETS_RESOURCES_DIR, virtualPath),
+  loggingConfig: (root, id) => path.join(root, ASSETS_LOG_CONFIGS_DIR, id),
+  nativesDir: (root, versionId) => path.join(root, VERSIONS_DIR, versionId, NATIVES_DIR_NAME),
+  /**
+   * Path to a runtime component's root directory. Honours `installRoot` (custom global
+   * runtime location) when present; otherwise falls back to `<directory>/runtime/<component>`.
+   */
+  runtimeRoot: (directory, component, installRoot) => installRoot !== void 0 ? path.join(installRoot, component) : path.join(directory, RUNTIMES_DIR, component),
+  runtimeJavaExecutable: (directory, component, os2, installRoot) => {
+    const runtime = targetPaths.runtimeRoot(directory, component, installRoot);
+    if (os2 === "windows") return path.join(runtime, JAVA_EXECUTABLE.windows);
+    if (os2 === "osx") return path.join(runtime, MAC_RUNTIME_PREFIX, JAVA_EXECUTABLE.osx);
+    return path.join(runtime, JAVA_EXECUTABLE.linux);
+  },
+  forgeInstaller: (root, mavenVersion) => path.join(root, FORGE_INSTALLERS_DIR, `forge-${mavenVersion}-installer.jar`)
+};
+
+// src/types/install.ts
+var InstallPhases = {
+  PLANNING: "planning",
+  DOWNLOADING_LIBRARIES: "downloading-libraries",
+  EXTRACTING_NATIVES: "extracting-natives",
+  INSTALLING_RUNTIME: "installing-runtime",
+  RUNNING_FORGE_PROCESSORS: "running-forge-processors",
+  WRITING_FILES: "writing-files",
+  COMPLETED: "completed"
+};
+var InstallActionKinds = {
+  DOWNLOAD_FILE: "download-file",
+  EXTRACT_NATIVE: "extract-native",
+  RUN_FORGE_PROCESSOR: "run-forge-processor",
+  WRITE_VERSION_JSON: "write-version-json",
+  WRITE_LOGGING_CONFIG: "write-logging-config"
+};
+
+// src/types/loader.ts
+var Loaders = {
+  /** Plain vanilla Minecraft, no mod loader. */
+  VANILLA: "vanilla",
+  /** Fabric mod loader. */
+  FABRIC: "fabric",
+  /** Modern (1.13+) Forge mod loader. */
+  FORGE: "forge"
+};
+var VersionPreference = {
+  LATEST: "latest",
+  RECOMMENDED: "recommended"
+};
+
+// src/constants/api.ts
+var PISTON_META = "https://piston-meta.mojang.com";
+var RESOURCES = "https://resources.download.minecraft.net";
+var FABRIC_META = "https://meta.fabricmc.net";
+var FORGE_MAVEN = "https://maven.minecraftforge.net";
+var FORGE_FILES = "https://files.minecraftforge.net";
+var RUNTIME_INDEX_DIGEST = "2ec0cc96c44e5a76b9c8b7c39df7210883d12871";
+var ApiEndpoints = {
+  mojang: {
+    /** Top-level Minecraft version manifest (v2). */
+    versionManifest: () => `${PISTON_META}/mc/game/version_manifest_v2.json`,
+    /** Mojang Java-runtime index. */
+    runtimeIndex: () => `${PISTON_META}/v1/products/java-runtime/${RUNTIME_INDEX_DIGEST}/all.json`
+  },
+  resources: {
+    /** Hash-addressed Minecraft asset object. */
+    asset: (hash) => `${RESOURCES}/${hash.slice(0, 2)}/${hash}`
+  },
+  fabric: {
+    gameVersions: () => `${FABRIC_META}/v2/versions/game`,
+    loaderVersions: () => `${FABRIC_META}/v2/versions/loader`,
+    loaderForGame: (minecraftVersion) => `${FABRIC_META}/v2/versions/loader/${encodeURIComponent(minecraftVersion)}`,
+    profile: (minecraftVersion, loaderVersion) => `${FABRIC_META}/v2/versions/loader/${encodeURIComponent(minecraftVersion)}/${encodeURIComponent(loaderVersion)}/profile/json`
+  },
+  forge: {
+    /** Forge Maven listing of all builds across all MC versions. */
+    mavenMetadata: () => `${FORGE_MAVEN}/net/minecraftforge/forge/maven-metadata.xml`,
+    /** Slim "recommended" / "latest" promotion mapping. */
+    promotions: () => `${FORGE_FILES}/net/minecraftforge/forge/promotions_slim.json`,
+    /** URL of the modern installer JAR for a Maven version (e.g. `1.20.1-47.2.0`). */
+    installer: (mavenVersion) => {
+      const filename = `forge-${mavenVersion}-installer.jar`;
+      return `${FORGE_MAVEN}/net/minecraftforge/forge/${mavenVersion}/${filename}`;
+    }
+  }
+};
+
+// src/http/metadata.ts
+async function fetchJson(http, cache, input) {
+  const key = input.cacheKey ?? `json:${input.url}`;
+  const cached = cache.get(key);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const requestOptions = {};
+  if (input.signal !== void 0) requestOptions.signal = input.signal;
+  const response = await http.request(input.url, requestOptions);
+  const value = await response.json();
+  cache.set(key, value, input.ttlMs ?? CACHE_TTL_MS);
+  return value;
+}
+async function fetchText(http, cache, input) {
+  const key = input.cacheKey ?? `text:${input.url}`;
+  const cached = cache.get(key);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const requestOptions = {};
+  if (input.signal !== void 0) requestOptions.signal = input.signal;
+  const response = await http.request(input.url, requestOptions);
+  const text = await response.text();
+  cache.set(key, text, input.ttlMs ?? CACHE_TTL_MS);
+  return text;
+}
+
+// src/install/assets.ts
+async function planAssetDownloads(input) {
+  const indexUrl = input.assetIndex.url;
+  const indexPath = targetPaths.assetIndex(input.directory, input.assetIndex.id);
+  const indexDocument = await fetchJson(input.http, input.cache, {
+    url: indexUrl,
+    cacheKey: `asset-index:${input.assetIndex.id}:${input.assetIndex.sha1}`,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  const actions = [
+    {
+      kind: InstallActionKinds.DOWNLOAD_FILE,
+      url: indexUrl,
+      target: indexPath,
+      expectedSha1: input.assetIndex.sha1,
+      expectedSize: input.assetIndex.size,
+      category: "asset-index"
+    }
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of Object.values(indexDocument.objects)) {
+    if (seen.has(entry.hash)) continue;
+    seen.add(entry.hash);
+    actions.push({
+      kind: InstallActionKinds.DOWNLOAD_FILE,
+      url: ApiEndpoints.resources.asset(entry.hash),
+      target: targetPaths.assetObject(input.directory, entry.hash),
+      expectedSha1: entry.hash,
+      expectedSize: entry.size,
+      category: "asset"
+    });
+  }
+  return { actions, indexDocument };
+}
+
+// src/constants/maven.ts
+var DEFAULT_LIBRARY_REPOSITORY = "https://libraries.minecraft.net/";
+
+// src/core/maven.ts
+function parseMavenCoordinate(input) {
+  const trimmed = input.startsWith("[") && input.endsWith("]") ? input.slice(1, -1) : input;
+  const atIndex = trimmed.indexOf("@");
+  const extension = atIndex === -1 ? "jar" : trimmed.slice(atIndex + 1);
+  const body = atIndex === -1 ? trimmed : trimmed.slice(0, atIndex);
+  const parts = body.split(":");
+  if (parts.length < 3 || parts.length > 4) {
+    throw new MinecraftKitError("INVALID_INPUT", `Invalid Maven coordinate: ${input}`, {
+      context: { input }
+    });
+  }
+  const [group, artifact, version, classifier] = parts;
+  if (!group || !artifact || !version) {
+    throw new MinecraftKitError(
+      "INVALID_INPUT",
+      `Invalid Maven coordinate (missing component): ${input}`,
+      { context: { input } }
+    );
+  }
+  if (classifier === void 0) {
+    return { group, artifact, version, extension };
+  }
+  return { group, artifact, version, classifier, extension };
+}
+function mavenRelativePath(coord) {
+  const groupPath = coord.group.replaceAll(".", "/");
+  const classifierSegment = coord.classifier === void 0 ? "" : `-${coord.classifier}`;
+  const filename = `${coord.artifact}-${coord.version}${classifierSegment}.${coord.extension}`;
+  return `${groupPath}/${coord.artifact}/${coord.version}/${filename}`;
+}
+function mavenRelativePathFor(input) {
+  return mavenRelativePath(parseMavenCoordinate(input));
+}
+
+// src/core/rules.ts
+function evaluateRules(rules, context) {
+  if (!rules || rules.length === 0) {
+    return true;
+  }
+  let allowed = false;
+  for (const rule of rules) {
+    if (matchesRule(rule, context)) {
+      allowed = rule.action === "allow";
+    }
+  }
+  return allowed;
+}
+function matchesRule(rule, context) {
+  if (rule.os !== void 0) {
+    if (rule.os.name !== void 0 && rule.os.name !== context.system.os) {
+      return false;
+    }
+    if (rule.os.arch !== void 0 && normalizeArch(rule.os.arch) !== context.system.arch) {
+      return false;
+    }
+    if (rule.os.version !== void 0) {
+      try {
+        if (!new RegExp(rule.os.version).test(context.system.osVersion)) {
+          return false;
+        }
+      } catch {
+        return false;
+      }
+    }
+  }
+  if (rule.features !== void 0) {
+    const features = context.features ?? {};
+    for (const [key, expected] of Object.entries(rule.features)) {
+      const actual = features[key] === true;
+      if (expected !== actual) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+function normalizeArch(arch) {
+  return arch === "ia32" ? "x86" : arch;
+}
+function resolveArchPlaceholder(template, archDigit2) {
+  return template.replaceAll("${arch}", archDigit2);
+}
+function archDigit(arch) {
+  if (arch === "x86") return "32";
+  if (arch === "x64") return "64";
+  return "64";
+}
+
+// src/install/libraries.ts
+function planLibraryDownloads(input) {
+  const downloads = [];
+  const nativeExtractions = [];
+  const classpathFiles = [];
+  const seenPaths = /* @__PURE__ */ new Set();
+  const nativesDir = targetPaths.nativesDir(input.directory, input.versionId);
+  for (const library of input.libraries) {
+    if (!evaluateRules(library.rules, { system: input.system })) continue;
+    const artifact = pickPrimaryArtifact(library);
+    if (artifact) {
+      const targetPath = path.join(
+        targetPaths.librariesDir(input.directory),
+        artifact.relativePath
+      );
+      if (!seenPaths.has(targetPath)) {
+        seenPaths.add(targetPath);
+        downloads.push({
+          kind: InstallActionKinds.DOWNLOAD_FILE,
+          url: artifact.url,
+          target: targetPath,
+          ...artifact.sha1 !== void 0 ? { expectedSha1: artifact.sha1 } : {},
+          ...artifact.size !== void 0 ? { expectedSize: artifact.size } : {},
+          category: input.category
+        });
+        classpathFiles.push(targetPath);
+      }
+    }
+    const native = pickNative(library, input.system);
+    if (native) {
+      const targetPath = path.join(targetPaths.librariesDir(input.directory), native.relativePath);
+      if (!seenPaths.has(targetPath)) {
+        seenPaths.add(targetPath);
+        downloads.push({
+          kind: InstallActionKinds.DOWNLOAD_FILE,
+          url: native.url,
+          target: targetPath,
+          ...native.sha1 !== void 0 ? { expectedSha1: native.sha1 } : {},
+          ...native.size !== void 0 ? { expectedSize: native.size } : {},
+          category: input.category
+        });
+      }
+      nativeExtractions.push({
+        kind: InstallActionKinds.EXTRACT_NATIVE,
+        source: targetPath,
+        destination: nativesDir,
+        exclude: library.extract?.exclude ?? ["META-INF/"]
+      });
+    }
+  }
+  return { downloads, nativeExtractions, classpathFiles };
+}
+function pickPrimaryArtifact(library) {
+  if (library.downloads?.artifact) {
+    return artifactFromDownload(library.downloads.artifact);
+  }
+  if (library.url) {
+    return mavenArtifactFromCoord(library.name, library.url);
+  }
+  if (library.name && !library.natives) {
+    return mavenArtifactFromCoord(library.name, DEFAULT_LIBRARY_REPOSITORY);
+  }
+  return null;
+}
+function pickNative(library, system) {
+  if (!library.natives) return null;
+  const classifierTemplate = library.natives[system.os];
+  if (!classifierTemplate) return null;
+  const classifier = resolveArchPlaceholder(classifierTemplate, archDigit(system.arch));
+  const classifierArtifact = library.downloads?.classifiers?.[classifier];
+  if (classifierArtifact) {
+    return artifactFromDownload(classifierArtifact);
+  }
+  if (library.url || library.name) {
+    const coord = parseMavenCoordinate(library.name);
+    const withClassifier = `${coord.group}:${coord.artifact}:${coord.version}:${classifier}`;
+    return mavenArtifactFromCoord(withClassifier, library.url ?? DEFAULT_LIBRARY_REPOSITORY);
+  }
+  return null;
+}
+function artifactFromDownload(artifact) {
+  return {
+    relativePath: artifact.path,
+    url: artifact.url,
+    sha1: artifact.sha1,
+    size: artifact.size
+  };
+}
+function mavenArtifactFromCoord(coord, baseUrl) {
+  const relativePath = mavenRelativePathFor(coord);
+  const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  if (!relativePath) {
+    throw new MinecraftKitError("MANIFEST_INVALID", `Invalid library coordinate: ${coord}`, {
+      context: { input: coord }
+    });
+  }
+  return {
+    relativePath,
+    url: `${normalizedBase}${relativePath}`,
+    sha1: void 0,
+    size: void 0
+  };
+}
+
+// src/install/fabric-install.ts
+function planFabricInstall(input) {
+  const versionId = input.loader.profile.id;
+  const versionJsonPath = targetPaths.versionJson(input.directory, versionId);
+  const versionJson = {
+    kind: InstallActionKinds.WRITE_VERSION_JSON,
+    path: versionJsonPath,
+    content: `${JSON.stringify(input.loader.profile, null, 2)}
+`
+  };
+  const plan = planLibraryDownloads({
+    libraries: input.loader.profile.libraries,
+    directory: input.directory,
+    system: input.system,
+    versionId: input.minecraft.version,
+    category: "fabric-library"
+  });
+  return {
+    versionJson,
+    libraryDownloads: plan.downloads,
+    classpathFiles: plan.classpathFiles,
+    versionId
+  };
+}
+
+// src/constants/limits.ts
+var EXTRACTION_MAX_FILE_SIZE = 256 * 1024 * 1024;
+var EXTRACTION_MAX_TOTAL_SIZE = 2 * 1024 * 1024 * 1024;
+var EXTRACTION_MAX_COMPRESSION_RATIO = 200;
+var EXTRACTION_MAX_ENTRY_COUNT = 1e5;
+async function ensureDir(directory) {
+  try {
+    await fs.mkdir(directory, { recursive: true });
+  } catch (cause) {
+    throw new MinecraftKitError(
+      "FILESYSTEM_WRITE_ERROR",
+      `Failed to create directory: ${directory}`,
+      { cause, context: { filePath: directory } }
+    );
+  }
+}
+async function fileExists(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+async function dirExists(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function fileSize(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.size;
+  } catch {
+    return -1;
+  }
+}
+async function atomicWrite(target, data) {
+  await ensureDir(path.dirname(target));
+  const tmp = `${target}.${crypto2.randomBytes(4).toString("hex")}.tmp`;
+  try {
+    if (typeof data === "string") {
+      await fs.writeFile(tmp, data, "utf8");
+    } else {
+      await fs.writeFile(tmp, data);
+    }
+    await fs.rename(tmp, target);
+  } catch (cause) {
+    try {
+      await fs.unlink(tmp);
+    } catch {
+    }
+    throw new MinecraftKitError("FILESYSTEM_WRITE_ERROR", `Failed to write file: ${target}`, {
+      cause,
+      context: { filePath: target }
+    });
+  }
+}
+async function readText(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (cause) {
+    throw new MinecraftKitError("FILESYSTEM_READ_ERROR", `Failed to read file: ${filePath}`, {
+      cause,
+      context: { filePath }
+    });
+  }
+}
+async function listChildDirectories(directory) {
+  try {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+async function chmodExecutable(filePath) {
+  if (process.platform === "win32") {
+    return;
+  }
+  try {
+    await fs.chmod(filePath, 493);
+  } catch {
+  }
+}
+function assertWithinRoot(root, child) {
+  const normalizedRoot = path.resolve(root);
+  const normalizedChild = path.resolve(root, child);
+  const sep = path.sep;
+  if (normalizedChild !== normalizedRoot && !normalizedChild.startsWith(normalizedRoot + sep)) {
+    throw new MinecraftKitError("FILESYSTEM_PATH_TRAVERSAL", `Path escapes root: ${child}`, {
+      context: { filePath: child, rootDirectory: root }
+    });
+  }
+}
+
+// src/core/archive.ts
+function openZip(filePath) {
+  return new Promise((resolve, reject) => {
+    yauzl.open(filePath, { lazyEntries: true, autoClose: false }, (err, zipFile) => {
+      if (err || !zipFile) {
+        reject(
+          new MinecraftKitError("ARCHIVE_INVALID", `Failed to open archive: ${filePath}`, {
+            cause: err,
+            context: { filePath }
+          })
+        );
+        return;
+      }
+      resolve(new ZipReader(zipFile, filePath));
+    });
+  });
+}
+var ZipReader = class {
+  constructor(file, filePath) {
+    this.file = file;
+    this.filePath = filePath;
+  }
+  file;
+  filePath;
+  /** Iterate every entry. Caller may break out of the loop early. */
+  async *entries() {
+    const file = this.file;
+    let count = 0;
+    while (true) {
+      const entry = await this.readNext();
+      if (entry === null) return;
+      count++;
+      if (count > EXTRACTION_MAX_ENTRY_COUNT) {
+        throw new MinecraftKitError(
+          "ARCHIVE_TOO_LARGE",
+          `Archive contains too many entries: ${this.filePath}`,
+          { context: { filePath: this.filePath } }
+        );
+      }
+      yield this.toZipEntry(entry, file);
+    }
+  }
+  /** Find a single entry by name. Returns undefined if absent. */
+  async findEntry(name) {
+    for await (const entry of this.entries()) {
+      if (entry.name === name) return entry;
+    }
+    return void 0;
+  }
+  /** Close the reader. */
+  close() {
+    this.file.close();
+  }
+  readNext() {
+    return new Promise((resolve, reject) => {
+      const onEntry = (entry) => {
+        cleanup();
+        resolve(entry);
+      };
+      const onEnd = () => {
+        cleanup();
+        resolve(null);
+      };
+      const onError = (err) => {
+        cleanup();
+        reject(
+          new MinecraftKitError("ARCHIVE_INVALID", "Failed to read archive entry", {
+            cause: err,
+            context: { filePath: this.filePath }
+          })
+        );
+      };
+      const cleanup = () => {
+        this.file.removeListener("entry", onEntry);
+        this.file.removeListener("end", onEnd);
+        this.file.removeListener("error", onError);
+      };
+      this.file.once("entry", onEntry);
+      this.file.once("end", onEnd);
+      this.file.once("error", onError);
+      this.file.readEntry();
+    });
+  }
+  toZipEntry(entry, file) {
+    const name = entry.fileName;
+    const isDirectory = name.endsWith("/");
+    return {
+      name,
+      compressedSize: entry.compressedSize,
+      uncompressedSize: entry.uncompressedSize,
+      isDirectory,
+      readBuffer: async () => {
+        if (entry.uncompressedSize > EXTRACTION_MAX_FILE_SIZE) {
+          throw new MinecraftKitError(
+            "ARCHIVE_TOO_LARGE",
+            `Archive entry exceeds size cap: ${name}`,
+            { context: { filePath: this.filePath, entryName: name, size: entry.uncompressedSize } }
+          );
+        }
+        if (entry.compressedSize > 0 && entry.uncompressedSize / entry.compressedSize > EXTRACTION_MAX_COMPRESSION_RATIO) {
+          throw new MinecraftKitError(
+            "ARCHIVE_TOO_LARGE",
+            `Archive entry exceeds compression-ratio cap: ${name}`,
+            { context: { filePath: this.filePath, entryName: name } }
+          );
+        }
+        const stream = await openStream(file, entry, this.filePath);
+        const chunks = [];
+        for await (const chunk of stream) {
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+      },
+      openReadStream: () => openStream(file, entry, this.filePath)
+    };
+  }
+};
+function openStream(file, entry, archivePath) {
+  return new Promise((resolve, reject) => {
+    file.openReadStream(entry, (err, stream) => {
+      if (err || !stream) {
+        reject(
+          new MinecraftKitError(
+            "ARCHIVE_INVALID",
+            `Failed to open archive entry: ${entry.fileName}`,
+            { cause: err, context: { filePath: archivePath, entryName: entry.fileName } }
+          )
+        );
+        return;
+      }
+      resolve(stream);
+    });
+  });
+}
+async function extractAllToDir(zipPath, targetDir, options = {}) {
+  const exclude = options.excludePrefixes ?? ["META-INF/"];
+  let fileCount = 0;
+  let totalSize = 0;
+  await ensureDir(targetDir);
+  const reader = await openZip(zipPath);
+  try {
+    for await (const entry of reader.entries()) {
+      if (entry.isDirectory) continue;
+      if (exclude.some((prefix) => entry.name.startsWith(prefix))) continue;
+      assertSafeEntryName(entry.name);
+      const destination = path.join(targetDir, entry.name);
+      assertWithinRoot(targetDir, entry.name);
+      totalSize += entry.uncompressedSize;
+      if (totalSize > EXTRACTION_MAX_TOTAL_SIZE) {
+        throw new MinecraftKitError(
+          "ARCHIVE_TOO_LARGE",
+          `Archive total size cap exceeded: ${zipPath}`,
+          { context: { filePath: zipPath } }
+        );
+      }
+      if (entry.uncompressedSize > EXTRACTION_MAX_FILE_SIZE) {
+        throw new MinecraftKitError(
+          "ARCHIVE_TOO_LARGE",
+          `Archive entry exceeds size cap: ${entry.name}`,
+          { context: { filePath: zipPath, entryName: entry.name } }
+        );
+      }
+      await ensureDir(path.dirname(destination));
+      const stream = await entry.openReadStream();
+      await pipeline(stream, createWriteStream(destination));
+      if (entry.name.endsWith(".so") || entry.name.endsWith(".dylib") || entry.name.endsWith(".jnilib")) {
+        await chmodExecutable(destination);
+      }
+      fileCount++;
+    }
+  } finally {
+    reader.close();
+  }
+  return { fileCount };
+}
+var RESERVED_NAME = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\..*)?$/i;
+function assertSafeEntryName(name) {
+  if (!name) {
+    throw rejectEntry(name, "empty entry name");
+  }
+  if (name.includes(String.fromCharCode(0))) {
+    throw rejectEntry(name, "null byte");
+  }
+  if (path.posix.isAbsolute(name) || /^[a-zA-Z]:/.test(name) || name.startsWith("\\")) {
+    throw rejectEntry(name, "absolute path");
+  }
+  const segments = name.split("/");
+  for (const segment of segments) {
+    if (segment === "..") {
+      throw rejectEntry(name, "parent traversal");
+    }
+    if (RESERVED_NAME.test(segment)) {
+      throw rejectEntry(name, "reserved Windows name");
+    }
+    if (/[\s.]$/.test(segment)) {
+      throw rejectEntry(name, "trailing dot or whitespace");
+    }
+  }
+}
+function rejectEntry(name, reason) {
+  return new MinecraftKitError(
+    "ARCHIVE_ENTRY_REJECTED",
+    `Archive entry rejected (${reason}): ${name}`,
+    { context: { entryName: name, reason } }
+  );
+}
+async function readEntryBuffer(zipPath, entryName) {
+  const reader = await openZip(zipPath);
+  try {
+    const entry = await reader.findEntry(entryName);
+    if (!entry) return void 0;
+    return await entry.readBuffer();
+  } finally {
+    reader.close();
+  }
+}
+async function extractSingleEntry(zipPath, entryName, destination) {
+  const buffer = await readEntryBuffer(zipPath, entryName);
+  if (!buffer) {
+    throw new MinecraftKitError("ARCHIVE_INVALID", `Archive entry not found: ${entryName}`, {
+      context: { filePath: zipPath, entryName }
+    });
+  }
+  await atomicWrite(destination, buffer);
+}
+var MANIFEST_LINE_CONTINUATION = /\r?\n[ \t]/g;
+var MANIFEST_MAIN_CLASS = /^Main-Class:\s*(.+)$/i;
+async function readJarMainClass(zipPath) {
+  const buf = await readEntryBuffer(zipPath, "META-INF/MANIFEST.MF");
+  if (!buf) return void 0;
+  const text = buf.toString("utf8").replaceAll(MANIFEST_LINE_CONTINUATION, "");
+  for (const line of text.split(/\r?\n/)) {
+    const match = MANIFEST_MAIN_CLASS.exec(line);
+    if (match?.[1]) return match[1].trim();
+  }
+  return void 0;
+}
+
+// src/core/collections.ts
+function dedupeBy(values, key) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const value of values) {
+    const k = key(value);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    result.push(value);
+  }
+  return result;
+}
+function dedupe(values) {
+  return dedupeBy(values, (v) => v);
+}
+
+// src/core/retry.ts
+function abortableSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(toAbortError(signal));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(toAbortError(signal));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function toAbortError(signal) {
+  return new MinecraftKitError("NETWORK_ABORTED", "Operation aborted", {
+    context: { reason: signal?.reason }
+  });
+}
+async function withRetry(op, isRetryable, options = {}) {
+  const max = options.maxAttempts ?? HTTP_RETRY_MAX;
+  const base = options.baseMs ?? HTTP_RETRY_BACKOFF_BASE_MS;
+  const cap = options.capMs ?? HTTP_RETRY_BACKOFF_CAP_MS;
+  const sleep = options.sleep ?? abortableSleep;
+  const random = options.random ?? Math.random;
+  let lastError;
+  for (let attempt = 0; attempt < max; attempt++) {
+    if (options.signal?.aborted) {
+      throw toAbortError(options.signal);
+    }
+    try {
+      return await op(attempt);
+    } catch (error) {
+      lastError = error;
+      options.onAttemptFailed?.(error, attempt);
+      if (!isRetryable(error) || attempt === max - 1) {
+        throw error;
+      }
+      const delayCap = Math.min(cap, base * 2 ** attempt);
+      const delay = Math.floor(random() * delayCap);
+      await sleep(delay, options.signal);
+    }
+  }
+  throw lastError ?? new Error("withRetry exhausted attempts");
+}
+function isHttpRetryable(error) {
+  if (!isMinecraftKitError(error)) {
+    return false;
+  }
+  if (error.code === "NETWORK_ABORTED") return false;
+  if (error.code === "NETWORK_TIMEOUT") return true;
+  if (error.code === "NETWORK_HTTP_ERROR") {
+    const status = typeof error.context.httpStatus === "number" ? error.context.httpStatus : 0;
+    if (status === 408 || status === 425 || status === 429) return true;
+    if (status >= 500 && status < 600) return true;
+    return status === 0;
+  }
+  return false;
+}
+
+// src/http/download.ts
+async function downloadFile(http, input) {
+  const fileRef = { url: input.url, target: input.target, category: input.category };
+  if (input.expectedSha1 !== void 0) {
+    const existing = await checkExistingFile(input.target, input.expectedSha1, input.expectedSize);
+    if (existing.matches) {
+      input.onEvent?.({ type: "download:skipped", file: fileRef });
+      return { bytesDownloaded: 0, sha1: existing.sha1, skipped: true };
+    }
+  }
+  await ensureDir(path.dirname(input.target));
+  const tmp = `${input.target}.${crypto2.randomBytes(4).toString("hex")}.download`;
+  return withRetry(
+    async () => {
+      input.onEvent?.({
+        type: "download:started",
+        file: fileRef,
+        expectedSize: input.expectedSize ?? 0
+      });
+      const startedAt = Date.now();
+      let bytesDownloaded = 0;
+      const hash = crypto2.createHash("sha1");
+      const response = await http.request(input.url, { signal: input.signal });
+      const contentLength = Number(response.headers["content-length"] ?? "0");
+      const total = input.expectedSize ?? (Number.isFinite(contentLength) ? contentLength : 0);
+      const sourceIterable = response.stream();
+      const counting = (async function* () {
+        for await (const chunk of sourceIterable) {
+          bytesDownloaded += chunk.byteLength;
+          hash.update(chunk);
+          input.onEvent?.({
+            type: "download:progress",
+            file: fileRef,
+            bytesDownloaded,
+            totalBytes: total
+          });
+          yield chunk;
+        }
+      })();
+      try {
+        await pipeline(Readable.from(counting), createWriteStream(tmp));
+      } catch (cause) {
+        await safeUnlink(tmp);
+        throw new MinecraftKitError(
+          "FILESYSTEM_WRITE_ERROR",
+          `Failed to write download: ${input.target}`,
+          { cause, context: { filePath: input.target, url: input.url } }
+        );
+      }
+      const computedSha1 = hash.digest("hex");
+      if (input.expectedSize !== void 0 && bytesDownloaded !== input.expectedSize) {
+        await safeUnlink(tmp);
+        throw new MinecraftKitError("INTEGRITY_SIZE_MISMATCH", `Size mismatch for ${input.url}`, {
+          context: {
+            url: input.url,
+            expectedSize: input.expectedSize,
+            actualSize: bytesDownloaded
+          }
+        });
+      }
+      if (input.expectedSha1 !== void 0 && computedSha1 !== input.expectedSha1) {
+        await safeUnlink(tmp);
+        input.onEvent?.({
+          type: "integrity:mismatch",
+          file: fileRef,
+          algorithm: "sha1",
+          expected: input.expectedSha1,
+          actual: computedSha1
+        });
+        throw new MinecraftKitError("INTEGRITY_HASH_MISMATCH", `SHA-1 mismatch for ${input.url}`, {
+          context: {
+            url: input.url,
+            expectedHash: input.expectedSha1,
+            actualHash: computedSha1
+          }
+        });
+      }
+      try {
+        await fs.rename(tmp, input.target);
+      } catch (cause) {
+        await safeUnlink(tmp);
+        throw new MinecraftKitError(
+          "FILESYSTEM_WRITE_ERROR",
+          `Failed to finalize download: ${input.target}`,
+          { cause, context: { filePath: input.target } }
+        );
+      }
+      input.onEvent?.({
+        type: "download:completed",
+        file: fileRef,
+        durationMs: Date.now() - startedAt,
+        bytes: bytesDownloaded
+      });
+      if (input.expectedSha1 !== void 0) {
+        input.onEvent?.({
+          type: "integrity:verified",
+          file: fileRef,
+          algorithm: "sha1",
+          hash: computedSha1
+        });
+      }
+      return { bytesDownloaded, sha1: computedSha1, skipped: false };
+    },
+    isHttpRetryable,
+    {
+      ...input.signal !== void 0 ? { signal: input.signal } : {},
+      onAttemptFailed: (error, attempt) => {
+        input.onEvent?.({
+          type: "download:failed",
+          file: fileRef,
+          error: error instanceof Error ? error : new Error(String(error)),
+          willRetry: isHttpRetryable(error) && attempt < HTTP_RETRY_MAX - 1
+        });
+      }
+    }
+  );
+}
+async function checkExistingFile(target, expectedSha1, expectedSize) {
+  let stat;
+  try {
+    stat = await fs.stat(target);
+  } catch {
+    return { matches: false, sha1: "" };
+  }
+  if (!stat.isFile()) {
+    return { matches: false, sha1: "" };
+  }
+  if (expectedSize !== void 0 && stat.size !== expectedSize) {
+    return { matches: false, sha1: "" };
+  }
+  const buf = await fs.readFile(target);
+  const sha1 = crypto2.createHash("sha1").update(buf).digest("hex");
+  return { matches: sha1 === expectedSha1, sha1 };
+}
+async function safeUnlink(filePath) {
+  try {
+    await fs.unlink(filePath);
+  } catch {
+  }
+}
+
+// src/install/forge-install.ts
+async function planForgeInstall(input) {
+  const installerPath = targetPaths.forgeInstaller(input.directory, input.loader.fullVersion);
+  await downloadFile(input.http, {
+    url: input.loader.installerUrl,
+    target: installerPath,
+    category: "forge-installer",
+    ...input.signal !== void 0 ? { signal: input.signal } : {},
+    ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+  });
+  const installerDownload = {
+    kind: InstallActionKinds.DOWNLOAD_FILE,
+    url: input.loader.installerUrl,
+    target: installerPath,
+    category: "forge-installer"
+  };
+  const profile = await readJsonEntry(installerPath, "install_profile.json");
+  const versionRelative = profile.json.startsWith("/") ? profile.json.slice(1) : profile.json;
+  const version = await readJsonEntry(installerPath, versionRelative);
+  await extractInstallerMavenEntries(installerPath, input.directory);
+  const dataResolved = await resolveProfileData({
+    profile,
+    installerPath,
+    directory: input.directory
+  });
+  const installerLibraries = planLibraryDownloads({
+    libraries: profile.libraries,
+    directory: input.directory,
+    system: input.system,
+    versionId: input.minecraft.version,
+    category: "forge-library"
+  });
+  const versionLibraries = planLibraryDownloads({
+    libraries: version.libraries,
+    directory: input.directory,
+    system: input.system,
+    versionId: version.id,
+    category: "forge-library"
+  });
+  const dedupedDownloads = dedupeBy(
+    [...installerLibraries.downloads, ...versionLibraries.downloads],
+    (action) => action.target
+  );
+  const classpathFiles = dedupe([
+    ...installerLibraries.classpathFiles,
+    ...versionLibraries.classpathFiles
+  ]);
+  const processorActions = await buildProcessorActions({
+    profile,
+    minecraft: input.minecraft,
+    installerPath,
+    directory: input.directory,
+    system: input.system,
+    dataResolved
+  });
+  const versionJsonPath = targetPaths.versionJson(input.directory, version.id);
+  const versionJson = {
+    kind: InstallActionKinds.WRITE_VERSION_JSON,
+    path: versionJsonPath,
+    content: `${JSON.stringify(version, null, 2)}
+`
+  };
+  return {
+    installerDownload,
+    libraryDownloads: dedupedDownloads,
+    classpathFiles,
+    processorActions,
+    versionJson,
+    versionId: version.id,
+    profile,
+    version
+  };
+}
+async function readJsonEntry(zipPath, entryName) {
+  const buffer = await readEntryBuffer(zipPath, entryName);
+  if (!buffer) {
+    throw new MinecraftKitError(
+      "FORGE_INSTALLER_INVALID",
+      `Forge installer is missing required entry: ${entryName}`,
+      { context: { filePath: zipPath, entryName } }
+    );
+  }
+  try {
+    return JSON.parse(buffer.toString("utf8"));
+  } catch (cause) {
+    throw new MinecraftKitError(
+      "FORGE_INSTALLER_INVALID",
+      `Forge installer entry is not valid JSON: ${entryName}`,
+      { cause, context: { filePath: zipPath, entryName } }
+    );
+  }
+}
+async function extractInstallerMavenEntries(installerPath, directory) {
+  const reader = await openZip(installerPath);
+  try {
+    for await (const entry of reader.entries()) {
+      if (!entry.name.startsWith("maven/") || entry.isDirectory) continue;
+      const relativeWithinLibraries = entry.name.slice("maven/".length);
+      const destination = path.join(targetPaths.librariesDir(directory), relativeWithinLibraries);
+      const buffer = await entry.readBuffer();
+      await atomicWrite(destination, buffer);
+    }
+  } finally {
+    reader.close();
+  }
+}
+async function resolveProfileData(input) {
+  const tokens = {};
+  for (const [key, sided] of Object.entries(input.profile.data)) {
+    const raw = sided.client;
+    tokens[key] = await resolveDataValue(raw, input.installerPath, input.directory);
+  }
+  return { tokens };
+}
+async function resolveDataValue(raw, installerPath, directory) {
+  if (raw.startsWith("[") && raw.endsWith("]")) {
+    const coord = raw.slice(1, -1);
+    const relativePath = mavenRelativePathFor(coord);
+    return {
+      value: path.join(targetPaths.librariesDir(directory), relativePath),
+      isPath: true
+    };
+  }
+  if (raw.startsWith("'")) {
+    return { value: raw.slice(1), isPath: false };
+  }
+  if (raw.startsWith("/")) {
+    const entryName = raw.slice(1);
+    const destination = path.join(targetPaths.librariesDir(directory), "forge-data", entryName);
+    await extractSingleEntry(installerPath, entryName, destination);
+    return { value: destination, isPath: true };
+  }
+  return { value: raw, isPath: false };
+}
+async function buildProcessorActions(input) {
+  const builtIns = {
+    SIDE: { value: "client", isPath: false },
+    MINECRAFT_JAR: {
+      value: targetPaths.versionJar(input.directory, input.minecraft.version),
+      isPath: true
+    },
+    MINECRAFT_VERSION: { value: input.minecraft.version, isPath: false },
+    ROOT: { value: input.directory, isPath: true },
+    INSTALLER: { value: input.installerPath, isPath: true },
+    LIBRARY_DIR: { value: targetPaths.librariesDir(input.directory), isPath: true }
+  };
+  const tokens = {
+    ...builtIns,
+    ...input.dataResolved.tokens
+  };
+  const actions = [];
+  let index = 0;
+  for (const processor of input.profile.processors) {
+    if (!processorAppliesToClient(processor)) {
+      continue;
+    }
+    if (!evaluateRules([], { system: input.system })) ;
+    const action = await buildProcessorAction({
+      processor,
+      directory: input.directory,
+      tokens,
+      index
+    });
+    actions.push(action);
+    index++;
+  }
+  return actions;
+}
+function processorAppliesToClient(processor) {
+  if (!processor.sides || processor.sides.length === 0) return true;
+  return processor.sides.includes("client");
+}
+async function buildProcessorAction(input) {
+  const jarPath = path.join(
+    targetPaths.librariesDir(input.directory),
+    mavenRelativePathFor(input.processor.jar)
+  );
+  const mainClass = await readJarMainClass(jarPath);
+  if (!mainClass) {
+    throw new MinecraftKitError(
+      "FORGE_INSTALLER_INVALID",
+      `Processor jar has no Main-Class: ${input.processor.jar}`,
+      { context: { filePath: jarPath } }
+    );
+  }
+  const classpath = [
+    jarPath,
+    ...input.processor.classpath.map(
+      (coord) => path.join(targetPaths.librariesDir(input.directory), mavenRelativePathFor(coord))
+    )
+  ];
+  const args = input.processor.args.map((arg) => substituteToken(arg, input.tokens));
+  const outputs = {};
+  if (input.processor.outputs) {
+    for (const [key, value] of Object.entries(input.processor.outputs)) {
+      outputs[substituteToken(key, input.tokens)] = stripLiteralPrefix(
+        substituteToken(value, input.tokens)
+      );
+    }
+  }
+  return {
+    kind: InstallActionKinds.RUN_FORGE_PROCESSOR,
+    index: input.index,
+    mainClass,
+    classpath,
+    args,
+    outputs
+  };
+}
+function substituteToken(raw, tokens) {
+  if (raw.startsWith("[") && raw.endsWith("]")) {
+    return path.join(...mavenRelativePathFor(raw.slice(1, -1)).split("/"));
+  }
+  return raw.replaceAll(/\{([A-Z0-9_]+)\}/g, (match, key) => {
+    const token = tokens[key];
+    if (token === void 0) {
+      throw new MinecraftKitError("FORGE_INSTALLER_INVALID", `Unknown processor token: ${match}`, {
+        context: { token: key }
+      });
+    }
+    return token.value;
+  });
+}
+function stripLiteralPrefix(value) {
+  return value.startsWith("'") ? value.slice(1) : value;
+}
+async function planRuntimeDownloads(input) {
+  const manifest = await fetchJson(input.http, input.cache, {
+    url: input.runtime.manifestUrl,
+    cacheKey: `runtime-manifest:${input.runtime.component}:${input.runtime.platformKey}:${input.runtime.manifestSha1}`,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  const actions = [];
+  const runtimeRoot = targetPaths.runtimeRoot(
+    input.directory,
+    input.runtime.component,
+    input.runtime.installRoot
+  );
+  for (const [relativePath, entry] of Object.entries(manifest.files)) {
+    if (entry.type !== "file") continue;
+    const target = path.join(runtimeRoot, relativePath);
+    actions.push({
+      kind: InstallActionKinds.DOWNLOAD_FILE,
+      url: entry.downloads.raw.url,
+      target,
+      expectedSha1: entry.downloads.raw.sha1,
+      expectedSize: entry.downloads.raw.size,
+      category: "runtime-file"
+    });
+  }
+  return { actions, manifest };
+}
+
+// src/install/planner.ts
+async function planInstall(input) {
+  const { target } = input;
+  const actions = [];
+  actions.push({
+    kind: InstallActionKinds.DOWNLOAD_FILE,
+    url: target.minecraft.manifest.downloads.client.url,
+    target: targetPaths.versionJar(target.directory, target.minecraft.version),
+    expectedSha1: target.minecraft.manifest.downloads.client.sha1,
+    expectedSize: target.minecraft.manifest.downloads.client.size,
+    category: "client-jar"
+  });
+  actions.push({
+    kind: InstallActionKinds.WRITE_VERSION_JSON,
+    path: targetPaths.versionJson(target.directory, target.minecraft.version),
+    content: `${JSON.stringify(target.minecraft.manifest, null, 2)}
+`
+  });
+  const vanillaLibraries = planLibraryDownloads({
+    libraries: target.minecraft.manifest.libraries,
+    directory: target.directory,
+    system: target.runtime.system,
+    versionId: target.minecraft.version,
+    category: "library"
+  });
+  actions.push(...vanillaLibraries.downloads);
+  actions.push(...vanillaLibraries.nativeExtractions);
+  const assetPlan = await planAssetDownloads({
+    directory: target.directory,
+    assetIndex: target.minecraft.manifest.assetIndex,
+    http: input.http,
+    cache: input.cache,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  actions.push(...assetPlan.actions);
+  if (target.minecraft.manifest.logging?.client) {
+    const logging = target.minecraft.manifest.logging.client;
+    actions.push({
+      kind: InstallActionKinds.DOWNLOAD_FILE,
+      url: logging.file.url,
+      target: targetPaths.loggingConfig(target.directory, logging.file.id),
+      expectedSha1: logging.file.sha1,
+      expectedSize: logging.file.size,
+      category: "logging-config"
+    });
+  }
+  const runtimePlan = await planRuntimeDownloads({
+    runtime: target.runtime,
+    directory: target.directory,
+    http: input.http,
+    cache: input.cache,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  actions.push(...runtimePlan.actions);
+  if (target.loader.type === Loaders.FABRIC) {
+    const fabricPlan = planFabricInstall({
+      loader: target.loader,
+      minecraft: target.minecraft,
+      directory: target.directory,
+      system: target.runtime.system
+    });
+    actions.push(fabricPlan.versionJson);
+    actions.push(...fabricPlan.libraryDownloads);
+  } else if (target.loader.type === Loaders.FORGE) {
+    const forgePlan = await planForgeInstall({
+      loader: target.loader,
+      minecraft: target.minecraft,
+      directory: target.directory,
+      system: target.runtime.system,
+      http: input.http,
+      cache: input.cache,
+      ...input.signal !== void 0 ? { signal: input.signal } : {},
+      ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+    });
+    actions.push(forgePlan.installerDownload);
+    actions.push(...forgePlan.libraryDownloads);
+    actions.push(forgePlan.versionJson);
+    actions.push(...forgePlan.processorActions);
+  }
+  const totalBytes = actions.reduce((sum, action) => {
+    if (action.kind === InstallActionKinds.DOWNLOAD_FILE) {
+      return sum + (action.expectedSize ?? 0);
+    }
+    return sum;
+  }, 0);
+  return {
+    targetId: target.id,
+    directory: target.directory,
+    target,
+    actions,
+    totalActions: actions.length,
+    totalBytes
+  };
+}
+async function materializeRuntimeExtras(input) {
+  const root = targetPaths.runtimeRoot(
+    input.directory,
+    input.runtime.component,
+    input.runtime.installRoot
+  );
+  for (const [relativePath, entry] of Object.entries(input.manifest.files)) {
+    const fullPath = path.join(root, relativePath);
+    if (entry.type === "directory") {
+      await ensureDir(fullPath);
+    } else if (entry.type === "link") {
+      await ensureDir(path.dirname(fullPath));
+      await unlinkIfPresent(fullPath);
+      await createLinkOrCopy(root, relativePath, entry.target, fullPath);
+    } else if (entry.executable && process.platform !== "win32") {
+      await fs.chmod(fullPath, 493).catch(() => {
+      });
+    }
+  }
+}
+async function unlinkIfPresent(target) {
+  try {
+    await fs.unlink(target);
+  } catch (cause) {
+    if (isNotFound(cause)) return;
+    throw new MinecraftKitError(
+      "FILESYSTEM_WRITE_ERROR",
+      `Failed to remove stale runtime entry: ${target}`,
+      { cause, context: { filePath: target } }
+    );
+  }
+}
+async function createLinkOrCopy(root, relativePath, linkTarget, destination) {
+  try {
+    await fs.symlink(linkTarget, destination);
+    return;
+  } catch (symlinkError) {
+    const absoluteSource = path.resolve(path.dirname(path.join(root, relativePath)), linkTarget);
+    try {
+      await fs.copyFile(absoluteSource, destination);
+    } catch (copyError) {
+      throw new MinecraftKitError(
+        "FILESYSTEM_WRITE_ERROR",
+        `Failed to materialize runtime entry: ${destination}`,
+        {
+          cause: copyError,
+          context: {
+            filePath: destination,
+            linkTarget,
+            symlinkError: errorMessage(symlinkError)
+          }
+        }
+      );
+    }
+  }
+}
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/install/runner.ts
+async function runInstall(input) {
+  const startedAt = Date.now();
+  let bytesDownloaded = 0;
+  let actionsCompleted = 0;
+  let actionsSkipped = 0;
+  const onEvent = input.onEvent;
+  let currentPhase = null;
+  const enterPhase = (phase) => {
+    if (phase === currentPhase) return;
+    onEvent?.({ type: "install:phase-changed", phase, previous: currentPhase });
+    currentPhase = phase;
+  };
+  const downloads = input.plan.actions.filter(isDownload);
+  const natives = input.plan.actions.filter(isNative);
+  const writeActions = input.plan.actions.filter(isWrite);
+  const processors = input.plan.actions.filter(isProcessor);
+  enterPhase(InstallPhases.PLANNING);
+  enterPhase(InstallPhases.DOWNLOADING_LIBRARIES);
+  const limit = pLimit(input.concurrency ?? DOWNLOAD_CONCURRENCY);
+  await Promise.all(
+    downloads.map(
+      (action) => limit(async () => {
+        if (input.signal?.aborted) {
+          throw new MinecraftKitError("LAUNCH_ABORTED", "Install aborted by signal");
+        }
+        const result = await downloadFile(input.http, {
+          url: action.url,
+          target: action.target,
+          ...action.expectedSha1 !== void 0 ? { expectedSha1: action.expectedSha1 } : {},
+          ...action.expectedSize !== void 0 ? { expectedSize: action.expectedSize } : {},
+          ...action.category !== void 0 ? { category: action.category } : {},
+          ...input.signal !== void 0 ? { signal: input.signal } : {},
+          ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+        });
+        bytesDownloaded += result.bytesDownloaded;
+        if (result.skipped) actionsSkipped++;
+        actionsCompleted++;
+      })
+    )
+  );
+  if (writeActions.length > 0) {
+    enterPhase(InstallPhases.WRITING_FILES);
+    for (const action of writeActions) {
+      if (input.signal?.aborted) {
+        throw new MinecraftKitError("LAUNCH_ABORTED", "Install aborted by signal");
+      }
+      await atomicWrite(action.path, action.content);
+      actionsCompleted++;
+    }
+  }
+  if (natives.length > 0) {
+    enterPhase(InstallPhases.EXTRACTING_NATIVES);
+    for (const action of natives) {
+      if (input.signal?.aborted) {
+        throw new MinecraftKitError("LAUNCH_ABORTED", "Install aborted by signal");
+      }
+      const { fileCount } = await extractAllToDir(action.source, action.destination, {
+        excludePrefixes: action.exclude
+      });
+      input.onEvent?.({
+        type: "archive:extracted",
+        archive: action.source,
+        target: action.destination,
+        fileCount
+      });
+      actionsCompleted++;
+    }
+  }
+  if (input.plan.target.runtime !== void 0) {
+    enterPhase(InstallPhases.INSTALLING_RUNTIME);
+    const runtimePlan = await planRuntimeDownloads({
+      runtime: input.plan.target.runtime,
+      directory: input.plan.directory,
+      http: input.http,
+      cache: input.cache,
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    await materializeRuntimeExtras({
+      runtime: input.plan.target.runtime,
+      directory: input.plan.directory,
+      manifest: runtimePlan.manifest
+    });
+  }
+  if (processors.length > 0) {
+    enterPhase(InstallPhases.RUNNING_FORGE_PROCESSORS);
+    if (input.plan.target.loader.type !== Loaders.FORGE) {
+      throw new MinecraftKitError(
+        "FORGE_PROCESSOR_FAILED",
+        "Forge processors planned for a non-Forge target"
+      );
+    }
+    const javaPath = targetPaths.runtimeJavaExecutable(
+      input.plan.directory,
+      input.plan.target.runtime.component,
+      input.plan.target.runtime.system.os,
+      input.plan.target.runtime.installRoot
+    );
+    for (const action of processors) {
+      if (input.signal?.aborted) {
+        throw new MinecraftKitError("LAUNCH_ABORTED", "Install aborted by signal");
+      }
+      await runProcessor({
+        action,
+        javaPath,
+        spawner: input.spawner,
+        ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {},
+        total: processors.length
+      });
+      actionsCompleted++;
+    }
+  }
+  enterPhase(InstallPhases.COMPLETED);
+  return {
+    targetId: input.plan.targetId,
+    bytesDownloaded,
+    actionsCompleted,
+    actionsSkipped,
+    durationMs: Date.now() - startedAt
+  };
+}
+function isDownload(action) {
+  return action.kind === InstallActionKinds.DOWNLOAD_FILE;
+}
+function isNative(action) {
+  return action.kind === InstallActionKinds.EXTRACT_NATIVE;
+}
+function isProcessor(action) {
+  return action.kind === InstallActionKinds.RUN_FORGE_PROCESSOR;
+}
+function isWrite(action) {
+  return action.kind === InstallActionKinds.WRITE_VERSION_JSON || action.kind === InstallActionKinds.WRITE_LOGGING_CONFIG;
+}
+async function runProcessor(input) {
+  const startedAt = Date.now();
+  const classpathSeparator = process.platform === "win32" ? ";" : ":";
+  const args = [
+    "-cp",
+    input.action.classpath.join(classpathSeparator),
+    input.action.mainClass,
+    ...input.action.args
+  ];
+  input.onEvent?.({
+    type: "forge:processor-started",
+    processor: { index: input.action.index, mainClass: input.action.mainClass },
+    total: input.total
+  });
+  const stderrTail = [];
+  const child = input.spawner.spawn(input.javaPath, args, { cwd: process.cwd() });
+  child.stdout.on("data", () => {
+  });
+  child.stderr.on("data", (line) => {
+    if (stderrTail.length >= MAX_PROCESSOR_STDERR_LINES) stderrTail.shift();
+    stderrTail.push(line);
+  });
+  const exit = await child.exited;
+  if (exit.code !== 0) {
+    throw new MinecraftKitError(
+      "FORGE_PROCESSOR_FAILED",
+      `Forge processor exited with code ${exit.code ?? "(signal)"}: ${input.action.mainClass}`,
+      {
+        context: {
+          exitCode: exit.code ?? void 0,
+          mainClass: input.action.mainClass,
+          stderr: stderrTail.join("\n")
+        }
+      }
+    );
+  }
+  input.onEvent?.({
+    type: "forge:processor-completed",
+    processor: { index: input.action.index, mainClass: input.action.mainClass },
+    exitCode: exit.code ?? 0,
+    durationMs: Date.now() - startedAt
+  });
+  for (const [outputPath, expectedSha1] of Object.entries(input.action.outputs)) {
+    const sha1 = await sha1OfFileStreaming(outputPath);
+    if (sha1 !== expectedSha1) {
+      throw new MinecraftKitError(
+        "FORGE_PROCESSOR_FAILED",
+        `Processor output hash mismatch: ${outputPath}`,
+        { context: { filePath: outputPath, expectedHash: expectedSha1, actualHash: sha1 } }
+      );
+    }
+    input.onEvent?.({
+      type: "forge:processor-output-verified",
+      processor: { index: input.action.index, mainClass: input.action.mainClass },
+      path: outputPath
+    });
+  }
+}
+async function sha1OfFileStreaming(filePath) {
+  const hash = crypto2.createHash("sha1");
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", () => resolve());
+    stream.on("error", reject);
+  });
+  return hash.digest("hex");
+}
+
+// src/install/runtime-install.ts
+async function planRuntimeInstall(input) {
+  const runtimePlan = await planRuntimeDownloads({
+    runtime: input.target.runtime,
+    directory: input.target.directory,
+    http: input.http,
+    cache: input.cache,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  const actions = runtimePlan.actions;
+  const totalBytes = runtimePlan.actions.reduce(
+    (sum, action) => sum + (action.expectedSize ?? 0),
+    0
+  );
+  return {
+    targetId: input.target.id,
+    directory: input.target.directory,
+    target: input.target,
+    actions,
+    totalActions: actions.length,
+    totalBytes
+  };
+}
+async function planStandaloneRuntimeInstall(input) {
+  const runtimePlan = await planRuntimeDownloads({
+    runtime: input.runtime,
+    directory: input.directory,
+    http: input.http,
+    cache: input.cache,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  const actions = runtimePlan.actions;
+  const totalBytes = runtimePlan.actions.reduce(
+    (sum, action) => sum + (action.expectedSize ?? 0),
+    0
+  );
+  const target = {
+    id: input.id,
+    directory: input.directory,
+    runtime: input.runtime,
+    minecraft: void 0,
+    loader: void 0
+  };
+  return {
+    targetId: input.id,
+    directory: input.directory,
+    target,
+    actions,
+    totalActions: actions.length,
+    totalBytes
+  };
+}
+
+// src/constants/launch.ts
+var BASE_JVM_ARGS = [
+  "-XX:+UnlockExperimentalVMOptions",
+  "-XX:+UseG1GC",
+  "-XX:G1NewSizePercent=20",
+  "-XX:G1ReservePercent=20",
+  "-XX:MaxGCPauseMillis=50",
+  "-XX:G1HeapRegionSize=32M"
+];
+var LEGACY_JVM_ARGS = [
+  "-Djava.library.path=${natives_directory}",
+  "-Dminecraft.launcher.brand=${launcher_name}",
+  "-Dminecraft.launcher.version=${launcher_version}",
+  "-cp",
+  "${classpath}"
+];
+var MACOS_JVM_ARGS = ["-Xdock:name=Minecraft"];
+
+// src/launch/arguments.ts
+function flattenArguments(entries, context) {
+  const result = [];
+  for (const entry of entries) {
+    if (typeof entry === "string") {
+      result.push(entry);
+      continue;
+    }
+    if (!evaluateRules(entry.rules, context)) continue;
+    if (typeof entry.value === "string") {
+      result.push(entry.value);
+    } else {
+      result.push(...entry.value);
+    }
+  }
+  return result;
+}
+function splitLegacyArguments(raw) {
+  return raw.trim().length === 0 ? [] : raw.trim().split(/\s+/);
+}
+function pickArguments(args, context) {
+  return {
+    game: flattenArguments(args?.game ?? [], context),
+    jvm: flattenArguments(args?.jvm ?? [], context)
+  };
+}
+
+// src/launch/placeholders.ts
+function substituteArg(raw, values) {
+  return raw.replaceAll(/\$\{([a-zA-Z0-9_]+)\}/g, (match, key) => {
+    const value = values[key];
+    if (value === void 0) {
+      throw new MinecraftKitError("INVALID_INPUT", `Unknown launch placeholder: ${match}`, {
+        context: { placeholder: key }
+      });
+    }
+    return value;
+  });
+}
+function substituteArgs(args, values) {
+  return args.map((arg) => substituteArg(arg, values));
+}
+
+// src/launch/args-composition.ts
+function composeArgs(input) {
+  const minMb = input.options.memory?.minMb ?? DEFAULT_MIN_MB;
+  const maxMb = input.options.memory?.maxMb ?? DEFAULT_MAX_MB;
+  const memoryArgs = [`-Xms${minMb}M`, `-Xmx${maxMb}M`];
+  const ruleContext = { system: input.target.runtime.system, features: input.features };
+  let rawJvm;
+  let rawGame;
+  if (input.merged.arguments) {
+    const picked = pickArguments(input.merged.arguments, ruleContext);
+    rawJvm = picked.jvm;
+    rawGame = picked.game;
+  } else if (input.merged.minecraftArguments) {
+    rawJvm = LEGACY_JVM_ARGS;
+    rawGame = splitLegacyArguments(input.merged.minecraftArguments);
+  } else {
+    rawJvm = [];
+    rawGame = [];
+  }
+  const macosArgs = input.target.runtime.system.os === "osx" ? MACOS_JVM_ARGS : [];
+  const baseJvm = [...memoryArgs, ...BASE_JVM_ARGS, ...macosArgs];
+  const substitutedJvm = substituteArgs(rawJvm, input.placeholderValues);
+  const substitutedGame = substituteArgs(rawGame, input.placeholderValues);
+  const jvmArgs = [...baseJvm, ...substitutedJvm];
+  if (input.merged.logging?.client?.argument) {
+    const logging = input.merged.logging.client;
+    const loggingArg = substituteArgs([logging.argument], {
+      ...input.placeholderValues,
+      path: targetPaths.loggingConfig(input.target.directory, logging.file.id)
+    })[0];
+    if (loggingArg !== void 0) jvmArgs.push(loggingArg);
+  }
+  const extraJvm = input.options.extraJvmArgs ?? [];
+  const extraGame = input.options.extraGameArgs ?? [];
+  const gameArgs = [...substitutedGame, ...extraGame];
+  if (input.options.fullscreen === true) gameArgs.push("--fullscreen");
+  if (input.options.resolution !== void 0 && rawGame.every((a) => !a.includes("--width"))) {
+    gameArgs.push(
+      "--width",
+      input.options.resolution.width.toString(),
+      "--height",
+      input.options.resolution.height.toString()
+    );
+  }
+  return { jvmArgs: [...jvmArgs, ...extraJvm], gameArgs };
+}
+function buildClasspath(input) {
+  const seen = /* @__PURE__ */ new Set();
+  const entries = [];
+  for (const library of input.merged.libraries) {
+    if (library.natives) continue;
+    if (!evaluateRules(library.rules, { system: input.system })) continue;
+    const relative = relativeFor(library);
+    if (!relative) continue;
+    const absolute = path.join(targetPaths.librariesDir(input.directory), relative);
+    if (seen.has(absolute)) continue;
+    seen.add(absolute);
+    entries.push(absolute);
+  }
+  const versionJar = targetPaths.versionJar(input.directory, input.versionId);
+  if (!seen.has(versionJar)) entries.push(versionJar);
+  return entries;
+}
+function relativeFor(library) {
+  if (library.downloads?.artifact?.path) return library.downloads.artifact.path;
+  if (library.name) {
+    const coord = parseMavenCoordinate(library.name);
+    return mavenRelativePath(coord);
+  }
+  return null;
+}
+function offlineUuidFor(username) {
+  const md5 = crypto2.createHash("md5");
+  md5.update(`OfflinePlayer:${username}`, "utf8");
+  const bytes = md5.digest();
+  bytes[6] = (bytes[6] ?? 0) & 15 | 48;
+  bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+  return formatUuid(bytes);
+}
+function formatUuid(bytes) {
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function stripUuidDashes(uuid) {
+  return uuid.replaceAll("-", "");
+}
+
+// src/types/auth.ts
+var AuthModes = {
+  /** Offline-mode play with a chosen username and synthetic UUID. */
+  OFFLINE: "offline",
+  /** Pre-authenticated session — caller provides the access token and identity. */
+  ONLINE: "online"
+};
+
+// src/launch/placeholder-values.ts
+function buildPlaceholderValues(input) {
+  const cpSeparator = process.platform === "win32" ? ";" : ":";
+  const directory = input.target.directory;
+  const username = input.auth.username;
+  const uuid = input.auth.mode === AuthModes.OFFLINE ? input.auth.uuid ?? offlineUuidFor(username) : input.auth.uuid;
+  const accessToken = input.auth.mode === AuthModes.OFFLINE ? "0" : input.auth.accessToken;
+  const userType = input.auth.mode === AuthModes.OFFLINE ? "legacy" : input.auth.userType ?? "msa";
+  const launcherName = input.options.launcherName ?? DEFAULT_LAUNCHER_NAME;
+  const launcherVersion = input.options.launcherVersion ?? DEFAULT_LAUNCHER_VERSION;
+  return {
+    auth_player_name: username,
+    version_name: input.versionId,
+    game_directory: directory,
+    assets_root: path.join(directory, ASSETS_DIR),
+    assets_index_name: input.target.minecraft.manifest.assets,
+    auth_uuid: stripUuidDashes(uuid),
+    auth_access_token: accessToken,
+    auth_session: `token:${accessToken}:${stripUuidDashes(uuid)}`,
+    clientid: input.auth.mode === AuthModes.ONLINE ? input.auth.clientId ?? "" : "",
+    auth_xuid: input.auth.mode === AuthModes.ONLINE ? input.auth.xuid ?? "" : "",
+    user_type: userType,
+    user_properties: "{}",
+    version_type: input.target.minecraft.channel,
+    game_assets: path.join(directory, ASSETS_LEGACY_DIR),
+    natives_directory: targetPaths.nativesDir(directory, input.target.minecraft.version),
+    classpath: input.classpath.join(cpSeparator),
+    classpath_separator: cpSeparator,
+    library_directory: path.join(directory, LIBRARIES_DIR),
+    launcher_name: launcherName,
+    launcher_version: launcherVersion,
+    resolution_width: input.options.resolution?.width.toString() ?? "",
+    resolution_height: input.options.resolution?.height.toString() ?? ""
+  };
+}
+
+// src/core/manifest-merge.ts
+function mergeManifest(parent, child) {
+  const merged = {
+    id: child.id || parent.id,
+    type: child.type ?? parent.type,
+    mainClass: child.mainClass ?? parent.mainClass,
+    assetIndex: child.assetIndex ?? parent.assetIndex,
+    assets: child.assets ?? parent.assets,
+    downloads: { ...parent.downloads, ...child.downloads },
+    libraries: mergeLibraries(parent.libraries, child.libraries),
+    arguments: mergeArguments(parent.arguments, child.arguments),
+    minecraftArguments: child.minecraftArguments ?? parent.minecraftArguments,
+    javaVersion: child.javaVersion ?? parent.javaVersion,
+    logging: child.logging ?? parent.logging,
+    inheritsFrom: child.inheritsFrom ?? parent.inheritsFrom,
+    releaseTime: child.releaseTime ?? parent.releaseTime,
+    time: child.time ?? parent.time,
+    minimumLauncherVersion: child.minimumLauncherVersion ?? parent.minimumLauncherVersion,
+    complianceLevel: child.complianceLevel ?? parent.complianceLevel
+  };
+  return merged;
+}
+function mergeLibraries(parent, child) {
+  return [...parent, ...child];
+}
+function mergeArguments(parent, child) {
+  if (!parent && !child) return void 0;
+  const parentGame = parent?.game ?? [];
+  const parentJvm = parent?.jvm ?? [];
+  const childGame = child?.game ?? [];
+  const childJvm = child?.jvm ?? [];
+  return {
+    game: [...parentGame, ...childGame],
+    jvm: [...parentJvm, ...childJvm]
+  };
+}
+
+// src/launch/version-resolution.ts
+async function resolveLaunchVersion(target) {
+  if (target.loader.type === Loaders.VANILLA) {
+    return {
+      versionId: target.minecraft.version,
+      merged: target.minecraft.manifest,
+      chain: [target.minecraft.version]
+    };
+  }
+  const versionId = await pickInstalledVersionId(target);
+  const merged = await loadAndMerge(target.directory, versionId, target.minecraft.manifest);
+  return { versionId, merged, chain: [versionId, target.minecraft.version] };
+}
+async function pickClientJarVersionId(directory, chain) {
+  for (const id of chain) {
+    const jar = targetPaths.versionJar(directory, id);
+    if (await fileExists(jar)) return id;
+  }
+  const fallback = chain.at(-1);
+  if (fallback === void 0) {
+    throw new MinecraftKitError(
+      "MANIFEST_NOT_FOUND",
+      "Cannot resolve a client jar version id from an empty inheritsFrom chain"
+    );
+  }
+  return fallback;
+}
+async function pickInstalledVersionId(target) {
+  if (target.loader.type === Loaders.FABRIC) {
+    const candidate = target.loader.profile.id;
+    const versionJsonPath = targetPaths.versionJson(target.directory, candidate);
+    if (await fileExists(versionJsonPath)) return candidate;
+  }
+  if (target.loader.type === Loaders.FORGE) {
+    const directories = await listChildDirectories(targetPaths.versionsDir(target.directory));
+    for (const id of directories) {
+      const versionJsonPath = targetPaths.versionJson(target.directory, id);
+      if (!await fileExists(versionJsonPath)) continue;
+      const text = await readText(versionJsonPath);
+      try {
+        const parsed = JSON.parse(text);
+        if (parsed.inheritsFrom === target.minecraft.version && (id.includes("forge") || (parsed.id ?? "").includes("forge"))) {
+          return id;
+        }
+      } catch {
+      }
+    }
+  }
+  throw new MinecraftKitError(
+    "MANIFEST_NOT_FOUND",
+    `Could not find an installed version JSON for target ${target.id}`,
+    { context: { targetId: target.id, loaderType: target.loader.type } }
+  );
+}
+async function loadAndMerge(directory, versionId, parentManifest) {
+  const versionJsonPath = targetPaths.versionJson(directory, versionId);
+  const text = await readText(versionJsonPath);
+  let child;
+  try {
+    child = JSON.parse(text);
+  } catch (cause) {
+    throw new MinecraftKitError(
+      "MANIFEST_INVALID",
+      `Version JSON is not valid JSON: ${versionJsonPath}`,
+      { cause, context: { filePath: versionJsonPath } }
+    );
+  }
+  if (child.inheritsFrom !== void 0 && child.inheritsFrom !== parentManifest.id) {
+    return mergeManifest(parentManifest, child);
+  }
+  return mergeManifest(parentManifest, child);
+}
+
+// src/launch/compose.ts
+async function composeLaunch(input) {
+  const { target, options } = input;
+  if (!options.auth.username || options.auth.username.length === 0) {
+    throw new MinecraftKitError(
+      "INVALID_INPUT",
+      `Auth username must be non-empty (target ${target.id})`,
+      { context: { targetId: target.id } }
+    );
+  }
+  const resolved = await resolveLaunchVersion(target);
+  const javaPath = targetPaths.runtimeJavaExecutable(
+    target.directory,
+    target.runtime.component,
+    target.runtime.system.os,
+    target.runtime.installRoot
+  );
+  const clientJarVersionId = await pickClientJarVersionId(target.directory, resolved.chain);
+  const classpath = buildClasspath({
+    directory: target.directory,
+    versionId: clientJarVersionId,
+    merged: resolved.merged,
+    system: target.runtime.system
+  });
+  const features = buildFeatures(options);
+  const placeholderValues = buildPlaceholderValues({
+    target,
+    versionId: resolved.versionId,
+    auth: options.auth,
+    classpath,
+    options
+  });
+  const composed = composeArgs({
+    target,
+    merged: resolved.merged,
+    options,
+    placeholderValues,
+    features
+  });
+  return {
+    targetId: target.id,
+    directory: target.directory,
+    javaPath,
+    mainClass: resolved.merged.mainClass,
+    jvmArgs: composed.jvmArgs,
+    gameArgs: composed.gameArgs,
+    classpath,
+    nativesDirectory: targetPaths.nativesDir(target.directory, target.minecraft.version),
+    auth: options.auth,
+    workingDirectory: target.directory
+  };
+}
+function buildFeatures(options) {
+  const features = { ...options.features ?? {} };
+  if (options.resolution !== void 0) {
+    features.has_custom_resolution = true;
+  }
+  return features;
+}
+
+// src/launch/runner.ts
+function runLaunch(input) {
+  const composition = input.composition;
+  const options = input.options ?? {};
+  const args = [...composition.jvmArgs, composition.mainClass, ...composition.gameArgs];
+  options.onEvent?.({
+    type: "launch:starting",
+    command: composition.javaPath,
+    args,
+    cwd: composition.workingDirectory
+  });
+  const child = input.spawner.spawn(composition.javaPath, args, {
+    cwd: composition.workingDirectory,
+    ...composition.env !== void 0 ? { env: composition.env } : {}
+  });
+  options.onEvent?.({ type: "launch:started", pid: child.pid });
+  child.stdout.on("data", (line) => {
+    options.onEvent?.({ type: "launch:stdout", line });
+  });
+  child.stderr.on("data", (line) => {
+    options.onEvent?.({ type: "launch:stderr", line });
+  });
+  const grace = options.killGracePeriodMs ?? DEFAULT_KILL_GRACE_MS;
+  let aborted = false;
+  const doAbort = (reason) => {
+    if (aborted) return;
+    aborted = true;
+    options.onEvent?.({ type: "launch:aborted", reason });
+    child.kill("SIGTERM");
+    setTimeout(() => child.kill("SIGKILL"), grace).unref();
+  };
+  if (options.signal !== void 0) {
+    if (options.signal.aborted) {
+      doAbort(reasonFrom(options.signal.reason));
+    } else {
+      options.signal.addEventListener("abort", () => doAbort(reasonFrom(options.signal?.reason)), {
+        once: true
+      });
+    }
+  }
+  const exited = (async () => {
+    const { code, signal } = await child.exited;
+    options.onEvent?.({ type: "launch:exited", code, signal });
+    if (!aborted && code !== 0 && code !== null) {
+      throw new MinecraftKitError(
+        "LAUNCH_PROCESS_FAILED",
+        `Minecraft process exited with code ${code}`,
+        { context: { exitCode: code } }
+      );
+    }
+    return { code, signal, aborted };
+  })();
+  return {
+    pid: child.pid,
+    exited,
+    abort(reason) {
+      doAbort(reason ?? "user");
+    }
+  };
+}
+function reasonFrom(value) {
+  if (value === void 0) return "aborted";
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return value.message;
+  return String(value);
+}
+var ChildProcessSpawner = class {
+  spawn(command, args, options) {
+    const child = spawn(command, [...args], {
+      cwd: options.cwd,
+      env: options.env === void 0 ? process.env : { ...process.env, ...options.env },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdout = streamFromBuffer(child.stdout);
+    const stderr = streamFromBuffer(child.stderr);
+    const exited = new Promise((resolve) => {
+      child.once("exit", (code, signal) => resolve({ code, signal }));
+    });
+    return {
+      pid: child.pid ?? -1,
+      stdout,
+      stderr,
+      exited,
+      kill(signal) {
+        return child.kill(signal);
+      }
+    };
+  }
+};
+function streamFromBuffer(stream) {
+  if (!stream) {
+    return { on() {
+    } };
+  }
+  let buffer = "";
+  const listeners = /* @__PURE__ */ new Set();
+  const emit = (line) => {
+    for (const listener of listeners) listener(line);
+  };
+  stream.on("data", (chunk) => {
+    const text = Buffer$1.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+    buffer += text;
+    let index = buffer.indexOf("\n");
+    while (index !== -1) {
+      const line = buffer.slice(0, index).replace(/\r$/, "");
+      buffer = buffer.slice(index + 1);
+      emitBounded(emit, line);
+      index = buffer.indexOf("\n");
+    }
+    while (buffer.length > SPAWNER_MAX_LINE_BYTES) {
+      emit(buffer.slice(0, SPAWNER_MAX_LINE_BYTES));
+      buffer = buffer.slice(SPAWNER_MAX_LINE_BYTES);
+    }
+  });
+  stream.on("end", () => {
+    if (buffer.length > 0) {
+      emitBounded(emit, buffer);
+      buffer = "";
+    }
+  });
+  return {
+    on(_event, listener) {
+      listeners.add(listener);
+    }
+  };
+}
+function emitBounded(emit, line) {
+  if (line.length <= SPAWNER_MAX_LINE_BYTES) {
+    emit(line);
+    return;
+  }
+  for (let i = 0; i < line.length; i += SPAWNER_MAX_LINE_BYTES) {
+    emit(line.slice(i, i + SPAWNER_MAX_LINE_BYTES));
+  }
+}
+
+// src/types/verify.ts
+var VerificationKinds = {
+  MINECRAFT: "minecraft",
+  FABRIC: "fabric",
+  FORGE: "forge",
+  RUNTIME: "runtime"
+};
+var VerifyFileStatuses = {
+  OK: "ok",
+  MISSING: "missing",
+  CORRUPT: "corrupt",
+  WRONG_SIZE: "wrong-size"
+};
+var VerifyFileCategories = {
+  CLIENT_JAR: "client-jar",
+  LIBRARY: "library",
+  ASSET: "asset",
+  ASSET_INDEX: "asset-index",
+  NATIVE: "native",
+  LOADER_LIBRARY: "loader-library",
+  RUNTIME_FILE: "runtime-file",
+  LOGGING_CONFIG: "logging-config"
+};
+
+// src/repair/helpers.ts
+function asResultArray(from) {
+  return Array.isArray(from) ? from : [from];
+}
+function buildIssueIndex(from) {
+  const map = /* @__PURE__ */ new Map();
+  for (const v of asResultArray(from)) {
+    for (const issue of v.issues) {
+      const set = map.get(issue.path);
+      if (set) set.add(issue.category);
+      else map.set(issue.path, /* @__PURE__ */ new Set([issue.category]));
+    }
+  }
+  return {
+    has: (path16) => map.has(path16),
+    hasNonNative: (path16) => {
+      const cats = map.get(path16);
+      if (!cats) return false;
+      for (const c of cats) {
+        if (c !== VerifyFileCategories.NATIVE) return true;
+      }
+      return false;
+    },
+    categoriesAt: (path16) => map.get(path16) ?? /* @__PURE__ */ new Set()
+  };
+}
+function sumDownloadBytes(actions) {
+  return actions.reduce((sum, action) => {
+    if (action.kind === InstallActionKinds.DOWNLOAD_FILE) {
+      return sum + (action.expectedSize ?? 0);
+    }
+    return sum;
+  }, 0);
+}
+function buildRepairPlan(target, actions) {
+  return {
+    targetId: target.id,
+    directory: target.directory,
+    target,
+    actions,
+    totalActions: actions.length,
+    totalBytes: sumDownloadBytes(actions)
+  };
+}
+async function planAspectRepair(input, aspectFilter, postprocess) {
+  const installPlan = await planInstall({
+    target: input.target,
+    http: input.http,
+    cache: input.cache,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+  const issues = buildIssueIndex(input.from);
+  const actions = selectRepairActions({
+    target: input.target,
+    installPlan,
+    issues,
+    aspectFilter
+  });
+  postprocess?.({ actions, installPlan, issues });
+  return buildRepairPlan(input.target, actions);
+}
+function selectRepairActions(input) {
+  const matching = [];
+  for (const action of input.installPlan.actions) {
+    if (!input.aspectFilter(action)) continue;
+    if (action.kind === InstallActionKinds.DOWNLOAD_FILE) {
+      if (input.issues.hasNonNative(action.target)) {
+        matching.push(action);
+      }
+    } else if (action.kind === InstallActionKinds.WRITE_VERSION_JSON) {
+      if (input.issues.has(action.path)) {
+        matching.push(action);
+      }
+    } else if (action.kind === InstallActionKinds.EXTRACT_NATIVE) {
+      if (input.issues.has(action.source)) {
+        matching.push(action);
+      }
+    } else {
+      matching.push(action);
+    }
+  }
+  return matching;
+}
+
+// src/repair/fabric.ts
+async function planFabricRepair(input) {
+  if (input.target.loader.type !== Loaders.FABRIC) {
+    throw new MinecraftKitError(
+      "INVALID_INPUT",
+      `repair.fabric requires a Fabric target (got ${input.target.loader.type})`
+    );
+  }
+  const fabricJsonPath = targetPaths.versionJson(
+    input.target.directory,
+    input.target.loader.profile.id
+  );
+  return planAspectRepair(input, (action) => {
+    if (action.kind === InstallActionKinds.DOWNLOAD_FILE) {
+      return action.category === "fabric-library";
+    }
+    if (action.kind === InstallActionKinds.WRITE_VERSION_JSON) {
+      return action.path === fabricJsonPath;
+    }
+    return false;
+  });
+}
+
+// src/repair/forge.ts
+var FORGE_DOWNLOAD_CATEGORIES = /* @__PURE__ */ new Set([
+  "forge-library",
+  "forge-installer"
+]);
+async function planForgeRepair(input) {
+  if (input.target.loader.type !== Loaders.FORGE) {
+    throw new MinecraftKitError(
+      "INVALID_INPUT",
+      `repair.forge requires a Forge target (got ${input.target.loader.type})`
+    );
+  }
+  const forgeJsonPath = targetPaths.versionJson(
+    input.target.directory,
+    input.target.loader.fullVersion
+  );
+  return planAspectRepair(
+    input,
+    (action) => {
+      if (action.kind === InstallActionKinds.DOWNLOAD_FILE) {
+        return FORGE_DOWNLOAD_CATEGORIES.has(action.category);
+      }
+      if (action.kind === InstallActionKinds.WRITE_VERSION_JSON) {
+        return action.path === forgeJsonPath;
+      }
+      return false;
+    },
+    ({ actions, installPlan, issues }) => {
+      if (!issues.has(forgeJsonPath)) return;
+      const alreadyIncluded = new Set(
+        actions.filter((a) => a.kind === InstallActionKinds.DOWNLOAD_FILE).map((a) => a.target)
+      );
+      for (const action of installPlan.actions) {
+        if (action.kind === InstallActionKinds.DOWNLOAD_FILE && action.category === "forge-library" && !alreadyIncluded.has(action.target)) {
+          actions.push(action);
+        } else if (action.kind === InstallActionKinds.RUN_FORGE_PROCESSOR) {
+          actions.push(action);
+        }
+      }
+    }
+  );
+}
+
+// src/repair/minecraft.ts
+var MINECRAFT_DOWNLOAD_CATEGORIES = /* @__PURE__ */ new Set([
+  "client-jar",
+  "library",
+  "asset-index",
+  "asset",
+  "logging-config"
+]);
+async function planMinecraftRepair(input) {
+  const vanillaJsonPath = targetPaths.versionJson(
+    input.target.directory,
+    input.target.minecraft.version
+  );
+  return planAspectRepair(input, (action) => {
+    if (action.kind === InstallActionKinds.DOWNLOAD_FILE) {
+      return MINECRAFT_DOWNLOAD_CATEGORIES.has(action.category);
+    }
+    if (action.kind === InstallActionKinds.WRITE_VERSION_JSON) {
+      return action.path === vanillaJsonPath;
+    }
+    if (action.kind === InstallActionKinds.EXTRACT_NATIVE) {
+      return true;
+    }
+    return false;
+  });
+}
+
+// src/repair/runner.ts
+async function runRepair(input) {
+  const report = await runInstall({
+    plan: {
+      ...input.plan,
+      totalActions: input.plan.actions.length,
+      totalBytes: input.plan.totalBytes
+    },
+    http: input.http,
+    cache: input.cache,
+    spawner: input.spawner,
+    ...input.signal !== void 0 ? { signal: input.signal } : {},
+    ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+  });
+  return {
+    targetId: report.targetId,
+    bytesDownloaded: report.bytesDownloaded,
+    actionsCompleted: report.actionsCompleted,
+    durationMs: report.durationMs
+  };
+}
+
+// src/repair/runtime.ts
+async function planRuntimeRepair(input) {
+  return planAspectRepair(
+    input,
+    (action) => action.kind === InstallActionKinds.DOWNLOAD_FILE && action.category === "runtime-file"
+  );
+}
+
+// src/types/runtime.ts
+var RuntimeComponents = {
+  JRE_LEGACY: "jre-legacy"};
+var RuntimePreference = {
+  /** Component declared by the Minecraft manifest. */
+  RECOMMENDED: "recommended",
+  /** Newest component available for the platform. */
+  LATEST: "latest"
+};
+
+// src/targets/index.ts
+var TargetsApi = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** The detected host system used by `resolve()` when no `system` is supplied. */
+  get system() {
+    return this.ctx.system;
+  }
+  /** Build a {@link Target} from already-resolved components. */
+  create(input) {
+    if (!input.id) {
+      throw new MinecraftKitError("INVALID_INPUT", "Target id must be non-empty");
+    }
+    if (!input.directory) {
+      throw new MinecraftKitError("INVALID_INPUT", "Target directory must be non-empty");
+    }
+    if (input.loader.minecraftVersion !== input.minecraft.version) {
+      throw new MinecraftKitError(
+        "INVALID_INPUT",
+        `Loader Minecraft version (${input.loader.minecraftVersion}) does not match resolved Minecraft (${input.minecraft.version})`,
+        {
+          context: {
+            loaderMinecraft: input.loader.minecraftVersion,
+            minecraftVersion: input.minecraft.version
+          }
+        }
+      );
+    }
+    return {
+      id: input.id,
+      directory: input.directory,
+      minecraft: input.minecraft,
+      loader: input.loader,
+      runtime: input.runtime
+    };
+  }
+  /** Sugar API: resolve every component then assemble a target. */
+  async resolve(input) {
+    const minecraft = await this.ctx.minecraft.resolve({
+      version: input.minecraft.version,
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    const system = input.system ?? this.ctx.system;
+    const componentOverride = input.runtime?.component;
+    const runtimeComponent = componentOverride ?? minecraft.manifest.javaVersion?.component;
+    const resolvedRuntime = await this.ctx.runtime.resolve({
+      system,
+      ...runtimeComponent !== void 0 ? { component: runtimeComponent } : {},
+      preference: input.runtime?.preference ?? RuntimePreference.RECOMMENDED,
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    const runtime = input.runtime?.installRoot !== void 0 ? { ...resolvedRuntime, installRoot: input.runtime.installRoot } : resolvedRuntime;
+    let loader;
+    if (input.loader.type === Loaders.VANILLA) {
+      loader = {
+        type: Loaders.VANILLA,
+        minecraftVersion: minecraft.version,
+        minecraft
+      };
+    } else if (input.loader.type === Loaders.FABRIC) {
+      loader = await this.ctx.fabric.resolve({
+        minecraftVersion: minecraft.version,
+        ...input.loader.preference !== void 0 ? { preference: input.loader.preference } : {},
+        ...input.loader.version !== void 0 ? { loaderVersion: input.loader.version } : {},
+        ...input.signal !== void 0 ? { signal: input.signal } : {}
+      });
+    } else {
+      loader = await this.ctx.forge.resolve({
+        minecraftVersion: minecraft.version,
+        ...input.loader.preference !== void 0 ? { preference: input.loader.preference } : {},
+        ...input.loader.version !== void 0 ? { forgeVersion: input.loader.version } : {},
+        ...input.signal !== void 0 ? { signal: input.signal } : {}
+      });
+    }
+    return this.create({
+      id: input.id,
+      directory: input.directory,
+      minecraft,
+      loader,
+      runtime
+    });
+  }
+  /** Scan a root directory for Minecraft installations. Returns only what is on disk. */
+  async list(input) {
+    if (!await dirExists(input.rootDir)) return [];
+    const subdirs = await listChildDirectories(input.rootDir);
+    const results = [];
+    for (const id of subdirs) {
+      const directory = path.join(input.rootDir, id);
+      const discovered = await discoverInstallation(id, directory);
+      if (discovered) results.push(discovered);
+    }
+    return results;
+  }
+};
+async function discoverInstallation(id, directory) {
+  const versionsDir = path.join(directory, VERSIONS_DIR);
+  const librariesDir = path.join(directory, LIBRARIES_DIR);
+  const assetsDir = path.join(directory, ASSETS_DIR);
+  const looksLikeInstall = await dirExists(versionsDir) && (await dirExists(librariesDir) || await dirExists(assetsDir));
+  if (!looksLikeInstall) return null;
+  const versionDirs = await listChildDirectories(versionsDir);
+  const minecraftVersions = [];
+  const loaders = [];
+  for (const versionId of versionDirs) {
+    const hint = inferLoaderFromVersionId(versionId);
+    if (hint) {
+      loaders.push(hint);
+      if (hint.minecraftVersion && !minecraftVersions.includes(hint.minecraftVersion)) {
+        minecraftVersions.push(hint.minecraftVersion);
+      }
+    } else {
+      minecraftVersions.push(versionId);
+    }
+  }
+  const runtime = await discoverRuntime(directory);
+  return { id, directory, minecraftVersions, loaders, ...runtime ? { runtime } : {} };
+}
+async function discoverRuntime(directory) {
+  const runtimeDir = path.join(directory, RUNTIMES_DIR);
+  if (!await dirExists(runtimeDir)) return void 0;
+  let components;
+  try {
+    components = await listChildDirectories(runtimeDir);
+  } catch {
+    return void 0;
+  }
+  for (const component of components) {
+    const root = path.join(runtimeDir, component);
+    const javaPath = process.platform === "win32" ? path.join(root, "bin", "javaw.exe") : process.platform === "darwin" ? path.join(root, "jre.bundle", "Contents", "Home", "bin", "java") : path.join(root, "bin", "java");
+    if (await fileExists(javaPath)) {
+      return { component, javaPath };
+    }
+  }
+  return void 0;
+}
+function inferLoaderFromVersionId(versionId) {
+  const fabricMatch = /^fabric-loader-([^-]+)-(.+)$/.exec(versionId);
+  if (fabricMatch?.[1] && fabricMatch[2]) {
+    return { type: Loaders.FABRIC, version: fabricMatch[1], minecraftVersion: fabricMatch[2] };
+  }
+  const forgeMatch = /^([^-]+)-forge-(.+)$/.exec(versionId);
+  if (forgeMatch?.[1] && forgeMatch[2]) {
+    return { type: Loaders.FORGE, minecraftVersion: forgeMatch[1], version: forgeMatch[2] };
+  }
+  return null;
+}
+
+// src/update/runner.ts
+async function planUpdate(input) {
+  return planInstall({
+    target: input.target,
+    http: input.http,
+    cache: input.cache,
+    ...input.signal !== void 0 ? { signal: input.signal } : {}
+  });
+}
+async function runUpdate(input) {
+  const report = await runInstall({
+    plan: input.plan,
+    http: input.http,
+    cache: input.cache,
+    spawner: input.spawner,
+    ...input.signal !== void 0 ? { signal: input.signal } : {},
+    ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+  });
+  return {
+    targetId: report.targetId,
+    bytesDownloaded: report.bytesDownloaded,
+    actionsCompleted: report.actionsCompleted,
+    actionsSkipped: report.actionsSkipped,
+    durationMs: report.durationMs
+  };
+}
+async function sha1OfFile(filePath) {
+  const hash = crypto2.createHash("sha1");
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", resolve);
+    stream.on("error", reject);
+  });
+  return hash.digest("hex");
+}
+
+// src/verify/helpers.ts
+async function runVerification(input, check) {
+  const startedAt = Date.now();
+  const results = [];
+  const record = (result) => {
+    results.push(result);
+    input.onEvent?.({ type: "verify:file-checked", file: result });
+  };
+  await check(record);
+  return {
+    targetId: input.targetId,
+    kind: input.kind,
+    isValid: results.every((r) => r.status === VerifyFileStatuses.OK),
+    issues: results.filter((r) => r.status !== VerifyFileStatuses.OK),
+    checkedFiles: results.length,
+    durationMs: Date.now() - startedAt
+  };
+}
+async function verifyHashedFile(input) {
+  if (!await fileExists(input.path)) {
+    return {
+      path: input.path,
+      category: input.category,
+      status: VerifyFileStatuses.MISSING,
+      ...input.expectedSha1 !== void 0 ? { expectedSha1: input.expectedSha1 } : {},
+      ...input.expectedSize !== void 0 ? { expectedSize: input.expectedSize } : {},
+      ...input.url !== void 0 ? { url: input.url } : {}
+    };
+  }
+  if (input.expectedSize !== void 0) {
+    const size = await fileSize(input.path);
+    if (size !== input.expectedSize) {
+      return {
+        path: input.path,
+        category: input.category,
+        status: VerifyFileStatuses.WRONG_SIZE,
+        expectedSize: input.expectedSize,
+        actualSize: size,
+        ...input.expectedSha1 !== void 0 ? { expectedSha1: input.expectedSha1 } : {},
+        ...input.url !== void 0 ? { url: input.url } : {}
+      };
+    }
+  }
+  if (input.expectedSha1 !== void 0) {
+    const actualSha1 = await sha1OfFile(input.path);
+    if (actualSha1 !== input.expectedSha1) {
+      return {
+        path: input.path,
+        category: input.category,
+        status: VerifyFileStatuses.CORRUPT,
+        expectedSha1: input.expectedSha1,
+        actualSha1,
+        ...input.expectedSize !== void 0 ? { expectedSize: input.expectedSize } : {},
+        ...input.url !== void 0 ? { url: input.url } : {}
+      };
+    }
+  }
+  return {
+    path: input.path,
+    category: input.category,
+    status: VerifyFileStatuses.OK,
+    ...input.expectedSha1 !== void 0 ? { expectedSha1: input.expectedSha1 } : {},
+    ...input.expectedSize !== void 0 ? { expectedSize: input.expectedSize } : {},
+    ...input.url !== void 0 ? { url: input.url } : {}
+  };
+}
+async function verifyExistence(input) {
+  if (await fileExists(input.path)) {
+    return {
+      path: input.path,
+      category: input.category,
+      status: VerifyFileStatuses.OK,
+      ...input.url !== void 0 ? { url: input.url } : {}
+    };
+  }
+  return {
+    path: input.path,
+    category: input.category,
+    status: VerifyFileStatuses.MISSING,
+    ...input.url !== void 0 ? { url: input.url } : {}
+  };
+}
+async function findForgeVersionJsonPath(directory, minecraftVersion) {
+  const versionsDir = targetPaths.versionsDir(directory);
+  const dirs = await listChildDirectories(versionsDir);
+  for (const id of dirs) {
+    if (!id.startsWith(`${minecraftVersion}-forge-`)) continue;
+    const jsonPath = targetPaths.versionJson(directory, id);
+    if (!await fileExists(jsonPath)) {
+      return jsonPath;
+    }
+    const parsed = await tryParseInheritsFrom(jsonPath);
+    if (parsed === minecraftVersion) return jsonPath;
+  }
+  return null;
+}
+async function tryParseInheritsFrom(jsonPath) {
+  try {
+    const parsed = JSON.parse(await readText(jsonPath));
+    return parsed.inheritsFrom;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/verify/fabric.ts
+async function verifyFabric(input) {
+  if (input.target.loader.type !== Loaders.FABRIC) {
+    throw new MinecraftKitError(
+      "INVALID_INPUT",
+      `verify.fabric requires a Fabric target (got ${input.target.loader.type})`
+    );
+  }
+  const loader = input.target.loader;
+  return runVerification(
+    {
+      targetId: input.target.id,
+      kind: VerificationKinds.FABRIC,
+      ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+    },
+    async (record) => {
+      record(
+        await verifyExistence({
+          path: targetPaths.versionJson(input.target.directory, loader.profile.id),
+          category: VerifyFileCategories.LOADER_LIBRARY
+        })
+      );
+      const fabricLibraries = planLibraryDownloads({
+        libraries: loader.profile.libraries,
+        directory: input.target.directory,
+        system: input.target.runtime.system,
+        versionId: input.target.minecraft.version,
+        category: "fabric-library"
+      });
+      for (const action of fabricLibraries.downloads) {
+        record(
+          await verifyHashedFile({
+            path: action.target,
+            expectedSha1: action.expectedSha1,
+            expectedSize: action.expectedSize,
+            ...action.url ? { url: action.url } : {},
+            category: VerifyFileCategories.LOADER_LIBRARY
+          })
+        );
+      }
+    }
+  );
+}
+
+// src/verify/forge.ts
+async function verifyForge(input) {
+  if (input.target.loader.type !== Loaders.FORGE) {
+    throw new MinecraftKitError(
+      "INVALID_INPUT",
+      `verify.forge requires a Forge target (got ${input.target.loader.type})`
+    );
+  }
+  return runVerification(
+    {
+      targetId: input.target.id,
+      kind: VerificationKinds.FORGE,
+      ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+    },
+    async (record) => {
+      const forgeVersionJsonPath = await findForgeVersionJsonPath(
+        input.target.directory,
+        input.target.minecraft.version
+      );
+      if (forgeVersionJsonPath === null) return;
+      record(
+        await verifyExistence({
+          path: forgeVersionJsonPath,
+          category: VerifyFileCategories.LOADER_LIBRARY
+        })
+      );
+      if (!await fileExists(forgeVersionJsonPath)) return;
+      let parsed;
+      try {
+        parsed = JSON.parse(await readText(forgeVersionJsonPath));
+      } catch {
+        record({
+          path: forgeVersionJsonPath,
+          category: VerifyFileCategories.LOADER_LIBRARY,
+          status: VerifyFileStatuses.CORRUPT
+        });
+        return;
+      }
+      const forgeLibraries = planLibraryDownloads({
+        libraries: parsed.libraries,
+        directory: input.target.directory,
+        system: input.target.runtime.system,
+        versionId: input.target.minecraft.version,
+        category: "forge-library"
+      });
+      for (const action of forgeLibraries.downloads) {
+        record(
+          await verifyHashedFile({
+            path: action.target,
+            expectedSha1: action.expectedSha1,
+            expectedSize: action.expectedSize,
+            ...action.url ? { url: action.url } : {},
+            category: VerifyFileCategories.LOADER_LIBRARY
+          })
+        );
+      }
+    }
+  );
+}
+
+// src/verify/minecraft.ts
+async function verifyMinecraft(input) {
+  return runVerification(
+    {
+      targetId: input.target.id,
+      kind: VerificationKinds.MINECRAFT,
+      ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+    },
+    async (record) => {
+      const { directory, minecraft, runtime } = input.target;
+      record(
+        await verifyHashedFile({
+          path: targetPaths.versionJar(directory, minecraft.version),
+          expectedSha1: minecraft.manifest.downloads.client.sha1,
+          expectedSize: minecraft.manifest.downloads.client.size,
+          url: minecraft.manifest.downloads.client.url,
+          category: VerifyFileCategories.CLIENT_JAR
+        })
+      );
+      record(
+        await verifyExistence({
+          path: targetPaths.versionJson(directory, minecraft.version),
+          category: VerifyFileCategories.CLIENT_JAR
+        })
+      );
+      if (minecraft.manifest.logging?.client) {
+        const logging = minecraft.manifest.logging.client;
+        record(
+          await verifyHashedFile({
+            path: targetPaths.loggingConfig(directory, logging.file.id),
+            expectedSha1: logging.file.sha1,
+            expectedSize: logging.file.size,
+            url: logging.file.url,
+            category: VerifyFileCategories.LOGGING_CONFIG
+          })
+        );
+      }
+      const libraryPlan = planLibraryDownloads({
+        libraries: minecraft.manifest.libraries,
+        directory,
+        system: runtime.system,
+        versionId: minecraft.version,
+        category: "library"
+      });
+      for (const action of libraryPlan.downloads) {
+        record(
+          await verifyHashedFile({
+            path: action.target,
+            expectedSha1: action.expectedSha1,
+            expectedSize: action.expectedSize,
+            url: action.url,
+            category: VerifyFileCategories.LIBRARY
+          })
+        );
+      }
+      const indexUrl = minecraft.manifest.assetIndex.url;
+      const indexPath = targetPaths.assetIndex(directory, minecraft.manifest.assetIndex.id);
+      record(
+        await verifyHashedFile({
+          path: indexPath,
+          expectedSha1: minecraft.manifest.assetIndex.sha1,
+          expectedSize: minecraft.manifest.assetIndex.size,
+          url: indexUrl,
+          category: VerifyFileCategories.ASSET_INDEX
+        })
+      );
+      const indexDocument = await fetchJson(input.http, input.cache, {
+        url: indexUrl,
+        cacheKey: `asset-index:${minecraft.manifest.assetIndex.id}:${minecraft.manifest.assetIndex.sha1}`,
+        ...input.signal !== void 0 ? { signal: input.signal } : {}
+      });
+      const seenAssetHashes = /* @__PURE__ */ new Set();
+      for (const entry of Object.values(indexDocument.objects)) {
+        if (seenAssetHashes.has(entry.hash)) continue;
+        seenAssetHashes.add(entry.hash);
+        record(
+          await verifyHashedFile({
+            path: targetPaths.assetObject(directory, entry.hash),
+            expectedSha1: entry.hash,
+            expectedSize: entry.size,
+            category: VerifyFileCategories.ASSET
+          })
+        );
+      }
+      const nativesDir = targetPaths.nativesDir(directory, minecraft.version);
+      if (!await fileExists(nativesDir)) {
+        for (const extraction of libraryPlan.nativeExtractions) {
+          record({
+            path: extraction.source,
+            category: VerifyFileCategories.NATIVE,
+            status: VerifyFileStatuses.MISSING
+          });
+        }
+      }
+    }
+  );
+}
+async function verifyRuntime(input) {
+  return runVerification(
+    {
+      targetId: input.target.id,
+      kind: VerificationKinds.RUNTIME,
+      ...input.onEvent !== void 0 ? { onEvent: input.onEvent } : {}
+    },
+    async (record) => {
+      let manifest;
+      try {
+        manifest = await fetchJson(input.http, input.cache, {
+          url: input.target.runtime.manifestUrl,
+          cacheKey: `runtime-manifest:${input.target.runtime.component}:${input.target.runtime.platformKey}:${input.target.runtime.manifestSha1}`,
+          ...input.signal !== void 0 ? { signal: input.signal } : {}
+        });
+      } catch {
+        record({
+          path: input.target.runtime.manifestUrl,
+          category: VerifyFileCategories.RUNTIME_FILE,
+          status: VerifyFileStatuses.MISSING
+        });
+        return;
+      }
+      const runtimeRoot = targetPaths.runtimeRoot(
+        input.target.directory,
+        input.target.runtime.component,
+        input.target.runtime.installRoot
+      );
+      for (const [relative, entry] of Object.entries(manifest.files)) {
+        if (entry.type !== "file") continue;
+        record(
+          await verifyHashedFile({
+            path: path.join(runtimeRoot, relative),
+            expectedSha1: entry.downloads.raw.sha1,
+            expectedSize: entry.downloads.raw.size,
+            url: entry.downloads.raw.url,
+            category: VerifyFileCategories.RUNTIME_FILE
+          })
+        );
+      }
+    }
+  );
+}
+
+// src/versions/fabric.ts
+var FabricVersionsApi = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** List Fabric loader versions, optionally constrained to a Minecraft version. */
+  async list(input = {}) {
+    if (input.minecraftVersion === void 0) {
+      return fetchJson(this.ctx.http, this.ctx.cache, {
+        url: ApiEndpoints.fabric.loaderVersions(),
+        cacheKey: "fabric-loader-all",
+        ...input.signal !== void 0 ? { signal: input.signal } : {}
+      });
+    }
+    const compat = await fetchJson(
+      this.ctx.http,
+      this.ctx.cache,
+      {
+        url: ApiEndpoints.fabric.loaderForGame(input.minecraftVersion),
+        cacheKey: `fabric-loader-mc:${input.minecraftVersion}`,
+        ...input.signal !== void 0 ? { signal: input.signal } : {}
+      }
+    );
+    return compat.map((c) => c.loader);
+  }
+  /** Resolve a Fabric loader version against a Minecraft version. */
+  async resolve(input) {
+    const loaders = await this.list({
+      minecraftVersion: input.minecraftVersion,
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    if (loaders.length === 0) {
+      throw new MinecraftKitError(
+        "MANIFEST_NOT_FOUND",
+        `No Fabric loader available for Minecraft ${input.minecraftVersion}`,
+        { context: { version: input.minecraftVersion } }
+      );
+    }
+    const chosen = pickFabricLoader(loaders, input);
+    if (!chosen) {
+      throw new MinecraftKitError(
+        "MANIFEST_NOT_FOUND",
+        `Fabric loader version not found: ${input.loaderVersion ?? "(none matched)"}`,
+        { context: { version: input.loaderVersion } }
+      );
+    }
+    const profile = await fetchJson(this.ctx.http, this.ctx.cache, {
+      url: ApiEndpoints.fabric.profile(input.minecraftVersion, chosen.version),
+      cacheKey: `fabric-profile:${input.minecraftVersion}:${chosen.version}`,
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    return {
+      type: Loaders.FABRIC,
+      minecraftVersion: input.minecraftVersion,
+      loaderVersion: chosen.version,
+      profile
+    };
+  }
+};
+function pickFabricLoader(loaders, input) {
+  if (input.loaderVersion !== void 0) {
+    return loaders.find((l) => l.version === input.loaderVersion);
+  }
+  const preference = input.preference ?? VersionPreference.LATEST;
+  if (preference === VersionPreference.RECOMMENDED) {
+    const stable = loaders.find((l) => l.stable);
+    if (stable) return stable;
+  }
+  return loaders[0];
+}
+
+// src/core/xml.ts
+function parseMavenMetadataVersions(xml) {
+  const versions = [];
+  const regex = /<version>\s*([^<]+?)\s*<\/version>/g;
+  for (const match of xml.matchAll(regex)) {
+    if (match[1]) versions.push(match[1]);
+  }
+  return versions;
+}
+
+// src/versions/forge.ts
+var ForgeVersionsApi = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** List Forge builds (across all Minecraft versions, or filtered to one). */
+  async list(input = {}) {
+    const xml = await fetchText(this.ctx.http, this.ctx.cache, {
+      url: ApiEndpoints.forge.mavenMetadata(),
+      cacheKey: "forge-maven-metadata",
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    const allVersions = parseMavenMetadataVersions(xml);
+    const promotions = await fetchJson(this.ctx.http, this.ctx.cache, {
+      url: ApiEndpoints.forge.promotions(),
+      cacheKey: "forge-promotions",
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    const summaries = allVersions.map((fullVersion) => buildSummary(fullVersion, promotions)).filter((s) => s !== null);
+    if (input.minecraftVersion === void 0) return summaries;
+    return summaries.filter((s) => s.minecraftVersion === input.minecraftVersion);
+  }
+  /** Resolve a Forge build for a Minecraft version. */
+  async resolve(input) {
+    const builds = await this.list({
+      minecraftVersion: input.minecraftVersion,
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    if (builds.length === 0) {
+      throw new MinecraftKitError(
+        "MANIFEST_NOT_FOUND",
+        `No Forge build available for Minecraft ${input.minecraftVersion}`,
+        { context: { version: input.minecraftVersion } }
+      );
+    }
+    const chosen = pickForge(builds, input);
+    if (!chosen) {
+      throw new MinecraftKitError(
+        "MANIFEST_NOT_FOUND",
+        `Forge build not found for ${input.minecraftVersion}: ${input.forgeVersion ?? "(none matched)"}`,
+        { context: { version: input.forgeVersion } }
+      );
+    }
+    return {
+      type: Loaders.FORGE,
+      minecraftVersion: chosen.minecraftVersion,
+      forgeVersion: chosen.forgeVersion,
+      fullVersion: chosen.fullVersion,
+      installerUrl: ApiEndpoints.forge.installer(chosen.fullVersion)
+    };
+  }
+};
+function buildSummary(fullVersion, promotions) {
+  const dashIndex = fullVersion.indexOf("-");
+  if (dashIndex <= 0 || dashIndex === fullVersion.length - 1) return null;
+  const minecraftVersion = fullVersion.slice(0, dashIndex);
+  const forgeVersion = fullVersion.slice(dashIndex + 1);
+  const promos = promotions.promos;
+  const recommended = promos[`${minecraftVersion}-recommended`];
+  const latest = promos[`${minecraftVersion}-latest`];
+  return {
+    fullVersion,
+    minecraftVersion,
+    forgeVersion,
+    isRecommended: recommended === forgeVersion,
+    isLatest: latest === forgeVersion
+  };
+}
+function pickForge(builds, input) {
+  if (input.forgeVersion !== void 0) {
+    return builds.find(
+      (b) => b.forgeVersion === input.forgeVersion || b.fullVersion === input.forgeVersion
+    );
+  }
+  const preference = input.preference ?? VersionPreference.RECOMMENDED;
+  if (preference === VersionPreference.RECOMMENDED) {
+    const recommended = builds.find((b) => b.isRecommended);
+    if (recommended) return recommended;
+  }
+  const latest = builds.find((b) => b.isLatest);
+  if (latest) return latest;
+  return builds[builds.length - 1];
+}
+
+// src/versions/minecraft.ts
+var MinecraftVersionsApi = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** List all Minecraft versions, optionally filtered by channel. */
+  async list(input = {}) {
+    const root = await this.fetchManifestRoot(input.signal);
+    if (input.channel === void 0) return root.versions;
+    return root.versions.filter((v) => v.type === input.channel);
+  }
+  /** Return the latest version on the given channel (defaults to RELEASE). */
+  async latest(input = {}) {
+    const root = await this.fetchManifestRoot(input.signal);
+    const targetId = input.channel === "snapshot" ? root.latest.snapshot : root.latest.release;
+    const summary = root.versions.find((v) => v.id === targetId);
+    if (!summary) {
+      throw new MinecraftKitError(
+        "MANIFEST_NOT_FOUND",
+        `Latest version ${targetId} not found in manifest`
+      );
+    }
+    return summary;
+  }
+  /** Return a single version summary or throw `MANIFEST_NOT_FOUND`. */
+  async get(input) {
+    const root = await this.fetchManifestRoot(input.signal);
+    const summary = root.versions.find((v) => v.id === input.version);
+    if (!summary) {
+      throw new MinecraftKitError(
+        "MANIFEST_NOT_FOUND",
+        `Minecraft version not found: ${input.version}`,
+        { context: { version: input.version } }
+      );
+    }
+    return summary;
+  }
+  /** Fetch and parse the per-version manifest in addition to the summary. */
+  async resolve(input) {
+    const summary = await this.get(input);
+    const manifest = await fetchJson(this.ctx.http, this.ctx.cache, {
+      url: summary.url,
+      cacheKey: `minecraft-manifest:${summary.id}:${summary.sha1}`,
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    if (!manifest.id || !manifest.mainClass) {
+      throw new MinecraftKitError(
+        "MANIFEST_INVALID",
+        `Per-version manifest is missing required fields: ${summary.id}`,
+        { context: { version: summary.id, url: summary.url } }
+      );
+    }
+    return {
+      version: summary.id,
+      channel: summary.type,
+      manifest,
+      summary
+    };
+  }
+  async fetchManifestRoot(signal) {
+    return fetchJson(this.ctx.http, this.ctx.cache, {
+      url: ApiEndpoints.mojang.versionManifest(),
+      cacheKey: "minecraft-version-manifest-v2",
+      ...signal !== void 0 ? { signal } : {}
+    });
+  }
+};
+
+// src/constants/runtime.ts
+var FALLBACK_COMPONENT = RuntimeComponents.JRE_LEGACY;
+
+// src/versions/runtime.ts
+var RuntimeVersionsApi = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** List available runtime entries for the host platform. */
+  async list(input) {
+    const platformKey = pickPlatformKey(input.system);
+    const index = await this.fetchIndex(input.signal);
+    const platform = index[platformKey];
+    if (!platform) return [];
+    const entries = [];
+    for (const [component, items] of Object.entries(platform)) {
+      for (const item of items) {
+        entries.push({
+          component,
+          platformKey,
+          versionName: item.version.name,
+          released: item.version.released,
+          manifestUrl: item.manifest.url
+        });
+      }
+    }
+    return entries;
+  }
+  /** Resolve a single runtime for the host platform and Minecraft version. */
+  async resolve(input) {
+    const platformKey = pickPlatformKey(input.system);
+    const index = await this.fetchIndex(input.signal);
+    const platform = index[platformKey];
+    if (!platform) {
+      throw new MinecraftKitError(
+        "RUNTIME_UNSUPPORTED_PLATFORM",
+        `No runtimes published for platform: ${platformKey}`,
+        { context: { platform: platformKey } }
+      );
+    }
+    const component = input.component ?? FALLBACK_COMPONENT;
+    const candidates = platform[component] ?? [];
+    if (candidates.length === 0) {
+      const all = Object.entries(platform);
+      const preference = input.preference ?? RuntimePreference.RECOMMENDED;
+      if (preference === RuntimePreference.LATEST) {
+        const fallback = pickLatestAcrossComponents(all);
+        if (fallback) {
+          return toResolved(fallback.component, platformKey, fallback.entry, input.system);
+        }
+      }
+      throw new MinecraftKitError(
+        "RUNTIME_NOT_FOUND",
+        `Runtime component ${component} not available on ${platformKey}`,
+        { context: { platform: platformKey, version: component } }
+      );
+    }
+    const entry = candidates[0];
+    if (!entry) {
+      throw new MinecraftKitError(
+        "RUNTIME_NOT_FOUND",
+        `Runtime component ${component} list is empty for ${platformKey}`,
+        { context: { platform: platformKey, version: component } }
+      );
+    }
+    return toResolved(component, platformKey, entry, input.system);
+  }
+  async fetchIndex(signal) {
+    return fetchJson(this.ctx.http, this.ctx.cache, {
+      url: ApiEndpoints.mojang.runtimeIndex(),
+      cacheKey: "mojang-runtime-index",
+      ...signal !== void 0 ? { signal } : {}
+    });
+  }
+};
+function pickPlatformKey(system) {
+  const archMap = RUNTIME_PLATFORM_KEYS[system.os];
+  return archMap[system.arch];
+}
+function pickLatestAcrossComponents(entries) {
+  let bestComponent = null;
+  let bestEntry = null;
+  for (const [component, list] of entries) {
+    for (const entry of list) {
+      if (!bestEntry || entry.version.released > bestEntry.version.released) {
+        bestComponent = component;
+        bestEntry = entry;
+      }
+    }
+  }
+  if (!bestComponent || !bestEntry) return null;
+  return { component: bestComponent, entry: bestEntry };
+}
+function toResolved(component, platformKey, entry, system) {
+  return {
+    component,
+    platformKey,
+    versionName: entry.version.name,
+    system,
+    manifestUrl: entry.manifest.url,
+    manifestSha1: entry.manifest.sha1
+  };
+}
+
+// src/kit.ts
+var MinecraftKit = class {
+  versions;
+  targets;
+  install;
+  update;
+  verify;
+  repair;
+  launch;
+  /** Cache surface useful for advanced consumers (e.g. clearing between operations). */
+  cache;
+  constructor(options = {}) {
+    const http = options.httpClient ?? new FetchHttpClient();
+    const cache = options.cache ?? createMemoryCache();
+    const logger = options.logger ?? silentLogger;
+    const system = options.system ?? detectSystem();
+    const spawner = options.spawner ?? new ChildProcessSpawner();
+    const ctx = { http, cache, logger };
+    const minecraft = new MinecraftVersionsApi(ctx);
+    const fabric = new FabricVersionsApi(ctx);
+    const forge = new ForgeVersionsApi(ctx);
+    const runtime = new RuntimeVersionsApi(ctx);
+    this.versions = { minecraft, fabric, forge, runtime };
+    this.targets = new TargetsApi({ minecraft, fabric, forge, runtime, system });
+    this.cache = cache;
+    const carry = (opts) => ({
+      ...opts?.signal !== void 0 ? { signal: opts.signal } : {},
+      ...opts?.onEvent !== void 0 ? { onEvent: opts.onEvent } : {}
+    });
+    const runInstallPlan = (plan, opts) => runInstall({ plan, http, cache, spawner, ...carry(opts) });
+    this.install = {
+      plan: (target, opts) => planInstall({ target, http, cache, ...carry(opts) }),
+      run: runInstallPlan,
+      runtime: {
+        plan: (target, opts) => planRuntimeInstall({ target, http, cache, ...carry(opts) }),
+        run: runInstallPlan,
+        standalonePlan: (input) => planStandaloneRuntimeInstall({ ...input, http, cache })
+      }
+    };
+    this.update = {
+      plan: (target, opts) => planUpdate({ target, http, cache, ...carry(opts) }),
+      run: (plan, opts) => runUpdate({ plan, http, cache, spawner, ...carry(opts) })
+    };
+    const verifyArgs = (target, opts) => ({
+      target,
+      http,
+      cache,
+      ...carry(opts)
+    });
+    this.verify = {
+      minecraft: { run: (target, opts) => verifyMinecraft(verifyArgs(target, opts)) },
+      fabric: { run: (target, opts) => verifyFabric(verifyArgs(target, opts)) },
+      forge: { run: (target, opts) => verifyForge(verifyArgs(target, opts)) },
+      runtime: { run: (target, opts) => verifyRuntime(verifyArgs(target, opts)) }
+    };
+    const repairArgs = (target, opts) => ({
+      target,
+      from: opts.from,
+      http,
+      cache,
+      ...carry({ ...opts.signal !== void 0 ? { signal: opts.signal } : {} })
+    });
+    const runRepairPlan = (plan, opts) => runRepair({ plan, http, cache, spawner, ...carry(opts) });
+    this.repair = {
+      minecraft: {
+        plan: (target, opts) => planMinecraftRepair(repairArgs(target, opts)),
+        run: runRepairPlan
+      },
+      fabric: {
+        plan: (target, opts) => planFabricRepair(repairArgs(target, opts)),
+        run: runRepairPlan
+      },
+      forge: {
+        plan: (target, opts) => planForgeRepair(repairArgs(target, opts)),
+        run: runRepairPlan
+      },
+      runtime: {
+        plan: (target, opts) => planRuntimeRepair(repairArgs(target, opts)),
+        run: runRepairPlan
+      }
+    };
+    this.launch = {
+      compose: (target, opts) => composeLaunch({ target, options: opts }),
+      run: (composition, opts) => runLaunch({
+        composition,
+        ...opts !== void 0 ? { options: opts } : {},
+        spawner
+      })
+    };
+  }
+};
+
+// src/cli/error-format.ts
+function formatUserError(error) {
+  if (isMinecraftKitError(error)) {
+    const status = typeof error.context.httpStatus === "number" ? error.context.httpStatus : void 0;
+    if (error.code === "NETWORK_HTTP_ERROR" && status !== void 0) {
+      if (status === 400 || status === 404) {
+        return "No matching data is available for that combination.";
+      }
+      if (status === 408) return "The server took too long to respond. Please retry.";
+      if (status === 429)
+        return "The metadata server is rate-limiting requests. Please retry shortly.";
+      if (status >= 500 && status < 600) {
+        return "The metadata server returned an error. Please retry later.";
+      }
+      return `Unexpected HTTP ${status} from the metadata server.`;
+    }
+    switch (error.code) {
+      case "NETWORK_TIMEOUT":
+        return "Network request timed out. Check your internet connection and retry.";
+      case "NETWORK_ABORTED":
+        return "The request was aborted.";
+      case "MANIFEST_NOT_FOUND":
+        return "Requested item is not available \u2014 try a different selection.";
+      case "MANIFEST_INVALID":
+        return "The metadata server returned a malformed response. Please retry.";
+      case "INTEGRITY_HASH_MISMATCH":
+        return "A downloaded file failed its hash check. Re-running install / repair will retry.";
+      case "INTEGRITY_SIZE_MISMATCH":
+        return "A downloaded file had the wrong size. Re-running install / repair will retry.";
+      case "RUNTIME_NOT_FOUND":
+        return "No runtime is published for that combination.";
+      case "RUNTIME_UNSUPPORTED_PLATFORM":
+        return "Your platform is not in Mojang's published runtime list.";
+      case "FORGE_INSTALLER_INVALID":
+        return "Forge installer appears to be corrupt or in an unsupported format.";
+      case "FORGE_PROCESSOR_FAILED":
+        return "A Forge processor failed during install.";
+      case "LAUNCH_JAVA_NOT_FOUND":
+        return "Could not find a Java executable. Install the runtime first.";
+      case "LAUNCH_PROCESS_FAILED":
+        return "Minecraft exited with an error.";
+      case "LAUNCH_ABORTED":
+        return "Operation was aborted.";
+      case "INVALID_INPUT":
+        return error.message;
+      case "FILESYSTEM_PATH_TRAVERSAL":
+        return "An archive entry tried to escape the install directory and was rejected.";
+      case "FILESYSTEM_WRITE_ERROR":
+      case "FILESYSTEM_READ_ERROR":
+        return `Filesystem error: ${error.message}`;
+      default:
+        return error.message;
+    }
+  }
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+// src/cli/progress.ts
+var DEFAULT_RENDER_INTERVAL_MS = 250;
+var SPEED_WINDOW_MS = 5e3;
+var BAR_WIDTH = 12;
+var SAFETY_MARGIN = 1;
+var ProgressRenderer = class {
+  ui;
+  label;
+  totalActions;
+  totalBytes;
+  now;
+  minRenderIntervalMs;
+  columnsFn;
+  speedSamples = [];
+  spinner;
+  /** Authoritative bytes for files that have completed. */
+  completedBytes = 0;
+  /** Latest progress bytes for files that are currently downloading. */
+  activeBytes = /* @__PURE__ */ new Map();
+  /** Files for which `download:started` fired but `download:completed/failed` has not. */
+  activeTargets = /* @__PURE__ */ new Set();
+  startedAt;
+  lastRenderAt = 0;
+  lastRenderedLine = null;
+  currentPhase = "idle";
+  filesCompleted = 0;
+  filesSkipped = 0;
+  filesFailed = 0;
+  active = false;
+  constructor(input) {
+    this.ui = input.ui;
+    this.label = input.label;
+    if (input.totalActions !== void 0) this.totalActions = input.totalActions;
+    if (input.totalBytes !== void 0) this.totalBytes = input.totalBytes;
+    this.now = input.now ?? (() => Date.now());
+    this.minRenderIntervalMs = input.minRenderIntervalMs ?? DEFAULT_RENDER_INTERVAL_MS;
+    this.columnsFn = input.columns ?? (() => typeof process.stdout.columns === "number" ? process.stdout.columns : 0);
+    this.spinner = this.ui.spinner();
+    this.startedAt = this.now();
+  }
+  /** Start the spinner and return a listener function suitable for `kit.install.run({ onEvent })`. */
+  attach() {
+    this.active = true;
+    this.startedAt = this.now();
+    this.lastRenderAt = 0;
+    this.lastRenderedLine = null;
+    this.spinner.start(`${this.label}\u2026`);
+    return (event) => this.handle(event);
+  }
+  /** Stop the spinner with a final summary line and return the metrics. */
+  finish() {
+    if (!this.active) return this.summary();
+    this.active = false;
+    const summary = this.summary();
+    this.spinner.stop(this.summaryLine(summary));
+    return summary;
+  }
+  /** Stop with a failure message instead of the summary. */
+  fail(message) {
+    if (!this.active) return;
+    this.active = false;
+    this.spinner.stop(`${this.label} failed: ${message}`);
+  }
+  /** Snapshot of current metrics. */
+  summary() {
+    const durationMs = Math.max(0, this.now() - this.startedAt);
+    const bytes = this.bytesDownloadedNow();
+    const avgSpeedBps = durationMs > 0 ? bytes * 1e3 / durationMs : 0;
+    return {
+      filesDownloaded: this.filesCompleted,
+      filesSkipped: this.filesSkipped,
+      filesFailed: this.filesFailed,
+      bytesDownloaded: bytes,
+      durationMs,
+      avgSpeedBps
+    };
+  }
+  /** Handle one event. Re-rendering is throttled to {@link minRenderIntervalMs}. */
+  handle(event) {
+    let forceRender = false;
+    switch (event.type) {
+      case "install:phase-changed":
+      case "repair:phase-changed":
+        this.currentPhase = event.phase;
+        forceRender = true;
+        break;
+      case "download:started":
+        this.activeTargets.add(event.file.target);
+        this.activeBytes.set(event.file.target, 0);
+        forceRender = true;
+        break;
+      case "download:progress": {
+        const previous = this.activeBytes.get(event.file.target) ?? 0;
+        if (event.bytesDownloaded > previous) {
+          const ts = this.now();
+          this.speedSamples.push({ ts, bytes: event.bytesDownloaded - previous });
+          const cutoff = ts - SPEED_WINDOW_MS;
+          while (this.speedSamples.length > 0 && this.speedSamples[0].ts < cutoff) {
+            this.speedSamples.shift();
+          }
+        }
+        this.activeBytes.set(event.file.target, event.bytesDownloaded);
+        break;
+      }
+      case "download:completed":
+        this.filesCompleted++;
+        this.completedBytes += event.bytes;
+        this.activeTargets.delete(event.file.target);
+        this.activeBytes.delete(event.file.target);
+        forceRender = true;
+        break;
+      case "download:skipped":
+        this.filesSkipped++;
+        this.filesCompleted++;
+        forceRender = true;
+        break;
+      case "download:failed":
+        if (event.willRetry) {
+          this.activeBytes.set(event.file.target, 0);
+        } else {
+          this.filesFailed++;
+          this.activeTargets.delete(event.file.target);
+          this.activeBytes.delete(event.file.target);
+        }
+        forceRender = true;
+        break;
+      case "archive:extracted":
+      case "forge:processor-started":
+      case "forge:processor-completed":
+        forceRender = true;
+        break;
+    }
+    this.maybeRender(forceRender);
+  }
+  maybeRender(force) {
+    if (!this.active) return;
+    const ts = this.now();
+    if (!force && ts - this.lastRenderAt < this.minRenderIntervalMs) return;
+    const line = this.formatLine();
+    if (line === this.lastRenderedLine) return;
+    this.lastRenderAt = ts;
+    this.lastRenderedLine = line;
+    this.spinner.message(line);
+  }
+  bytesDownloadedNow() {
+    let sum = this.completedBytes;
+    for (const v of this.activeBytes.values()) sum += v;
+    return sum;
+  }
+  formatLine() {
+    const phase = shortPhase(this.currentPhase);
+    const bytes = this.bytesDownloadedNow();
+    const speed = this.computeSpeedBps();
+    const active = this.activeTargets.size;
+    const ratio = this.computeRatio();
+    const fileCounter = this.totalActions !== void 0 ? `${this.filesCompleted}/${this.totalActions}` : `${this.filesCompleted}`;
+    const segments = [`[${phase}]`, fileCounter, formatBytes(bytes)];
+    if (speed > 0) segments.push(`${formatBytes(speed)}/s`);
+    segments.push(`active ${active}`);
+    if (ratio !== null) segments.push(`${this.formatBar(ratio)} ${(ratio * 100).toFixed(0)}%`);
+    const line = segments.join(" \xB7 ");
+    return clipToColumns(line, this.columnsFn());
+  }
+  formatBar(ratio) {
+    const filled = Math.round(ratio * BAR_WIDTH);
+    return `${"\u2588".repeat(filled)}${"\u2591".repeat(BAR_WIDTH - filled)}`;
+  }
+  computeRatio() {
+    if (this.totalBytes !== void 0 && this.totalBytes > 0) {
+      return Math.min(1, this.bytesDownloadedNow() / this.totalBytes);
+    }
+    if (this.totalActions !== void 0 && this.totalActions > 0) {
+      return Math.min(1, this.filesCompleted / this.totalActions);
+    }
+    return null;
+  }
+  computeSpeedBps() {
+    if (this.speedSamples.length === 0) return 0;
+    const oldest = this.speedSamples[0].ts;
+    const elapsed = Math.max(1, this.now() - oldest);
+    const bytes = this.speedSamples.reduce((sum, sample) => sum + sample.bytes, 0);
+    return bytes * 1e3 / elapsed;
+  }
+  summaryLine(summary) {
+    const total = this.totalActions !== void 0 ? `/${this.totalActions}` : "";
+    const parts = [`${this.label} done`, `${summary.filesDownloaded}${total} files`];
+    if (summary.filesSkipped > 0) parts.push(`${summary.filesSkipped} skipped`);
+    if (summary.filesFailed > 0) parts.push(`${summary.filesFailed} failed`);
+    parts.push(`${formatBytes(summary.bytesDownloaded)}`);
+    if (summary.avgSpeedBps > 0) parts.push(`avg ${formatBytes(summary.avgSpeedBps)}/s`);
+    parts.push(`in ${formatDuration(summary.durationMs)}`);
+    return clipToColumns(parts.join(" \xB7 "), this.columnsFn());
+  }
+};
+function shortPhase(phase) {
+  if (phase === "idle") return "starting";
+  for (const prefix of [
+    "downloading-",
+    "installing-",
+    "extracting-",
+    "repairing-",
+    "running-",
+    "writing-"
+  ]) {
+    if (phase.startsWith(prefix)) return phase.slice(prefix.length);
+  }
+  return phase;
+}
+function clipToColumns(line, cols) {
+  if (cols <= 0) return line;
+  const limit = cols - SAFETY_MARGIN;
+  if (limit <= 0) return "";
+  if (line.length <= limit) return line;
+  return `${line.slice(0, Math.max(0, limit - 1))}\u2026`;
+}
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "\u2014";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "\u2014";
+  const seconds = Math.round(ms / 1e3);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remSec = seconds % 60;
+  if (minutes < 60) return `${minutes}m${remSec.toString().padStart(2, "0")}s`;
+  const hours = Math.floor(minutes / 60);
+  const remMin = minutes % 60;
+  return `${hours}h${remMin.toString().padStart(2, "0")}m${remSec.toString().padStart(2, "0")}s`;
+}
+
+// src/cli/scenarios/install-helpers.ts
+async function runInstallWithProgress(ctx, target, label) {
+  const planSpinner = ctx.ui.spinner();
+  planSpinner.start(`Planning ${label}\u2026`);
+  let plan;
+  try {
+    plan = await ctx.kit.install.plan(target);
+    planSpinner.stop(`Plan ready: ${plan.totalActions} actions, ${formatBytes(plan.totalBytes)}.`);
+  } catch (error) {
+    planSpinner.stop("Planning failed.");
+    throw error;
+  }
+  const renderer = new ProgressRenderer({
+    ui: ctx.ui,
+    label: `Install ${label}`,
+    totalActions: plan.totalActions,
+    totalBytes: plan.totalBytes
+  });
+  const onEvent = renderer.attach();
+  try {
+    await ctx.kit.install.run(plan, { onEvent });
+    const summary = renderer.finish();
+    ctx.ui.note("Install summary", formatSummary(summary));
+  } catch (error) {
+    renderer.fail(formatUserError(error));
+    throw error;
+  }
+}
+async function runInstallFromSelection(ctx, sel) {
+  const v = sel.version;
+  const dir = sel.directory;
+  const loaderInput = buildLoaderInput(sel);
+  const runtimeInput = sel.runtimeOverride !== null ? { runtime: { component: sel.runtimeOverride } } : {};
+  let target;
+  try {
+    target = await ctx.kit.targets.resolve({
+      id: path.basename(dir),
+      directory: dir,
+      minecraft: { version: v.id },
+      loader: loaderInput,
+      ...runtimeInput
+    });
+  } catch (error) {
+    ctx.ui.log("error", formatUserError(error));
+    return "install-type";
+  }
+  try {
+    await runInstallWithProgress(ctx, target, describeLoader(sel));
+    return "ok";
+  } catch {
+    return "directory";
+  }
+}
+async function runStandaloneRuntimeInstallWithProgress(ctx, input) {
+  const label = `runtime ${input.runtime.component}`;
+  const planSpinner = ctx.ui.spinner();
+  planSpinner.start(`Planning ${label}\u2026`);
+  let plan;
+  try {
+    plan = await ctx.kit.install.runtime.standalonePlan({
+      id: input.id,
+      directory: input.directory,
+      runtime: input.runtime
+    });
+    planSpinner.stop(`Plan ready: ${plan.totalActions} files, ${formatBytes(plan.totalBytes)}.`);
+  } catch (error) {
+    planSpinner.stop("Planning failed.");
+    throw error;
+  }
+  const renderer = new ProgressRenderer({
+    ui: ctx.ui,
+    label: `Install ${label}`,
+    totalActions: plan.totalActions,
+    totalBytes: plan.totalBytes
+  });
+  const onEvent = renderer.attach();
+  try {
+    await ctx.kit.install.runtime.run(plan, { onEvent });
+    const summary = renderer.finish();
+    ctx.ui.note("Runtime install summary", formatSummary(summary));
+  } catch (error) {
+    renderer.fail(formatUserError(error));
+    throw error;
+  }
+}
+function buildLoaderInput(sel) {
+  if (sel.installType === Loaders.VANILLA) {
+    return { type: Loaders.VANILLA };
+  }
+  if (sel.installType === Loaders.FABRIC) {
+    return { type: Loaders.FABRIC, version: sel.fabricLoader };
+  }
+  return { type: Loaders.FORGE, version: sel.forgeBuild };
+}
+function describeLoader(sel) {
+  const v = sel.version.id;
+  if (sel.installType === Loaders.VANILLA) return `Vanilla ${v}`;
+  if (sel.installType === Loaders.FABRIC) return `Fabric ${sel.fabricLoader} on ${v}`;
+  return `Forge ${sel.forgeLabel ?? sel.forgeBuild} on ${v}`;
+}
+function summaryRows(sel) {
+  const v = sel.version;
+  const rows = [
+    ["Minecraft", v.id],
+    ["Type", labelForType(sel.installType)]
+  ];
+  if (sel.installType === Loaders.FABRIC && sel.fabricLoader) {
+    rows.push(["Fabric", sel.fabricLoader]);
+  }
+  if (sel.installType === Loaders.FORGE && (sel.forgeLabel || sel.forgeBuild)) {
+    rows.push(["Forge", sel.forgeLabel ?? sel.forgeBuild ?? ""]);
+  }
+  rows.push(["Runtime", sel.runtimeOverride ?? "auto-detect"]);
+  rows.push(["Directory", sel.directory]);
+  return rows;
+}
+function labelForType(type) {
+  if (type === Loaders.FABRIC) return "Fabric";
+  if (type === Loaders.FORGE) return "Forge (modern)";
+  return "Vanilla";
+}
+function previousFromDirectory(sel) {
+  if (sel.installType === Loaders.FABRIC) return "fabric-loader";
+  if (sel.installType === Loaders.FORGE) return "forge-build";
+  return "install-type";
+}
+function defaultIdFromSelection(sel) {
+  const v = sel.version.id;
+  if (sel.installType === Loaders.FABRIC) {
+    return defaultIdFor("fabric", `${v}-${sel.fabricLoader ?? ""}`);
+  }
+  if (sel.installType === Loaders.FORGE) {
+    return defaultIdFor("forge", `${v}-${sel.forgeBuild ?? ""}`);
+  }
+  return defaultIdFor("vanilla", v);
+}
+function defaultIdFor(loader, suffix) {
+  return `${loader}-${suffix}`.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+}
+function formatDetailed(entry) {
+  const versions = entry.minecraftVersions.length === 0 ? "(none)" : entry.minecraftVersions.join(", ");
+  const loaders = entry.loaders.length === 0 ? "(none)" : entry.loaders.map((l) => `${l.type}${l.version ? ` ${l.version}` : ""}`).join(", ");
+  const runtimePath = entry.runtime?.javaPath ?? "(none detected)";
+  const runtimeComponent = entry.runtime?.component ?? "(unknown)";
+  const runtimeVersion = entry.runtime?.javaVersion ?? "(unknown)";
+  return [
+    `Directory:         ${entry.directory}`,
+    `Minecraft:         ${versions}`,
+    `Loaders:           ${loaders}`,
+    `Runtime path:      ${runtimePath}`,
+    `Runtime component: ${runtimeComponent}`,
+    `Runtime version:   ${runtimeVersion}`
+  ].join("\n");
+}
+function formatSummary(summary) {
+  const lines = [
+    `Files downloaded: ${summary.filesDownloaded}`,
+    `Files skipped:    ${summary.filesSkipped}`
+  ];
+  if (summary.filesFailed > 0) {
+    lines.push(`Files failed:     ${summary.filesFailed}`);
+  }
+  lines.push(
+    `Bytes downloaded: ${formatBytes(summary.bytesDownloaded)}`,
+    `Average speed:    ${formatBytes(summary.avgSpeedBps)}/s`,
+    `Duration:         ${formatDuration(summary.durationMs)}`
+  );
+  return lines.join("\n");
+}
+
+// src/types/minecraft.ts
+var MinecraftChannels = {
+  RELEASE: "release",
+  SNAPSHOT: "snapshot",
+  OLD_BETA: "old_beta",
+  OLD_ALPHA: "old_alpha"
+};
+
+// src/cli/scenarios/types.ts
+var CHANNEL_OPTIONS = [
+  { label: "Release", value: MinecraftChannels.RELEASE, hint: "stable releases (recommended)" },
+  { label: "Snapshot", value: MinecraftChannels.SNAPSHOT, hint: "weekly development builds" },
+  { label: "Old versions", value: "old", hint: "old_beta + old_alpha" },
+  { label: "All", value: "all", hint: "every channel combined" }
+];
+
+// src/cli/scenarios/pickers.ts
+async function pickChannel(ui) {
+  return ui.select({
+    message: "Select Minecraft channel",
+    options: CHANNEL_OPTIONS,
+    allowCancel: true
+  });
+}
+async function pickMinecraftVersion(ctx, channel) {
+  const spinner = ctx.ui.spinner();
+  spinner.start("Loading Minecraft versions\u2026");
+  let versions;
+  try {
+    versions = await ctx.kit.versions.minecraft.list();
+    spinner.stop(`${versions.length} versions loaded.`);
+  } catch (error) {
+    spinner.stop("Failed to load versions.");
+    ctx.ui.log("error", formatUserError(error));
+    return { kind: "back" };
+  }
+  const filtered = filterVersionsByChannel(versions, channel);
+  if (filtered.length === 0) {
+    ctx.ui.log("warn", "No versions in that channel.");
+    return { kind: "back" };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const v of filtered) {
+    if (seen.has(v.id)) continue;
+    seen.add(v.id);
+    unique.push(v);
+  }
+  const sorted = [...unique].sort(
+    (a, b) => (b.releaseTime ?? "").localeCompare(a.releaseTime ?? "")
+  );
+  const options = sorted.map((v) => ({
+    label: v.id,
+    value: v,
+    hint: `${v.type} \xB7 ${(v.releaseTime ?? "").slice(0, 10)}`
+  }));
+  return ctx.ui.searchableSelect({
+    message: "Select Minecraft version",
+    options,
+    allowBack: true,
+    allowCancel: true
+  });
+}
+async function pickRuntime(ctx) {
+  const initial = await ctx.ui.select({
+    message: "Select Java/runtime",
+    options: [
+      {
+        label: "Use recommended",
+        value: "auto",
+        hint: "use the runtime declared by the version manifest"
+      },
+      {
+        label: "Pick specific component\u2026",
+        value: "specific",
+        hint: "choose from Mojang's published runtimes"
+      }
+    ],
+    allowBack: true,
+    allowCancel: true
+  });
+  if (initial.kind !== "ok") return initial;
+  if (initial.value === "auto") return { kind: "ok", value: null };
+  const spinner = ctx.ui.spinner();
+  spinner.start("Loading runtime components\u2026");
+  try {
+    const list = await ctx.kit.versions.runtime.list({
+      system: ctx.kit.targets.system
+    });
+    spinner.stop(
+      `${list.length} runtime entr${list.length === 1 ? "y" : "ies"} for your platform.`
+    );
+    if (list.length === 0) {
+      ctx.ui.log("warn", "No published runtimes for this platform \u2014 falling back to auto-detect.");
+      return { kind: "ok", value: null };
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const components = [];
+    for (const entry of list) {
+      if (seen.has(entry.component)) continue;
+      seen.add(entry.component);
+      components.push({
+        component: entry.component,
+        versionName: entry.versionName
+      });
+    }
+    const choice = await ctx.ui.select({
+      message: "Select runtime component",
+      options: components.map((c) => ({
+        label: c.component,
+        value: c.component,
+        hint: c.versionName
+      })),
+      allowBack: true,
+      allowCancel: true
+    });
+    if (choice.kind !== "ok") return choice;
+    return { kind: "ok", value: choice.value };
+  } catch (error) {
+    spinner.stop("Failed to load runtimes.");
+    ctx.ui.log("warn", `${formatUserError(error)} Falling back to auto-detect.`);
+    return { kind: "ok", value: null };
+  }
+}
+async function pickInstallType(ui) {
+  return ui.select({
+    message: "Select installation type",
+    options: [
+      { label: "Vanilla", value: Loaders.VANILLA, hint: "no mod loader" },
+      {
+        label: "Fabric",
+        value: Loaders.FABRIC,
+        hint: "lightweight modern loader"
+      },
+      { label: "Forge", value: Loaders.FORGE, hint: "modern Forge (1.13+)" }
+    ],
+    allowBack: true,
+    allowCancel: true
+  });
+}
+async function pickFabricLoader2(ctx, minecraftVersion) {
+  const spinner = ctx.ui.spinner();
+  spinner.start(`Loading Fabric loaders for ${minecraftVersion}\u2026`);
+  try {
+    const loaders = await ctx.kit.versions.fabric.list({ minecraftVersion });
+    spinner.stop(`${loaders.length} Fabric loader(s).`);
+    if (loaders.length === 0) {
+      return { kind: "incompatible" };
+    }
+    const options = loaders.map((loader) => ({
+      label: loader.version,
+      value: loader.version,
+      hint: loader.stable ? "stable" : "unstable"
+    }));
+    return await ctx.ui.searchableSelect({
+      message: "Select Fabric loader",
+      options,
+      allowBack: true,
+      allowCancel: true
+    });
+  } catch (error) {
+    spinner.stop("Failed to load Fabric loaders.");
+    ctx.ui.log("warn", formatUserError(error));
+    return { kind: "incompatible" };
+  }
+}
+async function pickForgeBuild(ctx, minecraftVersion) {
+  const spinner = ctx.ui.spinner();
+  spinner.start(`Loading Forge builds for ${minecraftVersion}\u2026`);
+  try {
+    const builds = await ctx.kit.versions.forge.list({ minecraftVersion });
+    spinner.stop(`${builds.length} Forge build(s).`);
+    if (builds.length === 0) {
+      return { kind: "incompatible" };
+    }
+    const recommended = builds.find((b) => b.isRecommended);
+    const latest = builds.find((b) => b.isLatest);
+    const options = [];
+    if (recommended) {
+      options.push({
+        label: `Recommended (${recommended.forgeVersion})`,
+        value: recommended.forgeVersion,
+        hint: "promoted -recommended"
+      });
+    }
+    if (latest && latest.forgeVersion !== recommended?.forgeVersion) {
+      options.push({
+        label: `Latest (${latest.forgeVersion})`,
+        value: latest.forgeVersion,
+        hint: "promoted -latest"
+      });
+    }
+    for (const build of builds) {
+      if (build.isRecommended || build.isLatest) continue;
+      options.push({
+        label: build.forgeVersion,
+        value: build.forgeVersion,
+        hint: build.fullVersion
+      });
+    }
+    const result = await ctx.ui.searchableSelect({
+      message: "Select Forge build",
+      options,
+      allowBack: true,
+      allowCancel: true
+    });
+    if (result.kind !== "ok") return result;
+    const matched = options.find((o) => o.value === result.value);
+    return {
+      kind: "ok",
+      value: result.value,
+      label: matched?.label ?? result.value
+    };
+  } catch (error) {
+    spinner.stop("Failed to load Forge builds.");
+    ctx.ui.log("warn", formatUserError(error));
+    return { kind: "incompatible" };
+  }
+}
+async function pickDirectory(ctx, suggestedId) {
+  const defaultPath = path.join(ctx.rootDir, suggestedId);
+  const choice = await ctx.ui.select({
+    message: "Where should the installation live?",
+    options: [
+      { label: `Default: ${defaultPath}`, value: "default" },
+      { label: "Custom path\u2026", value: "custom" }
+    ],
+    allowBack: true,
+    allowCancel: true
+  });
+  if (choice.kind !== "ok") return choice;
+  if (choice.value === "default") return { kind: "ok", value: defaultPath };
+  const text = await ctx.ui.text({
+    message: "Custom installation directory",
+    placeholder: defaultPath,
+    initial: defaultPath,
+    validate: (s) => s.trim().length === 0 ? "Path must be non-empty" : void 0,
+    allowBack: true
+  });
+  if (text.kind !== "ok") return text;
+  return { kind: "ok", value: (text.value ?? "").trim() };
+}
+async function confirmInstall(ctx, rows) {
+  ctx.ui.note("Summary", rows.map(([k, v]) => `${k.padEnd(11)} ${v}`).join("\n"));
+  return ctx.ui.confirm({
+    message: "Proceed with install?",
+    initial: true,
+    allowBack: true
+  });
+}
+async function pickRuntimeComponent(ctx) {
+  const spinner = ctx.ui.spinner();
+  spinner.start("Loading runtime components\u2026");
+  let entries;
+  try {
+    entries = await ctx.kit.versions.runtime.list({
+      system: ctx.kit.targets.system
+    });
+    spinner.stop(
+      `${entries.length} runtime entr${entries.length === 1 ? "y" : "ies"} for your platform.`
+    );
+  } catch (error) {
+    spinner.stop("Failed to load runtimes.");
+    ctx.ui.log("error", formatUserError(error));
+    return { kind: "cancel" };
+  }
+  if (entries.length === 0) {
+    ctx.ui.log("warn", "No published runtimes for this platform.");
+    return { kind: "cancel" };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const componentChoices = [];
+  for (const entry of entries) {
+    if (seen.has(entry.component)) continue;
+    seen.add(entry.component);
+    componentChoices.push({
+      component: entry.component,
+      versionName: entry.versionName
+    });
+  }
+  const choice = await ctx.ui.select({
+    message: "Select Java runtime component",
+    options: componentChoices.map((c) => ({
+      label: c.component,
+      value: c.component,
+      hint: c.versionName
+    })),
+    allowBack: true,
+    allowCancel: true
+  });
+  if (choice.kind !== "ok") return choice;
+  const picked = componentChoices.find((c) => c.component === choice.value);
+  if (!picked) return { kind: "cancel" };
+  return { kind: "ok", value: picked };
+}
+async function pickRuntimeInstallRoot(ctx) {
+  const choice = await ctx.ui.select({
+    message: "Where should the runtime files live?",
+    options: [
+      {
+        label: "Per-target (default)",
+        value: "per-target",
+        hint: "<directory>/runtime/<component>"
+      },
+      {
+        label: "Custom shared install root\u2026",
+        value: "custom",
+        hint: "absolute path containing component directories"
+      }
+    ],
+    allowBack: true,
+    allowCancel: true
+  });
+  if (choice.kind !== "ok") return choice;
+  if (choice.value === "per-target") return { kind: "ok", value: null };
+  const text = await ctx.ui.text({
+    message: "Custom runtime install root (absolute path)",
+    placeholder: "C:\\shared\\jre",
+    validate: (s) => s.trim().length === 0 ? "Path must be non-empty" : void 0,
+    allowBack: true
+  });
+  if (text.kind !== "ok") return text;
+  const trimmed = (text.value ?? "").trim();
+  if (trimmed.length === 0) return { kind: "ok", value: null };
+  return { kind: "ok", value: trimmed };
+}
+async function pickInstalledTarget(ctx) {
+  let list;
+  try {
+    list = await ctx.kit.targets.list({ rootDir: ctx.rootDir });
+  } catch (error) {
+    ctx.ui.log("error", formatUserError(error));
+    return null;
+  }
+  if (list.length === 0) {
+    ctx.ui.log("warn", `No installations under ${ctx.rootDir}. Install one first.`);
+    return null;
+  }
+  const choice = await ctx.ui.select({
+    message: "Pick an installation",
+    options: list.map((entry2) => ({
+      label: entry2.id,
+      value: entry2.id,
+      hint: entry2.minecraftVersions.join(", ") || "no versions"
+    })),
+    allowCancel: true
+  });
+  if (choice.kind !== "ok") return null;
+  const entry = list.find((e) => e.id === choice.value);
+  if (!entry) return null;
+  const mcVersion = await pickMinecraftVersionFromEntry(ctx, entry);
+  if (!mcVersion) return null;
+  const loaderHint = entry.loaders.find(
+    (l) => !l.minecraftVersion || l.minecraftVersion === mcVersion
+  );
+  try {
+    return await ctx.kit.targets.resolve({
+      id: entry.id,
+      directory: entry.directory,
+      minecraft: { version: mcVersion },
+      loader: loaderHintToInput(loaderHint)
+    });
+  } catch (error) {
+    ctx.ui.log("error", formatUserError(error));
+    return null;
+  }
+}
+async function pickMinecraftVersionFromEntry(ctx, entry) {
+  if (entry.minecraftVersions.length === 0) {
+    ctx.ui.log("warn", "Installation has no Minecraft versions on disk.");
+    return null;
+  }
+  if (entry.minecraftVersions.length === 1) {
+    return entry.minecraftVersions[0] ?? null;
+  }
+  const choice = await ctx.ui.select({
+    message: "Multiple Minecraft versions on disk \u2014 pick one",
+    options: entry.minecraftVersions.map((v) => ({ label: v, value: v })),
+    allowCancel: true
+  });
+  if (choice.kind !== "ok") return null;
+  return choice.value;
+}
+function loaderHintToInput(hint) {
+  if (!hint) return { type: Loaders.VANILLA };
+  if (hint.type === Loaders.FABRIC) {
+    return hint.version ? { type: Loaders.FABRIC, version: hint.version } : { type: Loaders.FABRIC, preference: VersionPreference.LATEST };
+  }
+  if (hint.type === Loaders.FORGE) {
+    return hint.version ? { type: Loaders.FORGE, version: hint.version } : { type: Loaders.FORGE, preference: VersionPreference.RECOMMENDED };
+  }
+  return { type: Loaders.VANILLA };
+}
+function filterVersionsByChannel(versions, channel) {
+  if (channel === "all") return versions;
+  if (channel === "old") {
+    return versions.filter(
+      (v) => v.type === MinecraftChannels.OLD_BETA || v.type === MinecraftChannels.OLD_ALPHA
+    );
+  }
+  return versions.filter((v) => v.type === channel);
+}
+
+// src/cli/scenarios/install.ts
+async function scenarioInstallMinecraft(ctx) {
+  const sel = {
+    channel: null,
+    version: null,
+    runtimeOverride: null,
+    installType: null,
+    fabricLoader: null,
+    forgeBuild: null,
+    forgeLabel: null,
+    directory: null
+  };
+  let step = "channel";
+  while (true) {
+    if (step === "channel") {
+      const r = await pickChannel(ctx.ui);
+      if (r.kind !== "ok") return "cancelled";
+      sel.channel = r.value;
+      step = "version";
+    } else if (step === "version") {
+      const r = await pickMinecraftVersion(ctx, sel.channel);
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") {
+        step = "channel";
+        continue;
+      }
+      sel.version = r.value;
+      step = "runtime";
+    } else if (step === "runtime") {
+      const r = await pickRuntime(ctx);
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") {
+        step = "version";
+        continue;
+      }
+      sel.runtimeOverride = r.value;
+      step = "install-type";
+    } else if (step === "install-type") {
+      const r = await pickInstallType(ctx.ui);
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") {
+        step = "runtime";
+        continue;
+      }
+      sel.installType = r.value;
+      if (r.value === Loaders.VANILLA) {
+        step = "directory";
+      } else if (r.value === Loaders.FABRIC) {
+        step = "fabric-loader";
+      } else {
+        step = "forge-build";
+      }
+    } else if (step === "fabric-loader") {
+      const r = await pickFabricLoader2(ctx, sel.version.id);
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") {
+        step = "install-type";
+        continue;
+      }
+      if (r.kind === "incompatible") {
+        ctx.ui.log(
+          "warn",
+          `Fabric is not available for Minecraft ${sel.version.id}. Pick another version or install type.`
+        );
+        step = "install-type";
+        continue;
+      }
+      sel.fabricLoader = r.value;
+      step = "directory";
+    } else if (step === "forge-build") {
+      const r = await pickForgeBuild(ctx, sel.version.id);
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") {
+        step = "install-type";
+        continue;
+      }
+      if (r.kind === "incompatible") {
+        ctx.ui.log(
+          "warn",
+          `Forge is not available for Minecraft ${sel.version.id}. Pick another version or install type.`
+        );
+        step = "install-type";
+        continue;
+      }
+      sel.forgeBuild = r.value;
+      sel.forgeLabel = r.label;
+      step = "directory";
+    } else if (step === "directory") {
+      const r = await pickDirectory(ctx, defaultIdFromSelection(sel));
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") {
+        step = previousFromDirectory(sel);
+        continue;
+      }
+      sel.directory = r.value;
+      step = "summary";
+    } else {
+      const ok = await confirmInstall(ctx, summaryRows(sel));
+      if (ok.kind === "cancel") return "cancelled";
+      if (ok.kind === "back") {
+        step = "directory";
+        continue;
+      }
+      if (!ok.value) return "cancelled";
+      const result = await runInstallFromSelection(ctx, sel);
+      if (result === "ok") return "completed";
+      step = result;
+    }
+  }
+}
+async function scenarioInstallRuntime(ctx) {
+  let step = "component";
+  let component = null;
+  let versionLabel = null;
+  let directory = null;
+  let installRoot = null;
+  while (true) {
+    if (step === "component") {
+      const r = await pickRuntimeComponent(ctx);
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") return "cancelled";
+      component = r.value.component;
+      versionLabel = r.value.versionName;
+      step = "directory";
+    } else if (step === "directory") {
+      const r = await pickDirectory(ctx, defaultIdFor("runtime", component ?? "java"));
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") {
+        step = "component";
+        continue;
+      }
+      directory = r.value;
+      step = "install-root";
+    } else if (step === "install-root") {
+      const r = await pickRuntimeInstallRoot(ctx);
+      if (r.kind === "cancel") return "cancelled";
+      if (r.kind === "back") {
+        step = "directory";
+        continue;
+      }
+      installRoot = r.value;
+      step = "summary";
+    } else {
+      const dir = directory;
+      const comp = component;
+      const ok = await confirmInstall(ctx, [
+        ["Goal", "Install Mojang Java runtime"],
+        ["Component", `${comp}${versionLabel ? ` (${versionLabel})` : ""}`],
+        ["Directory", dir],
+        ["Install root", installRoot ?? `${dir}/runtime (per-target)`]
+      ]);
+      if (ok.kind === "cancel") return "cancelled";
+      if (ok.kind === "back") {
+        step = "install-root";
+        continue;
+      }
+      if (!ok.value) return "cancelled";
+      try {
+        const runtime = await ctx.kit.versions.runtime.resolve({
+          system: ctx.kit.targets.system,
+          component: comp
+        });
+        const finalRuntime = installRoot !== null ? { ...runtime, installRoot } : runtime;
+        await runStandaloneRuntimeInstallWithProgress(ctx, {
+          id: path.basename(dir),
+          directory: dir,
+          runtime: finalRuntime
+        });
+        return "completed";
+      } catch (error) {
+        ctx.ui.log("error", formatUserError(error));
+        step = "component";
+      }
+    }
+  }
+}
+
+// src/cli/scenarios/verify-repair.ts
+async function verifyAllAspects(ctx, target) {
+  const results = [];
+  results.push(await ctx.kit.verify.minecraft.run(target));
+  if (target.loader.type === Loaders.FABRIC) {
+    results.push(await ctx.kit.verify.fabric.run(target));
+  } else if (target.loader.type === Loaders.FORGE) {
+    results.push(await ctx.kit.verify.forge.run(target));
+  }
+  results.push(await ctx.kit.verify.runtime.run(target));
+  return results;
+}
+function summarizeVerifications(results) {
+  const perKind = results.map((r) => ({ kind: r.kind, count: r.issues.length }));
+  const totalIssues = perKind.reduce((sum, p) => sum + p.count, 0);
+  return { totalIssues, perKind };
+}
+async function scenarioVerify(ctx) {
+  const target = await pickInstalledTarget(ctx);
+  if (!target) return "cancelled";
+  const spinner = ctx.ui.spinner();
+  spinner.start("Verifying\u2026");
+  try {
+    const results = await verifyAllAspects(ctx, target);
+    spinner.stop("Verification complete.");
+    const { totalIssues, perKind } = summarizeVerifications(results);
+    if (totalIssues === 0) {
+      ctx.ui.log("success", `${target.id} is clean.`);
+    } else {
+      const breakdown = perKind.filter((p) => p.count > 0).map((p) => `${p.kind}: ${p.count}`).join(", ");
+      ctx.ui.log(
+        "warn",
+        `${target.id}: ${totalIssues} issue(s) (${breakdown}). Run "Repair" to fix.`
+      );
+    }
+    return "completed";
+  } catch (error) {
+    spinner.stop("Verification failed.");
+    ctx.ui.log("error", formatUserError(error));
+    return "cancelled";
+  }
+}
+async function scenarioRepair(ctx) {
+  const target = await pickInstalledTarget(ctx);
+  if (!target) return "cancelled";
+  const verifySpinner = ctx.ui.spinner();
+  verifySpinner.start("Verifying installation\u2026");
+  try {
+    const verifications = await verifyAllAspects(ctx, target);
+    const { totalIssues, perKind } = summarizeVerifications(verifications);
+    if (totalIssues === 0) {
+      verifySpinner.stop("Nothing to repair.");
+      ctx.ui.log("success", "Installation is already clean.");
+      return "completed";
+    }
+    const breakdown = perKind.filter((p) => p.count > 0).map((p) => `${p.kind}: ${p.count}`).join(", ");
+    verifySpinner.stop(`Found ${totalIssues} issue(s) \u2014 ${breakdown}.`);
+    const ok = await ctx.ui.confirm({ message: `Repair ${totalIssues} item(s)?`, initial: true });
+    if (ok.kind !== "ok" || !ok.value) return "cancelled";
+    const aspects = [
+      { key: "minecraft", verification: verifications.find((v) => v.kind === "minecraft") },
+      { key: "fabric", verification: verifications.find((v) => v.kind === "fabric") },
+      { key: "forge", verification: verifications.find((v) => v.kind === "forge") },
+      { key: "runtime", verification: verifications.find((v) => v.kind === "runtime") }
+    ];
+    for (const aspect of aspects) {
+      if (!aspect.verification || aspect.verification.issues.length === 0) continue;
+      const plan = await ctx.kit.repair[aspect.key].plan(target, { from: aspect.verification });
+      if (plan.totalActions === 0) continue;
+      const renderer = new ProgressRenderer({
+        ui: ctx.ui,
+        label: `Repair ${aspect.key}`,
+        totalActions: plan.totalActions,
+        totalBytes: plan.totalBytes
+      });
+      const onEvent = renderer.attach();
+      try {
+        await ctx.kit.repair[aspect.key].run(plan, { onEvent });
+        const summary = renderer.finish();
+        ctx.ui.note(`Repair ${aspect.key} summary`, formatSummary(summary));
+      } catch (error) {
+        renderer.fail(formatUserError(error));
+        throw error;
+      }
+    }
+    return "completed";
+  } catch (error) {
+    ctx.ui.log("error", formatUserError(error));
+    return "cancelled";
+  }
+}
+
+// src/cli/scenarios/launch.ts
+async function scenarioLaunch(ctx) {
+  const target = await pickInstalledTarget(ctx);
+  if (!target) return "cancelled";
+  const usernameOutcome = await ctx.ui.text({
+    message: "Player username",
+    placeholder: "Player",
+    initial: "Player",
+    allowBack: true,
+    validate: (s) => s.trim().length === 0 ? "Username must be non-empty" : void 0
+  });
+  if (usernameOutcome.kind !== "ok") return "cancelled";
+  try {
+    const composition = await ctx.kit.launch.compose(target, {
+      auth: { mode: AuthModes.OFFLINE, username: usernameOutcome.value.trim() }
+    });
+    ctx.ui.note(
+      "Launch summary",
+      [
+        `Java:       ${composition.javaPath}`,
+        `Main class: ${composition.mainClass}`,
+        `Classpath:  ${composition.classpath.length} entries`,
+        `Natives:    ${composition.nativesDirectory}`,
+        `Working:    ${composition.workingDirectory}`
+      ].join("\n")
+    );
+    const ok = await ctx.ui.confirm({ message: "Spawn Minecraft now?", initial: true });
+    if (ok.kind !== "ok" || !ok.value) return "cancelled";
+    const session = ctx.kit.launch.run(composition, {
+      onEvent: (event) => {
+        if (event.type === "launch:stdout" || event.type === "launch:stderr") {
+          ctx.ui.log(event.type === "launch:stderr" ? "warn" : "info", event.line);
+        }
+      }
+    });
+    ctx.ui.log("info", `Started PID ${session.pid}. Waiting for exit\u2026`);
+    await session.exited;
+    ctx.ui.log("success", "Game exited.");
+    return "completed";
+  } catch (error) {
+    ctx.ui.log("error", formatUserError(error));
+    return "cancelled";
+  }
+}
+
+// src/cli/scenarios/inspect.ts
+async function scenarioInspect(ctx) {
+  try {
+    const list = await ctx.kit.targets.list({ rootDir: ctx.rootDir });
+    if (list.length === 0) {
+      ctx.ui.log("warn", "No installations found. Install one first.");
+      return "completed";
+    }
+    const choice = await ctx.ui.select({
+      message: "Pick an installation to inspect",
+      options: list.map((entry2) => ({
+        label: entry2.id,
+        value: entry2.id,
+        hint: entry2.minecraftVersions.join(", ") || "no versions"
+      })),
+      allowCancel: true
+    });
+    if (choice.kind !== "ok") return "cancelled";
+    const entry = list.find((e) => e.id === choice.value);
+    if (!entry) return "cancelled";
+    ctx.ui.note(`Inspect: ${entry.id}`, formatDetailed(entry));
+    return "completed";
+  } catch (error) {
+    ctx.ui.log("error", formatUserError(error));
+    return "cancelled";
+  }
+}
+
+// src/cli/ui.ts
+var BACK = /* @__PURE__ */ Symbol("mckit:back");
+var CANCEL = /* @__PURE__ */ Symbol("mckit:cancel");
+async function createClackUi() {
+  const clack = await import('@clack/prompts');
+  return buildUi(clack);
+}
+var MAX_VISIBLE_OPTIONS = 50;
+var DEFAULT_SEARCH_THRESHOLD = 30;
+function buildUi(clack) {
+  return {
+    intro: (m) => clack.intro(m),
+    outro: (m) => clack.outro(m),
+    write: (m) => process.stdout.write(`${m}
+`),
+    note: (title, body) => clack.note(body, title),
+    log: (level, message) => clack.log[level](message),
+    text: async (input) => {
+      const value = await clack.text({
+        message: input.message,
+        ...input.placeholder !== void 0 ? { placeholder: input.placeholder } : {},
+        ...input.initial !== void 0 ? { initialValue: input.initial } : {},
+        ...input.validate !== void 0 ? { validate: input.validate } : {}
+      });
+      if (clack.isCancel(value)) return { kind: "cancel" };
+      return { kind: "ok", value: typeof value === "string" ? value : "" };
+    },
+    select: async (input) => runSelect(clack, input),
+    searchableSelect: async (input) => searchableSelect(clack, input),
+    confirm: async (input) => {
+      const value = await clack.confirm({
+        message: input.message,
+        ...input.initial !== void 0 ? { initialValue: input.initial } : {}
+      });
+      if (clack.isCancel(value)) return { kind: "cancel" };
+      return { kind: "ok", value };
+    },
+    // Bypass clack.spinner() for progress: clack's spinner sometimes prints a fresh line
+    // per update on Windows / older versions, defeating in-place rendering. Our own
+    // {@link createInPlaceSpinner} writes raw ANSI escapes to stdout so updates always
+    // overwrite the previous line.
+    spinner: () => createInPlaceSpinner()
+  };
+}
+var DEFAULT_OUT = {
+  write(chunk) {
+    process.stdout.write(chunk);
+  },
+  get isTTY() {
+    return process.stdout.isTTY === true;
+  }
+};
+function createInPlaceSpinner(input = {}) {
+  const out = input.out ?? DEFAULT_OUT;
+  let started = false;
+  let lastLine = "";
+  return {
+    start(message) {
+      if (started) {
+        if (message !== lastLine) {
+          lastLine = message;
+          if (out.isTTY) {
+            out.write(`\r\x1B[2K${message}`);
+          } else {
+            out.write(`${message}
+`);
+          }
+        }
+        return;
+      }
+      started = true;
+      lastLine = message;
+      if (out.isTTY) {
+        out.write(message);
+      } else {
+        out.write(`${message}
+`);
+      }
+    },
+    message(message) {
+      if (!started) return;
+      if (message === lastLine) return;
+      lastLine = message;
+      if (out.isTTY) {
+        out.write(`\r\x1B[2K${message}`);
+      }
+    },
+    stop(message) {
+      if (!started) {
+        if (message !== void 0) {
+          out.write(`${message}
+`);
+        }
+        return;
+      }
+      const finalText = message ?? lastLine;
+      if (out.isTTY) {
+        out.write(`\r\x1B[2K${finalText}
+`);
+      } else {
+        out.write(`${finalText}
+`);
+      }
+      started = false;
+      lastLine = "";
+    }
+  };
+}
+async function runSelect(clack, input) {
+  const augmentedOptions = input.options.map(
+    (option) => {
+      const opt = {
+        label: option.label,
+        value: option.value
+      };
+      if (option.hint !== void 0) opt.hint = option.hint;
+      return opt;
+    }
+  );
+  if (input.allowBack === true) {
+    augmentedOptions.push({ label: "\u2190 Back", value: BACK });
+  }
+  if (input.allowCancel === true) {
+    augmentedOptions.push({ label: "\u2715 Cancel", value: CANCEL });
+  }
+  const result = await clack.select({
+    message: input.message,
+    options: augmentedOptions,
+    maxItems: 12,
+    ...input.initialValue !== void 0 ? { initialValue: input.initialValue } : {}
+  });
+  if (clack.isCancel(result)) return { kind: "cancel" };
+  if (result === BACK) return { kind: "back" };
+  if (result === CANCEL) return { kind: "cancel" };
+  return { kind: "ok", value: result };
+}
+async function searchableSelect(clack, input) {
+  const threshold = input.searchThreshold ?? DEFAULT_SEARCH_THRESHOLD;
+  if (input.options.length <= threshold) {
+    return runSelect(clack, input);
+  }
+  const trimmed = input.options.slice(0, MAX_VISIBLE_OPTIONS);
+  const truncatedHint = input.options.length > MAX_VISIBLE_OPTIONS ? ` (top ${MAX_VISIBLE_OPTIONS} of ${input.options.length})` : "";
+  return runSelect(clack, {
+    message: `${input.message}${truncatedHint}`,
+    options: trimmed,
+    ...input.allowBack === true ? { allowBack: true } : {},
+    ...input.allowCancel === true ? { allowCancel: true } : {}
+  });
+}
+
+// src/cli/main.ts
+var SCENARIO_KEYS = {
+  INSTALL_MC: "install-minecraft",
+  INSTALL_RUNTIME: "install-runtime",
+  VERIFY: "verify",
+  REPAIR: "repair",
+  LAUNCH: "launch",
+  INSPECT: "inspect",
+  EXIT: "exit"
+};
+async function runCli(input) {
+  if (input.args.includes("--help") || input.args.includes("-h")) {
+    input.ui.note(
+      "mckit \u2014 minecraft-kit CLI",
+      "Run with no arguments for the interactive menu.\n--version, --help, --debug"
+    );
+    return 0;
+  }
+  if (input.args.includes("--version") || input.args.includes("-v")) {
+    input.ui.log("info", "0.1.0");
+    return 0;
+  }
+  const debug = input.args.includes("--debug");
+  const kit = input.kit ?? new MinecraftKit();
+  const ctx = { kit, ui: input.ui, rootDir: input.rootDir };
+  input.ui.intro("mckit \u2014 Minecraft launcher kit");
+  while (true) {
+    const choice = await input.ui.select({
+      message: "What would you like to do?",
+      options: MAIN_MENU
+    });
+    if (choice.kind !== "ok" || choice.value === SCENARIO_KEYS.EXIT) {
+      input.ui.outro("Goodbye.");
+      return 0;
+    }
+    try {
+      const outcome = await dispatch(choice.value, ctx);
+      if (outcome === "cancelled") {
+        input.ui.log("info", "Operation cancelled.");
+      }
+    } catch (error) {
+      if (debug) {
+        input.ui.log("error", `${error instanceof Error ? error.stack : String(error)}`);
+      } else {
+        input.ui.log("error", formatUserError(error));
+      }
+    }
+  }
+}
+var MAIN_MENU = [
+  { label: "Install Minecraft", value: SCENARIO_KEYS.INSTALL_MC, hint: "Vanilla / Fabric / Forge" },
+  { label: "Install Java/runtime", value: SCENARIO_KEYS.INSTALL_RUNTIME },
+  { label: "Verify installation", value: SCENARIO_KEYS.VERIFY },
+  { label: "Repair installation", value: SCENARIO_KEYS.REPAIR },
+  { label: "Launch Minecraft", value: SCENARIO_KEYS.LAUNCH },
+  { label: "Inspect installation", value: SCENARIO_KEYS.INSPECT },
+  { label: "Exit", value: SCENARIO_KEYS.EXIT }
+];
+async function dispatch(choice, ctx) {
+  switch (choice) {
+    case SCENARIO_KEYS.INSTALL_MC:
+      return scenarioInstallMinecraft(ctx);
+    case SCENARIO_KEYS.INSTALL_RUNTIME:
+      return scenarioInstallRuntime(ctx);
+    case SCENARIO_KEYS.VERIFY:
+      return scenarioVerify(ctx);
+    case SCENARIO_KEYS.REPAIR:
+      return scenarioRepair(ctx);
+    case SCENARIO_KEYS.LAUNCH:
+      return scenarioLaunch(ctx);
+    case SCENARIO_KEYS.INSPECT:
+      return scenarioInspect(ctx);
+    default:
+      ctx.ui.log("warn", `Unknown action: ${choice}`);
+      return "cancelled";
+  }
+}
+async function bin() {
+  const ui = await createClackUi();
+  const code = await runCli({
+    args: process2.argv.slice(2),
+    ui,
+    rootDir: process2.cwd()
+  });
+  process2.exit(code);
+}
+
+// src/cli/index.ts
+void bin();
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map