Complete platform management workflows
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-13
|
||||
@@ -0,0 +1,65 @@
|
||||
## Context
|
||||
|
||||
The platform already has separate run control, job, log, and artifact channels. Plugin manifests currently declare lifecycle, file, log, artifact, and AI capabilities, but they do not describe whether a server may be reached by FTP, rsync, or run, nor do they declare run-only operations such as remote database reads or RCON. The previous SCUM codebase used FTP/SFTP workers for file upload, scum_run for server-side operations, SQLite query forwarding, log transfer, and game-client command handling; this change brings those ideas into the new platform as typed, plugin-declared capabilities.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Model remote access methods and remote run operations in the plugin manifest.
|
||||
- Require installed plugins to declare remote capabilities before platform bridge or direct job dispatch can queue them.
|
||||
- Keep remote file/database/RCON/log operations behind platform and run channels.
|
||||
- Allow both SCUM and Minecraft plugins to declare compatible remote access needs.
|
||||
- Keep job payloads bounded: logical target keys, scoped input/artifact refs, and safe result refs only.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- No raw FTP, rsync, database, or RCON credentials in plugin manifests or plugin pages.
|
||||
- No browser-to-run, plugin-to-run, or plugin-to-database direct connection.
|
||||
- No production FTP/rsync client, MySQL client, SQLite parser, or RCON protocol implementation in this change.
|
||||
- No cloud host provider workflow or server rental/billing feature.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Manifest declares methods and capabilities separately
|
||||
|
||||
`remoteAccess.methods` describes how a server may be reached (`ftp`, `rsync`, `run`). `remoteAccess.runCapabilities` lists the exact run operations the plugin can use. This keeps transport choice visible while still preserving the existing run capability matching model.
|
||||
|
||||
Alternative considered: encode everything as free-form tags. Rejected because marketplace and authorization need deterministic validation and filtering.
|
||||
|
||||
### Decision 2: Remote access uses a dedicated bridge action
|
||||
|
||||
Plugin pages use `remote.access.request` for database, RCON, log transfer, and remote file jobs. Existing `files.request` remains for generic scoped file operations; lifecycle `jobs.dispatch` remains for start/stop. The new action lets platform apply a distinct `server.remote.access` permission and capability declaration check.
|
||||
|
||||
Alternative considered: overload `jobs.dispatch` for every remote operation. Rejected because RCON/database/log transfer should not be authorized only by `server.lifecycle`.
|
||||
|
||||
### Decision 3: Direct server-bound jobs are plugin-gated
|
||||
|
||||
When a job includes a `serverInstanceId`, platform validates the instance plugin declares the requested capability. This prevents callers from bypassing plugin bridge and enabling remote DB/RCON/log transfer jobs on plugins that did not opt in.
|
||||
|
||||
Alternative considered: enforce declaration only in plugin bridge. Rejected because platform API callers can create jobs directly in tests and future admin flows.
|
||||
|
||||
### Decision 4: Run remote executor is bounded metadata first
|
||||
|
||||
Run reports remote capabilities and accepts remote jobs, but returns safe metadata/result refs rather than opening real network connections in this change. Real FTP/rsync/database/RCON adapters can later attach behind the same job envelopes without changing plugin manifests.
|
||||
|
||||
Alternative considered: implement protocol clients now. Rejected because credential storage, network policy, and result artifact formats need a separate change and should not be rushed into manifest plumbing.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Risk] Operators may expect real FTP/rsync/DB/RCON execution immediately. Mitigation: docs and result messages state this is the declared, bounded job contract; adapter implementation remains a follow-up.
|
||||
- [Risk] Capability names may grow numerous. Mitigation: keep them grouped under `remote.*` and validate them centrally.
|
||||
- [Risk] Existing tests using generic jobs may fail once server-bound jobs are plugin-gated. Mitigation: lifecycle/file capabilities remain declared in existing test plugin fixtures.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Add OpenSpec, schema, domain, DTO, validator, and service support for remote access declarations.
|
||||
2. Update SCUM and add Minecraft example manifests with declared remote access.
|
||||
3. Extend run protocol and runtime to validate/report remote capabilities and complete bounded remote jobs.
|
||||
4. Add tests for manifest validation, platform authorization, direct job gating, and run remote job handling.
|
||||
5. Run manifest validation, platform/run tests, structure check, and strict OpenSpec validation.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Which follow-up change should own real FTP/rsync credential storage and connection testing?
|
||||
- Should RCON results become log entries, artifacts, or both when full adapters land?
|
||||
@@ -0,0 +1,29 @@
|
||||
## Why
|
||||
|
||||
The platform needs one safe model for remote game server access across hosted files, run-managed hosts, databases, logs, and RCON. The old SCUM stack handled FTP/SFTP, run-side process control, SQLite queries, logs, and client commands in separate paths; the new platform must make those abilities plugin-declared before they can be used.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add plugin manifest metadata for declared remote access methods: `ftp`, `rsync`, and `run`.
|
||||
- Add remote run capabilities for remote file read/write, process start/stop, MySQL and SQLite query, log transfer, and RCON command dispatch.
|
||||
- Add platform registry and marketplace projection fields so operators can see which remote access methods a game plugin enables.
|
||||
- Add a platform-mediated bridge action for remote access requests that queues only capabilities declared by the installed plugin.
|
||||
- Extend run capability reporting and bounded remote job handling so MC and SCUM plugins can opt into the same contract.
|
||||
- Add first-party Minecraft and SCUM example manifests proving the shared declaration model.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `plugin-declared-remote-access`: Plugin-declared remote server access through ftp, rsync, or run with scoped run jobs for remote files, lifecycle, database reads, log transfer, and RCON.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affects `plugins/` manifest schema, manifest validator tests, and first-party example manifests.
|
||||
- Affects `platform/` domain, DTO, validators, service bridge dispatch, marketplace projections, docs, and tests.
|
||||
- Affects `run/` protocol capability constants, job validation, runtime capability reporting, worker execution, docs, and tests.
|
||||
- Does not add billing, cloud host sales, plugin-owned credentials, browser-to-run access, raw host paths, or raw database/RCON credentials in plugin pages.
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Plugin manifests declare remote access methods
|
||||
Game management plugin manifests SHALL declare remote access methods before platform exposes FTP, rsync, or run-mediated remote server operations for server instances created from that plugin.
|
||||
|
||||
#### Scenario: Manifest declares supported methods
|
||||
- **WHEN** a plugin manifest lists `ftp`, `rsync`, or `run` under remote access methods
|
||||
- **THEN** platform registry and marketplace responses MUST preserve those methods without exposing host paths, remote credentials, direct sockets, or provider secrets
|
||||
|
||||
#### Scenario: Unsafe remote access declaration is rejected
|
||||
- **WHEN** a plugin manifest includes raw credentials, host paths, direct run socket details, or unknown remote access methods
|
||||
- **THEN** plugin workspace validation and platform registration MUST reject the manifest before it becomes installable
|
||||
|
||||
### Requirement: Remote run operations are capability gated
|
||||
Remote run operations SHALL be represented as explicit run capabilities and SHALL require both the run endpoint and the installed game plugin to declare the requested capability.
|
||||
|
||||
#### Scenario: Declared remote run job is queued
|
||||
- **WHEN** a plugin declares a remote run capability and the selected run endpoint reports the same capability
|
||||
- **THEN** platform MAY queue a bounded job for that server instance using logical target keys and scoped input or artifact refs
|
||||
|
||||
#### Scenario: Undeclared remote run job is denied
|
||||
- **WHEN** a caller requests remote database, RCON, log transfer, or remote file work for a server instance whose plugin did not declare the requested capability
|
||||
- **THEN** platform MUST reject or deny the request before creating a job
|
||||
|
||||
### Requirement: Remote access bridge is platform mediated
|
||||
Plugin pages SHALL request remote access through a platform-mediated bridge action and MUST NOT connect directly to FTP, rsync, run, MySQL, SQLite, log storage, or RCON endpoints.
|
||||
|
||||
#### Scenario: Bridge queues declared remote access
|
||||
- **WHEN** a plugin page has `server.remote.access` permission and requests `remote.access.request` for a declared capability
|
||||
- **THEN** platform MUST authorize the action and queue the corresponding bounded run job
|
||||
|
||||
#### Scenario: Bridge denies undeclared remote access
|
||||
- **WHEN** a plugin page requests `remote.access.request` for a capability not declared by the plugin
|
||||
- **THEN** platform MUST return a safe denial and MUST NOT expose run credentials, host paths, database DSNs, RCON passwords, or remote storage endpoints
|
||||
|
||||
### Requirement: Run handles bounded remote jobs
|
||||
Run SHALL report supported remote capabilities and complete remote job assignments with bounded progress and safe result references while keeping control, job, logs, and artifact channels separate.
|
||||
|
||||
#### Scenario: Run accepts remote database and RCON assignments
|
||||
- **WHEN** run receives declared remote MySQL, SQLite, RCON, log transfer, or remote file assignments
|
||||
- **THEN** run MUST validate bounded job metadata and return terminal results without embedding raw credentials, host paths, query result bodies, log bodies, or RCON output in the job result payload
|
||||
|
||||
#### Scenario: Run rejects unsafe remote job payload
|
||||
- **WHEN** a remote job assignment includes an absolute path, parent traversal, raw secret, direct socket, or oversized inline content
|
||||
- **THEN** run MUST reject the assignment with a bounded failure result
|
||||
|
||||
### Requirement: MC and SCUM plugins share the remote access model
|
||||
First-party Minecraft and SCUM plugin manifests SHALL validate against the same remote access schema and declare only the capabilities each game needs.
|
||||
|
||||
#### Scenario: Minecraft plugin validates
|
||||
- **WHEN** the Minecraft example plugin declares run-managed files, logs, and RCON access
|
||||
- **THEN** plugin workspace manifest validation MUST pass
|
||||
|
||||
#### Scenario: SCUM plugin validates
|
||||
- **WHEN** the SCUM example plugin declares FTP/rsync/run file access, run lifecycle, SQLite/MySQL database read compatibility, log transfer, and RCON access
|
||||
- **THEN** plugin workspace manifest validation MUST pass
|
||||
@@ -0,0 +1,40 @@
|
||||
## 1. OpenSpec Contracts
|
||||
|
||||
- [x] 1.1 Create proposal, design, and spec for plugin-declared remote access.
|
||||
- [x] 1.2 Validate the new change artifacts with `openspec validate --strict`.
|
||||
|
||||
## 2. Plugin Manifest Contracts
|
||||
|
||||
- [x] 2.1 Extend the game plugin manifest schema with `remoteAccess` methods, run capabilities, database engines, RCON, and log transfer declarations.
|
||||
- [x] 2.2 Update manifest validation tests and examples so SCUM and Minecraft validate with remote access declarations.
|
||||
|
||||
## 3. Platform Registry and Authorization
|
||||
|
||||
- [x] 3.1 Add domain and DTO remote access metadata to game plugin, manifest, and marketplace projections.
|
||||
- [x] 3.2 Extend platform validators for remote methods, remote run capabilities, `server.remote.access`, and `remote.access.request`.
|
||||
- [x] 3.3 Gate server-bound jobs against the server instance plugin's declared capabilities.
|
||||
- [x] 3.4 Add bridge execution for declared remote access requests and tests for denied undeclared capabilities.
|
||||
|
||||
## 4. Run Protocol and Worker
|
||||
|
||||
- [x] 4.1 Add remote run capability constants and validation rules for bounded remote assignments.
|
||||
- [x] 4.2 Report remote capabilities from run smoke and worker mode.
|
||||
- [x] 4.3 Add bounded remote job execution results that keep heavy payloads in artifact/log channels.
|
||||
- [x] 4.4 Add run tests for remote DB/RCON/log/file capabilities and unsafe payload rejection.
|
||||
|
||||
## 5. Documentation and Verification
|
||||
|
||||
- [x] 5.1 Update platform, run, and plugin docs for remote access capability declarations.
|
||||
- [x] 5.2 Run plugin manifest validation, platform tests, run tests, and `scripts/check-structure.sh`.
|
||||
- [x] 5.3 Record verification evidence in `tasks.md`.
|
||||
|
||||
## Evidence
|
||||
|
||||
- `openspec validate add-plugin-declared-remote-access --strict` - passed; PostHog telemetry flush logged DNS warnings only after validation succeeded.
|
||||
- `go test ./...` in `platform/` - passed.
|
||||
- `go test ./...` in `run/` - passed.
|
||||
- `npm test` in `plugins/` - passed: 14 manifest/SDK tests.
|
||||
- `npm run typecheck` in `plugins/` - passed.
|
||||
- `TMPDIR=/private/tmp npm run validate:manifest` in `plugins/` - passed for dev, SCUM, and Minecraft manifests.
|
||||
- `scripts/check-structure.sh` - passed.
|
||||
- `git diff --check` - passed.
|
||||
Reference in New Issue
Block a user