guth_cli/

lib.rs

//! Shared external-plugin discovery and dispatch for Guth.

use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;
use std::ffi::{OsStr, OsString};
use std::fs;
use std::io::{self, Read, Write};
use std::os::fd::AsRawFd;
use std::os::unix::ffi::{OsStrExt, OsStringExt};
use std::path::{Path, PathBuf};
use std::process::{Child, Command, ExitStatus, Stdio};
use std::sync::mpsc::{self, Receiver};
use std::thread;
use std::time::{Duration, Instant};
use uuid::{Uuid, Variant, Version};

pub const MANIFEST_SCHEMA: u32 = 1;
pub const ACTION_MANIFEST_SCHEMA: u32 = 2;
pub const ACTION_PROTOCOL_VERSION: u32 = 1;
pub const ACTION_CONTRIBUTION_CAPABILITY: &str = "gui-actions";
pub const ACTION_PROTOCOL_ARGUMENT: &str = "--guth-action-protocol";
pub const MANIFEST_BYTES_LIMIT: u64 = 64 * 1024;
pub const PLUGIN_LIMIT: usize = 64;
pub const ENABLED_PLUGIN_BYTES_LIMIT: u64 = 8 * 1024;
pub const PLUGIN_DIAGNOSTIC_LIMIT: usize = 64;
pub const PLUGIN_ACTION_LIMIT: usize = 32;
pub const PLUGIN_ACTION_SELECTION_LIMIT: usize = 256;
pub const PLUGIN_ACTION_IO_BYTES_LIMIT: usize = 48 * 1024;
pub const PLUGIN_ACTION_INVOKE_TIMEOUT: Duration = Duration::from_secs(5 * 60);
const PLUGIN_DIRECTORY_ENTRY_LIMIT: usize = 4096;
const PLUGIN_OUTPUT_BYTES_LIMIT: usize = 64 * 1024;
const PLUGIN_PATH_BYTES_LIMIT: usize = 4096;
const PLUGIN_ACTION_EXTENSION_LIMIT: usize = 32;
const PLUGIN_ACTION_PROBE_TIMEOUT: Duration = Duration::from_secs(2);
const PLUGIN_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(2);
const PLUGIN_SHUTDOWN_POLL_INTERVAL: Duration = Duration::from_millis(25);
const PLUGIN_OUTPUT_DRAIN_TIMEOUT: Duration = Duration::from_millis(250);
const PLUGIN_SPAWN_BUSY_RETRIES: usize = 6;
const PLUGIN_SPAWN_BUSY_RETRY_DELAY: Duration = Duration::from_millis(10);

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginManifest {
    pub schema: u32,
    pub id: Uuid,
    pub name: String,
    pub version: String,
    pub executable: PathBuf,
    pub description: String,
    pub capabilities: Vec<String>,
}

impl PluginManifest {
    /// Validates the schema-1 command-manifest wire contract.
    ///
    /// Schema-2 GUI-action documents must be represented by and validated as
    /// [`PluginActionManifest`]. Discovery projects either schema into this
    /// metadata type; action-specific dispatch validates a schema-2 projection
    /// together with its contribution declaration.
    pub fn validate(&self) -> io::Result<()> {
        if self.schema != MANIFEST_SCHEMA {
            return Err(invalid_data("unsupported plugin manifest schema"));
        }
        self.validate_common()
    }

    fn validate_common(&self) -> io::Result<()> {
        validate_plugin_id(self.id)?;
        validate_text(&self.name, "plugin name", 80)?;
        validate_text(&self.version, "plugin version", 32)?;
        validate_text(&self.description, "plugin description", 280)?;
        if !self.executable.is_absolute() {
            return Err(invalid_data("plugin executable must be an absolute path"));
        }
        if self.capabilities.is_empty() || self.capabilities.len() > 16 {
            return Err(invalid_data("plugin must declare 1 to 16 capabilities"));
        }
        let mut seen = BTreeSet::new();
        for capability in &self.capabilities {
            validate_token(capability, "plugin capability")?;
            if !seen.insert(capability) {
                return Err(invalid_data("plugin capabilities must be unique"));
            }
        }
        Ok(())
    }

    pub fn supports(&self, capability: &str) -> bool {
        self.capabilities
            .iter()
            .any(|candidate| candidate == capability)
    }
}

/// A schema-2 plugin manifest that opts into Guth's external GUI-action protocol.
///
/// Schema-1 [`PluginManifest`] documents remain unchanged. Keeping this as a
/// separate wire type means older plugin authors do not need to add a field to
/// existing Rust struct literals, while discovery can normalize both schemas to
/// [`PluginManifest`] for metadata and enabled-state APIs.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionManifest {
    pub schema: u32,
    pub id: Uuid,
    pub name: String,
    pub version: String,
    pub executable: PathBuf,
    pub description: String,
    pub capabilities: Vec<String>,
    pub contributions: PluginContributions,
}

impl PluginActionManifest {
    pub fn validate(&self) -> io::Result<()> {
        if self.schema != ACTION_MANIFEST_SCHEMA {
            return Err(invalid_data(
                "GUI action manifests must use manifest schema 2",
            ));
        }
        let plugin = self.plugin();
        plugin.validate_common()?;
        if !plugin.supports(ACTION_CONTRIBUTION_CAPABILITY) {
            return Err(invalid_data(
                "GUI action manifests must declare the gui-actions capability",
            ));
        }
        self.contributions.validate()
    }

