@lsproxy/cli 0.4.1 → 0.4.2

package/README.md

@@ -5,6 +5,15 @@ its capabilities as typed subcommands — hover, rename, format, find-references
 code actions, and more. The command surface is built at runtime from the server's
 advertised capabilities, so it works with any LSP server out of the box.
 
+## Features
+
+- **Semantic refactoring** — project-wide rename, move-file with importer updates, extract symbol
+- **Reference tracking** — find all references, call hierarchy, workspace symbol search
+- **Code actions** — list and apply quick-fixes and refactors at any range
+- **Any LSP server** — TypeScript, Rust, Python, Go, or any LSP-compliant server via `lsp.json`
+- **Proxy daemon** — warm server connections for sub-100ms subsequent invocations
+- **Dry-run preview** — `--dry-run` prints diffs without writing; safe to inspect before committing
+
 ## Install
 
 ```bash
@@ -12,6 +21,25 @@ npx @lsproxy/cli textDocument hover src/foo.ts 12:7   # zero-install
 pnpm add -g @lsproxy/cli                               # or install globally
 ```
 
+## Quick Start
+
+```bash
+# Preview a rename before writing (always do this first)
+lsproxy textDocument rename --dry-run src/auth/login.ts 42:15 "signIn"
+
+# Find all references to a symbol
+lsproxy textDocument references src/auth/login.ts 42:15
+
+# List available code actions at a range, then apply the chosen one
+lsproxy textDocument codeAction src/foo.ts 12:1-12:20
+
+# Send any LSP method directly (useful for probing capabilities)
+lsproxy call workspace/executeCommand --params '{"command":"typescript.reloadProjects"}'
+```
+
+Positions are **1-based** (`line:col`, editor-style).
+Write-side commands apply changes to disk automatically — use `--dry-run` to preview first.
+
 ## Usage
 
 ```
@@ -19,52 +47,49 @@ lsproxy <namespace> <command> [args] [flags]
 lsproxy call <method> --params <json>
 ```
 
-Commands are built from the server's capabilities at startup:
+Commands are built from the server's capabilities at startup. Available namespaces:
+`callHierarchy`, `codeAction`, `codeLens`, `completionItem`, `documentLink`,
+`inlayHint`, `textDocument`, `workspace`, `workspaceSymbol`.
 
 ```bash
-lsproxy textDocument hover       src/foo.ts 12:7
-lsproxy textDocument rename      src/foo.ts 12:7 newName
-lsproxy textDocument references  src/foo.ts 12:7
-lsproxy textDocument definition  src/foo.ts 12:7
-lsproxy textDocument formatting  src/foo.ts
+lsproxy textDocument hover           src/foo.ts 12:7
+lsproxy textDocument rename          src/foo.ts 12:7 newName
+lsproxy textDocument references      src/foo.ts 12:7
+lsproxy textDocument definition      src/foo.ts 12:7
+lsproxy textDocument formatting      src/foo.ts
 lsproxy textDocument rangeFormatting src/foo.ts 1:1-50:1
-lsproxy textDocument onTypeFormatting src/foo.ts 12:7 --ch ";" --on-type-formatting-tab-size 2 --on-type-formatting-insert-spaces true
-lsproxy workspace   symbol       MyClass
+lsproxy workspace   symbol           MyClass
 lsproxy call        textDocument/semanticTokens/full --params '{"textDocument":{"uri":"file:///…"}}'
 ```
 
-Positions are **1-based** (`line:col`, editor-style).  
-Write-side commands (`rename`, `formatting`, code actions that produce edits)
-apply changes to disk automatically. Pass `--dry-run` to preview instead.
-
 ### Code actions
 
