first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-02
|
||||
@@ -0,0 +1,75 @@
|
||||
## 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.
|
||||
@@ -0,0 +1,26 @@
|
||||
## Why
|
||||
|
||||
The repository currently has architecture documents and ownership directories, but it does not yet have runnable project baselines. Later platform, run, frontend, and plugin changes need consistent local commands, package boundaries, and verification entry points before business behavior is implemented.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Establish Go module baselines for `platform/` and `run/` with minimal executable entry points and tests.
|
||||
- Establish a TypeScript/Vite baseline for `platform_web/` with a minimal browser-rendered management console shell.
|
||||
- Establish a TypeScript baseline for `plugins/` covering SDK exports, schema validation scripts, examples, and contract tests.
|
||||
- Add root orchestration scripts for build/test/check workflows without placing implementation code outside the matching project roots.
|
||||
- Document local development commands and required tool versions.
|
||||
- Extend structure verification only for new required baseline files and directories introduced by this change.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `development-runtime-baseline`: Runtime, tooling, command, and verification baseline for the four project roots.
|
||||
|
||||
### Modified Capabilities
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affects `platform/`, `run/`, `platform_web/`, `plugins/`, root documentation, and root verification scripts.
|
||||
- Introduces Go and npm-based development commands but does not implement platform business APIs, run job execution, plugin marketplace behavior, or full frontend pages.
|
||||
- Future OpenSpec changes will rely on these commands for tests, builds, and local walkthroughs.
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Platform Go Runtime Baseline
|
||||
`platform/` SHALL contain an independent Go module with a minimal command entry point, configuration package, HTTP health surface, and automated tests.
|
||||
|
||||
#### Scenario: Platform tests run
|
||||
- **WHEN** a contributor runs the documented platform test command
|
||||
- **THEN** the platform Go module test suite completes successfully without importing code from `run/`, `platform_web/`, or `plugins/`
|
||||
|
||||
#### Scenario: Platform server starts
|
||||
- **WHEN** a contributor runs the documented platform development command
|
||||
- **THEN** the process starts a local HTTP server with a health response suitable for smoke testing
|
||||
|
||||
### Requirement: Run Go Runtime Baseline
|
||||
`run/` SHALL contain an independent Go module with a minimal command entry point, configuration package, platform client boundary, and automated tests.
|
||||
|
||||
#### Scenario: Run tests run
|
||||
- **WHEN** a contributor runs the documented run test command
|
||||
- **THEN** the run Go module test suite completes successfully without importing code from `platform/`, `platform_web/`, or `plugins/`
|
||||
|
||||
#### Scenario: Run executor starts
|
||||
- **WHEN** a contributor runs the documented run development command
|
||||
- **THEN** the process starts in a local smoke-test mode without exposing host paths, raw credentials, or direct sockets to plugins or frontend code
|
||||
|
||||
### Requirement: Platform Web TypeScript Runtime Baseline
|
||||
`platform_web/` SHALL contain a Vite React TypeScript app with route definitions, required first-party page placeholders, API client boundaries, shared components, theme tokens, and automated build/typecheck/test scripts.
|
||||
|
||||
#### Scenario: Frontend checks run
|
||||
- **WHEN** a contributor runs the documented platform_web verification commands
|
||||
- **THEN** TypeScript typecheck, tests, and production build complete successfully
|
||||
|
||||
#### Scenario: Required navigation renders
|
||||
- **WHEN** the platform_web dev server is opened in a browser
|
||||
- **THEN** the shell renders navigation entries for 首页、服务器管理、插件市场、用户管理、AI 提供商管理 without visible overlap on desktop and mobile widths
|
||||
|
||||
### Requirement: Plugin Workspace TypeScript Baseline
|
||||
`plugins/` SHALL contain npm TypeScript tooling for SDK exports, JSON schema validation, example plugin fixtures, and automated tests.
|
||||
|
||||
#### Scenario: Plugin checks run
|
||||
- **WHEN** a contributor runs the documented plugin verification commands
|
||||
- **THEN** SDK typecheck, schema validation, and tests complete successfully
|
||||
|
||||
#### Scenario: Example manifest validates
|
||||
- **WHEN** the plugin schema validation command is run
|
||||
- **THEN** `plugins/examples/dev-game-plugin/manifest.json` validates against `plugins/manifests/game-plugin.manifest.schema.json`
|
||||
|
||||
### Requirement: Root Verification Orchestration
|
||||
The repository SHALL provide root-level verification scripts that orchestrate structure checks and per-root build/test commands without containing application logic.
|
||||
|
||||
#### Scenario: Full baseline check runs
|
||||
- **WHEN** a contributor runs the documented full check command from the repository root
|
||||
- **THEN** it runs structure verification plus platform, run, platform_web, and plugin baseline checks
|
||||
|
||||
#### Scenario: Structure rules include new baseline files
|
||||
- **WHEN** `scripts/check-structure.sh` runs after this change
|
||||
- **THEN** it verifies the new required module, package, command, test, and documentation baseline files added by this change
|
||||
|
||||
### Requirement: Development Documentation
|
||||
The repository SHALL document required tool versions, local development commands, verification commands, and the scope limits of this runtime baseline.
|
||||
|
||||
#### Scenario: Contributor reads the README
|
||||
- **WHEN** a contributor reads the root and per-root README files
|
||||
- **THEN** they can identify how to install dependencies, start local processes, run tests, run builds, and perform the frontend browser walkthrough
|
||||
|
||||
#### Scenario: Future change reads baseline docs
|
||||
- **WHEN** a future OpenSpec implementation needs to add product behavior
|
||||
- **THEN** it can reuse the documented baseline commands instead of inventing a new verification surface
|
||||
@@ -0,0 +1,75 @@
|
||||
## 1. Go Runtime Baselines
|
||||
|
||||
- [x] 1.1 Add an independent Go module under `platform/` with minimal command, config, HTTP health surface, and tests.
|
||||
- [x] 1.2 Add an independent Go module under `run/` with minimal command, config, platform client boundary, smoke-test mode, and tests.
|
||||
- [x] 1.3 Verify neither Go module imports implementation code from another project root.
|
||||
|
||||
## 2. Platform Web Baseline
|
||||
|
||||
- [x] 2.1 Add npm, Vite, React, and TypeScript baseline files under `platform_web/`.
|
||||
- [x] 2.2 Add route definitions, API client boundaries, required page placeholders, shared components, theme tokens, and test setup in the required directories.
|
||||
- [x] 2.3 Add scripts for `dev`, `build`, `typecheck`, `test`, and `preview`.
|
||||
|
||||
## 3. Plugin Workspace Baseline
|
||||
|
||||
- [x] 3.1 Add npm and TypeScript baseline files under `plugins/`.
|
||||
- [x] 3.2 Add SDK export stubs, schema validation scripts, example manifest validation, and tests inside the plugin root.
|
||||
- [x] 3.3 Keep plugin checks scoped to plugin contracts and do not add platform marketplace behavior in this change.
|
||||
|
||||
## 4. Root Orchestration And Documentation
|
||||
|
||||
- [x] 4.1 Add a root verification script that runs structure checks plus each root's baseline checks without containing application logic.
|
||||
- [x] 4.2 Update `scripts/check-structure.sh` for new required baseline files and directories.
|
||||
- [x] 4.3 Update root and per-root README files with tool versions, dependency install commands, local start commands, verification commands, and baseline scope limits.
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [x] 5.1 Run `go test ./...` in `platform/`.
|
||||
- [x] 5.2 Run `go test ./...` in `run/`.
|
||||
- [x] 5.3 Run the documented install, typecheck, test, and build commands in `platform_web/`.
|
||||
- [x] 5.4 Run the documented install, typecheck, test, and schema validation commands in `plugins/`.
|
||||
- [x] 5.5 Run the root full-check script and `scripts/check-structure.sh`.
|
||||
- [x] 5.6 Start the platform_web dev server and complete a browser walkthrough at desktop and mobile widths.
|
||||
- [x] 5.7 Run `openspec validate establish-development-runtime-baseline --strict`.
|
||||
|
||||
## Evidence
|
||||
|
||||
- `go test ./...` in `platform/`: passed.
|
||||
- `go test ./...` in `run/`: passed.
|
||||
- `npm install`, `npm run typecheck`, `npm run test`, and `npm run build` in `platform_web/`: passed.
|
||||
- `npm install`, `npm run typecheck`, `npm run test`, and `npm run validate:manifest` in `plugins/`: passed.
|
||||
- Cross-root import checks: `rg "browser\.local/(run|platform_web|plugins)" platform` and `rg "browser\.local/(platform|platform_web|plugins)" run` returned no matches.
|
||||
- `scripts/check-all.sh`: passed.
|
||||
- `scripts/check-structure.sh`: passed.
|
||||
- Browser walkthrough: Vite dev server at `http://127.0.0.1:5173/`; desktop 1440x900 and mobile 390x844 checks confirmed required labels, 5 navigation items, 3 metric cards, no nav/metric/header overlap, and mobile document width equal to viewport.
|
||||
- `openspec validate establish-development-runtime-baseline --strict`: passed.
|
||||
|
||||
## Implementation Handoff
|
||||
|
||||
```text
|
||||
Implement OpenSpec change: establish-development-runtime-baseline
|
||||
|
||||
Scope:
|
||||
- Implement only openspec/changes/establish-development-runtime-baseline/.
|
||||
- Add runtime/tooling baselines for platform, run, platform_web, and plugins.
|
||||
- Do not implement platform business APIs, run job execution, log ingest, artifact transfer, plugin marketplace workflows, billing, cloud host sales, or agent-provider/cloud-provider workflows.
|
||||
|
||||
Read first:
|
||||
- AGENTS.md
|
||||
- platform/AGENTS.md
|
||||
- run/AGENTS.md
|
||||
- platform_web/AGENTS.md
|
||||
- plugins/AGENTS.md
|
||||
- openspec/changes/bootstrap-game-server-platform-architecture/proposal.md
|
||||
- openspec/changes/bootstrap-game-server-platform-architecture/design.md
|
||||
- openspec/changes/architecture-delivery-stream/delivery-plan.md
|
||||
- openspec/changes/establish-development-runtime-baseline/proposal.md
|
||||
- openspec/changes/establish-development-runtime-baseline/design.md
|
||||
- openspec/changes/establish-development-runtime-baseline/tasks.md
|
||||
|
||||
Required closure:
|
||||
- Mark task checkboxes complete only after evidence exists.
|
||||
- Run platform Go tests, run Go tests, platform_web install/typecheck/test/build, plugin install/typecheck/test/schema validation, the root full-check script, scripts/check-structure.sh, and openspec validate establish-development-runtime-baseline --strict.
|
||||
- Because platform_web pages are touched, start the dev server and perform a browser walkthrough at desktop and mobile widths before claiming the UI is accepted.
|
||||
- Stop after this change is closed; do not start implement-platform-core-domain in the same chat unless explicitly asked.
|
||||
```
|
||||
Reference in New Issue
Block a user