fix(runtime): validate remote config and harden runtime commands

Fail fast on invalid runtime.connection, remote_url, command arrays, timeout, and path transform returns so misconfiguration is surfaced clearly. Also URL-encode query parameters to avoid malformed API requests with mapped paths.

Author: dekaravanhoc

lua/opencode/api_client.lua

@@ -2,6 +2,12 @@ local server_job = require('opencode.server_job')
 local state = require('opencode.state')
 local util = require('opencode.util')
 
+local function encode_query_value(value)
+	return tostring(value):gsub('([^%w%-_%.~])', function(ch)
+		return string.format('%%%02X', string.byte(ch))
+	end)
+end
+
 --- @class OpencodeApiClient
 --- @field base_url string The base URL of the opencode server
 local OpencodeApiClient = {}
@@ -80,7 +86,7 @@ function OpencodeApiClient:_call(endpoint, method, body, query)
 
 		for k, v in pairs(normalized_query) do
 			if v ~= nil then
-				table.insert(params, k .. '=' .. tostring(v))
+				table.insert(params, k .. '=' .. encode_query_value(v))
 			end
 		end
 
@@ -443,7 +449,7 @@ function OpencodeApiClient:subscribe_to_events(directory, on_event)
 	local url = self.base_url .. '/event'
 	directory = util.to_server_path(directory)
 	if directory then
