wip: before the machine move

This commit is contained in:
Simon Klee
2026-11-05 12:36:11 +01:00
Unverified
parent ba712f9654
commit 795f78fde3
20 changed files with 3240 additions and 30 deletions
+27
View File
@@ -969,6 +969,16 @@ version = "0.2.191"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
[[package]]
name = "libloading"
version = "0.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "754ca22de805bb5744484a5b151a9e1a8e837d5dc232c2d7d8c2e3492edc8b60"
dependencies = [
"cfg-if",
"windows-link",
]
[[package]]
name = "libsqlite3-sys"
version = "0.38.2"
@@ -1143,6 +1153,7 @@ version = "0.1.0"
dependencies = [
"anyhow",
"base64",
"bytes",
"chrono",
"clap",
"clap_complete",
@@ -1154,10 +1165,12 @@ dependencies = [
"opencode-drive",
"opencode-local",
"opencode-mini",
"opencode-plugin",
"opencode-service",
"opencode-store",
"opencode-tui",
"opencode-ui",
"opentui",
"regex",
"reqwest",
"rustix",
@@ -1260,9 +1273,23 @@ dependencies = [
name = "opencode-plugin"
version = "0.1.0"
dependencies = [
"libloading",
"log",
"opencode-plugin-abi",
"opencode-ui",
"opentui",
"serde",
"serde_json",
"tempfile",
"unicode-width",
]
[[package]]
name = "opencode-plugin-abi"
version = "0.1.0"
dependencies = [
"serde",
"serde_json",
]
[[package]]
+1
View File
@@ -21,6 +21,7 @@ opencode-mermaid = { path = "crates/mermaid" }
opencode-mini = { path = "crates/mini" }
opencode-parity = { path = "crates/parity" }
opencode-plugin = { path = "crates/plugin" }
opencode-plugin-abi = { path = "crates/plugin-abi" }
opencode-service = { path = "crates/service" }
opencode-store = { path = "crates/store" }
opencode-tui = { path = "crates/tui" }
+3
View File
@@ -47,5 +47,8 @@ opencode-tui.workspace = true
opencode-ui.workspace = true
[dev-dependencies]
bytes.workspace = true
opencode-plugin.workspace = true
opentui.workspace = true
serde_json.workspace = true
tempfile.workspace = true
@@ -9,6 +9,7 @@ use opencode_local::channel::Channels;
use opencode_local::cli_config::{CliConfig, Resolved};
use opencode_local::paths::{self, Paths};
use opencode_service::connect::{self, Env, Options, Source};
use opencode_tui::plugins::host::External;
use opencode_tui::{Args, Deps, Launch, Route, app::Roots};
use super::Context;
@@ -81,6 +82,10 @@ pub fn run(context: &Context, args: &RootArgs) -> anyhow::Result<()> {
environment: local.then(opencode_store::environment::session_environment),
..Args::default()
};
let plugins = External {
config_dir: paths.config.clone(),
cwd: directory.clone(),
};
// The TUI's tasks run on this runtime: `App::runtime` uses the multi-threaded runtime it starts in.
let _guard = runtime.enter();
opencode_tui::run(Launch {
@@ -99,6 +104,7 @@ pub fn run(context: &Context, args: &RootArgs) -> anyhow::Result<()> {
},
args: tui_args,
keep: Box::new(connection),
plugins: Some(plugins),
})?;
Ok(())
}
+282
View File
@@ -0,0 +1,282 @@
//! External native plugins (P.4) in the real TUI: the sample plugin found in a `plugins` directory renders its
//! fence in a transcript and its slot on the home screen, reloads when it is rebuilt, a panic shows as failed in
//! the plugin manager while the TUI keeps running, and a major ABI mismatch is refused there with its reason.
//! Config and state live in temp directories.
use std::path::Path;
use std::process::Command;
use std::rc::Rc;
use std::sync::{Arc, Mutex};
use std::time::Duration;
use bytes::Bytes;
use opencode_api::client::Client;
use opencode_api::generated::SessionID;
use opencode_api::transport::{BoxFuture, Request, Response, Transport};
use opencode_local::cli_config::{Info, Resolved};
use opencode_plugin::loader::entry_file;
use opencode_tui::plugins::host::{External, external};
use opencode_tui::{Deps, Route, Tui};
use opentui::testing::TestApp;
use serde_json::{Value, json};
/// Builds the sample plugin (`crates/plugin/examples/sample`) with `features` and `SAMPLE_VERSION=version`.
fn build(features: &str, version: &str) -> Vec<u8> {
static LOCK: Mutex<()> = Mutex::new(());
let _lock = LOCK.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
let sample = Path::new(env!("CARGO_MANIFEST_DIR")).join("../plugin/examples/sample");
let target = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../target/sample-plugin");
let status = Command::new(std::env::var("CARGO").unwrap_or_else(|_| "cargo".to_owned()))
.args(["build", "--quiet", "--manifest-path"])
.arg(sample.join("Cargo.toml"))
.arg("--target-dir")
.arg(&target)
.args(["--features", features])
.env("SAMPLE_VERSION", version)
.status()
.unwrap();
assert!(status.success(), "the sample plugin did not build");
let name = format!(
"{}opencode_sample_plugin{}",
std::env::consts::DLL_PREFIX,
std::env::consts::DLL_SUFFIX
);
std::fs::read(target.join("debug").join(name)).unwrap()
}
/// Serves one session whose assistant reply is `text`.
struct Fixture {
text: String,
}
impl Transport for Fixture {
fn send(&self, request: Request) -> BoxFuture<'_, Result<Response, String>> {
let path = request.url.path().to_owned();
Box::pin(async move {
let (status, body) = match path.as_str() {
"/api/session" => (200, json!({ "data": [], "cursor": {} })),
"/api/session/ses_p" => (200, json!({ "data": session() })),
"/api/session/ses_p/message" => {
(200, json!({ "data": messages(&self.text), "cursor": {} }))
}
"/api/session/ses_p/permission" => (200, json!({ "data": [] })),
_ => (404, json!({})),
};
Ok(Response {
status,
headers: vec![("content-type".into(), "application/json".into())],
body: Box::pin(futures_util::stream::iter([Ok(Bytes::from(
serde_json::to_vec(&body).unwrap(),
))])),
})
})
}
}
fn session() -> Value {
json!({
"id": "ses_p", "title": "Plugins", "projectID": "project", "cost": 0, "agent": "build",
"tokens": { "input": 0, "output": 0, "reasoning": 0, "cache": { "read": 0, "write": 0 } },
"time": { "created": 1, "updated": 1 },
"location": { "directory": "/project" },
})
}
/// Newest first, as the server pages them.
fn messages(text: &str) -> Value {
json!([
{
"id": "msg_2", "type": "assistant", "agent": "build",
"model": { "providerID": "provider", "id": "model" },
"time": { "created": 1500, "completed": 4000, "streamed": 3000 },
"finish": "stop",
"tokens": { "input": 1, "output": 1, "reasoning": 0, "cache": { "read": 0, "write": 0 } },
"content": [{ "type": "text", "text": text }],
},
{ "id": "msg_1", "type": "user", "text": "Show me", "time": { "created": 1000 } },
])
}
struct Harness {
app: TestApp,
tui: Rc<Tui>,
plugin: std::path::PathBuf,
_root: tempfile::TempDir,
}
/// The TUI on `route` with the sample's `build` in `<config>/plugins/sample`.
fn open(route: Route, text: &str, build: &[u8]) -> Harness {
let root = tempfile::tempdir().unwrap();
let config = root.path().join("config");
let plugin = config.join("plugins/sample");
std::fs::create_dir_all(&plugin).unwrap();
std::fs::write(plugin.join(entry_file()), build).unwrap();
let client = Client::with_transport(
"http://opencode.local",
Arc::new(Fixture {
text: text.to_owned(),
}),
)
.unwrap();
let app = TestApp::new(80, 24);
let tui = opencode_tui::mount(
&app,
Deps {
client,
directory: "/project".into(),
config: Resolved::new(Info::default(), |_| None),
roots: None,
route,
continue_: false,
events: false,
},
);
external(
&tui,
External {
config_dir: config,
cwd: root.path().to_path_buf(),
},
);
Harness {
app,
tui,
plugin,
_root: root,
}
}
fn session_route() -> Route {
Route::Session {
id: SessionID("ses_p".into()),
}
}
impl Harness {
fn wait_for(&self, text: &str) -> String {
let found = self
.app
.wait_until(Duration::from_secs(10), || self.app.text().contains(text));
let screen = self.app.text();
assert!(found, "{text:?} never showed:\n{screen}");
screen
}
fn status(&self) -> opencode_plugin::Status {
let target = self.plugin.to_string_lossy();
self.tui
.plugins
.entries()
.into_iter()
.find(|entry| entry.target.as_deref() == Some(&*target))
.unwrap()
.status
}
}
#[test]
fn the_sample_renders_in_the_transcript_and_reloads_on_change() {
let h = open(
session_route(),
"Here:\n\n```sample\nhello plugin\n```",
&build("", "v1"),
);
let screen = h.wait_for("SAMPLE v1 HELLO PLUGIN");
assert!(!screen.contains("hello plugin"), "{screen}");
assert_eq!(h.status(), opencode_plugin::Status::Active);
// A new build in place: the watcher reconciles, the route remounts, and the transcript draws v2.
write_atomic(&h.plugin.join(entry_file()), &build("", "v2"));
h.wait_for("SAMPLE v2 HELLO PLUGIN");
}
#[test]
fn the_sample_claims_the_home_footer_and_runs_its_command() {
let h = open(Route::Home, "", &build("", "v1"));
h.wait_for("sample plugin v1: home.footer");
h.tui.keymap.dispatch("sample.open", None);
h.wait_for("Sample route hello");
assert!(matches!(h.tui.route(), Route::Plugin { ref id, ref name } if id == "sample" && name == "hello"));
// Without storage the command still toasts.
h.tui.keymap.dispatch("sample.hello", None);
h.wait_for("Hello from sample v1 (1)");
}
#[test]
fn a_panicking_plugin_shows_as_failed_in_the_plugin_manager() {
let h = open(
session_route(),
"Crash:\n\n```sample-panic\nboom\n```",
&build("", "v1"),
);
// The fence falls back to the code view and the TUI keeps running.
let screen = h.wait_for("boom");
assert!(!screen.contains("SAMPLE"), "{screen}");
h.wait_for("Plugin failed: sample");
let opencode_plugin::Status::Failed(error) = h.status() else {
panic!("{:?}", h.status());
};
assert_eq!(error, "render-fence panicked: sample fence panicked");
h.tui.keymap.dispatch("plugins.list", None);
let screen = h.wait_for("Plugins");
let row = screen
.lines()
.find(|line| line.contains("sample"))
.unwrap_or_else(|| panic!("no sample row:\n{screen}"));
assert!(row.contains("failed"), "{screen}");
print_excerpt("plugin manager", &screen);
}
#[test]
fn a_panicking_command_is_caught_and_enabling_restarts_the_plugin() {
let h = open(Route::Home, "", &build("", "v1"));
h.wait_for("sample plugin v1: home.footer");
h.tui.keymap.dispatch("sample.panic", None);
assert_eq!(
h.status(),
opencode_plugin::Status::Failed("run-command panicked: sample command panicked".to_owned())
);
h.wait_for("Plugin failed: sample");
h.tui.keymap.dispatch("plugins.list", None);
h.wait_for("view error space");
h.app.press("space");
let screen = h.wait_for("run-command panicked: sample command panicked");
print_excerpt("error details after a panic", &screen);
h.app.press("escape");
h.wait_for("enable enter");
h.app.press("enter");
h.app.wait_until(Duration::from_secs(5), || {
h.status() == opencode_plugin::Status::Active
});
assert_eq!(h.status(), opencode_plugin::Status::Active);
}
#[test]
fn a_major_abi_mismatch_is_refused_with_its_reason() {
let h = open(Route::Home, "", &build("major-2", "v1"));
let opencode_plugin::Status::Failed(error) = h.status() else {
panic!("{:?}", h.status());
};
assert!(error.starts_with("plugin ABI 2.0 is not supported"), "{error}");
h.tui.keymap.dispatch("plugins.list", None);
let screen = h.wait_for("failed, local");
assert!(!screen.contains("sample plugin v1"), "{screen}");
h.app.press("space");
let screen = h.wait_for("plugin ABI 2.0 is not supported");
print_excerpt("error details of a major mismatch", &screen);
}
/// Replaces `path` as editors and build tools do: a new file renamed over the old one.
fn write_atomic(path: &Path, bytes: &[u8]) {
let next = path.with_extension("next");
std::fs::write(&next, bytes).unwrap();
std::fs::rename(next, path).unwrap();
}
fn print_excerpt(title: &str, screen: &str) {
println!("----- {title} -----");
for line in screen.lines().filter(|line| !line.trim().is_empty()) {
println!("{line}");
}
}
@@ -0,0 +1,12 @@
[package]
name = "opencode-plugin-abi"
description = "The C ABI of native opencode-rs TUI plugins (P.4), and export_plugin! for plugins written in Rust."
version.workspace = true
edition.workspace = true
license.workspace = true
publish.workspace = true
# A plugin crate depends on this one alone, so it stays free of the TUI and its native libraries.
[dependencies]
serde.workspace = true
serde_json.workspace = true
@@ -0,0 +1,658 @@
//! The C ABI of native opencode-rs TUI plugins (P.4, `docs/P.4.md`, decision O-42).
//!
//! A plugin is a shared library (`.so`, `.dylib`, `.dll`) that exports [`ENTRY`], a function returning a
//! [`PluginApi`]. Everything after that crosses the boundary as JSON in byte buffers: the plugin's [`Manifest`],
//! [`Request`]s from the host, and [`HostRequest`]s from the plugin. A buffer one side returns is freed by that
//! side's `free`, so each side keeps its own allocator.
//!
//! # Versions
//!
//! The ABI has a major and a minor version ([`ABI_MAJOR`], [`ABI_MINOR`]). A minor version only appends:
//!
//! - [`PluginApi`] and [`HostApi`] start with their own size and version. New entries are only ever added at the
//! end, and each new entry is optional (an `Option` of a function, null when absent). A reader treats entries
//! past the other side's size as absent, so a plugin built against an older minor version loads and works.
//! - JSON payloads only gain optional fields, and readers ignore fields they do not know.
//! - A newer plugin on an older host uses what the host offers: the host answers an unknown [`HostRequest`] with an
//! error, and a plugin that cannot work without a newer host sets [`PluginApi::requires_minor`], which the host
//! refuses with a message naming both versions.
//! - The major version is for a deliberate breaking change. A major mismatch is the only thing that refuses a
//! plugin outright. The entry symbol carries the major version (`opencode_plugin_v1`).
//!
//! A plugin written in Rust is a `cdylib` that depends on this crate and calls [`export_plugin!`] with a setup
//! function. The setup registers the P.1 surface through [`Setup`]: commands, code-fence renderers, slot claims,
//! routes, and storage keys. Renderers return styled rows ([`Line`]); the host turns them into widgets. Panics are
//! caught at every boundary and reported to the host, so keep the default `panic = "unwind"`. Other languages
//! implement the same structs and JSON by hand.
#![allow(unsafe_code)]
use std::ffi::c_void;
use std::panic::{AssertUnwindSafe, catch_unwind};
use serde::{Deserialize, Serialize};
/// The major version: changes only with a deliberate breaking change, and a mismatch refuses the plugin.
pub const ABI_MAJOR: u32 = 1;
/// The minor version: grows when entries are appended. 1.0 is the core; 1.1 adds [`PluginApi::describe`].
pub const ABI_MINOR: u32 = 1;
/// The symbol every plugin exports, of type [`EntryFn`].
pub const ENTRY: &str = "opencode_plugin_v1";
/// Status codes of [`PluginApi::create`], [`PluginApi::call`], and [`HostApi::call`]. With [`OK`] the output buffer
/// holds the JSON result; otherwise it holds the error text.
pub const OK: i32 = 0;
pub const ERROR: i32 = 1;
/// The callee panicked; the output holds the panic message.
pub const PANIC: i32 = 2;
pub type EntryFn = unsafe extern "C" fn() -> *const PluginApi;
/// Bytes borrowed for the length of one call.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct Bytes {
pub ptr: *const u8,
pub len: usize,
}
impl Bytes {
pub fn new(bytes: &[u8]) -> Self {
Self {
ptr: bytes.as_ptr(),
len: bytes.len(),
}
}
/// # Safety
/// `ptr` must point to `len` readable bytes that outlive the returned slice, or be null.
pub unsafe fn as_slice<'a>(self) -> &'a [u8] {
if self.ptr.is_null() {
return &[];
}
unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
}
}
/// A buffer the callee allocated; the caller copies it out, then passes it to the callee's `free`.
#[repr(C)]
pub struct Owned {
pub ptr: *mut u8,
pub len: usize,
pub cap: usize,
}
impl Owned {
pub const EMPTY: Self = Self {
ptr: std::ptr::null_mut(),
len: 0,
cap: 0,
};
pub fn from_vec(bytes: Vec<u8>) -> Self {
let mut bytes = std::mem::ManuallyDrop::new(bytes);
Self {
ptr: bytes.as_mut_ptr(),
len: bytes.len(),
cap: bytes.capacity(),
}
}
/// # Safety
/// `self` must come from [`Owned::from_vec`] in the same library, or be [`Owned::EMPTY`].
pub unsafe fn into_vec(self) -> Vec<u8> {
if self.ptr.is_null() {
return Vec::new();
}
unsafe { Vec::from_raw_parts(self.ptr, self.len, self.cap) }
}
/// A copy of the bytes, leaving the buffer for its owner to free.
///
/// # Safety
/// `ptr` must point to `len` readable bytes, or be null.
pub unsafe fn to_vec(&self) -> Vec<u8> {
unsafe { Bytes { ptr: self.ptr, len: self.len }.as_slice().to_vec() }
}
}
/// What the host gives a plugin instance. It stays valid until the host destroys the instance. A plugin reads an
/// entry only when `size` covers it.
#[repr(C)]
pub struct HostApi {
/// `size_of::<HostApi>()` of the host's build.
pub size: usize,
pub major: u32,
pub minor: u32,
pub ctx: *mut c_void,
/// Handles a [`HostRequest`] and writes the JSON result into `out`.
pub call: unsafe extern "C" fn(ctx: *mut c_void, request: Bytes, out: *mut Owned) -> i32,
/// Frees a buffer `call` wrote.
pub free: unsafe extern "C" fn(owned: Owned),
}
/// What a plugin exports. The host reads an entry only when `size` covers it; entries added by later minor versions
/// go at the end and are optional.
#[repr(C)]
pub struct PluginApi {
// 1.0: the core, which every plugin of major version 1 has.
/// `size_of` the struct as the plugin built it.
pub size: usize,
pub major: u32,
pub minor: u32,
/// The oldest host minor version the plugin works with; 0 for any.
pub requires_minor: u32,
/// Runs the plugin's setup with `options` (the JSON of its `plugins` entry's options, or empty). On [`OK`] it
/// sets `instance` and writes the [`Manifest`] JSON into `out`.
pub create: unsafe extern "C" fn(
host: *const HostApi,
options: Bytes,
instance: *mut *mut c_void,
out: *mut Owned,
) -> i32,
/// Handles a [`Request`] and writes the JSON result into `out`.
pub call: unsafe extern "C" fn(instance: *mut c_void, request: Bytes, out: *mut Owned) -> i32,
pub destroy: unsafe extern "C" fn(instance: *mut c_void),
/// Frees a buffer `create` or `call` wrote.
pub free: unsafe extern "C" fn(owned: Owned),
// 1.1
/// Writes the plugin's [`Metadata`] JSON into `out`.
pub describe: Option<unsafe extern "C" fn(out: *mut Owned) -> i32>,
}
/// The 1.0 layout of [`PluginApi`], a prefix of it. Plugins built against 1.0 export this; kept to test that they
/// still load.
#[doc(hidden)]
#[repr(C)]
pub struct PluginApiV1_0 {
pub size: usize,
pub major: u32,
pub minor: u32,
pub requires_minor: u32,
pub create: unsafe extern "C" fn(*const HostApi, Bytes, *mut *mut c_void, *mut Owned) -> i32,
pub call: unsafe extern "C" fn(*mut c_void, Bytes, *mut Owned) -> i32,
pub destroy: unsafe extern "C" fn(*mut c_void),
pub free: unsafe extern "C" fn(Owned),
}
/// What [`PluginApi::describe`] returns (1.1).
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Metadata {
/// The plugin's own version, such as its crate version.
#[serde(default)]
pub version: Option<String>,
}
/// Everything a plugin registered in its setup.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Manifest {
pub id: String,
pub commands: Vec<Command>,
/// The languages of the code fences it renders.
pub fences: Vec<String>,
/// Slot claims, in order; [`Request::Slot`] names one by index.
pub slots: Vec<SlotClaim>,
pub routes: Vec<String>,
/// Storage keys, stored by the host as `plugin.<id>.<key>`.
pub storage: Vec<String>,
}
/// A command: in the palette when `palette` is set, as `/slash`, and on `keybind` (such as `ctrl+shift+h`).
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Command {
pub name: String,
pub title: String,
pub group: Option<String>,
pub slash: Option<String>,
pub keybind: Option<String>,
pub palette: bool,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum SlotKind {
Prepend,
Append,
Before,
After,
Replace,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct SlotClaim {
pub kind: SlotKind,
/// A host slot path, such as `home.footer` or `sidebar.content`.
pub path: String,
}
/// Styled text. A color is a theme token path (`text.muted`, `markdown.heading`) or `#rrggbb`; an unknown token
/// draws in `text.base`.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Span {
pub text: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub fg: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub bg: Option<String>,
#[serde(default, skip_serializing_if = "is_false")]
pub bold: bool,
#[serde(default, skip_serializing_if = "is_false")]
pub italic: bool,
#[serde(default, skip_serializing_if = "is_false")]
pub underline: bool,
#[serde(default, skip_serializing_if = "is_false")]
pub dim: bool,
}
impl Span {
pub fn new(text: impl Into<String>) -> Self {
Self {
text: text.into(),
..Self::default()
}
}
pub fn fg(mut self, color: impl Into<String>) -> Self {
self.fg = Some(color.into());
self
}
pub fn bold(mut self) -> Self {
self.bold = true;
self
}
}
fn is_false(value: &bool) -> bool {
!value
}
/// One row; the host draws rows without wrapping and scrolls a wide fence sideways.
pub type Line = Vec<Span>;
/// A fenced Markdown code block.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Fence {
pub language: String,
pub info: String,
pub code: String,
/// The message is still streaming and the fence has not closed.
pub streaming: bool,
}
/// From the host to the plugin. Results: `Fence` → `Option<Vec<Line>>`, `Slot` and `Route` → `Vec<Line>`,
/// `Command` → `null`.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case")]
pub enum Request {
Fence(Fence),
Slot {
claim: usize,
session_id: Option<String>,
},
Route {
name: String,
},
Command {
name: String,
input: Option<String>,
},
}
/// From the plugin to the host. Results: `StorageGet` → `Option<String>` (JSON text), everything else `null`.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case")]
pub enum HostRequest {
Log { level: Level, message: String },
Toast { variant: Toast, message: String },
StorageGet { key: String },
/// `value` is JSON text: an object or an array.
StorageSet { key: String, value: String },
OpenRoute { name: String },
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum Level {
Debug,
Info,
Warn,
Error,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum Toast {
Info,
Success,
Warning,
Error,
}
/// The host, as a plugin calls it. Valid while the instance lives.
#[derive(Clone, Copy)]
pub struct Host {
api: *const HostApi,
}
impl Host {
fn request(&self, request: &HostRequest) -> Result<serde_json::Value, String> {
let json = serde_json::to_vec(request).map_err(|error| error.to_string())?;
let mut out = Owned::EMPTY;
// SAFETY: the host keeps `api` alive until it destroys the instance this handle belongs to.
let (status, bytes) = unsafe {
let api = &*self.api;
let status = (api.call)(api.ctx, Bytes::new(&json), &mut out);
let bytes = out.to_vec();
(api.free)(out);
(status, bytes)
};
match status {
OK => serde_json::from_slice(&bytes).map_err(|error| error.to_string()),
_ => Err(String::from_utf8_lossy(&bytes).into_owned()),
}
}
/// The JSON text stored under one of the plugin's storage keys.
pub fn storage_get(&self, key: &str) -> Option<String> {
let value = self
.request(&HostRequest::StorageGet { key: key.to_owned() })
.ok()?;
serde_json::from_value(value).ok().flatten()
}
/// Stores JSON text (an object or an array) under one of the plugin's storage keys.
pub fn storage_set(&self, key: &str, value: &str) -> Result<(), String> {
self.request(&HostRequest::StorageSet {
key: key.to_owned(),
value: value.to_owned(),
})
.map(drop)
}
/// Shows a toast once the current call returns.
pub fn toast(&self, variant: Toast, message: &str) {
let _ = self.request(&HostRequest::Toast {
variant,
message: message.to_owned(),
});
}
/// Opens one of the plugin's routes once the current call returns.
pub fn open_route(&self, name: &str) {
let _ = self.request(&HostRequest::OpenRoute { name: name.to_owned() });
}
pub fn log(&self, level: Level, message: &str) {
let _ = self.request(&HostRequest::Log {
level,
message: message.to_owned(),
});
}
}
type FenceFn = Box<dyn Fn(&Fence) -> Option<Vec<Line>>>;
type SlotFn = Box<dyn Fn(Option<&str>) -> Vec<Line>>;
type RouteFn = Box<dyn Fn() -> Vec<Line>>;
type CommandFn = Box<dyn Fn(Option<&str>)>;
/// What a plugin registers (the C-ABI form of P.1's `Setup`). The instance keeps it until the host destroys it.
pub struct Setup {
manifest: Manifest,
options: Option<String>,
host: Host,
fences: Vec<(String, FenceFn)>,
slots: Vec<SlotFn>,
routes: Vec<(String, RouteFn)>,
commands: Vec<(String, CommandFn)>,
}
impl Setup {
pub fn id(&self) -> &str {
&self.manifest.id
}
/// The `options` of the plugin's `plugins` entry, as JSON text.
pub fn options(&self) -> Option<&str> {
self.options.as_deref()
}
/// The host, for renderers and commands to keep.
pub fn host(&self) -> Host {
self.host
}
/// Declares storage key `key`; [`Host::storage_get`] and [`Host::storage_set`] accept declared keys only.
pub fn storage_key(&mut self, key: &str) {
self.manifest.storage.push(key.to_owned());
}
/// Registers a command; `run` receives the slash command's text after its name.
pub fn command(&mut self, command: Command, run: impl Fn(Option<&str>) + 'static) {
self.commands.push((command.name.clone(), Box::new(run)));
self.manifest.commands.push(command);
}
/// Renders Markdown fences of `language`; `None` keeps the plain code view.
pub fn code_block(
&mut self,
language: &str,
render: impl Fn(&Fence) -> Option<Vec<Line>> + 'static,
) {
self.manifest.fences.push(language.to_owned());
self.fences.push((language.to_owned(), Box::new(render)));
}
/// Claims a place in the slot tree; `render` receives the slot's session ID, if it has one.
pub fn slot(
&mut self,
kind: SlotKind,
path: &str,
render: impl Fn(Option<&str>) -> Vec<Line> + 'static,
) {
self.manifest.slots.push(SlotClaim {
kind,
path: path.to_owned(),
});
self.slots.push(Box::new(render));
}
/// Registers a route the host opens as `plugin/<id>/<name>`.
pub fn route(&mut self, name: &str, render: impl Fn() -> Vec<Line> + 'static) {
self.manifest.routes.push(name.to_owned());
self.routes.push((name.to_owned(), Box::new(render)));
}
fn handle(&self, request: Request) -> Result<serde_json::Value, String> {
let json = |value: Result<serde_json::Value, serde_json::Error>| value.map_err(|error| error.to_string());
match request {
Request::Fence(fence) => {
let render = self
.fences
.iter()
.find(|(language, _)| *language == fence.language)
.map(|(_, render)| render);
json(serde_json::to_value(render.and_then(|render| render(&fence))))
}
Request::Slot { claim, session_id } => {
let render = self.slots.get(claim).ok_or("no such slot claim")?;
json(serde_json::to_value(render(session_id.as_deref())))
}
Request::Route { name } => {
let (_, render) = self
.routes
.iter()
.find(|(route, _)| *route == name)
.ok_or("no such route")?;
json(serde_json::to_value(render()))
}
Request::Command { name, input } => {
let (_, run) = self
.commands
.iter()
.find(|(command, _)| *command == name)
.ok_or("no such command")?;
run(input.as_deref());
Ok(serde_json::Value::Null)
}
}
}
}
/// Exports a plugin: `export_plugin!("my.plugin", setup)` with `fn setup(setup: &mut Setup) -> Result<(), String>`.
/// It exports the current [`PluginApi`], with the crate's version as its [`Metadata`].
#[macro_export]
macro_rules! export_plugin {
($id:expr, $setup:path) => {
$crate::export_plugin!(@version $crate::ABI_MAJOR, $crate::ABI_MINOR, 0, $id, $setup);
};
// A plugin that pretends to be built against another version, for the loader's tests.
(@version $major:expr, $minor:expr, $requires:expr, $id:expr, $setup:path) => {
#[unsafe(no_mangle)]
pub extern "C" fn opencode_plugin_v1() -> *const $crate::PluginApi {
$crate::export_plugin!(@create $id, $setup);
unsafe extern "C" fn describe(out: *mut $crate::Owned) -> i32 {
unsafe { $crate::runtime::describe(env!("CARGO_PKG_VERSION"), out) }
}
static API: $crate::PluginApi = $crate::PluginApi {
size: ::std::mem::size_of::<$crate::PluginApi>(),
major: $major,
minor: $minor,
requires_minor: $requires,
create,
call: $crate::runtime::call,
destroy: $crate::runtime::destroy,
free: $crate::runtime::free,
describe: Some(describe),
};
&API
}
};
// A plugin built against 1.0: the shorter table, without `describe`.
(@v1_0 $id:expr, $setup:path) => {
#[unsafe(no_mangle)]
pub extern "C" fn opencode_plugin_v1() -> *const $crate::PluginApi {
$crate::export_plugin!(@create $id, $setup);
static API: $crate::PluginApiV1_0 = $crate::PluginApiV1_0 {
size: ::std::mem::size_of::<$crate::PluginApiV1_0>(),
major: 1,
minor: 0,
requires_minor: 0,
create,
call: $crate::runtime::call,
destroy: $crate::runtime::destroy,
free: $crate::runtime::free,
};
(&API as *const $crate::PluginApiV1_0).cast()
}
};
(@create $id:expr, $setup:path) => {
unsafe extern "C" fn create(
host: *const $crate::HostApi,
options: $crate::Bytes,
instance: *mut *mut ::std::ffi::c_void,
out: *mut $crate::Owned,
) -> i32 {
unsafe { $crate::runtime::create($id, $setup, host, options, instance, out) }
}
};
}
/// The shims [`export_plugin!`] wires into [`PluginApi`]. Each catches panics, so none unwinds into the host.
#[doc(hidden)]
pub mod runtime {
use super::*;
/// # Safety
/// The host's pointers must be valid as [`PluginApi::create`] documents.
pub unsafe fn create(
id: &str,
setup: fn(&mut Setup) -> Result<(), String>,
host: *const HostApi,
options: Bytes,
instance: *mut *mut c_void,
out: *mut Owned,
) -> i32 {
// SAFETY: the host passes valid pointers for the length of the call.
let options = unsafe { options.as_slice() };
guard(out, || {
let options = (!options.is_empty()).then(|| String::from_utf8_lossy(options).into_owned());
let mut registered = Setup {
manifest: Manifest {
id: id.to_owned(),
..Manifest::default()
},
options,
host: Host { api: host },
fences: Vec::new(),
slots: Vec::new(),
routes: Vec::new(),
commands: Vec::new(),
};
setup(&mut registered)?;
let manifest = serde_json::to_vec(&registered.manifest).map_err(|error| error.to_string())?;
// SAFETY: `instance` is valid for writes during the call.
unsafe { *instance = Box::into_raw(Box::new(registered)).cast() };
Ok(manifest)
})
}
/// # Safety
/// `out` must be valid for writes.
pub unsafe fn describe(version: &str, out: *mut Owned) -> i32 {
guard(out, || {
let metadata = Metadata {
version: Some(version.to_owned()),
};
serde_json::to_vec(&metadata).map_err(|error| error.to_string())
})
}
/// # Safety
/// `instance` must come from [`create`] and not be destroyed.
pub unsafe extern "C" fn call(instance: *mut c_void, request: Bytes, out: *mut Owned) -> i32 {
// SAFETY: as documented.
let (setup, request) = unsafe { (&*instance.cast::<Setup>(), request.as_slice()) };
guard(out, || {
let request: Request = serde_json::from_slice(request).map_err(|error| error.to_string())?;
let value = setup.handle(request)?;
serde_json::to_vec(&value).map_err(|error| error.to_string())
})
}
/// # Safety
/// `instance` must come from [`create`] and not be destroyed.
pub unsafe extern "C" fn destroy(instance: *mut c_void) {
// SAFETY: as documented.
let setup = unsafe { Box::from_raw(instance.cast::<Setup>()) };
let _ = catch_unwind(AssertUnwindSafe(move || drop(setup)));
}
/// # Safety
/// `owned` must come from this library.
pub unsafe extern "C" fn free(owned: Owned) {
// SAFETY: as documented.
drop(unsafe { owned.into_vec() });
}
fn guard(out: *mut Owned, f: impl FnOnce() -> Result<Vec<u8>, String>) -> i32 {
let (status, bytes) = match catch_unwind(AssertUnwindSafe(f)) {
Ok(Ok(bytes)) => (OK, bytes),
Ok(Err(error)) => (ERROR, error.into_bytes()),
Err(panic) => (PANIC, panic_message(&*panic).into_bytes()),
};
// SAFETY: `out` is valid for writes during the call.
unsafe { *out = Owned::from_vec(bytes) };
status
}
}
/// The text of a caught panic.
pub fn panic_message(panic: &(dyn std::any::Any + Send)) -> String {
panic
.downcast_ref::<&str>()
.map(|message| (*message).to_owned())
.or_else(|| panic.downcast_ref::<String>().cloned())
.unwrap_or_else(|| "a panic without a message".to_owned())
}
+9
View File
@@ -13,3 +13,12 @@ workspace = true
opentui.workspace = true
opencode-ui.workspace = true
log.workspace = true
# Native plugins (P.4): the C ABI, and dlopen.
opencode-plugin-abi.workspace = true
libloading = "0.9"
serde.workspace = true
serde_json.workspace = true
unicode-width.workspace = true
[dev-dependencies]
tempfile.workspace = true
+144
View File
@@ -0,0 +1,144 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
[[package]]
name = "equivalent"
version = "1.0.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
[[package]]
name = "foldhash"
version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
[[package]]
name = "hashbrown"
version = "0.17.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
[[package]]
name = "indexmap"
version = "2.14.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
dependencies = [
"equivalent",
"hashbrown",
]
[[package]]
name = "itoa"
version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "opencode-plugin-abi"
version = "0.1.0"
dependencies = [
"serde",
"serde_json",
]
[[package]]
name = "opencode-sample-plugin"
version = "0.1.0"
dependencies = [
"opencode-plugin-abi",
]
[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
"unicode-ident",
]
[[package]]
name = "quote"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
"proc-macro2",
]
[[package]]
name = "serde"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
name = "serde_core"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "serde_json"
version = "1.0.154"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
dependencies = [
"foldhash",
"indexmap",
"itoa",
"memchr",
"serde",
"serde_core",
"zmij",
]
[[package]]
name = "syn"
version = "3.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "unicode-ident"
version = "1.0.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
[[package]]
name = "zmij"
version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
@@ -0,0 +1,22 @@
# The sample native plugin (P.4): a `cdylib` on `opencode-plugin-abi`. The loader's tests build it with `cargo build`
# and load the library. Not a workspace member.
[package]
name = "opencode-sample-plugin"
version = "0.1.0"
edition = "2024"
license = "MIT"
publish = false
[lib]
crate-type = ["cdylib"]
[features]
# Builds that pretend to target another ABI version, for the version tests.
abi-1-0 = []
major-2 = []
requires-future = []
[dependencies]
opencode-plugin-abi = { path = "../../../plugin-abi" }
[workspace]
@@ -0,0 +1,86 @@
//! The sample native plugin: a command, a code-fence renderer, a slot claim, a route, and a storage key, plus a
//! fence and a command that panic, so the loader's tests can show a panic is caught. `SAMPLE_VERSION` (at build
//! time) changes what it draws, so a rebuild proves hot reload.
use opencode_plugin_abi::{Command, Line, Setup, SlotKind, Span, Toast, export_plugin};
const VERSION: &str = match option_env!("SAMPLE_VERSION") {
Some(version) => version,
None => "v1",
};
fn setup(setup: &mut Setup) -> Result<(), String> {
if setup.options().is_some_and(|options| options.contains("\"fail\":true")) {
return Err("sample setup failed".to_owned());
}
let host = setup.host();
setup.storage_key("count");
setup.command(command("sample.hello", "Say hello", Some("hello")), move |_| {
let count = count(host) + 1;
if let Err(error) = host.storage_set("count", &format!("{{\"count\":{count}}}")) {
host.log(opencode_plugin_abi::Level::Warn, &error);
}
host.toast(Toast::Success, &format!("Hello from sample {VERSION} ({count})"));
});
setup.command(command("sample.open", "Open the sample route", Some("sample")), move |_| {
host.open_route("hello")
});
setup.command(command("sample.panic", "Panic in the sample plugin", None), |_| {
panic!("sample command panicked")
});
setup.code_block("sample", |fence| {
if fence.code.trim().is_empty() {
return None;
}
let lines = fence.code.lines().map(|line| {
vec![
Span::new(format!("SAMPLE {VERSION} ")).fg("text.muted"),
Span::new(line.to_uppercase()).fg("markdown.heading").bold(),
]
});
Some(lines.collect())
});
setup.code_block("sample-panic", |_| panic!("sample fence panicked"));
setup.slot(SlotKind::Append, "home.footer", |_| {
vec![vec![Span::new(format!("sample plugin {VERSION}: home.footer")).fg("text.muted")]]
});
setup.route("hello", move || -> Vec<Line> {
vec![
vec![Span::new("Sample route hello").bold()],
vec![Span::new(format!("said hello {} times", count(host))).fg("text.muted")],
]
});
Ok(())
}
fn command(name: &str, title: &str, slash: Option<&str>) -> Command {
Command {
name: name.to_owned(),
title: title.to_owned(),
group: Some("Sample".to_owned()),
slash: slash.map(str::to_owned),
keybind: None,
palette: true,
}
}
/// The stored `{"count":N}`, else 0.
fn count(host: opencode_plugin_abi::Host) -> u64 {
host.storage_get("count")
.and_then(|json| json.chars().filter(char::is_ascii_digit).collect::<String>().parse().ok())
.unwrap_or(0)
}
#[cfg(not(any(feature = "abi-1-0", feature = "major-2", feature = "requires-future")))]
export_plugin!("sample", setup);
// Built against ABI 1.0: the shorter table, without `describe`.
#[cfg(feature = "abi-1-0")]
export_plugin!(@v1_0 "sample", setup);
#[cfg(feature = "major-2")]
export_plugin!(@version 2, 0, 0, "sample", setup);
// Needs a host minor version no host has yet.
#[cfg(feature = "requires-future")]
export_plugin!(@version 1, 99, 99, "sample", setup);
+210 -22
View File
@@ -1,7 +1,7 @@
//! The Rust plugin API (P.1, `docs/P.1.md`): the in-process form of `@opencode/plugin/tui`. Built-in
//! plugins and the LaTeX and Mermaid plugins register slots, keymap layers, routes, and code-block renderers
//! through [`Setup`]; the host mounts them through [`Registry`]. [`loader`] is where P.4 loads external
//! plugins.
//! through [`Setup`]; the host mounts them through [`Registry`]. [`loader`] finds and loads external plugins
//! (P.4).
pub mod loader;
pub mod slot;
@@ -29,6 +29,31 @@ pub trait Host: 'static {
fn theme(&self) -> Theme;
/// The keymap plugin layers register on.
fn keymap(&self) -> &DialogKeymap;
// What external plugins reach across the component boundary (P.4). Built-ins use the host directly.
/// The JSON text of storage key `key` (already `plugin.<id>.<key>`), if stored.
fn storage_read(&self, _key: &str) -> Option<String> {
None
}
/// Stores JSON text (an object or an array) under storage key `key`.
fn storage_write(&self, _key: &str, _json: &str) -> Result<(), String> {
Err("no storage".to_owned())
}
fn toast(&self, _variant: Toast, _title: Option<&str>, _message: &str) {}
/// Opens the route plugin `id` registered as `name`.
fn open_route(&self, _id: &str, _name: &str) {}
/// Mounts the current route again, so changed slot claims and code-block renderers show.
fn remount(&self) {}
}
/// A toast's variant, for [`Host::toast`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Toast {
Info,
Success,
Warning,
Error,
}
/// A mounted slot claim or plugin route: its root view, and a sync with each change batch. A plain
@@ -47,6 +72,8 @@ impl<H: Host> Slotted<H> for View {
pub type SlotRender<H> = Rc<dyn Fn(&H, &SlotInput) -> Box<dyn Slotted<H>>>;
pub type RouteRender<H> = Rc<dyn Fn(&H) -> Box<dyn Slotted<H>>>;
type SetupFn<H> = Rc<dyn Fn(&mut Setup<'_, H>)>;
/// The current failure of an external plugin, if any.
pub type ErrorFn = Rc<dyn Fn() -> Option<String>>;
/// Renders a fenced code block in the theme, or returns `None` to keep the default code view.
pub type CodeBlockRender = Rc<dyn Fn(&CodeBlock<'_>, &Theme) -> Option<AnyWidget>>;
@@ -55,6 +82,8 @@ pub type CodeBlockRender = Rc<dyn Fn(&CodeBlock<'_>, &Theme) -> Option<AnyWidget
pub struct Definition<H: Host> {
pub id: String,
setup: SetupFn<H>,
/// The `plugins` target or discovered path of an external plugin, and its failure.
external: Option<(String, ErrorFn)>,
}
impl<H: Host> Clone for Definition<H> {
@@ -62,6 +91,7 @@ impl<H: Host> Clone for Definition<H> {
Self {
id: self.id.clone(),
setup: self.setup.clone(),
external: self.external.clone(),
}
}
}
@@ -71,8 +101,20 @@ impl<H: Host> Definition<H> {
Self {
id: id.into(),
setup: Rc::new(setup),
external: None,
}
}
/// Marks an external plugin loaded from `target`; `error` reports its failure while it is active.
pub fn external(mut self, target: impl Into<String>, error: ErrorFn) -> Self {
self.external = Some((target.into(), error));
self
}
/// The target of an external plugin.
pub fn target(&self) -> Option<&str> {
self.external.as_ref().map(|(target, _)| target.as_str())
}
}
/// What a plugin registers while it is active.
@@ -177,8 +219,10 @@ pub enum Source {
Builtin,
/// Added by the host after the built-ins, such as a test plugin.
Added,
/// A `plugins` entry of `cli.json`.
/// A `plugins` entry of `cli.json`, or a directory found in a `plugins` directory, that is not loaded.
Configured,
/// Loaded from a WASM build (P.4).
External,
}
#[derive(Clone, Debug, PartialEq, Eq)]
@@ -187,6 +231,8 @@ pub enum Status {
Inactive,
/// Configured but not loaded, with the reason.
Skipped(String),
/// An external plugin that failed to load or crashed, with the error.
Failed(String),
}
/// One plugin as the plugin manager lists it.
@@ -194,6 +240,8 @@ pub enum Status {
pub struct Entry {
/// The plugin ID, or the configured target of a skipped entry.
pub id: String,
/// Where an external or skipped plugin comes from: its `plugins` target or path.
pub target: Option<String>,
pub source: Source,
pub status: Status,
}
@@ -209,10 +257,13 @@ struct Plugin<H: Host> {
active: Option<(u64, Registration<H>)>,
}
/// The host's plugins in enable order, and the configured entries it skipped.
/// The host's plugins in enable order, and the configured entries it did not load.
pub struct Registry<H: Host> {
plugins: RefCell<Vec<Plugin<H>>>,
skipped: Vec<String>,
/// Targets that are not loaded, with their status ([`Status::Skipped`] or [`Status::Failed`]).
unloaded: RefCell<Vec<(String, Status)>>,
/// The `plugins` targets, in order, which also enable and disable external plugins as they load.
directives: Vec<String>,
activations: Cell<u64>,
}
@@ -233,7 +284,8 @@ impl<H: Host> Registry<H> {
})
.collect();
let mut skipped = Vec::new();
for target in targets {
let directives: Vec<String> = targets.into_iter().map(str::to_owned).collect();
for target in directives.iter().map(String::as_str) {
if let Some(selector) = target.strip_prefix('-') {
plugins
.iter_mut()
@@ -250,13 +302,14 @@ impl<H: Host> Registry<H> {
if named || target == "*" || target.ends_with(".*") || target.starts_with("opencode.") {
continue;
}
if !skipped.iter().any(|known| known == target) {
skipped.push(target.to_owned());
if !skipped.iter().any(|(known, _)| known == target) {
skipped.push((target.to_owned(), Status::Skipped(SKIPPED.to_owned())));
}
}
Self {
plugins: RefCell::new(plugins),
skipped,
unloaded: RefCell::new(skipped),
directives,
activations: Cell::new(0),
}
}
@@ -271,9 +324,121 @@ impl<H: Host> Registry<H> {
});
}
/// The configured entries that were not loaded.
pub fn skipped(&self) -> &[String] {
&self.skipped
/// The entries that were skipped.
pub fn skipped(&self) -> Vec<String> {
self.unloaded
.borrow()
.iter()
.filter(|(_, status)| matches!(status, Status::Skipped(_)))
.map(|(target, _)| target.clone())
.collect()
}
/// Lists `target` as not loaded with `status`, or clears it with `None`.
pub fn set_unloaded(&self, target: &str, status: Option<Status>) {
let mut unloaded = self.unloaded.borrow_mut();
let index = unloaded.iter().position(|(known, _)| known == target);
match (index, status) {
(Some(index), Some(status)) => unloaded[index].1 = status,
(None, Some(status)) => unloaded.push((target.to_owned(), status)),
(Some(index), None) => {
unloaded.remove(index);
}
(None, None) => {}
}
}
/// Adds external plugin `definition`, or replaces the one loaded from the same target, and activates it
/// unless a `plugins` entry or the plugin manager disabled it. A replacement keeps its place, so slot
/// order holds across a reload.
pub fn load(&self, host: &Rc<H>, definition: Definition<H>) {
let Some(target) = definition.target().map(str::to_owned) else {
return;
};
self.set_unloaded(&target, None);
let previous = {
let mut plugins = self.plugins.borrow_mut();
match plugins
.iter_mut()
.find(|plugin| plugin.definition.target() == Some(target.as_str()))
{
Some(plugin) => {
plugin.definition = definition;
Some(plugin.active.take())
}
None => {
// Like TS, the directives after the plugin's own entry (all of them, for a discovered
// plugin) decide whether it starts enabled.
let after = self
.directives
.iter()
.position(|directive| *directive == target)
.map_or(0, |index| index + 1);
let enabled =
self.directives[after..]
.iter()
.fold(true, |enabled, directive| {
match directive.strip_prefix('-') {
Some(selector) if matches(selector, &definition.id) => false,
None if matches(directive, &definition.id) => true,
_ => enabled,
}
});
plugins.push(Plugin {
definition,
source: Source::External,
enabled,
active: None,
});
None
}
}
};
if let Some((_, registration)) = previous.flatten() {
registration.dispose();
}
// A `plugins` entry that names the plugin enables it; it is not a plugin of its own.
if let Some(id) = self.with_target(&target, |plugin| plugin.definition.id.clone()) {
self.unloaded.borrow_mut().retain(|(known, status)| {
!(matches!(status, Status::Skipped(_)) && matches(known, &id))
});
}
let started = self.with_target(&target, |plugin| {
plugin.enabled.then(|| plugin.definition.id.clone())
});
if let Some(Some(id)) = started {
self.start(host, &id);
}
}
/// Whether `target` is a selector of a plugin, rather than a plugin to load.
pub fn selects(&self, target: &str) -> bool {
self.plugins
.borrow()
.iter()
.any(|plugin| matches(target, &plugin.definition.id))
}
/// Whether a plugin other than the one loaded from `target` has ID `id`.
pub fn id_taken(&self, id: &str, target: &str) -> bool {
self.plugins
.borrow()
.iter()
.any(|plugin| plugin.definition.id == id && plugin.definition.target() != Some(target))
}
/// Deactivates and removes the external plugin loaded from `target`.
pub fn unload(&self, target: &str) {
let removed = {
let mut plugins = self.plugins.borrow_mut();
let index = plugins
.iter()
.position(|plugin| plugin.definition.target() == Some(target));
index.map(|index| plugins.remove(index))
};
if let Some((_, registration)) = removed.and_then(|plugin| plugin.active) {
registration.dispose();
}
}
/// Activates every enabled plugin that is not active, in enable order.
@@ -292,9 +457,9 @@ impl<H: Host> Registry<H> {
/// Activates or deactivates plugin `id` (the plugin manager's toggle); returns whether it exists.
pub fn set_active(&self, host: &Rc<H>, id: &str, active: bool) -> bool {
let Some(enabled) = self.with_plugin(id, |plugin| plugin.enabled) else {
if self.with_plugin(id, |_| ()).is_none() {
return false;
};
}
if !active {
let registration = self.with_plugin(id, |plugin| {
plugin.enabled = false;
@@ -305,8 +470,19 @@ impl<H: Host> Registry<H> {
}
return true;
}
if !enabled {
self.with_plugin(id, |plugin| plugin.enabled = true);
// Enabling a failed external plugin restarts it with a fresh setup.
let failed = self.with_plugin(id, |plugin| {
plugin.enabled = true;
let failed = plugin.active.is_some()
&& plugin
.definition
.external
.as_ref()
.is_some_and(|(_, error)| error().is_some());
failed.then(|| plugin.active.take()).flatten()
});
if let Some((_, registration)) = failed.flatten() {
registration.dispose();
}
self.start(host, id);
true
@@ -317,18 +493,22 @@ impl<H: Host> Registry<H> {
let plugins = self.plugins.borrow();
let active = plugins.iter().map(|plugin| Entry {
id: plugin.definition.id.clone(),
target: plugin.definition.target().map(str::to_owned),
source: plugin.source,
status: match plugin.active {
Some(_) => Status::Active,
None => Status::Inactive,
status: match (&plugin.active, &plugin.definition.external) {
(Some(_), Some((_, error))) => error().map_or(Status::Active, Status::Failed),
(Some(_), None) => Status::Active,
(None, _) => Status::Inactive,
},
});
let skipped = self.skipped.iter().map(|target| Entry {
let unloaded = self.unloaded.borrow();
let unloaded = unloaded.iter().map(|(target, status)| Entry {
id: target.clone(),
target: Some(target.clone()),
source: Source::Configured,
status: Status::Skipped(SKIPPED.to_owned()),
status: status.clone(),
});
active.chain(skipped).collect()
active.chain(unloaded).collect()
}
/// Mounts slot `path` into `parent`: the claims before it, prepended to it, `content` (the host's own,
@@ -418,6 +598,14 @@ impl<H: Host> Registry<H> {
});
}
fn with_target<T>(&self, target: &str, f: impl FnOnce(&mut Plugin<H>) -> T) -> Option<T> {
let mut plugins = self.plugins.borrow_mut();
plugins
.iter_mut()
.find(|plugin| plugin.definition.target() == Some(target))
.map(f)
}
fn with_plugin<T>(&self, id: &str, f: impl FnOnce(&mut Plugin<H>) -> T) -> Option<T> {
let mut plugins = self.plugins.borrow_mut();
plugins
+358 -2
View File
@@ -1,2 +1,358 @@
//! External plugins (P.4): discovery, `plugins` config, and loading as WASM components on `wasmtime`
//! (decision O-7). Until then the registry lists configured plugins as skipped.
//! External plugins (P.4, `docs/P.4.md`, row F16): discovery in `plugins` directories, the `plugins` entries of
//! `cli.json`, and loading of native builds (shared libraries on the C ABI of `opencode-plugin-abi`, decision
//! O-42) through a [`Backend`], which is [`native::Native`] in the TUI. Targets without a native build
//! (TypeScript plugins) are listed as skipped.
//!
//! A [`Loader`] reconciles the targets with the [`Registry`]: it loads new and changed builds, keeps a running
//! plugin when its new build fails, and unloads removed ones. The host calls [`Loader::reconcile`] again when a
//! directory of [`Loader::watch_dirs`] changes, which gives hot reload.
pub mod native;
use std::cell::RefCell;
use std::collections::HashMap;
use std::hash::{DefaultHasher, Hasher};
use std::path::{Component, Path, PathBuf};
use std::rc::Rc;
use crate::{Definition, ErrorFn, Host, Registry, SKIPPED, Status};
/// The file name of a plugin directory's native build: `plugin.so`, `plugin.dylib`, or `plugin.dll`.
pub fn entry_file() -> String {
format!("plugin.{}", std::env::consts::DLL_EXTENSION)
}
/// Loads native builds.
pub trait Backend<H: Host> {
/// Loads the build `library` and runs its setup once with `options` (JSON text), returning the definition,
/// not yet active, and its failure while it runs. An error is why the build cannot load.
fn load(&self, library: &[u8], options: Option<&str>)
-> Result<(Definition<H>, ErrorFn), String>;
}
/// A `plugins` entry of `cli.json` that names no built-in: a TypeScript package or path, or a native build.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Configured {
pub target: String,
/// The entry's `options` as JSON text.
pub options: Option<String>,
}
/// One plugin to reconcile: a discovered directory or a configured entry.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Target {
/// The configured target, or the discovered directory's path.
pub target: String,
/// The local path the target names, if it is one.
pub local: Option<PathBuf>,
pub options: Option<String>,
}
impl Target {
/// The native build: the target itself when it is a shared library, else the directory's [`entry_file`].
pub fn library(&self) -> Option<PathBuf> {
let local = self.local.as_ref()?;
let extension = std::env::consts::DLL_EXTENSION;
if local.extension().is_some_and(|known| known == extension) && local.is_file() {
return Some(local.clone());
}
Some(local.join(entry_file())).filter(|entry| entry.is_file())
}
}
/// What the loader last saw of a target.
struct Seen {
/// The digest of the build it loaded or failed on.
digest: u64,
/// The failure of a new build while the previous one keeps running.
reload: Rc<RefCell<Option<String>>>,
}
pub struct Loader<H: Host> {
backend: Rc<dyn Backend<H>>,
/// The global config directory, whose `plugins` directory is always searched and which relative
/// `plugins` paths start from (TS `path.dirname(config.path)`).
config_dir: PathBuf,
cwd: PathBuf,
configured: Vec<Configured>,
seen: RefCell<HashMap<String, Seen>>,
}
impl<H: Host> Loader<H> {
pub fn new(
backend: Rc<dyn Backend<H>>,
config_dir: PathBuf,
cwd: PathBuf,
configured: Vec<Configured>,
) -> Self {
Self {
backend,
config_dir,
cwd,
configured,
seen: RefCell::default(),
}
}
/// The discovered directories, then the configured entries, merged by local path (TS `mergePluginTargets`:
/// a later entry replaces an earlier one in its place).
pub fn targets(&self) -> Vec<Target> {
let discovered = discover(&plugin_directories(&self.config_dir, &self.cwd))
.into_iter()
.map(|path| Target {
target: path.to_string_lossy().into_owned(),
local: Some(path),
options: None,
});
let configured = self.configured.iter().map(|entry| Target {
target: entry.target.clone(),
local: local_source(&entry.target, &self.config_dir),
options: entry.options.clone(),
});
let mut targets: Vec<Target> = Vec::new();
for target in discovered.chain(configured) {
let key = |target: &Target| {
target.local.as_ref().map_or_else(
|| target.target.clone(),
|local| local.to_string_lossy().into_owned(),
)
};
match targets.iter_mut().find(|known| key(known) == key(&target)) {
Some(known) => *known = target,
None => targets.push(target),
}
}
targets
}
/// The directories whose changes can change the targets: the `plugins` directories (or, while one is
/// missing, the directory it would be made in), each local target's directory, and the directory of each
/// configured library. Missing ones are left out.
pub fn watch_dirs(&self) -> Vec<PathBuf> {
let mut dirs: Vec<PathBuf> = plugin_directories(&self.config_dir, &self.cwd)
.into_iter()
.map(|dir| match (dir.is_dir(), dir.parent()) {
(false, Some(parent)) => parent.to_path_buf(),
_ => dir,
})
.collect();
for target in self.targets() {
let Some(local) = target.local else { continue };
let dir = if local.is_dir() {
local
} else {
local.parent().map(Path::to_path_buf).unwrap_or(local)
};
dirs.push(dir);
}
let mut unique: Vec<PathBuf> = Vec::new();
for dir in dirs.into_iter().filter(|dir| dir.is_dir()) {
if !unique.contains(&dir) {
unique.push(dir);
}
}
unique
}
/// Brings the registry in line with the targets and their builds, then remounts the host's route when
/// anything changed. Returns whether it did.
pub fn reconcile(&self, host: &Rc<H>, registry: &Registry<H>) -> bool {
let targets = self.targets();
let mut changed = false;
let stale: Vec<String> = self
.seen
.borrow()
.keys()
.filter(|target| {
!targets
.iter()
.any(|known| known.target == **target && known.library().is_some())
})
.cloned()
.collect();
for target in stale {
self.seen.borrow_mut().remove(&target);
registry.unload(&target);
registry.set_unloaded(&target, None);
changed = true;
}
for target in &targets {
changed |= self.reconcile_target(host, registry, target);
}
if changed {
host.remount();
}
changed
}
fn reconcile_target(&self, host: &Rc<H>, registry: &Registry<H>, target: &Target) -> bool {
let name = target.target.as_str();
let skip = |reason: &str| {
let status = Some(Status::Skipped(reason.to_owned()));
let changed = registry.entries().iter().all(|entry| {
entry.target.as_deref() != Some(name) || Some(&entry.status) != status.as_ref()
});
registry.set_unloaded(name, status);
changed
};
let Some(file) = target.library() else {
if target.local.is_none() && registry.selects(name) {
registry.set_unloaded(name, None);
return false;
}
return skip(SKIPPED);
};
let bytes = match std::fs::read(&file) {
Ok(bytes) => bytes,
Err(error) => {
return self.fail(registry, name, 0, format!("{}: {error}", file.display()));
}
};
let mut hasher = DefaultHasher::new();
hasher.write(&bytes);
let digest = hasher.finish();
if self
.seen
.borrow()
.get(name)
.is_some_and(|seen| seen.digest == digest)
{
return false;
}
let loaded = self
.backend
.load(&bytes, target.options.as_deref())
.and_then(|loaded| match registry.id_taken(&loaded.0.id, name) {
true => Err(format!("plugin ID {} is already registered", loaded.0.id)),
false => Ok(loaded),
});
let (definition, error) = match loaded {
Ok(loaded) => loaded,
Err(error) => return self.fail(registry, name, digest, error),
};
log::info!("plugin {} loaded from {}", definition.id, file.display());
let reload: Rc<RefCell<Option<String>>> = Rc::default();
let failure = {
let reload = reload.clone();
Rc::new(move || error().or_else(|| reload.borrow().clone()))
};
self.seen
.borrow_mut()
.insert(name.to_owned(), Seen { digest, reload });
registry.load(host, definition.external(name, failure));
true
}
/// Records that the build of `target` failed: the running previous version, if any, keeps running and
/// reports the failure; otherwise the target is listed as failed.
fn fail(&self, registry: &Registry<H>, target: &str, digest: u64, error: String) -> bool {
log::error!("plugin {target} failed to load: {error}");
let mut seen = self.seen.borrow_mut();
match seen.get_mut(target) {
Some(previous) => {
previous.digest = digest;
*previous.reload.borrow_mut() =
Some(format!("{error} (previous version still active)"));
}
None => {
seen.insert(
target.to_owned(),
Seen {
digest,
reload: Rc::default(),
},
);
registry.set_unloaded(target, Some(Status::Failed(error)));
}
}
true
}
}
/// The `plugins` directories to search (TS `localPluginDirectories`): the global config directory's, then each
/// `.opencode` directory from the project root down to `cwd`. The project root is the nearest ancestor with
/// `.git` or `.hg`, else `cwd`. Directories other than the global one and the project's that do not exist are
/// left out.
pub fn plugin_directories(config_dir: &Path, cwd: &Path) -> Vec<PathBuf> {
let ancestors: Vec<PathBuf> = {
let mut ancestors: Vec<PathBuf> = cwd.ancestors().map(Path::to_path_buf).collect();
ancestors.reverse();
ancestors
};
let project = ancestors
.iter()
.rposition(|dir| dir.join(".git").exists() || dir.join(".hg").exists())
.unwrap_or(ancestors.len().saturating_sub(1));
let project_config = ancestors.get(project).map(|dir| dir.join(".opencode"));
let mut directories = vec![config_dir.to_path_buf()];
directories.extend(
ancestors
.iter()
.skip(project)
.map(|dir| dir.join(".opencode"))
.filter(|dir| Some(dir) == project_config.as_ref() || dir.is_dir()),
);
let mut unique: Vec<PathBuf> = Vec::new();
for dir in directories {
if !unique.contains(&dir) {
unique.push(dir);
}
}
unique.into_iter().map(|dir| dir.join("plugins")).collect()
}
/// The plugin directories inside `directories` (TS `discoverPluginTargets`): every subdirectory, or symlink to
/// one, by name in each.
pub fn discover(directories: &[PathBuf]) -> Vec<PathBuf> {
directories
.iter()
.flat_map(|directory| {
let mut entries: Vec<PathBuf> = std::fs::read_dir(directory)
.into_iter()
.flatten()
.flatten()
.map(|entry| entry.path())
.filter(|path| path.is_dir())
.collect();
// `localeCompare` without the ICU tables: case-insensitive, then by code point.
entries.sort_by_key(|path| {
let name = path
.file_name()
.unwrap_or_default()
.to_string_lossy()
.into_owned();
(name.to_lowercase(), name)
});
entries
})
.collect()
}
/// The local path a `plugins` target names (TS `localSource`): a `file://` URL, or a `./`, `../`, or absolute
/// path resolved against `directory`. A package name is not local.
pub fn local_source(target: &str, directory: &Path) -> Option<PathBuf> {
let path = match target.strip_prefix("file://") {
Some(path) => PathBuf::from(path),
None if target.starts_with("./")
|| target.starts_with("../")
|| Path::new(target).is_absolute() =>
{
directory.join(target)
}
None => return None,
};
let mut resolved = PathBuf::new();
for component in path.components() {
match component {
Component::ParentDir => {
resolved.pop();
}
Component::CurDir => {}
other => resolved.push(other),
}
}
Some(resolved)
}
#[cfg(test)]
mod tests;
@@ -0,0 +1,639 @@
//! The native backend (decision O-42): plugins are shared libraries on the C ABI of `opencode-plugin-abi`,
//! loaded with `libloading`. There is no sandbox; it is the user's machine. The host only keeps a plugin's
//! panics out of the TUI:
//!
//! - the plugin's shims catch its panics, and the host's callbacks catch the host's, so no panic unwinds across
//! the boundary (a crash such as a segfault still takes the process down);
//! - a panic fails the plugin: it is not called again, its fences fall back to the code view, its slots and routes
//! draw empty, the plugin manager lists it as `failed` with the message, and a toast says so. Enabling it again
//! in the plugin manager starts a fresh instance;
//! - host effects (toasts, routes) wait until the plugin returns, so it never reenters itself through the host.
//!
//! Versions follow the ABI's rules: only a major mismatch, a too-short table, or a plugin that requires a newer
//! host minor version is refused. Entries past the plugin's table size are absent.
//!
//! Each build is copied to a file of its own before it is opened, because the platform loader returns the
//! library already open at a path, and a rebuilt library is often written over the old one. Libraries are never
//! unloaded: a running plugin's code must outlive every pointer into it, and a reload leaks one library.
#![allow(unsafe_code)]
use std::cell::{Cell, RefCell};
use std::ffi::c_void;
use std::mem::{offset_of, size_of};
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::rc::{Rc, Weak};
use std::sync::atomic::{AtomicUsize, Ordering};
use std::time::Duration;
use opencode_plugin_abi::{
self as abi, ABI_MAJOR, ABI_MINOR, Bytes, HostApi, HostRequest, Line, Manifest, Owned,
PluginApi, PluginApiV1_0, Request,
};
use opencode_ui::keymap::{Bind, GLOBAL_MODE, KeymapLayer, Slash, TuiCommand};
use opencode_ui::theme::Theme;
use opentui::prelude::*;
use opentui::style::Color;
use serde::de::DeserializeOwned;
use super::Backend;
use crate::{Definition, ErrorFn, Host, Kind, Placement, Setup, Toast};
/// The host's minor version: it serves every entry and request up to it.
pub const HOST_MINOR: u32 = ABI_MINOR;
/// Loads native plugins.
#[derive(Clone, Copy, Debug, Default)]
pub struct Native;
/// What a library reports about itself before it is set up.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Inspected {
pub major: u32,
pub minor: u32,
/// The plugin's version from `describe` (ABI 1.1), when its table has it.
pub version: Option<String>,
}
impl Native {
/// Opens `library` and checks its version without setting it up.
pub fn inspect(&self, library: &[u8]) -> Result<Inspected, String> {
let library = Library::open(library)?;
Ok(Inspected {
major: ABI_MAJOR,
minor: library.minor,
version: library.version(),
})
}
}
impl<H: Host> Backend<H> for Native {
fn load(
&self,
library: &[u8],
options: Option<&str>,
) -> Result<(Definition<H>, ErrorFn), String> {
let library = Rc::new(Library::open(library)?);
if let Some(version) = library.version() {
log::info!("plugin library version {version}, ABI {ABI_MAJOR}.{}", library.minor);
}
let options = options.map(str::to_owned);
// Setup runs once now, to check the build and learn its ID; the first activation takes this instance.
let first = Instance::<H>::create(&library, Weak::new(), options.as_deref())?;
let id = first.1.id.clone();
let failure: Rc<RefCell<Option<String>>> = Rc::default();
let prepared = RefCell::new(Some(first));
let definition = Definition::new(id, {
let failure = failure.clone();
move |setup: &mut Setup<'_, H>| {
let host = Rc::downgrade(setup.host());
let instance = match prepared.borrow_mut().take() {
Some(first) => {
first.0.ctx.borrow_mut().host = host.clone();
Ok(first)
}
None => Instance::create(&library, host.clone(), options.as_deref()),
};
let (instance, manifest) = match instance {
Ok(instance) => instance,
Err(error) => {
log::error!("plugin {} failed: {error}", setup.id());
*failure.borrow_mut() = Some(error);
return;
}
};
*failure.borrow_mut() = None;
let guest = Rc::new(Guest {
instance,
busy: Cell::new(false),
failure: failure.clone(),
host,
id: setup.id().to_owned(),
});
register(setup, &guest, &manifest);
}
});
let error: ErrorFn = Rc::new(move || failure.borrow().clone());
Ok((definition, error))
}
}
/// An open library's entries. The library stays loaded for the life of the process.
struct Library {
minor: u32,
create: unsafe extern "C" fn(*const HostApi, Bytes, *mut *mut c_void, *mut Owned) -> i32,
call: unsafe extern "C" fn(*mut c_void, Bytes, *mut Owned) -> i32,
destroy: unsafe extern "C" fn(*mut c_void),
free: unsafe extern "C" fn(Owned),
describe: Option<unsafe extern "C" fn(*mut Owned) -> i32>,
}
impl Library {
fn open(bytes: &[u8]) -> Result<Self, String> {
static OPENED: AtomicUsize = AtomicUsize::new(0);
let dir = std::env::temp_dir().join(format!("opencode-rs-plugins-{}", std::process::id()));
std::fs::create_dir_all(&dir).map_err(|error| format!("{}: {error}", dir.display()))?;
let file = dir.join(format!(
"{}.{}",
OPENED.fetch_add(1, Ordering::Relaxed),
std::env::consts::DLL_EXTENSION
));
std::fs::write(&file, bytes).map_err(|error| format!("{}: {error}", file.display()))?;
// SAFETY: loading runs the library's initializers; a plugin is code the user chose to run.
let library = unsafe { libloading::Library::new(&file) };
// The mapping stays after the file is gone (where the platform allows removing it).
let _ = std::fs::remove_file(&file);
let library = library.map_err(|error| format!("cannot load the library: {error}"))?;
// SAFETY: `ENTRY` has type `EntryFn` in every plugin of this major version.
let entry = unsafe { library.get::<abi::EntryFn>(abi::ENTRY.as_bytes()) }
.map_err(|_| format!("not an opencode-rs plugin: no `{}` symbol", abi::ENTRY))?;
// SAFETY: as above; the table it returns lives as long as the library.
let api = unsafe { entry() };
if api.is_null() {
return Err(format!("`{}` returned no table", abi::ENTRY));
}
// SAFETY: every table of any version starts with `size`, `major`, and `minor`.
let (size, major, minor) = unsafe {
(
std::ptr::addr_of!((*api).size).read(),
std::ptr::addr_of!((*api).major).read(),
std::ptr::addr_of!((*api).minor).read(),
)
};
if major != ABI_MAJOR {
return Err(format!(
"plugin ABI {major}.{minor} is not supported: this opencode-rs loads ABI {ABI_MAJOR}.x plugins \
(up to {ABI_MAJOR}.{HOST_MINOR}); rebuild the plugin against opencode-plugin-abi {ABI_MAJOR}"
));
}
if size < size_of::<PluginApiV1_0>() {
return Err(format!("plugin table is {size} bytes, shorter than the ABI {ABI_MAJOR}.0 core"));
}
// SAFETY: the 1.0 core is within `size`.
let core = unsafe { &*api.cast::<PluginApiV1_0>() };
if core.requires_minor > HOST_MINOR {
return Err(format!(
"plugin needs host ABI {ABI_MAJOR}.{} or newer, this opencode-rs has {ABI_MAJOR}.{HOST_MINOR}; \
update opencode-rs",
core.requires_minor
));
}
let describe = has::<Option<unsafe extern "C" fn(*mut Owned) -> i32>>(
size,
offset_of!(PluginApi, describe),
)
// SAFETY: `size` covers the entry.
.then(|| unsafe { std::ptr::addr_of!((*api).describe).read() })
.flatten();
let opened = Self {
minor,
create: core.create,
call: core.call,
destroy: core.destroy,
free: core.free,
describe,
};
std::mem::forget(library);
Ok(opened)
}
/// The plugin's version, when it has `describe` (1.1).
fn version(&self) -> Option<String> {
let describe = self.describe?;
let mut out = Owned::EMPTY;
// SAFETY: `describe` writes `out`, which `free` takes back.
let (status, bytes) = unsafe {
let status = describe(&mut out);
let bytes = out.to_vec();
(self.free)(out);
(status, bytes)
};
(status == abi::OK)
.then(|| serde_json::from_slice::<abi::Metadata>(&bytes).ok())
.flatten()
.and_then(|metadata| metadata.version)
}
}
/// Whether a table of `size` bytes holds an entry of type `T` at `offset`.
fn has<T>(size: usize, offset: usize) -> bool {
size >= offset + size_of::<T>()
}
/// What the host's callbacks see: the plugin's identity, its storage keys, and effects that wait for the call to
/// return.
struct Ctx<H: Host> {
host: Weak<H>,
id: String,
keys: Vec<String>,
effects: Vec<Effect>,
}
enum Effect {
Toast(Toast, String),
Route(String),
}
/// One plugin instance; dropping it destroys the instance in the plugin.
struct Instance<H: Host> {
library: Rc<Library>,
handle: *mut c_void,
// The plugin keeps pointers to these until `destroy`, so they are boxed and dropped after it.
_api: Box<HostApi>,
ctx: Box<RefCell<Ctx<H>>>,
}
impl<H: Host> Instance<H> {
fn create(
library: &Rc<Library>,
host: Weak<H>,
options: Option<&str>,
) -> Result<(Self, Manifest), String> {
let ctx = Box::new(RefCell::new(Ctx {
host,
id: String::new(),
keys: Vec::new(),
effects: Vec::new(),
}));
let api = Box::new(HostApi {
size: size_of::<HostApi>(),
major: ABI_MAJOR,
minor: HOST_MINOR,
ctx: std::ptr::from_ref::<RefCell<Ctx<H>>>(&ctx).cast_mut().cast(),
call: host_call::<H>,
free: host_free,
});
let mut handle = std::ptr::null_mut();
let mut out = Owned::EMPTY;
let options = options.unwrap_or_default();
// SAFETY: the pointers are valid for the call, and `api` and `ctx` outlive the instance.
let (status, bytes) = unsafe {
let status = (library.create)(&*api, Bytes::new(options.as_bytes()), &mut handle, &mut out);
let bytes = out.to_vec();
(library.free)(out);
(status, bytes)
};
let text = || String::from_utf8_lossy(&bytes).into_owned();
match status {
abi::OK => {}
abi::PANIC => return Err(format!("setup panicked: {}", text())),
_ => return Err(text()),
}
let instance = Self {
library: library.clone(),
handle,
_api: api,
ctx,
};
let manifest: Manifest = serde_json::from_slice(&bytes)
.map_err(|error| format!("setup returned a bad manifest: {error}"))?;
if manifest.id.is_empty() {
return Err("setup returned an empty plugin ID".to_owned());
}
{
let mut ctx = instance.ctx.borrow_mut();
ctx.id = manifest.id.clone();
ctx.keys = manifest.storage.clone();
}
Ok((instance, manifest))
}
/// Sends `request`; a panic is `Err(Some(message))`, an error the plugin returned `Err(None)` after logging.
fn call(&self, request: &Request) -> Result<serde_json::Value, Option<String>> {
let json = serde_json::to_vec(request).map_err(|error| Some(error.to_string()))?;
let mut out = Owned::EMPTY;
// SAFETY: `handle` is live until drop; `out` goes back to the library's `free`.
let (status, bytes) = unsafe {
let status = (self.library.call)(self.handle, Bytes::new(&json), &mut out);
let bytes = out.to_vec();
(self.library.free)(out);
(status, bytes)
};
let text = String::from_utf8_lossy(&bytes);
match status {
abi::OK => serde_json::from_slice(&bytes).map_err(|error| Some(error.to_string())),
abi::PANIC => Err(Some(format!("panicked: {text}"))),
_ => {
log::warn!("plugin {}: {text}", self.ctx.borrow().id);
Err(None)
}
}
}
}
impl<H: Host> Drop for Instance<H> {
fn drop(&mut self) {
// SAFETY: `handle` came from `create` and is destroyed once; the plugin catches its own panics.
unsafe { (self.library.destroy)(self.handle) };
}
}
/// The host's side of [`HostApi::call`]. Catches the host's panics.
unsafe extern "C" fn host_call<H: Host>(ctx: *mut c_void, request: Bytes, out: *mut Owned) -> i32 {
// SAFETY: `ctx` is the `RefCell<Ctx<H>>` this instance was created with; `request` is valid for the call.
let (ctx, request) = unsafe { (&*ctx.cast::<RefCell<Ctx<H>>>(), request.as_slice()) };
let result = catch_unwind(AssertUnwindSafe(|| {
let request: HostRequest = serde_json::from_slice(request).map_err(|error| {
format!("unsupported host request (host ABI {ABI_MAJOR}.{HOST_MINOR}): {error}")
})?;
let mut ctx = ctx
.try_borrow_mut()
.map_err(|_| "the host is busy".to_owned())?;
handle(&mut ctx, request)
}));
let (status, bytes) = match result {
Ok(Ok(value)) => (abi::OK, serde_json::to_vec(&value).unwrap_or_default()),
Ok(Err(error)) => (abi::ERROR, error.into_bytes()),
Err(panic) => (abi::PANIC, abi::panic_message(&*panic).into_bytes()),
};
// SAFETY: `out` is valid for writes during the call.
unsafe { *out = Owned::from_vec(bytes) };
status
}
unsafe extern "C" fn host_free(owned: Owned) {
// SAFETY: the host made `owned` with `Owned::from_vec`.
drop(unsafe { owned.into_vec() });
}
fn handle<H: Host>(ctx: &mut Ctx<H>, request: HostRequest) -> Result<serde_json::Value, String> {
let key = |ctx: &Ctx<H>, key: &str| {
ctx.keys
.iter()
.any(|known| known == key)
.then(|| format!("plugin.{}.{key}", ctx.id))
.ok_or_else(|| format!("storage key {key} was not declared"))
};
match request {
HostRequest::Log { level, message } => {
let level = match level {
abi::Level::Debug => log::Level::Debug,
abi::Level::Info => log::Level::Info,
abi::Level::Warn => log::Level::Warn,
abi::Level::Error => log::Level::Error,
};
log::log!(level, "plugin {}: {message}", ctx.id);
}
HostRequest::Toast { variant, message } => {
let variant = match variant {
abi::Toast::Info => Toast::Info,
abi::Toast::Success => Toast::Success,
abi::Toast::Warning => Toast::Warning,
abi::Toast::Error => Toast::Error,
};
ctx.effects.push(Effect::Toast(variant, message));
}
HostRequest::StorageGet { key: name } => {
let stored = key(ctx, &name)?;
let value = ctx.host.upgrade().and_then(|host| host.storage_read(&stored));
return Ok(serde_json::to_value(value).unwrap_or_default());
}
HostRequest::StorageSet { key: name, value } => {
let stored = key(ctx, &name)?;
let host = ctx.host.upgrade().ok_or("the host is gone")?;
host.storage_write(&stored, &value)?;
}
HostRequest::OpenRoute { name } => ctx.effects.push(Effect::Route(name)),
}
Ok(serde_json::Value::Null)
}
/// One activation's instance, as registrations call it.
struct Guest<H: Host> {
instance: Instance<H>,
busy: Cell<bool>,
failure: Rc<RefCell<Option<String>>>,
host: Weak<H>,
id: String,
}
impl<H: Host> Guest<H> {
/// Sends one request. A failed plugin is not called again; a panic fails it.
fn request<T: DeserializeOwned>(&self, export: &str, request: &Request) -> Option<T> {
if self.failure.borrow().is_some() {
return None;
}
if self.busy.replace(true) {
log::warn!("plugin {}: {export} called while the plugin runs", self.id);
return None;
}
let result = self.instance.call(request);
self.busy.set(false);
let effects = std::mem::take(&mut self.instance.ctx.borrow_mut().effects);
self.apply(effects);
let error = match result {
Ok(value) => {
return serde_json::from_value(value)
.inspect_err(|error| log::warn!("plugin {}: {export}: {error}", self.id))
.ok();
}
Err(None) => return None,
Err(Some(error)) => format!("{export} {error}"),
};
log::error!("plugin {} failed: {error}", self.id);
*self.failure.borrow_mut() = Some(error);
let id = self.id.clone();
self.defer(move |host| {
host.toast(
Toast::Error,
Some(&format!("Plugin failed: {id}")),
"Run /plugins to view details.",
);
});
None
}
/// Applies the effects of a call once the current event is handled, as the host would for a built-in.
fn apply(&self, effects: Vec<Effect>) {
if effects.is_empty() {
return;
}
let id = self.id.clone();
self.defer(move |host| {
for effect in effects {
match effect {
Effect::Toast(variant, message) => host.toast(variant, None, &message),
Effect::Route(name) => host.open_route(&id, &name),
}
}
});
}
fn defer(&self, f: impl FnOnce(&H) + 'static) {
let Some(host) = self.host.upgrade() else {
return;
};
let weak = self.host.clone();
host.app().set_timeout(Duration::ZERO, move |_| {
if let Some(host) = weak.upgrade() {
f(&host);
}
});
}
}
/// Registers what the manifest lists, each calling into `guest`.
fn register<H: Host>(setup: &mut Setup<'_, H>, guest: &Rc<Guest<H>>, manifest: &Manifest) {
let commands: Vec<TuiCommand> = manifest
.commands
.iter()
.map(|command| {
let guest = guest.clone();
let name = command.name.clone();
let mut entry = TuiCommand::new(command.name.clone(), move |input, _| {
let request = Request::Command {
name: name.clone(),
input: input.map(str::to_owned),
};
guest.request::<serde_json::Value>("run-command", &request);
})
.title(command.title.clone())
.bind(command.keybind.clone().map_or(Bind::Default, Bind::Key));
if command.palette {
entry = entry.palette();
}
if let Some(group) = &command.group {
entry = entry.group(group.clone());
}
if let Some(slash) = &command.slash {
entry = entry.slash(Slash {
name: slash.clone(),
aliases: Vec::new(),
arguments: false,
});
}
entry
})
.collect();
if !commands.is_empty() {
setup.layer(KeymapLayer {
mode: Some(GLOBAL_MODE.to_owned()),
commands,
..KeymapLayer::default()
});
}
for language in &manifest.fences {
let guest = guest.clone();
setup.code_block(language.clone(), move |block, theme| {
let request = Request::Fence(abi::Fence {
language: block.language.to_owned(),
info: block.info.to_owned(),
code: block.code.to_owned(),
streaming: block.streaming && !block.closed,
});
let lines = guest
.request::<Option<Vec<Line>>>("render-fence", &request)
.flatten()?;
Some(lines_widget(block.app, theme, &lines, true))
});
}
for (claim, slot) in manifest.slots.iter().enumerate() {
let guest = guest.clone();
let kind = match slot.kind {
abi::SlotKind::Prepend => Kind::Prepend,
abi::SlotKind::Append => Kind::Append,
abi::SlotKind::Before => Kind::Before,
abi::SlotKind::After => Kind::After,
abi::SlotKind::Replace => Kind::Replace,
};
setup.slot(Placement::new(kind, slot.path.clone()), move |host, input| {
let request = Request::Slot {
claim,
session_id: input.session_id.clone(),
};
let lines = guest
.request::<Vec<Line>>("render-slot", &request)
.unwrap_or_default();
Box::new(lines_view(host.app(), &host.theme(), &lines))
});
}
for name in &manifest.routes {
let guest = guest.clone();
let request = Request::Route { name: name.clone() };
setup.route(name.clone(), move |host| {
let lines = guest
.request::<Vec<Line>>("render-route", &request)
.unwrap_or_default();
Box::new(lines_view(host.app(), &host.theme(), &lines))
});
}
}
/// Rows of spans as one no-wrap text. A fence scrolls sideways, as the LaTeX and Mermaid renderers do.
fn lines_widget(app: &App, theme: &Theme, lines: &[Line], scroll: bool) -> AnyWidget {
let width = lines
.iter()
.map(|line| {
line.iter()
.map(|span| unicode_width::UnicodeWidthStr::width(span.text.as_str()))
.sum::<usize>()
})
.max()
.unwrap_or(0);
let height = lines.len().max(1) as f32;
let mut spans: Vec<Span<'static>> = Vec::new();
for (index, line) in lines.iter().enumerate() {
if index > 0 {
spans.push(Span::styled("\n", Style::new().fg(theme.text.base)));
}
spans.extend(line.iter().map(|span| {
let mut attributes = Attributes::NONE;
for (set, attribute) in [
(span.bold, Attributes::BOLD),
(span.italic, Attributes::ITALIC),
(span.underline, Attributes::UNDERLINE),
(span.dim, Attributes::DIM),
] {
if set {
attributes |= attribute;
}
}
let fg = color(theme, span.fg.as_deref()).unwrap_or(theme.text.base);
let mut style = Style::new().fg(fg);
if let Some(bg) = color(theme, span.bg.as_deref()) {
style = style.bg(bg);
}
Span::styled(span.text.clone(), Style { attributes, ..style })
}));
}
let text = Text::new(app, spans)
.width(Length::percent(100.0))
.min_width(width as f32)
.height(height)
.wrap(WrapMode::None)
.selectable(false)
.shrink(0.0);
if !scroll {
return text.as_any();
}
ScrollBox::new(app)
.width(Length::percent(100.0))
.height(height)
.shrink(0.0)
.axes(true, false)
.scrollbars(false)
.child(&text)
.as_any()
}
/// A slot claim or route: the rows in a view, empty when the plugin drew nothing or failed.
fn lines_view(app: &App, theme: &Theme, lines: &[Line]) -> View {
let view = View::new(app).shrink(0.0);
if !lines.is_empty() {
view.add(&lines_widget(app, theme, lines, false));
}
view
}
/// A theme token path, or `#rrggbb`.
fn color(theme: &Theme, value: Option<&str>) -> Option<Color> {
let value = value?;
if let Some(hex) = value.strip_prefix('#').filter(|hex| hex.len() == 6) {
let channel = |index: usize| u8::from_str_radix(&hex[index..index + 2], 16).ok();
return Some(Color::rgb(channel(0)?, channel(2)?, channel(4)?));
}
theme.get(value).copied()
}
#[cfg(test)]
mod tests;
@@ -0,0 +1,220 @@
use std::fs;
use std::path::Path;
use std::process::Command;
use std::rc::Rc;
use std::sync::Mutex;
use std::time::Duration;
use opentui::keymap::RunResult;
use super::*;
use crate::loader::tests::{TestHost, entry, host};
use crate::loader::{Configured, Loader, entry_file};
use crate::{Registry, SlotInput, Status, slot};
/// Builds the sample plugin with `features` and `SAMPLE_VERSION=version` and returns the library. Builds share one
/// target directory, so a lock keeps a build and its read together.
pub(crate) fn build(features: &str, version: &str) -> Vec<u8> {
static LOCK: Mutex<()> = Mutex::new(());
let _lock = LOCK.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
let root = Path::new(env!("CARGO_MANIFEST_DIR"));
let target = root.join("../../target/sample-plugin");
let status = Command::new(std::env::var("CARGO").unwrap_or_else(|_| "cargo".to_owned()))
.args(["build", "--quiet", "--manifest-path"])
.arg(root.join("examples/sample/Cargo.toml"))
.arg("--target-dir")
.arg(&target)
.args(["--features", features])
.env("SAMPLE_VERSION", version)
.status()
.unwrap();
assert!(status.success(), "the sample plugin did not build");
let name = format!(
"{}opencode_sample_plugin{}",
std::env::consts::DLL_PREFIX,
std::env::consts::DLL_SUFFIX
);
fs::read(target.join("debug").join(name)).unwrap()
}
/// The sample, loaded from `library` and active in a fresh registry.
fn active(host: &Rc<TestHost>, library: &[u8]) -> Registry<TestHost> {
let (definition, error) = Backend::<TestHost>::load(&Native, library, None).unwrap();
assert_eq!(definition.id, "sample");
let registry = Registry::new(Vec::new(), []);
registry.load(host, definition.external("sample.so", error));
registry
}
/// The screen after a transcript-like Markdown view draws `markdown` with the registry's renderers.
fn markdown(host: &Rc<TestHost>, registry: &Registry<TestHost>, text: &str) -> String {
let view = opencode_ui::markdown::view(
host.app(),
&host.theme(),
&opencode_ui::code::syntax_theme(&host.theme()),
&registry.code_blocks(&host.theme()),
true,
false,
);
view.set_markdown(text);
host.app().root().clear();
host.app().root().add(&view);
host.app.render();
host.app.text()
}
fn status(registry: &Registry<TestHost>) -> Status {
entry(&registry.entries(), "sample.so").status.clone()
}
#[test]
fn the_sample_registers_a_command_a_fence_a_slot_and_a_route() {
let host = host();
let registry = active(&host, &build("", "v1"));
assert_eq!(status(&registry), Status::Active);
let screen = markdown(&host, &registry, "```sample\nhello\nworld\n```\n");
assert!(screen.contains("SAMPLE v1 HELLO"), "{screen}");
assert!(screen.contains("SAMPLE v1 WORLD"), "{screen}");
// The command writes its storage key and toasts once the current event is done.
assert!(matches!(host.keymap().dispatch("sample.hello", None), RunResult::Ok));
assert!(host.toasts.borrow().is_empty());
host.app.advance(Duration::from_millis(1));
assert_eq!(
*host.toasts.borrow(),
[(Toast::Success, None, "Hello from sample v1 (1)".to_owned())]
);
assert_eq!(
host.storage.borrow().get("plugin.sample.count").map(String::as_str),
Some("{\"count\":1}")
);
assert!(matches!(host.keymap().dispatch("sample.open", None), RunResult::Ok));
host.app.advance(Duration::from_millis(1));
assert_eq!(*host.routes.borrow(), [("sample".to_owned(), "hello".to_owned())]);
let parent = View::new(host.app());
let mounted = registry.mount(&*host, &parent, slot::HOME_FOOTER, &SlotInput::default(), |_| {});
assert!(!mounted.is_empty());
host.app().root().clear();
host.app().root().add(&parent);
let route = registry.route(&*host, "sample", "hello").unwrap();
host.app().root().add(&route.root());
host.app.render();
let screen = host.app.text();
assert!(screen.contains("sample plugin v1: home.footer"), "{screen}");
assert!(screen.contains("Sample route hello"), "{screen}");
assert!(screen.contains("said hello 1 times"), "{screen}");
}
#[test]
fn a_panicking_fence_fails_the_plugin_and_falls_back_to_the_code() {
let host = host();
let registry = active(&host, &build("", "v1"));
let screen = markdown(&host, &registry, "```sample-panic\nboom\n```\n");
assert!(screen.contains("boom"), "{screen}");
assert_eq!(
status(&registry),
Status::Failed("render-fence panicked: sample fence panicked".to_owned())
);
host.app.advance(Duration::from_millis(1));
assert_eq!(
*host.toasts.borrow(),
[(
Toast::Error,
Some("Plugin failed: sample".to_owned()),
"Run /plugins to view details.".to_owned()
)]
);
// A failed plugin is not called again: its fences keep the code view, its commands do nothing.
let screen = markdown(&host, &registry, "```sample\nquiet\n```\n");
assert!(screen.contains("quiet") && !screen.contains("QUIET"), "{screen}");
host.keymap().dispatch("sample.hello", None);
host.app.advance(Duration::from_millis(1));
assert!(host.storage.borrow().is_empty());
// Enabling it again starts a fresh instance.
registry.set_active(&host, "sample", true);
assert_eq!(status(&registry), Status::Active);
let screen = markdown(&host, &registry, "```sample\nback\n```\n");
assert!(screen.contains("SAMPLE v1 BACK"), "{screen}");
}
#[test]
fn a_panicking_command_fails_the_plugin() {
let host = host();
let registry = active(&host, &build("", "v1"));
assert!(matches!(host.keymap().dispatch("sample.panic", None), RunResult::Ok));
assert_eq!(
status(&registry),
Status::Failed("run-command panicked: sample command panicked".to_owned())
);
}
#[test]
fn versions_follow_the_abi_rules() {
let load = |library: &[u8], options: Option<&str>| {
Backend::<TestHost>::load(&Native, library, options).err()
};
// The current build has the 1.1 entry; a 1.0 build has the shorter table and still loads and works.
let current = build("", "v1");
assert_eq!(
Native.inspect(&current).unwrap(),
Inspected {
major: 1,
minor: 1,
version: Some("0.1.0".to_owned()),
}
);
let old = build("abi-1-0", "v1");
assert_eq!(
Native.inspect(&old).unwrap(),
Inspected {
major: 1,
minor: 0,
version: None,
}
);
let host = host();
let registry = active(&host, &old);
let screen = markdown(&host, &registry, "```sample\nold\n```\n");
assert!(screen.contains("SAMPLE v1 OLD"), "{screen}");
// Only a major mismatch, or a plugin that needs a newer host, is refused, with a clear reason.
assert_eq!(
load(&build("major-2", "v1"), None).unwrap(),
"plugin ABI 2.0 is not supported: this opencode-rs loads ABI 1.x plugins (up to 1.1); rebuild the \
plugin against opencode-plugin-abi 1"
);
assert_eq!(
load(&build("requires-future", "v1"), None).unwrap(),
"plugin needs host ABI 1.99 or newer, this opencode-rs has 1.1; update opencode-rs"
);
assert_eq!(load(&current, Some("{\"fail\":true}")).unwrap(), "sample setup failed");
assert!(load(b"not a library", None).unwrap().starts_with("cannot load the library"));
}
#[test]
fn the_loader_reloads_a_rebuilt_library() {
let root = tempfile::tempdir().unwrap();
let config = root.path().join("config");
let dir = config.join("plugins/sample");
fs::create_dir_all(&dir).unwrap();
fs::write(dir.join(entry_file()), build("", "v1")).unwrap();
let host = host();
let registry = Registry::<TestHost>::new(Vec::new(), []);
let loader = Loader::new(
Rc::new(Native) as Rc<dyn Backend<TestHost>>,
config,
root.path().to_path_buf(),
Vec::<Configured>::new(),
);
assert!(loader.reconcile(&host, &registry));
let screen = markdown(&host, &registry, "```sample\nhi\n```\n");
assert!(screen.contains("SAMPLE v1 HI"), "{screen}");
fs::write(dir.join(entry_file()), build("", "v2")).unwrap();
assert!(loader.reconcile(&host, &registry));
let screen = markdown(&host, &registry, "```sample\nhi\n```\n");
assert!(screen.contains("SAMPLE v2 HI"), "{screen}");
assert_eq!(registry.entries().len(), 1);
}
@@ -0,0 +1,355 @@
use std::cell::{Cell, RefCell};
use std::collections::HashMap;
use std::fs;
use std::path::Path;
use std::rc::Rc;
use opencode_ui::dialog::DialogKeymap;
use opencode_ui::keymap::{Keybinds, Options};
use opencode_ui::theme::{Catalog, Theme, ThemeMode};
use opentui::prelude::*;
use opentui::testing::TestApp;
use super::*;
use crate::{Entry, Source, Toast};
/// A host that records what plugins ask of it.
pub(super) struct TestHost {
pub app: TestApp,
keymap: DialogKeymap,
pub storage: RefCell<HashMap<String, String>>,
pub toasts: RefCell<Vec<(Toast, Option<String>, String)>>,
pub routes: RefCell<Vec<(String, String)>>,
pub remounts: Cell<usize>,
}
impl Host for TestHost {
type Changes = ();
fn app(&self) -> &App {
&self.app
}
fn theme(&self) -> Theme {
Catalog::default()
.load("opencode", ThemeMode::Dark)
.unwrap()
.theme
}
fn keymap(&self) -> &DialogKeymap {
&self.keymap
}
fn storage_read(&self, key: &str) -> Option<String> {
self.storage.borrow().get(key).cloned()
}
fn storage_write(&self, key: &str, json: &str) -> Result<(), String> {
self.storage
.borrow_mut()
.insert(key.to_owned(), json.to_owned());
Ok(())
}
fn toast(&self, variant: Toast, title: Option<&str>, message: &str) {
let title = title.map(str::to_owned);
self.toasts
.borrow_mut()
.push((variant, title, message.to_owned()));
}
fn open_route(&self, id: &str, name: &str) {
self.routes
.borrow_mut()
.push((id.to_owned(), name.to_owned()));
}
fn remount(&self) {
self.remounts.set(self.remounts.get() + 1);
}
}
pub(super) fn host() -> Rc<TestHost> {
Rc::new(TestHost {
app: TestApp::new(60, 10),
keymap: DialogKeymap::new(Keybinds::defaults(), Options::default()),
storage: RefCell::default(),
toasts: RefCell::default(),
routes: RefCell::default(),
remounts: Cell::new(0),
})
}
pub(super) fn entry<'a>(entries: &'a [Entry], target: &str) -> &'a Entry {
entries
.iter()
.find(|entry| entry.target.as_deref() == Some(target))
.unwrap_or_else(|| panic!("no entry for {target}: {entries:?}"))
}
/// A backend whose builds are text: `id=<id>` loads a plugin with a `fake` fence that draws nothing, anything
/// else fails with that text.
#[derive(Default)]
struct Fake {
loads: Cell<usize>,
/// Active instances: setup adds one, deactivation removes it.
active: Rc<Cell<i32>>,
}
impl Backend<TestHost> for Fake {
fn load(
&self,
library: &[u8],
options: Option<&str>,
) -> Result<(Definition<TestHost>, ErrorFn), String> {
self.loads.set(self.loads.get() + 1);
let text = String::from_utf8_lossy(library).into_owned();
let id = text
.strip_prefix("id=")
.ok_or(text.clone())?
.trim()
.to_owned();
assert_eq!(options, None);
let active = self.active.clone();
let definition = Definition::new(id, move |setup| {
active.set(active.get() + 1);
let active = active.clone();
setup.on_dispose(move || active.set(active.get() - 1));
setup.code_block("fake", |_, _| None);
});
Ok((definition, Rc::new(|| None)))
}
}
fn write(path: &Path, text: &str) {
fs::create_dir_all(path.parent().unwrap()).unwrap();
fs::write(path, text).unwrap();
}
#[test]
fn plugin_directories_follow_the_project_root_down_to_cwd() {
let root = tempfile::tempdir().unwrap();
let config = root.path().join("config");
let project = root.path().join("repo");
let cwd = project.join("a/b");
fs::create_dir_all(project.join(".git")).unwrap();
fs::create_dir_all(cwd.join(".opencode")).unwrap();
// Above the project root: not searched.
fs::create_dir_all(root.path().join(".opencode")).unwrap();
assert_eq!(
plugin_directories(&config, &cwd),
[
config.join("plugins"),
// The project's own `.opencode` is searched even when missing; `a/.opencode` is not there.
project.join(".opencode/plugins"),
cwd.join(".opencode/plugins"),
]
);
}
#[test]
fn discover_lists_subdirectories_by_name() {
let root = tempfile::tempdir().unwrap();
let plugins = root.path().join("plugins");
for name in ["beta", "Alpha", "gamma"] {
fs::create_dir_all(plugins.join(name)).unwrap();
}
write(&plugins.join(entry_file()), "");
assert_eq!(
discover(&[plugins.clone(), root.path().join("missing")]),
[
plugins.join("Alpha"),
plugins.join("beta"),
plugins.join("gamma")
]
);
}
#[test]
fn local_source_resolves_paths_and_urls_but_not_packages() {
let dir = Path::new("/home/me/.config/opencode");
assert_eq!(
local_source("./plugins/x", dir),
Some(dir.join("plugins/x"))
);
assert_eq!(
local_source("../x.wasm", dir),
Some("/home/me/.config/x.wasm".into())
);
assert_eq!(local_source("/abs/x", dir), Some("/abs/x".into()));
assert_eq!(
local_source("file:///abs/y.wasm", dir),
Some("/abs/y.wasm".into())
);
assert_eq!(local_source("@acme/opencode-tui", dir), None);
}
#[test]
fn reconcile_loads_reloads_keeps_and_unloads() {
let root = tempfile::tempdir().unwrap();
let config = root.path().join("config");
let lib_dir = config.join("plugins/fake");
let ts_dir = config.join("plugins/typescript");
fs::create_dir_all(&ts_dir).unwrap();
write(&lib_dir.join(entry_file()), "id=fake");
let file = root.path().join(format!("extra.{}", std::env::consts::DLL_EXTENSION));
write(&file, "id=extra");
let host = host();
let registry = Registry::<TestHost>::new(Vec::new(), [file.to_str().unwrap(), "@acme/tui"]);
let fake = Rc::new(Fake::default());
let configured = registry
.skipped()
.into_iter()
.map(|target| Configured {
target,
options: None,
})
.collect();
let loader = Loader::new(
fake.clone() as Rc<dyn Backend<TestHost>>,
config.clone(),
root.path().to_path_buf(),
configured,
);
let lib_target = lib_dir.to_string_lossy().into_owned();
let file_target = file.to_string_lossy().into_owned();
let ts_target = ts_dir.to_string_lossy().into_owned();
assert!(loader.reconcile(&host, &registry));
let entries = registry.entries();
assert_eq!(entry(&entries, &lib_target).id, "fake");
assert_eq!(entry(&entries, &lib_target).source, Source::External);
assert_eq!(entry(&entries, &lib_target).status, Status::Active);
assert_eq!(entry(&entries, &file_target).id, "extra");
assert_eq!(
entry(&entries, &ts_target).status,
Status::Skipped(SKIPPED.to_owned())
);
assert_eq!(
entry(&entries, "@acme/tui").status,
Status::Skipped(SKIPPED.to_owned())
);
assert_eq!(fake.active.get(), 2);
assert_eq!(host.remounts.get(), 1);
assert!(loader.watch_dirs().contains(&lib_dir));
// Nothing changed: no load, no remount.
assert!(!loader.reconcile(&host, &registry));
assert_eq!(fake.loads.get(), 2);
// A broken build keeps the running version and says so.
write(&lib_dir.join(entry_file()), "boom");
assert!(loader.reconcile(&host, &registry));
let entries = registry.entries();
assert_eq!(
entry(&entries, &lib_target).status,
Status::Failed("boom (previous version still active)".to_owned())
);
assert_eq!(fake.active.get(), 2);
// The same broken build is not retried.
assert!(!loader.reconcile(&host, &registry));
assert_eq!(fake.loads.get(), 3);
// A fixed build replaces it in place, under its new ID.
write(&lib_dir.join(entry_file()), "id=fake2");
assert!(loader.reconcile(&host, &registry));
let entries = registry.entries();
assert_eq!(entry(&entries, &lib_target).id, "fake2");
assert_eq!(entry(&entries, &lib_target).status, Status::Active);
assert_eq!(
entries
.iter()
.filter(|entry| entry.source == Source::External)
.map(|entry| entry.id.as_str())
.collect::<Vec<_>>(),
["fake2", "extra"]
);
// A removed build unloads; the directory is a TypeScript plugin now.
fs::remove_file(lib_dir.join(entry_file())).unwrap();
assert!(loader.reconcile(&host, &registry));
let entries = registry.entries();
assert_eq!(
entry(&entries, &lib_target).status,
Status::Skipped(SKIPPED.to_owned())
);
assert!(!entries.iter().any(|entry| entry.id == "fake2"));
assert_eq!(fake.active.get(), 1);
}
#[test]
fn a_build_that_never_loaded_is_failed_and_ids_stay_unique() {
let root = tempfile::tempdir().unwrap();
let config = root.path().join("config");
write(&config.join(&format!("plugins/a/{}", entry_file())), "id=same");
write(&config.join(&format!("plugins/b/{}", entry_file())), "id=same");
write(&config.join(&format!("plugins/c/{}", entry_file())), "not a library");
let host = host();
let registry = Registry::<TestHost>::new(Vec::new(), []);
let loader = Loader::new(
Rc::new(Fake::default()) as Rc<dyn Backend<TestHost>>,
config.clone(),
root.path().to_path_buf(),
Vec::new(),
);
loader.reconcile(&host, &registry);
let entries = registry.entries();
let target = |name: &str| {
config
.join("plugins")
.join(name)
.to_string_lossy()
.into_owned()
};
assert_eq!(entry(&entries, &target("a")).status, Status::Active);
assert_eq!(
entry(&entries, &target("b")).status,
Status::Failed("plugin ID same is already registered".to_owned())
);
assert_eq!(
entry(&entries, &target("c")).status,
Status::Failed("not a library".to_owned())
);
assert_eq!(entry(&entries, &target("c")).source, Source::Configured);
}
#[cfg(target_os = "linux")]
const ONE: &str = "./one.so";
#[cfg(target_os = "macos")]
const ONE: &str = "./one.dylib";
#[cfg(windows)]
const ONE: &str = "./one.dll";
#[test]
fn directives_after_an_entry_disable_an_external_plugin() {
let root = tempfile::tempdir().unwrap();
let config = root.path().join("config");
write(&config.join(format!("one.{}", std::env::consts::DLL_EXTENSION)), "id=one");
write(&config.join(&format!("plugins/two/{}", entry_file())), "id=two");
let host = host();
let registry =
Registry::<TestHost>::new(Vec::new(), ["-one", ONE, "-two", "-*", "two"]);
let loader = Loader::new(
Rc::new(Fake::default()) as Rc<dyn Backend<TestHost>>,
config.clone(),
root.path().to_path_buf(),
vec![Configured {
target: ONE.to_owned(),
options: None,
}],
);
loader.reconcile(&host, &registry);
let entries = registry.entries();
let status = |id: &str| {
entries
.iter()
.find(|entry| entry.id == id)
.unwrap()
.status
.clone()
};
// `-one` comes before its entry, `-*` after it; `two` is discovered, so every directive applies.
assert_eq!(status("one"), Status::Inactive);
assert_eq!(status("two"), Status::Active);
}
+5
View File
@@ -56,6 +56,8 @@ pub struct Launch {
pub args: Args,
/// Kept alive while the TUI runs: dropping a standalone connection stops its server.
pub keep: Box<dyn std::any::Any>,
/// External plugins to discover and load (P.4).
pub plugins: Option<crate::plugins::host::External>,
}
/// The shared context. Held as `Rc<Tui>`; widget callbacks keep a [`Weak`].
@@ -472,6 +474,9 @@ pub fn run(launch: Launch) -> opentui::Result<()> {
crate::features::system_commands::mouse_tracking(&launch.deps.config);
let app = App::new(options)?;
let tui = mount_with(&app, launch.deps, launch.args);
if let Some(external) = launch.plugins {
crate::plugins::host::external(&tui, external);
}
// Tests start the editor context with their own source; the real TUI reads the environment.
crate::prompt::editor_context::start(&tui, crate::prompt::editor_context::Source::from_env());
let result = app.run();
@@ -2,7 +2,8 @@
//! `opencode.plugins` with `plugins.list` (`/plugins`).
//!
//! TUI rows come from the plugin registry (`Registry::entries`): built-ins are internal and hidden until
//! `ctrl+a`; a configured TypeScript plugin is listed as `skipped` with the reason as its error (F16). Server rows
//! `ctrl+a`; a configured TypeScript plugin is listed as `skipped` with the reason as its error (F16), and an
//! external WASM plugin that failed to load or crashed as `failed` with its error (P.4). Server rows
//! come from `GET /api/plugin`. Enter toggles a TUI plugin through `Registry::set_active`, then the route mounts
//! again so slots follow; on another row it opens the error, if any.
@@ -329,13 +330,15 @@ impl Manager {
Status::Active => ("active", None),
Status::Inactive => ("inactive", None),
Status::Skipped(reason) => ("skipped", Some(reason.clone())),
Status::Failed(error) => ("failed", Some(error.clone())),
};
let loaded = !matches!(entry.status, Status::Skipped(_));
// Only a plugin with a definition can be toggled; an unloaded target cannot.
let loaded = entry.source != Source::Configured;
Entry::Tui {
key: format!("tui:{}", entry.id),
key: format!("tui:{}", entry.target.as_ref().unwrap_or(&entry.id)),
internal: entry.source == Source::Builtin,
id: loaded.then(|| entry.id.clone()),
target: entry.id,
target: entry.target.unwrap_or(entry.id),
status,
error,
}
+124 -2
View File
@@ -1,16 +1,24 @@
//! The plugin host (P.1, `docs/P.1.md`): the built-in plugins on the plugin API, the `cli.json` `plugins`
//! entries, and the calls the TUI's slots, plugin routes, and Markdown make.
//! entries, external plugins with hot reload (P.4, `docs/P.4.md`), and the calls the TUI's slots, plugin
//! routes, and Markdown make.
use std::cell::RefCell;
use std::path::PathBuf;
use std::rc::Rc;
use std::time::Duration;
use opencode_plugin::{Definition, Registry, SlotInput, SlotMount, Slotted};
use opencode_plugin::loader::native::Native;
use opencode_plugin::loader::{Backend, Configured, Loader};
use opencode_plugin::{Definition, Registry, SlotInput, SlotMount, Slotted, Toast};
use opencode_store::Changes;
use opencode_ui::dialog::DialogKeymap;
use opencode_ui::markdown::CodeBlockRenderers;
use opencode_ui::theme::Theme;
use opencode_ui::toast::{ToastOptions, Variant};
use opentui::prelude::*;
use crate::app::Tui;
use crate::routes::Route;
pub type Plugins = Registry<Tui>;
@@ -28,6 +36,47 @@ impl opencode_plugin::Host for Tui {
fn keymap(&self) -> &DialogKeymap {
&self.keymap
}
fn storage_read(&self, key: &str) -> Option<String> {
let value = self.storage()?.load(key, &serde_json::Value::Null).ok()?;
(!value.is_null()).then(|| value.to_string())
}
fn storage_write(&self, key: &str, json: &str) -> Result<(), String> {
let storage = self.storage().ok_or("this TUI has no storage")?;
let value: serde_json::Value =
serde_json::from_str(json).map_err(|error| error.to_string())?;
storage
.update(key, &serde_json::json!({}), |stored| *stored = value)
.map(|_| ())
.map_err(|error| error.to_string())
}
fn toast(&self, variant: Toast, title: Option<&str>, message: &str) {
let variant = match variant {
Toast::Info => Variant::Info,
Toast::Success => Variant::Success,
Toast::Warning => Variant::Warning,
Toast::Error => Variant::Error,
};
let mut options = ToastOptions::new(variant, message);
if let Some(title) = title {
options = options.title(title);
}
self.toasts.show(options);
}
fn open_route(&self, id: &str, name: &str) {
self.dialogs.clear();
self.navigate(Route::Plugin {
id: id.to_owned(),
name: name.to_owned(),
});
}
fn remount(&self) {
self.navigate(self.route());
}
}
/// The built-ins in TS order (`plugin/builtins.ts`). The storybook (F14) is excepted (Q17).
@@ -67,6 +116,79 @@ pub fn install(tui: &Rc<Tui>) {
tui.plugins.activate(tui);
}
/// What [`external`] needs: the global config directory and the working directory.
pub struct External {
pub config_dir: PathBuf,
pub cwd: PathBuf,
}
/// Posted when a watched plugin directory changed.
struct PluginsChanged;
/// Loads the external native plugins (P.4): the discovered `plugins` directories and the `cli.json` entries that name no
/// built-in. Each change in a watched directory reconciles them again (hot reload), debounced by 100 ms as in TS.
pub fn external(tui: &Rc<Tui>, external: External) {
let options = |target: &str| {
tui.config.info.plugins.iter().flatten().find_map(|plugin| match plugin {
opencode_local::cli_config::Plugin::Package {
package,
options: Some(options),
} if package == target => Some(serde_json::Value::Object(options.clone()).to_string()),
_ => None,
})
};
let configured = tui
.plugins
.skipped()
.into_iter()
.map(|target| Configured {
options: options(&target),
target,
})
.collect();
let loader = Rc::new(Loader::new(
Rc::new(Native) as Rc<dyn Backend<Tui>>,
external.config_dir,
external.cwd,
configured,
));
loader.reconcile(tui, &tui.plugins);
let watches: Rc<RefCell<Vec<(PathBuf, opencode_local::watch::Watch)>>> = Rc::default();
watch(tui, &loader, &watches);
let weak = tui.weak();
tui.app.on_message(move |_, _: &PluginsChanged| {
let Some(tui) = weak.upgrade() else { return };
loader.reconcile(&tui, &tui.plugins);
watch(&tui, &loader, &watches);
});
}
/// Watches the loader's directories that are not watched yet. A watch that stops seeing its directory costs a
/// handle until the TUI exits, as in TS.
fn watch(
tui: &Tui,
loader: &Loader<Tui>,
watches: &RefCell<Vec<(PathBuf, opencode_local::watch::Watch)>>,
) {
for dir in loader.watch_dirs() {
if watches.borrow().iter().any(|(known, _)| *known == dir) {
continue;
}
let proxy = tui.app.proxy();
let watch = opencode_local::watch::watch(
&dir,
|_| true,
Duration::from_millis(100),
move || {
let _ = proxy.send(PluginsChanged);
},
);
if let Some(watch) = watch {
watches.borrow_mut().push((dir, watch));
}
}
}
/// Adds and activates one more plugin, then remounts the route so its claims show.
pub fn add(tui: &Rc<Tui>, plugin: Definition<Tui>) {
tui.plugins.add(plugin);
+72
View File
@@ -0,0 +1,72 @@
# P.4 external plugins (`rs-plugin-loader`)
Row F16. External TUI plugins load as WebAssembly components on `wasmtime` (decision O-7), behind the cargo
feature `plugins-wasm` that only the `opencode-rs` binary turns on (O-40).
## Surface
The contract is `crates/plugin/src/loader/wit/plugin.wit`, world `plugin`. A component cannot hold widgets or
closures, so the P.1 API crosses the boundary as data:
| P.1 (`Setup`) | WIT |
| --- | --- |
| `layer` (commands, palette, slash, keybinds) | `manifest.commands`; the host calls `run-command(name, input)` |
| `code_block(language, render)` | `manifest.fences`; `render-fence(fence) -> option<list<line>>` |
| `slot(placement, render)` | `manifest.slots` (kind and path); `render-slot(path, session-id) -> list<line>` |
| `route(name, render)` | `manifest.routes`; `render-route(name) -> list<line>` |
| `storage_key(key)` | `manifest.storage`; imports `storage-get` and `storage-set` on `plugin.<id>.<key>` |
| `on_dispose` | the instance is dropped on deactivation |
A `line` is a list of spans with text, colors, and bold, italic, underline, and dim. A color is a theme token path
(`text.muted`, `markdown.heading`) or `#rrggbb`, so plugins follow the theme. The host draws rows without
wrapping; a fence scrolls sideways like the LaTeX and Mermaid renderers. Imports: `log`, `toast`, `storage-get`,
`storage-set`, `open-route`. `setup(options)` receives the `options` of the plugin's `plugins` entry as JSON text.
What does not cross: arbitrary widget trees, mouse handlers, and live store access (`api.state`). A slot or route
is drawn when it mounts; it is drawn again when the route remounts (hot reload, toggles, navigation).
## Discovery
The same targets as TS (`plugin/discovery.ts`, `plugin/context.tsx` reconcile):
1. Every subdirectory of the `plugins` directories: the global config directory's, then each `.opencode` from
the project root (nearest `.git` or `.hg`) down to the working directory.
2. Each `cli.json` `plugins` entry that names no built-in. Relative paths start at the config directory.
Merged by local path, a later entry replacing an earlier one. A target has a WASM build when it is a `.wasm`
file, or a directory with `plugin.wasm`. Every other target is a TypeScript plugin and is listed as skipped
(F16). A WASM target in a build without `plugins-wasm` is skipped with that reason.
Server-side TUI plugins (`GET /api/plugin` with `features.tui`) are not loaded: they are TypeScript packages.
## Lifecycle
- `Loader::reconcile` loads new and changed builds (by content digest), unloads removed ones, and remounts the
route when anything changed. A build that fails while a previous version runs keeps the previous version and
reports `… (previous version still active)`, as TS does.
- Hot reload: the TUI watches `Loader::watch_dirs` (the `plugins` directories, each plugin directory, and the
directory of each configured `.wasm`) with `opencode_local::watch` and a 100 ms debounce (TS `context.tsx`),
and reconciles on change. `OPENCODE_FILEWATCHER_DISABLE` turns it off (L09).
- The registry keeps an external plugin's place on reload, so slot order holds. `plugins` directives after its
entry (all of them, for a discovered plugin) decide whether it starts enabled; the plugin manager toggles it.
## Isolation
- Each activation gets a fresh instance with a 64 MiB memory limit.
- Every call runs under an epoch deadline (250 ms; a 10 ms clock thread). A guest that loops is interrupted.
- A trap (panic, interrupt, out of memory) fails the plugin: it is not called again, its fences fall back to the
code view, its slots and routes draw empty, the plugin manager lists it as `failed` with the error, and an
error toast says so. Toggling it in the plugin manager starts a fresh instance.
- Host effects (toasts, routes) run after the call returns, so a guest cannot reenter itself through the host.
## Build cost (O-40)
`opencode-plugin` has the feature `plugins-wasm` (wasmtime with only `runtime`, `cranelift`, and
`component-model`), and `opencode-cli` forwards it. The TUI and UI crates and their tests never enable it, so
their builds do not compile wasmtime. The step report has the release size and build time with and without it.
## Sample
`crates/plugin/examples/sample` is a tiny Rust guest (`wit-bindgen`). `build.sh` builds `sample-v1.wasm` and
`sample-v2.wasm` (they differ in what they draw, for the reload test). Without the `wasm32-wasip2` target it
builds std for `wasm32-unknown-unknown` from rust-src and wraps the module with `wasm-tools component new`.