    pub fn plugin(&self) -> PluginManifest {
        PluginManifest {
            schema: self.schema,
            id: self.id,
            name: self.name.clone(),
            version: self.version.clone(),
            executable: self.executable.clone(),
            description: self.description.clone(),
            capabilities: self.capabilities.clone(),
        }
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginContributions {
    pub actions: PluginActionContribution,
}

impl PluginContributions {
    fn validate(&self) -> io::Result<()> {
        self.actions.validate()
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionContribution {
    pub protocol: u32,
}

impl PluginActionContribution {
    pub fn validate(&self) -> io::Result<()> {
        if self.protocol != ACTION_PROTOCOL_VERSION {
            return Err(invalid_data("unsupported GUI action protocol version"));
        }
        Ok(())
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
pub struct DiscoveredActionContribution {
    pub plugin_id: Uuid,
    pub declaration: PluginActionContribution,
}

/// Lossless, bounded representation of a Linux path on the JSON protocol wire.
/// `display` is presentation-only; `unix_bytes_hex` is the authoritative path.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginProtocolPath {
    pub display: String,
    pub unix_bytes_hex: String,
}

impl PluginProtocolPath {
    pub fn from_path(path: &Path) -> io::Result<Self> {
        validate_protocol_path(path)?;
        Ok(Self {
            display: path.to_string_lossy().into_owned(),
            unix_bytes_hex: encode_hex(path.as_os_str().as_bytes()),
        })
    }

    pub fn to_path_buf(&self) -> io::Result<PathBuf> {
        let bytes = decode_hex(&self.unix_bytes_hex)?;
        let path = PathBuf::from(OsString::from_vec(bytes));
        validate_protocol_path(&path)?;
        if self.display != path.to_string_lossy() {
            return Err(invalid_data(
                "plugin protocol path display text does not match its bytes",
            ));
        }
        Ok(path)
    }

    fn validate(&self) -> io::Result<()> {
        self.to_path_buf().map(|_| ())
    }
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum PluginActionTargetKind {
    File,
    Directory,
    Symlink,
    Other,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionTarget {
    pub path: PluginProtocolPath,
    pub kind: PluginActionTargetKind,
    pub extension: Option<String>,
}

impl PluginActionTarget {
    pub fn from_path(path: &Path, kind: PluginActionTargetKind) -> io::Result<Self> {
        let extension = path
            .extension()
            .and_then(OsStr::to_str)
            .filter(|extension| validate_extension(extension).is_ok())
            .map(str::to_ascii_lowercase);
        Ok(Self {
            path: PluginProtocolPath::from_path(path)?,
            kind,
            extension,
        })
    }

    fn validate(&self) -> io::Result<()> {
        self.path.validate()?;
        if let Some(extension) = &self.extension {
            validate_extension(extension)?;
            if extension.bytes().any(|byte| byte.is_ascii_uppercase()) {
                return Err(invalid_data(
                    "plugin action target extensions must be lowercase",
                ));
            }
        }
        Ok(())
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionContext {
    pub current_directory: PluginProtocolPath,
    pub selection: Vec<PluginActionTarget>,
}

impl PluginActionContext {
    pub fn new(current_directory: &Path, selection: Vec<PluginActionTarget>) -> io::Result<Self> {
        let context = Self {
            current_directory: PluginProtocolPath::from_path(current_directory)?,
            selection,
        };
        context.validate()?;
        Ok(context)
    }

    pub fn validate(&self) -> io::Result<()> {
        self.current_directory.validate()?;
        if self.selection.len() > PLUGIN_ACTION_SELECTION_LIMIT {
            return Err(invalid_data(format!(
                "plugin action selection exceeds the {PLUGIN_ACTION_SELECTION_LIMIT}-item limit"
            )));
        }
        let mut paths = BTreeSet::new();
        for target in &self.selection {
            target.validate()?;
            if !paths.insert(&target.path.unix_bytes_hex) {
                return Err(invalid_data("plugin action selection paths must be unique"));
            }
        }
        Ok(())
    }
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum PluginActionPlacement {
    ContextMenu,
    CommandPalette,
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum PluginActionIcon {
    Plugin,
    Tool,
    Convert,
    Sync,
    Share,
    Archive,
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum PluginActionCategory {
    Tools,
    Organize,
    Convert,
    Sync,
    Share,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionMatcher {
    pub min_selection: u16,
    pub max_selection: u16,
    pub kinds: Vec<PluginActionTargetKind>,
    pub extensions: Vec<String>,
}

impl PluginActionMatcher {
    pub fn validate(&self) -> io::Result<()> {
        if self.min_selection > self.max_selection
            || usize::from(self.max_selection) > PLUGIN_ACTION_SELECTION_LIMIT
        {
            return Err(invalid_data("invalid plugin action selection bounds"));
        }
        if self.kinds.len() > 4 || !all_unique(&self.kinds) {
            return Err(invalid_data(
                "plugin action target kinds must be unique and bounded",
            ));
        }
        if self.extensions.len() > PLUGIN_ACTION_EXTENSION_LIMIT {
            return Err(invalid_data("too many plugin action extensions"));
        }
        let mut extensions = BTreeSet::new();
        for extension in &self.extensions {
            validate_extension(extension)?;
            if extension.bytes().any(|byte| byte.is_ascii_uppercase())
                || !extensions.insert(extension)
            {
                return Err(invalid_data(
                    "plugin action extensions must be unique lowercase values",
                ));
            }
        }
        if !self.extensions.is_empty() && self.max_selection == 0 {
            return Err(invalid_data(
                "extension-matched plugin actions must accept a selection",
            ));
        }
        Ok(())
    }

    pub fn matches(&self, context: &PluginActionContext) -> bool {
        if self.validate().is_err() || context.validate().is_err() {
            return false;
        }
        let selection_count = context.selection.len();
        if selection_count < usize::from(self.min_selection)
            || selection_count > usize::from(self.max_selection)
        {
            return false;
        }
        if !self.kinds.is_empty()
            && context
                .selection
                .iter()
                .any(|target| !self.kinds.contains(&target.kind))
        {
            return false;
        }
        if !self.extensions.is_empty() && context.selection.is_empty() {
            return false;
        }
        self.extensions.is_empty()
            || context.selection.iter().all(|target| {
                target
                    .extension
                    .as_ref()
                    .is_some_and(|extension| self.extensions.contains(extension))
            })
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionMetadata {
    pub id: String,
    pub label: String,
    pub description: String,
    pub category: PluginActionCategory,
    pub icon: PluginActionIcon,
    pub placements: Vec<PluginActionPlacement>,
    pub matcher: PluginActionMatcher,
    pub destructive: bool,
    pub confirmation: Option<String>,
}

impl PluginActionMetadata {
    pub fn validate(&self) -> io::Result<()> {
        validate_token(&self.id, "plugin action ID")?;
        validate_text(&self.label, "plugin action label", 80)?;
        validate_text(&self.description, "plugin action description", 280)?;
        if self.placements.is_empty() || self.placements.len() > 2 || !all_unique(&self.placements)
        {
            return Err(invalid_data(
                "plugin action placements must contain 1 to 2 unique values",
            ));
        }
        if let Some(confirmation) = &self.confirmation {
            validate_text(confirmation, "plugin action confirmation", 180)?;
        }
        if self.destructive && self.confirmation.is_none() {
            return Err(invalid_data(
                "destructive plugin actions must provide confirmation text",
            ));
        }
        self.matcher.validate()
    }

    pub fn matches_context(&self, context: &PluginActionContext) -> bool {
        self.validate().is_ok() && self.matcher.matches(context)
    }
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum PluginActionOperation {
    Probe,
    Invoke,
}

impl PluginActionOperation {
    fn argument(self) -> &'static str {
        match self {
            Self::Probe => "probe",
            Self::Invoke => "invoke",
        }
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionProbeRequest {
    pub protocol: u32,
    pub plugin_id: Uuid,
    pub operation: PluginActionOperation,
    pub context: PluginActionContext,
}

impl PluginActionProbeRequest {
    /// Validates a decoded probe request against the executable's own plugin ID.
    pub fn validate(&self, expected_plugin_id: Uuid) -> io::Result<()> {
        validate_protocol_identity(self.protocol, self.plugin_id, expected_plugin_id)?;
        if self.operation != PluginActionOperation::Probe {
            return Err(invalid_data(
                "plugin action probe request has the wrong operation",
            ));
        }
        self.context.validate()
    }
}

/// Parses the bounded JSON request received by a plugin in `probe` mode.
///
/// Pass a locked stdin handle and the executable's manifest UUID. The helper
/// reads at most [`PLUGIN_ACTION_IO_BYTES_LIMIT`] plus one sentinel byte, then
/// rejects oversized or malformed JSON, protocol/UUID confusion, an `invoke`
/// operation, and invalid or duplicate context paths.
pub fn parse_plugin_action_probe_request(
    input: impl Read,
    expected_plugin_id: Uuid,
) -> io::Result<PluginActionProbeRequest> {
    let request: PluginActionProbeRequest = parse_plugin_protocol_request(input, "probe")?;
    request.validate(expected_plugin_id)?;
    Ok(request)
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionProbeResponse {
    pub protocol: u32,
    pub plugin_id: Uuid,
    pub actions: Vec<PluginActionMetadata>,
}

impl PluginActionProbeResponse {
    pub fn validate(&self, expected_plugin_id: Uuid) -> io::Result<()> {
        validate_protocol_identity(self.protocol, self.plugin_id, expected_plugin_id)?;
        if self.actions.len() > PLUGIN_ACTION_LIMIT {
            return Err(invalid_data(format!(
                "plugin action probe exceeds the {PLUGIN_ACTION_LIMIT}-action limit"
            )));
        }
        let mut ids = BTreeSet::new();
        for action in &self.actions {
            action.validate()?;
            if !ids.insert(&action.id) {
                return Err(invalid_data("plugin action IDs must be unique"));
            }
        }
        Ok(())
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionInvokeRequest {
    pub protocol: u32,
    pub plugin_id: Uuid,
    pub operation: PluginActionOperation,
    pub action_id: String,
    pub context: PluginActionContext,
}

impl PluginActionInvokeRequest {
    /// Validates a decoded invocation, including membership in the plugin's
    /// bounded list of action IDs returned by its probe implementation.
    pub fn validate(
        &self,
        expected_plugin_id: Uuid,
        allowed_action_ids: &[&str],
    ) -> io::Result<()> {
        validate_protocol_identity(self.protocol, self.plugin_id, expected_plugin_id)?;
        if self.operation != PluginActionOperation::Invoke {
            return Err(invalid_data(
                "plugin action invocation request has the wrong operation",
            ));
        }
        validate_token(&self.action_id, "plugin action invocation ID")?;
        validate_allowed_action_ids(allowed_action_ids)?;
        if !allowed_action_ids.contains(&self.action_id.as_str()) {
            return Err(invalid_data(
                "plugin action invocation requested an unsupported action ID",
            ));
        }
        self.context.validate()
    }
}

/// Parses the bounded JSON request received by a plugin in `invoke` mode.
///
/// `allowed_action_ids` must contain the plugin's complete set of at most
/// [`PLUGIN_ACTION_LIMIT`] unique, valid action IDs. This prevents a validly
/// shaped request from dispatching an undeclared action.
pub fn parse_plugin_action_invoke_request(
    input: impl Read,
    expected_plugin_id: Uuid,
    allowed_action_ids: &[&str],
) -> io::Result<PluginActionInvokeRequest> {
    let request: PluginActionInvokeRequest = parse_plugin_protocol_request(input, "invocation")?;
    request.validate(expected_plugin_id, allowed_action_ids)?;
    Ok(request)
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum PluginActionOutcome {
    Completed,
    Cancelled,
    Failed,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PluginActionResult {
    pub protocol: u32,
    pub plugin_id: Uuid,
    pub action_id: String,
    pub outcome: PluginActionOutcome,
    pub message: Option<String>,
    pub refresh: bool,
}

impl PluginActionResult {
    pub fn validate(&self, expected_plugin_id: Uuid, expected_action_id: &str) -> io::Result<()> {
        validate_protocol_identity(self.protocol, self.plugin_id, expected_plugin_id)?;
        validate_token(&self.action_id, "plugin action result ID")?;
        if self.action_id != expected_action_id {
            return Err(invalid_data(
                "plugin action result does not match the invoked action",
            ));
        }
        if let Some(message) = &self.message {
            validate_text(message, "plugin action result message", 280)?;
        }
        if self.outcome == PluginActionOutcome::Failed && self.message.is_none() {
            return Err(invalid_data(
                "failed plugin action results must include a message",
            ));
        }
        Ok(())
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PluginDiagnostic {
    pub path: PathBuf,
    pub message: String,
}

#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct PluginDiscoveryReport {
    pub plugins: Vec<PluginManifest>,
    pub action_contributions: Vec<DiscoveredActionContribution>,
    pub diagnostics: Vec<PluginDiagnostic>,
    pub diagnostics_limited: bool,
    /// Whether an entry error or safety limit prevented discovery from
    /// examining every candidate. Partial reports are suitable for
    /// diagnostics, but must not be used to rewrite enabled-plugin state.
    pub scan_truncated: bool,
}

pub fn plugin_data_dir() -> PathBuf {
    std::env::var_os("XDG_DATA_HOME")
        .map(PathBuf::from)
        .unwrap_or_else(|| home_dir().join(".local/share"))
        .join("guth/plugins")
}

pub fn enabled_plugins_path() -> PathBuf {
    std::env::var_os("XDG_CONFIG_HOME")
        .map(PathBuf::from)
        .unwrap_or_else(|| home_dir().join(".config"))
        .join("guth/enabled-plugins.conf")
}

/// Loads the persisted enabled IDs without discovering plugins or pruning stale entries.
pub fn load_enabled_plugins() -> io::Result<BTreeSet<Uuid>> {
    load_enabled_plugins_from(&enabled_plugins_path())
}

fn load_enabled_plugins_from(path: &Path) -> io::Result<BTreeSet<Uuid>> {
    let file = match open_verified_file(path, false, true) {
        Ok(file) => file,
        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(BTreeSet::new()),
        Err(error) => return Err(error),
    };
    let metadata = file.metadata()?;
    if metadata.len() > ENABLED_PLUGIN_BYTES_LIMIT {
        return Err(invalid_data("enabled plugin file is too large"));
    }
    let mut bytes = Vec::with_capacity(metadata.len() as usize);
    file.take(ENABLED_PLUGIN_BYTES_LIMIT + 1)
        .read_to_end(&mut bytes)?;
    let text = std::str::from_utf8(&bytes)
        .map_err(|_| invalid_data("enabled plugin file must be UTF-8"))?;
    let mut enabled = BTreeSet::new();
    for line in text.lines() {
        if line.is_empty() {
            continue;
        }
        let id = parse_plugin_id(line)?;
        if !enabled.insert(id) || enabled.len() > PLUGIN_LIMIT {
            return Err(invalid_data("enabled plugin file contains invalid entries"));
        }
    }
    Ok(enabled)
}

pub fn set_plugin_enabled(id: Uuid, enabled: bool) -> io::Result<()> {
    validate_plugin_id(id)?;
    let path = enabled_plugins_path();
    let directory_file = lock_enabled_plugin_directory(&path)?;
    let mut ids = load_enabled_plugins_from(&path)?;
    if enabled {
        if ids.len() >= PLUGIN_LIMIT && !ids.contains(&id) {
            return Err(invalid_data("enabled plugin limit reached"));
        }
        ids.insert(id);
    } else {
        ids.remove(&id);
    }
    write_enabled_plugins_locked(&ids, &path, &directory_file)
}

pub fn prune_uninstalled_enabled_plugins() -> io::Result<BTreeSet<Uuid>> {
    let plugin_directory = plugin_data_dir();
    if let Some(parent) = plugin_directory.parent() {
        create_private_dir(parent)?;
    }
    let plugin_directory_file = create_private_dir(&plugin_directory)?;
    rustix::fs::flock(
        &plugin_directory_file,
        rustix::fs::FlockOperation::LockExclusive,
    )
    .map_err(errno_error)?;
    let installed = discover_plugins_in(&plugin_directory)?
        .into_iter()
        .map(|plugin| plugin.id)
        .collect::<BTreeSet<_>>();
    let path = enabled_plugins_path();
    let directory_file = lock_enabled_plugin_directory(&path)?;
    let mut ids = load_enabled_plugins_from(&path)?;
    let original_len = ids.len();
    ids.retain(|id| installed.contains(id));
    if ids.len() != original_len {
        write_enabled_plugins_locked(&ids, &path, &directory_file)?;
    }
    Ok(ids)
}

pub fn discover_plugins() -> io::Result<Vec<PluginManifest>> {
    require_complete_discovery(discover_plugins_with_diagnostics()?)
}

pub fn discover_plugins_in(directory: &Path) -> io::Result<Vec<PluginManifest>> {
    require_complete_discovery(discover_plugins_in_with_diagnostics(directory)?)
}

pub fn discover_plugins_with_diagnostics() -> io::Result<PluginDiscoveryReport> {
    discover_plugins_in_with_diagnostics(&plugin_data_dir())
}

pub fn discover_plugins_in_with_diagnostics(directory: &Path) -> io::Result<PluginDiscoveryReport> {
    let mut manifests = Vec::new();
    let mut action_contributions = Vec::new();
    let mut diagnostics = Vec::new();
    let mut diagnostics_limited = false;
    let mut scan_truncated = false;
    let entries = match fs::read_dir(directory) {
        Ok(entries) => entries,
        Err(error) if error.kind() == io::ErrorKind::NotFound => {
            return Ok(PluginDiscoveryReport::default())
        }
        Err(error) => return Err(error),
    };
    let mut paths = Vec::new();
    for (index, entry) in entries.enumerate() {
        if index >= PLUGIN_DIRECTORY_ENTRY_LIMIT {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                directory.to_path_buf(),
                format!(
                    "Plugin directory scan stopped after {PLUGIN_DIRECTORY_ENTRY_LIMIT} entries; remove stale or unrelated files and refresh"
                ),
            );
            diagnostics_limited = true;
            scan_truncated = true;
            break;
        }
        let entry = match entry {
            Ok(entry) => entry,
            Err(error) => {
                scan_truncated = true;
                push_plugin_diagnostic(
                    &mut diagnostics,
                    &mut diagnostics_limited,
                    directory.to_path_buf(),
                    format!("Could not inspect directory entry: {error}"),
                );
                continue;
            }
        };
        let path = entry.path();
        let is_json = path
            .extension()
            .and_then(|extension| extension.to_str())
            .is_some_and(|extension| extension.eq_ignore_ascii_case("json"));
        if !is_json {
            continue;
        }
        if path
            .extension()
            .is_some_and(|extension| extension != "json")
        {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                "Manifest filename must use the lowercase .json extension".to_string(),
            );
            continue;
        }
        let Some(stem) = path.file_stem().and_then(|stem| stem.to_str()) else {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                "Manifest filename must be a canonical lowercase UUIDv7 followed by .json"
                    .to_string(),
            );
            continue;
        };
        let Ok(id) = Uuid::parse_str(stem) else {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                "Manifest filename must be a canonical lowercase UUIDv7 followed by .json"
                    .to_string(),
            );
            continue;
        };
        if validate_plugin_id(id).is_err() || id.to_string() != stem {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                "Manifest filename must be a canonical lowercase UUIDv7 followed by .json"
                    .to_string(),
            );
            continue;
        }
        paths.push((id, path));
    }
    paths.sort();
    if paths.len() > PLUGIN_LIMIT {
        scan_truncated = true;
        push_plugin_diagnostic(
            &mut diagnostics,
            &mut diagnostics_limited,
            directory.to_path_buf(),
            format!(
                "Plugin limit reached: discovered {} candidates, loaded at most {PLUGIN_LIMIT}",
                paths.len()
            ),
        );
    }
    for (expected_id, path) in paths.into_iter().take(PLUGIN_LIMIT) {
        let file = match open_verified_file(&path, false, true) {
            Ok(file) => file,
            Err(error) => {
                push_plugin_diagnostic(
                    &mut diagnostics,
                    &mut diagnostics_limited,
                    path,
                    format!("Manifest is not a safe private file: {error}"),
                );
                continue;
            }
        };
        let metadata = match file.metadata() {
            Ok(metadata) => metadata,
            Err(error) => {
                push_plugin_diagnostic(
                    &mut diagnostics,
                    &mut diagnostics_limited,
                    path,
                    format!("Could not inspect manifest metadata: {error}"),
                );
                continue;
            }
        };
        if metadata.len() > MANIFEST_BYTES_LIMIT {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                format!("Manifest exceeds the {MANIFEST_BYTES_LIMIT}-byte limit"),
            );
            continue;
        }
        let mut bytes = Vec::with_capacity(metadata.len() as usize);
        if let Err(error) = file.take(MANIFEST_BYTES_LIMIT + 1).read_to_end(&mut bytes) {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                format!("Could not read manifest: {error}"),
            );
            continue;
        }
        #[derive(Deserialize)]
        struct SchemaProbe {
            schema: u32,
        }
        let schema = match serde_json::from_slice::<SchemaProbe>(&bytes) {
            Ok(probe) => probe.schema,
            Err(error) => {
                push_plugin_diagnostic(
                    &mut diagnostics,
                    &mut diagnostics_limited,
                    path,
                    format!("Manifest JSON is invalid: {error}"),
                );
                continue;
            }
        };
        let (manifest, action_contribution) = match schema {
            MANIFEST_SCHEMA => match serde_json::from_slice::<PluginManifest>(&bytes) {
                Ok(manifest) => (manifest, None),
                Err(error) => {
                    push_plugin_diagnostic(
                        &mut diagnostics,
                        &mut diagnostics_limited,
                        path,
                        format!("Manifest JSON is invalid: {error}"),
                    );
                    continue;
                }
            },
            ACTION_MANIFEST_SCHEMA => {
                let action_manifest = match serde_json::from_slice::<PluginActionManifest>(&bytes) {
                    Ok(manifest) => manifest,
                    Err(error) => {
                        push_plugin_diagnostic(
                            &mut diagnostics,
                            &mut diagnostics_limited,
                            path,
                            format!("Manifest JSON is invalid: {error}"),
                        );
                        continue;
                    }
                };
                if let Err(error) = action_manifest.validate() {
                    push_plugin_diagnostic(
                        &mut diagnostics,
                        &mut diagnostics_limited,
                        path,
                        format!("Manifest contract is invalid: {error}"),
                    );
                    continue;
                }
                let declaration = action_manifest.contributions.actions.clone();
                (action_manifest.plugin(), Some(declaration))
            }
            _ => {
                push_plugin_diagnostic(
                    &mut diagnostics,
                    &mut diagnostics_limited,
                    path,
                    "Manifest contract is invalid: unsupported plugin manifest schema".to_string(),
                );
                continue;
            }
        };
        if manifest.id != expected_id {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                "Manifest UUID does not match its filename".to_string(),
            );
            continue;
        }
        let contract_result = match action_contribution.as_ref() {
            Some(contribution) => validate_action_contributor(&manifest, contribution),
            None => manifest.validate(),
        };
        if let Err(error) = contract_result {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                format!("Manifest contract is invalid: {error}"),
            );
            continue;
        }
        if let Err(error) = open_verified_file(&manifest.executable, true, false) {
            push_plugin_diagnostic(
                &mut diagnostics,
                &mut diagnostics_limited,
                path,
                format!(
                    "Plugin executable was quarantined: {error}. Restore trusted ownership, remove group/world or special permission bits, and ensure an execute bit is set"
                ),
            );
            continue;
        }
        if let Some(declaration) = action_contribution {
            action_contributions.push(DiscoveredActionContribution {
                plugin_id: manifest.id,
                declaration,
            });
        }
        manifests.push(manifest);
    }
    manifests.sort_by(|left, right| left.name.cmp(&right.name).then(left.id.cmp(&right.id)));
    manifests.dedup_by_key(|manifest| manifest.id);
    action_contributions.sort_by_key(|contribution| contribution.plugin_id);
    action_contributions.dedup_by_key(|contribution| contribution.plugin_id);
    Ok(PluginDiscoveryReport {
        plugins: manifests,
        action_contributions,
        diagnostics,
        diagnostics_limited,
        scan_truncated,
    })
}

fn require_complete_discovery(report: PluginDiscoveryReport) -> io::Result<Vec<PluginManifest>> {
    if report.scan_truncated {
        return Err(invalid_data(
            "plugin discovery was incomplete; review diagnostics before retrying",
        ));
    }
    Ok(report.plugins)
}

fn push_plugin_diagnostic(
    diagnostics: &mut Vec<PluginDiagnostic>,
    diagnostics_limited: &mut bool,
    path: PathBuf,
    message: String,
) {
    if diagnostics.len() < PLUGIN_DIAGNOSTIC_LIMIT {
        diagnostics.push(PluginDiagnostic { path, message });
    } else {
        *diagnostics_limited = true;
    }
}

pub fn install_manifest(manifest: &PluginManifest) -> io::Result<PathBuf> {
    install_manifest_in(manifest, &plugin_data_dir())
}

pub fn install_manifest_in(manifest: &PluginManifest, directory: &Path) -> io::Result<PathBuf> {
    if manifest.schema != MANIFEST_SCHEMA {
        return Err(invalid_data(
            "use install_action_manifest for schema-2 GUI action manifests",
        ));
    }
    manifest.validate()?;
    let bytes = serde_json::to_vec_pretty(manifest).map_err(invalid_json)?;
    install_manifest_bytes(manifest.id, &manifest.executable, &bytes, directory)
}

pub fn install_action_manifest(manifest: &PluginActionManifest) -> io::Result<PathBuf> {
    install_action_manifest_in(manifest, &plugin_data_dir())
}

pub fn install_action_manifest_in(
    manifest: &PluginActionManifest,
    directory: &Path,
) -> io::Result<PathBuf> {
    manifest.validate()?;
    let bytes = serde_json::to_vec_pretty(manifest).map_err(invalid_json)?;
    install_manifest_bytes(manifest.id, &manifest.executable, &bytes, directory)
}

fn install_manifest_bytes(
    id: Uuid,
    executable: &Path,
    bytes: &[u8],
    directory: &Path,
) -> io::Result<PathBuf> {
    if bytes.len() as u64 > MANIFEST_BYTES_LIMIT {
        return Err(invalid_data(format!(
            "manifest exceeds the {MANIFEST_BYTES_LIMIT}-byte limit"
        )));
    }
    open_verified_file(executable, true, false)?;
    if let Some(parent) = directory.parent() {
        create_private_dir(parent)?;
    }
    let directory_file = create_private_dir(directory)?;
    rustix::fs::flock(&directory_file, rustix::fs::FlockOperation::LockExclusive)
        .map_err(errno_error)?;
    let destination = directory.join(format!("{id}.json"));
    let destination_name = format!("{id}.json");
    let temporary_name = format!(".{id}.{}.tmp", Uuid::now_v7());
    if !destination.exists() && manifest_count(directory)? >= PLUGIN_LIMIT {
        return Err(invalid_data("plugin limit reached"));
    }
    let result = (|| {
        let owned_fd = rustix::fs::openat(
            &directory_file,
            temporary_name.as_str(),
            rustix::fs::OFlags::WRONLY
                | rustix::fs::OFlags::CREATE
                | rustix::fs::OFlags::EXCL
                | rustix::fs::OFlags::NOFOLLOW
                | rustix::fs::OFlags::CLOEXEC,
            rustix::fs::Mode::RUSR | rustix::fs::Mode::WUSR,
        )
        .map_err(errno_error)?;
        let mut file = fs::File::from(owned_fd);
        file.write_all(bytes)?;
        file.write_all(b"\n")?;
        file.sync_all()?;
        drop(file);
        rustix::fs::renameat(
            &directory_file,
            temporary_name.as_str(),
            &directory_file,
            destination_name.as_str(),
        )
        .map_err(errno_error)?;
        directory_file.sync_all()?;
        Ok(destination.clone())
    })();
    if result.is_err() {
        let _ = rustix::fs::unlinkat(
            &directory_file,
            temporary_name.as_str(),
            rustix::fs::AtFlags::empty(),
        );
    }
    result
}

pub fn run_plugin(
    manifest: &PluginManifest,
    arguments: impl IntoIterator<Item = OsString>,
) -> io::Result<ExitStatus> {
    manifest.validate()?;
    let executable = open_verified_file(&manifest.executable, true, false)?;
    rustix::io::fcntl_setfd(&executable, rustix::io::FdFlags::empty()).map_err(errno_error)?;
    let executable_path = format!("/proc/self/fd/{}", executable.as_raw_fd());
    let mut command = Command::new(executable_path);
    command
        .args(arguments)
        .stdin(Stdio::inherit())
        .stdout(Stdio::inherit())
        .stderr(Stdio::inherit());
    spawn_plugin_command(&mut command)?.wait()
}

#[derive(Debug)]
pub struct PluginOutput {
    pub status: ExitStatus,
    pub stdout: Vec<u8>,
    pub stderr: Vec<u8>,
}

pub struct PluginProcess {
    child: Option<Child>,
    process_group: rustix::process::Pid,
    stdin_writer: Option<Receiver<io::Result<()>>>,
    stdout_reader: Option<Receiver<io::Result<Vec<u8>>>>,
    stderr_reader: Option<Receiver<io::Result<Vec<u8>>>>,
    cancellation_requested_at: Option<Instant>,
}

impl PluginProcess {
    pub fn try_wait(&mut self) -> io::Result<Option<PluginOutput>> {
        if self
            .cancellation_requested_at
            .is_some_and(|started| started.elapsed() >= PLUGIN_SHUTDOWN_TIMEOUT)
        {
            let _ = rustix::process::kill_process_group(
                self.process_group,
                rustix::process::Signal::KILL,
            );
        }
        let Some(child) = self.child.as_mut() else {
            return Err(io::Error::other("plugin process was already collected"));
        };
        let Some(status) = child.try_wait()? else {
            return Ok(None);
        };
        self.child.take();
        let _ =
            rustix::process::kill_process_group(self.process_group, rustix::process::Signal::KILL);
        collect_input(&mut self.stdin_writer)?;
        let stdout = collect_output(&mut self.stdout_reader)?;
        let stderr = collect_output(&mut self.stderr_reader)?;
        Ok(Some(PluginOutput {
            status,
            stdout,
            stderr,
        }))
    }

    pub fn cancel(&mut self) -> io::Result<()> {
        if self.cancellation_requested_at.is_some() {
            return Ok(());
        }
        match rustix::process::kill_process_group(self.process_group, rustix::process::Signal::TERM)
        {
            Ok(()) | Err(rustix::io::Errno::SRCH) => {}
            Err(error) => return Err(errno_error(error)),
        }
        self.cancellation_requested_at = Some(Instant::now());
        Ok(())
    }

    pub fn cancellation_requested(&self) -> bool {
        self.cancellation_requested_at.is_some()
    }
}

impl Drop for PluginProcess {
    fn drop(&mut self) {
        let Some(child) = self.child.as_mut() else {
            return;
        };
        let _ =
            rustix::process::kill_process_group(self.process_group, rustix::process::Signal::TERM);
        let started = Instant::now();
        while started.elapsed() < PLUGIN_SHUTDOWN_TIMEOUT {
            match child.try_wait() {
                Ok(Some(_)) => break,
                Ok(None) => thread::sleep(PLUGIN_SHUTDOWN_POLL_INTERVAL),
                Err(_) => break,
            }
        }
        let _ =
            rustix::process::kill_process_group(self.process_group, rustix::process::Signal::KILL);
        if child.try_wait().ok().flatten().is_none() {
            let _ = child.kill();
            let _ = child.wait();
        }
        self.child.take();
        self.stdin_writer.take();
        self.stdout_reader.take();
        self.stderr_reader.take();
    }
}

pub fn spawn_plugin(
    manifest: &PluginManifest,
    arguments: impl IntoIterator<Item = OsString>,
) -> io::Result<PluginProcess> {
    spawn_plugin_process(manifest, arguments, None, RuntimeManifestKind::Command)
}

#[derive(Clone, Copy)]
enum RuntimeManifestKind {
    Command,
    GuiAction,
}

fn spawn_plugin_process(
    manifest: &PluginManifest,
    arguments: impl IntoIterator<Item = OsString>,
    input: Option<Vec<u8>>,
    kind: RuntimeManifestKind,
) -> io::Result<PluginProcess> {
    validate_runtime_manifest(manifest, kind)?;
    let executable = open_verified_file(&manifest.executable, true, false)?;
    rustix::io::fcntl_setfd(&executable, rustix::io::FdFlags::empty()).map_err(errno_error)?;
    let executable_path = format!("/proc/self/fd/{}", executable.as_raw_fd());
    let mut command = Command::new(executable_path);
    command.args(arguments);
    command.stdin(if input.is_some() {
        Stdio::piped()
    } else {
        Stdio::null()
    });
    command.stdout(Stdio::piped()).stderr(Stdio::piped());
    #[cfg(unix)]
    {
        use std::os::unix::process::CommandExt;
        command.process_group(0);
    }
    let mut child = spawn_plugin_command(&mut command)?;
    let process_group = match i32::try_from(child.id())
        .ok()
        .and_then(rustix::process::Pid::from_raw)
    {
        Some(process_group) => process_group,
        None => {
            let _ = child.kill();
            let _ = child.wait();
            return Err(io::Error::other("plugin process ID is out of range"));
        }
    };
    let stdin_writer = if let Some(input) = input {
        let Some(stdin) = child.stdin.take() else {
            terminate_failed_spawn(&mut child, process_group);
            return Err(io::Error::other("plugin stdin was not captured"));
        };
        match spawn_input_writer(stdin, input) {
            Ok(writer) => Some(writer),
            Err(error) => {
                terminate_failed_spawn(&mut child, process_group);
                return Err(error);
            }
        }
    } else {
        None
    };
    let Some(stdout) = child.stdout.take() else {
        terminate_failed_spawn(&mut child, process_group);
        return Err(io::Error::other("plugin stdout was not captured"));
    };
    let Some(stderr) = child.stderr.take() else {
        terminate_failed_spawn(&mut child, process_group);
        return Err(io::Error::other("plugin stderr was not captured"));
    };
    let stdout_reader = match spawn_output_reader("guth-plugin-stdout", stdout) {
        Ok(reader) => reader,
        Err(error) => {
            terminate_failed_spawn(&mut child, process_group);
            return Err(error);
        }
    };
    let stderr_reader = match spawn_output_reader("guth-plugin-stderr", stderr) {
        Ok(reader) => reader,
        Err(error) => {
            terminate_failed_spawn(&mut child, process_group);
            drop(stdout_reader);
            return Err(error);
        }
    };
    Ok(PluginProcess {
        child: Some(child),
        process_group,
        stdin_writer,
        stdout_reader: Some(stdout_reader),
        stderr_reader: Some(stderr_reader),
        cancellation_requested_at: None,
    })
}

/// Starts a bounded schema-2 action probe. The executable receives exactly
/// `--guth-action-protocol 1 probe`; its request is a single JSON object on
/// stdin and its response must be a single versioned JSON object on stdout.
pub fn spawn_plugin_action_probe(
    manifest: &PluginManifest,
    contribution: &PluginActionContribution,
    context: &PluginActionContext,
) -> io::Result<PluginProcess> {
    validate_action_contributor(manifest, contribution)?;
    context.validate()?;
    let request = PluginActionProbeRequest {
        protocol: ACTION_PROTOCOL_VERSION,
        plugin_id: manifest.id,
        operation: PluginActionOperation::Probe,
        context: context.clone(),
    };
    spawn_plugin_protocol(manifest, PluginActionOperation::Probe, &request)
}

/// Parses and validates a completed action probe without trusting plugin IDs,
/// action identifiers, menu placement, or selection matchers from stdout.
pub fn parse_plugin_action_probe(
    manifest: &PluginManifest,
    contribution: &PluginActionContribution,
    output: &PluginOutput,
) -> io::Result<Vec<PluginActionMetadata>> {
    validate_action_contributor(manifest, contribution)?;
    let response: PluginActionProbeResponse = parse_plugin_protocol_output(output, "probe")?;
    response.validate(manifest.id)?;
    Ok(response.actions)
}

/// Blocking probe convenience for worker threads and headless callers. GUI
/// code should run this away from the render thread or use the spawn/parse pair.
pub fn probe_plugin_actions(
    manifest: &PluginManifest,
    contribution: &PluginActionContribution,
    context: &PluginActionContext,
) -> io::Result<Vec<PluginActionMetadata>> {
    let mut process = spawn_plugin_action_probe(manifest, contribution, context)?;
    let started = Instant::now();
    loop {
        if let Some(output) = process.try_wait()? {
            return parse_plugin_action_probe(manifest, contribution, &output);
        }
        if started.elapsed() >= PLUGIN_ACTION_PROBE_TIMEOUT {
            process.cancel()?;
            return Err(io::Error::new(
                io::ErrorKind::TimedOut,
                "plugin action probe exceeded the 2-second limit",
            ));
        }
        thread::sleep(Duration::from_millis(5));
    }
}

/// Starts an action previously returned by a validated probe. Invocation is
/// rejected when the action no longer matches the supplied context.
pub fn spawn_plugin_action(
    manifest: &PluginManifest,
    contribution: &PluginActionContribution,
    action: &PluginActionMetadata,
    context: &PluginActionContext,
) -> io::Result<PluginProcess> {
    validate_action_contributor(manifest, contribution)?;
    action.validate()?;
    context.validate()?;
    if !action.matches_context(context) {
        return Err(invalid_data(
            "plugin action does not match the current file context",
        ));
    }
    let request = PluginActionInvokeRequest {
        protocol: ACTION_PROTOCOL_VERSION,
        plugin_id: manifest.id,
        operation: PluginActionOperation::Invoke,
        action_id: action.id.clone(),
        context: context.clone(),
    };
    spawn_plugin_protocol(manifest, PluginActionOperation::Invoke, &request)
}

/// Runs a validated action to completion for worker-thread and headless use.
/// The process is cancelled after five minutes and is always reaped by the
/// bounded [`PluginProcess`] shutdown path.
pub fn invoke_plugin_action(
    manifest: &PluginManifest,
    contribution: &PluginActionContribution,
    action: &PluginActionMetadata,
    context: &PluginActionContext,
) -> io::Result<PluginActionResult> {
    let mut process = spawn_plugin_action(manifest, contribution, action, context)?;
    let started = Instant::now();
    loop {
        if let Some(output) = process.try_wait()? {
            return parse_plugin_action_result(manifest, contribution, action, &output);
        }
        if started.elapsed() >= PLUGIN_ACTION_INVOKE_TIMEOUT {
            process.cancel()?;
            return Err(io::Error::new(
                io::ErrorKind::TimedOut,
                "plugin action exceeded the 5-minute limit",
            ));
        }
        thread::sleep(Duration::from_millis(10));
    }
}

pub fn parse_plugin_action_result(
    manifest: &PluginManifest,
    contribution: &PluginActionContribution,
    action: &PluginActionMetadata,
    output: &PluginOutput,
) -> io::Result<PluginActionResult> {
    validate_action_contributor(manifest, contribution)?;
    action.validate()?;
    let result: PluginActionResult = parse_plugin_protocol_output(output, "invocation")?;
    result.validate(manifest.id, &action.id)?;
    Ok(result)
}

fn spawn_plugin_protocol(
    manifest: &PluginManifest,
    operation: PluginActionOperation,
    request: &impl Serialize,
) -> io::Result<PluginProcess> {
    let input = serialize_plugin_protocol_request(request)?;
    spawn_plugin_process(
        manifest,
        [
            OsString::from(ACTION_PROTOCOL_ARGUMENT),
            OsString::from(ACTION_PROTOCOL_VERSION.to_string()),
            OsString::from(operation.argument()),
        ],
        Some(input),
        RuntimeManifestKind::GuiAction,
    )
}

fn validate_action_contributor(
    manifest: &PluginManifest,
    contribution: &PluginActionContribution,
) -> io::Result<()> {
    contribution.validate()?;
    if manifest.schema != ACTION_MANIFEST_SCHEMA
        || !manifest.supports(ACTION_CONTRIBUTION_CAPABILITY)
    {
        return Err(invalid_data(
            "plugin did not opt into the schema-2 GUI action contract",
        ));
    }
    manifest.validate_common()
}

fn validate_runtime_manifest(
    manifest: &PluginManifest,
    kind: RuntimeManifestKind,
) -> io::Result<()> {
    match kind {
        RuntimeManifestKind::Command => manifest.validate(),
        RuntimeManifestKind::GuiAction
            if manifest.schema == ACTION_MANIFEST_SCHEMA
                && manifest.supports(ACTION_CONTRIBUTION_CAPABILITY) =>
        {
            manifest.validate_common()
        }
        RuntimeManifestKind::GuiAction => Err(invalid_data(
            "GUI action runtime plugins must use schema 2 and declare gui-actions",
        )),
    }
}

fn serialize_plugin_protocol_request(request: &impl Serialize) -> io::Result<Vec<u8>> {
    let mut input = serde_json::to_vec(request)
        .map_err(|error| invalid_data(format!("invalid plugin protocol request: {error}")))?;
    if input.len().saturating_add(1) > PLUGIN_ACTION_IO_BYTES_LIMIT {
        return Err(invalid_data(format!(
            "plugin protocol request exceeds the {PLUGIN_ACTION_IO_BYTES_LIMIT}-byte limit"
        )));
    }
    input.push(b'\n');
    Ok(input)
}

fn parse_plugin_protocol_request<T: DeserializeOwned>(
    input: impl Read,
    operation: &str,
) -> io::Result<T> {
    let mut bytes = Vec::new();
    input
        .take(PLUGIN_ACTION_IO_BYTES_LIMIT as u64 + 1)
        .read_to_end(&mut bytes)?;
    if bytes.len() > PLUGIN_ACTION_IO_BYTES_LIMIT {
        return Err(invalid_data(format!(
            "plugin action {operation} request exceeds the {PLUGIN_ACTION_IO_BYTES_LIMIT}-byte limit"
        )));
    }
    serde_json::from_slice(&bytes).map_err(|error| {
        invalid_data(format!(
            "invalid plugin action {operation} request: {error}"
        ))
    })
}

fn validate_allowed_action_ids(action_ids: &[&str]) -> io::Result<()> {
    if action_ids.is_empty() || action_ids.len() > PLUGIN_ACTION_LIMIT {
        return Err(invalid_data(format!(
            "allowed plugin action IDs must contain 1 to {PLUGIN_ACTION_LIMIT} entries"
        )));
    }
    let mut unique = BTreeSet::new();
    for action_id in action_ids {
        validate_token(action_id, "allowed plugin action ID")?;
        if !unique.insert(*action_id) {
            return Err(invalid_data("allowed plugin action IDs must be unique"));
        }
    }
    Ok(())
}

fn parse_plugin_protocol_output<T: DeserializeOwned>(
    output: &PluginOutput,
    operation: &str,
) -> io::Result<T> {
    if !output.status.success() {
        let stderr = bounded_protocol_message(&output.stderr);
        let detail = if stderr.is_empty() {
            String::new()
        } else {
            format!(": {stderr}")
        };
        return Err(io::Error::other(format!(
            "plugin action {operation} exited unsuccessfully{detail}"
        )));
    }
    if output.stdout.len() > PLUGIN_ACTION_IO_BYTES_LIMIT {
        return Err(invalid_data(format!(
            "plugin action {operation} response exceeds the {PLUGIN_ACTION_IO_BYTES_LIMIT}-byte limit"
        )));
    }
    serde_json::from_slice(&output.stdout).map_err(|error| {
        invalid_data(format!(
            "invalid plugin action {operation} response: {error}"
        ))
    })
}

fn bounded_protocol_message(bytes: &[u8]) -> String {
    let normalized = String::from_utf8_lossy(bytes)
        .split_whitespace()
        .collect::<Vec<_>>()
        .join(" ");
    normalized.chars().take(512).collect()
}

fn spawn_plugin_command(command: &mut Command) -> io::Result<Child> {
    for attempt in 0..=PLUGIN_SPAWN_BUSY_RETRIES {
        match command.spawn() {
            Ok(child) => return Ok(child),
            Err(error)
                if error.raw_os_error() == Some(rustix::io::Errno::TXTBSY.raw_os_error())
                    && attempt < PLUGIN_SPAWN_BUSY_RETRIES =>
            {
                thread::sleep(PLUGIN_SPAWN_BUSY_RETRY_DELAY);
            }
            Err(error) => return Err(error),
        }
    }
    unreachable!("bounded plugin spawn loop always returns")
}

fn spawn_output_reader(
    name: &str,
    reader: impl Read + Send + 'static,
) -> io::Result<Receiver<io::Result<Vec<u8>>>> {
    let (sender, receiver) = mpsc::sync_channel(1);
    thread::Builder::new()
        .name(name.to_string())
        .spawn(move || {
            let _ = sender.send(read_bounded(reader));
        })?;
    Ok(receiver)
}

fn spawn_input_writer(
    mut writer: impl Write + Send + 'static,
    input: Vec<u8>,
) -> io::Result<Receiver<io::Result<()>>> {
    let (sender, receiver) = mpsc::sync_channel(1);
    thread::Builder::new()
        .name("guth-plugin-stdin".to_string())
        .spawn(move || {
            let result = writer.write_all(&input).and_then(|()| writer.flush());
            let _ = sender.send(result);
        })?;
    Ok(receiver)
}

fn terminate_failed_spawn(child: &mut Child, process_group: rustix::process::Pid) {
    let _ = rustix::process::kill_process_group(process_group, rustix::process::Signal::KILL);
    let _ = child.kill();
    let _ = child.wait();
}

fn read_bounded(mut reader: impl Read) -> io::Result<Vec<u8>> {
    let mut output = Vec::new();
    let mut buffer = [0_u8; 8 * 1024];
    loop {
        let count = reader.read(&mut buffer)?;
        if count == 0 {
            return Ok(output);
        }
        if count >= PLUGIN_OUTPUT_BYTES_LIMIT {
            output.clear();
            output.extend_from_slice(&buffer[count - PLUGIN_OUTPUT_BYTES_LIMIT..count]);
            continue;
        }
        let overflow = output
            .len()
            .saturating_add(count)
            .saturating_sub(PLUGIN_OUTPUT_BYTES_LIMIT);
        if overflow > 0 {
            output.drain(..overflow);
        }
        output.extend_from_slice(&buffer[..count]);
    }
}

fn collect_output(reader: &mut Option<Receiver<io::Result<Vec<u8>>>>) -> io::Result<Vec<u8>> {
    reader
        .take()
        .ok_or_else(|| io::Error::other("plugin output was already collected"))?
        .recv_timeout(PLUGIN_OUTPUT_DRAIN_TIMEOUT)
        .map_err(|error| io::Error::other(format!("plugin output reader failed: {error}")))?
}

fn collect_input(writer: &mut Option<Receiver<io::Result<()>>>) -> io::Result<()> {
    let Some(writer) = writer.take() else {
        return Ok(());
    };
    writer
        .recv_timeout(PLUGIN_OUTPUT_DRAIN_TIMEOUT)
        .map_err(|error| io::Error::other(format!("plugin input writer failed: {error}")))?
}

fn validate_text(value: &str, label: &str, max_len: usize) -> io::Result<()> {
    if value.is_empty()
        || value.trim().is_empty()
        || value.len() > max_len
        || value.chars().any(is_unsafe_plugin_ui_character)
    {
        return Err(invalid_data(format!("invalid {label}")));
    }
    Ok(())
}

fn is_unsafe_plugin_ui_character(character: char) -> bool {
    character.is_control()
        || matches!(
            character,
            // Invisible formatting characters that can conceal an otherwise
            // empty label or alter adjacent host-owned interface text.
            '\u{00ad}'
                | '\u{061c}'
                | '\u{180e}'
                | '\u{200b}'
                | '\u{200e}'
                | '\u{200f}'
                | '\u{2028}'
                | '\u{2029}'
                | '\u{202a}'..='\u{202e}'
                | '\u{2060}'
                | '\u{2066}'..='\u{206f}'
                | '\u{feff}'
                | '\u{fff9}'..='\u{fffb}'
        )
}

fn validate_token(value: &str, label: &str) -> io::Result<()> {
    if value.is_empty()
        || value.len() > 40
        || !value
            .bytes()
            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
    {
        return Err(invalid_data(format!("invalid {label}")));
    }
    Ok(())
}

fn validate_extension(value: &str) -> io::Result<()> {
    if value.is_empty()
        || value.len() > 32
        || !value
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'+' | b'-' | b'_' | b'.'))
    {
        return Err(invalid_data("invalid plugin action extension"));
    }
    Ok(())
}

fn validate_protocol_path(path: &Path) -> io::Result<()> {
    let bytes = path.as_os_str().as_bytes();
    if !path.is_absolute()
        || bytes.is_empty()
        || bytes.len() > PLUGIN_PATH_BYTES_LIMIT
        || bytes.contains(&0)
    {
        return Err(invalid_data(
            "plugin protocol paths must be bounded absolute Linux paths",
        ));
    }
    Ok(())
}

fn validate_protocol_identity(
    protocol: u32,
    plugin_id: Uuid,
    expected_plugin_id: Uuid,
) -> io::Result<()> {
    if protocol != ACTION_PROTOCOL_VERSION {
        return Err(invalid_data(
            "plugin action response protocol version does not match Guth",
        ));
    }
    validate_plugin_id(expected_plugin_id)?;
    validate_plugin_id(plugin_id)?;
    if plugin_id != expected_plugin_id {
        return Err(invalid_data(
            "plugin action response does not match the requested plugin",
        ));
    }
    Ok(())
}

fn all_unique<T: Ord>(values: &[T]) -> bool {
    values.iter().collect::<BTreeSet<_>>().len() == values.len()
}

fn encode_hex(bytes: &[u8]) -> String {
    const HEX: &[u8; 16] = b"0123456789abcdef";
    let mut encoded = String::with_capacity(bytes.len() * 2);
    for byte in bytes {
        encoded.push(char::from(HEX[usize::from(byte >> 4)]));
        encoded.push(char::from(HEX[usize::from(byte & 0x0f)]));
    }
    encoded
}

fn decode_hex(value: &str) -> io::Result<Vec<u8>> {
    if !value.len().is_multiple_of(2) || value.len() > PLUGIN_PATH_BYTES_LIMIT * 2 {
        return Err(invalid_data("invalid plugin protocol path encoding"));
    }
    value
        .as_bytes()
        .chunks_exact(2)
        .map(|pair| {
            let high = decode_hex_digit(pair[0])?;
            let low = decode_hex_digit(pair[1])?;
            Ok((high << 4) | low)
        })
        .collect()
}

fn decode_hex_digit(byte: u8) -> io::Result<u8> {
    match byte {
        b'0'..=b'9' => Ok(byte - b'0'),
        b'a'..=b'f' => Ok(byte - b'a' + 10),
        _ => Err(invalid_data(
            "plugin protocol path encoding must use lowercase hexadecimal",
        )),
    }
}

fn parse_plugin_id(value: &str) -> io::Result<Uuid> {
    let id = Uuid::parse_str(value).map_err(|_| invalid_data("invalid plugin UUID"))?;
    if id.to_string() != value {
        return Err(invalid_data(
            "plugin UUID must use canonical lowercase text",
        ));
    }
    validate_plugin_id(id)?;
    Ok(id)
}

fn validate_plugin_id(id: Uuid) -> io::Result<()> {
    if id.get_version() != Some(Version::SortRand) || id.get_variant() != Variant::RFC4122 {
        return Err(invalid_data("plugin ID must be a UUIDv7"));
    }
    Ok(())
}

fn open_verified_file(path: &Path, executable: bool, private: bool) -> io::Result<fs::File> {
    let owned_fd = rustix::fs::open(
        path,
        rustix::fs::OFlags::RDONLY
            | rustix::fs::OFlags::CLOEXEC
            | rustix::fs::OFlags::NOFOLLOW
            | rustix::fs::OFlags::NONBLOCK,
        rustix::fs::Mode::empty(),
    )
    .map_err(errno_error)?;
    let file = fs::File::from(owned_fd);
    let metadata = file.metadata()?;
    if !metadata.is_file() {
        return Err(invalid_data("plugin path must be a regular file"));
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        let current_uid = rustix::process::geteuid().as_raw();
        if metadata.uid() != current_uid && metadata.uid() != 0 {
            return Err(io::Error::new(
                io::ErrorKind::PermissionDenied,
                "plugin file has an untrusted owner",
            ));
        }
        // Set-user/group-ID and sticky bits have no place on plugin manifests or
        // executables. Rejecting them also keeps root-owned executables from
        // unexpectedly crossing a privilege boundary when dispatched.
        let unsafe_permissions = if private { 0o7077 } else { 0o7022 };
        if metadata.mode() & unsafe_permissions != 0 {
            return Err(io::Error::new(
                io::ErrorKind::PermissionDenied,
                "plugin file has unsafe permissions",
            ));
        }
        if executable && metadata.mode() & 0o111 == 0 {
            return Err(io::Error::new(
                io::ErrorKind::PermissionDenied,
                "plugin executable is not executable",
            ));
        }
    }
    Ok(file)
}

fn create_private_dir(path: &Path) -> io::Result<fs::File> {
    if !path.is_absolute() {
        return Err(invalid_data("plugin directory must be absolute"));
    }
    fs::create_dir_all(path)?;
    let owned_fd = rustix::fs::open(
        path,
        rustix::fs::OFlags::RDONLY
            | rustix::fs::OFlags::DIRECTORY
            | rustix::fs::OFlags::NOFOLLOW
            | rustix::fs::OFlags::CLOEXEC,
        rustix::fs::Mode::empty(),
    )
    .map_err(errno_error)?;
    let directory = fs::File::from(owned_fd);
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        let metadata = directory.metadata()?;
        if !metadata.is_dir() {
            return Err(io::Error::new(
                io::ErrorKind::PermissionDenied,
                "plugin directory must be a real directory",
            ));
        }
        if metadata.uid() != rustix::process::geteuid().as_raw() {
            return Err(io::Error::new(
                io::ErrorKind::PermissionDenied,
                "plugin directory has an unexpected owner",
            ));
        }
        rustix::fs::fchmod(&directory, rustix::fs::Mode::RWXU).map_err(errno_error)?;
    }
    Ok(directory)
}

fn manifest_count(directory: &Path) -> io::Result<usize> {
    let mut count = 0;
    for (index, entry) in fs::read_dir(directory)?.enumerate() {
        if index >= PLUGIN_DIRECTORY_ENTRY_LIMIT {
            return Err(invalid_data(format!(
                "plugin directory contains more than {PLUGIN_DIRECTORY_ENTRY_LIMIT} entries"
            )));
        }
        let Ok(entry) = entry else {
            continue;
        };
        let path = entry.path();
        let Some(stem) = path.file_stem().and_then(|stem| stem.to_str()) else {
            continue;
        };
        if path
            .extension()
            .is_some_and(|extension| extension == "json")
            && Uuid::parse_str(stem)
                .is_ok_and(|id| validate_plugin_id(id).is_ok() && id.to_string() == stem)
        {
            count += 1;
        }
    }
    Ok(count)
}

#[cfg(test)]
fn write_enabled_plugins_to(ids: &BTreeSet<Uuid>, path: &Path) -> io::Result<()> {
    let directory_file = lock_enabled_plugin_directory(path)?;
    write_enabled_plugins_locked(ids, path, &directory_file)
}

fn lock_enabled_plugin_directory(path: &Path) -> io::Result<fs::File> {
    let directory = path
        .parent()
        .ok_or_else(|| invalid_data("enabled plugin path has no parent"))?;
    let directory_file = create_private_dir(directory)?;
    rustix::fs::flock(&directory_file, rustix::fs::FlockOperation::LockExclusive)
        .map_err(errno_error)?;
    Ok(directory_file)
}

fn write_enabled_plugins_locked(
    ids: &BTreeSet<Uuid>,
    path: &Path,
    directory_file: &fs::File,
) -> io::Result<()> {
    let file_name = path
        .file_name()
        .ok_or_else(|| invalid_data("enabled plugin path has no file name"))?;
    let temporary_name = format!(".enabled-plugins.{}.tmp", Uuid::now_v7());
    let result = (|| {
        let owned_fd = rustix::fs::openat(
            directory_file,
            temporary_name.as_str(),
            rustix::fs::OFlags::WRONLY
                | rustix::fs::OFlags::CREATE
                | rustix::fs::OFlags::EXCL
                | rustix::fs::OFlags::NOFOLLOW
                | rustix::fs::OFlags::CLOEXEC,
            rustix::fs::Mode::RUSR | rustix::fs::Mode::WUSR,
        )
        .map_err(errno_error)?;
        let mut file = fs::File::from(owned_fd);
        for id in ids {
            writeln!(file, "{id}")?;
        }
        file.sync_all()?;
        drop(file);
        rustix::fs::renameat(
            directory_file,
            temporary_name.as_str(),
            directory_file,
            file_name,
        )
        .map_err(errno_error)?;
        directory_file.sync_all()
    })();
    if result.is_err() {
        let _ = rustix::fs::unlinkat(
            directory_file,
            temporary_name.as_str(),
            rustix::fs::AtFlags::empty(),
        );
    }
    result
}

fn home_dir() -> PathBuf {
    std::env::var_os("HOME")
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from("/"))
}

fn invalid_data(message: impl Into<String>) -> io::Error {
    io::Error::new(io::ErrorKind::InvalidData, message.into())
}

fn invalid_json(error: impl std::fmt::Display) -> io::Error {
    invalid_data(format!("invalid plugin manifest: {error}"))
}

fn errno_error(error: rustix::io::Errno) -> io::Error {
    io::Error::from_raw_os_error(error.raw_os_error())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::{SystemTime, UNIX_EPOCH};

    struct TestDir(PathBuf);

    impl TestDir {
        fn new(label: &str) -> Self {
            let nonce = SystemTime::now()
                .duration_since(UNIX_EPOCH)
                .unwrap()
                .as_nanos();
            let path = std::env::temp_dir()
                .join(format!("guth-cli-{label}-{}-{nonce}", std::process::id()));
            fs::create_dir(&path).unwrap();
            Self(path)
        }
    }

    impl Drop for TestDir {
        fn drop(&mut self) {
            let _ = fs::remove_dir_all(&self.0);
        }
    }

    fn test_manifest(executable: PathBuf) -> PluginManifest {
        PluginManifest {
            schema: MANIFEST_SCHEMA,
            id: Uuid::now_v7(),
            name: "Test Sync".to_string(),
            version: "0.1.0".to_string(),
            executable,
            description: "A test plugin".to_string(),
            capabilities: vec!["sync".to_string()],
        }
    }

    fn test_action_manifest(executable: PathBuf) -> PluginActionManifest {
        PluginActionManifest {
            schema: ACTION_MANIFEST_SCHEMA,
            id: Uuid::now_v7(),
            name: "Test Actions".to_string(),
            version: "0.1.0".to_string(),
            executable,
            description: "A test GUI action plugin".to_string(),
            capabilities: vec![ACTION_CONTRIBUTION_CAPABILITY.to_string()],
            contributions: PluginContributions {
                actions: PluginActionContribution {
                    protocol: ACTION_PROTOCOL_VERSION,
                },
            },
        }
    }

    fn test_action() -> PluginActionMetadata {
        PluginActionMetadata {
            id: "convert-text".to_string(),
            label: "Convert text".to_string(),
            description: "Converts selected text files".to_string(),
            category: PluginActionCategory::Convert,
            icon: PluginActionIcon::Convert,
            placements: vec![
                PluginActionPlacement::ContextMenu,
                PluginActionPlacement::CommandPalette,
            ],
            matcher: PluginActionMatcher {
                min_selection: 1,
                max_selection: 4,
                kinds: vec![PluginActionTargetKind::File],
                extensions: vec!["txt".to_string()],
            },
            destructive: false,
            confirmation: None,
        }
    }

    fn test_action_context(extension: &str) -> PluginActionContext {
        PluginActionContext::new(
            Path::new("/workspace"),
            vec![PluginActionTarget::from_path(
                Path::new(&format!("/workspace/document.{extension}")),
                PluginActionTargetKind::File,
            )
            .unwrap()],
        )
        .unwrap()
    }

    #[test]
    fn manifests_require_uuid_v7_and_absolute_executables() {
        let mut manifest = test_manifest(PathBuf::from("relative"));
        assert!(manifest.validate().is_err());
        manifest.executable = PathBuf::from("/bin/true");
        manifest.id = Uuid::nil();
        assert!(manifest.validate().is_err());

        let mut non_rfc_bytes = *Uuid::now_v7().as_bytes();
        non_rfc_bytes[8] &= 0x3f;
        manifest.id = Uuid::from_bytes(non_rfc_bytes);
        assert_eq!(manifest.id.get_version(), Some(Version::SortRand));
        assert_eq!(manifest.id.get_variant(), Variant::NCS);
        assert!(manifest.validate().is_err());
    }

    #[test]
    fn schema_one_manifest_wire_contract_remains_unchanged() {
        let manifest = test_manifest(PathBuf::from("/bin/true"));
        let value = serde_json::to_value(&manifest).unwrap();

        assert_eq!(value["schema"], MANIFEST_SCHEMA);
        assert!(value.get("contributions").is_none());
        assert_eq!(
            serde_json::from_value::<PluginManifest>(value).unwrap(),
            manifest
        );
    }

    #[test]
    fn action_manifests_require_schema_capability_and_protocol() {
        let mut manifest = test_action_manifest(PathBuf::from("/bin/true"));
        assert!(manifest.validate().is_ok());

        let projection = manifest.plugin();
        assert!(projection.validate().is_err());
        assert!(validate_runtime_manifest(&projection, RuntimeManifestKind::GuiAction).is_ok());
        assert!(validate_runtime_manifest(&projection, RuntimeManifestKind::Command).is_err());
        assert!(spawn_plugin(&projection, []).is_err());
        assert!(run_plugin(&projection, []).is_err());

        manifest.schema = MANIFEST_SCHEMA;
        assert!(manifest.validate().is_err());
        manifest.schema = ACTION_MANIFEST_SCHEMA;
        manifest.capabilities.clear();
        assert!(manifest.validate().is_err());
        manifest
            .capabilities
            .push(ACTION_CONTRIBUTION_CAPABILITY.to_string());
        manifest.contributions.actions.protocol = ACTION_PROTOCOL_VERSION + 1;
        assert!(manifest.validate().is_err());
    }

    #[cfg(unix)]
    #[test]
    fn schema_two_action_manifests_are_discovered_without_hiding_schema_one_plugins() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("action-discovery");
        let legacy_executable = root.0.join("legacy-plugin");
        let action_executable = root.0.join("action-plugin");
        for executable in [&legacy_executable, &action_executable] {
            fs::write(executable, b"#!/bin/sh\nexit 0\n").unwrap();
            fs::set_permissions(executable, fs::Permissions::from_mode(0o700)).unwrap();
        }
        let legacy = test_manifest(legacy_executable);
        let action = test_action_manifest(action_executable);
        let directory = root.0.join("manifests");
        install_manifest_in(&legacy, &directory).unwrap();
        install_action_manifest_in(&action, &directory).unwrap();

        let report = discover_plugins_in_with_diagnostics(&directory).unwrap();

        assert_eq!(report.plugins.len(), 2);
        assert!(report.plugins.contains(&legacy));
        assert!(report.plugins.contains(&action.plugin()));
        assert_eq!(
            report.action_contributions,
            vec![DiscoveredActionContribution {
                plugin_id: action.id,
                declaration: action.contributions.actions,
            }]
        );
        assert!(report.diagnostics.is_empty());
        assert!(!report.scan_truncated);
    }

    #[test]
    fn action_matching_is_bounded_and_checks_every_selected_target() {
        let action = test_action();
        let text = test_action_context("txt");
        let image = test_action_context("png");
        let empty = PluginActionContext::new(Path::new("/workspace"), Vec::new()).unwrap();

        assert!(action.matches_context(&text));
        assert!(!action.matches_context(&image));
        assert!(!action.matches_context(&empty));

        let mut invalid = action.clone();
        invalid.matcher.max_selection = (PLUGIN_ACTION_SELECTION_LIMIT + 1) as u16;
        assert!(invalid.validate().is_err());
        invalid = action;
        invalid.matcher.extensions.push("txt".to_string());
        assert!(invalid.validate().is_err());
    }

    #[test]
    fn action_metadata_rejects_ambiguous_or_unconfirmed_destructive_actions() {
        let mut action = test_action();
        action.destructive = true;
        assert!(action.validate().is_err());
        action.confirmation = Some("Replace the selected files?".to_string());
        assert!(action.validate().is_ok());

        let mut response = PluginActionProbeResponse {
            protocol: ACTION_PROTOCOL_VERSION,
            plugin_id: Uuid::now_v7(),
            actions: vec![action.clone(), action],
        };
        assert!(response.validate(response.plugin_id).is_err());
        response.actions.pop();
        assert!(response.validate(Uuid::now_v7()).is_err());
    }

    #[test]
    fn plugin_ui_text_rejects_blank_and_unsafe_formatting() {
        let mut action = test_action();
        action.label = "   ".to_string();
        assert!(action.validate().is_err());

        action = test_action();
        action.description = "Misleading\u{202e}text".to_string();
        assert!(action.validate().is_err());

        action = test_action();
        action.description = "First\u{2028}second".to_string();
        assert!(action.validate().is_err());

        action = test_action();
        action.destructive = true;
        action.confirmation = Some("\u{200b}".to_string());
        assert!(action.validate().is_err());

        let result = PluginActionResult {
            protocol: ACTION_PROTOCOL_VERSION,
            plugin_id: Uuid::now_v7(),
            action_id: "convert-text".to_string(),
            outcome: PluginActionOutcome::Failed,
            message: Some("   ".to_string()),
            refresh: false,
        };
        assert!(result.validate(result.plugin_id, "convert-text").is_err());

        assert!(validate_text("أداة صور", "localized label", 80).is_ok());
    }

    #[test]
    fn plugin_author_probe_parser_rejects_malformed_oversized_and_confused_requests() {
        let plugin_id = Uuid::now_v7();
        let mut request = PluginActionProbeRequest {
            protocol: ACTION_PROTOCOL_VERSION,
            plugin_id,
            operation: PluginActionOperation::Probe,
            context: test_action_context("txt"),
        };
        let valid = serde_json::to_vec(&request).unwrap();

        assert_eq!(
            parse_plugin_action_probe_request(valid.as_slice(), plugin_id).unwrap(),
            request
        );
        assert!(parse_plugin_action_probe_request(&b"{"[..], plugin_id).is_err());
        assert!(parse_plugin_action_probe_request(
            vec![b' '; PLUGIN_ACTION_IO_BYTES_LIMIT + 1].as_slice(),
            plugin_id,
        )
        .is_err());
        assert!(parse_plugin_action_probe_request(valid.as_slice(), Uuid::now_v7()).is_err());

        request.operation = PluginActionOperation::Invoke;
        assert!(parse_plugin_action_probe_request(
            serde_json::to_vec(&request).unwrap().as_slice(),
            plugin_id,
        )
        .is_err());
        request.operation = PluginActionOperation::Probe;
        request.context.current_directory.display = "/different".to_string();
        assert!(parse_plugin_action_probe_request(
            serde_json::to_vec(&request).unwrap().as_slice(),
            plugin_id,
        )
        .is_err());
    }

    #[test]
    fn plugin_author_invoke_parser_requires_declared_action_identity() {
        let plugin_id = Uuid::now_v7();
        let mut request = PluginActionInvokeRequest {
            protocol: ACTION_PROTOCOL_VERSION,
            plugin_id,
            operation: PluginActionOperation::Invoke,
            action_id: "convert-text".to_string(),
            context: test_action_context("txt"),
        };
        let valid = serde_json::to_vec(&request).unwrap();

        assert_eq!(
            parse_plugin_action_invoke_request(valid.as_slice(), plugin_id, &["convert-text"])
                .unwrap(),
            request
        );
        assert!(
            parse_plugin_action_invoke_request(valid.as_slice(), plugin_id, &["other-action"])
                .is_err()
        );
        assert!(parse_plugin_action_invoke_request(valid.as_slice(), plugin_id, &[]).is_err());
        assert!(parse_plugin_action_invoke_request(
            valid.as_slice(),
            plugin_id,
            &["convert-text", "convert-text"],
        )
        .is_err());

        request.action_id = "INVALID ACTION".to_string();
        assert!(parse_plugin_action_invoke_request(
            serde_json::to_vec(&request).unwrap().as_slice(),
            plugin_id,
            &["convert-text"],
        )
        .is_err());
        request.action_id = "convert-text".to_string();
        request.operation = PluginActionOperation::Probe;
        assert!(parse_plugin_action_invoke_request(
            serde_json::to_vec(&request).unwrap().as_slice(),
            plugin_id,
            &["convert-text"],
        )
        .is_err());
    }

    #[cfg(unix)]
    #[test]
    fn protocol_paths_round_trip_non_utf8_linux_names() {
        let path = PathBuf::from(OsString::from_vec(b"/workspace/non-utf8-\xff.txt".to_vec()));
        let wire = PluginProtocolPath::from_path(&path).unwrap();

        assert_eq!(wire.to_path_buf().unwrap(), path);
        assert!(wire.display.contains('\u{fffd}'));

        let mut tampered = wire;
        tampered.display = "/workspace/different.txt".to_string();
        assert!(tampered.to_path_buf().is_err());
    }

    #[cfg(unix)]
    #[test]
    fn installed_manifests_are_private_and_discoverable() {
        use std::os::unix::fs::{MetadataExt, PermissionsExt};

        let root = TestDir::new("discovery");
        let executable = root.0.join("plugin");
        fs::write(&executable, b"#!/bin/sh\nexit 0\n").unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let manifest = test_manifest(executable);
        let directory = root.0.join("manifests");

        let installed = install_manifest_in(&manifest, &directory).unwrap();
        assert_eq!(fs::metadata(&directory).unwrap().mode() & 0o777, 0o700);
        assert_eq!(fs::metadata(&installed).unwrap().mode() & 0o777, 0o600);
        assert_eq!(discover_plugins_in(&directory).unwrap(), vec![manifest]);
    }

    #[cfg(unix)]
    #[test]
    fn writable_executables_are_rejected() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("permissions");
        let executable = root.0.join("plugin");
        fs::write(&executable, b"plugin").unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o722)).unwrap();
        let error = open_verified_file(&executable, true, false).unwrap_err();
        assert_eq!(error.kind(), io::ErrorKind::PermissionDenied);
    }

    #[cfg(unix)]
    #[test]
    fn special_permission_bits_quarantine_plugin_executables() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("special-permissions");
        let executable = root.0.join("plugin");
        fs::write(&executable, b"plugin").unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o4700)).unwrap();

        let error = open_verified_file(&executable, true, false).unwrap_err();

        assert_eq!(error.kind(), io::ErrorKind::PermissionDenied);
    }

    #[cfg(unix)]
    #[test]
    fn malformed_neighbors_do_not_hide_valid_plugins() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("malformed-neighbor");
        let executable = root.0.join("plugin");
        fs::write(&executable, b"plugin").unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let manifest = test_manifest(executable);
        let directory = root.0.join("manifests");
        install_manifest_in(&manifest, &directory).unwrap();
        let malformed = directory.join(format!("{}.json", Uuid::now_v7()));
        fs::write(&malformed, b"not json").unwrap();
        fs::set_permissions(&malformed, fs::Permissions::from_mode(0o600)).unwrap();

        let report = discover_plugins_in_with_diagnostics(&directory).unwrap();
        assert_eq!(report.plugins, vec![manifest]);
        assert_eq!(report.diagnostics.len(), 1);
        assert_eq!(report.diagnostics[0].path, malformed);
        assert!(report.diagnostics[0].message.contains("JSON is invalid"));
        assert!(!report.diagnostics_limited);
    }

    #[cfg(unix)]
    #[test]
    fn malformed_manifest_filenames_are_actionable_without_hiding_valid_plugins() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("malformed-filename");
        let executable = root.0.join("plugin");
        fs::write(&executable, b"plugin").unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let manifest = test_manifest(executable);
        let directory = root.0.join("manifests");
        install_manifest_in(&manifest, &directory).unwrap();
        let malformed = directory.join("plugin.json");
        fs::write(&malformed, b"{}").unwrap();
        fs::set_permissions(&malformed, fs::Permissions::from_mode(0o600)).unwrap();

        let report = discover_plugins_in_with_diagnostics(&directory).unwrap();

        assert_eq!(report.plugins, vec![manifest]);
        assert_eq!(report.diagnostics.len(), 1);
        assert_eq!(report.diagnostics[0].path, malformed);
        assert!(report.diagnostics[0].message.contains("UUIDv7"));
    }

    #[cfg(unix)]
    #[test]
    fn discovery_diagnostics_are_bounded() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("bounded-diagnostics");
        for _ in 0..=PLUGIN_LIMIT {
            let path = root.0.join(format!("{}.json", Uuid::now_v7()));
            fs::write(&path, b"not json").unwrap();
            fs::set_permissions(&path, fs::Permissions::from_mode(0o600)).unwrap();
        }

        let report = discover_plugins_in_with_diagnostics(&root.0).unwrap();
        assert!(report.plugins.is_empty());
        assert_eq!(report.diagnostics.len(), PLUGIN_DIAGNOSTIC_LIMIT);
        assert!(report.diagnostics_limited);
        assert!(report.scan_truncated);
        assert!(discover_plugins_in(&root.0).is_err());
    }

