fresh_core/

hooks.rs

//! Hook System: Event subscription and notification for plugins
//!
//! Hooks allow plugins to subscribe to editor events and react to them.

use anyhow::Result;
use std::collections::HashMap;
use std::ops::Range;
use std::path::PathBuf;

use crate::action::Action;
use crate::api::{ViewTokenWire, ViewTokenWireKind};
use crate::{BufferId, CursorId, SplitId};

/// Arguments passed to hook callbacks
#[derive(Debug, Clone, serde::Serialize)]
pub enum HookArgs {
    /// Before a file is opened
    BeforeFileOpen { path: PathBuf },

    /// After a file is successfully opened
    AfterFileOpen { buffer_id: BufferId, path: PathBuf },

    /// Before a buffer is saved to disk
    BeforeFileSave { buffer_id: BufferId, path: PathBuf },

    /// After a buffer is successfully saved
    AfterFileSave { buffer_id: BufferId, path: PathBuf },

    /// A buffer was closed
    BufferClosed { buffer_id: BufferId },

    /// Before text is inserted
    BeforeInsert {
        buffer_id: BufferId,
        position: usize,
        text: String,
    },

    /// After text was inserted
    AfterInsert {
        buffer_id: BufferId,
        position: usize,
        text: String,
        /// Byte position where the affected range starts
        affected_start: usize,
        /// Byte position where the affected range ends (after the inserted text)
        affected_end: usize,
        /// Line number where insertion occurred (0-indexed)
        start_line: usize,
        /// Line number where insertion ended (0-indexed)
        end_line: usize,
        /// Number of lines added by this insertion
        lines_added: usize,
    },

    /// Before text is deleted
    BeforeDelete {
        buffer_id: BufferId,
        range: Range<usize>,
    },

    /// After text was deleted
    AfterDelete {
        buffer_id: BufferId,
        range: Range<usize>,
        deleted_text: String,
        /// Byte position where the deletion occurred
        affected_start: usize,
        /// Length of the deleted content in bytes
        deleted_len: usize,
        /// Line number where deletion started (0-indexed)
        start_line: usize,
        /// Line number where deletion ended (0-indexed, in original buffer)
        end_line: usize,
        /// Number of lines removed by this deletion
        lines_removed: usize,
    },

    /// Cursor moved to a new position
    CursorMoved {
        buffer_id: BufferId,
        cursor_id: CursorId,
        old_position: usize,
        new_position: usize,
        /// Line number at new position (1-indexed)
        line: usize,
        /// Text properties at the new cursor position
        text_properties: Vec<std::collections::HashMap<String, serde_json::Value>>,
    },

    /// Buffer became active
    BufferActivated { buffer_id: BufferId },

    /// Buffer was deactivated
    BufferDeactivated { buffer_id: BufferId },

    /// LSP diagnostics were updated for a file
    DiagnosticsUpdated {
        /// The URI of the file that was updated
        uri: String,
        /// Number of diagnostics in the update
        count: usize,
    },

    /// Before a command/action is executed
    PreCommand { action: Action },

    /// After a command/action was executed
    PostCommand { action: Action },

    /// Editor has been idle for N milliseconds (no input)
    Idle { milliseconds: u64 },

    /// Editor is initializing
    EditorInitialized,

    /// All plugin packages + init.ts have been loaded. Fires after the
    /// plugin discovery loop and before session restore — the lifecycle
    /// hook for code that wants to configure a plugin via its
    /// getPluginApi(...) surface. See design §3.3 (phase 2).
    PluginsLoaded,

    /// Editor has completed startup: plugins are loaded, session is
    /// restored, and the active buffer exists. Design §3.3 (phase 3).
    Ready,

    /// Rendering is starting for a buffer (called once per buffer before render_line hooks)
    RenderStart { buffer_id: BufferId },

    /// A line is being rendered (called during the rendering pass)
    RenderLine {
        buffer_id: BufferId,
        line_number: usize,
        byte_start: usize,
        byte_end: usize,
        content: String,
    },

