streamline node package

Author: Manwe-777

.claude/settings.local.json

@@ -15,7 +15,10 @@
       "Bash(sudo cargo run:*)",
       "Bash(sudo timeout 10 cargo run:*)",
       "Bash(curl:*)",
-      "Bash(sudo node:*)"
+      "Bash(sudo node:*)",
+      "Bash(npm run build:*)",
+      "Bash(sudo npm test:*)",
+      "Bash(sudo npm run demo:*)"
     ]
   }
 }

Cargo.lock

@@ -12,12 +12,13 @@ path = "src/lib.rs"
 default = ["mono", "il2cpp"]
 mono = []
 il2cpp = []
+napi-bindings = ["napi", "napi-derive"]
 
 [dependencies]
 is_elevated = "0.1.2"
 # Default enable napi4 feature, see https://nodejs.org/api/n-api.html#node-api-version-matrix
-napi = { version = "2.12.2", default-features = false, features = ["napi4", "serde-json"] }
-napi-derive = "2.12.2"
+napi = { version = "2.12.2", default-features = false, features = ["napi4", "serde-json"], optional = true }
+napi-derive = { version = "2.12.2", optional = true }
 process-memory = "0.5.0"
 read-process-memory = "0.1.6"
 serde_json = "1.0.116"
@@ -39,6 +40,7 @@ winapi = { version = "0.3", features = ["psapi", "processthreadsapi", "handleapi
 [target.'cfg(target_os = "macos")'.dependencies]
 mach2 = "0.4"
 libproc = "0.14"
+libc = "0.2"
 
 [build-dependencies]
 napi-build = "2.0.1"

Cargo.toml

@@ -1,4 +1,6 @@
-/* Auto-generated TypeScript definitions for mtga-reader-node */
+/**
+ * mtga-reader - Node.js bindings for reading Magic: The Gathering Arena memory
+ */
 
 export interface ClassInfo {
   name: string;
@@ -33,7 +35,7 @@ export interface InstanceField {
   name: string;
   typeName: string;
   isStatic: boolean;
-  value: any;
+  value: unknown;
 }
 
 export interface InstanceData {
@@ -44,35 +46,33 @@ export interface InstanceData {
 }
 
 export interface DictionaryEntry {
-  key: any;
-  value: any;
+  key: unknown;
+  value: unknown;
 }
 
 export interface DictionaryData {
   count: number;
   entries: DictionaryEntry[];
 }
 
-// Utility functions
-
 /**
- * Check if the current process has administrator privileges
+ * Check if running with admin/root privileges
  */
 export function isAdmin(): boolean;
 
 /**
- * Find a process by name and return true if found
+ * Check if a process with the given name is running
  */
 export function findProcess(processName: string): boolean;
 
 /**
- * Initialize connection to the target process
- * Must be called before using any other reader functions
+ * Initialize the reader for a given process
+ * @throws Error if process not found or initialization fails
  */
 export function init(processName: string): boolean;
 
 /**
- * Close the connection to the target process
+ * Close the reader and release resources
  */
 export function close(): boolean;
 
@@ -81,61 +81,54 @@ export function close(): boolean;
  */
 export function isInitialized(): boolean;
 
-// Assembly functions
-
 /**
- * Get all loaded assembly names
+ * Get list of loaded assemblies
  */
 export function getAssemblies(): string[];
 
 /**
- * Get all classes in an assembly
+ * Get classes in an assembly
  */
 export function getAssemblyClasses(assemblyName: string): ClassInfo[];
 
 /**
- * Get detailed information about a class
+ * Get detailed class information including fields
  */
 export function getClassDetails(assemblyName: string, className: string): ClassDetails;
 
-// Instance reading functions
-
 /**
- * Read an instance at a given memory address
+ * Get instance data at a memory address
  */
 export function getInstance(address: number): InstanceData;
 
 /**
- * Read a specific field from an instance
+ * Get a specific field from an instance
  */
-export function getInstanceField(address: number, fieldName: string): any;
+export function getInstanceField(address: number, fieldName: string): unknown;
 
 /**
- * Read a static field from a class
+ * Get a static field from a class
  */
-export function getStaticField(classAddress: number, fieldName: string): any;
-
-// Dictionary reading
+export function getStaticField(classAddress: number, fieldName: string): unknown;
 
 /**
- * Read a dictionary at a given memory address
+ * Read a dictionary at a memory address
  */
 export function getDictionary(address: number): DictionaryData;
 
-// High-level data reading
-
 /**
- * Read nested data by traversing a path of field names
- * The first element is the root class name, subsequent elements are field names
+ * Legacy API: Read data by following a path of field names
+ * Windows: WrapperController path (WrapperController.Instance.InventoryManager...)
+ * macOS: PAPA path (PAPA._InventoryManager.GetPlayerCardsNoLock...)
  */
-export function readData(processName: string, fields: string[]): any;
+export function readData(processName: string, fields: string[]): unknown;
 
 /**
- * Read a managed class at a given address
+ * Legacy API: Read class at address
  */
-export function readClass(processName: string, address: number): any;
+export function readClass(processName: string, address: number): unknown;
 
 /**
- * Read a generic instance at a given address
+ * Legacy API: Read generic instance at address
  */
-export function readGenericInstance(processName: string, address: number): any;
+export function readGenericInstance(processName: string, address: number): unknown;

node-test/index.d.ts mtga-reader-js/index.d.tsnode-test/index.d.ts renamed to mtga-reader-js/index.d.ts

@@ -0,0 +1,214 @@
+/**
+ * mtga-reader - Node.js bindings for reading Magic: The Gathering Arena memory
+ *
+ * Cross-platform support:
+ * - Windows: Uses Mono backend
+ * - macOS: Uses IL2CPP backend
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// Try to load the native addon
+let nativeBinding = null;
+
+// Possible locations for the .node file
+const possiblePaths = [
+  // Same directory as index.js
+  path.join(__dirname, 'mtga_reader.node'),
+  // Platform-specific naming
+  path.join(__dirname, `mtga_reader.${process.platform}-${process.arch}.node`),
+  // Build output from cargo (release)
+  path.join(__dirname, '..', 'target', 'release', 'libmtga_reader.dylib'),
+  path.join(__dirname, '..', 'target', 'release', 'mtga_reader.dll'),
+];
+
+for (const bindingPath of possiblePaths) {
+  if (fs.existsSync(bindingPath)) {
+    try {
+      nativeBinding = require(bindingPath);
+      break;
+    } catch (e) {
+      // Try next path
+    }
+  }
+}
+
+if (!nativeBinding) {
+  throw new Error(
+    `Failed to load native binding. Tried:\n${possiblePaths.join('\n')}\n\n` +
+    'Please ensure the native addon is built. Run: npm run build'
+  );
+}
+
+// Export all functions from the native binding
+module.exports = {
+  /**
+   * Check if running with admin/root privileges
+   * @returns {boolean}
+   */
+  isAdmin: nativeBinding.isAdmin,
+
+  /**
+   * Check if a process with the given name is running
+   * @param {string} processName - Name of the process to find
+   * @returns {boolean}
+   */
+  findProcess: nativeBinding.findProcess,
+
+  /**
+   * Initialize the reader for a given process
+   * @param {string} processName - Name of the process (e.g., "MTGA")
+   * @returns {boolean} - True if initialization succeeded
+   * @throws {Error} - If process not found or initialization fails
+   */
+  init: nativeBinding.init,
+
+  /**
+   * Close the reader and release resources
+   * @returns {boolean}
+   */
+  close: nativeBinding.close,
+
+  /**
+   * Check if the reader is initialized
+   * @returns {boolean}
+   */
+  isInitialized: nativeBinding.isInitialized,
+
+  /**
+   * Get list of loaded assemblies
+   * @returns {string[]}
+   */
+  getAssemblies: nativeBinding.getAssemblies,
+
+  /**
+   * Get classes in an assembly
+   * @param {string} assemblyName - Name of the assembly
+   * @returns {ClassInfo[]}
+   */
+  getAssemblyClasses: nativeBinding.getAssemblyClasses,
+
+  /**
+   * Get detailed class information including fields
+   * @param {string} assemblyName - Name of the assembly
+   * @param {string} className - Name of the class
+   * @returns {ClassDetails}
+   */
+  getClassDetails: nativeBinding.getClassDetails,
+
+  /**
+   * Get instance data at a memory address
+   * @param {number} address - Memory address of the instance
+   * @returns {InstanceData}
+   */
+  getInstance: nativeBinding.getInstance,
+
+  /**
+   * Get a specific field from an instance
+   * @param {number} address - Memory address of the instance
+   * @param {string} fieldName - Name of the field
+   * @returns {any} - Field value
+   */
+  getInstanceField: nativeBinding.getInstanceField,
+
+  /**
+   * Get a static field from a class
+   * @param {number} classAddress - Memory address of the class
+   * @param {string} fieldName - Name of the static field
+   * @returns {any} - Field value
+   */
+  getStaticField: nativeBinding.getStaticField,
+
+  /**
+   * Read a dictionary at a memory address
+   * @param {number} address - Memory address of the dictionary
+   * @returns {DictionaryData}
+   */
+  getDictionary: nativeBinding.getDictionary,
+
+  /**
+   * Legacy API: Read data by following a path of field names
+   * @param {string} processName - Process name
+   * @param {string[]} fields - Array of field names to traverse
+   * @returns {any} - The value at the end of the path
+   */
+  readData: nativeBinding.readData,
+
+  /**
+   * Legacy API: Read class at address
+   * @param {string} processName - Process name
+   * @param {number} address - Memory address
+   * @returns {any}
+   */
+  readClass: nativeBinding.readClass,
+
+  /**
+   * Legacy API: Read generic instance at address
+   * @param {string} processName - Process name
+   * @param {number} address - Memory address
+   * @returns {any}
+   */
+  readGenericInstance: nativeBinding.readGenericInstance,
+};
+
+/**
+ * @typedef {Object} ClassInfo
+ * @property {string} name - Class name
+ * @property {string} namespace - Class namespace
+ * @property {number} address - Memory address
+ * @property {boolean} isStatic - Is static class
+ * @property {boolean} isEnum - Is enum type
+ */
+
+/**
+ * @typedef {Object} FieldInfo
+ * @property {string} name - Field name
+ * @property {string} typeName - Field type name
+ * @property {number} offset - Field offset
+ * @property {boolean} isStatic - Is static field
+ * @property {boolean} isConst - Is const field
+ */
+
+/**
+ * @typedef {Object} StaticInstanceInfo
+ * @property {string} fieldName - Static field name
+ * @property {number} address - Instance address
+ */
+
+/**
+ * @typedef {Object} ClassDetails
+ * @property {string} name - Class name
+ * @property {string} namespace - Class namespace
+ * @property {number} address - Class address
+ * @property {FieldInfo[]} fields - Class fields
+ * @property {StaticInstanceInfo[]} staticInstances - Static instances
+ */
+
+/**
+ * @typedef {Object} InstanceField
+ * @property {string} name - Field name
+ * @property {string} typeName - Field type
+ * @property {boolean} isStatic - Is static
+ * @property {any} value - Field value
+ */
+
+/**
+ * @typedef {Object} InstanceData
+ * @property {string} className - Class name
+ * @property {string} namespace - Namespace
+ * @property {number} address - Instance address
+ * @property {InstanceField[]} fields - Instance fields
+ */
+
+/**
+ * @typedef {Object} DictionaryEntry
+ * @property {any} key - Entry key
+ * @property {any} value - Entry value
+ */
+
+/**
+ * @typedef {Object} DictionaryData
+ * @property {number} count - Number of entries
+ * @property {DictionaryEntry[]} entries - Dictionary entries
+ */