feat: prep first release#1
Merged
Merged
Conversation
- 'it's tmux window name' -> 'its tmux window name' (possessive) - FAQ snippet referenced provider = 'tmux_window' which does not exist; corrected to 'tmux_window_name' - Providers table claimed tmux-pane-%17/ but util.sanitize strips '%'; corrected to tmux-pane-_17/ with a clarifying note
init.lua was doing six jobs at once (config, scope state, file parsing,
item construction, Snacks preview rendering, restore decision tree).
Reduce it to ~110 lines of public API plus setup() wiring, with each
concern in its own module:
config.lua defaults + merge, typed PersistenceScope.Config
scope.lua provider resolution, current scope, base_dir/session_dir,
scope-from-file
session.lua glob, .vim parsing, item construction, load_file,
recent_count, typed PersistenceScope.SessionItem
restore.lua the restore() decision tree, isolated and testable
Snacks-specific preview rendering (SnacksPicker* highlight groups) moved
out of init.lua and into pickers/snacks.lua where it belongs. Preview
building is now lazy so the vim.ui fallback never pays for it.
All inner modules are lazy-required from init.lua so importing the
package does almost no work until a function is actually called.
Bundled in this commit because they touch the same setup() function:
- Friendly vim.notify error when folke/persistence.nvim is missing,
instead of a cryptic Lua stack trace.
- Restore-failure notify now prefixed with 'persistence-scope:' so users
can tell which plugin is talking. This is the one intentional
behavioral change; verified against the pre-refactor code that
everything else is bit-for-bit equivalent.
- Added desc fields to the user-command registrations.
Public API surface is unchanged: setup, restore, select, sessions,
load_file, config, scope.
Previously :PersistenceScopeRestore and :PersistenceScopeSelect were only created inside setup(), which meant they did not appear in :command output (or tab completion) until setup() ran. Define them in plugin/persistence_scope.lua at startup with lazy-required handlers, so they are discoverable immediately. setup() re-registers them with force=true (identical behavior, just cleaner discovery). Guarded with vim.g.loaded_persistence_scope to prevent double loading.
Reports everything a user needs to self-diagnose:
- Neovim version (errors below 0.10)
- folke/persistence.nvim installed (errors if missing, warns if its
fire() function is missing)
- folke/snacks.nvim installed (info-only, optional dependency)
- Whether setup() has been called or defaults are in use
- Resolved scope: kind, label, and the target sessions directory
(or 'global' / base_dir when no scope is resolved)
- Whether the editor is running inside tmux
- Count of session files currently under base_dir
Uses the modern vim.health.{start,ok,warn,error,info} API with a
fallback to vim.health.report_* for compatibility.
stylua.toml 2-space indent, 120-column, double quotes
.editorconfig LF, trim trailing whitespace, 2-space Lua, tab Makefile
.luacheckrc declares vim and Snacks as known globals, sets
max_line_length=120, ignores a few benign Lua warnings
These set baseline expectations for contributors and are consumed by
the CI workflow added in the following commit.
Three jobs run on every push to main and on pull requests:
stylua stylua --check . fails the build on formatting drift
lint luacheck lua plugin catches unused vars, shadowing, etc.
smoke headless Neovim across 0.10.4 / stable / nightly clones
folke/persistence.nvim, runs runtime plugin/persistence_scope,
calls setup() with a stub provider, asserts the public API is
present, and runs :checkhealth persistence_scope
The smoke test catches load-time regressions across the supported
Neovim version matrix. Behavioral regressions still need targeted
tests, which are intentionally left as a follow-up.
Previously the Lua API was a single unanchored block in the help file.
Each function now has its own tag so :help works for individual entries:
:help persistence_scope.restore()
:help persistence_scope.select()
:help persistence_scope.sessions()
:help persistence_scope.load_file()
Also adds:
*persistence-scope-need-option* documents 'need', forwarded
to persistence.nvim
*persistence-scope-custom-provider* direct anchor for the custom
provider example
*persistence-scope-troubleshooting* new section pointing at
:checkhealth persistence_scope
Reformatted to follow standard Vim help conventions (>/< code blocks,
column-aligned tags) and regenerated doc/tags accordingly.
- vim.pack install snippet for Neovim 0.12+ users (native package manager) right after the lazy.nvim snippet - 'Sessions are still written by folke/persistence.nvim' framing line under the directory diagram so readers immediately understand this is a layer on top of persistence.nvim, not a replacement - New Troubleshooting section pointing at :checkhealth persistence_scope with a 3-step debug checklist - Config block: document the 'need' option (forwarded to persistence.nvim) and clarify that setup() with no arguments works fine - Minor copy clean-ups in the config block and IMPORTANT callout - TOC entry for the new Troubleshooting section
Fixes stylua --check violations caught by the new CI workflow: - util.lua and vim_ui.lua predate this PR; one nested table.concat call in each exceeded the 120-column budget and got reflowed. - session.lua is new in this PR; a long 3-clause if condition got collapsed onto a single line. All formatting choices are stylua's defaults under the repo's stylua.toml (2-space, 120-col, double quotes).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Prep work for the first public release. Eight atomic commits — each builds and runs on its own.
🐛 Fixes
it's→its)tmux_window→tmux_window_name)tmux-pane-%17/bututil.sanitizestrips%— corrected totmux-pane-_17/with a clarifying note🏗️ Refactor
init.luawas doing six jobs at once. Split it into focused modules so each concern is reviewable, testable, and lazy-loaded:config.luaPersistenceScope.Configscope.luabase_dir/session_dir, scope-from-filesession.lua.vimparsing, item construction,load_file, typedPersistenceScope.SessionItemrestore.luarestore()decision tree, isolatedpickers/snacks.luainit.lua)init.luasetup()wiring onlyPublic API is unchanged. The one intentional behavioral change is a friendlier notify prefix (
persistence-scope: ...) — everything else was verified bit-for-bit equivalent against the pre-refactor code.✨ Features
:checkhealth persistence_scope— reports Neovim version, dependency status, resolved scope, target directory, tmux state, and session-file countplugin/so:PersistenceScopeRestore/:PersistenceScopeSelectare discoverable in:commandbeforesetup()runsvim.notifyerror whenfolke/persistence.nvimis missing, instead of a Lua stack tracePersistenceScope.Config/Scope/SessionItem) for LSP hovers and custom-provider authors🧰 Tooling & CI
stylua.toml,.editorconfig,.luacheckrcfor contributor baselinestylua --checkluacheckpersistence.nvim, runssetup(), asserts API, runs:checkhealth)📚 Documentation
vim.packinstall snippet for Neovim 0.12+ users (native package manager):checkhealthneedoption (forwarded topersistence.nvim) which was previously undocumented:help persistence_scope.restore()works for each Lua API entrypersistence.nvimrather than replacing it✅ Verified
Local headless run confirms:
setup()is calledpersistence.select/load_fileare patched as expectedsessions()enumerates real session files (477 in my state dir) with branches and buffer summaries:checkhealth persistence_scoperenders cleanlyCommits