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-06
@@ -0,0 +1,60 @@
+## Context
+
+The platform can validate and register game plugin manifests, and the frontend already has the first-party Plugin Marketplace area. The remaining gap is that the page is not yet an authoritative view over platform registry data. This change makes the marketplace page API-driven while keeping commerce concepts out of scope.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Expose marketplace list and detail data from platform registry metadata.
+- Let operators filter installed game management plugins by status, server type, keyword, and capability.
+- Allow safe install/enable/disable state changes without exposing implementation internals.
+- Centralize frontend API types and client methods outside page-local hidden types.
+- Add tests and browser walkthrough evidence for loading, errors, filtering, install/state actions, and no-secret rendering.
+
+**Non-Goals:**
+
+- No billing, pricing, cloud host sales, provider marketplace, ratings, reviews, checkout, or subscription behavior.
+- No plugin page execution, bridge transport, run-side action execution, or AI invocation implementation.
+- No raw host paths, direct run sockets, raw credentials, or raw AI provider keys in responses.
+- No new visual system that replaces the platform_web theme.
+
+## Decisions
+
+### Decision 1: Marketplace data is a view over installed registry metadata
+
+Marketplace APIs will project installed plugin metadata into list/detail DTOs. The response includes identity, version, server type, status, description, pages, capabilities, permissions, and AI purposes, but not commerce data or backend internals.
+
+Alternative considered: create a separate catalog model with publish/store metadata. Rejected because this repository is a game server management platform, and current needs are covered by installed registry data.
+
+### Decision 2: Install and state actions remain metadata-only
+
+Install/enable/disable actions update platform plugin registry state and return the updated marketplace DTO. They do not download external packages or execute run jobs in this change.
+
+Alternative considered: trigger package download and runtime deployment from the marketplace page. Rejected because package acquisition and run execution require separate explicit changes.
+
+### Decision 3: Frontend fallback is isolated to development
+
+The page may keep a clearly isolated local fallback for standalone frontend development, but production flow prefers API data and shows API errors. Tests assert fallback does not leak into successful API flows.
+
+Alternative considered: remove all fallback state immediately. Rejected because local frontend demos still need useful data when the backend is absent.
+
+## Risks / Trade-offs
+
+- [Risk] Marketplace APIs duplicate some game plugin list/detail behavior. Mitigation: implement them as service projections over the same registry metadata.
+- [Risk] Install state can be confused with package acquisition. Mitigation: name docs and DTO fields around installed/active registry state only.
+- [Risk] Frontend state can drift from backend after actions. Mitigation: action methods return updated DTOs and tests cover refresh/update behavior.
+
+## Migration Plan
+
+1. Add platform marketplace DTOs, validators, service projection, routes, and docs.
+2. Update frontend API contracts and marketplace page to consume API data.
+3. Add backend and frontend tests.
+4. Run browser walkthrough, structure check, and strict OpenSpec validation.
+
+Rollback before dependent changes is removal of marketplace projection routes/page API integration and this change's artifacts.
+
+## Open Questions
+
+- Whether future plugin package publication should use signed artifacts or an internal admin upload flow.
+- Whether marketplace sorting should later incorporate operational health or compatibility scores.
@@ -0,0 +1,27 @@
+## Why
+
+The plugin registry and bridge contracts exist, but the plugin marketplace page still needs to be driven by platform API data instead of hardcoded catalog state. Operators need to browse installed game management plugins, inspect manifest-backed capabilities, and start install/enable workflows without exposing host paths, run sockets, credentials, or raw AI provider keys.
+
+## What Changes
+
+- Add marketplace-focused API responses derived from installed game plugin registry metadata.
+- Add platform service and handler behavior for listing marketplace plugins, viewing detail, and changing install/enable state through safe metadata workflows.
+- Replace production hardcoded marketplace data in `platform_web` with API client calls, typed contracts, loading/error states, filters, and plugin detail/install actions.
+- Preserve the magical-girl crystal-moonlight console visual direction while keeping the marketplace operational and game-management focused.
+- Add backend, frontend, browser walkthrough, structure, and strict OpenSpec verification.
+
+## Capabilities
+
+### New Capabilities
+
+- `plugin-marketplace-api-driven-ui`: Platform and frontend workflows for rendering the plugin marketplace from registry APIs and managing installed plugin state safely.
+
+### Modified Capabilities
+
+- Builds on `plugin-registry-and-manifest-validation` and `plugin-bridge-and-sdk`; it does not change their archived contracts directly.
+
+## Impact
+
+- Affects `platform/` game plugin DTOs, service, validators, API routes, and docs.
+- Affects `platform_web/` API types/client methods, plugin marketplace page/components, and tests.
+- Does not add billing, cloud host sales, provider marketplaces, unrelated SaaS marketplace behavior, direct plugin-run access, or raw key exposure.
@@ -0,0 +1,57 @@
+## ADDED Requirements
+
+### Requirement: Marketplace APIs expose registry-backed plugin catalog data
+
+The platform SHALL expose marketplace list and detail APIs derived from installed game plugin registry metadata.
+
+#### Scenario: Marketplace list returns installed plugin data
+- **WHEN** a client requests marketplace plugins with optional status, server type, capability, or keyword filters
+- **THEN** the platform MUST return bounded plugin summaries with identity, version, display metadata, server type, install status, capabilities, pages, permissions, and AI purposes
+
+#### Scenario: Marketplace detail returns safe plugin metadata
+- **WHEN** a client requests one marketplace plugin detail
+- **THEN** the platform MUST return manifest-backed metadata and MUST NOT expose raw host paths, direct run sockets, raw credentials, platform auth storage, storage backend credentials, or raw AI provider keys
+
+### Requirement: Marketplace state actions are platform-mediated
+
+The platform SHALL provide safe marketplace actions for changing installed plugin state without external package download or run execution.
+
+#### Scenario: Plugin is enabled or disabled
+- **WHEN** an operator enables or disables a marketplace plugin
+- **THEN** the platform MUST validate the plugin ID, update registry state, and return the redacted marketplace plugin detail
+
+#### Scenario: Unknown plugin action is rejected
+- **WHEN** an operator submits a state action for a missing plugin ID or unsupported action
+- **THEN** the platform MUST return a stable JSON error and MUST NOT change other plugin state
+
+### Requirement: Marketplace frontend uses centralized API contracts
+
+The frontend SHALL keep marketplace API types and client methods in `platform_web/api` and SHALL use them from the plugin marketplace page.
+
+#### Scenario: Page loads marketplace data
+- **WHEN** the Plugin Marketplace page renders with a reachable backend
+- **THEN** it MUST fetch plugin summaries from the marketplace API and render loading, error, empty, and populated states
+
+#### Scenario: Page filters and opens detail
+- **WHEN** an operator filters or selects a plugin
+- **THEN** the page MUST use API-backed data to update the list/detail view without relying on hidden page-local DTO contracts
+
+### Requirement: Marketplace UI preserves safety and theme constraints
+
+The Plugin Marketplace page SHALL preserve the platform_web magical-girl crystal-moonlight operations console style and avoid unsafe or unrelated marketplace concepts.
+
+#### Scenario: UI renders plugin cards and actions
+- **WHEN** marketplace data is displayed
+- **THEN** the UI MUST show game plugin metadata, capability tags, status controls, and install/enable actions without billing, cloud host sales, provider marketplace, raw secrets, or generic SaaS storefront behavior
+
+#### Scenario: Browser walkthrough verifies no secret rendering
+- **WHEN** frontend marketplace behavior is claimed complete
+- **THEN** a browser walkthrough MUST verify the page renders API-backed plugin data and visible text excludes raw credential markers
+
+### Requirement: Marketplace implementation is verified
+
+The change SHALL include backend tests, frontend tests/build, browser walkthrough evidence, structure validation, and strict OpenSpec validation.
+
+#### Scenario: Verification commands pass
+- **WHEN** the change is complete
+- **THEN** platform tests, platform_web tests/typecheck/build, `scripts/check-structure.sh`, and `openspec validate implement-plugin-marketplace-api-driven-ui --strict` MUST pass
@@ -0,0 +1,42 @@
+## 1. Platform Marketplace Contracts
+
+- [x] 1.1 Add marketplace plugin summary/detail DTOs and domain projection contracts from registered plugin metadata.
+- [x] 1.2 Add validators for marketplace filters, plugin IDs, bounded list responses, supported state actions, and response safety.
+- [x] 1.3 Add service methods for marketplace list, detail, install-state projection, and enable/disable actions.
+
+## 2. Platform Marketplace API
+
+- [x] 2.1 Implement marketplace list and detail routes under the platform API surface.
+- [x] 2.2 Implement safe install/enable/disable state action routes without package download or run execution.
+- [x] 2.3 Update platform route/protocol documentation for marketplace APIs and deferred package/runtime behavior.
+- [x] 2.4 Add platform service/API tests for filters, detail, state actions, missing plugins, unsupported actions, and no-secret responses.
+
+## 3. Frontend Marketplace API Integration
+
+- [x] 3.1 Add centralized `platform_web/api` marketplace types and `PlatformApiClient` methods.
+- [x] 3.2 Update Plugin Marketplace page to load API data, support filters/search/detail, and render loading/error/empty/populated states.
+- [x] 3.3 Wire install/enable/disable controls to API actions and update page state from API responses.
+- [x] 3.4 Isolate any local fallback data to standalone development and keep production API flow authoritative.
+- [x] 3.5 Add frontend tests for loading, errors, filters, detail selection, state actions, and no raw key/path rendering.
+
+## 4. Verification
+
+- [x] 4.1 Run `cd platform && go test ./...` and record evidence.
+- [x] 4.2 Run `cd platform_web && npm run typecheck && npm test && npm run build` and record evidence.
+- [x] 4.3 Run browser walkthrough for the Plugin Marketplace API-driven page and record evidence.
+- [x] 4.4 Run `scripts/check-structure.sh` and record evidence.
+- [x] 4.5 Run `openspec validate implement-plugin-marketplace-api-driven-ui --strict` and record evidence.
+
+## Evidence
+
+- 2026-07-06: `cd platform && go test ./domain ./dto ./validator ./service ./api` passed after adding marketplace contracts, validators, service methods, and routes.
+- 2026-07-06: `cd platform && go test ./service ./api -run 'TestCoreServiceMarketplacePluginsAreFilteredSafeAndStateful|TestPluginMarketplaceAPIListsDetailsAndChangesStateSafely|TestGamePluginManifestRegistryAPI'` passed, covering filters, detail, install/enable/disable state actions, missing plugins, unsupported actions, unsafe filters, and no-secret API response assertions.
+- 2026-07-06: `cd platform_web && npm run typecheck` passed after adding marketplace API types/client methods and the API-driven Plugins page.
+- 2026-07-06: `cd platform_web && npm test -- --run api/client.test.ts pages/PluginsPage.test.tsx pages/ConsolePages.test.tsx` passed, covering marketplace client URLs/actions, loading/error/API-backed detail rendering, standalone fallback labeling, state controls, and no raw key/path fragments.
+- 2026-07-06: `cd platform && go test ./...` passed.
+- 2026-07-06: `cd platform_web && npm test` passed with 10 files / 36 tests.
+- 2026-07-06: `cd platform_web && npm run typecheck` passed.
+- 2026-07-06: `cd platform_web && npm run build` passed.
+- 2026-07-06: Browser walkthrough against `http://127.0.0.1:5176/#/plugins` and platform API `127.0.0.1:18089` rendered API-backed `Example Server`, `logs.query`, `平台 API`, successfully applied the disable state action, and verified `/Users/`, `unix://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, and `billing` were absent from visible text.
+- 2026-07-06: `scripts/check-structure.sh` passed.
+- 2026-07-06: `openspec validate implement-plugin-marketplace-api-driven-ui --strict` passed; PostHog telemetry flush logged a restricted-network DNS error after local validation succeeded.