wip

Author: mxcl

README.md

@@ -11,21 +11,19 @@ Install `pkgx` packages to `/usr/local`.
 
 ```sh
 $ pkgm install node
-# ^^ installs latest git to ~/.local. ie. you get ~/.local/bin/git
+# ^^ installs latest node to ~/.local. ie. you get ~/.local/bin/node
 
 $ pkgm install node@20.1
-# ^^ installs git^2.41 or switches out the installed git to 2.41
+# ^^ installs node^20.1 or switches out the installed node to 20.1
 
 $ pkgm uninstall node
 
 $ sudo pkgm install node
-# ^^ installs git to /usr/local. ie. you get /usr/local/bin/git
+# ^^ installs node to /usr/local. ie. you get /usr/local/bin/node
 
 $ pkgm shim node
-# ^^ creates a shim for git in ~/.local/bin
-# these shims mimic the pkgx v1 lazy-loading shims, and are desirable for
-# certain types of self-healing and dev-setup containers, among other things
-# requires pkgx^2.4.0 for --shebang option
+# ^^ creates a shim for node at ~/.local/bin/node
+# see the docs below for details about shims
 
 $ pkgm list
 # ^^ lists what’s installed
@@ -51,9 +49,20 @@ $ sudo pkgm update
 >
 > You should probably `sudo pkgm install` rather than install to `~/.local`.
 > This is because many other tools will not look in `~/.local` for packages
-> _even_ if it’s in `PATH`.
+> _even_ if it’s in `PATH`. Having said this—by all means—see how it goes!
+
+> ### Shims
+>
+> Shims are files with a single line, eg `#!/usr/bin/env -S pkgx -q! node@22`.
+>
+> Thus using the shell to reinvoke the file via `pkgx`. You get all the benefits
+> of an installed package without actually having to install it. Desirable
+> traits for certain types of self-healing, devops containers and plenty more
+> one-off or ephemeral tasks.
 >
-> Having said this, by all means see how it goes!
+> Shims are pretty great—but have caveats. Some software might be surprised that
+> a package is not fully “installed” and lead to errors. In practice we have
+> seen issues only rarely and for more complex package combinations.
 
 ## Installation
 

pkgm.ts

@@ -140,10 +140,10 @@ async function install(args: string[], basePath: string) {
   // we are running as sudo on linux since it doesn’t give us a good way to get
   // the home directory of the pre-sudo user
   const pkgx_dir = (() => {
-    const {path, pkg} = json.pkgs[0]!
+    const { path, pkg } = json.pkgs[0]!;
     const remove = pkg.project + "/v" + pkg.version;
-    return path.string.slice(0, - remove.length - 1 );
-  })()
+    return path.string.slice(0, -remove.length - 1);
+  })();
 
   const runtime_env = expand_runtime_env(json, basePath);