| … | … | @@ -60,6 +60,123 @@ Make sure `~/.local/bin` is on your `PATH`. |
| 60 | 60 | Other install forms (pinned version, local tarball, custom prefix) are in |
| 61 | 61 | [`docs/overview.md`](./docs/overview.md). |
| 62 | 62 | |
| 63 | ## Install from source |
| 64 | |
| 65 | The quick install pulls prebuilt bootstrap tarballs. To build from a git |
| 66 | checkout instead — for hacking on pgh, running an unreleased branch, or a |
| 67 | platform without a published tarball — you clone pgh **and its sibling |
| 68 | packages**, because pgh consumes them as local `file:` dependencies rather |
| 69 | than from a registry. There is no single `npm install pgh` — the daemon |
| 70 | (`pgh-sidecar`) and the shared libraries have to be present on disk too. |
| 71 | |
| 72 | ### 1. Prerequisites |
| 73 | |
| 74 | - **git** and **npm** (Node ≥ 18) to fetch and install. Node is used only as |
| 75 | the package manager; pgh itself runs on the **bare** runtime. |
| 76 | - A **glibc Linux or macOS** host with a POSIX filesystem (see *Prerequisites* |
| 77 | above — unix sockets + symlinks are required, musl is unsupported). |
| 78 | - No root needed; everything lands under `$HOME`. |
| 79 | |
| 80 | ### 2. Clone the package set into one parent directory |
| 81 | |
| 82 | pgh's `file:` deps are relative paths, so the layout is load-bearing. Every |
| 83 | package sits flat beside pgh, **except `hyperident`, which pgh references as |
| 84 | `../repos/hyperident`** and therefore lives under a `repos/` subdirectory: |
| 85 | |
| 86 | ``` |
| 87 | pgh-src/ |
| 88 | ├── pgh/ # the CLI (this repo) |
| 89 | ├── pgh-sidecar/ # the always-on user daemon (required) |
| 90 | ├── pgh-runtime/ # OTA update engine (pgh dep) |
| 91 | ├── hyper-deploy/ # tree distribution layer |
| 92 | ├── hyper-overlay/ # per-file content overlay |
| 93 | ├── hyper-svc/ # hyper-svc UDS/RPC transport |
| 94 | ├── hyper-rooms/ # autobase room primitive (hyper-svc dep) |
| 95 | └── repos/ |
| 96 | └── hyperident/ # identity vault (pgh dep — note the repos/ nesting) |
| 97 | ``` |
| 98 | |
| 99 | The `file:` edges that make this exact set mandatory: |
| 100 | |
| 101 | - **pgh** → hyper-deploy, hyper-overlay, hyper-svc, pgh-runtime, repos/hyperident |
| 102 | - **pgh-sidecar** → hyper-deploy, hyper-overlay, hyper-svc, pgh |
| 103 | - **hyper-deploy** → hyper-overlay |
| 104 | - **hyper-svc** → hyper-rooms |
| 105 | - **pgh-runtime** → hyper-overlay |
| 106 | |
| 107 | Clone all eight over the forge (HTTPS anonymous read; substitute your own |
| 108 | mirror for `7rnx.net` if you have one): |
| 109 | |
| 110 | ```bash |
| 111 | mkdir -p pgh-src/repos && cd pgh-src |
| 112 | |
| 113 | for repo in pgh pgh-sidecar pgh-runtime hyper-deploy \ |
| 114 | hyper-overlay hyper-svc hyper-rooms; do |
| 115 | git clone https://7rnx.net/git/$repo.git |
| 116 | done |
| 117 | git clone https://7rnx.net/git/hyperident.git repos/hyperident |
| 118 | ``` |
| 119 | |
| 120 | (Already running a forge? `git clone punch://<serverKey>/<repo>` works too, |
| 121 | once `git-remote-punch` is installed.) |
| 122 | |
| 123 | ### 3. Install dependencies (leaf packages first) |
| 124 | |
| 125 | Install each package's deps in dependency order so the `file:` links resolve |
| 126 | against already-populated trees. This also fetches the native prebuilds |
| 127 | (`bare-runtime`, `sodium-native`, `udx-native`): |
| 128 | |
| 129 | ```bash |
| 130 | for pkg in hyper-overlay hyper-rooms hyper-svc hyper-deploy \ |
| 131 | pgh-runtime repos/hyperident pgh pgh-sidecar; do |
| 132 | ( cd "$pkg" && npm install ) |
| 133 | done |
| 134 | ``` |
| 135 | |
| 136 | `bare-runtime` drops a `bare` binary at `pgh/node_modules/.bin/bare`. pgh's |
| 137 | launchers resolve `bare` from your `PATH`, so put one there — either install |
| 138 | it globally (`npm i -g bare-runtime`) or symlink the one you just built: |
| 139 | |
| 140 | ```bash |
| 141 | ln -sf "$PWD/pgh/node_modules/.bin/bare" ~/.local/bin/bare |
| 142 | ``` |
| 143 | |
| 144 | ### 4. Register the source trees and initialise |
| 145 | |
| 146 | `pgh app adopt` writes a launcher that runs the app **in place** from your |
| 147 | checkout (the launcher's `sourcePath` points back at the clone), so edits take |
| 148 | effect on the next run with no rebuild step. Run the first adopt through bare |
| 149 | directly, since `pgh` isn't on your `PATH` yet: |
| 150 | |
| 151 | ```bash |
| 152 | # bootstrap: adopt pgh itself (launcher → ~/.local/bin/pgh) |
| 153 | ./pgh/node_modules/.bin/bare ./pgh/bin/pgh app adopt ./pgh \ |
| 154 | --name pgh --bin pgh |
| 155 | |
| 156 | # now `pgh` is on PATH — adopt the daemon |
| 157 | pgh app adopt ./pgh-sidecar --name pgh-sidecar --bin pgh-sidecar |
| 158 | |
| 159 | # one-time machine setup: store, identity vault, start pgh-sidecar |
| 160 | pgh init |
| 161 | ``` |
| 162 | |
| 163 | Confirm it came up: |
| 164 | |
| 165 | ```bash |
| 166 | pgh app status # pgh-sidecar should be registered + running |
| 167 | pgh --help # full command list |
| 168 | ``` |
| 169 | |
| 170 | From here everything works as with a tarball install — `pgh app install`, |
| 171 | `pgh publish`, the forge commands — except your `pgh` / `pgh-sidecar` run from |
| 172 | source. To pick up upstream changes: `git pull` in the relevant repo, |
| 173 | `npm install` if deps changed, then `pgh app restart pgh-sidecar`. |
| 174 | |
| 175 | > **Note — OTA and source installs.** An adopted source tree is *not* managed |
| 176 | > by the release-registry, so the sidecar's autoupdate won't overwrite it (that |
| 177 | > is the point). It also won't self-heal over the swarm. Update it yourself with |
| 178 | > `git pull` as above. |
| 179 | |
| 63 | 180 | ## Common commands |
| 64 | 181 | |
| 65 | 182 | ### install & run an app |