feat: auto-deploy guided servers on run registration

2026-07-28 16:57:09 +08:00
parent e2d0bc0595
commit 7f64765c1c
15 changed files with 191 additions and 55 deletions
@@ -0,0 +1,4 @@
+schema: spec-driven
+created: 2026-07-28
+goal: Treat guided-install selection as authorization for secure automatic
+  deployment and recovery.
@@ -0,0 +1,3 @@
+# auto-managed-server-deployment
+
+Automatically deploy guided server installations when their dedicated Run registers.
@@ -0,0 +1,20 @@
+## Decision
+
+The Platform owns the desired deployment definition. A successful, component-authenticated hello from the reserved dedicated Run endpoint is the trigger to enqueue the first guided installation. The enqueue uses a stable idempotency key derived from the server and deployment revision, so reconnects cannot duplicate work.
+
+The automatic path is restricted to target-bound `guided-install` servers in `draft`. Existing-server and custom-command modes remain explicit because a missing directory can be intentional or user-owned. A future reconcile capability may safely repair guided deployments after an attested drift check; it must not be simulated by blindly reinstalling on every hello.
+
+## Flow
+
+1. Create stores a target-bound draft and protected guided definition.
+2. The user generates, downloads, and starts the dedicated Run.
+3. Platform validates and persists the component hello/session.
+4. Platform atomically advances the draft to installing and creates one `process.install` job.
+5. Run claims the job through the existing job channel.
+
+## Boundaries
+
+- No host path, command, credential, or socket is returned to Platform Web or plugins.
+- A running server is never overwritten by this registration trigger.
+- Failed jobs use the existing bounded retry policy; reconnects do not create unbounded retries.
+- The former deploy endpoint may remain for compatibility, but is not part of the normal user journey.
@@ -0,0 +1,15 @@
+## Why
+
+Creating a guided server already captures the user's installation intent, directory, and game configuration. Requiring a second Deploy click after the dedicated Run registers exposes an internal bootstrap stage and leaves a healthy Run idle.
+
+## What Changes
+
+- Treat `guided-install` as authorization to deploy automatically once the server-scoped Run successfully registers.
+- Keep existing-server and custom-command definitions non-destructive: registration never silently reinstalls them.
+- Remove Deploy/Retry deploy from the normal server-detail flow; registration and durable job state become the source of deployment progress.
+
+## Impact
+
+- `platform/` schedules the initial fenced install from successful dedicated Run registration.
+- `platform_web/` presents registration as an automatic deployment wait state rather than an operator action.
+- The independent Run contract remains channelized; its SCUM executor work is validated separately and is not exposed to the browser.
@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: Guided creation authorizes automatic initial deployment
+The Platform SHALL queue one fenced `process.install` job when the dedicated Run for a target-bound draft with a `guided-install` definition successfully registers.
+
+#### Scenario: Dedicated Run registers for a guided draft
+- **WHEN** the Run presents the valid server-scoped component identity for a guided draft
+- **THEN** the Platform persists the session and queues the guided install using the stored deployment revision
+- **AND** the server transitions to `installing` without another browser action
+
+#### Scenario: The dedicated Run reconnects
+- **WHEN** the Run registers again after the automatic installation has been queued
+- **THEN** the Platform does not create another installation job for the same deployment revision
+
+### Requirement: Automatic registration dispatch is non-destructive outside guided installs
+The Platform SHALL NOT automatically reinstall existing-server or custom-command deployments solely because their Run registers.
+
+#### Scenario: Existing server Run registers
+- **WHEN** a target-bound draft uses `existing-server` and its dedicated Run registers
+- **THEN** the Platform records the Run session without creating an installation job
+
+### Requirement: Normal server management does not require a manual deployment click
+The management console SHALL present guided deployment as automatically pending after dedicated Run registration rather than as a Deploy or Retry deploy button.
+
+#### Scenario: Guided draft awaits Run registration
+- **WHEN** an operator opens a newly created guided draft before its dedicated Run has registered
+- **THEN** the console directs the operator to generate and start the dedicated Run
+- **AND** it does not offer a separate Deploy or Retry deploy action
@@ -0,0 +1,13 @@
+## 1. Platform automatic dispatch
+
+- [x] 1.1 Queue a fenced guided install after an accepted dedicated Run hello, with stable revision idempotency and no duplicate reconnect dispatch.
+- [x] 1.2 Cover guided automatic dispatch and non-guided no-op behavior with service tests.
+
+## 2. Management workflow
+
+- [x] 2.1 Remove the normal manual Deploy/Retry deploy controls and describe automatic deployment after Run registration.
+- [x] 2.2 Update focused frontend tests for the automatic workflow.
+
+## 3. Verification
+
+- [x] 3.1 Run focused backend/frontend tests, type checking, structure validation, and strict OpenSpec validation.