implements PLN-0065
This commit is contained in:
@@ -1,4 +1,5 @@
|
||||
{"type":"meta","next_id":{"DSC":32,"AGD":35,"DEC":32,"PLN":65,"LSN":47,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":33,"AGD":36,"DEC":33,"PLN":68,"LSN":47,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0032","status":"in_progress","ticket":"studio-new-lsp-api-and-v1-boundary","title":"Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code","created_at":"2026-05-05","updated_at":"2026-05-05","tags":["studio","lsp","vscode","protocol","api","boundary"],"agendas":[{"id":"AGD-0035","file":"AGD-0035-studio-new-lsp-api-and-v1-boundary.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05"}],"decisions":[{"id":"DEC-0032","file":"DEC-0032-studio-new-lsp-api-and-v1-boundary.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05","ref_agenda":"AGD-0035"}],"plans":[{"id":"PLN-0065","file":"PLN-0065-lsp-boundary-and-module-scaffolding.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]},{"id":"PLN-0066","file":"PLN-0066-project-scoped-lsp-server-lifecycle-in-studio.md","status":"open","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]},{"id":"PLN-0067","file":"PLN-0067-compiler-backed-dumb-lsp-server-baseline.md","status":"open","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0032"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0031","status":"in_progress","ticket":"studio-editor-workspace-cleanup","title":"Limpeza completa do Workspace Editor do Studio e remoção dos acoplamentos legados","created_at":"2026-05-05","updated_at":"2026-05-05","tags":["studio","editor","cleanup","vfs","lsp","migration"],"agendas":[{"id":"AGD-0034","file":"AGD-0034-vscode-editor-migration-feasibility.md","status":"accepted","created_at":"2026-05-05","updated_at":"2026-05-05"}],"decisions":[{"id":"DEC-0031","file":"DEC-0031-studio-editor-workspace-cleanup.md","status":"in_progress","created_at":"2026-05-05","updated_at":"2026-05-05","ref_agenda":"AGD-0034"}],"plans":[{"id":"PLN-0062","file":"PLN-0062-shell-session-and-state-cleanup-after-editor-removal.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0063","file":"PLN-0063-legacy-lsp-and-vfs-module-removal-with-runtime-preservation.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0064","file":"PLN-0064-normative-test-and-lesson-cleanup-for-editor-stack-removal.md","status":"done","created_at":"2026-05-05","updated_at":"2026-05-05","ref_decisions":["DEC-0031"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0030","status":"done","ticket":"studio-scene-pack-runtime-binary-contract","title":"Studio scene pack contract for runtime SCENE binary payload","created_at":"2026-04-24","updated_at":"2026-05-01","tags":["studio","packer","runtime","scene","asset-pack","binary-format","tiled"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0030-studio-scene-pack-runtime-binary-contract/LSN-0046-canonical-scene-owns-editorial-truth-while-pack-stays-request-driven.md","status":"done","created_at":"2026-05-01","updated_at":"2026-05-01"}]}
|
||||
{"type":"discussion","id":"DSC-0029","status":"done","ticket":"studio-frame-composer-syscall-and-sprite-alignment","title":"Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["studio","compiler","pbs","stdlib","runtime-alignment","abi","syscall","frame-composer","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
id: AGD-0035
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code
|
||||
status: accepted
|
||||
created: 2026-05-05
|
||||
resolved: 2026-05-05
|
||||
decision: DEC-0032
|
||||
tags: [studio, lsp, vscode, protocol, api, boundary]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
O stack legado de editor, `prometeu-lsp` e `prometeu-vfs` acabou de ser removido. O próximo passo natural é reconstruir o backend de linguagem, mas sem repetir o erro anterior de misturar engine semântica, transporte LSP, sessão editorial e host UI em um único desenho.
|
||||
|
||||
Ao mesmo tempo, já existe uma extensão em `tools/vscode-extension` que hoje sabe conectar via TCP em `127.0.0.1:7777` e falar LSP como cliente real. Isso reduz incerteza no lado do FE, mas aumenta a exigência arquitetural do backend: o servidor novo precisa nascer com boundary correto.
|
||||
|
||||
O risco central é reintroduzir acoplamento acidental entre:
|
||||
|
||||
- contratos internos de linguagem;
|
||||
- transporte externo LSP;
|
||||
- implementação concreta baseada em `LSP4J`;
|
||||
- e necessidades específicas do VS Code.
|
||||
|
||||
## Context
|
||||
|
||||
- O cleanup do stack legado foi fechado por `DEC-0031`.
|
||||
- A extensão VS Code já existe em `tools/vscode-extension`.
|
||||
- A extensão usa `vscode-languageclient` e conecta por socket TCP configurável.
|
||||
- O usuário quer explicitamente que `LSP4J` **não vaze** de `lsp-v1`.
|
||||
- A intenção geral do produto é que o Studio fale a própria língua internamente e exponha adapters externos para FEs, no mesmo espírito já discutido para integrações como Tiled.
|
||||
|
||||
Hoje, a pergunta não é "como implementar o LSP inteiro", mas sim:
|
||||
|
||||
- que módulos recriar;
|
||||
- qual boundary o `lsp-api` realmente deve carregar;
|
||||
- e qual responsabilidade cabe a `lsp-v1` como adapter concreto.
|
||||
|
||||
Também já existe um direcionamento adicional do produto:
|
||||
|
||||
- `lsp-v1` deve consumir serviços existentes de `compiler`;
|
||||
- `lsp-api` deve expor funcionalidades reutilizáveis por outras partes do sistema;
|
||||
- o bootstrap do servidor deve acontecer quando um projeto é aberto, e o shutdown quando o projeto é fechado;
|
||||
- a API pode começar mínima, por exemplo com `boot server` e `shutdown server`, e crescer só quando houver necessidade real.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] O `lsp-api` deve expor contratos próprios de domínio/serviço ou DTOs alinhados diretamente ao protocolo LSP?
|
||||
R: o lsp-api deve expor somente servicos que serao usados por outras partes do sistema, e nao ser um espelho do protocolo.
|
||||
- [x] O `lsp-v1` deve ser somente um adapter `LSP4J` sobre serviços internos de `compiler`, ou também pode carregar parte da orquestração de sessão?
|
||||
R: O lsp-v1 deve conter o servidor e todo o necessario para falar LSP, incluindo DTOs e dependencias de LSP4J (e fazer uso de compiler quando necessario). o start e o stop do servidor podem ser chamados via lsp-api, mas a logica de orquestracao de sessao deve ficar dentro do lsp-v1.
|
||||
- [x] O lifecycle de bootstrap/shutdown do servidor por projeto pertence ao `lsp-api`, ao `lsp-v1`, ou a outro serviço do Studio?
|
||||
R: o contrato fica no lsp-api, mas a logica de orquestracao fica no lsp-v1. o lsp-api pode expor um contrato como `bootServer(project)` e `shutdownServer(project)`, mas a implementacao concreta e a logica de associar o servidor ao projeto fica no lsp-v1.
|
||||
- [x] O canal de automação (`compile/build/run/debug`) deve viver fora do novo `lsp-api` desde o início?
|
||||
R: o canal de automacao deve viver fora do lsp-api. nesse primeiro momento o foco principal deve ser o LSP e o comportamento editorial/semantico. o canal de automacao pode ser discutido e implementado separadamente, sem misturar responsabilidades.
|
||||
- [x] O `tools/vscode-extension` deve continuar falando LSP puro em socket TCP, ou o produto precisa reservar outra estratégia de transporte já nesta fase?
|
||||
R: o vscode-extension deve continuar falando LSP puro em socket TCP. o lsp-api deve ser agnóstico ao transporte, mas ainda aceito recomendacoes q sejam mais faceis ou performaticas.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - `lsp-api` como API diretamente moldada pelo protocolo LSP
|
||||
- **Approach:** recriar `lsp-api` com tipos e serviços muito próximos da superfície do protocolo, deixando `lsp-v1` apenas como bootstrap `LSP4J` e roteamento para `compiler`.
|
||||
- **Pro:** acelera integração com o cliente existente e reduz tradução entre camadas.
|
||||
- **Con:** tende a tornar o protocolo externo dono do desenho interno; muda mal quando surgir outro FE ou outro adapter.
|
||||
- **Maintainability:** fraca. O risco de vazamento conceitual do protocolo para dentro do domínio é alto, mesmo sem importar classes `LSP4J` fora de `lsp-v1`.
|
||||
|
||||
### Option B - `lsp-api` mínima e operacional; `lsp-v1` como adapter LSP4J que consome `compiler`
|
||||
- **Approach:** `lsp-api` expõe uma surface mínima e reutilizável para o sistema, começando com operações como `boot server(project)` e `shutdown server(project)` e, no máximo, contratos estáveis que outras partes do Studio precisem enxergar. `lsp-v1` concentra a implementação concreta do servidor, depende exclusivamente de `LSP4J`, e consome os serviços do `compiler` para responder às capacidades LSP.
|
||||
- **Pro:** respeita a regra de não vazamento de `LSP4J`, evita inflar a API cedo demais e alinha o lifecycle do servidor ao projeto aberto, não ao processo global do Studio.
|
||||
- **Con:** exige disciplina para não transformar `lsp-api` em um espelho parcial do protocolo nem `lsp-v1` em um segundo backend semântico solto do `compiler`.
|
||||
- **Maintainability:** forte. O backend nasce hexagonal e o custo de evolução fica mais previsível.
|
||||
|
||||
### Option C - Sem `lsp-api`; expor apenas um servidor LSP concreto em `lsp-v1`
|
||||
- **Approach:** pular a separação e concentrar tudo em um único módulo novo de servidor, com contratos locais apenas package-private ou internos.
|
||||
- **Pro:** menor custo inicial de scaffolding.
|
||||
- **Con:** repete exatamente o tipo de colapso arquitetural que gerou o legado descartado; dificulta teste, substituição de transporte e integração com outros FEs.
|
||||
- **Maintainability:** ruim. A velocidade inicial é comprada com dívida estrutural imediata.
|
||||
|
||||
## Discussion
|
||||
|
||||
O dado novo mais importante é que o cliente VS Code já está funcional como cliente LSP puro. Isso elimina a necessidade de desenhar o protocolo "pensando no editor". O editor já sabe falar LSP; quem precisa de disciplina agora é o Studio.
|
||||
|
||||
Isso empurra a arquitetura para uma separação bem objetiva:
|
||||
|
||||
- `lsp-api` não deve ser "API pública do protocolo";
|
||||
- `lsp-api` deve ser uma API interna e mínima do backend de linguagem do Studio;
|
||||
- `lsp-v1` deve ser o adapter LSP concreto e consumidor dos serviços de `compiler`;
|
||||
- `LSP4J` deve existir exclusivamente em `lsp-v1`.
|
||||
|
||||
O ponto sensível é não confundir "API interna" com "engine concreta". Se `lsp-api` virar um lugar para pôr qualquer detalhe de sessão, thread, socket, `CompletableFuture` de transporte, ou estruturas do `LSP4J`, ele já nasce errado. Pelo direcionamento atual, a API deve começar deliberadamente estreita:
|
||||
|
||||
- boot do servidor por projeto;
|
||||
- shutdown do servidor por projeto;
|
||||
- e só depois crescer quando outro consumidor real do sistema exigir isso.
|
||||
|
||||
Também vale separar desde já o que não pertence ao LSP:
|
||||
|
||||
- `compile/build/run/debug` não devem entrar no `lsp-api` por conveniência;
|
||||
- esses fluxos pertencem a um contrato de automação paralelo;
|
||||
- o LSP deve se limitar ao que é comportamento editorial/semântico.
|
||||
|
||||
Outro ponto: o usuário já fixou que o Studio é o backend autoritativo e o cliente externo é só cliente. Isso reforça que o lifecycle do servidor precisa acompanhar o projeto aberto. Em outras palavras:
|
||||
|
||||
- abrir Studio não implica subir servidor LSP global;
|
||||
- abrir projeto pode implicar subir o servidor LSP daquele projeto;
|
||||
- fechar projeto deve encerrar o servidor correspondente.
|
||||
|
||||
As respostas atuais também fecharam um boundary operacional importante:
|
||||
|
||||
- quem "fala LSP" de verdade é o `lsp-v1`;
|
||||
- `lsp-api` não é adapter nem espelho do protocolo;
|
||||
- `lsp-api` existe para expor um boundary interno consumível pelo Studio;
|
||||
- o contrato mínimo inicial pode ser pequeno, desde que suficiente para boot/shutdown por projeto;
|
||||
- DTOs, tipos e dependências do protocolo podem existir em `lsp-v1` sem contaminar a API interna.
|
||||
|
||||
## Resolution
|
||||
|
||||
Direção recomendada para convergir:
|
||||
|
||||
1. recriar `lsp-api` como surface interna mínima e reutilizável do sistema, começando com bootstrap e shutdown por projeto;
|
||||
2. recriar `lsp-v1` como adapter LSP/JSON-RPC concreto, com dependência exclusiva de `LSP4J`;
|
||||
3. fazer `lsp-v1` consumir serviços existentes de `compiler`, em vez de reconstruir pipeline semântico próprio;
|
||||
4. deixar a lógica concreta de orquestração de sessão e associação `projeto -> servidor` dentro de `lsp-v1`, mesmo quando o bootstrap/shutdown for disparado através de `lsp-api`;
|
||||
5. tratar qualquer tipo `LSP4J` fora de `lsp-v1` como violação arquitetural;
|
||||
6. manter `tools/vscode-extension` como cliente LSP puro em socket TCP;
|
||||
7. discutir separadamente o contrato de automação para `compile/build/run/debug`, em vez de empurrá-lo para dentro do LSP.
|
||||
|
||||
Neste ponto, a agenda já tem direção clara o bastante para virar `decision`. O que ainda resta fechar depois disso é implementação, não escolha arquitetural principal.
|
||||
@@ -0,0 +1,196 @@
|
||||
---
|
||||
id: DEC-0032
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: Boundary normativo entre lsp-api, lsp-v1 e a extensao VS Code
|
||||
status: accepted
|
||||
created: 2026-05-05
|
||||
accepted: 2026-05-05
|
||||
agenda: AGD-0035
|
||||
plans: [PLN-0065, PLN-0066, PLN-0067]
|
||||
tags: [studio, lsp, vscode, protocol, api, boundary, compiler]
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
O repositório SHALL reconstruir o stack de linguagem do Studio com separação explícita entre:
|
||||
|
||||
1. `lsp-api` como boundary interno do Studio;
|
||||
2. `lsp-v1` como adapter LSP/JSON-RPC concreto;
|
||||
3. `compiler` como owner dos serviços semânticos e de análise consumidos por esse adapter;
|
||||
4. `tools/vscode-extension` como cliente externo que continua falando LSP puro via socket TCP.
|
||||
|
||||
Esta decisão ALSO locks os seguintes pontos:
|
||||
|
||||
1. `lsp-api` MUST NOT ser espelho do protocolo LSP;
|
||||
2. `lsp-api` MUST expor apenas funcionalidades internas realmente consumíveis por outras partes do Studio;
|
||||
3. `lsp-api` MAY começar mínima, por exemplo com contratos como `bootServer(project)` e `shutdownServer(project)`;
|
||||
4. `lsp-v1` MUST concentrar o servidor LSP concreto, os DTOs de protocolo, o transporte e qualquer dependência de `LSP4J`;
|
||||
5. `LSP4J` MUST NOT vazar para fora de `lsp-v1`;
|
||||
6. `lsp-v1` MUST consumir serviços existentes de `compiler` em vez de reconstruir pipeline semântico próprio;
|
||||
7. o lifecycle do servidor LSP MUST ser associado à abertura e ao fechamento de projeto, não à abertura global do processo Studio;
|
||||
8. o atual `lsp-v1` presente hoje no repositório serve apenas como mock de conectividade VS Code ↔ Studio e MUST NOT ser tratado como padrão arquitetural, base estrutural ou referência de implementação do backend definitivo.
|
||||
9. a primeira onda de implementação desta decisão SHALL priorizar arquitetura, lifecycle e separação de responsabilidades, mesmo que o comportamento LSP permaneça deliberadamente simples ou "dumb" por um período controlado.
|
||||
|
||||
## Rationale
|
||||
|
||||
O stack legado anterior foi removido justamente porque misturava responsabilidades erradas e criou boundaries frágeis entre UI, sessão, semântica e transporte.
|
||||
|
||||
Ao mesmo tempo, o projeto já tem dois fatos importantes:
|
||||
|
||||
1. a extensão VS Code já existe e já sabe atuar como cliente LSP puro;
|
||||
2. o Studio já possui serviços de `compiler` que devem continuar sendo a fonte real de comportamento semântico.
|
||||
|
||||
Logo, o problema não é "inventar um cliente" nem "reescrever a semântica". O problema é definir corretamente:
|
||||
|
||||
1. o que é boundary interno reutilizável do Studio;
|
||||
2. o que é adapter concreto de protocolo;
|
||||
3. e onde termina a influência do protocolo externo.
|
||||
|
||||
Essa separação reduz acoplamento, melhora teste e evita que detalhes de `LSP4J` ou do transporte contaminem o restante da base.
|
||||
|
||||
Também existe uma prioridade explícita de rollout:
|
||||
|
||||
1. primeiro consolidar a arquitetura;
|
||||
2. depois adicionar capacidade semântica por camadas;
|
||||
3. sem obrigar a primeira implementação a já ser semanticamente rica.
|
||||
|
||||
Isso evita repetir o padrão anterior de crescer funcionalidade em cima de uma base estrutural errada.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Module Roles
|
||||
|
||||
`lsp-api` MUST ser tratado como módulo de boundary interno do Studio.
|
||||
|
||||
Ele SHALL:
|
||||
|
||||
1. expor somente contratos que façam sentido para outros consumidores internos do sistema;
|
||||
2. permanecer agnóstico ao protocolo LSP concreto;
|
||||
3. permanecer agnóstico a `LSP4J`;
|
||||
4. permanecer agnóstico ao transporte TCP ou a qualquer detalhe de socket;
|
||||
5. começar com surface mínima suficiente para o lifecycle do servidor por projeto.
|
||||
|
||||
`lsp-v1` MUST ser tratado como o primeiro adapter concreto do boundary acima.
|
||||
|
||||
Ele SHALL:
|
||||
|
||||
1. implementar o servidor LSP;
|
||||
2. carregar os DTOs e tipos de protocolo que forem necessários para falar LSP;
|
||||
3. carregar a dependência de `LSP4J`;
|
||||
4. realizar a tradução entre o mundo do protocolo e os serviços internos consumidos;
|
||||
5. concentrar a lógica concreta de sessão e associação `projeto -> servidor`.
|
||||
|
||||
### 2. LSP4J Containment
|
||||
|
||||
O repositório MUST tratar `LSP4J` como dependência exclusiva de `lsp-v1`.
|
||||
|
||||
Portanto:
|
||||
|
||||
1. nenhum tipo de `LSP4J` MAY aparecer em `lsp-api`;
|
||||
2. nenhum tipo de `LSP4J` MAY aparecer em outros módulos do Studio;
|
||||
3. nenhum contrato de `lsp-api` MAY depender semanticamente de tipos, nomes ou formas obrigadas pelo `LSP4J`;
|
||||
4. qualquer vazamento de `LSP4J` para fora de `lsp-v1` SHALL ser tratado como violação arquitetural.
|
||||
|
||||
### 3. Compiler Ownership
|
||||
|
||||
`lsp-v1` MUST consumir serviços existentes de `compiler` quando precisar responder capacidades editoriais e semânticas.
|
||||
|
||||
Isso implica:
|
||||
|
||||
1. `lsp-v1` MUST NOT reconstruir uma engine semântica paralela por conveniência;
|
||||
2. `lsp-v1` MUST preferir compor sobre entrypoints e serviços canônicos do `compiler`;
|
||||
3. qualquer lacuna percebida no `compiler` para servir o novo backend SHALL ser tratada como evolução explícita do `compiler`, e não como autorização para duplicação semântica dentro de `lsp-v1`.
|
||||
|
||||
### 4. Server Lifecycle
|
||||
|
||||
O lifecycle do servidor MUST ser project-scoped.
|
||||
|
||||
Regras:
|
||||
|
||||
1. abrir o processo Studio MUST NOT implicitamente significar "subir um servidor LSP global";
|
||||
2. abrir um projeto MAY disparar `bootServer(project)` através do boundary exposto por `lsp-api`;
|
||||
3. fechar um projeto MUST disparar `shutdownServer(project)` para o servidor correspondente;
|
||||
4. a implementação concreta desse bootstrap/shutdown e o vínculo entre projeto e instância do servidor MUST residir em `lsp-v1`.
|
||||
|
||||
### 5. Internal API Minimalism
|
||||
|
||||
`lsp-api` MUST nascer pequeno.
|
||||
|
||||
Ele SHALL:
|
||||
|
||||
1. expor apenas o que outro consumidor interno realmente precise enxergar;
|
||||
2. evitar DTOs de protocolo sem necessidade;
|
||||
3. evitar antecipar capacidades futuras sem consumidor real;
|
||||
4. crescer somente quando houver pressão concreta de uso interno.
|
||||
|
||||
O contrato inicial mínimo aceito por esta decisão é:
|
||||
|
||||
1. `bootServer(project)`
|
||||
2. `shutdownServer(project)`
|
||||
|
||||
Contratos adicionais MAY ser adicionados depois, mas não fazem parte do lock inicial desta decisão.
|
||||
|
||||
### 6. VS Code Transport
|
||||
|
||||
`tools/vscode-extension` SHALL permanecer cliente LSP puro via socket TCP nesta fase.
|
||||
|
||||
Isso implica:
|
||||
|
||||
1. a extensão atual pode continuar evoluindo nesse modelo;
|
||||
2. `lsp-api` MUST permanecer agnóstico a esse transporte;
|
||||
3. mudanças futuras de transporte MAY ser discutidas depois, mas não fazem parte do boundary normativo inicial.
|
||||
|
||||
### 7. Current Mock Status
|
||||
|
||||
O `lsp-v1` que existe hoje para testes de conectividade entre VS Code e Studio MUST ser tratado como mock transitório.
|
||||
|
||||
Ele MUST NOT:
|
||||
|
||||
1. servir de blueprint estrutural do novo servidor;
|
||||
2. servir de contrato implícito do sistema;
|
||||
3. servir de justificativa para manter responsabilidades colapsadas;
|
||||
4. contaminar o padrão de código alvo do backend definitivo.
|
||||
|
||||
O backend definitivo SHALL priorizar:
|
||||
|
||||
1. separação clara de responsabilidades;
|
||||
2. boundaries pequenos e explícitos;
|
||||
3. código fácil de manter;
|
||||
4. composição sobre serviços canônicos do `compiler`;
|
||||
5. isolamento rígido do adapter de protocolo.
|
||||
|
||||
### 8. Implementation Wave 1
|
||||
|
||||
A primeira onda de implementação derivada desta decisão MUST focar em transformar o mock atual em uma estrutura sólida de trabalho.
|
||||
|
||||
Essa onda SHALL incluir:
|
||||
|
||||
1. `lsp-api` mínimo com bootstrap e shutdown por projeto;
|
||||
2. `lsp-v1` organizado como adapter concreto limpo, mesmo que ainda responda um conjunto reduzido ou simplificado de capacidades;
|
||||
3. boot do servidor quando o projeto abrir;
|
||||
4. shutdown do servidor quando o projeto fechar;
|
||||
5. isolamento explícito entre boundary interno, adapter de protocolo e consumo de `compiler`.
|
||||
|
||||
Essa onda MUST NOT ser bloqueada pela ausência de "carne semântica" completa.
|
||||
|
||||
Em outras palavras:
|
||||
|
||||
1. é aceitável manter um comportamento LSP inicial deliberadamente simples;
|
||||
2. não é aceitável manter um padrão arquitetural improvisado só porque o comportamento ainda é simples;
|
||||
3. a evolução semântica futura SHALL acontecer por camadas sobre a estrutura consolidada.
|
||||
|
||||
## Constraints
|
||||
|
||||
1. Esta decisão MUST preservar a separação entre boundary interno e adapter externo.
|
||||
2. Esta decisão MUST preservar `compiler` como owner semântico do sistema.
|
||||
3. Esta decisão MUST impedir vazamento de `LSP4J` para fora de `lsp-v1`.
|
||||
4. Esta decisão MUST impedir que o mock atual de conectividade seja usado como padrão do produto.
|
||||
5. Esta decisão MUST manter `compile/build/run/debug` fora do escopo do `lsp-api` nesta fase.
|
||||
6. Qualquer plano derivado desta decisão MUST refletir explicitamente o lifecycle por projeto e a contenção de protocolo em `lsp-v1`.
|
||||
7. O primeiro plano derivado desta decisão MUST priorizar a consolidação estrutural do servidor antes do enriquecimento semântico.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-05-05: Initial draft from AGD-0035.
|
||||
- 2026-05-05: Added explicit phase-1 rollout guidance to solidify architecture before semantic depth.
|
||||
- 2026-05-05: Accepted and decomposed into PLN-0065, PLN-0066, and PLN-0067.
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
id: PLN-0065
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: LSP Boundary and Module Scaffolding
|
||||
status: done
|
||||
created: 2026-05-05
|
||||
completed: 2026-05-05
|
||||
tags: [studio, lsp, api, boundary, modules, architecture]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Recreate `prometeu-lsp:prometeu-lsp-api` and `prometeu-lsp:prometeu-lsp-v1` with a structurally correct boundary that is ready for long-term maintenance, while intentionally keeping the initial server behavior minimal.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0032` locks that:
|
||||
|
||||
- `lsp-api` is an internal Studio boundary, not a mirror of the LSP protocol;
|
||||
- `lsp-v1` is the concrete LSP adapter and the only module allowed to depend on `LSP4J`;
|
||||
- the current mock server shape MUST NOT be treated as the product pattern;
|
||||
- wave 1 prioritizes architecture and lifecycle over semantic depth.
|
||||
|
||||
The repository already reserves `prometeu-lsp:*` in `settings.gradle.kts`, but the modules are currently empty shells after the cleanup.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Recreate Gradle/module structure for `prometeu-lsp-api` and `prometeu-lsp-v1`.
|
||||
- Define the minimal internal API contract for server lifecycle by project.
|
||||
- Establish package boundaries that keep protocol DTOs and `LSP4J` types out of `lsp-api`.
|
||||
- Add boundary-oriented tests or build checks where feasible.
|
||||
|
||||
### Excluded
|
||||
- Wiring the server into Studio project open/close.
|
||||
- Rich semantic behavior, diagnostics, definition, symbols, or incremental analysis.
|
||||
- Automation channel work for `compile/build/run/debug`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Full language feature implementation.
|
||||
- Any attempt to preserve compatibility with the legacy removed `prometeu-lsp`.
|
||||
- Transport changes in the VS Code extension.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Recreate the Gradle modules with explicit dependency ownership
|
||||
|
||||
**What:** Reintroduce the `prometeu-lsp-api` and `prometeu-lsp-v1` modules as clean boundaries.
|
||||
**How:** Restore the module directories and `build.gradle.kts` files, wire them in `settings.gradle.kts`, and keep dependencies explicit:
|
||||
|
||||
- `prometeu-lsp-api` depends only on stable internal modules it truly needs;
|
||||
- `prometeu-lsp-v1` depends on `prometeu-lsp-api`, `compiler` services it consumes, and `LSP4J`;
|
||||
- no other Studio module depends on `LSP4J`.
|
||||
|
||||
**File(s):** `settings.gradle.kts`, `prometeu-lsp/prometeu-lsp-api/build.gradle.kts`, `prometeu-lsp/prometeu-lsp-v1/build.gradle.kts`, affected root/module build files.
|
||||
|
||||
### Step 2 - Define the minimal internal lifecycle contract in `lsp-api`
|
||||
|
||||
**What:** Create the smallest stable API needed by the Studio host.
|
||||
**How:** Add internal contracts such as a project-scoped `bootServer(project)` and `shutdownServer(project)` surface plus the minimal supporting DTO/entity types required by that lifecycle. Keep the API transport-agnostic and free of protocol DTOs.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-api/src/main/java/**`.
|
||||
|
||||
### Step 3 - Define the adapter shape in `lsp-v1`
|
||||
|
||||
**What:** Establish the internal code organization of the concrete adapter.
|
||||
**How:** Create clear package slices inside `lsp-v1`, such as:
|
||||
|
||||
- lifecycle/bootstrap,
|
||||
- server host/transport,
|
||||
- protocol DTO mapping,
|
||||
- compiler-facing service bridge.
|
||||
|
||||
The implementation may stay behaviorally dumb, but the structure MUST already reflect the final responsibility split.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`.
|
||||
|
||||
### Step 4 - Add boundary conformance tests
|
||||
|
||||
**What:** Prevent architectural drift from day 1.
|
||||
**How:** Add tests or static checks that fail if:
|
||||
|
||||
- `lsp-api` imports `LSP4J`;
|
||||
- protocol DTOs leak into `lsp-api`;
|
||||
- non-`lsp-v1` Studio modules start importing `LSP4J`.
|
||||
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-api/src/test/java/**`, `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`, or build-level checks if that is cleaner.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Verify the lifecycle contracts in `lsp-api` have deterministic defaults and null-safety.
|
||||
- Verify `lsp-v1` module-local bootstrap pieces can be instantiated without a running Studio shell.
|
||||
- Verify boundary checks catch `LSP4J` leakage.
|
||||
|
||||
### Integration Tests
|
||||
- Run a root or targeted Gradle build proving the new modules compile and coexist with `prometeu-studio` and `prometeu-app`.
|
||||
|
||||
### Manual Verification
|
||||
- Inspect the recreated module tree and confirm `lsp-api` contains no protocol or `LSP4J` types.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] `prometeu-lsp-api` and `prometeu-lsp-v1` exist again as active modules.
|
||||
- [x] `lsp-api` exposes only internal lifecycle-oriented contracts.
|
||||
- [x] `lsp-v1` is the only module allowed to depend on `LSP4J`.
|
||||
- [x] The new module structure expresses clear responsibility boundaries even with dumb behavior.
|
||||
- [x] Boundary conformance is covered by tests or equivalent build checks.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0032` accepted and normatively locked.
|
||||
- Current Gradle graph and module includes available for reactivation.
|
||||
|
||||
## Risks
|
||||
|
||||
- Reintroducing the modules too loosely can recreate the same ambiguity that killed the legacy stack.
|
||||
- An underspecified API can force churn later; an oversized API can lock the wrong shape too early.
|
||||
- Build-only enforcement may miss architectural drift unless the checks are explicit.
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
id: PLN-0066
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: Project-Scoped LSP Server Lifecycle in Studio
|
||||
status: open
|
||||
created: 2026-05-05
|
||||
completed:
|
||||
tags: [studio, lsp, lifecycle, projects, boot, shutdown]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Wire the new LSP server lifecycle into the Studio project lifecycle so a server starts when a project opens and stops when that project closes, without introducing a process-global LSP service.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0032` requires a project-scoped server lifecycle and explicitly rejects a global Studio-wide server. The current natural integration points are:
|
||||
|
||||
- `StudioProjectSession`
|
||||
- `StudioProjectSessionFactory`
|
||||
- `StudioWindowCoordinator`
|
||||
|
||||
These surfaces already own project startup and teardown flow and therefore are the correct place to consume `lsp-api`.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Add project-scoped LSP server ownership to the Studio project session lifecycle.
|
||||
- Boot the server during project open.
|
||||
- Shutdown the server during project close.
|
||||
- Preserve existing shell, packer, play/stop, and debug flows.
|
||||
|
||||
### Excluded
|
||||
- Rich semantic responses.
|
||||
- Automation channel work.
|
||||
- VS Code extension transport changes.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Cross-project shared server process management.
|
||||
- Multi-project pooling or server reuse.
|
||||
- Changing the overall launcher/window model.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Extend project session ownership to include the LSP lifecycle boundary
|
||||
|
||||
**What:** Make `StudioProjectSession` own the new project-scoped LSP service reference.
|
||||
**How:** Add the minimal `lsp-api` contract to `StudioProjectSession`, ensure it is initialized by `StudioProjectSessionFactory`, and guarantee shutdown on `close()`, including failure-safe teardown ordering.
|
||||
**File(s):** `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`, `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSessionFactory.java`, related tests.
|
||||
|
||||
### Step 2 - Trigger boot during project open flow
|
||||
|
||||
**What:** Start the LSP server as part of project initialization.
|
||||
**How:** Update the project-open sequence so the server boots after the project context is ready and before the project window is considered fully opened. Ensure failures surface as project-open failures instead of becoming silent background errors.
|
||||
**File(s):** `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java`, possibly `prometeu-app/src/main/java/p/studio/AppContainer.java` and `prometeu-studio/src/main/java/p/studio/Container.java` if dependency injection changes are needed.
|
||||
|
||||
### Step 3 - Trigger shutdown during project close flow
|
||||
|
||||
**What:** Cleanly stop the project-bound server when the project closes.
|
||||
**How:** Ensure the existing project close path tears down the LSP service through the session close path, with no leaked socket listener or hanging background resources.
|
||||
**File(s):** `prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java`, `prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java`.
|
||||
|
||||
### Step 4 - Preserve current dumb connectivity semantics
|
||||
|
||||
**What:** Keep the initial server behavior intentionally simple while validating lifecycle.
|
||||
**How:** Wire the server so the VS Code extension can still connect over TCP, even if the server behavior remains a minimal handshake or stubbed capability set for now.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`, `tools/vscode-extension/src/extension.ts` only if configuration or expectations need adjustment.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Verify project session close calls LSP shutdown exactly once.
|
||||
- Verify boot failures are surfaced deterministically during project open.
|
||||
- Verify repeated close remains idempotent.
|
||||
|
||||
### Integration Tests
|
||||
- Run `prometeu-studio` tests covering project open/close lifecycle.
|
||||
- Add a focused integration test proving a project-scoped server is booted and then shut down.
|
||||
|
||||
### Manual Verification
|
||||
- Open a Studio project, confirm the server starts.
|
||||
- Close the project, confirm the server port is released and the process/resources terminate.
|
||||
- Connect via the existing VS Code extension and confirm the dumb server remains reachable.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Opening a Studio project boots an LSP server for that project.
|
||||
- [ ] Closing the project shuts down that server.
|
||||
- [ ] The lifecycle is owned by project session boundaries, not global app startup.
|
||||
- [ ] Existing non-LSP project flows remain operational.
|
||||
- [ ] The current dumb connectivity workflow remains usable as a temporary implementation phase.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0032` accepted and normatively locked.
|
||||
- `PLN-0065` providing the new module and API boundary.
|
||||
|
||||
## Risks
|
||||
|
||||
- Startup ordering mistakes can make project open flaky or hide boot errors.
|
||||
- Shutdown ordering mistakes can leak ports or threads.
|
||||
- Lifecycle wiring can accidentally reintroduce global process ownership if the session boundary is not kept strict.
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
id: PLN-0067
|
||||
ticket: studio-new-lsp-api-and-v1-boundary
|
||||
title: Compiler-Backed Dumb LSP Server Baseline
|
||||
status: open
|
||||
created: 2026-05-05
|
||||
completed:
|
||||
tags: [studio, lsp, compiler, baseline, protocol, vscode]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Establish a maintainable, compiler-backed baseline inside `lsp-v1` that keeps the server behavior deliberately simple while creating the seams required for later semantic layering.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0032` explicitly allows wave 1 to remain semantically thin, but it forbids keeping an ad hoc mock structure as the long-term coding pattern. The backend therefore needs a baseline that is:
|
||||
|
||||
- dumb in behavior when necessary,
|
||||
- but already correctly composed over `compiler` services,
|
||||
- and already structured for layered enrichment later.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Create compiler-facing service seams used by `lsp-v1`.
|
||||
- Provide a small, explicit set of LSP capabilities or responses that prove the adapter shape.
|
||||
- Keep the VS Code extension compatible with the current TCP model.
|
||||
- Document the temporary behavioral limits in code and tests.
|
||||
|
||||
### Excluded
|
||||
- Full diagnostics, definition, symbols, inlay hints, or multi-file semantic completeness.
|
||||
- Automation channel work.
|
||||
- Non-TCP transport experiments.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Matching the full final language feature set.
|
||||
- Recreating the deleted legacy `prometeu-lsp` behavior.
|
||||
- Optimizing for performance before the baseline structure is validated.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Define compiler-facing bridge services inside `lsp-v1`
|
||||
|
||||
**What:** Introduce explicit bridge classes or adapters between protocol handlers and `compiler`.
|
||||
**How:** Create narrow services inside `lsp-v1` that own calls into `compiler` entrypoints. Even if the first concrete responses are stubbed or partial, the protocol handlers must already call through these seams instead of embedding compiler knowledge everywhere.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`, relevant `prometeu-compiler` integration points when discoverable.
|
||||
|
||||
### Step 2 - Implement a minimal but structured capability slice
|
||||
|
||||
**What:** Keep the server intentionally dumb, but no longer structurally improvised.
|
||||
**How:** Choose a small capability surface such as `initialize`, `shutdown`, and one lightweight language feature or health response. The exact feature set may stay narrow, but the code must already follow the final layering:
|
||||
|
||||
- protocol request handling,
|
||||
- bridge service invocation,
|
||||
- result mapping.
|
||||
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/**`, potentially `tools/vscode-extension/src/extension.ts` if initialization expectations need tightening.
|
||||
|
||||
### Step 3 - Codify temporary behavior limits
|
||||
|
||||
**What:** Make the current limitations explicit instead of implicit.
|
||||
**How:** Add tests and lightweight documentation/comments that define the intentionally supported baseline behavior so future work can add capability in layers without guessing what the "mock" currently means.
|
||||
**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`, targeted source comments where they reduce ambiguity.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Verify protocol handlers call the correct bridge services.
|
||||
- Verify compiler bridge services can be instantiated and return stable baseline results.
|
||||
- Verify no handler bypasses the bridge layer to embed semantic logic ad hoc.
|
||||
|
||||
### Integration Tests
|
||||
- Run a targeted Studio/LSP integration proving the VS Code client can initialize against the dumb server.
|
||||
- Run compiler-related tests needed to validate the consumed service seams.
|
||||
|
||||
### Manual Verification
|
||||
- Connect from VS Code and confirm the server initializes and remains stable.
|
||||
- Confirm the limited capability set behaves predictably and does not masquerade as richer support than actually implemented.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `lsp-v1` talks to `compiler` through explicit bridge services.
|
||||
- [ ] The baseline server behavior remains intentionally simple but structurally clean.
|
||||
- [ ] At least one minimal end-to-end capability slice proves the final layering.
|
||||
- [ ] The extension can still connect over TCP without protocol regressions.
|
||||
- [ ] Temporary semantic limits are explicit in tests and code structure.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0032` accepted and normatively locked.
|
||||
- `PLN-0065` for module/boundary setup.
|
||||
- `PLN-0066` for project-scoped lifecycle integration.
|
||||
|
||||
## Risks
|
||||
|
||||
- A "temporary" dumb server can calcify unless the seams are truly explicit and tested.
|
||||
- Over-stubbing can hide compiler integration issues that should be surfaced early.
|
||||
- Picking too many baseline features in this wave can dilute the architectural focus.
|
||||
Reference in New Issue
Block a user