home-hosted 0.7.1 → 0.7.3

package/AGENTS.md

@@ -3,12 +3,14 @@
 `home-hosted` is a Node 24 / TypeScript harness for self-hosted servers: `up` starts a Hono/srvx
 panel (default `127.0.0.1:3999`) that supervises the entries in each workspace's
 `servers.config.json` and serves a UI. User docs: `README.md`, `docs/SERVERS.md` (entries and port
-conflicts), `docs/NOTIFICATIONS.md`, `docs/DDNS.md`; UI authors: `docs/UI_CREATION.md`.
+conflicts), `docs/NOTIFICATIONS.md`, `docs/DDNS.md`, `docs/REVERSE_PROXY.md`; UI authors:
+`docs/UI_CREATION.md`.
 
 State lives only in `$HHOSTED_HOME/.hh` (default `~/.home-hosted/.hh`). Global files sit at its top
-level: `settings.json` (listener, auth, TLS policy, host vitals, backups), `workspaces.json`,
-`.control-secrets.json` (0600: password hash, API token hash), `.tls/`, `.backups/`, `.ui/`, `.logs/`
-(the panel console), and `run.json` — the live daemon's pid/url/token, 0600. Every workspace owns
+level: `settings.json` (listener, auth, TLS policy, host vitals, backups, reverse proxy),
+`workspaces.json`, `.control-secrets.json` (0600: password hash, API token hash), `.tls/`,
+`.backups/`, `.ui/`, `.logs/` (the panel console), `.proxy/` (the reverse-proxy engine, its generated
+configuration and its nanny state), and `run.json` — the live daemon's pid/url/token, 0600. Every workspace owns
 `.hh/<id>/`: `settings.json` (server defaults, log retention, notifications, DDNS), `servers.config.json`,
 `.secrets.json` (0600: Telegram bot token and DDNS credentials sealed with AES-256-GCM under
 `HHOSTED_DDNS_SECRET`), `.logs/`, and `.state/` (a persistent entry's nanny state plus its 0600 spawn
@@ -109,12 +111,13 @@ a minor without one.
   `identity` (which port holder is this entry's own successor: marker first, then resolved image +
   argv), `nanny` (a persistent entry's spec/state files and the liveness rules for one),
   `log-tail` (an offset reader that survives rotation and truncation), `ddns/` (one `DdnsProvider` per
-  registrar over one HTTP call each, plus `ip` and `zone` helpers), health-check, host, telegram,
-  archive.
+  registrar over one HTTP call each, plus `ip` and `zone` helpers), `proxy/` (the reverse-proxy
+  engines this build can drive: where the binary comes from and how to start it — the route model
+  stays the panel's), health-check, host, telegram, archive.
 - `src/services/` — stateful orchestration: `panel` (one `WorkspaceRuntime` per workspace, workspace
   CRUD, and the single aggregate state frame — every per-workspace service hangs off it), supervisor,
   control-server, config-watch, state, auth + exposure, dependencies, history, log-buffer/log-files,
-  notifications, host-monitor, ddns, backups, tls, ui, plus `init` (the scaffold behind
+  notifications, host-monitor, ddns, proxy, backups, tls, ui, plus `init` (the scaffold behind
   `home-hosted init`: a manifest, a `.gitignore`, and the prompts stay in the CLI), `nanny` (the
   process a persistent entry runs under) and `log-relay` (the tailer that feeds its lines to the
   supervisor). It names no server — the scaffold must stay as neutral as the supervisor.
@@ -132,23 +135,28 @@ a minor without one.
   `repo`/`tag`/`asset` (which release carries it, for `ui-update`) and `unix` (when it was built).
   `UiService` carries those fields into the installed `$HHOSTED_HOME/.ui/ui.json` unchanged and adds
   `uploadedAt`/`files` of its own.
-- **Bumping a UI ships a new asset, so its `ui.json` is part of the change.** Any commit that alters
-  a UI under `uis/<name>/` bumps that `ui.json`'s `version` and sets `unix` to the commit's own epoch
-  seconds: patch for a fix, minor for a feature, and **major only for a rewrite or a restyle**. The
-  number is what tells a person how big the change is — `ui-update` prints it and holds it against
-  the release it is offering. `tag` is what pairs an official UI with its panel, and it is **stamped
-  by `build-uis.mjs`**, not trusted from the source file: a UI zip is built before its release is cut,
-  so the committed value is always a release behind the asset it ends up inside. The release workflow
-  passes `HHOSTED_UI_TAG`; anywhere else the build stamps `v<package.json version>`. Do not hand-edit
-  `tag` to chase a release — a stale one makes `ui-update` re-install the same UI on every boot.
+- **Bumping a UI ships a new asset, so its `ui.json` is part of the change — and it is bumped once,
+  when the commit is made, not on every edit.** A commit that alters what a UI *ships*
+  (`uis/<name>/src`, `public`, its build inputs — not `test/`, which is not in the asset) raises that
+  `ui.json`'s `version`: patch for a fix, minor for a feature, and **major only for a rewrite or a
+  restyle**. The number is what tells a person how big the change is — `ui-update` prints it and holds
+  it against the release it is offering. `unix` is that commit's own epoch, never a leftover from
+  whenever the file was edited: `scripts/stamp-uis.mjs` runs from the pre-commit hook, stamps it, and
+  refuses a commit that changed a shipped UI without raising its version. `tag` is what pairs an
+  official UI with its panel, and it is **stamped by `build-uis.mjs`**, not trusted from the source
+  file: a UI zip is built before its release is cut, so the committed value is always a release behind
+  the asset it ends up inside. The release workflow passes `HHOSTED_UI_TAG`; anywhere else the build
+  stamps `v<package.json version>`. Do not hand-edit `tag` to chase a release — a stale one makes
+  `ui-update` re-install the same UI on every boot.
 - `bin/home-hosted.mjs` — the published bin: `dist/cli.js`, or `src/cli.ts` through tsx when the
   build is missing (a linked checkout).
 - `scripts/` — `build-uis.mjs` (build one UI, optionally zip it), `typecheck-uis.mjs`,
   `capture-media.mjs` (the README's media), `check-release-version.mjs` and `release-notes.mjs`
   (used by the release workflow), `dev.mjs` (`pnpm dev`).
-- `docs/` — the topic docs (`SERVERS.md`, `NOTIFICATIONS.md`, `DDNS.md`, `UI_CREATION.md`),
+- `docs/` — the topic docs (`SERVERS.md`, `NOTIFICATIONS.md`, `DDNS.md`, `REVERSE_PROXY.md`,
+  `UI_CREATION.md`),
   `mockups/*.html` (hand-written UI examples in four directions) and `media/*`: their screenshots plus
-  the README's `tour.gif`, all regenerated by `pnpm run media`. Only the four `.md` files are
+  the README's `tour.gif`, all regenerated by `pnpm run media`. Only the five `.md` files are
   published; the media is a build artifact.
 
 ## Conventions
@@ -293,6 +301,12 @@ either is a last resort, and never an accidental one.
   `$HHOSTED_HOME/.hh/.ui` overrides the packaged UI at runtime.
 - **A restore writes only where a config says** — archive allowlist, `origin` matching first,
   symlinks never recreated.
+- **The reverse proxy's engine is a process the panel owns, not a server entry.** Its generated
+  configuration is applied through the engine's admin API (atomic, never hand-edited), the engine runs
+  under the same nanny a `persistent: true` entry uses so a panel restart does not drop the socket,
+  and its admin endpoint stays panel-side — a unix socket in a `0700` directory, loopback plus the
+  engine's origin check on Windows. A route that points at the panel is exposure and obeys
+  `checkProxyExposure()`, the same bar as a non-loopback bind.
 - **Cross-platform.** Linux/macOS/Windows: `/proc` vs `ps` vs Win32_Process, process groups vs
   `taskkill /T`, graceful fallbacks, no shell utilities assumed.
 - **Writes are atomic** (`writeFileAtomic`) and validated before commit.
@@ -345,6 +359,9 @@ either is a last resort, and never an accidental one.
   file-only blocks on their own. The copy has to be **detached**, too: a shallow one leaves a nested
   group (`health.http`) aliased to live state, so an edit to "Healthy below status" mutated the very
   config the guard compared against and the next frame reset the whole editor (`cloneHealth`).
+- **An absolutely positioned element inside a *static* scroll container resolves against the
+  page, not the scroller** — an `sr-only` label in a table row was enough to give the document a
+  second, empty scrollbar. The shell's `main` carries `relative` for that reason; keep it there.
 - **A dialog's footer has to be a flex sibling of a scrolling body** (`uis/stock/src/components/ui/Modal.vue`):
   the sheet is `flex flex-col` with `max-h-[88dvh]`, the body `min-h-0 flex-1 overflow-y-auto`. When
   only the body carried a max-height, a tall form pushed its own save button below the clipped
@@ -400,5 +417,5 @@ either is a last resort, and never an accidental one.
 ## Publishing
 
 `pnpm pack` runs `prepack` (a full build) and ships `bin/`, `dist/`, `uis/stock/dist`, `README.md`, `docs/DDNS.md`,
-`docs/SERVERS.md`, `docs/NOTIFICATIONS.md`, `docs/UI_CREATION.md`, `AGENTS.md` and `LICENSE`. The bin falls back to tsx so `pnpm link` works before a
+`docs/SERVERS.md`, `docs/NOTIFICATIONS.md`, `docs/REVERSE_PROXY.md`, `docs/UI_CREATION.md`, `AGENTS.md` and `LICENSE`. The bin falls back to tsx so `pnpm link` works before a
 build; `vue`/`vue-router` are devDependencies because the UIs are prebuilt.

package/README.md

@@ -8,7 +8,7 @@
 
 Point it at the things you run — a gateway, a media server, a bot, a database — and it starts
 them, watches them, restarts what dies, and shows you one page of what is going on. Split them into
-[workspaces](#-workspaces) when one panel holds more than one setup. Or
+[workspaces](#-workspaces) when one panel holds more than one setup. And
 [BYOU](#-bring-your-own-ui-byou), for a specialized UI that fits you exactly.
 
 [![npm](https://img.shields.io/npm/v/home-hosted.svg)](https://www.npmjs.com/package/home-hosted)
@@ -17,7 +17,7 @@ them, watches them, restarts what dies, and shows you one page of what is going
 [![License](https://img.shields.io/npm/l/home-hosted.svg)](./LICENSE)
 [![Node](https://img.shields.io/node/v/home-hosted.svg)](https://nodejs.org)
 
-[🚀 Quick start](#-quick-start) · [🗂 Workspaces](#-workspaces) · [🧩 Servers](./docs/SERVERS.md) · [🤖 Agents & API](#-agents-scripts-and-tools) · [✨ Features](#-features) · [🛠 CLI](#-cli) · [🔔 Notifications](./docs/NOTIFICATIONS.md) · [🎨 BYOU](#-bring-your-own-ui-byou)
+[🚀 Quick start](#-quick-start) · [🗂 Workspaces](#-workspaces) · [🧩 Servers](./docs/SERVERS.md) · [🤖 Agents & API](#-agents-scripts-and-tools) · [✨ Features](#-features) · [🛠 CLI](#-cli) · [🔔 Notifications](./docs/NOTIFICATIONS.md) · [🔀 Reverse proxy](./docs/REVERSE_PROXY.md) · [🎨 BYOU](#-bring-your-own-ui-byou)
 
 </div>
 
@@ -213,19 +213,26 @@ default workspace.
 <details>
 <summary><b>🌐 The endpoints worth knowing</b></summary>
 
-| | |
-| --- | --- |
-| `GET /api/state` | the full snapshot: global settings, every workspace with its servers, host vitals |
-| `GET`/`POST /api/workspaces`, `PATCH`/`DELETE /api/workspaces/:id` | the registry: list, create, rename, remove |
-| `GET /api/events` | SSE: the live state, plus logs (`?logs=0`, `?serverId=…`; a `server` payload carries its `workspaceId`) |
-| `GET /api/servers/:id/stream` | SSE: one server's state and logs (`?workspace=…`) |
-| `POST /api/servers/:id/{start,stop,restart}` | lifecycle (workspace-scoped) |
-| `POST /api/servers/:id/free-port` | ask whatever holds that server's port to stop |
-| `PATCH /api/servers/:id`, `PATCH /api/settings`, `PATCH /api/settings/workspace` | edit configuration |
-| `GET /api/logs`, `/api/backups` | history and archives |
-| `PUT`/`DELETE /api/notifications/token`, `POST /api/notifications/{test,detect-chats}` | the bot credential, a test send |
-| `GET /healthz` | no session needed — the one an external monitor wants (its per-server detail needs a credential) |
-| `GET /api/metrics` | Prometheus text (needs a token or session, like every `/api` route) |
+| | | `?workspace` |
+| --- | --- | --- |
+| `GET /api/state` | the full snapshot: global settings, every workspace with its servers, host vitals | ❌ |
+| `GET`/`POST /api/workspaces`, `PATCH`/`DELETE /api/workspaces/:id` | the registry: list, create, rename, remove | ❌ |
+| `GET /api/events` | SSE: the live state, plus logs (`?logs=0`, `?serverId=…`; a `server` payload carries its `workspaceId`) | ❌ |
+| `GET`/`POST /api/servers`, `POST /api/servers/{start,stop}-all` | that workspace's entries, and its lifecycle for all of them | ✅ |
+| `GET`/`PATCH`/`DELETE /api/servers/:id` | one entry | ✅ |
+| `POST /api/servers/:id/{start,stop,restart}`, `POST /api/servers/:id/free-port` | one entry's lifecycle, and freeing its port | ✅ |
+| `GET /api/servers/:id/logs`, `GET /api/servers/:id/stream` | that entry's buffered lines, and its SSE | ✅ |
+| `GET /api/logs` | persisted history and files | ✅ |
+| `GET`/`PUT /api/ddns`, `/api/ddns/credentials/:id`, `/api/ddns/check` | that workspace's Dynamic DNS policy, credentials and a check | ✅ |
+| `PUT`/`DELETE /api/notifications/token`, `POST /api/notifications/{test,detect-chats}` | that workspace's bot credential and a test send | ✅ |
+| `GET`/`PATCH /api/settings/workspace` | server defaults, logs, notifications | ✅ |
+| `GET`/`PATCH /api/settings` | panel-wide: listener, authentication, TLS, host vitals, backups | ❌ |
+| `GET`/`POST /api/backups`, restore | archives | ❌ |
+| `GET /healthz` | no session needed — the one an external monitor wants (its per-server detail needs a credential) | ❌ |
+| `GET /api/metrics` | Prometheus text (needs a token or session, like every `/api` route) | ❌ |
+
+✅ takes `?workspace=<id>`; ❌ is panel-wide. Omitting it means the panel's default workspace — never
+another one.
 
 `GET /openapi/spec.json` describes all of it, `/openapi/ui` is the browsable version, and every error
 comes back as one envelope (`{ message, code, detail }`) with a stable `code` a tool can branch on.
@@ -265,6 +272,7 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 🤖 **Token API** | Scripts and agents drive it with `Authorization: Bearer` — no browser, no session. [↑](#-agents-scripts-and-tools) |
 | 🔔 **Notifications** | Telegram on crash, unhealthy, forced restart, recovery, host thresholds and DNS changes — [setup here](./docs/NOTIFICATIONS.md). |
 | 🌐 **Dynamic DNS** | Keep hostnames pointed at your public IP — Cloudflare, Namecheap, Spaceship, Porkbun, GoDaddy, Gandi and more. [DDNS.md](./docs/DDNS.md) |
+| 🔀 **Reverse proxy** | One engine in front of everything, with automatic HTTPS: `git.example.com` → a Gitea entry, `media.example.com` → a service on another box, `panel.example.com` → the panel. Caddy, installed and supervised by the panel. [REVERSE_PROXY.md](./docs/REVERSE_PROXY.md) |
 | 💾 **Backups** | Two levels: pick global settings, global secrets, TLS or a whole workspace at the top, then the pieces inside it (settings, servers, secrets, data directories) — plain `.zip`, or AES-256 with a password, restored per path. |
 | 🎨 **BYOU — Bring Your Own UI** | Upload a static build, `ui-update` to follow its releases, `ui-revert` to go back. [UI_CREATION.md](./docs/UI_CREATION.md) |
 | 🔐 **Security** | Cookie sessions, API tokens, scrypt hashes, per-IP lockout, optional TLS, and a refusal to expose itself without a password. |
@@ -496,10 +504,7 @@ Two ship in this repo: `uis/stock`, and `uis/noc-console` for TUI and shortcuts
 attaches both as `home-hosted-ui-<name>.zip`. Yours can be anything that compiles to static files —
 the server never cares what built it.
 
-<sub>Install a UI from the CLI: `home-hosted ui-switch` — with no flags it fetches the official asset
-built for this release. An **official** UI keeps itself paired with the panel: upgrade the panel and
-the next `up` re-installs the matching asset. Someone else's UI declares its own `repo`/`asset` in
-`ui.json`, and `home-hosted ui-update` offers its newer releases to pick from — `--old` for older ones.</sub>
+<sub>Install a UI from the CLI: `home-hosted ui-switch` `--asset noc-console` selects an UI directly, no flags interactively show official assets. Official UIs's version auto-sync when you update `home-hosted`. For unofficial UIs, `home-hosted ui-update` offers its newer releases to pick from — or `--old` for older (author must set up `ui.json` and GH releases).</sub>
 
 <details>
 <summary><b>🤖 Or have an agent build the UI you actually want</b></summary>
@@ -617,6 +622,7 @@ plus types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 | --- | --- |
 | declare a server: every field, placeholders, port conflicts | [SERVERS.md](./docs/SERVERS.md) |
 | get Telegram alerts working end to end | [NOTIFICATIONS.md](./docs/NOTIFICATIONS.md) |
+| expose the stack behind one hostname, with HTTPS | [REVERSE_PROXY.md](./docs/REVERSE_PROXY.md) |
 | build a UI against the API | [UI_CREATION.md](./docs/UI_CREATION.md) |
 | change the internals: architecture and the rules | [AGENTS.md](./AGENTS.md) |
 | poke the live API on your own panel | [/openapi/ui](http://127.0.0.1:3999/openapi/ui) |
@@ -628,7 +634,7 @@ plus types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 <details>
 <summary><b>🔗 Interesting resources</b></summary>
 
-- [dsh-home-hosted](https://github.com/NamesMT/dsh-home-hosted) — home-hosted servers management with boot autostart from [DeepSeek Harness](https://github.com/deepseek-ai/dsh)
+- [dsh-home-hosted](https://github.com/NamesMT/dsh-home-hosted) — home-hosted servers management with boot autostart from inside [DeepSeek Harness](https://github.com/deepseek-ai/dsh)
 
 <sub><i>+ PR to add yours</i></sub>