refactor(provider)!: replace providers with simpler, more maintainable server option

The plugin's purpose is _interfacing_ with `opencode` - running it is
just a neat convenience. But as the plugin has grown (yay!), that "neat
convenience" has become endless quirks and the majority of maintenance
work. Unfortunately, I'm forced to make the difficult call to remove
providers to make time for more useful work.

I retained the embedded terminal (and instructions to integrate e.g.
`snacks.terminal`) because it's useful to have _some_ way to get
started. But beyond that, it's not practical to service every user's
preferences. And anyway, it's bad UX to ask them to understand a new way
of using/configuring their terminal environment. It may make sense as
its own plugin (and feel free to extract the code for that!), but as far
as `opencode.nvim` goes, it is far, far out of scope.

Thank you for understanding! I look forward to bringing you more cool
features :D

#118
#180
#166
#104
#150
#119
#105

Author: nickjvandyke

README.md

@@ -44,7 +44,6 @@ Integrate the [opencode](https://github.com/sst/opencode) AI assistant with Neov
             },
           },
         },
-        terminal = {}, -- Enables the `snacks` provider
       },
     },
   },
@@ -123,155 +122,60 @@ Select or reference prompts to review, explain, and improve your code:
 | `review`      | Review `@this` for correctness and readability                         |
 | `test`        | Add tests for `@this`                                                  |
 
-### Provider
+### Server
 
-You can manually run `opencode` however you like and `opencode.nvim` will find them!
-
-If `opencode.nvim` can't find an existing `opencode`, it uses the configured provider (defaulting based on availability) to manage one for you.
+You can manually run `opencode`s however you like and `opencode.nvim` will find them!
 
 > [!IMPORTANT]
-> You _must_ run `opencode` with the `--port` flag to expose its server. Providers do so by default.
-
-<details>
-<summary><a href="https://neovim.io/doc/user/terminal.html">Neovim terminal</a></summary>
-
-```lua
-vim.g.opencode_opts = {
-  provider = {
-    enabled = "terminal",
-    terminal = {
-      -- ...
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><a href="https://github.com/folke/snacks.nvim/blob/main/docs/terminal.md">snacks.terminal</a></summary>
-
-```lua
-vim.g.opencode_opts = {
-  provider = {
-    enabled = "snacks",
-    snacks = {
-      -- ...
-    }
-  }
-}
-```
-
-</details>
+> You _must_ run `opencode` with the `--port` flag to expose its server.
 
-<details>
-<summary><a href="https://sw.kovidgoyal.net/kitty/">kitty</a></summary>
+If `opencode.nvim` can't find an existing `opencode`, it uses the configured server to start one for you, defaulting to an embedded terminal.
 
-```lua
-vim.g.opencode_opts = {
-  provider = {
-    enabled = "kitty",
-    kitty = {
-      -- ...
-    }
-  }
-}
-```
-
-The kitty provider requires [remote control via a socket](https://sw.kovidgoyal.net/kitty/remote-control/#remote-control-via-a-socket) to be enabled.
-
-You can do this either by running Kitty with the following command:
-
-```bash
-# For Linux only:
-kitty -o allow_remote_control=yes --single-instance --listen-on unix:@mykitty
-
-# Other UNIX systems:
-kitty -o allow_remote_control=yes --single-instance --listen-on unix:/tmp/mykitty
-```
-
-OR, by adding the following to your `kitty.conf`:
-
-```
-# For Linux only:
-allow_remote_control yes
-listen_on unix:@mykitty
-# Other UNIX systems:
-allow_remote_control yes
-listen_on unix:/tmp/kitty
-```
-
-</details>
+#### Keymaps
 
-<details>
-<summary><a href="https://wezterm.org/">wezterm</a></summary>
+`opencode.nvim` sets these normal-mode keymaps in the embedded terminal for Neovim-like message navigation:
 
-```lua
-vim.g.opencode_opts = {
-  provider = {
-    enabled = "wezterm",
-    wezterm = {
-      -- ...
-    }
-  }
-}
-```
+| Keymap  | Command                  | Description           |
+| ------- | ------------------------ | --------------------- |
+| `<C-u>` | `session.half.page.up`   | Scroll up half page   |
+| `<C-d>` | `session.half.page.down` | Scroll down half page |
+| `gg`    | `session.first`          | Go to first message   |
+| `G`     | `session.last`           | Go to last message    |
+| `<Esc>` | `session.interrupt`      | Interrupt             |
 
-</details>
+#### Customization
 
-<details>
-<summary><a href="https://github.com/tmux/tmux">tmux</a></summary>
+Example using [`snacks.terminal`](https://github.com/folke/snacks.nvim/blob/main/docs/terminal.md) instead:
 
 ```lua
