From 9959e09fe247cfa5f043d2a21e229f7ea936d101 Mon Sep 17 00:00:00 2001 From: leetcrypt Date: Sun, 7 Jun 2026 13:20:07 -0700 Subject: [PATCH] docs(scripts): add --help to remaining scripts; document scripts + layout in README - Add a -h/--help guard (prints the usage header) to the five scripts that lacked one: smoke.sh, smoke-e2e.sh, test-features.sh, demo-save-load.sh, sandbox-bootstrap.sh. All 15 hh/scripts/*.sh now respond to --help. - README: new "Scripts" section detailing every script (setup, hosting, sandbox provisioning, tests) and noting each takes --help; plus an archive note for the film-* recording scripts. - README: new "Window layout" section documenting live pane resizing (F4 fullscreen, click/F5 to select + arrows to resize) and the /layout save/load/list/rm/reset presets, with matching keybinding-table rows. Co-Authored-By: Claude Opus 4.6 --- README.MD | 75 ++++++++++++++++++++++++++++++++- hh/scripts/demo-save-load.sh | 5 +++ hh/scripts/sandbox-bootstrap.sh | 7 +++ hh/scripts/smoke-e2e.sh | 5 +++ hh/scripts/smoke.sh | 5 +++ hh/scripts/test-features.sh | 5 +++ 6 files changed, 100 insertions(+), 2 deletions(-) diff --git a/README.MD b/README.MD index 6b1f933..dc9021f 100644 --- a/README.MD +++ b/README.MD @@ -50,8 +50,7 @@ Encrypted chat that runs in your terminal. You host the server, you control the | `cmd_chat/agent/` | The model-agnostic AI agent bridge (joins a room as an encrypted client) | | `models.toml` | Named provider profiles for `/ai start ` (see `docs/providers.md`) | | `docs/providers.md` | Connect any model — profiles, flags, discovery, bring-your-own-provider | -| `hh/scripts/lets-hack.sh` | Spin up a local test "clergy" in tmux (server + N client panes) | -| `hh/scripts/bootstrap-ai.sh` | Optional: install Ollama + pull a model for the local `/ai` agent | +| `hh/scripts/` | Helper scripts — setup, hosting, sandbox provisioning, tests (see [Scripts](#scripts); each takes `-h`/`--help`) | | `hh/direnv-autostart/` | `cd` into a directory to auto-launch a session (direnv) | ## Quick start @@ -169,6 +168,8 @@ Type to chat. Slash commands and keys: | `Ctrl+C` (while driving) | Interrupt the running command | | `Ctrl+R` | Reconnect after a drop | | `↑/↓` · `PgUp/PgDn` · mouse wheel | Scroll chat / sandbox scrollback | +| `F4` · `F5` · click | Layout: fullscreen terminal · select a pane to resize (then arrows · `Esc`) — see [Window layout](#window-layout) | +| `/layout save \| load \| list \| rm \| reset` | Save / recall named pane arrangements | ### The shared sandbox @@ -289,6 +290,32 @@ with `Ctrl+Alt+P` (and save it to disk), or load your own TOML at launch with `--theme ` (see `hh/themes/`). Each theme defines its own sigil, colours, and roster width. +### Window layout + +The chat, roster (clergy), and sandbox-terminal panes are resizable and can be +fullscreened — live, with no restart. Resizing the terminal also re-syncs the +shared PTY grid so everyone in the room sees the same dimensions. + +- **Fullscreen** — `F4` cycles the sandbox terminal fullscreen → chat + fullscreen → back to the split. The 3-line input bar always stays visible, so + `F4` always brings you back. +- **Resize a pane** — click a pane (or press `F5` to cycle the selection: + terminal → chat → roster). The selected pane gets a bold accent border and an + `✎` marker in its title. Then: + - `↑` / `↓` grow / shrink the **terminal** or **chat** pane's height share + - `←` / `→` narrow / widen the **roster** column (down to hidden) + - `Esc` or `Enter` finishes editing. +- **Presets** — save the current arrangement and recall it later: + + | Command | Effect | + |---|---| + | `/layout` | Show the current arrangement + a reminder of the keys | + | `/layout save ` | Save the current split/roster to `hh/layouts/.toml` | + | `/layout load ` (or `/layout `) | Re-apply a saved layout | + | `/layout list` | List saved presets | + | `/layout rm ` | Delete a saved preset | + | `/layout reset` | Restore the default split | + ### Staying connected If the connection drops (network blip, laptop sleep), press `Ctrl+R` to re-run @@ -296,6 +323,50 @@ the SRP handshake and re-attach — no restart needed. If you were hosting the sandbox, it's re-announced so the room re-syncs the shared shell. Chat keeps up to ~4000 lines of scrollback; the sandbox terminal keeps 2000. +## Scripts + +Everything lives in `hh/scripts/`; run from the `hh/` directory. **Every script +supports `-h` / `--help`** for full usage. + +**Setup** + +| Script | What it does | +|---|---| +| `bootstrap.sh` | One-shot first-run setup: checks prereqs, creates the Python venv, installs server deps, builds the Rust client (plus the AI layer unless `--no-ai`). | +| `bootstrap-ai.sh` | Optional AI layer: runs the baseline, then installs Ollama and pulls a default local model for the `/ai` agent. | + +**Run a session** + +| Script | What it does | +|---|---| +| `lets-hack.sh` | Local demo/test: boots a `--no-tls` server and tiles one TUI client pane per user in tmux. | +| `host-house.sh` | Host a real room *and* take a seat — builds the client, starts the server, and opens your own client, all in tmux. | +| `host-room.sh` | Host the server only (no seat): mints a password, frees the port, prints the LAN/Tailscale join banner, runs in the foreground. | +| `connect.sh` | Join a room with the password kept RAM-only (no-echo prompt). Flags: `--sync` (pull latest code before building), `--tls`, `--insecure`, `--no-build`, `-P PORT`. | + +**Sandbox provisioning** — driven by the client at runtime; you rarely run these by hand + +| Script | What it does | +|---|---| +| `ensure-docker.sh` | Install Docker and/or start its daemon (idempotent; `--check`/`--plan`/`--yes`). Invoked by `/sbx launch docker`. | +| `ensure-multipass.sh` | Install Multipass. Invoked by `/sbx launch multipass`. | +| `ensure-vbox.sh` | Install VirtualBox (warns on Secure Boot). Invoked by `/sbx launch virtualbox` and `/sbx gui`. | +| `vbox-new.sh` | Create + boot a fresh Ubuntu VirtualBox VM via cloud-init. Invoked by `/sbx launch virtualbox`. | +| `sandbox-bootstrap.sh` | Baseline dev-tool install piped into a Docker sandbox at provision time (package list from `sandbox-tools.json`). | +| `sandbox-tools.json` | Editable package list consumed by `sandbox-bootstrap.sh`. | + +**Tests & demos** — for contributors + +| Script | What it does | +|---|---| +| `smoke-e2e.sh` | Headless CI smoke test: server + two real TUI clients in tmux; asserts SRP join, chat round-trip, `/sbx` dispatch. | +| `smoke.sh` | Crypto smoke test: Rust unit tests → SRP self-test → live server → Rust handshake → Python decrypts the Rust-sent message. | +| `test-features.sh` | Broad TUI regression: drives owner + member panes and scrapes the screen to assert ~13 UI features. | +| `demo-save-load.sh` | PoC harness proving the persistent-sandbox flow (`/sbx save` → quit → `/sbx load`, code intact). | + +`hh/scripts/archive/` holds personal demo-*recording* scripts (`film-*.sh`) that +depend on external video tooling — not needed to use or develop hack-house. + ## Configuration | Variable | Where | Effect | diff --git a/hh/scripts/demo-save-load.sh b/hh/scripts/demo-save-load.sh index 4076ed6..b49e9f9 100755 --- a/hh/scripts/demo-save-load.sh +++ b/hh/scripts/demo-save-load.sh @@ -14,6 +14,11 @@ # --keep leave the server, container, image and tmux sessions up afterwards set -uo pipefail +# -h/--help: print the usage header above and exit. +case "${1:-}" in + -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;; +esac + # ---- config ----------------------------------------------------------------- REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" # Pick a free TCP port so we never collide with a stale server from another diff --git a/hh/scripts/sandbox-bootstrap.sh b/hh/scripts/sandbox-bootstrap.sh index b84d96a..be434dc 100644 --- a/hh/scripts/sandbox-bootstrap.sh +++ b/hh/scripts/sandbox-bootstrap.sh @@ -12,6 +12,13 @@ # HH_SBX_PKGS="vim tmux ripgrep" ./host-house.sh ... set -uo pipefail +# -h/--help: print the usage header above and exit. (No effect in normal use — +# hh pipes this to `bash -s` inside the container with no args; the flag is for +# running it standalone to read what it does.) +case "${1:-}" in + -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;; +esac + SENTINEL=/var/lib/hh-bootstrap.done [[ -f "$SENTINEL" ]] && exit 0 # this container is already provisioned diff --git a/hh/scripts/smoke-e2e.sh b/hh/scripts/smoke-e2e.sh index 35af3e0..05ad311 100755 --- a/hh/scripts/smoke-e2e.sh +++ b/hh/scripts/smoke-e2e.sh @@ -15,6 +15,11 @@ # Env overrides: PY= BIN= PORT= PW= set -uo pipefail +# -h/--help: print the usage header above and exit. +case "${1:-}" in + -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;; +esac + REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" # Python: prefer the repo venv locally, fall back to PATH (CI installs into the # job's own interpreter). diff --git a/hh/scripts/smoke.sh b/hh/scripts/smoke.sh index 131b55c..fc62524 100755 --- a/hh/scripts/smoke.sh +++ b/hh/scripts/smoke.sh @@ -6,6 +6,11 @@ # Run from anywhere: hh/scripts/smoke.sh set -uo pipefail +# -h/--help: print the usage header above and exit. +case "${1:-}" in + -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;; +esac + HERE="$(cd "$(dirname "$0")/.." && pwd)" # .../hh ROOT="$(cd "$HERE/.." && pwd)" # repo root PY="$ROOT/.venv/bin/python" diff --git a/hh/scripts/test-features.sh b/hh/scripts/test-features.sh index 838dc69..c8f340d 100755 --- a/hh/scripts/test-features.sh +++ b/hh/scripts/test-features.sh @@ -14,6 +14,11 @@ # tmux attach -t hh-autotest set -uo pipefail +# -h/--help: print the usage header above and exit. +case "${1:-}" in + -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;; +esac + HERE="$(cd "$(dirname "$0")/.." && pwd)" # .../hh ROOT="$(cd "$HERE/.." && pwd)" # repo root PY="$ROOT/.venv/bin/python"