Plugins: warn-and-skip on incompatible BitMono.API + NuGet docs (#227)

Follow-ups to the plugin system from review feedback:

- Detect when a plugin was built against a newer BitMono.API than this build
  provides (compare the referenced contract's Major.Minor to the host's) and
  skip it with a clear warning, instead of letting it fail later with a cryptic
  MissingMethodException mid-obfuscation. Reading a plugin's references is
  wrapped so a malformed assembly never aborts the run. A locally-built BitMono
  (version 0.0.x) can't be compared, so the check is skipped there.
- Log each plugin's version when it loads ("Loaded plugin: MyPlugin v1.2.0.0").
- Docs: reference BitMono from NuGet with ExcludeAssets="runtime" instead of raw
  DLL HintPaths (a clean build then leaves just your plugin DLL), document the
  --plugins CLI override, and add a versioning/compatibility section - no custom
  attribute, the plugin's assembly version is its version.

There's deliberately no [ProtectionVersion]/[RequiresApiVersion] attribute:
ConfuserEx has nothing like it, and the assembly version already carries this.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sunnamed434

docs/source/developers/plugins.rst

@@ -1,44 +1,50 @@
 Plugins
 =======
 
-BitMono can load **plugins** - external assemblies that contribute your own protections - without
-rebuilding BitMono. Drop a plugin DLL into the plugins directory and BitMono discovers and runs the
-protections inside it, exactly like the built-in ones. (`#227 <https://github.com/sunnamed434/BitMono/issues/227>`_)
+BitMono can load **plugins**, external assemblies that add your own protections, without rebuilding
+BitMono. Drop a plugin DLL into the plugins directory and BitMono finds the protections inside it and
+runs them exactly like the built-in ones. (`#227 <https://github.com/sunnamed434/BitMono/issues/227>`_)
 
 .. warning::
 
-    Plugins are loaded into the BitMono process with full trust - .NET cannot sandbox them. Only drop
-    in plugins from sources you trust, just as you would with any other executable.
+    Plugins run inside the BitMono process with full trust, .NET can't sandbox them. Only drop in
+    plugins from sources you trust, same as you would with any other executable.
 
 
 Where plugins live
 ------------------
 
-By default BitMono scans a ``plugins`` directory next to the BitMono executable. You can change the
-directory name (or point it at an absolute path) with ``PluginsDirectoryName`` in ``obfuscation.json``:
+By default BitMono scans a ``plugins`` directory next to the BitMono executable. You can rename it (or
+point it at an absolute path) with ``PluginsDirectoryName`` in ``obfuscation.json``:
 
 .. code-block:: json
 
     {
       "PluginsDirectoryName": "plugins"
     }
 
-Two layouts are supported:
+or override it for a single run from the CLI with ``--plugins``:
 
-- **Flat** - drop the DLL straight into the directory: ``plugins/MyProtections.dll``.
-- **Per-plugin folder** - give each plugin its own folder: ``plugins/MyProtections/MyProtections.dll``.
-  Put any extra dependencies in a nested folder (for example ``plugins/MyProtections/libs/``); they are
-  resolved on demand and are not themselves treated as plugins.
+.. code-block:: bash
+
+    BitMono.CLI -f MyApp.dll --plugins "C:\path\to\my-plugins" -p HelloPlugin
+
+Two layouts work:
 
-If the directory does not exist, BitMono simply skips plugin loading.
+- **Flat**, drop the DLL straight in: ``plugins/MyProtections.dll``.
+- **Per-plugin folder**, give each plugin its own folder: ``plugins/MyProtections/MyProtections.dll``.
+  Put any extra dependencies in a nested folder (say ``plugins/MyProtections/libs/``), they're resolved
+  on demand and aren't treated as plugins themselves.
+
+If the directory doesn't exist, BitMono just skips plugin loading.
 
 
 Writing a plugin
 ----------------
 
 A plugin is an ordinary class library that references ``BitMono.API`` (and usually ``BitMono.Core`` for
-the ``Protection`` base class) and exposes one or more public protections. Writing a protection is the
-same as :doc:`creating a built-in one <first-protection>`:
+the ``Protection`` base class) and exposes one or more public protections. Writing the protection itself
+is the same as writing a :doc:`built-in one <first-protection>`:
 
 .. code-block:: csharp
 
@@ -66,46 +72,58 @@ same as :doc:`creating a built-in one <first-protection>`:
 
 .. note::
 
