impl: remove support for data dir fallback setting (#287)

This PR is a result of discussion that happened in the
#286. Basically it
as an attempt of simplifying the CLI resolution and trying to be more
aligned with the VS Code extension. The existing implementation was too
cumbersome to understand, brittle and a lot of tedious work needed to
solve all of it's usecases.

This PR removes the enable fallback to data dir setting, which was used
only for access denied exceptions. The CLI resolution uses the binary
destination if it was configured by the user, or it automatically falls
back to data dir if binary destination was not configured. The
implementation respects the user's choice and no longer tries to make
smart choices on behalf of the user. For example if the user configured
the binary destination but disabled downloads we just prompt him with an
error instead of trying to fall on data dir.

There were a couple of other small improvements left from the previous
PR that are now addressed.

- resolves #285

Author: fioan89

CHANGELOG.md

@@ -4,7 +4,13 @@
 
 ### Added
 
-- support for using a locally provided CLI binary when downloads are disabled
+- `Binary destination` can now point directly to an executable, used as-is; otherwise it is treated as a base directory
+  as before
+
+### 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.
 
 ## 0.8.6 - 2026-03-05
 
@@ -17,7 +23,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,19 +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.
-  Defaults to enabled.
+- `Enable downloads` allows automatic downloading of the CLI if the current version is missing or outdated. Enabled by
+  default.
 
 - `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` when enabled, if the binary destination is not writable the
-  plugin falls back to the data directory instead of failing. Only takes effect when downloads are
-  enabled and the binary destination differs from the data directory. Defaults to disabled.
-
 - `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`).
+  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.
@@ -477,20 +474,21 @@ storage paths. The options can be configured from the plugin's main Workspaces p
 #### How CLI resolution works
 
 When connecting to a deployment the plugin ensures a compatible CLI binary is available.
-The settings above interact as follows:
-
-1. If a CLI already exists at the binary destination and its version matches the deployment, it is
-   used immediately.
-2. If **downloads are enabled**, the plugin downloads the matching version to the binary destination.
-    - If the download fails with a permission error and **binary directory fallback** is enabled (and
-      the binary destination is not already in the data directory), the plugin checks whether the data
-      directory already has a matching CLI. If so it is used; otherwise the plugin downloads to the
-      data directory instead.
-    - Any other download error is reported to the user.
-3. If **downloads are disabled**, the plugin checks the data directory for a CLI whose version
-   matches the deployment. If no exact match is found anywhere, whichever CLI is available is
-   returned — preferring the binary destination unless it is missing, in which case the data
-   directory CLI is used regardless of its version. If no CLI exists at all, an error is raised.
+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
 

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

@@ -48,24 +48,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. Create a CLI manager for the deployment URL.
  * 2. If the CLI version matches the build version, return it immediately.
- * 3. If downloads are enabled, attempt to download the CLI.
+ * 3. Otherwise, if downloads are enabled, attempt to download the CLI.
  *    a. On success, return the CLI.
- *    b. On [java.nio.file.AccessDeniedException]: rethrow if the binary
- *       path parent equals the data directory or if binary directory
- *       fallback is disabled. Otherwise, if the fallback data directory
- *       CLI already matches the build version return it; if not, download
- *       to the data directory and return the fallback CLI.
- *    c. Any other exception propagates to the caller.
+ *    b. Any exception propagates to the user.
  * 4. If downloads are disabled:
- *    a. If the data directory CLI version matches, return it.
- *    b. If neither the configured binary nor the data directory CLI can
- *       report a version, throw [IllegalStateException].
- *    c. Prefer the configured binary; fall back to the data directory CLI
- *       only when the configured binary is missing or unexecutable.
+ *    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,
@@ -95,44 +88,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
-            }
-            // fall back to the data directory.
-            val fallbackCLI = CoderCLIManager(context, deploymentURL, true)
-            val fallbackMatches = fallbackCLI.matchesVersion(buildVersion)
-            if (fallbackMatches == true) {
-                reportProgress("Local CLI version from data directory matches server version: $buildVersion")
-                return fallbackCLI
-            }
-
-            reportProgress("Downloading Coder CLI to the data directory...")
-            fallbackCLI.download(buildVersion, showTextProgress)
-            return fallbackCLI
-        }
-    }
-
-    // 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
     }
 
