# ryo-plugin-api

[![crates.io](https://img.shields.io/crates/v/ryo-plugin-api.svg)](https://crates.io/crates/ryo-plugin-api)
[![docs.rs](https://docs.rs/ryo-plugin-api/badge.svg)](https://docs.rs/ryo-plugin-api)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)

> **Status:** experimental. APIs may change in v0.x.
> Part of the [ryo](https://github.com/ynishi/ryo-rs) workspace —
> AST-centric Rust programming for AI agents.

WebAssembly Interface Types for ryo mutation plugins. WIT-generated Rust
types that define the host ↔ guest contract: plugins act as "Definition
Providers" supplying mutation metadata and transformation logic.

## Install

```sh
cargo add ryo-plugin-api
```

## Quickstart

For plugin authors (guest side):

```rust,ignore
use ryo_plugin_api::*;

wit_bindgen::generate!({
    world: "mutation-plugin",
    path: "../../wit",
    exports: {
        "ryo:transform/mutation": MyMutation,
    }
});

struct MyMutation;

impl exports::ryo::transform::mutation::Guest for MyMutation {
    fn get_manifest() -> MutationManifest {
        MutationManifest {
            api_version: CURRENT_API_VERSION,
            name: "bool-simplify".into(),
            description: "Simplify boolean comparisons".into(),
            category: MutationCategory::Idiom,
            tier: 1,
            pattern: "...".into(),
            transform: TransformDef::Template("{{var}}".into()),
        }
    }
    // ... get_pattern_source(), execute_transform(), ...
}
```

## API Summary

| Item | Purpose |
|---|---|
| `MutationManifest` | Plugin metadata returned from `get-manifest()` |
| `MutationCategory` | Idiom / Refactor / Generate / Custom |
| `TransformDef` | Template-based or WASM-executed transforms |
| `MatchResult` / `Capture` / `NodeKind` | Pattern-match payloads |
| `TextEdit` | Replacement instructions returned to host |
| `TransformContext` / `TypeHint` | Per-call context information |
| `TransformError` | Plugin-side error reporting |
| `CURRENT_API_VERSION` | Version constant for compatibility check |

## Status

**Experimental.** WIT definitions and plugin loader contract are evolving.
Production-quality stability is deferred to v1.0.

## License

Licensed under either of [Apache-2.0](https://github.com/ynishi/ryo-rs/blob/main/LICENSE-APACHE)
or [MIT](https://github.com/ynishi/ryo-rs/blob/main/LICENSE-MIT) at your option.
