PatchEntry SearchHints and CandidateFileNames in Wand-Enhancer: Purpose and Implementation

PatchEntry's SearchHints and CandidateFileNames properties provide a two-step verification system that ensures JavaScript patches are applied only to correct file paths and specific code versions, preventing application corruption when Wand updates alter its bundle structure.

The Wand-Enhancer project implements a robust patching mechanism for modifying Wand's JavaScript bundles packaged within ASAR archives. At the core of this configuration-driven system lies the PatchEntry class defined in WandEnhancer/Core/EnhancerConfig.cs, which leverages SearchHints and CandidateFileNames to accurately locate target code while maintaining version safety across different Wand releases.

Two-Step Verification: File Targeting and Version Safety

The patching engine employs a defensive strategy that verifies both file location and content integrity before applying any modifications. This dual-check mechanism prevents the injector from corrupting unsupported Wand versions when the target code has changed between updates.

CandidateFileNames Property

CandidateFileNames is a string array containing file-path patterns relative to the ASAR root where the patch might validly reside. This property narrows the search space by filtering the extracted ASAR contents to only relevant bundles, such as renderer.js or services/account.js, rather than scanning every file in the archive.

SearchHints Property

SearchHints is a string array containing unique identifiers—such as function names, endpoint URLs, or specific comments—that must exist within the target file's source code. Before a patch is applied, the engine validates that the file content contains at least one of these hints, confirming the file matches the expected version and structure the patch was designed to modify.

Implementation in the Wand-Enhancer Source Code

According to the source code in the k1tbyte/Wand-Enhancer repository, the verification logic is implemented in WandEnhancer/Core/Enhancer.cs through the CanSearchPatchInFile and ContainsSearchHint methods. The PatchEntry class itself is defined in WandEnhancer/Core/EnhancerConfig.cs alongside a static dictionary mapping EPatchType values to their respective patch configurations.

The patching workflow follows this sequence:

1. The engine extracts the ASAR archive and iterates through the extracted files.
2. For each PatchEntry, CanSearchPatchInFile checks if the current file path ends with any of the CandidateFileNames entries.
3. If the filename matches, ContainsSearchHint scans the file content for any string in the SearchHints array.
4. Only when both conditions pass does the engine invoke ApplyJsPatch to inject the JavaScript modification.

// Example PatchEntry configuration from EnhancerConfig.cs
new PatchEntry {
    Patch = "// JavaScript code to inject...",
    SearchHints = new[] {
        "getUserAccount()", 
        "/v3/account"
    },
    CandidateFileNames = new[] { 
        "renderer.js", 
        "services/account.js" 
    }
};

// Core verification logic concept from Enhancer.cs
bool CanApplyPatch(string filePath, string fileContent, PatchEntry entry) =>
    entry.CandidateFileNames.Any(name => filePath.EndsWith(name)) &&
    entry.SearchHints.Any(hint => fileContent.Contains(hint));

Summary

• CandidateFileNames filters the ASAR extraction to specific file paths, ensuring the patch engine only inspects relevant JavaScript bundles like renderer.js or service files.
• SearchHints provides content-based verification by checking for unique code signatures, protecting against version mismatches that could corrupt the application.
• Both properties must validate successfully before ApplyJsPatch executes, creating a fail-safe mechanism that skips incompatible patches silently rather than causing runtime errors.
• The configuration resides in WandEnhancer/Core/EnhancerConfig.cs while the execution logic lives in WandEnhancer/Core/Enhancer.cs, with UI selection handled in WandEnhancer/View/Popups/PatchVectorsPopup.xaml.cs and settings managed through WandEnhancer/Models/PatchConfig.cs.

Frequently Asked Questions

What happens if SearchHints are not found in a matching candidate file?

If the file path matches a CandidateFileNames entry but ContainsSearchHint fails to locate any hints in the content, the patch engine skips that file and reports that the patch could not be applied. This typically indicates the user's Wand build is newer or older than the patch supports, preventing accidental code corruption.

Can CandidateFileNames use wildcards or regular expressions?

Based on the source implementation in Enhancer.cs, the matching uses simple string suffix checks (typically filePath.EndsWith(name)). While the examples show specific filenames like renderer.js, the array structure supports multiple entries to cover different possible paths without requiring regex patterns.

How does this system prevent corruption when Wand updates?

The two-step verification requires both filename and content confirmation. When Wand updates change line numbers or rename functions, the SearchHints check fails because the expected strings no longer exist in the source. This causes the patcher to skip the modification rather than injecting code into the wrong location, ensuring the application remains functional even when patches become outdated.

Where are patch definitions configured in the codebase?

Static patch definitions are stored in WandEnhancer/Core/EnhancerConfig.cs as a dictionary mapping EPatchType enums to PatchEntry instances. At runtime, the UI in PatchVectorsPopup.xaml.cs presents these options to the user, and the selected types are passed via PatchConfig.cs to the Enhancer class which orchestrates the patching process.

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