Update README.md

README.md

@@ -1,16 +1,53 @@
-# packages
+# webinstall/packages
 
-Primary and community-submitted packages for
-[webinstall.dev](https://webinstall.dev)
+> WebInstall is how developers install their tools
 
-# Guidelines
+This repository contains the primary and community-submitted packages for
+[webinstall.dev](https://webinstall.dev).
 
-- Should install to `./local/opt/<package>-<version>`
+# Installer Guidelines
+
+- Should install to `$HOME/.local/opt/<package>-<version>` or `$HOME/.local/bin`
 - Should not need `sudo` (except perhaps for a one-time `setcap`, etc)
-- Follow the example of
-  <https://github.com/webinstall/packages/tree/master/ripgrep>,
-  <https://github.com/webinstall/packages/tree/master/node>, or
-  <https://github.com/webinstall/packages/tree/master/golang>
+- Examples:
+    - Full Packages:
+        - Node.js: <https://github.com/webinstall/packages/tree/master/node>
+        - Golang: <https://github.com/webinstall/packages/tree/master/golang>
+        - PostgreSQL: <https://github.com/webinstall/packages/tree/master/postgres>
+    - Single-Binary Installers:
+        - Caddy: <https://github.com/webinstall/packages/tree/master/caddy>
+        - Ripgrep: <https://github.com/webinstall/packages/tree/master/ripgrep>
+        - Gitea: <https://github.com/webinstall/packages/tree/master/gitea>
+    - Convenience Scripts:
+        - Prettier: <https://github.com/webinstall/packages/tree/master/prettier>
+        - Rust-lang: <https://github.com/webinstall/packages/tree/master/rustlang>
+        - Rust-lang: <https://github.com/webinstall/packages/tree/master/vim-sensible>
+
+# How it works
+
+- Contacts official release APIs for download URLs
+- Selects the appropriate package version and archive format
+- Installs to `$HOME/.local/`
+- Updates `PATH` via `$HOME/.config/envman/PATH.env`
+- Symlinks or copies current selected version
+
+More technically:
+
+1. `<package>/releases.js` transforms the package's release API into a common formatt
+    - (i.e. HTML, CSV, TAB, or JSON into a specific JSON format)
+    - common release APIs are in `_common/` (i.e. `_common/github.js`)
+2. `_webi/bootstrap.sh` is a template that exchanges system information for a correct installer
+    - contructs a user agent with os, cpu, and utility info (i.e. `macos`, `amd64`, can unpack `tar,zip,xz`)
+3. `_webi/template.sh` is the base installer template with common functions for
+    - checking versions
+    - downloading & unpacking
+    - updating PATH
+    - (re-)linking directories
+4. `<package>/install.sh` may provide functions to override `_webi/template.sh`
+5. Recap:
+    - `curl https://webinstall.dev/<pkg>` => `bootstrap-<pkg>.sh`
+    - `bash bootstrap-<pkg>.sh` => `https://webinstall.dev/api/installers/<pkg>@<ver>.sh?formats=zip,tar`
+    - `bash install-<pkg>.sh` => download, unpack, move, link, update PATH
 
 ## Creating an Installer
 
@@ -161,7 +198,7 @@ pkg_done_message() {}               # Override, pretty print a success message
 
 ## Script API
 
-See `webi/template.bash`
+See `webi/template.sh`
 
 These variables will be set by the server:
 
@@ -202,16 +239,6 @@ webi_post_install       # Runs `webi_add_path $pkg_dst_bin`
 # Roadmap
 
 - Wrap release APIs to unify and expose
-  - [x] Golang <https://golang.org/dl/?mode=json>
-  - [x] Node <https://nodejs.org/dist/index.tab>
-  - [x] Flutter
-        <https://storage.googleapis.com/flutter_infra/releases/releases_linux.json> -
-        Started at
-        <https://github.com/webinstall/packages/blob/master/flutter/versions.js>
-  - [ ] git
-    - Note: do all platforms expose tar/zip releases with the same URLs?
-  - [ ] npm
-  - [x] github (see ripgrep)
-  - [x] gitea (see serviceman)
-- [ ] Support git urls (i.e. `@github.com/node/node`)
+- [ ] Support arbitrary git urls (i.e. `@github.com/node/node`)
   - (maybe `ghi node/node` for github specifically)
+- [ ] Support git as an archive format