-		url = url .. '?directory=' .. directory
+		url = url .. '?directory=' .. encode_query_value(directory)
 	end
 
 	return server_job.stream_api(url, 'GET', nil, function(chunk)

lua/opencode/core.lua

@@ -430,18 +430,27 @@ end)
 
 M.opencode_ok = Promise.async(function()
   local runtime = config.runtime or {}
-  local connection = runtime.connection or 'spawn'
+  local connection, connection_err = util.get_runtime_connection()
+  if not connection then
+    vim.notify(connection_err, vim.log.levels.ERROR)
+    return false
+  end
 
   if connection == 'remote' then
-    local remote_url = runtime.remote_url
-    if type(remote_url) ~= 'string' or remote_url == '' then
-      vim.notify('runtime.remote_url is required when runtime.connection is "remote"', vim.log.levels.ERROR)
+    local _, remote_url_err = util.normalize_remote_url(runtime.remote_url)
+    if remote_url_err then
+      vim.notify(remote_url_err, vim.log.levels.ERROR)
       return false
     end
     return true
   end
 
-  local runtime_cmd = util.get_runtime_command()
+  local runtime_cmd, runtime_cmd_err = util.get_runtime_command()
+  if not runtime_cmd then
+    vim.notify(runtime_cmd_err, vim.log.levels.ERROR)
+    return false
+  end
+
   if vim.fn.executable(runtime_cmd[1]) == 0 then
     vim.notify(
       string.format(
@@ -454,7 +463,11 @@ M.opencode_ok = Promise.async(function()
   end
 
   if not state.opencode_cli_version or state.opencode_cli_version == '' then
-    local cmd = util.get_runtime_version_command()
+    local cmd, cmd_err = util.get_runtime_version_command()
+    if not cmd then
+      vim.notify(cmd_err, vim.log.levels.ERROR)
+      return false
+    end
     local result = Promise.system(cmd):await()
     local out = (result and result.stdout or ''):gsub('%s+$', '')
     state.opencode_cli_version = out:match('(%d+%%.%d+%%.%d+)') or out

lua/opencode/health.lua

@@ -8,12 +8,19 @@ local function command_exists(cmd)
 end
 
 local function get_opencode_version()
-  local runtime_cmd = util.get_runtime_command()
+  local runtime_cmd, runtime_cmd_err = util.get_runtime_command()
+  if not runtime_cmd then
+    return nil, runtime_cmd_err
+  end
+
   if not command_exists(runtime_cmd[1]) then
     return nil, 'opencode runtime command not found: ' .. tostring(runtime_cmd[1])
   end
 
-  local cmd = util.get_runtime_version_command()
+  local cmd, cmd_err = util.get_runtime_version_command()
+  if not cmd then
+    return nil, cmd_err
+  end
 
   local result = vim.system(cmd):wait()
   if result.code ~= 0 then
@@ -29,8 +36,11 @@ local function check_opencode_cli()
   health.start('OpenCode CLI')
 
   local config = require('opencode.config')
-  local runtime = config.runtime or {}
-  local connection = runtime.connection or 'spawn'
+  local connection, connection_err = util.get_runtime_connection()
+  if not connection then
+    health.error(connection_err)
+    return
+  end
 
   if connection == 'remote' then
     health.info('CLI executable checks are skipped in remote runtime mode')
@@ -40,7 +50,12 @@ local function check_opencode_cli()
   local state = require('opencode.state')
   local required_version = state.required_version
 
-  local runtime_cmd = util.get_runtime_command()
+  local runtime_cmd, runtime_cmd_err = util.get_runtime_command()
+  if not runtime_cmd then
+    health.error(runtime_cmd_err)
+    return
+  end
+
   if not command_exists(runtime_cmd[1]) then
     health.error('opencode runtime command not found', {
       'Install opencode CLI from: https://docs.opencode.com/installation',
@@ -73,21 +88,19 @@ local function check_opencode_server()
 
   local config = require('opencode.config')
   local runtime = config.runtime or {}
-  local connection = runtime.connection or 'spawn'
+  local connection, connection_err = util.get_runtime_connection()
+  if not connection then
+    health.error(connection_err)
+    return
+  end
 
   if connection == 'remote' then
-    local remote_url = runtime.remote_url
-    if type(remote_url) ~= 'string' or remote_url == '' then
-      health.error('runtime.remote_url is required when runtime.connection is "remote"')
+    local normalized_remote_url, remote_url_err = util.normalize_remote_url(runtime.remote_url)
+    if not normalized_remote_url then
+      health.error(remote_url_err)
       return
     end
 
-    local normalized_remote_url = remote_url
-    if normalized_remote_url:match('^%d+%.%d+%.%d+%.%d+:%d+$') or normalized_remote_url:match('^localhost:%d+$') then
-      normalized_remote_url = 'http://' .. normalized_remote_url
-    end
-    normalized_remote_url = normalized_remote_url:gsub('/$', '')
-
     local server_job = require('opencode.server_job')
     local ok, result = pcall(function()
       return server_job.call_api(normalized_remote_url .. '/config', 'GET', nil):wait()

lua/opencode/opencode_server.lua

@@ -1,7 +1,6 @@
 local util = require('opencode.util')
 local safe_call = util.safe_call
 local Promise = require('opencode.promise')
-local config = require('opencode.config')
 
 --- @class OpencodeServer
 --- @field job any The vim.system job handle
@@ -198,7 +197,12 @@ function OpencodeServer:spawn(opts)
     end
   end
 
-  local cmd = util.get_runtime_serve_command()
+  local cmd, cmd_err = util.get_runtime_serve_command()
+  if not cmd then
+    self.spawn_promise:reject(cmd_err)
+    safe_call(opts.on_error, cmd_err)
+    return self.spawn_promise
+  end
   local system_opts = {
     cwd = opts.cwd,
   }
@@ -270,7 +274,13 @@ function OpencodeServer:spawn(opts)
 
   self.handle = self.job and self.job.pid
 
-  local startup_timeout_ms = tonumber(config.runtime and config.runtime.startup_timeout_ms) or 15000
+  local startup_timeout_ms, timeout_err = util.get_runtime_startup_timeout_ms()
+  if not startup_timeout_ms then
+    self.spawn_promise:reject(timeout_err)
+    safe_call(opts.on_error, timeout_err)
+    return self.spawn_promise
+  end
+
   vim.defer_fn(function()
     if ready then
       return

lua/opencode/server_job.lua

@@ -139,21 +139,34 @@ end
 function M.ensure_server()
   local promise = Promise.new()
   local runtime = config.runtime or {}
-  local connection = runtime.connection or 'spawn'
+  local connection, connection_err = util.get_runtime_connection()
+
+  if not connection then
+    log.error(connection_err)
+    vim.notify(connection_err, vim.log.levels.ERROR)
+    return promise:reject(connection_err)
+  end
 
   if state.opencode_server and state.opencode_server:is_running() then
     return promise:resolve(state.opencode_server)
   end
 
   state.opencode_server = opencode_server.new()
   local cwd = vim.fn.getcwd()
-  local pre_start_command = util.get_runtime_pre_start_command()
+  local pre_start_command, pre_start_command_err = util.get_runtime_pre_start_command()
+
+  if pre_start_command_err then
+    log.error(pre_start_command_err)
+    vim.notify(pre_start_command_err, vim.log.levels.ERROR)
+    state.opencode_server = nil
+    return promise:reject(pre_start_command_err)
+  end
 
   local function continue_startup()
     if connection == 'remote' then
-      local remote_url = runtime.remote_url
-      if type(remote_url) ~= 'string' or remote_url == '' then
-        local err = 'runtime.remote_url must be set when runtime.connection is "remote"'
+      local remote_url, remote_url_err = util.normalize_remote_url(runtime.remote_url)
+      if not remote_url then
+        local err = remote_url_err
         log.error(err)
         vim.notify(err, vim.log.levels.ERROR)
         state.opencode_server = nil