From 93cb37441daa810531368afde5627eb99109bb2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Tue, 8 Sep 2026 20:47:40 +0200 Subject: [PATCH] :memo: Document pi-lsp tooling and agent usage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README § Tooling and § Tooling decisions record the extension and the reasoning behind it: read-only by design, auto-detects TypeScript 7, and never a correctness gate — verify is. AGENTS.md § First action tells agents the lsp_* tools exist, to prefer lsp_references over grep -w for colliding identifiers, and to treat empty LSP output as inconclusive. Close the backlog evaluation task with a resolved note, and allowlist the tsgo/tsserver tool names for cspell. --- AGENTS.md | 1 + README.md | 2 ++ backlog.tasks | 6 ++++++ cspell.json | 2 ++ 4 files changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e74557b..341558c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,7 @@ first-action facts. Do not restate evolving prose here — it will drift. - Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim). - **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed. +- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run. - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit. - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch. diff --git a/README.md b/README.md index afea147..361a6f2 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ What each tier runs, when it fires and what it costs: - **publint** — validates `package.json` for ESM publishing correctness. - **@arethetypeswrong/cli** (`attw`) — validates `.d.ts` declarations against multiple module-resolution scenarios. - **lefthook** — git hooks. +- **@spences10/pi-lsp** — read-only LSP code intelligence for AI coding agents (project-local `.pi/settings.json`). Talks to this repo's TypeScript 7 via `tsc --lsp --stdio`. Each tool's configuration trade-off is recorded in [Tooling decisions](#tooling-decisions); when it runs is in [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers). @@ -46,6 +47,7 @@ The choice and configuration of each tool above is the result of deliberate trad - **`check:tsc` runs first** in the `npm run check` chain so a type error short-circuits the rest (faster feedback than letting oxlint/oxfmt run and then failing on tsc at the end). - **The pre-commit hook sets the `LEFTHOOK_FILES` env var** to the staged-files list, and the affected scripts use `${LEFTHOOK_FILES:-}` to default to the whole project when invoked manually. This keeps `package.json#scripts` as the single source of truth for the underlying commands — `lefthook.yml` only describes _what to run on which files_. - **`tslib` and `type-fest` are deliberately not used.** `tslib` is a runtime helper for old ES3/ES5 targets (the project targets ES2024); `type-fest` was never imported. knip caught both. +- **`@spences10/pi-lsp` is pinned to `0.0.46` and is read-only by design.** The package inspects `node_modules/typescript`, sees major ≥ 7 with no `lib/tsserver.js` (true of the `typescript-go` / `tsgo` port), and spawns the repo's own `tsc --lsp --stdio` binary — no `typescript-language-server` dependency is required. Earlier releases (`≤ 0.0.10`) hard-wire to `typescript-language-server --stdio` and are TS6-only. The tool is _intermediate_ agent feedback (hover, references, definition, symbols, diagnostics); it has no rename / code-action / apply-edit surface, and never a correctness gate — `npm run check` / `verify` remain that. ### Requirements diff --git a/backlog.tasks b/backlog.tasks index 108d5a7..3f241b3 100644 --- a/backlog.tasks +++ b/backlog.tasks @@ -11,6 +11,12 @@ Setup: ✔ Document branching model @done ✔ Describe branching model: when to branch, base branch, naming @done ✔ Clarify release workflow: who pushes `main`, CI as post-merge gate, drop PR usage @done (9/8/2026, 2:54:32 PM) +✔ Evaluate connecting the agent to lsp typescript server @done + - might be more difficult with TS7, since LSP Server has changed from 6 + - but since vscode is running TS7, maybe it is possible to connect to the TS7 LSP server of vscode + - LSP servers in general? + - maybe skills? + → resolved: adopted @spences10/pi-lsp@0.0.46 as a project-local pi extension (`.pi/settings.json`). It auto-detects the repo's TypeScript 7 (no `lib/tsserver.js`) and spawns `tsc --lsp --stdio` — the same tsgo binary VS Code's native-preview uses. Read-only: hover / definition / references / symbols / diagnostics. No skill; skills don't own persistent processes. v1.0: ☐ API surface is stable and fully typed diff --git a/cspell.json b/cspell.json index 076b536..bdee250 100644 --- a/cspell.json +++ b/cspell.json @@ -19,6 +19,8 @@ "arethetypeswrong", "knip", "tsgolint", + "tsgo", + "tsserver", "gitea", "pubv", "knope",