@saifymatteo/pi-x-ide 0.0.0-stage → 1.20.2

package/CHANGELOG.md

@@ -0,0 +1,328 @@
+# Changelog
+
+## [1.20.1](https://github.com/balaenis/pi-x-ide/compare/v1.20.0...v1.20.1) (2026-09-21)
+
+
+### Bug Fixes
+
+* **jetbrains:** run pi through cmd.exe in native Windows projects ([a3c4581](https://github.com/balaenis/pi-x-ide/commit/a3c45816ad03beda2937a4ed5825e838e8447b87))
+* **jetbrains:** run pi through cmd.exe in native Windows projects ([f7ba6a2](https://github.com/balaenis/pi-x-ide/commit/f7ba6a211032a201ce49f0ca7df41f76795998df))
+
+## [1.20.0](https://github.com/balaenis/pi-x-ide/compare/v1.19.5...v1.20.0) (2026-09-08)
+
+
+### Features
+
+* add contextPlacement option to control editor context reminder placement ([34f20ab](https://github.com/balaenis/pi-x-ide/commit/34f20ab6add40c05e22d830409b9aa0aa44ec5cf))
+* add contextPlacement option to control editor context reminder placement ([7aadd0f](https://github.com/balaenis/pi-x-ide/commit/7aadd0f0b7d1bc9d477cfff90f653173f5352f60))
+
+## [1.19.5](https://github.com/balaenis/pi-x-ide/compare/v1.19.4...v1.19.5) (2026-08-20)
+
+
+### Bug Fixes
+
+* **discovery:** keep live IDE locks and refresh owned locks via heartbeat ([bd5e98a](https://github.com/balaenis/pi-x-ide/commit/bd5e98a704fb7eb33fcae37d45c40d87a337e465)), closes [#50](https://github.com/balaenis/pi-x-ide/issues/50)
+* preserve live IDE locks across long sessions ([8ffa912](https://github.com/balaenis/pi-x-ide/commit/8ffa9120bd447cc2caecbc995695819b7b638d3b))
+
+## [1.19.4](https://github.com/balaenis/pi-x-ide/compare/v1.19.3...v1.19.4) (2026-07-30)
+
+
+### Bug Fixes
+
+* **pi:** add trailing newline when pasting selection mention ([a09b159](https://github.com/balaenis/pi-x-ide/commit/a09b159ce42b7191f92e04fde93d153b4ccee193))
+
+## [1.19.3](https://github.com/balaenis/pi-x-ide/compare/v1.19.2...v1.19.3) (2026-07-23)
+
+
+### Bug Fixes
+
+* **pi-error-routing:** replace console.error with pi ui.notify for extension errors ([dda5c09](https://github.com/balaenis/pi-x-ide/commit/dda5c099de8c9d2321b24e28c1dac64ba516e9c0))
+
+## [1.19.2](https://github.com/balaenis/pi-x-ide/compare/v1.19.1...v1.19.2) (2026-07-22)
+
+
+### Bug Fixes
+
+* **pi:** stop stale extension ctx from spamming the console ([a2b557e](https://github.com/balaenis/pi-x-ide/commit/a2b557ef90fadf9ebaa80de98cdbfc5f9a90ccdb))
+* **pi:** stop stale extension ctx from spamming the console ([#43](https://github.com/balaenis/pi-x-ide/issues/43)) ([a2b557e](https://github.com/balaenis/pi-x-ide/commit/a2b557ef90fadf9ebaa80de98cdbfc5f9a90ccdb))
+
+## [1.19.1](https://github.com/balaenis/pi-x-ide/compare/v1.19.0...v1.19.1) (2026-07-22)
+
+
+### Bug Fixes
+
+* **pi:** eliminate host-package runtime imports from compiled output ([bde0c10](https://github.com/balaenis/pi-x-ide/commit/bde0c102917b3dc7da7825c14f2d3f585fd443d1))
+
+## [1.19.0](https://github.com/balaenis/pi-x-ide/compare/v1.18.0...v1.19.0) (2026-07-22)
+
+
+### Features
+
+* **pi:** split extension into lightweight shell and heavy runtime via code splitting ([4c25cdc](https://github.com/balaenis/pi-x-ide/commit/4c25cdcddc16a4b39c1fddf83a0d052d5a8432ee))
+
+## [1.18.0](https://github.com/balaenis/pi-x-ide/compare/v1.17.0...v1.18.0) (2026-07-21)
+
+
+### Features
+
+* add status_display option, rename fix_prompt to fixPrompt ([d9b37d5](https://github.com/balaenis/pi-x-ide/commit/d9b37d515ddfe27125bc4ef21146101333bee136))
+* **pi:** add /ide settings dialog with global and project scope config ([1095a89](https://github.com/balaenis/pi-x-ide/commit/1095a89dbbde34c6bafd8d15547a913f92b8efae))
+
+## [1.17.0](https://github.com/balaenis/pi-x-ide/compare/v1.16.3...v1.17.0) (2026-07-21)
+
+
+### Features
+
+* adopt Effect for Pi-side errors, schema, IO, and fibers ([0c3c622](https://github.com/balaenis/pi-x-ide/commit/0c3c6220e29aca86363e1e594f3068cb51d63288))
+* **shared:** add Effect tagged errors and boundary runners ([4ac61c2](https://github.com/balaenis/pi-x-ide/commit/4ac61c293b522251cac2abf778177fcd3ac32b8f))
+* **shared:** validate protocol payloads with Effect Schema ([c37f3d4](https://github.com/balaenis/pi-x-ide/commit/c37f3d47e9e4b7830e779ab087ef91caef2c94b8))
+
+
+### Bug Fixes
+
+* **pi:** harden reconnect fiber fire-clear and lifecycle tests ([aedbbb6](https://github.com/balaenis/pi-x-ide/commit/aedbbb6fb8987b83b1bf29bedf485fc5481e7c5e))
+* **pi:** restore connect timeout cleanup order before terminate ([21dd4a7](https://github.com/balaenis/pi-x-ide/commit/21dd4a76f12722a9bc3a9c07f5ae2e63ba6d035a))
+
+## [1.16.3](https://github.com/balaenis/pi-x-ide/compare/v1.16.2...v1.16.3) (2026-07-06)
+
+### Bug Fixes
+
+- **jetbrains:** avoid internal API for plugin version ([d7d1be7](https://github.com/balaenis/pi-x-ide/commit/d7d1be7fa8ccda4e0bbb105cd8552dc8858453ce))
+
+## [1.16.2](https://github.com/balaenis/pi-x-ide/compare/v1.16.1...v1.16.2) (2026-07-04)
+
+### Bug Fixes
+
+- **jetbrains:** avoid internal plugin manager API ([efc694d](https://github.com/balaenis/pi-x-ide/commit/efc694d4885294cd01fbe039ef142dd62631eabf))
+
+## [1.16.1](https://github.com/balaenis/pi-x-ide/compare/v1.16.0...v1.16.1) (2026-06-30)
+
+### Bug Fixes
+
+- **release:** update version marker for release-please ([351f71a](https://github.com/balaenis/pi-x-ide/commit/351f71adbf0e721d5d22ef57d30ad55270ff453b))
+
+## [1.16.0](https://github.com/balaenis/pi-x-ide/compare/v1.15.2...v1.16.0) (2026-06-30)
+
+### Features
+
+- **pi:** render diagnostic-fix requests as custom TUI messages ([82d1821](https://github.com/balaenis/pi-x-ide/commit/82d18219cdfdfbb48689d6812db093396f229f4d))
+
+## [1.15.2](https://github.com/balaenis/pi-x-ide/compare/v1.15.1...v1.15.2) (2026-06-29)
+
+### Bug Fixes
+
+- **pi:** resolve package version from package root ([9a5db66](https://github.com/balaenis/pi-x-ide/commit/9a5db66780b85203730825abfd5f95d24b2c3a87))
+
+## [1.15.1](https://github.com/balaenis/pi-x-ide/compare/v1.15.0...v1.15.1) (2026-06-29)
+
+### Bug Fixes
+
+- **ui:** use grapheme-aware width for CJK-safe IDE status bar truncation ([9513960](https://github.com/balaenis/pi-x-ide/commit/95139605c36926be7e0ecb1553f823d3639a2b65))
+
+## [1.15.0](https://github.com/balaenis/pi-x-ide/compare/v1.14.0...v1.15.0) (2026-06-23)
+
+### Features
+
+- **context:** wrap editor context in SELECTED_CONTEXT_MARKER for precise detection ([341e957](https://github.com/balaenis/pi-x-ide/commit/341e957e6f9ea32f60a90645f8fafa2e814bf267))
+
+## [1.14.0](https://github.com/balaenis/pi-x-ide/compare/v1.13.1...v1.14.0) (2026-06-22)
+
+### Features
+
+- **jetbrains:** add JetBrains IDE plugin with lock-file, selection-tracking, and WebSocket server ([401e65d](https://github.com/balaenis/pi-x-ide/commit/401e65d50ed00f2803324c954560551f9ebe5c70)), closes [#47](https://github.com/balaenis/pi-x-ide/issues/47)
+- **jetbrains:** add plugin icons, toolbar group, and icon references to actions ([ab5b0c4](https://github.com/balaenis/pi-x-ide/commit/ab5b0c483d004b2cc1d5950acbbdab9af8b9d9b6))
+- **jetbrains:** add signing and publishPlugin support for JetBrains Marketplace ([d86f5e0](https://github.com/balaenis/pi-x-ide/commit/d86f5e0ec2769eeaec5a90b4c117c40d08e4df4e))
+- **jetbrains:** run pi through login shell for proper PATH setup on native Unix and WSL ([7bf2924](https://github.com/balaenis/pi-x-ide/commit/7bf2924918692481c80a78fffd3ccffa67b166d3))
+- **wsl:** add WSL-aware IDE discovery and cross-platform host resolution ([d8bd2e4](https://github.com/balaenis/pi-x-ide/commit/d8bd2e42687a79022a47337149169f03f1034b21))
+
+## [1.13.1](https://github.com/balaenis/pi-x-ide/compare/v1.13.0...v1.13.1) (2026-06-20)
+
+### Bug Fixes
+
+- **vscode:** run pi through login shell in tmux terminal ([bee8563](https://github.com/balaenis/pi-x-ide/commit/bee8563bfde5623eb08d1db40260e50ea6ff2d94))
+
+## [1.13.0](https://github.com/balaenis/pi-x-ide/compare/v1.12.0...v1.13.0) (2026-06-19)
+
+### Features
+
+- add error containment boundaries across all extension entry points ([064e725](https://github.com/balaenis/pi-x-ide/commit/064e72589f18979e57024166692627de7464edf0))
+
+### Bug Fixes
+
+- guard stale extension context callbacks ([316b1c1](https://github.com/balaenis/pi-x-ide/commit/316b1c1cea974229c8bef94a94d105b31cc76796))
+- **pi:** guard stale connection callbacks and extension ctx errors ([094975c](https://github.com/balaenis/pi-x-ide/commit/094975c0081a48fb08ae226f4d8f64b5b38b5084))
+
+## [1.12.0](https://github.com/balaenis/pi-x-ide/compare/v1.11.1...v1.12.0) (2026-06-16)
+
+### Features
+
+- **ui:** add animated spinner for connecting state ([ae82969](https://github.com/balaenis/pi-x-ide/commit/ae82969223f79c6ce28315337e846888738649aa))
+
+## [1.11.1](https://github.com/balaenis/pi-x-ide/compare/v1.11.0...v1.11.1) (2026-06-15)
+
+### Bug Fixes
+
+- **ci:** Modify the rules guide and trigger once release pr ([f468f5a](https://github.com/balaenis/pi-x-ide/commit/f468f5ab8d61227b1d16faf2719f218a17829ecc))
+
+## [1.11.0](https://github.com/balaenis/pi-x-ide/compare/v1.10.0...v1.11.0) (2026-06-14)
+
+### Features
+
+- **diagnostics:** send diagnostic context to one connected Pi client instead of broadcasting ([9681fd4](https://github.com/balaenis/pi-x-ide/commit/9681fd4dcf88aad1a43a5c1d002219a2477c5279))
+
+### Bug Fixes
+
+- **diagnostics:** escape primary context line marker to avoid markdown blockquote interpretation ([c2f005e](https://github.com/balaenis/pi-x-ide/commit/c2f005e8cd16c2743838d2e79d0ca0987a2e0a8d))
+
+## [1.10.0](https://github.com/balaenis/pi-x-ide/compare/v1.9.0...v1.10.0) (2026-06-14)
+
+### Features
+
+- **diagnostics:** add configurable fix prompt for IDE diagnostics ([ca8621c](https://github.com/balaenis/pi-x-ide/commit/ca8621c6050c37ed921e20efcb4dd38907b1cbb9))
+- **nvim:** verify sidecar binary against GitHub Release SHA-256 digest ([0cc1d9b](https://github.com/balaenis/pi-x-ide/commit/0cc1d9bf1ee5ef8f30d50374ffe68953c242d4ce))
+- **vscode:** add Fix with Pi suggest quick action for diagnostics ([e8dc6d5](https://github.com/balaenis/pi-x-ide/commit/e8dc6d56543afb1d8019bcede0a540cacd440c6d))
+- **vscode:** add Pi: Send diagnostic quick fix action ([d53d72b](https://github.com/balaenis/pi-x-ide/commit/d53d72bb1030f58da7f82136a75b95da2568f28a))
+- **vscode:** hide pi terminal from user initially and show without stealing focus ([15ca612](https://github.com/balaenis/pi-x-ide/commit/15ca6121a4c25a1ed68cb6631372b5a100c77a7b))
+
+### Bug Fixes
+
+- **pi:** wrap diagnostic context message with marker on both sides ([592da42](https://github.com/balaenis/pi-x-ide/commit/592da424d16a190c958eac86a70045405e91e936))
+
+## [1.9.0](https://github.com/balaenis/pi-x-ide/compare/v1.8.0...v1.9.0) (2026-06-13)
+
+### Features
+
+- **vscode:** add useTmux setting to open Pi through tmux ([93cec4d](https://github.com/balaenis/pi-x-ide/commit/93cec4de9f2f51312db4c3a4672b2f2ffe2ddc61))
+
+### Bug Fixes
+
+- **pi/install:** filter out unknown-reason candidates from auto-install ([375449b](https://github.com/balaenis/pi-x-ide/commit/375449b2306d8fa1098a30a0176eff9dc5f602e2))
+
+## [1.8.0](https://github.com/balaenis/pi-x-ide/compare/v1.7.0...v1.8.0) (2026-06-12)
+
+### Features
+
+- **attach:** make TUI attach shortcut configurable via PI_X_IDE_ATTACH_SHORTCUT ([20a7e9c](https://github.com/balaenis/pi-x-ide/commit/20a7e9c80644d4a46cdc4459c7394faa7f3e21e5))
+- **ide:** register Ctrl+Alt+K shortcut in Pi TUI for /ide attach ([9803840](https://github.com/balaenis/pi-x-ide/commit/9803840f73bc965dae3e0e0a53f7fccae173e2d7))
+
+## [1.7.0](https://github.com/balaenis/pi-x-ide/compare/v1.6.0...v1.7.0) (2026-06-12)
+
+### Features
+
+- **zed:** add configurable poll interval env var and clean up env schema ([04d870e](https://github.com/balaenis/pi-x-ide/commit/04d870e88d756a2faea998e741f8893bc95c3a31))
+
+## [1.6.0](https://github.com/balaenis/pi-x-ide/compare/v1.5.1...v1.6.0) (2026-06-12)
+
+### Features
+
+- **mise:** add compile and compile:all tasks ([517e9cd](https://github.com/balaenis/pi-x-ide/commit/517e9cdfe533294f69d71021680b471662104a32))
+- **pi:** limit reconnect attempts and add handshake timeout ([4dc855e](https://github.com/balaenis/pi-x-ide/commit/4dc855e715f1b8bf141a0f055962af53ac581696))
+
+## [1.5.1](https://github.com/balaenis/pi-x-ide/compare/v1.5.0...v1.5.1) (2026-06-11)
+
+### Bug Fixes
+
+- **nvim:** capture sidecar download stderr and handle job start failure ([eae98bf](https://github.com/balaenis/pi-x-ide/commit/eae98bfd7cd313f2e57b4c5665255df6ef30d25f))
+
+## [1.5.0](https://github.com/balaenis/pi-x-ide/compare/v1.4.3...v1.5.0) (2026-06-11)
+
+### Features
+
+- **nvim:** auto-download sidecar binary from GitHub Releases ([85f8e0a](https://github.com/balaenis/pi-x-ide/commit/85f8e0a395cb12f436bf972628d0306e78ee0bf5))
+- **nvim:** compile sidecar to standalone binary via bun ([c7b0763](https://github.com/balaenis/pi-x-ide/commit/c7b07632a5d5a683c48f7517334bc4033cb8d556))
+
+## [1.4.3](https://github.com/balaenis/pi-x-ide/compare/v1.4.2...v1.4.3) (2026-06-11)
+
+### Bug Fixes
+
+- always create a fresh Pi terminal instead of reusing existing ([6ad4438](https://github.com/balaenis/pi-x-ide/commit/6ad4438acdd41ea6464c62a0f0ac2858b0c2f2d7))
+
+## [1.4.2](https://github.com/balaenis/pi-x-ide/compare/v1.4.1...v1.4.2) (2026-06-11)
+
+### Bug Fixes
+
+- **pi:** normalize Windows drive letter to uppercase for path matching ([cb4e8ad](https://github.com/balaenis/pi-x-ide/commit/cb4e8adef41d2d80cf2577c3e33879c5aaceb52b))
+- **pi:** skip extensionless search on Windows to avoid matching shell scripts ([bb47f76](https://github.com/balaenis/pi-x-ide/commit/bb47f761c7388f316c10d2a6eae53b839e486322))
+- **pi:** update install notification on connection success or failure ([46a8901](https://github.com/balaenis/pi-x-ide/commit/46a8901fb271c4c4c6931c02f4da33794224f638))
+- update notification messages to reference `/ide` instead of `/ide auto` ([cc27727](https://github.com/balaenis/pi-x-ide/commit/cc277274d1e0fda23e8fbf3e597de9924d2863f5))
+
+## [1.4.1](https://github.com/balaenis/pi-x-ide/compare/v1.4.0...v1.4.1) (2026-06-11)
+
+### Bug Fixes
+
+- **docs:** replace lazy.nvim `rtp` with `init` block in install instructions ([1f186ff](https://github.com/balaenis/pi-x-ide/commit/1f186fffa6e050e495fcece71a8ddc185a4f217d))
+- **nvim:** safely stop timer with pcall to prevent errors ([22c422e](https://github.com/balaenis/pi-x-ide/commit/22c422e53057eb2ed7c1b2b343851d751a936632))
+
+## [1.4.0](https://github.com/balaenis/pi-x-ide/compare/v1.3.0...v1.4.0) (2026-06-11)
+
+### Features
+
+- **config:** support pi config env overrides ([1aa20c1](https://github.com/balaenis/pi-x-ide/commit/1aa20c1027ec2172c5ca86cdfb4c1fb362d616b1))
+
+## [1.3.0](https://github.com/balaenis/pi-x-ide/compare/v1.2.0...v1.3.0) (2026-06-10)
+
+### Features
+
+- **vscode:** cache selection snapshot when terminal tab is active ([785f834](https://github.com/balaenis/pi-x-ide/commit/785f834a5092ec77944e7659ca0efa2c6a94f74b))
+- **zed:** add Zed editor integration with SQLite polling ([90da726](https://github.com/balaenis/pi-x-ide/commit/90da726a4d997446f3d05d0b3fb9a439572bec9f))
+- **zed:** support WSL+Windows path normalization for cross-OS Zed DB access ([963e975](https://github.com/balaenis/pi-x-ide/commit/963e975eb3e4824b8e46015ae324bfcc8c33f6c0))
+
+### Performance Improvements
+
+- **zed:** skip DB snapshot when WAL unchanged, checkpoint into snapshot ([76a6dab](https://github.com/balaenis/pi-x-ide/commit/76a6dab7e6af78a534d9f7401901b1df813dd039))
+
+## [1.2.0](https://github.com/balaenis/pi-x-ide/compare/v1.1.0...v1.2.0) (2026-06-10)
+
+### Features
+
+- **vscode:** add editor toolbar button to open Pi terminal ([6289dbd](https://github.com/balaenis/pi-x-ide/commit/6289dbdab4ba8414231cc38c883724f7a56efcb5))
+
+### Bug Fixes
+
+- **pi:** restrict auto-connect to direct workspace matches ([6899dda](https://github.com/balaenis/pi-x-ide/commit/6899dda792571e2a51402f235d45c7ff3667eeb2))
+
+## [1.1.0](https://github.com/balaenis/pi-x-ide/compare/v1.0.5...v1.1.0) (2026-06-10)
+
+### Features
+
+- **pi:** auto-install IDE extension and add /ide install command ([cbaeb11](https://github.com/balaenis/pi-x-ide/commit/cbaeb11dcd897790f68941b84b297505b370dac6)), closes [#6](https://github.com/balaenis/pi-x-ide/issues/6)
+
+## [1.0.5](https://github.com/balaenis/pi-x-ide/compare/v1.0.4...v1.0.5) (2026-06-10)
+
+### Bug Fixes
+
+- build vsix error display name is taken ([477a044](https://github.com/balaenis/pi-x-ide/commit/477a0447b7c4fbfa0f582c47c649ea0e5c5983bd))
+
+## [1.0.4](https://github.com/balaenis/pi-x-ide/compare/v1.0.3...v1.0.4) (2026-06-10)
+
+### Bug Fixes
+
+- build vsix error ([fab6668](https://github.com/balaenis/pi-x-ide/commit/fab66685ce416fa170a939d74564ca75d480ae50))
+
+## [1.0.3](https://github.com/balaenis/pi-x-ide/compare/v1.0.2...v1.0.3) (2026-06-10)
+
+### Bug Fixes
+
+- force release ([6525d08](https://github.com/balaenis/pi-x-ide/commit/6525d083f661d40a7a9506e8cc93db3fd34a6893))
+
+## [1.0.2](https://github.com/balaenis/pi-x-ide/compare/v1.0.1...v1.0.2) (2026-06-10)
+
+### Bug Fixes
+
+- release workflows ([30f6b70](https://github.com/balaenis/pi-x-ide/commit/30f6b70492746f376b5b0520aefc44be687603d1))
+
+## [1.0.1](https://github.com/balaenis/pi-x-ide/compare/v1.0.0...v1.0.1) (2026-06-10)
+
+### Bug Fixes
+
+- test release pipeline ([2d887b8](https://github.com/balaenis/pi-x-ide/commit/2d887b8a27da44c116e4e6a42c69727c469c873d))
+
+## 1.0.0 (2026-06-09)
+
+### Features
+
+- **ci:** add CI/CD workflows and release automation ([a989bfc](https://github.com/balaenis/pi-x-ide/commit/a989bfc2ed39644d9543e4f8a28ece48a0596612))
+- **pi:** add argument completions for ide command ([bc95e88](https://github.com/balaenis/pi-x-ide/commit/bc95e887172ebea5b86263d330c16bad00de3047))
+- **protocol:** broadcast selection_cleared when no active editor ([3fd4c32](https://github.com/balaenis/pi-x-ide/commit/3fd4c328e906b29c83fb61d8dfe6d84ba753b180))
+- **vscode:** add extension icon and branding assets ([efb71b5](https://github.com/balaenis/pi-x-ide/commit/efb71b5852f6ea81097079c8b42f052a2bd67053))
+- **vscode:** send editor selection snapshot on client init ([a268483](https://github.com/balaenis/pi-x-ide/commit/a2684832ba1f3f36ad73cf45a70ae8b76cc61270))

package/CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to Pi × IDE
+
+This guide covers building the project, testing each IDE integration locally, and
+cutting a release. For user-facing setup and usage, see the
+[documentation](README.md#documentation).
+
+## Prerequisites
+
+- Node.js ≥ 26
+- bun ≥ 1.3 (`packageManager` declared as `bun@1.3.14`)
+- VS Code ≥ 1.120.0 (VS Code extension only)
+- Neovim ≥ 0.9 (Neovim plugin only)
+- JDK 21 (JetBrains plugin only; Gradle can download the toolchain automatically)
+
+[mise](https://mise.jdx.dev/) manages the toolchain. Run `mise install` in the
+repo root to install the declared versions.
+
+## Install & build
+
+```bash
+git clone https://github.com/saifymatteo/pi-x-ide.git
+cd pi-x-ide
+mise run setup
+mise run build
+```
+
+To load the local build without installing globally:
+
+```bash
+pi -e ./src/pi/index.ts
+```
+
+## Tasks
+
+All build and check commands are defined as `mise run` tasks (see `.mise/tasks/`):
+
+| Command                        | Description                                                                                                                   |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `mise run build`               | Build Pi-side TypeScript -> `dist/` + Neovim sidecar -> `ide-plugins/nvim/bin/` + VS Code bundle -> `ide-plugins/vscode/out/` |
+| `mise run typecheck`           | Type-check only (no output files)                                                                                             |
+| `mise run test`                | Build + run unit tests                                                                                                        |
+| `mise run package:vsix`        | Package the VS Code extension as a VSIX                                                                                       |
+| `mise run compile:jetbrains`   | Compile and test the JetBrains plugin with Gradle                                                                             |
+| `mise run package:jetbrains`   | Package the JetBrains plugin ZIP under `ide-plugins/jetbrains/build/distributions/`                                           |
+| `mise run verify:jetbrains`    | Run the IntelliJ Plugin Verifier for the configured target IDE                                                                |
+| `mise run check:config-schema` | Verify `schemas/config.json` is in sync with the config registry                                                              |
+
+## Test the VS Code extension locally
+
+### Option 1: F5 Extension Development Host (recommended)
+
+1. Open the **project root** in VS Code.
+2. Go to the **Run and Debug** panel (`Ctrl+Shift+D`).
+3. Select **Run Pi x IDE VS Code Extension**.
+4. Press **F5**:
+   - The `preLaunchTask` automatically runs `mise run build`.
+   - A new VS Code window titled `[Extension Development Host]` opens.
+
+### Option 2: Package a VSIX and install
+
+```bash
+mise run package:vsix
+cd ide-plugins/vscode && code --install-extension dist/pi-x-ide-$(node -p "require('./package.json').version").vsix
+```
+
+The extension installed this way runs in all VS Code windows, independent of the
+F5 Extension Development Host.
+
+### Verify the extension is running
+
+```bash
+ls -l ~/.pi/pi-x-ide/lock
+```
+
+You should see a file like `vscode-12345-48123.lock`. If not, run
+**Developer: Reload Window** in VS Code.
+
+## Test the JetBrains plugin locally
+
+Run a sandbox IDE:
+
+```bash
+cd ide-plugins/jetbrains
+./gradlew runIde
+```
+
+Build the installable plugin ZIP:
+
+```bash
+mise run package:jetbrains
+```
+
+The ZIP is written under `ide-plugins/jetbrains/build/distributions/`. For a smoke
+test, open this repository in the sandbox IDE, start `pi` from the same directory,
+open and select text in a local file, then press `Ctrl+Alt+K` or run
+**Pi x IDE: Attach Selection**. Pi should receive an `@relative/path#Lx-Ly`
+mention.
+
+## Configuration schema
+
+When you add or change a Pi-side configuration option or environment variable that
+should be configurable through `~/.pi/config.json`, update the registry in
+`src/shared/config-options.ts` and regenerate the schema:
+
+```bash
+mise run generate:config-schema
+```
+
+Then verify it is in sync:
+
+```bash
+mise run check:config-schema
+```
+
+## Release
+
+This project uses [Release Please](https://github.com/googleapis/release-please)
+with [Conventional Commits](https://www.conventionalcommits.org/) to automate
+versioning and publishing. See [RELEASE.md](RELEASE.md) for the full release guide.

package/CONTRIBUTING.zh-CN.md

@@ -0,0 +1,106 @@
+# 贡献 Pi × IDE
+
+本指南介绍如何构建项目、本地测试各 IDE 集成以及发布流程。面向用户的使用说明见 [文档](README.zh-CN.md#文档)。
+
+## 环境依赖
+
+- Node.js ≥ 26
+- bun ≥ 1.3（`packageManager` 声明为 `bun@1.3.14`）
+- VS Code ≥ 1.120.0（仅 VS Code 扩展需要）
+- Neovim ≥ 0.9（仅 Neovim 插件需要）
+- JDK 21（仅 JetBrains 插件需要；Gradle 可自动下载 toolchain）
+
+[mise](https://mise.jdx.dev/) 管理工具链。在仓库根目录运行 `mise install` 即可安装声明的版本。
+
+## 安装与构建
+
+```bash
+git clone https://github.com/saifymatteo/pi-x-ide.git
+cd pi-x-ide
+mise run setup
+mise run build
+```
+
+加载本地构建（无需全局安装）：
+
+```bash
+pi -e ./src/pi/index.ts
+```
+
+## 任务
+
+所有构建与检查命令都定义为 `mise run` 任务（见 `.mise/tasks/`）：
+
+| 命令                           | 说明                                                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `mise run build`               | 编译 Pi 侧 TypeScript -> `dist/` + Neovim sidecar -> `ide-plugins/nvim/bin/` + VS Code bundle -> `ide-plugins/vscode/out/` |
+| `mise run typecheck`           | 类型检查（不产出文件）                                                                                                     |
+| `mise run test`                | 编译 + 运行单元测试                                                                                                        |
+| `mise run package:vsix`        | 打包 VS Code 扩展为 VSIX                                                                                                   |
+| `mise run compile:jetbrains`   | 用 Gradle 编译并测试 JetBrains 插件                                                                                        |
+| `mise run package:jetbrains`   | 将 JetBrains 插件打包为 `ide-plugins/jetbrains/build/distributions/` 下的 ZIP                                              |
+| `mise run verify:jetbrains`    | 对配置的目标 IDE 运行 IntelliJ Plugin Verifier                                                                             |
+| `mise run check:config-schema` | 验证 `schemas/config.json` 与配置注册表是否同步                                                                            |
+
+## 本地测试 VS Code 扩展
+
+### 方式一：F5 启动 Extension Development Host（推荐）
+
+1. 用 VS Code 打开 **项目根目录**。
+2. 进入 **Run and Debug** 面板（`Ctrl+Shift+D`）。
+3. 选择 **Run Pi x IDE VS Code Extension**。
+4. 按 **F5**：
+   - preLaunchTask 会自动执行 `mise run build`。
+   - 打开一个标题包含 `[Extension Development Host]` 的新 VS Code 窗口。
+
+### 方式二：打包 VSIX 后安装
+
+```bash
+mise run package:vsix
+cd ide-plugins/vscode && code --install-extension dist/pi-x-ide-$(node -p "require('./package.json').version").vsix
+```
+
+这样安装的扩展在所有 VS Code 窗口中运行，不依赖 F5 Extension Host。
+
+### 验证扩展是否运行
+
+```bash
+ls -l ~/.pi/pi-x-ide/lock
+```
+
+应看到类似 `vscode-12345-48123.lock` 的文件。如果没有，在 VS Code 中执行 **Developer: Reload Window**。
+
+## 本地测试 JetBrains 插件
+
+运行 sandbox IDE：
+
+```bash
+cd ide-plugins/jetbrains
+./gradlew runIde
+```
+
+构建可安装的插件 ZIP：
+
+```bash
+mise run package:jetbrains
+```
+
+ZIP 会输出到 `ide-plugins/jetbrains/build/distributions/`。Smoke test：在 sandbox IDE 中打开本仓库，从同一目录启动 `pi`，打开并选择一个本地文件中的文本，然后按 `Ctrl+Alt+K` 或运行 **Pi x IDE: Attach Selection**。Pi 应收到 `@relative/path#Lx-Ly` mention。
+
+## 配置 schema
+
+当你新增或修改需要通过 `~/.pi/config.json` 配置的 Pi 侧配置项或环境变量时，更新 `src/shared/config-options.ts` 中的注册表并重新生成 schema：
+
+```bash
+mise run generate:config-schema
+```
+
+然后验证是否同步：
+
+```bash
+mise run check:config-schema
+```
+
+## 发布
+
+本项目使用 [Release Please](https://github.com/googleapis/release-please) 和 [Conventional Commits](https://www.conventionalcommits.org/) 来自动化版本管理和发布流程。详见 [RELEASE.md](RELEASE.md)。