minecraft-server-dl-cli 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# minecraft-server-dl-cli
+
+[![npm version](https://img.shields.io/npm/v/minecraft-server-dl-cli.svg)](https://www.npmjs.com/package/minecraft-server-dl-cli)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A simple CLI tool for downloading the official Minecraft Java `server.jar` by version.
+
+This tool reads Mojang's official version manifest, resolves the requested Minecraft Java version, downloads the matching `server.jar`, and verifies the downloaded file using SHA1 when available.
+
+## Languages
+
+* [English](README.md)
+* [繁體中文](README.zh-TW.md)
+
+## Features
+
+* Download official Minecraft Java `server.jar` by version
+* Uses Mojang's official version manifest
+* Automatically names files as `server_<version>.jar`
+* Supports custom output paths
+* Supports SHA1 and file size verification
+* Can print the resolved download URL without downloading
+* No runtime dependencies
+
+## Official Data Sources
+
+This tool uses Mojang/Minecraft official endpoints:
+
+* [Minecraft Java version manifest](https://piston-meta.mojang.com/mc/game/version_manifest_v2.json)
+* [Official Minecraft Java server download page](https://www.minecraft.net/en-us/download/server)
+
+The resolved `server.jar` URL usually points to:
+
+```text
+https://piston-data.mojang.com/v1/objects/<sha1>/server.jar
+```
+
+## Requirements
+
+* [Node.js](https://nodejs.org/) 18 or later
+* npm, pnpm, or yarn
+
+## Installation
+
+Install globally from npm:
+
+```bash
+npm install -g minecraft-server-dl-cli
+```
+
+Then run:
+
+```bash
+mc-server-dl 1.21.8
+```
+
+Or use it directly with `npx`:
+
+```bash
+npx minecraft-server-dl-cli 1.21.8
+```
+
+## Usage
+
+```bash
+mc-server-dl <version> [options]
+```
+
+Example:
+
+```bash
+mc-server-dl 1.21.8
+```
+
+This downloads:
+
+```text
+server_1.21.8.jar
+```
+
+## Options
+
+| Option                | Description                                             |
+| --------------------- | ------------------------------------------------------- |
+| `-o, --output <path>` | Custom output path                                      |
+| `--no-verify`         | Skip SHA1 and file size verification                    |
+| `--url-only`          | Print the resolved `server.jar` URL without downloading |
+| `-h, --help`          | Show help message                                       |
+
+## Examples
+
+Download a specific Minecraft Java server version:
+
+```bash
+mc-server-dl 1.21.8
+```
+
+Download and save to a custom path:
+
+```bash
+mc-server-dl 1.21.8 -o ./servers/1.21.8/server.jar
+```
+
+Print the official download URL only:
+
+```bash
+mc-server-dl 1.21.8 --url-only
+```
+
+Skip verification:
+
+```bash
+mc-server-dl 1.21.8 --no-verify
+```
+
+## Exit Codes
+
+| Code | Meaning                                                   |
+| ---: | --------------------------------------------------------- |
+|  `0` | Success                                                   |
+|  `1` | Unexpected error                                          |
+|  `2` | Invalid CLI arguments                                     |
+|  `3` | Failed to fetch or parse metadata                         |
+|  `4` | Minecraft version not found                               |
+|  `5` | Version exists, but no official `server.jar` is available |
+|  `6` | Download failed                                           |
+|  `7` | File size or SHA1 verification failed                     |
+
+## How It Works
+
+1. Fetches Mojang's version manifest.
+2. Finds the requested Minecraft Java version.
+3. Fetches that version's metadata JSON.
+4. Reads `downloads.server.url`.
+5. Downloads the official `server.jar`.
+6. Verifies file size and SHA1 when metadata is available.
+
+## Disclaimer
+
+This project is not affiliated with Mojang Studios or Microsoft.
+
+Minecraft is a trademark of Mojang Synergies AB. This tool only resolves and downloads files from official Mojang/Minecraft endpoints.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-TW.md

@@ -0,0 +1,147 @@
+# minecraft-server-dl-cli
+
+[![npm version](https://img.shields.io/npm/v/minecraft-server-dl-cli.svg)](https://www.npmjs.com/package/minecraft-server-dl-cli)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+一個簡易的 CLI 工具，用來依照指定版本下載官方 Minecraft Java `server.jar`。
+
+這個工具會讀取 Mojang 官方版本清單，解析指定的 Minecraft Java 版本，下載對應的 `server.jar`，並在 metadata 有提供時使用 SHA1 驗證下載結果。
+
+## 語言
+
+* [English](README.md)
+* [繁體中文](README.zh-TW.md)
+
+## 功能
+
+* 依照版本下載官方 Minecraft Java `server.jar`
+* 使用 Mojang 官方版本 manifest
+* 預設輸出檔名為 `server_<version>.jar`
+* 支援自訂輸出路徑
+* 支援 SHA1 與檔案大小驗證
+* 可只印出解析後的下載 URL，不下載檔案
+* 不需要額外 runtime dependencies
+
+## 官方資料來源
+
+本工具使用 Mojang/Minecraft 官方端點：
+
+* [Minecraft Java version manifest](https://piston-meta.mojang.com/mc/game/version_manifest_v2.json)
+* [Minecraft Java 官方伺服器下載頁](https://www.minecraft.net/en-us/download/server)
+
+解析後的 `server.jar` 下載 URL 通常會長這樣：
+
+```text
+https://piston-data.mojang.com/v1/objects/<sha1>/server.jar
+```
+
+## 系統需求
+
+* [Node.js](https://nodejs.org/) 18 或更新版本
+* npm、pnpm 或 yarn
+
+## 安裝
+
+從 npm 全域安裝：
+
+```bash
+npm install -g minecraft-server-dl-cli
+```
+
+執行：
+
+```bash
+mc-server-dl 1.21.8
+```
+
+或直接使用 `npx`：
+
+```bash
+npx minecraft-server-dl-cli 1.21.8
+```
+
+## 使用方式
+
+```bash
+mc-server-dl <version> [options]
+```
+
+範例：
+
+```bash
+mc-server-dl 1.21.8
+```
+
+會下載成：
+
+```text
+server_1.21.8.jar
+```
+
+## 參數
+
+| 參數                    | 說明                             |
+| --------------------- | ------------------------------ |
+| `-o, --output <path>` | 自訂輸出路徑                         |
+| `--no-verify`         | 跳過 SHA1 與檔案大小驗證                |
+| `--url-only`          | 只印出解析後的 `server.jar` URL，不下載檔案 |
+| `-h, --help`          | 顯示說明                           |
+
+## 範例
+
+下載指定 Minecraft Java server 版本：
+
+```bash
+mc-server-dl 1.21.8
+```
+
+下載到指定路徑：
+
+```bash
+mc-server-dl 1.21.8 -o ./servers/1.21.8/server.jar
+```
+
+只印出官方下載 URL：
+
+```bash
+mc-server-dl 1.21.8 --url-only
+```
+
+跳過驗證：
+
+```bash
+mc-server-dl 1.21.8 --no-verify
+```
+
+## Exit Codes
+
+| Code | 意義                          |
+| ---: | --------------------------- |
+|  `0` | 成功                          |
+|  `1` | 未預期錯誤                       |
+|  `2` | CLI 參數錯誤                    |
+|  `3` | metadata 取得或解析失敗            |
+|  `4` | 找不到指定 Minecraft 版本          |
+|  `5` | 版本存在，但沒有官方 `server.jar` 可下載 |
+|  `6` | 下載失敗                        |
+|  `7` | 檔案大小或 SHA1 驗證失敗             |
+
+## 運作方式
+
+1. 取得 Mojang version manifest。
+2. 找到使用者指定的 Minecraft Java 版本。
+3. 取得該版本的 metadata JSON。
+4. 讀取 `downloads.server.url`。
+5. 下載官方 `server.jar`。
+6. 若 metadata 有提供，驗證檔案大小與 SHA1。
+
+## 免責聲明
+
+本專案與 Mojang Studios 或 Microsoft 沒有關聯。
+
+Minecraft 是 Mojang Synergies AB 的商標。本工具只會解析並下載 Mojang/Minecraft 官方端點提供的檔案。
+
+## 授權
+
+[MIT](LICENSE)

package/bin/mc-server-dl.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, rename, rm, stat } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const MANIFEST_URL = 'https://piston-meta.mojang.com/mc/game/version_manifest_v2.json';
+const USER_AGENT = 'mc-server-dl-cli/0.1.0';
+
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+  }
+}
+
+function printHelp() {
+  console.log(`
+Usage:
+  mc-server-dl <version> [options]
+
+Options:
+  -o, --output <path>    Output jar path. Default: server_<version>.jar
+  --no-verify           Skip SHA1 verification
+  --url-only            Print server.jar URL only, do not download
+  -h, --help            Show help
+
+Examples:
+  mc-server-dl 1.21.8
+  mc-server-dl 1.21.8 -o ./servers/1.21.8/server.jar
+  mc-server-dl 1.21.8 --url-only
+`.trim());
+}
+
+function parseArgs(argv) {
+  const args = {
+    version: null,
+    output: null,
+    verify: true,
+    urlOnly: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === '-h' || token === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+
+    if (token === '-o' || token === '--output') {
+      const value = argv[i + 1];
+
+      if (!value || value.startsWith('-')) {
+        throw new CliError('Missing output path: -o <path>', 2);
+      }
+
+      args.output = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === '--no-verify') {
+      args.verify = false;
+      continue;
+    }
+
+    if (token === '--url-only') {
+      args.urlOnly = true;
+      continue;
+    }
+
+    if (token.startsWith('-')) {
+      throw new CliError(`Unknown option: ${token}`, 2);
+    }
+
+    if (args.version) {
+      throw new CliError(`Only one Minecraft version can be specified. Extra argument: ${token}`, 2);
+    }
+
+    args.version = token;
+  }
+
+  if (!args.version) {
+    throw new CliError('Please specify a Minecraft version, for example: mc-server-dl 1.21.8', 2);
+  }
+
+  return args;
+}
+
+async function getJson(url) {
+  const response = await fetch(url, {
+    headers: {
+      // Make requests identifiable in server logs for easier troubleshooting.
+      'User-Agent': USER_AGENT,
+      Accept: 'application/json'
+    }
+  });
+
+  if (!response.ok) {
+    throw new CliError(`HTTP ${response.status}: ${url}`, 3);
+  }
+
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new CliError(`Failed to parse JSON response: ${url}`, 3);
+  }
+}
+
+function findVersion(manifest, version) {
+  const item = manifest.versions?.find((entry) => entry.id === version);
+
+  if (!item) {
+    const latestRelease = manifest.latest?.release ?? 'unknown';
+    const latestSnapshot = manifest.latest?.snapshot ?? 'unknown';
+
+    throw new CliError(
+      [
+        `Minecraft Java version not found: ${version}`,
+        `latest release: ${latestRelease}`,
+        `latest snapshot: ${latestSnapshot}`
+      ].join('\n'),
+      4
+    );
+  }
+
+  return item;
+}
+
+async function resolveServerDownload(version) {
+  const manifest = await getJson(MANIFEST_URL);
+  const versionMeta = findVersion(manifest, version);
+  const versionJson = await getJson(versionMeta.url);
+
+  const server = versionJson.downloads?.server;
+
+  if (!server?.url) {
+    throw new CliError(`Version ${version} exists, but no official server.jar download is available.`, 5);
+  }
+
+  return {
+    version,
+    url: server.url,
+    sha1: server.sha1 ?? '',
+    size: Number(server.size ?? 0)
+  };
+}
+
+async function downloadFile(url, outputPath) {
+  const absoluteOutputPath = resolve(outputPath);
+  const tempPath = `${absoluteOutputPath}.tmp-${process.pid}`;
+
+  await mkdir(dirname(absoluteOutputPath), { recursive: true });
+
+  try {
+    const response = await fetch(url, {
+      headers: {
+        'User-Agent': USER_AGENT
+      }
+    });
+
+    if (!response.ok) {
+      throw new CliError(`Download failed, HTTP ${response.status}: ${url}`, 6);
+    }
+
+    if (!response.body) {
+      throw new CliError('Download failed: response body is empty', 6);
+    }
+
+    // Write to a temporary file first to avoid replacing an existing valid server.jar on failure.
+    await pipeline(
+      Readable.fromWeb(response.body),
+      createWriteStream(tempPath)
+    );
+
+    await rename(tempPath, absoluteOutputPath);
+
+    return absoluteOutputPath;
+  } catch (error) {
+    await rm(tempPath, { force: true });
+
+    if (error instanceof CliError) {
+      throw error;
+    }
+
+    throw new CliError(`Download failed: ${error.message}`, 6);
+  }
+}
+
+async function sha1OfFile(path) {
+  const hash = createHash('sha1');
+  const fileStream = Readable.toWeb(
+    await import('node:fs').then(({ createReadStream }) => createReadStream(path))
+  );
+
+  const reader = fileStream.getReader();
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (done) {
+        break;
+      }
+
+      hash.update(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return hash.digest('hex');
+}
+
+async function verifyFile(path, expectedSha1, expectedSize) {
+  if (expectedSize > 0) {
+    const fileStat = await stat(path);
+
+    if (fileStat.size !== expectedSize) {
+      throw new CliError(
+        `File size mismatch: expected=${expectedSize}, actual=${fileStat.size}`,
+        7
+      );
+    }
+  }
+
+  if (!expectedSha1) {
+    return;
+  }
+
+  const actualSha1 = await sha1OfFile(path);
+
+  if (actualSha1.toLowerCase() !== expectedSha1.toLowerCase()) {
+    throw new CliError(
+      [
+        'SHA1 verification failed:',
+        `expected: ${expectedSha1}`,
+        `actual:   ${actualSha1}`
+      ].join('\n'),
+      7
+    );
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const server = await resolveServerDownload(args.version);
+
+  if (args.urlOnly) {
+    console.log(server.url);
+    return;
+  }
+
+  console.log(`Version: ${server.version}`);
+  console.log(`URL: ${server.url}`);
+
+  const output = args.output ?? `server_${server.version}.jar`;
+  const outputPath = await downloadFile(server.url, output);
+
+  if (args.verify) {
+    await verifyFile(outputPath, server.sha1, server.size);
+  }
+
+  console.log(`Downloaded: ${outputPath}`);
+}
+
+main().catch((error) => {
+  if (error instanceof CliError) {
+    console.error(`Error: ${error.message}`);
+    process.exit(error.exitCode);
+  }
+
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "minecraft-server-dl-cli",
+  "version": "0.1.0",
+  "description": "Download official Minecraft Java server.jar by version.",
+  "type": "module",
+  "bin": {
+    "mc-server-dl": "./bin/mc-server-dl.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "node ./bin/mc-server-dl.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "minecraft",
+    "server",
+    "cli",
+    "downloader",
+    "mojang"
+  ],
+  "author": "DoSer ZBlock",
+  "license": "MIT"
+}