    /// Lines have changed and need processing (batched for efficiency)
    LinesChanged {
        buffer_id: BufferId,
        lines: Vec<LineInfo>,
    },

    /// Prompt input changed (user typed/edited)
    PromptChanged { prompt_type: String, input: String },

    /// Prompt was confirmed (user pressed Enter)
    PromptConfirmed {
        prompt_type: String,
        input: String,
        selected_index: Option<usize>,
    },

    /// Prompt was cancelled (user pressed Escape/Ctrl+G)
    PromptCancelled { prompt_type: String, input: String },

    /// Prompt suggestion selection changed (user navigated with Up/Down)
    PromptSelectionChanged {
        prompt_type: String,
        selected_index: usize,
    },

    /// Request keyboard shortcuts data (key, action) for the help buffer
    KeyboardShortcuts { bindings: Vec<(String, String)> },

    /// LSP find references response received
    LspReferences {
        /// The symbol name being queried
        symbol: String,
        /// The locations where the symbol is referenced
        locations: Vec<LspLocation>,
    },

    /// View transform request
    ViewTransformRequest {
        buffer_id: BufferId,
        split_id: SplitId,
        /// Byte offset of the viewport start
        viewport_start: usize,
        /// Byte offset of the viewport end
        viewport_end: usize,
        /// Base tokens (Text, Newline, Space) from the source
        tokens: Vec<ViewTokenWire>,
        /// Byte positions of all cursors in this buffer
        cursor_positions: Vec<usize>,
    },

    /// Mouse click event
    MouseClick {
        /// Column (x coordinate) in screen cells
        column: u16,
        /// Row (y coordinate) in screen cells
        row: u16,
        /// Mouse button: "left", "right", "middle"
        button: String,
        /// Modifier keys
        modifiers: String,
        /// Content area X offset
        content_x: u16,
        /// Content area Y offset
        content_y: u16,
        /// Buffer under the click (None when the click is outside any
        /// buffer panel).
        buffer_id: Option<u64>,
        /// 0-indexed buffer row (line number) of the click, accounting
        /// for scroll. None when the click is outside any buffer.
        buffer_row: Option<u32>,
        /// 0-indexed byte column inside the buffer row. None when the
        /// click is outside any buffer.
        buffer_col: Option<u32>,
    },

    /// Mouse move/hover event
    MouseMove {
        /// Column (x coordinate) in screen cells
        column: u16,
        /// Row (y coordinate) in screen cells
        row: u16,
        /// Content area X offset
        content_x: u16,
        /// Content area Y offset
        content_y: u16,
    },

    /// LSP server request (server -> client)
    LspServerRequest {
        /// The language/server that sent the request
        language: String,
        /// The JSON-RPC method name
        method: String,
        /// The server command used to spawn this LSP
        server_command: String,
        /// The request parameters as a JSON string
        params: Option<String>,
    },

    /// Viewport changed (scrolled or resized)
    ViewportChanged {
        split_id: SplitId,
        buffer_id: BufferId,
        top_byte: usize,
        top_line: Option<usize>,
        width: u16,
        height: u16,
    },

    /// LSP server failed to start or crashed
    LspServerError {
        /// The language that failed
        language: String,
        /// The server command that failed
        server_command: String,
        /// Error type: "not_found", "spawn_failed", "timeout", "crash"
        error_type: String,
        /// Human-readable error message
        message: String,
    },

    /// User clicked the LSP status indicator
    LspStatusClicked {
        /// The language of the current buffer
        language: String,
        /// Whether there's an active error
        has_error: bool,
        /// Commands of configured servers whose binaries are not on `$PATH`
        /// (or absolute-path equivalents). Empty when every configured
        /// server is installed. Plugins can inspect this to show tailored
        /// install hints without waiting for a failed spawn.
        missing_servers: Vec<String>,
        /// Whether the user previously dismissed the LSP pill for this
        /// language (via the popup's "Disable" action). Plugins seeing
        /// this as `true` should offer "Enable" / "Install" rather than
        /// "Start".
        user_dismissed: bool,
    },

