Merge branch 'main' into impl-support-for-oauth

Author: fioan89

CHANGELOG.md

@@ -4,10 +4,14 @@
 
 ### Added
 
+- `Binary destination` can now point directly to an executable, used as-is; otherwise it is treated as a base directory
+  as before
 - support for OAuth2
 
-### Changed
+### Removed
 
+- support for enabling or disabling the fallback to data dir. CLI resolution will always fall back on data dir if binary
+  destination is not configured.
 - redesigned the Settings page, all the options are now grouped in a couple of sections for easy navigation
 
 ## 0.8.6 - 2026-03-05
@@ -21,7 +25,8 @@
 ### Added
 
 - support for configuring the SSH connection timeout, defaults to 10 seconds
-- enhanced IDE resolution by supporting latest EAP, latest release, latest installed labels with clear fallback behavior in URI handlers
+- enhanced IDE resolution by supporting latest EAP, latest release, latest installed labels with clear fallback behavior
+  in URI handlers
 
 ### Fixed
 

README.md

@@ -447,16 +447,16 @@ storage paths. The options can be configured from the plugin's main Workspaces p
 - `Binary source` specifies the source URL or relative path from which the Coder CLI should be downloaded.
   If a relative path is provided, it is resolved against the deployment domain.
 
-- `Enable downloads` allows automatic downloading of the CLI if the current version is missing or outdated.
+- `Enable downloads` allows automatic downloading of the CLI if the current version is missing or outdated. Enabled by
+  default.
 
-- `Binary directory` specifies the directory where CLI binaries are stored. If omitted, it defaults to the data
-  directory.
+- `Binary destination` specifies where the CLI binary is placed. This can be a path to an existing
+  executable (used as-is) or a base directory (the CLI is placed under a host-specific subdirectory).
+  If blank, the data directory is used. Supports `~` and `$HOME` expansion.
 
-- `Enable binary directory fallback` if enabled, falls back to the data directory when the specified binary
-  directory is not writable.
-
-- `Data directory` directory where plugin-specific data such as session tokens and binaries are stored if not
-  overridden by the binary directory setting.
+- `Data directory` directory where deployment-specific data such as session tokens and CLI binaries
+  are stored. Each deployment gets a host-specific subdirectory (e.g. `coder.example.com`). Supports `~` and `$HOME`
+  expansion.
 
 - `Header command` command that outputs additional HTTP headers. Each line of output must be in the format key=value.
   The environment variable CODER_URL will be available to the command process.
@@ -471,6 +471,25 @@ storage paths. The options can be configured from the plugin's main Workspaces p
   Helpful for customers that have their own in-house dashboards. Defaults to the Coder deployment templates page.
   This setting supports `$workspaceOwner` as placeholder with the replacing value being the username that logged in.
 
+#### How CLI resolution works
+
+When connecting to a deployment the plugin ensures a compatible CLI binary is available.
+The binary location is resolved as follows:
+
+- If **binary destination** points to an existing executable file, it is used as-is.
+- If **binary destination** is set but is not an executable file, it is treated as a base
+  directory and the CLI is placed under a host-specific subdirectory (e.g.
+  `<binary destination>/coder.example.com/<default-cli-name>`).
+- If **binary destination** is not set, the data directory is used instead.
+
+Once the binary location is resolved:
+
+1. If a CLI already exists there and its version matches the deployment, it is used immediately.
+2. Otherwise, if **downloads are enabled**, the plugin downloads the matching version to that location.
+   Any download error is reported to the user.
+3. If **downloads are disabled** and the CLI exists but its version does not match, the stale
+   CLI is used with a warning. If no CLI exists at all, an error is raised.
+
 ### TLS settings
 
 The following options control the secure communication behavior of the plugin with Coder deployment and its available

gradle/libs.versions.toml

@@ -13,7 +13,7 @@ ksp = "2.3.6"
 retrofit = "3.0.0"
 changelog = "2.5.0"
 gettext = "0.7.0"
-plugin-structure = "3.321"
+plugin-structure = "3.323"
 mockk = "1.14.9"
 detekt = "1.23.8"
 bouncycastle = "1.83"

src/main/kotlin/com/coder/toolbox/cli/CoderCLIManager.kt

