refactor(forge): simplify auth gating and rename gitea_backend

Problem: forge auth/warning logic was scattered through
`fetch_metadata` — per-API-call auth status checks, `_warned` flags,
and `warn_missing_cli` conditionals on every fetch.

Solution: replace `_warned` with `_auth` (cached per session), add
`is_configured()` to skip unconfigured forges entirely, extract
`check_auth()` for one-time auth verification, and strip
`fetch_metadata` to a pure API caller returning `ForgeFetchError`.
Gate `refresh` and new `validate_refs` with both checks. Rename
`gitea_backend` to `gitea_forge`.

doc/pending.txt

@@ -1524,7 +1524,9 @@ Configuration: ~
 Top-level fields: ~
     {close}             (boolean, default: false) When true, tasks linked to
                         closed/merged remote issues are automatically marked
-                        done on buffer open.
+                        done on buffer open. Only forges with an explicit
+                        per-forge key (e.g. `github = {}`) are checked;
+                        unconfigured forges are skipped entirely.
     {warn_missing_cli}  (boolean, default: true) When true, warns once per
                         forge per session if the CLI is missing or fails.
 

lua/pending/forge.lua

@@ -15,6 +15,9 @@ local log = require('pending.log')
 ---@field labels? string[]
 ---@field fetched_at string
 
+---@class pending.ForgeFetchError
+---@field kind 'not_found'|'auth'|'network'
+
 ---@class pending.ForgeBackend
 ---@field name string
 ---@field shorthand string
@@ -24,7 +27,7 @@ local log = require('pending.log')
 ---@field auth_status_args string[]
 ---@field default_icon string
 ---@field default_issue_format string
----@field _warned boolean
+---@field _auth 'unknown'|'ok'|'failed'
 ---@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'
@@ -50,7 +53,7 @@ local _instances_resolved = false
 ---@param backend pending.ForgeBackend
 ---@return nil
 function M.register(backend)
-  backend._warned = false
+  backend._auth = 'unknown'
   table.insert(_backends, backend)
   _by_name[backend.name] = backend
   _by_shorthand[backend.shorthand] = backend
@@ -63,6 +66,53 @@ function M.backends()
   return _backends
 end
 
+---@param forge_name string
+---@return boolean
+function M.is_configured(forge_name)
+  local raw = vim.g.pending
+  if not raw or not raw.forge then
+    return false
+  end
+  return raw.forge[forge_name] ~= nil
+end
+
+---@param backend pending.ForgeBackend
+---@param callback fun(ok: boolean)
+function M.check_auth(backend, callback)
+  if backend._auth == 'ok' then
+    callback(true)
+    return
+  end
+  if backend._auth == 'failed' then
+    callback(false)
+    return
+  end
+  if vim.fn.executable(backend.cli) == 0 then
+    backend._auth = 'failed'
+    local forge_cfg = config.get().forge or {}
+    if forge_cfg.warn_missing_cli ~= false then
+      log.warn(('%s not found — run `%s`'):format(backend.cli, backend.auth_cmd))
+    end
+    callback(false)
+    return
+  end
+  vim.system(backend.auth_status_args, { text = true }, function(result)
+    vim.schedule(function()
+      if result.code == 0 then
+        backend._auth = 'ok'
+        callback(true)
+      else
+        backend._auth = 'failed'
+        local forge_cfg = config.get().forge or {}
+        if forge_cfg.warn_missing_cli ~= false then
+          log.warn(('%s not authenticated — run `%s`'):format(backend.cli, backend.auth_cmd))
+        end
+        callback(false)
+      end
+    end)
+  end)
+end
+
 function M._reset_instances()
   _instances_resolved = false
   _by_shorthand = {}
@@ -244,35 +294,27 @@ function M.format_label(ref, cache)
 end
 
 ---@param ref pending.ForgeRef
----@param callback fun(cache: pending.ForgeCache?)
+---@param callback fun(cache: pending.ForgeCache?, err: pending.ForgeFetchError?)
 function M.fetch_metadata(ref, callback)
   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
