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,68 @@
+## Context
+
+The platform already has a basic `GamePlugin` resource in `platform/` and an initial JSON Schema validator in `plugins/`. Those pieces are not yet enough for the plugin marketplace and server creation backlog because registration can still be assembled by hand instead of coming from a validated game management plugin manifest.
+
+This change covers the first registry boundary between `plugins/` and `platform/`: plugin authors validate manifest files in the plugin workspace, while the platform accepts a structured manifest registration payload, validates the same safety constraints in backend validators, stores only registry metadata, and exposes that metadata through the existing game plugin APIs.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Define one concrete manifest contract for game management plugins.
+- Reject unsafe manifest requests for raw run, host path, credential, socket, and raw AI key access.
+- Register installed plugins from manifest metadata through platform DTO/service/API layers.
+- Keep registry responses useful for plugin marketplace display without exposing raw paths, raw credentials, run internals, or AI provider keys.
+- Add focused schema, validator, service, and API tests.
+
+**Non-Goals:**
+
+- Do not implement plugin page bridge runtime, plugin action execution, or SDK transport.
+- Do not add billing, cloud host sales, provider marketplaces, or unrelated SaaS marketplace behavior.
+- Do not make platform import TypeScript plugin validation code or plugin workspace files directly.
+- Do not implement frontend plugin marketplace pages in this change.
+
+## Decisions
+
+### Decision 1: Use a copied manifest contract at the root boundary
+
+`plugins/` owns the JSON Schema and TypeScript validation helper. `platform/` owns named DTOs and domain types that mirror the externally submitted manifest shape. The two roots are kept aligned by tests and OpenSpec requirements rather than direct imports.
+
+Alternative considered: have platform read `plugins/manifests/game-plugin.manifest.schema.json` directly. Rejected because that would make the backend depend on the plugin workspace file layout and blur root ownership.
+
+### Decision 2: Platform registration converts manifests to existing registry metadata
+
+The platform will add a manifest registration service/API path that converts a validated manifest into `GamePlugin` registry metadata. The existing create/list/detail endpoints remain available for low-level metadata tests and future migration, while the new manifest endpoint is the supported installation boundary for plugin manifests.
+
+Alternative considered: replace `GamePluginCreateRequest` with the manifest shape. Rejected because existing server-management tests and API contracts already use the metadata resource directly.
+
+### Decision 3: Deny unsafe permissions by explicit allowlists and substring checks
+
+Plugin manifests may declare scoped permissions such as server lifecycle, file, log, artifact, and platform-mediated AI permissions. They must not declare direct run sockets, raw host paths, raw credentials, raw AI keys, provider keys, or direct run credentials. `plugins/` catches these during schema/test validation and `platform/` repeats the safety validation before registry insertion.
+
+Alternative considered: rely only on JSON Schema enum restrictions. Rejected because unsafe intent can appear in action paths, capability names, or future fields; backend validation still needs an explicit defense.
+
+### Decision 4: Registry metadata is marketplace-ready but not commerce-oriented
+
+Registry responses include identity, version, server type/display name, manifest/schema references, required run capabilities, permissions, pages, and AI purposes. They intentionally exclude pricing, cloud host purchase flows, and provider marketplace concepts.
+
+Alternative considered: add a richer marketplace catalog model now. Rejected because the repository scope is game server management, and later UI can derive its first catalog view from registry metadata.
+
+## Risks / Trade-offs
+
+- [Risk] The plugin manifest contract may evolve when plugin bridge work starts. Mitigation: keep this change focused on registry metadata and add bridge-specific fields in the next OpenSpec change.
+- [Risk] Duplicating contract shapes across TypeScript and Go can drift. Mitigation: tests cover the example manifest and platform manifest registration until a generated contract package is introduced.
+- [Risk] Strict allowlists can reject useful future plugin capabilities. Mitigation: add new allowed capability/permission keys through explicit OpenSpec changes.
+
+## Migration Plan
+
+1. Add plugin schema restrictions, fixtures, and validation tests while keeping the development example valid.
+2. Add platform manifest DTO/domain conversion, validators, service registration, and API route tests.
+3. Keep existing `POST /api/v1/game-plugins` metadata creation working for current tests.
+4. Validate the change with plugin tests, platform tests, structure check, and strict OpenSpec validation.
+
+Rollback during this phase is straightforward: remove the manifest registration route and schema/test additions before downstream plugin bridge work depends on them.
+
+## Open Questions
+
+- Whether manifest contract generation should be added in the plugin bridge change or a later contract-generation change.
+- Whether registry metadata should eventually support signed manifest artifacts before plugin publish/install workflows are implemented.
@@ -0,0 +1,27 @@
+## Why
+
+Plugin installability is now the next platform dependency: server creation, plugin marketplace display, and plugin bridge work all need a trusted registry of game management plugin manifests. This change adds the manifest validation and registry surface so only safe, well-formed plugins become available to the platform.
+
+## What Changes
+
+- Define the first plugin manifest contract for game management plugins, including identity, server type, create form schema, lifecycle actions, run capabilities, UI contribution, and scoped permissions.
+- Add manifest validation in `plugins/` with schema fixtures and tests for valid and unsafe manifests.
+- Add platform domain, repository, service, DTO, validator, and API handling for registering, listing, and inspecting installed plugin metadata.
+- Reject or disable unsafe manifest requests such as raw host paths, direct run sockets, raw credentials, or raw AI provider keys.
+- Keep plugin marketplace metadata focused on game server management plugins, not billing, cloud host sales, or unrelated SaaS marketplace features.
+
+## Capabilities
+
+### New Capabilities
+
+- `plugin-registry-and-manifest-validation`: Validates game management plugin manifests and exposes installed plugin registry metadata through platform APIs.
+
+### Modified Capabilities
+
+- None. This change builds on the bootstrap plugin and platform-core constraints, which have not yet been archived into `openspec/specs/`.
+
+## Impact
+
+- Affects `plugins/` manifest schemas, fixtures, SDK-adjacent types, and validation tests.
+- Affects `platform/` plugin domain, DTOs, models, repositories, services, validators, routes, and API tests.
+- Adds or updates verification commands for plugin schema tests, platform API tests, `scripts/check-structure.sh`, and strict OpenSpec validation.
@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Manifest Schema Validation
+The plugin workspace SHALL validate game management plugin manifests with a JSON Schema that defines identity, version, plugin kind, server type, create form schema reference, run capabilities, lifecycle actions, optional pages, AI purposes, and scoped permissions.
+
+#### Scenario: Development plugin manifest validates
+- **WHEN** the development game plugin manifest is validated by the plugin workspace validator
+- **THEN** validation MUST pass and its referenced create form schema MUST also validate
+
+#### Scenario: Unsafe manifest fails validation
+- **WHEN** a manifest requests direct run sockets, host paths, raw credentials, raw AI keys, or direct provider key access
+- **THEN** validation MUST return violations and MUST NOT treat the plugin as installable
+
+### Requirement: Platform Manifest Registration
+The platform SHALL expose a manifest registration API that accepts a structured game plugin manifest payload and converts it into installed plugin registry metadata.
+
+#### Scenario: Valid manifest is registered
+- **WHEN** a valid game management plugin manifest is submitted to the platform registration API
+- **THEN** the platform MUST persist an installed plugin record with manifest reference, create form schema reference, server type, required run capabilities, scoped permissions, pages, and AI purposes
+
+#### Scenario: Duplicate plugin registration is rejected
+- **WHEN** a manifest is submitted for an already registered plugin ID
+- **THEN** the platform MUST return a duplicate error and MUST preserve the existing registry record
+
+### Requirement: Registry Query Surface
+The platform SHALL expose plugin registry list and detail responses suitable for the plugin marketplace and server creation workflows.
+
+#### Scenario: Marketplace lists installed plugins
+- **WHEN** platform clients list game plugins by status or server type
+- **THEN** each response item MUST include plugin identity, version, server type/display metadata, manifest/schema references, run capabilities, scoped permissions, pages, AI purposes, and install status
+
+#### Scenario: Registry detail excludes unsafe internals
+- **WHEN** platform clients fetch one registered plugin
+- **THEN** the response MUST NOT include raw host paths, raw credentials, run connection details, or raw AI provider keys
+
+### Requirement: Backend Safety Validation
+The platform SHALL independently validate plugin manifest safety before registry persistence, regardless of plugin workspace validation results.
+
+#### Scenario: Raw key request reaches platform
+- **WHEN** a registration payload contains raw AI key, provider key, bearer token, or secret-like content
+- **THEN** the platform MUST reject the registration with a validation error
+
+#### Scenario: Direct run or host path request reaches platform
+- **WHEN** a registration payload contains direct run socket, direct run credential, or raw host path access requests
+- **THEN** the platform MUST reject the registration with a validation error
+
+### Requirement: Ownership Boundary Preservation
+The manifest registry implementation SHALL keep `plugins/` validation code and `platform/` backend code in their own roots and share contract shapes only through named DTO/domain/schema files.
+
+#### Scenario: Platform validates registration
+- **WHEN** platform code handles manifest registration
+- **THEN** it MUST use platform DTOs, domain types, and validators rather than importing plugin workspace implementation files
@@ -0,0 +1,68 @@
+## 1. Plugin Manifest Validation
+
+- [x] 1.1 Extend the plugin manifest schema and SDK-adjacent types with registry metadata, lifecycle actions, pages, AI purposes, artifacts permission, and explicit safe permission/capability allowlists.
+- [x] 1.2 Extend `plugins/scripts/validate-manifest.ts` to reject unsafe raw host path, direct run, raw credential, and raw AI/provider key requests beyond JSON Schema shape validation.
+- [x] 1.3 Add plugin validation fixtures/tests for the valid development manifest, invalid create form schema, and unsafe manifest requests.
+
+## 2. Platform Registry Contracts
+
+- [x] 2.1 Add platform domain, DTO, model, copy, and conversion contracts for game plugin manifest registration metadata including server display metadata, pages, AI purposes, and validation violations.
+- [x] 2.2 Add platform validator rules for manifest registration, allowed permissions/capabilities, unsafe string detection, duplicate-free lists, and registry response safety.
+- [x] 2.3 Add service and repository behavior that registers a manifest as an installed game plugin while preserving existing metadata create/list/detail behavior.
+
+## 3. Platform Registry API
+
+- [x] 3.1 Add a manifest registration endpoint under the game plugin API surface using named DTOs and the core service.
+- [x] 3.2 Extend game plugin list/detail responses with registry metadata required by marketplace and server creation workflows.
+- [x] 3.3 Add platform API/service/validator tests for valid manifest registration, duplicate rejection, filtering, unsafe manifest rejection, and no raw internal/key fields in responses.
+
+## 4. Documentation And Handoff
+
+- [x] 4.1 Update platform route/protocol documentation and plugin documentation to describe manifest validation and registry registration boundaries.
+- [x] 4.2 Add a fresh-chat handoff block for this change.
+
+## 5. Verification
+
+- [x] 5.1 Run `npm test` from `plugins/` and record evidence.
+- [x] 5.2 Run `npm run typecheck` from `plugins/` and record evidence.
+- [x] 5.3 Run `go test ./...` from `platform/` and record evidence.
+- [x] 5.4 Run `scripts/check-structure.sh` and record evidence.
+- [x] 5.5 Run `openspec validate implement-plugin-registry-and-manifest-validation --strict` and record evidence.
+
+## Evidence
+
+- 2026-07-03: `npm test` from `plugins/` passed with 4 manifest/SDK tests.
+- 2026-07-03: `npm run typecheck` from `plugins/` passed.
+- 2026-07-03: `go test ./...` from `platform/` passed across api, config, domain, dto, model, repo, service, and validator packages.
+- 2026-07-03: `scripts/check-structure.sh` passed with `structure check passed`.
+- 2026-07-03: `openspec validate implement-plugin-registry-and-manifest-validation --strict` passed with `Change 'implement-plugin-registry-and-manifest-validation' is valid`.
+
+## Fresh-Chat Handoff
+
+```text
+Implement OpenSpec change: implement-plugin-registry-and-manifest-validation
+
+Scope:
+- Implement only openspec/changes/implement-plugin-registry-and-manifest-validation/.
+- Preserve root ownership boundaries in AGENTS.md.
+- Do not add billing, cloud host sales, agent-provider/cloud-provider workflows, or unrelated marketplace features.
+
+Read first:
+- AGENTS.md
+- openspec/changes/bootstrap-game-server-platform-architecture/proposal.md
+- openspec/changes/bootstrap-game-server-platform-architecture/design.md
+- openspec/changes/bootstrap-game-server-platform-architecture/specs/game-plugin-system/spec.md
+- openspec/changes/bootstrap-game-server-platform-architecture/specs/game-server-platform-core/spec.md
+- openspec/changes/implement-plugin-registry-and-manifest-validation/proposal.md
+- openspec/changes/implement-plugin-registry-and-manifest-validation/design.md
+- openspec/changes/implement-plugin-registry-and-manifest-validation/specs/plugin-registry-and-manifest-validation/spec.md
+- openspec/changes/implement-plugin-registry-and-manifest-validation/tasks.md
+
+Required closure:
+- Complete task checkboxes only after evidence exists.
+- Run `npm test` and `npm run typecheck` from `plugins/`.
+- Run `go test ./...` from `platform/`.
+- Run `scripts/check-structure.sh`.
+- Run `openspec validate implement-plugin-registry-and-manifest-validation --strict`.
+- Stop after this change is closed; do not start the next backlog item unless explicitly asked.
+```