nitro-patcher 0.1.0 → 0.2.0

package/src/browser.ts

@@ -1,5 +1,27 @@
 import { NDSFile } from './nitro/nds-file';
-import { patchBuffer as patch } from './nitro-patch-helper';
+import {
+  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;
@@ -56,5 +78,24 @@ 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);
+
+export const PatchHelper = Object.freeze({
+  patchBuffer,
+  readPatchInfo,
+  readPatchMetadata,
+  readPatchReadme,
+});
 export const NitroHelper = Object.freeze({ inspectRom });

package/src/cli.ts

@@ -2,15 +2,22 @@
 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 { patchBuffer, readPatchInfo, type PatchMetadata } 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;
@@ -24,6 +31,39 @@ const sameFile = async (input: string, output: string): Promise<boolean> => {
   }
 };
 
+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,
@@ -31,6 +71,10 @@ const main = async (): Promise<void> => {
       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) {
@@ -51,23 +95,75 @@ const main = async (): Promise<void> => {
     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.trimEnd()}`);
+  }
+  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/nitro-patch-helper.ts

@@ -31,7 +31,117 @@ export interface PatchOptions {
   maxEntries?: number;
 }
 
+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;
+}
+
 const md5 = (data: Uint8Array): string => hashDigest('md5', data).toString('hex');
+const invalidMetadata = (message: string): null => {
+  console.warn(`忽略 metadata.json：${message}`);
+  return null;
+};
+const invalidMetadataField = (field: keyof PatchMetadata, message: string): void => {
+  console.warn(`忽略 metadata.json 的 ${field}：${message}`);
+};
+
+const readMetadata = (files: Map<string, Buffer>): PatchMetadata | null => {
+  const file = files.get('metadata.json');
+  if (!file) return null;
+
+  let metadata: unknown;
+  try {
+    metadata = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(file));
+  } catch (error) {
+    return invalidMetadata(
+      `格式错误，可能是因为补丁包已损坏：${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
+    return invalidMetadata('根节点必须是对象。');
+
+  const value = metadata as Record<string, unknown>;
+  const result: PatchMetadata = {};
+  for (const field of ['id', 'author', 'name', 'homepage', 'version'] as const) {
+    if (typeof value[field] === 'string') result[field] = value[field];
+    else invalidMetadataField(field, '必须是字符串。');
+  }
+  if (typeof value.isBeta === 'boolean') result.isBeta = value.isBeta;
+  else invalidMetadataField('isBeta', '必须是布尔值。');
+
+  return result;
+};
+
+const readReadme = (files: Map<string, Buffer>): PatchReadme | null => {
+  for (const [filename, format] of [
+    ['README.md', 'markdown'],
+    ['README.txt', 'plaintext'],
+  ] as const) {
+    const file = files.get(filename.toLowerCase());
+    if (!file) continue;
+    try {
+      return {
+        format,
+        content: new TextDecoder('utf-8', { fatal: true }).decode(file),
+      };
+    } catch (error) {
+      console.warn(
+        `忽略 ${filename}：不是有效的 UTF-8 文本：${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return null;
+};
+
+/** Read and validate metadata.json from a NitroPatcher ZIP package. */
+export const readPatchMetadata = (
+  patch: Uint8Array,
+  options: PatchOptions = {},
+): PatchMetadata | null => readMetadata(readZip(patch, options));
+
+/** Read a root README.md or README.txt from a NitroPatcher ZIP package. */
+export const readPatchReadme = (
+  patch: Uint8Array,
+  options: PatchOptions = {},
+): PatchReadme | null => readReadme(readZip(patch, options));
+
+/** Read metadata and README content while parsing the patch package only once. */
+export const readPatchInfo = (patch: Uint8Array, options: PatchOptions = {}): PatchInfo => {
+  const files = readZip(patch, options);
+  return { metadata: readMetadata(files), readme: readReadme(files) };
+};
+
+/** Read metadata.json from a NitroPatcher ZIP package on disk. */
+export const readPatchMetadataFile = async (
+  patchPath: string,
+  options: PatchOptions = {},
+): Promise<PatchMetadata | null> => readPatchMetadata(await readFile(patchPath), options);
+
+/** Read a patch README from disk. */
+export const readPatchReadmeFile = async (
+  patchPath: string,
+  options: PatchOptions = {},
+): Promise<PatchReadme | null> => readPatchReadme(await readFile(patchPath), options);
+
+/** Read patch metadata and README content from disk. */
+export const readPatchInfoFile = async (
+  patchPath: string,
+  options: PatchOptions = {},
+): Promise<PatchInfo> => readPatchInfo(await readFile(patchPath), options);
 
 /** Apply an existing NitroPatcher ZIP package entirely in memory. */
 export const patchBuffer = (
@@ -90,6 +200,15 @@ export const patchIt = async (
 };
 
 /** Namespaced counterpart of the original C# helper, sharing the same typed functions. */
-export const PatchHelper = Object.freeze({ patchBuffer, patchIt });
+export const PatchHelper = Object.freeze({
+  patchBuffer,
+  patchIt,
+  readPatchInfo,
+  readPatchInfoFile,
+  readPatchMetadata,
+  readPatchMetadataFile,
+  readPatchReadme,
+  readPatchReadmeFile,
+});
 export { decodeXdelta } from './patch/xdelta';
 export type { XdeltaOptions } from './patch/xdelta';