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,62 @@
+## Context
+
+The current frontend calls `/metrics/platform`, `/metrics/server-instances`, and `/server-instances/{id}/config`, but the backend router does not implement them. HomePage falls back to partial data or error states, and ServerDetailPage uses a hardcoded `server.properties` sample when config read fails.
+
+This change is deliberately read-only. It creates the observability/config read surface needed by later config write, AI suggestion, and run execution changes without introducing file mutation or process orchestration.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Implement platform resource usage and per-server metrics API routes.
+- Implement safe server config read route with role-scoped access.
+- Keep response contracts bounded and free of secrets, host paths, direct sockets, and raw run credentials.
+- Update frontend pages to consume real API data and demote local samples to explicit fallback.
+- Add service/API/frontend tests and browser walkthrough evidence.
+
+**Non-Goals:**
+
+- No config write, file write, or diff approval routes.
+- No external metrics collector or long-term metrics storage backend.
+- No browser log tail, artifact transfer UI, or AI log analysis.
+- No run worker changes beyond existing data sources.
+
+## Decisions
+
+### Decision 1: Keep metrics as platform-owned read models
+
+The service will expose platform and server metrics through platform DTOs. Initial values may be derived from existing run endpoint/server/job metadata or stored in the in-memory repository, but callers see stable read contracts.
+
+Alternative considered: let the frontend compute all metrics locally from server lists. Rejected because the console already has API client methods and future run workers need a platform-owned metrics surface.
+
+### Decision 2: Server config read returns logical content only
+
+The config read response returns server instance ID, config version, content, format/key metadata, and timestamps. It must not include host filesystem paths or run-local socket details.
+
+Alternative considered: return a host path for browser editing. Rejected because run paths must not leak to platform_web or plugins.
+
+### Decision 3: Role-scoped access applies to config and server metrics
+
+Platform administrators can read all metrics/config. Server owners and administrators can read only their server instances. This reuses the existing bearer session and ACL behavior.
+
+### Decision 4: Frontend fallback remains visibly non-production
+
+Local sample config can remain only as an explicit fallback state for API-unavailable development/demo flows. Production rendering must prefer API data and show errors/empty states honestly.
+
+## Risks / Trade-offs
+
+- [Risk] Derived metrics can look less live than future run telemetry. Mitigation: expose source/timestamp fields and keep later real-time collectors as a separate change.
+- [Risk] Config content may be stale relative to actual files until run worker integration exists. Mitigation: include config version and source metadata.
+- [Risk] Server detail can still show fallback config if backend is unavailable. Mitigation: label fallback clearly and add tests that API success suppresses fallback.
+
+## Migration Plan
+
+1. Add metrics/config domain, DTO, validators, and service methods in `platform/`.
+2. Add API handlers/routes and route documentation updates.
+3. Update `platform_web` API types/views to render API metrics/config.
+4. Add tests and browser walkthrough.
+
+## Open Questions
+
+- Whether future metrics persistence should be a repository table or a projection from run heartbeats/logs.
+- Whether config format should start as plain text only or include structured sections after file dispatch is implemented.
@@ -0,0 +1,27 @@
+## Why
+
+The console already calls platform metrics and server config read APIs, but those routes are not implemented. Operators see empty/error states or local sample config even when real server, job, and run endpoint data exists. This change closes the read-only observability gap before write and execution work builds on it.
+
+## What Changes
+
+- Add backend contracts and routes for platform resource usage, per-server metrics, and server config reads.
+- Enforce existing role-scoped server access for server config and server metrics.
+- Return bounded, safe metadata without host paths, raw credentials, run sockets, or AI keys.
+- Update HomePage and ServerDetailPage to prefer API data and keep any local samples as explicit dev/demo fallback only.
+- Add tests and browser walkthrough coverage for 首页 and server detail config views.
+
+## Capabilities
+
+### New Capabilities
+
+- `platform-observability-and-config-read`: API-backed platform/server metrics and safe server config read workflows.
+
+### Modified Capabilities
+
+- `platform-web-console-shell`: Removes production reliance on local observability/config samples for existing console pages.
+
+## Impact
+
+- Affects `platform/` domain, DTO, validators, service, API handlers, route docs, and tests.
+- Affects `platform_web/` API types/client usage, HomePage, ServerDetailPage, tests, and browser walkthrough.
+- Does not add config writes, file dispatch, log tail transport, external metrics backends, billing, cloud host sales, raw host paths, raw credentials, or direct run access.
@@ -0,0 +1,53 @@
+## ADDED Requirements
+
+### Requirement: Platform exposes resource usage metrics
+The platform SHALL expose a bounded platform resource usage endpoint for the management console.
+
+#### Scenario: Platform metrics loaded
+- **WHEN** an authorized platform administrator requests platform resource usage
+- **THEN** the platform MUST return CPU, memory, disk, source, and timestamp metadata in a named DTO response
+
+#### Scenario: Platform metrics remain safe
+- **WHEN** the platform returns resource usage data
+- **THEN** the response MUST NOT include host paths, raw credentials, direct sockets, storage backend credentials, or raw AI provider keys
+
+### Requirement: Platform exposes per-server metrics
+The platform SHALL expose bounded per-server metrics for server management and overview pages.
+
+#### Scenario: Server metrics listed
+- **WHEN** an authorized user requests server metrics
+- **THEN** the platform MUST return only metrics for server instances visible to that user
+
+#### Scenario: Pending metrics are bounded
+- **WHEN** a server does not have current metrics
+- **THEN** the platform MUST return a bounded missing/pending representation rather than unsafe fallback internals
+
+### Requirement: Server config read is safe and role scoped
+The platform SHALL expose a server config read endpoint that returns logical config content for an authorized server instance.
+
+#### Scenario: Owner reads server config
+- **WHEN** a server owner requests config for their server instance
+- **THEN** the platform MUST return config content, config version, server instance ID, and bounded metadata
+
+#### Scenario: Unauthorized config read rejected
+- **WHEN** a user without access requests server config
+- **THEN** the platform MUST reject the request and MUST NOT return config content
+
+#### Scenario: Config response hides run internals
+- **WHEN** the platform returns server config
+- **THEN** the response MUST NOT expose run credentials, raw host paths, direct sockets, or raw secret values
+
+### Requirement: Console uses API-backed observability and config reads
+The frontend SHALL prefer API-backed platform metrics, server metrics, and server config content over hardcoded production data.
+
+#### Scenario: API config suppresses fallback
+- **WHEN** the server config API returns content
+- **THEN** ServerDetailPage MUST render that content and MUST NOT display the local sample config label
+
+#### Scenario: Metrics render from API
+- **WHEN** metrics APIs return data
+- **THEN** HomePage and server cards MUST render API metric values with safe loading/error states
+
+#### Scenario: Fallback is explicit
+- **WHEN** a development fallback is used because an API is unavailable
+- **THEN** the UI MUST label it as local/demo fallback and MUST NOT present it as persisted platform data
@@ -0,0 +1,51 @@
+## 1. Platform Metrics Contracts
+
+- [x] 1.1 Add domain contracts for platform resource usage snapshots and per-server metrics.
+- [x] 1.2 Add DTO request/response contracts for `/metrics/platform` and `/metrics/server-instances`.
+- [x] 1.3 Add repository/service interfaces for storing or deriving platform and server metrics.
+- [x] 1.4 Add validators for metric ranges, timestamps, server IDs, and bounded list responses.
+
+## 2. Server Config Read Contracts
+
+- [x] 2.1 Add domain and DTO contracts for server config read responses.
+- [x] 2.2 Add service method for reading server config metadata/content by server instance.
+- [x] 2.3 Enforce role-scoped access for config reads using existing server ACL rules.
+- [x] 2.4 Ensure config read responses never expose host paths, raw credentials, or direct run sockets.
+
+## 3. Backend API Surface
+
+- [x] 3.1 Implement `GET /api/v1/metrics/platform`.
+- [x] 3.2 Implement `GET /api/v1/metrics/server-instances`.
+- [x] 3.3 Implement `GET /api/v1/server-instances/{id}/config`.
+- [x] 3.4 Update `platform/api/routes.md` and protocol docs to mark these routes implemented.
+
+## 4. Frontend Integration
+
+- [x] 4.1 Update HomePage to render platform metrics from API data instead of empty fallback states.
+- [x] 4.2 Update ServerDetailPage config section to show API config content when available.
+- [x] 4.3 Remove or clearly isolate hardcoded config fallback from production flow.
+- [x] 4.4 Add UI tests for metrics/config loading, errors, and no-secret rendering.
+
+## 5. Verification
+
+- [x] 5.1 Add platform service/API tests for metrics and config read access control.
+- [x] 5.2 Run `cd platform && go test ./...` and record evidence.
+- [x] 5.3 Run `cd platform_web && npm run typecheck && npm test && npm run build` and record evidence.
+- [x] 5.4 Run browser walkthrough for 首页 and server detail config view.
+- [x] 5.5 Run `scripts/check-structure.sh` and record evidence.
+- [x] 5.6 Run `openspec validate implement-platform-observability-and-config-read --strict` and record evidence.
+
+## Evidence
+
+- 2026-07-06: Added platform domain/DTO/service/validator/API implementation for platform metrics, server metrics, and safe server config reads.
+- 2026-07-06: Added platform service/API tests for role-scoped metrics and config reads, unauthorized access denial, and no host path/raw credential/socket fragments.
+- 2026-07-06: Updated frontend API contracts/client tests for platform metrics, server metrics, and server config responses; existing HomePage and ServerDetailPage API flows consume these methods with explicit local fallback labeling.
+- 2026-07-06: `cd platform && go test ./domain ./dto ./validator ./service ./api` passed.
+- 2026-07-06: `cd platform_web && npm test -- --run api/client.test.ts pages/ConsolePages.test.tsx` passed with 2 files / 9 tests.
+- 2026-07-06: `cd platform && go test ./...` passed across api, cmd/platform, config, domain, dto, model, repo, service, and validator packages.
+- 2026-07-06: `cd platform_web && npm run typecheck` passed.
+- 2026-07-06: `cd platform_web && npm test` passed with 9 files / 31 tests.
+- 2026-07-06: `cd platform_web && npm run build` passed and produced Vite production assets.
+- 2026-07-06: Headless Chrome walkthrough against `http://127.0.0.1:5175/` passed: seeded platform API data, verified 首页 rendered API platform metrics/resource usage and server distribution, opened `#/servers/server-walkthrough`, verified config tab showed `配置版本 v1` with API textarea content `server.name=Walkthrough SCUM`, and confirmed rendered text/textarea excluded `/Users/`, `unix://`, `Bearer `, `sk-`, and `password=`.
+- 2026-07-06: `scripts/check-structure.sh` passed with `structure check passed`.
+- 2026-07-06: `openspec validate implement-platform-observability-and-config-read --strict` passed with `Change 'implement-platform-observability-and-config-read' is valid`.