fix(vim.ui)!: change open() to return pcall-like values #28502

Problem:
`vim.ui.open` unnecessarily invents a different success/failure
convention. Its return type was changed in 57adf8c6e01d, so we might as
well change it to have a more conventional form.

Solution:
Change the signature to use the `pcall` convention of `status, result`.

6 files changed, 25 insertions, 22 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 92c49bca40..2909f1130f 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2560,8 +2560,8 @@ vim.ui.open({path})                                            *vim.ui.open()*
         vim.ui.open("https://neovim.io/")
         vim.ui.open("~/path/to/file")
         -- Synchronous (wait until the process exits).
-        local cmd, err = vim.ui.open("$VIMRUNTIME")
-        if cmd then
+        local ok, cmd = vim.ui.open("$VIMRUNTIME")
+        if ok then
           cmd:wait()
         end
 <
@@ -2570,8 +2570,8 @@ vim.ui.open({path})                                            *vim.ui.open()*
       • {path}  (`string`) Path or URL to open
 
     Return (multiple): ~
-        (`vim.SystemObj?`) Command object, or nil if not found.
-        (`string?`) Error message on failure
+        (`boolean`) false if command not found, else true.
+        (`vim.SystemObj|string`) Command object, or error message on failure
 
     See also: ~
       • |vim.system()|
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index c05e060920..537542ee46 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -157,6 +157,8 @@ unreleased features on Nvim HEAD.
 
 • Renamed vim.tbl_isarray() to vim.isarray().
 
+• Changed |vim.ui.open()| return-signature to match pcall() convention.
+
 ==============================================================================
 NEW FEATURES                                                    *news-features*
 
diff --git a/runtime/lua/vim/_defaults.lua b/runtime/lua/vim/_defaults.lua
index 68ad95b725..419a29a5c6 100644
--- a/runtime/lua/vim/_defaults.lua
+++ b/runtime/lua/vim/_defaults.lua
@@ -98,18 +98,19 @@ do
   --- Map |gx| to call |vim.ui.open| on the <cfile> at cursor.
   do
     local function do_open(uri)
-      local cmd, err = vim.ui.open(uri)
-      local rv = cmd and cmd:wait(1000) or nil
-      if cmd and rv and rv.code ~= 0 then
-        err = ('vim.ui.open: command %s (%d): %s'):format(
+      local ok, cmd_or_err = vim.ui.open(uri)
+      local rv = ok and (cmd_or_err --[[@as vim.SystemObj]]):wait(1000) or nil
+      if rv and rv.code ~= 0 then
+        ok = false
+        cmd_or_err = ('vim.ui.open: command %s (%d): %s'):format(
           (rv.code == 124 and 'timeout' or 'failed'),
           rv.code,
-          vim.inspect(cmd.cmd)
+          vim.inspect(cmd_or_err.cmd)
         )
       end
 
-      if err then
-        vim.notify(err, vim.log.levels.ERROR)
+      if not ok then
+        vim.notify(cmd_or_err --[[@as string]], vim.log.levels.ERROR)
       end
     end
 
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index 4672d94105..ab4fa52c40 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -654,15 +654,15 @@ M[ms.window_showDocument] = function(_, result, ctx, _)
 
   if result.external then
     -- TODO(lvimuser): ask the user for confirmation
-    local cmd, err = vim.ui.open(uri)
-    local ret = cmd and cmd:wait(2000) or nil
+    local ok, cmd_or_err = vim.ui.open(uri)
+    local ret = ok and (cmd_or_err --[[@as vim.SystemObj]]):wait(2000) or nil
 
     if ret == nil or ret.code ~= 0 then
       return {
         success = false,
         error = {
           code = protocol.ErrorCodes.UnknownErrorCode,
-          message = ret and ret.stderr or err,
+          message = ret and ret.stderr or cmd_or_err,
         },
       }
     end
diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index e02acaf25c..b8323efa66 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -118,16 +118,16 @@ end
 --- vim.ui.open("https://neovim.io/")
 --- vim.ui.open("~/path/to/file")
 --- -- Synchronous (wait until the process exits).
---- local cmd, err = vim.ui.open("$VIMRUNTIME")
---- if cmd then
+--- local ok, cmd = vim.ui.open("$VIMRUNTIME")
+--- if ok then
 ---   cmd:wait()
 --- end
 --- ```
 ---
 ---@param path string Path or URL to open
 ---
----@return vim.SystemObj|nil # Command object, or nil if not found.
----@return string|nil # Error message on failure
+---@return boolean # false if command not found, else true.
+---@return vim.SystemObj|string # Command object, or error message on failure
 ---
 ---@see |vim.system()|
 function M.open(path)
@@ -147,7 +147,7 @@ function M.open(path)
     if vim.fn.executable('rundll32') == 1 then
       cmd = { 'rundll32', 'url.dll,FileProtocolHandler', path }
     else
-      return nil, 'vim.ui.open: rundll32 not found'
+      return false, 'vim.ui.open: rundll32 not found'
     end
   elseif vim.fn.executable('wslview') == 1 then
     cmd = { 'wslview', path }
@@ -156,10 +156,10 @@ function M.open(path)
   elseif vim.fn.executable('xdg-open') == 1 then
     cmd = { 'xdg-open', path }
   else
-    return nil, 'vim.ui.open: no handler found (tried: wslview, explorer.exe, xdg-open)'
+    return false, 'vim.ui.open: no handler found (tried: wslview, explorer.exe, xdg-open)'
   end
 
-  return vim.system(cmd, { text = true, detach = true }), nil
+  return true, vim.system(cmd, { text = true, detach = true })
 end
 
 return M
diff --git a/test/functional/lua/ui_spec.lua b/test/functional/lua/ui_spec.lua
index d69e893c96..3f5c051347 100644
--- a/test/functional/lua/ui_spec.lua
+++ b/test/functional/lua/ui_spec.lua
@@ -144,7 +144,7 @@ describe('vim.ui', function()
       end
       if not is_os('bsd') then
         local rv =
-          exec_lua [[local cmd = vim.ui.open('non-existent-file'); return cmd:wait(100).code]]
+          exec_lua [[local _, cmd = vim.ui.open('non-existent-file'); return cmd:wait(100).code]]
         ok(type(rv) == 'number' and rv ~= 0, 'nonzero exit code', rv)
       end