116 lines
4.6 KiB
Markdown
116 lines
4.6 KiB
Markdown
# Chapter 7 — Apps beyond the shell
|
||
|
||
Bare OS now ships a **P2P App Store** client (`/bin/appstore`) and **guest Pear tooling** (`/bin/pear`) so “applications” can be authored, published, installed, and launched **inside the shell** without a second GUI runtime.
|
||
|
||
This chapter orients you to what is **real today** versus what still requires a **host Pear** process.
|
||
|
||
---
|
||
|
||
## Four application models
|
||
|
||
| Model | When to use | Entry points |
|
||
| --- | --- | --- |
|
||
| **Shell + `/bin` + files** | Scripts, pipelines, git on the VFS | `$HOME`, `run(ctx, argv)` utilities |
|
||
| **Guest TUI** | Full-screen terminal apps in the session | `ctx.tui.run(model)` — [Chapter 20](20-tui-and-sdk.md), **`tui demo`** |
|
||
| **Pear app (guest)** | P2P apps with `pear://` distribution | `pear init` → `stage` → `release` → `appstore install` → `launch` |
|
||
| **Host Pear app** | Custom booter/seeder images, native addons, desktop Pear | Repo root `pear run`, new Pear project (Chapter 1) |
|
||
|
||
Most **end-user Pear apps** you build in Bare OS follow the **guest Pear + App Store** row. See **[Guest Pear and App Store workflow](../docs/guides/guest-pear-and-appstore-workflow.md)** for copy-paste commands.
|
||
|
||
---
|
||
|
||
## Guest Pear pipeline (`/bin/pear`)
|
||
|
||
Implemented in `packages/bare-os-coreutils` (`pear.js`, `pear-stage.js`, `pear-release.js`).
|
||
|
||
```bash
|
||
pear init
|
||
cd ~/pear-projects/my-pear-app
|
||
pear stage
|
||
login # unlock identity / HDMS
|
||
pear release .
|
||
pear seed .
|
||
```
|
||
|
||
- **`pear stage`** — Writes `<project>/.pear/stage/` (`sources/`, `package.json`, `app.bundle.js`, `stage.json`).
|
||
- **`pear release`** — Mirrors the stage tree onto a writable HDMS mount (`/mnt/pear-<name>/`) and prints **`pear://`** links (uses HDMS registry keys; does not require host Pear CLI).
|
||
- **`pear seed`** — Best-effort Hyperswarm flush so peers can replicate the release drive.
|
||
|
||
Release metadata is stored in **`<project>/.pear/release.json`**.
|
||
|
||
---
|
||
|
||
## P2P App Store (`/bin/appstore`)
|
||
|
||
Implemented in `packages/bare-os-coreutils` (`appstore.js`, `appstore-pear.js`, `p2p-suite.js` preamble).
|
||
|
||
```bash
|
||
appstore install my-app pear://0.<length>.<key> --yes
|
||
appstore launch my-app
|
||
```
|
||
|
||
- **`install`** — Fetches the `pear://` release tree (local HDMS mount with matching key, or ephemeral readonly HDMS fetch) into `~/.appstore/packages/<name>/` (or `/mnt/appstore/packages/<name>/` when the store HDMS drive is mounted).
|
||
- **`launch`** — Runs the materialized entry script (`sources/index.js` or `package.json` `main`) in the guest shell; output appears on **`ctx.console`**.
|
||
- **`update`** — Re-fetches from the package’s stored `pearLink`.
|
||
- **`setup`** — Prints how to create/mount the optional **`appstore`** HDMS label.
|
||
|
||
Design and trust model: **[p2p-app-store.md](../docs/design/p2p-app-store.md)**.
|
||
|
||
---
|
||
|
||
## The default platform: shell + `/bin` + git
|
||
|
||
Workflows that are not Pear-packaged still use:
|
||
|
||
- Scripts in **`$HOME`** (`run(ctx, argv)`).
|
||
- Pipelines and redirection (simulated stdin/stdout).
|
||
- **`git`** on the VFS ([Handbook ch.8](../handbook/08-git-on-bare-os.md)).
|
||
|
||
---
|
||
|
||
## initd, cron, and services
|
||
|
||
**initd** — User units under `~/.config/bare-os/units/`. `appstore services` can generate initd unit stubs for packages that declare a service manifest (see `appstore.js`).
|
||
|
||
**Timers / cron** — See [Chapter 11](11-kernel-pear-cookbook.md) and handbook ch.4.
|
||
|
||
---
|
||
|
||
## HDMS and `/mnt`
|
||
|
||
After **login**, HDMS mounts extra Hyperdrives under **`/mnt/<label>/`**. Pear releases use labels like **`pear-my-pear-app`**. The App Store prefers label **`appstore`** at **`/mnt/appstore`**.
|
||
|
||
User scripts should use **`ctx.vfs`** rather than hard-coding drive handles.
|
||
|
||
---
|
||
|
||
## Replacing the kernel
|
||
|
||
Shipping a different **`/boot/init.js`** remains a **kernel image** change (non-interactive worker, custom menu, etc.). Pear **user apps** do not require replacing the stock kernel.
|
||
|
||
---
|
||
|
||
## When you need a new host Pear app
|
||
|
||
Use a **new Pear application** on the host when you need:
|
||
|
||
- A different system image or booter embedding model
|
||
- Native addons unsuitable for `AsyncFunction` `/bin` scripts
|
||
- Desktop/mobile Pear runtime features
|
||
|
||
Guest **`pear release`** still produces valid **`pear://`** links consumable by host **`pear run`**.
|
||
|
||
---
|
||
|
||
## See also
|
||
|
||
- [Guest Pear and App Store workflow](../docs/guides/guest-pear-and-appstore-workflow.md)
|
||
- [Chapter 20 — Guest TUI](20-tui-and-sdk.md)
|
||
- [Chapter 12 — Bare modules and Pear](12-bare-modules-and-pear-ecosystem.md)
|
||
- [Chapter 3 — Kernel](03-kernel-boot-init.md)
|
||
- [Handbook — Identity, vault, HDMS](../handbook/05-identity-vault-and-hdms.md)
|
||
|
||
---
|
||
|
||
[← Extending /bin](06-extending-bin-coreutils.md) · [Testing →](08-testing-and-debugging.md)
|