How AsarCreator Repackages Directories in Wand-Enhancer

AsarCreator converts a folder hierarchy into a single ASAR archive by crawling the file system, building an in-memory tree model, applying optional unpack rules, and serializing the structure to disk. This core component of the k1tbyte/Wand-Enhancer project handles the heavy lifting required to bundle Electron application resources while maintaining the flexibility to exclude specific subdirectories from packing.

The AsarCreator class follows a four-stage pipeline to transform raw directories into the ASAR format used by Electron. Understanding this flow is essential for customizing how Wand-Enhancer packages its remote panel components or any other directory structure requiring selective extraction.

Initialization and Configuration

The process begins in AsarSharp/AsarCreator.cs with the constructor capturing the source folder, destination path, and optional creation rules.

public AsarCreator(string folderPath, string destPath, CreateOptions options)

This initialization stores the _folderPath and _destPath for later use. The optional CreateOptions parameter plays a critical role in directory repackaging decisions—specifically through the Unpack property, which accepts a regular expression to identify paths that must remain unpacked in the final archive.

File System Discovery

The CreatePackageWithOptions method kicks off the repackaging workflow by invoking FileSystemCrawler.CrawlFileSystem to walk the entire directory tree. This static crawler returns two essential collections:

• _filenames – A flat list containing every path relative to the source folder
• _metadata – A dictionary mapping each path to a CrawledFileType enum value indicating whether the entry is a directory, regular file, or symbolic link

This discovery phase ensures the system captures the complete hierarchy before any structural decisions are made.

Building the In-Memory ASAR Model

Once crawling completes, CreatePackageFromFiles instantiates a new Filesystem object (new Filesystem(_folderPath)) to represent the ASAR tree structure in memory. The method then iterates through every filename and delegates processing to HandleFile.

Registering Directories

For directory entries, the handler calls filesystem.InsertDirectory(filename, false), which registers the folder in the ASAR tree without special flags. This establishes the structural backbone of the archive.

Processing Files

File handling involves several precise steps:

1. Parent path analysis – The code extracts the relative parent directory of the current file
2. Unpack decision – ShouldUnpackPath tests the parent path against the CreateOptions.Unpack regex to determine if this file's directory should remain unpacked
3. Integrity generation – IntegrityHelper.CreatePlaceholder(fileSize) generates hash placeholders for verification
4. Metadata recording – The file is added to a temporary files list (Disk.BasicFileInfo) before filesystem.InsertFile records the entry with its unpack flag and integrity data

Handling Symbolic Links

Currently, symbolic link entries trigger a throw new NotImplementedException(), indicating the Wand-Enhancer project does not support link preservation during repackaging.

Finalizing the Archive

After processing all entries, InsertsDone prepares the destination directory and invokes Disk.WriteFileSystem. This critical method receives:

• The populated Filesystem model
• The collected file list containing metadata and integrity placeholders
• The complete metadata dictionary

Disk.WriteFileSystem then serializes the in-memory structure to the destination .asar file, completing the repackaging pipeline.

Practical Implementation Examples

Basic Directory Packing

Pack a folder without any unpack rules:

var creator = new AsarCreator(
    folderPath: @"C:\Wand\remote-panel",
    destPath:   @"C:\Wand\app.asar",
    options:    null);               // No unpack rules
creator.CreatePackageWithOptions();

Selective Unpacking

Keep specific subdirectories (like native DLLs or large assets) unpacked while compressing the rest:

var opts = new AsarSharp.CreateOptions {
    // Unpack any file under a "native" sub-folder
    Unpack = new System.Text.RegularExpressions.Regex(@"^native\\", RegexOptions.IgnoreCase)
};
var creator = new AsarSharp.AsarCreator(
    @"C:\Wand\remote-panel",
    @"C:\Wand\app.asar",
    opts);
creator.CreatePackageWithOptions();

Summary

• AsarCreator serves as the primary interface for converting directories to ASAR format in the Wand-Enhancer project.
• The crawling phase uses FileSystemCrawler.CrawlFileSystem to inventory all paths and their types before processing.
• An in-memory Filesystem model stores the hierarchy via InsertDirectory and InsertFile calls.
• The unpack regex in CreateOptions applies to parent directory paths, not individual files, enabling selective exclusion of sub-trees.
• Integrity placeholders generated by IntegrityHelper ensure package verification capabilities.
• Final serialization occurs through Disk.WriteFileSystem, which writes the complete structure to disk.

Frequently Asked Questions

How does AsarCreator decide which files to unpack?

AsarCreator evaluates the CreateOptions.Unpack regular expression against the relative parent path of each file using the ShouldUnpackPath method. If the parent directory matches the pattern, the file is marked for unpacking and stored separately from the packed archive contents.

What happens to symbolic links during repackaging?

The current implementation in HandleFile throws a NotImplementedException when encountering symbolic links. The Wand-Enhancer codebase does not yet support preserving symlink relationships during the ASAR creation process.

Where is the actual ASAR file writing performed?

The physical write operation occurs in Disk.WriteFileSystem (located in AsarSharp/AsarFileSystem/Disk.cs), which receives the complete in-memory filesystem model, file metadata list, and destination path from AsarCreator.InsertsDone.

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