nitro-patcher 0.2.0 → 0.3.0

package/src/cli.ts

@@ -1,24 +1,36 @@
 #!/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 { render } from 'markdansi';
-import { patchBuffer, readPatchInfo, type PatchMetadata } from './nitro-patch-helper';
+import { render } from "markdansi";
+import { mkdir, mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
 
-const help = `nitro-patcher — 原生 Node.js NDS ROM 补丁工具
+import { NDSFile } from "./nitro/nds-file";
+import { type PatchMetadata, patchBuffer, readPatchInfo } from "./nitro-patch-helper";
+
+const help = `nitro-patcher — NDS ROM 补丁工具
 
 用法：
   nitro-patcher [--json] [--dry-run] <原始ROM> <补丁ZIP> [输出ROM]
-  nitro-patcher [--json] [--dry-run] --input <原始ROM> --patch <补丁ZIP> [--output <输出ROM>]
+  nitro-patcher patch [--json] [--dry-run] --input <原始ROM> --patch <补丁ZIP> [--output <输出ROM>]
+  nitro-patcher extract [--json] --input <ROM> --output <目录>
+  nitro-patcher inspect [--json] --input <ROM>
 
-  --json         输出 JSON 状态和 MD5
+  --json         结果输出为 JSON 格式
   --dry-run      完整执行补丁流程，但不写入输出 ROM
-  -i, --input    原始 ROM 路径
+  -i, --input    输入 ROM 路径
   -p, --patch    补丁 ZIP 路径
-  -o, --output   输出 ROM 路径；试运行时可省略
+  -o, --output   输出 ROM 或提取目录；试运行时可省略
   -h, --help     显示帮助
   -v, --version  显示版本`;
 
+interface CommandOptions {
+  json: boolean;
+  dryRun: boolean;
+  input: string | undefined;
+  patch: string | undefined;
+  output: string | undefined;
+}
+
 const sameFile = async (input: string, output: string): Promise<boolean> => {
   if (resolve(input) === resolve(output)) return true;
   const original = await stat(input);
@@ -26,14 +38,14 @@ 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')) {
+  for (const character of value.replaceAll("\r\n", "\n").replaceAll("\r", "\n")) {
     const code = character.codePointAt(0)!;
     if (
       (code < 0x20 && code !== 0x09 && code !== 0x0a) ||
@@ -44,37 +56,97 @@ const safeTerminalText = (value: string): string => {
       continue;
     characters.push(character);
   }
-  return characters.join('');
+  return characters.join("");
 };
 
 const formatMetadata = (metadata: PatchMetadata): string => {
   const labels = {
-    author: '作者',
-    name: '名称',
-    homepage: '主页',
-    version: '版本',
+    author: "作者",
+    name: "名称",
+    homepage: "主页",
+    version: "版本",
   } as const;
   const lines: string[] = [];
-  for (const field of ['author', 'name', 'homepage', 'version'] as const) {
+  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}`);
+    const suffix = field === "version" && metadata.isBeta ? "（测试版）" : "";
+    lines.push(`- ${labels[field]}：${safeTerminalText(value).replaceAll("\n", " ")}${suffix}`);
+  }
+  return lines.join("\n");
+};
+
+const extractRom = async (options: CommandOptions): Promise<void> => {
+  if (!options.input || !options.output || options.patch !== undefined || options.dryRun) throw new Error(help);
+  const destination = join(await realpath(dirname(resolve(options.output))), basename(resolve(options.output)));
+  const rom = new NDSFile(await readFile(options.input));
+  const files = rom.listFiles();
+  await mkdir(destination, { recursive: true });
+  for (const { path } of files) {
+    const output = resolve(destination, path);
+    if (!output.startsWith(`${destination}${sep}`)) throw new Error(`ROM 文件路径超出输出目录：${path}`);
+    await mkdir(dirname(output), { recursive: true });
+    await writeFile(output, rom.getFile(path));
+  }
+
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        output: destination,
+        fileCount: files.length,
+        files: files.map(({ path }) => path),
+      }),
+    );
+  } else {
+    console.log(`已提取 ${files.length} 个文件到：${destination}`);
   }