-    The container builds your protection by calling its **first** constructor and resolving each
-    parameter. Take ``IBitMonoServiceProvider`` (as above) to reach BitMono's services. If a parameter
-    cannot be resolved the protection is skipped and the error is logged - it never aborts the run.
+    The container builds your protection through its **first** constructor, resolving each parameter.
+    Take ``IBitMonoServiceProvider`` (like above) to reach BitMono's services. If a parameter can't be
+    resolved the protection is skipped and the error is logged, it never aborts the run.
 
 
 .. _plugins-reference-the-host:
 
 Reference BitMono, don't ship it
 --------------------------------
 
-Reference the BitMono assemblies with ``Private="false"`` so they are **not** copied next to your
-plugin. Your plugin must bind to the *same* ``BitMono.API`` the host is running; if you ship your own
-copy, your protection implements a *different* ``IProtection`` type and BitMono will ignore it (and warn
-you in the log).
+Reference BitMono from NuGet and mark it ``ExcludeAssets="runtime"`` so its assemblies are **not** copied
+into your build output (BitMono itself provides them at runtime). Your plugin has to bind to the *same*
+``BitMono.API`` the host is running. Ship your own copy and your protection implements a *different*
+``IProtection`` type, so BitMono ignores it (and warns you in the log).
+
+``BitMono.Core`` pulls in ``BitMono.API``, ``BitMono.Shared`` and ``AsmResolver`` for you, and
+``ExcludeAssets="runtime"`` keeps the whole graph out of your output, so a successful build leaves just
+your own plugin DLL behind.
 
 .. code-block:: xml
 
     <ItemGroup>
-      <Reference Include="BitMono.API">
-        <HintPath>path\to\BitMono.API.dll</HintPath>
-        <Private>false</Private>
-      </Reference>
-      <Reference Include="BitMono.Core">
-        <HintPath>path\to\BitMono.Core.dll</HintPath>
-        <Private>false</Private>
-      </Reference>
-      <Reference Include="BitMono.Shared">
-        <HintPath>path\to\BitMono.Shared.dll</HintPath>
-        <Private>false</Private>
-      </Reference>
+      <!-- Use the version that matches the BitMono you run the plugin against. -->
+      <PackageReference Include="BitMono.Core" Version="0.40.1">
+        <ExcludeAssets>runtime</ExcludeAssets>
+      </PackageReference>
     </ItemGroup>
 
 
+Versioning and compatibility
+----------------------------
+
+There's no special "plugin version" attribute - your plugin's own assembly version is its version, and
+BitMono prints it when it loads it (``Loaded plugin: MyPlugin v1.2.0.0``).
+
+What actually matters is the ``BitMono.API`` version you build against (``BitMono.Core`` pulls it in). It's
+the contract, and it follows `semver <https://semver.org>`_: a new minor only adds things, a new major can
+break ``IProtection``/``Protection``. If a plugin is built against a *newer* ``BitMono.API`` than the
+BitMono you drop it into, it'd probably call something that isn't there - so BitMono skips it and logs a
+warning telling you to rebuild against the version you're running. Same or older builds load fine.
+
+So pin ``BitMono.Core`` to the version you ship against and bump it when you move to a newer BitMono.
+
+
 External dependencies
 ---------------------
 
-If your plugin uses external libraries (NuGet packages, your own helpers), ship those DLLs alongside the
-plugin - either next to it or in a nested folder such as ``libs``. BitMono installs an
-``AppDomain.AssemblyResolve`` handler that probes the plugin directories and loads dependencies on
-demand, so they don't have to sit in BitMono's own folder.
+If your plugin uses external libraries (other NuGet packages, your own helpers), reference them
+**normally** (without ``ExcludeAssets`` - that switch is only for BitMono itself) so they're copied next
+to your plugin, then ship those DLLs next to the plugin or in a nested folder like ``libs``. BitMono
+installs an ``AppDomain.AssemblyResolve`` handler that probes the plugin directories and loads
+dependencies on demand, so they don't have to sit in BitMono's own folder.
 
 A typical per-plugin layout::
 
@@ -119,7 +137,7 @@ A typical per-plugin layout::
 Enabling a plugin protection
 ----------------------------
 
