60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
## 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.
|