-      local forge_cfg = config.get().forge or {}
+      local kind = 'network'
-      local backend = _by_name[ref.forge]
+      local stderr = result.stderr or ''
-      if backend and forge_cfg.warn_missing_cli ~= false and not backend._warned then
+      if stderr:find('404') or stderr:find('Not Found') then
-        backend._warned = true
+        kind = 'not_found'
-        vim.system(backend.auth_status_args, { text = true }, function(auth_result)
+      elseif stderr:find('401') or stderr:find('403') or stderr:find('auth') then
-          vim.schedule(function()
+        kind = 'auth'
-            if auth_result.code ~= 0 then
-              log.warn(('%s not authenticated — run `%s`'):format(backend.cli, backend.auth_cmd))
       end
-            callback(nil)
-          end)
-        end)
-      else
       vim.schedule(function()
-          callback(nil)
+        callback(nil, { kind = kind })
       end)
-      end
       return
     end
     local ok, decoded = pcall(vim.json.decode, result.stdout)
     if not ok or not decoded then
       vim.schedule(function()
-        callback(nil)
+        callback(nil, { kind = 'network' })
       end)
       return
     end
@@ -307,21 +349,36 @@ function M.refresh(s)
     return
   end
   local tasks = s:tasks()
-  local pending_fetches = 0
+  local by_forge = {} ---@type table<string, pending.Task[]>
-  local any_changed = false
-  local any_fetched = false
   for _, task in ipairs(tasks) do
     if task.status ~= 'deleted' and task._extra and task._extra._forge_ref then
+      local fname = task._extra._forge_ref.forge
+      if not by_forge[fname] then
+        by_forge[fname] = {}
+      end
+      table.insert(by_forge[fname], task)
+    end
+  end
+  local any_work = false
+  for fname, forge_tasks in pairs(by_forge) do
+    if M.is_configured(fname) and _by_name[fname] then
+      any_work = true
+      M.check_auth(_by_name[fname], function(authed)
+        if not authed then
+          return
+        end
+        local remaining = #forge_tasks
+        local any_changed = false
+        local any_fetched = false
+        for _, task in ipairs(forge_tasks) do
           local ref = task._extra._forge_ref --[[@as pending.ForgeRef]]
-      pending_fetches = pending_fetches + 1
           M.fetch_metadata(ref, function(cache)
-        pending_fetches = pending_fetches - 1
+            remaining = remaining - 1
             if cache then
               task._extra._forge_cache = cache
               any_fetched = true
               if
-            forge_cfg.close
+                (cache.state == 'closed' or cache.state == 'merged')
-            and (cache.state == 'closed' or cache.state == 'merged')
                 and (task.status == 'pending' or task.status == 'wip' or task.status == 'blocked')
               then
                 task.status = 'done'
@@ -335,7 +392,7 @@ function M.refresh(s)
                 fetched_at = os.date('!%Y-%m-%dT%H:%M:%SZ') --[[@as string]],
               }
             end
-        if pending_fetches == 0 then
+            if remaining == 0 then
               if any_changed then
                 s:save()
               end
@@ -350,15 +407,47 @@ function M.refresh(s)
             end
           end)
         end
+      end)
     end
-  if pending_fetches == 0 then
+  end
+  if not any_work then
     log.info('No linked tasks to refresh.')
   end
 end
 
+---@param refs pending.ForgeRef[]
+function M.validate_refs(refs)
+  local by_forge = {} ---@type table<string, pending.ForgeRef[]>
+  for _, ref in ipairs(refs) do
+    local fname = ref.forge
+    if not by_forge[fname] then
+      by_forge[fname] = {}
+    end
+    table.insert(by_forge[fname], ref)
+  end
+  for fname, forge_refs in pairs(by_forge) do
+    if not M.is_configured(fname) or not _by_name[fname] then
+      goto continue
+    end
+    M.check_auth(_by_name[fname], function(authed)
+      if not authed then
+        return
+      end
+      for _, ref in ipairs(forge_refs) do
+        M.fetch_metadata(ref, function(_, err)
+          if err and err.kind == 'not_found' then
+            log.warn(('%s:%s/%s#%d not found'):format(ref.forge, ref.owner, ref.repo, ref.number))
+          end
+        end)
+      end
+    end)
+    ::continue::
+  end
+end
+
 ---@param opts {name: string, shorthand: string, default_host: string, cli?: string, auth_cmd?: string, auth_status_args?: string[], default_icon?: string, default_issue_format?: string}
 ---@return pending.ForgeBackend
