housekeeping

This commit is contained in:
2026-05-08 09:17:43 +01:00
parent 0e6a2cd5bc
commit ef814b2420
16 changed files with 215 additions and 1274 deletions
@@ -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.
@@ -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.