179 lines
8.2 KiB
Markdown
179 lines
8.2 KiB
Markdown
---
|
|
id: DEC-0009
|
|
ticket: studio-editor-document-vfs-boundary
|
|
title: Estabelecer `prometeu-vfs` como boundary documental de projeto para o Studio
|
|
status: in_progress
|
|
created: 2026-03-31
|
|
accepted: 2026-03-31
|
|
agenda: AGD-0012
|
|
plans:
|
|
- PLN-0015
|
|
- PLN-0016
|
|
- PLN-0017
|
|
- PLN-0018
|
|
tags:
|
|
- studio
|
|
- editor
|
|
- workspace
|
|
- vfs
|
|
- filesystem
|
|
- boundary
|
|
---
|
|
|
|
## Context
|
|
|
|
O `Code Editor` do Studio ja fechou sua primeira wave como shell editorial read-only, mas a implementacao concreta ainda instancia diretamente servicos filesystem-backed para:
|
|
|
|
- montar a arvore estrutural do projeto;
|
|
- abrir arquivos;
|
|
- carregar conteudo de documentos;
|
|
- e aplicar regras de suporte ou nao suporte a arquivos.
|
|
|
|
Isso mantem concerns de I/O e sincronizacao acoplados ao `EditorWorkspace`, quando o owner correto desses concerns deve ser um boundary documental de projeto.
|
|
|
|
Tambem ficou fechado na agenda que:
|
|
|
|
- esta etapa nao introduz novas capacidades editoriais alem das que o `EditorWorkspace` ja possui hoje;
|
|
- o estado documental precisa continuar vivo mesmo quando o `Code Editor` nao esta em foco;
|
|
- o `Project Navigator` nao deve ver filesystem diretamente;
|
|
- `prometeu-lsp` deve continuar reservado para a futura camada de protocolo/handlers;
|
|
- e packer/assets permanecem fora deste boundary.
|
|
|
|
## Decision
|
|
|
|
1. O repositório SHALL introduzir um novo modulo-base chamado `prometeu-vfs`.
|
|
2. `prometeu-vfs` SHALL ser o boundary documental de projeto consumido pelo Studio para `tree`, `open files` e `document content`.
|
|
3. O Studio MUST passar a tocar o disco atraves de `prometeu-vfs` para o escopo coberto por este boundary.
|
|
4. O escopo desta primeira wave MUST transportar apenas as capacidades hoje existentes no `EditorWorkspace`; nenhuma nova feature editorial SHALL ser adicionada nesta etapa.
|
|
5. `prometeu-vfs` SHALL viver no lifecycle de sessao de projeto do Studio, nao no lifecycle de foco do `EditorWorkspace`.
|
|
6. O snapshot de `prometeu-vfs` MUST cobrir apenas conteudo do projeto.
|
|
7. A `tree` exposta por `prometeu-vfs` MUST ser estrutural e de dados apenas; ela MUST NOT carregar concerns visuais ou view-model concerns de UI.
|
|
8. O `Project Navigator` do Studio SHALL consumir uma entidade que representa a arvore inteira do projeto e MAY solicitar atualizacoes mais pontuais do que um reload completo.
|
|
9. A abertura de arquivos no Studio MUST passar por `prometeu-vfs`, inclusive quando o backend concreto continuar sendo filesystem.
|
|
10. Regras de arquivos, plugins e suporte ou nao suporte MUST morar em `prometeu-vfs`; o Studio SHALL apenas apresentar o erro ou estado resultante.
|
|
11. A API oficial inicial de `prometeu-vfs` SHALL ficar concentrada em RPC/comandos/queries.
|
|
12. `prometeu-vfs` MAY manter eventos internos como parte de seu runtime, mas esses eventos MUST NOT ser publicados como API oficial nesta primeira wave.
|
|
13. `refresh` SHALL permanecer somente manual nesta primeira wave.
|
|
14. `watchers` MUST permanecer fora de escopo desta decisao e MUST NOT ser introduzidos por inferencia durante planning ou implementation.
|
|
15. `prometeu-vfs` SHALL nascer como primitive util do dominio `studio`: hoje para o editor, e futuramente podendo servir `prometeu-lsp`.
|
|
16. `prometeu-lsp` MUST permanecer como namespace/modulo separado, reservado para a futura camada de protocolo/handlers acima de `prometeu-vfs`.
|
|
17. Packer, assets e demais dominios MUST manter ownership proprio e MUST NOT ser absorvidos por `prometeu-vfs` sem decisao posterior explicita.
|
|
|
|
## Rationale
|
|
|
|
Esta decisao fecha a fronteira correta entre shell editorial e runtime documental.
|
|
|
|
O Studio precisa continuar owner de:
|
|
|
|
- layout;
|
|
- controls;
|
|
- navigator visual;
|
|
- estado de apresentacao;
|
|
- e UX de erro.
|
|
|
|
`prometeu-vfs` precisa passar a ser owner de:
|
|
|
|
- leitura estrutural do projeto;
|
|
- resolucao de documentos;
|
|
- abertura de arquivos;
|
|
- regras de suporte;
|
|
- refresh manual;
|
|
- e sincronizacao documental de sessao.
|
|
|
|
Isso remove do `EditorWorkspace` um conjunto de concerns que nao pertencem ao shell.
|
|
|
|
Criar `prometeu-vfs` como modulo novo e superior a renomear `prometeu-lsp` porque:
|
|
|
|
- preserva a hierarquia conceitual correta;
|
|
- evita ruido editorial nos roadmaps ja existentes;
|
|
- e mantem `lsp` como consumidor futuro do substrate documental, nao como nome prematuro do substrate em si.
|
|
|
|
Manter eventos publicos fora da primeira wave tambem e deliberado:
|
|
|
|
- o modulo continua livre para estabilizar sua maquina interna;
|
|
- o contrato externo inicial permanece menor e mais controlado;
|
|
- e nenhum consumidor passa a depender de detalhes de runtime antes da hora.
|
|
|
|
## Technical Specification
|
|
|
|
### 1. Module Boundary
|
|
|
|
- O workspace Gradle MUST incluir um novo modulo `prometeu-vfs`.
|
|
- Esse modulo SHALL ser a superficie de integracao documental do Studio para o escopo coberto por esta decisao.
|
|
- `prometeu-lsp` SHALL permanecer separado e sem reaproveitamento nominal do namespace.
|
|
|
|
### 2. Project Session Ownership
|
|
|
|
- A instancia principal de `prometeu-vfs` MUST pertencer a uma sessao de projeto do Studio.
|
|
- O `EditorWorkspace` MUST consumir essa instancia, e MUST NOT ser o owner do lifecycle documental.
|
|
- Troca de foco entre workspaces MUST NOT destruir o estado documental da sessao.
|
|
|
|
### 3. Filesystem Access
|
|
|
|
- Para o escopo coberto por esta decisao, o Studio MUST acessar o disco atraves de `prometeu-vfs`.
|
|
- O backend inicial de `prometeu-vfs` SHALL ser filesystem-backed.
|
|
- Essa decisao MUST NOT ser interpretada como criacao de um filesystem universal para todos os dominios do produto.
|
|
|
|
### 4. Structural Tree Contract
|
|
|
|
- `prometeu-vfs` MUST expor uma representacao estrutural do projeto inteiro.
|
|
- Essa representacao MUST incluir apenas dados e metadados estruturais/documentais necessarios ao consumo.
|
|
- Essa representacao MUST NOT conter:
|
|
- estado de expansao visual;
|
|
- selecao;
|
|
- foco;
|
|
- scroll;
|
|
- reveal;
|
|
- icones;
|
|
- ou qualquer chrome de navigator.
|
|
- O Studio MAY derivar view models visuais a partir dessa estrutura.
|
|
- O `Project Navigator` MAY solicitar atualizacoes pontuais, sem obrigar reload completo da arvore a cada interacao.
|
|
|
|
### 5. Document and Open-File Contract
|
|
|
|
- Abrir um arquivo no Studio MUST significar resolver esse arquivo atraves de `prometeu-vfs`.
|
|
- O conteudo de documento devolvido por `prometeu-vfs` SHALL representar apenas o estado documental do projeto dentro da sessao atual.
|
|
- Esta decisao MUST NOT ser interpretada como permissao para introduzir novas features de edicao, save, dirty tracking, merge ou write semantics.
|
|
|
|
### 6. Support Rules and Errors
|
|
|
|
- A determinacao de suporte ou nao suporte de um arquivo MUST ocorrer em `prometeu-vfs`.
|
|
- Regras relacionadas a plugins e resolucao de handlers de arquivo MUST morar em `prometeu-vfs`.
|
|
- O Studio SHALL apenas reagir ao resultado, exibindo erro ou estado apropriado com os mecanismos de UI existentes ou futuros.
|
|
|
|
### 7. Communication Model
|
|
|
|
- A API oficial inicial de `prometeu-vfs` MUST ser RPC-oriented.
|
|
- O modulo MAY manter eventos internos para coordenacao de runtime.
|
|
- Esses eventos internos MUST NOT ser expostos como API publica nesta primeira wave.
|
|
- Nenhum plano ou implementacao posterior MAY promover eventos internos a API publica por inferencia; isso exigira decisao posterior explicita.
|
|
|
|
### 8. Refresh and Watchers
|
|
|
|
- `refresh` SHALL permanecer manual.
|
|
- `watchers` MUST permanecer fora de escopo.
|
|
- Nenhum plano posterior MAY introduzir watching automatico por aproximacao arquitetural.
|
|
|
|
### 9. Domain Boundaries
|
|
|
|
- O escopo de `prometeu-vfs` SHALL permanecer restrito ao boundary documental de projeto do dominio `studio`.
|
|
- `prometeu-vfs` MUST NOT absorver responsabilidades do packer.
|
|
- `prometeu-vfs` MUST NOT redefinir ownership de assets.
|
|
- Um futuro `prometeu-lsp` MAY consumir `prometeu-vfs`, mas `prometeu-vfs` MUST NOT depender de uma camada LSP para justificar seu contrato.
|
|
|
|
## Constraints
|
|
|
|
- Esta decisao e normativamente travada ao escopo hoje existente no `EditorWorkspace`.
|
|
- Nenhuma feature nova de editor pode ser adicionada por conveniencia durante a migracao para `prometeu-vfs`.
|
|
- O contrato inicial deve permanecer pequeno o suficiente para planejamento e implementacao direta.
|
|
- Qualquer tentativa de:
|
|
- expor eventos publicos;
|
|
- introduzir watchers;
|
|
- ampliar o snapshot para fora do conteudo do projeto;
|
|
- ou absorver outros dominios;
|
|
exigira nova decisao explicita.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-03-31: Initial draft from AGD-0012.
|