clean up
This commit is contained in:
-136
@@ -1,136 +0,0 @@
|
||||
---
|
||||
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
@@ -1,155 +0,0 @@
|
||||
---
|
||||
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.
|
||||
-142
@@ -1,142 +0,0 @@
|
||||
---
|
||||
id: DEC-0012
|
||||
ticket: studio-frontend-owned-semantic-editor-presentation
|
||||
title: Frontend-owned semantic editor presentation via FrontendSpec-derived descriptor
|
||||
status: accepted
|
||||
created: 2026-04-02
|
||||
accepted: 2026-04-02
|
||||
agenda: AGD-0015
|
||||
plans:
|
||||
- PLN-0026
|
||||
- PLN-0027
|
||||
- PLN-0028
|
||||
tags:
|
||||
- studio
|
||||
- editor
|
||||
- frontend
|
||||
- presentation
|
||||
- semantic-highlighting
|
||||
- compiler
|
||||
- pbs
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
The semantic editor presentation for frontend documents SHALL be frontend-owned.
|
||||
|
||||
Normative decision:
|
||||
|
||||
1. Each frontend MUST publish its own semantic vocabulary.
|
||||
2. Each frontend MUST publish its own semantic highlight resources.
|
||||
3. Neither Studio nor LSP SHALL own frontend semantic presentation assets.
|
||||
4. The canonical source of this contract MUST live in `FrontendSpec`.
|
||||
5. LSP MUST act only as a hub/contract bridge between frontend metadata and Studio consumption.
|
||||
6. LSP MUST NOT reduce frontend semantics into a shared artificial vocabulary such as `fe-keyword`, `fe-type`, or equivalent host-owned categories.
|
||||
7. Studio MUST consume the frontend semantic presentation contract without reinterpreting frontend semantics.
|
||||
8. Studio MUST project semantic keys to CSS classes mechanically, without semantic translation tables.
|
||||
9. If semantic presentation metadata or usable resources are absent at runtime, Studio SHALL not apply semantic highlight for that frontend document.
|
||||
10. Studio MUST NOT replace missing frontend presentation with a generic host-owned fallback theme.
|
||||
|
||||
## Rationale
|
||||
|
||||
The prior arrangement centralized frontend semantic colors in Studio under a generic `fe.css` presentation. That arrangement was acceptable as an early integration shortcut, but it violates the intended boundary of a multi-frontend editor:
|
||||
|
||||
- Studio owns rendering surfaces and editor UX.
|
||||
- The frontend owns semantic meaning.
|
||||
- Semantic presentation is part of that frontend-owned meaning.
|
||||
|
||||
If Studio remains the owner of semantic presentation, every additional frontend either:
|
||||
|
||||
- collapses into a weak common denominator,
|
||||
- negotiates language-specific editorial rules inside the host,
|
||||
- or forces Studio to accumulate language-owned semantics.
|
||||
|
||||
That is the wrong ownership direction.
|
||||
|
||||
LSP is also not the correct owner. Its role in this design is to bridge frontend analysis products into host consumption, not to normalize, reinterpret, or host language assets.
|
||||
|
||||
This decision therefore locks the boundary as follows:
|
||||
|
||||
- frontend owns semantic vocabulary,
|
||||
- frontend owns semantic presentation assets,
|
||||
- `FrontendSpec` is the canonical contract source,
|
||||
- LSP derives and transports a consumable descriptor,
|
||||
- Studio renders what the frontend publishes.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Canonical Contract Source
|
||||
|
||||
1. `FrontendSpec` MUST carry the semantic presentation contract.
|
||||
2. `FrontendSpec` SHALL remain a static specification surface.
|
||||
3. The semantic presentation contract MUST be frontend-owned and versionable together with the frontend.
|
||||
|
||||
### 2. Contract Shape
|
||||
|
||||
The initial semantic presentation contract MUST remain simple but complete.
|
||||
|
||||
It SHALL include, at minimum:
|
||||
|
||||
1. `semanticKeys`
|
||||
2. `resources`
|
||||
|
||||
These fields MUST be carried inside a single descriptor/message so the contract can evolve without scattering related presentation metadata across multiple unrelated surfaces.
|
||||
|
||||
At minimum:
|
||||
|
||||
- `semanticKeys` defines the frontend-owned stable semantic keys consumable by the editor pipeline.
|
||||
- `resources` defines the frontend-owned presentation resources, including the stylesheet resource used for semantic highlight.
|
||||
|
||||
### 3. Frontend Semantic Vocabulary
|
||||
|
||||
1. Semantic keys MUST be produced from a frontend-owned semantic vocabulary, for example `SemanticKind -> semanticKey`.
|
||||
2. A semantic key MUST be stable enough to serve as contract output.
|
||||
3. The name of this contract field SHOULD be `semanticKey`, not `cssKey`, because the key is not owned by CSS and may serve multiple consumers.
|
||||
|
||||
### 4. LSP Responsibility
|
||||
|
||||
1. LSP MUST derive a semantic presentation descriptor from the `FrontendSpec` resolved during analysis.
|
||||
2. LSP MUST expose that descriptor to Studio.
|
||||
3. LSP MUST NOT translate frontend semantic keys into host-owned generic categories.
|
||||
4. LSP MUST NOT become the owner of frontend stylesheets or semantic resources.
|
||||
|
||||
### 5. Studio Responsibility
|
||||
|
||||
1. Studio MUST remain the owner of rendering, style application, and editor UI plumbing.
|
||||
2. Studio MUST NOT define frontend semantic vocabulary.
|
||||
3. Studio MUST map semantic keys into CSS classes mechanically.
|
||||
4. That mapping MUST be syntactic only, not semantic.
|
||||
|
||||
Illustrative direction:
|
||||
|
||||
- frontend semantic key: `pbs-function`
|
||||
- Studio-applied class: `editor-semantic-pbs-function`
|
||||
|
||||
The exact class projection convention MAY be specified later, but the projection MUST remain mechanical and MUST NOT introduce host-owned semantic translation.
|
||||
|
||||
### 6. Resource Ownership and Resolution
|
||||
|
||||
1. Frontend semantic presentation resources MUST live under the frontend's own `resources/` surface.
|
||||
2. These resources MUST be resolved like ordinary Java resources.
|
||||
3. Studio and LSP MUST consume these resources through the contract and MUST NOT duplicate or host them as owners.
|
||||
|
||||
### 7. Validation and Runtime Behavior
|
||||
|
||||
1. Deep runtime validation in Studio is NOT required.
|
||||
2. Frontend teams SHOULD cover semantic presentation publication with frontend tests.
|
||||
3. If descriptor data is present and resources are usable, Studio SHOULD apply semantic highlight.
|
||||
4. If descriptor data is absent or resources are unusable, Studio SHALL continue without semantic highlight.
|
||||
5. This condition MUST NOT surface as a product-facing Studio error.
|
||||
6. At most, normal development logs MAY record the condition.
|
||||
|
||||
## Constraints
|
||||
|
||||
1. This decision does NOT change FE edit rights.
|
||||
2. This decision does NOT revise `DEC-0011`; it refines ownership and contract shape for semantic presentation only.
|
||||
3. This decision MUST NOT be implemented by reintroducing a generic host-owned `fe.css` fallback.
|
||||
4. This decision MUST NOT be implemented by collapsing language semantics into generic host-owned semantic buckets.
|
||||
5. Any future expansion of the descriptor MUST preserve frontend ownership and the single-descriptor principle established here.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-02: Initial accepted decision from AGD-0015.
|
||||
Reference in New Issue
Block a user