implements PLN-0065

This commit is contained in:
2026-05-05 15:50:55 +01:00
parent e5342e34f7
commit b0073cd7bd
32 changed files with 1445 additions and 277 deletions
+2 -1
View File
@@ -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.