implements PLN-0065
This commit is contained in:
@@ -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