diff --git a/packages/cli-rs/Cargo.lock b/packages/cli-rs/Cargo.lock index 532e83e6397..952c8cef0c9 100644 --- a/packages/cli-rs/Cargo.lock +++ b/packages/cli-rs/Cargo.lock @@ -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]] diff --git a/packages/cli-rs/Cargo.toml b/packages/cli-rs/Cargo.toml index cc5839c1cbf..1864fe0cd24 100644 --- a/packages/cli-rs/Cargo.toml +++ b/packages/cli-rs/Cargo.toml @@ -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" } diff --git a/packages/cli-rs/crates/cli/Cargo.toml b/packages/cli-rs/crates/cli/Cargo.toml index 766f1d6584f..d582ae2c6e4 100644 --- a/packages/cli-rs/crates/cli/Cargo.toml +++ b/packages/cli-rs/crates/cli/Cargo.toml @@ -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 diff --git a/packages/cli-rs/crates/cli/src/commands/default.rs b/packages/cli-rs/crates/cli/src/commands/default.rs index 5aab9b9f1e1..297c588ceaa 100644 --- a/packages/cli-rs/crates/cli/src/commands/default.rs +++ b/packages/cli-rs/crates/cli/src/commands/default.rs @@ -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(()) } diff --git a/packages/cli-rs/crates/cli/tests/plugins.rs b/packages/cli-rs/crates/cli/tests/plugins.rs new file mode 100644 index 00000000000..5c419041067 --- /dev/null +++ b/packages/cli-rs/crates/cli/tests/plugins.rs @@ -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 { + 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> { + 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, + plugin: std::path::PathBuf, + _root: tempfile::TempDir, +} + +/// The TUI on `route` with the sample's `build` in `/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}"); + } +} diff --git a/packages/cli-rs/crates/plugin-abi/Cargo.toml b/packages/cli-rs/crates/plugin-abi/Cargo.toml new file mode 100644 index 00000000000..c557011d3e7 --- /dev/null +++ b/packages/cli-rs/crates/plugin-abi/Cargo.toml @@ -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 diff --git a/packages/cli-rs/crates/plugin-abi/src/lib.rs b/packages/cli-rs/crates/plugin-abi/src/lib.rs new file mode 100644 index 00000000000..88574bb9850 --- /dev/null +++ b/packages/cli-rs/crates/plugin-abi/src/lib.rs @@ -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) -> 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 { + 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 { + 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::()` 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 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, +} + +/// Everything a plugin registered in its setup. +#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)] +pub struct Manifest { + pub id: String, + pub commands: Vec, + /// The languages of the code fences it renders. + pub fences: Vec, + /// Slot claims, in order; [`Request::Slot`] names one by index. + pub slots: Vec, + pub routes: Vec, + /// Storage keys, stored by the host as `plugin..`. + pub storage: Vec, +} + +/// 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, + pub slash: Option, + pub keybind: Option, + 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, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub bg: Option, + #[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) -> Self { + Self { + text: text.into(), + ..Self::default() + } + } + + pub fn fg(mut self, color: impl Into) -> 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; + +/// 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>`, `Slot` and `Route` → `Vec`, +/// `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, + }, + Route { + name: String, + }, + Command { + name: String, + input: Option, + }, +} + +/// From the plugin to the host. Results: `StorageGet` → `Option` (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 { + 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 { + 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 Option>>; +type SlotFn = Box) -> Vec>; +type RouteFn = Box Vec>; +type CommandFn = Box)>; + +/// 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, + host: Host, + fences: Vec<(String, FenceFn)>, + slots: Vec, + 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> + '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 + '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//`. + pub fn route(&mut self, name: &str, render: impl Fn() -> Vec + 'static) { + self.manifest.routes.push(name.to_owned()); + self.routes.push((name.to_owned(), Box::new(render))); + } + + fn handle(&self, request: Request) -> Result { + let json = |value: Result| 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(®istered.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::(), 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::()) }; + 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, 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::().cloned()) + .unwrap_or_else(|| "a panic without a message".to_owned()) +} diff --git a/packages/cli-rs/crates/plugin/Cargo.toml b/packages/cli-rs/crates/plugin/Cargo.toml index 083df9e41ee..ae8a80bd1b9 100644 --- a/packages/cli-rs/crates/plugin/Cargo.toml +++ b/packages/cli-rs/crates/plugin/Cargo.toml @@ -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 diff --git a/packages/cli-rs/crates/plugin/examples/sample/Cargo.lock b/packages/cli-rs/crates/plugin/examples/sample/Cargo.lock new file mode 100644 index 00000000000..4d6fa0b146d --- /dev/null +++ b/packages/cli-rs/crates/plugin/examples/sample/Cargo.lock @@ -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" diff --git a/packages/cli-rs/crates/plugin/examples/sample/Cargo.toml b/packages/cli-rs/crates/plugin/examples/sample/Cargo.toml new file mode 100644 index 00000000000..de514d57070 --- /dev/null +++ b/packages/cli-rs/crates/plugin/examples/sample/Cargo.toml @@ -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] diff --git a/packages/cli-rs/crates/plugin/examples/sample/src/lib.rs b/packages/cli-rs/crates/plugin/examples/sample/src/lib.rs new file mode 100644 index 00000000000..66f354ecd44 --- /dev/null +++ b/packages/cli-rs/crates/plugin/examples/sample/src/lib.rs @@ -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 { + 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::().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); diff --git a/packages/cli-rs/crates/plugin/src/lib.rs b/packages/cli-rs/crates/plugin/src/lib.rs index 964552bf50b..08266135f94 100644 --- a/packages/cli-rs/crates/plugin/src/lib.rs +++ b/packages/cli-rs/crates/plugin/src/lib.rs @@ -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..`), if stored. + fn storage_read(&self, _key: &str) -> Option { + 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 Slotted for View { pub type SlotRender = Rc Box>>; pub type RouteRender = Rc Box>>; type SetupFn = Rc)>; +/// The current failure of an external plugin, if any. +pub type ErrorFn = Rc Option>; /// Renders a fenced code block in the theme, or returns `None` to keep the default code view. pub type CodeBlockRender = Rc, &Theme) -> Option>; @@ -55,6 +82,8 @@ pub type CodeBlockRender = Rc, &Theme) -> Option { pub id: String, setup: SetupFn, + /// The `plugins` target or discovered path of an external plugin, and its failure. + external: Option<(String, ErrorFn)>, } impl Clone for Definition { @@ -62,6 +91,7 @@ impl Clone for Definition { Self { id: self.id.clone(), setup: self.setup.clone(), + external: self.external.clone(), } } } @@ -71,8 +101,20 @@ impl Definition { 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, 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, pub source: Source, pub status: Status, } @@ -209,10 +257,13 @@ struct Plugin { active: Option<(u64, Registration)>, } -/// 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 { plugins: RefCell>>, - skipped: Vec, + /// Targets that are not loaded, with their status ([`Status::Skipped`] or [`Status::Failed`]). + unloaded: RefCell>, + /// The `plugins` targets, in order, which also enable and disable external plugins as they load. + directives: Vec, activations: Cell, } @@ -233,7 +284,8 @@ impl Registry { }) .collect(); let mut skipped = Vec::new(); - for target in targets { + let directives: Vec = 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 Registry { 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 Registry { }); } - /// The configured entries that were not loaded. - pub fn skipped(&self) -> &[String] { - &self.skipped + /// The entries that were skipped. + pub fn skipped(&self) -> Vec { + 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) { + 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, definition: Definition) { + 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 Registry { /// Activates or deactivates plugin `id` (the plugin manager's toggle); returns whether it exists. pub fn set_active(&self, host: &Rc, 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 Registry { } 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 Registry { 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 Registry { }); } + fn with_target(&self, target: &str, f: impl FnOnce(&mut Plugin) -> T) -> Option { + let mut plugins = self.plugins.borrow_mut(); + plugins + .iter_mut() + .find(|plugin| plugin.definition.target() == Some(target)) + .map(f) + } + fn with_plugin(&self, id: &str, f: impl FnOnce(&mut Plugin) -> T) -> Option { let mut plugins = self.plugins.borrow_mut(); plugins diff --git a/packages/cli-rs/crates/plugin/src/loader/mod.rs b/packages/cli-rs/crates/plugin/src/loader/mod.rs index a8acb621aa2..6fa92f3e979 100644 --- a/packages/cli-rs/crates/plugin/src/loader/mod.rs +++ b/packages/cli-rs/crates/plugin/src/loader/mod.rs @@ -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 { + /// 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, 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, +} + +/// 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, + pub options: Option, +} + +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 { + 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>>, +} + +pub struct Loader { + backend: Rc>, + /// 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, + seen: RefCell>, +} + +impl Loader { + pub fn new( + backend: Rc>, + config_dir: PathBuf, + cwd: PathBuf, + configured: Vec, + ) -> 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 { + 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 = 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 { + let mut dirs: Vec = 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 = 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, registry: &Registry) -> bool { + let targets = self.targets(); + let mut changed = false; + let stale: Vec = 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, registry: &Registry, 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>> = 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, 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 { + let ancestors: Vec = { + let mut ancestors: Vec = 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 = 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 { + directories + .iter() + .flat_map(|directory| { + let mut entries: Vec = 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 { + 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; diff --git a/packages/cli-rs/crates/plugin/src/loader/native.rs b/packages/cli-rs/crates/plugin/src/loader/native.rs new file mode 100644 index 00000000000..a10c8904025 --- /dev/null +++ b/packages/cli-rs/crates/plugin/src/loader/native.rs @@ -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, +} + +impl Native { + /// Opens `library` and checks its version without setting it up. + pub fn inspect(&self, library: &[u8]) -> Result { + let library = Library::open(library)?; + Ok(Inspected { + major: ABI_MAJOR, + minor: library.minor, + version: library.version(), + }) + } +} + +impl Backend for Native { + fn load( + &self, + library: &[u8], + options: Option<&str>, + ) -> Result<(Definition, 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::::create(&library, Weak::new(), options.as_deref())?; + let id = first.1.id.clone(); + let failure: Rc>> = 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 i32>, +} + +impl Library { + fn open(bytes: &[u8]) -> Result { + 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::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::() { + 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::() }; + 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:: 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 { + 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::(&bytes).ok()) + .flatten() + .and_then(|metadata| metadata.version) + } +} + +/// Whether a table of `size` bytes holds an entry of type `T` at `offset`. +fn has(size: usize, offset: usize) -> bool { + size >= offset + size_of::() +} + +/// What the host's callbacks see: the plugin's identity, its storage keys, and effects that wait for the call to +/// return. +struct Ctx { + host: Weak, + id: String, + keys: Vec, + effects: Vec, +} + +enum Effect { + Toast(Toast, String), + Route(String), +} + +/// One plugin instance; dropping it destroys the instance in the plugin. +struct Instance { + library: Rc, + handle: *mut c_void, + // The plugin keeps pointers to these until `destroy`, so they are boxed and dropped after it. + _api: Box, + ctx: Box>>, +} + +impl Instance { + fn create( + library: &Rc, + host: Weak, + 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::(), + major: ABI_MAJOR, + minor: HOST_MINOR, + ctx: std::ptr::from_ref::>>(&ctx).cast_mut().cast(), + call: host_call::, + 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> { + 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 Drop for Instance { + 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(ctx: *mut c_void, request: Bytes, out: *mut Owned) -> i32 { + // SAFETY: `ctx` is the `RefCell>` this instance was created with; `request` is valid for the call. + let (ctx, request) = unsafe { (&*ctx.cast::>>(), 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(ctx: &mut Ctx, request: HostRequest) -> Result { + let key = |ctx: &Ctx, 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 { + instance: Instance, + busy: Cell, + failure: Rc>>, + host: Weak, + id: String, +} + +impl Guest { + /// Sends one request. A failed plugin is not called again; a panic fails it. + fn request(&self, export: &str, request: &Request) -> Option { + 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) { + 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(setup: &mut Setup<'_, H>, guest: &Rc>, manifest: &Manifest) { + let commands: Vec = 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::("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::>>("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::>("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::>("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::() + }) + .max() + .unwrap_or(0); + let height = lines.len().max(1) as f32; + let mut spans: Vec> = 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 { + 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; diff --git a/packages/cli-rs/crates/plugin/src/loader/native/tests.rs b/packages/cli-rs/crates/plugin/src/loader/native/tests.rs new file mode 100644 index 00000000000..9e3d400a927 --- /dev/null +++ b/packages/cli-rs/crates/plugin/src/loader/native/tests.rs @@ -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 { + 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, library: &[u8]) -> Registry { + let (definition, error) = Backend::::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, registry: &Registry, text: &str) -> String { + let view = opencode_ui::markdown::view( + host.app(), + &host.theme(), + &opencode_ui::code::syntax_theme(&host.theme()), + ®istry.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) -> Status { + entry(®istry.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(®istry), Status::Active); + + let screen = markdown(&host, ®istry, "```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, ®istry, "```sample-panic\nboom\n```\n"); + assert!(screen.contains("boom"), "{screen}"); + assert_eq!( + status(®istry), + 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, ®istry, "```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(®istry), Status::Active); + let screen = markdown(&host, ®istry, "```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(®istry), + 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::::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(¤t).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, ®istry, "```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(¤t, 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::::new(Vec::new(), []); + let loader = Loader::new( + Rc::new(Native) as Rc>, + config, + root.path().to_path_buf(), + Vec::::new(), + ); + assert!(loader.reconcile(&host, ®istry)); + let screen = markdown(&host, ®istry, "```sample\nhi\n```\n"); + assert!(screen.contains("SAMPLE v1 HI"), "{screen}"); + fs::write(dir.join(entry_file()), build("", "v2")).unwrap(); + assert!(loader.reconcile(&host, ®istry)); + let screen = markdown(&host, ®istry, "```sample\nhi\n```\n"); + assert!(screen.contains("SAMPLE v2 HI"), "{screen}"); + assert_eq!(registry.entries().len(), 1); +} diff --git a/packages/cli-rs/crates/plugin/src/loader/tests.rs b/packages/cli-rs/crates/plugin/src/loader/tests.rs new file mode 100644 index 00000000000..bf94529db5e --- /dev/null +++ b/packages/cli-rs/crates/plugin/src/loader/tests.rs @@ -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>, + pub toasts: RefCell, String)>>, + pub routes: RefCell>, + pub remounts: Cell, +} + +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 { + 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 { + 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=` loads a plugin with a `fake` fence that draws nothing, anything +/// else fails with that text. +#[derive(Default)] +struct Fake { + loads: Cell, + /// Active instances: setup adds one, deactivation removes it. + active: Rc>, +} + +impl Backend for Fake { + fn load( + &self, + library: &[u8], + options: Option<&str>, + ) -> Result<(Definition, 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::::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>, + 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, ®istry)); + 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, ®istry)); + 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, ®istry)); + 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, ®istry)); + 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, ®istry)); + 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::>(), + ["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, ®istry)); + 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::::new(Vec::new(), []); + let loader = Loader::new( + Rc::new(Fake::default()) as Rc>, + config.clone(), + root.path().to_path_buf(), + Vec::new(), + ); + loader.reconcile(&host, ®istry); + 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::::new(Vec::new(), ["-one", ONE, "-two", "-*", "two"]); + let loader = Loader::new( + Rc::new(Fake::default()) as Rc>, + config.clone(), + root.path().to_path_buf(), + vec![Configured { + target: ONE.to_owned(), + options: None, + }], + ); + loader.reconcile(&host, ®istry); + 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); +} diff --git a/packages/cli-rs/crates/tui/src/app.rs b/packages/cli-rs/crates/tui/src/app.rs index 9bf6b58733f..e515ee7e764 100644 --- a/packages/cli-rs/crates/tui/src/app.rs +++ b/packages/cli-rs/crates/tui/src/app.rs @@ -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, + /// External plugins to discover and load (P.4). + pub plugins: Option, } /// The shared context. Held as `Rc`; 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(); diff --git a/packages/cli-rs/crates/tui/src/dialogs/plugins.rs b/packages/cli-rs/crates/tui/src/dialogs/plugins.rs index 7d3e04619df..0aeb1a17c8e 100644 --- a/packages/cli-rs/crates/tui/src/dialogs/plugins.rs +++ b/packages/cli-rs/crates/tui/src/dialogs/plugins.rs @@ -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, } diff --git a/packages/cli-rs/crates/tui/src/plugins/host.rs b/packages/cli-rs/crates/tui/src/plugins/host.rs index d02e2a6a47d..61679bd5428 100644 --- a/packages/cli-rs/crates/tui/src/plugins/host.rs +++ b/packages/cli-rs/crates/tui/src/plugins/host.rs @@ -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; @@ -28,6 +36,47 @@ impl opencode_plugin::Host for Tui { fn keymap(&self) -> &DialogKeymap { &self.keymap } + + fn storage_read(&self, key: &str) -> Option { + 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.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, 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>, + external.config_dir, + external.cwd, + configured, + )); + loader.reconcile(tui, &tui.plugins); + let watches: Rc>> = 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, + watches: &RefCell>, +) { + 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, plugin: Definition) { tui.plugins.add(plugin); diff --git a/packages/cli-rs/docs/P.4.md b/packages/cli-rs/docs/P.4.md new file mode 100644 index 00000000000..c411432bcd9 --- /dev/null +++ b/packages/cli-rs/docs/P.4.md @@ -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>` | +| `slot(placement, render)` | `manifest.slots` (kind and path); `render-slot(path, session-id) -> list` | +| `route(name, render)` | `manifest.routes`; `render-route(name) -> list` | +| `storage_key(key)` | `manifest.storage`; imports `storage-get` and `storage-set` on `plugin..` | +| `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`.