Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

.system/plans/PX-PLAN-LSPMV8Q2-lsp-navigation-mvp/index.md

Raw
Rendered preview

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.

Behavior dependencies

Each behavior extends the working native Pi tool, not an isolated layer.

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 depends on this usable baseline.

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