diff --git a/docs/consultations/gemini-blueprint-confyml-2026-04-06.md b/docs/consultations/gemini-blueprint-confyml-2026-04-06.md new file mode 100644 index 0000000..69ee352 --- /dev/null +++ b/docs/consultations/gemini-blueprint-confyml-2026-04-06.md @@ -0,0 +1,107 @@ +# Gemini Consultation: Blueprint conf.yml Configuration + +**Date:** April 6, 2026 +**Chronicler:** #63 +**Task:** #26 ModpackChecker Phase 5 Deployment + +--- + +## The Question + +We were getting a Blueprint build error: +``` +FATAL: Extension configuration points towards one or more files that do not exist. +``` + +Our `conf.yml` was pointing to: +- `data.directory: "modpackchecker"` (folder didn't exist) +- `dashboard.wrapper: "views/server/wrapper.tsx"` (TSX not supported in wrapper field) + +--- + +## Gemini's Response + +### Root Causes + +1. **`data.directory: "modpackchecker"`** — Points to a folder that doesn't exist. If you don't have default data/config files to push to storage, this must be empty. + +2. **`dashboard.wrapper: "views/server/wrapper.tsx"`** — Blueprint's native `wrapper` field is hardcoded to expect `.blade.php` files. TSX components must be injected via `build.sh` using sed. + +### The Architecture Fix + +Use `requests.app: "app"` to properly inject PHP classes. Blueprint merges the `app/` folder directly into Pterodactyl's `app/` directory, which means PSR-4 autoloading works automatically. + +**Correct structure:** +``` +.blueprint/dev/ +├── app/ +│ ├── Console/ +│ │ └── Commands/ +│ │ └── CheckModpackUpdates.php +│ └── Http/ +│ └── Controllers/ +│ └── ModpackAPIController.php +├── admin/ +├── build.sh +├── conf.yml +├── database/ +├── routes/ +└── views/ +``` + +### Working conf.yml + +```yaml +info: + name: "ModpackChecker" + identifier: "modpackchecker" + description: "4-platform modpack version checker" + flags: "" + version: "1.0.0" + target: "beta-2026-01" + author: "Firefrost Gaming " + icon: "" + website: "https://firefrostgaming.com" +admin: + view: "admin/view.blade.php" + controller: "admin/controller.php" + css: "" + wrapper: "" +dashboard: + css: "" + wrapper: "" # Empty! TSX not supported here + components: "" +data: + directory: "" # Empty! No folder to copy + public: "" + console: "" +requests: + views: "views" + app: "app" # This enables app/ folder merging + routers: + application: "" + client: "routes/client.php" + web: "" +database: + migrations: "database/migrations" +``` + +--- + +## Key Learnings + +1. **Blueprint's `wrapper` field only accepts Blade templates** — TSX must be injected via build.sh +2. **The `requests.app` field is how you properly inject PHP classes** — it merges into Pterodactyl's app/ +3. **Every path in conf.yml must exist** — empty string if not used +4. **Namespace must match location** — `app/Http/Controllers/` = `Pterodactyl\Http\Controllers` +5. **Linux is case-sensitive** — `Controllers/` not `controllers/` + +--- + +## Result + +After making these changes: +- `blueprint -build`: ✅ SUCCESS +- `yarn build:production`: ✅ SUCCESS +- `php artisan modpackchecker:check`: ✅ SUCCESS +- Extension appears in admin panel: ✅ SUCCESS