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>
2026-03-18 22:19:56 +01:00
parent c364e2b46d
commit c7b8fd516a
139 changed files with 7591 additions and 2535 deletions
--- a/tests/App/AppContainerTest.php
+++ b/tests/App/AppContainerTest.php
@@ -0,0 +1,40 @@
+<?php
+
+namespace MintyPHP\Tests\App;
+
+use MintyPHP\App\AppContainer;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+final class AppContainerTest extends TestCase
+{
+    public function testOverwritingBindingIsAllowedBeforeProtection(): void
+    {
+        $container = new AppContainer();
+        $container->set('service.test', static fn (): string => 'first');
+        $container->set('service.test', static fn (): string => 'second');
+
+        self::assertSame('second', $container->get('service.test'));
+    }
+
+    public function testOverwritingExistingBindingIsBlockedAfterProtection(): void
+    {
+        $container = new AppContainer();
+        $container->set('service.test', static fn (): string => 'first');
+        $container->protectExistingBindings();
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('Refusing to overwrite existing service binding: service.test');
+        $container->set('service.test', static fn (): string => 'second');
+    }
+
+    public function testAddingNewBindingStillWorksAfterProtection(): void
+    {
+        $container = new AppContainer();
+        $container->set('service.first', static fn (): string => 'first');
+        $container->protectExistingBindings();
+        $container->set('service.second', static fn (): string => 'second');
+
+        self::assertSame('second', $container->get('service.second'));
+    }
+}
--- a/tests/App/Module/ModuleManifestTest.php
+++ b/tests/App/Module/ModuleManifestTest.php
@@ -35,10 +35,32 @@ final class ModuleManifestTest extends TestCase
            'ui_slots' => ['aside.tab_panel' => [['key' => 'people', 'label' => 'People']]],
            'search_resources' => ['App\\SearchProvider'],
            'asset_groups' => ['address-book' => ['css/view.css']],
-            'scheduler_jobs' => [],
+            'scheduler_jobs' => [
+                [
+                    'job_key' => 'addressbook.sync',
+                    'handler' => 'App\\Scheduler\\AddressBookSyncHandler',
+                    'label' => 'Address book sync',
+                    'description' => 'Syncs address data',
+                    'default_enabled' => true,
+                    'default_timezone' => 'Europe/Berlin',
+                    'default_schedule_type' => 'daily',
+                    'default_schedule_interval' => 1,
+                    'default_schedule_time' => '02:00',
+                    'default_schedule_weekdays_csv' => null,
+                    'default_catchup_once' => true,
+                    'allowed_schedule_types' => ['daily', 'weekly'],
+                ],
+            ],
            'layout_context_providers' => ['App\\LayoutProvider'],
            'session_providers' => ['App\\SessionProvider'],
-            'permissions' => ['address_book.view'],
+            'permissions' => [
+                [
+                    'key' => 'address_book.view',
+                    'description' => 'Can view address book',
+                    'active' => true,
+                    'is_system' => true,
+                ],
+            ],
            'migrations_path' => 'db/updates',
        ];

@@ -49,7 +71,13 @@ final class ModuleManifestTest extends TestCase
        self::assertTrue($manifest->enabledByDefault);
        self::assertSame(10, $manifest->loadOrder);
        self::assertCount(1, $manifest->routes);
-        self::assertSame(['address_book.view'], $manifest->permissions);
+        self::assertSame([[
+            'key' => 'address_book.view',
+            'description' => 'Can view address book',
+            'active' => 1,
+            'is_system' => 1,
+        ]], $manifest->permissions);
+        self::assertSame('addressbook.sync', $manifest->schedulerJobs[0]['job_key']);
        self::assertSame('/srv/modules/addressbook/db/updates', $manifest->migrationsPath);
        self::assertSame(['App\\LayoutProvider'], $manifest->layoutContextProviders);
        self::assertSame(['App\\SessionProvider'], $manifest->sessionProviders);
@@ -69,4 +97,38 @@ final class ModuleManifestTest extends TestCase

        ModuleManifest::fromArray(['id' => '  '], '/tmp/modules/broken');
    }
