Struct PluginManager 

pub struct PluginManager { /* private fields */ }

Coordinates plugin discovery, cached metadata, and dispatch settings.

This is the main host-side facade for plugin integration. A typical caller constructs one manager, points it at explicit roots plus optional config and cache roots, then asks it for one of three things:

• plugin inventory via PluginManager::list_plugins
• merged command metadata via PluginManager::command_catalog or PluginManager::command_policy_registry
• dispatch-time configuration such as manager-local provider selections

If you are implementing the plugin executable itself rather than the host, start in crate::core::plugin instead of here.

Implementations

impl PluginManager

pub fn refresh(&self)

Clears both passive and dispatch discovery caches.

Call this after changing plugin search roots or the filesystem state they point at so later browse or dispatch calls rescan discovery inputs. This does not clear in-memory command preferences such as provider selections.

Examples

use osp_cli::plugin::PluginManager;

let manager = PluginManager::new(Vec::new());
manager.refresh();

assert!(manager.list_plugins().is_empty());

impl PluginManager

pub fn dispatch( &self, command: &str, args: &[String], context: &PluginDispatchContext, ) -> Result<ResponseV1, PluginDispatchError>

Runs a plugin command and returns its validated structured response.

command is the full command path resolved against the active plugin catalog. args are passed to the plugin after that command name. context carries runtime hints, optional environment overrides, and an optional one-shot provider override for this dispatch only.

Errors

Returns PluginDispatchError when provider resolution fails, the plugin subprocess cannot be executed, the subprocess times out, the plugin exits non-zero, or the returned JSON is syntactically or semantically invalid.

Examples

use osp_cli::plugin::{PluginDispatchContext, PluginDispatchError, PluginManager};

let err = PluginManager::new(Vec::new())
    .dispatch("shared", &[], &PluginDispatchContext::default())
    .unwrap_err();

assert!(matches!(err, PluginDispatchError::CommandNotFound { .. }));

pub fn dispatch_passthrough( &self, command: &str, args: &[String], context: &PluginDispatchContext, ) -> Result<RawPluginOutput, PluginDispatchError>

Runs a plugin command and returns raw stdout, stderr, and exit status.

Unlike PluginManager::dispatch, this does not attempt to decode or validate plugin JSON output. Non-zero exit codes are returned in RawPluginOutput::status_code rather than surfaced as PluginDispatchError::NonZeroExit.

Errors

Returns PluginDispatchError when provider resolution fails, the plugin subprocess cannot be executed, or the subprocess times out.

Examples

use osp_cli::plugin::{PluginDispatchContext, PluginDispatchError, PluginManager};

let err = PluginManager::new(Vec::new())
    .dispatch_passthrough("shared", &[], &PluginDispatchContext::default())
    .unwrap_err();

assert!(matches!(err, PluginDispatchError::CommandNotFound { .. }));

impl PluginManager

pub fn new(explicit_dirs: Vec<PathBuf>) -> Self

Creates a plugin manager with the provided explicit search roots.

Examples

use osp_cli::plugin::PluginManager;
use std::path::PathBuf;

let manager = PluginManager::new(vec![PathBuf::from("/plugins")]);

assert_eq!(manager.explicit_dirs().len(), 1);

pub fn explicit_dirs(&self) -> &[PathBuf]

Returns the explicit plugin search roots configured for this manager.

pub fn with_roots( self, config_root: Option<PathBuf>, cache_root: Option<PathBuf>, ) -> Self

Sets config and cache roots used for user plugin discovery and describe cache files.

The config root feeds the per-user plugin directory lookup. The cache root feeds the on-disk describe cache. This does not make command provider selections persistent by itself; those remain manager-local in-memory state.

Examples

use osp_cli::plugin::PluginManager;
use std::path::PathBuf;

let manager = PluginManager::new(Vec::new()).with_roots(
    Some(PathBuf::from("/config")),
    Some(PathBuf::from("/cache")),
);

assert_eq!(manager.config_root(), Some(PathBuf::from("/config").as_path()));
assert_eq!(manager.cache_root(), Some(PathBuf::from("/cache").as_path()));

pub fn config_root(&self) -> Option<&Path>

Returns the configured config root used to resolve the user plugin directory.

pub fn cache_root(&self) -> Option<&Path>

Returns the configured cache root used for the describe metadata cache.

pub fn with_default_roots(self, allow_default_roots: bool) -> Self

Enables or disables fallback to platform config/cache roots when explicit roots are not configured.

The default is true. Disable this when the caller wants plugin discovery and describe-cache state to stay fully in-memory unless explicit roots are provided.

pub fn default_roots_enabled(&self) -> bool

Returns whether platform config/cache root fallback is enabled.

pub fn with_process_timeout(self, timeout: Duration) -> Self

Sets the subprocess timeout used for plugin describe and dispatch calls.

Timeout values are clamped to at least one millisecond so the manager never stores a zero-duration subprocess timeout.

Examples

use osp_cli::plugin::PluginManager;
use std::time::Duration;

let manager = PluginManager::new(Vec::new())
    .with_process_timeout(Duration::from_millis(0));

assert_eq!(manager.process_timeout(), Duration::from_millis(1));

pub fn process_timeout(&self) -> Duration

Returns the subprocess timeout used for describe and dispatch calls.

pub fn with_path_discovery(self, allow_path_discovery: bool) -> Self

Enables or disables fallback discovery through the process PATH.

