Merge #41075 from echasnovski/pack-packspec-part1

runtime/doc/news.txt

@@ -370,6 +370,7 @@ LUA
 • |vim.log| provides a logging interface.
 • |vim.pack.get()| output includes revision of a pending update.
 • |vim.pack.get()| can fetch new updates before computing the output.
+• |vim.pack| supports |vim.pack-manifest| of plugins.
 • |vim.o| now accepts table style values for assignment.
 • |vim.keycode()| returns structured info as return value 2.
 • |Iter:count()| counts items in the iterator.

runtime/doc/pack.txt

@@ -423,6 +423,56 @@ These events can be used to execute plugin hooks. For example: >lua
     vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })
 <
 
+                                                           *vim.pack-manifest*
+
+Plugins can come with a special top level `pkg.json` manifest file with extra
+information. If present, `vim.pack` uses it for improved user experience:
+• Apply |:source| for scripts after triggering corresponding
+  |vim.pack-events|. This allows plugins to define hooks that will be executed
+  during plugin's lifetime. Sourcing is done with special context:
+  • The |current-directory| is temporarily set to plugin's root (to make it
+    easier to run |vim.system()| commands).
+  • Plugin's path is temporarily ensured to be inside |'runtimepath'| (so
+    script can use |require()| with plugin's module, possibly with explicit
+    |package.loaded| reset inside `"update"` scripts).
+• Running |:checkhealth| for `vim.pack` will perform extra checks to ensure
+  healthy plugin installation.
+
+Full specification see at https://packspec.org/. See also |vim.pack.Manifest|.
+A simple example: >json
+    {
+     "name": "best-plugin.nvim",
+     "description": "The best plugin for Neovim",
+     "engines": {
+         "nvim": ">=0.13.0",
+         "vim": ">=9.1.0"
+     },
+     "scripts": {
+       "install": "scripts/install.lua",
+       "preupdate": "scripts/preupdate.vim",
+       "update": "scripts/update.vim",
+       "preuninstall": "scripts/preuninstall.lua"
+     }
+    }
+<
+
+
+*vim.pack.Manifest*
+
+    Fields: ~
+      • {description}?  (`string`) Plugin description
+      • {engines}?      (`table`) Supported engine versions. Values should be
+                        |vim.version.range()| compatible specs.
+                        • {nvim}? (`string`) Version range for Nvim.
+                        • {vim}? (`string`) Version range for Vim.
+      • {name}?         (`string`) Plugin name
+      • {scripts}?      (`table`) Script locations (relative to plugin's root)
+                        to |:source| after triggering corresponding
+                        |vim.pack-events|.
+                        • {install}? (`string`) Post install script.
+                        • {preuninstall}? (`string`) Pre delete script.
+                        • {preupdate}? (`string`) Pre update script.
+                        • {update}? (`string`) Post update script.
 
 *vim.pack.Spec*
 
@@ -506,6 +556,9 @@ get({names}, {opts})                                          *vim.pack.get()*
           to current session.
         • {branches}? (`string[]`) Available Git branches (first is default).
           Missing if `info=false`.
+        • {manifest}? (`vim.pack.Manifest`) Data from the |vim.pack-manifest|.
+          Empty in case of reading error. Missing if `info=false`. See
+          |vim.pack.Manifest|.
         • {path} (`string`) Plugin's path on disk.
         • {rev} (`string`) Current Git revision. Taken from
           |vim.pack-lockfile| if `info=false`.