# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

Official native plugins for the [Owlry](https://somegit.dev/Owlibou/owlry) application launcher. Each plugin is compiled as a shared library (`.so`) and loaded by the `owlry-core` daemon at runtime via the ABI-stable plugin interface.

## Build & Development Commands

```bash
just build          # Debug build (all plugins)
just release        # Release build (all plugins, LTO + stripped)
just plugin <name>  # Build specific plugin release (e.g., just plugin calculator)
just plugins        # Alias for release build of all plugins
just check          # cargo check + clippy
just test           # Run tests
just fmt            # Format code
just show-versions  # List all plugin crate versions
just install-local  # Build release + install all .so to /usr/lib/owlry/plugins/

# Build a specific plugin manually
cargo build -p owlry-plugin-calculator --release
# Output: target/release/libowlry_plugin_calculator.so

# Bump versions
just bump-crate owlry-plugin-weather 0.5.0  # Bump specific plugin
just bump-all 0.5.0                          # Bump all plugins

# Tagging convention: every changed crate gets its own tag
# Format: {crate-name}-v{version}
# Examples:
#   owlry-plugin-bookmarks-v1.0.1
#   owlry-plugin-calculator-v1.0.1
#
# IMPORTANT: After bumping, tag EVERY changed plugin crate individually.
# Unchanged plugins don't need new tags.
#
# Plugin API dependency uses a git tag from the core repo:
#   owlry-plugin-api = { git = "...", tag = "plugin-api-v1.0.1" }
# Update this tag reference when the core repo bumps plugin-api.
```

## Workspace Structure

```
owlry-plugins/
├── Cargo.toml                          # Workspace root
├── crates/
│   ├── owlry-plugin-bookmarks/         # Firefox/Chrome bookmarks
│   ├── owlry-plugin-calculator/        # Math expression evaluation
│   ├── owlry-plugin-clipboard/         # Clipboard history (cliphist)
│   ├── owlry-plugin-emoji/             # Emoji picker
│   ├── owlry-plugin-filesearch/        # File search (fd/mlocate)
│   ├── owlry-plugin-media/             # Media player controls (widget)
│   ├── owlry-plugin-pomodoro/          # Pomodoro timer (widget)
│   ├── owlry-plugin-scripts/           # User script runner
│   ├── owlry-plugin-ssh/               # SSH host picker
│   ├── owlry-plugin-system/            # System actions (shutdown, reboot, etc.)
│   ├── owlry-plugin-systemd/           # systemd user unit control
│   ├── owlry-plugin-weather/           # Weather display (widget)
│   └── owlry-plugin-websearch/         # Web search providers
├── aur/                                # AUR PKGBUILDs for all plugins + meta-packages
└── docs/                               # Plugin development documentation
```

## Plugin API Dependency

All plugins depend on `owlry-plugin-api` from the core repo. Currently referenced as a local path (for development), will be a git dependency for releases:

```toml
# In each plugin's Cargo.toml
[dependencies]
owlry-plugin-api = { path = "/path/to/owlry/crates/owlry-plugin-api" }
```

Each plugin crate is compiled as `cdylib`:

```toml
[lib]
crate-type = ["cdylib"]
```

## Plugin Architecture

Every plugin exports a single C-ABI function:

```rust
#[no_mangle]
pub extern "C" fn owlry_plugin_vtable() -> &'static PluginVTable
```

The `PluginVTable` provides function pointers for:
- `info()` - Plugin metadata (name, version, description)
- `providers()` - List of providers the plugin offers (id, name, prefix, icon, position, priority)
- `provider_init(id)` - Initialize a provider instance
- `provider_refresh(handle)` - Populate/reload items (static providers)
- `provider_query(handle, query)` - Search items (dynamic providers)
- `provider_drop(handle)` - Clean up provider instance

All types cross the ABI boundary using `abi_stable` crate types (`RVec`, `RStr`, `RString`, etc.).

### Provider Categories

| Category | Plugins | Behavior |
|----------|---------|----------|
| Static | bookmarks, clipboard, emoji, scripts, ssh, system, systemd | `refresh()` populates items at startup; `query()` filters them |
| Dynamic | calculator, websearch, filesearch | `query()` generates results per keystroke |
| Widget | weather, media, pomodoro | Displayed at top of results via `position: Widget` |

### Submenu System

Plugins can return items with `SUBMENU:plugin_id:data` as the command. When the user selects such an item, the daemon calls `provider_query(handle, "?SUBMENU:data")` to get contextual action items (e.g., systemd service start/stop/restart).

## Adding a New Plugin

1. Create crate: `cargo init --lib crates/owlry-plugin-myplugin`
2. Set `crate-type = ["cdylib"]` in Cargo.toml
3. Add `owlry-plugin-api` and `abi_stable` dependencies
4. Implement `owlry_plugin_vtable()` returning a static `PluginVTable`
5. Add the crate to workspace members in root `Cargo.toml`
6. Register the provider ID prefix in the core repo's `ProviderFilter` if desired

See `docs/PLUGIN_DEVELOPMENT.md` for detailed guidance.

## AUR Packaging

The `aur/` directory contains PKGBUILDs for:

| Category | Packages |
|----------|----------|
| Plugins (13) | `owlry-plugin-{bookmarks,calculator,clipboard,emoji,filesearch,media,pomodoro,scripts,ssh,system,systemd,weather,websearch}` |
| Meta-bundles | `owlry-meta-essentials`, `owlry-meta-widgets`, `owlry-meta-tools`, `owlry-meta-full` |

Plugin `.so` files are installed to `/usr/lib/owlry/plugins/` with consistent naming: `libowlry_plugin_*.so`.

All plugin PKGBUILDs include `.install` files that clean up old plugin files on upgrade.

## Testing

```bash
# Run all plugin tests
just test

# Test a specific plugin
cargo test -p owlry-plugin-calculator
```

Most plugins are tested via their `query()` and `refresh()` implementations. The `owlry-plugin-api` crate provides the types needed for test assertions.

## External Dependencies

Some plugins require external tools at runtime:

| Plugin | Dependencies |
|--------|-------------|
| clipboard | `cliphist`, `wl-clipboard` |
| filesearch | `fd` or `mlocate` |
| emoji | `wl-clipboard`, `noto-fonts-emoji` |
| systemd | `systemd` (user services) |
| bookmarks | None (bundled SQLite via `rusqlite`) |
| media | D-Bus (MPRIS) |
| websearch | `xdg-open` or configured browser |

## Key Patterns

- All plugins are `cdylib` crates producing `.so` files
- ABI stability via `abi_stable` crate - never break the vtable contract
- Plugin API v3: `ProviderInfo` includes `position` (Normal/Widget) and `priority` fields
- Plugins have independent versions from the core (currently 0.4.x)
- No direct dependency on GTK or UI code - plugins are pure data providers