-    // Prefer the binary directory unless the data directory has a
-    // working binary and the binary directory does not.
-    if (cliMatches == null && dataCLIMatches == null && !settings.enableDownloads) {
+    if (cliMatches == null) {
         throw IllegalStateException("Can't resolve Coder CLI and downloads are disabled")
     }
-    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
 }
 
 /**
@@ -151,16 +115,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 {
@@ -180,7 +141,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

@@ -90,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
@@ -179,9 +173,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

@@ -54,8 +54,6 @@ class CoderSettingsStore(
     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(
@@ -127,30 +125,19 @@ class CoderSettingsStore(
      *
      * Resolution logic:
      * 1. If [binaryDestination] is null/blank, return the deployment's data
-     *    directory with the default CLI binary name. [forceDownloadToData]
-     *    is ignored because both paths resolve to the same location.
-     * 2. If [forceDownloadToData] is true, return a host-specific subdirectory
-     *    under the deployment's data directory with the default CLI binary name.
-     * 3. If the expanded (~ and $HOME) [binaryDestination] is an existing executable file,
+     *    directory with the default CLI binary name.
+     * 2. If the expanded (~ and $HOME) [binaryDestination] is an existing executable file,
      *    return it as-is.
-     * 4. Otherwise, treat [binaryDestination] as a base directory and return a
+     * 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 {
-        if (binaryDestination.isNullOrBlank()) {
-            return dataDir(url).resolve(defaultCliBinaryNameByOsAndArch).toAbsolutePath()
-        }
-
-        val dest = Path.of(expand(binaryDestination!!))
-        val isExecutable = Files.isRegularFile(dest) && Files.isExecutable(dest)
+    override fun binPath(url: URL): Path {
+        val raw = binaryDestination?.takeIf { it.isNotBlank() } ?: return dataDir(url).resolve(
+            defaultCliBinaryNameByOsAndArch
+        ).toAbsolutePath()
 
-        if (forceDownloadToData) {
-            return dataDir(url).resolve(defaultCliBinaryNameByOsAndArch).toAbsolutePath()
-        }
-        if (isExecutable) {
+        val dest = Path.of(expand(raw))
+        if (Files.isRegularFile(dest) && Files.isExecutable(dest)) {
             return dest.toAbsolutePath()
         }
         return withHost(dest, url).resolve(defaultCliBinaryNameByOsAndArch).toAbsolutePath()
@@ -222,10 +209,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

@@ -25,8 +25,6 @@ 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"

src/main/kotlin/com/coder/toolbox/util/Error.kt

@@ -4,31 +4,29 @@ import com.coder.toolbox.cli.ex.ResponseException
 import com.coder.toolbox.sdk.ex.APIResponseException
 import org.zeroturnaround.exec.InvalidExitValueException
 import java.net.ConnectException
-import java.net.SocketTimeoutException
-import java.net.URL
 import java.net.UnknownHostException
-import javax.net.ssl.SSLHandshakeException
 
-fun humanizeConnectionError(deploymentURL: URL, requireTokenAuth: Boolean, e: Exception): String {
-    val reason = e.message ?: "No reason was provided."
-    return when (e) {
-        is java.nio.file.AccessDeniedException -> "Access denied to ${e.file}."
-        is UnknownHostException -> "Unknown host ${e.message ?: deploymentURL.host}."
-        is InvalidExitValueException -> "CLI exited unexpectedly with ${e.exitValue}."
+private fun accessDenied(file: String) = "Access denied to $file"
+private fun fileSystemFailed(file: String) = "A file system operation failed when trying to access $file"
+
+fun Throwable.prettify(): String {
+    val reason = this.message ?: "No reason was provided"
+    return when (this) {
+        is AccessDeniedException -> accessDenied(this.file.toString())
+        is java.nio.file.AccessDeniedException -> accessDenied(this.file)
+        is FileSystemException -> fileSystemFailed(this.file.toString())
+        is java.nio.file.FileSystemException -> fileSystemFailed(this.file)
+        is UnknownHostException -> "Unknown host $reason"
+        is InvalidExitValueException -> "CLI exited unexpectedly with ${this.exitValue}."
         is APIResponseException -> {
-            if (e.isUnauthorized) {
-                if (requireTokenAuth) {
-                    "Token was rejected by $deploymentURL; has your token expired?"
-                } else {
-                    "Authorization failed to $deploymentURL."
-                }
+            if (this.isUnauthorized) {
+                "Authorization failed"
             } else {
                 reason
             }
         }
-        is SocketTimeoutException -> "Unable to connect to $deploymentURL; is it up?"
+
         is ResponseException, is ConnectException -> "Failed to download Coder CLI: $reason"
-        is SSLHandshakeException -> "Connection to $deploymentURL failed: $reason. See the <a href='https://coder.com/docs/v2/latest/ides/gateway#configuring-the-gateway-plugin-to-use-internal-certificates'>documentation for TLS certificates</a> for information on how to make your system trust certificates coming from your deployment."
         else -> reason
     }
 }

src/main/kotlin/com/coder/toolbox/views/CoderSettingsPage.kt

@@ -68,10 +68,6 @@ class CoderSettingsPage(
         )
     )
 
-    private val enableBinaryDirectoryFallbackField = CheckboxField(
-        settings.enableBinaryDirectoryFallback,
-        context.i18n.ptrl("Enable binary directory fallback")
-    )
     private val headerCommandField = TextField(
         context.i18n.ptrl("Header command"),
         settings.headerCommand ?: "",
@@ -132,7 +128,6 @@ class CoderSettingsPage(
             enableDownloadsField,
             useAppNameField,
             binaryDestinationField,
-            enableBinaryDirectoryFallbackField,
             disableSignatureVerificationField,
             signatureFallbackStrategyField,
             httpLoggingField,
@@ -163,7 +158,6 @@ class CoderSettingsPage(
                     updateDisableSignatureVerification(disableSignatureVerificationField.checkedState.value)
                     updateSignatureFallbackStrategy(signatureFallbackStrategyField.checkedState.value)
                     updateHttpClientLogLevel(httpLoggingField.selectedValueState.value)
-                    updateBinaryDirectoryFallback(enableBinaryDirectoryFallbackField.checkedState.value)
                     updateHeaderCommand(headerCommandField.contentState.value)
                     updateCertPath(tlsCertPathField.contentState.value)
                     updateKeyPath(tlsKeyPathField.contentState.value)
@@ -216,10 +210,6 @@ class CoderSettingsPage(
             settings.fallbackOnCoderForSignatures.isAllowed()
         }
 
-        enableBinaryDirectoryFallbackField.checkedState.update {
-            settings.enableBinaryDirectoryFallback
-        }
-
         headerCommandField.contentState.update {
             settings.headerCommand ?: ""
         }