first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-03
@@ -0,0 +1,87 @@
+## Context
+
+The platform already has installed game plugin metadata, server instance records, run endpoint registration, job claim/ack/progress/result, log ingest, artifact transfer, and a console shell. The missing product path is the operator workflow that creates a server from a plugin, dispatches lifecycle jobs through the job channel, updates server state from terminal job results, and exposes those actions in the server management UI.
+
+This change must keep platform, run, plugin, and frontend ownership boundaries intact. Browser code must call platform APIs only; plugin pages and platform_web must not receive run credentials, raw host paths, raw AI keys, or direct sockets. Run-side lifecycle execution remains a bounded job executor and does not add unrestricted command execution.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add platform-mediated create/install, start, and stop workflow APIs for server instances.
+- Dispatch install/start/stop through existing job-channel records with stable lifecycle capabilities and idempotency keys.
+- Validate plugin installation state, lifecycle action references, run endpoint status/capabilities, server state, and config version before dispatch.
+- Project terminal lifecycle job results onto `ServerInstance.State`.
+- Add run-side lifecycle executor code that handles install/start/stop job assignments with bounded metadata-only results.
+- Add server management frontend contracts, API methods, form/actions, tests, and browser walkthrough evidence.
+- Keep plugin manifest and SDK capability enums aligned with lifecycle install support.
+
+**Non-Goals:**
+
+- No real game process execution, installer downloads, file writes, backups, update/restart workflows, or schedulers.
+- No authentication/authorization route group beyond existing service validation.
+- No direct plugin-to-run access, run sockets, raw host path exposure, raw credentials, billing, cloud host sales, or provider marketplace behavior.
+- No new database persistence layer, migrations, or distributed lease storage.
+- No replacement of the existing hash router or introduction of a frontend router dependency.
+
+## Decisions
+
+### Decision 1: Add workflow action routes beside existing resource routes
+
+The existing `POST /api/v1/server-instances` resource route remains a direct server instance record creation path. Workflow creation is added as `POST /api/v1/server-instances/workflows/create`, and lifecycle commands are added as `POST /api/v1/server-instances/{id}/start` and `POST /api/v1/server-instances/{id}/stop`.
+
+Alternative considered: change `POST /api/v1/server-instances` to return a workflow response and always dispatch install. Rejected because existing resource-route tests and clients use the direct create/list/detail contract, and explicit workflow routes make dispatching side effects clear.
+
+### Decision 2: Lifecycle jobs use fixed run capabilities
+
+Workflow dispatch maps create/install to `process.install`, start to `process.start`, and stop to `process.stop`. The plugin manifest schema, plugin SDK type union, platform validator allowlist, and run smoke/runtime capability list will include `process.install` so create workflows can be validated consistently.
+
+Alternative considered: use arbitrary plugin action JSON references as job capabilities. Rejected because claim matching already uses capability strings reported by run endpoints, and action references are plugin metadata rather than run capability names.
+
+### Decision 3: Platform service owns lifecycle validation and dispatch
+
+`platform/service.Core` adds explicit lifecycle methods that validate dependencies and state transitions, then create queued jobs with operator-provided idempotency keys. The service rejects stale `configVersion` values for start/stop commands.
+
+Alternative considered: let the frontend create jobs directly through generic `POST /api/v1/jobs`. Rejected because lifecycle state rules, plugin lifecycle action references, and config-version checks belong in the platform service, not the browser.
+
+### Decision 4: Terminal job results project instance state
+
+When a lifecycle job completes, the existing run job result path updates the job and then projects the terminal result onto the server instance: successful install makes the instance `ready`, successful start makes it `running`, successful stop makes it `stopped`, and failed/cancelled lifecycle jobs make the instance `failed`.
+
+Alternative considered: require a separate status polling endpoint from run before changing server state. Rejected for this first workflow because the job result is already the authoritative terminal signal in the current in-memory platform.
+
+### Decision 5: Run executor is bounded and metadata-only
+
+The run-side lifecycle executor accepts a claimed job assignment, supports only the fixed lifecycle capabilities, and returns bounded success/failure metadata without executing arbitrary local commands or returning paths.
+
+Alternative considered: execute plugin action definitions immediately. Rejected because scoped file/process execution semantics and plugin proof behavior belong to later changes.
+
+### Decision 6: Frontend uses platform APIs with local fallback data
+
+The server management page loads plugins, run endpoints, server instances, and jobs through typed API client methods, but retains safe seed data when the backend is not available. Create/start/stop buttons call workflow APIs and update local state from the returned instance/job.
+
+Alternative considered: keep the page as a static overview until a later acceptance suite. Rejected because this change's completion gate requires browser walkthrough of create/start/stop workflows.
+
+## Risks / Trade-offs
+
+- [Risk] Workflow APIs create jobs but the run executor still simulates lifecycle completion. Mitigation: name this as bounded lifecycle execution and test the dispatch/result/state contract; real process orchestration stays deferred.
+- [Risk] Idempotency keys are caller-provided, so poor clients can create repeated lifecycle jobs. Mitigation: validators require non-empty keys and the frontend generates per-action keys; service tests cover duplicate idempotency behavior through the existing job repository.
+- [Risk] Direct resource creation can still create `draft` instances without workflow dispatch. Mitigation: keep direct route documented as metadata creation and make the console use workflow routes for operational create.
+- [Risk] Instance state can remain unchanged while start/stop jobs are active because no `starting`/`stopping` states exist. Mitigation: the UI shows pending job state separately, and terminal job result projection updates the instance state.
+- [Risk] In-memory job/state projection can be lost on process restart. Mitigation: this repository currently uses in-memory storage; persistence and reconciliation remain future changes.
+
+## Migration Plan
+
+1. Add lifecycle domain, DTO, validation, service, API route, and documentation changes in `platform/`.
+2. Add `process.install` to plugin schema, SDK, platform validator, fixtures, and run smoke/runtime capability reporting.
+3. Add run lifecycle executor support and tests in `run/runtime`.
+4. Add frontend server management contracts, schemas, API methods, page interactions, tests, and styling in `platform_web/`.
+5. Verify with platform/run/frontend tests, structure check, strict OpenSpec validation, and browser walkthrough.
+
+Rollback is contained to this change before dependent work: remove workflow routes/service methods, lifecycle executor, frontend interactions, and capability enum additions. After dev plugin proof or acceptance suite depends on these routes, rollback must be handled by a new OpenSpec change.
+
+## Open Questions
+
+- Whether a future persistence change should add explicit `starting` and `stopping` states or keep active lifecycle status derived from jobs.
+- Whether restart/update/delete workflows should reuse the same response shape or introduce a richer lifecycle operation resource.
+- Whether lifecycle action execution should be interpreted by run directly or mediated through a plugin action runtime in the next plugin proof change.
@@ -0,0 +1,29 @@
+## Why
+
+Server management is the next first-party workflow after the console shell, plugin registry, run job channel, log ingest, and artifact transfer are available. Operators need a complete platform-mediated path to create a server instance from an installed game plugin, start it, stop it, and observe the resulting lifecycle state without exposing run internals to the browser or plugin pages.
+
+## What Changes
+
+- Add server lifecycle action APIs for create/install, start, and stop workflows.
+- Dispatch lifecycle work through the existing platform job channel using bounded job metadata and idempotency keys.
+- Enforce plugin, run endpoint, instance state, and optimistic config-version validation before lifecycle dispatch.
+- Project lifecycle job state back onto server instances so the platform and frontend can show actionable states.
+- Add frontend server management views and API client methods for create, start, stop, refresh, and workflow status.
+- Add run-side lifecycle executor support for installing, starting, and stopping server jobs without exposing host paths, raw credentials, or direct sockets.
+
+## Capabilities
+
+### New Capabilities
+
+- `server-management-workflows`: Platform-mediated server instance create, start, stop, and status workflows across `platform/`, `run/`, and `platform_web/`.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Affects `platform/` domain, DTO, validator, service, repository, API handlers, route docs, and protocol docs for server lifecycle operations.
+- Affects `run/` protocol/client/executor code for lifecycle job handling.
+- Affects `platform_web/` API types/client methods, route/page contracts, server management components, tests, and browser walkthrough.
+- Reuses existing game plugin registry, run control, run job, log ingest, and artifact transfer contracts; does not add billing, cloud host sales, raw AI key exposure, host-path exposure, or direct plugin-to-run access.
@@ -0,0 +1,79 @@
+## ADDED Requirements
+
+### Requirement: Server create workflow dispatches install job
+The platform SHALL provide a server create workflow that validates an installed game plugin, a compatible run endpoint, and a non-empty idempotency key before creating a server instance and dispatching a queued install job through the job channel.
+
+#### Scenario: Create workflow accepted
+- **WHEN** an operator submits a create workflow with an installed plugin, an online compatible run endpoint, a server name, and an idempotency key
+- **THEN** the platform MUST create a server instance in `installing` state and create a queued `process.install` job bound to that instance and run endpoint
+
+#### Scenario: Create workflow rejects invalid dependencies
+- **WHEN** an operator submits a create workflow with a missing plugin, disabled plugin, offline run endpoint, or run endpoint missing required capabilities
+- **THEN** the platform MUST reject the workflow and MUST NOT dispatch a lifecycle job
+
+### Requirement: Server start workflow dispatches start job
+The platform SHALL provide a start workflow for an existing server instance that validates the instance state, config version, plugin lifecycle action, run endpoint status, run endpoint capability, and idempotency key before dispatching a queued start job.
+
+#### Scenario: Start workflow accepted
+- **WHEN** an operator starts a `ready` or `stopped` server instance with the current config version and an idempotency key
+- **THEN** the platform MUST create a queued `process.start` job for the instance and return both the instance and job metadata
+
+#### Scenario: Start workflow rejects stale config
+- **WHEN** an operator starts a server instance with an expected config version that does not match the instance config version
+- **THEN** the platform MUST reject the workflow and MUST NOT dispatch a lifecycle job
+
+### Requirement: Server stop workflow dispatches stop job
+The platform SHALL provide a stop workflow for an existing running server instance that validates the instance state, config version, plugin lifecycle action, run endpoint status, run endpoint capability, and idempotency key before dispatching a queued stop job.
+
+#### Scenario: Stop workflow accepted
+- **WHEN** an operator stops a `running` server instance with the current config version and an idempotency key
+- **THEN** the platform MUST create a queued `process.stop` job for the instance and return both the instance and job metadata
+
+#### Scenario: Stop workflow rejects non-running instance
+- **WHEN** an operator stops a server instance that is not `running`
+- **THEN** the platform MUST reject the workflow and MUST NOT dispatch a lifecycle job
+
+### Requirement: Lifecycle job results update server instance state
+The platform SHALL project terminal lifecycle job results onto the associated server instance after accepting a run job result.
+
+#### Scenario: Install result marks ready
+- **WHEN** run completes a `process.install` lifecycle job successfully
+- **THEN** the platform MUST mark the associated server instance `ready`
+
+#### Scenario: Start result marks running
+- **WHEN** run completes a `process.start` lifecycle job successfully
+- **THEN** the platform MUST mark the associated server instance `running`
+
+#### Scenario: Stop result marks stopped
+- **WHEN** run completes a `process.stop` lifecycle job successfully
+- **THEN** the platform MUST mark the associated server instance `stopped`
+
+#### Scenario: Failed lifecycle result marks failed
+- **WHEN** run completes an install, start, or stop lifecycle job as failed or cancelled
+- **THEN** the platform MUST mark the associated server instance `failed`
+
+### Requirement: Run lifecycle executor is bounded
+The run executor SHALL support only declared lifecycle capabilities for install, start, and stop jobs and MUST return bounded metadata-only results without raw host paths, raw credentials, or direct socket details.
+
+#### Scenario: Supported lifecycle job handled
+- **WHEN** run receives a job assignment for `process.install`, `process.start`, or `process.stop`
+- **THEN** the lifecycle executor MUST produce a successful bounded result suitable for the job result channel
+
+#### Scenario: Unsupported lifecycle job rejected
+- **WHEN** run receives a job assignment for an unsupported lifecycle capability
+- **THEN** the lifecycle executor MUST return a failed bounded result without executing local commands
+
+### Requirement: Server management UI supports create start and stop
+The frontend SHALL expose server management controls that use platform workflow APIs to create, start, stop, and refresh server instances without receiving run credentials, raw host paths, raw AI keys, or direct sockets.
+
+#### Scenario: UI creates server workflow
+- **WHEN** an operator submits the server management create form
+- **THEN** the frontend MUST call the platform create workflow API and render the returned instance and lifecycle job status
+
+#### Scenario: UI starts and stops server
+- **WHEN** an operator clicks start or stop for an eligible server instance
+- **THEN** the frontend MUST call the matching platform workflow API with the current config version and render the returned lifecycle job status
+
+#### Scenario: UI refreshes workflow status
+- **WHEN** the server management page refreshes data
+- **THEN** the frontend MUST read server instances, jobs, plugins, and run endpoints through platform APIs and MUST NOT display raw secrets, host paths, run credentials, or direct sockets
@@ -0,0 +1,43 @@
+## 1. Platform Lifecycle Workflows
+
+- [x] 1.1 Add lifecycle domain, DTO, validator, and conversion contracts for create/start/stop workflow requests and responses.
+- [x] 1.2 Implement platform service methods for create/install, start, and stop workflow validation and job dispatch.
+- [x] 1.3 Project accepted terminal lifecycle job results onto server instance state.
+- [x] 1.4 Add platform HTTP routes and OpenAPI-style comments for create/start/stop lifecycle workflow actions.
+- [x] 1.5 Update platform route/protocol/domain documentation for implemented server lifecycle workflows.
+- [x] 1.6 Add platform service/API tests for accepted create/start/stop workflows, rejected invalid state/stale config, and lifecycle result state projection.
+
+## 2. Lifecycle Capabilities and Run Executor
+
+- [x] 2.1 Add `process.install` to plugin manifest schema, plugin SDK capability types, platform validation allowlists, examples, and fixtures where lifecycle install support is required.
+- [x] 2.2 Add run lifecycle executor support for bounded install/start/stop job handling without host paths, raw credentials, or direct sockets.
+- [x] 2.3 Add run tests for supported lifecycle jobs, unsupported lifecycle jobs, and smoke capability reporting.
+- [x] 2.4 Update run protocol/runtime documentation for lifecycle executor scope.
+
+## 3. Frontend Server Management
+
+- [x] 3.1 Add frontend API contracts and client methods for run endpoints, jobs, and create/start/stop server lifecycle workflows.
+- [x] 3.2 Add frontend server management view contracts and request builders outside page components.
+- [x] 3.3 Implement the server management page create form, refresh action, start/stop actions, pending job display, and safe fallback data.
+- [x] 3.4 Add frontend tests for API client calls and server management page rendering without unsafe fields.
+
+## 4. Verification
+
+- [x] 4.1 Run `go test ./...` from `platform/` and record evidence.
+- [x] 4.2 Run `go test ./...` from `run/` and record evidence.
+- [x] 4.3 Run `cd plugins && npm run typecheck && npm run test && npm run validate:manifest` and record evidence.
+- [x] 4.4 Run `cd platform_web && npm run typecheck && npm run test && npm run build` and record evidence.
+- [x] 4.5 Run browser walkthrough for server management create/start/stop UI at desktop and mobile widths.
+- [x] 4.6 Run `scripts/check-structure.sh` and record evidence.
+- [x] 4.7 Run `openspec validate implement-server-management-workflows --strict` and record evidence.
+
+## Evidence
+
+- 2026-07-03: `cd platform && go test ./...` passed after platform lifecycle service/API implementation.
+- 2026-07-03: `cd run && go test ./...` passed after run lifecycle executor implementation.
+- 2026-07-03: `cd plugins && npm run typecheck && npm run test && npm run validate:manifest` passed after adding `process.install`.
+- 2026-07-03: Frontend API client/contracts, server management view contracts, request builders, page workflow UI, styling, docs, and tests were updated for run endpoints, jobs, create/start/stop workflows, pending job display, and safe fallback data.
+- 2026-07-03: `cd platform_web && npm run typecheck && npm run test && npm run build` passed; Vitest reported 6 files / 14 tests passed and Vite built production assets.
+- 2026-07-03: Browser walkthrough via Chrome DevTools at `http://127.0.0.1:4173/#/servers` passed for desktop create/install, start, stop, no unsafe fields visible, and mobile single-column server workspace.
+- 2026-07-03: `scripts/check-structure.sh` passed.
+- 2026-07-03: `openspec validate implement-server-management-workflows --strict` passed.