104 lines
4.8 KiB
Markdown
104 lines
4.8 KiB
Markdown
---
|
|
id: PLN-0066
|
|
ticket: studio-new-lsp-api-and-v1-boundary
|
|
title: Project-Scoped LSP Server Lifecycle in Studio
|
|
status: done
|
|
created: 2026-05-05
|
|
completed: 2026-05-05
|
|
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
|
|
|
|
- [x] Opening a Studio project boots an LSP server for that project.
|
|
- [x] Closing the project shuts down that server.
|
|
- [x] The lifecycle is owned by project session boundaries, not global app startup.
|
|
- [x] Existing non-LSP project flows remain operational.
|
|
- [x] 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.
|