feat: extend module platform with UI slots, runtime components, CLI tooling and {{userId}} search support

Completes the generic module platform that enables modules to contribute
UI elements, runtime JS components, and search resources without any
core hardcoding.

New generic UI slot types:
- topbar.right_item: module-contributed topbar buttons
- layout.body_end_template: module-contributed dialog/overlay templates
- layout.head_style: module-contributed global CSS
- runtime.component: declarative JS component registration with phase ordering

New infrastructure:
- ModuleAutoloader: PSR-4 autoloading for module-local PHP classes
- ModuleRuntimePageBuilder: symlinks module pages into runtime directory
- ModuleRuntimeAssetPublisher: publishes module CSS/JS to web/modules/
- ModulePermissionSynchronizer: syncs module permissions to DB
- CLI scripts: module-runtime-sync, module-build, module-migrate,
  module-permissions-sync, module-assets-sync
- {{userId}} placeholder in SearchDataService for user-scoped search queries
- Component runtime with phased initialization (early/default/late)
- AppContainer.protectExistingBindings() to prevent module→core overwrites
- Architecture tests: ModuleStructureContractTest, CoreTemplateIsolationTest,
  FrontendComponentRuntimeContractTest, AppContainerIsolationContractTest

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

tests/Unit/Module/LayoutContextProviderTest.php

@@ -4,24 +4,34 @@ namespace MintyPHP\Tests\Unit\Module;
 
 use MintyPHP\App\AppContainer;
 use MintyPHP\Module\AddressBook\Providers\AddressBookLayoutProvider;
+use MintyPHP\Tests\Support\AppContainerIsolationTrait;
 use PHPUnit\Framework\TestCase;
 
 /**
  * Verifies that the AddressBookLayoutProvider correctly contributes
- * the 'addressBook' key to the layout context.
+ * the 'addressbook.nav' key to the layout context.
  */
 final class LayoutContextProviderTest extends TestCase
 {
+    use AppContainerIsolationTrait;
+
     protected function setUp(): void
     {
         // Guard against other tests overwriting the global container
         if (!($GLOBALS['minty_app_container'] ?? null) instanceof AppContainer
-            || !($GLOBALS['minty_app_container'])->has(\MintyPHP\App\Module\ModuleRegistry::class)) {
+            || !($GLOBALS['minty_app_container'])->has(\MintyPHP\App\Module\ModuleRegistry::class)
+            || !($GLOBALS['minty_app_container'])->has(\MintyPHP\Service\Access\UiAccessService::class)) {
             $container = require dirname(__DIR__, 3) . '/lib/App/registerContainer.php';
+            $this->pushAppContainer($container);
             setAppContainer($container);
         }
     }
 
+    protected function tearDown(): void
+    {
+        $this->restoreAppContainer();
+    }
+
     public function testProviderReturnsAddressBookKey(): void
     {
         $provider = new AddressBookLayoutProvider();
@@ -38,8 +48,8 @@ final class LayoutContextProviderTest extends TestCase
 
         $result = $provider->provide($session, $container);
 
-        self::assertArrayHasKey('addressBook', $result);
-        $ab = $result['addressBook'];
+        self::assertArrayHasKey('addressbook.nav', $result);
+        $ab = $result['addressbook.nav'];
         self::assertArrayHasKey('url', $ab);
         self::assertArrayHasKey('activeSearch', $ab);
         self::assertArrayHasKey('activeTenants', $ab);
@@ -57,18 +67,17 @@ final class LayoutContextProviderTest extends TestCase
 
         $result = $provider->provide([], $container);
 
-        self::assertArrayHasKey('addressBook', $result);
-        self::assertSame([], $result['addressBook']['peopleGroups']);
+        self::assertArrayHasKey('addressbook.nav', $result);
+        self::assertSame([], $result['addressbook.nav']['peopleGroups']);
     }
 
     public function testProviderIsIncludedInLayoutNavWhenModuleActive(): void
     {
         // When the module is active, appBuildLayoutNavContext() should include
-        // addressBook via the provider loop
-        $layoutAuth = app(\MintyPHP\Service\Access\UiAccessService::class)->layoutCapabilities(0);
-        $layoutNav = appBuildLayoutNavContext($layoutAuth, [], []);
+        // addressbook.nav via the provider loop
+        $layoutNav = appBuildLayoutNavContext([], [], []);
 
-        self::assertArrayHasKey('addressBook', $layoutNav,
-            'addressBook key must be present in layoutNav when module is active');
+        self::assertArrayHasKey('addressbook.nav', $layoutNav,
+            'addressbook.nav key must be present in layoutNav when module is active');
     }
 }

