editor and lsp

This commit is contained in:
2026-03-31 11:12:52 +01:00
parent 2868203706
commit 91ca49a074
15 changed files with 1549 additions and 4 deletions
@@ -0,0 +1,136 @@
---
id: DEC-0010
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Establish the controlled non-frontend editor write wave in Studio
status: accepted
created: 2026-03-31
accepted: 2026-03-31
agenda: AGD-0013
plans:
- PLN-0019
- PLN-0020
- PLN-0021
tags:
- studio
- editor
- workspace
- write
- read-only
- vfs
- frontend-boundary
---
## Context
The first Studio `Code Editor` wave established a read-only editorial shell and later moved project-document ownership into `prometeu-vfs`.
That left one immediate follow-up decision:
- which files may become editable now,
- which files must remain `read-only`,
- where access policy lives,
- how save works,
- and how editorial in-memory state stays contained away from build-facing state.
The accepted agenda closed the intended first write wave as deliberately narrower than "all supported text files":
- the same supported-document universe remains valid for opening,
- but access policy must distinguish `read-only` from `editable`,
- frontend-scoped files remain `read-only`,
- and only already-supported non-frontend text classes enter the first write wave.
## Decision
1. Studio SHALL introduce a controlled first editor write wave only for supported non-frontend documents.
2. The canonical document universe for this wave SHALL remain the same universe already supported for opening through `prometeu-vfs`.
3. `prometeu-vfs` SHALL own document access policy for this wave, including `load`, `save`, and the classification of each supported document as `read-only` or `editable`.
4. `EditorWorkspace` MUST consume access policy from `prometeu-vfs` and MUST NOT rederive editability rules locally.
5. Frontend-scoped documents SHALL remain hard `read-only` in this wave.
6. Frontend scope SHALL be decided inside `prometeu-vfs` using `FrontendSpec.allowedExtensions` as the source of truth.
7. The `prometeu-vfs` contract SHALL evolve so that `typeId` canonically represents that frontend scope in a way compatible with `FrontendSpec.allowedExtensions`, rather than exposing only a raw dynamic language identifier.
8. The initial editable non-frontend document classes SHALL be limited to the currently supported textual classes represented as `text`, `json`, `ndjson`, and `bash`.
9. No additional document-support class SHALL be inferred or added by implementation convenience during this wave.
10. For editable documents in this wave, `prometeu-vfs` SHALL maintain an in-memory editorial snapshot for the current Studio session.
11. `save` SHALL persist that in-memory editorial snapshot to disk through `prometeu-vfs`.
12. The global shell `Save` menu item MUST NOT be the save surface for this wave.
13. Save actions for this wave SHALL live inside the editor itself through a top command bar containing at least `Save` and `Save All`.
14. Frontend-scoped hard `read-only` tabs MAY coexist with editable non-frontend tabs in the same editor workspace.
15. Frontend-scoped hard `read-only` documents SHALL expose a `read-only` state in the editor status bar.
16. The status-bar `read-only` surface SHOULD be designed so that it can evolve later into a per-file toggle without requiring a model rewrite.
17. Frontend-scoped hard `read-only` documents MUST NOT allow local editorial mutation in this wave.
18. Opening a frontend-scoped hard `read-only` document SHALL also show a top-of-editor warning stating that the file is `read-only`, cannot be edited, and cannot be saved in this wave.
19. The editable documents in this wave SHALL be treated as editorial scope and SHALL NOT participate in the build by implication.
20. The in-memory editorial snapshot used for this wave MUST remain contained and MUST NOT be treated as canonical build input.
21. No implementation in this wave MAY collapse editorial session snapshots into build-facing or artifact-facing document state by inference.
## Rationale
This decision preserves the correct architectural order.
The editor needed real write behavior, but not at the cost of undoing the `prometeu-vfs` boundary that was just established.
Keeping access policy in `prometeu-vfs` prevents a return to editor-local conditional logic.
Keeping frontend documents `read-only` avoids releasing mutation for language-owned files before semantic support is ready.
At the same time, allowing already-supported non-frontend text classes to become editable gives the Studio a meaningful write wave without pretending that all textual files belong to the same product tier.
The decision also protects the build boundary.
Having an in-memory editorial snapshot is necessary for writing, but it must not silently become the source of truth for build consumers.
## Technical Specification
### 1. Access Policy Surface
- `prometeu-vfs` MUST expose access policy as part of the document contract for supported files.
- That policy MUST distinguish at least:
- unsupported document,
- supported `read-only` document,
- supported editable document.
- The editor MUST treat this classification as canonical.
### 2. Frontend Classification
- `prometeu-vfs` MUST classify frontend scope internally.
- `FrontendSpec.allowedExtensions` MUST be the source of truth for that classification.
- The VFS contract MUST expose a frontend-compatible canonical `typeId` or equivalent scope marker derived from that source of truth.
- The editor MUST NOT infer frontend scope from path heuristics, local UI state, or ad hoc extension checks.
### 3. Editable Non-Frontend Set
- Editable scope in this wave is limited to the currently supported textual document classes:
- `text`
- `json`
- `ndjson`
- `bash`
- Future additions require explicit decision revision or a new decision.
### 4. Editorial Snapshot and Save
- Editable documents MUST have a session-owned in-memory editorial snapshot.
- `prometeu-vfs` MUST own the mutation-ready document state that `Save` and `Save All` use.
- Persisting to disk MUST happen through `prometeu-vfs`.
- The editor MUST remain a caller of save intent, not the owner of persistence policy.
### 5. UI Surfaces
- The editor MUST provide a top command bar with at least `Save` and `Save All`.
- Frontend hard `read-only` state MUST be visible in the status bar.
- A frontend hard `read-only` document MUST show a top warning that it cannot be edited or saved in this wave.
- Mixed tabs between editable and `read-only` documents are allowed.
### 6. Boundary with Build
- Editorial snapshots for this wave MUST remain separate from build-facing state.
- This wave MUST NOT introduce recompilation, artifact invalidation, build triggers, or any implied build participation.
- Any future bridge between editorial state and build-facing state requires a separate explicit decision.
## Constraints
- This decision does not release frontend editing.
- This decision does not authorize completion, semantic gating, or LSP-owned save policy.
- This decision does not authorize build-side observation of editorial in-memory snapshots.
- Any ambiguity found later in planning or implementation MUST be resolved by a new explicit clarification instead of local inference.
## Revision Log
- 2026-03-31: Initial accepted decision from AGD-0013.
- 2026-03-31: Clarified that `FrontendSpec.allowedExtensions` is the source of truth for frontend scope, that VFS `typeId` must represent that scope canonically, and that frontend documents are hard read-only in this wave.
@@ -0,0 +1,155 @@
---
id: DEC-0011
ticket: studio-editor-write-wave-supported-non-frontend-files
title: Establish the frontend read-only minimum LSP phase in Studio
status: accepted
created: 2026-03-31
accepted: 2026-03-31
agenda: AGD-0014
plans:
- PLN-0022
- PLN-0023
- PLN-0024
- PLN-0025
tags:
- studio
- editor
- workspace
- frontend-boundary
- lsp
- access-policy
---
## Context
The controlled non-frontend write wave intentionally kept frontend-scoped documents `read-only`.
After that closure, the next question was not "how to edit frontend now", but rather:
- whether Studio could already gain semantic value over frontend documents while they remain `read-only`,
- how `prometeu-lsp` should relate to `prometeu-vfs`,
- what minimum semantic scope is worth shipping,
- and how to keep this phase separate from the later decision that may release frontend editing.
The accepted agenda closed that this phase should remain explicitly `read-only` for frontend documents while introducing a minimum integrated LSP layer over the same project-session document substrate.
## Decision
1. Studio SHALL introduce a frontend `read-only` semantic phase before any frontend editing phase is considered.
2. This phase SHALL keep frontend-scoped documents hard `read-only`.
3. This phase SHALL introduce a minimum integrated `prometeu-lsp` consumer above `prometeu-vfs`.
4. `prometeu-lsp` SHALL consume document state exposed by `prometeu-vfs`.
5. For opened frontend documents, `prometeu-lsp` SHALL analyze the in-memory session snapshot exposed by `prometeu-vfs`.
6. For unopened frontend documents, `prometeu-lsp` MAY fall back to filesystem-backed state exposed through the same document boundary.
7. `prometeu-lsp` MUST NOT become the owner of document persistence, save policy, or access policy.
8. `prometeu-vfs` SHALL remain the owner of document state, snapshots, persistence, and access-policy context.
9. Frontend scope in this phase SHALL continue to use `FrontendSpec.allowedExtensions` as source of truth, and the VFS contract SHALL expose a frontend-compatible canonical `typeId` or equivalent scope marker derived from that source of truth.
10. The minimum semantic scope of this phase SHALL include:
- diagnostics,
- document symbols and workspace symbols,
- outline-facing structural symbol data,
- definition,
- highlight for frontend documents.
11. Highlight for non-frontend documents MAY remain Studio-local as currently implemented in this phase.
12. Highlight for frontend documents SHALL come from semantic information provided through `prometeu-lsp` and SHALL use frontend-owned color semantics rather than a Studio-local fallback scheme.
13. `Completion` SHALL remain out of scope for this minimum `read-only` phase.
14. `Rename`, code actions, formatting, and any frontend edit-right release SHALL remain out of scope for this phase.
15. The future release of frontend editing SHALL be handled by a separate discussion and decision.
16. The editorial in-memory state observed by `prometeu-lsp` MAY feed semantic analysis, but MUST NOT be treated as canonical build input by implication.
17. Any future bridge between frontend editorial state and build-facing state SHALL require a separate explicit decision.
18. `prometeu-lsp` API organization SHALL prefer flat packaging modeled after `prometeu-packer-api`, using explicit public surfaces such as `dtos`, `messages`, and `events` where appropriate.
19. `prometeu-vfs` does not need to persist document-access context yet, but it SHALL introduce a single context entity for such values so that read, mutation, and future persistence remain a natural extension rather than a redesign.
## Rationale
This decision separates semantic readiness from editing rights.
That separation is valuable because frontend files are materially different from generic textual documents.
For frontend documents, even a minimum Studio-integrated semantic consumer provides immediate value:
- diagnostics,
- outline and symbols,
- definition,
- highlight,
- and a validated path from document session state into semantic reading.
At the same time, keeping editing out of this phase protects the product from releasing mutation before its semantic consumer and editorial boundaries are ready.
The decision also preserves a clean ownership model:
- `prometeu-vfs` owns document state,
- `prometeu-lsp` consumes that state,
- the editor owns UX,
- and build remains separate.
## Technical Specification
### 1. Phase Boundary
- This decision defines a frontend semantic-read phase, not a frontend editing phase.
- Frontend documents remain hard `read-only` throughout this decision's scope.
- No plan derived from this decision may infer `save`, mutation, or frontend dirty-tracking rights.
### 2. Document Source of Truth for Analysis
- Opened frontend documents MUST be analyzed from the in-memory document snapshot held by `prometeu-vfs`.
- Closed frontend documents MAY be analyzed from filesystem-backed document state through the same boundary.
- Frontend scope MUST continue to derive from `FrontendSpec.allowedExtensions`.
- The VFS contract MUST expose a frontend-compatible canonical `typeId` or equivalent scope marker derived from that source of truth.
- Consumers MUST NOT bypass `prometeu-vfs` with ad hoc file loading inside Studio UI code.
### 3. Minimum LSP Capability Set
- The minimum phase MUST provide:
- diagnostics,
- document symbols,
- workspace symbols,
- outline-facing symbol structure,
- go-to-definition,
- frontend highlight.
- `Completion` is explicitly excluded from this minimum phase.
- Highlight for non-frontend files may remain Studio-local during this phase.
- Highlight for frontend files MUST come from LSP semantic output and frontend-owned color semantics.
### 4. Ownership Rules
- `prometeu-lsp` MUST remain a semantic consumer.
- `prometeu-lsp` MUST NOT own:
- save,
- persistence,
- document access policy,
- frontend edit-right release.
- `prometeu-vfs` MUST remain the owner of document state and access context.
### 5. Packaging Rules
- The public API of `prometeu-lsp` SHOULD use flat packaging similar to `prometeu-packer-api`.
- Public contract types SHOULD be grouped under explicit, shallow package surfaces such as:
- `dtos`
- `messages`
- `events`
- Deep packaging by internal implementation concern SHOULD be avoided for public contract surfaces.
### 6. Context Reservation
- `prometeu-vfs` MUST introduce a single context entity for document-access-related values that may evolve later.
- This context does not need persistence yet.
- It MUST already support lookup and mutation under current demand so that future persistence can be added without reworking the model.
### 7. Boundary with Build
- Semantic analysis over editorial in-memory state does not authorize build participation.
- No implementation derived from this decision may treat editorial snapshots as canonical build inputs.
- Build-facing transitions require separate decision work.
## Constraints
- This decision does not release frontend editing.
- This decision does not authorize completion.
- This decision does not authorize semantic gating of save because save for frontend files remains out of scope.
- This decision does not authorize external-editor compatibility requirements.
## Revision Log
- 2026-03-31: Initial accepted decision from AGD-0014.
- 2026-03-31: Clarified frontend scope source-of-truth via `FrontendSpec.allowedExtensions`, hardened frontend read-only semantics, and locked frontend highlight to LSP semantic output while non-frontend highlight remains Studio-local.