browser/plugins

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, or ftp-only.
• 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, component 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:

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 bounded scheduler, process supervisor, and isolated log/artifact/control channels are Platform/Run capabilities; plugins receive only declarations and safe status projections.