Move SCUM lifecycle ownership to plugin

2026-08-01 09:36:12 +08:00
parent bca4f935ba
commit d1249fca85
49 changed files with 795 additions and 566 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-31
@@ -0,0 +1,37 @@
+## Design
+
+The lifecycle boundary becomes:
+
+- Platform validates the selected plugin, resolves the plugin lifecycle action reference, packages plugin action assets into generated run workspaces, and dispatches a generic lifecycle job with typed inputs.
+- The SCUM plugin owns Windows scripts/action specs that check whether `SCUMServer.exe` exists, install or update through SteamCMD, stop before update, write plugin-declared config values, and start with plugin-declared `port`/`MaxPlayers` plus the plugin default `-log`.
+- Run executes the referenced action through generic primitives. It never branches on `game.scum`, `SCUMServer.exe`, or app `3792580`.
+
+### SCUM Plugin Action Model
+
+The SCUM install action is the authoritative setup action. It runs before first start and may also be reused as a pre-start update action. The action checks for SteamCMD, downloads it if missing, stops the SCUM process when an update is needed, runs:
+
+```powershell
+./steamcmd.exe +force_install_dir C:/scumserver +login anonymous +app_update 3792580 validate +quit
+```
+
+Then the start action runs:
+
+```powershell
+C:/scumserver\SCUM\Binaries\Win64\SCUMServer.exe -port=<gamePort> -MaxPlayers=<maxPlayers> -log
+```
+
+The concrete path may come from server deployment inputs, but the SCUM executable relative path, app id, SteamCMD arguments, and `-log` default are plugin assets, not platform/run code.
+
+### Platform Changes
+
+Platform no longer freezes a `ServerDeploymentPlan` for SCUM or requires `deployment.scum.v1`. It keeps generic deployment definitions and dispatches plugin action refs. Deployment projections can still show queued/running/failed lifecycle state from generic receipts, but detailed SCUM evidence is plugin-generated output/log/artifact data, not a platform-owned SCUM evidence schema.
+
+### Run Changes
+
+Run removes the SCUM deployment executor and SCUM capability advertisement. Assignments carrying `serverDeploymentPlan` are rejected as legacy unsupported input. Generic lifecycle template execution remains, including managed process start/stop/status, file operations, logs, and artifacts.
+
+## Risks / Trade-Offs
+
+- Existing tests expecting SCUM evidence need to shift to plugin-action dispatch assertions.
+- The first plugin script implementation must be careful about Windows quoting and idempotency.
+- If future games need richer setup flows, add generic action primitives or structured lifecycle DSL features without moving game policy into run.
@@ -0,0 +1,28 @@
+## Why
+
+The current SCUM deployment flow hardcodes SteamCMD, SCUM executable paths, app id `3792580`, config writes, and start arguments inside platform/run code. That violates the intended boundary: the SCUM plugin should own game lifecycle policy while platform dispatches and run executes generic, bounded actions.
+
+## What Changes
+
+- **BREAKING**: Retire the SCUM-specific `deployment.scum.v1` run capability and the platform-to-run `serverDeploymentPlan` path for SCUM installs/adoptions.
+- Move SCUM install/update/start command ownership into the SCUM plugin action bundle.
+- Use plugin lifecycle actions for idempotent "install if missing, update if present, then start" behavior.
+- Keep platform limited to manifest/action validation, distribution packaging, lifecycle job dispatch, and generic result projection.
+- Keep run limited to generic action execution, scoped file/process operations, logs, artifacts, and capability enforcement.
+
+## Capabilities
+
+### New Capabilities
+
+- `plugin-owned-game-lifecycle`: Game plugins own game-specific lifecycle commands, default launch flags, app IDs, executable paths, install/update policies, and pre-start checks.
+
+### Modified Capabilities
+
+- `platform-side-distribution-builds`: Generated run packages must carry plugin-owned lifecycle action assets without requiring run to advertise game-specific deployment capabilities.
+
+## Impact
+
+- Affects `plugins/examples/scum-server-plugin` action assets and manifest declarations.
+- Affects `platform/service`, `platform/domain`, `platform/dto`, `platform/validator`, and protocol docs by removing SCUM-specific deployment plan dispatch/gating.
+- Affects the independent `run` repository by removing SCUM-specific runtime execution and capability advertisement.
+- Requires tests proving SCUM lifecycle jobs are plugin action jobs and run no longer contains a SCUM deployment executor.
@@ -0,0 +1,42 @@
+# plugin-owned-game-lifecycle Specification
+
+## Purpose
+
+Ensure game-specific server lifecycle behavior lives in game plugins while platform and run remain generic.
+
+## ADDED Requirements
+
+### Requirement: Game plugins own game-specific lifecycle policy
+
+The system SHALL keep game-specific install, update, pre-start, start argument, stop, status, executable path, app id, and default launch flag policy in plugin-owned manifests, action specs, templates, or scripts.
+
+#### Scenario: SCUM lifecycle declares concrete commands in plugin assets
+
+- **WHEN** SCUM requires SteamCMD installation/update or server start
+- **THEN** the Steam app id `3792580`, `SCUMServer.exe` relative path, `+app_update 3792580 validate`, `-port`, `-MaxPlayers`, and `-log` are provided by SCUM plugin assets or plugin startup fields
+- **AND** platform and run do not hardcode those values to make SCUM lifecycle work
+
+### Requirement: Platform dispatches plugin lifecycle actions generically
+
+The platform SHALL dispatch lifecycle jobs using plugin-declared action references and generic lifecycle/deployment inputs, and SHALL NOT require a game-specific run capability for SCUM deployment.
+
+#### Scenario: SCUM install job is queued
+
+- **WHEN** a SCUM server create/install lifecycle job is created
+- **THEN** the job target key references the SCUM plugin install action
+- **AND** the job execution input does not include a SCUM-specific server deployment plan
+- **AND** required run capabilities contain only generic lifecycle/deployment capabilities
+
+### Requirement: Run executes generic actions only
+
+Run SHALL execute lifecycle action templates and scoped process/file operations generically, and SHALL NOT branch on a game id or contain per-game deployment executors.
+
+#### Scenario: Legacy SCUM deployment plan reaches run
+
+- **WHEN** a run assignment includes a legacy `serverDeploymentPlan`
+- **THEN** run rejects it as unsupported legacy input instead of executing game-specific deployment logic
+
+#### Scenario: Run capability report
+
+- **WHEN** run reports supported capabilities
+- **THEN** the report does not include `deployment.scum.v1`
@@ -0,0 +1,25 @@
+## 1. OpenSpec Artifacts
+
+- [x] 1.1 Create proposal, design, and spec delta for plugin-owned SCUM lifecycle ownership.
+- [x] 1.2 Validate the OpenSpec change strictly before completion.
+
+## 2. Plugin Lifecycle Assets
+
+- [x] 2.1 Add SCUM-owned Windows install/update and start scripts/action specs with SteamCMD app update and startup arguments owned by the plugin.
+- [x] 2.2 Update plugin manifest/tests so SCUM lifecycle no longer depends on `deployment.scum.v1`.
+
+## 3. Platform Dispatch Boundary
+
+- [x] 3.1 Remove SCUM-specific deployment plan creation, capability gating, and evidence validation from platform lifecycle dispatch.
+- [x] 3.2 Update platform tests/protocol docs to assert generic plugin action dispatch.
+
+## 4. Run Executor Boundary
+
+- [x] 4.1 Remove the SCUM-specific run executor/capability path and reject legacy `serverDeploymentPlan` inputs generically.
+- [x] 4.2 Update run tests to prove generated run capabilities exclude `deployment.scum.v1` and generic plugin actions still execute.
+
+## 5. Verification And Delivery
+
+- [x] 5.1 Run focused plugin, platform, and run tests.
+- [x] 5.2 Run `scripts/check-structure.sh` and final repository status checks.
+- [ ] 5.3 Commit and push main-repo and run-repo changes separately.