feat(library): add proxy diagnostics and components config split

Author: ImperaZim

CHANGELOG.md

@@ -202,9 +202,13 @@ elprobe run <package>
   installed packages no longer reports false dependency failures.
 - Added package proxy inspection and guarded operations:
   - `/easylibrary packages proxies [package]`;
+  - `/easylibrary packages proxies doctor [package]`;
   - `/easylibrary packages proxies prepare <package> confirm`;
   - `/easylibrary packages proxies reconcile confirm`;
   - `/easylibrary packages proxies cleanup confirm`.
+- Proxy diagnostics now print a mount summary plus per-package recovery hints
+  for missing/incomplete proxies, stale metadata, parked manifests, standalone
+  shadows and plugin-loader allow/block-list problems.
 
 ### Runtime diagnostics absorbed into 3.0-dev
 
@@ -297,9 +301,16 @@ elprobe run <package>
 - Standalone library-installer settings now read from
   `config/library-installer.yml` when present and fall back to `config.yml`
   values when absent.
-- Added split config templates for package manager and library installer.
-- Config doctor, migrate, repair and reload now operate on both supported areas:
-  `package-manager` and `library-installer`.
+- Core component settings now read from `config/components.yml` when present
+  and fall back to the legacy `components.yml` file when absent.
+- Fresh servers without a legacy `components.yml` now generate component
+  settings under `config/components.yml`.
+- Added split config templates for package manager, library installer and
+  components.
+- Config doctor, migrate, repair and reload now operate on the supported areas:
+  `package-manager`, `library-installer` and `components`.
+- Component config reload is intentionally diagnostic only for the current
+  session; component toggles and command overrides take effect on the next boot.
 
 ### Runtime compatibility hardening
 
@@ -339,7 +350,8 @@ elprobe run <package>
 - Package install/update/remove/rollback flows prepare the next boot.
 - Proxy folders under `plugins/` are still required when PMMP plugin identity
   must satisfy `depend`, `softdepend`, `/pl` and `getPlugin()`.
-- Config Split currently covers `package-manager` and `library-installer`.
+- Config Split currently covers `package-manager`, `library-installer` and
+  `components`.
 - Legacy embedded source has been removed from the EasyLibrary core. Remaining
   3.0-dev hardening should focus on package lifecycle, docs/wiki and release
   validation.

README.md

@@ -67,7 +67,7 @@ Libraries: 13 / standalone: 0 / package-backed: 13 / not installed: 0
 Problems: 0
 Command provider: package-backed
 Command backend: libcommand-rich
-Config: package-manager=split / library-installer=split
+Config: package-manager=split / library-installer=split / components=split
 ```
 
 If the server still reports `legacy` config, migrate supported config blocks once:
@@ -78,7 +78,7 @@ If the server still reports `legacy` config, migrate supported config blocks onc
 /easylibrary config doctor
 ```
 
-The migration writes supported files such as `plugin_data/EasyLibrary/config/package-manager.yml` and `plugin_data/EasyLibrary/config/library-installer.yml`, then leaves the old `config.yml` blocks untouched as fallback.
+The migration writes supported files such as `plugin_data/EasyLibrary/config/package-manager.yml`, `plugin_data/EasyLibrary/config/library-installer.yml` and `plugin_data/EasyLibrary/config/components.yml`, then leaves the old `config.yml` blocks and legacy `components.yml` untouched as fallback.
 
 ### Installing internal packages
 
@@ -118,7 +118,7 @@ elprobe run libplaceholder
 
 ### Safe config operations
 
-Config Split currently supports `package-manager` and `library-installer`:
+Config Split currently supports `package-manager`, `library-installer` and `components`:
 
 ```txt
 /easylibrary config doctor
@@ -127,7 +127,7 @@ Config Split currently supports `package-manager` and `library-installer`:
 /easylibrary config repair [confirm]
 ```
 
-`config reload` reloads config files only. It does not hot-swap package-backed plugins, regenerate PMMP dependency graphs, change loaded permissions or remount proxies. Changes to `plugin-loader`, `runtime-autoload`, `plugin.yml`, dependencies, permissions and load order still require restart.
+`config reload` reloads config files only. It does not hot-swap package-backed plugins, regenerate PMMP dependency graphs, change loaded permissions, remount proxies, enable/disable active components or re-register command overrides. Changes to `plugin-loader`, `runtime-autoload`, `components`, `plugin.yml`, dependencies, permissions and load order still require restart.
 
 ### Plugin developer rule of thumb
 
