emacs-lsp-proxy 0.7.2 → 0.8.0

package/README.md

@@ -32,6 +32,34 @@ npm install -g emacs-lsp-proxy
 
 This will automatically install the appropriate binary for your platform (Linux x64/ARM64, macOS x64/ARM64, Windows x64) and make the `emacs-lsp-proxy` command available in your PATH.
 
+### Nix Flake
+If you use Nix, you can build an optimized binary directly from the repository:
+
+```bash
+# Build and run directly
+nix run github:jadestrong/lsp-proxy
+
+# Build and install to your profile
+nix profile install github:jadestrong/lsp-proxy
+
+# Or build locally if you've cloned the repo
+nix build
+./result/bin/emacs-lsp-proxy --version
+```
+
+You can add it as a flake input in your NixOS/home-manager configuration:
+
+```nix
+# flake.nix
+{
+  inputs.lsp-proxy.url = "github:jadestrong/lsp-proxy";
+
+  outputs = { self, nixpkgs, lsp-proxy, ... }: {
+    # Then use lsp-proxy.packages.${system}.default wherever you need it
+  };
+}
+```
+
 ### Manually
 Before installing LSP-PROXY manually, you should install rust and cargo first.
 
@@ -743,6 +771,166 @@ For specialized setups, you can extend the language mapping:
 | Wrong language server started | Check `lsp-proxy-org-babel-language-map` for correct mapping |
 | Edit buffer not getting LSP | Verify `lsp-proxy-org-edit-special-enable-lsp` is `t` |
 
