home-hosted 0.8.2 → 0.9.0

package/AGENTS.md

@@ -10,8 +10,8 @@ level: `settings.json` (listener, auth, TLS policy, host vitals, backups, revers
 `.ui/`, `.logs/` (the panel console), `.proxy/` (the engine, its generated config and 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 token, plus DDNS credentials sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET` — only DDNS
-is sealed, because it is the one thing replayed to a third party), `.logs/` (per server, `<id>.log`
+Telegram bot tokens, one per destination, plus DDNS credentials sealed with AES-256-GCM under
+`HHOSTED_DDNS_SECRET` — only DDNS is sealed, because it is the one thing replayed to a third party), `.logs/` (per server, `<id>.log`
 plus `<id>.log.1` when it rotates), and `.state/` (nanny state, its 0600 spawn spec until read,
 `ddns.json`). A home still on the 0.6.x layout is **refused** by `ensureLayout()`, which names the file
 and tells the person to install the latest 0.7.x; 0.8.0 does not relocate it. **The package ships no
@@ -39,7 +39,7 @@ Where knowledge lives, and when to reach for each:
 | [`.agentDocs/COMPATIBILITY.md`](.agentDocs/COMPATIBILITY.md) | config and UI compatibility, migrations |
 | [`.agentDocs/RELEASING.md`](.agentDocs/RELEASING.md) | how a release is cut, and which version to dispatch |
 | [`docs/SERVERS.md`](docs/SERVERS.md) | entries, port conflicts, persistent entries |
-| [`docs/NOTIFICATIONS.md`](docs/NOTIFICATIONS.md) | Telegram events |
+| [`docs/NOTIFICATIONS.md`](docs/NOTIFICATIONS.md) | notification destinations: Telegram, webhooks, shared defaults |
 | [`docs/DDNS.md`](docs/DDNS.md) | dynamic-DNS providers and hostnames |
 | [`docs/REVERSE_PROXY.md`](docs/REVERSE_PROXY.md) | the Caddy engine, routes, certificates |
 | [`docs/UI_CREATION.md`](docs/UI_CREATION.md) | the contract for a new UI |
@@ -56,6 +56,8 @@ pnpm run start                     # up --foreground (systemd, docker, a foregro
 pnpm exec tsx src/cli.ts logs      # the panel's own console output (--lines, --follow, --json)
 pnpm dev                           # tsx-watch panel :6000 + the stock UI's Vite :6001, state in .dev-state/
 pnpm dev --ui noc-console          # the same, for another UI; --port/--ui-port override
+pnpm dev --home /tmp/hh-dev        # state elsewhere; HHOSTED_HOME is IGNORED here, and the real
+                                   #   ~/.home-hosted is refused. Dev password: `dev`
 pnpm run build                     # dist/cli.js + the stock UI (uis/stock/dist)
 pnpm run build:uis                 # every UI under uis/, zipped into uis/dist/ (release assets)
 pnpm run build:locales             # i18n/sheets/*.csv -> the git-ignored i18n/generated/*.json (also
@@ -69,7 +71,8 @@ pnpm run set-password              # non-interactive through HHOSTED_PASSWORD
 pnpm run set-token                 # --generate prints a new API token once
 pnpm run migrate                   # bring the config up to this release's schema
 pnpm exec tsx src/cli.ts init      # scaffold a project (interactive; --yes for defaults)
-pnpm run media                     # regenerate docs/media (mockups, both served UIs, tour.gif)
+pnpm run media                     # regenerate docs/media; needs `pnpm exec playwright install chromium`
+                                   #   once (browser only; `gif` alone does not)
 ```
 
 The published bin is `home-hosted`, with an `hh` alias: both names run the same CLI.
@@ -128,7 +131,8 @@ These prevent defects if broken. The *why* for the non-obvious ones is in
   **refuses** a commit that changed a shipped UI without raising it (a UI's `test/` and its own
   `README.md` are exempt — neither is in the built asset).
   `src/shared/**` is a UI build input, so a runtime contract needs the bump too — the hook does not
-  inspect that commit.
+  inspect that commit. **`tag` and `unix` are build provenance**, stamped into `dist/ui.json` by
+  `build-uis.mjs`; never committed to `public/ui.json`.
 - **Paths.** `dataRoot` is state, under `dataRoot/.hh`; `projectDir` is the base for relative entry
   paths. `{…}` and `${ENV}` expand in config — the full list is the table in
   [`docs/SERVERS.md`](docs/SERVERS.md), which is what to keep in step. No package-relative state.

package/README.md

@@ -1,6 +1,8 @@
 <div align="center">
 
-# 🏠 home-hosted
+<img src="docs/branding/logo.svg" alt="home-hosted" width="128" height="128">
+
+# home-hosted
 
 **The control panel for everything you self-host at home.**
 
@@ -81,7 +83,8 @@ some arguments, and the environment you give it:
 ```
 
 <sub>Manage them from the panel, `home-hosted start|stop <id>` from a shell, `home-hosted status --json`,
-or `GET /api/state`; `GET /healthz` is the same status line for your own monitor, no session needed.</sub>
+or `GET /api/state`; `GET /healthz` is the same status line for your own monitor, no session needed —
+`503` when an autostart server has crashed or a running one is failing its health check.</sub>
 
 ---
 
@@ -267,17 +270,17 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 🗂 **Workspaces** | One panel, many scopes: pick a workspace in the header and it owns its servers, secrets, logs and settings. Create, rename and delete them there. Panel-wide things — listener, auth, host vitals, backups, TLS, UI — stay in **Global settings**. |
 | 🚦 **Lifecycle** | Start, stop, restart from the panel or the API; `autostart` entries come up with it. |
 | 📝 **Hand edits welcome** | Change a workspace's `servers.config.json` in an editor, a `git checkout` or a config tool: the panel notices within seconds, no restart. A file it cannot read is reported in the panel, and the running servers are left alone. |
-| ♻️ **Auto-restart** | Exponential backoff on crash, with the counter reset once a process stays up. |
+| ♻️ **Auto-restart** | Exponential backoff on crash, with the counter reset once a process stays up. The budget is remembered across a restart of the panel. |
 | 🩺 **Health that acts** | TCP or HTTP probes per server: warn on the card, force a restart after a timeout, check ports before starting — and [follow or replace](./docs/SERVERS.md#when-a-program-restarts-itself) a program that restarts itself. |
 | 🔗 **Ordered startup** | `dependsOn` waits for a dependency to be *healthy* — not merely spawned. `stop-all`/`down` stop dependents before their dependencies; stopping one server names the dependents it leaves running. [SERVERS.md](./docs/SERVERS.md#field-reference) |
 | 📜 **Logs** | Live per-server stream, buffer plus rotated files on disk, search, filter to one stream, download, one click to clear. |
 | 📈 **Resources** | CPU and RSS of the whole process tree, with an optional memory ceiling that triggers a restart. |
 | 🌡️ **Host vitals** | Load, memory, swap, disk and CPU temperature, with thresholds that notify once and again on recovery. |
 | 🤖 **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). |
+| 🔔 **Notifications** | One list of **destinations** — Telegram chats and webhooks (ntfy, Discord, Slack, your own endpoint) — on crash, unhealthy, forced restart, recovery, host thresholds and DNS changes. The event toggles and throttle are set once, and each destination may inherit them or carry its own. [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** | Deep and customizable: pick global settings, global secrets, TLS, Workspaces, then the pieces inside it (workspace settings, servers, secrets, data directories) — plain `.zip`, or AES-256 with a password, customized restore is supported too! |
+| 💾 **Backups** | Global settings, TLS, workspaces, and inside each one its settings, servers, secrets and declared data — plain `.zip`, or AES-256 with a password. Each secret is picked separately, and a restore can be customized. |
 | 🌍 **Nine languages** | English, Vietnamese, Chinese, Japanese, Spanish, Korean, Russian, French, German — picked on the login page or in **Global settings → Language**, kept per browser. |
 | 🎨 **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. |
@@ -464,10 +467,15 @@ Everything binds `127.0.0.1` until you say otherwise.
 
 ## 🔔 Notifications
 
-Telegram, when something happens while you are not looking: a server that gave up restarting, a
+A message when something happens while you are not looking: a server that gave up restarting, a
 failing health check, a forced restart, a recovery, a host threshold (disk, memory, swap, load,
-temperature), or a dynamic DNS change. Opt-in, rate-limited per server *and* reason, and the bot token
-stays in the secrets file. **Two minutes of setup: [NOTIFICATIONS.md](./docs/NOTIFICATIONS.md).**
+temperature), or a dynamic DNS change.
+
+Every alert goes to a list of **destinations** — a Telegram chat, a webhook, or several of each. The
+event toggles and the throttle are set **once**, and each destination either inherits them or carries
+its own. Rate-limited per destination, server *and* reason. Bot tokens and webhook credentials stay in
+the secrets file, never in a config. **Two minutes of setup:
+[NOTIFICATIONS.md](./docs/NOTIFICATIONS.md).**
 
 ---
 
@@ -485,11 +493,38 @@ Provider tokens stay in the workspace's secrets file. **Providers and the config
 
 **Global settings → Backups** archives the panel's own settings, its secrets and the TLS pair — plus
 every workspace you pick. It is two-level: the top of *Create backup…* lists the global items and
-each workspace; opening a workspace lists its **settings**, **servers**, **secrets** and every data
-directory its entries declare, and you can drop any single piece. *Restore…* shows the same list from
-an archive before anything is written. Either way it is an ordinary `.zip`, or WinZip AES-256 with a
-password, restored per path. Known build output and dependency directories (`node_modules`, `dist`,
-`.next`, framework caches) are skipped per entry; `backupIgnoreGenerated: false` captures them anyway.
+each workspace; opening one lists its **settings**, **servers**, its **secrets** and every data
+directory its entries declare, and you can drop any single piece. Each secret has its own checkbox.
+*Restore…* shows the same list from an archive before anything is written. Either way it is an
+ordinary `.zip`, or WinZip AES-256 with a password, restored per path. Known build output and
+dependency directories (`node_modules`, `dist`, `.next`, framework caches) are skipped per entry;
+`backupIgnoreGenerated: false` captures them anyway.
+
+**Automatic backups** write one archive on a schedule you set — the page asks in hours; the config
+stores `intervalMs` — with a retention of its own (`Keep automatic`). The two counts are independent: `Keep` bounds the archives you take by hand,
+and a scheduled pass never prunes one of yours to make room for its own. Both live in the same
+directory, and an automatic archive is named `auto-…` so you can tell them apart — a name you drop
+in by hand with that prefix is treated as one, so do not use it.
+
+<details>
+<summary><b>🔑 Restoring a secret</b></summary>
+
+An archive records **which release wrote it and the config schema it understood**; a restore refuses
+a newer schema outright rather than restoring the parts it recognizes.
+
+Ticking a **single secret** merges by field: it lands and the others in that file are left alone. So
+restoring the Telegram token does not clear the DDNS credentials. Ticking the whole **Secrets** entry
+replaces the file with the archive's copy instead, which is what makes the two worth telling apart.
+
+Two things to know before restoring onto a machine already in use:
+
+- **The password hash and API token hash are secrets like any other.** Restoring them reinstates the
+  old machine's password and long-lived token, so anyone holding that token keeps access. Leave them
+  unticked, or rotate afterwards with `pnpm run set-token --generate`.
+- **`HHOSTED_DDNS_SECRET` is not in the archive.** DDNS credentials travel sealed under it, so a host
+  with a different value cannot open them. Supply the same secret, or re-enter the credentials.
+
+</details>
 
 <details>
 <summary><b>🚚 One archive is a whole setup</b></summary>
@@ -649,6 +684,7 @@ src/cli.ts      the command line; one file per command under src/cli/
 src/index.ts    the control plane itself, used by `up --foreground`
 uis/            UIs: `stock` (shipped in the package) and alternatives — any framework, static output
 bin/            the published entry point
+docs/branding/  logo, icons and the social preview; the SVGs are the source, `pnpm run brand` renders them
 docs/           topic docs, UI examples and the README's media
 scripts/        builds, typechecks, media capture, release helpers
 test/           the vitest suite
@@ -665,7 +701,7 @@ plus types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 | if you want to… | read |
 | --- | --- |
 | 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) |
+| get Telegram or webhook 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) |