Review atlas.nvim for forge.nvim UX lessons #607

New issue

Closed

opened 2026-05-06 03:02:06 +00:00 by barrettruth · 1 comment

barrettruth commented

2026-05-06 03:02:06 +00:00

Owner

Question

Do we have anything useful to glean from atlas.nvim?

Source: https://github.com/emrearmagan/atlas.nvim

Quick notes

atlas.nvim appears to solve adjacent problems: Jira issues plus GitHub/Bitbucket PRs inside Neovim. It is not a direct model for forge.nvim, but it may be worth briefly reviewing for product ideas around:

panel/tab organization for issue and PR detail views
mock providers for trying the UI before configuring credentials
saved/custom views and provider-specific view configs
custom issue/PR actions
health, logs, cache clearing, and command completion UX
how it presents configurable keymaps and help

Scope

Do a short remote/code review and decide whether any ideas should become concrete forge.nvim issues.

Non-goals

Do not copy atlas.nvim architecture wholesale.
Do not expand forge.nvim into Jira/Bitbucket scope from this issue alone.
Do not start implementation until there is a specific follow-up.

## Question Do we have anything useful to glean from atlas.nvim? Source: https://github.com/emrearmagan/atlas.nvim ## Quick notes atlas.nvim appears to solve adjacent problems: Jira issues plus GitHub/Bitbucket PRs inside Neovim. It is not a direct model for forge.nvim, but it may be worth briefly reviewing for product ideas around: - panel/tab organization for issue and PR detail views - mock providers for trying the UI before configuring credentials - saved/custom views and provider-specific view configs - custom issue/PR actions - health, logs, cache clearing, and command completion UX - how it presents configurable keymaps and help ## Scope Do a short remote/code review and decide whether any ideas should become concrete forge.nvim issues. ## Non-goals - Do not copy atlas.nvim architecture wholesale. - Do not expand forge.nvim into Jira/Bitbucket scope from this issue alone. - Do not start implementation until there is a specific follow-up.

barrettruth commented

2026-05-06 03:15:50 +00:00

Author

Owner

Reviewed emrearmagan/atlas.nvim at 8ad154ce7ac82563c5aea39878b0b401d9eaf59e.

Findings

Atlas is more of an in-editor forge workbench than forge.nvim is today: main list plus a toggleable detail panel. The detail panels are tabbed: Jira issues use overview/comments/history; GitHub PRs use overview/conversation/activity/commits/changes; Bitbucket PRs use overview/activity/comments/commits/changes. The useful lesson is the product shape of explicit, contextual detail panes, not the renderer architecture. For forge.nvim, I would keep the current fzf-first picker/action model and only add detail surfaces when a specific workflow needs them.
The panel idea worth borrowing is small and specific: grouped details/chips for provider-specific status that does not fit a picker row, e.g. review/build/conflict summaries. It should live in existing review/log/check buffers or a focused route, not as a global persistent tab framework.
Mock providers are the most transferable idea. :AtlasIssues mock and :AtlasPulls mock exercise list/detail/comment/action flows without Jira/GitHub/Bitbucket credentials. For forge.nvim, a mock/demo source could be useful for screenshots, manual UI QA, and tests of picker contracts across PR/issue/CI/release surfaces.
Atlas has configured provider views, not really saved views yet. Jira and GitHub views are config-defined JQL/search queries with optional keys; Bitbucket views can define repo lists, layout, and Lua filters. The README still marks “save JQL queries as custom views” as TODO. For forge.nvim, the relevant follow-up would be provider-specific saved picker views/presets, not a fake universal query abstraction.
Custom actions are exposed through provider action menus and user-configured Lua callbacks. Forge already has a bounded extension surface (register_action() plus command/picker actions), so the lesson is mostly UX: a secondary action menu can keep provider-specific actions discoverable without crowding picker headers.
Health/log/cache/command-completion UX is solid but unevenly relevant. Atlas has :checkhealth atlas for provider config and keymap conflicts, :AtlasLogs, :AtlasClearCache, provider argument completion, and JQL completion backed by cached autocomplete data plus static fallback data. Forge already has health, cache clear, command completion, log buffers, and picker cache controls. The gap worth stealing is keymap-contract validation in health, not a second log/cache subsystem.
For #610, Atlas's strongest pattern is not its default keys; it is the separation between action IDs, key resolution, hidden-vs-shown help registration, aliases, disabled mappings, and health conflict checks. That maps cleanly to standardizing Forge's supported hidden picker mappings. Active bindings do not all need header hints, but they should have one documented/discoverable registry.

