ExamplePlugins

This folder contains small, self-contained plugin repositories you can build and install to learn how OpenVCS plugins work.

Each example is a module plugin implemented as a WASI (.wasm) executable that talks to OpenVCS over a JSON-RPC-like protocol on stdio (see OpenVCS-Core/src/plugin_runtime.rs).

How plugins work (high level)

• OpenVCS spawns the plugin module (module.exec) and communicates by sending one JSON message per line over stdin/stdout.
• OpenVCS → Plugin: {"id":1,"method":"...","params":{...}}
• Plugin → OpenVCS: {"id":1,"ok":true,"result":...} (or ok:false with error / error_code)
• Plugin → OpenVCS events: {"event":{...}} (see openvcs_core::models::VcsEvent)
• Plugin ↔ plugin events (optional): OpenVCS can fan out events between plugins via events.subscribe / events.emit.

In Rust, plugins typically:

• Register RPC handlers with openvcs_core::plugin_runtime::register_delegate.
• Optionally subscribe to inter-plugin events with openvcs_core::events::subscribe.
• Enter the request loop with openvcs_core::plugin_runtime::run_registered().
• Call OpenVCS APIs with openvcs_core::host::call("method.name", json!(...)).

Building a plugin bundle (.ovcsp)

Use the SDK packager:

1. Build + bundle a plugin:
   • cargo run --manifest-path OpenVCS-SDK/Cargo.toml --bin openvcs-plugin -- --plugin-dir ExamplePlugins/example.notify --out ExamplePlugins/dist
2. The output is a single .ovcsp tar.xz in ExamplePlugins/dist.

Notes:

• These examples build for wasm32-wasip1 (preferred).
• If you don’t have the target installed, add it with rustup target add wasm32-wasip1.

If you install the SDK globally (cargo install openvcs-sdk), the cargo openvcs dist subcommand is exposed (via the cargo-openvcs binary) and behaves like the openvcs-plugin CLI; run it from a plugin directory to bundle that plugin (cargo openvcs dist --plugin-dir path/to/plugin --out path/to/dist, defaults to the current directory and ./dist). To rebuild all examples you can script multiple invocations (e.g., loop over each plugin directory).

With SDK v0.1.1+:

• From an individual plugin folder (contains openvcs.plugin.json), run cargo openvcs dist to bundle that plugin into ./dist/.
• From ExamplePlugins/, run cargo openvcs dist --all to bundle all plugin subfolders into ExamplePlugins/dist/.
• If a Rust plugin fails to compile due to fixable issues, rerun with --fix to apply cargo fix before bundling (example: cargo openvcs dist --all --fix).

Examples

UI plugins (JavaScript)

• ExamplePlugins/example.ui-quick-tools: Adds a titlebar button + menu items, plus right-click actions on changed files, commits, and branches.
• ExamplePlugins/example.ui-themes: Ships a small theme pack under themes/ (no entry.js required).
• ExamplePlugins/example.hybrid-conventional: Hybrid plugin: UI hook + context menu actions that call into a Rust/WASI functions component via invoke_plugin_function.

Module plugins (WASI / Rust)

• ExamplePlugins/example.notify: Adds a single method OpenVCS can call (example.notify.ping). When called, it asks OpenVCS to show a notification and emits an info event.
• ExamplePlugins/example.workspace: Adds methods OpenVCS can call to write/read a “memo” file. All file access goes through OpenVCS, which enforces the allowed workspace root and required capabilities.
• ExamplePlugins/example.events: Adds a method OpenVCS can call (example.events.broadcast) that emits a demo.broadcast event. It also subscribes to demo.broadcast so it can react when other plugins broadcast.