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    ThemeRead,
106    EventSubscribe,
107}
108
109impl HostCapability {
110    pub fn as_str(&self) -> &'static str {
111        match self {
112            Self::Navigation => "navigation",
113            Self::AppState => "app_state",
114            Self::FileIntents => "file_intents",
115            Self::FileDialogs => "file_dialogs",
116            Self::AiChat => "aichat",
117            Self::ThemeRead => "theme_read",
118            Self::EventSubscribe => "event_subscribe",
119        }
120    }
121}
122
123impl From<u8> for CapabilityLevel {
124    fn from(v: u8) -> Self {
125        match v {
126            0 => Self::Module,
127            1 => Self::ModuleFeature,
128            2 => Self::UiExtension,
129            3 => Self::AiAssistant,
130            4 => Self::Service,
131            _ => Self::Service,
132        }
133    }
134}
135
136impl From<CapabilityLevel> for u8 {
137    fn from(l: CapabilityLevel) -> u8 {
138        l as u8
139    }
140}
141
142/// Integration configuration block — one sub-block per declared level.
143#[derive(Debug, Clone, Default, Serialize, Deserialize)]
144pub struct IntegrationConfig {
145    #[serde(default)]
146    pub level0: Option<Level0Config>,
147    #[serde(default)]
148    pub level1: Option<Level1Config>,
149    #[serde(default)]
150    pub level2: Option<Level2Config>,
151    #[serde(default)]
152    pub level3: Option<Level3Config>,
153    #[serde(default)]
154    pub level4: Option<Level4Config>,
155}
156
157/// Level 0 — The plugin adds a new top-level module to the sidebar.
158#[derive(Debug, Clone, Serialize, Deserialize)]
159pub struct Level0Config {
160    /// Unique module ID (must not collide with "devkit", "aichat", "settings").
161    pub module_id: String,
162    pub module_label: String,
163    /// Lucide icon name.
164    pub module_icon: String,
165    /// "main" = above the settings divider; "bottom" = below it.
166    #[serde(default = "default_sidebar_position")]
167    pub sidebar_position: String,
168    /// Lower = higher up. Defaults to 100.
169    #[serde(default = "default_sidebar_order")]
170    pub sidebar_order: u32,
171    /// Path inside the package to the JS bundle for this module's panel.
172    pub panel_entry: String,
173}
174
175fn default_sidebar_position() -> String { "main".into() }
176fn default_sidebar_order() -> u32 { 100 }
177
178/// Level 1 — The plugin adds a feature tab to an existing module.
179#[derive(Debug, Clone, Serialize, Deserialize)]
180pub struct Level1Config {
181    /// Target module: "devkit", "aichat", or a plugin module_id.
182    pub parent_module: String,
183    /// Unique tab ID within the parent module.
184    pub tab_id: String,
185    pub tab_label: String,
186    /// Lucide icon name.
187    pub tab_icon: String,
188    /// "after:snippet" | "before:summary" | "index:5"
189    #[serde(default)]
190    pub tab_position: Option<String>,
191    /// Path inside the package to the JS bundle for this tab's panel.
192    pub panel_entry: String,
193}
194
195/// Level 2 — The plugin injects into UI slots.
196#[derive(Debug, Clone, Serialize, Deserialize)]
197pub struct Level2Config {
198    /// Which slots the plugin injects into (see UI Slot Reference in the design doc).
199    pub slots: Vec<String>,
200}
201
202/// Level 3 — The plugin registers an AI assistant.
203#[derive(Debug, Clone, Serialize, Deserialize)]
204pub struct Level3Config {
205    pub assistant_id: String,
206    pub assistant_name: String,
207    #[serde(default)]
208    pub assistant_icon: Option<String>,
209    #[serde(default)]
210    pub assistant_description: Option<String>,
211    /// Path inside the package to the system prompt markdown file.
212    pub system_prompt_file: String,
213    /// Optional: auto-select a specific model_config_id for this assistant.
214    #[serde(default)]
215    pub preferred_model: Option<String>,
216}
217
218/// Level 4 — The plugin registers backend services / workflow step types.
219#[derive(Debug, Clone, Default, Serialize, Deserialize)]
220pub struct Level4Config {
221    /// Step type IDs this plugin registers (e.g. ["p4_sync", "p4_submit"]).
222    #[serde(default)]
223    pub workflow_step_types: Vec<String>,
224}
225
226/// Native library paths per platform.
227#[derive(Debug, Clone, Default, Serialize, Deserialize)]
228pub struct EntryConfig {
229    #[serde(default)]
230    pub native: Option<NativeEntry>,
231    #[serde(default)]
232    pub frontend: Option<String>,
233    #[serde(default)]
234    pub frontend_styles: Option<String>,
235}
236
237#[derive(Debug, Clone, Default, Serialize, Deserialize)]
238pub struct NativeEntry {
239    #[serde(default)]
240    pub macos_arm64: Option<String>,
241    #[serde(default)]
242    pub macos_x64: Option<String>,
243    #[serde(default)]
244    pub windows_x64: Option<String>,
245    #[serde(default)]
246    pub windows_arm64: Option<String>,
247    #[serde(default)]
248    pub linux_x64: Option<String>,
249    #[serde(default)]
250    pub linux_arm64: Option<String>,
251}
252
253impl NativeEntry {
254    /// Return the library path for the current platform/arch, if present.
255    pub fn for_current_platform(&self) -> Option<&str> {
256        #[cfg(all(target_os = "macos", target_arch = "aarch64"))]
257        return self.macos_arm64.as_deref();
258
259        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
260        return self.macos_x64.as_deref();
261
262        #[cfg(all(target_os = "windows", target_arch = "x86_64"))]
263        return self.windows_x64.as_deref();
264
265        #[cfg(all(target_os = "windows", target_arch = "aarch64"))]
266        return self.windows_arm64.as_deref();
267
268        #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
269        return self.linux_x64.as_deref();
270
271        #[cfg(all(target_os = "linux", target_arch = "aarch64"))]
272        return self.linux_arm64.as_deref();
273
274        #[allow(unreachable_code)]
275        None
276    }
277}
278
279#[derive(Debug, Clone, Serialize, Deserialize)]
280pub struct PluginDependency {
281    pub id: String,
282    /// SemVer requirement string, e.g. ">=1.0.0".
283    pub version: String,
284}
285
286#[derive(Debug, Clone, Serialize, Deserialize)]
287pub struct CommandDeclaration {
288    pub id: String,
289    #[serde(default)]
290    pub description: Option<String>,
291}
292
293#[cfg(test)]
294mod tests {
295    use super::{HostCapability, PluginManifest};
296
297    #[test]
298    fn manifest_supports_public_host_api_fields() {
299        let manifest: PluginManifest = serde_json::from_value(serde_json::json!({
300            "id": "dev.haloforge.example",
301            "name": "Example",
302            "version": "0.1.0",
303            "description": "Example plugin",
304            "author": "HaloForge Team",
305            "compatibility": {
306                "min_app_version": "0.1.0",
307                "min_host_api_version": "0.1.0",
308                "platforms": ["windows"]
309            },
310            "capability_levels": [2],
311            "host_capabilities": ["navigation", "aichat"],
312            "integration": {
313                "level2": { "slots": ["devkit.toolbar"] }
314            }
315        }))
316        .expect("manifest should deserialize");
317
318        assert_eq!(
319            manifest.compatibility.min_host_api_version.as_deref(),
320            Some("0.1.0")
321        );
322        assert_eq!(
323            manifest.host_capabilities,
324            vec![HostCapability::Navigation, HostCapability::AiChat]
325        );
326    }
327
328    #[test]
329    fn host_capability_names_are_stable() {
330        assert_eq!(HostCapability::FileIntents.as_str(), "file_intents");
331        assert_eq!(HostCapability::FileDialogs.as_str(), "file_dialogs");
332        assert_eq!(HostCapability::ThemeRead.as_str(), "theme_read");
333    }
334}
haloforge_plugin_api/manifest.rs

haloforge_plugin_api/
manifest.rs
