MD Formatting fixes
This commit is contained in:
Raven Scott
@@ -10,46 +10,46 @@ requires: [read_man_page, read_file, read_proc_file]
|
||||
|
||||
## When to use
|
||||
|
||||
Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through Holepunch-style tunnels, **`/bin/holesail`** CLI, **`bare-holesail`** initd, **`BARE_OS_HOLESAIL_*`** environment variables, **`ctx.bare.holesail`** from drive bundles, **`~/.holesail/state.json`** persistence (**`seed`** / **`key`**), or licensing (**upstream `holesail` is AGPL-3.0**).
|
||||
Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through Holepunch-style tunnels, **`/bin/holesail**` CLI, `**bare-holesail**` initd, `**BARE_OS_HOLESAIL_***` environment variables, `**ctx.bare.holesail**` from drive bundles, `**~/.holesail/state.json**` persistence (`**seed**` / `**key`**), or licensing (**upstream `holesail` is AGPL-3.0**).
|
||||
|
||||
## Mental model
|
||||
|
||||
1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance), **`bare-holesail-managed.js`** ( **`state.json`** rows, **`ensure`**, **`SyncPersistedServerKey`** ), **`holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**), **`bare-os-www-holesail.js`**, **`bare-os-ssh-holesail.js`**.
|
||||
2. **Resolution order** under **`pear run`**: the booter prefers **`ctx.bare.holesail`** ( **`/lib/bare/bundles/holesail.js`** after drive merge), else host **`import.meta.resolve('holesail')`**, else eval of the drive IIFE bundle via **`ctx.vfs`** — **`/bin`** and **`/boot/init.js`** are **not** Node modules, so scripts must not **`require('holesail')`**.
|
||||
3. **Stock default**: initd unit **`bare-holesail`** is **on** when **`BARE_OS_HOLESAIL_INITD`** and **`BARE_OS_HOLESAIL_MANAGED`** are left at defaults (**`1`** in stock **`shellEnv`** unless the host clears them). Disable with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** (**`~/.config/bare-os/initd/disabled.txt`**).
|
||||
4. **Stock auto-rows** — **`bare-www-<port>`** after **`bare-os-www`** listens (**`BARE_OS_WWW_HOLESAIL=0`** disables merge). **`bare-ssh-<port>`** after **`bare-openssh`** listens (**`BARE_OS_SSH_HOLESAIL=0`** disables). **`bare-user-session-stack`** re-ensures SSH tunnel after **`bare-holesail`** starts if sshd was already listening.
|
||||
1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js**` (initd + optional early “kernel-path” instance), `**bare-holesail-managed.js**` ( `**state.json**` rows, `**ensure**`, `**SyncPersistedServerKey**` ), `**holesail-cli.js**` (`**ctx.bareOsRunHolesailCli**` for `**/bin/holesail**`), `**bare-os-www-holesail.js**`, `**bare-os-ssh-holesail.js`**.
|
||||
2. **Resolution order** under **`pear run**`: the booter prefers `**ctx.bare.holesail**` ( `**/lib/bare/bundles/holesail.js**` after drive merge), else host `**import.meta.resolve('holesail')**`, else eval of the drive IIFE bundle via `**ctx.vfs**` — `**/bin**` and `**/boot/init.js**` are **not** Node modules, so scripts must not `**require('holesail')`**.
|
||||
3. **Stock default**: initd unit **`bare-holesail**` is **on** when `**BARE_OS_HOLESAIL_INITD**` and `**BARE_OS_HOLESAIL_MANAGED**` are left at defaults (`**1**` in stock `**shellEnv**` unless the host clears them). Disable with `**BARE_OS_HOLESAIL_INITD=0**` or `**systemctl disable bare-holesail**` (`**~/.config/bare-os/initd/disabled.txt`**).
|
||||
4. **Stock auto-rows** — **`bare-www-<port>**` after `**bare-os-www**` listens (`**BARE_OS_WWW_HOLESAIL=0**` disables merge). `**bare-ssh-<port>**` after `**bare-openssh**` listens (`**BARE_OS_SSH_HOLESAIL=0**` disables). `**bare-user-session-stack**` re-ensures SSH tunnel after `**bare-holesail`** starts if sshd was already listening.
|
||||
|
||||
## Managed state (`state.json`)
|
||||
|
||||
- **Default path** — **`BARE_OS_HOLESAIL_STATE`** unset → **`~/.holesail/state.json`** (logical, under **`$HOME`**). Override env for a different logical path.
|
||||
- **Legacy merge** — If the primary file is empty/missing: **`/.bare/holesail/state.json`**, **`/.bare/holesail/guest/state.json`**, **`/home/guest/.holesail/state.json`** are merged once.
|
||||
- **`seed`** — Stable ctor secret: **64-char hex**, or valid **z32** suffix (migrated from legacy **`hs://…`**-only rows). Never replace **`seed`** with only the URL suffix written as ctor input.
|
||||
- **`key`** — Full shareable **`hs://…`** URL; written/updated after **`ready()`** (**`bareHolesailManagedSyncPersistedServerKey`**). **`holesail list`** shows live URL when tunnel runs.
|
||||
- **Daemon** — First **`startManagedConnectionsFromDisk`** pass starts all rows; **yield** one tick; **second pass** uses **`onlyNew`** so **`bare-os-www`** / **`bare-openssh`** can append rows without tearing down tunnels already started.
|
||||
- **Default path** — **`BARE_OS_HOLESAIL_STATE**` unset → `**~/.holesail/state.json**` (logical, under `**$HOME`**). Override env for a different logical path.
|
||||
- **Legacy merge** — If the primary file is empty/missing: **`/.bare/holesail/state.json**`, `**/.bare/holesail/guest/state.json**`, `**/home/guest/.holesail/state.json`** are merged once.
|
||||
- **`seed**` — Stable ctor secret: **64-char hex**, or valid **z32** suffix (migrated from legacy `**hs://…**`-only rows). Never replace `**seed`** with only the URL suffix written as ctor input.
|
||||
- **`key**` — Full shareable `**hs://…**` URL; written/updated after `**ready()**` (`**bareHolesailManagedSyncPersistedServerKey**`). `**holesail list`** shows live URL when tunnel runs.
|
||||
- **Daemon** — First **`startManagedConnectionsFromDisk**` pass starts all rows; **yield** one tick; **second pass** uses `**onlyNew**` so `**bare-os-www**` / `**bare-openssh`** can append rows without tearing down tunnels already started.
|
||||
|
||||
## Managed vs single-tunnel mode
|
||||
|
||||
- **Managed (default)** — **`BARE_OS_HOLESAIL_MANAGED=1`**. Operator CLI: **`holesail list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`restart`**, **`enable`**, **`disable`**, **`path`**, **`help`**.
|
||||
- **Single tunnel** — **`BARE_OS_HOLESAIL_MANAGED=0`**, then exactly one of **`BARE_OS_HOLESAIL_SERVER=1`** or **`BARE_OS_HOLESAIL_CLIENT=1`**, and in client mode **`BARE_OS_HOLESAIL_KEY=…`**. Optional: **`BARE_OS_HOLESAIL_SECURE`**, **`PORT`**, **`HOST`**, **`UDP`**, **`LOG`**.
|
||||
- **Managed (default)** — **`BARE_OS_HOLESAIL_MANAGED=1**`. Operator CLI: `**holesail list**`, `**add**`, `**remove**`, `**start**`, `**stop**`, `**restart**`, `**enable**`, `**disable**`, `**path**`, `**help`**.
|
||||
- **Single tunnel** — **`BARE_OS_HOLESAIL_MANAGED=0**`, then exactly one of `**BARE_OS_HOLESAIL_SERVER=1**` or `**BARE_OS_HOLESAIL_CLIENT=1**`, and in client mode `**BARE_OS_HOLESAIL_KEY=…**`. Optional: `**BARE_OS_HOLESAIL_SECURE**`, `**PORT**`, `**HOST**`, `**UDP**`, `**LOG`**.
|
||||
|
||||
## Early booter (“kernel-path”) instance
|
||||
|
||||
Separate from initd: enable with **`BARE_OS_HOLESAIL_KERNEL=1`** and the **`BARE_OS_HOLESAIL_KERNEL_*`** mirror env vars. Starts after the **`repl`** boot phase and before **`startBareInitd`**; teardown uses **`registerKernelShutdownHook`**. **`hs.pause()` / `hs.resume()`** tie into mobile suspend/resume.
|
||||
Separate from initd: enable with **`BARE_OS_HOLESAIL_KERNEL=1**` and the `**BARE_OS_HOLESAIL_KERNEL_***` mirror env vars. Starts after the `**repl**` boot phase and before `**startBareInitd**`; teardown uses `**registerKernelShutdownHook**`. `**hs.pause()` / `hs.resume()`** tie into mobile suspend/resume.
|
||||
|
||||
## Operator CLI quick reference
|
||||
|
||||
From **`holesail-cli.js`** help text:
|
||||
|
||||
- **`holesail add ID --server|--client`** with optional **`--key`**, bare **`hs://…`** token (no **`--key`** prefix), **`--port`**, **`--host`**, **`--udp`**, **`--secure` / `--no-secure`**, **`--log`**.
|
||||
- **`holesail remove ID`**, **`start|stop|restart ID`**, **`enable|disable ID`**.
|
||||
- **`holesail add ID --server|--client**` with optional `**--key**`, bare `**hs://…**` token (no `**--key**` prefix), `**--port**`, `**--host**`, `**--udp**`, `**--secure` / `--no-secure**`, `**--log`**.
|
||||
- **`holesail remove ID**`, `**start|stop|restart ID**`, `**enable|disable ID`**.
|
||||
|
||||
Managed **`bare-holesail`** starts after **`kernel-logger`** and **`bare-os-www`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`**.
|
||||
Managed **`bare-holesail**` starts after `**kernel-logger**` and `**bare-os-www**` by default. Logs: `**/var/log/bare-os/holesail.log**`. Example unit drop-in: `**/etc/bare-os/units/bare-holesail.unit.example`**.
|
||||
|
||||
## Debugging and safety
|
||||
|
||||
- **`BARE_OS_HOLESAIL_DEBUG=1`** — extra console lines (**URLs only**; keys are not logged in full).
|
||||
- Do **not** paste full connection secrets into chat or commit logs; redact **`hs://`** payloads when summarizing.
|
||||
- **`read_man_page holesail`** (after a coreutils/man build); **`handbook/04-the-booter-runtime.md`** § **bare-holesail**, § **bare-os-www**, § **bare-openssh** — prose source of truth.
|
||||
- **`read_man_page holesail**` (after a coreutils/man build); `**handbook/04-the-booter-runtime.md`** § **bare-holesail**, § **bare-os-www**, § **bare-openssh** — prose source of truth.
|
||||
|
||||
## Execution steps (for the agent)
|
||||
|
||||
@@ -60,4 +60,4 @@ Managed **`bare-holesail`** starts after **`kernel-logger`** and **`bare-os-www`
|
||||
## Constraints
|
||||
|
||||
- Read-only unless the user explicitly authorizes changing env, initd disables, or **`holesail add`** state.
|
||||
- Do not assume **`holesail`** is **`import()`**-able from **`pear:`** without **`ctx.bare`** or the drive bundle.
|
||||
- Do not assume **`holesail**` is `**import()**`-able from `**pear:**` without `**ctx.bare`** or the drive bundle.
|
||||
|
||||
Reference in New Issue
Block a user