Worth considering

Open a follow-up for a mock/demo forge source if we want zero-credential demos and manual picker QA. Keep it opt-in and clearly non-production.
Open a follow-up for saved picker views/presets after the current refactor stack, scoped to provider-specific query semantics. Examples: GitHub search query views, GitLab search/filter views, Forgejo/Gitea filters only where the backend supports them honestly.
Fold #610 toward a central picker action/key contract: action id, default key, optional aliases, whether it appears in the header, supported picker families, and health/doc validation.
Extend :checkhealth forge with key conflict/disabled-key diagnostics once the supported hidden mapping contract is explicit.
Consider a lightweight discoverability route or help action for picker bindings if the header stays intentionally sparse. Atlas's g? popup is heavier than Forge needs, but its “hidden binding is still discoverable elsewhere” model is useful.

Not worth copying

Do not copy Atlas's persistent multi-pane tabbed workbench wholesale. It would compete with forge.nvim's picker, review adapter, log, terminal, and compose surfaces.
Do not import Jira/Bitbucket scope, ADF markdown editing, templates, or repo-path mapping ideas from this issue. They are product-scope choices for Atlas, not forge.nvim architecture lessons.
Do not treat Atlas's config-time Lua custom actions as a reason to make Forge actions ambient or untyped. If Forge expands action menus, keep provider/backend differences explicit and keep the extension API bounded.
Do not generalize provider-specific tabs into a shared forge abstraction unless a real cross-backend contract exists. Atlas's own panel hooks are provider-specific for good reason.
Do not prioritize runtime “save view” UI based on Atlas; the repo documents it as future work, not a proven implementation.

Sources reviewed