@@ -255,6 +255,7 @@ The preferred 3.x command path is `/easylibrary packages`. The old `/easylibrary
 | Return to local package version | `/easylibrary packages rollback <package> [version] [confirm]` |
 | Clean temporary downloads/staging | `/easylibrary packages cleanup [confirm]` |
 | Inspect package proxy mounts | `/easylibrary packages proxies [package]` |
+| Diagnose package proxy mounts | `/easylibrary packages proxies doctor [package]` |
 | Prepare one proxy | `/easylibrary packages proxies prepare <package> confirm` |
 | Reconcile managed proxies | `/easylibrary packages proxies reconcile confirm` |
 | Repair state, lock and proxy metadata | `/easylibrary packages repair <package\|all> [confirm]` |
@@ -274,6 +275,7 @@ The preferred 3.x command path is `/easylibrary packages`. The old `/easylibrary
 /easylibrary packages rollback <package> [version] [confirm]
 /easylibrary packages cleanup [confirm]
 /easylibrary packages proxies [package]
+/easylibrary packages proxies doctor [package]
 /easylibrary packages proxies prepare <package> confirm
 /easylibrary packages proxies reconcile confirm
 /easylibrary packages proxies cleanup confirm
@@ -291,24 +293,25 @@ Current asset-ready internal packages in this wave include `libpacket`, `libcomm
 
 Installing a package is still separate from replacing a standalone plugin. EasyLibrary 3.0-dev prepares a hidden package-backed proxy under `plugins/.easylibrary-<Plugin>.easylibplugin/`, while the real package code stays under `plugin_data/EasyLibrary/packages/`. If the matching standalone plugin is present, the proxy is parked and the standalone wins for that server session.
 
-### Modular package-manager config
+### Modular config split
 
-EasyLibrary 3.0-dev includes the first Config Split foundation. Package-manager and standalone library-installer settings can now be read from:
+EasyLibrary 3.0-dev includes the Config Split foundation. Package-manager, standalone library-installer and core component settings can now be read from:
 
 ```txt
 plugin_data/EasyLibrary/config/package-manager.yml
 plugin_data/EasyLibrary/config/library-installer.yml
+plugin_data/EasyLibrary/config/components.yml
 ```
 
-When one of those files exists, its values override the matching `package-manager.*` or `library-installer.*` entries from the legacy `plugin_data/EasyLibrary/config.yml`. If a split file does not exist, the old `config.yml` path continues to work exactly as before. No config file is moved or migrated automatically in this phase.
+When `package-manager.yml` or `library-installer.yml` exists, its values override the matching `package-manager.*` or `library-installer.*` entries from the legacy `plugin_data/EasyLibrary/config.yml`. When `components.yml` exists under `config/`, it overrides the legacy `plugin_data/EasyLibrary/components.yml`. Existing legacy files are left in place as fallback.
 
 Use `/easylibrary doctor` to confirm which config sources are active. The doctor reports `split`, `legacy` or `defaults` for supported areas. For a more detailed migration check, run `/easylibrary config doctor`; it prints each split path, split value detection, legacy value detection and any warnings about empty or mismatched split files.
 
-Use `/easylibrary config migrate` for a dry-run plan that creates supported split files from legacy `config.yml` blocks. Repeat with `confirm` to write missing split files. The command intentionally leaves `config.yml` unchanged, so rollback is just removing the split file and restarting if behavior changed.
+Use `/easylibrary config migrate` for a dry-run plan that creates supported split files from legacy sources. `package-manager` and `library-installer` are copied from `config.yml`; `components` is copied from `components.yml`. Repeat with `confirm` to write missing split files. The command intentionally leaves legacy files unchanged, so rollback is just removing the split file and restarting if behavior changed.
 
-Use `/easylibrary config repair` when a supported split file is missing, empty or not recognized but `config.yml` still has a valid block for that area. It is dry-run by default; with `confirm`, it writes only the split file and still leaves `config.yml` untouched. It does not try to reconcile divergent values yet.
+Use `/easylibrary config repair` when a supported split file is missing, empty or not recognized but the legacy source still has valid values for that area. It is dry-run by default; with `confirm`, it writes only the split file and still leaves legacy files untouched. It does not try to reconcile divergent values yet.
 
-Use `/easylibrary config reload` for a safe config-file reload. It reloads `config.yml`, rereads split config files through a fresh resolver and reports restart boundaries. It does not unload, mount or hot-swap package-backed plugins; changes to `package-manager.plugin-loader`, `package-manager.runtime-autoload`, plugin dependencies, permissions or load order still require a restart to affect the current PMMP session.
+Use `/easylibrary config reload` for a safe config-file reload. It reloads `config.yml`, rereads split config files through a fresh resolver and reports restart boundaries. It does not unload, mount or hot-swap package-backed plugins; changes to `package-manager.plugin-loader`, `package-manager.runtime-autoload`, `components`, plugin dependencies, permissions or load order still require a restart to affect the current PMMP session.
 
 The modular files use each legacy block's contents without the outer area key. For `package-manager.yml`:
 
@@ -341,6 +344,16 @@ backup-before-install: true
 restart-required: true
 ```
 
