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