refactor: tighten LuaCATS annotations across modules

Problem: type annotations repeated inline unions with no aliases,
used `table<string, any>` where structured types exist, and had
loose `string` where union types should be used.

Solution: add `pending.TaskStatus`, `pending.RecurMode`,
`pending.TaskExtra`, `pending.ForgeType`, `pending.ForgeState`,
`pending.ForgeAuthStatus` aliases and `pending.SyncBackend`
interface. Replace inline unions and loose types with the new
aliases in `store.lua`, `forge.lua`, `config.lua`, `diff.lua`,
`views.lua`, `parse.lua`, `init.lua`, and `oauth.lua`.

lua/pending/config.lua

@@ -43,7 +43,9 @@
 ---@field close? boolean
 ---@field validate? boolean
 ---@field warn_missing_cli? boolean
----@field [string] pending.ForgeInstanceConfig
+---@field github? pending.ForgeInstanceConfig
+---@field gitlab? pending.ForgeInstanceConfig
+---@field codeberg? pending.ForgeInstanceConfig
 
 ---@class pending.SyncConfig
 ---@field remote_delete? boolean

lua/pending/diff.lua

@@ -7,11 +7,11 @@ local parse = require('pending.parse')
 ---@field id? integer
 ---@field description? string
 ---@field priority? integer
----@field status? string
+---@field status? pending.TaskStatus
 ---@field category? string
 ---@field due? string
 ---@field rec? string
----@field rec_mode? string
+---@field rec_mode? pending.RecurMode
 ---@field forge_ref? pending.ForgeRef
 ---@field lnum integer
 

lua/pending/forge.lua

@@ -1,17 +1,21 @@
 local config = require('pending.config')
 local log = require('pending.log')
 
+---@alias pending.ForgeType 'issue'|'pull_request'|'merge_request'|'repo'
+---@alias pending.ForgeState 'open'|'closed'|'merged'
+---@alias pending.ForgeAuthStatus 'unknown'|'ok'|'failed'
+
 ---@class pending.ForgeRef
 ---@field forge string
 ---@field owner string
 ---@field repo string
----@field type 'issue'|'pull_request'|'merge_request'|'repo'
+---@field type pending.ForgeType
 ---@field number? integer
 ---@field url string
 
 ---@class pending.ForgeCache
 ---@field title? string
----@field state 'open'|'closed'|'merged'
+---@field state pending.ForgeState
 ---@field labels? string[]
 ---@field fetched_at string
 
@@ -27,10 +31,10 @@ local log = require('pending.log')
 ---@field auth_status_args string[]
 ---@field default_icon string
 ---@field default_issue_format string
----@field _auth? 'unknown'|'ok'|'failed'
+---@field _auth? pending.ForgeAuthStatus
 ---@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'
+---@field parse_state fun(self: pending.ForgeBackend, decoded: table): pending.ForgeState
 
 ---@class pending.forge
 local M = {}

lua/pending/init.lua

@@ -998,6 +998,14 @@ function M.add(text)
   log.info('Task added: ' .. description)
 end
 
+---@class pending.SyncBackend
+---@field name string
+---@field auth fun(): nil
+---@field push? fun(): nil
+---@field pull? fun(): nil
+---@field sync? fun(): nil
+---@field health? fun(): nil
+
 ---@type string[]?
 local _sync_backends = nil
 

lua/pending/parse.lua

@@ -4,7 +4,7 @@ local config = require('pending.config')
 ---@field due? string
 ---@field cat? string
 ---@field rec? string
----@field rec_mode? 'scheduled'|'completion'
+---@field rec_mode? pending.RecurMode
 ---@field priority? integer
 
 ---@class pending.parse

lua/pending/store.lua

@@ -1,19 +1,31 @@
 local config = require('pending.config')
 
+---@alias pending.TaskStatus 'pending'|'done'|'deleted'|'wip'|'blocked'
+---@alias pending.RecurMode 'scheduled'|'completion'
+
+---@class pending.TaskExtra
+---@field _forge_ref? pending.ForgeRef
+---@field _forge_cache? pending.ForgeCache
+---@field _gtasks_task_id? string
+---@field _gtasks_list_id? string
+---@field _gcal_event_id? string
+---@field _gcal_calendar_id? string
+---@field [string] any
+
 ---@class pending.Task
 ---@field id integer
 ---@field description string
----@field status 'pending'|'done'|'deleted'|'wip'|'blocked'
+---@field status pending.TaskStatus
 ---@field category? string
 ---@field priority integer
 ---@field due? string
 ---@field recur? string
----@field recur_mode? 'scheduled'|'completion'
+---@field recur_mode? pending.RecurMode
 ---@field entry string
 ---@field modified string
 ---@field end? string
 ---@field order integer
----@field _extra? table<string, any>
+---@field _extra? pending.TaskExtra
 
 ---@class pending.Data
 ---@field version integer
@@ -24,14 +36,14 @@ local config = require('pending.config')
 
 ---@class pending.TaskFields
 ---@field description string
----@field status? string
+---@field status? pending.TaskStatus
 ---@field category? string
 ---@field priority? integer
 ---@field due? string
 ---@field recur? string
----@field recur_mode? string
+---@field recur_mode? pending.RecurMode
 ---@field order? integer
----@field _extra? table
+---@field _extra? pending.TaskExtra
 
 ---@class pending.Store
 ---@field path string

lua/pending/sync/oauth.lua

@@ -24,6 +24,15 @@ local BUNDLED_CLIENT_SECRET = 'PLACEHOLDER'
 ---@field config_key string
 
 ---@class pending.OAuthClient : pending.OAuthClientOpts
+---@field token_path fun(self: pending.OAuthClient): string
+---@field resolve_credentials fun(self: pending.OAuthClient): pending.OAuthCredentials
+---@field load_tokens fun(self: pending.OAuthClient): pending.OAuthTokens?
+---@field save_tokens fun(self: pending.OAuthClient, tokens: pending.OAuthTokens): boolean
+---@field refresh_access_token fun(self: pending.OAuthClient, creds: pending.OAuthCredentials, tokens: pending.OAuthTokens): pending.OAuthTokens?
+---@field get_access_token fun(self: pending.OAuthClient): string?
+---@field setup fun(self: pending.OAuthClient): nil
+---@field auth fun(self: pending.OAuthClient, on_complete?: fun(ok: boolean): nil): nil
+---@field clear_tokens fun(self: pending.OAuthClient): nil
 local OAuthClient = {}
 OAuthClient.__index = OAuthClient
 

lua/pending/views.lua

@@ -13,7 +13,7 @@ local parse = require('pending.parse')
 ---@field id? integer
 ---@field due? string
 ---@field raw_due? string
----@field status? string
+---@field status? pending.TaskStatus
 ---@field category? string
 ---@field overdue? boolean
 ---@field show_category? boolean