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