Plugin Discovery & Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
The Zephyr plugin system allows you to extend the application's capabilities through external modules managed by the Prism Engine. The system handles the entire lifecycle of a plugin, from scanning the local file system to execution, hook triggering, and uninstallation. Plugins run within a secure environment with fine-grained permission controls to protect system integrity.
Sources: FEATURES.md, README_en.md
Plugin Discovery
The Prism Engine discovers plugins by scanning the prism/plugins/ directory for valid plugin structures. You trigger this process manually through the user interface to refresh the list of available extensions.
Sources: apps/desktop/src/ui/plugins-smart.js:68-83
Discovery Flow
The discovery process identifies metadata such as the plugin ID, name, description, and version.
The diagram shows the sequential steps from a user request to the visual rendering of discovered plugins.
Sources: apps/desktop/src/ui/plugins-smart.js:68-83
Lifecycle Management
Plugin lifecycle states include discovered, loaded, executed, and unloaded. The backend provides IPC commands to transition plugins between these states.
State Transitions
| Action | Description | Resulting State |
|---|---|---|
| Load | Loads the plugin into the Prism Engine memory. | Loaded |
| Execute | Runs the entry script of the loaded plugin. | Running/Completed |
| Unload | Removes the plugin from active memory. | Discovered |
| Delete | Removes the plugin files from the directory. | Uninstalled |
Sources: apps/desktop/src/ui/plugins-smart.js:125-144, apps/desktop/src-tauri/src/prism/plugin_commands.rs
Lifecycle Execution Sequence
When you interact with a plugin card, the frontend communicates with the Rust backend to manage the plugin's state.
The sequence diagram illustrates the communication between the UI components and the backend engine during lifecycle operations.
Sources: apps/desktop/src/ui/plugins-smart.js:125-144
Hooks and Event Triggering
Plugins can subscribe to specific system events known as "Hooks." These allow plugins to react to internal application changes. You can also manually trigger hooks for testing or specific workflows.
- Hook Discovery: You can list all available hooks for a specific plugin or use a wildcard (
*) to see all system hooks. - High Frequency: Some hooks are flagged as
high-freq, indicating they trigger often and require efficient logic. - Execution: Triggering a hook returns a result list showing which plugins responded successfully.
Sources: apps/desktop/src/ui/plugins-smart.js:154-184, apps/desktop/src-tauri/src/prism/plugin_commands.rs
Permission Control
The system implements a fine-grained permission model to restrict plugin actions. Permissions are categorized based on their intended use case, such as configuration modification or UI extension.
| Permission Attribute | Description |
|---|---|
| name | Technical identifier for the permission. |
| displayName | Human-readable label shown in the UI. |
| allowedForConfigPlugin | Boolean indicating if config-level plugins can use it. |
| allowedForUiExtension | Boolean indicating if UI-level extensions can use it. |
Sources: apps/desktop/src/ui/plugins-smart.js:189-216, apps/desktop/src-tauri/src/prism/plugin_commands.rs
Data Persistence (KV Store)
Plugins access a persistent Key-Value (KV) store to save state across application restarts. The Prism Engine manages this store, and you can view or modify entries directly through the Settings interface.
Sources: apps/desktop/src/ui/plugins-smart.js:88-100, FEATURES.md
KV Operations
The UI supports CRUD operations on the plugin data store:
kvKeys(): Retrieves all stored keys.kvGet(key): Fetches a specific value.kvSet(key, value): Updates or creates an entry.kvDelete(key): Removes an entry.
Sources: apps/desktop/src/ui/plugins-smart.js:221-270
Conclusion
The Plugin Discovery & Lifecycle system provides a managed environment for extending Zephyr's functionality. By combining automated discovery, controlled lifecycle transitions, and strict permission checks, the Prism Engine ensures that extensions are powerful yet secure. Developers can leverage hooks and the KV store to create complex integrations while users maintain full control over which plugins are active.