first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -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.