tests/Unit/Module/LayoutNavProviderGuardTest.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace MintyPHP\Tests\Unit\Module;
+
+use MintyPHP\App\AppContainer;
+use MintyPHP\App\Module\Contracts\LayoutContextProvider;
+use MintyPHP\App\Module\ModuleRegistry;
+use MintyPHP\Tests\Support\AppContainerIsolationTrait;
+use PHPUnit\Framework\TestCase;
+
+final class LayoutNavProviderGuardTest extends TestCase
+{
+    use AppContainerIsolationTrait;
+
+    private string $fixturesDir = '';
+
+    protected function setUp(): void
+    {
+        $this->fixturesDir = sys_get_temp_dir() . '/layout-provider-guard-' . uniqid();
+        mkdir($this->fixturesDir, 0777, true);
+    }
+
+    protected function tearDown(): void
+    {
+        $this->removeDir($this->fixturesDir);
+        $this->restoreAppContainer();
+    }
+
+    public function testReservedLayoutKeyIsRejected(): void
+    {
+        $registry = $this->createRegistryWithProvider(DummyReservedLayoutProvider::class);
+        $container = new AppContainer();
+        $container->set(ModuleRegistry::class, static fn (): ModuleRegistry => $registry);
+        $this->pushAppContainer($container);
+
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage("must not override reserved layout key 'moduleSlots'");
+
+        appBuildLayoutNavContext([], [], []);
+    }
+
+    public function testNamespacedLayoutProviderKeyIsAccepted(): void
+    {
+        $registry = $this->createRegistryWithProvider(DummyNamespacedLayoutProvider::class);
+        $container = new AppContainer();
+        $container->set(ModuleRegistry::class, static fn (): ModuleRegistry => $registry);
+        $this->pushAppContainer($container);
+
+        $layoutNav = appBuildLayoutNavContext([], [], []);
+
+        self::assertSame('ok', $layoutNav['dummy.value'] ?? null);
+    }
+
+    private function createRegistryWithProvider(string $providerClass): ModuleRegistry
+    {
+        $moduleDir = $this->fixturesDir . '/dummy-module';
+        mkdir($moduleDir, 0777, true);
+        file_put_contents(
+            $moduleDir . '/module.php',
+            '<?php return ' . var_export([
+                'id' => 'dummy-module',
+                'layout_context_providers' => [$providerClass],
+            ], true) . ';'
+        );
+
+        return ModuleRegistry::boot($this->fixturesDir, ['dummy-module']);
+    }
+
+    private function removeDir(string $dir): void
+    {
+        if (!is_dir($dir)) {
+            return;
+        }
+
+        $items = new \RecursiveIteratorIterator(
+            new \RecursiveDirectoryIterator($dir, \FilesystemIterator::SKIP_DOTS),
+            \RecursiveIteratorIterator::CHILD_FIRST
+        );
+
+        foreach ($items as $item) {
+            if ($item->isDir()) {
+                rmdir($item->getPathname());
+            } else {
+                unlink($item->getPathname());
+            }
+        }
+
+        rmdir($dir);
+    }
+}
+
+final class DummyReservedLayoutProvider implements LayoutContextProvider
+{
+    public function provide(array $session, AppContainer $container): array
+    {
+        return [
+            'moduleSlots' => ['bad' => true],
+        ];
+    }
+}
+
+final class DummyNamespacedLayoutProvider implements LayoutContextProvider
+{
+    public function provide(array $session, AppContainer $container): array
+    {
+        return [
+            'dummy.value' => 'ok',
+        ];
+    }
+}

tests/Unit/Module/SearchProviderCollectionTest.php

@@ -5,6 +5,7 @@ namespace MintyPHP\Tests\Unit\Module;
 use MintyPHP\App\Module\ModuleRegistry;
 use MintyPHP\Module\AddressBook\Providers\AddressBookSearchProvider;
 use MintyPHP\Support\SearchConfig;
