snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
3dd3861494e8a3e8b4ba1df024a2c6c19c908a3c
bare-operating-system/PEAR_RUN_DEPRICATION_WORK.md
T
Raven Scott 24fb26d8aa
Release rolling / release (push) Successful in 5m38s
Details
Ad doc
2026-07-31 13:52:38 -04:00

11 KiB
Raw Blame History

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:

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:

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/
Reference in New Issue View Git Blame Copy Permalink