editor and lsp
This commit is contained in:
+136
@@ -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.
|
||||
+155
@@ -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.
|
||||
Reference in New Issue
Block a user