+use MintyPHP\Tests\Support\AppContainerIsolationTrait;
 use PHPUnit\Framework\TestCase;
 
 /**
@@ -12,18 +13,15 @@ use PHPUnit\Framework\TestCase;
  */
 final class SearchProviderCollectionTest extends TestCase
 {
-    private static ?\MintyPHP\App\AppContainer $originalContainer = null;
+    use AppContainerIsolationTrait;
 
     protected function setUp(): void
     {
-        // Guard against other tests overwriting the global container (e.g. ThemeResolutionTest)
-        if (self::$originalContainer === null) {
-            self::$originalContainer = $GLOBALS['minty_app_container'] ?? null;
-        }
         if (!($GLOBALS['minty_app_container'] ?? null) instanceof \MintyPHP\App\AppContainer
             || !($GLOBALS['minty_app_container'])->has(ModuleRegistry::class)) {
             // Restore the bootstrap container that has the module registry
             $container = require dirname(__DIR__, 3) . '/lib/App/registerContainer.php';
+            $this->pushAppContainer($container);
             setAppContainer($container);
         }
         SearchConfig::resetModuleProviders();
@@ -31,6 +29,7 @@ final class SearchProviderCollectionTest extends TestCase
 
     protected function tearDown(): void
     {
+        $this->restoreAppContainer();
         SearchConfig::resetModuleProviders();
     }
 

tests/Unit/Module/SessionProviderTest.php

@@ -0,0 +1,95 @@
+<?php
+
+namespace MintyPHP\Tests\Unit\Module;
+
+use MintyPHP\App\AppContainer;
+use MintyPHP\App\Module\Contracts\SessionProvider;
+use MintyPHP\Module\AddressBook\Providers\AddressBookSessionProvider;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @covers \MintyPHP\Module\AddressBook\Providers\AddressBookSessionProvider
+ */
+final class SessionProviderTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        $_SESSION = [];
+    }
+
+    protected function tearDown(): void
+    {
+        $_SESSION = [];
+    }
+
+    /**
+     * Create a real AppContainer that returns null for any get() call.
+     * AppContainer is final and cannot be mocked.
+     */
+    private function emptyContainer(): AppContainer
+    {
+        return new AppContainer();
+    }
+
+    public function testImplementsSessionProviderContract(): void
+    {
+        $provider = new AddressBookSessionProvider();
+        self::assertInstanceOf(SessionProvider::class, $provider);
+    }
+
+    public function testPopulateWithInvalidUserClearsSessionKey(): void
+    {
+        $_SESSION['available_departments_by_tenant'] = [['tenant' => 'old']];
+
+        $provider = new AddressBookSessionProvider();
+        $provider->populate(['id' => 0], $this->emptyContainer());
+
+        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+    }
+
+    public function testPopulateWithMissingUserIdClearsSessionKey(): void
+    {
+        $_SESSION['available_departments_by_tenant'] = [['tenant' => 'old']];
+
+        $provider = new AddressBookSessionProvider();
+        $provider->populate([], $this->emptyContainer());
+
+        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+    }
+
+    public function testPopulateReturnsEarlyWhenContainerMissesDependencies(): void
+    {
+        $provider = new AddressBookSessionProvider();
+        // Container has no bindings → get() will throw, but provider guards with instanceof check
+        // The provider should handle this gracefully (no session key set)
+        try {
+            $provider->populate(['id' => 42], $this->emptyContainer());
+        } catch (\Throwable) {
+            // Provider may throw if container has no binding — that's acceptable;
+            // in production, bindings are always registered before providers run.
+        }
+
+        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+    }
+
+    public function testClearRemovesSessionKey(): void
+    {
+        $_SESSION['available_departments_by_tenant'] = [
+            ['tenant' => ['uuid' => 'abc'], 'departments' => []],
+        ];
+
+        $provider = new AddressBookSessionProvider();
+        $provider->clear();
+
+        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+    }
+
+    public function testClearIsIdempotent(): void
+    {
+        // Key doesn't exist — clear() should not throw
+        $provider = new AddressBookSessionProvider();
+        $provider->clear();
+
+        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+    }
+}