firefrost-gaming/firefrost-operations-manual

Files

Claude (Chronicler #63) c881e55bc1 docs(consultations): Add Gemini Blueprint conf.yml consultation

Documents the solution to 'files do not exist' Blueprint error:
- data.directory must be empty if no folder exists
- dashboard.wrapper doesn't support TSX (use build.sh)
- requests.app: 'app' enables proper PSR-4 autoloading
- Namespace must match folder location exactly

This consultation saved Task #26 ModpackChecker deployment.

Signed-off-by: Claude (Chronicler #63) <claude@firefrostgaming.com>

2026-04-06 09:55:19 +00:00

2.9 KiB

Raw Permalink Blame History

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

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.
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

info:
  name: "ModpackChecker"
  identifier: "modpackchecker"
  description: "4-platform modpack version checker"
  flags: ""
  version: "1.0.0"
  target: "beta-2026-01"
  author: "Firefrost Gaming <dev@firefrostgaming.com>"
  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

Blueprint's wrapper field only accepts Blade templates — TSX must be injected via build.sh
The requests.app field is how you properly inject PHP classes — it merges into Pterodactyl's app/
Every path in conf.yml must exist — empty string if not used
Namespace must match location — app/Http/Controllers/ = Pterodactyl\Http\Controllers
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

2.9 KiB Raw Permalink Blame History