+
+    public function testInvalidPermissionContractThrows(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("must define non-empty 'key' and 'description'");
+
+        ModuleManifest::fromArray([
+            'id' => 'mod-invalid-perm',
+            'permissions' => [['key' => 'mod.permission']],
+        ], '/tmp/modules/mod-invalid-perm');
+    }
+
+    public function testInvalidSchedulerJobContractThrows(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("missing required key 'allowed_schedule_types'");
+
+        ModuleManifest::fromArray([
+            'id' => 'mod-invalid-job',
+            'scheduler_jobs' => [[
+                'job_key' => 'mod.job',
+                'handler' => 'App\\Handler',
+                'label' => 'Label',
+                'description' => 'Desc',
+                'default_enabled' => true,
+                'default_timezone' => 'UTC',
+                'default_schedule_type' => 'daily',
+                'default_schedule_interval' => 1,
+                'default_schedule_time' => '01:00',
+                'default_schedule_weekdays_csv' => null,
+                'default_catchup_once' => true,
+            ]],
+        ], '/tmp/modules/mod-invalid-job');
+    }
 }
--- a/tests/App/Module/ModulePermissionSynchronizerTest.php
+++ b/tests/App/Module/ModulePermissionSynchronizerTest.php
@@ -0,0 +1,181 @@
+<?php
+
+namespace MintyPHP\Tests\App\Module;
+
+use MintyPHP\App\Module\ModulePermissionSynchronizer;
+use MintyPHP\App\Module\ModuleRegistry;
+use MintyPHP\Repository\Access\PermissionRepositoryInterface;
+use PHPUnit\Framework\TestCase;
+
+final class ModulePermissionSynchronizerTest extends TestCase
+{
+    private string $fixturesDir = '';
+
+    protected function setUp(): void
+    {
+        $this->fixturesDir = sys_get_temp_dir() . '/module-permission-sync-' . uniqid();
+        mkdir($this->fixturesDir, 0777, true);
+    }
+
+    protected function tearDown(): void
+    {
+        $this->removeDir($this->fixturesDir);
+    }
+
+    public function testSyncCreatesPermissionAndIsIdempotent(): void
+    {
+        $registry = $this->createRegistryWithPermissions([[
+            'key' => 'address_book.view',
+            'description' => 'Can view address book',
+            'active' => 1,
+            'is_system' => 1,
+        ]]);
+
+        $repository = new InMemoryPermissionRepository();
+        $synchronizer = new ModulePermissionSynchronizer($registry, $repository);
+
+        $first = $synchronizer->sync();
+        self::assertSame(1, $first['created']);
+        self::assertSame(0, $first['updated']);
+        self::assertSame(0, $first['unchanged']);
+
+        $second = $synchronizer->sync();
+        self::assertSame(0, $second['created']);
+        self::assertSame(0, $second['updated']);
+        self::assertSame(1, $second['unchanged']);
+    }
+
+    public function testSyncUpdatesExistingPermissionWhenDefinitionChanged(): void
+    {
+        $registry = $this->createRegistryWithPermissions([[
+            'key' => 'address_book.view',
+            'description' => 'Can view address book',
+            'active' => 1,
+            'is_system' => 1,
+        ]]);
+
+        $repository = new InMemoryPermissionRepository();
+        $repository->create([
+            'key' => 'address_book.view',
+            'description' => 'Old description',
+            'active' => 0,
+            'is_system' => 0,
+        ]);
+
+        $synchronizer = new ModulePermissionSynchronizer($registry, $repository);
+        $result = $synchronizer->sync();
+
+        self::assertSame(0, $result['created']);
+        self::assertSame(1, $result['updated']);
+        self::assertSame(0, $result['unchanged']);
+
+        $permission = $repository->findByKey('address_book.view');
+        self::assertSame('Can view address book', $permission['description'] ?? null);
+        self::assertSame(1, (int) ($permission['active'] ?? 0));
+        self::assertSame(1, (int) ($permission['is_system'] ?? 0));
+    }
+
+    /**
+     * @param list<array{key: string, description: string, active: int, is_system: int}> $permissions
+     */
+    private function createRegistryWithPermissions(array $permissions): ModuleRegistry
+    {
+        mkdir($this->fixturesDir . '/mod-perm', 0777, true);
+        file_put_contents(
+            $this->fixturesDir . '/mod-perm/module.php',
+            '<?php return ' . var_export([
+                'id' => 'mod-perm',
+                'permissions' => $permissions,
+            ], true) . ';'
+        );
+
+        return ModuleRegistry::boot($this->fixturesDir, ['mod-perm']);
+    }
+
+    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 InMemoryPermissionRepository implements PermissionRepositoryInterface
+{
+    /** @var array<int, array<string, mixed>> */
+    private array $rows = [];
+    private int $nextId = 1;
+
+    public function list(): array
+    {
+        return array_values($this->rows);
+    }
+
+    public function listActive(): array
+    {
+        return array_values(array_filter($this->rows, static fn (array $row): bool => (int) ($row['active'] ?? 0) === 1));
+    }
+
+    public function listPaged(array $options): array
+    {
+        return ['rows' => $this->list(), 'total' => count($this->rows)];
+    }
+
+    public function find(int $id): ?array
+    {
+        return $this->rows[$id] ?? null;
+    }
+
+    public function findByKey(string $key): ?array
+    {
+        foreach ($this->rows as $row) {
+            if ((string) ($row['key'] ?? '') === $key) {
+                return $row;
+            }
+        }
+        return null;
+    }
+
+    public function create(array $data): ?int
+    {
+        $id = $this->nextId++;
+        $this->rows[$id] = [
+            'id' => $id,
+            'key' => (string) ($data['key'] ?? ''),
+            'description' => (string) ($data['description'] ?? ''),
+            'active' => (int) ($data['active'] ?? 1),
+            'is_system' => (int) ($data['is_system'] ?? 1),
+        ];
+        return $id;
+    }
+
+    public function update(int $id, array $data): bool
+    {
+        if (!isset($this->rows[$id])) {
+            return false;
+        }
+        $this->rows[$id]['key'] = (string) ($data['key'] ?? $this->rows[$id]['key']);
+        $this->rows[$id]['description'] = (string) ($data['description'] ?? $this->rows[$id]['description']);
+        $this->rows[$id]['active'] = (int) ($data['active'] ?? $this->rows[$id]['active']);
+        $this->rows[$id]['is_system'] = (int) ($data['is_system'] ?? $this->rows[$id]['is_system']);
+        return true;
+    }
+
+    public function delete(int $id): bool
+    {
+        unset($this->rows[$id]);
+        return true;
+    }
+}
--- a/tests/App/Module/ModuleRegistryTest.php
+++ b/tests/App/Module/ModuleRegistryTest.php
@@ -43,7 +43,10 @@ final class ModuleRegistryTest extends TestCase
            'id' => 'testmod',
            'version' => '1.0.0',
            'load_order' => 10,
-            'permissions' => ['test.view', 'test.edit'],
+            'permissions' => [
+                ['key' => 'test.view', 'description' => 'Test view'],
+                ['key' => 'test.edit', 'description' => 'Test edit'],
+            ],
            'search_resources' => [],
        ]);