    #[test]
    fn directory_entry_limit_is_diagnostic_but_strict_discovery_fails_closed() {
        let root = TestDir::new("entry-limit");
        for index in 0..=PLUGIN_DIRECTORY_ENTRY_LIMIT {
            fs::write(root.0.join(format!("neighbor-{index}")), b"").unwrap();
        }

        let report = discover_plugins_in_with_diagnostics(&root.0).unwrap();

        assert!(report.plugins.is_empty());
        assert!(report.scan_truncated);
        assert!(report
            .diagnostics
            .iter()
            .any(|diagnostic| diagnostic.message.contains("scan stopped")));
        assert!(discover_plugins_in(&root.0).is_err());
    }

    #[cfg(unix)]
    #[test]
    fn special_file_candidates_do_not_block_discovery() {
        let root = TestDir::new("special-file");
        let fifo = root.0.join(format!("{}.json", Uuid::now_v7()));
        rustix::fs::mkfifoat(
            rustix::fs::CWD,
            &fifo,
            rustix::fs::Mode::RUSR | rustix::fs::Mode::WUSR,
        )
        .unwrap();

        assert!(discover_plugins_in(&root.0).unwrap().is_empty());
    }

    #[test]
    fn enabled_plugin_state_round_trips_uuid_v7_ids() {
        let root = TestDir::new("enabled-state");
        let path = root.0.join("guth/enabled-plugins.conf");
        let ids = BTreeSet::from([Uuid::now_v7(), Uuid::now_v7()]);

        write_enabled_plugins_to(&ids, &path).unwrap();
        assert_eq!(load_enabled_plugins_from(&path).unwrap(), ids);
    }