    /// User selected an action from an action popup
    ActionPopupResult {
        /// The popup ID
        popup_id: String,
        /// The action ID selected, or "dismissed"
        action_id: String,
    },

    /// Background process output (streaming)
    ProcessOutput {
        /// The process ID
        process_id: u64,
        /// The output data
        data: String,
    },

    /// Buffer language was changed (e.g. via "Set Language" command or Save-As)
    LanguageChanged {
        buffer_id: BufferId,
        /// The new language identifier (e.g., "markdown", "rust", "text")
        language: String,
    },

    /// Request to inspect a theme key in the theme editor
    ThemeInspectKey {
        /// The name of the current theme
        theme_name: String,
        /// The theme key to inspect (e.g. "editor.bg")
        key: String,
    },

    /// Mouse scroll event (wheel up/down)
    MouseScroll {
        buffer_id: BufferId,
        /// Scroll delta: negative = up, positive = down (typically ±3)
        delta: i32,
        /// Mouse column (0-based, terminal origin top-left)
        col: u16,
        /// Mouse row (0-based, terminal origin top-left)
        row: u16,
    },

    /// Terminal was resized
    Resize { width: u16, height: u16 },

    /// Terminal focus was gained (e.g. user switched back to the editor)
    FocusGained,
}

/// Information about a single line for the LinesChanged hook
#[derive(Debug, Clone, serde::Serialize)]
pub struct LineInfo {
    /// Line number (0-based)
    pub line_number: usize,
    /// Byte offset where the line starts in the buffer
    pub byte_start: usize,
    /// Byte offset where the line ends (exclusive)
    pub byte_end: usize,
    /// The content of the line
    pub content: String,
}

/// Location information for LSP references
#[derive(Debug, Clone, serde::Serialize)]
pub struct LspLocation {
    /// File path
    pub file: String,
    /// Line number (1-based)
    pub line: u32,
    /// Column number (1-based)
    pub column: u32,
}

/// Type for hook callbacks
pub type HookCallback = Box<dyn Fn(&HookArgs) -> bool + Send + Sync>;

/// Registry for managing hooks
pub struct HookRegistry {
    /// Map from hook name to list of callbacks
    hooks: HashMap<String, Vec<HookCallback>>,
}

impl HookRegistry {
    /// Create a new hook registry
    pub fn new() -> Self {
        Self {
            hooks: HashMap::new(),
        }
    }

    /// Add a hook callback for a specific hook name
    pub fn add_hook(&mut self, name: &str, callback: HookCallback) {
        self.hooks
            .entry(name.to_string())
            .or_default()
            .push(callback);
    }

    /// Remove all hooks for a specific name
    pub fn remove_hooks(&mut self, name: &str) {
        self.hooks.remove(name);
    }

    /// Run all hooks for a specific name
    pub fn run_hooks(&self, name: &str, args: &HookArgs) -> bool {
        if let Some(hooks) = self.hooks.get(name) {
            for callback in hooks {
                if !callback(args) {
                    return false;
                }
            }
        }
        true
    }

    /// Get count of registered callbacks for a hook
    pub fn hook_count(&self, name: &str) -> usize {
        self.hooks.get(name).map(|v| v.len()).unwrap_or(0)
    }

    /// Get all registered hook names
    pub fn hook_names(&self) -> Vec<String> {
        self.hooks.keys().cloned().collect()
    }
}

impl Default for HookRegistry {
    fn default() -> Self {
        Self::new()
    }
}

