WIP and merge

crates/extension_api/Cargo.toml

@@ -6,8 +6,7 @@ repository = "https://github.com/zed-industries/zed"
 documentation = "https://docs.rs/zed_extension_api"
 keywords = ["zed", "extension"]
 edition.workspace = true
-# Change back to `true` when we're ready to publish v0.6.0.
-publish = false
+publish = true
 license = "Apache-2.0"
 
 [lints]

crates/extension_api/README.md

@@ -65,6 +65,7 @@ Here is the compatibility of the `zed_extension_api` with versions of Zed:
 
 | Zed version | `zed_extension_api` version |
 | ----------- | --------------------------- |
+| `0.192.x`   | `0.0.1` - `0.6.0`           |
 | `0.186.x`   | `0.0.1` - `0.5.0`           |
 | `0.184.x`   | `0.0.1` - `0.4.0`           |
 | `0.178.x`   | `0.0.1` - `0.3.0`           |

crates/extension_api/src/extension_api.rs

@@ -20,9 +20,10 @@ pub use wit::{
     make_file_executable,
     zed::extension::context_server::ContextServerConfiguration,
     zed::extension::dap::{
-        DebugAdapterBinary, DebugTaskDefinition, StartDebuggingRequestArguments,
-        StartDebuggingRequestArgumentsRequest, TcpArguments, TcpArgumentsTemplate,
-        resolve_tcp_template,
+        AttachRequest, BuildTaskDefinition, BuildTaskDefinitionTemplatePayload, BuildTaskTemplate,
+        DebugAdapterBinary, DebugConfig, DebugRequest, DebugScenario, DebugTaskDefinition,
+        LaunchRequest, StartDebuggingRequestArguments, StartDebuggingRequestArgumentsRequest,
+        TaskTemplate, TcpArguments, TcpArgumentsTemplate, resolve_tcp_template,
     },
     zed::extension::github::{
         GithubRelease, GithubReleaseAsset, GithubReleaseOptions, github_release_by_tag_name,
@@ -198,14 +199,65 @@ pub trait Extension: Send + Sync {
         &mut self,
         _adapter_name: String,
         _config: DebugTaskDefinition,
-        _user_provided_path: Option<String>,
+        _user_provided_debug_adapter_path: Option<String>,
         _worktree: &Worktree,
     ) -> Result<DebugAdapterBinary, String> {
         Err("`get_dap_binary` not implemented".to_string())
     }
 
-    fn dap_schema(&mut self) -> Result<serde_json::Value, String> {
-        Err("`dap_schema` not implemented".to_string())
+    /// Determines whether the specified adapter configuration should *launch* a new debuggee process
+    /// or *attach* to an existing one. This function should not perform any further validation (outside of determining the kind of a request).
+    /// This function should return an error when the kind cannot be determined (rather than fall back to a known default).
+    fn dap_request_kind(
+        &mut self,
+        _adapter_name: String,
+        _config: serde_json::Value,
+    ) -> Result<StartDebuggingRequestArgumentsRequest, String> {
+        Err("`dap_request_kind` not implemented".to_string())
+    }
+    /// Converts a high-level definition of a debug scenario (originating in a new session UI) to a "low-level" configuration suitable for a particular adapter.
+    ///
+    /// In layman's terms: given a program, list of arguments, current working directory and environment variables,
+    /// create a configuration that can be used to start a debug session.
+    fn dap_config_to_scenario(&mut self, _config: DebugConfig) -> Result<DebugScenario, String> {
+        Err("`dap_config_to_scenario` not implemented".to_string())
+    }
+
+    /// Locators are entities that convert a Zed task into a debug scenario.
+    ///
+    /// They can be provided even by extensions that don't provide a debug adapter.
+    /// For all tasks applicable to a given buffer, Zed will query all locators to find one that can turn the task into a debug scenario.
+    /// A converted debug scenario can include a build task (it shouldn't contain any configuration in such case); a build task result will later
+    /// be resolved with [`Extension::run_dap_locator`].
+    ///
+    /// To work through a real-world example, take a `cargo run` task and a hypothetical `cargo` locator:
+    /// 1. We may need to modify the task; in this case, it is problematic that `cargo run` spawns a binary. We should turn `cargo run` into a debug scenario with
+    /// `cargo build` task. This is the decision we make at `dap_locator_create_scenario` scope.
+    /// 2. Then, after the build task finishes, we will run `run_dap_locator` of the locator that produced the build task to find the program to be debugged. This function
+    /// should give us a debugger-agnostic configuration for launching a debug target (that we end up resolving with [`Extension::dap_config_to_scenario`]). It's almost as if the user
+    /// found the artifact path by themselves.
+    ///
+    /// Note that you're not obliged to use build tasks with locators. Specifically, it is sufficient to provide a debug configuration directly in the return value of
+    /// `dap_locator_create_scenario` if you're able to do that. Make sure to not fill out `build` field in that case, as that will prevent Zed from running second phase of resolution in such case.
+    /// This might be of particular relevance to interpreted languages.
+    fn dap_locator_create_scenario(
+        &mut self,
+        _locator_name: String,
+        _build_task: TaskTemplate,
+        _resolved_label: String,
+        _debug_adapter_name: String,
+    ) -> Option<DebugScenario> {
+        None
+    }
+
+    /// Runs the second phase of locator resolution.
+    /// See [`Extension::dap_locator_create_scenario`] for a hefty comment on locators.
+    fn run_dap_locator(
+        &mut self,
+        _locator_name: String,
+        _build_task: TaskTemplate,
+    ) -> Result<DebugRequest, String> {
+        Err("`run_dap_locator` not implemented".to_string())
     }
 }
 
@@ -401,8 +453,36 @@ impl wit::Guest for Component {
         extension().get_dap_binary(adapter_name, config, user_installed_path, worktree)
     }
 
-    fn dap_schema() -> Result<String, String> {
-        extension().dap_schema().map(|schema| schema.to_string())
+    fn dap_request_kind(
+        adapter_name: String,
+        config: String,
+    ) -> Result<StartDebuggingRequestArgumentsRequest, String> {
+        extension().dap_request_kind(
+            adapter_name,
+            serde_json::from_str(&config).map_err(|e| format!("Failed to parse config: {e}"))?,
+        )
+    }
+    fn dap_config_to_scenario(config: DebugConfig) -> Result<DebugScenario, String> {
+        extension().dap_config_to_scenario(config)
+    }
+    fn dap_locator_create_scenario(
+        locator_name: String,
+        build_task: TaskTemplate,
+        resolved_label: String,
+        debug_adapter_name: String,
+    ) -> Option<DebugScenario> {
+        extension().dap_locator_create_scenario(
+            locator_name,
+            build_task,
+            resolved_label,
+            debug_adapter_name,
+        )
+    }
+    fn run_dap_locator(
+        locator_name: String,
+        build_task: TaskTemplate,
+    ) -> Result<DebugRequest, String> {
+        extension().run_dap_locator(locator_name, build_task)
     }
 }
 

crates/extension_api/wit/since_v0.6.0/dap.wit

@@ -32,10 +32,55 @@ interface dap {
         timeout: option<u64>,
     }
 
-    record debug-task-definition {
+    /// Debug Config is the "highest-level" configuration for a debug session.
+    /// It comes from a new session modal UI; thus, it is essentially debug-adapter-agnostic.
+    /// It is expected of the extension to translate this generic configuration into something that can be debugged by the adapter (debug scenario).
+    record debug-config {
+        /// Name of the debug task
         label: string,
+        /// The debug adapter to use
         adapter: string,
+        request: debug-request,
+        stop-on-entry: option<bool>,
+    }
+
+    record task-template {
+        /// Human readable name of the task to display in the UI.
+        label: string,
+        /// Executable command to spawn.
+        command: string,
+        args: list<string>,
+        env: env-vars,
+        cwd: option<string>,
+    }
+
+    /// A task template with substituted task variables.
+    type resolved-task = task-template;
+
+    /// A task template for building a debug target.
+    type build-task-template = task-template;
+
+    variant build-task-definition {
+        by-name(string),
+        template(build-task-definition-template-payload )
+    }
+    record build-task-definition-template-payload {
+        locator-name: option<string>,
+        template: build-task-template
+    }
+
+    /// Debug Scenario is the user-facing configuration type (used in debug.json). It is still concerned with what to debug and not necessarily how to do it (except for any
+    /// debug-adapter-specific configuration options).
+    record debug-scenario {
+        /// Unsubstituted label for the task.DebugAdapterBinary
+        label: string,
+        /// Name of the Debug Adapter this configuration is intended for.
+        adapter: string,
+        /// An optional build step to be ran prior to starting a debug session. Build steps are used by Zed's locators to locate the executable to debug.
+        build: option<build-task-definition>,
+        /// JSON-encoded configuration for a given debug adapter.
         config: string,
+        /// TCP connection parameters (if they were specified by user)
         tcp-connection: option<tcp-arguments-template>,
     }
 
@@ -44,16 +89,34 @@ interface dap {
         attach,
     }
 
+    record debug-task-definition {
+        /// Unsubstituted label for the task.DebugAdapterBinary
+        label: string,
+        /// Name of the Debug Adapter this configuration is intended for.
+        adapter: string,
+        /// JSON-encoded configuration for a given debug adapter.
+        config: string,
+        /// TCP connection parameters (if they were specified by user)
+        tcp-connection: option<tcp-arguments-template>,
+    }
+
     record start-debugging-request-arguments {
+        /// JSON-encoded configuration for a given debug adapter. It is specific to each debug adapter.
+        /// `configuration` will have it's Zed variable references substituted prior to being passed to the debug adapter.
         configuration: string,
         request: start-debugging-request-arguments-request,
     }
 
+    /// The lowest-level representation of a debug session, which specifies:
+    /// - How to start a debug adapter process
+    /// - How to start a debug session with it (using DAP protocol)
+    /// for a given debug scenario.
     record debug-adapter-binary {
-        command: string,
+        command: option<string>,
         arguments: list<string>,
         envs: env-vars,
         cwd: option<string>,
+        /// Zed will use TCP transport if `connection` is specified.
         connection: option<tcp-arguments>,
         request-args: start-debugging-request-arguments
     }

crates/extension_api/wit/since_v0.6.0/extension.wit

@@ -11,7 +11,7 @@ world extension {
 
     use common.{env-vars, range};
     use context-server.{context-server-configuration};
-    use dap.{debug-adapter-binary, debug-task-definition, debug-request};
+    use dap.{attach-request, build-task-template, debug-config, debug-adapter-binary, debug-task-definition, debug-request, debug-scenario, launch-request, resolved-task, start-debugging-request-arguments-request};
     use lsp.{completion, symbol};
     use process.{command};
     use slash-command.{slash-command, slash-command-argument-completion, slash-command-output};
@@ -159,6 +159,9 @@ world extension {
 
     /// Returns a configured debug adapter binary for a given debug task.
     export get-dap-binary: func(adapter-name: string, config: debug-task-definition, user-installed-path: option<string>, worktree: borrow<worktree>) -> result<debug-adapter-binary, string>;
-    /// Get a debug adapter's configuration schema
-    export dap-schema: func() -> result<string, string>;
+    /// Returns the kind of a debug scenario (launch or attach).
+    export dap-request-kind: func(adapter-name: string, config: string) -> result<start-debugging-request-arguments-request, string>;
+    export dap-config-to-scenario: func(config: debug-config) -> result<debug-scenario, string>;
+    export dap-locator-create-scenario: func(locator-name: string, build-config-template: build-task-template, resolved-label: string, debug-adapter-name: string) -> option<debug-scenario>;
+    export run-dap-locator: func(locator-name: string, config: resolved-task) -> result<debug-request, string>;
 }