first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,38 @@
+## Context
+
+The platform already supports registry-backed game plugins, marketplace projection, server lifecycle workflows, run-side lifecycle jobs, and browser-visible server controls. The missing piece is a concrete SCUM plugin package that follows those contracts instead of relying on the generic `game.example` development fixture.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Provide a SCUM plugin directory with manifest, create form schema, lifecycle action templates, and platform-hosted page declarations.
+- Keep lifecycle requests platform-mediated and safe: plugin metadata must expose only logical action refs, capabilities, page keys, and permissions.
+- Prove one SCUM plugin can be registered, discovered in the marketplace, and used to create at least two SCUM server instances.
+- Preserve the existing platform_web management console style and reuse the generic server/plugin surfaces.
+
+**Non-Goals:**
+
+- No real commercial SCUM binary download or production hosting orchestration.
+- No direct browser/plugin connection to run endpoints.
+- No cloud-provider, host-sales, billing, or unrelated marketplace behavior.
+
+## Decisions
+
+### Decision 1: SCUM plugin is a first-party local example plugin
+
+The plugin lives under `plugins/examples/scum-server-plugin` and follows the same manifest and validation schema as other game management plugins.
+
+### Decision 2: Lifecycle templates use safe local fixture commands
+
+The action templates use bounded executable names and arguments accepted by the run lifecycle executor. They prove install/start/stop wiring without exposing real host paths or requiring a SCUM dedicated server binary.
+
+### Decision 3: Platform and frontend reuse existing plugin contracts
+
+No new platform_web route or visual system is introduced. The SCUM plugin declares overview/config/log pages, and the existing marketplace/server management/plugin bridge surfaces render those declarations with the current theme-aware console components.
+
+## Risks / Mitigations
+
+- [Risk] The SCUM proof could be mistaken for production SCUM hosting. Mitigation: describe it as a local fixture plugin and keep action templates bounded.
+- [Risk] Adding another plugin could drift from manifest safety rules. Mitigation: default validation now checks both example and SCUM manifests.
+- [Risk] Browser-facing surfaces could expose unsafe details. Mitigation: local debug smoke rejects forbidden fragments from registration, marketplace, server, job, log, and artifact responses.
@@ -0,0 +1,22 @@
+## Why
+
+The current lifecycle proof uses the generic development plugin, but operators need a concrete SCUM server plugin that can be discovered from the plugin marketplace and used to create multiple SCUM server instances through the platform-mediated lifecycle path.
+
+## What Changes
+
+- Add a first-party local SCUM server plugin directory under `plugins/examples/scum-server-plugin`.
+- Copy the existing safe plugin lifecycle pattern into SCUM-specific manifest metadata, create-form schema, plugin pages, and lifecycle action templates.
+- Update plugin validation so both the development plugin and SCUM plugin are validated by default.
+- Extend local debug smoke coverage so the plugin marketplace can discover the SCUM plugin and the platform can create multiple SCUM server instances from it.
+
+## Capabilities
+
+### New Capabilities
+
+- `scum-server-plugin`: Provides a local SCUM game management plugin discoverable through the plugin marketplace and usable for multi-instance platform-mediated lifecycle workflows.
+
+## Impact
+
+- Affects `plugins/` example plugin assets, manifest validation, and tests.
+- Affects `scripts/local-debug-smoke.sh` registration and API proof data.
+- Does not add billing, cloud host sales, unrelated SaaS marketplace behavior, direct plugin-run transport, raw credentials, direct sockets, or raw host paths.
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: SCUM plugin package
+The repository SHALL include a first-party local SCUM server plugin package with manifest metadata, create-form schema, lifecycle action templates, and plugin page declarations.
+
+#### Scenario: SCUM manifest validates
+- **WHEN** plugin manifest validation runs with default targets
+- **THEN** it MUST validate the SCUM plugin manifest and reject unsafe raw host paths, direct run sockets, bearer credentials, passwords, raw AI keys, and undeclared transport details
+
+### Requirement: SCUM plugin marketplace discovery
+The platform SHALL be able to register the SCUM plugin manifest and project it into the plugin marketplace using safe platform registry metadata.
+
+#### Scenario: SCUM plugin is discoverable
+- **WHEN** the SCUM plugin manifest is registered through platform APIs
+- **THEN** `GET /api/v1/plugin-marketplace/plugins?serverType=scum&keyword=scum` MUST include the SCUM plugin without exposing unsafe fields
+
+### Requirement: SCUM multi-instance creation
+The platform SHALL allow the SCUM plugin to create multiple independent SCUM server instances through the existing platform-mediated server lifecycle workflow.
+
+#### Scenario: Two SCUM servers are created from one plugin
+- **WHEN** local debug proof creates two server instances using the SCUM plugin
+- **THEN** both instances MUST have distinct IDs and names, share the SCUM plugin association, and receive independent lifecycle install jobs
@@ -0,0 +1,50 @@
+## 1. SCUM Plugin Assets
+
+- [x] 1.1 Add `plugins/examples/scum-server-plugin` with SCUM manifest metadata, create-form schema, pages, and lifecycle action templates.
+- [x] 1.2 Ensure plugin manifest validation accepts the SCUM plugin and still rejects unsafe transport/credential/path content.
+
+## 2. Discovery and Multi-Instance Proof
+
+- [x] 2.1 Update local debug smoke registration to register SCUM plugin metadata through platform APIs.
+- [x] 2.2 Update local debug smoke creation proof to create two SCUM servers from the SCUM plugin and verify marketplace discovery.
+
+## 3. Verification
+
+- [x] 3.1 Run `cd plugins && npm run typecheck && npm run test && npm run validate:manifest`.
+- [x] 3.2 Run `scripts/check-structure.sh`.
+- [x] 3.3 Run `openspec validate implement-scum-server-plugin --strict`.
+- [x] 3.4 Run focused platform/platform_web checks and a browser walkthrough if UI behavior changes beyond existing generic surfaces.
+
+## Evidence
+
+- Plugin validation:
+  - `cd plugins && npm run typecheck` passed.
+  - `cd plugins && npm run test` passed: `tests/manifest-validation.test.ts` passed 12 tests, including SCUM manifest validation.
+  - Initial sandbox `cd plugins && npm run validate:manifest` failed because `tsx` could not create its local IPC pipe (`EPERM`); escalated rerun passed.
+  - `cd plugins && npm run validate:manifest` validated both `examples/dev-game-plugin/manifest.json` and `examples/scum-server-plugin/manifest.json`.
+
+- SCUM plugin implementation:
+  - Added `plugins/examples/scum-server-plugin/manifest.json` with `game.scum`, server type `scum`, SCUM-specific marketplace metadata, lifecycle actions, bridge actions, permissions, plugin pages, and AI purposes.
+  - Added `plugins/examples/scum-server-plugin/schemas/create-form.schema.json` with SCUM server name, game port, query port, and max-player fields.
+  - Added scoped lifecycle fixtures under `plugins/examples/scum-server-plugin/actions/` for install/start/stop/restart/status using safe bounded command templates.
+  - Updated `plugins/package.json`, `plugins/tests/manifest-validation.test.ts`, and `scripts/check-structure.sh` so SCUM plugin assets are part of default validation.
+
+- API/local debug proof:
+  - Updated `scripts/local-debug-smoke.sh` to register `game.scum` through `/api/v1/game-plugins/register-manifest`.
+  - Updated smoke proof to create `scum-alpha` and `scum-beta` through `/api/v1/server-instances/workflows/create`.
+  - Initial smoke against `18080` failed because that port was already occupied by stale state. Isolated rerun on `18087` with `LOCAL_DEBUG_ROOT=/private/tmp/browser-scum-local-debug-proof-2` passed.
+  - Passing smoke evidence directory: `/private/tmp/browser-scum-local-debug-proof-2/smoke`.
+  - Smoke verified `/api/v1/plugin-marketplace/plugins?serverType=scum&keyword=scum` contains `game.scum`, and both SCUM instances have separate lifecycle install job records.
+
+- Browser walkthrough:
+  - Started an isolated browser verification stack on platform `127.0.0.1:18088` and frontend `127.0.0.1:5188`.
+  - Seeded the stack with `LOCAL_DEBUG_SELF_START=false LOCAL_DEBUG_PLATFORM_PORT=18088 LOCAL_DEBUG_WEB_PORT=5188 LOCAL_DEBUG_ROOT=/private/tmp/browser-scum-browser-proof scripts/local-debug-smoke.sh`; smoke passed.
+  - Logged into `http://127.0.0.1:5188/` as `operator.local@example.test / operator-local`; 首页 showed API-backed platform data and `game.scum: 2 个实例`.
+  - 插件市场 showed `SCUM Server`, `game.scum`, status `已安装`, server type `scum`, and capabilities `process.install`, `process.start`, `process.stop`; no local fallback or forbidden fragments were visible.
+  - 服务器管理 showed `SCUM Alpha` (`scum-alpha`) and `SCUM Beta` (`scum-beta`) as separate server cards; no local fallback or forbidden fragments were visible.
+  - Opened `#/servers/scum-alpha`, confirmed plugin binding `game.scum@0.1.0`, started the server via the visible `启动` control, confirmed the dialog, and observed `SCUM Alpha` change to `运行中` / `在线` with `停止` enabled.
+
+- Final gates:
+  - `bash -n scripts/local-debug-smoke.sh` passed.
+  - `scripts/check-structure.sh` passed with `structure check passed`.
+  - `openspec validate implement-scum-server-plugin --strict` passed with `Change 'implement-scum-server-plugin' is valid`; PostHog telemetry flush reported `ENOTFOUND edge.openspec.dev`, which did not affect validation.