Reviewed `emrearmagan/atlas.nvim` at `8ad154ce7ac82563c5aea39878b0b401d9eaf59e`. ### Findings - Atlas is more of an in-editor forge workbench than forge.nvim is today: main list plus a toggleable detail panel. The detail panels are tabbed: Jira issues use overview/comments/history; GitHub PRs use overview/conversation/activity/commits/changes; Bitbucket PRs use overview/activity/comments/commits/changes. The useful lesson is the product shape of explicit, contextual detail panes, not the renderer architecture. For forge.nvim, I would keep the current fzf-first picker/action model and only add detail surfaces when a specific workflow needs them. - The panel idea worth borrowing is small and specific: grouped details/chips for provider-specific status that does not fit a picker row, e.g. review/build/conflict summaries. It should live in existing review/log/check buffers or a focused route, not as a global persistent tab framework. - Mock providers are the most transferable idea. `:AtlasIssues mock` and `:AtlasPulls mock` exercise list/detail/comment/action flows without Jira/GitHub/Bitbucket credentials. For forge.nvim, a mock/demo source could be useful for screenshots, manual UI QA, and tests of picker contracts across PR/issue/CI/release surfaces. - Atlas has configured provider views, not really saved views yet. Jira and GitHub views are config-defined JQL/search queries with optional keys; Bitbucket views can define repo lists, layout, and Lua filters. The README still marks “save JQL queries as custom views” as TODO. For forge.nvim, the relevant follow-up would be provider-specific saved picker views/presets, not a fake universal query abstraction. - Custom actions are exposed through provider action menus and user-configured Lua callbacks. Forge already has a bounded extension surface (`register_action()` plus command/picker actions), so the lesson is mostly UX: a secondary action menu can keep provider-specific actions discoverable without crowding picker headers. - Health/log/cache/command-completion UX is solid but unevenly relevant. Atlas has `:checkhealth atlas` for provider config and keymap conflicts, `:AtlasLogs`, `:AtlasClearCache`, provider argument completion, and JQL completion backed by cached autocomplete data plus static fallback data. Forge already has health, cache clear, command completion, log buffers, and picker cache controls. The gap worth stealing is keymap-contract validation in health, not a second log/cache subsystem. - For #610, Atlas's strongest pattern is not its default keys; it is the separation between action IDs, key resolution, hidden-vs-shown help registration, aliases, disabled mappings, and health conflict checks. That maps cleanly to standardizing Forge's supported hidden picker mappings. Active bindings do not all need header hints, but they should have one documented/discoverable registry. ### Worth considering - Open a follow-up for a mock/demo forge source if we want zero-credential demos and manual picker QA. Keep it opt-in and clearly non-production. - Open a follow-up for saved picker views/presets after the current refactor stack, scoped to provider-specific query semantics. Examples: GitHub search query views, GitLab search/filter views, Forgejo/Gitea filters only where the backend supports them honestly. - Fold #610 toward a central picker action/key contract: action id, default key, optional aliases, whether it appears in the header, supported picker families, and health/doc validation. - Extend `:checkhealth forge` with key conflict/disabled-key diagnostics once the supported hidden mapping contract is explicit. - Consider a lightweight discoverability route or help action for picker bindings if the header stays intentionally sparse. Atlas's `g?` popup is heavier than Forge needs, but its “hidden binding is still discoverable elsewhere” model is useful. ### Not worth copying - Do not copy Atlas's persistent multi-pane tabbed workbench wholesale. It would compete with forge.nvim's picker, review adapter, log, terminal, and compose surfaces. - Do not import Jira/Bitbucket scope, ADF markdown editing, templates, or repo-path mapping ideas from this issue. They are product-scope choices for Atlas, not forge.nvim architecture lessons. - Do not treat Atlas's config-time Lua custom actions as a reason to make Forge actions ambient or untyped. If Forge expands action menus, keep provider/backend differences explicit and keep the extension API bounded. - Do not generalize provider-specific tabs into a shared forge abstraction unless a real cross-backend contract exists. Atlas's own panel hooks are provider-specific for good reason. - Do not prioritize runtime “save view” UI based on Atlas; the repo documents it as future work, not a proven implementation. ### Sources reviewed - Atlas README overview, commands, mock mode, provider config, custom actions, and keymaps: https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/README.md#L8-L121, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/README.md#L127-L245, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/README.md#L257-L470, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/README.md#L474-L517 - Provider selection and command registration: https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/init.lua#L23-L112, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/config.lua#L194-L268 - Panel/tab organization: https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/issues/ui/panel/issue/init.lua#L91-L177, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/pulls/ui/panel/pr/init.lua#L79-L167, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/pulls/providers/github/ui/panel.lua#L377-L410, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/pulls/providers/bitbucket/ui/panel.lua#L161-L195 - Mock providers: https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/issues/providers/mock/init.lua#L5-L69, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/issues/providers/mock/init.lua#L334-L390, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/pulls/providers/mock/init.lua#L278-L319, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/pulls/providers/mock/init.lua#L683-L689 - Action registries/custom actions: https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/pulls/providers/github/actions/registry.lua#L432-L528, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/issues/providers/jira/actions/registry.lua#L935-L993 - Health/log/cache/completion: https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/health.lua#L161-L183, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/core/cache.lua#L94-L149, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/core/logger.lua#L58-L165, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/ui/logs.lua#L153-L205, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/issues/providers/jira/completion/search.lua#L49-L60 - Keymap/help discoverability: https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/core/keymaps.lua#L94-L151, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/core/keymaps.lua#L185-L230, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/ui/popups/help.lua#L95-L136, https://github.com/emrearmagan/atlas.nvim/blob/8ad154ce7ac82563c5aea39878b0b401d9eaf59e/lua/atlas/ui/popups/help.lua#L320-L408

barrettruth closed this issue

2026-05-06 18:22:49 +00:00