/// Convert HookArgs to a serde_json::Value for plugin communication
pub fn hook_args_to_json(args: &HookArgs) -> Result<serde_json::Value> {
    let json_value = match args {
        HookArgs::RenderStart { buffer_id } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
            })
        }
        HookArgs::RenderLine {
            buffer_id,
            line_number,
            byte_start,
            byte_end,
            content,
        } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "line_number": line_number,
                "byte_start": byte_start,
                "byte_end": byte_end,
                "content": content,
            })
        }
        HookArgs::BufferActivated { buffer_id } => {
            serde_json::json!({ "buffer_id": buffer_id.0 })
        }
        HookArgs::BufferDeactivated { buffer_id } => {
            serde_json::json!({ "buffer_id": buffer_id.0 })
        }
        HookArgs::DiagnosticsUpdated { uri, count } => {
            serde_json::json!({
                "uri": uri,
                "count": count,
            })
        }
        HookArgs::BufferClosed { buffer_id } => {
            serde_json::json!({ "buffer_id": buffer_id.0 })
        }
        HookArgs::CursorMoved {
            buffer_id,
            cursor_id,
            old_position,
            new_position,
            line,
            text_properties,
        } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "cursor_id": cursor_id.0,
                "old_position": old_position,
                "new_position": new_position,
                "line": line,
                "text_properties": text_properties,
            })
        }
        HookArgs::BeforeInsert {
            buffer_id,
            position,
            text,
        } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "position": position,
                "text": text,
            })
        }
        HookArgs::AfterInsert {
            buffer_id,
            position,
            text,
            affected_start,
            affected_end,
            start_line,
            end_line,
            lines_added,
        } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "position": position,
                "text": text,
                "affected_start": affected_start,
                "affected_end": affected_end,
                "start_line": start_line,
                "end_line": end_line,
                "lines_added": lines_added,
            })
        }
        HookArgs::BeforeDelete { buffer_id, range } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "start": range.start,
                "end": range.end,
            })
        }
        HookArgs::AfterDelete {
            buffer_id,
            range,
            deleted_text,
            affected_start,
            deleted_len,
            start_line,
            end_line,
            lines_removed,
        } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "start": range.start,
                "end": range.end,
                "deleted_text": deleted_text,
                "affected_start": affected_start,
                "deleted_len": deleted_len,
                "start_line": start_line,
                "end_line": end_line,
                "lines_removed": lines_removed,
            })
        }
        HookArgs::BeforeFileOpen { path } => {
            serde_json::json!({ "path": path.to_string_lossy() })
        }
        HookArgs::AfterFileOpen { path, buffer_id } => {
            serde_json::json!({
                "path": path.to_string_lossy(),
                "buffer_id": buffer_id.0,
            })
        }
        HookArgs::BeforeFileSave { path, buffer_id } => {
            serde_json::json!({
                "path": path.to_string_lossy(),
                "buffer_id": buffer_id.0,
            })
        }
        HookArgs::AfterFileSave { path, buffer_id } => {
            serde_json::json!({
                "path": path.to_string_lossy(),
                "buffer_id": buffer_id.0,
            })
        }
        HookArgs::PreCommand { action } => {
            serde_json::json!({ "action": format!("{:?}", action) })
        }
        HookArgs::PostCommand { action } => {
            serde_json::json!({ "action": format!("{:?}", action) })
        }
        HookArgs::Idle { milliseconds } => {
            serde_json::json!({ "milliseconds": milliseconds })
        }
        HookArgs::EditorInitialized => {
            serde_json::json!({})
        }
        HookArgs::PluginsLoaded => {
            serde_json::json!({})
        }
        HookArgs::Ready => {
            serde_json::json!({})
        }
        HookArgs::PromptChanged { prompt_type, input } => {
            serde_json::json!({
                "prompt_type": prompt_type,
                "input": input,
            })
        }
        HookArgs::PromptConfirmed {
            prompt_type,
            input,
            selected_index,
        } => {
            serde_json::json!({
                "prompt_type": prompt_type,
                "input": input,
                "selected_index": selected_index,
            })
        }
        HookArgs::PromptCancelled { prompt_type, input } => {
            serde_json::json!({
                "prompt_type": prompt_type,
                "input": input,
            })
        }
        HookArgs::PromptSelectionChanged {
            prompt_type,
            selected_index,
        } => {
            serde_json::json!({
                "prompt_type": prompt_type,
                "selected_index": selected_index,
            })
        }
        HookArgs::KeyboardShortcuts { bindings } => {
            let entries: Vec<serde_json::Value> = bindings
                .iter()
                .map(|(key, action)| serde_json::json!({ "key": key, "action": action }))
                .collect();
            serde_json::json!({ "bindings": entries })
        }
        HookArgs::LspReferences { symbol, locations } => {
            let locs: Vec<serde_json::Value> = locations
                .iter()
                .map(|loc| {
                    serde_json::json!({
                        "file": loc.file,
                        "line": loc.line,
                        "column": loc.column,
                    })
                })
                .collect();
            serde_json::json!({ "symbol": symbol, "locations": locs })
        }
        HookArgs::LinesChanged { buffer_id, lines } => {
            let lines_json: Vec<serde_json::Value> = lines
                .iter()
                .map(|line| {
                    serde_json::json!({
                        "line_number": line.line_number,
                        "byte_start": line.byte_start,
                        "byte_end": line.byte_end,
                        "content": line.content,
                    })
                })
                .collect();
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "lines": lines_json,
            })
        }
        HookArgs::ViewTransformRequest {
            buffer_id,
            split_id,
            viewport_start,
            viewport_end,
            tokens,
            cursor_positions,
        } => {
            let tokens_json: Vec<serde_json::Value> = tokens
                .iter()
                .map(|token| {
                    let kind_json = match &token.kind {
                        ViewTokenWireKind::Text(s) => serde_json::json!({ "Text": s }),
                        ViewTokenWireKind::Newline => serde_json::json!("Newline"),
                        ViewTokenWireKind::Space => serde_json::json!("Space"),
                        ViewTokenWireKind::Break => serde_json::json!("Break"),
                        ViewTokenWireKind::BinaryByte(b) => serde_json::json!({ "BinaryByte": b }),
                    };
                    serde_json::json!({
                        "source_offset": token.source_offset,
                        "kind": kind_json,
                    })
                })
                .collect();
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "split_id": split_id.0,
                "viewport_start": viewport_start,
                "viewport_end": viewport_end,
                "tokens": tokens_json,
                "cursor_positions": cursor_positions,
            })
        }
        HookArgs::MouseClick {
            column,
            row,
            button,
            modifiers,
            content_x,
            content_y,
            buffer_id,
            buffer_row,
            buffer_col,
        } => {
            serde_json::json!({
                "column": column,
                "row": row,
                "button": button,
                "modifiers": modifiers,
                "content_x": content_x,
                "content_y": content_y,
                "buffer_id": buffer_id,
                "buffer_row": buffer_row,
                "buffer_col": buffer_col,
            })
        }
        HookArgs::MouseMove {
            column,
            row,
            content_x,
            content_y,
        } => {
            serde_json::json!({
                "column": column,
                "row": row,
                "content_x": content_x,
                "content_y": content_y,
            })
        }
        HookArgs::LspServerRequest {
            language,
            method,
            server_command,
            params,
        } => {
            serde_json::json!({
                "language": language,
                "method": method,
                "server_command": server_command,
                "params": params,
            })
        }
        HookArgs::ViewportChanged {
            split_id,
            buffer_id,
            top_byte,
            top_line,
            width,
            height,
        } => {
            serde_json::json!({
                "split_id": split_id.0,
                "buffer_id": buffer_id.0,
                "top_byte": top_byte,
                "top_line": top_line,
                "width": width,
                "height": height,
            })
        }
        HookArgs::LspServerError {
            language,
            server_command,
            error_type,
            message,
        } => {
            serde_json::json!({
                "language": language,
                "server_command": server_command,
                "error_type": error_type,
                "message": message,
            })
        }
        HookArgs::LspStatusClicked {
            language,
            has_error,
            missing_servers,
            user_dismissed,
        } => {
            serde_json::json!({
                "language": language,
                "has_error": has_error,
                "missing_servers": missing_servers,
                "user_dismissed": user_dismissed,
            })
        }
        HookArgs::ActionPopupResult {
            popup_id,
            action_id,
        } => {
            serde_json::json!({
                "popup_id": popup_id,
                "action_id": action_id,
            })
        }
        HookArgs::ProcessOutput { process_id, data } => {
            serde_json::json!({
                "process_id": process_id,
                "data": data,
            })
        }
        HookArgs::LanguageChanged {
            buffer_id,
            language,
        } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "language": language,
            })
        }
        HookArgs::ThemeInspectKey { theme_name, key } => {
            serde_json::json!({
                "theme_name": theme_name,
                "key": key,
            })
        }
        HookArgs::MouseScroll {
            buffer_id,
            delta,
            col,
            row,
        } => {
            serde_json::json!({
                "buffer_id": buffer_id.0,
                "delta": delta,
                "col": col,
                "row": row,
            })
        }
        HookArgs::Resize { width, height } => {
            serde_json::json!({
                "width": width,
                "height": height,
            })
        }
        HookArgs::FocusGained => {
            serde_json::json!({})
        }
    };

    Ok(json_value)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::atomic::{AtomicUsize, Ordering};
    use std::sync::Arc;

    fn noop_true() -> HookCallback {
        Box::new(|_| true)
    }

    /// Adding, listing, counting, and removing hooks behave consistently:
    /// counts match the number added, names reflect the keys, and removal
    /// purges all callbacks for that key.
    #[test]
    fn add_count_list_remove_round_trip() {
        let mut reg = HookRegistry::new();
        assert_eq!(reg.hook_count("a"), 0);
        assert!(reg.hook_names().is_empty());

        reg.add_hook("a", noop_true());
        reg.add_hook("a", noop_true());
        reg.add_hook("b", noop_true());

        assert_eq!(reg.hook_count("a"), 2);
        assert_eq!(reg.hook_count("b"), 1);
        assert_eq!(reg.hook_count("missing"), 0);

        let mut names = reg.hook_names();
        names.sort();
        assert_eq!(names, vec!["a".to_string(), "b".to_string()]);

        reg.remove_hooks("a");
        assert_eq!(reg.hook_count("a"), 0);
        assert_eq!(reg.hook_count("b"), 1);
        assert_eq!(reg.hook_names(), vec!["b".to_string()]);
    }

    /// `run_hooks` returns true iff every callback returned true, short-circuits
    /// on the first `false`, and returns true for hook names with no callbacks.
    #[test]
    fn run_hooks_all_true_and_short_circuits_on_false() {
        let mut reg = HookRegistry::new();
        let args = HookArgs::EditorInitialized;

        // Unknown hook: treated as "no callbacks" → true.
        assert!(reg.run_hooks("unknown", &args));

        // All-true chain returns true and calls every callback.
        let calls = Arc::new(AtomicUsize::new(0));
        for _ in 0..3 {
            let c = calls.clone();
            reg.add_hook(
                "all_true",
                Box::new(move |_| {
                    c.fetch_add(1, Ordering::SeqCst);
                    true
                }),
            );
        }
        assert!(reg.run_hooks("all_true", &args));
        assert_eq!(calls.load(Ordering::SeqCst), 3);

        // Short-circuits on the first `false` — the second callback must not run.
        let calls = Arc::new(AtomicUsize::new(0));
        let c1 = calls.clone();
        reg.add_hook(
            "short",
            Box::new(move |_| {
                c1.fetch_add(1, Ordering::SeqCst);
                false
            }),
        );
        let c2 = calls.clone();
        reg.add_hook(
            "short",
            Box::new(move |_| {
                c2.fetch_add(1, Ordering::SeqCst);
                true
            }),
        );
        assert!(!reg.run_hooks("short", &args));
        assert_eq!(calls.load(Ordering::SeqCst), 1);
    }

    /// `hook_args_to_json` produces an object with the expected field for
    /// a representative variant — ensuring the function actually serializes
    /// the payload instead of returning a default (null) value.
    #[test]
    fn hook_args_to_json_serializes_payload_fields() {
        let json = hook_args_to_json(&HookArgs::DiagnosticsUpdated {
            uri: "file:///x.rs".into(),
            count: 7,
        })
        .unwrap();
        assert_eq!(json["uri"], "file:///x.rs");
        assert_eq!(json["count"], 7);
    }
}