@@ -51,7 +54,7 @@ final class ModuleRegistryTest extends TestCase

        self::assertTrue($registry->hasModule('testmod'));
        self::assertSame('1.0.0', $registry->getModule('testmod')->version);
-        self::assertSame(['test.view', 'test.edit'], $registry->getPermissions());
+        self::assertSame(['test.view', 'test.edit'], $registry->getPermissionKeys());
    }

    public function testDeterministicOrdering(): void
@@ -80,8 +83,16 @@ final class ModuleRegistryTest extends TestCase

    public function testPermissionConflictThrows(): void
    {
-        $this->createModuleManifest('mod-a', ['id' => 'mod-a', 'load_order' => 1, 'permissions' => ['shared.perm']]);
-        $this->createModuleManifest('mod-b', ['id' => 'mod-b', 'load_order' => 2, 'permissions' => ['shared.perm']]);
+        $this->createModuleManifest('mod-a', [
+            'id' => 'mod-a',
+            'load_order' => 1,
+            'permissions' => [['key' => 'shared.perm', 'description' => 'Shared permission']],
+        ]);
+        $this->createModuleManifest('mod-b', [
+            'id' => 'mod-b',
+            'load_order' => 2,
+            'permissions' => [['key' => 'shared.perm', 'description' => 'Shared permission duplicate']],
+        ]);

        $this->expectException(RuntimeException::class);
        $this->expectExceptionMessage("Permission conflict: 'shared.perm'");
@@ -108,6 +119,137 @@ final class ModuleRegistryTest extends TestCase
        ModuleRegistry::boot($this->fixturesDir, ['mod-a', 'mod-b']);
    }

