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        let _ = theme;
33    }
34    fn on_user_update(&mut self, _user: Option<&User>) {}
35    fn status_hints(&self) -> Vec<(String, String)> {
36        vec![]
37    }
38    /// Palette commands that this plugin registers (category, label).
39    fn commands(&self) -> Vec<PluginCmdItem> {
40        vec![]
41    }
42    /// Called when a palette command from this plugin is selected.
43    /// `index` is the position in `commands()`.
44    fn handle_palette_command(&mut self, _index: usize) {}
45
46    /// Called when a plugin-to-plugin message arrives.
47    fn on_plugin_message(&mut self, _from: &str, _action: &str, _data: &str) {}
48
49    /// Called before the plugin is unloaded (hot-reload or app exit).
50    /// The plugin should flush state, close handles, and prepare to be dropped.
51    /// For IPC plugins this sends `Shutdown` and waits briefly for a response
52    /// before the child process is killed.
53    fn shutdown(&mut self) {}
54
55    /// Return the filesystem path to this plugin's binary, if it runs as an
56    /// external process.  `None` for in-process plugins.  Used by the hot-reload
57    /// mechanism to detect when the binary has been updated on disk.
58    fn binary_path(&self) -> Option<&Path> {
59        None
60    }
61}
62
63pub struct PluginContext {
64    pub theme: Theme,
65    pub auth: Option<Arc<dyn AuthHandle>>,
66    /// Santui data directory (e.g. `~/.santui`). Plugins can use this
67    /// for persistent storage. The registry plugin uses it to find
68    /// installed plugins and `registry.toml`.
69    pub data_dir: PathBuf,
70}
71
72impl PluginContext {
73    pub fn new() -> Self {
74        PluginContext {
75            theme: Theme::default(),
76            auth: None,
77            data_dir: PathBuf::new(),
78        }
79    }
80}
81
82impl Default for PluginContext {
83    fn default() -> Self {
84        Self::new()
85    }
86}
santui_core/plugin.rs

santui_core/
plugin.rs
