Make peardock-client the full Pear GUI via Electron Forge

Replace the headless Bare agent client with a real desktop app: Electron shell loads the same index.html/app.js UI as pear run, with a Pear polyfill, Holesail control, and Node ESM bootstrap for HyperDHT. Server remains bare-build standalone; CI rolling release publishes both product types.
2026-07-11 00:24:26 -04:00
parent 0e097308ce
commit 08b6e8be6d
15 changed files with 8917 additions and 511 deletions
@@ -1,194 +1,117 @@
 # peardock release process

-## Standalone Bare binaries (recommended)
+## Two products

-peardock ships **two separate self-contained binaries** built with the Holepunch
-stack (`bare-pack` + `bare-build --standalone`):
+| Artifact | What it is | Build |
+|----------|------------|--------|
+| **peardock-server** | Bare standalone daemon (HyperDHT + Docker) | `bare-pack` + `bare-build --standalone` |
+| **peardock-client** | **Full Pear GUI app** (same UI as `pear run -d .`) | Electron Forge (hello-pear-electron pattern) |

-| Binary | Role |
-|--------|------|
-| `peardock-server-<host>` | HyperDHT Docker control plane (dockerode over Unix socket) |
-| `peardock-client-<host>` | Bare agent: Holesail local control + optional headless HyperDHT connect |
+---

