feat: support custom server deployment drafts

2026-07-24 16:56:28 +08:00
parent 292b380f3c
commit 220ef91a8e
36 changed files with 1520 additions and 85 deletions
@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Plugin create schemas drive server creation input
+The system SHALL publish validated plugin create-field schemas to the management console and SHALL render supported fields during server draft creation. Required fields, defaults, select options, numeric values, port values, and boolean values MUST be validated before saving.
+
+#### Scenario: Create a SCUM definition
+- **WHEN** an operator chooses the SCUM plugin
+- **THEN** the console renders the declared server name, game port, query port, and maximum player fields with their declared defaults
+
+### Requirement: Game configuration is distinct from runtime transport binding
+The system SHALL persist plugin create inputs as deployment configuration and MUST NOT store game ports, player limits, paths, or startup commands in runtime binding records.
+
+#### Scenario: Save Minecraft port settings
+- **WHEN** an operator saves Minecraft game and RCON ports in a draft
+- **THEN** the values are retained as plugin create configuration and runtime binding remains reserved for declared transports
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Run executes protected custom lifecycle plans under declared policy
+The system SHALL dispatch custom lifecycle commands only to a Run endpoint that advertises deployment-plan support and the selected execution policy. Run MUST perform local path, executable, timeout, and port preflight before executing a write or process action.
+
+#### Scenario: Run accepts an argv custom start plan
+- **WHEN** a compatible Run claims a custom start job using argv execution mode
+- **THEN** it receives the protected working directory and arguments only through the leased execution input and reports a safe preflight result
+
+### Requirement: Shell interpretation is explicit
+The system SHALL require an explicit shell kind for a shell command string and MUST NOT infer shell interpretation from command text. The system MUST reject shell execution when the selected Run policy does not allow that shell kind.
+
+#### Scenario: Disallowed shell command
+- **WHEN** an operator selects a shell command mode unsupported by the assigned Run
+- **THEN** dispatch fails with a safe policy error and does not execute the command
+
+### Requirement: Run reports redacted phase progress
+The Run contract SHALL report only a defined deployment phase, percent, and safe message or error code. It MUST NOT return raw host paths, raw command text, raw credentials, or direct socket values.
+
+#### Scenario: Preflight path failure
+- **WHEN** a configured working directory is unavailable on Run
+- **THEN** Run reports a `preflight` failure with a safe reason without echoing the supplied absolute path
@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Server definitions can be saved before Run is available
+The system SHALL allow an authorized server manager to create and edit a draft server definition without a Run endpoint binding. The system MUST NOT dispatch a lifecycle job for an unbound draft.
+
+#### Scenario: Create an unbound draft
+- **WHEN** an authorized user saves a server definition without selecting a Run endpoint
+- **THEN** the system stores it in `draft` state and returns no install job
+
+#### Scenario: Deploy a draft after Run registration
+- **WHEN** an authorized user binds a draft to a compatible online Run endpoint and requests deployment
+- **THEN** the system validates the deployment definition and queues the requested lifecycle job
+
+### Requirement: Deployment modes support real self-hosted layouts
+The system SHALL support `guided-install`, `existing-server`, and `custom-command` deployment modes. An operator MAY provide an absolute server root and working directory for all modes and lifecycle command definitions for custom-command mode.
+
+#### Scenario: Adopt an existing Python virtual-environment server
+- **WHEN** an operator saves existing-server or custom-command mode with an absolute working directory and a Python virtual-environment startup command
+- **THEN** the system stores the protected execution input and does not require the server directory to be adjacent to Run
+
+### Requirement: Protected execution inputs are not exposed by read APIs
+The system SHALL treat supplied host paths and command text as protected execution inputs. List, detail, job, audit, log, and plugin bridge read responses MUST expose only configured state, deployment mode, and safe fingerprints or summaries.
+
+#### Scenario: Read a configured custom deployment
+- **WHEN** an authorized user reads a server deployment definition after saving a path and command
+- **THEN** the response indicates the protected fields are configured without returning their values
+
+### Requirement: Deployment requires an execution-capable Run only when dispatching
+The system SHALL require an online compatible Run endpoint only for preflight, install, start, stop, or status dispatch. The system MUST reject dispatch when the assigned Run does not declare the versioned deployment-plan capability.
+
+#### Scenario: Attempt deployment with incompatible Run
+- **WHEN** an operator requests deployment against a Run that lacks deployment-plan support
+- **THEN** the system returns a safe compatibility reason and does not queue an executable lifecycle job
+
+### Requirement: Lifecycle status explains waiting and execution phases
+The system SHALL surface whether a deployment job is queued, claimed, in preflight, installing, configuring, starting, or performing a health check. Safe Run failures MUST remain attached to the job and server state.
+
+#### Scenario: Run has not claimed deployment
+- **WHEN** a deployment job remains queued
+- **THEN** the server UI identifies it as waiting for Run claim rather than reporting installation progress