229 lines
11 KiB
Markdown
229 lines
11 KiB
Markdown
# Pear `run` deprecation work (2026-07-31)
|
||
|
||
This document records what landed on **2026-07-31** to retire **`pear run`** as the host path for seeder/booter and replace it with **Bare standalone binaries**, Gitea rolling releases, a curl|bash installer, and optional `pear install` / OTA channels.
|
||
|
||
**Why:** Pear v3 removed `pear run`. Host distribution is now packed Bare binaries (`bare-pack` / `bare-build`), published as rolling tarballs, not Pear-swapped `pear run` processes.
|
||
|
||
**Canonical docs after this work:**
|
||
|
||
- [docs/BINARY-RELEASE.md](docs/BINARY-RELEASE.md) — build, install, run, secrets
|
||
- [docs/PEAR-RUN.md](docs/PEAR-RUN.md) — legacy channel notes only (no `pear run` instructions)
|
||
|
||
**Commits (oldest → newest):**
|
||
|
||
| Hash | Subject |
|
||
|------|---------|
|
||
| `2b7025b2` | Bare standalone packaging, OTA entries, Gitea rolling, pear-run retirement |
|
||
| `cdf776a6` | Fix CI |
|
||
| `6105b8d4` | Add installer |
|
||
| `33937db1` | fixes (bin → package `standalone.mjs` / meta sync) |
|
||
| `633fe22b` | Updates (OTA stubs, package standalone entries) |
|
||
| `302c968b` | Update booter (`--datadir`, pear-runtime stub default, prune) |
|
||
| `d30b9184` | booter fixes (static host modules, drive-bundle eval, verify) |
|
||
| `d1725bc8` | Update README (canonical installer host) |
|
||
|
||
---
|
||
|
||
## 1. `2b7025b2` — Bare standalone packaging and pear-run retirement
|
||
|
||
### Packaging toolchain
|
||
|
||
New / primary scripts:
|
||
|
||
- **`scripts/bare-standalone.cjs`** — pack seeder or booter for a host (`linux-x64`, `linux-arm64`, `darwin-*`, `win32-*`):
|
||
- merges **`bare-node-runtime/imports`** with package/root import maps
|
||
- applies **`build/stubs/`** (e.g. `undici`, empty stubs) so pack does not pull Node-only graphs
|
||
- runs **`scripts/prepare-pack.mjs`** (kernel sync into seeder package, flatten `node_modules`)
|
||
- optional omit of heavy/native bits (e.g. sshcrypto) as needed for size
|
||
- embeds **`bare-runtime`** via bare-build and writes `out/bare-os-{product}-{host}/`
|
||
- **`scripts/make.cjs`** — orchestrates product × host builds
|
||
- **`scripts/hosts.cjs`** — shared 64-bit host list / parsing
|
||
- **`scripts/prepare-pack.mjs`** — kernel image sync + node_modules flatten before pack
|
||
- **`scripts/sign-macos-binary.cjs`** + vendored **`tools/rcodesign/`** (linux-x64 / linux-arm64) for Gatekeeper-friendly darwin signing from CI/Linux
|
||
|
||
### App entries (no `pear run`)
|
||
|
||
- **`bin/bare-os-seeder.mjs`** / **`bin/bare-os-booter.mjs`** — host entrypoints for packed binaries and `npm run os:*:bin`
|
||
- Root **`package.json`** scripts shifted off `pear run` toward `bare` / make / release helpers
|
||
- Seeder/booter **`package.json`** upgrade links kept for OTA / `pear install`
|
||
- **`packages/*/lib/paths.js`** adjusted for standalone / datadir layouts
|
||
- **`scripts/pm2-run-binary.sh`** + ecosystem updates — PM2 runs binaries instead of pear
|
||
- **`scripts/pm2-pear-run.sh`** left as legacy/shim-oriented, not the primary path
|
||
|
||
### OTA wrapper
|
||
|
||
- **`lib/bare-os-ota.mjs`** — optional pear-runtime OTA around the app; disable with **`--no-updates`** / **`BARE_OS_OTA_DISABLE=1`**
|
||
- Default packaging story: binaries can embed or stub pear-runtime (refined in later commits)
|
||
|
||
### Gitea rolling release
|
||
|
||
- **`.gitea/workflows/release-rolling.yml`** — on `main`, build and publish tag **`rolling`**
|
||
- **`scripts/gitea-rolling-release.sh`** — tarball assets + checksums; uses **`RELEASE_TOKEN`**
|
||
- Artifacts: `bare-os-{seeder,booter}-<ver>-<host>.tar.gz`, `by-arch-*.tar.gz`, `*.sha256`
|
||
- Seeder tarballs include **`kernel/`**
|
||
|
||
### Pear by-arch / offline stage (not CI pear-ci)
|
||
|
||
- **`scripts/pear-stage-by-arch.sh`** — stage `by-arch` trees offline with **`PEAR_PRIMARY_KEY`**
|
||
- **`ci/snapshot-seeder.json`** / **`ci/snapshot-booter.json`** — snapshots when staging
|
||
- CI publishes by-arch tarballs but does **not** require pear-ci secrets on every push
|
||
|
||
### Docs / product messaging
|
||
|
||
- New **`docs/BINARY-RELEASE.md`**
|
||
- **`docs/PEAR-RUN.md`** rewritten as **legacy notes** — explicitly: do not use `pear run`
|
||
- README + **`users-manual/03-running-seeder-and-booter.md`** updated for binary run paths
|
||
|
||
---
|
||
|
||
## 2. `cdf776a6` — Fix CI
|
||
|
||
- Hardened **`.gitea/workflows/release-rolling.yml`** and **`scripts/gitea-rolling-release.sh`** so rolling publish is reliable (token/env/docs alignment)
|
||
- Small **`docs/BINARY-RELEASE.md`** clarifications for the CI path
|
||
|
||
---
|
||
|
||
## 3. `6105b8d4` — Web / curl installer
|
||
|
||
- New **`scripts/install.sh`** — peardock-style interactive installer:
|
||
- roles: `--seeder` / `--booter` / `--both`
|
||
- `--yes` non-interactive, `--system` (Linux `/opt/bare-os` + systemd), `--no-updates`, `--tag` / `--version` / `--dir`
|
||
- downloads rolling assets from Gitea; user install under `~/.local/share/bare-os/{seeder,booter}/` with `~/.local/bin` shims
|
||
- **`deploy/bare-os-seeder.service`** / **`deploy/bare-os-booter.service`** for system installs
|
||
- README / BINARY-RELEASE / users-manual wired to the installer
|
||
|
||
---
|
||
|
||
## 4. `33937db1` — Entry graph fixes (pack must see `./index.js`)
|
||
|
||
Problem: packing only the thin bin wrapper missed the package graph (`MODULE_NOT_FOUND` for package `index.js` under `bare:/app.bundle/`).
|
||
|
||
- Bin entries resolve through package **`standalone.mjs`** next to the app so **`bare-pack`** traces `./index.js`
|
||
- **`bin/meta/{seeder,booter}.mjs`** + **`scripts/sync-bin-meta.mjs`** — keep meta/bin packaging metadata in sync
|
||
- **`scripts/prepare-pack.mjs`** tweak for that graph
|
||
|
||
---
|
||
|
||
## 5. `633fe22b` — Package `standalone.mjs` + OTA stubs
|
||
|
||
- **`packages/bare-os-{seeder,booter}/standalone.mjs`** — OTA prelude then app `index.js` (pack root for each product)
|
||
- Bin files slimmed to import runtime global + package standalone
|
||
- Stubs: **`build/stubs/pear-appdrive.cjs`**, **`build/stubs/pear-ref.cjs`**
|
||
- **`lib/bare-os-ota.mjs`** refined for standalone mkdir/storage behavior
|
||
|
||
---
|
||
|
||
## 6. `302c968b` — Datadir, slim OTA default, CodeRange-safe pack
|
||
|
||
### Host flags / storage
|
||
|
||
- **`lib/bare-os-host-flags.mjs`** — **`--datadir` / `--data-dir`** → **`BARE_OS_HOST_DATA`**
|
||
- Seeder/booter **`index.js`** + standalone honor datadir so Corestore lives under `<datadir>/corestore/{seeder,booter}`
|
||
|
||
### OTA default for packed binaries
|
||
|
||
- **`build/stubs/pear-runtime.cjs`** — stub so default pack does **not** embed full pear-runtime (Gitea rolling is the primary update path)
|
||
- Real pear-runtime only when packing with **`--with-ota`**
|
||
- **`lib/bare-os-ota.mjs`** — create OTA storage dirs when enabled; default OTA off unless `--updates` / `BARE_OS_OTA=1` (as documented on binaries)
|
||
|
||
### Pack size / OOM
|
||
|
||
- **`scripts/bare-standalone.cjs`** — prune hoisted duplicate deps under `packages/*/node_modules` before pack; rematerialize patched **`bare-ssh2`** for booter
|
||
- Target sizes ~90 MiB darwin / ~130 MiB linux booter (avoids V8 CodeRange OOM on fat embeds)
|
||
|
||
---
|
||
|
||
## 7. `d30b9184` — Booter standalone `ctx.bare` / drive-bundle correctness
|
||
|
||
After slim install, boot reached the guest shell but flooded:
|
||
|
||
- `[drive_bundle_eval_failed]` — `ADDON_NOT_FOUND` / `__require.addon is not a function` / Dynamic require of `path`
|
||
- `[ctx_bare_module_load_failed]` — dynamic `import('holesail')` / `b4a` / … from packed `bare-os-ctx-bare.js` (no per-referrer resolution under `bare:/app.bundle/`)
|
||
|
||
### Static module graph
|
||
|
||
- **`bin/bare-os-booter.mjs`** — static `import 'bare-node-runtime/global'` + package standalone
|
||
- **`packages/bare-os-booter/standalone.mjs`** — static pack-import anchors + `index.js`
|
||
- **`packages/bare-os-booter/lib/bare-os-host-ota-boot.mjs`** — OTA boot prelude as a static import from `index.js`
|
||
- **`packages/bare-os-booter/lib/bare-os-standalone-pack-imports.mjs`** — ensures host-modules stay in the pack graph
|
||
|
||
### Host module map + drive require
|
||
|
||
- **`packages/bare-os-booter/lib/bare-os-ctx-bare-host-modules.mjs`** — static imports of holesail, b4a, protomux, many `bare-*`, plus Node-builtin aliases (`path`→`bare-path`, `os`→`bare-os`, …)
|
||
- **`bare-os-ctx-bare.js`**:
|
||
- prefer packed host map in **`buildBareCtxObjectFromHost`** before dynamic `import(ent.package)`
|
||
- **`withDriveBundleGlobalRequire`** / **`createDriveBundleRequireWrapper`** — resolve builtins from the host map; **`require.addon`** via bare-module `createRequire` (static binding) + addon fallbacks across packed natives
|
||
- **`runDriveBundleSource`** — eval IIFEs with explicit `require`, `__filename`, `__dirname`
|
||
- on **`bare:`** standalone: host-import first, then drive merge; skip drive eval for optional non-`bundle:true` keys already satisfied by host (stops optional native tooling spam: bare-apk, bare-ffmpeg, …)
|
||
- pear-only load failures softened when `Pear` is absent
|
||
|
||
### Verify / CI quality gate
|
||
|
||
- **`scripts/verify-standalone-build.cjs`** — size ceilings per product/host, pear-runtime stub marker check, native-host booter smoke with `--datadir`
|
||
- **`scripts/make.cjs`** / rolling release script invoke verify after builds
|
||
- Workflow / release script small follow-ups
|
||
|
||
**Outcome verified locally:** full boot against a seeder → **0** `drive_bundle_eval_failed`, **0** `ctx_bare_module_load_failed` / pear ctx noise; guest welcome / shell; binaries installed under `~/.local/share/bare-os/booter/` and linux-x64 rebuilt for CI artifact shape.
|
||
|
||
---
|
||
|
||
## 8. `d1725bc8` — Canonical web installer URL
|
||
|
||
Installer host set to:
|
||
|
||
```bash
|
||
curl -fsSL https://install.bare-os.live | bash
|
||
```
|
||
|
||
Updated in:
|
||
|
||
- `README.md`
|
||
- `docs/BINARY-RELEASE.md`
|
||
- `scripts/install.sh` (header + `--help`)
|
||
- `users-manual/03-running-seeder-and-booter.md`
|
||
|
||
Gitea raw URL remains a documented fallback.
|
||
|
||
---
|
||
|
||
## End state (what operators use)
|
||
|
||
| Path | Status |
|
||
|------|--------|
|
||
| `pear run pear://…` | **Retired** (Pear v3 + docs) |
|
||
| Bare standalone binary (tarball / installer) | **Primary** |
|
||
| `pear install pear://…` + optional in-binary OTA | **Supported** (upgrade links; OTA often stubbed in pack) |
|
||
| Gitea `rolling` release | **CI publish** of host tarballs + by-arch trees |
|
||
| `curl \| bash` installer | **https://install.bare-os.live** |
|
||
| Dev without pack | `npm run os:seeder` / `os:booter` (or `:bin` entries) |
|
||
|
||
## Key files touched (index)
|
||
|
||
```
|
||
.bin/bare-os-{seeder,booter}.mjs
|
||
bin/meta/{seeder,booter}.mjs
|
||
build/stubs/{empty,undici,pear-runtime,pear-appdrive,pear-ref}.cjs
|
||
lib/bare-os-ota.mjs
|
||
lib/bare-os-host-flags.mjs
|
||
packages/bare-os-{seeder,booter}/standalone.mjs
|
||
packages/bare-os-booter/lib/bare-os-ctx-bare.js
|
||
packages/bare-os-booter/lib/bare-os-ctx-bare-host-modules.mjs
|
||
packages/bare-os-booter/lib/bare-os-host-ota-boot.mjs
|
||
packages/bare-os-booter/lib/bare-os-standalone-pack-imports.mjs
|
||
scripts/bare-standalone.cjs
|
||
scripts/make.cjs
|
||
scripts/hosts.cjs
|
||
scripts/prepare-pack.mjs
|
||
scripts/verify-standalone-build.cjs
|
||
scripts/gitea-rolling-release.sh
|
||
scripts/pear-stage-by-arch.sh
|
||
scripts/install.sh
|
||
scripts/sign-macos-binary.cjs
|
||
scripts/pm2-run-binary.sh
|
||
deploy/bare-os-*.service
|
||
.gitea/workflows/release-rolling.yml
|
||
docs/BINARY-RELEASE.md
|
||
docs/PEAR-RUN.md
|
||
tools/rcodesign/
|
||
```
|