haloforge_plugin_api/
manifest.rs

1use serde::{Deserialize, Serialize};
2use crate::permissions::Permission;
3
4/// Full parsed plugin manifest (from manifest.json inside .hfpkg).
5#[derive(Debug, Clone, Serialize, Deserialize)]
6pub struct PluginManifest {
7    pub id: String,
8    pub name: String,
9    pub version: String,
10    pub description: String,
11    #[serde(default)]
12    pub long_description: Option<String>,
13    pub author: String,
14    #[serde(default)]
15    pub author_url: Option<String>,
16    #[serde(default)]
17    pub homepage: Option<String>,
18    #[serde(default)]
19    pub license: Option<String>,
20    #[serde(default)]
21    pub keywords: Vec<String>,
22    #[serde(default)]
23    pub icon: Option<String>,
24
25    pub compatibility: CompatibilitySpec,
26
27    /// Which capability levels this plugin uses (e.g. [1, 4]).
28    pub capability_levels: Vec<CapabilityLevel>,
29
30    /// Per-level integration configuration.
31    #[serde(default)]
32    pub integration: IntegrationConfig,
33
34    /// Entry points for native library and frontend bundle.
35    #[serde(default)]
36    pub entry: EntryConfig,
37
38    /// Other plugin IDs this plugin depends on.
39    #[serde(default)]
40    pub dependencies: Vec<PluginDependency>,
41
42    /// Declared permissions (checked at install time and enforced at runtime).
43    #[serde(default)]
44    pub permissions: Vec<Permission>,
45
46    /// Declarative access to stable host-side capability groups.
47    /// These should match the host hooks used from `@haloforge/plugin-sdk`.
48    #[serde(default)]
49    pub host_capabilities: Vec<HostCapability>,
50
51    /// JSON Schema for plugin settings (auto-rendered in Plugin Manager).
52    #[serde(default)]
53    pub settings_schema: Option<serde_json::Value>,
54
55    /// IPC commands this plugin registers (informational, for documentation).
56    #[serde(default)]
57    pub commands: Vec<CommandDeclaration>,
58
59    /// SHA-256 checksum of the .hfpkg file. Required for published plugins.
60    #[serde(default)]
61    pub checksum: Option<String>,
62}
63
64#[derive(Debug, Clone, Serialize, Deserialize)]
65pub struct CompatibilitySpec {
66    pub min_app_version: String,
67    #[serde(default)]
68    pub min_host_api_version: Option<String>,
69    #[serde(default)]
70    pub max_app_version: Option<String>,
71    #[serde(default = "all_platforms")]
72    pub platforms: Vec<String>,
73}
74
75fn all_platforms() -> Vec<String> {
76    vec!["windows".into(), "macos".into(), "linux".into()]
77}
78
79/// Capability level integer constants (matching the design doc).
80#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
81#[serde(from = "u8", into = "u8")]
82pub enum CapabilityLevel {
83    /// Level 0 — Top-level module (same tier as DevKit/AIChat).
84    Module = 0,
85    /// Level 1 — Feature inside an existing module.
86    ModuleFeature = 1,
87    /// Level 2 — UI slot injection / extension.
88    UiExtension = 2,
89    /// Level 3 — AI assistant registration.
90    AiAssistant = 3,
91    /// Level 4 — Headless service / backend extension.
92    Service = 4,
93}
94
95/// Stable, documented host capability groups for black-box-compatible plugins.
96#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
97#[serde(rename_all = "snake_case")]
98pub enum HostCapability {
99    Navigation,
100    AppState,
101    FileIntents,
102    FileDialogs,
103    #[serde(rename = "aichat")]
104    AiChat,
105    EnterpriseGateway,
106    ThemeRead,
107    EventSubscribe,
108}
109
110impl HostCapability {
111    pub fn as_str(&self) -> &'static str {
112        match self {
113            Self::Navigation => "navigation",
114            Self::AppState => "app_state",
115            Self::FileIntents => "file_intents",
116            Self::FileDialogs => "file_dialogs",
117            Self::AiChat => "aichat",
118            Self::EnterpriseGateway => "enterprise_gateway",
119            Self::ThemeRead => "theme_read",
120            Self::EventSubscribe => "event_subscribe",
121        }
122    }
123}
124
125impl From<u8> for CapabilityLevel {
126    fn from(v: u8) -> Self {
127        match v {
128            0 => Self::Module,
129            1 => Self::ModuleFeature,
130            2 => Self::UiExtension,
131            3 => Self::AiAssistant,
132            4 => Self::Service,
133            _ => Self::Service,
134        }
135    }
136}
137
138impl From<CapabilityLevel> for u8 {
139    fn from(l: CapabilityLevel) -> u8 {
140        l as u8
141    }
142}
143
144/// Integration configuration block — one sub-block per declared level.
145#[derive(Debug, Clone, Default, Serialize, Deserialize)]
146pub struct IntegrationConfig {
147    #[serde(default)]
148    pub level0: Option<Level0Config>,
149    #[serde(default)]
150    pub level1: Option<Level1Config>,
151    #[serde(default)]
152    pub level2: Option<Level2Config>,
153    #[serde(default)]
154    pub level3: Option<Level3Config>,
155    #[serde(default)]
156    pub level4: Option<Level4Config>,
157}
158
159/// Level 0 — The plugin adds a new top-level module to the sidebar.
160#[derive(Debug, Clone, Serialize, Deserialize)]
161pub struct Level0Config {
162    /// Unique module ID (must not collide with "devkit", "aichat", "settings").
163    pub module_id: String,
164    pub module_label: String,
165    /// Lucide icon name.
166    pub module_icon: String,
167    /// "main" = above the settings divider; "bottom" = below it.
168    #[serde(default = "default_sidebar_position")]
169    pub sidebar_position: String,
170    /// Lower = higher up. Defaults to 100.
171    #[serde(default = "default_sidebar_order")]
172    pub sidebar_order: u32,
173    /// Path inside the package to the JS bundle for this module's panel.
174    pub panel_entry: String,
175}
176
177fn default_sidebar_position() -> String { "main".into() }
178fn default_sidebar_order() -> u32 { 100 }
179
180/// Level 1 — The plugin adds a feature tab to an existing module.
181#[derive(Debug, Clone, Serialize, Deserialize)]
182pub struct Level1Config {
183    /// Target module: "devkit", "aichat", or a plugin module_id.
184    pub parent_module: String,
185    /// Unique tab ID within the parent module.
186    pub tab_id: String,
187    pub tab_label: String,
188    /// Lucide icon name.
189    pub tab_icon: String,
190    /// "after:snippet" | "before:summary" | "index:5"
191    #[serde(default)]
192    pub tab_position: Option<String>,
193    /// Path inside the package to the JS bundle for this tab's panel.
194    pub panel_entry: String,
195}
196
197/// Level 2 — The plugin injects into UI slots.
198#[derive(Debug, Clone, Serialize, Deserialize)]
199pub struct Level2Config {
200    /// Which slots the plugin injects into (see UI Slot Reference in the design doc).
201    pub slots: Vec<String>,
202}
203
204/// Level 3 — The plugin registers an AI assistant.
205#[derive(Debug, Clone, Serialize, Deserialize)]
206pub struct Level3Config {
207    pub assistant_id: String,
208    pub assistant_name: String,
209    #[serde(default)]
210    pub assistant_icon: Option<String>,
211    #[serde(default)]
212    pub assistant_description: Option<String>,
213    /// Path inside the package to the system prompt markdown file.
214    pub system_prompt_file: String,
215    /// Optional: auto-select a specific model_config_id for this assistant.
216    #[serde(default)]
217    pub preferred_model: Option<String>,
218}
219
220/// Level 4 — The plugin registers backend services / workflow step types.
221#[derive(Debug, Clone, Default, Serialize, Deserialize)]
222pub struct Level4Config {
223    /// Step type IDs this plugin registers (e.g. ["p4_sync", "p4_submit"]).
224    #[serde(default)]
225    pub workflow_step_types: Vec<String>,
226}
227
228/// Native library paths per platform.
229#[derive(Debug, Clone, Default, Serialize, Deserialize)]
230pub struct EntryConfig {
231    #[serde(default)]
232    pub native: Option<NativeEntry>,
233    #[serde(default)]
234    pub frontend: Option<String>,
235    #[serde(default)]
236    pub frontend_styles: Option<String>,
237}
238
239#[derive(Debug, Clone, Default, Serialize, Deserialize)]
240pub struct NativeEntry {
241    #[serde(default)]
242    pub macos_arm64: Option<String>,
243    #[serde(default)]
244    pub macos_x64: Option<String>,
245    #[serde(default)]
246    pub windows_x64: Option<String>,
247    #[serde(default)]
248    pub windows_arm64: Option<String>,
249    #[serde(default)]
250    pub linux_x64: Option<String>,
251    #[serde(default)]
252    pub linux_arm64: Option<String>,
253}
254
255impl NativeEntry {
256    /// Return the library path for the current platform/arch, if present.
257    pub fn for_current_platform(&self) -> Option<&str> {
258        #[cfg(all(target_os = "macos", target_arch = "aarch64"))]
259        return self.macos_arm64.as_deref();
260
261        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
262        return self.macos_x64.as_deref();
263
264        #[cfg(all(target_os = "windows", target_arch = "x86_64"))]
265        return self.windows_x64.as_deref();
266
267        #[cfg(all(target_os = "windows", target_arch = "aarch64"))]
268        return self.windows_arm64.as_deref();
269
270        #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
271        return self.linux_x64.as_deref();
272
273        #[cfg(all(target_os = "linux", target_arch = "aarch64"))]
274        return self.linux_arm64.as_deref();
275
276        #[allow(unreachable_code)]
277        None
278    }
279}
280
281#[derive(Debug, Clone, Serialize, Deserialize)]
282pub struct PluginDependency {
283    pub id: String,
284    /// SemVer requirement string, e.g. ">=1.0.0".
285    pub version: String,
286}
287
288#[derive(Debug, Clone, Serialize, Deserialize)]
289pub struct CommandDeclaration {
290    pub id: String,
291    #[serde(default)]
292    pub description: Option<String>,
293}
294
295#[cfg(test)]
296mod tests {
297    use super::{HostCapability, PluginManifest};
298
299    #[test]
300    fn manifest_supports_public_host_api_fields() {
301        let manifest: PluginManifest = serde_json::from_value(serde_json::json!({
302            "id": "dev.haloforge.example",
303            "name": "Example",
304            "version": "0.1.0",
305            "description": "Example plugin",
306            "author": "HaloForge Team",
307            "compatibility": {
308                "min_app_version": "0.1.0",
309                "min_host_api_version": "0.1.0",
310                "platforms": ["windows"]
311            },
312            "capability_levels": [2],
313            "host_capabilities": ["navigation", "aichat"],
314            "integration": {
315                "level2": { "slots": ["devkit.toolbar"] }
316            }
317        }))
318        .expect("manifest should deserialize");
319
320        assert_eq!(
321            manifest.compatibility.min_host_api_version.as_deref(),
322            Some("0.1.0")
323        );
324        assert_eq!(
325            manifest.host_capabilities,
326            vec![HostCapability::Navigation, HostCapability::AiChat]
327        );
328    }
329
330    #[test]
331    fn host_capability_names_are_stable() {
332        assert_eq!(HostCapability::FileIntents.as_str(), "file_intents");
333        assert_eq!(HostCapability::FileDialogs.as_str(), "file_dialogs");
334        assert_eq!(HostCapability::ThemeRead.as_str(), "theme_read");
335    }
336}
haloforge_plugin_api/manifest.rs

haloforge_plugin_api/
manifest.rs
