feat(runtime): gate legacy embedded fallbacks

Author: ImperaZim

CHANGELOG.md

@@ -59,6 +59,14 @@ elprobe run <package>
   do not break before packages, fallback commands and migration docs are ready.
 - Defined the 3.x target model: EasyLibrary core plus official installable
   packages under `plugin_data/EasyLibrary/packages/`.
+- Added `legacy-embedded.enabled=false` as the package-first default gate for
+  old bundled runtime fallbacks. EasyLibrary no longer auto-starts embedded
+  LibCommand, LibPlaceholder, LibTrigger, LibWorld or LibHud fallback pieces
+  unless the operator explicitly enables that legacy escape hatch.
+- Changed command backend selection so embedded LibCommand classes on disk do
+  not automatically unlock the rich command tree. Package-backed or standalone
+  LibCommand still provides the rich backend; otherwise EasyLibrary uses the
+  native recovery command.
 
 ### Package manager
 

README.md

@@ -177,6 +177,20 @@ AgentFlagsAPI::set(AgentNetworkFlags::DOUBLE_XP, true, 3600, 'Weekend booster');
 
 EasyLibrary 3.x is moving away from shipping every lib as always-on embedded code. These namespaces still exist during the migration window so existing servers do not break immediately, but the target is to move them into official internal packages and remove the legacy embedded copy only after install + restart is proven safe.
 
