lsp-cli 0.1.1__tar.gz

lsp_cli-0.1.1/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.3
+Name: lsp-cli
+Version: 0.1.1
+Summary: A powerful command-line interface for the Language Server Agent Protocol (LSAP)
+Keywords: Language Server Protocol,LSP,CLI,Developer Tools,LSAP
+Author: observerw
+Author-email: observerw <wozluohd@gmail.com>
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Dist: anyio>=4.12.0
+Requires-Dist: asyncer>=0.0.12
+Requires-Dist: attrs>=25.4.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: platformdirs>=4.5.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: typer>=0.20.1
+Requires-Dist: uvicorn>=0.40.0
+Requires-Dist: litestar>=2.19.0
+Requires-Dist: xxhash>=3.6.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: lsp-client>=0.3.0
+Requires-Dist: lsap-sdk>=0.1.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# LSP CLI
+
+[![PyPI](https://img.shields.io/pypi/v/lsp-cli.svg)](https://pypi.org/project/lsp-cli/)
+[![Python](https://img.shields.io/badge/Python-3.13+-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+> **⚠️ Windows Temporary Not Supported**  
+> Due to implementation details, `lsp-cli` does not currently support Windows. Support for Windows will be added in the next version.
+
+A powerful command-line interface for the [**Language Server Agent Protocol (LSAP)**](https://github.com/lsp-client/LSAP). `lsp-cli` provides a bridge between traditional [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) servers and high-level agentic workflows, offering structured data access and a robust background server management system.
+
+Built on top of [lsp-client](https://github.com/lsp-client/lsp-client) and [LSAP](https://github.com/lsp-client/LSAP), this tool is designed for developers and AI agents who need reliable, fast, and structured access to language intelligence.
+
+## Key Features
+
+- **🤖 Built for Agents**: The CLI output is optimized for Coding Agents. By avoiding fancy TUI/UI elements and rich terminal formatting, it significantly reduces token consumption while maintaining high readability for LLMs.
+- **🚀 Instant Analysis**: Quickly get definitions, references, hover info, and completions from the terminal.
+- **🏢 Managed Server Lifecycle**: A background manager automatically handles language server processes, reusing them across requests for maximum performance.
+- **🧩 LSAP Integration**: Leverages the Language Server Agent Protocol for structured, agent-friendly responses with built-in pagination and text-based location finding.
+- **⚡ Async-First**: Built with `anyio` and `asyncer` for high-performance concurrent operations.
+
+## Supported Languages
+
+`lsp-cli` currently supports the following languages:
+
+| Language                    | Language Server              |
+| :-------------------------- | :--------------------------- |
+| **Python**                  | `basedpyright`               |
+| **Go**                      | `gopls`                      |
+| **Rust**                    | `rust-analyzer`              |
+| **TypeScript / JavaScript** | `typescript-language-server` |
+| **Deno**                    | `deno`                       |
+
+More supported languages coming very soon!
+
+```bash
+uv tool install --python 3.13 lsp-cli
+```
+
+## Quick Start
+
+The main entry point is the `lsp` command. It automatically detects the appropriate language server for your project.
+
+### Find Definition
+
+Find where a symbol is defined:
+
+```bash
+# Using line scope
+lsp definition --locate main.py:10
+
+# Using text search to locate the symbol
+lsp definition --locate "main.py@my_function<HERE>"
+
+# Find declaration instead of definition
+lsp definition --locate models.py:25 --decl
+```
+
+### Get Symbol Information
+
+Get detailed information about a symbol at a specific location:
+
+```bash
+# Get symbol info at line 15
+lsp symbol --locate main.py:15
+
+# Find and get symbol info
+lsp symbol --locate "utils.py@UserClass<HERE>"
+```
+
+### Find References
+
+Find all references to a symbol:
+
+```bash
+# Find references to a symbol at line 20
+lsp reference --locate models.py:20
+
+# Find references with text search
+lsp reference --locate "models.py@UserClass<HERE>"
+
+# Show more context lines around each reference
+lsp reference --locate app.py:10 --context-lines 5
+
+# Find implementations instead of references
+lsp reference --locate interface.py:15 --impl
+```
+
+### Search Workspace Symbols
+
+Search for symbols across the entire workspace by name:
+
+```bash
+# Search for symbols containing "MyClass"
+lsp search MyClass
+
+# Search in a specific workspace
+lsp search "UserModel" --workspace /path/to/project
+
+# Filter by symbol kind
+lsp search "test" --kind function --kind method
+
+# Limit results
+lsp search "Config" --max-items 10
+```
+
+### Get File Outline
+
+Get a hierarchical outline of symbols in a file:
+
+```bash
+# Get outline of main symbols (classes, functions, methods)
+lsp outline main.py
+
+# Include all symbols (variables, parameters, etc.)
+lsp outline utils.py --all
+```
+
+### Get Hover Information
+
+Get documentation and type information for a symbol:
+
+```bash
+# Get hover info at a specific line
+lsp hover --locate main.py:42
+
+# Find symbol and get hover info
+lsp hover --locate "models.py@process_data<HERE>"
+```
+
+## Commands
+
+| Command      | Description                                             |
+| ------------ | ------------------------------------------------------- |
+| `definition` | Find symbol definition, declaration, or type definition |
+| `hover`      | Get hover information (type info, documentation)        |
+| `reference`  | Find symbol references or implementations               |
+| `outline`    | Get a structured symbol outline for a file              |
+| `symbol`     | Get detailed symbol information at a specific location  |
+| `search`     | Search for symbols across the entire workspace by name  |
+| `rename`     | Rename a symbol across the workspace                    |
+| `server`     | Manage background LSP server processes                  |
+| `locate`     | Parse and verify a location string                      |
+
+## Server Management
+
+`lsp-cli` uses a **background manager process to keep language servers alive between command invocations**. This significantly reduces latency for repeated queries.
+
+```bash
+# List all running LSP servers
+lsp server list
+
+# Manually start a server for a path
+lsp server start .
+
+# Stop a server
+lsp server stop .
+```
+
+The manager starts automatically when you run any analysis command.
+
+## Usage Tips
+
+### Locating Symbols
+
+LSP CLI uses a unified `locate` string syntax (`-L` or `--locate`) to specify positions in your code. The format is `<file_path>[:<scope>][@<find>]`.
+
+1. **Line-based**: Specify a line number (1-based)
+
+   ```bash
+   lsp definition --locate main.py:42
+   ```
+
+2. **Range-based**: Specify a line range
+
+   ```bash
+   lsp symbol --locate utils.py:10,20
+   ```
+
+3. **Text-based**: Search for text with a cursor marker `<HERE>` or `<|>`
+
+   ```bash
+   lsp hover --locate "app.py@my_function<HERE>()"
+   ```
+
+4. **Symbol path**: Navigate using symbol hierarchy
+   ```bash
+   lsp definition --locate models.py:UserClass.get_name
+   ```
+
+### Working with Results
+
+Pagination for large result sets:
+
+```bash
+# Get first 50 results
+lsp search "config" --max-items 50
+
+# Get next page
+lsp search "config" --max-items 50 --start-index 50
+```
+
+### Debugging
+
+Enable debug mode to see detailed logs:
+
+```bash
+lsp --debug definition --locate main.py:10
+```
+
+## Configuration
+
+`lsp-cli` can be configured via environment variables or a `config.toml` file.
+
+- **Config File**: `~/.config/lsp-cli/config.toml` (on Linux) or `~/Library/Application Support/lsp-cli/config.toml` (on macOS).
+- **Environment Variables**: Prefix with `LSP_` (e.g., `LSP_LOG_LEVEL=DEBUG`).
+
+### Available Settings
+
+Create a `config.toml` file at the location above with the following options:
+
+```toml
+# config.toml
+
+# Enable debug mode (verbose logging)
+debug = false
+
+# Idle timeout for managed servers (in seconds)
+idle_timeout = 600
+
+# Log level: TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
+log_level = "INFO"
+
+# Default maximum items for paginated results (search, reference, etc.)
+# Set to null for no limit, or a number like 20
+default_max_items = 20
+
+# Default number of context lines for reference results
+default_context_lines = 2
+
+# Paths to ignore in search results (e.g., virtual environments, build directories)
+ignore_paths = [".git", "node_modules", "venv", ".venv", "__pycache__", "dist", "build"]
+```
+
+### Environment Variables
+
+All settings can be overridden via environment variables:
+
+```bash
+export LSP_DEBUG=true
+export LSP_LOG_LEVEL=DEBUG
+export LSP_DEFAULT_MAX_ITEMS=50
+```
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+- Development setup
+- Adding new CLI commands
+- Improving the server manager
+- Development workflow
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- [lsp-client](https://github.com/lsp-client/python-sdk): The underlying LSP client library.
+- [LSAP](https://github.com/lsp-client/LSAP): The Language Server Agent Protocol.
+- [lsprotocol](https://github.com/microsoft/lsprotocol): LSP type definitions.

lsp_cli-0.1.1/README.md

@@ -0,0 +1,272 @@
+# LSP CLI
+
+[![PyPI](https://img.shields.io/pypi/v/lsp-cli.svg)](https://pypi.org/project/lsp-cli/)
+[![Python](https://img.shields.io/badge/Python-3.13+-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+> **⚠️ Windows Temporary Not Supported**  
+> Due to implementation details, `lsp-cli` does not currently support Windows. Support for Windows will be added in the next version.
+
+A powerful command-line interface for the [**Language Server Agent Protocol (LSAP)**](https://github.com/lsp-client/LSAP). `lsp-cli` provides a bridge between traditional [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) servers and high-level agentic workflows, offering structured data access and a robust background server management system.
+
+Built on top of [lsp-client](https://github.com/lsp-client/lsp-client) and [LSAP](https://github.com/lsp-client/LSAP), this tool is designed for developers and AI agents who need reliable, fast, and structured access to language intelligence.
+
+## Key Features
+
+- **🤖 Built for Agents**: The CLI output is optimized for Coding Agents. By avoiding fancy TUI/UI elements and rich terminal formatting, it significantly reduces token consumption while maintaining high readability for LLMs.
+- **🚀 Instant Analysis**: Quickly get definitions, references, hover info, and completions from the terminal.
+- **🏢 Managed Server Lifecycle**: A background manager automatically handles language server processes, reusing them across requests for maximum performance.
+- **🧩 LSAP Integration**: Leverages the Language Server Agent Protocol for structured, agent-friendly responses with built-in pagination and text-based location finding.
+- **⚡ Async-First**: Built with `anyio` and `asyncer` for high-performance concurrent operations.
+
+## Supported Languages
+
+`lsp-cli` currently supports the following languages:
+
+| Language                    | Language Server              |
+| :-------------------------- | :--------------------------- |
+| **Python**                  | `basedpyright`               |
+| **Go**                      | `gopls`                      |
+| **Rust**                    | `rust-analyzer`              |
+| **TypeScript / JavaScript** | `typescript-language-server` |
+| **Deno**                    | `deno`                       |
+
+More supported languages coming very soon!
+
+```bash
+uv tool install --python 3.13 lsp-cli
+```
+
+## Quick Start
+
+The main entry point is the `lsp` command. It automatically detects the appropriate language server for your project.
+
+### Find Definition
+
+Find where a symbol is defined:
+
+```bash
+# Using line scope
+lsp definition --locate main.py:10
+
+# Using text search to locate the symbol
+lsp definition --locate "main.py@my_function<HERE>"
+
+# Find declaration instead of definition
+lsp definition --locate models.py:25 --decl
+```
+
+### Get Symbol Information
+
+Get detailed information about a symbol at a specific location:
+
+```bash
+# Get symbol info at line 15
+lsp symbol --locate main.py:15
+
+# Find and get symbol info
+lsp symbol --locate "utils.py@UserClass<HERE>"
+```
+
+### Find References
+
+Find all references to a symbol:
+
+```bash
+# Find references to a symbol at line 20
+lsp reference --locate models.py:20
+
+# Find references with text search
+lsp reference --locate "models.py@UserClass<HERE>"
+
+# Show more context lines around each reference
+lsp reference --locate app.py:10 --context-lines 5
+
+# Find implementations instead of references
+lsp reference --locate interface.py:15 --impl
+```
+
+### Search Workspace Symbols
+
+Search for symbols across the entire workspace by name:
+
+```bash
+# Search for symbols containing "MyClass"
+lsp search MyClass
+
+# Search in a specific workspace
+lsp search "UserModel" --workspace /path/to/project
+
+# Filter by symbol kind
+lsp search "test" --kind function --kind method
+
+# Limit results
+lsp search "Config" --max-items 10
+```
+
+### Get File Outline
+
+Get a hierarchical outline of symbols in a file:
+
+```bash
+# Get outline of main symbols (classes, functions, methods)
+lsp outline main.py
+
+# Include all symbols (variables, parameters, etc.)
+lsp outline utils.py --all
+```
+
+### Get Hover Information
+
+Get documentation and type information for a symbol:
+
+```bash
+# Get hover info at a specific line
+lsp hover --locate main.py:42
+
+# Find symbol and get hover info
+lsp hover --locate "models.py@process_data<HERE>"
+```
+
+## Commands
+
+| Command      | Description                                             |
+| ------------ | ------------------------------------------------------- |
+| `definition` | Find symbol definition, declaration, or type definition |
+| `hover`      | Get hover information (type info, documentation)        |
+| `reference`  | Find symbol references or implementations               |
+| `outline`    | Get a structured symbol outline for a file              |
+| `symbol`     | Get detailed symbol information at a specific location  |
+| `search`     | Search for symbols across the entire workspace by name  |
+| `rename`     | Rename a symbol across the workspace                    |
+| `server`     | Manage background LSP server processes                  |
+| `locate`     | Parse and verify a location string                      |
+
+## Server Management
+
+`lsp-cli` uses a **background manager process to keep language servers alive between command invocations**. This significantly reduces latency for repeated queries.
+
+```bash
+# List all running LSP servers
+lsp server list
+
+# Manually start a server for a path
+lsp server start .
+
+# Stop a server
+lsp server stop .
+```
+
+The manager starts automatically when you run any analysis command.
+
+## Usage Tips
+
+### Locating Symbols
+
+LSP CLI uses a unified `locate` string syntax (`-L` or `--locate`) to specify positions in your code. The format is `<file_path>[:<scope>][@<find>]`.
+
+1. **Line-based**: Specify a line number (1-based)
+
+   ```bash
+   lsp definition --locate main.py:42
+   ```
+
+2. **Range-based**: Specify a line range
+
+   ```bash
+   lsp symbol --locate utils.py:10,20
+   ```
+
+3. **Text-based**: Search for text with a cursor marker `<HERE>` or `<|>`
+
+   ```bash
+   lsp hover --locate "app.py@my_function<HERE>()"
+   ```
+
+4. **Symbol path**: Navigate using symbol hierarchy
+   ```bash
+   lsp definition --locate models.py:UserClass.get_name
+   ```
+
+### Working with Results
+
+Pagination for large result sets:
+
+```bash
+# Get first 50 results
+lsp search "config" --max-items 50
+
+# Get next page
+lsp search "config" --max-items 50 --start-index 50
+```
+
+### Debugging
+
+Enable debug mode to see detailed logs:
+
+```bash
+lsp --debug definition --locate main.py:10
+```
+
+## Configuration
+
+`lsp-cli` can be configured via environment variables or a `config.toml` file.
+
+- **Config File**: `~/.config/lsp-cli/config.toml` (on Linux) or `~/Library/Application Support/lsp-cli/config.toml` (on macOS).
+- **Environment Variables**: Prefix with `LSP_` (e.g., `LSP_LOG_LEVEL=DEBUG`).
+
+### Available Settings
+
+Create a `config.toml` file at the location above with the following options:
+
+```toml
+# config.toml
+
+# Enable debug mode (verbose logging)
+debug = false
+
+# Idle timeout for managed servers (in seconds)
+idle_timeout = 600
+
+# Log level: TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
+log_level = "INFO"
+
+# Default maximum items for paginated results (search, reference, etc.)
+# Set to null for no limit, or a number like 20
+default_max_items = 20
+
+# Default number of context lines for reference results
+default_context_lines = 2
+
+# Paths to ignore in search results (e.g., virtual environments, build directories)
+ignore_paths = [".git", "node_modules", "venv", ".venv", "__pycache__", "dist", "build"]
+```
+
+### Environment Variables
+
+All settings can be overridden via environment variables:
+
+```bash
+export LSP_DEBUG=true
+export LSP_LOG_LEVEL=DEBUG
+export LSP_DEFAULT_MAX_ITEMS=50
+```
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+- Development setup
+- Adding new CLI commands
+- Improving the server manager
+- Development workflow
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- [lsp-client](https://github.com/lsp-client/python-sdk): The underlying LSP client library.
+- [LSAP](https://github.com/lsp-client/LSAP): The Language Server Agent Protocol.
+- [lsprotocol](https://github.com/microsoft/lsprotocol): LSP type definitions.

lsp_cli-0.1.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "lsp-cli"
+version = "0.1.1"
+description = "A powerful command-line interface for the Language Server Agent Protocol (LSAP)"
+readme = "README.md"
+authors = [{ name = "observerw", email = "wozluohd@gmail.com" }]
+requires-python = ">=3.13"
+keywords = ["Language Server Protocol", "LSP", "CLI", "Developer Tools", "LSAP"]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+]
+dependencies = [
+    "anyio>=4.12.0",
+    "asyncer>=0.0.12",
+    "attrs>=25.4.0",
+    "httpx>=0.28.1",
+    "loguru>=0.7.3",
+    "platformdirs>=4.5.1",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.12.0",
+    "typer>=0.20.1",
+    "uvicorn>=0.40.0",
+    "litestar>=2.19.0",
+    "xxhash>=3.6.0",
+    "tenacity>=9.1.2",
+    "lsp-client>=0.3.0",
+    "lsap-sdk>=0.1.0",
+]
+
+[project.scripts]
+lsp = "lsp_cli.__main__:run"
+
+[build-system]
+requires = ["uv_build>=0.9.9,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.14.10",
+    "ty>=0.0.8",
+]
+
+[tool.pytest.ini_options]
+norecursedirs = ["references"]

lsp_cli-0.1.1/src/lsp_cli/__main__.py

@@ -0,0 +1,65 @@
+import logging
+import sys
+
+import typer
+
+from lsp_cli.cli import (
+    definition,
+    hover,
+    locate,
+    outline,
+    reference,
+    rename,
+    search,
+    symbol,
+)
+from lsp_cli.cli.main import main_callback
+from lsp_cli.cli.shared import get_msg
+from lsp_cli.server import app as server_app
+from lsp_cli.settings import settings
+
+app = typer.Typer(
+    help="LSP CLI: A command-line tool for interacting with Language Server Protocol (LSP) features.",
+    context_settings={
+        "help_option_names": ["-h", "--help"],
+        "max_content_width": 1000,
+        "terminal_width": 1000,
+    },
+    add_completion=False,
+    rich_markup_mode=None,
+    pretty_exceptions_enable=False,
+)
+
+# Set callback
+app.callback(invoke_without_command=True)(main_callback)
+
+# Add sub-typers
+app.add_typer(server_app)
+app.add_typer(rename.app)
+app.add_typer(definition.app)
+app.add_typer(hover.app)
+app.add_typer(locate.app)
+app.add_typer(reference.app)
+app.add_typer(outline.app)
+app.add_typer(symbol.app)
+app.add_typer(search.app)
+
+
+def run():
+    # Suppress httpx INFO logs in CLI (unless debug mode)
+    if not settings.debug:
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+
+    try:
+        app()
+    except (typer.Exit, typer.Abort):
+        pass
+    except Exception as e:
+        if settings.debug:
+            raise e
+        print(f"Error: {get_msg(e)}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run()