Skip to content

feat: add public introspection API for third-party tooling#12

Merged
zuqini merged 1 commit intomainfrom
zuqini/public-api
Apr 10, 2026
Merged

feat: add public introspection API for third-party tooling#12
zuqini merged 1 commit intomainfrom
zuqini/public-api

Conversation

@zuqini
Copy link
Copy Markdown
Owner

@zuqini zuqini commented Apr 10, 2026

Introduces require('zpack').get_plugins() and get_plugin(name) as the supported surface for tools (e.g. zshow.nvim) that need to enumerate or look up plugins zpack is managing, along with a documented zpack.PluginInfo shape and stability promise.

Fixes a regression in b1eab47 where external consumers reaching into zpack's internal src_to_pack_spec crashed on disabled plugins. The API draws a clear internal/external boundary so consumers no longer need to touch internal state.

To keep the contract simple, enabled = false plugins (and any dep-only plugins orphaned by the cascade) are now pruned from the registry during setup and do not appear in the API; use cond for runtime conditions that should remain visible with status = "disabled". Every plugin returned by the API has therefore been through vim.pack.add, so PluginInfo.name, path, and lazy are all guaranteed to be populated.

Introduces `require('zpack').get_plugins()` and `get_plugin(name)` as
the supported surface for tools (e.g. zshow.nvim) that need to enumerate
or look up plugins zpack is managing, along with a documented
`zpack.PluginInfo` shape.

Fixes a regression in b1eab47 where external consumers reaching into
zpack's internal `src_to_pack_spec` crashed on disabled plugins. The API
draws a clear internal/external boundary so consumers no longer need to
touch internal state.

To keep the contract simple, `enabled = false` plugins (and any dep-only
plugins orphaned by the cascade) are now pruned from the registry during
setup and do not appear in the API; use `cond` for runtime conditions
that should remain visible with `status = "disabled"`. `:ZClean` will
remove `enabled = false` plugins from disk, matching the hard-disable
semantic.

Install-state queries (checked-out rev, available updates, etc.) are
intentionally not part of this API — they are owned by `vim.pack`, which
is itself public and stable. Consumers should call `vim.pack.get`
directly for those.

`name_to_src` and `is_lazy_resolved` are now populated during
`resolve_all` from the merged spec, so `get_plugin(name)` is symmetric
with `get_plugins()` across the installing → pending → loaded
lifecycle, and the reported `lazy` flag stays stable as an entry
transitions (no flip between raw `merged_spec.lazy` and the plugin-aware
resolution). Entries whose `vim.pack.add` load callback has not yet
fired surface as `status = "installing"` with a nil `path` so UIs can
render "downloading" instead of the plugin vanishing. `get_plugins()` is
side-effect-free — no notifications — so it is safe for statuslines and
dashboards to poll.

`derive_status` checks `load_status` before `cond_result` so a
cond=false plugin that gets force-loaded (via `:ZLoad!` or as a
required dependency of a live parent) correctly reports `loaded`
instead of `disabled`.

`src` is now documented as "the git URL or local path passed to
vim.pack.add" — committing to a real semantic rather than the previous
"opaque, do not parse" disclaimer. A formal deprecation policy is
deliberately deferred until the first time a field actually needs
retiring, rather than promised in advance.
@zuqini zuqini force-pushed the zuqini/public-api branch from 4de0007 to d8940e9 Compare April 10, 2026 21:06
@zuqini zuqini merged commit b678a07 into main Apr 10, 2026
2 checks passed
@zuqini zuqini deleted the zuqini/public-api branch April 10, 2026 21:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant