244 lines
15 KiB
Markdown
244 lines
15 KiB
Markdown
---
|
|
id: AGD-0013
|
|
ticket: studio-editor-write-wave-supported-non-frontend-files
|
|
title: Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE
|
|
status: accepted
|
|
created: 2026-03-31
|
|
resolved: 2026-03-31
|
|
decision: DEC-0010
|
|
tags:
|
|
- studio
|
|
- editor
|
|
- workspace
|
|
- write
|
|
- read-only
|
|
- vfs
|
|
- frontend-boundary
|
|
---
|
|
|
|
## Pain
|
|
|
|
O `Code Editor` do Studio ja saiu da fase de abertura somente leitura e agora existe pressao para iniciar a wave de edicao de arquivos.
|
|
|
|
Mas o recorte pedido nao e "liberar escrita para tudo".
|
|
O recorte correto e mais estreito:
|
|
|
|
- editar apenas arquivos aceitos pelo sistema;
|
|
- manter todos os arquivos relacionados ao frontend (`FE`) em `read-only` nesta etapa;
|
|
- e evitar que o editor misture, por inferencia, tres conceitos diferentes:
|
|
- arquivo suportado para abrir,
|
|
- arquivo elegivel para highlight/presentacao,
|
|
- arquivo elegivel para mutacao e persistencia.
|
|
|
|
Se isso nao for fechado agora, a wave de escrita corre risco de nascer com uma regra pobre:
|
|
|
|
- ou o editor libera escrita para qualquer texto suportado;
|
|
- ou empilha `ifs` locais no `EditorWorkspace`;
|
|
- ou trata "arquivo do FE" apenas como detalhe visual, sem uma politica operacional clara de mutabilidade.
|
|
|
|
## Context
|
|
|
|
Domain owner: `studio`
|
|
Owner surface: `docs/specs/studio`
|
|
|
|
Superficies e referencias relevantes:
|
|
|
|
- `docs/specs/studio/5. Code Editor Workspace Specification.md` ainda trava a wave atual como `read-only`;
|
|
- `docs/specs/studio/6. Project Document VFS Specification.md` ja moveu classificacao de suporte e abertura de documento para `prometeu-vfs`;
|
|
- `discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md` consolida que a primeira wave do editor foi propositalmente somente leitura;
|
|
- `discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md` consolida que o editor deve consumir um boundary documental, nao virar owner de runtime de filesystem;
|
|
- `FilesystemProjectDocumentVfs` hoje diferencia:
|
|
- arquivos `json`/`ndjson`,
|
|
- arquivos `bash`,
|
|
- arquivos do frontend pela linguagem registrada,
|
|
- e `text` generico;
|
|
- `EditorWorkspace` ainda marca o `CodeArea` como `setEditable(false)`, ou seja, a wave de escrita exigira revisao normativa e nao apenas um ajuste tecnico.
|
|
|
|
Clarificacao importante para esta discussion:
|
|
|
|
- "arquivo aceito" nesta agenda significa arquivo que o sistema aceita abrir como documento textual no boundary atual;
|
|
- isso nao implica automaticamente que o arquivo e editavel;
|
|
- "arquivo relacionado ao FE" tambem nao pode ficar como intuicao editorial solta;
|
|
- a fronteira precisa virar regra operacional explicita, provavelmente no boundary documental ou em politica derivada dele;
|
|
- a verificacao deve ficar no `prometeu-vfs`, usando o enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`.
|
|
|
|
## Open Questions
|
|
|
|
- [x] O criterio canonico de "arquivo aceito para edicao" deve ser o mesmo universo de documentos suportados para abrir; a politica de acesso do `prometeu-vfs` decide se cada documento suportado fica `read-only` ou `editable` nesta wave.
|
|
- [x] "Relacionado ao FE" deve ser definido no `prometeu-vfs` pelo enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`.
|
|
- [x] Fora do escopo classificado como `FE`, a wave editavel inicial fica limitada aos tipos textuais ja suportados hoje: `text`, `json`, `ndjson` e `bash`.
|
|
- [x] O bloqueio de escrita para FE deve usar o item `read-only` na status bar, com espaco para evoluir para icone de cadeado aberto/fechado e futuro toggle de edicao; arquivos `FE` `read-only` tambem devem mostrar alerta no topo informando que nao podem ser salvos e que qualquer alteracao sera perdida.
|
|
- [x] A politica de acesso documental deve morar sempre no `prometeu-vfs`, inclusive para `load` e `save`.
|
|
- [x] A primeira wave de edicao inclui snapshot em memoria para documentos editaveis e persistencia em disco no `save` a partir desse snapshot.
|
|
- [x] O menu global `Save` nao deve ser usado para este fluxo; `save` e acao local do editor e deve viver numa barra de comandos no topo do editor, inicialmente com `Save` e `Save All`.
|
|
- [x] Tabs com arquivos FE `read-only` podem coexistir com tabs editaveis nao-FE no mesmo workspace, com estados visuais diferentes.
|
|
- [x] Os arquivos editaveis desta wave nao fazem parte da build em si.
|
|
- [x] O snapshot editavel em memoria desta wave deve permanecer contido e separado do snapshot documental usado pelos fluxos que participam da build.
|
|
|
|
## Options
|
|
|
|
### Option A - Liberar escrita para todo arquivo textual suportado
|
|
- **Approach:** Tratar todo `VfsTextDocument` como potencialmente editavel, exceto binarios ou sem handler.
|
|
- **Pro:** Menor custo inicial e quase nenhum metadado novo.
|
|
- **Con:** Viola diretamente o recorte pedido, porque arquivos de FE tambem passariam a ser editaveis ou exigiriam excecoes tardias e espalhadas.
|
|
- **Maintainability:** Baixa. A regra nasce ampla demais e depois precisa ser recortada por remendos.
|
|
|
|
### Option B - Manter suporte no VFS e derivar editabilidade so no `EditorWorkspace`
|
|
- **Approach:** O `prometeu-vfs` continua apenas dizendo se o arquivo abre, e o editor decide localmente se aquele documento fica `read-only` ou editavel.
|
|
- **Pro:** Mudanca pequena no boundary atual.
|
|
- **Con:** Regride a disciplina arquitetural recente; o editor volta a carregar regra de produto que deveria ser compartilhavel e auditavel.
|
|
- **Maintainability:** Media para baixa. Funciona rapido, mas enfraquece o boundary documental.
|
|
|
|
### Option C - Introduzir uma politica explicita de acesso documental acima do VFS
|
|
- **Approach:** Manter o `prometeu-vfs` como owner de suporte/abertura e adicionar uma classificacao explicita de `document access mode`, distinguindo ao menos `unsupported`, `read-only` e `editable`.
|
|
- **Pro:** Separa corretamente:
|
|
- abrir o documento,
|
|
- classificar o documento,
|
|
- e decidir se esta wave permite mutacao.
|
|
- **Con:** Exige desenhar melhor onde essa politica mora e como ela chega ao editor sem inflar o contrato cedo demais.
|
|
- **Maintainability:** Forte. O sistema ganha uma regra clara e evolutiva para waves futuras.
|
|
|
|
### Option D - Colocar a politica de editabilidade dentro do contrato documental do `prometeu-vfs`
|
|
- **Approach:** O proprio boundary documental passa a devolver metadados normativos de acesso, incluindo se o documento e `editable` ou `read-only` nesta wave.
|
|
- **Pro:** Mantem suporte, tipo documental e politica de acesso no mesmo owner, reduzindo ambiguidade nos consumidores.
|
|
- **Con:** Exige desenhar com cuidado o snapshot editavel em memoria, o ciclo de `save` e a fronteira do que continua fora da build.
|
|
- **Maintainability:** Forte, desde que o contrato permaneça estreito e centrado em acesso documental, nao em UX.
|
|
|
|
## Discussion
|
|
|
|
As discussoes anteriores fecharam duas coisas importantes:
|
|
|
|
1. o editor nao deve fingir semantica de IDE cedo demais;
|
|
2. o editor nao deve voltar a ser owner de concerns documentais que ja foram movidos para `prometeu-vfs`.
|
|
|
|
Isso significa que a wave de escrita precisa evitar dois erros simetricos:
|
|
|
|
- liberar mutacao ampla demais e quebrar o recorte de produto;
|
|
- ou resolver a restricao de FE com condicionais locais no `EditorWorkspace`, quebrando a separacao arquitetural que acabou de ser criada.
|
|
|
|
O ponto mais delicado aqui e que "arquivo textual aceito" e "arquivo editavel nesta etapa" ja nao sao a mesma coisa.
|
|
Hoje o sistema ja consegue abrir um conjunto de documentos textuais, inclusive documentos associados ao frontend.
|
|
Mas o pedido atual cria uma nova regra de produto:
|
|
|
|
- alguns arquivos suportados continuarao `read-only`;
|
|
- e isso nao acontece por incapacidade tecnica de abrir o arquivo, mas por decisao deliberada de wave.
|
|
|
|
Portanto, o modelo tende a precisar de uma superficie nova de classificacao.
|
|
Se ela nao existir, o editor fica tentado a usar heuristicas locais:
|
|
|
|
- `typeId == languageId`
|
|
- path em source roots
|
|
- extensao
|
|
- ou combinacoes desses sinais
|
|
|
|
Esse caminho e rapido, mas ruim.
|
|
Ele espalha a politica de mutabilidade pelo consumidor errado.
|
|
|
|
Tambem houve um fechamento importante para a decisao:
|
|
|
|
- o recorte canonico de `FE` deve ser verificado no `prometeu-vfs`;
|
|
- essa verificacao deve usar o enquadramento do `typeId` contra `allowedExtensions` do `FrontendSpec`;
|
|
- e o editor deve apenas consumir essa classificacao pronta, sem rederivar a regra localmente.
|
|
|
|
Se isso nao for fechado, o time pode permitir escrita em arquivos do frontend por acidente apenas porque eles aparecem como `text`, `json` ou outro tipo textual generico.
|
|
|
|
Outro fechamento importante desta agenda e que a primeira whitelist editavel nao cresce alem do que o produto ja suporta hoje como texto:
|
|
|
|
- `text`
|
|
- `json`
|
|
- `ndjson`
|
|
- `bash`
|
|
|
|
Ou seja, a wave inicial de edicao nao abre novo suporte documental.
|
|
Ela apenas permite mutacao em um subconjunto dos documentos textuais que ja existem hoje, excluindo o escopo classificado como `FE`.
|
|
|
|
Tambem ja existe um fechamento arquitetural relevante sobre ownership:
|
|
|
|
- a politica de acesso nao deve viver em policy layer solta no `studio`;
|
|
- `prometeu-vfs` deve ser o owner de `load`, `save` e da classificacao `read-only` versus `editable`;
|
|
- para documentos editaveis desta wave, o VFS deve manter um snapshot em memoria durante a sessao;
|
|
- quando houver `save`, o VFS persiste em disco o conteudo desse snapshot;
|
|
- o editor consome esse estado e dispara a intencao de salvar, mas nao reimplementa a politica nem o fluxo de persistencia.
|
|
|
|
Tambem ficou fechado que o universo canonico de documentos continua sendo o conjunto suportado pelo VFS.
|
|
O que muda nao e o universo de abertura, mas a politica de acesso aplicada a cada documento suportado:
|
|
|
|
- alguns suportados permanecem `read-only`, como o escopo de `FE`;
|
|
- outros suportados podem entrar como `editable` nesta wave;
|
|
- e essa decisao continua centralizada no `prometeu-vfs`.
|
|
|
|
Isso empurra a agenda com mais forca para a direcao de `Option D`.
|
|
|
|
Outro limite importante tambem ficou explicitado:
|
|
|
|
- os arquivos editaveis desta wave nao participam da build em si;
|
|
- portanto, a wave de escrita nao pode inferir integracao com pipeline, recompilacao, invalidacao de artefatos ou qualquer contrato de build;
|
|
- o escopo aqui e documental/editorial, nao de toolchain.
|
|
- isso tambem significa que o snapshot editavel em memoria nao deve se misturar com snapshots documentais ou entradas que alimentem a build;
|
|
- deve existir contencao clara entre:
|
|
- o estado editorial temporario usado pela sessao de edicao;
|
|
- e o estado documental/build-facing que outros fluxos do sistema possam consumir.
|
|
|
|
Essa contencao importa porque "ter snapshot em memoria" nao pode virar permissao implicita para o restante do produto observar rascunhos editoriais como se fossem input canonico de build.
|
|
|
|
A direcao mais coerente hoje parece ser preservar o boundary documental e introduzir um conceito explicito de politica de acesso.
|
|
Essa politica pode morar:
|
|
|
|
1. dentro do `prometeu-vfs`, se quisermos que o owner documental responda tambem pela mutabilidade da wave;
|
|
2. ou numa camada de policy ainda no dominio `studio`, mas acima do VFS, desde que o `EditorWorkspace` continue apenas consumindo a decisao pronta.
|
|
|
|
Com o fechamento atual, a agenda ja converge para descartar a segunda alternativa.
|
|
O que parece fraco e empurrar isso para o `EditorWorkspace`, e o usuario tambem ja fechou que a politica de acesso deve passar sempre por `prometeu-vfs`.
|
|
|
|
No plano de UX, a direcao tambem ficou suficiente para a proxima etapa:
|
|
|
|
- o estado `read-only` de `FE` deve aparecer na status bar;
|
|
- essa superficie pode evoluir mais tarde para um toggle explicito de habilitar/desabilitar edicao por arquivo;
|
|
- o `prometeu-vfs` deve, portanto, ja nascer pensando em contexto persistente de acesso por documento;
|
|
- `Save` e `Save All` nao pertencem ao menu global do shell e sim ao editor, em uma barra de comandos propria no topo;
|
|
- arquivos `FE` `read-only` nao podem ser salvos;
|
|
- ao abrir esse tipo de arquivo, o editor deve mostrar um alerta no topo informando que ele e `read-only` e que qualquer alteracao sera perdida.
|
|
|
|
Tambem vale registrar desde ja a implicacao para um futuro `prometeu-lsp` integrado ao Studio:
|
|
|
|
- o objetivo nao e portar o suporte das linguagens Prometeu para VSCode ou para um editor externo;
|
|
- portanto, a agenda de escrita nao deve introduzir dependencia de protocolo externo como fundamento da edicao;
|
|
- um futuro `prometeu-lsp` integrado deve ser tratado como consumidor semantico in-process ou Studio-owned acima do mesmo substrate de sessao, e nao como dono da politica de acesso documental;
|
|
- esse consumidor futuro deve observar o estado documental/snapshots editoriais necessarios para analise, sem colapsar a contencao entre estado editorial temporario e inputs canonicos de build;
|
|
- `read-only` para `FE` nesta wave significa apenas bloqueio de mutacao editorial, nao proibicao de leitura ou analise semantica futura;
|
|
- a integracao semantica continua sendo tema de decisao propria e nao deve ser inferida automaticamente a partir desta wave de escrita.
|
|
|
|
Observacao cravada para o proximo ciclo:
|
|
|
|
- quando o escopo de `FE` for liberado para edicao, o `prometeu-lsp` integrado ao Studio deve entrar em questao como consumidor do conteudo disponibilizado pelo `prometeu-vfs`;
|
|
- para documentos abertos, a analise deve enxergar o snapshot em memoria da sessao;
|
|
- para documentos nao abertos, a analise pode ler o estado em filesystem exposto pelo mesmo boundary;
|
|
- isso reforca que `prometeu-vfs` precisa permanecer como substrate documental canonico do editor e da futura analise semantica integrada.
|
|
|
|
## Resolution
|
|
|
|
Esta agenda convergiu para uma direcao suficiente para `decision`.
|
|
|
|
Recomendacao final: evoluir para uma decisao que introduza uma classificacao explicita de acesso documental para o `Code Editor`, separando:
|
|
|
|
1. arquivo nao suportado;
|
|
2. arquivo suportado porem `read-only`;
|
|
3. arquivo suportado e editavel.
|
|
|
|
Fechamentos aceitos:
|
|
|
|
- manter todo arquivo relacionado ao `FE` em `read-only` nesta wave;
|
|
- deixar o `prometeu-vfs` verificar se o `typeId` do documento cai no conjunto de `allowedExtensions` do `FrontendSpec`;
|
|
- manter como universo canonico os mesmos documentos suportados para abrir, sem criar registro paralelo de elegibilidade fora do `prometeu-vfs`;
|
|
- limitar a wave editavel inicial, fora do escopo de `FE`, aos tipos ja suportados hoje: `text`, `json`, `ndjson` e `bash`;
|
|
- fazer `prometeu-vfs` ser o owner de `load`, snapshot editavel em memoria e `save` em disco para esses documentos;
|
|
- tratar essa wave como escopo documental que nao participa da build em si;
|
|
- manter contencao explicita entre snapshot editorial em memoria e qualquer snapshot/build-input de carater canonico;
|
|
- expor o estado `read-only` de `FE` na status bar, com espaco para futura evolucao a toggle por arquivo;
|
|
- adicionar uma barra de comandos no topo do editor com `Save` e `Save All`, em vez de usar o menu global do shell;
|
|
- permitir coexistencia de tabs `read-only` de `FE` com tabs editaveis nao-`FE`;
|
|
- e mostrar alerta no topo para arquivos `FE` informando que sao `read-only`, nao podem ser salvos e que qualquer alteracao sera perdida.
|
|
- registrar que um futuro `prometeu-lsp` integrado ao Studio deve consumir o mesmo substrate de sessao/documentos sem virar owner da politica de acesso ou forcar compatibilidade com editor externo.
|
|
|
|
Next step suggestion: converter esta agenda em `decision` normativa para propagar a wave de escrita controlada do editor para specs, plano e implementacao.
|