nitro-patcher 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitro-patcher",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Native Node.js Nintendo DS ROM reader, repacker and ZIP/Xdelta patcher",
   "type": "module",
   "engines": {
@@ -50,15 +50,19 @@
     "@noble/hashes": "2.4.0",
     "@types/node": "22.20.2",
     "buffer": "6.0.3",
-    "esbuild": "0.27.3",
+    "esbuild": "0.28.1",
     "eslint": "10.9.1",
     "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-import-x": "4.17.1",
+    "eslint-plugin-prettier": "5.5.5",
+    "eslint-plugin-unused-imports": "4.4.1",
     "fflate": "0.8.3",
     "globals": "16.5.0",
     "jiti": "2.7.0",
     "prettier": "3.9.6",
     "tsup": "8.5.1",
     "tsx": "4.23.13",
+    "type-fest": "4.41.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.70.0"
   },
@@ -68,6 +72,9 @@
     "#browser-hmac": "@noble/hashes/hmac.js",
     "#browser-aes": "@noble/ciphers/aes.js"
   },
+  "dependencies": {
+    "markdansi": "0.3.3"
+  },
   "scripts": {
     "clean": "tsx scripts/clean.ts",
     "build": "pnpm run build:node && pnpm run build:browser",

package/src/browser/buffer.ts

@@ -1 +1 @@
-export { Buffer } from 'buffer';
+export { Buffer } from "buffer";

package/src/browser.ts

@@ -1,5 +1,28 @@
-import { NDSFile } from './nitro/nds-file';
-import { patchBuffer as patch } from './nitro-patch-helper';
+import { NDSFile } from "./nitro/nds-file";
+import {
+  extractZipEntry as extractEntry,
+  patchBuffer as patch,
+  readPatchInfo as readInfo,
+  readPatchMetadata as readMetadata,
+  readPatchReadme as readReadme,
+} from "./nitro-patch-helper";
+
+export interface PatchMetadata {
+  id?: string;
+  author?: string;
+  name?: string;
+  homepage?: string;
+  version?: string;
+  isBeta?: boolean;
+}
+export interface PatchReadme {
+  format: "markdown" | "plaintext";
+  content: string;
+}
+export interface PatchInfo {
+  metadata: PatchMetadata | null;
+  readme: PatchReadme | null;
+}
 
 export interface BrowserPatchOptions {
   maxOutputSize?: number;
@@ -9,7 +32,7 @@ export interface BrowserPatchOptions {
 }
 export interface BrowserPatchResult {
   buffer: Uint8Array<ArrayBuffer>;
-  returnValue: 'SUCCESS' | 'MD5_MISMATCH';
+  returnValue: "SUCCESS" | "MD5_MISMATCH";
   inputMd5: string;
   outputMd5: string;
 }
@@ -56,5 +79,27 @@ export const patchBuffer = (
     outputMd5: result.outputMd5,
   };
 };
-export const PatchHelper = Object.freeze({ patchBuffer });
+/** Read and validate metadata.json from a patch package entirely in memory. */
+export const readPatchMetadata = (archive: Uint8Array, options: BrowserPatchOptions = {}): PatchMetadata | null =>
+  readMetadata(archive, options);
+/** Read a root README.md or README.txt from a patch package entirely in memory. */
+export const readPatchReadme = (archive: Uint8Array, options: BrowserPatchOptions = {}): PatchReadme | null =>
+  readReadme(archive, options);
+/** Read metadata and README content while parsing the patch package only once. */
+export const readPatchInfo = (archive: Uint8Array, options: BrowserPatchOptions = {}): PatchInfo =>
+  readInfo(archive, options);
+/** Extract one file from a ZIP archive entirely in memory. */
+export const extractZipEntry = (
+  archive: Uint8Array,
+  entryName: string,
+  options: BrowserPatchOptions = {},
+): Uint8Array<ArrayBuffer> => new Uint8Array(extractEntry(archive, entryName, options));
+
+export const PatchHelper = Object.freeze({
+  extractZipEntry,
+  patchBuffer,
+  readPatchInfo,
+  readPatchMetadata,
+  readPatchReadme,
+});
 export const NitroHelper = Object.freeze({ inspectRom });

package/src/cli.ts

@@ -1,16 +1,24 @@
 #!/usr/bin/env node
-import { mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
-import { parseArgs } from 'node:util';
-import { patchIt } from './nitro-patch-helper';
+import { render } from "markdansi";
+import { mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+import { type PatchMetadata, patchBuffer, readPatchInfo } from "./nitro-patch-helper";
 
 const help = `nitro-patcher — 原生 Node.js NDS ROM 补丁工具
 
-用法：nitro-patcher [--json] <原始ROM> <补丁ZIP> <输出ROM>
+用法：
+  nitro-patcher [--json] [--dry-run] <原始ROM> <补丁ZIP> [输出ROM]
+  nitro-patcher [--json] [--dry-run] --input <原始ROM> --patch <补丁ZIP> [--output <输出ROM>]
 
-  --json        输出 JSON 状态和 MD5
-  -h, --help    显示帮助
-  -v, --version 显示版本`;
+  --json         输出 JSON 状态和 MD5
+  --dry-run      完整执行补丁流程，但不写入输出 ROM
+  -i, --input    原始 ROM 路径
+  -p, --patch    补丁 ZIP 路径
+  -o, --output   输出 ROM 路径；试运行时可省略
+  -h, --help     显示帮助
+  -v, --version  显示版本`;
 
 const sameFile = async (input: string, output: string): Promise<boolean> => {
   if (resolve(input) === resolve(output)) return true;
@@ -19,18 +27,55 @@ const sameFile = async (input: string, output: string): Promise<boolean> => {
     const destination = await stat(output);
     return original.dev === destination.dev && original.ino === destination.ino;
   } catch (error) {
-    if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
     return false;
   }
 };
 
+const safeTerminalText = (value: string): string => {
+  const characters: string[] = [];
+  for (const character of value.replaceAll("\r\n", "\n").replaceAll("\r", "\n")) {
+    const code = character.codePointAt(0)!;
+    if (
+      (code < 0x20 && code !== 0x09 && code !== 0x0a) ||
+      (code >= 0x7f && code <= 0x9f) ||
+      (code >= 0x202a && code <= 0x202e) ||
+      (code >= 0x2066 && code <= 0x2069)
+    )
+      continue;
+    characters.push(character);
+  }
+  return characters.join("");
+};
+
+const formatMetadata = (metadata: PatchMetadata): string => {
+  const labels = {
+    author: "作者",
+    name: "名称",
+    homepage: "主页",
+    version: "版本",
+  } as const;
+  const lines: string[] = [];
+  for (const field of ["author", "name", "homepage", "version"] as const) {
+    const value = metadata[field];
+    if (value === undefined) continue;
+    const suffix = field === "version" && metadata.isBeta ? "（测试版）" : "";
+    lines.push(`- ${labels[field]}：${safeTerminalText(value).replaceAll("\n", " ")}${suffix}`);
+  }
+  return lines.join("\n");
+};
+
 const main = async (): Promise<void> => {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
     options: {
-      help: { type: 'boolean', short: 'h' },
-      version: { type: 'boolean', short: 'v' },
-      json: { type: 'boolean' },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      json: { type: "boolean" },
+      "dry-run": { type: "boolean" },
+      input: { type: "string", short: "i" },
+      patch: { type: "string", short: "p" },
+      output: { type: "string", short: "o" },
     },
   });
   if (values.help) {
@@ -38,36 +83,77 @@ const main = async (): Promise<void> => {
     return;
   }
   if (values.version) {
-    const metadata: unknown = JSON.parse(
-      await readFile(new URL('../package.json', import.meta.url), 'utf8'),
-    );
-    if (
-      !metadata ||
-      typeof metadata !== 'object' ||
-      !('version' in metadata) ||
-      typeof metadata.version !== 'string'
-    )
-      throw new Error('Invalid package version metadata');
+    const metadata: unknown = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    if (!metadata || typeof metadata !== "object" || !("version" in metadata) || typeof metadata.version !== "string")
+      throw new Error("Invalid package version metadata");
     console.log(metadata.version);
     return;
   }
-  if (positionals.length !== 3) throw new Error(help);
-  const [original, patch, output] = positionals;
-  if ((await sameFile(original, output)) || (await sameFile(patch, output)))
-    throw new Error('输出路径不能覆盖原始 ROM 或补丁包。');
-  const result = await patchIt(original, patch);
-  const destination = join(await realpath(dirname(resolve(output))), basename(output));
-  const temporary = await mkdtemp(join(dirname(destination), '.nitro-patcher-'));
-  try {
-    const file = join(temporary, 'output.nds');
-    await writeFile(file, result.buffer);
-    await rename(file, destination);
-  } finally {
-    await rm(temporary, { recursive: true, force: true });
+  const dryRun = values["dry-run"] ?? false;
+  const usesNamedPaths = values.input !== undefined || values.patch !== undefined || values.output !== undefined;
+  if (usesNamedPaths && positionals.length > 0) throw new Error(help);
+  if (
+    (usesNamedPaths && (!values.input || !values.patch || (!dryRun && !values.output))) ||
+    (!usesNamedPaths &&
+      ((!dryRun && positionals.length !== 3) || (dryRun && (positionals.length < 2 || positionals.length > 3))))
+  )
+    throw new Error(help);
+  const [original, patch, output] = usesNamedPaths ? [values.input, values.patch, values.output] : positionals;
+  if (!original || !patch) throw new Error(help);
+  if (!dryRun) {
+    if (!output) throw new Error(help);
+    if ((await sameFile(original, output)) || (await sameFile(patch, output)))
+      throw new Error("输出路径不能覆盖原始 ROM 或补丁包。");
+  }
+  const [originalBytes, patchBytes] = await Promise.all([readFile(original), readFile(patch)]);
+  const info = readPatchInfo(patchBytes);
+  const result = patchBuffer(originalBytes, patchBytes);
+  if (!dryRun) {
+    if (!output) throw new Error(help);
+    const destination = join(await realpath(dirname(resolve(output))), basename(output));
+    const temporary = await mkdtemp(join(dirname(destination), ".nitro-patcher-"));
+    try {
+      const file = join(temporary, "output.nds");
+      await writeFile(file, result.buffer);
+      await rename(file, destination);
+    } finally {
+      await rm(temporary, { recursive: true, force: true });
+    }
   }
   const { returnValue, inputMd5, outputMd5 } = result;
-  if (values.json) console.log(JSON.stringify({ returnValue, inputMd5, outputMd5 }));
-  else console.log(`${returnValue}\n\n原始 ROM 的 MD5：${inputMd5}\n生成 ROM 的 MD5：${outputMd5}`);
+  if (values.json) {
+    console.log(
+      JSON.stringify({
+        returnValue,
+        inputMd5,
+        outputMd5,
+        ...info,
+        ...(dryRun && { dryRun: true }),
+      }),
+    );
+    return;
+  }
+
+  const sections: string[] = [];
+  if (info.metadata) {
+    const metadata = formatMetadata(info.metadata);
+    if (metadata) sections.push(`补丁元数据：\n\n${metadata}`);
+  }
+  if (info.readme) {
+    const content = safeTerminalText(info.readme.content);
+    const rendered =
+      info.readme.format === "markdown"
+        ? render(content, {
+            width: process.stdout.columns ?? 80,
+            color: Boolean(process.stdout.isTTY),
+            hyperlinks: false,
+          })
+        : content;
+    sections.push(`补丁说明：\n\n${rendered.trim()}`);
+  }
+  if (dryRun) sections.push("试运行完成，未写入输出 ROM。");
+  sections.push(`${returnValue}\n\n原始 ROM 的 MD5：${inputMd5}\n生成 ROM 的 MD5：${outputMd5}`);
+  console.log(sections.join("\n\n"));
 };
 
 main().catch((error: unknown) => {

package/src/index.ts

@@ -1,2 +1,2 @@
-export * from './nitro-helper';
-export * from './nitro-patch-helper';
+export * from "./nitro-helper";
+export * from "./nitro-patch-helper";

package/src/nitro/banner.ts

@@ -1,16 +1,16 @@
 // Port of NitroHelper/Banner.cs. Copyright Xzonn and upstream contributors, GPL-3.0.
-import { bytes, range } from './binary';
-import { crc16 } from './crc';
+import { bytes, range } from "./binary";
+import { crc16 } from "./crc";
 
 const titles = [
-  'japaneseTitle',
-  'englishTitle',
-  'frenchTitle',
-  'germanTitle',
-  'italianTitle',
-  'spanishTitle',
-  'chineseTitle',
-  'koreanTitle',
+  "japaneseTitle",
+  "englishTitle",
+  "frenchTitle",
+  "germanTitle",
+  "italianTitle",
+  "spanishTitle",
+  "chineseTitle",
+  "koreanTitle",
 ] as const;
 export class Banner {
   version: number;
@@ -18,21 +18,20 @@ export class Banner {
   bannerCRC: boolean;
   tileData: Buffer;
   palette: Buffer;
-  japaneseTitle = '';
-  englishTitle = '';
-  frenchTitle = '';
-  germanTitle = '';
-  italianTitle = '';
-  spanishTitle = '';
-  chineseTitle = '';
-  koreanTitle = '';
+  japaneseTitle = "";
+  englishTitle = "";
+  frenchTitle = "";
+  germanTitle = "";
+  italianTitle = "";
+  spanishTitle = "";
+  chineseTitle = "";
+  koreanTitle = "";
   constructor(input: Uint8Array, offset = 0, hardSize = 0) {
-    const data = bytes(input, 'banner');
-    this.version = range(data, offset, 2, 'banner').readUInt16LE();
+    const data = bytes(input, "banner");
+    this.version = range(data, offset, 2, "banner").readUInt16LE();
     let size = this.getDefSize(hardSize);
-    if (this.version >>> 8 === 1)
-      size = hardSize > 0 && hardSize !== 0xffffffff ? Math.min(hardSize, 0x23c0) : 0x23c0;
-    this.raw = Buffer.from(range(data, offset, size, 'banner'));
+    if (this.version >>> 8 === 1) size = hardSize > 0 && hardSize !== 0xffffffff ? Math.min(hardSize, 0x23c0) : 0x23c0;
+    this.raw = Buffer.from(range(data, offset, size, "banner"));
     this.bannerCRC = crc16(this.raw.subarray(0x20, 0x840)) === this.raw.readUInt16LE(2);
     this.tileData = Buffer.from(this.raw.subarray(0x20, 0x220));
     this.palette = Buffer.from(this.raw.subarray(0x220, 0x240));
@@ -41,9 +40,9 @@ export class Banner {
         i < this.titleCount
           ? this.raw
               .subarray(0x240 + i * 0x100, 0x340 + i * 0x100)
-              .toString('utf16le')
-              .split('\0')[0]
-          : '';
+              .toString("utf16le")
+              .split("\0")[0]
+          : "";
   }
   get titleCount() {
     return this.version >= 3 ? 8 : this.version >= 2 ? 7 : 6;
@@ -57,14 +56,12 @@ export class Banner {
   toBuffer() {
     const output = Buffer.from(this.raw);
     output.writeUInt16LE(this.version);
-    if (this.tileData.length !== 512 || this.palette.length !== 32)
-      throw new RangeError('Invalid banner icon size');
+    if (this.tileData.length !== 512 || this.palette.length !== 32) throw new RangeError("Invalid banner icon size");
     this.tileData.copy(output, 0x20);
     this.palette.copy(output, 0x220);
     for (let i = 0; i < this.titleCount; i++) {
-      const text = Buffer.from(this[titles[i]], 'utf16le');
-      if (text.length > 256)
-        throw new RangeError(`Banner ${titles[i]} exceeds 128 UTF-16 code units`);
+      const text = Buffer.from(this[titles[i]], "utf16le");
+      if (text.length > 256) throw new RangeError(`Banner ${titles[i]} exceeds 128 UTF-16 code units`);
       output.fill(0, 0x240 + i * 256, 0x340 + i * 256);
       text.copy(output, 0x240 + i * 256);
     }

package/src/nitro/binary.ts

@@ -1,16 +1,11 @@
 export const DEFAULT_MAX_SIZE = 0x40000000;
 
-export const bytes = (value: Uint8Array, name = 'input'): Buffer => {
+export const bytes = (value: Uint8Array, name = "input"): Buffer => {
   if (!(value instanceof Uint8Array)) throw new TypeError(`${name} must be a Buffer or Uint8Array`);
   return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
 };
 
-export const range = (
-  buffer: Buffer,
-  offset: number,
-  size: number,
-  name = 'binary data',
-): Buffer => {
+export const range = (buffer: Buffer, offset: number, size: number, name = "binary data"): Buffer => {
   if (
     !Number.isSafeInteger(offset) ||
     !Number.isSafeInteger(size) ||
@@ -18,16 +13,12 @@ export const range = (
     size < 0 ||
     offset + size > buffer.length
   ) {
-    throw new RangeError(
-      `Invalid ${name} range: offset=${offset}, size=${size}, available=${buffer.length}`,
-    );
+    throw new RangeError(`Invalid ${name} range: offset=${offset}, size=${size}, available=${buffer.length}`);
   }
   return buffer.subarray(offset, offset + size);
 };
 
-export const align = (value: number, alignment = 0x200): number => {
-  return Math.ceil(value / alignment) * alignment;
-};
+export const align = (value: number, alignment = 0x200): number => Math.ceil(value / alignment) * alignment;
 
 /** Seekable, bounded in-memory writer; unwritten gaps have MemoryStream's zero fill. */
 export class BinaryWriter {
@@ -37,7 +28,7 @@ export class BinaryWriter {
   length: number;
   constructor(initialSize = 65536, maxSize = DEFAULT_MAX_SIZE) {
     if (!Number.isSafeInteger(maxSize) || maxSize < 1 || maxSize > 0xffffffff)
-      throw new RangeError('Invalid output size limit');
+      throw new RangeError("Invalid output size limit");
     this.maxSize = maxSize;
     this.buffer = Buffer.alloc(Math.min(initialSize, maxSize));
     this.position = 0;
@@ -55,8 +46,7 @@ export class BinaryWriter {
 
   write(data: Uint8Array) {
     data = bytes(data);
-    if (!Number.isSafeInteger(this.position) || this.position < 0)
-      throw new RangeError('Invalid writer position');
+    if (!Number.isSafeInteger(this.position) || this.position < 0) throw new RangeError("Invalid writer position");
     this.ensure(this.position + data.length);
     bytes(data).copy(this.buffer, this.position);
     this.position += data.length;

package/src/nitro/blz.ts

@@ -7,7 +7,7 @@ export interface Arm9Header {
 // Native port of Xzonn/BlzHelper BLZ.cs (MIT), including overwrite-safe prefix.
 // Compression returns an empty Buffer when no smaller representation exists.
 export const decompressBLZ = (input: Buffer, maxSize = 0x10000000): Buffer => {
-  if (input.length < 8) throw new Error('BLZ footer is truncated');
+  if (input.length < 8) throw new Error("BLZ footer is truncated");
   const diff = input.readUInt32LE(input.length - 4);
   const packed = input.readUInt32LE(input.length - 8),
     header = packed >>> 24,
@@ -15,7 +15,7 @@ export const decompressBLZ = (input: Buffer, maxSize = 0x10000000): Buffer => {
   const size = input.length + diff,
     prefix = input.length - length;
   if (header < 8 || header > length || length > input.length || size > maxSize)
-    throw new Error('Invalid BLZ size or footer');
+    throw new Error("Invalid BLZ size or footer");
   const out = Buffer.alloc(size);
   input.copy(out, 0, 0, prefix);
   let src = input.length - header,
@@ -24,16 +24,15 @@ export const decompressBLZ = (input: Buffer, maxSize = 0x10000000): Buffer => {
     const flags = input[--src];
     for (let bit = 128; bit && src > prefix; bit >>= 1) {
       if (!(flags & bit)) {
-        if (dst <= prefix) throw new Error('BLZ output overflow');
+        if (dst <= prefix) throw new Error("BLZ output overflow");
         out[--dst] = input[--src];
       } else {
-        if (src - 2 < prefix) throw new Error('Truncated BLZ reference');
+        if (src - 2 < prefix) throw new Error("Truncated BLZ reference");
         const high = input[--src],
           low = input[--src];
         const count = (high >>> 4) + 3,
           offset = (((high & 15) << 8) | low) + 3;
-        if (dst - count < prefix || dst - 1 + offset >= size)
-          throw new Error('Invalid BLZ reference');
+        if (dst - count < prefix || dst - 1 + offset >= size) throw new Error("Invalid BLZ reference");
         for (let j = 0; j < count; j++) {
           --dst;
           out[dst] = out[dst + offset];
@@ -41,12 +40,12 @@ export const decompressBLZ = (input: Buffer, maxSize = 0x10000000): Buffer => {
       }
     }
   }
-  if (dst !== prefix) throw new Error('BLZ decompressed size mismatch');
+  if (dst !== prefix) throw new Error("BLZ decompressed size mismatch");
   return out;
 };
 
 export const compressBLZ = (input: Buffer): Buffer => {
-  if (input.length > 0xffffff) throw new Error('BLZ input exceeds 24-bit format limit');
+  if (input.length > 0xffffff) throw new Error("BLZ input exceeds 24-bit format limit");
   const temp = Buffer.alloc(input.length);
   let src = input.length,
     dst = input.length;
@@ -131,31 +130,24 @@ export const compressBLZ = (input: Buffer): Buffer => {
   return out;
 };
 
-export const decompressArm9 = (
-  data: Buffer,
-  header: Arm9Header,
-): { compressed: boolean; data: Buffer } => {
-  if (data.length < 0x18) throw new Error('ARM9 data too short');
+export const decompressArm9 = (data: Buffer, header: Arm9Header): { compressed: boolean; data: Buffer } => {
+  if (data.length < 0x18) throw new Error("ARM9 data too short");
   const nitro = data.readUInt32LE(0xc) === 0xdec00621 ? 12 : 0;
   const init = header.reserved2.readUInt32LE(0) & 0x3fff;
   const ptr = init ? data.readUInt32LE(init + 0x14) : header.ARM9ramAddress + header.ARM9size;
-  const compressed =
-    ptr > header.ARM9ramAddress && ptr + nitro >= header.ARM9ramAddress + data.length;
+  const compressed = ptr > header.ARM9ramAddress && ptr + nitro >= header.ARM9ramAddress + data.length;
   return {
     compressed,
     data: compressed
-      ? Buffer.concat([
-          decompressBLZ(data.subarray(0, data.length - nitro)),
-          data.subarray(data.length - nitro),
-        ])
+      ? Buffer.concat([decompressBLZ(data.subarray(0, data.length - nitro)), data.subarray(data.length - nitro)])
       : Buffer.from(data),
   };
 };
 export const compressArm9 = (data: Buffer, header: Arm9Header, postSize = 0): Buffer => {
-  if (data.length < 0x4000) throw new Error('ARM9 secure area is truncated');
+  if (data.length < 0x4000) throw new Error("ARM9 secure area is truncated");
   const nitro = data.readUInt32LE(0xc) === 0xdec00621 ? 12 : 0;
   const packed = compressBLZ(data.subarray(0x4000, data.length - nitro));
-  if (!packed.length) throw new Error('ARM9 BLZ compression produced no smaller representation');
+  if (!packed.length) throw new Error("ARM9 BLZ compression produced no smaller representation");
   const out = Buffer.concat([data.subarray(0, 0x4000), packed, data.subarray(data.length - nitro)]);
   const init = header.reserved2.readUInt32LE(0) & 0x3fff;
   if (init) out.writeUInt32LE(out.length - postSize + header.ARM9ramAddress, init + 0x14);