+In the package-first 3.0-dev model, legacy embedded fallback is disabled by
+default:
+
+```yaml
+legacy-embedded:
+  enabled: false
+```
+
+With this setting, EasyLibrary does not automatically start bundled
+LibCommand, LibPlaceholder, LibTrigger, LibWorld or LibHud fallback runtime
+pieces. Install the official EasyLibrary package or standalone plugin instead.
+Only enable `legacy-embedded.enabled=true` as a temporary compatibility escape
+hatch while migrating an older 2.x-style server.
+
 | Library | Namespace | Main purpose |
 |---|---|---|
 | [LibPlaceholder](https://github.com/ImperaZim/LibPlaceholder) | `imperazim\placeholder` | Placeholder parsing and expansion registry |
@@ -209,7 +223,9 @@ Standalone installed:
   an installed internal package reports installed-shadowed-by-standalone instead of active
 
 Legacy embedded fallback:
-  kept during early 3.0-dev so existing servers keep working
+  source kept during 3.0-dev migration
+  disabled by default through legacy-embedded.enabled=false
+  can be enabled temporarily for older 2.x-style servers
   removed only after the internal package replacement is tested
 ```
 
@@ -403,6 +419,12 @@ or reloads managers that EasyLibrary itself owns in the current server session.
 After a restart, normal `plugin.yml`, config and standalone plugin priority
 rules still apply.
 
+The legacy embedded runtime targets are gated by
+`legacy-embedded.enabled=true`. With the default package-first config, use
+package-backed or standalone libs instead. The fallback native
+`/easylibrary` recovery command still remains available when LibCommand is not
+loaded.
+
 The standalone installer remains available for compatibility. The preferred 3.x path is `/easylibrary packages install`, but `/easylibrary libs install` can still download official standalone PHARs after `confirm`, checksum validation and `library-installer.enabled=true`. It still does not hot-load the PHAR; restart is required.
 
 ```txt

changelogs/3.0.md

@@ -84,6 +84,48 @@ does not mean embedded full-bundle behavior is the final target. It exists so
 servers can migrate gradually while the package manager, fallback command and
 Wiki/migration docs mature.
 
+### Legacy embedded fallback is now gated
+
+The package-first 3.0-dev default now disables automatic embedded fallback
+runtime startup:
+
+```yaml
+legacy-embedded:
+  enabled: false
+```
+
+This changed the migration behavior intentionally:
+
+- EasyLibrary no longer auto-starts bundled LibCommand, LibPlaceholder,
+  LibTrigger, LibWorld or LibHud fallback runtime pieces just because their
+  source directories still exist inside the EasyLibrary tree.
+- Package-backed or standalone LibCommand still unlocks the rich command tree.
+- If no LibCommand provider is active and the only available classes are the
+  EasyLibrary embedded copy, EasyLibrary registers the native recovery command
+  instead of silently using the legacy rich command backend.
+- `/easylibrary doctor` and library status now report the legacy embedded
+  fallback as disabled by config instead of implying that it is the preferred
+  active provider.
+
+Why this exists:
+
+- The 3.x target is package-backed/standalone ownership, not hidden embedded
+  ownership.
+- Operators should see a missing package/provider and install the official
+  package instead of accidentally relying on old bundled source.
+- The embedded source can still stay in the repository while the migration
+  audit continues, but it no longer defines the normal boot model.
+
+Temporary escape hatch:
+
+```yaml
+legacy-embedded:
+  enabled: true
+```
+
+Use that only while migrating an older 2.x-style server that still depends on
+the full-bundle behavior. It should not be the default for new 3.x setups.
+
 ### Public API compatibility so far
 
 The 3.0-dev work described here is an architectural and operational migration,

docs/standalone-vs-embedded.md

@@ -34,6 +34,18 @@ break immediately. It is not the long-term target. The target is:
 EasyLibrary core + official internal packages
 ```
 
+The current 3.0-dev package-first default keeps that fallback disabled:
+
+```yaml
+legacy-embedded:
+  enabled: false
+```
+
+When disabled, EasyLibrary does not auto-start bundled LibCommand,
+LibPlaceholder, LibTrigger, LibWorld or LibHud fallback runtime pieces. Use
+package-backed or standalone providers. Turn it on only as a temporary escape
+hatch for an older server while migrating to packages.
+
 ## Mixed mode rule
 
 Mixed mode is allowed for migration only:

docs/usage.md

@@ -16,6 +16,17 @@ EasyLibrary 3.x has three possible providers for official libs:
 Only one provider should own a runtime at a time. If a standalone plugin exists,
 it wins over the matching internal package for that server session.
 
+The package-first 3.0-dev default keeps legacy embedded fallback disabled:
+
+```yaml
+legacy-embedded:
+  enabled: false
+```
+
+With this default, install official packages or standalone plugins. If
+LibCommand is unavailable, EasyLibrary registers only the small native recovery
+command so package repair/install commands remain reachable.
+
 ## First boot
 
 After installing EasyLibrary, run:

resources/config.yml

@@ -88,6 +88,14 @@ library-installer:
   # standalone plugin files.
   restart-required: true
 
+# Temporary EasyLibrary 2.x embedded fallback.
+# Keep disabled for the 3.x package-first model. When disabled, EasyLibrary does
+# not automatically start bundled LibCommand, LibPlaceholder, LibTrigger,
+# LibWorld or LibHud fallback runtime pieces. Use official packages or
+# standalone plugins instead.
+legacy-embedded:
+  enabled: false
+
 # Embedded LibPlaceholder options.
 libplaceholder:
   # Optional LibPacket bridge for outgoing text packets.

src/LibraryModules.php

@@ -29,6 +29,11 @@ final class LibraryModules {
     * Load all modules.
     */
     public static function loadModules(PluginBase $plugin): void {
+        if (!self::isLegacyEmbeddedEnabled($plugin)) {
+            $plugin->getLogger()->info('[LegacyEmbedded] Disabled by config; official libs must be loaded as packages or standalone plugins.');
+            return;
+        }
+
         $pluginManager = $plugin->getServer()->getPluginManager();
         $pluginManager->registerEvents(
             new EmbeddedLibraryLifecycleListener($plugin),
@@ -107,6 +112,7 @@ public static function unloadModules(PluginBase $plugin): void {
     }
 
     public static function activateEmbeddedCommandRuntime(PluginBase $plugin): bool {
+        self::requireLegacyEmbeddedEnabled($plugin, 'LibCommand');
         if (!CommandClassAvailability::hookerAvailable()) {
             throw new \RuntimeException('Embedded LibCommand classes are not available.');
         }
@@ -142,6 +148,7 @@ public static function deactivateEmbeddedCommandRuntime(PluginBase $plugin): boo
     }
 
     public static function activateEmbeddedPlaceholderRuntime(PluginBase $plugin): bool {
+        self::requireLegacyEmbeddedEnabled($plugin, 'LibPlaceholder');
         if (!self::isPlaceholderRuntimeAvailable()) {
             throw new \RuntimeException('LibPlaceholder classes are not available.');
         }
@@ -182,6 +189,7 @@ public static function deactivateEmbeddedPlaceholderRuntime(PluginBase $plugin):
     }
 
     public static function activateEmbeddedTriggerRuntime(PluginBase $plugin): bool {
+        self::requireLegacyEmbeddedEnabled($plugin, 'LibTrigger');
         if (!self::isTriggerRuntimeAvailable()) {
             throw new \RuntimeException('LibTrigger classes are not available.');
         }
@@ -218,6 +226,7 @@ public static function deactivateEmbeddedTriggerRuntime(PluginBase $plugin): boo
     }
 
     public static function activateEmbeddedWorldRuntime(PluginBase $plugin): bool {
+        self::requireLegacyEmbeddedEnabled($plugin, 'LibWorld');
         if (!self::isWorldRuntimeAvailable()) {
             throw new \RuntimeException('LibWorld classes are not available.');
         }
@@ -262,6 +271,31 @@ private static function isStandaloneEnabled(PluginBase $plugin, string $pluginNa
         return $standalone !== null && $standalone->isEnabled();
     }
 
+    public static function isLegacyEmbeddedEnabled(PluginBase $plugin): bool {
+        $value = $plugin->getConfig()->getNested('legacy-embedded.enabled', false);
+        if (is_bool($value)) {
+            return $value;
+        }
+        if (is_int($value) || is_float($value)) {
+            return ((int) $value) !== 0;
+        }
+        if (is_string($value)) {
+            $normalized = strtolower(trim($value));
+            if (is_numeric($normalized)) {
+                return ((int) $normalized) !== 0;
+            }
+            return in_array($normalized, ['1', 'true', 'yes', 'on', 'enabled'], true);
+        }
+
+        return false;
+    }
+
+    private static function requireLegacyEmbeddedEnabled(PluginBase $plugin, string $pluginName): void {
+        if (!self::isLegacyEmbeddedEnabled($plugin)) {
+            throw new \RuntimeException("Embedded {$pluginName} runtime is disabled by config (legacy-embedded.enabled=false). Install the official package or standalone plugin instead.");
+        }
+    }
+
     private static function isPlaceholderRuntimeAvailable(): bool {
         return class_exists(\imperazim\placeholder\PlaceholderManager::class);
     }
@@ -339,6 +373,9 @@ public static function onStandalonePlaceholderDisabled(
         PluginBase $plugin,
         Plugin $standalone
     ): void {
+        if (!self::isLegacyEmbeddedEnabled($plugin)) {
+            return;
+        }
         if (!self::isPlaceholderRuntimeAvailable()) {
             return;
         }
@@ -377,6 +414,9 @@ public static function onStandaloneWorldDisabled(
         PluginBase $plugin,
         Plugin $standalone
     ): void {
+        if (!self::isLegacyEmbeddedEnabled($plugin)) {
+            return;
+        }
         if (!self::isWorldRuntimeAvailable()) {
             return;
         }

src/imperazim/library/LibraryStatusService.php

@@ -125,6 +125,10 @@ private function inspect(OfficialLibrarySource $source): LibraryStatus {
             );
         }
 
+        if ($source->getPluginName() !== 'EasyLibraryAgentBridge' && !\LibraryModules::isLegacyEmbeddedEnabled($this->host)) {
+            return $this->legacyEmbeddedDisabledStatus($source);
+        }
+
         return match ($source->getPluginName()) {
             'LibCommand' => $this->embeddedCommandStatus($source),
             'LibPlaceholder' => $this->embeddedPlaceholderStatus($source),
@@ -141,6 +145,19 @@ private function inspect(OfficialLibrarySource $source): LibraryStatus {
         };
     }
 
+    private function legacyEmbeddedDisabledStatus(OfficialLibrarySource $source): LibraryStatus {
+        return new LibraryStatus(
+            $source,
+            LibraryRuntimeState::EMBEDDED_DISABLED,
+            $this->host->getName(),
+            $source->getExpectedVersion(),
+            [
+                'Legacy embedded fallback is disabled by config.',
+                'Install the official package or standalone plugin to provide this library.',
+            ]
+        );
+    }
+
     /**
      * @param string[] $files
      */
@@ -417,6 +434,9 @@ private function embeddedRuntimeHostName(OfficialLibrarySource $source): ?string
     }
 
     private function embeddedFallbackProviderName(OfficialLibrarySource $source): ?string {
+        if ($source->getPluginName() !== 'EasyLibraryAgentBridge' && !\LibraryModules::isLegacyEmbeddedEnabled($this->host)) {
+            return null;
+        }
         if ($source->getEmbeddedKind() === OfficialLibrarySource::EMBEDDED_CLASSPATH) {
             return $this->host->getName();
         }

src/imperazim/library/command/backend/CommandBackendResolver.php

@@ -7,6 +7,8 @@
 use imperazim\agent\AgentManager;
 use imperazim\components\plugin\PluginToolkit;
 use imperazim\library\command\provider\CommandClassAvailability;
+use imperazim\library\command\provider\CommandProviderResolver;
+use imperazim\library\command\provider\CommandProviderStatus;
 
 final class CommandBackendResolver {
 
@@ -16,7 +18,14 @@ public function __construct(
     ) {}
 
     public function resolve(): CommandBackend {
-        if (CommandClassAvailability::richCommandsAvailable()) {
+        $provider = (new CommandProviderResolver($this->host))->resolve();
+        if (
+            CommandClassAvailability::richCommandsAvailable()
+            && (
+                $provider->getProvider() !== CommandProviderStatus::EMBEDDED_LEGACY
+                || \LibraryModules::isLegacyEmbeddedEnabled($this->host)
+            )
+        ) {
             return new LibCommandBackend($this->host, $this->agentManager);
         }
 

src/imperazim/library/command/provider/CommandProviderResolver.php

@@ -40,8 +40,13 @@ public function resolve(): CommandProviderStatus {
         $notes = [];
 
         if ($provider === CommandProviderStatus::EMBEDDED_LEGACY) {
-            $warnings[] = 'EasyLibrary internal commands are currently using the embedded legacy LibCommand classes.';
-            $notes[] = 'Do not remove src/imperazim/command until package-backed or standalone LibCommand is guaranteed for command registration.';
+            if (\LibraryModules::isLegacyEmbeddedEnabled($this->host)) {
+                $warnings[] = 'EasyLibrary internal commands are currently using the embedded legacy LibCommand classes.';
+                $notes[] = 'Do not remove src/imperazim/command until package-backed or standalone LibCommand is guaranteed for command registration.';
+            } else {
+                $notes[] = 'Embedded legacy LibCommand classes exist on disk but are disabled by legacy-embedded.enabled=false.';
+                $notes[] = 'EasyLibrary will use the native recovery command unless package-backed or standalone LibCommand is active.';
+            }
         }
         if ($provider === CommandProviderStatus::MISSING) {
             $warnings[] = 'imperazim\\command\\Command is not loaded; EasyLibrary command registration would fail.';