server-manager/AGENTS.md

ServerManager — AGENTS.md

Repo-specific guidance for OpenCode sessions. Verified against code.

Stack

• PHP 8.3+, custom MVC (not Laravel), MySQL/MariaDB, phpseclib 3.0, phpdotenv
• Autoload: PSR-4 ServerManager\ → src/; src/Helpers/functions.php auto-loaded
• Android companion app at android/ (Jetpack Compose, Material3, Retrofit, Kotlinx Serialization)

Entry point

public/index.php → App::boot() → App::run() → Router::dispatch()

Commands

• composer install — install deps (no dev deps in composer.json)
• php bin/generate-key.php — generate master key at /etc/servermanager/master.key
• php bin/monitor.php — collect server metrics (runs via cron every minute)
• sudo bash install.sh — full Ubuntu 22.04+/24.04+ install (needs sudo)
• mysql servermanager < database/migrations/001_initial_schema.sql — db setup
• export ANDROID_HOME=/opt/android-sdk && cd android && ./gradlew assembleDebug — build APK → public/sysadmin.apk

Non-obvious conventions

• Route params use :id syntax (/servers/:id), not {id}. Patterns: :id → (\d+), :slug → ([a-zA-Z0-9\-]+)
• Router supports method spoofing via _method POST field
• Session name is SM_SESSION; sessions stored server-side in sessions table
• View engine: custom PHP templates (extract() + include), not Twig/Blade
• SSH credentials encrypted with AES-256-CBC; master key at /etc/servermanager/master.key
• vendor/ is properly gitignored now (/vendor/ in .gitignore, no leading space)
• Android build outputs ignored: android/.gradle/, android/build/, android/app/build/, android/local.properties
• Bump versionCode and versionName in android/app/build.gradle.kts on every code change to the Android app

Backend gotchas

• View::json() has : never return type — calls exit immediately. Do not put code after it expecting to run.
• AuditService::log(string $action, string $entityType, ?int $entityId, ?array $details = null, ?array $metadata = null) — requires 3 positional args minimum. Calling with 2 args causes Error 500.
• RoleMiddleware defaults to 'admin' required level. Hierarchy: super_admin (3) > admin (2) > operator (1).
• Role helper functions in views: is_super_admin(), is_admin(), is_operator()
• CSRF: middleware checks $_POST['_csrf_token'] then $_SERVER['HTTP_X_CSRF_TOKEN']. Token expiry 7200s default.
• API routes have no middleware (auth is manual via $this->authenticateRequest() in controller). Web routes use AuthMiddleware / RoleMiddleware / CSRFMiddleware.
• Admin group routes (/admin/*) already include AuthMiddleware + RoleMiddleware; individual routes add CSRFMiddleware.
• Rate limiting on POST /login only (via RateLimitMiddleware)
• Every credential access must be logged at warning level via AuditService
• Notification read receipts tracked in notification_reads table: (notification_id, user_id) unique pair, with read_at timestamp

Permission validation on server create/edit

• When creating or editing a server, required SSH permissions can be specified and are validated via SSH before saving.
• PermissionValidator::validate(array $serverConfig, array $permissions) connects to the remote server and runs check commands for each permission.
• Permission types: sudo (checks passwordless sudo), command (checks command -v), file_read (test -r), file_write (test -w), custom (arbitrary command, exit code 0 = pass).
• ServerPermission model handles CRUD for the server_permissions table.
• Both web (ServerController::store/update) and API (ApiController::serverAdd/serverUpdate) flows include permission validation.
• On validation failure, the web flow preserves form input via $_SESSION['_form_input'] and redirects back with error details.

Database

• Migrations run manually: mysql servermanager < database/migrations/NNN_name.sql
• 8 migrations: 001_initial_schema, 002_server_access, 003_teams, 004_soft_deletes, 005_app_config_and_notifications, 006_agent_tokens, 007_server_permission_checks, 008_notification_reads
• Users table has role ENUM: super_admin, admin, operator
• api_token column on users for Bearer token auth
• server_permissions table stores required SSH permissions per server (FK to servers.id CASCADE)

Testing / CI

• No tests, no CI, no linter, no formatter, no typechecker exist in this repo

Notable missing files

• .env.example does NOT exist (referenced in composer.json post-install-cmd but missing from repo)
• No Makefile, Dockerfile, or CI workflows