1//! Baseline interface of Tasks in Zed: all tasks in Zed are intended to use those for implementing their own logic.
2
3mod adapter_schema;
4mod debug_format;
5mod serde_helpers;
6pub mod static_source;
7mod task_template;
8mod vscode_debug_format;
9mod vscode_format;
10
11use anyhow::Context as _;
12use collections::{HashMap, HashSet, hash_map};
13use gpui::SharedString;
14use serde::{Deserialize, Serialize};
15use std::borrow::Cow;
16use std::path::PathBuf;
17use std::str::FromStr;
18use std::sync::Arc;
19
20pub use adapter_schema::{AdapterSchema, AdapterSchemas};
21pub use debug_format::{
22 AttachRequest, BuildTaskDefinition, DebugRequest, DebugScenario, DebugTaskFile, LaunchRequest,
23 Request, TcpArgumentsTemplate, ZedDebugConfig,
24};
25pub use task_template::{
26 DebugArgsRequest, HideStrategy, RevealStrategy, SaveStrategy, TaskHook, TaskTemplate,
27 TaskTemplates, substitute_variables_in_map, substitute_variables_in_str,
28};
29pub use util::shell::{Shell, ShellKind};
30pub use util::shell_builder::ShellBuilder;
31pub use vscode_debug_format::VsCodeDebugTaskFile;
32pub use vscode_format::VsCodeTaskFile;
33pub use zed_actions::RevealTarget;
34
35/// Task identifier, unique within the application.
36/// Based on it, task reruns and terminal tabs are managed.
37#[derive(Default, Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Deserialize)]
38pub struct TaskId(pub String);
39
40/// Contains all information needed by Zed to spawn a new terminal tab for the given task.
41#[derive(Default, Debug, Clone, PartialEq, Eq)]
42pub struct SpawnInTerminal {
43 /// Id of the task to use when determining task tab affinity.
44 pub id: TaskId,
45 /// Full unshortened form of `label` field.
46 pub full_label: String,
47 /// Human readable name of the terminal tab.
48 pub label: String,
49 /// Executable command to spawn.
50 pub command: Option<String>,
51 /// Arguments to the command, potentially unsubstituted,
52 /// to let the shell that spawns the command to do the substitution, if needed.
53 pub args: Vec<String>,
54 /// A human-readable label, containing command and all of its arguments, joined and substituted.
55 pub command_label: String,
56 /// Current working directory to spawn the command into.
57 pub cwd: Option<PathBuf>,
58 /// Env overrides for the command, will be appended to the terminal's environment from the settings.
59 pub env: HashMap<String, String>,
60 /// Whether to use a new terminal tab or reuse the existing one to spawn the process.
61 pub use_new_terminal: bool,
62 /// Whether to allow multiple instances of the same task to be run, or rather wait for the existing ones to finish.
63 pub allow_concurrent_runs: bool,
64 /// What to do with the terminal pane and tab, after the command was started.
65 pub reveal: RevealStrategy,
66 /// Where to show tasks' terminal output.
67 pub reveal_target: RevealTarget,
68 /// What to do with the terminal pane and tab, after the command had finished.
69 pub hide: HideStrategy,
70 /// Which shell to use when spawning the task.
71 pub shell: Shell,
72 /// Whether to show the task summary line in the task output (sucess/failure).
73 pub show_summary: bool,
74 /// Whether to show the command line in the task output.
75 pub show_command: bool,
76 /// Whether to show the rerun button in the terminal tab.
77 pub show_rerun: bool,
78 /// Which edited buffers to save before running the task.
79 pub save: SaveStrategy,
80}
81
82impl SpawnInTerminal {
83 pub fn to_proto(&self) -> proto::SpawnInTerminal {
84 proto::SpawnInTerminal {
85 label: self.label.clone(),
86 command: self.command.clone(),
87 args: self.args.clone(),
88 env: self
89 .env
90 .iter()
91 .map(|(k, v)| (k.clone(), v.clone()))
92 .collect(),
93 cwd: self
94 .cwd
95 .clone()
96 .map(|cwd| cwd.to_string_lossy().into_owned()),
97 }
98 }
99
100 pub fn from_proto(proto: proto::SpawnInTerminal) -> Self {
101 Self {
102 label: proto.label.clone(),
103 command: proto.command.clone(),
104 args: proto.args.clone(),
105 env: proto.env.into_iter().collect(),
106 cwd: proto.cwd.map(PathBuf::from),
107 ..Default::default()
108 }
109 }
110}
111
112/// A final form of the [`TaskTemplate`], that got resolved with a particular [`TaskContext`] and now is ready to spawn the actual task.
113#[derive(Clone, Debug, PartialEq, Eq)]
114pub struct ResolvedTask {
115 /// A way to distinguish tasks produced by the same template, but different contexts.
116 /// NOTE: Resolved tasks may have the same labels, commands and do the same things,
117 /// but still may have different ids if the context was different during the resolution.
118 /// Since the template has `env` field, for a generic task that may be a bash command,
119 /// so it's impossible to determine the id equality without more context in a generic case.
120 pub id: TaskId,
121 /// A template the task got resolved from.
122 original_task: TaskTemplate,
123 /// Full, unshortened label of the task after all resolutions are made.
124 pub resolved_label: String,
125 /// Variables that were substituted during the task template resolution.
126 substituted_variables: HashSet<VariableName>,
127 /// Further actions that need to take place after the resolved task is spawned,
128 /// with all task variables resolved.
129 pub resolved: SpawnInTerminal,
130}
131
132impl ResolvedTask {
133 /// A task template before the resolution.
134 pub fn original_task(&self) -> &TaskTemplate {
135 &self.original_task
136 }
137
138 /// Variables that were substituted during the task template resolution.
139 pub fn substituted_variables(&self) -> &HashSet<VariableName> {
140 &self.substituted_variables
141 }
142
143 /// A human-readable label to display in the UI.
144 pub fn display_label(&self) -> &str {
145 self.resolved.label.as_str()
146 }
147}
148
149/// Variables, available for use in [`TaskContext`] when a Zed's [`TaskTemplate`] gets resolved into a [`ResolvedTask`].
150/// Name of the variable must be a valid shell variable identifier, which generally means that it is
151/// a word consisting only of alphanumeric characters and underscores,
152/// and beginning with an alphabetic character or an underscore.
153#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
154pub enum VariableName {
155 /// An absolute path of the currently opened file.
156 File,
157 /// A path of the currently opened file (relative to worktree root).
158 RelativeFile,
159 /// A path of the currently opened file's directory (relative to worktree root).
160 RelativeDir,
161 /// The currently opened filename.
162 Filename,
163 /// The path to a parent directory of a currently opened file.
164 Dirname,
165 /// Stem (filename without extension) of the currently opened file.
166 Stem,
167 /// An absolute path of the currently opened worktree, that contains the file.
168 WorktreeRoot,
169 /// A symbol text, that contains latest cursor/selection position.
170 Symbol,
171 /// A row with the latest cursor/selection position.
172 Row,
173 /// A column with the latest cursor/selection position.
174 Column,
175 /// Text from the latest selection.
176 SelectedText,
177 /// The language of the currently opened buffer (e.g., "Rust", "Python").
178 Language,
179 /// The symbol selected by the symbol tagging system, specifically the @run capture in a runnables.scm
180 RunnableSymbol,
181 /// Open a Picker to select a process ID to use in place
182 /// Can only be used to debug configurations
183 PickProcessId,
184 /// An absolute path of the main (original) git worktree for the current repository.
185 /// For normal checkouts, this equals the worktree root. For linked worktrees,
186 /// this is the original repo's working directory.
187 MainGitWorktree,
188 /// Custom variable, provided by the plugin or other external source.
189 /// Will be printed with `CUSTOM_` prefix to avoid potential conflicts with other variables.
190 Custom(Cow<'static, str>),
191}
192
193impl VariableName {
194 /// Generates a `$VARIABLE`-like string value to be used in templates.
195 pub fn template_value(&self) -> String {
196 format!("${self}")
197 }
198 /// Generates a `"$VARIABLE"`-like string, to be used instead of `Self::template_value` when expanded value could contain spaces or special characters.
199 pub fn template_value_with_whitespace(&self) -> String {
200 format!("\"${self}\"")
201 }
202}
203
204impl FromStr for VariableName {
205 type Err = ();
206
207 fn from_str(s: &str) -> Result<Self, Self::Err> {
208 let without_prefix = s.strip_prefix(ZED_VARIABLE_NAME_PREFIX).ok_or(())?;
209 let value = match without_prefix {
210 "FILE" => Self::File,
211 "FILENAME" => Self::Filename,
212 "RELATIVE_FILE" => Self::RelativeFile,
213 "RELATIVE_DIR" => Self::RelativeDir,
214 "DIRNAME" => Self::Dirname,
215 "STEM" => Self::Stem,
216 "WORKTREE_ROOT" => Self::WorktreeRoot,
217 "SYMBOL" => Self::Symbol,
218 "RUNNABLE_SYMBOL" => Self::RunnableSymbol,
219 "SELECTED_TEXT" => Self::SelectedText,
220 "LANGUAGE" => Self::Language,
221 "ROW" => Self::Row,
222 "COLUMN" => Self::Column,
223 "MAIN_GIT_WORKTREE" => Self::MainGitWorktree,
224 _ => {
225 if let Some(custom_name) =
226 without_prefix.strip_prefix(ZED_CUSTOM_VARIABLE_NAME_PREFIX)
227 {
228 Self::Custom(Cow::Owned(custom_name.to_owned()))
229 } else {
230 return Err(());
231 }
232 }
233 };
234 Ok(value)
235 }
236}
237
238/// A prefix that all [`VariableName`] variants are prefixed with when used in environment variables and similar template contexts.
239pub const ZED_VARIABLE_NAME_PREFIX: &str = "ZED_";
240const ZED_CUSTOM_VARIABLE_NAME_PREFIX: &str = "CUSTOM_";
241
242impl std::fmt::Display for VariableName {
243 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
244 match self {
245 Self::File => write!(f, "{ZED_VARIABLE_NAME_PREFIX}FILE"),
246 Self::Filename => write!(f, "{ZED_VARIABLE_NAME_PREFIX}FILENAME"),
247 Self::RelativeFile => write!(f, "{ZED_VARIABLE_NAME_PREFIX}RELATIVE_FILE"),
248 Self::RelativeDir => write!(f, "{ZED_VARIABLE_NAME_PREFIX}RELATIVE_DIR"),
249 Self::Dirname => write!(f, "{ZED_VARIABLE_NAME_PREFIX}DIRNAME"),
250 Self::Stem => write!(f, "{ZED_VARIABLE_NAME_PREFIX}STEM"),
251 Self::WorktreeRoot => write!(f, "{ZED_VARIABLE_NAME_PREFIX}WORKTREE_ROOT"),
252 Self::Symbol => write!(f, "{ZED_VARIABLE_NAME_PREFIX}SYMBOL"),
253 Self::Row => write!(f, "{ZED_VARIABLE_NAME_PREFIX}ROW"),
254 Self::Column => write!(f, "{ZED_VARIABLE_NAME_PREFIX}COLUMN"),
255 Self::SelectedText => write!(f, "{ZED_VARIABLE_NAME_PREFIX}SELECTED_TEXT"),
256 Self::Language => write!(f, "{ZED_VARIABLE_NAME_PREFIX}LANGUAGE"),
257 Self::RunnableSymbol => write!(f, "{ZED_VARIABLE_NAME_PREFIX}RUNNABLE_SYMBOL"),
258 Self::PickProcessId => write!(f, "{ZED_VARIABLE_NAME_PREFIX}PICK_PID"),
259 Self::MainGitWorktree => write!(f, "{ZED_VARIABLE_NAME_PREFIX}MAIN_GIT_WORKTREE"),
260 Self::Custom(s) => write!(
261 f,
262 "{ZED_VARIABLE_NAME_PREFIX}{ZED_CUSTOM_VARIABLE_NAME_PREFIX}{s}"
263 ),
264 }
265 }
266}
267
268/// Container for predefined environment variables that describe state of Zed at the time the task was spawned.
269#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
270pub struct TaskVariables(HashMap<VariableName, String>);
271
272impl TaskVariables {
273 /// Inserts another variable into the container, overwriting the existing one if it already exists — in this case, the old value is returned.
274 pub fn insert(&mut self, variable: VariableName, value: String) -> Option<String> {
275 self.0.insert(variable, value)
276 }
277
278 /// Extends the container with another one, overwriting the existing variables on collision.
279 pub fn extend(&mut self, other: Self) {
280 self.0.extend(other.0);
281 }
282 /// Get the value associated with given variable name, if there is one.
283 pub fn get(&self, key: &VariableName) -> Option<&str> {
284 self.0.get(key).map(|s| s.as_str())
285 }
286 /// Clear out variables obtained from tree-sitter queries, which are prefixed with '_' character
287 pub fn sweep(&mut self) {
288 self.0.retain(|name, _| {
289 if let VariableName::Custom(name) = name {
290 !name.starts_with('_')
291 } else {
292 true
293 }
294 })
295 }
296
297 pub fn iter(&self) -> impl Iterator<Item = (&VariableName, &String)> {
298 self.0.iter()
299 }
300}
301
302impl FromIterator<(VariableName, String)> for TaskVariables {
303 fn from_iter<T: IntoIterator<Item = (VariableName, String)>>(iter: T) -> Self {
304 Self(HashMap::from_iter(iter))
305 }
306}
307
308impl IntoIterator for TaskVariables {
309 type Item = (VariableName, String);
310
311 type IntoIter = hash_map::IntoIter<VariableName, String>;
312
313 fn into_iter(self) -> Self::IntoIter {
314 self.0.into_iter()
315 }
316}
317
318/// Keeps track of the file associated with a task and context of tasks execution (i.e. current file or current function).
319/// Keeps all Zed-related state inside, used to produce a resolved task out of its template.
320#[derive(Clone, Debug, Default, PartialEq, Eq)]
321pub struct TaskContext {
322 /// A path to a directory in which the task should be executed.
323 pub cwd: Option<PathBuf>,
324 /// Additional environment variables associated with a given task.
325 pub task_variables: TaskVariables,
326 /// Environment variables obtained when loading the project into Zed.
327 /// This is the environment one would get when `cd`ing in a terminal
328 /// into the project's root directory.
329 pub project_env: HashMap<String, String>,
330}
331
332/// A shared reference to a [`TaskContext`], used to avoid cloning the context multiple times.
333#[derive(Clone, Debug, Default)]
334pub struct SharedTaskContext(Arc<TaskContext>);
335
336impl std::ops::Deref for SharedTaskContext {
337 type Target = TaskContext;
338
339 fn deref(&self) -> &Self::Target {
340 &self.0
341 }
342}
343
344impl From<TaskContext> for SharedTaskContext {
345 fn from(context: TaskContext) -> Self {
346 Self(Arc::new(context))
347 }
348}
349
350/// This is a new type representing a 'tag' on a 'runnable symbol', typically a test of main() function, found via treesitter.
351#[derive(Clone, Debug)]
352pub struct RunnableTag(pub SharedString);
353
354pub fn shell_from_proto(proto: proto::Shell) -> anyhow::Result<Shell> {
355 let shell_type = proto.shell_type.context("invalid shell type")?;
356 let shell = match shell_type {
357 proto::shell::ShellType::System(_) => Shell::System,
358 proto::shell::ShellType::Program(program) => Shell::Program(program),
359 proto::shell::ShellType::WithArguments(program) => Shell::WithArguments {
360 program: program.program,
361 args: program.args,
362 title_override: None,
363 },
364 };
365 Ok(shell)
366}
367
368pub fn shell_to_proto(shell: Shell) -> proto::Shell {
369 let shell_type = match shell {
370 Shell::System => proto::shell::ShellType::System(proto::System {}),
371 Shell::Program(program) => proto::shell::ShellType::Program(program),
372 Shell::WithArguments {
373 program,
374 args,
375 title_override: _,
376 } => proto::shell::ShellType::WithArguments(proto::shell::WithArguments { program, args }),
377 };
378 proto::Shell {
379 shell_type: Some(shell_type),
380 }
381}
382
383type VsCodeEnvVariable = String;
384type VsCodeCommand = String;
385type ZedEnvVariable = String;
386
387struct EnvVariableReplacer {
388 variables: HashMap<VsCodeEnvVariable, ZedEnvVariable>,
389 commands: HashMap<VsCodeCommand, ZedEnvVariable>,
390}
391
392impl EnvVariableReplacer {
393 fn new(variables: HashMap<VsCodeEnvVariable, ZedEnvVariable>) -> Self {
394 Self {
395 variables,
396 commands: HashMap::default(),
397 }
398 }
399
400 fn with_commands(
401 mut self,
402 commands: impl IntoIterator<Item = (VsCodeCommand, ZedEnvVariable)>,
403 ) -> Self {
404 self.commands = commands.into_iter().collect();
405 self
406 }
407
408 fn replace_value(&self, input: serde_json::Value) -> serde_json::Value {
409 match input {
410 serde_json::Value::String(s) => serde_json::Value::String(self.replace(&s)),
411 serde_json::Value::Array(arr) => {
412 serde_json::Value::Array(arr.into_iter().map(|v| self.replace_value(v)).collect())
413 }
414 serde_json::Value::Object(obj) => serde_json::Value::Object(
415 obj.into_iter()
416 .map(|(k, v)| (self.replace(&k), self.replace_value(v)))
417 .collect(),
418 ),
419 _ => input,
420 }
421 }
422 // Replaces occurrences of VsCode-specific environment variables with Zed equivalents.
423 fn replace(&self, input: &str) -> String {
424 shellexpand::env_with_context_no_errors(&input, |var: &str| {
425 // Colons denote a default value in case the variable is not set. We want to preserve that default, as otherwise shellexpand will substitute it for us.
426 let colon_position = var.find(':').unwrap_or(var.len());
427 let (left, right) = var.split_at(colon_position);
428 if left == "env" && !right.is_empty() {
429 let variable_name = &right[1..];
430 return Some(format!("${{{variable_name}}}"));
431 } else if left == "command" && !right.is_empty() {
432 let command_name = &right[1..];
433 if let Some(replacement_command) = self.commands.get(command_name) {
434 return Some(format!("${{{replacement_command}}}"));
435 }
436 }
437
438 let (variable_name, default) = (left, right);
439 let append_previous_default = |ret: &mut String| {
440 if !default.is_empty() {
441 ret.push_str(default);
442 }
443 };
444 if let Some(substitution) = self.variables.get(variable_name) {
445 // Got a VSCode->Zed hit, perform a substitution
446 let mut name = format!("${{{substitution}");
447 append_previous_default(&mut name);
448 name.push('}');
449 return Some(name);
450 }
451 // This is an unknown variable.
452 // We should not error out, as they may come from user environment (e.g. $PATH). That means that the variable substitution might not be perfect.
453 // If there's a default, we need to return the string verbatim as otherwise shellexpand will apply that default for us.
454 if !default.is_empty() {
455 return Some(format!("${{{var}}}"));
456 }
457 // Else we can just return None and that variable will be left as is.
458 None
459 })
460 .into_owned()
461 }
462}