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,59 @@
+## Context
+
+The frontend already has a useful diff review UX, but it dispatches config writes by calling `POST /jobs` with `capability=config.write`. That bypasses platform-owned config validation, stale version checks, and scoped file semantics.
+
+This change creates a platform service boundary for config/file dispatch. Later run worker and plugin bridge changes can execute the queued jobs using the same safe envelopes.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add config diff preview and approval routes.
+- Validate expected config version, bounded content size, logical config keys, and server ACLs.
+- Queue scoped run jobs for approved config/file operations.
+- Update frontend to call approval routes rather than generic job creation.
+- Keep all write operations reviewable and auditable.
+
+**Non-Goals:**
+
+- No real process execution or local file mutation in this change.
+- No unrestricted file manager or raw path API.
+- No plugin page bridge execution beyond shared dispatch contracts.
+- No external storage backend implementation.
+
+## Decisions
+
+### Decision 1: Platform service owns write approval
+
+Config write approval is a service method, not a frontend-generated generic job. It validates server access, config version, diff payload, and logical file key before creating a queued job.
+
+### Decision 2: File operations use logical keys and refs
+
+Requests identify server-scoped config/file targets by logical keys or artifact/input refs. Raw absolute paths, home directories, sockets, and credentials are rejected.
+
+### Decision 3: Diff preview can be pure platform computation
+
+The backend can compute a textual diff from current config and proposed content without dispatching work. Approval is a separate explicit call.
+
+### Decision 4: Frontend keeps second confirmation
+
+ServerDetailPage and AI suggestion flows must keep an explicit confirmation after showing the diff. Approval dispatch happens only after that confirmation.
+
+## Risks / Trade-offs
+
+- [Risk] Queued jobs may not execute until the real run worker change lands. Mitigation: this change verifies dispatch and state, not local mutation.
+- [Risk] Diff preview duplicates frontend diff code. Mitigation: frontend diff remains display-oriented; backend diff validates dispatch input.
+- [Risk] Logical file keys may be too narrow. Mitigation: keep schema extensible and add cases through future OpenSpec changes.
+
+## Migration Plan
+
+1. Add platform contracts and validators for config diff/write and file dispatch.
+2. Add API handlers and route docs.
+3. Extend run protocol payload validation for scoped config/file jobs.
+4. Update ServerDetailPage config and AI write flows.
+5. Add backend/frontend/run tests and walkthrough.
+
+## Open Questions
+
+- Whether approved config writes should become a first-class operation resource rather than a job-only response.
+- Whether future restart/update/delete workflows should share the same approval envelope.
@@ -0,0 +1,28 @@
+## Why
+
+ServerDetailPage currently previews config diffs locally and then creates a generic `config.write` job directly from the browser. The route catalog still lists config diff review and file operation dispatch as future work. Operators need a platform-mediated, auditable flow that validates config versions and dispatches scoped run jobs without leaking host paths or credentials.
+
+## What Changes
+
+- Add backend config diff preview and config write approval workflows.
+- Add scoped file operation dispatch contracts for safe file read/write jobs.
+- Move config write dispatch out of generic frontend job creation and into platform-owned service methods.
+- Keep explicit user confirmation before any write job is dispatched.
+- Update frontend config and AI suggestion write paths to use approved platform routes.
+
+## Capabilities
+
+### New Capabilities
+
+- `config-write-and-file-dispatch`: Safe config diff review, approval, and scoped file operation dispatch.
+
+### Modified Capabilities
+
+- `server-management-workflows`: Server detail config writes use platform lifecycle/file dispatch rules instead of direct generic job creation.
+
+## Impact
+
+- Affects `platform/` domain, DTO, validators, service, API handlers, route/protocol docs, and tests.
+- Affects `run/` protocol validation for scoped config/file job payloads.
+- Affects `platform_web/` ServerDetailPage config and AI suggestion apply flows.
+- Does not add unrestricted file browsing, raw path exposure, billing, cloud sales, or direct plugin-to-run access.
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Config diff preview is platform mediated
+The platform SHALL provide a config diff preview route that compares current server config with proposed content without dispatching a write.
+
+#### Scenario: Preview accepted
+- **WHEN** an authorized operator submits proposed config content with the current config version
+- **THEN** the platform MUST return a bounded diff and MUST NOT create a run job
+
+#### Scenario: Preview rejects stale config
+- **WHEN** proposed config content references a stale config version
+- **THEN** the platform MUST reject the preview and MUST NOT dispatch work
+
+### Requirement: Config write approval dispatches scoped job
+The platform SHALL dispatch config writes only after an explicit approval request passes validation.
+
+#### Scenario: Approved config write queued
+- **WHEN** an authorized operator approves a reviewed config diff
+- **THEN** the platform MUST queue a bounded `config.write` job for the server instance and return job metadata
+
+#### Scenario: Config write hides unsafe internals
+- **WHEN** the platform dispatches a config write job
+- **THEN** the request and response MUST NOT expose raw host paths, run credentials, direct sockets, or raw secret values
+
+### Requirement: File operation dispatch is scoped
+The platform SHALL provide scoped file operation dispatch for server/plugin workflows using logical file keys or artifact refs.
+
+#### Scenario: Scoped file read dispatched
+- **WHEN** an authorized caller requests a declared logical file read
+- **THEN** the platform MUST queue a bounded file read job with scoped target metadata
+
+#### Scenario: Unsafe file target rejected
+- **WHEN** a request includes an absolute path, parent traversal, raw credential, direct socket, or host-local secret path
+- **THEN** the platform MUST reject the request before creating a job
+
+### Requirement: Frontend config writes use approval APIs
+The frontend SHALL use platform config preview and approval APIs for config writes.
+
+#### Scenario: User previews and approves config write
+- **WHEN** a user edits config, previews the diff, and confirms approval
+- **THEN** ServerDetailPage MUST call the approval API and render the returned platform job state
+
+#### Scenario: Frontend avoids generic write job creation
+- **WHEN** a config write is initiated from manual edit or AI suggestion
+- **THEN** the frontend MUST NOT create a generic `config.write` job directly through `POST /jobs`
@@ -0,0 +1,58 @@
+## 1. Config Diff Review Contracts
+
+- [x] 1.1 Add domain contracts for config diff review, proposed content, approval status, and dispatch metadata.
+- [x] 1.2 Add DTO contracts for config diff preview, approval, rejection, and dispatch responses.
+- [x] 1.3 Add validators for bounded config size, allowed file keys, expected config version, and diff content safety.
+- [x] 1.4 Add service methods for previewing and approving config writes without exposing host paths.
+
+## 2. File Operation Dispatch Contracts
+
+- [x] 2.1 Add domain/DTO contracts for scoped file read/write requests.
+- [x] 2.2 Map file operations to platform job capabilities such as `config.write`, `files.read`, and `files.write`.
+- [x] 2.3 Enforce plugin/server permissions and role-scoped server access before dispatch.
+- [x] 2.4 Ensure dispatch payloads use logical file keys or artifact/input refs, not raw host paths.
+
+## 3. Backend API Surface
+
+- [x] 3.1 Implement config diff preview route for a server instance.
+- [x] 3.2 Implement config write approval route that queues a bounded run job.
+- [x] 3.3 Implement file operation dispatch route for scoped plugin/platform file jobs.
+- [x] 3.4 Update route/protocol documentation to mark config and file dispatch implemented.
+
+## 4. Frontend Integration
+
+- [x] 4.1 Update ServerDetailPage config write flow to call config diff preview API.
+- [x] 4.2 Update confirmation flow to call config write approval API instead of creating a generic job directly.
+- [x] 4.3 Keep explicit second confirmation before dispatching any config write.
+- [x] 4.4 Remove local-only config mutation after job dispatch; show pending platform job state instead.
+
+## 5. Run Integration Prep
+
+- [x] 5.1 Extend run protocol job payloads to carry scoped config/file input refs.
+- [x] 5.2 Add run-side validation for allowed logical paths and bounded write payloads.
+- [x] 5.3 Add tests proving raw host paths and credentials are rejected.
+
+## 6. Verification
+
+- [x] 6.1 Add platform tests for preview, approval, stale config version, unauthorized server access, and unsafe paths.
+- [x] 6.2 Add frontend tests for diff preview, approval, failure, and no local mutation on dispatch.
+- [x] 6.3 Run platform, run, and platform_web test/build commands and record evidence.
+- [x] 6.4 Run browser walkthrough for config diff and write approval.
+- [x] 6.5 Run `scripts/check-structure.sh` and record evidence.
+- [x] 6.6 Run `openspec validate implement-config-write-and-file-dispatch --strict` and record evidence.
+
+## Evidence
+
+- 2026-07-06: `cd platform && go test ./domain ./dto ./validator ./service ./api ./model` passed after adding config diff/write contracts, validators, service methods, and API handlers.
+- 2026-07-06: `cd run && go test ./protocol` passed after adding scoped job target/input refs and run protocol validation tests for raw host paths and raw credential refs.
+- 2026-07-06: Updated `platform/api/routes.md`, `platform/protocol/server-lifecycle.md`, `run/protocol/job.md`, and `platform_web/api/contracts.md` to document implemented config diff/approval and scoped file dispatch routes/protocol payloads.
+- 2026-07-06: `cd platform && go test ./service ./api -run 'TestCoreServiceConfigWriteAndFileDispatchAreScoped|TestConfigWriteAndFileDispatchAPIAreScoped'` passed, covering preview, approval, stale config version, unauthorized access, unsafe keys, and scoped file dispatch.
+- 2026-07-06: `cd platform_web && npm run typecheck` passed after adding config diff/approval/file dispatch API types and client methods.
+- 2026-07-06: `cd platform_web && npm test -- --run api/client.test.ts pages/ServerDetailPage.test.tsx` passed, covering preview/approval client requests, preview failure surfacing, platform diff mapping, no generic `config.write` job creation, and no local config mutation after approval dispatch.
+- 2026-07-06: `cd platform && go test ./...` passed.
+- 2026-07-06: `cd run && go test ./...` passed.
+- 2026-07-06: `cd platform_web && npm test` passed with 11 files / 40 tests.
+- 2026-07-06: `cd platform_web && npm run build` passed.
+- 2026-07-06: Browser walkthrough passed using local platform `127.0.0.1:18090`, Vite `127.0.0.1:5177`, and headless Chrome: logged in, opened `#/servers/server-walkthrough`, edited config, previewed the platform diff, confirmed approval dispatch, saw the returned `config.write` job badge, and verified no `/Users/`, `unix://`, bearer token, raw key, password, or billing fragments were visible.
+- 2026-07-06: `scripts/check-structure.sh` passed.
+- 2026-07-06: `openspec validate implement-config-write-and-file-dispatch --strict` reported `Change 'implement-config-write-and-file-dispatch' is valid`; PostHog telemetry flush failed due restricted DNS and did not affect validation.