How to Contribute to the Wand Enhancer Project: Setup, Workflow, and Code Guidelines

To contribute to the Wand Enhancer project, fork the repository on GitHub, configure the .NET Framework and Node.js development environment, create a feature branch from master, and submit a pull request that follows the architectural constraints documented in AGENTS.md and CONTRIBUTING.md.

The Wand Enhancer is an open-source patching tool for the Wand Electron client, built as a .NET Framework WPF application with an integrated TypeScript web panel. Understanding how to contribute to the Wand Enhancer project requires familiarity with its hybrid architecture spanning C# desktop code, ASAR archive manipulation, and modern frontend tooling.

Setting Up Your Development Environment

Before modifying the codebase, you must configure the specialized toolchain that builds both the native components and the web interface.

Fork and Clone the Repository

Start by creating your own copy of the repository and cloning it locally:

git clone https://github.com/<your-username>/Wand-Enhancer.git
cd Wand-Enhancer

Install Required Build Tools

The project requires a specific stack documented in the README – Build Steps:

• CMake for native compilation
• Node.js ≥ 18 and pnpm (npm i -g pnpm)
• Visual Studio 2022 (or Build Tools) with the Desktop development with C++ workload
• .NET Framework 4.8 development pack

Build the Solution

Use the provided cross-platform script to restore dependencies and compile:

./build.cmd   # or build.sh / build.ps1 depending on your shell

This script installs web-panel dependencies, compiles the native helper with CMake, restores NuGet packages, and builds the Wand-Enhancer.sln solution.

Understanding the Three-Component Architecture

Wand Enhancer consists of three distinct layers. Isolating your changes to the correct component ensures clean pull requests that are easy to review.

Desktop Patcher (WPF Application)

The desktop patcher is the .NET Framework WPF application that extracts, patches, and repacks the app.asar file from the Wand client. Key entry points include:

• WandEnhancer/App.xaml.cs – Application entry point that launches the patch workflow
• WandEnhancer/Core/Enhancer.cs – Core logic that determines which patches to apply and coordinates the modification sequence

ASAR Handling Library (AsarSharp)

The ASAR handling library (AsarSharp) is a C# library that reads and writes ASAR archives, enabling the patcher to modify the Electron bundle without corrupting the archive structure:

• AsarSharp/AsarExtractor.cs – Handles reading and extraction of ASAR bundles
• AsarSharp/AsarCreator.cs – Manages repacking the modified archive after patching

Reference the ASAR Patch Pipeline section in AGENTS.md for invariants like avoiding hard failures when extracting unpacked entries.

Remote Web Panel (TypeScript/React)

The remote web panel provides a TypeScript bridge and React-compatible UI that runs inside the patched Electron renderer:

• web-panel/bridge/src/websocket-codec.ts – Encodes and decodes WebSocket messages between the Electron bridge and the remote panel
• web-panel/src/trainer/controls/SliderTrack.tsx – Example UI component for the trainer interface

The AGENTS.md file documents implementation details including the default port 3223, storage conventions, and bridge-to-renderer IPC protocols.

The Contribution Workflow: From Branch to Pull Request

Follow this standardized workflow to contribute to the Wand Enhancer project effectively.

Create a Feature Branch

Always branch from master with a descriptive name:

git checkout -b feature/awesome-feature

Make Isolated Changes

Keep modifications scoped to the relevant component:

• For UI work, use the Tailwind-based primitives in web-panel/src/shared/ui/
• For ASAR modifications, respect the pipeline invariants in AGENTS.md
• For patch logic, modify the core workflow in WandEnhancer/Core/Enhancer.cs

Validate with Build and Tests

Before committing, verify your changes compile correctly:

# For web-panel changes

cd web-panel
pnpm install
pnpm run build   # Validates TypeScript and bundles the bridge

node --check web-panel/dist/bridge.cjs   # Syntax check

# For C# changes

dotnet build

Submit Your Pull Request

Commit with clear, conventional messages:

git add .
git commit -m "feat: add XYZ support to remote panel"
git push origin feature/awesome-feature

Open a pull request on GitHub explaining why the change is needed, what was modified, and referencing any relevant issue numbers. Consult CONTRIBUTING.md for the exact checklist and coding style requirements.

Code Examples for Common Contributions

These practical examples demonstrate how to extend specific subsystems when you contribute to the Wand Enhancer project.

Injecting a Custom Script into the Renderer

Place a .js file in the renderer-scripts/ folder (or add via the patch dialog) to inject code into the Wand renderer:

if (!globalThis.__helloInstalled) {
  globalThis.__helloInstalled = true;
  WandEnhancer.log("Hello from my custom script!", WandEnhancer.remoteUrl);
}

When the patcher runs, this script bundles into app.asar and executes inside the Electron renderer process.

Adding a New IPC Channel to the Bridge

To extend communication between the bridge and the remote panel, modify web-panel/bridge/src/constants.ts:

export const IPC = {
  REMOTE_COMMAND: "wand-remote-command",
  NEW_FEATURE: "wand-new-feature"
};

export type IpcMessage = 
  | { type: typeof IPC.REMOTE_COMMAND; payload: any }
  | { type: typeof IPC.NEW_FEATURE; payload: any };

Reference the new channel in web-panel/bridge/src/websocket-codec.ts, then rebuild with pnpm run build:bridge to regenerate the injected bridge.cjs.

Modifying ASAR Extraction Rules

When handling edge cases in archive extraction, update AsarSharp/AsarExtractor.cs:

if (entry.IsUnpacked && entry.SourcePath.Equals(entry.DestinationPath, StringComparison.OrdinalIgnoreCase))
{
    // Skip self-copy to avoid locked-file errors (see AGENTS.md)
    continue;
}

This follows the guideline to never re-introduce hard failures when extracting unpacked entries.

Summary

• Fork and clone the repository, then install CMake, Node.js ≥18, pnpm, Visual Studio 2022, and .NET Framework 4.8 to build the project using ./build.cmd.
• Understand the three layers: the WPF desktop patcher (WandEnhancer/Core/Enhancer.cs), the ASAR library (AsarSharp/AsarExtractor.cs), and the TypeScript web panel (web-panel/bridge/src/websocket-codec.ts).
• Follow the workflow: Create feature branches, keep changes isolated, validate with pnpm run build and dotnet build, and submit PRs referencing CONTRIBUTING.md.
• Respect architectural constraints documented in AGENTS.md, particularly regarding ASAR extraction invariants and IPC message structures.

Frequently Asked Questions

Do I need a specific IDE to contribute to Wand Enhancer?

While Visual Studio 2022 is recommended for the C# components, you can use any editor that supports .NET Framework 4.8 and CMake. For the TypeScript web panel, any editor with Node.js support works, provided you can run pnpm commands from the terminal.

What are the most important files to understand before contributing?

Study WandEnhancer/Core/Enhancer.cs for the main patching logic, AsarSharp/AsarExtractor.cs for archive handling, and web-panel/bridge/src/websocket-codec.ts for the IPC communication layer. Additionally, review AGENTS.md for architectural constraints and CONTRIBUTING.md for style guidelines.

How do I test changes to the remote web panel?

After modifying files in web-panel/, run pnpm install followed by pnpm run build to validate TypeScript compilation and bundle the bridge. Use node --check web-panel/dist/bridge.cjs to verify the output syntax before testing the patcher against a Wand client installation.

Where should I place custom scripts for the patcher?

Place custom .js files in the renderer-scripts/ directory adjacent to the patcher executable, or add them via the patch dialog. These scripts automatically bundle into the ASAR archive and execute within the Electron renderer context when the patched client launches.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}