-`codeAction` returns a JSON array of available fixes and refactors for the given
-range.
+`codeAction` returns a JSON array of available fixes and refactors for a range.
+When exactly one action carries an edit it is applied automatically; when zero or
+multiple carry edits the array is printed and no files are changed.
 
 ```bash
-lsproxy textDocument codeAction src/foo.ts 12:1-12:20
+lsproxy textDocument codeAction --dry-run src/foo.ts 12:1-12:20
 ```
 
-```json
-[
-  { "title": "Add missing import",       "kind": "quickfix" },
-  { "title": "Extract to variable",      "kind": "refactor.extract.variable" },
-  { "title": "Convert to arrow function","kind": "refactor.rewrite",
-    "edit": { "changes": { "file:///src/foo.ts": [ ... ] } } }
-]
-```
+## Troubleshooting
 
-**When exactly one** action in the result carries an `edit`, it is applied to
-disk automatically. Use `--dry-run` to preview the diff instead:
+**Commands missing from `--help`** — lsproxy only registers commands for capabilities the
+server actually advertises. If `textDocument rename` doesn't appear, the server doesn't
+support `renameProvider`. Use `lsproxy call initialize --params '{}'` to inspect the
+server's capability response.
 
-```bash
-lsproxy textDocument codeAction --dry-run src/foo.ts 12:1-12:20
-```
+**Wrong positions** — Positions must be 1-based (`line:col`). Most editors display
+1-based positions; LSP protocol is 0-based internally but lsproxy converts for you.
+Passing 0-based values shifts edits by one line/column.
+
+**Server not found** — Without `--server`, lsproxy walks up from `--root` looking for
+`lsp.json`. If it can't find one it will time out. Either add `lsp.json` to the project
+root or pass `--server <cmd>` explicitly.
 
-When the server returns zero or multiple edit-bearing actions, the full JSON
-array is printed and no files are changed — pick the one you want and re-run
-with `--params` to apply it directly.
+**Write commands applied unexpectedly** — `rename`, `formatting`, and code actions that
+produce edits write to disk immediately. Always run with `--dry-run` first on an
+unfamiliar codebase.
 
 ## Help output
 

package/dist/index.d.ts

@@ -12,4 +12,5 @@ export type { SessionOptions } from './session.js';
 export { applyWorkspaceEdit, applyTextEdits, planWorkspaceEdit } from './apply.js';
 export type { WorkspaceEdit, LspTextEdit, LspRange, LspPosition, AppliedChange } from './apply.js';
 export type { GlobalFlags } from './io.js';
+export { buildProgram } from './program.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACnF,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACnG,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACnF,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACnG,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -9,4 +9,5 @@
  */
 export { RefactorSession } from './session.js';
 export { applyWorkspaceEdit, applyTextEdits, planWorkspaceEdit } from './apply.js';
+export { buildProgram } from './program.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGnF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/program.d.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+/**
+ * Build the full Commander program with all LSP method subcommands populated.
+ *
+ * Uses a mock {@link ServerCapabilities} where every capability path is truthy
+ * so the complete command tree is included regardless of what a live server
+ * would actually advertise. Intended for static introspection by tools such as
+ * `skillit gen --source cli`; action handlers close over stub values and will
+ * error if invoked, so this program is not suitable for real command dispatch.
+ *
+ * @returns A Commander {@link Command} rooted at `lsproxy` with all known LSP
+ *   method subcommands registered under their namespace (e.g. `textDocument`,
+ *   `workspace`) plus the catch-all `call <method>` command.
+ */
+export declare function buildProgram(): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAqCtC"}

package/dist/program.js

