Complete platform management workflows

2026-07-14 16:39:37 +08:00
parent 7e05d0a4e7
commit 4f33f761a3
106 changed files with 11313 additions and 460 deletions
@@ -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?