santui_core/
plugin.rs

1use crate::auth::{AuthHandle, User};
2use crate::theme::Theme;
3use crossterm::event::KeyEvent;
4use ratatui::layout::Rect;
5use ratatui::Frame;
6use std::path::{Path, PathBuf};
7use std::sync::Arc;
8
9/// Factory that creates a `Box<dyn Plugin>` from an id, name, and binary path.
10/// The binary (`santui`) sets this to `IpcPluginHost::new_boxed`.
11pub type PluginFactory = Arc<dyn Fn(&str, &str, &Path) -> Box<dyn Plugin + Send> + Send + Sync>;
12
13/// A command that a plugin registers for the Ctrl+P palette.
14#[derive(Debug, Clone)]
15pub struct PluginCmdItem {
16    pub category: String,
17    pub label: String,
18}
19
20pub trait Plugin: Send {
21    fn id(&self) -> &str;
22    fn name(&self) -> &str;
23    fn init(&mut self, ctx: &mut PluginContext) -> Result<(), Box<dyn std::error::Error>>;
24    fn handle_key(&mut self, _key: KeyEvent) -> bool {
25        false
26    }
27    fn render(&self, _f: &mut Frame, _area: Rect) {}
28    fn tick(&mut self) {}
29    fn on_focus(&mut self) {}
30    fn on_blur(&mut self) {}
31    fn on_theme_change(&mut self, _theme: &Theme) {}
32    fn on_user_update(&mut self, _user: Option<&User>) {}
33    fn status_hints(&self) -> Vec<(String, String)> {
34        vec![]
35    }
36    /// Palette commands that this plugin registers (category, label).
37    fn commands(&self) -> Vec<PluginCmdItem> {
38        vec![]
39    }
40    /// Called when a palette command from this plugin is selected.
41    /// `index` is the position in `commands()`.
42    fn handle_palette_command(&mut self, _index: usize) {}
43
44    /// Called when a plugin-to-plugin message arrives.
45    fn on_plugin_message(&mut self, _from: &str, _action: &str, _data: &str) {}
46
47    /// Called before the plugin is unloaded (hot-reload or app exit).
48    /// The plugin should flush state, close handles, and prepare to be dropped.
49    /// For IPC plugins this sends `Shutdown` and waits briefly for a response
50    /// before the child process is killed.
51    fn shutdown(&mut self) {}
52
53    /// Return the filesystem path to this plugin's binary, if it runs as an
54    /// external process.  `None` for in-process plugins.  Used by the hot-reload
55    /// mechanism to detect when the binary has been updated on disk.
56    fn binary_path(&self) -> Option<&Path> {
57        None
58    }
59
60    /// Whether the plugin process is still running.
61    /// Returns `true` for in-process plugins.
62    /// IPC plugins override this to check the child process.
63    fn is_alive(&self) -> bool {
64        true
65    }
66}
67
68pub struct PluginContext {
69    pub theme: Theme,
70    pub auth: Option<Arc<dyn AuthHandle>>,
71    /// Santui data directory (e.g. `~/.santui`). Plugins can use this
72    /// for persistent storage. The registry plugin uses it to find
73    /// installed plugins and `registry.toml`.
74    pub data_dir: PathBuf,
75}
76
77impl PluginContext {
78    pub fn new() -> Self {
79        PluginContext {
80            theme: Theme::default(),
81            auth: None,
82            data_dir: PathBuf::new(),
83        }
84    }
85}
86
87impl Default for PluginContext {
88    fn default() -> Self {
89        Self::new()
90    }
91}
santui_core/plugin.rs

santui_core/
plugin.rs