+    public function testRoutePathConflictThrows(): void
+    {
+        $this->createModuleManifest('mod-a', [
+            'id' => 'mod-a',
+            'load_order' => 1,
+            'routes' => [['path' => '/shared-path', 'target' => 'a/index']],
+        ]);
+        $this->createModuleManifest('mod-b', [
+            'id' => 'mod-b',
+            'load_order' => 2,
+            'routes' => [['path' => '/shared-path', 'target' => 'b/index']],
+        ]);
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('Route path conflict');
+
+        ModuleRegistry::boot($this->fixturesDir, ['mod-a', 'mod-b']);
+    }
+
+    public function testUiSlotConflictThrows(): void
+    {
+        $panelTemplateA = $this->createFixtureFile('mod-a-panel.phtml', '<ul></ul>');
+        $panelTemplateB = $this->createFixtureFile('mod-b-panel.phtml', '<ul></ul>');
+
+        $this->createModuleManifest('mod-a', [
+            'id' => 'mod-a',
+            'load_order' => 1,
+            'ui_slots' => [
+                'aside.tab_panel' => [
+                    [
+                        'key' => 'people',
+                        'label' => 'People',
+                        'icon' => 'bi-people',
+                        'permission' => 'can_view_people',
+                        'panel_template' => $panelTemplateA,
+                    ],
+                ],
+            ],
+        ]);
+        $this->createModuleManifest('mod-b', [
+            'id' => 'mod-b',
+            'load_order' => 2,
+            'ui_slots' => [
+                'aside.tab_panel' => [
+                    [
+                        'key' => 'people',
+                        'label' => 'People B',
+                        'icon' => 'bi-people',
+                        'permission' => 'can_view_people',
+                        'panel_template' => $panelTemplateB,
+                    ],
+                ],
+            ],
+        ]);
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage("UI slot conflict: slot 'aside.tab_panel' key 'people'");
+
+        ModuleRegistry::boot($this->fixturesDir, ['mod-a', 'mod-b']);
+    }
+
+    public function testInvalidRouteContractThrows(): void
+    {
+        $this->createModuleManifest('mod-a', [
+            'id' => 'mod-a',
+            'routes' => [['path' => '', 'target' => 'address-book/index']],
+        ]);
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage("must define non-empty 'path' and 'target'");
+
+        ModuleRegistry::boot($this->fixturesDir, ['mod-a']);
+    }
+
+    public function testInvalidUiSlotContractThrows(): void
+    {
+        $this->createModuleManifest('mod-a', [
+            'id' => 'mod-a',
+            'ui_slots' => [
+                'aside.tab_panel' => [
+                    ['label' => 'Missing Key'],
+                ],
+            ],
+        ]);
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage("must define a non-empty 'key'");
+
+        ModuleRegistry::boot($this->fixturesDir, ['mod-a']);
+    }
+
+    public function testUiSlotsAreSortedDeterministicallyByOrderModuleAndKey(): void
+    {
+        $this->createModuleManifest('mod-z', [
+            'id' => 'mod-z',
+            'load_order' => 1,
+            'ui_slots' => [
+                'search.resource_item' => [
+                    ['key' => 'z-second', 'label' => 'Z Second', 'base_url' => 'z-second', 'permission' => 'can.z', 'order' => 20],
+                    ['key' => 'z-first', 'label' => 'Z First', 'base_url' => 'z-first', 'permission' => 'can.z', 'order' => 20],
+                ],
+            ],
+        ]);
+        $this->createModuleManifest('mod-a', [
+            'id' => 'mod-a',
+            'load_order' => 1,
+            'ui_slots' => [
+                'search.resource_item' => [
+                    ['key' => 'a-mid', 'label' => 'A Mid', 'base_url' => 'a-mid', 'permission' => 'can.a', 'order' => 20],
+                ],
+            ],
+        ]);
+        $this->createModuleManifest('mod-b', [
+            'id' => 'mod-b',
+            'load_order' => 1,
+            'ui_slots' => [
+                'search.resource_item' => [
+                    ['key' => 'b-low', 'label' => 'B Low', 'base_url' => 'b-low', 'permission' => 'can.b', 'order' => 10],
+                ],
+            ],
+        ]);
+
+        $registry = ModuleRegistry::boot($this->fixturesDir, ['mod-z', 'mod-b', 'mod-a']);
+        $slotItems = $registry->getSlotContributions('search.resource_item');
+
+        self::assertSame(['b-low', 'a-mid', 'z-first', 'z-second'], array_column($slotItems, 'key'));
+        foreach ($slotItems as $slotItem) {
+            self::assertArrayNotHasKey('__module_id', $slotItem);
+        }
+    }
+
    public function testMissingManifestFileThrows(): void
    {
        $this->expectException(RuntimeException::class);
@@ -126,16 +268,21 @@ final class ModuleRegistryTest extends TestCase
        ModuleRegistry::boot($this->fixturesDir, ['wrongdir']);
    }

