80 lines
6.8 KiB
Markdown
80 lines
6.8 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 plugin-owned component declarations.
|
|
- Optional plugin pages hosted by platform_web.
|
|
- AI/file/log permissions declared for platform authorization, including `ai.mediation=platform` and `ai.configWritePolicy=review-required`.
|
|
- Production lifecycle operations, dependency policy, and disruptive approval requirements.
|
|
|
|
## 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, carries declared log channels verbatim, resolves transports, and executes plugin-owned lifecycle declarations. 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, or plugin-declared typed channels. Log bodies remain opaque and verbatim to Run and Platform.
|
|
- transport profiles for declared file, FTP/rsync, SQL, RCON, and run-mediated operations.
|
|
Plugin-owned component declarations may describe their own typed bridge records and lifecycle, while the generic Run/Platform path only transports declared envelopes and opaque log channels. Neither Run nor Platform parses, filters, normalizes, correlates, redacts, or derives plugin records from stdout, stderr, or declared file tails.
|
|
|
|
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.
|
|
- `createProductionPluginLifecycleRequest`: request server-bound install/enable/disable/upgrade/rollback/retire/dependency-check through Platform operations.
|
|
|
|
Bridge envelopes carry operation names, profile keys, target platforms, artifact IDs, checkpoint refs, immutable reviewed dependency plan digests, and idempotency keys only. Dependency install bridge helpers require a `sha256:<64 hex>` reviewed plan digest; Platform re-resolves the declaration and rejects stale or missing approvals. 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 persists the validated runtime-profile declaration with the installed plugin contract and repeats safety validation before a plugin becomes installable. Per-server values are stored separately as platform-owned runtime bindings; plugin pages receive only logical readiness and never the stored values.
|
|
|
|
## 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, target-matched typed dependency plan requests, run distribution envelopes, typed dependency/log backfill requests, and plugin-owned typed SCUM RCON data flows. Marketplace package acquisition, private source credentials, public build-worker sandboxing, remote plugin hosting policies, production KMS/code signing/fleet rollout, and external package distribution remain future work.
|
|
|
|
Runtime-profile declarations do not provide a general secret vault, arbitrary machine execution, production code signing/KMS, or fleet orchestration. The durable Client Manager installation/session state, bounded scheduler, process supervisor, and isolated log/artifact/control channels are Platform/Run capabilities; plugins receive only declarations and safe status projections.
|
|
# Client Manager profile contract
|
|
|
|
Plugins may declare a Client Manager profile with version/revision, supported targets, fixed relative executable, deployment mode, lifecycle capabilities, bounded startup/stop/health settings, compatibility constraints, and update policy. Platform enables lifecycle actions only after a real available distribution, complete server binding, an owned online Run endpoint, matching target/revision, and the current component-key generation.
|
|
|
|
Plugin pages and SDK bridge responses expose profile declarations, action availability, logical status/health, version/revision, job progress, and safe failure reasons only. They never receive component keys, sessions, secret refs/values, host paths, PIDs, sockets, credentials, DSNs, or direct Run endpoints. Arbitrary shell, raw credentials, and endpoint-bearing declarations are rejected during manifest validation.
|