--- id: PX-PLAN-LSPMV8Q2 type: plan title: LSP Navigation MVP spec: PX-SPEC-LSP4N8Q2 status: approved depends_on: [] --- ## Outcome Pi can resolve Go definitions, references, and hover through one `lsp` tool using installed gopls. Queries remain useful after edits; missing tools, uncertainty, cancellation, and shutdown are honest and bounded. Implements first slice of [Agent LSP Navigation](../../specs/PX-SPEC-LSP4N8Q2-agent-lsp-navigation/index.md). ## Behavior dependencies Each behavior extends the working native Pi tool, not an isolated layer. ```mermaid flowchart TB D["Resolve a Go usage"] --> R["Find usages and inspect types"] R --> F["Query again after edits"] F --> C["Cancel and close safely"] C --> P["Use relocated package in Pi"] ``` ## Implementation boundaries All runtime ownership stays under `extensions/lsp/`; no sibling imports or Helix editor runtime. | Module | Responsibility | | --- | --- | | `index.ts`, `src/tool.ts` | Lazy registration, operation/input contract, native Pi results | | `src/registry.ts`, `registry/servers.json` | Validated local profiles, provenance, file/server/root resolution | | `src/client.ts` | Owned server sessions, protocol exchange, capabilities, cancellation, teardown | | `src/source.ts` | Disk snapshots, document versions, URI and position conversion, change information | | `src/result.ts` | Normalized evidence, budgets, statuses, freshness/completeness qualifiers | Use `vscode-languageserver-protocol` typed connection/transport APIs rather than custom JSON-RPC framing. Declare only actual direct imports in owning manifest with repository dependency policy; preserve root `package-lock.json` through `//:lock`. Integrate generated settings/debug helpers through codegen; no startup server launch or repository scan. ## Ordered behaviors 1. **Resolve an actual usage through Pi.** Add normal extension/package/task integration and a small committed gopls profile curated from pinned Helix data with provenance. `tool.ts`, `registry.ts`, `client.ts`, and `source.ts` carry one definition query end to end, including initialization and incoming configuration requests. Explicit workspace bounds root discovery; nested-root/server ambiguity returns candidates rather than silently reusing another context. Missing executable, invalid profile, unsupported capability, and invalid input return actionable outcomes without installation or repair. 2. **Find references and inspect inferred information.** Extend the same dispatch/client/result path for references and hover. Inputs and result ranges use one-based lines and one-based Unicode-scalar columns; convert negotiated LSP encodings internally. Bound results/context and client waits; disclose tool truncation, reported server limits, unknown completeness, and unknown readiness. Display source context as current snapshot evidence without asserting unverifiable server/source revision correspondence. 3. **Repeat queries against changing disk content.** `source.ts` synchronizes managed documents and relevant observed changes before querying; `client.ts` isolates sessions by root and effective configuration. Cover Pi edits, external edits to open files and unopened dependencies, Unicode, and distinct workspace roots. Unverifiable workspace/index freshness stays unknown; no exhaustive scanning/indexing subsystem. Preserve correct no-result/error distinctions instead of interpreting every empty response as semantic absence. 4. **Cancel and release ownership predictably.** `client.ts` bounds concurrent requests, live sessions, message/output sizes, startup, query, and shutdown waits. Cancellation/deadlines settle the tool locally; late replies cannot overwrite that result or contaminate later queries. Reject server-requested edits/command execution through the extension; own child-process cleanup across session teardown/reload/shutdown. Use actual process termination evidence, not a sent shutdown notification, to verify cleanup. 5. **Use the built extension outside its checkout.** Declare registry runtime resource in `package.json`; integrate `README.md`, `mise.toml`, generated settings/debug targets, and package verification. Build through `//:build-ext lsp`; verify relocation and real Pi tool use with installed gopls. Keep startup cheap; measure added startup/context impact using repository tooling and report unavailable measurements explicitly. ## Verification - Required `__tests__/contract.test.ts` uses `test/fixture/create-pi-session.ts`; focused source/result tests use deterministic protocol peers for unsupported, malformed, delayed, canceled, and mutation-request paths. - Owned subprocess tests cover configuration replies, request races, URI/Unicode conversion, edit synchronization, root/config separation, and stubborn process cleanup in OS temp. - New `//extensions/lsp:live` exercises built native Pi tool plus real gopls on known positive/negative fixtures; missing prerequisites block this gate rather than pass via skips. - Add extension `lint`, `test`, `check`, and `verify-package` tasks using existing root orchestration; validate Mise definitions. - Run affected tasks during iteration, relocation/live gate at slice completion, and root `//:check` at integration; no implicit full CI or unrelated E2E. ## Exit criteria - [ ] Built Pi tool returns correct Go definitions, references, and hover with documented positions and bounded evidence. - [ ] Known edits and root/config changes do not silently reuse stale document targets or incompatible server sessions. - [ ] Unknown readiness, workspace freshness, and server completeness remain explicit; failures are not empty successes. - [ ] Cancellation/deadlines prevent late success; teardown terminates all owned server work within bounds. - [ ] Focused checks, real-server native Pi use, relocation, and startup/context evidence are recorded. ## Deferred to completion slice Remaining navigation operations, actionable ambiguous call targets, one-hop call hierarchy, upstream registry importer, and TypeScript/C++ profiles. [Completion plan](../PX-PLAN-LSPCP6R4-lsp-navigation-complete/index.md) depends on this usable baseline.