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

package/dist/src/shared/lock-file.js

@@ -0,0 +1,50 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { LOCK_FILE_EXTENSION } from "./protocol.js";
+import { resolveLockDir } from "./paths.js";
+export function createAuthToken() {
+    return randomBytes(32).toString("hex");
+}
+export function createIdeLockFilePath(source, port, pid = process.pid, lockDir) {
+    return join(lockDir ?? resolveLockDir(), `${source}-${pid}-${port}${LOCK_FILE_EXTENSION}`);
+}
+export function createIdeLockFile(options) {
+    const now = (options.now ?? new Date()).toISOString();
+    return {
+        version: 1,
+        ide: options.ide,
+        name: options.name,
+        transport: "ws",
+        host: "127.0.0.1",
+        port: options.port,
+        authToken: options.authToken,
+        workspaceFolders: options.workspaceFolders,
+        pid: options.pid ?? process.pid,
+        runningInWindows: options.runningInWindows ?? process.platform === "win32",
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+export async function writeIdeLockFile(path, lock, lockDir) {
+    const dir = lockDir ?? resolveLockDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700).catch(() => undefined);
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(lock, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await chmod(tmp, 0o600).catch(() => undefined);
+    await rename(tmp, path);
+    await chmod(path, 0o600).catch(() => undefined);
+}
+export async function removeIdeLockFile(path) {
+    if (!path)
+        return;
+    await rm(path, { force: true }).catch(() => undefined);
+}
+export function refreshIdeLockFile(lock, workspaceFolders, now = new Date()) {
+    return {
+        ...lock,
+        workspaceFolders,
+        updatedAt: now.toISOString(),
+    };
+}

package/dist/src/shared/paths.js

@@ -0,0 +1,79 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { CONFIG_DIR_NAME, EXT_CONFIG_NAME } from "./config.js";
+import { normalizePathForHost, windowsUserProfileDirs } from "./platform.js";
+export function resolveLockDir() {
+    return resolve(homedir(), CONFIG_DIR_NAME, EXT_CONFIG_NAME, "lock");
+}
+export function resolveLockDirs(options = {}) {
+    if (options.lockDir)
+        return [resolve(options.lockDir)];
+    const dirs = [resolve(options.homeLockDir ?? resolveLockDir())];
+    for (const profileDir of windowsUserProfileDirs(options.windowsUsersRoot, options.env)) {
+        dirs.push(resolve(profileDir, CONFIG_DIR_NAME, EXT_CONFIG_NAME, "lock"));
+    }
+    return dedupePaths(dirs);
+}
+function dedupePaths(paths) {
+    const seen = new Set();
+    const deduped = [];
+    for (const path of paths) {
+        const resolved = resolve(path);
+        let key = resolved;
+        try {
+            key = realpathSync(resolved);
+        }
+        catch {
+        }
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(resolved);
+    }
+    return deduped;
+}
+export function normalizePath(input) {
+    const resolved = resolve(input);
+    if (process.platform === "win32" && resolved.length >= 2 && resolved[1] === ":") {
+        return resolved[0].toUpperCase() + resolved.slice(1);
+    }
+    return resolved;
+}
+export function normalizePathForComparison(input, env = process.env) {
+    return normalizePath(normalizePathForHost(input, env));
+}
+export function isPathInsideOrEqual(parent, child) {
+    const normalizedParent = normalizePath(parent);
+    const normalizedChild = normalizePath(child);
+    if (normalizedParent === normalizedChild)
+        return true;
+    const rel = relative(normalizedParent, normalizedChild);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+export function hasDirectWorkspaceMatch(workspaceFolders, cwd, env = process.env) {
+    const normalizedCwd = normalizePathForComparison(cwd, env);
+    return workspaceFolders.some((workspaceFolder) => isPathInsideOrEqual(normalizePathForComparison(workspaceFolder, env), normalizedCwd));
+}
+export function relationshipMatchLength(workspaceFolder, cwd, env = process.env) {
+    const workspace = normalizePathForComparison(workspaceFolder, env);
+    const active = normalizePathForComparison(cwd, env);
+    if (isPathInsideOrEqual(workspace, active)) {
+        return workspace.length + 10_000;
+    }
+    if (isPathInsideOrEqual(active, workspace)) {
+        return active.length;
+    }
+    return 0;
+}
+export function toRelativeDisplayPath(filePath, workspaceFolder, cwd, env = process.env) {
+    const base = workspaceFolder ?? cwd;
+    if (!base)
+        return normalizePathForHost(filePath, env);
+    const normalizedFilePath = normalizePathForHost(filePath, env);
+    const normalizedBase = normalizePathForHost(base, env);
+    const rel = relative(normalizedBase, normalizedFilePath);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel))
+        return normalizedFilePath;
+    return rel.split(sep).join("/");
+}

package/dist/src/shared/platform.js

@@ -0,0 +1,57 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isProcessEnvOrPiConfigOverlay, resolvePiConfigEnv } from "./config.js";
+const WINDOWS_SYSTEM_PROFILES = new Set(["public", "default", "default user", "all users"]);
+export function isWsl(env = process.env) {
+    const configuredEnv = resolvePiConfigEnv(env);
+    if (configuredEnv.WSL_DISTRO_NAME || configuredEnv.WSL_INTEROP)
+        return true;
+    if (!isProcessEnvOrPiConfigOverlay(configuredEnv))
+        return false;
+    try {
+        return /microsoft|wsl/i.test(readFileSync("/proc/version", "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+export function normalizePathForHost(input, env = process.env) {
+    const configuredEnv = resolvePiConfigEnv(env);
+    if (!input || !isWsl(configuredEnv))
+        return input;
+    const driveMatch = input.match(/^([a-zA-Z]):[\\/](.*)$/);
+    if (driveMatch) {
+        const drive = driveMatch[1].toLowerCase();
+        const rest = driveMatch[2].replaceAll("\\", "/");
+        return `/mnt/${drive}/${rest}`;
+    }
+    const uncMatch = input.match(/^[\\/]{2}(?:wsl\$|wsl\.localhost)[\\/]([^\\/]+)[\\/](.*)$/i);
+    if (uncMatch) {
+        const distro = uncMatch[1];
+        const rest = uncMatch[2].replaceAll("\\", "/");
+        const currentDistro = configuredEnv.WSL_DISTRO_NAME;
+        if (!currentDistro || distro.toLowerCase() === currentDistro.toLowerCase()) {
+            return `/${rest}`;
+        }
+    }
+    return input;
+}
+export function windowsUserProfileDirs(usersRoot = "/mnt/c/Users", env = process.env) {
+    if (!isWsl(env))
+        return [];
+    try {
+        return readdirSync(usersRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !WINDOWS_SYSTEM_PROFILES.has(entry.name.toLowerCase()))
+            .map((entry) => resolve(usersRoot, entry.name));
+    }
+    catch {
+        return [];
+    }
+}
+export function normalizeEditorSelectionSnapshotForHost(snapshot, env = process.env) {
+    return {
+        ...snapshot,
+        filePath: normalizePathForHost(snapshot.filePath, env),
+        workspaceFolder: snapshot.workspaceFolder ? normalizePathForHost(snapshot.workspaceFolder, env) : undefined,
+    };
+}

package/dist/src/shared/protocol.js

@@ -0,0 +1,3 @@
+export const PROTOCOL_VERSION = 1;
+export const AUTH_HEADER = "x-pi-x-ide-authorization";
+export const LOCK_FILE_EXTENSION = ".lock";

package/dist/src/shared/schema.js

@@ -0,0 +1,37 @@
+import { decodeAtMentionedParams, decodeDiagnosticFixRequestedParams, decodeEditorSelectionSnapshot, decodeLockFile, decodeSelectionChangedParams, decodeSelectionClearedParams, } from "./effect-schema.js";
+import { isJsonRpcRequest } from "./jsonrpc-guard.js";
+export { isJsonRpcRequest };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isIdeLockFile(value) {
+    return decodeLockFile(value) !== undefined;
+}
+export function isEditorSelectionSnapshot(value) {
+    return decodeEditorSelectionSnapshot(value) !== undefined;
+}
+export function isSelectionChangedParams(value) {
+    return decodeSelectionChangedParams(value) !== undefined;
+}
+export function isSelectionClearedParams(value) {
+    return decodeSelectionClearedParams(value) !== undefined;
+}
+export function isAtMentionedParams(value) {
+    return decodeAtMentionedParams(value) !== undefined;
+}
+export function isDiagnosticFixRequestedParams(value) {
+    return decodeDiagnosticFixRequestedParams(value) !== undefined;
+}
+export function parseJsonObject(input) {
+    try {
+        const parsed = JSON.parse(input);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseLockFileContent(content) {
+    const parsed = parseJsonObject(content);
+    return parsed === undefined ? undefined : decodeLockFile(parsed);
+}

package/dist/src/shared/version.js

@@ -0,0 +1 @@
+export const PI_X_IDE_VERSION = "1.20.1";

package/dist/src/shared/ws.js

@@ -0,0 +1,8 @@
+import { Buffer } from "node:buffer";
+export function decodeRawData(raw) {
+    if (Array.isArray(raw))
+        return Buffer.concat(raw).toString("utf8");
+    if (Buffer.isBuffer(raw))
+        return raw.toString("utf8");
+    return Buffer.from(raw).toString("utf8");
+}

package/docs/explanation/architecture.md

@@ -0,0 +1,123 @@
+# Architecture
+
+Pi × IDE bridges two processes that normally know nothing about each other: your
+IDE and the Pi TUI. This page explains the moving parts, the data flow, and why
+each editor connects differently. It is understanding-oriented — for exact
+message shapes and field semantics, see the
+[protocol specification](../specs/ide-protocol.md).
+
+## The three roles
+
+| Role             | Who                                                              | Responsibility                                                                   |
+| ---------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| **IDE plugin**   | VS Code extension, JetBrains plugin, Neovim Lua plugin + sidecar | Observe the active editor and selection, expose them over a local WebSocket.     |
+| **Lock file**    | Written by the IDE plugin, read by Pi                            | Advertise the WebSocket endpoint (host, port, auth token) and workspace folders. |
+| **Pi extension** | `pi-x-ide` loaded into the Pi TUI                                | Discover lock files, connect, receive selections, inject them as LLM context.    |
+
+Zed is the exception: it has no plugin, so Pi reads Zed's local state database
+directly. See [Why each editor connects differently](#why-each-editor-connects-differently).
+
+## Data flow
+
+```
+User selects text in the IDE
+        │
+        ▼
+┌──────────────────────────────────────────────────────────┐
+│ IDE plugin (VS Code / JetBrains / Neovim sidecar)        │
+│                                                          │
+│  Captures editor + selection, broadcasts a               │
+│  JSON-RPC "selection_changed" notification.              │
+└──────────────────────┬───────────────────────────────────┘
+                       │  WebSocket  ws://127.0.0.1:<port>
+                       │  Auth: x-pi-x-ide-authorization header
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│ Pi extension  (src/pi/connection.ts)                     │
+│                                                          │
+│  Receives the notification, caches it as                 │
+│  runtime.latestSelection, marks attachState = "pending", │
+│  updates the TUI widget (⇡ marker).                      │
+└──────────────────────┬───────────────────────────────────┘
+                       │  on next user message
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│ Pi prompt lifecycle  (src/pi/context.ts)                 │
+│                                                          │
+│  before_agent_start: snapshots the pending selection.    │
+│  Adds a visible custom message containing only IDE, file, │
+│  and selected line range metadata. Prompt stays intact;   │
+│  agent can read source from disk as needed.               │
+│  attachState = "sent".                                   │
+└──────────────────────────────────────────────────────────┘
+```
+
+The attach shortcut (`Ctrl+Alt+K` in the TUI, or the IDE's attach command) sends
+an `at_mentioned` notification instead. That inserts the `@file#Lx-Ly` mention
+into the Pi input box and caches the selection text so it is ready for the next
+turn.
+
+## Why each editor connects differently
+
+Each IDE's extension API dictates the transport.
+
+| Editor        | Mechanism                                  | Reason                                                                                                                                                               |
+| ------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **VS Code**   | WebSocket server inside the extension host | Rich extension API: `onDidChangeTextEditorSelection`, file-system access, terminal creation. A lightweight server runs in-process — no separate process needed.      |
+| **JetBrains** | WebSocket server inside the IDE process    | Same rationale: the `com.intellij` API provides editor listeners and project-service lifecycle. The Kotlin plugin runs the server in-process.                        |
+| **Neovim**    | Separate **sidecar** process               | Lua cannot run a WebSocket server natively. The sidecar is a standalone process that talks to Neovim over stdin/stdout (JSON lines) and exposes the WebSocket to Pi. |
+| **Zed**       | **Pi-side SQLite polling**                 | Zed has no extension API. It stores editor state in a local SQLite database, which Pi reads directly every second. The polling runs on the Pi side, not in Zed.      |
+
+### The Neovim sidecar
+
+Because Neovim cannot host a WebSocket server, the Lua plugin spawns a sidecar
+process (`src/nvim/sidecar.ts`) that owns the server and the lock file. The
+plugin captures selections via Neovim autocmds (`CursorMoved`, `BufEnter`,
+visual-mode marks), debounces them, and writes JSON messages to the sidecar's
+stdin. The sidecar broadcasts them as JSON-RPC notifications to Pi.
+
+The sidecar is resolved in this order (`ide-plugins/nvim/lua/pi_x_ide/download.lua`):
+
+1. A platform binary bundled in `ide-plugins/nvim/bin/`.
+2. A cached binary downloaded from GitHub Releases, verified by SHA256.
+3. A fallback Node.js script (`pi-x-ide-nvim-sidecar.cjs`).
+
+This is why the Neovim plugin "just works" on first start: it downloads the right
+binary for your platform and falls back to Node if the download is unavailable.
+
+### Zed polling
+
+Pi reads Zed's state database directly (`src/pi/zed.ts`). On each poll (default
+1000 ms, clampable to 100–2000 ms via `PI_X_IDE_ZED_POLL_INTERVAL_MS`):
+
+1. Check the SQLite WAL file's mtime — skip the expensive read if nothing changed
+   (this matters especially under WSL, where a full snapshot would otherwise be
+   copied each tick).
+2. Query the active editor by joining Zed's `items`, `panes`, `workspaces`, and
+   `editors` tables.
+3. Score candidates by workspace match and pick the best.
+4. Convert UTF-8 byte offsets to VS Code/LSP-style line/character positions.
+
+## Authentication model
+
+Each IDE process generates a fresh token per session using
+`randomBytes(32).toString("hex")` — a 64-character hex string
+(`src/shared/lock-file.ts`). JetBrains generates the equivalent with
+`SecureRandom`. The token is written to the lock file (mode `0600`) and sent only
+during the WebSocket upgrade handshake, in the `x-pi-x-ide-authorization` header.
+The server's `verifyClient` callback rejects any connection whose header does not
+match (`src/shared/ide-server.ts`).
+
+Tokens never leave localhost except across the WSL boundary, where the WebSocket
+still targets the resolved Windows host.
+
+## Related
+
+- [How discovery works](discovery.md) — how Pi finds lock files and picks a
+  connection.
+- [Effect adoption](effect.md) — how Pi-side TypeScript may use Effect internally
+  for errors, schema validation, and IO boundaries.
+- [Protocol specification](../specs/ide-protocol.md) — exact message shapes,
+  handshake, and notifications.
+- [Feature parity](../reference/feature-parity.md) — which capabilities each
+  editor supports.

package/docs/explanation/discovery.md

@@ -0,0 +1,113 @@
+# How discovery works
+
+Pi discovers IDE connections through **lock files**: small JSON files that each
+running IDE plugin writes to advertise its WebSocket endpoint. This page explains
+where they live, how Pi picks the right one, and how the WSL boundary is crossed.
+For the exact file schema, see the
+[protocol specification](../specs/ide-protocol.md).
+
+## The lock directory
+
+The primary lock directory is always:
+
+```
+~/.pi/pi-x-ide/lock/
+```
+
+Each file is named `<ide>-<pid>-<port>.lock`, for example:
+
+- `vscode-12345-48123.lock`
+- `nvim-98765-50001.lock`
+- `jetbrains-4242-51234.lock`
+
+A lock file contains the IDE source, WebSocket host and port, an auth token, the
+workspace folders, the process PID, and timestamps. Writers create a temp file and
+rename it into place atomically; the directory is mode `0700` and files are mode
+`0600`.
+
+## How Pi picks a connection
+
+When Pi starts, it scans every lock directory it knows about, parses each file,
+and ranks the candidates. The ranking prefers a connection whose workspace
+**contains** your terminal's current working directory (`relationshipMatchLength`
+in `src/shared/paths.ts`):
+
+1. A workspace folder that contains your `cwd` scores highest.
+2. A workspace folder contained _by_ your `cwd` (you started Pi in a parent
+   directory) scores lower.
+3. No relationship scores zero.
+
+This is why the recommended workflow is to start Pi from **inside your project
+directory**: the match is exact and Pi connects automatically. If your `cwd` is
+only a parent (for example `~/`), no candidate wins outright - run `/ide` to
+choose one manually, or `/ide auto` to re-attempt matching.
+
+## Lock file lifecycle
+
+Lock files are ephemeral. Pi parses each lock before it applies stale-file policy.
+When Pi proves that a producer is live, it keeps the lock at any age.
+
+- **Live local PID:** a usable local PID is a positive safe integer. A live usable
+  PID keeps the lock. A dead usable PID removes the lock.
+- **Age-only cleanup:** if the PID is missing or unusable, or if PID checking is
+  disabled, Pi uses age. Files older than 24 hours are then deleted.
+- **WSL Windows locks:** for `runningInWindows: true` when Pi runs in WSL, TCP
+  reachability is authoritative. Pi keeps a reachable lock and removes an
+  unreachable lock.
+- **Malformed:** unparseable files are removed.
+
+VS Code, Neovim, and JetBrains refresh owned locks every 15 minutes while they
+are active. Refresh keeps the endpoint identity and the auth token, and it updates
+freshness data. If the file is deleted while the producer is still active, the
+lock can stay missing until the next heartbeat.
+
+Zed does not write this lock file. Pi reads Zed state from SQLite.
+
+When you close your IDE, the plugin removes its lock file. If the IDE crashes, Pi
+reclaims the file on the next scan when liveness fails or age-only cleanup applies.
+
+## WSL2: discovering an IDE on Windows
+
+When Pi runs inside WSL and your IDE runs on native Windows, the IDE writes its
+lock file to the Windows user profile. Pi scans both the Linux home lock directory
+**and** Windows user profiles such as
+`/mnt/c/Users/<user>/.pi/pi-x-ide/lock/`, skipping Windows system profiles.
+
+A Windows lock file sets `runningInWindows: true`. When Pi runs in WSL,
+TCP reachability to the Windows producer is authoritative. Pi does not use
+the Windows PID as Linux process-liveness evidence.
+
+### Resolving the connection host
+
+The lock file's `host` is always `127.0.0.1`, which is correct for the IDE
+process but **not** reachable from inside WSL. Pi resolves a usable host in this
+order (`src/pi/ide-host.ts`):
+
+1. **`PI_X_IDE_HOST_OVERRIDE`** - if set (in the environment or
+   `~/.pi/pi-x-ide/config.json` under `env`), use it directly.
+2. **WSL default gateway** - if the lock has `runningInWindows: true` and Pi is in
+   WSL, parse the gateway from `ip route show` and use it only if a short TCP
+   probe to `<gateway>:<port>` succeeds (500 ms timeout).
+3. **The lock file `host` value** - `127.0.0.1` for same-host connections.
+4. **`127.0.0.1`** - if `host` is empty.
+
+Most WSL setups need no configuration: step 2 handles it automatically. If your
+WSL networking mode, firewall, or endpoint security blocks the probe, set
+`PI_X_IDE_HOST_OVERRIDE` explicitly. See [Use Pi × IDE over WSL2](../how-to/use-wsl2.md).
+
+## Path normalization
+
+Editor paths arriving from a Windows IDE are Windows-style. Pi normalizes them to
+the Linux host before workspace matching, UI display, `@file#Lx-Ly` mention
+formatting, and prompt context formatting. For example, a WSL UNC path like
+`\\wsl.localhost\Ubuntu\home\user\project` becomes `/home/user/project` when Pi is
+running in the `Ubuntu` distro (`src/shared/platform.ts`).
+
+## Related
+
+- [Architecture](architecture.md) - the end-to-end data flow and per-editor
+  transports.
+- [Protocol specification](../specs/ide-protocol.md) - lock file schema, handshake,
+  and notification semantics.
+- [Troubleshoot a missing connection](../how-to/troubleshoot-connection.md) - what
+  to do when discovery does not connect.

package/docs/explanation/effect.md

@@ -0,0 +1,127 @@
+# Effect adoption
+
+Pi × IDE uses [Effect](https://effect.website/) as an **implementation detail**
+for typed failures, Schema validation, and composable async work on the Pi side.
+Public APIs that VS Code, tests, and Pi host callbacks call stay Promise- or
+sync-friendly. This page is for contributors who touch `src/shared/*` or
+`src/pi/*`.
+
+## Why Effect here
+
+- **Structured errors** — tagged failures (`LockFileParseError`, connect/install
+  errors) carry fields without free-form string parsing.
+- **Schema decode** — lock files, selections, and diagnostic payloads share one
+  validation path (`effect-schema` → `schema.ts` adapters).
+- **Boundary control** — IO programs (discovery, host resolve, install, connect,
+  reconnect, Zed poll) can fail closed or log-and-swallow at process edges.
+
+Effect is not a product feature. End users never configure it.
+
+## Boundary rule
+
+- **Never** throw Effect failures into Pi host callbacks or VS Code activation.
+- Exit Effects with `Effect.runPromise` / `Effect.runSync`, Phase 1 runners
+  (`runEffect` / `runEffectSync`), or Pi helpers (`runPiEffect`).
+- On failure at a Pi boundary: report via `logExtensionError` / `containPiError`
+  (pi `ui.notify`, not `console`); optionally set `runtime.connectionStatus = "error"`.
+- **Interrupt** (reconnect / Zed poll fibers) is cancellation, not a UI error.
+
+Auth tokens stay in WebSocket upgrade headers only. Do not put `authToken` or
+full lock JSON into logs, Effect error messages, or `scope` strings.
+
+## Module map
+
+| Module                                                                                                     | Role                                                                                                                   |
+| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `src/shared/effect-errors.ts`                                                                              | `Data.TaggedError` domain errors with readable `message` getters                                                       |
+| `src/shared/effect-runtime.ts`                                                                             | `runEffect` / `runEffectSync` (log-and-swallow); `runEffectOrThrow` (tests)                                            |
+| `src/shared/effect-schema.ts`                                                                              | Effect Schema definitions + `decode*` helpers                                                                          |
+| `src/shared/schema.ts`                                                                                     | Stable `is*` / `parse*` facades over Schema decode                                                                     |
+| `src/shared/jsonrpc-guard.ts`                                                                              | Effect-free `isJsonRpcRequest` for the VS Code `ide-server` import graph                                               |
+| `src/pi/index.ts`, `commands.ts`, `context.ts`, `ui.ts`, `state.ts`, `safety.ts`, `diagnostic-renderer.ts` | Lightweight static shell: registration, status UI, local diagnostic renderer, error containment (no Effect, no pi-tui) |
+| `src/pi/config-ui.ts`                                                                                      | Settings dialog (pi-tui); loaded only via dynamic import from `/ide settings`                                          |
+| `src/pi/runtime-loader.ts`                                                                                 | Heavy-runtime dynamic boundary: cached `import("./runtime-services.js")`                                               |
+| `src/pi/runtime-services.ts`                                                                               | Heavy lifecycle: discovery/install/connect/reconnect/Zed (may import Effect)                                           |
+| `src/pi/effect-boundary.ts`                                                                                | `runPiEffect` → `containPiError` + UI status (Effect runtime import)                                                   |
+| `src/pi/safety.ts`                                                                                         | Effect-free `containPiError`, `runPiBoundary`, `runPiBoundaryAsync`                                                    |
+| `src/pi/discovery.ts`, `ide-host.ts`, `install.ts`                                                         | Effect programs + Promise facades                                                                                      |
+| `src/pi/connection.ts`                                                                                     | Connect handshake Effect; maps tagged timeout → `IdeConnectionTimeoutError`                                            |
+| `src/pi/reconnect.ts`, `zed.ts`                                                                            | Interruptible fibers for reconnect delay and Zed poll                                                                  |
+
+VS Code still imports `@shared/*` pieces that must stay Effect-free on the hot
+path (`jsonrpc-guard`, protocol, lock-file helpers). Pulling `effect-schema` into
+the VS Code bundle is an escape-hatch failure: keep decode on the Pi path or
+split guards if bundle size grows.
+
+### Pi startup shell vs heavy runtime
+
+- The published Pi entry is an esbuild code-split ESM shell (`dist/src/pi/index.js`)
+  with Effect/`ws`/`node:sqlite` only on **dynamic-import** edges into lazy chunks.
+- `runtime-loader.ts` is the only dynamic boundary for the heavy lifecycle
+  (`runtime-services.ts`). `effect-boundary.ts` may import Effect; the static
+  shell must not.
+- `/ide settings` is a second lazy boundary: `commands.ts` dynamically imports
+  `config-ui.ts` only when the settings subcommand runs. That keeps `pi-tui`
+  (SettingsList and friends) out of the static shell graph. Because the lazy
+  chunk bundles its own pi-tui code, it seeds that copy with the keybinding
+  manager injected by `ctx.ui.custom()` so user remappings still apply.
+- The diagnostic message renderer is a **local** Component-shaped helper
+  (`render` / `invalidate`) so the shell never takes a runtime edge into
+  `@earendil-works/pi-tui`. Config UI uses a local `DynamicBorder` for the same
+  reason — no coding-agent value import for borders.
+- **Host package runtime edge ban:** every generated Pi entry JS output (static
+  entry and lazy chunks) must have **zero** runtime external imports of
+  `@earendil-works/pi-coding-agent` or `@earendil-works/pi-tui`. Type-only imports
+  are fine; value imports of host packages in native ESM bypass Pi's jiti aliases
+  and can double-load host copies. The bundler metafile gate fails the build on
+  any remaining host external edge. `pi-tui` is bundled into the settings lazy
+  chunk; coding-agent stays listed as esbuild `external` for future checks but
+  must not appear as a runtime edge in outputs.
+- Adding a static Effect, heavy-runtime, or host-package value import to the
+  shell is a **startup regression**. Topology/size gates fail the build if the
+  static entry gains a heavy static dependency or if any output reintroduces a
+  host runtime external edge.
+
+## Import style
+
+Prefer Effect subpath imports for tree-shaking:
+
+```ts
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Data from "effect/Data";
+import * as Fiber from "effect/Fiber";
+```
+
+## Error tagging
+
+- Use tags listed in `effect-errors.ts` (or add a tag in the phase that needs it).
+- Override `message` so default logging is useful without dumping secrets.
+- Promise facades that existing code checks with `instanceof` (e.g.
+  `IdeConnectionTimeoutError`) must map tagged failures back to those classes.
+
+## What stays Promise / sync based
+
+- Exported discovery, install, connect, and host-resolve entry points.
+- `IdeConnection` class methods and callback model.
+- VS Code extension activation and shared IDE host WebSocket server.
+- Pure helpers: ranking, version compare, path matching, Zed snapshot SQL.
+
+Call sites in the heavy runtime (`runtime-services.ts` and deeper) should keep
+using Promise facades unless a path explicitly opts into `runPiEffect` from
+`effect-boundary.ts`. The lightweight shell must not import `effect-boundary.ts`
+or Effect modules.
+
+## Non-goals
+
+- Full `Layer` DI rewrite of the extension entrypoint.
+- JetBrains Kotlin / Neovim Lua rewrites.
+- Replacing `node:test` with `@effect/vitest` as a requirement.
+- On-wire protocol or lock-file JSON shape changes.
+- Mock modes or fake Effect data paths.
+
+## Related
+
+- [Architecture](architecture.md) — process roles and data flow.
+- [How discovery works](discovery.md) — lock ranking (behavior unchanged by Effect).
+- Implementation plans: [effect-adoption-plan](../plans/effect-adoption-plan/).

package/docs/how-to/install-jetbrains.md

@@ -0,0 +1,58 @@
+# Install the JetBrains plugin
+
+Pi × IDE integrates with IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains
+IDEs through a marketplace plugin.
+
+## Prerequisites
+
+- The [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI installed.
+- The `pi-x-ide` Pi package installed: `pi install npm:pi-x-ide`.
+- A JetBrains IDE (2024.2 or later recommended).
+
+## Install from the JetBrains Marketplace
+
+1. In your IDE, open **Settings / Preferences -> Plugins -> Marketplace**.
+2. Search for `balaenis.pi-x-ide`.
+3. Click **Install**, then restart the IDE when prompted.
+
+The plugin is also listed on the
+[JetBrains Marketplace](https://plugins.jetbrains.com/plugin/32664-pi-x-ide).
+
+## Verify the connection
+
+1. Open a project in your JetBrains IDE.
+2. Open a terminal in that project and start Pi:
+
+   ```bash
+   pi
+   ```
+
+3. Open a source file and select some text. The Pi widget should show:
+
+   ```
+   ⧉ ⇡ foo.ts#L10-L20
+   ```
+
+If the widget does not appear, see
+[Troubleshoot a missing connection](troubleshoot-connection.md).
+
+## Attach a selection
+
+With text selected in the editor, do either of the following:
+
+- Press `Ctrl+Alt+K` (Linux/Windows) or `Cmd+Alt+K` (macOS).
+- Run the **Pi x IDE: Attach Selection** action from the Find Action dialog
+  (`Ctrl+Shift+A` / `Cmd+Shift+A`).
+
+Pi inserts `@relative/path#Lx-Ly` into the input box. Submit your message to send
+the selected text as LLM context.
+
+## Notes
+
+- JetBrains sends selection notifications for both non-empty selections and an
+  active file with no selected text.
+- Diagnostic Quick Fix and auto-install are VS Code-family features and are not
+  available for JetBrains. See the
+  [feature parity](../reference/feature-parity.md) table.
+- For local development and sandbox testing, see
+  [CONTRIBUTING.md](../../CONTRIBUTING.md).