plugin_api 1.0.0

[![Crates.io - boltpm](https://img.shields.io/crates/v/boltpm.svg)](https://crates.io/crates/boltpm)
[![Crates.io - plugin_api](https://img.shields.io/crates/v/plugin_api.svg)](https://crates.io/crates/plugin_api)

- [boltpm on crates.io](https://crates.io/crates/boltpm)
- [plugin_api on crates.io](https://crates.io/crates/plugin_api)

# BoltPM

BoltPM is a fast, modern, cross-platform NPM alternative written in Rust. It features a CLI, real-time GUI, private registry, and dynamic plugin system.

## Installation

### From crates.io (Recommended)
```bash
cargo install boltpm
```

### From source
```bash
git clone https://github.com/nom-nom-hub/boltpm.git
cd boltpm
cargo build --workspace
```

## Features
- CLI: install, remove, update, run, link, etc.
- GUI: Tauri desktop app with live logs, dependency tree, search, config, and dark mode
- Registry: self-hosted, token-auth, CORS, JSON index
- Plugins: dynamic hooks for install lifecycle

## Quick Start

### Using the installed binary
```bash
# Initialize a new project
boltpm init

# Install a package
boltpm install lodash

# Remove a package
boltpm remove lodash

# Update all packages
boltpm update

# Run a script
boltpm run build
```

### Building from source

### 1. Build All Components
```sh
cargo build --workspace
```

### 2. Run the Registry
```sh
cd registry
cargo run
# Registry runs at http://localhost:4000
```

### 3. Use the CLI
```sh
cd cli
cargo run -- init
cargo run -- install dep1
cargo run -- remove dep1
```

### 4. Run the GUI
```sh
cd gui
cargo tauri dev
```

## GUI Dark Mode
- Click the 🌙/☀️ button in the header to toggle dark mode.
- Your theme preference is remembered.
- ![Dark mode screenshot](docs/darkmode.png) <!-- Add screenshot here -->

## Usage Examples

### Basic Commands
```bash
# Initialize a new project
boltpm init

# Install a package
boltpm install lodash

# Remove a package
boltpm remove lodash

# Update all packages
boltpm update

# Run a script
boltpm run build

# List installed packages
boltpm list

# Search for packages
boltpm search react
```

### Advanced Usage
```bash
# Install with specific version
boltpm install lodash@4.17.21

# Install as dev dependency
boltpm install --dev jest

# Install globally
boltpm install -g typescript

# Publish a package to your registry
curl -X PUT -F "version=1.0.0" -F "description=My lib" -F "tarball=@package.tgz" http://localhost:4000/v1/mylib/

# Use plugins (place compiled .so/.dylib/.dll in .boltpm/plugins/)
# Plugins are called automatically on install/remove/update
```

## Troubleshooting & FAQ

- **Q: The GUI is blank or buttons don't work?**
  - A: Make sure you run `cargo tauri dev` in the `gui` directory and that the backend is built.
- **Q: Install fails with a network error?**
  - A: Ensure the registry is running at `http://localhost:4000`.
- **Q: Plugin not executing?**
  - A: Check that your plugin is in `.boltpm/plugins/` and built for your OS/arch.
- **Q: How do I clear the cache?**
  - A: Delete the `.boltpm/cache/` directory.

## Accessibility & UX Tips
- All navigation is keyboard accessible.
- Error messages are shown at the top of the GUI.
- Tooltips are available for all major actions.
- For best experience, keep your plugins stateless and your `package.json` valid.
- Dark mode is available for comfortable coding at night!

## Plugin System
- Plugins are dynamic libraries in `.boltpm/plugins/`.
- Hooks: `preinstall`, `postinstall`, `onError`.
- Example plugin logs the hook and package info.
- To develop a plugin:
  1. Implement the `run(ctx: PluginContext)` function.
  2. Build as `cdylib`.
  3. Place in `.boltpm/plugins/`.

## Error Handling & UX
- All errors print clear messages to the console and GUI.
- If a plugin fails, the `onError` hook is called.
- GUI shows logs, dependency tree, and config for troubleshooting.
- For best UX, keep plugins simple and stateless.

## Contributing
- PRs welcome! Run `cargo test --workspace` before submitting.
- See `dev.md` for architecture and roadmap.

## License
MIT