reverse-engineering-anything/src/cli/il2cppCommands.ts

import { localPathStringSchema } from "../domain/localPath.js";
import { absoluteCallerPath } from "../filesystem/callerPath.js";
import { z } from "incur";
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
import { err } from "../domain/result.js";
import { createIl2cppMetadataService } from "../composition/il2cpp.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { withCommandCancellation } from "./commandCancellation.js";
import {
  analysisEvidenceDeliveryOptions,
  deliverCliAnalysisEvidence,
} from "./analysisEvidenceDelivery.js";

/** CLI and MCP share inspection; one-shot summaries preserve a complete Evidence file. */
export const registerIl2cppCommands = (
  cli: CliInstance,
  logger: Logger,
): void => {
  cli.command(CLI_COMMANDS.inspectIl2cppMetadata, {
    description:
      "Inventory IL2CPP global-metadata.dat names, owners and string literals, optionally linking method addresses from the native binary",
    args: z.object({
      path: localPathStringSchema.describe(
        "Local global-metadata.dat (version 24, 27, 29, 31 or 39)",
      ),
    }),
    options: z
      .object({
        ...analysisEvidenceDeliveryOptions,
        binary: localPathStringSchema
          .optional()
          .describe(
            "Matching native binary (Mach-O GameAssembly.dylib, PE GameAssembly.dll or ELF libil2cpp.so) to link method addresses; read only",
          ),
        architecture: z
          .enum(["arm64", "amd64"])
          .optional()
          .describe("Slice of a universal Mach-O binary"),
        genericInstances: z
          .boolean()
          .optional()
          .describe(
            "Also link generic method instances (Type<Args>$$Method<Args>) and include them in --ghidra-seeds; needs --binary",
          ),
        ghidraSeeds: localPathStringSchema
          .optional()
          .describe(
            "Also write REA_GHIDRA_SEED_FILE function seeds named Type$$Method for every linked method; needs --binary",
          ),
        seedBase: z
          .string()
          .regex(/^0x[0-9a-fA-F]{1,16}$/u)
          .optional()
          .describe(
            "Address Ghidra loads the binary at; seeds are seed-base + RVA (default: Ghidra's loader default, 0x100000 for an ELF linked at 0, else the link base)",
          ),
      })
      .meta({
        dependentRequired: {
          architecture: ["binary"],
          ghidraSeeds: ["binary"],
          seedBase: ["ghidraSeeds"],
        },
        if: {
          properties: { genericInstances: { const: true } },
          required: ["genericInstances"],
        },
        then: { required: ["binary"] },
      }),
    run: ({ args, options }) =>
      withCommandCancellation((signal) =>
        logCliCommand(logger, CLI_COMMANDS.inspectIl2cppMetadata, async () => {
          const service = createIl2cppMetadataService();
          return deliverCliAnalysisEvidence({
            callerInputPath: args.path,
            ...(options.binary === undefined
              ? {}
              : { callerInputPaths: { binary_path: options.binary } }),
            run: () => {
              const input = {
                path: absoluteCallerPath(args.path),
                detail: "complete" as const,
                ...(options.binary === undefined
                  ? {}
                  : { binary_path: absoluteCallerPath(options.binary) }),
                ...(options.architecture === undefined
                  ? {}
                  : { binary_architecture: options.architecture }),
                ...(options.genericInstances === true
                  ? { generic_instances: true }
                  : {}),
              };
              if (options.ghidraSeeds !== undefined)
                return service.inspectWithGhidraSeeds(
                  input,
                  {
                    path: absoluteCallerPath(options.ghidraSeeds),
                    ...(options.seedBase === undefined
                      ? {}
                      : { base: options.seedBase }),
                  },
                  { signal },
                );
              if (options.seedBase !== undefined)
                return Promise.resolve(
                  err(
                    new AnalysisInputError(
                      "inspect_il2cpp_metadata",
                      undefined,
                      [
                        {
                          path: ["seed_base"],
                          reason: "invalid_value",
                          message: "--seed-base requires --ghidra-seeds.",
                        },
                      ],
                    ),
                  ),
                );
              return service.inspect(input, { signal });
            },
            service,
            providerId: "il2cpp-metadata",
            operation: "inspect_il2cpp_metadata",
            signal,
            detail: options.detail,
            evidenceOutput: options.evidence_output,
          });
        }),
      ),
  });
};