74 lines
5.2 KiB
Markdown
74 lines
5.2 KiB
Markdown
# plugins
|
|
|
|
Game management plugin workspace.
|
|
|
|
A game management plugin defines how the platform creates and manages one type of game server. One installed plugin can create many server instances.
|
|
|
|
## Plugin Responsibilities
|
|
|
|
- Manifest identity and server type declaration.
|
|
- Create-server form schema.
|
|
- Lifecycle action definitions.
|
|
- Required run capabilities.
|
|
- Optional remote access methods and remote run capabilities.
|
|
- Optional runtime profiles for discovery, lifecycle modes, dependency probes, install plans, log sources, transports, and client-manager builds.
|
|
- Optional plugin pages hosted by platform_web.
|
|
- AI/file/log permissions declared for platform authorization.
|
|
|
|
## Required Directory Plan
|
|
|
|
Implementation should use dedicated directories for:
|
|
|
|
- `manifests/`: plugin manifest examples or shared manifest schemas.
|
|
- `schemas/`: action, config, and create-form schemas.
|
|
- `sdk/`: plugin bridge SDK and shared contracts.
|
|
- `examples/`: example game management plugins.
|
|
- `tests/`: plugin contract tests and fixtures.
|
|
|
|
Plugins must use the platform bridge and must not connect directly to run, log storage, artifact storage internals, or AI provider endpoints.
|
|
|
|
Manifest validation is the plugin-side installability gate. The shared manifest schema defines identity, version, server type/display metadata, create form schema reference, lifecycle action references, required run capabilities, scoped permissions, remote access declarations, runtime profiles, optional pages, tags, and AI purposes. `scripts/validate-manifest.ts` also scans manifest and create-form content for unsafe raw host path, raw credential, direct run, and raw AI/provider key requests.
|
|
|
|
Remote access declarations describe whether a plugin can use `ftp`, `rsync`, or `run`, and which `remote.*` run capabilities are enabled for that game. Runtime profiles describe how run discovers servers, checks dependencies, tails live logs, backfills historical logs, resolves transports, and builds optional client managers. Plugin pages use platform-mediated bridge actions; they never receive FTP passwords, rsync endpoints, database DSNs, RCON credentials, run/client keys, run sockets, or host paths.
|
|
|
|
Runtime profiles are declarative contracts, not executable scripts. A profile can declare:
|
|
|
|
- discovery probes for logical targets such as Java, Steam app, service, file, or toolchain checks.
|
|
- lifecycle modes such as `local-process`, `hosted-ftp-rcon`, `ftp-only`, or `custom-client`.
|
|
- dependency probes and typed install plans for supported OS targets.
|
|
- log sources for stdout/stderr, file tailing, FTP polling, SQL cursors, or plugin-specific client-manager logs.
|
|
- transport profiles for declared file, FTP/rsync, SQL, RCON, and run-mediated operations.
|
|
- client-manager build profiles for games such as SCUM that need a separate companion executable.
|
|
|
|
Client-manager profiles declare repository URL, revision policy, supported target OS/architecture pairs, build system hints, config template keys, dependency hints, and produced artifact paths. Platform performs target validation, creates a build record, injects a distinct server/component key into the generated package config, redacts build logs, and publishes a downloadable artifact. The run key and client-manager key are separate singleton keys in platform storage; resetting either key revokes packages from older generations and requires regenerating that component.
|
|
|
|
Plugin pages may request these operations only through bridge helpers:
|
|
|
|
- `createRunDistributionRequest`: generate/download/reset/update run packages.
|
|
- `createDependencyActionRequest`: check or install declared dependency probes/plans.
|
|
- `createLogBackfillRequest`: request historical log cursors for declared sources.
|
|
- `createClientManagerRequest`: generate/download/reset declared client-manager packages.
|
|
|
|
Bridge envelopes carry operation names, profile keys, target platforms, artifact IDs, checkpoint refs, and idempotency keys only. The plugin SDK and manifest validation reject raw run keys, client-manager keys, FTP passwords, rsync endpoints, SQL DSNs, RCON passwords, direct run sockets, host paths, and arbitrary shell snippets.
|
|
|
|
Validated manifests are registered through the platform registry API rather than by plugin code importing platform internals. Platform stores registry metadata only and repeats safety validation before a plugin becomes installable.
|
|
|
|
## Development Baseline
|
|
|
|
Tooling:
|
|
|
|
- Node 22.17.0.
|
|
- npm 11.6.1.
|
|
- TypeScript 5.
|
|
|
|
Commands:
|
|
|
|
```bash
|
|
npm install
|
|
npm run typecheck
|
|
npm run test
|
|
npm run validate:manifest
|
|
```
|
|
|
|
Current plugin behavior includes SDK bridge contracts, manifest schema validation, the `examples/dev-game-plugin`, `examples/scum-server-plugin`, and `examples/minecraft-server-plugin` fixtures, platform registry metadata registration, marketplace projections, hosted plugin-page bridge execution, platform-mediated lifecycle job dispatch, declared remote access envelopes, runtime profile declarations, run distribution envelopes, typed dependency/log backfill requests, and SCUM-style client-manager build declarations. Marketplace package acquisition, private source credentials, public build-worker sandboxing, real FTP/rsync/database/RCON adapters beyond bounded envelopes, remote plugin hosting policies, and external package distribution remain future OpenSpec work.
|