LSP distribution strategy for VSCode extension (avoid bundling multi-platform binaries)

[emil14]

Problem

vscode-neva currently needs to ship LSP binaries for multiple OS/arch targets, which makes every extension release large and tightly couples extension publishing cadence with backend binary updates.

This issue tracks how VSCode should obtain and run Neva LSP going forward.

Important clarification

This is not about moving LSP into neva CLI in the nevalang/neva repository.

• Canonical LSP source lives in nevalang/neva-lsp.
• The question here is extension-side distribution/runtime strategy.

Goals

• Keep extension package small.
• Avoid shipping all platform binaries in every extension release.
• Keep UX simple for end users.
• Keep CLI / extension / LSP version compatibility manageable.

Candidate directions

1. Extension-managed install (Go-style):
   • extension downloads platform-specific neva-lsp on demand
   • verifies checksums/signatures
   • stores binary in extension global storage
   • supports update + rollback policy
2. External tool management:
   • user installs neva-lsp separately (brew, scoop, apt, etc.)
   • extension resolves from PATH and reports actionable diagnostics if missing
3. Hybrid:
   • prefer external neva-lsp if present
   • otherwise offer one-click managed install

Questions to resolve

• Version handshake policy: must LSP match CLI exactly, or tolerate a semver window?
• Who owns updates: extension auto-update vs explicit command (Neva: Update Language Tools)?
• How to support air-gapped/corporate environments?
• Should we introduce a shared "tool manager" concept for future Neva tools (formatter, debugger, etc.)?

Acceptance criteria

• Chosen strategy documented in repo docs.
• Extension no longer bundles all LSP binaries.
• Clear install/update UX in VSCode.
• Compatibility and fallback behavior explicitly defined.

Related context

• Migrated from nevalang/neva issue: Remove LSP binaries from VSCode-Neva and instead include to Neva-CLI neva#879

[emil14]

Reference points from other ecosystems for LSP/tool distribution:

• Go (VS Code): extension installs/manages tools separately, uses pinned command-line tool versions, and supports explicit Install/Update Tools workflow.
  • https://github.com/golang/vscode-go/wiki/tools
• Rust (rust-analyzer): extension keeps server alongside extension install and can download matching server binary on update; also supports no-server VSIX + manual server.path.
  • https://rust-analyzer.github.io/book/vs_code.html
• Zig (ZLS): ZLS is a standalone server with separate install guidance; toolchain compatibility is explicitly called out (keep Zig and ZLS in sync).
  • https://github.com/zigtools/zls
  • https://zigtools.org/zls/install/
• Kotlin (kotlin-lsp): offers both VS Code extension packaging and a standalone LSP distribution artifact.
  • https://github.com/Kotlin/kotlin-lsp
  • https://github.com/Kotlin/kotlin-lsp/releases
• Nim: nimlangserver is distributed as a separate tool (nimble install nimlangserver) and editor integrations consume it.
  • https://github.com/nim-lang/langserver
• Crystal: VS Code flow expects separate crystalline binary path configuration.
  • https://github.com/elbywan/crystalline
• Odin: ols is a separate language server binary; editor clients point to it.
  • https://github.com/DanielGavin/ols

Common patterns worth adopting:

1. Keep extension thin; avoid shipping all OS/arch binaries in one package.
2. Treat LSP as first-class separately versioned tool.
3. Provide explicit install/update UX and a server.path override.
4. Define compatibility contract (strict match vs semver window) and publish it.

[emil14]

Adding Neva-specific constraints and intent from project discussion so we keep this actionable long-term.

Clarified problem framing

• The core pain is extension release bloat (shipping binaries for all platforms in each VSIX) and release coupling.
• This issue is not "move LSP into neva CLI".
• LSP implementation ownership is already externalized (nevalang/neva-lsp), so vscode-neva should focus on distribution/runtime strategy.

Architecture guardrails for Neva

1. Keep neva-lsp as separately versioned artifact (independent release cadence).
2. Keep VSCode extension thin (no multi-platform binary bundle by default).
3. Define explicit compatibility contract between:
   • vscode-neva extension version
   • neva-lsp version
   • neva CLI/toolchain version

Options to evaluate (Neva-specific)

1. PATH-first + managed fallback (recommended starting point)
   • if neva-lsp exists in PATH, use it
   • otherwise offer one-click install/download of platform-specific binary
2. Optional facade command in CLI ecosystem (e.g. neva tool ...)
   • acts as UX facade / launcher for external tools
   • does not imply embedding LSP implementation into neva repository
3. Dedicated version manager (separate project is acceptable)
   • manage multiple installed versions of neva and neva-lsp
   • support pinning/selection per workspace or project

Product/UX requirements to capture early

• Neva: Install Language Tools
• Neva: Update Language Tools
• neva-lsp.path setting override
• actionable diagnostics when binary is missing/incompatible
• offline/air-gapped installation path

Cross-ecosystem pattern summary

• Go: extension-managed tooling + explicit install/update command.
• Rust: extension can fetch matching server; also supports manual server path.
• Zig/Nim/Odin/Crystal/Kotlin: widely use standalone LSP binaries with editor integration.

Net: industry trend is to treat LSP as an external tool with explicit tool management, not as a permanent multi-platform payload inside VSIX.