2.8 KiB
AGENTS.md for platform
This file applies to platform/.
Backend Structure
Keep definitions out of business logic:
- Request/response structs go in
dto/or a dedicated contract package. - Database tables go in
model/with field comments and tags before migrations or repositories reference them. - API route declarations and handlers go in
api/. - Business aggregates and value objects go in
domain/. - Protocol payloads go in
protocol/. - Shared helper functions go in
shared/only when at least two packages need them.
API Rules
Every HTTP/API handler must have OpenAPI-style comments when implemented. Request bodies, response bodies, and errors must reference named DTO structs.
Database Rules
Prefer model-first table definitions. Do not define table schemas only inside migration SQL. Migrations may use raw DDL only when the model remains the source of truth.
Platform Boundaries
Plugins and platform_web must never receive run credentials, raw host paths, or AI provider keys. All access must pass through platform authorization and bounded DTOs.
Platform may read plugin manifests, validate lifecycle/action declarations, package plugin-owned action assets into generated run distributions, and dispatch lifecycle jobs with typed inputs. Platform must not implement game-specific install/update/start behavior itself.
Platform may persist desired lifecycle state, last-known run reports, and UI projections. It must not treat those persisted fields as the authoritative source for the current machine/process state; current runtime status must come from the registered run endpoint's reports, heartbeats, supervised process facts, and job/log channels.
Log bodies from supervised stdout/stderr and plugin-declared file tails are opaque verbatim payloads. Platform may validate the transport envelope, sequence, checksum, and source binding, then persist, relay, and display the body unchanged. It must not inspect, parse, filter, redact, normalize, correlate, or derive player, login, user, or other plugin records from a log body. A plugin companion owns any game-specific parsing and its typed records arrive through the component boundary, never as a Platform log projection.
Do not add platform service code that hardcodes a game's executable path, Steam app ID, SteamCMD command line, process name, default launch flags, or update policy. For SCUM specifically, SCUMServer.exe, app 3792580, +app_update 3792580 validate, -port, -MaxPlayers, and -log must come from the SCUM plugin action assets or plugin-declared startup fields.
If a lifecycle job requires checking whether game files exist, installing missing files, updating existing files, stopping before update, or building the final launch command, dispatch the plugin-owned action and keep platform limited to authorization, input validation, job creation, and result handling.