coder · fioan89 · Apr 11, 2025 · Apr 10, 2025 · Apr 10, 2025 · Apr 10, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,14 +5,12 @@
 ### Fixed
 
 - SSH connection to a Workspace is no longer established only once 
+- authorization wizard automatically goes to a previous screen when an error is encountered during connection to Coder deployment
 
 ### Changed
 
 - action buttons on the token input step were swapped to achieve better keyboard navigation 
-
-### Fixed
-
-- authorization wizard automatically goes to a previous screen when an error is encountered during connection to Coder deployment 
+- URI `project_path` query parameter was renamed to `folder`
 
 ## 0.1.3 - 2025-04-09
 

diff --git a/README.md b/README.md
@@ -1,12 +1,110 @@
-# Toolbox Gateway plugin sample
+# Coder Toolbox plugin
 
-To load plugin into the provided Toolbox App, run `./gradlew build copyPlugin`
+[!["Join us onDiscord"](https://img.shields.io/badge/join-us%20on%20Discord-gray.svg?longCache=true&logo=discord&colorB=purple)](https://discord.gg/coder)
+[![Twitter Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq)
+[![Coder Toolbox Plugin Build](https://github.com/coder/coder-jetbrains-toolbox/actions/workflows/build.yml/badge.svg)](https://github.com/coder/coder-jetbrains-toolbox/actions/workflows/build.yml)
 
-or put files in the following directory:
+Connects your JetBrains IDE to Coder workspaces
 
-* Windows: `%LocalAppData%/JetBrains/Toolbox/cache/plugins/plugin-id`
-* macOS: `~/Library/Caches/JetBrains/Toolbox/plugins/plugin-id`
-* Linux: `~/.local/share/JetBrains/Toolbox/plugins/plugin-id`
+## Getting Started
 
-Put all required .jar files (do not include any dependencies already included with the Toolbox App to avoid possible resolution conflicts),
-`extensions.json` and `icon.svg` in this directory.
+To install this plugin using JetBrains Toolbox, follow the steps below.
+
+1. Install [JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/). Make sure it's the `2.6.0.40284` release or
+   above.
+2. Launch the Toolbox app and sign in with your JetBrains account (if needed).
+
+### Install Coder plugin via URI
+
+You can quickly install the plugin using this JetBrains hyperlink.
+
+👉 [Install plugin](jetbrains://gateway/com.coder.toolbox)
+
+This will open JetBrains Toolbox and prompt you to install the Coder Toolbox plugin automatically.
+
+Alternatively, you can paste `jetbrains://gateway/com.coder.toolbox` into a browser.
+
+### Manual install
+
+There are two ways Coder Toolbox plugin can be installed. The first option is to manually download the plugin
+artifact from [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/26968-coder/versions)
+or from [Coder's Github Release page](https://github.com/coder/coder-jetbrains-toolbox/releases).
+
+The next step is to copy the zip content to one of the following locations, depending on your OS:
+
+* Windows: `%LocalAppData%/JetBrains/Toolbox/cache/plugins/com.coder.toolbox`
+* macOS: `~/Library/Caches/JetBrains/Toolbox/plugins/com.coder.toolbox`
+* Linux: `~/.local/share/JetBrains/Toolbox/plugins/com.coder.toolbox`
+
+Alternatively, you can install it using the _Gradle_ tasks included in the project:
+
+```shell
+
+./gradlew cleanAll build copyPlugin
+```
+
+Make sure Toolbox is closed before running the command.
+
+## Connect to a Coder Workspace via JetBrains Toolbox URI
+
+You can use specially crafted JetBrains Gateway URIs to automatically:
+
+1. Open Toolbox
+
+2. Install the Coder Toolbox plugin (if not already installed)
+
+3. Connect to a specific Coder deployment using a URL and a token.
+
+4. Select a running workspace
+
+5. Install a specified JetBrains IDE on that Workspace
+
+6. Open a project folder directly in the remote IDE
+
+### Example URIs
+
+```text
+jetbrains://gateway/com.coder.toolbox?url=https%3A%2F%2Fdev.coder.com&token=zeoX4SbSpP-j2qGpajkdwxR9jBdcekXS2&workspace=bobiverse-bob&agent=dev&ide_product_code=GO&ide_build_number=241.23774.119&folder=%2Fhome%2Fcoder%2Fworkspace%2Fhello-world-rs
+
+jetbrains://gateway/com.coder.toolbox?url=https%3A%2F%2Fj5gj2r1so5nbi.pit-1.try.coder.app%2F&token=gqEirOoI1U-FfCQ6uj8iOLtybBIk99rr8&workspace=bobiverse-riker&agent=dev&ide_product_code=RR&ide_build_number=243.26053.17&folder=%2Fhome%2Fcoder%2Fworkspace%2Fhello-world-rs
+```
+
+### URI Breakdown
+
+```text
+jetbrains://gateway/com.coder.toolbox
+  ?url=http(s)://<your-coder-deployment>
+  &token=<auth-token>
+  &workspace=<workspace-name>
+  &agent/agent_id=<agent-name-or-agent-id>
+  &ide_product_code=<IDE-code>
+  &ide_build_number=<IDE-build>
+  &folder=<absolute-path-to-a-project-folder>
+```
+
+| Query param      | 	Description                                                                 | Mandatory |
+|------------------|------------------------------------------------------------------------------|-----------|
+| url              | 	Your Coder deployment URL (encoded)                                         | Yes       |
+| token            | 	Coder authentication token                                                  | Yes       |
+| workspace        | 	Name of the Coder workspace to connect to.                                  | Yes       |
+| agent            | 	Name of the agent associated with the workspace                             | No        |
+| agent_id         | 	ID of the agent associated with the workspace                               | No        |
+| ide_product_code | 	JetBrains IDE product code (e.g., GO for GoLand, RR for Rider)              | No        |
+| ide_build_number | 	Specific build number of the JetBrains IDE to install on the workspace      | No        |
+| folder           | 	Absolute path to the project folder to open in the remote IDE (URL-encoded) | No        |
+
+If only a single agent is available, specifying an agent name or ID is optional. However, if multiple agents exist,
+you must provide either the name or ID to target a specific one. Note that this version of the Coder Toolbox plugin
+does not automatically start agents if they are offline, so please ensure the selected agent is running before
+proceeding.
+
+If `ide_product_code` and `ide_build_number` is missing, Toolbox will only open and highlight the workspace environment
+page. Coder Toolbox will attempt to start the workspace if it’s not already running; however, for the most reliable
+experience, it’s recommended to ensure the workspace is running prior to initiating the connection.
+
+## Releasing
+
+1. Check that the changelog lists all the important changes.
+2. Update the gradle.properties version.
+3. Publish the resulting draft release after validating it.
+4. Merge the resulting changelog PR.
diff --git a/gradle.properties b/gradle.properties
@@ -1,3 +1,3 @@
-version=0.1.3
+version=0.1.4
 group=com.coder.toolbox
 name=coder-toolbox
diff --git a/src/main/kotlin/com/coder/toolbox/util/CoderProtocolHandler.kt b/src/main/kotlin/com/coder/toolbox/util/CoderProtocolHandler.kt
@@ -43,6 +43,10 @@ open class CoderProtocolHandler(
         reInitialize: suspend (CoderRestClient, CoderCLIManager) -> Unit
     ) {
         val params = uri.toQueryParameters()
+        if (params.isEmpty()) {
+            // probably a plugin installation scenario
+            return
+        }
 
         val deploymentURL = params.url() ?: askUrl()
         if (deploymentURL.isNullOrBlank()) {
@@ -123,7 +127,19 @@ open class CoderProtocolHandler(
         }
 
         // TODO: Show a dropdown and ask for an agent if missing.
-        val agent = getMatchingAgent(params, workspace)
+        val agent: WorkspaceAgent
+        try {
+            agent = getMatchingAgent(params, workspace)
+        } catch (e: IllegalArgumentException) {
+            context.logger.error(e, "Can't resolve an agent for workspace $workspaceName from $deploymentURL")
+            context.showErrorPopup(
+                MissingArgumentException(
+                    "Can't handle URI because we can't resolve an agent for workspace $workspaceName from $deploymentURL",
+                    e
+                )
+            )
+            return
+        }
         val status = WorkspaceAndAgentStatus.from(workspace, agent)
 
         if (!status.ready()) {
@@ -157,7 +173,7 @@ open class CoderProtocolHandler(
         context.envPageManager.showEnvironmentPage(environmentId, false)
         val productCode = params.ideProductCode()
         val buildNumber = params.ideBuildNumber()
-        val projectPath = params.projectPath()
+        val projectFolder = params.projectFolder()
         if (!productCode.isNullOrBlank() && !buildNumber.isNullOrBlank()) {
             context.cs.launch {
                 val ideVersion = "$productCode-$buildNumber"
@@ -167,7 +183,7 @@ open class CoderProtocolHandler(
                 }
                 job.join()
                 context.logger.info("launching $ideVersion on $environmentId")
-                context.ideOrchestrator.connectToIde(environmentId, ideVersion, projectPath)
+                context.ideOrchestrator.connectToIde(environmentId, ideVersion, projectFolder)
             }
         }
     }
@@ -263,9 +279,9 @@ internal fun resolveRedirects(url: URL): URL {
 /**
  * Return the agent matching the provided agent ID or name in the parameters.
  * The name is ignored if the ID is set.  If neither was supplied and the
- * workspace has only one agent, return that.  Otherwise throw an error.
+ * workspace has only one agent, return that.  Otherwise, throw an error.
  *
- * @throws [MissingArgumentException, IllegalArgumentException]
+ * @throws [IllegalArgumentException]
  */
 internal fun getMatchingAgent(
     parameters: Map<String, String?>,

diff --git a/src/main/kotlin/com/coder/toolbox/util/LinkMap.kt b/src/main/kotlin/com/coder/toolbox/util/LinkMap.kt
@@ -1,20 +1,13 @@
 package com.coder.toolbox.util
 
-// These are keys that we support in our Gateway links and must not be changed.
-private const val TYPE = "type"
 const val URL = "url"
 const val TOKEN = "token"
 const val WORKSPACE = "workspace"
 const val AGENT_NAME = "agent"
 const val AGENT_ID = "agent_id"
 private const val IDE_PRODUCT_CODE = "ide_product_code"
 private const val IDE_BUILD_NUMBER = "ide_build_number"
-private const val PROJECT_PATH = "project_path"
-
-// Helper functions for reading from the map.  Prefer these to directly
-// interacting with the map.
-
-fun Map<String, String>.isCoder(): Boolean = this[TYPE] == "coder"
+private const val FOLDER = "folder"
 
 fun Map<String, String>.url() = this[URL]
 
@@ -30,4 +23,4 @@ fun Map<String, String>.ideProductCode() = this[IDE_PRODUCT_CODE]
 
 fun Map<String, String>.ideBuildNumber() = this[IDE_BUILD_NUMBER]
 
-fun Map<String, String>.projectPath() = this[PROJECT_PATH]
+fun Map<String, String>.projectFolder() = this[FOLDER]