-function M.gitea_backend(opts)
+function M.gitea_forge(opts)
   return {
     name = opts.name,
     shorthand = opts.shorthand,
@@ -368,7 +457,6 @@ function M.gitea_backend(opts)
     auth_status_args = opts.auth_status_args or { opts.cli or 'tea', 'login', 'list' },
     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 =
@@ -419,7 +507,6 @@ M.register({
   auth_status_args = { 'gh', 'auth', 'status' },
   default_icon = '',
   default_issue_format = '%i %o/%r#%n',
-  _warned = false,
   parse_url = function(self, url)
     _ensure_instances()
     local host, owner, repo, kind, number =
@@ -470,7 +557,6 @@ M.register({
   auth_status_args = { 'glab', 'auth', 'status' },
   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+)$')
@@ -526,7 +612,6 @@ M.register({
   auth_status_args = { 'tea', 'login', 'list' },
   default_icon = '',
   default_issue_format = '%i %o/%r#%n',
-  _warned = false,
   parse_url = function(self, url)
     _ensure_instances()
     local host, owner, repo, kind, number =

lua/pending/health.lua

@@ -49,7 +49,9 @@ function M.check()
   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
+    if not forge.is_configured(backend.name) then
+      vim.health.info(('%s: not configured (skipped)'):format(backend.name))
+    elseif 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))

spec/forge_spec.lua

@@ -330,7 +330,7 @@ describe('forge registry', function()
   end)
 
   it('register() with custom backend resolves URLs', function()
-    local custom = forge.gitea_backend({
+    local custom = forge.gitea_forge({
       name = 'mygitea',
       shorthand = 'mg',
       default_host = 'gitea.example.com',
@@ -367,8 +367,8 @@ describe('forge registry', function()
     assert.same({ 'tea', 'api', '/repos/alice/proj/issues/7' }, args)
   end)
 
-  it('gitea_backend() creates a working backend', function()
+  it('gitea_forge() creates a working backend', function()
-    local b = forge.gitea_backend({
+    local b = forge.gitea_forge({
       name = 'forgejo',
       shorthand = 'fj',
       default_host = 'forgejo.example.com',
@@ -396,7 +396,7 @@ describe('custom forge prefixes', function()
   local complete = require('pending.complete')
 
   it('parses custom-length shorthand (3+ chars)', function()
-    local custom = forge.gitea_backend({
+    local custom = forge.gitea_forge({
       name = 'customforge',
       shorthand = 'cgf',
       default_host = 'custom.example.com',
@@ -458,6 +458,32 @@ describe('custom forge prefixes', function()
   end)
 end)
 
+describe('is_configured', function()
+  it('returns false when vim.g.pending is nil', function()
+    vim.g.pending = nil
+    assert.is_false(forge.is_configured('github'))
+  end)
+
+  it('returns false when forge key is absent', function()
+    vim.g.pending = { forge = { close = true } }
+    assert.is_false(forge.is_configured('github'))
+    vim.g.pending = nil
+  end)
+
+  it('returns true when forge key is present', function()
+    vim.g.pending = { forge = { github = {} } }
+    assert.is_true(forge.is_configured('github'))
+    assert.is_false(forge.is_configured('gitlab'))
+    vim.g.pending = nil
+  end)
+
+  it('returns true for non-empty forge config', function()
+    vim.g.pending = { forge = { gitlab = { icon = '' } } }
+    assert.is_true(forge.is_configured('gitlab'))
+    vim.g.pending = nil
+  end)
+end)
+
 describe('forge diff integration', function()
   local store = require('pending.store')
   local diff = require('pending.diff')