feat(package): register libcommons package

Author: ImperaZim

CHANGELOG.md

@@ -98,6 +98,7 @@ elprobe run <package>
   - `libserializer`;
   - `libform`;
   - `libdb`;
+  - `libcommons`;
   - `libplaceholder`;
   - `libworld`;
   - `agent-bridge`;
@@ -106,10 +107,15 @@ elprobe run <package>
   - `libhud`;
   - `libtrigger`;
   - `libwindow`.
-- Validated all 13 official packages as package-backed plugins in the local
-  3.0-dev matrix.
+- Added `LibCommons` as the first new official 3.0-dev library repository. It
+  ships as both a standalone PHAR and an EasyLibrary `classpath` package with
+  release assets (`.phar`, `.easylib.zip`, `package.yml` and `checksums.txt`).
+- Registered `libcommons` in the package manager catalog and standalone library
+  installer catalog.
+- Validated all 14 official packages as package-backed plugins in the local
+  3.0-dev matrix after adding `LibCommons`.
 - Validated fresh installation from official GitHub Release `.easylib.zip`
-  assets for all 13 official packages on a disposable PMMP server.
+  assets for all 14 official packages on a disposable PMMP server.
 - Kept standalone plugins supported and protected by the standalone shadow
   guard.
 
@@ -129,7 +135,7 @@ elprobe run <package>
 - Added package status/doctor detection for package-backed plugins that load
   before EasyLibrary itself.
 - Added staged validation waves for package-backed proxies, ending with all
-  13 official packages active and healthy.
+  14 official packages active and healthy.
 - Hardened the package-backed proxy loader so parked or stale proxy folders are
   never accepted as loadable plugins. A proxy now needs an armed `plugin.yml`
   and a matching installed `package-state.yml` entry before PMMP can load it.

README.md

@@ -17,7 +17,7 @@ The 3.x direction is: EasyLibrary becomes the minimal manager, official libs bec
 
 ## What EasyLibrary provides
 
-- A 3.x internal package manager foundation for official packages such as `libpacket`, `libcommand`, `libserializer`, `libform`, `libdb`, `libplaceholder`, `libworld` and `agent-bridge`.
+- A 3.x internal package manager foundation for official packages such as `libpacket`, `libcommand`, `libserializer`, `libform`, `libdb`, `libcommons`, `libplaceholder`, `libworld` and `agent-bridge`.
 - Dry-run package install plans, checksum-backed downloads, backups, restart-required state and package lock diagnostics.
 - Legacy standalone PHAR install planning through `/easylibrary libs install` while migration is in progress.
 - Official library runtime diagnostics through `/easylibrary libs`, `/easylibrary packages` and `/easylibrary doctor`.
