Adds docs for v2

README.md

@@ -1,22 +1,133 @@
 # esy - GitHub Action
 
-This action runs cached `esy install` and `esy build` in the current directory
+This action will setup [`esy`](https://esy.sh/) and cache any dependencies that
+are built (hopefully saving you CI minutes). Additionally, it can help
+you package your apps for multiple platforms into a single NPM
+tarball.
 
-## Inputs
+For instance,
+
+```
+npm i -g your-app
+```
+
+Even if, it's single command, the tarball can contain binaries for
+multiple target platforms - this action will create a postinstall
+script that will install the correct binaries.
 
-- `cache-key`: **Required** The cache key. Typically
-  `${{ hashFiles('esy.lock/index.json') }}`
-- `esy-prefix`: The prefix of esy folder
-- `working-directory`: Working directory.
-- `manifest`: JSON or opam file to be used
+Another benefit of this approach, is that, this action creates binary
+wrappers that make your apps self-sufficient in terms of runtime
+dependencies. For instance, if you need a runtime dependency (say,
+`zlib`), it can be tricky to make sure the user has the
+correct version installed via their system package manager. On Windows
+this is harder that one might expect. Read more about binary wrappers
+on [`esy` documentation](https://esy.sh/docs/concepts/#release)
 
-## Example usage
+## Example
 
 ```yml
-- uses: actions/setup-node@v2
-- name: Install esy
-  run: npm install -g esy
-- uses: esy/github-action@v1
-  with:
-    cache-key: ${{ hashFiles('esy.lock/index.json') }}
+name: Build
+
+on: [push]
+jobs:
+  build:
+    steps:
+      - uses: esy/github-action@v2
+        with:
+          cache-key: ${{ hashFiles('esy.lock/index.json') }}
+```
+
+## Inputs
+
+### Required inputs
+
+#### `cache-key`
+
+The cache key. Typically `${{ hashFiles('esy.lock/index.json') }}`. You could
+also use a prefix additionally to bust cache when needed.
+
+Example: `20240801-2-${{ hashFiles('esy.lock/index.json') }}`
+
+#### `source-cache-key`
+
+Typically a value similar to `cache-key` but used instead for caching the
+sources of the dependencies.
+
+### Optional inputs
+
+The following inputs are optional. When missing, the actions will fallback to
+use defaults are mentioned below.
+
+#### `esy-prefix`
+
+Path where esy can setup the cache. Default: `$HOME/.esy`
+
+#### `working-directory`
+
+Working directory of the project. Useful for projects that place esy project
+under a folder.
+
+Default: Action workspace root.
+
+#### `manifest`
+
+JSON or opam file to be used.
+
+#### `prepare-npm-artifacts-mode`
+
+Runs a step that prepare artifacts for releasing the app to NPM. Useful for CLI
+apps. These artifacts are later used by, `bundle-npm-tarball-mode`
+
+#### `bundle-npm-artifacts-mode`
+
+Runs a steps that bundle artifacts so that a single NPM tarball that contains
+binaries built for different platforms. This way, the app can be distributed on
+NPM under a single command, but will work on multiple platforms. `esy` itself
+uses this mode.
+
+#### `postinstall-js`
+
+Path to a custom `postinstall.js` file that could be placed in the final bundled
+NPM tarball.
+
+#### `setup-esy`
+
+Flag to control if esy itself should be installed by the action By default, it's
+true. You can disable it if you wish to install esy yourself
+
+Example:
+
 ```
+    steps:
+	  - run: npm i -g esy
+	  - uses: esy/github-action@v2
+        with:
+          source-cache-key: ${{ hashFiles('esy.lock/index.json') }}
+          cache-key: ${{ hashFiles('esy.lock/index.json') }}
+		  setup-esy: false
+
+```
+
+#### `setup-esy-tarball`
+
+URL to esy tarball. Must be provided together with shasum and version. Else, the
+action will default to latest from NPM  
+Example: `https://registry.npmjs.org/esy/-/esy-0.7.2.tgz`
+
+#### `setup-esy-shasum`
+
+shasum of the tarball. Must be provided together with shasum and version. Else,
+the action will default to latest from NPM
+
+#### `setup-esy-version`
+
+version of the esy tool. Must be provided together with shasum and version.
+Else, the action will default to latest from NPM
+
+#### `setup-esy-npm-package`
+
+Alternative NPM package that contains esy. Example: `@diningphilosophers/esy`.
+
+## License
+
+BSD 2-Clause License

action.yml

@@ -25,7 +25,9 @@ inputs:
     description: Runs a steps that bundle artifacts for release the app to NPM.
     required: false
   postinstall-js:
-    description: Path to a postinstall.js file that would be run by NPM
+    description:
+      Path to a custom `postinstall.js` file that could be placed in the final
+      bundled NPM tarball.
     required: false
   setup-esy:
     description: Flag to control if esy itself should be installed by the action