feat!: add framework-aware file copying for multi-framework module support

[roble]

Summary

• Reads frontend.json at project root to determine the selected framework (vue, react, etc.)
• After install/update, copies files from resources/js/{framework}/ flat into resources/js/ and removes all framework subdirs
• Hard-fails with a clear error if the module does not support the requested framework (missing subdir)
• Silently skips when: no resources/js/ (PHP-only module), no frontend.json, or dev: true in frontend.json
• Dev mode guard preserves framework subdirs so contributor-mode page resolution still works

Breaking change

copyFrameworkFiles() throws RuntimeException when a module has resources/js/ but lacks the selected framework subdir — any vue-only module installed with "framework":"react" will now hard-fail on install.

Test plan

• 11 new PHPUnit tests pass (vendor/bin/phpunit)
• Integration scenarios A–E pass (../test-module-installer/run-scenarios.sh)
• CI php.yml green on this PR

[Copilot]

Pull request overview

Adds framework-aware post-install/update file handling to the module installer. After a module is installed or updated, the installer reads frontend.json from the project root, picks the configured framework (vue/react/...), copies that subdirectory's contents flat into resources/js/, and removes the framework subdirs. Modules whose resources/js/ lacks the requested framework subdir hard-fail with a RuntimeException.

Changes:

• New getSelectedFramework() / getFrontendJsonPath() reading the project's frontend.json (with dev-mode and missing-file silent skips).
• New copyFrameworkFiles() (+ copyDirectory() helper) wired into both install() and update().
• New parentInstall() indirection plus 11 PHPUnit tests covering the new behavior via a TestableInstaller extension.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
src/Installer.php	Adds frontend.json reader, framework-flatten logic, parent-install proxy, and hooks them into install/update flows
tests/ModuleInstallerTest.php	Extends TestableInstaller with hooks, adds 11 tests for getSelectedFramework, copyFrameworkFiles, and install integration

Comments suppressed due to low confidence (2)

src/Installer.php:498

• The 3-way merge update strategy is broken by the new framework-flattening step. copyFrameworkFiles($target) is invoked on the freshly-downloaded installPath but is NOT applied to $basePath (the "original" version downloaded into a temp dir). When mergeStash() then iterates the stash (which is the user's previously-installed copy — already flattened, so files live at e.g. app.ts), it computes baseFile = $base.'/app.ts'. Because base was never flattened, that file actually lives at $base/vue/app.ts, so ! file_exists($baseFile) is true and every file is misclassified as "user-added" — meaning the user's old copy is unconditionally written over the new upstream version, silently losing all upstream changes during a merge update. copyFrameworkFiles() (or an equivalent flattening pass) must be applied to $basePath as well so the 3-way merge sees a consistent flattened tree on all three sides.

                    $this->removeExcludedDirectories($target);
                    $this->copyFrameworkFiles($target);
                    if ($basePath !== null) {
                        // Merge strategy: apply 3-way merge then clean up base temp dir
                        $this->mergeStash($stashPath, $basePath, $installPath);
                        (new Filesystem)->removeDirectory($basePath);

tests/ModuleInstallerTest.php:836

• Tests use fixed path names directly under sys_get_temp_dir() based only on the package short-name (vue-only, flatten-test, no-js, skip-module). If a previous test run failed and left these directories behind, or if two CI jobs share a temp dir, the tests will produce confusing failures or false passes. They also do not use tearDown() so any exception before the cleanup line leaks the directory. Consider including uniqid() in the package name (or wrapping each test in try/finally cleanup using a unique base dir like the helper used elsewhere in this file).

    public function test_copy_framework_files_hard_fails_when_framework_subdir_missing(): void
    {
        $baseDir = sys_get_temp_dir();
        // Package 'saucebase/vue-only' → module dir 'vue-only' → install path = $baseDir/vue-only
        $moduleDir = $baseDir.'/vue-only';
        mkdir($moduleDir.'/resources/js', 0755, true);

        $installer = $this->makeInstallerWithModuleDir($baseDir);
        $installer->setFrontendJsonPath($this->writeFrontendJson(['framework' => 'react']));

        $pkg = new Package('saucebase/vue-only', '1.0.0.0', '1.0.0');

        $this->expectException(\RuntimeException::class);
        $this->expectExceptionMessageMatches('/does not support react/');

        try {
            $installer->callCopyFrameworkFiles($pkg);
        } finally {
            (new Filesystem)->remove($moduleDir);
        }
    }

    public function test_copy_framework_files_flattens_files_and_removes_framework_subdirs(): void
    {
        $baseDir = sys_get_temp_dir();
        // Package 'saucebase/flatten-test' → module dir 'flatten-test' → install path = $baseDir/flatten-test
        $moduleDir = $baseDir.'/flatten-test';
        $jsRoot = $moduleDir.'/resources/js';
        mkdir($jsRoot.'/vue/pages', 0755, true);
        mkdir($jsRoot.'/react', 0755, true);
        file_put_contents($jsRoot.'/vue/app.ts', 'vue app');
        file_put_contents($jsRoot.'/vue/pages/Login.vue', 'login page');
        file_put_contents($jsRoot.'/react/app.tsx', 'react app');

        $installer = $this->makeInstallerWithModuleDir($baseDir);
        $installer->setFrontendJsonPath($this->writeFrontendJson(['framework' => 'vue']));

        $pkg = new Package('saucebase/flatten-test', '1.0.0.0', '1.0.0');

        $installer->callCopyFrameworkFiles($pkg);

        $this->assertFileExists($jsRoot.'/app.ts');
        $this->assertSame('vue app', file_get_contents($jsRoot.'/app.ts'));
        $this->assertFileExists($jsRoot.'/pages/Login.vue');
        $this->assertDirectoryDoesNotExist($jsRoot.'/vue');
        $this->assertDirectoryDoesNotExist($jsRoot.'/react');

        (new Filesystem)->remove($moduleDir);
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.