@@ -67,7 +67,7 @@ Run these commands after installing or updating EasyLibrary:
 At minimum, a healthy server should report `Problems: 0`. When all official packages are installed and active, a full package-backed test server looks like this:
 
 ```txt
-Libraries: 13 / standalone: 0 / package-backed: 13 / not installed: 0
+Libraries: 14 / standalone: 0 / package-backed: 14 / not installed: 0
 Problems: 0
 Command provider: package-backed
 Command backend: libcommand-rich
@@ -193,6 +193,7 @@ while migrating one library at a time.
 | [LibForm](https://github.com/ImperaZim/LibForm) | `imperazim\form` | Long, modal, custom, paginated, conditional and chained forms |
 | [LibHud](https://github.com/ImperaZim/LibHud) | `imperazim\hud` | Boss bars, scoreboards, nametags, titles, notifications and tab lists |
 | [LibDB](https://github.com/ImperaZim/LibDB) | `imperazim\db` | SQLite/MySQL, query builder, models, migrations, seeds, cache and async queries |
+| [LibCommons](https://github.com/ImperaZim/LibCommons) | `imperazim\commons` | Arrays, text, numbers, time, durations and validation helpers |
 | [LibSerializer](https://github.com/ImperaZim/LibSerializer) | `imperazim\serializer` | Items, blocks, entities, inventories, positions, skins and schematics |
 | [LibTrigger](https://github.com/ImperaZim/LibTrigger) | `imperazim\trigger` | Scheduled global, per-player and item triggers with modes and priorities |
 | [LibWindow](https://github.com/ImperaZim/LibWindow) | `imperazim\window` | Virtual inventories, layouts, sessions, transactions and window presets |
@@ -322,7 +323,7 @@ The preferred 3.x command path is `/easylibrary packages`. The old `/easylibrary
 ```
 
 
-Current asset-ready internal packages in this wave include `libpacket`, `libcommand`, `libserializer`, `libform`, `libdb`, `libplaceholder`, `libworld`, `agent-bridge`, `libcustom`, `libenchantment`, `libhud`, `libtrigger` and `libwindow`. Every package remains protected by the standalone shadow guard while a matching standalone plugin is installed.
+Current asset-ready internal packages in this wave include `libpacket`, `libcommand`, `libserializer`, `libform`, `libdb`, `libcommons`, `libplaceholder`, `libworld`, `agent-bridge`, `libcustom`, `libenchantment`, `libhud`, `libtrigger` and `libwindow`. Every package remains protected by the standalone shadow guard while a matching standalone plugin is installed.
 
 ### Internal package activation gate
 
@@ -411,7 +412,7 @@ First package targets:
 - `libpacket` is the first dependency-safe classpath package and should be installed before command/runtime packages that depend on packet services.
 - `libcommand` is asset-ready too, but should be installed after `libpacket`.
 
-The package-backed loader has now validated the base wave (`libserializer`, `libform`, `libdb`, `libpacket`, `libcommand`), the isolated runtime wave (`libwindow`, `libcustom`, `libenchantment`, `libtrigger`), the standalone `libhud` wave, the dependency-heavy placeholder wave, the world-service wave and the final Agent bridge wave.
+The package-backed loader has now validated the base wave (`libserializer`, `libform`, `libdb`, `libpacket`, `libcommand`), the isolated runtime wave (`libwindow`, `libcustom`, `libenchantment`, `libtrigger`), the standalone `libhud` wave, the dependency-heavy placeholder wave, the world-service wave, the final Agent bridge wave and the new `libcommons` classpath package wave.
 
 `/easylibrary packages doctor` validates package paths, installed manifests, sha256 metadata, proxy marker data and stale restart markers. If a package is already active through the package-backed proxy, stale restart-required entries are cleared automatically.
 
@@ -429,11 +430,11 @@ The package-backed loader has now validated the base wave (`libserializer`, `lib
 
 `/easylibrary doctor` also reports the active command provider and the selected command backend. The provider explains where `imperazim\command\Command` was loaded from, while the backend explains how EasyLibrary registered its command surface: `libcommand-rich` for the full command tree or `native-pocketmine-recovery` for the minimal recovery command. EasyLibrary 3.x only treats package-backed or standalone `LibCommand` as rich command providers; if neither is available, the core registers the recovery-safe native command.
 
-The package-backed command path has been validated in-game with all 13 official packages active: `/easylibrary doctor` should show `Command provider: package-backed`, `Command backend: libcommand-rich`, `rich: yes`, `overrides: yes` and no official library runtime problems.
+The package-backed command path has been validated in-game with all official packages active: `/easylibrary doctor` should show `Command provider: package-backed`, `Command backend: libcommand-rich`, `rich: yes`, `overrides: yes` and no official library runtime problems.
 
 If LibCommand is unavailable, EasyLibrary registers a minimal recovery command that uses PocketMine's native command base instead of the rich LibCommand tree. That fallback intentionally exposes only recovery-safe commands: `doctor`, `config doctor`, `config reload`, `config migrate`, `config repair`, `packages doctor`, `packages install`, `packages repair` and `packages cleanup`. This means a broken or missing command provider can be recovered from console with `/easylibrary packages install libcommand confirm` after package writes are enabled.
 
-During mixed-mode migration, installing `libpacket`, `libcommand`, `libserializer`, `libform`, `libdb`, `libwindow`, `libcustom`, `libenchantment`, `libtrigger`, `libhud`, `libplaceholder`, `libworld` or `agent-bridge` while the standalone PHAR is still in `plugins/` is allowed. After restart, the package is expected to show as `installed-shadowed-by-standalone`; the standalone plugin continues to provide the runtime and EasyLibrary does not autoload the duplicate internal package.
+During mixed-mode migration, installing `libpacket`, `libcommand`, `libserializer`, `libform`, `libdb`, `libcommons`, `libwindow`, `libcustom`, `libenchantment`, `libtrigger`, `libhud`, `libplaceholder`, `libworld` or `agent-bridge` while the standalone PHAR is still in `plugins/` is allowed. After restart, the package is expected to show as `installed-shadowed-by-standalone`; the standalone plugin continues to provide the runtime and EasyLibrary does not autoload the duplicate internal package.
 
 Example dry-run:
 