-vim.g.opencode_opts = {
-  provider = {
-    enabled = "tmux",
-    tmux = {
-      -- ...
-    }
-  }
+local opencode_cmd = 'opencode --port'
+---@type snacks.terminal.Opts
+local snacks_terminal_opts = {
+  win = {
+    position = 'right',
+    enter = false,
+    on_win = function(win)
+      -- Set up keymaps and cleanup for an arbitrary terminal
+      require('opencode.terminal').setup(win.win)
+    end,
+  },
 }
-```
-
-</details>
-
-<details>
-<summary>custom</summary>
-
-Integrate your custom method for convenience!
-
-```lua
+---@type opencode.Opts
 vim.g.opencode_opts = {
-  provider = {
-    toggle = function(self)
-      -- ...
+  server = {
+    start = function()
+      require('snacks.terminal').open(opencode_cmd, snacks_terminal_opts)
     end,
-    start = function(self)
-      -- ...
+    stop = function()
+      require('snacks.terminal').get(opencode_cmd, snacks_terminal_opts):close()
     end,
-    stop = function(self)
-      -- ...
+    toggle = function()
+      require('snacks.terminal').toggle(opencode_cmd, snacks_terminal_opts)
     end,
-  }
+  },
 }
 ```
 
-</details>
-
-Please submit PRs adding new providers! 🙂
-
-#### Keymaps
-
-`opencode.nvim` sets these buffer-local keymaps in provider terminals for Neovim-like message navigation:
-
-| Keymap  | Command                  | Description           |
-| ------- | ------------------------ | --------------------- |
-| `<C-u>` | `session.half.page.up`   | Scroll up half page   |
-| `<C-d>` | `session.half.page.down` | Scroll down half page |
-| `<Esc>` | `session.interrupt`      | Interrupt             |
-| `gg`    | `session.first`          | Go to first message   |
-| `G`     | `session.last`           | Go to last message    |
-
 ## 🚀 Usage
 
 ### Ask — `require("opencode").ask()`
@@ -293,7 +197,7 @@ Select from all `opencode.nvim` functionality.
 - Prompts
 - Commands
   - Fetches custom commands from `opencode`
-- Provider controls
+- Server controls
 
 Highlights and previews items when using `snacks.picker`.
 
@@ -343,7 +247,7 @@ Command `opencode`:
 | LSP Function | `opencode.nvim` Handler                                                 |
 | ------------ | ----------------------------------------------------------------------- |
 | Hover        | Asks `opencode` for a brief explanation of the symbol under the cursor. |
-| Code Actions | Asks `opencode` to explain or fix diagnostics under the cursor.                    |
+| Code Actions | Asks `opencode` to explain or fix diagnostics under the cursor.         |
 
 ## 👀 Events
 

lua/opencode.lua

@@ -49,7 +49,6 @@ end
 --- - Prompts
 --- - Commands
 ---   - Fetches custom commands from `opencode`
---- - Provider controls
 --- - Server controls
 ---
 --- Highlights and previews items when using `snacks.picker`.
@@ -131,12 +130,36 @@ end
 M.operator = require("opencode.api.operator").operator
 
 ----------------
---- Provider ---
+--- Server ---
 ----------------
 
-M.toggle = require("opencode.provider").toggle
-M.start = require("opencode.provider").start
-M.stop = require("opencode.provider").stop
+---Toggle the configured `opencode` server.
+M.toggle = function()
+  local opts = require("opencode.config").opts
+  if opts.server and opts.server.toggle then
+    opts.server.toggle()
+  else
+    vim.notify("No server `toggle` function configured", vim.log.levels.ERROR, { title = "opencode" })
+  end
+end
+---Start the configured `opencode` server.
+M.start = function()
+  local opts = require("opencode.config").opts
+  if opts.server and opts.server.start then
+    opts.server.start()
+  else
+    vim.notify("No server `start` function configured", vim.log.levels.ERROR, { title = "opencode" })
+  end
+end
+---Stop the configured `opencode` server.
+M.stop = function()
+  local opts = require("opencode.config").opts
+  if opts.server and opts.server.stop then
+    opts.server.stop()
+  else
+    vim.notify("No server `stop` function configured", vim.log.levels.ERROR, { title = "opencode" })
+  end
+end
 
 --------------------
 --- Integrations ---

lua/opencode/cli/client.lua

@@ -277,7 +277,6 @@ end
 ---@field properties table
 
 ---Calls the `/event` SSE endpoint and invokes `callback` for each event received.
----Stops any previous subscription, so only one is active at a time.
 ---
 ---@param port number
 ---@param callback fun(response: opencode.cli.client.Event)|nil

lua/opencode/cli/server.lua

@@ -1,5 +1,21 @@
 local M = {}
 
+---@class opencode.cli.server.Opts
+---
+---The port to look for `opencode` on.
+---When set, _only_ this port will be checked.
+---When not set, _all_ `opencode` processes will be checked.
+---Be sure to also launch `opencode` accordingly, e.g. `opencode --port 12345`.
+---@field port? number
+---
+---Start an `opencode` server.
+---Called when when none are found; will retry after.
+---@field start? fun()|false
+---
+---@field stop? fun()|false
+---
+---@field toggle? fun()|false
+
 ---An `opencode` server process and some details about it.
 ---@class opencode.cli.server.Server
 ---@field port number
@@ -176,7 +192,7 @@ end
 ---1. The currently subscribed server in `opencode.events`.
 ---2. The configured port in `require("opencode.config").opts.port`.
 ---3. All servers, prioritizing one sharing CWD with Neovim, and prompting the user to select if multiple are found.
----4. Calling `require("opencode.provider").start()` to launch a new server, then retrying the above.
+---4. Calling `opts.server.start()`, then retrying the above.
 ---
 ---Upon success, subscribes to the server's events.
 ---
@@ -185,10 +201,11 @@ end
 function M.get(launch)
   launch = launch ~= false
 
+  local opts = require("opencode.config").opts.server or {}
+
   local Promise = require("opencode.promise")
   return Promise.resolve(
-    require("opencode.events").connected_server and require("opencode.events").connected_server.port
-      or require("opencode.config").opts.port
+    require("opencode.events").connected_server and require("opencode.events").connected_server.port or opts.port
   )
     :next(function(priority_port) ---@param priority_port number
       if priority_port then
@@ -229,13 +246,13 @@ function M.get(launch)
       end
 
       return Promise.new(function(resolve, reject)
-        if launch then
-          local start_ok, start_result = pcall(require("opencode.provider").start)
+        if launch and opts.start then
+          local start_ok, start_result = pcall(opts.start)
           if not start_ok then
             return reject("Error starting `opencode`: " .. start_result)
           end
 
-          -- Wait for the provider to start
+          -- Wait for the server to start
           vim.defer_fn(function()
             resolve(true)
           end, 2000)