-Plugin protections are configured exactly like the built-in ones - by name (the class name, or the
+Plugin protections are configured exactly like the built-in ones, by name (the class name, or the
 ``[ProtectionName("...")]`` value). Add them to ``protections.json``:
 
 .. code-block:: json
@@ -139,5 +157,5 @@ or pass them on the command line:
 
     BitMono.CLI -f MyApp.dll -p HelloPlugin
 
-Execution order follows the configuration order, the same as built-in protections. See
+Execution order follows the configuration order, same as built-in protections. See
 :doc:`obfuscation-execution-order` for details.

src/BitMono.Host/Extensions/ContainerExtensions.cs

@@ -22,6 +22,9 @@ public static class BitMonoContainerExtensions
     private const string ProtectionsFileName = "BitMono.Protections.dll";
     private const string UnityFileName = "BitMono.Unity.dll";
     private const string DefaultPluginsDirectoryName = "plugins";
+    // The plugin SDK contract: any real protection implements IProtection, which lives here, so the
+    // compiler always emits this reference into a plugin's IL - making it a reliable compatibility anchor.
+    private const string ContractAssemblyName = "BitMono.API";
 
     /// <summary>
     /// Loads and registers protection assemblies, including any drop-in plugins (see #227).
@@ -43,11 +46,12 @@ public static Container AddProtections(this Container container, string? file =
         }
 
         var logger = container.GetService(typeof(ILogger)) as ILogger;
+        var scanLogger = logger?.ForContext(typeof(BitMonoContainerExtensions));
 
         // Load drop-in plugins before scanning so their protections are discovered alongside the built-ins.
-        LoadPlugins(container, logger);
+        var pluginAssemblies = LoadPlugins(container, logger);
+        var incompatiblePlugins = GetIncompatiblePlugins(pluginAssemblies, scanLogger);
 
-        var scanLogger = logger?.ForContext(typeof(BitMonoContainerExtensions));
         var assemblies = AppDomain.CurrentDomain.GetAssemblies();
 
         // Collect all protection types (excluding IPhaseProtection)
@@ -73,6 +77,10 @@ public static Container AddProtections(this Container container, string? file =
                 if (!type.IsClass || type.IsAbstract || !type.IsPublic || type.IsGenericTypeDefinition)
                     continue;
 
+                // Skip protections from a plugin built against a newer BitMono.API (already warned, #227).
+                if (incompatiblePlugins.Contains(type.Assembly))
+                    continue;
+
                 // IPhaseProtection extends IProtection, so it MUST be checked first - phase protections
                 // are driven by their pipeline, not registered as standalone protections.
                 if (typeof(IPhaseProtection).IsAssignableFrom(type))
@@ -124,11 +132,11 @@ public static Container AddProtections(this Container container, string? file =
         return container;
     }
 
-    private static void LoadPlugins(Container container, ILogger? logger)
+    private static IReadOnlyList<Assembly> LoadPlugins(Container container, ILogger? logger)
     {
         // No logger means the host wasn't fully set up; plugin loading relies on logging for diagnostics.
         if (logger == null)
-            return;
+            return [];
 
         var obfuscationSettings = container.GetService(typeof(ObfuscationSettings)) as ObfuscationSettings;
         var directoryName = obfuscationSettings?.PluginsDirectoryName;
@@ -139,6 +147,41 @@ private static void LoadPlugins(Container container, ILogger? logger)
             ? directoryName!
             : Path.Combine(AppContext.BaseDirectory, directoryName!);
 
-        new PluginLoader(pluginsDirectory, logger).LoadPlugins();
+        return new PluginLoader(pluginsDirectory, logger).LoadPlugins();
+    }
+
+    // Plugins built against a newer BitMono.API than this build provides are skipped with a clear warning,
+    // instead of failing later with a cryptic MissingMethodException mid-obfuscation (#227).
+    private static HashSet<Assembly> GetIncompatiblePlugins(IReadOnlyList<Assembly> plugins, ILogger? logger)
+    {
+        var incompatible = new HashSet<Assembly>();
+        var hostVersion = typeof(IProtection).Assembly.GetName().Version;
+        foreach (var plugin in plugins)
+        {
+            Version? contractVersion;
+            try
+            {
+                contractVersion = plugin.GetReferencedAssemblies()
+                    .FirstOrDefault(x => string.Equals(x.Name, ContractAssemblyName, StringComparison.OrdinalIgnoreCase))
+                    ?.Version;
+            }
+            catch (Exception ex)
+            {
+                // Can't read the plugin's metadata - don't let it abort the run; treat as compatible.
+                logger?.Warning("Could not read references of plugin '{0}': {1}",
+                    plugin.GetName().Name ?? "?", ex.Message);
+                continue;
+            }
+            if (!PluginCompatibility.IsBuiltAgainstNewerContract(hostVersion, contractVersion))
+                continue;
+
+            incompatible.Add(plugin);
+            logger?.Warning(
+                "Plugin '{0}' was built against {1} {2}, newer than this build's {3}; its protections are skipped. " +
+                "Update BitMono or rebuild the plugin against {3}.",
+                plugin.GetName().Name ?? "?", ContractAssemblyName,
+                contractVersion!.ToString(2), hostVersion!.ToString(2));
+        }
+        return incompatible;
     }
 }

src/BitMono.Shared/Plugins/PluginCompatibility.cs

@@ -0,0 +1,33 @@
+namespace BitMono.Shared.Plugins;
+
+/// <summary>
+/// Decides whether a plugin built against a given BitMono.API version is compatible with the host.
+/// BitMono uses standard assembly versioning instead of a custom plugin-version attribute, so this just
+/// compares the contract assembly versions. See #227.
+/// </summary>
+public static class PluginCompatibility
+{
+    /// <summary>
+    /// Returns <c>true</c> when the plugin was built against a NEWER contract (compared on Major.Minor)
+    /// than the host provides - it likely uses API this BitMono build doesn't have, so it should be
+    /// skipped with a clear warning rather than failing cryptically later. Older or equal contracts are
+    /// considered compatible (best effort). A locally-built BitMono reports version 0.0.x, which can't be
+    /// compared meaningfully, so the check is skipped (returns <c>false</c>) in that case.
+    /// </summary>
+    public static bool IsBuiltAgainstNewerContract(System.Version? hostVersion, System.Version? pluginContractVersion)
+    {
+        if (hostVersion == null || pluginContractVersion == null)
+        {
+            return false;
+        }
+        if (hostVersion.Major == 0 && hostVersion.Minor == 0)
+        {
+            return false;
+        }
+        if (pluginContractVersion.Major != hostVersion.Major)
+        {
+            return pluginContractVersion.Major > hostVersion.Major;
+        }
+        return pluginContractVersion.Minor > hostVersion.Minor;
+    }
+}

src/BitMono.Shared/Plugins/PluginLoader.cs

@@ -62,7 +62,7 @@ public IReadOnlyList<Assembly> LoadPlugins()
                 // dependencies probe correctly and the AssemblyResolve fallback has somewhere to look.
                 var assembly = Assembly.LoadFrom(file);
                 loaded.Add(assembly);
-                _logger.Information("Loaded plugin: {0}", assembly.GetName().Name);
+                _logger.Information("Loaded plugin: {0} v{1}", assembly.GetName().Name, assembly.GetName().Version);
             }
             catch (BadImageFormatException)
             {

test/BitMono.Shared.Tests/Plugins/PluginCompatibilityTests.cs

@@ -0,0 +1,34 @@
+using BitMono.Shared.Plugins;
+
+namespace BitMono.Shared.Tests.Plugins;
+
+public class PluginCompatibilityTests
+{
+    [Theory]
+    // Plugin built against a newer minor than the host -> incompatible.
+    [InlineData("0.40.0.0", "0.41.0.0", true)]
+    [InlineData("0.40.5.0", "0.41.0.0", true)]
+    [InlineData("1.0.0.0", "2.0.0.0", true)]
+    // Equal or older contract -> compatible (best effort).
+    [InlineData("0.40.0.0", "0.40.0.0", false)]
+    [InlineData("0.40.0.0", "0.40.9.0", false)] // same Major.Minor, patch differences ignored
+    [InlineData("0.41.0.0", "0.40.0.0", false)]
+    [InlineData("2.0.0.0", "1.5.0.0", false)]
+    // Locally-built host (0.0.x) can't be compared -> never flagged.
+    [InlineData("0.0.0.0", "0.41.0.0", false)]
+    // An unversioned/locally-built plugin (0.0.x) against a real host is never "newer".
+    [InlineData("0.40.0.0", "0.0.0.0", false)]
+    public void IsBuiltAgainstNewerContract_ComparesMajorMinor(string host, string plugin, bool expected)
+    {
+        var result = PluginCompatibility.IsBuiltAgainstNewerContract(new Version(host), new Version(plugin));
+
+        result.Should().Be(expected);
+    }
+
+    [Fact]
+    public void IsBuiltAgainstNewerContract_ReturnsFalse_WhenEitherVersionMissing()
+    {
+        PluginCompatibility.IsBuiltAgainstNewerContract(null, new Version(9, 9)).Should().BeFalse();
+        PluginCompatibility.IsBuiltAgainstNewerContract(new Version(0, 40), null).Should().BeFalse();
+    }
+}