From 94ccc16963180bdd88ce0297c70052a33d25a7c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thomas=20M=C3=BCller?= <thomas.mi.iller.gitea.tmu@gmail.com>
Date: Fri, 18 Sep 2026 07:14:45 +0000
Subject: [PATCH] :heavy_plus_sign: Add the LSP protocol dependency

The autocomplete helper drives tsc --lsp --stdio; vscode-languageserver-protocol
supplies the transport (re-exported vscode-jsonrpc/node) and the typed LSP
requests, replacing the hand-rolled JSON-RPC client. Record the choice and
the rejected alternatives in tooling.md.
---
 development/tooling.md | 34 ++++++++++++++++++++++++++++++++++
 package-lock.json      | 31 ++++++++++++++++++++++++++++++-
 package.json           |  3 ++-
 3 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/development/tooling.md b/development/tooling.md
index d1ab59f..53d3637 100644
--- a/development/tooling.md
+++ b/development/tooling.md
@@ -24,6 +24,8 @@ in [package.json](../package.json).
 - **@spences10/pi-lsp** — read-only LSP code intelligence for AI agents
   (project-local `.pi/settings.json`); talks to this repo's TypeScript 7 via
   `tsc --lsp --stdio`.
+- **vscode-languageserver-protocol** — LSP client and protocol types for the
+  autocomplete test helper (`src/util/__tests__/lsp-completion.ts`).
 
 When each runs is in
 [CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers).
@@ -247,6 +249,38 @@ project.
 - The same script works by hand (whole project) and staged (scoped), so there is
   no second command to maintain.
 
+## Language server tooling
+
+### `vscode-languageserver-protocol` backs the autocomplete helper
+
+#### Decision (2026-09)
+
+The autocomplete helper (`src/util/__tests__/lsp-completion.ts`) drives
+`tsc --lsp --stdio` through `vscode-languageserver-protocol`'s
+`createMessageConnection` and its typed request / notification objects, instead
+of a hand-rolled JSON-RPC client.
+
+#### Why
+
+- Framing, `Content-Length` parsing, the pending-request map and server-request
+  dispatch are protocol plumbing the helper only reimplemented; the official
+  client owns them and tolerates the server's `string | number` ids.
+- `InitializeRequest`, `CompletionRequest`, `DidOpenTextDocumentNotification`,
+  … carry their parameter and result types, so `CompletionList` / `CompletionItem`
+  replace the helper's ad-hoc shape guards.
+- The `./node` entry re-exports `vscode-jsonrpc/node`, so one devDependency
+  supplies both the transport and the protocol types. It is test-only and never
+  ships (`files` publishes `dist/` only).
+
+#### Rejected
+
+- `vscode-languageclient`: the editor-side client with a full feature registry
+  — far more than a test helper needs.
+- Generic JSON-RPC (`jsonrpc-lite`, `jayson`): still no LSP types, so they
+  replace framing only and leave the typed protocol surface unimplemented.
+- Keeping the hand-rolled client: the low-level shape is the maintenance cost
+  the helper exists to remove, and it must be re-audited against the server.
+
 ## Editor and agent tooling
 
 ### VSCode integration
diff --git a/package-lock.json b/package-lock.json
index 116442f..7f0c319 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -27,7 +27,8 @@
                 "oxlint": "^1.83.0",
                 "oxlint-tsgolint": "^7.0.2001",
                 "publint": "^0.3.24",
-                "typescript": "^7.0.2"
+                "typescript": "^7.0.2",
+                "vscode-languageserver-protocol": "^3.18.3"
             },
             "engines": {
                 "node": ">=26"
@@ -4822,6 +4823,27 @@
                 "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
             }
         },
+        "node_modules/vscode-jsonrpc": {
+            "version": "9.0.2",
+            "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-9.0.2.tgz",
+            "integrity": "sha512-SbQSV9yRemARxeXw6LU5sS6Zq0e9/DgCCX5yelH263ZQWukbTk8EF8fjTrr1dziasf4GwlJbvTwFnTrnQFWZXQ==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=14.0.0"
+            }
+        },
+        "node_modules/vscode-languageserver-protocol": {
+            "version": "3.18.3",
+            "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.18.3.tgz",
+            "integrity": "sha512-DF49+WeV5py4zO5hhobp60jjsDSK0lAqA0OuKBLBvp423HPWQcCbhZz3JgyfIewsEz2f8U+X75xNIFHdiXZm2w==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "vscode-jsonrpc": "9.0.2",
+                "vscode-languageserver-types": "3.18.3"
+            }
+        },
         "node_modules/vscode-languageserver-textdocument": {
             "version": "1.0.14",
             "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.14.tgz",
@@ -4829,6 +4851,13 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/vscode-languageserver-types": {
+            "version": "3.18.3",
+            "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.18.3.tgz",
+            "integrity": "sha512-XIlzJ7Qp/jzSI1ds7/FwPAWrPeTZA7pAtlW4hdJ1J6xXWJL6dR9QYnDhJOdLzdKhUQ5Mm6mvUMw+3DcOQQasPw==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/vscode-uri": {
             "version": "3.2.0",
             "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.2.0.tgz",
diff --git a/package.json b/package.json
index 7e83d0f..1b228c5 100644
--- a/package.json
+++ b/package.json
@@ -87,7 +87,8 @@
         "oxlint": "^1.83.0",
         "oxlint-tsgolint": "^7.0.2001",
         "publint": "^0.3.24",
-        "typescript": "^7.0.2"
+        "typescript": "^7.0.2",
+        "vscode-languageserver-protocol": "^3.18.3"
     },
     "engines": {
         "node": ">=26"