69 lines
5.4 KiB
Markdown
69 lines
5.4 KiB
Markdown
## 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.
|