@@ -0,0 +1,47 @@
+import { Command } from 'commander';
+import { buildCommandTree } from './build-commands.js';
+/**
+ * Build the full Commander program with all LSP method subcommands populated.
+ *
+ * Uses a mock {@link ServerCapabilities} where every capability path is truthy
+ * so the complete command tree is included regardless of what a live server
+ * would actually advertise. Intended for static introspection by tools such as
+ * `skillit gen --source cli`; action handlers close over stub values and will
+ * error if invoked, so this program is not suitable for real command dispatch.
+ *
+ * @returns A Commander {@link Command} rooted at `lsproxy` with all known LSP
+ *   method subcommands registered under their namespace (e.g. `textDocument`,
+ *   `workspace`) plus the catch-all `call <method>` command.
+ */
+export function buildProgram() {
+    const program = new Command('lsproxy')
+        .description('LSP-driven CLI for project-wide refactoring via any LSP server')
+        .option('--server <cmd>', 'LSP server launch command (overrides lsp.json discovery)')
+        .option('--root <dir>', 'Project root (default: cwd)')
+        .option('--dry-run', 'Print changes; do not write')
+        .option('--json', 'Machine-readable JSON on stdout; diagnostics to stderr')
+        .option('--wait <ms>', 'Server index wait in ms (default: 15000)')
+        .option('--verbose', 'Progress logging to stderr')
+        .option('--allow-outside-root', 'Allow file paths outside --root')
+        .option('--no-proxy', 'Bypass proxy daemon; connect directly to language server');
+    // Proxy that returns itself for any property access so every capability
+    // path resolves to a truthy object — all capability-gated method subcommands
+    // are included in the tree without needing a live LSP server connection.
+    const allCaps = new Proxy({}, {
+        get: (_target, _prop, receiver) => receiver
+    });
+    const stubFlags = {
+        server: '',
+        root: process.cwd(),
+        dryRun: false,
+        json: false,
+        verbose: false,
+        waitMs: 15000,
+        allowOutsideRoot: false,
+        noProxy: false,
+        overwrite: false
+    };
+    buildCommandTree(program, allCaps, null, stubFlags);
+    return program;
+}
+//# sourceMappingURL=program.js.map

package/dist/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,SAAS,CAAC;SACnC,WAAW,CAAC,gEAAgE,CAAC;SAC7E,MAAM,CAAC,gBAAgB,EAAE,0DAA0D,CAAC;SACpF,MAAM,CAAC,cAAc,EAAE,6BAA6B,CAAC;SACrD,MAAM,CAAC,WAAW,EAAE,6BAA6B,CAAC;SAClD,MAAM,CAAC,QAAQ,EAAE,wDAAwD,CAAC;SAC1E,MAAM,CAAC,aAAa,EAAE,0CAA0C,CAAC;SACjE,MAAM,CAAC,WAAW,EAAE,4BAA4B,CAAC;SACjD,MAAM,CAAC,sBAAsB,EAAE,iCAAiC,CAAC;SACjE,MAAM,CAAC,YAAY,EAAE,0DAA0D,CAAC,CAAC;IAEpF,wEAAwE;IACxE,6EAA6E;IAC7E,yEAAyE;IACzE,MAAM,OAAO,GAAG,IAAI,KAAK,CACvB,EAAE,EACF;QACE,GAAG,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ;KAC5C,CAC+B,CAAC;IAEnC,MAAM,SAAS,GAAgB;QAC7B,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE;QACnB,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,KAAK;QACb,gBAAgB,EAAE,KAAK;QACvB,OAAO,EAAE,KAAK;QACd,SAAS,EAAE,KAAK;KACjB,CAAC;IAEF,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAkC,EAAE,SAAS,CAAC,CAAC;IAElF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsproxy/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Standalone refactor CLI driving any LSP server: project-wide rename, file-move with importer updates, and move-symbol",
   "private": false,
   "keywords": [
@@ -38,7 +38,9 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills",
+    "skillit-postinstall.cjs"
   ],
   "publishConfig": {
     "access": "public"
@@ -51,6 +53,8 @@
     "@lspeasy/core": "2.3.0"
   },
   "devDependencies": {
+    "@skillit/cli": "^0.4.0",
+    "typedoc-plugin-skillit": "^1.4.0",
     "typescript": "^6.0.3"
   },
   "engines": {
@@ -60,6 +64,7 @@
     "build": "tsgo --build",
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
     "dev": "tsgo --build --watch",
-    "type-check": "tsgo --noEmit"
+    "type-check": "tsgo --noEmit",
+    "postinstall": "node ./skillit-postinstall.cjs"
   }
 }