-    public function testResolveEnabledModulesFromConfig(): void
+    public function testResolveEnabledModulesFromConfigWhenEnvUnset(): void
    {
-        $result = ModuleRegistry::resolveEnabledModules([
-            'enabled_modules' => ['mod-a', 'mod-b'],
-        ]);
+        putenv('APP_ENABLED_MODULES');
+        try {
+            $result = ModuleRegistry::resolveEnabledModules([
+                'enabled_modules' => ['mod-a', 'mod-b'],
+            ]);

-        self::assertSame(['mod-a', 'mod-b'], $result);
+            self::assertSame(['mod-a', 'mod-b'], $result);
+        } finally {
+            putenv('APP_ENABLED_MODULES');
+        }
    }

-    public function testResolveEnabledModulesFromEnv(): void
+    public function testResolveEnabledModulesFromEnvList(): void
    {
        putenv('APP_ENABLED_MODULES=env-a,env-b');

@@ -149,13 +296,32 @@ final class ModuleRegistryTest extends TestCase
        }
    }

+    public function testResolveEnabledModulesFromEmptyEnvReturnsNoModules(): void
+    {
+        putenv('APP_ENABLED_MODULES=');
+
+        try {
+            $result = ModuleRegistry::resolveEnabledModules([
+                'enabled_modules' => ['config-a', 'config-b'],
+            ]);
+            self::assertSame([], $result);
+        } finally {
+            putenv('APP_ENABLED_MODULES');
+        }
+    }
+
    public function testResolveEnabledModulesDeduplicates(): void
    {
-        $result = ModuleRegistry::resolveEnabledModules([
-            'enabled_modules' => ['mod-a', 'mod-a', 'mod-b'],
-        ]);
+        putenv('APP_ENABLED_MODULES');
+        try {
+            $result = ModuleRegistry::resolveEnabledModules([
+                'enabled_modules' => ['mod-a', 'mod-a', 'mod-b'],
+            ]);

-        self::assertSame(['mod-a', 'mod-b'], $result);
+            self::assertSame(['mod-a', 'mod-b'], $result);
+        } finally {
+            putenv('APP_ENABLED_MODULES');
+        }
    }

    public function testGetNonExistentModuleThrows(): void
@@ -212,6 +378,17 @@ final class ModuleRegistryTest extends TestCase
        );
    }

