From 0ccfb2da4b3a6dee023092ca97def655dc708b9f Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Tue, 10 Mar 2026 22:16:25 -0400
Subject: [PATCH] refactor(forge): extract ForgeBackend class and registry
 (#129)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: document S3 backend, auto-auth, and `:Pending done` command

Problem: The S3 backend had no `:Pending s3` entry in the COMMANDS
section, `:Pending auth` only mentioned Google, the `sync` config
field omitted `s3`, `_s3_sync_id` was missing from the data format
section, `:Pending done` was implemented but undocumented, and the
README lacked a features overview.

Solution: Add `:Pending s3` and `:Pending done` command docs, rewrite
`:Pending auth` to cover all backends and sub-actions, update config
and data format references, add `aws` CLI to requirements, and add a
Features section to `README.md`.

* feat(forge): add forge link parser and metadata fetcher

Problem: no way to associate tasks with GitHub, GitLab, or Codeberg
issues/PRs, or to track their remote state.

Solution: add `forge.lua` with shorthand (`gh:user/repo#42`) and full
URL parsing, async metadata fetching via `curl`, label formatting,
conceal pattern generation, token resolution, and `refresh()` for
state pull (closed/merged -> done).

* feat(config): add forge config defaults and `%l` eol specifier

Problem: no configuration surface for forge link rendering, icons,
issue format, or self-hosted instances.

Solution: add `pending.ForgeConfig` class with per-forge `token`,
`icon`, `issue_format`, and `instances` fields. Add `%l` to the
default `eol_format` so forge labels render in virtual text.

* feat(parse): extract forge refs from task body

Problem: `parse.body()` had no awareness of forge link tokens, so
`gh:user/repo#42` stayed in the description instead of metadata.

Solution: add `forge_ref` field to `pending.Metadata` and extend the
right-to-left token loop in `body()` to call `forge.parse_ref()` as
the final fallback before breaking.

* feat(diff): persist forge refs in store on write

Problem: forge refs parsed from buffer lines were discarded during
diff reconciliation and never stored in the JSON.

Solution: thread `forge_ref` through `parse_buffer` entries into
`diff.apply`, storing it in `task._extra._forge_ref` for both new
and existing tasks.

* feat(views): pass forge ref and cache to line metadata

Problem: `LineMeta` had no forge fields, so `buffer.lua` could not
render forge labels or apply forge-specific highlights.

Solution: add `forge_ref` and `forge_cache` fields to `LineMeta`,
populated from `task._extra` in both `category_view` and
`priority_view`.

* feat(buffer): render forge links as concealed text with eol virt text

Problem: forge tokens were visible as raw text with no virtual text
labels, and the eol separator logic collapsed all gaps when
non-adjacent specifiers were absent.

Solution: add forge conceal syntax patterns in `setup_syntax()`, add
`PendingForge`/`PendingForgeClosed` highlight groups, handle the
`%l` specifier in `build_eol_virt()`, fix separator collapsing to
buffer one separator between present segments, and change
`concealcursor` to `nc` (reveal in visual and insert mode).

* feat(complete): add forge shorthand omnifunc completions

Problem: no completion support for `gh:`, `gl:`, or `cb:` tokens,
requiring users to type owner/repo from memory.

Solution: extend `omnifunc` to detect `gh:`/`gl:`/`cb:` prefixes and
complete with `owner/repo#` candidates from existing forge refs in
the store.

* feat: trigger forge refresh on buffer open

Problem: forge metadata was never fetched, so virt text highlights
could not reflect remote issue/PR state.

Solution: call `forge.refresh()` in `M.open()` so metadata is
fetched once per `:Pending` invocation rather than on every render.

* test(forge): add forge parsing spec

Problem: no test coverage for forge link shorthand parsing, URL
parsing, label formatting, or API URL generation.

Solution: add `spec/forge_spec.lua` covering `_parse_shorthand`,
`parse_ref` for all three forges, full URL parsing including nested
GitLab groups, `format_label`, and `_api_url`.

* docs: document forge links feature

Problem: no user-facing documentation for forge link syntax,
configuration, or behavior.

Solution: add forge links section to `README.md` and `pending.txt`
covering shorthand/URL syntax, config options, virtual text
rendering, state pull, and auth resolution.

* feat(forge): add `find_refs()` inline token scanner

Problem: forge tokens were extracted by `parse.body()` which stripped
them from the description, making editing awkward and multi-ref lines
impossible.

Solution: add `find_refs(text)` that scans a string for all forge
tokens by whitespace tokenization, returning byte offsets and parsed
refs without modifying the input. Remove unused `conceal_patterns()`.

* refactor: move forge ref detection from `parse.body()` to `diff`

Problem: `parse.body()` stripped forge tokens from the description,
losing the raw text. This made inline overlay rendering impossible
since the token no longer existed in the buffer.

Solution: remove the `forge.parse_ref()` branch from `parse.body()`
and call `forge.find_refs()` in `diff.parse_buffer()` instead. The
description now retains forge tokens verbatim; `_extra._forge_ref`
is still populated from the first matched ref.

* feat(buffer): render forge links as inline conceal overlays

Problem: forge tokens were stripped from the buffer and shown as EOL
virtual text via `%l`. The token disappeared from the editable line,
and multi-ref tasks broke.

Solution: compute `forge_spans` in `views.lua` with byte offsets for
each forge token in the rendered line. In `apply_inline_row()`, place
extmarks with `conceal=''` and `virt_text_pos='inline'` to visually
replace each raw token with its formatted label. Clear stale
`forge_spans` on dirty rows to prevent `end_col` out-of-range errors
after edits like `dd`.

* fix(config): remove `%l` from default `eol_format`

Problem: forge links are now rendered inline, making the `%l` EOL
specifier redundant in the default format.

Solution: change default `eol_format` from `'%l  %c  %r  %d'` to
`'%c  %r  %d'`. The `%l` specifier remains functional for users who
explicitly set it.

* test(forge): update specs for inline forge refs

Problem: existing tests asserted that `parse.body()` stripped forge
tokens from the description and populated `meta.forge_ref`. The
`conceal_patterns` test referenced a removed function.

Solution: update `parse.body` integration tests to assert tokens stay
in the description. Add `find_refs()` tests covering single/multiple
refs, URLs, byte offsets, and empty cases. Remove `conceal_patterns`
test. Update diff tests to assert description includes the token.

* docs: update forge links for inline overlay rendering

Problem: documentation described forge tokens as stripped from the
description and rendered via EOL `%l` specifier by default.

Solution: update forge links section to describe inline conceal
overlay rendering. Update default `eol_format` reference. Change
`issue_format` field description from "EOL label" to "inline overlay
label".

* ci: format

* refactor(forge): remove `%l` eol specifier, add `auto_close` config, fix icons

Problem: `%l` was dead code after inline overlays replaced EOL
rendering. Auto-close was always on with no opt-out. Forge icon
defaults were empty strings.

Solution: remove `%l` from the eol format parser and renderer. Add
`forge.auto_close` (default `false`) to gate state-pull. Set nerd
font icons: `` (GitHub), `` (GitLab), `` (Codeberg). Keep
conceal active in insert mode via `concealcursor = 'nic'`.

* fix(config): set correct nerd font icons for forge defaults

* refactor(forge): replace curl/token auth with CLI-native API calls

Problem: Forge metadata fetching required manual token management —
config fields, CLI token extraction, and curl with auth headers. Each
forge had a different auth path, and Codeberg had no CLI support at all.

Solution: Delete `get_token()` and `_api_url()`, replace with
`_api_args()` that builds `gh api`, `glab api`, or `tea api` arg
arrays. The CLIs handle auth internally. Add `warn_missing_cli` config
(default true) that warns once per forge per session on failure. Add
forge CLI checks to `:checkhealth`. Remove `token` from config/docs.

* refactor(forge): extract ForgeBackend class and registry

Problem: adding a new forge required touching 5 lookup tables
(`FORGE_HOSTS`, `FORGE_CLI`, `FORGE_AUTH_CMD`, `SHORTHAND_PREFIX`,
`_warned_forges`) and every branching site in `_api_args`,
`fetch_metadata`, and `parse_ref`.

Solution: introduce a `ForgeBackend` class with `parse_url`,
`api_args`, and `parse_state` methods, plus a `register()` /
`backends()` registry. New forges (Gitea, Forgejo) are a single
`register()` call via the `gitea_backend()` convenience constructor.

* ci: format
---
 doc/pending.txt        |  28 ++-
 lua/pending/config.lua |   7 +-
 lua/pending/forge.lua  | 515 ++++++++++++++++++++++++-----------------
 lua/pending/health.lua |  10 +
 spec/forge_spec.lua    | 101 ++++++--
 5 files changed, 422 insertions(+), 239 deletions(-)

diff --git a/doc/pending.txt b/doc/pending.txt
index 58ad4e0..9195c76 100644
--- a/doc/pending.txt
+++ b/doc/pending.txt
@@ -1501,20 +1501,18 @@ Configuration: ~
     vim.g.pending = {
       forge = {
         auto_close = false,
+        warn_missing_cli = true,
         github = {
-          token = nil,
           icon = '',
           issue_format = '%i %o/%r#%n',
           instances = {},
         },
         gitlab = {
-          token = nil,
           icon = '',
           issue_format = '%i %o/%r#%n',
           instances = {},
         },
         codeberg = {
-          token = nil,
           icon = '',
           issue_format = '%i %o/%r#%n',
           instances = {},
@@ -1524,27 +1522,27 @@ Configuration: ~
 <
 
 Top-level fields: ~
-    {auto_close}    (boolean, default: false) When true, tasks linked to
-                    closed/merged remote issues are automatically marked
-                    done on buffer open.
+    {auto_close}        (boolean, default: false) When true, tasks linked to
+                        closed/merged remote issues are automatically marked
+                        done on buffer open.
+    {warn_missing_cli}  (boolean, default: true) When true, warns once per
+                        forge per session if the CLI is missing or fails.
 
 Fields (per forge): ~
-    {token}         (string, optional) API token for authenticated requests.
-                    Falls back to CLI: `gh auth token` (GitHub), `glab auth
-                    token` (GitLab). Codeberg uses token only.
     {icon}          (string) Nerd font icon used in virtual text.
     {issue_format}  (string) Format string for the inline overlay label.
     {instances}     (string[]) Additional hostnames for self-hosted instances
                     (e.g. `{ 'github.company.com' }`).
 
 Authentication: ~
-Token retrieval is CLI-preferred, config fallback:
-1. GitHub: `gh auth token` stdout. Falls back to `forge.github.token`.
-2. GitLab: `glab auth token` stdout. Falls back to `forge.gitlab.token`.
-3. Codeberg: `forge.codeberg.token` only (no standard CLI).
+Forge metadata fetching uses each forge's native CLI. No tokens are
+configured in pending.nvim — authenticate once in your shell:
+1. GitHub: `gh auth login`
+2. GitLab: `glab auth login`
+3. Codeberg: `tea login add`
 
-Unauthenticated requests work for public repositories. Private repositories
-require a token.
+Public repositories work without authentication. Private repositories
+require a logged-in CLI session.
 
 Metadata fetching: ~
 On buffer open, tasks with a `_forge_ref` whose cached metadata is older
diff --git a/lua/pending/config.lua b/lua/pending/config.lua
index 4c35348..b1ab639 100644
--- a/lua/pending/config.lua
+++ b/lua/pending/config.lua
@@ -34,16 +34,14 @@
 ---@field region? string
 
 ---@class pending.ForgeInstanceConfig
----@field token? string
 ---@field icon? string
 ---@field issue_format? string
 ---@field instances? string[]
 
 ---@class pending.ForgeConfig
 ---@field auto_close? boolean
----@field github? pending.ForgeInstanceConfig
----@field gitlab? pending.ForgeInstanceConfig
----@field codeberg? pending.ForgeInstanceConfig
+---@field warn_missing_cli? boolean
+---@field [string] pending.ForgeInstanceConfig
 
 ---@class pending.SyncConfig
 ---@field remote_delete? boolean
@@ -156,6 +154,7 @@ local defaults = {
   sync = {},
   forge = {
     auto_close = false,
+    warn_missing_cli = true,
     github = {
       icon = '',
       issue_format = '%i %o/%r#%n',
diff --git a/lua/pending/forge.lua b/lua/pending/forge.lua
index c7724f8..9b32655 100644
--- a/lua/pending/forge.lua
+++ b/lua/pending/forge.lua
@@ -2,7 +2,7 @@ local config = require('pending.config')
 local log = require('pending.log')
 
 ---@class pending.ForgeRef
----@field forge 'github'|'gitlab'|'codeberg'
+---@field forge string
 ---@field owner string
 ---@field repo string
 ---@field type 'issue'|'pull_request'|'merge_request'
@@ -15,29 +15,66 @@ local log = require('pending.log')
 ---@field labels? string[]
 ---@field fetched_at string
 
+---@class pending.ForgeBackend
+---@field name string
+---@field shorthand string
+---@field default_host string
+---@field cli string
+---@field auth_cmd string
+---@field default_icon string
+---@field default_issue_format string
+---@field _warned boolean
+---@field parse_url fun(self: pending.ForgeBackend, url: string): pending.ForgeRef?
+---@field api_args fun(self: pending.ForgeBackend, ref: pending.ForgeRef): string[]
+---@field parse_state fun(self: pending.ForgeBackend, decoded: table): 'open'|'closed'|'merged'
+
 ---@class pending.forge
 local M = {}
 
----@type table<string, string>
-local FORGE_HOSTS = {
-  ['github.com'] = 'github',
-  ['gitlab.com'] = 'gitlab',
-  ['codeberg.org'] = 'codeberg',
-}
+---@type pending.ForgeBackend[]
+local _backends = {}
 
----@type table<string, string>
-local FORGE_API_BASE = {
-  github = 'https://api.github.com',
-  gitlab = 'https://gitlab.com',
-  codeberg = 'https://codeberg.org',
-}
+---@type table<string, pending.ForgeBackend>
+local _by_name = {}
 
----@type table<string, string>
-local SHORTHAND_PREFIX = {
-  gh = 'github',
-  gl = 'gitlab',
-  cb = 'codeberg',
-}
+---@type table<string, pending.ForgeBackend>
+local _by_shorthand = {}
+
+---@type table<string, pending.ForgeBackend>
+local _by_host = {}
+
+---@type boolean
+local _instances_resolved = false
+
+---@param backend pending.ForgeBackend
+---@return nil
+function M.register(backend)
+  backend._warned = false
+  table.insert(_backends, backend)
+  _by_name[backend.name] = backend
+  _by_shorthand[backend.shorthand] = backend
+  _by_host[backend.default_host] = backend
+  _instances_resolved = false
+end
+
+---@return pending.ForgeBackend[]
+function M.backends()
+  return _backends
+end
+
+local function _ensure_instances()
+  if _instances_resolved then
+    return
+  end
+  _instances_resolved = true
+  local cfg = config.get().forge or {}
+  for _, backend in ipairs(_backends) do
+    local forge_cfg = cfg[backend.name] or {}
+    for _, inst in ipairs(forge_cfg.instances or {}) do
+      _by_host[inst] = backend
+    end
+  end
+end
 
 ---@param token string
 ---@return pending.ForgeRef?
@@ -46,8 +83,8 @@ function M._parse_shorthand(token)
   if not prefix then
     return nil
   end
-  local forge = SHORTHAND_PREFIX[prefix]
-  if not forge then
+  local backend = _by_shorthand[prefix]
+  if not backend then
     return nil
   end
   local owner, repo, number = rest:match('^([%w%.%-_]+)/([%w%.%-_]+)#(%d+)$')
@@ -55,12 +92,9 @@ function M._parse_shorthand(token)
     return nil
   end
   local num = tonumber(number) --[[@as integer]]
-  local host = forge == 'github' and 'github.com'
-    or forge == 'gitlab' and 'gitlab.com'
-    or 'codeberg.org'
-  local url = 'https://' .. host .. '/' .. owner .. '/' .. repo .. '/issues/' .. num
+  local url = 'https://' .. backend.default_host .. '/' .. owner .. '/' .. repo .. '/issues/' .. num
   return {
-    forge = forge,
+    forge = backend.name,
     owner = owner,
     repo = repo,
     type = 'issue',
@@ -72,115 +106,31 @@ end
 ---@param url string
 ---@return pending.ForgeRef?
 function M._parse_github_url(url)
-  local host, owner, repo, kind, number =
-    url:match('^https?://([^/]+)/([%w%.%-_]+)/([%w%.%-_]+)/(%a+)/(%d+)$')
-  if not host then
+  local backend = _by_name['github']
+  if not backend then
     return nil
   end
-  if kind ~= 'issues' and kind ~= 'pull' then
-    return nil
-  end
-  local forge_name = FORGE_HOSTS[host]
-  if not forge_name then
-    local cfg = config.get().forge or {}
-    local gh_cfg = cfg.github or {}
-    for _, inst in ipairs(gh_cfg.instances or {}) do
-      if host == inst then
-        forge_name = 'github'
-        break
-      end
-    end
-  end
-  if forge_name ~= 'github' then
-    return nil
-  end
-  local num = tonumber(number) --[[@as integer]]
-  local ref_type = kind == 'pull' and 'pull_request' or 'issue'
-  return {
-    forge = 'github',
-    owner = owner,
-    repo = repo,
-    type = ref_type,
-    number = num,
-    url = url,
-  }
+  return backend:parse_url(url)
 end
 
 ---@param url string
 ---@return pending.ForgeRef?
 function M._parse_gitlab_url(url)
-  local host, path, kind, number = url:match('^https?://([^/]+)/(.+)/%-/([%w_]+)/(%d+)$')
-  if not host then
+  local backend = _by_name['gitlab']
+  if not backend then
     return nil
   end
-  if kind ~= 'issues' and kind ~= 'merge_requests' then
-    return nil
-  end
-  local forge_name = FORGE_HOSTS[host]
-  if not forge_name then
-    local cfg = config.get().forge or {}
-    local gl_cfg = cfg.gitlab or {}
-    for _, inst in ipairs(gl_cfg.instances or {}) do
-      if host == inst then
-        forge_name = 'gitlab'
-        break
-      end
-    end
-  end
-  if forge_name ~= 'gitlab' then
-    return nil
-  end
-  local owner, repo = path:match('^(.+)/([^/]+)$')
-  if not owner then
-    return nil
-  end
-  local num = tonumber(number) --[[@as integer]]
-  local ref_type = kind == 'merge_requests' and 'merge_request' or 'issue'
-  return {
-    forge = 'gitlab',
-    owner = owner,
-    repo = repo,
-    type = ref_type,
-    number = num,
-    url = url,
-  }
+  return backend:parse_url(url)
 end
 
 ---@param url string
 ---@return pending.ForgeRef?
 function M._parse_codeberg_url(url)
-  local host, owner, repo, kind, number =
-    url:match('^https?://([^/]+)/([%w%.%-_]+)/([%w%.%-_]+)/(%a+)/(%d+)$')
-  if not host then
+  local backend = _by_name['codeberg']
+  if not backend then
     return nil
   end
-  if kind ~= 'issues' and kind ~= 'pulls' then
-    return nil
-  end
-  local forge_name = FORGE_HOSTS[host]
-  if not forge_name then
-    local cfg = config.get().forge or {}
-    local cb_cfg = cfg.codeberg or {}
-    for _, inst in ipairs(cb_cfg.instances or {}) do
-      if host == inst then
-        forge_name = 'codeberg'
-        break
-      end
-    end
-  end
-  if forge_name ~= 'codeberg' then
-    return nil
-  end
-  local num = tonumber(number) --[[@as integer]]
-  local ref_type = kind == 'pulls' and 'pull_request' or 'issue'
-  return {
-    forge = 'codeberg',
-    owner = owner,
-    repo = repo,
-    type = ref_type,
-    number = num,
-    url = url,
-  }
+  return backend:parse_url(url)
 end
 
 ---@param token string
@@ -193,7 +143,16 @@ function M.parse_ref(token)
   if not token:match('^https?://') then
     return nil
   end
-  return M._parse_github_url(token) or M._parse_gitlab_url(token) or M._parse_codeberg_url(token)
+  _ensure_instances()
+  local host = token:match('^https?://([^/]+)')
+  if not host then
+    return nil
+  end
+  local backend = _by_host[host]
+  if not backend then
+    return nil
+  end
+  return backend:parse_url(token)
 end
 
 ---@class pending.ForgeSpan
@@ -230,38 +189,13 @@ function M.find_refs(text)
 end
 
 ---@param ref pending.ForgeRef
----@return string
-function M._api_url(ref)
-  if ref.forge == 'github' then
-    return FORGE_API_BASE.github
-      .. '/repos/'
-      .. ref.owner
-      .. '/'
-      .. ref.repo
-      .. '/issues/'
-      .. ref.number
-  elseif ref.forge == 'gitlab' then
-    local encoded = (ref.owner .. '/' .. ref.repo):gsub('/', '%%2F')
-    local endpoint = ref.type == 'merge_request' and 'merge_requests' or 'issues'
-    return FORGE_API_BASE.gitlab
-      .. '/api/v4/projects/'
-      .. encoded
-      .. '/'
-      .. endpoint
-      .. '/'
-      .. ref.number
-  else
-    local endpoint = ref.type == 'pull_request' and 'pulls' or 'issues'
-    return FORGE_API_BASE.codeberg
-      .. '/api/v1/repos/'
-      .. ref.owner
-      .. '/'
-      .. ref.repo
-      .. '/'
-      .. endpoint
-      .. '/'
-      .. ref.number
+---@return string[]
+function M._api_args(ref)
+  local backend = _by_name[ref.forge]
+  if not backend then
+    return {}
   end
+  return backend:api_args(ref)
 end
 
 ---@param ref pending.ForgeRef
@@ -271,8 +205,11 @@ end
 function M.format_label(ref, cache)
   local cfg = config.get().forge or {}
   local forge_cfg = cfg[ref.forge] or {}
-  local fmt = forge_cfg.issue_format or '%i %o/%r#%n'
-  local icon = forge_cfg.icon or ''
+  local backend = _by_name[ref.forge]
+  local default_icon = backend and backend.default_icon or ''
+  local default_fmt = backend and backend.default_issue_format or '%i %o/%r#%n'
+  local fmt = forge_cfg.issue_format or default_fmt
+  local icon = forge_cfg.icon or default_icon
   local text = fmt
     :gsub('%%i', icon)
     :gsub('%%o', ref.owner)
@@ -287,49 +224,22 @@ function M.format_label(ref, cache)
   return text, hl
 end
 
----@param forge string
----@return string?
-function M.get_token(forge)
-  local cfg = config.get().forge or {}
-  local forge_cfg = cfg[forge] or {}
-  if forge_cfg.token then
-    return forge_cfg.token
-  end
-  if forge == 'github' then
-    local result = vim.fn.system({ 'gh', 'auth', 'token' })
-    if vim.v.shell_error == 0 and result and result ~= '' then
-      return vim.trim(result)
-    end
-  elseif forge == 'gitlab' then
-    local result = vim.fn.system({ 'glab', 'auth', 'token' })
-    if vim.v.shell_error == 0 and result and result ~= '' then
-      return vim.trim(result)
-    end
-  end
-  return nil
-end
-
 ---@param ref pending.ForgeRef
 ---@param callback fun(cache: pending.ForgeCache?)
 function M.fetch_metadata(ref, callback)
-  local token = M.get_token(ref.forge)
-  local url = M._api_url(ref)
-  local args = { 'curl', '-s', '-L' }
-  if token then
-    table.insert(args, '-H')
-    if ref.forge == 'gitlab' then
-      table.insert(args, 'PRIVATE-TOKEN: ' .. token)
-    else
-      table.insert(args, 'Authorization: Bearer ' .. token)
-    end
-  end
-  table.insert(args, '-H')
-  table.insert(args, 'Accept: application/json')
-  table.insert(args, url)
+  local args = M._api_args(ref)
 
   vim.system(args, { text = true }, function(result)
     if result.code ~= 0 or not result.stdout or result.stdout == '' then
       vim.schedule(function()
+        local forge_cfg = config.get().forge or {}
+        local backend = _by_name[ref.forge]
+        if backend and forge_cfg.warn_missing_cli ~= false and not backend._warned then
+          backend._warned = true
+          log.warn(
+            ('%s not found or not authenticated — run `%s`'):format(backend.cli, backend.auth_cmd)
+          )
+        end
         callback(nil)
       end)
       return
@@ -341,24 +251,8 @@ function M.fetch_metadata(ref, callback)
       end)
       return
     end
-    local state = 'open'
-    if ref.forge == 'github' then
-      if decoded.pull_request and decoded.pull_request.merged_at then
-        state = 'merged'
-      elseif decoded.state == 'closed' then
-        state = 'closed'
-      end
-    elseif ref.forge == 'gitlab' then
-      if decoded.state == 'merged' then
-        state = 'merged'
-      elseif decoded.state == 'closed' then
-        state = 'closed'
-      end
-    else
-      if decoded.state == 'closed' then
-        state = 'closed'
-      end
-    end
+    local backend = _by_name[ref.forge]
+    local state = backend and backend:parse_state(decoded) or 'open'
     local labels = {}
     if decoded.labels then
       for _, label in ipairs(decoded.labels) do
@@ -434,4 +328,211 @@ function M.refresh(s)
   end
 end
 
+---@param opts {name: string, shorthand: string, default_host: string, cli?: string, auth_cmd?: string, default_icon?: string, default_issue_format?: string}
+---@return pending.ForgeBackend
+function M.gitea_backend(opts)
+  return {
+    name = opts.name,
+    shorthand = opts.shorthand,
+    default_host = opts.default_host,
+    cli = opts.cli or 'tea',
+    auth_cmd = opts.auth_cmd or 'tea login add',
+    default_icon = opts.default_icon or '',
+    default_issue_format = opts.default_issue_format or '%i %o/%r#%n',
+    _warned = false,
+    parse_url = function(self, url)
+      _ensure_instances()
+      local host, owner, repo, kind, number =
+        url:match('^https?://([^/]+)/([%w%.%-_]+)/([%w%.%-_]+)/(%a+)/(%d+)$')
+      if not host then
+        return nil
+      end
+      if kind ~= 'issues' and kind ~= 'pulls' then
+        return nil
+      end
+      if _by_host[host] ~= self then
+        return nil
+      end
+      local num = tonumber(number) --[[@as integer]]
+      local ref_type = kind == 'pulls' and 'pull_request' or 'issue'
+      return {
+        forge = self.name,
+        owner = owner,
+        repo = repo,
+        type = ref_type,
+        number = num,
+        url = url,
+      }
+    end,
+    api_args = function(self, ref)
+      local endpoint = ref.type == 'pull_request' and 'pulls' or 'issues'
+      return {
+        self.cli,
+        'api',
+        '/repos/' .. ref.owner .. '/' .. ref.repo .. '/' .. endpoint .. '/' .. ref.number,
+      }
+    end,
+    parse_state = function(_, decoded)
+      if decoded.state == 'closed' then
+        return 'closed'
+      end
+      return 'open'
+    end,
+  }
+end
+
+M.register({
+  name = 'github',
+  shorthand = 'gh',
+  default_host = 'github.com',
+  cli = 'gh',
+  auth_cmd = 'gh auth login',
+  default_icon = '',
+  default_issue_format = '%i %o/%r#%n',
+  _warned = false,
+  parse_url = function(self, url)
+    _ensure_instances()
+    local host, owner, repo, kind, number =
+      url:match('^https?://([^/]+)/([%w%.%-_]+)/([%w%.%-_]+)/(%a+)/(%d+)$')
+    if not host then
+      return nil
+    end
+    if kind ~= 'issues' and kind ~= 'pull' then
+      return nil
+    end
+    if _by_host[host] ~= self then
+      return nil
+    end
+    local num = tonumber(number) --[[@as integer]]
+    local ref_type = kind == 'pull' and 'pull_request' or 'issue'
+    return {
+      forge = 'github',
+      owner = owner,
+      repo = repo,
+      type = ref_type,
+      number = num,
+      url = url,
+    }
+  end,
+  api_args = function(_, ref)
+    return {
+      'gh',
+      'api',
+      '/repos/' .. ref.owner .. '/' .. ref.repo .. '/issues/' .. ref.number,
+    }
+  end,
+  parse_state = function(_, decoded)
+    if decoded.pull_request and decoded.pull_request.merged_at then
+      return 'merged'
+    elseif decoded.state == 'closed' then
+      return 'closed'
+    end
+    return 'open'
+  end,
+})
+
+M.register({
+  name = 'gitlab',
+  shorthand = 'gl',
+  default_host = 'gitlab.com',
+  cli = 'glab',
+  auth_cmd = 'glab auth login',
+  default_icon = '',
+  default_issue_format = '%i %o/%r#%n',
+  _warned = false,
+  parse_url = function(self, url)
+    _ensure_instances()
+    local host, path, kind, number = url:match('^https?://([^/]+)/(.+)/%-/([%w_]+)/(%d+)$')
+    if not host then
+      return nil
+    end
+    if kind ~= 'issues' and kind ~= 'merge_requests' then
+      return nil
+    end
+    if _by_host[host] ~= self then
+      return nil
+    end
+    local owner, repo = path:match('^(.+)/([^/]+)$')
+    if not owner then
+      return nil
+    end
+    local num = tonumber(number) --[[@as integer]]
+    local ref_type = kind == 'merge_requests' and 'merge_request' or 'issue'
+    return {
+      forge = 'gitlab',
+      owner = owner,
+      repo = repo,
+      type = ref_type,
+      number = num,
+      url = url,
+    }
+  end,
+  api_args = function(_, ref)
+    local encoded = (ref.owner .. '/' .. ref.repo):gsub('/', '%%2F')
+    local endpoint = ref.type == 'merge_request' and 'merge_requests' or 'issues'
+    return {
+      'glab',
+      'api',
+      '/projects/' .. encoded .. '/' .. endpoint .. '/' .. ref.number,
+    }
+  end,
+  parse_state = function(_, decoded)
+    if decoded.state == 'merged' then
+      return 'merged'
+    elseif decoded.state == 'closed' then
+      return 'closed'
+    end
+    return 'open'
+  end,
+})
+
+M.register({
+  name = 'codeberg',
+  shorthand = 'cb',
+  default_host = 'codeberg.org',
+  cli = 'tea',
+  auth_cmd = 'tea login add',
+  default_icon = '',
+  default_issue_format = '%i %o/%r#%n',
+  _warned = false,
+  parse_url = function(self, url)
+    _ensure_instances()
+    local host, owner, repo, kind, number =
+      url:match('^https?://([^/]+)/([%w%.%-_]+)/([%w%.%-_]+)/(%a+)/(%d+)$')
+    if not host then
+      return nil
+    end
+    if kind ~= 'issues' and kind ~= 'pulls' then
+      return nil
+    end
+    if _by_host[host] ~= self then
+      return nil
+    end
+    local num = tonumber(number) --[[@as integer]]
+    local ref_type = kind == 'pulls' and 'pull_request' or 'issue'
+    return {
+      forge = 'codeberg',
+      owner = owner,
+      repo = repo,
+      type = ref_type,
+      number = num,
+      url = url,
+    }
+  end,
+  api_args = function(_, ref)
+    local endpoint = ref.type == 'pull_request' and 'pulls' or 'issues'
+    return {
+      'tea',
+      'api',
+      '/repos/' .. ref.owner .. '/' .. ref.repo .. '/' .. endpoint .. '/' .. ref.number,
+    }
+  end,
+  parse_state = function(_, decoded)
+    if decoded.state == 'closed' then
+      return 'closed'
+    end
+    return 'open'
+  end,
+})
+
 return M
diff --git a/lua/pending/health.lua b/lua/pending/health.lua
index f819269..457eb67 100644
--- a/lua/pending/health.lua
+++ b/lua/pending/health.lua
@@ -46,6 +46,16 @@ function M.check()
     end
   end
 
+  vim.health.start('pending.nvim: forge')
+  local forge = require('pending.forge')
+  for _, backend in ipairs(forge.backends()) do
+    if vim.fn.executable(backend.cli) == 1 then
+      vim.health.ok(('%s found'):format(backend.cli))
+    else
+      vim.health.warn(('%s not found — run `%s`'):format(backend.cli, backend.auth_cmd))
+    end
+  end
+
   local sync_paths = vim.fn.globpath(vim.o.runtimepath, 'lua/pending/sync/*.lua', false, true)
   if #sync_paths == 0 then
     vim.health.info('No sync backends found')
diff --git a/spec/forge_spec.lua b/spec/forge_spec.lua
index 3d17374..fac8021 100644
--- a/spec/forge_spec.lua
+++ b/spec/forge_spec.lua
@@ -186,9 +186,9 @@ describe('forge', function()
     end)
   end)
 
-  describe('_api_url', function()
-    it('builds GitHub API URL', function()
-      local url = forge._api_url({
+  describe('_api_args', function()
+    it('builds GitHub CLI args', function()
+      local args = forge._api_args({
         forge = 'github',
         owner = 'user',
         repo = 'repo',
@@ -196,11 +196,11 @@ describe('forge', function()
         number = 42,
         url = '',
       })
-      assert.equals('https://api.github.com/repos/user/repo/issues/42', url)
+      assert.same({ 'gh', 'api', '/repos/user/repo/issues/42' }, args)
     end)
 
-    it('builds GitLab API URL for issue', function()
-      local url = forge._api_url({
+    it('builds GitLab CLI args for issue', function()
+      local args = forge._api_args({
         forge = 'gitlab',
         owner = 'group',
         repo = 'project',
@@ -208,11 +208,11 @@ describe('forge', function()
         number = 15,
         url = '',
       })
-      assert.equals('https://gitlab.com/api/v4/projects/group%2Fproject/issues/15', url)
+      assert.same({ 'glab', 'api', '/projects/group%2Fproject/issues/15' }, args)
     end)
 
-    it('builds GitLab API URL for merge request', function()
-      local url = forge._api_url({
+    it('builds GitLab CLI args for merge request', function()
+      local args = forge._api_args({
         forge = 'gitlab',
         owner = 'group',
         repo = 'project',
@@ -220,11 +220,11 @@ describe('forge', function()
         number = 5,
         url = '',
       })
-      assert.equals('https://gitlab.com/api/v4/projects/group%2Fproject/merge_requests/5', url)
+      assert.same({ 'glab', 'api', '/projects/group%2Fproject/merge_requests/5' }, args)
     end)
 
-    it('builds Codeberg API URL', function()
-      local url = forge._api_url({
+    it('builds Codeberg CLI args', function()
+      local args = forge._api_args({
         forge = 'codeberg',
         owner = 'user',
         repo = 'repo',
@@ -232,7 +232,7 @@ describe('forge', function()
         number = 3,
         url = '',
       })
-      assert.equals('https://codeberg.org/api/v1/repos/user/repo/issues/3', url)
+      assert.same({ 'tea', 'api', '/repos/user/repo/issues/3' }, args)
     end)
   end)
 
@@ -316,6 +316,81 @@ describe('forge parse.body integration', function()
   end)
 end)
 
+describe('forge registry', function()
+  it('backends() returns all registered backends', function()
+    local backends = forge.backends()
+    assert.is_true(#backends >= 3)
+    local names = {}
+    for _, b in ipairs(backends) do
+      names[b.name] = true
+    end
+    assert.is_true(names['github'])
+    assert.is_true(names['gitlab'])
+    assert.is_true(names['codeberg'])
+  end)
+
+  it('register() with custom backend resolves URLs', function()
+    local custom = forge.gitea_backend({
+      name = 'mygitea',
+      shorthand = 'mg',
+      default_host = 'gitea.example.com',
+    })
+    forge.register(custom)
+
+    local ref = forge.parse_ref('https://gitea.example.com/alice/proj/issues/7')
+    assert.is_not_nil(ref)
+    assert.equals('mygitea', ref.forge)
+    assert.equals('alice', ref.owner)
+    assert.equals('proj', ref.repo)
+    assert.equals('issue', ref.type)
+    assert.equals(7, ref.number)
+  end)
+
+  it('register() with custom shorthand resolves', function()
+    local ref = forge._parse_shorthand('mg:alice/proj#7')
+    assert.is_not_nil(ref)
+    assert.equals('mygitea', ref.forge)
+    assert.equals('alice', ref.owner)
+    assert.equals('proj', ref.repo)
+    assert.equals(7, ref.number)
+  end)
+
+  it('_api_args dispatches to custom backend', function()
+    local args = forge._api_args({
+      forge = 'mygitea',
+      owner = 'alice',
+      repo = 'proj',
+      type = 'issue',
+      number = 7,
+      url = '',
+    })
+    assert.same({ 'tea', 'api', '/repos/alice/proj/issues/7' }, args)
+  end)
+
+  it('gitea_backend() creates a working backend', function()
+    local b = forge.gitea_backend({
+      name = 'forgejo',
+      shorthand = 'fj',
+      default_host = 'forgejo.example.com',
+      cli = 'forgejo-cli',
+      auth_cmd = 'forgejo-cli login',
+    })
+    assert.equals('forgejo', b.name)
+    assert.equals('fj', b.shorthand)
+    assert.equals('forgejo-cli', b.cli)
+
+    local ref = b:parse_url('https://forgejo.example.com/bob/repo/pulls/3')
+    assert.is_nil(ref)
+
+    forge.register(b)
+    ref = b:parse_url('https://forgejo.example.com/bob/repo/pulls/3')
+    assert.is_not_nil(ref)
+    assert.equals('forgejo', ref.forge)
+    assert.equals('pull_request', ref.type)
+    assert.equals(3, ref.number)
+  end)
+end)
+
 describe('forge diff integration', function()
   local store = require('pending.store')
   local diff = require('pending.diff')