package/skillit-postinstall.cjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
+const pkgName = pkg.name;
+const binMap = pkg.bin;
+if (!pkgName || !binMap || typeof binMap !== 'object' || Object.keys(binMap).length === 0) {
+  process.exit(0);
+}
+const binName = Object.keys(binMap)[0];
+const npxPrefix = 'npx ' + pkgName;
+
+const skillsDir = path.join(__dirname, 'skills');
+if (!fs.existsSync(skillsDir)) process.exit(0);
+
+function walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const content = fs.readFileSync(full, 'utf8');
+      const updated = content.replaceAll(npxPrefix, binName);
+      if (updated !== content) fs.writeFileSync(full, updated, 'utf8');
+    }
+  }
+}
+
+walk(skillsDir);

package/skills/cli/SKILL.md

@@ -0,0 +1,171 @@
+---
+description: API reference for cli
+name: cli
+---
+
+# cli
+
+## Features
+
+- **Semantic refactoring** — project-wide rename, move-file with importer updates, extract symbol
+- **Reference tracking** — find all references, call hierarchy, workspace symbol search
+- **Code actions** — list and apply quick-fixes and refactors at any range
+- **Any LSP server** — TypeScript, Rust, Python, Go, or any LSP-compliant server via `lsp.json`
+- **Proxy daemon** — warm server connections for sub-100ms subsequent invocations
+- **Dry-run preview** — `--dry-run` prints diffs without writing; safe to inspect before committing
+
+## Quick Start
+
+```
+lsproxy <namespace> <command> [args] [flags]
+lsproxy call <method> --params <json>
+```
+
+Commands are built from the server's capabilities at startup. Available namespaces:
+`callHierarchy`, `codeAction`, `codeLens`, `completionItem`, `documentLink`,
+`inlayHint`, `textDocument`, `workspace`, `workspaceSymbol`.
+
+```bash
+lsproxy textDocument hover           src/foo.ts 12:7
+lsproxy textDocument rename          src/foo.ts 12:7 newName
+lsproxy textDocument references      src/foo.ts 12:7
+lsproxy textDocument definition      src/foo.ts 12:7
+lsproxy textDocument formatting      src/foo.ts
+lsproxy textDocument rangeFormatting src/foo.ts 1:1-50:1
+lsproxy workspace   symbol           MyClass
+lsproxy call        textDocument/semanticTokens/full --params '{"textDocument":{"uri":"file:///…"}}'
+```
+
+### Code actions
+
+`codeAction` returns a JSON array of available fixes and refactors for a range.
+When exactly one action carries an edit it is applied automatically; when zero or
+multiple carry edits the array is printed and no files are changed.
+
+```bash
+lsproxy textDocument codeAction --dry-run src/foo.ts 12:1-12:20
+```
+
+## Troubleshooting
+
+**Commands missing from `--help`** — lsproxy only registers commands for capabilities the
+server actually advertises. If `textDocument rename` doesn't appear, the server doesn't
+support `renameProvider`. Use `lsproxy call initialize --params '{}'` to inspect the
+server's capability response.
+
+**Wrong positions** — Positions must be 1-based (`line:col`). Most editors display
+1-based positions; LSP protocol is 0-based internally but lsproxy converts for you.
+Passing 0-based values shifts edits by one line/column.
+
+**Server not found** — Without `--server`, lsproxy walks up from `--root` looking for
+`lsp.json`. If it can't find one it will time out. Either add `lsp.json` to the project
+root or pass `--server <cmd>` explicitly.
+
+**Write commands applied unexpectedly** — `rename`, `formatting`, and code actions that
+produce edits write to disk immediately. Always run with `--dry-run` first on an
+unfamiliar codebase.
+
+## Commands
+
+### callHierarchy
+
+callHierarchy operations
+
+**Usage:**
+```
+lsproxy callHierarchy [options] [command]
+```
+
+### codeAction
+
+codeAction operations
+
+**Usage:**
+```
+lsproxy codeAction [options] [command]
+```
+
+### codeLens
+
+codeLens operations
+
+**Usage:**
+```
+lsproxy codeLens [options] [command]
+```
+
+### completionItem
+
+completionItem operations
+
+**Usage:**
+```
+lsproxy completionItem [options] [command]
+```
+
+### documentLink
+
+documentLink operations
+
+**Usage:**
+```
+lsproxy documentLink [options] [command]
+```
+
+### inlayHint
+
+inlayHint operations
+
+**Usage:**
+```
+lsproxy inlayHint [options] [command]
+```
+
+### textDocument
+
+textDocument operations
+
+**Usage:**
+```
+lsproxy textDocument [options] [command]
+```
+
+### workspace
+
+workspace operations
+
+**Usage:**
+```
+lsproxy workspace [options] [command]
+```
+
+### workspaceSymbol
+
+workspaceSymbol operations
+
+**Usage:**
+```
+lsproxy workspaceSymbol [options] [command]
+```
+
+### call
+
+Send any LSP request by method name with raw JSON params
+
+**Usage:**
+```
+lsproxy call [options] <method>
+```
+
+| Flag | Type | Required | Default | Env | Description |
+| --- | --- | --- | --- | --- | --- |
+| `--params` | `string` | no | — | — | LSP params as JSON |
+
+**Arguments:**
+- `method` *(required)*
+
+## References
+
+Load these on demand — do NOT read all at once:
+
+- When using CLI commands → read `references/commands.md` for flags, arguments, and defaults

