Merge pull request #42 from narumiruna/feat/pi-lsp-extension

feat: add shared pi lsp extension

Author: narumiruna

AGENTS.md

@@ -43,3 +43,10 @@ Run commands from the repository root unless noted otherwise.
 - Recent history uses Conventional Commits such as `feat: ...`, `fix: ...`, and `chore(release): ...`; keep commit messages grounded in the actual diff.
 - Stage only intended paths. Do not use blanket staging for unrelated local changes.
 - For PRs or handoff notes, include the commands run and any publish/visibility checks performed.
+
+## MEMORY.md
+
+- `MEMORY.md` is not auto-loaded. Check it before non-trivial debugging or design work when prior project context may matter.
+- Keep entries short and reusable.
+- `MEMORY.md` must use `## GOTCHA` and `## TASTE` sections.
+- After a non-trivial error or discovery, add one concise entry if it will help future work.

MEMORY.md

@@ -14,6 +14,8 @@
 - Codex usage can be queried without Codex CLI by sending Pi's `openai-codex` bearer token to `https://chatgpt.com/backend-api/wham/usage`; response uses Codex `RateLimitStatusPayload` snake_case fields.
 - `pi-codex-usage` statusline must select a rate-limit bucket by current model id/name; `gpt-5.3-codex-spark` can use its own returned bucket instead of primary `codex`.
 - `node-domexception` deprecation comes via `@google/genai -> google-auth-library -> gaxios -> node-fetch -> fetch-blob`; use the root npm override to `npm:@profoundlogic/node-domexception`.
+- New filesystem-writing Pi tools need a pre-review edge-case pass: workspace containment, absolute/`..` paths, symlink loops/escapes, duplicate paths, cancellation, process errors, protocol errors, and edit ordering.
+- When PR comments expose one class of bug, stop patching comment-by-comment and do a holistic pass over adjacent Modules before pushing again.
 
 ## TASTE
 

README.md

