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
@@ -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.