package/skills/cli/references/commands.md

@@ -0,0 +1,95 @@
+# Commands
+
+## callHierarchy
+
+callHierarchy operations
+
+```
+lsproxy callHierarchy [options] [command]
+```
+
+## codeAction
+
+codeAction operations
+
+```
+lsproxy codeAction [options] [command]
+```
+
+## codeLens
+
+codeLens operations
+
+```
+lsproxy codeLens [options] [command]
+```
+
+## completionItem
+
+completionItem operations
+
+```
+lsproxy completionItem [options] [command]
+```
+
+## documentLink
+
+documentLink operations
+
+```
+lsproxy documentLink [options] [command]
+```
+
+## inlayHint
+
+inlayHint operations
+
+```
+lsproxy inlayHint [options] [command]
+```
+
+## textDocument
+
+textDocument operations
+
+```
+lsproxy textDocument [options] [command]
+```
+
+## workspace
+
+workspace operations
+
+```
+lsproxy workspace [options] [command]
+```
+
+## workspaceSymbol
+
+workspaceSymbol operations
+
+```
+lsproxy workspaceSymbol [options] [command]
+```
+
+## call
+
+Send any LSP request by method name with raw JSON params
+
+```
+lsproxy call [options] <method>
+```
+
+### Options
+
+#### --params
+
+LSP params as JSON
+
+**Type:** `string`
+
+### Arguments
+
+#### `method`
+
+**Required:** yes

