@ivan-bekker/ghav 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Bekker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# ghav
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A localhost web viewer for running GitHub Actions workflows from the browser. Point it at local repos, pick a workflow, job and event, press Run, and watch live logs, job and step status, and run history. Nothing is pushed to GitHub.
+
+It is a UI over [`act`](https://github.com/nektos/act), which runs the workflows in Docker. Results approximate GitHub; they are not identical.
+
+## Requirements
+
+- Node.js 24 or newer
+- [`act`](https://github.com/nektos/act) on your `PATH`
+- Docker, running (not needed for host-mode runs or dry runs)
+
+The **Setup check** button in the sidebar reports what is missing.
+
+## Install and run
+
+```sh
+npm i -g @ivanbekker/ghav
+ghav
+```
+
+The server listens on `http://localhost:4780` (the next free port if that is busy) and opens the browser on macOS. It binds to `127.0.0.1` only. Stop it with Ctrl-C; running workflows are cancelled.
+
+## Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `GHA_VIEW_HOME` | Data directory (database, logs, secrets). Default `~/.gha-view` |
+| `GHA_VIEW_PORT` | Fixed port, no fallback to the next one |
+| `GHA_VIEW_ACT_BIN` | Path to the `act` binary. Default `act` |
+| `GHA_VIEW_DOCKER_BIN` | Path to the `docker` binary. Default `docker` |
+| `GHA_VIEW_NO_OPEN=1` | Don't open the browser |
+
+## Security
+
+The server runs workflow code on your machine. It accepts requests from `127.0.0.1` only, checks `Host` and `Origin`, and requires a per-process token for every write. Secrets are stored per repo in `~/.gha-view/secrets` (mode 0600) and passed to `act` through its environment, never on the command line.
+
+## Develop
+
+```sh
+npm install
+npm run dev          # API on :4780, UI on http://localhost:5173
+npm test
+npm run build && npm start
+```
+
+## License
+
+MIT