    #[test]
    fn loading_enabled_plugins_does_not_rewrite_or_prune_state() {
        let root = TestDir::new("enabled-state-nondestructive");
        let path = root.0.join("guth/enabled-plugins.conf");
        let ids = BTreeSet::from([Uuid::now_v7(), Uuid::now_v7()]);
        write_enabled_plugins_to(&ids, &path).unwrap();
        let before = fs::read(&path).unwrap();

        assert_eq!(load_enabled_plugins_from(&path).unwrap(), ids);
        assert_eq!(fs::read(path).unwrap(), before);
    }

    #[cfg(unix)]
    #[test]
    fn versioned_action_probe_and_invocation_use_fixed_argv_and_json_stdio() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("action-protocol");
        let executable = root.0.join("plugin");
        let captured = root.0.join("request.json");
        let manifest = test_action_manifest(executable.clone());
        let plugin = manifest.plugin();
        let action = test_action();
        let action_json = serde_json::to_string(&action).unwrap();
        let script = format!(
            "#!/bin/sh\n\
             [ \"$1\" = \"{ACTION_PROTOCOL_ARGUMENT}\" ] || exit 20\n\
             [ \"$2\" = \"{ACTION_PROTOCOL_VERSION}\" ] || exit 21\n\
             case \"$3\" in probe|invoke) ;; *) exit 22 ;; esac\n\
             IFS= read -r request || exit 23\n\
             printf '%s' \"$request\" > '{}'\n\
             if [ \"$3\" = probe ]; then\n\
               printf '%s\\n' '{{\"protocol\":{ACTION_PROTOCOL_VERSION},\"plugin_id\":\"{}\",\"actions\":[{}]}}'\n\
             else\n\
               printf '%s\\n' '{{\"protocol\":{ACTION_PROTOCOL_VERSION},\"plugin_id\":\"{}\",\"action_id\":\"{}\",\"outcome\":\"completed\",\"message\":\"Converted\",\"refresh\":true}}'\n\
             fi\n",
            captured.display(),
            manifest.id,
            action_json,
            manifest.id,
            action.id,
        );
        fs::write(&executable, script).unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let contribution = manifest.contributions.actions;
        let context = test_action_context("txt");