docs/smoke-tests.md

@@ -52,6 +52,7 @@ libcommand
 libserializer
 libform
 libdb
+libcommons
 libplaceholder
 libworld
 agent-bridge
@@ -94,7 +95,7 @@ Config: package-manager=split / library-installer=split / components=split
 For a full package-backed server, `/easylibrary packages doctor` should report:
 
 ```text
-Packages: 13 / installed: 13 / active: 13 / pending restart: 0 / shadowed: 0
+Packages: 14 / installed: 14 / active: 14 / pending restart: 0 / shadowed: 0
 Problems: 0
 ```
 
@@ -109,6 +110,7 @@ Each official package must pass both the source guard and the functional probe.
 | `libserializer` | `source=package-backed-plugin` | `functional=yes` for compact format roundtrip |
 | `libform` | `source=package-backed-plugin` | `functional=yes` for form builder output |
 | `libdb` | `source=package-backed-plugin` | `functional=yes` for SQLite CRUD |
+| `libcommons` | `source=package-backed-plugin` | `functional=yes` for pure array/text/number/time/validation helpers |
 | `libplaceholder` | `source=package-backed-plugin` | `functional=yes` for placeholder parse and registry state |
 | `libworld` | `source=package-backed-plugin` | `functional=yes` for world service/runtime checks |
 | `agent-bridge` | `source=package-backed-plugin` | `functional=yes` for bridge runtime status, heartbeat and PubSub state |
@@ -126,6 +128,7 @@ Run all package probes:
 /elprobe run libserializer
 /elprobe run libform
 /elprobe run libdb
+/elprobe run libcommons
 /elprobe run libplaceholder
 /elprobe run libworld
 /elprobe run agent-bridge
@@ -188,7 +191,7 @@ Status target: required before stable.
 Purpose:
 
 ```text
-Prove all 13 official packages can be active through EasyLibrary package-backed
+Prove all 14 official packages can be active through EasyLibrary package-backed
 proxies in one server session.
 ```
 
@@ -219,8 +222,8 @@ Then run every package probe from the package functional probe matrix.
 Expected:
 
 ```text
-Libraries: 13 / standalone: 0 / package-backed: 13
-Packages: 13 / installed: 13 / active: 13 / pending restart: 0 / shadowed: 0
+Libraries: 14 / standalone: 0 / package-backed: 14
+Packages: 14 / installed: 14 / active: 14 / pending restart: 0 / shadowed: 0
 Problems: 0
 Command provider: package-backed
 Command backend: libcommand-rich
@@ -433,6 +436,9 @@ LibWindow v2.0.0-dev
 LibWorld v1.0.0-dev
 ```
 
+LibCommons was not part of this older standalone-only run and must be included
+when this scenario is rerun for the final 3.0 release candidate.
+
 Command checks:
 
 ```text
@@ -590,9 +596,9 @@ Pass criteria:
 
 ```text
 Before restart: libform / LibForm v2.0.0-dev [installed-pending-restart]
-Before restart: Packages: 13 / installed: 13 / active: 12 / pending restart: 1
+Before restart: Packages: 14 / installed: 14 / active: 13 / pending restart: 1
 After restart:  libform / LibForm v2.0.0-dev [active]
-After restart:  Packages: 13 / installed: 13 / active: 13 / pending restart: 0
+After restart:  Packages: 14 / installed: 14 / active: 14 / pending restart: 0
 functional=yes
 ```
 
@@ -845,6 +851,8 @@ DevTools: absent
 EasyLibraryPackageProbe: absent
 PMMP plugins: 14 enabled, 0 disabled
 Packages: 13/13 installed, 13 active, 0 pending, 0 shadowed
+Note: this older PHAR smoke predates LibCommons; rerun with 14/14 packages
+before the final 3.0 release candidate.
 EasyLibrary doctor: Problems 0
 Package doctor: Problems 0
 Config doctor: Problems 0
@@ -952,7 +960,7 @@ Follow-up issues:
 Before tagging `3.0.0`, these must be true:
 
 - `server-clean` passes.
-- `package-backed-all` passes with all 13 official packages.
+- `package-backed-all` passes with all 14 official packages.
 - `mixed-standalone`, `standalone-to-package` and `package-to-standalone` pass.
 - `command-provider-fallback` passes.
 - `config-split` passes.

docs/usage.md

@@ -36,7 +36,7 @@ At minimum, a healthy server should report `Problems: 0`. When all official pack
 Problems: 0
 Command provider: package-backed
 Command backend: libcommand-rich
-Packages: 13 / installed: 13 / active: 13
+Packages: 14 / installed: 14 / active: 14
 Config: package-manager=split / library-installer=split / components=split
 ```
 