-Each binary embeds the full JS module graph and native addons (no `node_modules`
-on the target host). Pattern matches [hello-pear-bare](https://github.com/holepunchto/hello-pear-bare)
-and [bare-build](https://github.com/holepunchto/bare-build).
+## peardock-server (Bare binary)

-### Local build
+Self-contained ELF/Mach-O/PE with the full JS graph and native addons embedded.

 ```bash
 npm ci
-# Native host (server + client)
-npm run make
-
-# Explicit targets
 npm run make:server:linux-x64
-npm run make:client:linux-x64
-npm run make:all   # all desktop hosts × both products
-```
+# → out/server/linux-x64/peardock-server

-Outputs:
-
-```
-out/server/<host>/peardock-server[.exe]
-out/client/<host>/peardock-client[.exe]
+./out/server/linux-x64/peardock-server
+# Identity: PEARDOCK_HOME or next to the binary (.env)
 ```

 Hosts: `linux-x64`, `linux-arm64`, `darwin-arm64`, `darwin-x64`, `win32-x64`, `win32-arm64`.

-### Why `scripts/bare-standalone.cjs` instead of plain `bare-build`?
-
-`bare-build` 1.x packs with Bare resolution but does **not** expose
-`bare-pack --imports`. Node packages such as `dockerode` need
-`bare-node-runtime/imports.json` so builtins (`events`, `stream`, …) map to
-`bare-*`. The peardock builder:
-
-1. `bare-pack` with bare-node-runtime imports + small shims/stubs
-2. Embeds the bundle into a portable Bare runtime ELF/Mach-O/PE (same as
-   `bare-build --standalone`)
-
-Shims under `build/`:
-
-| Path | Purpose |
-|------|---------|
-| `shims/http.cjs` | Unix `socketPath` for Docker (bare-http1 is TCP-only) |
-| `shims/url.cjs` | Legacy `url.resolve` / `parse` for docker-modem |
-| `stubs/ssh2.cjs` | docker-modem optional SSH (local socket only) |
-| `stubs/grpc-js.cjs` | dockerode BuildKit gRPC sessions (not used for Engine API) |
-
-### Run server binary
-
-```bash
-# Identity lives next to the binary by default (.env)
-./out/server/linux-x64/peardock-server
-
-# Or point at a home directory
-PEARDOCK_HOME=/var/lib/peardock ./peardock-server
-# / PEARDOCK_ENV=/etc/peardock.env
-```
-
-Requires: Docker Engine socket (`/var/run/docker.sock`) and network for HyperDHT.
-
-### Run client binary (agent)
-
-```bash
-./out/client/linux-x64/peardock-client
-./out/client/linux-x64/peardock-client --connect <server-public-key-hex>
-```
-
-Full **desktop GUI** still uses Pear + pear-electron:
-
-```bash
-npm run dev   # pear run -d .
-```
-
-(Electron-forge installers can follow the [hello-pear-electron](https://github.com/holepunchto/hello-pear-electron)
-pattern later.)
+Builder: `scripts/bare-standalone.cjs` (passes `bare-node-runtime` imports + Docker socket shims).

 ---

-## Gitea CI — rolling release (`RELEASE_TOKEN`)
+## peardock-client (full Pear GUI)
+
+The desktop app is the **same** peardock UI as development (`index.html` + `app.js` + HyperDHT client + Holesail).
+
+### Development
+
+```bash
+# Pear platform (recommended for day-to-day UI work)
+npm run dev          # pear run -d .   → index.js (pear-electron + bridge)
+
+# Electron shell (what the released client binary uses)
+npm run start:client # electron electron/main.cjs
+```
+
+### Package / make
+
+```bash
+npm run package:client    # → out/peardock-<platform>-<arch>/peardock-client
+npm run make:client       # zip / deb / AppImage under out/make/
+npm run make:client:linux-x64
+```
+
+Architecture:
+
+- `electron/main.cjs` — window, local static server, Holesail control, Pear polyfill
+- `electron/preload.cjs` — `globalThis.Pear.config.storage` etc. for UI + holesailLocal
+- App entry remains `app.js` (Node ESM via dynamic `import(fileURL)` so npm deps resolve)
+- Packaged `package.json` main rewritten to `electron/main.cjs` (source tree keeps `main: index.js` for `pear run`)
+
+Pattern: [hello-pear-electron](https://github.com/holepunchto/hello-pear-electron) + peardock’s existing pear-electron UI.
+
+---
+
+## Gitea CI rolling release

 Workflow: `.gitea/workflows/release-rolling.yml`

-### Secret
+| Secret | Purpose |
+|--------|---------|
+| `RELEASE_TOKEN` | Gitea PAT with release write |
+| `GITEA_URL` | Optional forge base URL |

-In the Gitea repo **Settings → Secrets**:
+On push to `main`:

-| Name | Value |
-|------|--------|
-| `RELEASE_TOKEN` | Personal access token with **repository** write (create/delete releases + upload assets) |
+1. Matrix-build **servers** (Bare) for all desktop hosts  
+2. Matrix-build **clients** (Electron Forge) on Linux/macOS/Windows runners  
+3. Publish/replace tag **`rolling`** with all assets + `SHA256SUMS`

-Optional:
-
-| Name | Value |
-|------|--------|
-| `GITEA_URL` | Forge base URL if not the same as the Actions host (e.g. `https://git.example.com`) |
-
-### Behaviour
-
-1. On every push to `main` / `master` (and manual dispatch), matrix-builds
-   server + client for desktop hosts via `npm run make:<product>:<host>`.
-2. `publish` job downloads artifacts and runs
-   `scripts/gitea-rolling-release.sh`.
-3. That script **replaces** the release tagged `rolling` (delete + recreate) and
-   uploads:
-
-   - `peardock-server-<host>[.exe]`
-   - `peardock-client-<host>[.exe]`
-   - `SHA256SUMS`
-
-### Manual publish (from a machine with artifacts)
+Manual:

 ```bash
-export RELEASE_TOKEN=...
-export GITEA_URL=https://your.gitea.host
-export GITEA_OWNER=snxraven
-export GITEA_REPO=peardock
-npm run make:all   # or copy CI artifacts into out/
+export RELEASE_TOKEN=... GITEA_URL=https://your.gitea GITEA_OWNER=... GITEA_REPO=peardock
+npm run make:server:linux-x64
+npm run make:client
 npm run release:rolling
 ```

 ---

-## Source tarball + checksums (legacy / Node install)
-
-```bash
-chmod +x scripts/release-checksums.sh
-./scripts/release-checksums.sh dist/
-# Optional GPG:
-GPG_KEY_ID=YOUR_KEY_ID ./scripts/release-checksums.sh dist/
-```
-
-| File | Purpose |
-|------|---------|
-| `peardock-<ver>-<stamp>.tar.gz` | Source/runtime tree (no node_modules) |
-| `*.sha256` | SHA-256 checksum |
-| `*.asc` | Detached GPG signature (if keyed) |
-
-```bash
-tar -xzf peardock-*.tar.gz -C /opt/peardock
-cd /opt/peardock && npm ci --omit=dev
-# Prefer binary: copy peardock-server into place and set ExecStart
-cp deploy/peardock.service /etc/systemd/system/
-systemctl enable --now peardock
-```
-
-Update `deploy/peardock.service` `ExecStart` to the standalone binary when using
-Bare builds:
+## systemd (server)

 ```ini
 ExecStart=/opt/peardock/peardock-server
 Environment=PEARDOCK_HOME=/opt/peardock
 ```

+See `deploy/peardock.service`.
+
 ---

-## Pear desktop app (GUI OTA)
+## Pear OTA (optional)

 ```bash
-npm ci
 pear stage .
 pear release .
-# Distribute pear:// link per Pear docs
+# pear-install pear://...
 ```

+Electron client can later embed `pear-runtime` OTA like hello-pear-electron (`upgrade` field in package.json).
+
 ---

-## Certification soak (24h)
+## Source tarball (legacy Node server)

 ```bash
-# Terminal 1
-./out/server/linux-x64/peardock-server
-# or: npm run server
-
-# Terminal 2
-SOAK_DURATION_MS=86400000 npm run soak
+./scripts/release-checksums.sh dist/
 ```
-
---
-
-## Encoding profile
-
-Handshake returns `schemaVersion` and features. Default encoding remains JSON
-(`shared/encodings.js`); binary bulk uses `binaryStream*` + `push:binaryChunk`.