+    private function createFixtureFile(string $relativePath, string $content): string
+    {
+        $path = $this->fixturesDir . '/' . ltrim($relativePath, '/');
+        $dir = dirname($path);
+        if (!is_dir($dir)) {
+            mkdir($dir, 0777, true);
+        }
+        file_put_contents($path, $content);
+        return $path;
+    }
+
    private function removeDir(string $dir): void
    {
        if (!is_dir($dir)) {
--- a/tests/App/Module/ModuleRuntimeAssetPublisherTest.php
+++ b/tests/App/Module/ModuleRuntimeAssetPublisherTest.php
@@ -0,0 +1,142 @@
+<?php
+
+namespace MintyPHP\Tests\App\Module;
+
+use MintyPHP\App\Module\ModuleManifest;
+use MintyPHP\App\Module\ModuleRuntimeAssetPublisher;
+use PHPUnit\Framework\TestCase;
+
+final class ModuleRuntimeAssetPublisherTest extends TestCase
+{
+    private string $tmpDir;
+
+    protected function setUp(): void
+    {
+        $this->tmpDir = sys_get_temp_dir() . '/corecore-module-assets-test-' . uniqid();
+        mkdir($this->tmpDir, 0777, true);
+    }
+
+    protected function tearDown(): void
+    {
+        $this->removePath($this->tmpDir);
+    }
+
+    public function testPublishSymlinkCreatesManagedModuleLinksAndRemovesStaleEntries(): void
+    {
+        if (!function_exists('symlink')) {
+            self::markTestSkipped('Symlink support is required for this test.');
+        }
+
+        $moduleA = $this->createModuleWithWebAssets('module-a', ['js/a.js' => 'console.log("a");']);
+        $moduleB = $this->createModuleWithoutWebAssets('module-b');
+        $runtimeModulesDir = $this->tmpDir . '/web/modules';
+        mkdir($runtimeModulesDir, 0777, true);
+        file_put_contents($runtimeModulesDir . '/stale.txt', 'old');
+
+        $publisher = new ModuleRuntimeAssetPublisher();
+        $result = $publisher->publish($runtimeModulesDir, [
+            'module-a' => $moduleA,
+            'module-b' => $moduleB,
+        ], 'symlink');
+
+        self::assertTrue(is_link($runtimeModulesDir . '/module-a'));
+        self::assertSame(
+            realpath($this->tmpDir . '/modules/module-a/web'),
+            realpath($runtimeModulesDir . '/module-a')
+        );
+        self::assertFileDoesNotExist($runtimeModulesDir . '/module-b');
+        self::assertFileDoesNotExist($runtimeModulesDir . '/stale.txt');
+        self::assertSame(1, $result['created']);
+        self::assertSame(1, $result['removed']);
+    }
+
+    public function testPublishSymlinkUpdatesWrongExistingLink(): void
+    {
+        if (!function_exists('symlink')) {
+            self::markTestSkipped('Symlink support is required for this test.');
+        }
+
+        $moduleA = $this->createModuleWithWebAssets('module-a', ['css/a.css' => '.a{}']);
+        $runtimeModulesDir = $this->tmpDir . '/web/modules';
+        mkdir($runtimeModulesDir, 0777, true);
+
+        $wrongTarget = $this->tmpDir . '/wrong-target';
+        mkdir($wrongTarget, 0777, true);
+        symlink($wrongTarget, $runtimeModulesDir . '/module-a');
+
+        $publisher = new ModuleRuntimeAssetPublisher();
+        $result = $publisher->publish($runtimeModulesDir, ['module-a' => $moduleA], 'symlink');
+
+        self::assertTrue(is_link($runtimeModulesDir . '/module-a'));
+        self::assertSame(
+            realpath($this->tmpDir . '/modules/module-a/web'),
+            realpath($runtimeModulesDir . '/module-a')
+        );
+        self::assertSame(1, $result['updated']);
+    }
+
+    public function testPublishCopyModeCopiesModuleAssets(): void
+    {
+        $moduleA = $this->createModuleWithWebAssets('module-a', [
+            'js/app.js' => 'console.log("copy-mode");',
+            'css/app.css' => '.copy-mode{}',
+        ]);
+        $runtimeModulesDir = $this->tmpDir . '/web/modules';
+
+        $publisher = new ModuleRuntimeAssetPublisher();
+        $result = $publisher->publish($runtimeModulesDir, ['module-a' => $moduleA], 'copy');
+
+        self::assertDirectoryExists($runtimeModulesDir . '/module-a');
+        self::assertFalse(is_link($runtimeModulesDir . '/module-a'));
+        self::assertFileExists($runtimeModulesDir . '/module-a/js/app.js');
+        self::assertFileExists($runtimeModulesDir . '/module-a/css/app.css');
+        self::assertSame(1, $result['created']);
+    }
+
+    private function createModuleWithWebAssets(string $id, array $files): ModuleManifest
+    {
+        $moduleDir = $this->tmpDir . '/modules/' . $id;
+        mkdir($moduleDir . '/web', 0777, true);
+        foreach ($files as $relativePath => $content) {
+            $target = $moduleDir . '/web/' . ltrim($relativePath, '/');
+            $targetDir = dirname($target);
+            if (!is_dir($targetDir)) {
+                mkdir($targetDir, 0777, true);
+            }
+            file_put_contents($target, $content);
+        }
+
+        return ModuleManifest::fromArray(['id' => $id], $moduleDir);
+    }
+
+    private function createModuleWithoutWebAssets(string $id): ModuleManifest
+    {
+        $moduleDir = $this->tmpDir . '/modules/' . $id;
+        mkdir($moduleDir, 0777, true);
+        return ModuleManifest::fromArray(['id' => $id], $moduleDir);
+    }
+
+    private function removePath(string $path): void
+    {
+        if (!file_exists($path) && !is_link($path)) {
+            return;
+        }
+        if (is_link($path) || is_file($path)) {
+            @unlink($path);
+            return;
+        }
+        if (!is_dir($path)) {
+            return;
+        }
+        $entries = scandir($path);
+        if ($entries !== false) {
+            foreach ($entries as $entry) {
+                if ($entry === '.' || $entry === '..') {
+                    continue;
+                }
+                $this->removePath($path . '/' . $entry);
+            }
+        }
+        @rmdir($path);
+    }
+}
--- a/tests/App/Module/RouterConfigCollisionTest.php
+++ b/tests/App/Module/RouterConfigCollisionTest.php
@@ -0,0 +1,55 @@
+<?php
+
+namespace MintyPHP\Tests\App\Module;
+
+use MintyPHP\App\AppContainer;
+use MintyPHP\App\Module\ModuleRegistry;
+use MintyPHP\Tests\Support\AppContainerIsolationTrait;
+use PHPUnit\Framework\TestCase;
+
+final class RouterConfigCollisionTest extends TestCase
+{
+    use AppContainerIsolationTrait;
+
+    /**
+     * @runInSeparateProcess
+     */
+    public function testModuleRoutePathCollidingWithCoreRouteThrows(): void
+    {
+        $fixturesDir = sys_get_temp_dir() . '/router-config-collision-' . uniqid();
+        mkdir($fixturesDir . '/mod-a', 0777, true);
+        file_put_contents(
+            $fixturesDir . '/mod-a/module.php',
+            '<?php return ' . var_export([
+                'id' => 'mod-a',
+                'routes' => [
+                    ['path' => 'login', 'target' => 'mod-a/login'],
+                ],
+            ], true) . ';'
+        );
+
+        try {
+            $registry = ModuleRegistry::boot($fixturesDir, ['mod-a']);
+
+            $container = new AppContainer();
+            $container->set(ModuleRegistry::class, static fn (): ModuleRegistry => $registry);
+            $this->pushAppContainer($container);
+
+            if (!defined('APP_ROUTE_DEFINITIONS')) {
+                define('APP_ROUTE_DEFINITIONS', [
+                    ['path' => 'login', 'target' => 'auth/login'],
+                ]);
+            }
+
+            $this->expectException(\RuntimeException::class);
+            $this->expectExceptionMessage('Module route path conflict');
+
+            require dirname(__DIR__, 3) . '/config/router.php';
+        } finally {
+            $this->restoreAppContainer();
+            @unlink($fixturesDir . '/mod-a/module.php');
+            @rmdir($fixturesDir . '/mod-a');
+            @rmdir($fixturesDir);
+        }
+    }
+}