Harper

Harper is a JetBrains IDE plugin that integrates the Harper Language Server for grammar and spell checking directly into your development environment.

Features

• 🚀 Language Server Protocol (LSP) Integration: Seamless integration with Harper Language Server
• 📦 Automatic Server Management: Downloads and manages the Harper language server binary automatically
• 🔄 Auto-Updates: Checks for and downloads newer versions of the language server
• ⚙️ Project Settings: Configurable settings per project
• 📝 Real-time Checking: Grammar and spell checking as you type
• 🎯 Multi-Platform Support: Works on macOS, Linux, and Windows

Installation

From JetBrains Marketplace (Coming Soon)

1. Open your JetBrains IDE (IntelliJ IDEA, PyCharm, WebStorm, etc.)
2. Go to Settings/Preferences → Plugins → Marketplace
3. Search for "Harper"
4. Click Install

From Source

1. Clone this repository:

   git clone https://github.com/yourusername/harper.git
   cd harper

2. Build the plugin:

   ./gradlew buildPlugin

3. Install the plugin from disk:

   • Open your JetBrains IDE
   • Go to Settings/Preferences → Plugins → ⚙️ → Install Plugin from Disk...
   • Select the built plugin ZIP from build/distributions/harper-1.0-SNAPSHOT.zip

Usage

First Time Setup

When you first open a project after installing Harper, the plugin will:

1. Automatically download the Harper language server binary
2. Extract and configure it in your system's application data directory
3. Start the language server in the background

The language server binary is stored in:

• macOS: ~/Library/Application Support/Harper/language-server/<version>/
• Linux: ~/.local/share/Harper/language-server/<version>/
• Windows: %LOCALAPPDATA%\Harper\language-server\<version>\

Configuration

Access Harper settings via:

• Settings/Preferences → Tools → Harper (or search for "Harper" in settings)

Manual Server Restart

If needed, you can restart the Harper language server from the LSP console or by restarting the IDE.

Development

Prerequisites

• JDK 21 or higher
• Gradle 8.x (wrapper included)
• IntelliJ IDEA 2025.2.4 or newer (for development)

Building from Source

# Clone the repository
git clone https://github.com/yourusername/harper.git
cd harper

# Build the project
./gradlew build

# Run the plugin in a sandbox IDE
./gradlew runIde

# Run tests
./gradlew test

Project Structure

harper/
├── src/
│   └── main/
│       ├── kotlin/
│       │   └── im/cheng/harper/
│       │       ├── lsp/              # LSP integration
│       │       ├── services/         # Services and utilities
│       │       └── ui/               # UI components
│       └── resources/
│           ├── icons/                # Plugin icons
│           ├── messages/             # Localization bundles
│           └── META-INF/
│               └── plugin.xml        # Plugin configuration
├── build.gradle.kts                  # Build configuration
└── README.md

Key Components

• HarperLspServerSupportProvider: Main LSP server provider implementation
• HarperServiceSettings: Project-level settings management
• LanguageServerDownloader: Handles automatic download and updates of the Harper LSP server
• HarperSettingsConfigurable: UI for plugin configuration

Technologies Used

• Kotlin: Primary programming language
• IntelliJ Platform SDK: Plugin framework
• LSP4J: Language Server Protocol support
• Gradle: Build system
• Apache Commons Compress: Archive extraction
• AppDirs: Cross-platform application directory management

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Follow Kotlin coding conventions
• Use meaningful variable and function names
• Add KDoc comments for public APIs
• Keep functions focused and concise

Troubleshooting

Language Server Not Starting

If the Harper language server fails to start:

1. Check the IDE logs: Help → Show Log in Finder/Explorer
2. Look for Harper-related errors
3. Verify the language server binary has execute permissions:

   # macOS/Linux
   chmod +x ~/Library/Application\ Support/Harper/language-server/*/harper-ls

4. Try manually restarting the server from the LSP console

Download Issues

If the automatic download fails:

1. Check your internet connection
2. Verify firewall settings allow downloads from GitHub releases
3. Check available disk space
4. Review error messages in the IDE's Event Log

Permission Errors

If you encounter permission errors (error=13):

# macOS/Linux - make the binary executable
chmod +x ~/Library/Application\ Support/Harper/language-server/*/harper-ls

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Harper Language Server - The underlying grammar and spell checker
• JetBrains - For the excellent IntelliJ Platform SDK
• Contributors and users of this plugin

Links

• Harper Language Server
• JetBrains Plugin Development
• Language Server Protocol

Support

If you encounter any issues or have questions:

• 📫 Open an issue on GitHub Issues
• 💬 Check existing issues for solutions
• 📧 Contact: [your-email@example.com]

---

Note: This plugin is under active development. Features and APIs may change between versions.