        let actions = probe_plugin_actions(&plugin, &contribution, &context).unwrap();
        assert_eq!(actions, vec![action.clone()]);
        let probe_request =
            parse_plugin_action_probe_request(fs::read(&captured).unwrap().as_slice(), manifest.id)
                .unwrap();
        assert_eq!(probe_request.protocol, ACTION_PROTOCOL_VERSION);
        assert_eq!(probe_request.plugin_id, manifest.id);
        assert_eq!(probe_request.operation, PluginActionOperation::Probe);
        assert_eq!(probe_request.context, context);

        let result = invoke_plugin_action(&plugin, &contribution, &action, &context).unwrap();
        assert_eq!(result.outcome, PluginActionOutcome::Completed);
        assert!(result.refresh);
        let invoke_request = parse_plugin_action_invoke_request(
            fs::read(captured).unwrap().as_slice(),
            manifest.id,
            &[action.id.as_str()],
        )
        .unwrap();
        assert_eq!(invoke_request.operation, PluginActionOperation::Invoke);
        assert_eq!(invoke_request.action_id, action.id);
        assert_eq!(invoke_request.context, context);
    }

    #[test]
    fn action_invocation_rejects_legacy_plugins_and_stale_contexts() {
        let legacy = test_manifest(PathBuf::from("/bin/true"));
        let action_manifest = test_action_manifest(PathBuf::from("/bin/true"));
        let contribution = action_manifest.contributions.actions.clone();
        let action = test_action();

        assert!(
            spawn_plugin_action(&legacy, &contribution, &action, &test_action_context("txt"),)
                .is_err()
        );
        assert!(spawn_plugin_action(
            &action_manifest.plugin(),
            &contribution,
            &action,
            &test_action_context("png"),
        )
        .is_err());
    }

    #[cfg(unix)]
    #[test]
    fn typed_action_results_require_a_successful_process_exit() {
        use std::os::unix::process::ExitStatusExt;

        let action_manifest = test_action_manifest(PathBuf::from("/bin/true"));
        let contribution = action_manifest.contributions.actions.clone();
        let action = test_action();
        let result = PluginActionResult {
            protocol: ACTION_PROTOCOL_VERSION,
            plugin_id: action_manifest.id,
            action_id: action.id.clone(),
            outcome: PluginActionOutcome::Failed,
            message: Some("Conversion failed".to_string()),
            refresh: false,
        };
        let output = PluginOutput {
            status: ExitStatus::from_raw(1 << 8),
            stdout: serde_json::to_vec(&result).unwrap(),
            stderr: b"plugin failed".to_vec(),
        };

        let error =
            parse_plugin_action_result(&action_manifest.plugin(), &contribution, &action, &output)
                .unwrap_err();

        assert!(error.to_string().contains("exited unsuccessfully"));
        assert!(error.to_string().contains("plugin failed"));
    }

    #[cfg(unix)]
    #[test]
    fn spawned_plugins_capture_output_and_exit_status() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("spawn-output");
        let executable = root.0.join("plugin");
        fs::write(
            &executable,
            b"#!/bin/sh\nprintf 'converted:%s' \"$1\"\nprintf 'diagnostic' >&2\nexit 7\n",
        )
        .unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let mut process =
            spawn_plugin(&test_manifest(executable), [OsString::from("track.wav")]).unwrap();
        let output = loop {
            if let Some(output) = process.try_wait().unwrap() {
                break output;
            }
            thread::sleep(Duration::from_millis(5));
        };

        assert_eq!(output.status.code(), Some(7));
        assert_eq!(output.stdout, b"converted:track.wav");
        assert_eq!(output.stderr, b"diagnostic");
    }

    #[cfg(unix)]
    #[test]
    fn plugin_spawn_retries_a_transient_executable_busy_error() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("spawn-busy-retry");
        let executable = root.0.join("plugin");
        fs::write(&executable, b"#!/bin/sh\nexit 0\n").unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let writer = fs::OpenOptions::new()
            .write(true)
            .open(&executable)
            .unwrap();
        let release_writer = thread::spawn(move || {
            thread::sleep(Duration::from_millis(25));
            drop(writer);
        });
        let mut command = Command::new(&executable);
        command
            .stdin(Stdio::null())
            .stdout(Stdio::null())
            .stderr(Stdio::null());

        let status = spawn_plugin_command(&mut command).unwrap().wait().unwrap();
        release_writer.join().unwrap();

        assert!(status.success());
    }

    #[cfg(unix)]
    #[test]
    fn spawned_plugins_can_be_cancelled_and_reaped() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("spawn-cancel");
        let executable = root.0.join("plugin");
        fs::write(&executable, b"#!/bin/sh\nwhile :; do sleep 1; done\n").unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let mut process = spawn_plugin(&test_manifest(executable), []).unwrap();
        thread::sleep(Duration::from_millis(50));
        process.cancel().unwrap();
        assert!(process.cancellation_requested());
        let output = loop {
            if let Some(output) = process.try_wait().unwrap() {
                break output;
            }
            thread::sleep(Duration::from_millis(5));
        };

        assert!(!output.status.success());
    }

    #[cfg(unix)]
    #[test]
    fn cancellation_escalates_when_term_is_ignored() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("spawn-cancel-escalation");
        let executable = root.0.join("plugin");
        fs::write(
            &executable,
            b"#!/bin/sh\ntrap '' TERM\nwhile :; do sleep 1; done\n",
        )
        .unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let mut process = spawn_plugin(&test_manifest(executable), []).unwrap();
        thread::sleep(Duration::from_millis(50));
        process.cancel().unwrap();
        let started = Instant::now();
        let output = loop {
            if let Some(output) = process.try_wait().unwrap() {
                break output;
            }
            assert!(started.elapsed() < Duration::from_secs(3));
            thread::sleep(Duration::from_millis(10));
        };

        assert!(!output.status.success());
    }

    #[cfg(unix)]
    #[test]
    fn dropping_plugin_with_a_descendant_is_bounded() {
        use std::os::unix::fs::PermissionsExt;

        let root = TestDir::new("spawn-drop-descendant");
        let executable = root.0.join("plugin");
        fs::write(&executable, b"#!/bin/sh\nsleep 30 &\nexit 0\n").unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let process = spawn_plugin(&test_manifest(executable), []).unwrap();
        let started = Instant::now();
        drop(process);

        assert!(started.elapsed() < Duration::from_secs(3));
    }
}