Skip to main content

agent_engine/skills/
manifest.rs

1//! Parse .synaps-plugin/plugin.json and .synaps-plugin/marketplace.json.
2
3use serde::Deserialize;
4
5use super::keybinds::ManifestKeybind;
6use super::plugin_index::PluginIndexEntry;
7
8#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
9pub struct PluginCompatibility {
10    #[serde(default)]
11    pub synaps: Option<String>,
12    #[serde(default)]
13    pub extension_protocol: Option<String>,
14}
15
16#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
17#[serde(untagged)]
18pub enum ManifestCommand {
19    Shell(ManifestShellCommand),
20    ExtensionTool(ManifestExtensionToolCommand),
21    SkillPrompt(ManifestSkillPromptCommand),
22    Interactive(ManifestInteractiveCommand),
23}
24
25#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
26pub struct ManifestShellCommand {
27    pub name: String,
28    #[serde(default)]
29    pub description: Option<String>,
30    pub command: String,
31    #[serde(default)]
32    pub args: Vec<String>,
33}
34
35#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
36pub struct ManifestExtensionToolCommand {
37    pub name: String,
38    #[serde(default)]
39    pub description: Option<String>,
40    pub tool: String,
41    #[serde(default)]
42    pub input: serde_json::Value,
43}
44
45#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
46pub struct ManifestSkillPromptCommand {
47    pub name: String,
48    #[serde(default)]
49    pub description: Option<String>,
50    pub skill: String,
51    pub prompt: String,
52}
53
54#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
55pub struct ManifestInteractiveCommand {
56    pub name: String,
57    #[serde(default)]
58    pub description: Option<String>,
59    /// Route this slash command to the plugin extension's `command.invoke` RPC.
60    pub interactive: bool,
61    #[serde(default)]
62    pub subcommands: Vec<String>,
63}
64
65#[derive(Debug, Clone, Deserialize)]
66pub struct PluginManifest {
67    pub name: String,
68    #[serde(default)]
69    pub version: Option<String>,
70    #[serde(default)]
71    pub description: Option<String>,
72    #[serde(default)]
73    pub keybinds: Vec<ManifestKeybind>,
74    #[serde(default)]
75    pub compatibility: Option<PluginCompatibility>,
76    #[serde(default)]
77    pub commands: Vec<ManifestCommand>,
78    #[serde(default)]
79    pub extension: Option<crate::extensions::manifest::ExtensionManifest>,
80    #[serde(default, alias = "help")]
81    pub help_entries: Vec<crate::help::HelpEntry>,
82    /// Plugin-declared Settings categories (Path B Phase 4). Each plugin
83    /// may contribute one or more categories to the `/settings` modal,
84    /// each with declarative `text`/`cycler`/`picker` fields or a
85    /// plugin-rendered `custom` editor (JSON-RPC `settings.editor.*`).
86    #[serde(default)]
87    pub settings: Option<ManifestSettings>,
88}
89
90/// Container for plugin-declared settings categories.
91///
92/// JSON shape:
93/// ```jsonc
94/// "settings": {
95///   "category": [
96///     { "id": "capture", "label": "Sample", "fields": [ ... ] }
97///   ]
98/// }
99/// ```
100/// The TOML equivalent (`[[settings.category]]`) deserializes through the
101/// `category` alias. The plural Rust field name is preferred internally.
102#[derive(Debug, Clone, Default, Deserialize, PartialEq, Eq)]
103pub struct ManifestSettings {
104    #[serde(default, alias = "category")]
105    pub categories: Vec<ManifestSettingsCategory>,
106}
107
108#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
109pub struct ManifestSettingsCategory {
110    pub id: String,
111    pub label: String,
112    #[serde(default)]
113    pub fields: Vec<ManifestSettingsField>,
114}
115
116#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
117pub struct ManifestSettingsField {
118    pub key: String,
119    pub label: String,
120    pub editor: ManifestEditorKind,
121    /// Discrete options for `cycler` editors. Ignored otherwise.
122    #[serde(default)]
123    pub options: Vec<String>,
124    #[serde(default)]
125    pub help: Option<String>,
126    /// Optional default value seeded into the plugin's config namespace
127    /// when the field is first read. Type-erased JSON; consumer decides
128    /// how to interpret based on `editor`.
129    #[serde(default)]
130    pub default: Option<serde_json::Value>,
131    /// `true` for fields whose editor is `text` and accepts only numeric
132    /// input. Mirrors `EditorKind::Text { numeric }` in the core schema.
133    #[serde(default)]
134    pub numeric: bool,
135}
136
137#[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
138#[serde(rename_all = "lowercase")]
139pub enum ManifestEditorKind {
140    /// Free-text input (optionally numeric — see `numeric`).
141    Text,
142    /// Discrete-option cycler — uses `options`.
143    Cycler,
144    /// Generic picker. Options are supplied by the plugin at editor-open
145    /// time via the `settings.editor.*` JSON-RPC contract.
146    Picker,
147    /// Plugin-rendered overlay using `settings.editor.open` /
148    /// `settings.editor.render` / `settings.editor.key` /
149    /// `settings.editor.commit`. See
150    /// `src/extensions/settings_editor.rs` for the typed payloads.
151    Custom,
152}
153
154#[derive(Debug, Clone, Deserialize)]
155pub struct MarketplaceManifest {
156    pub name: String,
157    #[serde(default)]
158    pub version: Option<String>,
159    #[serde(default)]
160    pub description: Option<String>,
161    #[serde(default)]
162    pub categories: Vec<String>,
163    #[serde(default)]
164    pub keywords: Vec<String>,
165    #[serde(default)]
166    pub trust: Option<MarketplaceTrust>,
167    pub plugins: Vec<MarketplacePluginEntry>,
168}
169
170#[derive(Debug, Clone, Deserialize)]
171pub struct MarketplaceTrust {
172    #[serde(default)]
173    pub publisher: Option<String>,
174    #[serde(default)]
175    pub homepage: Option<String>,
176}
177
178#[derive(Debug, Clone, Deserialize)]
179pub struct MarketplacePluginEntry {
180    pub name: String,
181    #[serde(default)]
182    pub source: Option<String>,
183    #[serde(default)]
184    pub version: Option<String>,
185    #[serde(default)]
186    pub description: Option<String>,
187    #[serde(default)]
188    pub category: Option<String>,
189    #[serde(default)]
190    pub keywords: Vec<String>,
191    #[serde(default)]
192    pub license: Option<String>,
193    #[serde(default)]
194    pub index: Option<PluginIndexEntry>,
195}
196
197#[cfg(test)]
198mod tests {
199    use super::*;
200
201    #[test]
202    fn plugin_manifest_minimal() {
203        let json = r#"{"name":"web-tools"}"#;
204        let m: PluginManifest = serde_json::from_str(json).unwrap();
205        assert_eq!(m.name, "web-tools");
206        assert_eq!(m.version, None);
207        assert_eq!(m.description, None);
208        assert!(m.commands.is_empty());
209        assert!(m.help_entries.is_empty());
210        assert!(m.compatibility.is_none());
211    }
212
213    #[test]
214    fn plugin_manifest_full_with_extras() {
215        let json = r#"{
216            "name": "web-tools",
217            "version": "1.0.0",
218            "description": "Web tools",
219            "author": {"name": "x"},
220            "repository": "https://...",
221            "license": "MIT",
222            "compatibility": {
223                "synaps": ">=0.1.0",
224                "extension_protocol": "1"
225            },
226            "unknown_field": 42
227        }"#;
228        let m: PluginManifest = serde_json::from_str(json).unwrap();
229        assert_eq!(m.name, "web-tools");
230        assert_eq!(m.version.as_deref(), Some("1.0.0"));
231        assert_eq!(m.description.as_deref(), Some("Web tools"));
232        assert_eq!(
233            m.compatibility.as_ref().unwrap().synaps.as_deref(),
234            Some(">=0.1.0")
235        );
236        assert_eq!(
237            m.compatibility
238                .as_ref()
239                .unwrap()
240                .extension_protocol
241                .as_deref(),
242            Some("1")
243        );
244    }
245
246    #[test]
247    fn plugin_manifest_parses_help_entries_with_usage_examples() {
248        let json = r#"{
249            "name": "web-tools",
250            "help_entries": [
251                {
252                    "id": "web-search-help",
253                    "command": "/web:search",
254                    "title": "Web Search",
255                    "summary": "Search the web from a plugin.",
256                    "category": "Plugin",
257                    "topic": "Command",
258                    "protected": false,
259                    "common": false,
260                    "keywords": ["web", "search"],
261                    "usage": "/web:search <query>",
262                    "examples": [
263                        {
264                            "command": "/web:search rust serde",
265                            "description": "Search for Rust serde resources."
266                        }
267                    ]
268                }
269            ]
270        }"#;
271        let m: PluginManifest = serde_json::from_str(json).unwrap();
272        assert_eq!(m.help_entries.len(), 1);
273        assert_eq!(m.help_entries[0].command, "/web:search");
274        assert_eq!(
275            m.help_entries[0].usage.as_deref(),
276            Some("/web:search <query>")
277        );
278        assert_eq!(
279            m.help_entries[0].examples[0].command,
280            "/web:search rust serde"
281        );
282    }
283
284    #[test]
285    fn plugin_manifest_accepts_help_alias_for_help_entries() {
286        let json = r#"{
287            "name": "web-tools",
288            "help": [
289                {
290                    "id": "web-help",
291                    "command": "/help web",
292                    "title": "Web Tools",
293                    "summary": "Use web tools from the plugin.",
294                    "category": "Plugin",
295                    "topic": "Branch",
296                    "protected": false,
297                    "common": false
298                }
299            ]
300        }"#;
301        let m: PluginManifest = serde_json::from_str(json).unwrap();
302        assert_eq!(m.help_entries.len(), 1);
303        assert_eq!(m.help_entries[0].command, "/help web");
304        assert_eq!(m.help_entries[0].topic, crate::help::HelpTopicKind::Branch);
305    }
306
307    #[test]
308    fn plugin_manifest_can_add_command_and_matching_help_entries_together() {
309        let json = r#"{
310            "name": "dev-tools",
311            "commands": [
312                {
313                    "name": "lint",
314                    "description": "Run lint",
315                    "command": "bash",
316                    "args": ["scripts/lint.sh"]
317                }
318            ],
319            "help_entries": [
320                {
321                    "id": "dev-lint-help",
322                    "command": "/dev-tools:lint",
323                    "title": "Lint",
324                    "summary": "Run plugin lint checks.",
325                    "category": "Plugin",
326                    "topic": "Command",
327                    "protected": false,
328                    "common": false,
329                    "usage": "/dev-tools:lint"
330                }
331            ]
332        }"#;
333        let m: PluginManifest = serde_json::from_str(json).unwrap();
334        assert_eq!(m.commands.len(), 1);
335        assert_eq!(m.help_entries.len(), 1);
336        assert_eq!(m.help_entries[0].command, "/dev-tools:lint");
337    }
338
339    #[test]
340    fn plugin_manifest_help_entries_default_boilerplate_fields() {
341        let json = r#"{
342            "name": "dev-tools",
343            "help": [
344                {
345                    "id": "dev-lint-help",
346                    "command": "/dev-tools:lint",
347                    "title": "Lint",
348                    "summary": "Run plugin lint checks."
349                }
350            ]
351        }"#;
352        let m: PluginManifest = serde_json::from_str(json).unwrap();
353        assert_eq!(m.help_entries.len(), 1);
354        assert_eq!(m.help_entries[0].category, "Plugin");
355        assert_eq!(m.help_entries[0].topic, crate::help::HelpTopicKind::Command);
356        assert!(!m.help_entries[0].protected);
357        assert!(!m.help_entries[0].common);
358    }
359
360    #[test]
361    fn plugin_manifest_parses_interactive_command() {
362        let json = r#"{
363            "name": "demo-plugin",
364            "commands": [
365                {
366                    "name": "demo",
367                    "description": "Run interactive demo",
368                    "interactive": true,
369                    "subcommands": ["models", "download"]
370                }
371            ]
372        }"#;
373        let m: PluginManifest = serde_json::from_str(json).unwrap();
374        match &m.commands[0] {
375            ManifestCommand::Interactive(cmd) => {
376                assert_eq!(cmd.name, "demo");
377                assert_eq!(cmd.description.as_deref(), Some("Run interactive demo"));
378                assert_eq!(cmd.subcommands, vec!["models", "download"]);
379            }
380            other => panic!("expected interactive command, got {other:?}"),
381        }
382    }
383
384    #[test]
385    fn plugin_manifest_parses_commands() {
386        let json = r#"{
387            "name": "dev-tools",
388            "commands": [
389                {
390                    "name": "lint",
391                    "description": "Run lint",
392                    "command": "bash",
393                    "args": ["scripts/lint.sh"]
394                }
395            ]
396        }"#;
397        let m: PluginManifest = serde_json::from_str(json).unwrap();
398        assert_eq!(m.commands.len(), 1);
399        match &m.commands[0] {
400            ManifestCommand::Shell(cmd) => {
401                assert_eq!(cmd.name, "lint");
402                assert_eq!(cmd.description.as_deref(), Some("Run lint"));
403                assert_eq!(cmd.command, "bash");
404                assert_eq!(cmd.args, vec!["scripts/lint.sh"]);
405            }
406            other => panic!("expected shell command, got {other:?}"),
407        }
408    }
409
410    #[test]
411    fn plugin_manifest_parses_extension_tool_command() {
412        let json = r#"{
413            "name": "dev-tools",
414            "commands": [
415                {
416                    "name": "echo",
417                    "description": "Echo via extension tool",
418                    "tool": "echo",
419                    "input": {"text": "hello"}
420                }
421            ]
422        }"#;
423        let m: PluginManifest = serde_json::from_str(json).unwrap();
424        match &m.commands[0] {
425            ManifestCommand::ExtensionTool(cmd) => {
426                assert_eq!(cmd.name, "echo");
427                assert_eq!(cmd.tool, "echo");
428                assert_eq!(cmd.input["text"], "hello");
429            }
430            other => panic!("expected extension tool command, got {other:?}"),
431        }
432    }
433
434    #[test]
435    fn plugin_manifest_parses_skill_prompt_command() {
436        let json = r#"{
437            "name": "dev-tools",
438            "commands": [
439                {
440                    "name": "review",
441                    "description": "Run review skill",
442                    "skill": "reviewer",
443                    "prompt": "Review this diff"
444                }
445            ]
446        }"#;
447        let m: PluginManifest = serde_json::from_str(json).unwrap();
448        match &m.commands[0] {
449            ManifestCommand::SkillPrompt(cmd) => {
450                assert_eq!(cmd.name, "review");
451                assert_eq!(cmd.skill, "reviewer");
452                assert_eq!(cmd.prompt, "Review this diff");
453            }
454            other => panic!("expected skill prompt command, got {other:?}"),
455        }
456    }
457
458    #[test]
459    fn plugin_manifest_command_missing_command_fails() {
460        let json = r#"{"name":"p","commands":[{"name":"x"}]}"#;
461        let result: Result<PluginManifest, _> = serde_json::from_str(json);
462        assert!(result.is_err());
463    }
464
465    #[test]
466    fn plugin_manifest_missing_name_fails() {
467        let json = r#"{"version":"1.0.0"}"#;
468        let result: Result<PluginManifest, _> = serde_json::from_str(json);
469        assert!(result.is_err());
470    }
471
472    #[test]
473    fn marketplace_manifest_basic() {
474        let json = r#"{
475            "name": "pi-skills",
476            "version": "1.0.0",
477            "description": "Plugin index",
478            "categories": ["productivity"],
479            "keywords": ["local-first"],
480            "trust": {"publisher":"Maha Media","homepage":"https://example.com"},
481            "plugins": [
482                {"name": "web-tools", "source": "./web-tools-plugin", "category":"research", "keywords":["web"]},
483                {"name": "dev-tools", "source": "./dev-tools", "version": "2.0.0", "license":"MIT"}
484            ]
485        }"#;
486        let m: MarketplaceManifest = serde_json::from_str(json).unwrap();
487        assert_eq!(m.name, "pi-skills");
488        assert_eq!(m.categories, vec!["productivity"]);
489        assert_eq!(m.keywords, vec!["local-first"]);
490        assert_eq!(
491            m.trust.as_ref().unwrap().publisher.as_deref(),
492            Some("Maha Media")
493        );
494        assert_eq!(m.plugins.len(), 2);
495        assert_eq!(m.plugins[0].name, "web-tools");
496        assert_eq!(m.plugins[0].source.as_deref(), Some("./web-tools-plugin"));
497        assert_eq!(m.plugins[0].category.as_deref(), Some("research"));
498        assert_eq!(m.plugins[0].keywords, vec!["web"]);
499    }
500
501    #[test]
502    fn marketplace_manifest_missing_plugins_fails() {
503        let json = r#"{"name":"empty"}"#;
504        let result: Result<MarketplaceManifest, _> = serde_json::from_str(json);
505        assert!(result.is_err());
506    }
507
508    #[test]
509    fn plugin_manifest_parses_settings_categories_with_declarative_fields() {
510        let json = r#"{
511            "name": "demo",
512            "settings": {
513                "category": [
514                    {
515                        "id": "demo",
516                        "label": "Demo",
517                        "fields": [
518                            {
519                                "key": "backend",
520                                "label": "Backend",
521                                "editor": "cycler",
522                                "options": ["auto", "cpu", "cuda"]
523                            },
524                            {
525                                "key": "endpoint",
526                                "label": "API endpoint",
527                                "editor": "text",
528                                "help": "Base URL"
529                            },
530                            {
531                                "key": "max_tokens",
532                                "label": "Max tokens",
533                                "editor": "text",
534                                "numeric": true,
535                                "default": 2048
536                            },
537                            {
538                                "key": "model_path",
539                                "label": "Model",
540                                "editor": "custom"
541                            },
542                            {
543                                "key": "preset",
544                                "label": "Preset",
545                                "editor": "picker"
546                            }
547                        ]
548                    }
549                ]
550            }
551        }"#;
552        let m: PluginManifest = serde_json::from_str(json).unwrap();
553        let s = m.settings.expect("settings should deserialize");
554        assert_eq!(s.categories.len(), 1);
555        let cat = &s.categories[0];
556        assert_eq!(cat.id, "demo");
557        assert_eq!(cat.label, "Demo");
558        assert_eq!(cat.fields.len(), 5);
559
560        assert_eq!(cat.fields[0].key, "backend");
561        assert_eq!(cat.fields[0].editor, ManifestEditorKind::Cycler);
562        assert_eq!(cat.fields[0].options, vec!["auto", "cpu", "cuda"]);
563
564        assert_eq!(cat.fields[1].editor, ManifestEditorKind::Text);
565        assert!(!cat.fields[1].numeric);
566        assert_eq!(cat.fields[1].help.as_deref(), Some("Base URL"));
567
568        assert_eq!(cat.fields[2].editor, ManifestEditorKind::Text);
569        assert!(cat.fields[2].numeric);
570        assert_eq!(cat.fields[2].default, Some(serde_json::json!(2048)));
571
572        assert_eq!(cat.fields[3].editor, ManifestEditorKind::Custom);
573        assert_eq!(cat.fields[4].editor, ManifestEditorKind::Picker);
574    }
575
576    #[test]
577    fn plugin_manifest_settings_default_to_none() {
578        let json = r#"{"name":"plain"}"#;
579        let m: PluginManifest = serde_json::from_str(json).unwrap();
580        assert!(m.settings.is_none());
581    }
582
583    #[test]
584    fn plugin_manifest_settings_unknown_editor_kind_fails() {
585        let json = r#"{
586            "name": "demo",
587            "settings": {
588                "category": [
589                    { "id": "x", "label": "X", "fields": [
590                        { "key": "k", "label": "L", "editor": "bogus" }
591                    ] }
592                ]
593            }
594        }"#;
595        let result: Result<PluginManifest, _> = serde_json::from_str(json);
596        assert!(result.is_err());
597    }
598
599    #[test]
600    fn plugin_manifest_settings_additive_with_help_entries_field() {
601        // Verifies the `settings` field (Phase 4) and the `help_entries`
602        // field (help-command series) coexist on PluginManifest.
603        let json = r#"{
604            "name": "merge-friendly",
605            "settings": {
606                "category": [
607                    { "id": "x", "label": "X", "fields": [] }
608                ]
609            },
610            "help_entries": [
611                {
612                    "id": "x-do",
613                    "command": "/x:do",
614                    "title": "Do",
615                    "summary": "do a thing"
616                }
617            ]
618        }"#;
619        let m: PluginManifest = serde_json::from_str(json).unwrap();
620        assert!(m.settings.is_some());
621        assert_eq!(m.settings.unwrap().categories[0].id, "x");
622        assert_eq!(m.help_entries.len(), 1);
623        assert_eq!(m.help_entries[0].command, "/x:do");
624    }
625
626    #[test]
627    fn marketplace_entry_missing_source_is_allowed_for_index_backed_entries() {
628        let json = r#"{"name":"p","plugins":[{"name":"x"}]}"#;
629        let m: MarketplaceManifest = serde_json::from_str(json).unwrap();
630        assert!(m.plugins[0].source.is_none());
631    }
632}