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

haloforge_plugin_api/
manifest.rs
