spec: pkg.json "pivot"

part of #41

README.md

@@ -1,12 +1,52 @@
-# The Neovim package specification 
+# pkg.json
+
+- `pkg.json` is just a way to declare dependencies on URLs and versions
+- Decentralized ("federated", omg)
+- Subset of `package.json`
+- Upstream dependencies don't need a `pkg.json` file.
+- No client spec (yet)
+- No official client (yet)
+- TODO: support conflicting dependencies using git worktree.
+- Useful for: vim, nvim, emacs, (others?)
+- Used by:
+    - [lazy.nvim](https://github.com/folke/lazy.nvim/)
+    - TBD
+
+## Build
+
+    brew install luarocks
+    make
+    make test
+
+## Run tests
+
+    cd test-npm/
+    npm ci
+    npm run test
+
+## What about LuaRocks?
+
+LuaRocks is a natural as the Nvim plugin manager, but defining a ~~"plugin spec"~~ "federated package spec" also makes sense because:
+
+- There is no "federated" plugin spec (corrections welcome!). LuaRocks is a "centralized" approach.
+- LuaRocks + Nvim is starting to see real progress in the form of https://github.com/nvim-neorocks , but thus far has not gained momentum. A decentralized, lowest-common-denominator, "infectious" approach is high-leverage, while work continues on the centralized LuaRocks approach at its own pace.
+- There's no central _asset_ registry, just a bunch of URLs. 
+    - Could have a central _list_ of plugins, but not assets.
+- We can do both, at low cost. `pkg.json` is a fairly "cheap" approach. LuaRocks
+
+## Release
+
+TBD
+
+---
+
+# OLD
 
 The neovim package specification consists of three components:
 1. Guidelines which provide guidance to package authors,
 2. the `packspec` file format, and
 3. guidelines for `packspec`-compatible plugin manager implementers
 
-This specification is an effort to improve the consistency and reliability of Neovim packages.
-
 # Guidelines for plugin authors
 
 ### Semantic versioning

docs/README.md

@@ -1,30 +1,51 @@
 # pkg.json
 
+`pkg.json` allows artifacts to depend on other artifacts, by URLs.
+You can think of it as a "federated package spec": it's just a JSON file that
+lists URLs in a simple format that is dead simple to write a client for.
+
+The initial use-case is for Vim and Emacs plugins (which can be downloaded from
+anywhere). But the format is designed to be ecosystem-agnostic: it's just
+a formalized way to list dependencies by URL.
+
+# Features
+
 - `pkg.json` is just a way to declare dependencies on URLs and versions
 - Decentralized ("federated", omg)
 - Subset of `package.json`
 - Upstream dependencies don't need a `pkg.json` file.
-- No client spec (yet)
+- No client spec (yet): only the format is specified, not client behavior.
 - No official client (yet)
 - TODO: support conflicting dependencies using git worktree.
 - Useful for: vim, nvim, emacs, (others?)
 - Used by:
     - [lazy.nvim](https://github.com/folke/lazy.nvim/)
     - TBD
 
-## Build
+# Client requirements
+
+- `git` (packages can live at any git URL)
+- JSON parser
 
-    brew install luarocks
-    make
-    make test
+# Package server requirements
 
-## Run tests
+- Dependency URLs are expected to be git repos.
+- TODO: support other kinds of artifacts, like zip archives or binaries.
 
-    cd test-npm/
-    npm ci
-    npm run test
+# Design
 
-## Release
+1. Support _all "assets" or "artifacts" of any kind_. 
+1. Why JSON:
+    - ubiquitous
+    - "machine readable" (sandboxed by design): can recursively download an entire dependency tree before executing any code, including hooks. Aggregators such as https://neovimcraft.com/ can consume it.
+    - Turing-complete formats (unlike JSON) invite sprawling, special-case behavior (nvim-lspconfig is a [living example](https://github.com/neovim/nvim-lspconfig/pull/2595)).
+1. Client requirements are only `git` and a JSON parser.
+1. Avoid fields that overlap with info provided by git. Git is a client requirement. Git is the "common case" for servers (but not a requirement).
+1. Strive to be a subset of NPM's `package.json`. Avoid unnecessary entropy.
+1. No side-effects: evaluating  `pkg.json` not have side-effects, only input and output.
 
-TBD
+# References
 
+- https://json-schema.org/
+- lazy.nvim [pkg.json impl](https://github.com/folke/lazy.nvim/pull/910/files#diff-eeb8f2e48ace6e2f4c40bf159b7f59e5eb1208e056a3f9f1b9cc6822ecb45371)
+- [A way for artifacts to depend on other artifacts.](https://sink.io/jmk/artifact-system)