1use std::ffi::OsStr;
2use std::fmt;
3use std::path::{Path, PathBuf};
4use std::sync::Arc;
5
6use anyhow::{Context as _, Result, anyhow, bail};
7use cloud_api_types::ExtensionProvides;
8use collections::{BTreeMap, BTreeSet, HashMap};
9use fs::Fs;
10use language::LanguageName;
11use lsp::LanguageServerName;
12use semver::Version;
13use serde::{Deserialize, Serialize};
14
15use crate::ExtensionCapability;
16
17/// This is the old version of the extension manifest, from when it was `extension.json`.
18#[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
19pub struct OldExtensionManifest {
20 pub name: String,
21 pub version: Arc<str>,
22
23 #[serde(default)]
24 pub description: Option<String>,
25 #[serde(default)]
26 pub repository: Option<String>,
27 #[serde(default)]
28 pub authors: Vec<String>,
29
30 #[serde(default)]
31 pub themes: BTreeMap<Arc<str>, PathBuf>,
32 #[serde(default)]
33 pub languages: BTreeMap<Arc<str>, PathBuf>,
34 #[serde(default)]
35 pub grammars: BTreeMap<Arc<str>, PathBuf>,
36}
37
38/// The schema version of the [`ExtensionManifest`].
39#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy, Serialize, Deserialize)]
40pub struct SchemaVersion(pub i32);
41
42impl fmt::Display for SchemaVersion {
43 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
44 write!(f, "{}", self.0)
45 }
46}
47
48impl SchemaVersion {
49 pub const ZERO: Self = Self(0);
50
51 pub fn is_v0(&self) -> bool {
52 self == &Self::ZERO
53 }
54}
55
56// TODO: We should change this to just always be a Vec<PathBuf> once we bump the
57// extension.toml schema version to 2
58#[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
59#[serde(untagged)]
60pub enum ExtensionSnippets {
61 Single(PathBuf),
62 Multiple(Vec<PathBuf>),
63}
64
65impl ExtensionSnippets {
66 pub fn paths(&self) -> impl Iterator<Item = &PathBuf> {
67 match self {
68 ExtensionSnippets::Single(path) => std::slice::from_ref(path).iter(),
69 ExtensionSnippets::Multiple(paths) => paths.iter(),
70 }
71 }
72}
73
74impl From<&str> for ExtensionSnippets {
75 fn from(value: &str) -> Self {
76 ExtensionSnippets::Single(value.into())
77 }
78}
79
80#[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
81pub struct ExtensionManifest {
82 pub id: Arc<str>,
83 pub name: String,
84 pub version: Arc<str>,
85 pub schema_version: SchemaVersion,
86
87 #[serde(default)]
88 pub description: Option<String>,
89 #[serde(default)]
90 pub repository: Option<String>,
91 #[serde(default)]
92 pub authors: Vec<String>,
93 #[serde(default)]
94 pub lib: LibManifestEntry,
95
96 #[serde(default)]
97 pub themes: Vec<PathBuf>,
98 #[serde(default)]
99 pub icon_themes: Vec<PathBuf>,
100 #[serde(default)]
101 pub languages: Vec<PathBuf>,
102 #[serde(default)]
103 pub grammars: BTreeMap<Arc<str>, GrammarManifestEntry>,
104 #[serde(default)]
105 pub language_servers: BTreeMap<LanguageServerName, LanguageServerManifestEntry>,
106 #[serde(default)]
107 pub context_servers: BTreeMap<Arc<str>, ContextServerManifestEntry>,
108 #[serde(default)]
109 pub agent_servers: BTreeMap<Arc<str>, AgentServerManifestEntry>,
110 #[serde(default)]
111 pub slash_commands: BTreeMap<Arc<str>, SlashCommandManifestEntry>,
112 #[serde(default)]
113 pub snippets: Option<ExtensionSnippets>,
114 #[serde(default)]
115 pub capabilities: Vec<ExtensionCapability>,
116 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
117 pub debug_adapters: BTreeMap<Arc<str>, DebugAdapterManifestEntry>,
118 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
119 pub debug_locators: BTreeMap<Arc<str>, DebugLocatorManifestEntry>,
120 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
121 pub language_model_providers: BTreeMap<Arc<str>, LanguageModelProviderManifestEntry>,
122}
123
124impl ExtensionManifest {
125 /// Returns the set of features provided by the extension.
126 pub fn provides(&self) -> BTreeSet<ExtensionProvides> {
127 let mut provides = BTreeSet::default();
128 if !self.themes.is_empty() {
129 provides.insert(ExtensionProvides::Themes);
130 }
131
132 if !self.icon_themes.is_empty() {
133 provides.insert(ExtensionProvides::IconThemes);
134 }
135
136 if !self.languages.is_empty() {
137 provides.insert(ExtensionProvides::Languages);
138 }
139
140 if !self.grammars.is_empty() {
141 provides.insert(ExtensionProvides::Grammars);
142 }
143
144 if !self.language_servers.is_empty() {
145 provides.insert(ExtensionProvides::LanguageServers);
146 }
147
148 if !self.context_servers.is_empty() {
149 provides.insert(ExtensionProvides::ContextServers);
150 }
151
152 if !self.agent_servers.is_empty() {
153 provides.insert(ExtensionProvides::AgentServers);
154 }
155
156 if self.snippets.is_some() {
157 provides.insert(ExtensionProvides::Snippets);
158 }
159
160 if !self.debug_adapters.is_empty() {
161 provides.insert(ExtensionProvides::DebugAdapters);
162 }
163
164 provides
165 }
166
167 pub fn allow_exec(
168 &self,
169 desired_command: &str,
170 desired_args: &[impl AsRef<str> + std::fmt::Debug],
171 ) -> Result<()> {
172 let is_allowed = self.capabilities.iter().any(|capability| match capability {
173 ExtensionCapability::ProcessExec(capability) => {
174 capability.allows(desired_command, desired_args)
175 }
176 _ => false,
177 });
178
179 if !is_allowed {
180 bail!(
181 "capability for process:exec {desired_command} {desired_args:?} was not listed in the extension manifest",
182 );
183 }
184
185 Ok(())
186 }
187
188 pub fn allow_remote_load(&self) -> bool {
189 !self.language_servers.is_empty()
190 || !self.debug_adapters.is_empty()
191 || !self.debug_locators.is_empty()
192 }
193}
194
195pub fn build_debug_adapter_schema_path(
196 adapter_name: &Arc<str>,
197 meta: &DebugAdapterManifestEntry,
198) -> PathBuf {
199 meta.schema_path.clone().unwrap_or_else(|| {
200 Path::new("debug_adapter_schemas")
201 .join(Path::new(adapter_name.as_ref()).with_extension("json"))
202 })
203}
204
205#[derive(Clone, Default, PartialEq, Eq, Debug, Deserialize, Serialize)]
206pub struct LibManifestEntry {
207 pub kind: Option<ExtensionLibraryKind>,
208 pub version: Option<Version>,
209}
210
211#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
212pub struct AgentServerManifestEntry {
213 /// Display name for the agent (shown in menus).
214 pub name: String,
215 /// Environment variables to set when launching the agent server.
216 #[serde(default)]
217 pub env: HashMap<String, String>,
218 /// Optional icon path (relative to extension root, e.g., "ai.svg").
219 /// Should be a small SVG icon for display in menus.
220 #[serde(default)]
221 pub icon: Option<String>,
222 /// Per-target configuration for archive-based installation.
223 /// The key format is "{os}-{arch}" where:
224 /// - os: "darwin" (macOS), "linux", "windows"
225 /// - arch: "aarch64" (arm64), "x86_64"
226 ///
227 /// Example:
228 /// ```toml
229 /// [agent_servers.myagent.targets.darwin-aarch64]
230 /// archive = "https://example.com/myagent-darwin-arm64.zip"
231 /// cmd = "./myagent"
232 /// args = ["--serve"]
233 /// sha256 = "abc123..." # optional
234 /// ```
235 ///
236 /// For Node.js-based agents, you can use "node" as the cmd to automatically
237 /// use Zed's managed Node.js runtime instead of relying on the user's PATH:
238 /// ```toml
239 /// [agent_servers.nodeagent.targets.darwin-aarch64]
240 /// archive = "https://example.com/nodeagent.zip"
241 /// cmd = "node"
242 /// args = ["index.js", "--port", "3000"]
243 /// ```
244 ///
245 /// Note: All commands are executed with the archive extraction directory as the
246 /// working directory, so relative paths in args (like "index.js") will resolve
247 /// relative to the extracted archive contents.
248 pub targets: HashMap<String, TargetConfig>,
249}
250
251#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
252pub struct TargetConfig {
253 /// URL to download the archive from (e.g., "https://github.com/owner/repo/releases/download/v1.0.0/myagent-darwin-arm64.zip")
254 pub archive: String,
255 /// Command to run (e.g., "./myagent" or "./myagent.exe")
256 pub cmd: String,
257 /// Command-line arguments to pass to the agent server.
258 #[serde(default)]
259 pub args: Vec<String>,
260 /// Optional SHA-256 hash of the archive for verification.
261 /// If not provided and the URL is a GitHub release, we'll attempt to fetch it from GitHub.
262 #[serde(default)]
263 pub sha256: Option<String>,
264 /// Environment variables to set when launching the agent server.
265 /// These target-specific env vars will override any env vars set at the agent level.
266 #[serde(default)]
267 pub env: HashMap<String, String>,
268}
269
270impl TargetConfig {
271 pub fn from_proto(proto: proto::ExternalExtensionAgentTarget) -> Self {
272 Self {
273 archive: proto.archive,
274 cmd: proto.cmd,
275 args: proto.args,
276 sha256: proto.sha256,
277 env: proto.env.into_iter().collect(),
278 }
279 }
280
281 pub fn to_proto(&self) -> proto::ExternalExtensionAgentTarget {
282 proto::ExternalExtensionAgentTarget {
283 archive: self.archive.clone(),
284 cmd: self.cmd.clone(),
285 args: self.args.clone(),
286 sha256: self.sha256.clone(),
287 env: self
288 .env
289 .iter()
290 .map(|(k, v)| (k.clone(), v.clone()))
291 .collect(),
292 }
293 }
294}
295
296#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
297pub enum ExtensionLibraryKind {
298 Rust,
299}
300
301#[derive(Clone, Default, PartialEq, Eq, Debug, Deserialize, Serialize)]
302pub struct GrammarManifestEntry {
303 pub repository: String,
304 #[serde(alias = "commit")]
305 pub rev: String,
306 #[serde(default)]
307 pub path: Option<String>,
308}
309
310#[derive(Clone, Default, PartialEq, Eq, Debug, Deserialize, Serialize)]
311pub struct LanguageServerManifestEntry {
312 /// Deprecated in favor of `languages`.
313 #[serde(default)]
314 language: Option<LanguageName>,
315 /// The list of languages this language server should work with.
316 #[serde(default)]
317 languages: Vec<LanguageName>,
318 #[serde(default)]
319 pub language_ids: HashMap<LanguageName, String>,
320 #[serde(default)]
321 pub code_action_kinds: Option<Vec<lsp::CodeActionKind>>,
322}
323
324impl LanguageServerManifestEntry {
325 /// Returns the list of languages for the language server.
326 ///
327 /// Prefer this over accessing the `language` or `languages` fields directly,
328 /// as we currently support both.
329 ///
330 /// We can replace this with just field access for the `languages` field once
331 /// we have removed `language`.
332 pub fn languages(&self) -> impl IntoIterator<Item = LanguageName> + '_ {
333 let language = if self.languages.is_empty() {
334 self.language.clone()
335 } else {
336 None
337 };
338 self.languages.iter().cloned().chain(language)
339 }
340}
341
342#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
343pub struct ContextServerManifestEntry {}
344
345#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
346pub struct SlashCommandManifestEntry {
347 pub description: String,
348 pub requires_argument: bool,
349}
350
351#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
352pub struct DebugAdapterManifestEntry {
353 pub schema_path: Option<PathBuf>,
354}
355
356#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
357pub struct DebugLocatorManifestEntry {}
358
359/// Manifest entry for a language model provider.
360#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
361pub struct LanguageModelProviderManifestEntry {
362 /// Display name for the provider.
363 pub name: String,
364 /// Path to an SVG icon file relative to the extension root (e.g., "icons/provider.svg").
365 #[serde(default)]
366 pub icon: Option<String>,
367}
368
369impl ExtensionManifest {
370 pub async fn load(fs: Arc<dyn Fs>, extension_dir: &Path) -> Result<Self> {
371 let extension_name = extension_dir
372 .file_name()
373 .and_then(OsStr::to_str)
374 .context("invalid extension name")?;
375
376 let extension_manifest_path = extension_dir.join("extension.toml");
377 if fs.is_file(&extension_manifest_path).await {
378 let manifest_content = fs.load(&extension_manifest_path).await.with_context(|| {
379 format!("loading {extension_name} extension.toml, {extension_manifest_path:?}")
380 })?;
381 toml::from_str(&manifest_content).map_err(|err| {
382 anyhow!("Invalid extension.toml for extension {extension_name}:\n{err}")
383 })
384 } else if let extension_manifest_path = extension_manifest_path.with_extension("json")
385 && fs.is_file(&extension_manifest_path).await
386 {
387 let manifest_content = fs.load(&extension_manifest_path).await.with_context(|| {
388 format!("loading {extension_name} extension.json, {extension_manifest_path:?}")
389 })?;
390
391 serde_json::from_str::<OldExtensionManifest>(&manifest_content)
392 .with_context(|| format!("invalid extension.json for extension {extension_name}"))
393 .map(|manifest_json| manifest_from_old_manifest(manifest_json, extension_name))
394 } else {
395 anyhow::bail!("No extension manifest found for extension {extension_name}")
396 }
397 }
398}
399
400fn manifest_from_old_manifest(
401 manifest_json: OldExtensionManifest,
402 extension_id: &str,
403) -> ExtensionManifest {
404 ExtensionManifest {
405 id: extension_id.into(),
406 name: manifest_json.name,
407 version: manifest_json.version,
408 description: manifest_json.description,
409 repository: manifest_json.repository,
410 authors: manifest_json.authors,
411 schema_version: SchemaVersion::ZERO,
412 lib: Default::default(),
413 themes: {
414 let mut themes = manifest_json.themes.into_values().collect::<Vec<_>>();
415 themes.sort();
416 themes.dedup();
417 themes
418 },
419 icon_themes: Vec::new(),
420 languages: {
421 let mut languages = manifest_json.languages.into_values().collect::<Vec<_>>();
422 languages.sort();
423 languages.dedup();
424 languages
425 },
426 grammars: manifest_json
427 .grammars
428 .into_keys()
429 .map(|grammar_name| (grammar_name, Default::default()))
430 .collect(),
431 language_servers: Default::default(),
432 context_servers: BTreeMap::default(),
433 agent_servers: BTreeMap::default(),
434 slash_commands: BTreeMap::default(),
435 snippets: None,
436 capabilities: Vec::new(),
437 debug_adapters: Default::default(),
438 debug_locators: Default::default(),
439 language_model_providers: Default::default(),
440 }
441}
442
443#[cfg(test)]
444mod tests {
445 use pretty_assertions::assert_eq;
446
447 use crate::ProcessExecCapability;
448
449 use super::*;
450
451 fn extension_manifest() -> ExtensionManifest {
452 ExtensionManifest {
453 id: "test".into(),
454 name: "Test".to_string(),
455 version: "1.0.0".into(),
456 schema_version: SchemaVersion::ZERO,
457 description: None,
458 repository: None,
459 authors: vec![],
460 lib: Default::default(),
461 themes: vec![],
462 icon_themes: vec![],
463 languages: vec![],
464 grammars: BTreeMap::default(),
465 language_servers: BTreeMap::default(),
466 context_servers: BTreeMap::default(),
467 agent_servers: BTreeMap::default(),
468 slash_commands: BTreeMap::default(),
469 snippets: None,
470 capabilities: vec![],
471 debug_adapters: Default::default(),
472 debug_locators: Default::default(),
473 language_model_providers: BTreeMap::default(),
474 }
475 }
476
477 #[test]
478 fn test_build_adapter_schema_path_with_schema_path() {
479 let adapter_name = Arc::from("my_adapter");
480 let entry = DebugAdapterManifestEntry {
481 schema_path: Some(PathBuf::from("foo/bar")),
482 };
483
484 let path = build_debug_adapter_schema_path(&adapter_name, &entry);
485 assert_eq!(path, PathBuf::from("foo/bar"));
486 }
487
488 #[test]
489 fn test_build_adapter_schema_path_without_schema_path() {
490 let adapter_name = Arc::from("my_adapter");
491 let entry = DebugAdapterManifestEntry { schema_path: None };
492
493 let path = build_debug_adapter_schema_path(&adapter_name, &entry);
494 assert_eq!(
495 path,
496 PathBuf::from("debug_adapter_schemas").join("my_adapter.json")
497 );
498 }
499
500 #[test]
501 fn test_allow_exec_exact_match() {
502 let manifest = ExtensionManifest {
503 capabilities: vec![ExtensionCapability::ProcessExec(ProcessExecCapability {
504 command: "ls".to_string(),
505 args: vec!["-la".to_string()],
506 })],
507 ..extension_manifest()
508 };
509
510 assert!(manifest.allow_exec("ls", &["-la"]).is_ok());
511 assert!(manifest.allow_exec("ls", &["-l"]).is_err());
512 assert!(manifest.allow_exec("pwd", &[] as &[&str]).is_err());
513 }
514
515 #[test]
516 fn test_allow_exec_wildcard_arg() {
517 let manifest = ExtensionManifest {
518 capabilities: vec![ExtensionCapability::ProcessExec(ProcessExecCapability {
519 command: "git".to_string(),
520 args: vec!["*".to_string()],
521 })],
522 ..extension_manifest()
523 };
524
525 assert!(manifest.allow_exec("git", &["status"]).is_ok());
526 assert!(manifest.allow_exec("git", &["commit"]).is_ok());
527 assert!(manifest.allow_exec("git", &["status", "-s"]).is_err()); // too many args
528 assert!(manifest.allow_exec("npm", &["install"]).is_err()); // wrong command
529 }
530
531 #[test]
532 fn test_allow_exec_double_wildcard() {
533 let manifest = ExtensionManifest {
534 capabilities: vec![ExtensionCapability::ProcessExec(ProcessExecCapability {
535 command: "cargo".to_string(),
536 args: vec!["test".to_string(), "**".to_string()],
537 })],
538 ..extension_manifest()
539 };
540
541 assert!(manifest.allow_exec("cargo", &["test"]).is_ok());
542 assert!(manifest.allow_exec("cargo", &["test", "--all"]).is_ok());
543 assert!(
544 manifest
545 .allow_exec("cargo", &["test", "--all", "--no-fail-fast"])
546 .is_ok()
547 );
548 assert!(manifest.allow_exec("cargo", &["build"]).is_err()); // wrong first arg
549 }
550
551 #[test]
552 fn test_allow_exec_mixed_wildcards() {
553 let manifest = ExtensionManifest {
554 capabilities: vec![ExtensionCapability::ProcessExec(ProcessExecCapability {
555 command: "docker".to_string(),
556 args: vec!["run".to_string(), "*".to_string(), "**".to_string()],
557 })],
558 ..extension_manifest()
559 };
560
561 assert!(manifest.allow_exec("docker", &["run", "nginx"]).is_ok());
562 assert!(manifest.allow_exec("docker", &["run"]).is_err());
563 assert!(
564 manifest
565 .allow_exec("docker", &["run", "ubuntu", "bash"])
566 .is_ok()
567 );
568 assert!(
569 manifest
570 .allow_exec("docker", &["run", "alpine", "sh", "-c", "echo hello"])
571 .is_ok()
572 );
573 assert!(manifest.allow_exec("docker", &["ps"]).is_err()); // wrong first arg
574 }
575 #[test]
576 fn parse_manifest_with_agent_server_archive_launcher() {
577 let toml_src = r#"
578id = "example.agent-server-ext"
579name = "Agent Server Example"
580version = "1.0.0"
581schema_version = 0
582
583[agent_servers.foo]
584name = "Foo Agent"
585
586[agent_servers.foo.targets.linux-x86_64]
587archive = "https://example.com/agent-linux-x64.tar.gz"
588cmd = "./agent"
589args = ["--serve"]
590"#;
591
592 let manifest: ExtensionManifest = toml::from_str(toml_src).expect("manifest should parse");
593 assert_eq!(manifest.id.as_ref(), "example.agent-server-ext");
594 assert!(manifest.agent_servers.contains_key("foo"));
595 let entry = manifest.agent_servers.get("foo").unwrap();
596 assert!(entry.targets.contains_key("linux-x86_64"));
597 let target = entry.targets.get("linux-x86_64").unwrap();
598 assert_eq!(target.archive, "https://example.com/agent-linux-x64.tar.gz");
599 assert_eq!(target.cmd, "./agent");
600 assert_eq!(target.args, vec!["--serve"]);
601 }
602}