housekeeping
This commit is contained in:
@@ -1,148 +0,0 @@
|
||||
---
|
||||
id: DEC-0031
|
||||
ticket: studio-editor-workspace-cleanup
|
||||
title: Limpeza completa do Workspace Editor do Studio e remoção dos acoplamentos legados
|
||||
status: in_progress
|
||||
created: 2026-05-05
|
||||
accepted: 2026-05-05
|
||||
agenda: AGD-0034
|
||||
plans: [PLN-0062, PLN-0063, PLN-0064]
|
||||
tags: [studio, editor, cleanup, vfs, lsp, migration]
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
O repositório SHALL remover integralmente o `Workspace Editor` do Studio como superfície ativa do produto.
|
||||
|
||||
Essa remoção SHALL incluir:
|
||||
|
||||
1. o workspace de código embutido em `prometeu-studio`;
|
||||
2. o `prometeu-lsp` legado usado por esse workspace;
|
||||
3. o `prometeu-vfs` legado acoplado ao modelo editorial desse workspace;
|
||||
4. os pontos de integração do shell, da sessão de projeto e do bootstrap que assumem a existência desse stack;
|
||||
5. e os artefatos normativos, testes e referências documentais que tratam esse stack como superfície vigente.
|
||||
|
||||
Ao mesmo tempo, esta decisão ALSO locks que:
|
||||
|
||||
1. a capacidade de compilação dos projetos MUST permanecer disponível no Studio;
|
||||
2. os fluxos atuais de `build`, `play`, `run` e `debug` MUST permanecer funcionais desde que não dependam do editor legado, do `prometeu-lsp` legado ou do `prometeu-vfs` legado;
|
||||
3. esta decisão MUST NOT introduzir o novo backend de código, o novo servidor LSP ou o futuro contrato de automação;
|
||||
4. qualquer reconstrução dessas superfícies MUST acontecer em discussão posterior e separada.
|
||||
|
||||
## Rationale
|
||||
|
||||
O `Workspace Editor`, o `prometeu-lsp` atual e o `prometeu-vfs` atual formam um stack único, criado especificamente para o editor embutido do Studio.
|
||||
|
||||
Esse stack não é mais alinhado à direção do produto:
|
||||
|
||||
1. o editor JavaFX deixou de ser a direção principal;
|
||||
2. o `prometeu-lsp` atual não deve ser tratado como base séria para um futuro servidor LSP;
|
||||
3. o `prometeu-vfs` atual carrega um contrato editorial pensado para o editor embutido;
|
||||
4. manter esse legado vivo aumenta o custo de reconstrução e preserva boundaries errados por inércia.
|
||||
|
||||
Portanto, a limpeza precisa acontecer antes da reconstrução.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Editor Workspace Removal
|
||||
|
||||
O Studio MUST remover a superfície `Code Editor` do shell.
|
||||
|
||||
Isso inclui:
|
||||
|
||||
1. remover `WorkspaceId.EDITOR`;
|
||||
2. remover o `EditorWorkspace` e todos os controles, painéis, modelos e helpers sob `prometeu-studio/.../workspaces/editor`;
|
||||
3. remover a presença do editor na workspace rail, no layout principal e no fluxo de restauração de shell;
|
||||
4. remover strings, ícones e estado visual exclusivos dessa superfície.
|
||||
|
||||
### 2. Legacy LSP Removal
|
||||
|
||||
O repositório MUST remover o `prometeu-lsp` legado como módulo ativo.
|
||||
|
||||
Isso inclui:
|
||||
|
||||
1. remover os módulos `prometeu-lsp-api` e `prometeu-lsp-v1`;
|
||||
2. remover `LspService`, `LspServiceFactory` e todos os DTOs/messages específicos desse stack legado;
|
||||
3. remover a criação e injeção dessas dependências no `AppContainer`, no `Container`, na sessão de projeto e nos testes associados;
|
||||
4. remover a hipótese de que esse `LSP` será evoluído para o futuro backend de código.
|
||||
|
||||
Os conceitos úteis descobertos nesse stack MAY ser reaproveitados mais tarde, mas esta decisão não preserva compatibilidade de código, pacote ou contrato com ele.
|
||||
|
||||
### 3. Legacy VFS Removal
|
||||
|
||||
O repositório MUST remover o `prometeu-vfs` legado como módulo ativo.
|
||||
|
||||
Isso inclui:
|
||||
|
||||
1. remover os módulos `prometeu-vfs-api` e `prometeu-vfs-v1`;
|
||||
2. remover `VfsProjectDocument`, `ProjectDocumentVfsFactory` e implementações filesystem-backed associadas;
|
||||
3. remover a criação e posse desse `VFS` na sessão de projeto;
|
||||
4. remover qualquer regra que trate esse `VFS` como boundary documental vigente do Studio.
|
||||
|
||||
Esta decisão assume que o `prometeu-vfs` atual pertence ao modelo do editor legado e, portanto, não deve sobreviver por compatibilidade acidental.
|
||||
|
||||
### 4. Session and Shell Cleanup
|
||||
|
||||
O Studio MUST reconfigurar a sessão de projeto e o shell principal para não depender do stack removido.
|
||||
|
||||
Isso inclui:
|
||||
|
||||
1. remover `LSP` e `VFS` legados da estrutura de `StudioProjectSession`;
|
||||
2. remover sua criação em `StudioProjectSessionFactory`;
|
||||
3. remover dependências globais correspondentes do bootstrap e do container;
|
||||
4. remover persistência de layout e restauração editorial específicas do editor.
|
||||
|
||||
### 5. State Cleanup
|
||||
|
||||
O estado local do projeto MUST deixar de persistir dados exclusivos do editor legado.
|
||||
|
||||
Isso inclui:
|
||||
|
||||
1. remover `editorRestoration`;
|
||||
2. remover `shellLayout.editorLayout`;
|
||||
3. garantir fallback seguro para estados antigos já persistidos em `.studio/state.json`;
|
||||
4. preservar apenas os campos ainda pertencentes a workspaces vivos e ao shell remanescente.
|
||||
|
||||
### 6. Documentation and Test Cleanup
|
||||
|
||||
O repositório MUST limpar artefatos normativos e testes que descrevem o stack legado como vigente.
|
||||
|
||||
Isso inclui:
|
||||
|
||||
1. revisar ou remover as specs do `Code Editor`, do `Project Document VFS` e do `Integrated LSP Semantic Read Phase`;
|
||||
2. revisar `docs/specs/studio/README.md`;
|
||||
3. remover ou arquivar testes exclusivos do editor, do `prometeu-lsp` legado e do `prometeu-vfs` legado;
|
||||
4. revisar lessons e referências históricas para deixar explícito que se tratam de legado, quando forem mantidas.
|
||||
|
||||
### 7. Capabilities That MUST Survive
|
||||
|
||||
As seguintes capacidades MUST sobreviver a esta limpeza:
|
||||
|
||||
1. compilação de projetos pelo pipeline canônico existente;
|
||||
2. build de artefatos via `BuilderPipelineService`;
|
||||
3. preparação do fluxo de shipper;
|
||||
4. `play`, `run` e `debug` do Studio, desde que apoiados nas superfícies remanescentes e não no stack removido;
|
||||
5. workspaces `Assets`, `Shipper` e `Debug`, além do launcher e do shell geral.
|
||||
|
||||
### 8. Explicit Non-Goals
|
||||
|
||||
Esta decisão MUST NOT:
|
||||
|
||||
1. definir o novo servidor LSP;
|
||||
2. definir o novo contrato de automação;
|
||||
3. definir o novo modelo de sessão de código;
|
||||
4. definir integração com VS Code;
|
||||
5. reter compatibilidade com o `LSP` ou `VFS` legados por conveniência.
|
||||
|
||||
## Constraints
|
||||
|
||||
1. A limpeza MUST preservar o pipeline canônico `analyze`, `compile` e `build` já existente no compiler.
|
||||
2. A limpeza MUST evitar remover ou degradar fluxos de `build/run/debug` que hoje dependem apenas de `compiler`, `shipper`, runtime e shell.
|
||||
3. A limpeza MUST deixar o shell do Studio em estado coerente, sem workspace fantasma, sem layout órfão e sem dependências mortas.
|
||||
4. A limpeza MUST tratar specs e estado persistido como parte do trabalho, não como detalhe pós-código.
|
||||
5. A futura reconstrução do backend de código SHALL nascer em discussão separada, sem herdar obrigação de compatibilidade com o stack removido.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-05-05: Initial draft from AGD-0034.
|
||||
- 2026-05-05: Accepted and decomposed into PLN-0062, PLN-0063, and PLN-0064.
|
||||
-152
@@ -1,152 +0,0 @@
|
||||
---
|
||||
id: DEC-0033
|
||||
ticket: frontend-visual-theme-spec-and-css-retirement
|
||||
title: Frontend-owned visual theme spec as canonical presentation contract
|
||||
status: accepted
|
||||
created: 2026-05-06
|
||||
accepted: 2026-05-06
|
||||
agenda: AGD-0036
|
||||
plans: [PLN-0068, PLN-0069, PLN-0070, PLN-0071]
|
||||
tags: [compiler, compiler-general, frontend, presentation, theming, studio, vscode, lsp, pbs]
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
Prometeu SHALL replace frontend-authored host-consumed semantic CSS with a structured frontend-owned visual theme specification as the canonical presentation contract.
|
||||
|
||||
This decision locks the following normative points:
|
||||
|
||||
1. Each `FrontendSpec` MUST publish its own semantic vocabulary and MAY publish multiple visual themes for that vocabulary.
|
||||
2. Visual themes MUST be frontend-owned and MUST remain associated with the semantic tokens defined by that same frontend.
|
||||
3. `semantic-highlighting.css` MUST be treated as migration input only and MUST cease to be an authored canonical contract by the end of this refactor.
|
||||
4. Studio and the VS Code extension MUST act as rendering adapters over the frontend-owned visual contract and MUST NOT become owners of frontend theme data.
|
||||
5. The VS Code extension MUST translate the frontend visual contract dynamically or mechanically from the contract itself, so frontend visual adjustments do not require extension maintenance for each theme change.
|
||||
|
||||
## Rationale
|
||||
|
||||
The current model is structurally weak for multi-host consumption.
|
||||
PBS still carries a CSS resource that works as the practical source of visual truth, while VS Code can only consume a partial manual approximation through semantic token configuration.
|
||||
|
||||
That creates the wrong ownership boundary:
|
||||
|
||||
1. the frontend owns semantic meaning but does not fully own its exported visual contract;
|
||||
2. hosts are forced to reinterpret or approximate visual intent;
|
||||
3. every frontend visual adjustment risks requiring host edits;
|
||||
4. visual drift becomes likely across Studio and VS Code.
|
||||
|
||||
The repository already established that semantic presentation belongs to the frontend.
|
||||
This decision extends that ownership model into a stronger cross-host contract:
|
||||
|
||||
1. the frontend authors semantic and visual intent once;
|
||||
2. LSP transports that intent;
|
||||
3. hosts adapt it without redefining it.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Canonical Visual Contract
|
||||
|
||||
`FrontendSpec` MUST evolve to expose a structured visual presentation contract as canonical data.
|
||||
|
||||
That contract MUST:
|
||||
|
||||
1. live with the frontend definition;
|
||||
2. be versioned together with `FrontendSpec`;
|
||||
3. be sufficient for multiple hosts to render the frontend's intended appearance without interpreting CSS as the source of truth;
|
||||
4. remain compiler-general even if PBS is the first frontend to implement it.
|
||||
|
||||
The canonical contract MAY be encoded as JSON-backed structured data or as an equivalent strongly-typed model, but the authored source of truth MUST be the structured visual contract, not CSS.
|
||||
|
||||
### 2. Frontend-Owned Themes
|
||||
|
||||
Each frontend MAY publish multiple visual themes.
|
||||
|
||||
Rules:
|
||||
|
||||
1. themes MUST belong to the frontend that defines the semantic vocabulary they style;
|
||||
2. themes MUST be expressed in terms of that frontend's own semantic token keys and related editor presentation surfaces;
|
||||
3. hosts MAY select which frontend theme is active;
|
||||
4. hosts MUST NOT redefine the theme contract as host-owned authored data.
|
||||
|
||||
This means theme ownership is:
|
||||
|
||||
1. frontend authors themes,
|
||||
2. host selects and applies themes,
|
||||
3. host does not author the frontend visual semantics.
|
||||
|
||||
### 3. Token-Centric Contract with Editor Surfaces
|
||||
|
||||
The visual contract MUST be token-centric, but it SHALL also support editor-level presentation data where needed to preserve frontend visual intent.
|
||||
|
||||
Therefore the contract MUST be able to express:
|
||||
|
||||
1. token-scoped presentation such as foreground, emphasis, and related token styling attributes;
|
||||
2. editor surface colors such as base foreground, selection, gutter, and other editing-surface colors when they are part of frontend visual intent;
|
||||
3. optional frontend-specific accents tied to the editing experience.
|
||||
|
||||
Token-centricity remains mandatory because semantic meaning MUST stay anchored to semantic keys.
|
||||
Editor-surface data is allowed because semantic fidelity alone is insufficient to reproduce frontend identity across hosts.
|
||||
|
||||
### 4. Host Adapter Responsibilities
|
||||
|
||||
Studio and the VS Code extension MUST consume the frontend visual contract as adapters.
|
||||
|
||||
Studio:
|
||||
|
||||
1. MUST consume the structured frontend visual contract;
|
||||
2. MAY render through generated CSS or another host mechanism;
|
||||
3. MUST NOT treat generated CSS as the canonical frontend artifact.
|
||||
|
||||
VS Code extension:
|
||||
|
||||
1. MUST consume the frontend visual contract through the server description path or an equivalent frontend-owned transport surface;
|
||||
2. MUST translate that contract into whatever VS Code requires, whether through runtime translation, generated contributions, or another adapter mechanism;
|
||||
3. MUST behave as a mechanical translator of the frontend contract;
|
||||
4. MUST NOT require hand-maintained extension theme edits whenever a frontend changes a color, emphasis rule, or theme variant.
|
||||
|
||||
### 5. LSP Transport Responsibilities
|
||||
|
||||
The LSP path MUST transport enough structured frontend-owned visual information for hosts to render the active frontend theme.
|
||||
|
||||
It MUST preserve:
|
||||
|
||||
1. frontend identity,
|
||||
2. semantic token identity,
|
||||
3. theme identity where multiple themes exist,
|
||||
4. visual attributes needed by the host adapter.
|
||||
|
||||
LSP MUST NOT collapse frontend themes into host-authored generic theme categories.
|
||||
|
||||
### 6. Migration and CSS Retirement
|
||||
|
||||
`semantic-highlighting.css` is allowed only as migration input for the first structured contract derivation.
|
||||
|
||||
Migration rules:
|
||||
|
||||
1. PBS SHALL be the first frontend migrated;
|
||||
2. the existing PBS CSS MAY be parsed or manually transcribed into the first canonical structured visual contract;
|
||||
3. once the structured contract becomes authoritative, the CSS MUST no longer be treated as authored truth;
|
||||
4. any remaining CSS after migration MAY exist only as generated adapter output or as temporary compatibility residue scheduled for removal;
|
||||
5. the refactor is not complete while host-consumed semantic CSS remains the canonical frontend presentation source.
|
||||
|
||||
### 7. Extension Stability Requirement
|
||||
|
||||
This decision explicitly locks an operational requirement for `tools/vscode-extension`:
|
||||
|
||||
1. frontend visual changes MUST be expressible by changing frontend-owned contract data;
|
||||
2. such frontend changes MUST NOT force routine extension source edits;
|
||||
3. the extension SHALL be stable as a contract adapter rather than a repository of manually curated frontend theme rules.
|
||||
|
||||
## Constraints
|
||||
|
||||
1. The canonical source of frontend visual intent MUST move out of authored CSS.
|
||||
2. Theme ownership MUST remain with the frontend.
|
||||
3. The contract MUST support multiple themes per frontend.
|
||||
4. The contract MUST remain compiler-general and MUST NOT hardcode PBS as the universal model.
|
||||
5. Hosts MUST remain adapters and MUST NOT become fallback authors of frontend visual identity.
|
||||
6. Any derived plan MUST include an explicit migration path for PBS and explicit retirement of `semantic-highlighting.css` as canonical data.
|
||||
7. Any derived plan MUST cover compiler contract changes, transport propagation, Studio consumption, and VS Code consumption.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-05-06: Initial accepted decision from AGD-0036.
|
||||
- 2026-05-06: Decomposed into PLN-0068, PLN-0069, PLN-0070, and PLN-0071.
|
||||
Reference in New Issue
Block a user