76 lines
5.3 KiB
Markdown
76 lines
5.3 KiB
Markdown
## Context
|
|
|
|
The repository has the required project roots and architecture contracts, but there is no executable backend, run executor, frontend app, plugin SDK package, or common check command. Future changes need a stable local development baseline so every OpenSpec implementation can run tests and builds in the same way.
|
|
|
|
The local environment currently has Go 1.25.1, Node 22.17.0, and npm 11.6.1. This change uses those tool families without adding business behavior beyond minimal health or placeholder shells.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Add separate Go module baselines under `platform/` and `run/`.
|
|
- Add minimal executable entry points and tests for both Go roots.
|
|
- Add a Vite React TypeScript baseline under `platform_web/` with required route/page placeholders and a browser-verifiable shell.
|
|
- Add a TypeScript/npm baseline under `plugins/` for manifest schema validation, SDK exports, example fixtures, and tests.
|
|
- Add root orchestration scripts that run all baseline checks while keeping implementation code inside the owning roots.
|
|
- Document development commands and update structure checks for new required baseline files.
|
|
|
|
**Non-Goals:**
|
|
|
|
- No platform database implementation.
|
|
- No real platform API resource behavior beyond minimal health/bootstrap endpoints needed to prove the server starts.
|
|
- No run job execution, log ingest, artifact transfer, or game server lifecycle work.
|
|
- No plugin marketplace behavior or hosted plugin page runtime.
|
|
- No production deployment packaging.
|
|
|
|
## Decisions
|
|
|
|
### Decision 1: Use separate Go modules for `platform/` and `run/`
|
|
|
|
`platform/` and `run/` SHALL each own a Go module, command entry point, internal packages, config loading, and tests. They must not import code from each other. Protocol sharing stays in documented contract files until a later OpenSpec introduces generated contracts.
|
|
|
|
Alternative considered: one root Go module for both backend roots. Rejected because it would make casual cross-root imports too easy and weaken the ownership boundary required by `AGENTS.md`.
|
|
|
|
### Decision 2: Use Vite, React, and TypeScript for `platform_web/`
|
|
|
|
`platform_web/` SHALL use npm scripts for dev, build, typecheck, test, and preview. The baseline app should render the required first-party navigation entries and page placeholders without implementing backend-driven workflows.
|
|
|
|
Alternative considered: a static HTML placeholder. Rejected because future frontend work needs route definitions, component structure, schema typing, and browser verification from the start.
|
|
|
|
### Decision 3: Use npm TypeScript tooling for `plugins/`
|
|
|
|
`plugins/` SHALL own its SDK package metadata, TypeScript sources, JSON schema validation scripts, example manifest fixtures, and tests. This keeps plugin contract checks close to plugin ownership while leaving platform registration behavior for a later change.
|
|
|
|
Alternative considered: validate plugin schemas from `platform/`. Rejected because plugin authoring and fixture tests belong in the plugin workspace; platform can later consume the same published or copied contracts through an explicit boundary.
|
|
|
|
### Decision 4: Root scripts orchestrate checks only
|
|
|
|
Root `scripts/` may contain shell scripts such as `check-structure.sh` and `check-all.sh`, but no application logic. These scripts call commands inside each root and provide a single verification entry point for future OpenSpec changes.
|
|
|
|
Alternative considered: a root package manager workspace. Deferred because there is not enough shared package structure yet, and root-level dependency metadata could blur ownership boundaries before generated contracts exist.
|
|
|
|
### Decision 5: Minimal UI still requires browser verification
|
|
|
|
Because this change creates the initial frontend shell, closure requires a local dev server and browser walkthrough. The walkthrough only needs to prove the shell renders, required navigation exists, and layout does not visibly overlap on desktop and mobile widths.
|
|
|
|
Alternative considered: rely on build and unit tests only. Rejected because the repository rules require a browser walkthrough when frontend pages are touched.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Risk] Separate Go modules add repeated tooling setup. Mitigation: add root orchestration scripts and keep shared protocol files documented until generation is introduced.
|
|
- [Risk] Vite baseline may look like product UI before APIs exist. Mitigation: keep pages minimal and avoid fake workflows; later changes will implement data-backed pages.
|
|
- [Risk] npm dependency versions may drift. Mitigation: commit lockfiles during implementation and document the Node/npm baseline.
|
|
- [Risk] `scripts/check-all.sh` may be slow as features grow. Mitigation: start with baseline commands and allow future changes to add narrower scripts when needed.
|
|
|
|
## Migration Plan
|
|
|
|
1. Add module/package metadata and minimal source files inside each project root.
|
|
2. Add root orchestration scripts and update `scripts/check-structure.sh` for new required baseline files.
|
|
3. Update README files with local development commands.
|
|
4. Run root structure checks, per-root tests/builds, strict OpenSpec validation, and frontend browser walkthrough.
|
|
|
|
## Open Questions
|
|
|
|
- Whether future generated contracts should be produced from OpenAPI, protobuf, JSON Schema, or TypeScript source remains for a later contract-generation change.
|
|
- Whether `platform/` starts with SQLite or Postgres remains for the platform API surface change.
|