package/skills/lsproxy-cli/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: lsproxy-cli
+description: "`@lspeasy/cli` — programmatic entry point.
+
+Exposes the reusable refactor internals (session pipeline + WorkspaceEdit
+applier) so the same machinery can be embedded in scripts, not just invoked
+through the `lspeasy` bin. Also: lsp, language-server-protocol, refactor, rename, codemod, move-symbol, cli."
+license: MIT
+---
+
+# @lsproxy/cli
+
+`@lspeasy/cli` — programmatic entry point.
+
+Exposes the reusable refactor internals (session pipeline + WorkspaceEdit
+applier) so the same machinery can be embedded in scripts, not just invoked
+through the `lspeasy` bin.
+
+## Quick Start
+
+```
+lsproxy <namespace> <command> [args] [flags]
+lsproxy call <method> --params <json>
+```
+
+## Configuration
+
+**SessionOptions** (6 options — see references/config.md)
+
+## Quick Reference
+
+**apply:** `applyWorkspaceEdit` (Apply a WorkspaceEdit to disk and return what was changed), `applyTextEdits` (Apply text edits to a string, splicing in reverse offset order so earlier
+edits do not invalidate the offsets of later ones), `planWorkspaceEdit` (Normalize a WorkspaceEdit into an ordered list of changes without
+touching disk), `WorkspaceEdit`, `LspTextEdit`, `LspRange`, `LspPosition`, `AppliedChange` (A single change the apply pipeline performed, for reporting / dry-run output)
+**session:** `RefactorSession`
+**io:** `GlobalFlags`
+
+## References
+
+Load these on demand — do NOT read all at once:
+
+- When calling any function → read `references/functions.md` for full signatures, parameters, and return types
+- When using a class → read `references/classes.md` for properties, methods, and inheritance
+- When defining typed variables or function parameters → read `references/types.md`
+- When configuring options → read `references/config.md` for all settings and defaults
+
+## Links
+
+- [Repository](https://github.com/pradeepmouli/lspeasy)
+- Author: Pradeep Mouli <pmouli@mac.com> (https://github.com/pradeepmouli)

package/skills/lsproxy-cli/references/classes.md

@@ -0,0 +1,22 @@
+# Classes
+
+## session
+
+### `RefactorSession`
+```ts
+constructor(opts: SessionOptions): RefactorSession
+```
+**Methods:**
+- `start(): Promise<void>` — Spawn the server (or reuse a pre-built transport) and complete the LSP handshake.
+- `open(anchorFile: string): Promise<void>` — Notify the server that an anchor file is open.
+- `requestWithRetry<R>(run: () => Promise<R | null | undefined>): Promise<R | null>` — Run a request immediately and retry with exponential backoff while the
+server returns null (i.e. it is still indexing). Gives up after
+`indexWaitMs` total elapsed time and returns null.
+
+Initial retry delay: 250 ms, doubling each round, capped at 5 s per
+attempt. The first attempt is always immediate so fast servers pay no
+extra latency at all.
+- `takeCapturedEdits(): WorkspaceEdit[]` — Drain ALL edits pushed by the server via `workspace/applyEdit` since the
+last drain, in arrival order. Returns an empty array if none were pushed.
+Callers apply them in order so a multi-applyEdit command is fully honored.
+- `stop(): Promise<void>` — Shut down the client and kill the server process.

package/skills/lsproxy-cli/references/config.md

@@ -0,0 +1,46 @@
+# Configuration
+
+## SessionOptions
+
+### Properties
+
+#### serverCommand
+
+Server launch command, e.g. `typescript-language-server --stdio`. Required unless `transport` is supplied.
+
+**Type:** `string`
+
+#### root
+
+Absolute project root directory.
+
+**Type:** `string`
+
+**Required:** yes
+
+#### languageId
+
+languageId for textDocument/didOpen (e.g. 'typescript', 'rust').
+
+**Type:** `string`
+
+#### indexWaitMs
+
+Milliseconds to wait for the server to index before the first request.
+
+**Type:** `number`
+
+#### verbose
+
+Emit `[lsproxy] …` progress lines to stderr.
+
+**Type:** `boolean`
+
+#### transport
+
+Pre-built transport to use instead of spawning a server process.
+
+When supplied, `serverCommand` is ignored and no child process is spawned.
+Used by the proxy path to reuse all downstream session logic unchanged.
+
+**Type:** `Transport`

package/skills/lsproxy-cli/references/functions.md

@@ -0,0 +1,58 @@
+# Functions
+
+## apply
+
+### `applyWorkspaceEdit`
+Apply a WorkspaceEdit to disk and return what was changed.
+
+### `documentChanges` — sequential, order significant
+Per the LSP spec the `documentChanges` array order is SIGNIFICANT: each entry
+(text edit or resource op) is applied in the exact order the server emitted
+it. This is the only correct interpretation — e.g. `[rename old→new, textEdit
+on new]` requires the rename to run first so the edit can read `new`. (An
+earlier three-phase model hoisted all resource ops into separate passes,
+which silently reordered a server's ops and broke exactly that shape.)
+
+Because order is honored literally, a failure partway through `documentChanges`
+(e.g. a text edit keyed to a not-yet-created path) may leave earlier ops
+applied — that is inherent to respecting server-specified order.
+
+### `changes` map — unordered, transactional
+The `changes` map carries no resource ops and no defined ordering, so it is
+applied as a batch: every target is read and its new content computed in
+memory BEFORE any write. If a read fails the function throws before any write,
+so a failed edit never leaves the tree half-applied.
+```ts
+applyWorkspaceEdit(edit: WorkspaceEdit, guard?: BoundaryGuard): AppliedChange[]
+```
+**Parameters:**
+- `edit: WorkspaceEdit`
+- `guard: BoundaryGuard` (optional)
+**Returns:** `AppliedChange[]`
+
+### `applyTextEdits`
+Apply text edits to a string, splicing in reverse offset order so earlier
+edits do not invalidate the offsets of later ones.
+
+`lineStarts` is computed once from the original `text` and reused for both the
+sort and the splice loop. This is correct because edits apply in reverse
+offset order: a later splice never shifts the line map of an earlier (smaller)
+offset, so the original line map stays valid for every remaining edit.
+```ts
+applyTextEdits(text: string, edits: LspTextEdit[]): string
+```
+**Parameters:**
+- `text: string`
+- `edits: LspTextEdit[]`
+**Returns:** `string`
+
+### `planWorkspaceEdit`
+Normalize a WorkspaceEdit into an ordered list of changes without
+touching disk. Useful for `--dry-run` and `--json` reporting.
+```ts
+planWorkspaceEdit(edit: WorkspaceEdit, guard?: BoundaryGuard): AppliedChange[]
+```
+**Parameters:**
+- `edit: WorkspaceEdit`
+- `guard: BoundaryGuard` (optional)
+**Returns:** `AppliedChange[]`

package/skills/lsproxy-cli/references/types.md

@@ -0,0 +1,45 @@
+# Types & Enums
+
+## apply
+
+### `WorkspaceEdit`
+**Properties:**
+- `changes: Record<string, LspTextEdit[]>` (optional)
+- `documentChanges: DocumentChange[]` (optional)
+
+### `LspTextEdit`
+**Properties:**
+- `range: LspRange`
+- `newText: string`
+
+### `LspRange`
+**Properties:**
+- `start: LspPosition`
+- `end: LspPosition`
+
+### `LspPosition`
+**Properties:**
+- `line: number`
+- `character: number`
+
+### `AppliedChange`
+A single change the apply pipeline performed, for reporting / dry-run output.
+**Properties:**
+- `kind: "rename" | "create" | "delete" | "edit"`
+- `path: string`
+- `editCount: number` (optional) — For `edit`, the number of text edits applied.
+- `toPath: string` (optional) — For `rename`, the destination path.
+
+## io
+
+### `GlobalFlags`
+**Properties:**
+- `server: string`
+- `root: string`
+- `dryRun: boolean`
+- `json: boolean`
+- `verbose: boolean`
+- `waitMs: number`
+- `allowOutsideRoot: boolean`
+- `overwrite: boolean` — Permit move-file to replace an existing destination (default: OFF).
+- `noProxy: boolean` — Bypass the proxy daemon and connect directly to the language server.