-  return lines.join('\n');
+};
+
+const inspectRom = async (options: CommandOptions): Promise<void> => {
+  if (!options.input || options.patch !== undefined || options.output !== undefined || options.dryRun)
+    throw new Error(help);
+  const input = await readFile(options.input);
+  const rom = new NDSFile(input);
+  const info = {
+    gameTitle: rom.header.gameTitle.replace(/\0+$/, ""),
+    gameCode: rom.header.gameCode,
+    size: input.length,
+    fileCount: rom.listFiles().length,
+    checksums: {
+      header: rom.header.headerCRC,
+      logo: rom.header.logoCRC,
+      secureArea: rom.header.secureCRC,
+      banner: rom.banner.bannerCRC,
+    },
+  };
+  if (options.json) {
+    console.log(JSON.stringify(info));
+    return;
+  }
+  console.log(`ROM 信息：
+
+标题：${safeTerminalText(info.gameTitle).replaceAll("\n", " ")}
+游戏代码：${safeTerminalText(info.gameCode).replaceAll("\n", " ")}
+大小：${info.size} 字节
+文件数量：${info.fileCount}
+校验：
+- Header：${info.checksums.header ? "通过" : "失败"}
+- Logo：${info.checksums.logo ? "通过" : "失败"}
+- Secure Area：${info.checksums.secureArea ? "通过" : "失败"}
+- Banner：${info.checksums.banner ? "通过" : "失败"}`);
 };
 
 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' },
-      'dry-run': { type: 'boolean' },
-      input: { type: 'string', short: 'i' },
-      patch: { type: 'string', short: 'p' },
-      output: { type: 'string', short: 'o' },
+      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) {
@@ -82,38 +154,43 @@ 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;
   }
-  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))))
-  )
+  const options: CommandOptions = {
+    json: values.json ?? false,
+    dryRun: values["dry-run"] ?? false,
+    input: values.input,
+    patch: values.patch,
+    output: values.output,
+  };
+  const command = positionals.length === 1 ? positionals[0] : undefined;
+  if (positionals.length !== 0 && positionals.length !== 1 && positionals.length !== 3) throw new Error(help);
+  if (command !== undefined && command !== "patch" && command !== "extract" && command !== "inspect")
+    throw new Error(help);
+  if (command === "extract") {
+    await extractRom(options);
+    return;
+  }
+  if (command === "inspect") {
+    await inspectRom(options);
+    return;
+  }
+
+  const dryRun = options.dryRun;
+  const usesLegacyPaths = positionals.length === 3;
+  if (usesLegacyPaths && (values.input !== undefined || values.patch !== undefined || values.output !== undefined))
     throw new Error(help);
-  const [original, patch, output] = usesNamedPaths
-    ? [values.input, values.patch, values.output]
-    : positionals;
+  if (!usesLegacyPaths && (!values.input || !values.patch || (!dryRun && !values.output))) throw new Error(help);
+  const [original, patch, output] = usesLegacyPaths ? positionals : [values.input, values.patch, values.output];
   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 或补丁包。');
+      throw new Error("输出路径不能覆盖原始 ROM 或补丁包。");
   }
   const [originalBytes, patchBytes] = await Promise.all([readFile(original), readFile(patch)]);
   const info = readPatchInfo(patchBytes);
@@ -121,9 +198,9 @@ const main = async (): Promise<void> => {
   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-'));
+    const temporary = await mkdtemp(join(dirname(destination), ".nitro-patcher-"));
     try {
-      const file = join(temporary, 'output.nds');
+      const file = join(temporary, "output.nds");
       await writeFile(file, result.buffer);
       await rename(file, destination);
     } finally {
@@ -131,7 +208,7 @@ const main = async (): Promise<void> => {
     }
   }
   const { returnValue, inputMd5, outputMd5 } = result;
-  if (values.json) {
+  if (options.json) {
     console.log(
       JSON.stringify({
         returnValue,
@@ -147,23 +224,23 @@ const main = async (): Promise<void> => {
   const sections: string[] = [];
   if (info.metadata) {
     const metadata = formatMetadata(info.metadata);
-    if (metadata) sections.push(`补丁元数据：\n\n${metadata}`);
+    if (metadata) sections.push(`补丁信息：\n\n${metadata}`);
   }
   if (info.readme) {
     const content = safeTerminalText(info.readme.content);
     const rendered =
-      info.readme.format === 'markdown'
+      info.readme.format === "markdown"
         ? render(content, {
             width: process.stdout.columns ?? 80,
             color: Boolean(process.stdout.isTTY),
             hyperlinks: false,
           })
         : content;
-    sections.push(`补丁说明：\n\n${rendered.trimEnd()}`);
+    sections.push(`补丁说明：\n\n${rendered.trim()}`);
   }
-  if (dryRun) sections.push('试运行完成，未写入输出 ROM。');
+  if (dryRun) sections.push("试运行完成，未写入输出 ROM。");
   sections.push(`${returnValue}\n\n原始 ROM 的 MD5：${inputMd5}\n生成 ROM 的 MD5：${outputMd5}`);
-  console.log(sections.join('\n\n'));
+  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);