+## Remote Development
+
+LSP-Proxy supports transparent remote development over SSH via Emacs TRAMP. When you open a TRAMP file, the local lsp-proxy process checks whether a compatible binary exists on the remote host, starts a remote server process, and routes all LSP traffic through the SSH tunnel. Binary deployment is controlled by `lsp-proxy-remote-deploy-mode` — either manually on demand or automatically in the background.
+
+### How It Works
+
+1. You open a file with a TRAMP path (e.g., `/ssh:myserver:/home/user/project/main.rs`)
+2. lsp-proxy detects the `/ssh:` prefix and establishes an SSH ControlMaster connection
+3. It checks whether `emacs-lsp-proxy` is available in the remote PATH; if the version matches, it is used directly without uploading any file
+4. If the global command is absent or has a version mismatch, lsp-proxy checks the fixed deploy path (`lsp-proxy-remote-binary-path`). If neither location has a matching binary, deployment is triggered according to `lsp-proxy-remote-deploy-mode` (see [Binary Deployment](#binary-deployment))
+5. The remote binary is started with `--remote-server`; LSP traffic is forwarded through the tunnel
+6. From Emacs's perspective, everything works the same as a local buffer
+
+### Supported TRAMP Methods
+
+| TRAMP path form | Description |
+|---|---|
+| `/ssh:host:/path` | SSH config alias (user resolved via `~/.ssh/config`) |
+| `/ssh:user@host:/path` | Explicit username |
+| `/ssh:user@host#port:/path` | Custom SSH port |
+| `/rpc:user@host:/path` | RPC tunnel (alternative to ssh method) |
+
+### Prerequisites
+
+- SSH access to the remote host (password-less key auth recommended)
+- The local `emacs-lsp-proxy` binary must be compatible with the remote host's architecture (Linux x86-64 or ARM64)
+- The remote user needs write permission to the deploy directory (default: `~/.cache/emacs/lsp-proxy/`)
+
+### Basic Usage
+
+No special configuration is required. Enable `lsp-proxy-mode` normally, then open any TRAMP file:
+
+```elisp
+;; In your init file — same hook as local files
+(add-hook 'typescript-ts-mode-hook #'lsp-proxy-mode)
+```
+
+```elisp
+;; Open a remote file — lsp-proxy-mode activates automatically
+(find-file "/ssh:myserver:/home/user/project/main.rs")
+```
+
+lsp-proxy handles binary deployment and tunnel setup on first access. Subsequent files on the same host reuse the existing SSH connection.
+
+### Customization
+
+```elisp
+;; Change where the binary is deployed on the remote host
+;; Default: "~/.cache/emacs/lsp-proxy/emacs-lsp-proxy"
+(setq lsp-proxy-remote-binary-path "/opt/tools/emacs-lsp-proxy")
+
+;; Deploy mode: 'manual (default) or 'auto
+(setq lsp-proxy-remote-deploy-mode 'manual)
+```
+
+### Binary Deployment
+
+When the binary check fails (missing or version mismatch on both the global command and the deploy path), lsp-proxy behaves according to `lsp-proxy-remote-deploy-mode`.
+
+#### `manual` (default)
+
+lsp-proxy prints a hint in the minibuffer and waits for you to act:
+
+```text
+[lsp-proxy] Remote binary unavailable on myserver (…). Run M-x lsp-proxy-remote-deploy to deploy v0.7.2 to ~/.cache/…
+```
+
+Run `M-x lsp-proxy-remote-deploy` to open the `*lsp-proxy-deploy*` buffer. It shows the check result for both locations, then asks for confirmation before uploading:
+
+```text
+Deploy log — myserver  [manual]  (started 2026-05-19 10:30:00)
+------------------------------------------------------------
+
+[10:30:00] Checking remote binary...
+
+[10:30:01] Local version : 0.7.2
+[10:30:01] Deploy path   : ~/.cache/emacs/lsp-proxy/emacs-lsp-proxy
+
+[10:30:01] Global command (emacs-lsp-proxy): ✗ not found in PATH
+[10:30:01] Deploy path   (~/.cache/…):       ✗ not found
+
+[10:30:01] Binary not available or outdated. Deploy required.
+```
+
+Confirm the `[lsp-proxy] Deploy v0.7.2 to myserver?` prompt and the upload begins, with each step appended to the same buffer. Re-open the remote file once the deploy succeeds.
+
+#### `auto`
+
+lsp-proxy starts the upload immediately as soon as the check fails, streaming each step to the `*lsp-proxy-deploy*` buffer so you can follow along without doing anything:
+
+```text
+Deploy log — myserver  [auto]  (started 2026-05-19 10:30:00)
+------------------------------------------------------------
+
+[10:30:00] Binary unavailable (…). Starting automatic deploy of v0.7.2...
+[10:30:00] Target path: ~/.cache/emacs/lsp-proxy/emacs-lsp-proxy
+[10:30:00] Starting upload...
+[10:30:01] Checking global emacs-lsp-proxy on remote (need v0.7.2)...
+[10:30:01] Global emacs-lsp-proxy not found in remote PATH.
+[10:30:01] Checking ~/.cache/emacs/lsp-proxy/emacs-lsp-proxy...
+[10:30:01] Uploading /usr/local/bin/emacs-lsp-proxy (8388608 bytes)...
+[10:30:04] Upload complete, verifying...
+[10:30:04] ✓ Deploy succeeded. Binary: ~/.cache/emacs/lsp-proxy/emacs-lsp-proxy
+```
+
+Re-open the remote file once the deploy completes.
+
+#### `M-x lsp-proxy-remote-deploy`
+
+This command is always available regardless of the deploy mode. It runs the full check-and-deploy flow interactively, defaulting to the host that most recently requested a deploy. Use it to re-deploy after a version upgrade or to recover from a failed auto-deploy.
+
+### Diagnostics
+
+**Connection status** — run `M-x lsp-proxy-doctor` and check the **Remote Connection Status** section:
+
+| Field | Meaning |
+|---|---|
+| `Binary Path` | Command or path actually used (`emacs-lsp-proxy` if the global command was selected, otherwise the deploy path) |
+| `Deploy Status` | `deployed`, `missing`, `version_mismatch`, or `unknown` |
+| `Local Version` | Version of your local lsp-proxy binary |
+| `Remote Version` | Version reported by the remote binary |
+
+**Check the remote binary manually** — verify which binary is in use and its version:
+
+```bash
+# Global command (preferred when available)
+ssh myserver 'emacs-lsp-proxy --version'
+
+# Deployed binary at the default path
+ssh myserver '~/.cache/emacs/lsp-proxy/emacs-lsp-proxy --version'
+```
+
+**View the remote log** — each server start creates a new timestamped log file next to the binary (`~/.cache/emacs/lsp-proxy/remote-server-YYYYMMDD-HHMMSS.log`). First set the log level so output is written, then open the remote file to trigger a fresh start:
+
+```elisp
+(setq lsp-proxy-log-level 2)
+```
+
+```bash
+# Print the latest log
+ssh myserver 'ls -t ~/.cache/emacs/lsp-proxy/remote-server-*.log | head -1 | xargs cat'
+
+# Follow in real time while reproducing the issue
+ssh myserver 'ls -t ~/.cache/emacs/lsp-proxy/remote-server-*.log | head -1 | xargs tail -f'
+
+# Clean up old logs, keeping the 5 most recent
+ssh myserver 'ls -t ~/.cache/emacs/lsp-proxy/remote-server-*.log | tail -n +6 | xargs rm -f'
+```
+
+### Troubleshooting
+
+| Issue | Solution |
+|---|---|
+| Remote binary missing, no prompt shown | Check `lsp-proxy-remote-deploy-mode`; in `manual` mode the hint appears in the minibuffer — run `M-x lsp-proxy-remote-deploy` |
+| Deploy fails with permission error | Ensure the remote directory is writable; set `lsp-proxy-remote-binary-path` to a writable path |
+| Binary architecture mismatch | Cross-platform deploy is not supported; the local binary must match the remote OS/arch |
+| SSH connection times out | Configure `ServerAliveInterval` / `ServerAliveCountMax` in `~/.ssh/config` |
+| Remote LSP not starting | Set `lsp-proxy-log-level` to `2`, reopen the file, check the log for SSH/deploy errors |
+| Features stop working after reconnect | Run `M-x lsp-proxy-restart` to re-establish the remote session |
+
 ## Acknowledgements
 Thanks to [Helix](https://github.com/helix-editor/helix), the architecture of Lsp-Proxy Server is entirely based on Helix's implementation. Language configuration and communication with different language servers are all dependent on Helix. As a Rust beginner, I've gained a lot from this approach during the implementation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emacs-lsp-proxy",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "scripts": {
     "postinstall": "node ./install.js"
   },
@@ -20,11 +20,11 @@
   ],
   "author": "jadestrong",
   "optionalDependencies": {
-    "@emacs-lsp-proxy/darwin-x64": "0.7.2",
-    "@emacs-lsp-proxy/darwin-arm64": "0.7.2",
-    "@emacs-lsp-proxy/linux-x64": "0.7.2",
-    "@emacs-lsp-proxy/linux-arm64": "0.7.2",
-    "@emacs-lsp-proxy/win32-x64": "0.7.2"
+    "@emacs-lsp-proxy/darwin-x64": "0.8.0",
+    "@emacs-lsp-proxy/darwin-arm64": "0.8.0",
+    "@emacs-lsp-proxy/linux-x64": "0.8.0",
+    "@emacs-lsp-proxy/linux-arm64": "0.8.0",
+    "@emacs-lsp-proxy/win32-x64": "0.8.0"
   },
   "license": "ISC",
   "description": "An LSP client for Emacs implemented in Rust."