hdms and holesail skills

2026-04-22 03:30:37 -04:00
parent 5731445ab4
commit 9200780e21
19 changed files with 340 additions and 12 deletions
@@ -0,0 +1,54 @@
+---
+name: bare-os-holesail
+version: 1.0.0
+description: Holesail P2P tunnels in Bare OS — managed state, initd unit bare-holesail, env toggles, and ctx.bare.holesail for /bin scripts.
+tags: [holesail, p2p, tunnel, initd, bare-modules]
+requires: [read_man_page, read_file, read_proc_file]
+---
+
+# bare-os-holesail Skill
+
+## 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, 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) and **`packages/bare-os-booter/lib/holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**).
+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`**).
+
+## Managed vs single-tunnel mode
+
+- **Managed (default)** — **`BARE_OS_HOLESAIL_MANAGED=1`**. Persisted tunnel list in **`BARE_OS_HOLESAIL_STATE`** (default **`~/.holesail/state.json`**, on the **personal** drive under the session **`$HOME`**). On unit start, each **enabled** entry gets its own **`holesail`** instance. Operator CLI: **`holesail list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`restart`**, **`enable`**, **`disable`**, plus **`path`** (prints resolved state path) and **`help`**.
+- **Single tunnel** — Set **`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 (e.g. **`BARE_OS_HOLESAIL_KERNEL_SERVER=1`**). Starts after the **`repl`** boot phase and before **`startBareInitd`**; teardown uses **`registerKernelShutdownHook`**. **`hs.pause()` / `hs.resume()`** tie into mobile suspend/resume with other subsystems.
+
+## 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`**.
+
+Initd starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
+
+## 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) for in-image synopsis; **`handbook/04-the-booter-runtime.md`** § **bare-holesail** is the prose source of truth for this repo.
+
+## Execution steps (for the agent)
+
+1. Confirm whether the question is **operator tunnels** (CLI + state file + initd) vs **guest scripting** (**`ctx.bare.holesail`**).
+2. If live behavior matters, prefer **`read_proc_file`** / initd journal paths the user can access over guessing from docs.
+3. Mention **AGPL** when the user plans to redistribute or ship a product that bundles **`holesail`**.
+
+## 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.