@@ -45,16 +45,17 @@ internal data class Version(
 
 
 /**
- * Do as much as possible to get a valid, up-to-date CLI.
+ * Best effort to get an up-to-date CLI.
  *
- * 1. Read the binary directory for the provided URL.
- * 2. Abort if we already have an up-to-date version.
- * 3. Download the binary using an ETag.
- * 4. Abort if we get a 304 (covers cases where the binary is older and does not
- *    have a version command).
- * 5. Download on top of the existing binary.
- * 6. Since the binary directory can be read-only, if downloading fails, start
- *    from step 2 with the data directory.
+ * 1. Create a CLI manager for the deployment URL.
+ * 2. If the CLI version matches the build version, return it immediately.
+ * 3. Otherwise, if downloads are enabled, attempt to download the CLI.
+ *    a. On success, return the CLI.
+ *    b. Any exception propagates to the user.
+ * 4. If downloads are disabled:
+ *    a. [IllegalStateException] is raised if the CLI does not exist (look into binary destination if it was configured,
+ *    fallback to data dir otherwise)
+ *    b. Otherwise, warn the user and return the mismatched version.
  */
 suspend fun ensureCLI(
     context: CoderToolboxContext,
@@ -84,36 +85,15 @@ suspend fun ensureCLI(
     // If downloads are enabled download the new version.
     if (settings.enableDownloads) {
         reportProgress("Downloading Coder CLI...")
-        try {
-            cli.download(buildVersion, showTextProgress)
-            return cli
-        } catch (e: java.nio.file.AccessDeniedException) {
-            // Might be able to fall back to the data directory.
-            val binPath = settings.binPath(deploymentURL)
-            val dataDir = settings.dataDir(deploymentURL)
-            if (binPath.parent == dataDir || !settings.enableBinaryDirectoryFallback) {
-                throw e
-            }
-        }
-    }
-
-    // Try falling back to the data directory.
-    val dataCLI = CoderCLIManager(context, deploymentURL, true)
-    val dataCLIMatches = dataCLI.matchesVersion(buildVersion)
-    if (dataCLIMatches == true) {
-        reportProgress("Local CLI version from data directory matches server version: $buildVersion")
-        return dataCLI
+        cli.download(buildVersion, showTextProgress)
+        return cli
     }
 
-    if (settings.enableDownloads) {
-        reportProgress("Downloading Coder CLI to the data directory...")
-        dataCLI.download(buildVersion, showTextProgress)
-        return dataCLI
+    if (cliMatches == null) {
+        throw IllegalStateException("Can't resolve Coder CLI and downloads are disabled")
     }
-
-    // Prefer the binary directory unless the data directory has a
-    // working binary and the binary directory does not.
-    return if (cliMatches == null && dataCLIMatches != null) dataCLI else cli
+    reportProgress("Downloads are disabled, and a cached CLI is used which does not match the server version $buildVersion and could cause compatibility issues")
+    return cli
 }
 
 /**
@@ -132,16 +112,13 @@ data class Features(
 class CoderCLIManager(
     private val context: CoderToolboxContext,
     // The URL of the deployment this CLI is for.
-    private val deploymentURL: URL,
-    // If the binary directory is not writable, this can be used to force the
-    // manager to download to the data directory instead.
-    private val forceDownloadToData: Boolean = false,
+    private val deploymentURL: URL
 ) {
     private val downloader = createDownloadService()
     private val gpgVerifier = GPGVerifier(context)
 
     val remoteBinaryURL: URL = context.settingsStore.binSource(deploymentURL)
-    val localBinaryPath: Path = context.settingsStore.binPath(deploymentURL, forceDownloadToData)
+    val localBinaryPath: Path = context.settingsStore.binPath(deploymentURL)
     val coderConfigPath: Path = context.settingsStore.dataDir(deploymentURL).resolve("config")
 
     private fun createDownloadService(): CoderDownloadService {
@@ -154,7 +131,7 @@ class CoderCLIManager(
             .build()
 
         val service = retrofit.create(CoderDownloadApi::class.java)
-        return CoderDownloadService(context, service, deploymentURL, forceDownloadToData)
+        return CoderDownloadService(context, service, deploymentURL)
     }
 
     /**

src/main/kotlin/com/coder/toolbox/cli/downloader/CoderDownloadService.kt

@@ -38,17 +38,17 @@ private val SUPPORTED_BIN_MIME_TYPES = listOf(
     "application/x-ms-dos-executable",
     "application/vnd.microsoft.portable-executable"
 )
+
 /**
  * Handles the download steps of Coder CLI
  */
 class CoderDownloadService(
     private val context: CoderToolboxContext,
     private val downloadApi: CoderDownloadApi,
-    private val deploymentUrl: URL,
-    forceDownloadToData: Boolean,
+    private val deploymentUrl: URL
 ) {
     private val remoteBinaryURL: URL = context.settingsStore.binSource(deploymentUrl)
-    private val cliFinalDst: Path = context.settingsStore.binPath(deploymentUrl, forceDownloadToData)
+    private val cliFinalDst: Path = context.settingsStore.binPath(deploymentUrl)
     private val cliTempDst: Path = cliFinalDst.resolveSibling("${cliFinalDst.name}.tmp")
 
     suspend fun downloadCli(buildVersion: String, showTextProgress: (String) -> Unit): DownloadResult {

src/main/kotlin/com/coder/toolbox/settings/ReadOnlyCoderSettings.kt

@@ -35,10 +35,13 @@ interface ReadOnlyCoderSettings {
     val binarySource: String?
 
     /**
-     * Directories are created here that store the CLI for each domain to which
-     * the plugin connects.   Defaults to the data directory.
+     * An absolute path to either a directory or an existing executable CLI binary.
+     * When the path points to an existing executable file, it is used as the CLI
+     * binary path directly. Otherwise, it is treated as a base directory under
+     * which the CLI is placed in a host-specific subdirectory. Defaults to the
+     * data directory when not set.
      */
-    val binaryDirectory: String?
+    val binaryDestination: String?
 
     /**
      * Controls whether we verify the cli signature
@@ -60,19 +63,14 @@ interface ReadOnlyCoderSettings {
      */
     val defaultCliBinaryNameByOsAndArch: String
 
-    /**
-     * Configurable CLI binary name with extension, dependent on OS and arch
-     */
-    val binaryName: String
-
     /**
      * Default CLI signature name based on OS and architecture
      */
     val defaultSignatureNameByOsAndArch: String
 
     /**
      * Where to save plugin data like the Coder binary (if not configured with
-     * binaryDirectory) and the deployment URL and session token.
+     * binaryDestination) and the deployment URL and session token.
      */
     val dataDirectory: String?
 
@@ -92,12 +90,6 @@ interface ReadOnlyCoderSettings {
      */
     val enableDownloads: Boolean
 
-    /**
-     * Whether to allow the plugin to fall back to the data directory when the
-     * CLI directory is not writable.
-     */
-    val enableBinaryDirectoryFallback: Boolean
-
     /**
      * An external command that outputs additional HTTP headers added to all
      * requests. The command must output each header as `key=value` on its own
@@ -187,9 +179,9 @@ interface ReadOnlyCoderSettings {
     fun binSource(url: URL): URL
 
     /**
-     * To where the specified deployment should download the binary.
+     * Returns a path to where the specified deployment should place the CLI binary.
      */
-    fun binPath(url: URL, forceDownloadToData: Boolean = false): Path
+    fun binPath(url: URL): Path
 
     /**
      * Return the URL and token from the config, if they exist.

src/main/kotlin/com/coder/toolbox/store/CoderSettingsStore.kt

@@ -41,22 +41,19 @@ class CoderSettingsStore(
     override val defaultURL: String get() = store[DEFAULT_URL] ?: "https://dev.coder.com"
     override val useAppNameAsTitle: Boolean get() = store[APP_NAME_AS_TITLE]?.toBooleanStrictOrNull() ?: false
     override val binarySource: String? get() = store[BINARY_SOURCE]
-    override val binaryDirectory: String? get() = store[BINARY_DIRECTORY]
+    override val binaryDestination: String? get() = store[BINARY_DESTINATION] ?: store[BINARY_DIRECTORY]
     override val disableSignatureVerification: Boolean
         get() = store[DISABLE_SIGNATURE_VALIDATION]?.toBooleanStrictOrNull() ?: false
     override val fallbackOnCoderForSignatures: SignatureFallbackStrategy
         get() = SignatureFallbackStrategy.fromValue(store[FALLBACK_ON_CODER_FOR_SIGNATURES])
     override val httpClientLogLevel: HttpLoggingVerbosity
         get() = HttpLoggingVerbosity.fromValue(store[HTTP_CLIENT_LOG_LEVEL])
     override val defaultCliBinaryNameByOsAndArch: String get() = getCoderCLIForOS(getOS(), getArch())
-    override val binaryName: String get() = store[BINARY_NAME] ?: getCoderCLIForOS(getOS(), getArch())
     override val defaultSignatureNameByOsAndArch: String get() = getCoderSignatureForOS(getOS(), getArch())
     override val dataDirectory: String? get() = store[DATA_DIRECTORY]
     override val globalDataDirectory: String get() = getDefaultGlobalDataDir().normalize().toString()
     override val globalConfigDir: String get() = getDefaultGlobalConfigDir().normalize().toString()
     override val enableDownloads: Boolean get() = store[ENABLE_DOWNLOADS]?.toBooleanStrictOrNull() ?: true
-    override val enableBinaryDirectoryFallback: Boolean
-        get() = store[ENABLE_BINARY_DIR_FALLBACK]?.toBooleanStrictOrNull() ?: false
     override val headerCommand: String? get() = store[HEADER_COMMAND]
     override val tls: ReadOnlyTLSSettings
         get() = TLSSettings(
@@ -125,21 +122,26 @@ class CoderSettingsStore(
     }
 
     /**
-     * To where the specified deployment should download the binary.
+     * To where the specified deployment should place the CLI binary.
+     *
+     * Resolution logic:
+     * 1. If [binaryDestination] is null/blank, return the deployment's data
+     *    directory with the default CLI binary name.
+     * 2. If the expanded (~ and $HOME) [binaryDestination] is an existing executable file,
+     *    return it as-is.
+     * 3. Otherwise, treat [binaryDestination] as a base directory and return a
+     *    host-specific subdirectory with the default CLI binary name.
      */
-    override fun binPath(
-        url: URL,
-        forceDownloadToData: Boolean,
-    ): Path {
-        binaryDirectory.let {
-            val dir =
-                if (forceDownloadToData || it.isNullOrBlank()) {
-                    dataDir(url)
-                } else {
-                    withHost(Path.of(expand(it)), url)
-                }
-            return dir.resolve(binaryName).toAbsolutePath()
+    override fun binPath(url: URL): Path {
+        val raw = binaryDestination?.takeIf { it.isNotBlank() } ?: return dataDir(url).resolve(
+            defaultCliBinaryNameByOsAndArch
+        ).toAbsolutePath()
+
+        val dest = Path.of(expand(raw))
+        if (Files.isRegularFile(dest) && Files.isExecutable(dest)) {
+            return dest.toAbsolutePath()
         }
+        return withHost(dest, url).resolve(defaultCliBinaryNameByOsAndArch).toAbsolutePath()
     }
 
     /**
@@ -180,8 +182,8 @@ class CoderSettingsStore(
         store[BINARY_SOURCE] = source
     }
 
-    fun updateBinaryDirectory(dir: String) {
-        store[BINARY_DIRECTORY] = dir
+    fun updateBinaryDestination(dest: String) {
+        store[BINARY_DESTINATION] = dest
     }
 
     fun updateDataDirectory(dir: String) {
@@ -208,10 +210,6 @@ class CoderSettingsStore(
         store[HTTP_CLIENT_LOG_LEVEL] = level.toString()
     }
 
-    fun updateBinaryDirectoryFallback(shouldEnableBinDirFallback: Boolean) {
-        store[ENABLE_BINARY_DIR_FALLBACK] = shouldEnableBinDirFallback.toString()
-    }
-
     fun updateHeaderCommand(cmd: String) {
         store[HEADER_COMMAND] = cmd
     }

src/main/kotlin/com/coder/toolbox/store/StoreKeys.kt

@@ -10,22 +10,21 @@ internal const val APP_NAME_AS_TITLE = "useAppNameAsTitle"
 
 internal const val BINARY_SOURCE = "binarySource"
 
+@Deprecated("Use BINARY_DESTINATION instead", replaceWith = ReplaceWith("BINARY_DESTINATION"))
 internal const val BINARY_DIRECTORY = "binaryDirectory"
 
+internal const val BINARY_DESTINATION = "binaryDestination"
+
 internal const val DISABLE_SIGNATURE_VALIDATION = "disableSignatureValidation"
 
 internal const val FALLBACK_ON_CODER_FOR_SIGNATURES = "signatureFallbackStrategy"
 
 internal const val HTTP_CLIENT_LOG_LEVEL = "httpClientLogLevel"
 
-internal const val BINARY_NAME = "binaryName"
-
 internal const val DATA_DIRECTORY = "dataDirectory"
 
 internal const val ENABLE_DOWNLOADS = "enableDownloads"
 
-internal const val ENABLE_BINARY_DIR_FALLBACK = "enableBinaryDirectoryFallback"
-
 internal const val HEADER_COMMAND = "headerCommand"
 
 internal const val TLS_CERT_PATH = "tlsCertPath"