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 1/5] 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 -local FORGE_HOSTS = { - ['github.com'] = 'github', - ['gitlab.com'] = 'gitlab', - ['codeberg.org'] = 'codeberg', -} +---@type pending.ForgeBackend[] +local _backends = {} ----@type table -local FORGE_API_BASE = { - github = 'https://api.github.com', - gitlab = 'https://gitlab.com', - codeberg = 'https://codeberg.org', -} +---@type table +local _by_name = {} ----@type table -local SHORTHAND_PREFIX = { - gh = 'github', - gl = 'gitlab', - cb = 'codeberg', -} +---@type table +local _by_shorthand = {} + +---@type table +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') From 24e8741ae16118bd48efb8270ca869e1efe77ee0 Mon Sep 17 00:00:00 2001 From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com> Date: Tue, 10 Mar 2026 22:30:20 -0400 Subject: [PATCH 2/5] feat(diff): disallow editing done tasks by default (#132) 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 * feat(diff): disallow editing done tasks by default Problem: Done tasks could be freely edited in the buffer, leading to accidental modifications of completed work. Solution: Add a `lock_done` config option (default `true`) and a guard in `diff.apply()` that rejects field changes to done tasks unless the user toggles the checkbox back to pending first. Co-Authored-By: Claude Opus 4.6 --------- Co-authored-by: Claude Opus 4.6 --- lua/pending/config.lua | 2 + lua/pending/diff.lua | 161 ++++++++++++++++++++++------------------- spec/diff_spec.lua | 61 ++++++++++++++++ 3 files changed, 148 insertions(+), 76 deletions(-) diff --git a/lua/pending/config.lua b/lua/pending/config.lua index b1ab639..6942c1b 100644 --- a/lua/pending/config.lua +++ b/lua/pending/config.lua @@ -100,6 +100,7 @@ ---@field view pending.ViewConfig ---@field max_priority? integer ---@field sync? pending.SyncConfig +---@field lock_done? boolean ---@field forge? pending.ForgeConfig ---@field icons pending.Icons @@ -114,6 +115,7 @@ local defaults = { date_syntax = 'due', recur_syntax = 'rec', someday_date = '9999-12-30', + lock_done = true, max_priority = 3, view = { default = 'category', diff --git a/lua/pending/diff.lua b/lua/pending/diff.lua index 29c292b..a213584 100644 --- a/lua/pending/diff.lua +++ b/lua/pending/diff.lua @@ -1,5 +1,6 @@ local config = require('pending.config') local forge = require('pending.forge') +local log = require('pending.log') local parse = require('pending.parse') ---@class pending.ParsedEntry @@ -102,14 +103,91 @@ function M.apply(lines, s, hidden_ids) local order_counter = 0 for _, entry in ipairs(parsed) do - if entry.type ~= 'task' then - goto continue - end + if entry.type == 'task' then + order_counter = order_counter + 1 - order_counter = order_counter + 1 - - if entry.id and old_by_id[entry.id] then - if seen_ids[entry.id] then + if entry.id and old_by_id[entry.id] then + if seen_ids[entry.id] then + s:add({ + description = entry.description, + category = entry.category, + priority = entry.priority, + due = entry.due, + recur = entry.rec, + recur_mode = entry.rec_mode, + order = order_counter, + _extra = entry.forge_ref and { _forge_ref = entry.forge_ref } or nil, + }) + else + seen_ids[entry.id] = true + local task = old_by_id[entry.id] + if + config.get().lock_done + and task.status == 'done' + and entry.status == 'done' + then + if task.order ~= order_counter then + task.order = order_counter + task.modified = now + end + log.warn('cannot edit done task — toggle status first') + else + local changed = false + if task.description ~= entry.description then + task.description = entry.description + changed = true + end + if task.category ~= entry.category then + task.category = entry.category + changed = true + end + if entry.priority == 0 and task.priority > 0 then + task.priority = 0 + changed = true + elseif entry.priority > 0 and task.priority == 0 then + task.priority = entry.priority + changed = true + end + if entry.due ~= nil and task.due ~= entry.due then + task.due = entry.due + changed = true + end + if entry.rec ~= nil then + if task.recur ~= entry.rec then + task.recur = entry.rec + changed = true + end + if task.recur_mode ~= entry.rec_mode then + task.recur_mode = entry.rec_mode + changed = true + end + end + if entry.forge_ref ~= nil then + if not task._extra then + task._extra = {} + end + task._extra._forge_ref = entry.forge_ref + changed = true + end + if entry.status and task.status ~= entry.status then + task.status = entry.status + if entry.status == 'done' then + task['end'] = now + else + task['end'] = nil + end + changed = true + end + if task.order ~= order_counter then + task.order = order_counter + changed = true + end + if changed then + task.modified = now + end + end + end + else s:add({ description = entry.description, category = entry.category, @@ -120,77 +198,8 @@ function M.apply(lines, s, hidden_ids) order = order_counter, _extra = entry.forge_ref and { _forge_ref = entry.forge_ref } or nil, }) - else - seen_ids[entry.id] = true - local task = old_by_id[entry.id] - local changed = false - if task.description ~= entry.description then - task.description = entry.description - changed = true - end - if task.category ~= entry.category then - task.category = entry.category - changed = true - end - if entry.priority == 0 and task.priority > 0 then - task.priority = 0 - changed = true - elseif entry.priority > 0 and task.priority == 0 then - task.priority = entry.priority - changed = true - end - if entry.due ~= nil and task.due ~= entry.due then - task.due = entry.due - changed = true - end - if entry.rec ~= nil then - if task.recur ~= entry.rec then - task.recur = entry.rec - changed = true - end - if task.recur_mode ~= entry.rec_mode then - task.recur_mode = entry.rec_mode - changed = true - end - end - if entry.forge_ref ~= nil then - if not task._extra then - task._extra = {} - end - task._extra._forge_ref = entry.forge_ref - changed = true - end - if entry.status and task.status ~= entry.status then - task.status = entry.status - if entry.status == 'done' then - task['end'] = now - else - task['end'] = nil - end - changed = true - end - if task.order ~= order_counter then - task.order = order_counter - changed = true - end - if changed then - task.modified = now - end end - else - s:add({ - description = entry.description, - category = entry.category, - priority = entry.priority, - due = entry.due, - recur = entry.rec, - recur_mode = entry.rec_mode, - order = order_counter, - _extra = entry.forge_ref and { _forge_ref = entry.forge_ref } or nil, - }) end - - ::continue:: end for id, task in pairs(old_by_id) do diff --git a/spec/diff_spec.lua b/spec/diff_spec.lua index 01d8aac..c897df1 100644 --- a/spec/diff_spec.lua +++ b/spec/diff_spec.lua @@ -287,5 +287,66 @@ describe('diff', function() local task = s:get(1) assert.are.equal(0, task.priority) end) + + it('rejects editing description of a done task', function() + local t = s:add({ description = 'Finished work', status = 'done' }) + t['end'] = '2026-03-01T00:00:00Z' + s:save() + local lines = { + '# Todo', + '/1/- [x] Changed description', + } + diff.apply(lines, s) + s:load() + local task = s:get(1) + assert.are.equal('Finished work', task.description) + assert.are.equal('done', task.status) + end) + + it('allows toggling done task back to pending', function() + local t = s:add({ description = 'Finished work', status = 'done' }) + t['end'] = '2026-03-01T00:00:00Z' + s:save() + local lines = { + '# Todo', + '/1/- [ ] Finished work', + } + diff.apply(lines, s) + s:load() + local task = s:get(1) + assert.are.equal('pending', task.status) + end) + + it('allows editing done task when lock_done is false', function() + local cfg = require('pending.config') + vim.g.pending = { lock_done = false } + cfg.reset() + local t = s:add({ description = 'Finished work', status = 'done' }) + t['end'] = '2026-03-01T00:00:00Z' + s:save() + local lines = { + '# Todo', + '/1/- [x] Changed description', + } + diff.apply(lines, s) + s:load() + local task = s:get(1) + assert.are.equal('Changed description', task.description) + vim.g.pending = {} + cfg.reset() + end) + + it('does not affect editing of pending tasks', function() + s:add({ description = 'Active task' }) + s:save() + local lines = { + '# Todo', + '/1/- [ ] Updated active task', + } + diff.apply(lines, s) + s:load() + local task = s:get(1) + assert.are.equal('Updated active task', task.description) + end) end) end) From 8e1795a1f292906eada838f5ff5a4647d8c0dc0e Mon Sep 17 00:00:00 2001 From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com> Date: Tue, 10 Mar 2026 22:30:42 -0400 Subject: [PATCH 3/5] feat(forge): support custom shorthand prefixes (#131) 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 * feat(forge): support custom shorthand prefixes Problem: forge shorthand parsing hardcoded `%l%l` (exactly 2 lowercase letters), preventing custom prefixes like `github:`. Completions also hardcoded `gh:`, `gl:`, `cb:` patterns. Solution: iterate `_by_shorthand` keys dynamically in `_parse_shorthand` instead of matching a fixed pattern. Build completion patterns from `forge.backends()`. Add `shorthand` field to `ForgeInstanceConfig` so users can override prefixes via config, applied in `_ensure_instances()`. Co-Authored-By: Claude Opus 4.6 --------- Co-authored-by: Claude Opus 4.6 --- lua/pending/complete.lua | 20 +++++++++--- lua/pending/config.lua | 1 + lua/pending/forge.lua | 26 +++++++++++++--- spec/forge_spec.lua | 67 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 106 insertions(+), 8 deletions(-) diff --git a/lua/pending/complete.lua b/lua/pending/complete.lua index 135d1a4..98291ce 100644 --- a/lua/pending/complete.lua +++ b/lua/pending/complete.lua @@ -1,4 +1,5 @@ local config = require('pending.config') +local forge = require('pending.forge') ---@class pending.CompletionItem ---@field word string @@ -109,6 +110,17 @@ local function recur_completions() return result end +---@param source string +---@return boolean +function M._is_forge_source(source) + for _, b in ipairs(forge.backends()) do + if b.shorthand == source then + return true + end + end + return false +end + ---@type string? local _complete_source = nil @@ -128,10 +140,10 @@ function M.omnifunc(findstart, base) { vim.pesc(dk) .. ':([%S]*)$', dk }, { 'cat:([%S]*)$', 'cat' }, { vim.pesc(rk) .. ':([%S]*)$', rk }, - { 'gh:([%S]*)$', 'gh' }, - { 'gl:([%S]*)$', 'gl' }, - { 'cb:([%S]*)$', 'cb' }, } + for _, b in ipairs(forge.backends()) do + table.insert(checks, { vim.pesc(b.shorthand) .. ':([%S]*)$', b.shorthand }) + end for _, check in ipairs(checks) do local start = before:find(check[1]) @@ -172,7 +184,7 @@ function M.omnifunc(findstart, base) table.insert(matches, { word = c.word, menu = '[' .. source .. ']', info = c.info }) end end - elseif source == 'gh' or source == 'gl' or source == 'cb' then + elseif M._is_forge_source(source) then local s = require('pending.buffer').store() if s then local seen = {} diff --git a/lua/pending/config.lua b/lua/pending/config.lua index 6942c1b..1359f9a 100644 --- a/lua/pending/config.lua +++ b/lua/pending/config.lua @@ -37,6 +37,7 @@ ---@field icon? string ---@field issue_format? string ---@field instances? string[] +---@field shorthand? string ---@class pending.ForgeConfig ---@field auto_close? boolean diff --git a/lua/pending/forge.lua b/lua/pending/forge.lua index 9b32655..baebc0a 100644 --- a/lua/pending/forge.lua +++ b/lua/pending/forge.lua @@ -62,6 +62,14 @@ function M.backends() return _backends end +function M._reset_instances() + _instances_resolved = false + _by_shorthand = {} + for _, b in ipairs(_backends) do + _by_shorthand[b.shorthand] = b + end +end + local function _ensure_instances() if _instances_resolved then return @@ -73,17 +81,27 @@ local function _ensure_instances() for _, inst in ipairs(forge_cfg.instances or {}) do _by_host[inst] = backend end + if forge_cfg.shorthand and forge_cfg.shorthand ~= backend.shorthand then + _by_shorthand[backend.shorthand] = nil + backend.shorthand = forge_cfg.shorthand + _by_shorthand[backend.shorthand] = backend + end end end ---@param token string ---@return pending.ForgeRef? function M._parse_shorthand(token) - local prefix, rest = token:match('^(%l%l):(.+)$') - if not prefix then - return nil + _ensure_instances() + local backend, rest + for prefix, b in pairs(_by_shorthand) do + local candidate = token:match('^' .. vim.pesc(prefix) .. ':(.+)$') + if candidate then + backend = b + rest = candidate + break + end end - local backend = _by_shorthand[prefix] if not backend then return nil end diff --git a/spec/forge_spec.lua b/spec/forge_spec.lua index fac8021..8bd4162 100644 --- a/spec/forge_spec.lua +++ b/spec/forge_spec.lua @@ -391,6 +391,73 @@ describe('forge registry', function() end) end) +describe('custom forge prefixes', function() + local config = require('pending.config') + local complete = require('pending.complete') + + it('parses custom-length shorthand (3+ chars)', function() + local custom = forge.gitea_backend({ + name = 'customforge', + shorthand = 'cgf', + default_host = 'custom.example.com', + }) + forge.register(custom) + + local ref = forge._parse_shorthand('cgf:alice/proj#99') + assert.is_not_nil(ref) + assert.equals('customforge', ref.forge) + assert.equals('alice', ref.owner) + assert.equals('proj', ref.repo) + assert.equals(99, ref.number) + end) + + it('parse_ref dispatches custom-length shorthand', function() + local ref = forge.parse_ref('cgf:alice/proj#5') + assert.is_not_nil(ref) + assert.equals('customforge', ref.forge) + assert.equals(5, ref.number) + end) + + it('find_refs finds custom-length shorthand', function() + local refs = forge.find_refs('Fix cgf:alice/proj#12') + assert.equals(1, #refs) + assert.equals('customforge', refs[1].ref.forge) + assert.equals(12, refs[1].ref.number) + end) + + it('completion returns entries for custom backends', function() + assert.is_true(complete._is_forge_source('cgf')) + end) + + it('config shorthand override re-registers backend', function() + vim.g.pending = { + forge = { + github = { shorthand = 'github' }, + }, + } + config.reset() + forge._reset_instances() + + local ref = forge._parse_shorthand('github:user/repo#1') + assert.is_not_nil(ref) + assert.equals('github', ref.forge) + assert.equals('user', ref.owner) + assert.equals('repo', ref.repo) + assert.equals(1, ref.number) + + assert.is_nil(forge._parse_shorthand('gh:user/repo#1')) + + vim.g.pending = nil + config.reset() + for _, b in ipairs(forge.backends()) do + if b.name == 'github' then + b.shorthand = 'gh' + end + end + forge._reset_instances() + end) +end) + describe('forge diff integration', function() local store = require('pending.store') local diff = require('pending.diff') From 6e385db3c7e855da3e342c076bdab062b733af72 Mon Sep 17 00:00:00 2001 From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com> Date: Tue, 10 Mar 2026 22:45:07 -0400 Subject: [PATCH 4/5] Revert "feat(diff): disallow editing done tasks by default (#132)" (#133) This reverts commit 24e8741ae16118bd48efb8270ca869e1efe77ee0. --- lua/pending/config.lua | 2 - lua/pending/diff.lua | 161 +++++++++++++++++++---------------------- spec/diff_spec.lua | 61 ---------------- 3 files changed, 76 insertions(+), 148 deletions(-) diff --git a/lua/pending/config.lua b/lua/pending/config.lua index 1359f9a..5a139cb 100644 --- a/lua/pending/config.lua +++ b/lua/pending/config.lua @@ -101,7 +101,6 @@ ---@field view pending.ViewConfig ---@field max_priority? integer ---@field sync? pending.SyncConfig ----@field lock_done? boolean ---@field forge? pending.ForgeConfig ---@field icons pending.Icons @@ -116,7 +115,6 @@ local defaults = { date_syntax = 'due', recur_syntax = 'rec', someday_date = '9999-12-30', - lock_done = true, max_priority = 3, view = { default = 'category', diff --git a/lua/pending/diff.lua b/lua/pending/diff.lua index a213584..29c292b 100644 --- a/lua/pending/diff.lua +++ b/lua/pending/diff.lua @@ -1,6 +1,5 @@ local config = require('pending.config') local forge = require('pending.forge') -local log = require('pending.log') local parse = require('pending.parse') ---@class pending.ParsedEntry @@ -103,91 +102,14 @@ function M.apply(lines, s, hidden_ids) local order_counter = 0 for _, entry in ipairs(parsed) do - if entry.type == 'task' then - order_counter = order_counter + 1 + if entry.type ~= 'task' then + goto continue + end - if entry.id and old_by_id[entry.id] then - if seen_ids[entry.id] then - s:add({ - description = entry.description, - category = entry.category, - priority = entry.priority, - due = entry.due, - recur = entry.rec, - recur_mode = entry.rec_mode, - order = order_counter, - _extra = entry.forge_ref and { _forge_ref = entry.forge_ref } or nil, - }) - else - seen_ids[entry.id] = true - local task = old_by_id[entry.id] - if - config.get().lock_done - and task.status == 'done' - and entry.status == 'done' - then - if task.order ~= order_counter then - task.order = order_counter - task.modified = now - end - log.warn('cannot edit done task — toggle status first') - else - local changed = false - if task.description ~= entry.description then - task.description = entry.description - changed = true - end - if task.category ~= entry.category then - task.category = entry.category - changed = true - end - if entry.priority == 0 and task.priority > 0 then - task.priority = 0 - changed = true - elseif entry.priority > 0 and task.priority == 0 then - task.priority = entry.priority - changed = true - end - if entry.due ~= nil and task.due ~= entry.due then - task.due = entry.due - changed = true - end - if entry.rec ~= nil then - if task.recur ~= entry.rec then - task.recur = entry.rec - changed = true - end - if task.recur_mode ~= entry.rec_mode then - task.recur_mode = entry.rec_mode - changed = true - end - end - if entry.forge_ref ~= nil then - if not task._extra then - task._extra = {} - end - task._extra._forge_ref = entry.forge_ref - changed = true - end - if entry.status and task.status ~= entry.status then - task.status = entry.status - if entry.status == 'done' then - task['end'] = now - else - task['end'] = nil - end - changed = true - end - if task.order ~= order_counter then - task.order = order_counter - changed = true - end - if changed then - task.modified = now - end - end - end - else + order_counter = order_counter + 1 + + if entry.id and old_by_id[entry.id] then + if seen_ids[entry.id] then s:add({ description = entry.description, category = entry.category, @@ -198,8 +120,77 @@ function M.apply(lines, s, hidden_ids) order = order_counter, _extra = entry.forge_ref and { _forge_ref = entry.forge_ref } or nil, }) + else + seen_ids[entry.id] = true + local task = old_by_id[entry.id] + local changed = false + if task.description ~= entry.description then + task.description = entry.description + changed = true + end + if task.category ~= entry.category then + task.category = entry.category + changed = true + end + if entry.priority == 0 and task.priority > 0 then + task.priority = 0 + changed = true + elseif entry.priority > 0 and task.priority == 0 then + task.priority = entry.priority + changed = true + end + if entry.due ~= nil and task.due ~= entry.due then + task.due = entry.due + changed = true + end + if entry.rec ~= nil then + if task.recur ~= entry.rec then + task.recur = entry.rec + changed = true + end + if task.recur_mode ~= entry.rec_mode then + task.recur_mode = entry.rec_mode + changed = true + end + end + if entry.forge_ref ~= nil then + if not task._extra then + task._extra = {} + end + task._extra._forge_ref = entry.forge_ref + changed = true + end + if entry.status and task.status ~= entry.status then + task.status = entry.status + if entry.status == 'done' then + task['end'] = now + else + task['end'] = nil + end + changed = true + end + if task.order ~= order_counter then + task.order = order_counter + changed = true + end + if changed then + task.modified = now + end end + else + s:add({ + description = entry.description, + category = entry.category, + priority = entry.priority, + due = entry.due, + recur = entry.rec, + recur_mode = entry.rec_mode, + order = order_counter, + _extra = entry.forge_ref and { _forge_ref = entry.forge_ref } or nil, + }) end + + ::continue:: end for id, task in pairs(old_by_id) do diff --git a/spec/diff_spec.lua b/spec/diff_spec.lua index c897df1..01d8aac 100644 --- a/spec/diff_spec.lua +++ b/spec/diff_spec.lua @@ -287,66 +287,5 @@ describe('diff', function() local task = s:get(1) assert.are.equal(0, task.priority) end) - - it('rejects editing description of a done task', function() - local t = s:add({ description = 'Finished work', status = 'done' }) - t['end'] = '2026-03-01T00:00:00Z' - s:save() - local lines = { - '# Todo', - '/1/- [x] Changed description', - } - diff.apply(lines, s) - s:load() - local task = s:get(1) - assert.are.equal('Finished work', task.description) - assert.are.equal('done', task.status) - end) - - it('allows toggling done task back to pending', function() - local t = s:add({ description = 'Finished work', status = 'done' }) - t['end'] = '2026-03-01T00:00:00Z' - s:save() - local lines = { - '# Todo', - '/1/- [ ] Finished work', - } - diff.apply(lines, s) - s:load() - local task = s:get(1) - assert.are.equal('pending', task.status) - end) - - it('allows editing done task when lock_done is false', function() - local cfg = require('pending.config') - vim.g.pending = { lock_done = false } - cfg.reset() - local t = s:add({ description = 'Finished work', status = 'done' }) - t['end'] = '2026-03-01T00:00:00Z' - s:save() - local lines = { - '# Todo', - '/1/- [x] Changed description', - } - diff.apply(lines, s) - s:load() - local task = s:get(1) - assert.are.equal('Changed description', task.description) - vim.g.pending = {} - cfg.reset() - end) - - it('does not affect editing of pending tasks', function() - s:add({ description = 'Active task' }) - s:save() - local lines = { - '# Todo', - '/1/- [ ] Updated active task', - } - diff.apply(lines, s) - s:load() - local task = s:get(1) - assert.are.equal('Updated active task', task.description) - end) end) end) From b52e35aec33d023b371c4a94d7bfad9cc09e0607 Mon Sep 17 00:00:00 2001 From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com> Date: Tue, 10 Mar 2026 23:18:20 -0400 Subject: [PATCH 5/5] refactor(forge): rename `auto_close` to `close` (#137) Problem: `auto_close` is verbose given it's already namespaced under `forge.` in the config table. Solution: Rename to `close` in config defaults, class annotation, `refresh()` usage, and vimdoc. --- doc/pending.txt | 6 +++--- lua/pending/config.lua | 4 ++-- lua/pending/forge.lua | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/pending.txt b/doc/pending.txt index 9195c76..3078ea9 100644 --- a/doc/pending.txt +++ b/doc/pending.txt @@ -1500,7 +1500,7 @@ Configuration: ~ >lua vim.g.pending = { forge = { - auto_close = false, + close = false, warn_missing_cli = true, github = { icon = '', @@ -1522,7 +1522,7 @@ Configuration: ~ < Top-level fields: ~ - {auto_close} (boolean, default: false) When true, tasks linked to + {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 @@ -1550,7 +1550,7 @@ than 5 minutes are re-fetched asynchronously. The buffer renders immediately with cached data and updates extmarks when the fetch completes. State pull: ~ -Requires `forge.auto_close = true`. After fetching, if the remote issue/PR +Requires `forge.close = true`. After fetching, if the remote issue/PR is closed or merged and the local task is pending/wip/blocked, the task is automatically marked as done. Disabled by default. One-way: local status changes do not push back to the forge. diff --git a/lua/pending/config.lua b/lua/pending/config.lua index 5a139cb..60775fe 100644 --- a/lua/pending/config.lua +++ b/lua/pending/config.lua @@ -40,7 +40,7 @@ ---@field shorthand? string ---@class pending.ForgeConfig ----@field auto_close? boolean +---@field close? boolean ---@field warn_missing_cli? boolean ---@field [string] pending.ForgeInstanceConfig @@ -154,7 +154,7 @@ local defaults = { }, sync = {}, forge = { - auto_close = false, + close = false, warn_missing_cli = true, github = { icon = '', diff --git a/lua/pending/forge.lua b/lua/pending/forge.lua index baebc0a..43150c0 100644 --- a/lua/pending/forge.lua +++ b/lua/pending/forge.lua @@ -310,7 +310,7 @@ function M.refresh(s) any_fetched = true local forge_cfg = config.get().forge or {} if - forge_cfg.auto_close + forge_cfg.close and (cache.state == 'closed' or cache.state == 'merged') and (task.status == 'pending' or task.status == 'wip' or task.status == 'blocked') then