PATH discovery is passive on browse/read surfaces. A PATH-discovered plugin will not be executed for --describe during passive listing or catalog building, so command metadata is unavailable there until the first command dispatch to that plugin. Dispatching a command triggers --describe as a cache miss and writes the result to the on-disk describe cache; subsequent browse and catalog calls will then see the full command metadata.

Examples

use osp_cli::plugin::PluginManager;

let manager = PluginManager::new(Vec::new()).with_path_discovery(true);

assert!(manager.path_discovery_enabled());

pub fn path_discovery_enabled(&self) -> bool

Returns whether fallback discovery through the process PATH is enabled.

pub fn list_plugins(&self) -> Vec<PluginSummary>

Lists discovered plugins with health, command, and enablement status.

When PATH discovery is enabled, PATH-discovered plugins can appear here before their command metadata is available because passive discovery does not execute them for --describe.

Examples

use osp_cli::plugin::PluginManager;

let plugins = PluginManager::new(Vec::new()).list_plugins();

assert!(plugins.is_empty());

pub fn command_catalog(&self) -> Vec<CommandCatalogEntry>

Builds the effective command catalog after provider resolution and health filtering.

This is the host-facing “what commands exist?” view used by help, completion, and similar browse/read surfaces. PATH-discovered plugins only contribute commands here after describe metadata has been cached; passive discovery alone is not enough.

Examples

use osp_cli::plugin::PluginManager;

let catalog = PluginManager::new(Vec::new()).command_catalog();

assert!(catalog.is_empty());

pub fn command_policy_registry(&self) -> CommandPolicyRegistry

Builds a command policy registry from active plugin describe metadata.

Use this when plugin auth hints need to participate in the same runtime visibility and access evaluation as native commands. Commands that still require provider selection are omitted until one provider is selected explicitly.

Examples

use osp_cli::plugin::PluginManager;

let registry = PluginManager::new(Vec::new()).command_policy_registry();

assert!(registry.is_empty());

pub fn completion_words(&self) -> Vec<String>

Returns completion words derived from the current plugin command catalog.

The returned list always includes the REPL backbone words used by the plugin/completion surface, even when no plugins are currently available.

Examples

use osp_cli::plugin::PluginManager;

let words = PluginManager::new(Vec::new()).completion_words();

assert!(words.contains(&"help".to_string()));
assert!(words.contains(&"|".to_string()));

pub fn repl_help_text(&self) -> String

Renders a plain-text help view for plugin commands in the REPL.

Examples

use osp_cli::plugin::PluginManager;

let help = PluginManager::new(Vec::new()).repl_help_text();

assert!(help.contains("Backbone commands: help, exit, quit"));
assert!(help.contains("No plugin commands available."));

pub fn command_providers(&self, command: &str) -> Vec<String>

Returns the available provider labels for a command after health and enablement filtering.

Unknown commands and commands with no currently available providers return an empty list.

Examples

use osp_cli::plugin::PluginManager;

let providers = PluginManager::new(Vec::new()).command_providers("shared");

assert!(providers.is_empty());

pub fn selected_provider_label(&self, command: &str) -> Option<String>

Returns the selected provider label when command resolution is unambiguous.

Returns None when the command is unknown, ambiguous, or currently unavailable after health and enablement filtering.

Examples

use osp_cli::plugin::PluginManager;

let provider = PluginManager::new(Vec::new()).selected_provider_label("shared");

assert_eq!(provider, None);

pub fn doctor(&self) -> DoctorReport

Produces a doctor report with plugin health summaries and command conflicts.

Examples

use osp_cli::plugin::PluginManager;

let report = PluginManager::new(Vec::new()).doctor();

assert!(report.plugins.is_empty());
assert!(report.conflicts.is_empty());

pub fn select_provider(&self, command: &str, plugin_id: &str) -> Result<()>

Applies an explicit provider selection for a command on this manager.

The selection is kept in the manager’s in-memory command-preference state and affects subsequent command resolution through this PluginManager value. It is not written to disk.

Examples

use osp_cli::plugin::PluginManager;
let manager = PluginManager::new(vec![plugins_dir]);

assert_eq!(manager.selected_provider_label("shared"), None);

manager.select_provider("shared", "beta")?;

assert_eq!(
    manager.selected_provider_label("shared").as_deref(),
    Some("beta (explicit)")
);

Errors

Returns an error when command or plugin_id is blank, when no healthy provider currently exports command, or when plugin_id is not one of the healthy providers for command.

pub fn clear_provider_selection(&self, command: &str) -> Result<bool>

Clears any explicit in-memory provider selection for a command.

Examples

use osp_cli::plugin::PluginManager;

let removed = PluginManager::new(Vec::new())
    .clear_provider_selection("shared")
    .unwrap();

assert!(!removed);

Errors

Returns an error when command is blank.

pub fn validate_provider_selection( &self, command: &str, plugin_id: &str, ) -> Result<()>

Verifies that a plugin is a healthy provider candidate for a command.

This validates the command/plugin pair against the manager’s current discovery view but does not change selection state or persist anything.

Examples

use osp_cli::plugin::PluginManager;

let err = PluginManager::new(Vec::new())
    .validate_provider_selection("shared", "alpha")
    .unwrap_err();

assert!(err.to_string().contains("no healthy plugin provides command"));

Errors

Returns an error when no healthy provider currently exports command, or when plugin_id is not one of the healthy providers for command.