@@ -2,7 +2,7 @@
 
 [![npm scope](https://img.shields.io/badge/npm-@narumitw-blue)](https://www.npmjs.com/org/narumitw) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-Production-ready, independently installable [Pi](https://pi.dev) extension packages for the Pi coding agent. This monorepo provides native Pi tools and commands for Biome LSP diagnostics, Chrome DevTools automation, Codex usage status, Firecrawl web scraping, Python LSP diagnostics with ty and Ruff, goal-driven task completion, retry handling, terminal statuslines, and keep-awake automation.
+Production-ready, independently installable [Pi](https://pi.dev) extension packages for the Pi coding agent. This monorepo provides native Pi tools and commands for shared LSP diagnostics and edits, Biome LSP diagnostics, Chrome DevTools automation, Codex usage status, Firecrawl web scraping, Python LSP diagnostics with ty and Ruff, goal-driven task completion, retry handling, terminal statuslines, and keep-awake automation.
 
 ## 📦 Pi extension packages
 
@@ -17,6 +17,7 @@ Install only the Pi extensions you need. Each package is published under the `@n
 | [`@narumitw/pi-codex-usage`](./extensions/pi-codex-usage) | 📊 `/codex-status` command and automatic statusline item for ChatGPT Codex subscription usage, using Pi auth first and Codex CLI only as fallback. | `pi install npm:@narumitw/pi-codex-usage` |
 | [`@narumitw/pi-firecrawl`](./extensions/pi-firecrawl) | 🔥 Firecrawl-powered web scraping, crawling, URL discovery, and web search tools for research workflows. | `pi install npm:@narumitw/pi-firecrawl` |
 | [`@narumitw/pi-goal`](./extensions/pi-goal) | 🎯 `/goal` mode that keeps the agent working until a verifiable task is complete. | `pi install npm:@narumitw/pi-goal` |
+| [`@narumitw/pi-lsp`](./extensions/pi-lsp) | 🧠 Shared language-server tools for Biome diagnostics/edits, ty diagnostics, and Ruff diagnostics/edits. | `pi install npm:@narumitw/pi-lsp` |
 | [`@narumitw/pi-python-lsp`](./extensions/pi-python-lsp) | 🐍 Python language-server tools for ty type diagnostics and Ruff linting, formatting, and fixes. | `pi install npm:@narumitw/pi-python-lsp` |
 | [`@narumitw/pi-retry`](./extensions/pi-retry) | 🔁 Retry support for provider responses that fail with `Unknown error (no error details in response)`. | `pi install npm:@narumitw/pi-retry` |
 | [`@narumitw/pi-statusline`](./extensions/pi-statusline) | ✨ A rich Pi terminal statusline with model, tools, git branch, context usage, token totals, cost, and time. | `pi install npm:@narumitw/pi-statusline` |
@@ -39,11 +40,15 @@ pi -e npm:@narumitw/pi-statusline
 Use multiple Pi extensions together:
 
 ```bash
-pi -e npm:@narumitw/pi-goal -e npm:@narumitw/pi-statusline -e npm:@narumitw/pi-python-lsp -e npm:@narumitw/pi-biome-lsp
+pi -e npm:@narumitw/pi-goal -e npm:@narumitw/pi-statusline -e npm:@narumitw/pi-lsp
 ```
 
 ## 🛠️ Extension use cases
 
+### 🧠 Shared language-server workflows
+
+Use [`@narumitw/pi-lsp`](./extensions/pi-lsp) to let Pi run Biome, ty, and Ruff language-server tools through one shared LSP runner. It covers Biome diagnostics and edits, ty type diagnostics, and Ruff lint diagnostics, formatting, import organization, and source fixes. The older [`@narumitw/pi-biome-lsp`](./extensions/pi-biome-lsp) and [`@narumitw/pi-python-lsp`](./extensions/pi-python-lsp) packages remain available and are not deprecated yet.
+
 ### 🧬 JavaScript and TypeScript coding with Biome
 
 Use [`@narumitw/pi-biome-lsp`](./extensions/pi-biome-lsp) to let Pi run Biome diagnostics through `biome lsp-proxy`, format supported files, organize imports, and apply safe Biome source fixes.
@@ -100,6 +105,7 @@ pi -e ./extensions/pi-chrome-devtools
 pi -e ./extensions/pi-codex-usage
 pi -e ./extensions/pi-firecrawl
 pi -e ./extensions/pi-goal
+pi -e ./extensions/pi-lsp
 pi -e ./extensions/pi-python-lsp
 pi -e ./extensions/pi-retry
 pi -e ./extensions/pi-statusline
@@ -116,6 +122,7 @@ npm run pack:chrome-devtools
 npm run pack:codex-usage
 npm run pack:firecrawl
 npm run pack:goal
+npm run pack:lsp
 npm run pack:python-lsp
 npm run pack:retry
 npm run pack:statusline
@@ -142,6 +149,7 @@ extensions/
 ├── pi-codex-usage/
 ├── pi-firecrawl/
 ├── pi-goal/
+├── pi-lsp/
 ├── pi-python-lsp/
 ├── pi-retry/
 ├── pi-statusline/

docs/implementation-notes/pi-lsp-parity-checklist.md

@@ -0,0 +1,49 @@
+# pi-lsp parity checklist
+
+`@narumitw/pi-lsp` keeps the existing public tool Interface from `@narumitw/pi-biome-lsp` and `@narumitw/pi-python-lsp` while moving common LSP behavior into a shared runner Module.
+
+## Tool names and parameters
+
+- [x] `biome_lsp_diagnostics`: `paths?`, `root?`, `limit?`.
+- [x] `biome_lsp_format`: `path`, `root?`, `write?`.
+- [x] `biome_lsp_fix`: `path`, `root?`, `kind?`, `write?`; default kind `source.fixAll.biome`.
+- [x] `ty_lsp_diagnostics`: `paths?`, `root?`, `limit?`.
+- [x] `ruff_lsp_diagnostics`: `paths?`, `root?`, `limit?`.
+- [x] `ruff_lsp_format`: `path`, `root?`, `write?`.
+- [x] `ruff_lsp_fix`: `path`, `root?`, `kind?`, `write?`; default kind `source.fixAll.ruff`.
+
+## Server commands and environment variables
+
+- [x] Biome defaults to `biome lsp-proxy`, supports `PI_BIOME_LSP_COMMAND`, and uses `PI_BIOME_LSP_TIMEOUT_MS`.
+- [x] ty defaults to `ty server`, supports `PI_TY_LSP_COMMAND`, and uses `PI_TY_LSP_TIMEOUT_MS`.
+- [x] Ruff defaults to `ruff server`, supports `PI_RUFF_LSP_COMMAND`, and uses `PI_RUFF_LSP_TIMEOUT_MS`.
+- [x] Command splitting preserves the old quoted-command support but intentionally preserves normal backslashes so Windows command paths such as `C:\\Tools\\ruff.exe` remain valid.
+- [x] Command probing validates runnable files, rejects directories/non-executable POSIX files, and resolves relative command paths against the LSP workspace root used as the server `cwd`.
+
+## File discovery
+
+- [x] Biome file extensions match `pi-biome-lsp`: `.astro`, `.css`, `.cts`, `.cjs`, `.graphql`, `.gql`, `.html`, `.js`, `.json`, `.jsonc`, `.jsx`, `.mjs`, `.mts`, `.svelte`, `.ts`, `.tsx`, `.vue`.
+- [x] Biome skips `.git`, `.hg`, `.next`, `.nuxt`, `.output`, `.svelte-kit`, `coverage`, `dist`, `node_modules`, and `out`.
+- [x] Python files match `pi-python-lsp`: `.py` and `.pyi`.
+- [x] Python skips `.git`, `.hg`, `.mypy_cache`, `.ruff_cache`, `.tox`, `.venv`, `__pycache__`, `node_modules`, and `venv`.
+
+## LSP behavior
+
+- [x] Shared runner owns JSON-RPC framing, subprocess lifecycle, initialize/shutdown, file open/close, diagnostics, formatting, code actions, action resolution, and workspace edit application.
+- [x] Biome Adapter keeps dynamic registration capabilities, publish-diagnostics fallback, workspace-folder request handling, tab size 2, and tabs.
+- [x] ty Adapter keeps diagnostic requests without code actions, tab size 4, and spaces.
+- [x] Ruff Adapter keeps diagnostic requests, code actions, tab size 4, and spaces.
+
+## Result shapes and messages
+
+- [x] Tool results still return `{ content: [{ type: "text", text }], details }`.
+- [x] Diagnostics details include `root`, `command`, `files`, and `summary`.
+- [x] Format/fix details include `path`, `uri`, `changed`, `write`, `edits`, and preview `text` when `write` is false.
+- [x] Fix details include `kind` and resolved `actions`.
+- [x] Missing-command errors preserve server-specific install guidance.
+
+## Documentation and compatibility
+
+- [x] `extensions/pi-lsp/README.md` documents tool-name compatibility, environment variables, and no-deprecation status for the old packages.
+- [x] Root `README.md`, `package.json`, and `justfile` include `pi-lsp` integration.
+- [x] `pi-biome-lsp` and `pi-python-lsp` package metadata and READMEs are unchanged in this phase.

docs/plans/archived/2026-05-17_pi-lsp-extension-plan.md

@@ -0,0 +1,65 @@
+## Goal
+
+Create a new `@narumitw/pi-lsp` Pi extension that provides one deep LSP runner Module for diagnostics, formatting, source fixes, and import organization across multiple language-server Adapters. The initial success condition is that the new package covers the current `pi-biome-lsp` and `pi-python-lsp` behavior without deprecating those packages yet.
+
+## Context
+
+`extensions/pi-biome-lsp/src/biome-lsp.ts` and `extensions/pi-python-lsp/src/python-lsp.ts` duplicate most of their LSP JSON-RPC, subprocess lifecycle, file collection, workspace edit, and result formatting Implementation. The intended deepening is to move that behavior behind a smaller `pi-lsp` Interface, while keeping Biome, ty, and Ruff as concrete Adapters.
+
+## Architecture
+
+- The external Pi tool Interface remains familiar to existing users: diagnostics, format, and fix tools for Biome, ty, and Ruff.
+- The new package contains an internal LSP runner Module with one Seam for server-specific Adapters.
+- Each Adapter describes server command resolution, supported file discovery, language id, initialization options/capabilities, formatting options, code-action kind defaults, and missing-command guidance.
+- `pi-biome-lsp` and `pi-python-lsp` remain unchanged until a later deprecation decision.
+
+## Non-Goals
+
+- Do not deprecate or remove `@narumitw/pi-biome-lsp` or `@narumitw/pi-python-lsp` in this phase.
+- Do not publish the new npm package in this phase unless explicitly requested after local verification.
+- Do not add a separate shared workspace package unless the new `pi-lsp` package proves that reuse outside the package is needed.
+
+## Assumptions
+
+- The new package can initially copy behavior from the existing LSP extensions, then consolidate it behind deeper internal Modules.
+- Tool names may stay compatible with the existing names at first, even if users should avoid installing old and new LSP packages together because duplicate tool names can conflict.
+- The package should follow current monorepo conventions: `extensions/pi-lsp`, package-local `README.md`, `LICENSE`, `tsconfig.json`, `src/*.ts`, root scripts, and just recipes.
+
+## Unknowns
+
+- Resolved: duplicate tool names are documented as an installation caveat in `extensions/pi-lsp/README.md`; side-by-side installs are not recommended until a later Pi-version-specific decision.
+- Resolved: generic configurable LSP tools are deferred; this phase ships built-in Biome, ty, and Ruff Adapters only.
+
+## Plan
+
+- [x] Inventory current LSP behavior in `extensions/pi-biome-lsp/src/biome-lsp.ts`, `extensions/pi-python-lsp/src/python-lsp.ts`, and their READMEs to produce a parity checklist of tool names, parameters, environment variables, command defaults, supported file extensions, result details, and error messages; verified by `docs/implementation-notes/pi-lsp-parity-checklist.md`.
+- [x] Create `extensions/pi-lsp/` with `package.json`, `README.md`, `LICENSE`, `tsconfig.json`, and `src/` following existing package conventions; verified with `npm --workspace @narumitw/pi-lsp run typecheck`.
+- [x] Add root workspace integration for the new package in `package.json`, `justfile`, and root `README.md` without changing old LSP packages; verified with `just --list | rg '(^|-)lsp|pack-lsp|try-lsp|install-lsp|publish-lsp'` and `just pack lsp`.
+- [x] Implement an internal LSP runner Module in `extensions/pi-lsp/src/` that owns JSON-RPC framing, process lifecycle, initialize/shutdown, file open/close, diagnostics collection, formatting requests, code-action requests, and workspace edit application; verified with `npm --workspace @narumitw/pi-lsp run typecheck`, `npm run biome:check`, and the parity checklist.
+- [x] Implement Biome, ty, and Ruff Adapters for the runner Module, each with command resolution, file support, language id, capabilities/options, and missing-command guidance matching existing packages; verified by `docs/implementation-notes/pi-lsp-parity-checklist.md`.
+- [x] Register Pi tools in `extensions/pi-lsp/src/pi-lsp.ts` for existing Biome, ty, and Ruff diagnostics/format/fix workflows; verified with `npm --workspace @narumitw/pi-lsp run typecheck` and `npm run biome:check`.
+- [x] Add package documentation that explains what `@narumitw/pi-lsp` replaces, the current no-deprecation status of old packages, tool-name conflict guidance, environment variables, and local try instructions; verified by `extensions/pi-lsp/README.md` and root `README.md`.
+- [x] Run local package verification with `npm run check` and `just pack lsp`; verified both commands passed and the dry-run tarball listed only `LICENSE`, `README.md`, `package.json`, and `src/*.ts`.
+- [x] Try the extension locally with `pi -e ./extensions/pi-lsp` on at least one TypeScript/JSON file and one Python file, using available Biome/Ruff/ty commands when installed; verified by `pi -e ./extensions/pi-lsp --version`, compiled local harness execution of `biome_lsp_diagnostics`, `biome_lsp_format`, `biome_lsp_fix`, `ty_lsp_diagnostics`, `ruff_lsp_diagnostics`, `ruff_lsp_format`, and `ruff_lsp_fix` against `/tmp/pi-lsp-runtime` sample JSON/Python files.
+- [x] Decide whether old packages should enter a later deprecation plan only after `@narumitw/pi-lsp` passes local verification; verified by leaving `pi-biome-lsp` and `pi-python-lsp` package metadata and READMEs unchanged in this phase.
+
+## Risks
+
+- Mitigated: duplicate tool names may confuse users if `pi-lsp` is installed with the old packages; documented in `extensions/pi-lsp/README.md` and old packages were not deprecated.
+- Mitigated: consolidation can accidentally change result shapes or error wording; `docs/implementation-notes/pi-lsp-parity-checklist.md` records parity checks.
+- Mitigated: LSP server behavior differs subtly between Biome, ty, and Ruff; server-specific behavior is kept in `extensions/pi-lsp/src/adapters.ts`.
+
+## Rollback / Recovery
+
+- If the new package fails later verification, remove `extensions/pi-lsp/` and root references in one rollback commit; old LSP packages remain available because this phase does not modify or deprecate them.
+- If a specific Adapter is unstable after wider use, keep the package unpublished and document the failing Adapter while preserving the runner Module work for follow-up.
+
+## Completion Checklist
+
+- [x] `@narumitw/pi-lsp` package exists with package metadata, README, LICENSE, tsconfig, and source files verified by repository paths under `extensions/pi-lsp/`.
+- [x] Biome, ty, and Ruff tool parity is verified by `docs/implementation-notes/pi-lsp-parity-checklist.md` against the old LSP packages.
+- [x] Repository integration is verified by root scripts/just recipes and root README entries for the new package, plus `just --list | rg '(^|-)lsp|pack-lsp|try-lsp|install-lsp|publish-lsp'`.
+- [x] Static verification is complete with passing `npm run check`.
+- [x] Package contents are verified with passing `just pack lsp` dry-run output listing 11 expected files.
+- [x] Runtime behavior is verified with `pi -e ./extensions/pi-lsp --version` and recorded diagnostics/format/fix harness results for Biome JSON and Python ty/Ruff workflows.
+- [x] `pi-biome-lsp` and `pi-python-lsp` are not deprecated, removed, or behavior-changed in this phase, verified by no diffs under `extensions/pi-biome-lsp/` or `extensions/pi-python-lsp/`.

extensions/pi-lsp/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.