resources/config.yml

@@ -51,6 +51,7 @@ package-manager:
       - libdb
       - libpacket
       - libcommand
+      - libcommons
       - libwindow
       - libcustom
       - libenchantment

resources/config/package-manager.yml

@@ -48,6 +48,7 @@ plugin-loader:
     - libdb
     - libpacket
     - libcommand
+    - libcommons
     - libwindow
     - libcustom
     - libenchantment

src/imperazim/library/LibraryStatusService.php

@@ -148,8 +148,10 @@ private function packageBackedStatus(
         ];
         $version = $plugin->getDescription()->getVersion();
 
-        if ($version !== $source->getExpectedVersion()) {
+        if (!$this->acceptsVersion($source, $version)) {
             $problems[] = "Expected {$source->getExpectedVersion()}, found {$version}.";
+        } elseif ($version !== $source->getExpectedVersion()) {
+            $notes[] = 'Development channel provider is active.';
         }
         if ($files !== []) {
             $notes[] = 'A standalone artifact also exists in /plugins, but the active provider is package-backed.';
@@ -179,8 +181,10 @@ private function standaloneStatus(
         $version = $standalone->getDescription()->getVersion();
         $state = LibraryRuntimeState::STANDALONE_ACTIVE;
 
-        if ($version !== $source->getExpectedVersion()) {
+        if (!$this->acceptsVersion($source, $version)) {
             $problems[] = "Expected {$source->getExpectedVersion()}, found {$version}.";
+        } elseif ($version !== $source->getExpectedVersion()) {
+            $notes[] = 'Development channel provider is active.';
         }
 
         if ($files === []) {
@@ -239,4 +243,9 @@ private function pluginDirectory(): ?string {
         $directory = $serverRoot . DIRECTORY_SEPARATOR . 'plugins';
         return is_dir($directory) ? $directory : null;
     }
+
+    private function acceptsVersion(OfficialLibrarySource $source, string $version): bool {
+        return $version === $source->getExpectedVersion()
+            || $version === $source->getVersionForChannel('development');
+    }
 }

src/imperazim/library/OfficialLibraryRegistry.php

@@ -46,6 +46,15 @@ public static function all(): array {
                 'SQLite/MySQL access, query builders, models, migrations and cache helpers.',
                 ['database']
             ),
+            new OfficialLibrarySource(
+                'commons',
+                'LibCommons',
+                'ImperaZim/LibCommons',
+                '1.0.0',
+                OfficialLibrarySource::PACKAGE_CLASSPATH,
+                'Common helpers for arrays, text, numbers, time, durations and validation.',
+                ['common', 'utils', 'utilities']
+            ),
             new OfficialLibrarySource(
                 'serializer',
                 'LibSerializer',

src/imperazim/library/package/PackageRegistry.php

@@ -96,6 +96,23 @@ public static function all(): array {
                 PackageSource::CATALOG_PACKAGED,
                 'imperazim\\db\\LibDB'
             ),
+            new PackageSource(
+                'libcommons',
+                'LibCommons',
+                'ImperaZim/LibCommons',
+                '1.0.0',
+                'classpath',
+                'imperazim\\commons',
+                'Common utility helpers for arrays, text, numbers, time, durations and validation.',
+                true,
+                ['commons', 'common', 'utils', 'utilities'],
+                [],
+                [],
+                ['commons', 'utilities'],
+                'checksums.txt',
+                PackageSource::CATALOG_PACKAGED,
+                'imperazim\\commons\\LibCommons'
+            ),
             new PackageSource(
                 'libplaceholder',
                 'LibPlaceholder',