+For `components.yml`:
+
+```yaml
+logger: true
+commands:
+  overwrite_defaults: true
+vendor:
+  Cache: true
+```
+
 For controlled smoke tests, remove one matching standalone plugin at a time and restart. The package should move from `installed-shadowed-by-standalone` to `active`, `/easylibrary packages doctor` should report no problems, and `elprobe run <package>` should report `functional=yes`.
 
 Package installs are guarded by the same safety rules as the standalone installer:
@@ -367,6 +380,8 @@ The package-backed loader has now validated the base wave (`libserializer`, `lib
 
 `/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.
 
+`/easylibrary packages proxies doctor [package]` focuses only on generated package-backed proxy mounts. It prints mount summaries, active/parked/missing manifest counts and per-package recovery hints such as `proxies prepare`, `packages repair`, `packages switch` or config allow-list fixes.
+
 `/easylibrary packages repair <package|all>` is dry-run by default. With `confirm`, it can rewrite missing package lock entries from installed state, normalize stale state metadata, clear restart markers for active package-backed plugins and regenerate managed proxy mounts.
 
 `/easylibrary packages update <package> [channel]` is also dry-run by default. It only stages a different registered target version for an already installed package; it does not move the currently loaded package directory while the server is running, and the updated package becomes active after restart.
@@ -417,6 +432,7 @@ The standalone installer remains available for compatibility. The preferred 3.x
 /easylibrary packages rollback <package> [version] [confirm]
 /easylibrary packages cleanup [confirm]
 /easylibrary packages proxies [package]
+/easylibrary packages proxies doctor [package]
 /easylibrary packages proxies prepare <package> confirm
 /easylibrary packages proxies reconcile confirm
 /easylibrary packages proxies cleanup confirm

changelogs/3.0.md

@@ -1029,6 +1029,35 @@ Failed to load some plugins, stopping server to protect server integrity
 | `parked-standalone-present` | standalone exists and wins. |
 | `armed-switch-pending` | operator confirmed migration and must remove standalone before boot. |
 
+### Proxy doctor
+
+Proxy recovery now has a dedicated read-only diagnostic mode:
+
+```text
+/easylibrary packages proxies doctor
+/easylibrary packages proxies doctor libplaceholder
+```
+
+The normal `proxies` command still lists generated mounts. The `doctor` action
+adds operator guidance:
+
+- installed proxy mount counts;
+- complete, active, parked, missing and blocked proxy totals;
+- per-package mount and package paths;
+- package status problems related to proxy markers or package state;
+- the next recovery command to run.
+
+Example recovery hints:
+
+```text
+/easylibrary packages proxies prepare libplaceholder confirm
+/easylibrary packages repair libplaceholder confirm
+/easylibrary packages switch libplaceholder
+```
+
+This keeps proxy troubleshooting inside EasyLibrary instead of forcing admins
+to inspect hidden folders or marker JSON by hand.
+
 ### Migration flows
 
 Standalone to package:
@@ -1326,7 +1355,7 @@ It keeps server/system information and adds EasyLibrary context:
 Packages: 13/13 installed, 13 active, 0 pending, 0 shadowed
 Official libs: 13 package-backed, 0 standalone, 0 not installed
 Command backend: libcommand-rich
-Config: package-manager=split / library-installer=split
+Config: package-manager=split / library-installer=split / components=split
 ```
 
 It also fixed the PHP 8.2 float-to-int deprecation from the old uptime
@@ -1341,16 +1370,25 @@ Supported split files:
 ```text
 plugin_data/EasyLibrary/config/package-manager.yml
 plugin_data/EasyLibrary/config/library-installer.yml
+plugin_data/EasyLibrary/config/components.yml
 ```
 
-Read order:
+Read order for `package-manager` and `library-installer`:
 
 ```text
 1. config/<area>.yml
 2. config.yml legacy block
 3. built-in defaults
 ```
 
+Read order for `components`:
+
+```text
+1. config/components.yml
+2. components.yml legacy file
+3. built-in defaults
+```
+
 Commands:
 
 ```text
@@ -1364,7 +1402,9 @@ Commands:
 
 The old `config.yml` was becoming too large. Package manager, runtime autoload,
 plugin loader, installer and future notification settings all need separate
-space.
+space. Component settings were already separate, but lived beside `config.yml`
+as `components.yml`; moving them under `config/` keeps operational config in a
+single predictable directory.
 
 Config Split starts moving large areas into:
 
@@ -1374,6 +1414,11 @@ plugin_data/EasyLibrary/config/
 
 without breaking old servers that still use `config.yml`.
 
+For components, existing servers keep using `components.yml` until
+`/easylibrary config migrate confirm` creates `config/components.yml`. Fresh
+servers without a legacy component file write component defaults directly under
+`config/components.yml`.
+
 ### Example `package-manager.yml`
 
 ```yaml
@@ -1396,6 +1441,16 @@ backup-before-install: true
 restart-required: true
 ```
 
+### Example `components.yml`
+
+```yaml
+logger: true
+commands:
+  overwrite_defaults: true
+vendor:
+  Cache: true
+```
+
 ### Migration flow
 
 Dry-run:
@@ -1417,10 +1472,10 @@ Validate:
 /easylibrary doctor
 ```
 
-Expected after migrating both supported areas:
+Expected after migrating all supported areas:
 
 ```text
-Config: package-manager=split / library-installer=split
+Config: package-manager=split / library-installer=split / components=split
 ```
 
 ### Repair flow
@@ -1434,6 +1489,12 @@ Repair is conservative. It can recreate a missing split file or replace an
 empty/unrecognized split file from a usable legacy block. It does not merge
 divergent values yet.
 
+Reload is still bounded. `/easylibrary config reload` can refresh values for
+future command reads, but it does not hot-swap package-backed plugins, remount
+proxies, enable/disable active components or re-register `/plugins` and
+`/version` overrides. Component config changes should be followed by a restart
+when they affect runtime behavior.
+
 ### Reload flow
 
 ```text

docs/getting-started.md

@@ -32,6 +32,9 @@ If `config doctor` reports `legacy`, migrate supported split configs:
 /easylibrary config migrate confirm
 ```
 
+The current split areas are `package-manager`, `library-installer` and
+`components`. Existing legacy files are kept as rollback fallback.
+
 ## Use from another plugin
 
 If your plugin requires EasyLibrary to boot:

docs/migration.md

@@ -82,10 +82,11 @@ if($provider === null || !$provider->isEnabled()){
 
 ## Safe rollback
 
-Because config migration does not delete `config.yml`, rollback is simple:
+Because config migration does not delete `config.yml` or `components.yml`,
+rollback is simple:
 
 1. Stop the server.
-2. Remove or move the relevant split file, such as `plugin_data/EasyLibrary/config/package-manager.yml` or `plugin_data/EasyLibrary/config/library-installer.yml`.
+2. Remove or move the relevant split file, such as `plugin_data/EasyLibrary/config/package-manager.yml`, `plugin_data/EasyLibrary/config/library-installer.yml` or `plugin_data/EasyLibrary/config/components.yml`.
 3. Start the server.
 4. Confirm `/easylibrary config doctor` reports `legacy` for that area.
 

docs/smoke-tests.md

@@ -88,7 +88,7 @@ Passing baseline:
 Problems: 0
 Command provider: package-backed
 Command backend: libcommand-rich
-Config: package-manager=split / library-installer=split
+Config: package-manager=split / library-installer=split / components=split
 ```
 
 For a full package-backed server, `/easylibrary packages doctor` should report:
@@ -503,7 +503,7 @@ Purpose:
 
 ```text
 Prove split config files can be created, repaired and reloaded without deleting
-legacy config.yml values.
+legacy config.yml or components.yml values.
 ```
 
 Steps:
@@ -523,14 +523,18 @@ Expected after migration:
 ```text
 Package manager: split / split file: yes / split values: yes / legacy values: yes
 Library installer: split / split file: yes / split values: yes / legacy values: yes
+Components: split / split file: yes / split values: yes / legacy values: yes
 Legacy values still exist in config.yml; split config takes precedence.
+Legacy components values still exist in components.yml; split config takes precedence.
 ```
 
 Pass criteria:
 
 - `config/package-manager.yml` exists.
 - `config/library-installer.yml` exists.
+- `config/components.yml` exists.
 - `config.yml` remains untouched.
+- `components.yml` remains untouched when it existed before migration.
 - `config reload` explains restart boundaries.
 - Doctor still reports `Problems: 0`.