home-hosted 0.7.3 → 0.7.5

package/AGENTS.md

@@ -12,8 +12,9 @@ level: `settings.json` (listener, auth, TLS policy, host vitals, backups, revers
 `.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
+`.secrets.json` (0600: Telegram bot 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/`, and `.state/` (a persistent entry's nanny state plus its 0600 spawn
 spec until the nanny reads it, plus `ddns.json`). A pre-`.hh` instance is relocated automatically by
 `ensureLayout()` (`src/config/layout.ts`). The package ships **no servers**: never commit a config, a
 seed entry, or a path that names one.
@@ -165,9 +166,10 @@ a minor without one.
 - A single on/off setting is a `ToggleSwitch`; `CheckField` is only for picking items out of a set
   (the restore plan). A checkbox in a `FieldGroup` grid reads as misaligned next to the inputs.
 - A create body carries only what differs from what the entry would inherit — the schema's defaults
-  with `Workspace Settings → Server defaults` on top (`inheritBaseline` + `diffFields` in both
-  UIs). A value written into `servers.config.json` stops following those defaults, so anything the
-  person did not decide stays out; the editor applies the same rule to an edit.
+  with `Workspace Settings → Server defaults` on top (each UI's own `inheritBaseline` plus the shared
+  `diffFields` in `src/shared/patch-diff.ts`). A value written into `servers.config.json` stops
+  following those defaults, so anything the person did not decide stays out; the editor applies the
+  same rule to an edit.
 - ArkType at every runtime boundary: routes use `validate('json'|'query'|'param', schema)` then
   `c.req.valid(...)`; ad-hoc payloads use `parseOrThrow`. Schemas reject undeclared keys.
 - Every failure is a `DetailedError` (`@namesmt/utils`), mapped by `src/helpers/error.ts` into one
@@ -277,10 +279,12 @@ either is a last resort, and never an accidental one.
   boot through `.state/<id>.json` before any port preflight (`nannyIsAlive` = live pid **and** a fresh
   heartbeat, the `HHOSTED_SERVER_ID` marker or the argv), tails that file for live logs, and reads
   `lastExit` once so a crash nobody watched is reported. The spawn spec is consumed by the read and
-  swept at boot — it carries expanded env. Two lifetimes are pinned: the nanny **exits with its child**
+  swept at boot — it carries expanded env. Three lifetimes are pinned: the nanny **exits with its child**
   (an inherited pipe would keep it alive, and the panel would report a healthy entry whose server is a
-  detached stranger), and a stop reaches the child by pid from the state file, because `SIGKILL` and
-  `killGroup: false` cannot be forwarded — which is why a self-restarting program belongs on `reclaim`.
+  detached stranger), a stop reaches the child by pid from the state file, because `SIGKILL` and
+  `killGroup: false` cannot be forwarded — which is why a self-restarting program belongs on `reclaim` —
+  and its `SIGTERM`/`SIGINT` traps are armed *before* the child exists and before that state file
+  appears, so a stop that beats the spawn can never orphan a child nobody has a record of.
   The nanny never restarts anything: retries and health stay the supervisor's. `logs.persist: false`
   keeps that file out of the Logs page but never stops it being written — it is the transport.
 - **A port is only ever freed by re-listing its listeners.** `POST /api/servers/:id/free-port` never

package/README.md

@@ -25,7 +25,7 @@ them, watches them, restarts what dies, and shows you one page of what is going
 
 <div align="center">
 
-![Six views of the panel: the stock UI, the NOC-console, and UI examples](docs/media/tour.gif)
+![Eight views of the panel: the stock UI and its reverse proxy, the NOC-console, and UI examples](docs/media/tour.gif)
 
 <sub>The stock panel, the [NOC-console](./uis/noc-console) that ships alongside it (for TUI and
 shortcuts wizards), and UI directions you could build yourself —
@@ -163,13 +163,13 @@ Worked example, with per-server data inside the project:
 <sub>Call them as `pnpm run up` — `pnpm up` is pnpm's own update, not your script.</sub>
 
 > [!TIP]
-> Give a project its own panel port (`control.port`, e.g. `4399`) — the default `3999` is what the
-> global instance and every other project also want.
+> Recommended to give a project its own panel port (`control.port`, e.g. `4399`), to avoid port conflict
+> with other projects.
 
 </details>
 
 <details>
-<summary><b>🧰 Run it under systemd or Docker (no daemon needed)</b></summary>
+<summary><b>🧰 Run it under systemd or Docker</b></summary>
 
 ```bash
 home-hosted up --foreground     # stays in the foreground, logs to stderr
@@ -179,12 +179,16 @@ home-hosted up --foreground     # stays in the foreground, logs to stderr
 [Unit]
 Description=home-hosted
 [Service]
+User=$YOUR_USER
 ExecStart=/usr/local/bin/home-hosted up --foreground
 Environment=HHOSTED_HOME=/srv/home-hosted
 Restart=always
 [Install]
 WantedBy=multi-user.target
 ```
+> [!CAUTION]
+> Note: change `$YOUR_USER` to your actual user account, or remove for `root`.
+> You could also change `/srv/home-hosted` to change where the data stores.
 
 </details>
 
@@ -228,11 +232,11 @@ default workspace.
 | `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`/`PATCH /api/proxy`, `POST /api/proxy/{engine,start,stop,apply,revert}`, `PUT`/`DELETE /api/proxy/certificates/:id` | the reverse proxy: its engine, its route table, and its uploaded certificates | ❌ |
 | `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.
+✅ takes `?workspace=<id>`; ❌ is panel-wide. Omitting `?workspace` means `default` workspace is used.
 
 `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.
@@ -273,7 +277,7 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 🔔 **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. |
+| 💾 **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! |
 | 🎨 **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. |
 | 🧩 **No special treatment** | A server is `command` + `args` + `env` + `cwd`; nothing is built in for any particular app. |
@@ -283,27 +287,17 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 
 ## 🗂 Workspaces
 
-A workspace is the ownership boundary: its own servers, secrets, logs, nanny state and settings. The
-header picker is the whole control — choose one, create one, rename it, or delete it (which stops
-what it supervises first). The first boot creates a `default` workspace; a pre-workspaces instance is
-relocated into one automatically.
-
-> [!IMPORTANT]
-> **Upgrading from before workspaces (0.6 → 0.7)?** That release is breaking: state moves under
-> `$HHOSTED_HOME/.hh`, settings split global vs. per-workspace, and backups become two-level. The
-> relocation runs on the next command — `home-hosted migrate` reports it and stamps every file. See
-> [Upgrading](#-cli).
+A workspace is the ownership boundary: its own servers, secrets, logs, states and settings.
+The first boot creates a `default` workspace.
 
 | page | url | scope |
 | --- | --- | --- |
 | **Overview** | `/w/<workspace>` | the selected workspace: its servers, counts and live status |
 | **Servers** · **Logs** · **Workspace settings** | `/w/<workspace>/servers` · `/w/<workspace>/logs` · `/w/<workspace>/settings` | the selected workspace |
+| **One server** | `/w/<workspace>/servers/<id>` | that entry: config, live logs, resources |
 | **Global Overview** | `/global/overview` | host vitals plus every server from every workspace |
 | **Global settings** | `/global/settings` | Listener, Authentication, Host vitals, Backups, TLS, Interface, Paths |
-
-Every page is bookmarked by its own URL: the workspace id is part of it, so a link opens the same
-workspace even in a browser that never selected it. `/` opens **Global Overview**. The sidebar lists
-the panel-wide pages first, then the selected workspace's.
+| **Reverse Proxy** | `/proxy` | panel-wide: one engine, every workspace's servers ([REVERSE_PROXY.md](./docs/REVERSE_PROXY.md)) |
 
 <details>
 <summary><b>🗂 What lives where</b></summary>
@@ -334,6 +328,7 @@ An entry is a few lines. Add one with **➕ Add server**, or write it into the s
 ```
 
 `dataEnvs` declares a data directory once: it is exported to the process *and* picked up by Backups.
+
 **Every field, every placeholder, the port-conflict policies (including adopting a server that
 restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.md).**
 
@@ -352,9 +347,9 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | `home-hosted set-password` | set the panel password without opening a browser |
 | `home-hosted set-token` | set the API token scripts and agents use (`--generate`, `--clear`) |
 | `home-hosted migrate` | relocate a pre-workspaces state directory and stamp every config for this release (`--dry-run`, `--yes`) |
-| `home-hosted init` | scaffold a project that keeps `state/` and its data in the repo |
+| `home-hosted init` | scaffold a self-contained project, whose scripts keep state in the repo (`--home ./state`) |
 | `home-hosted ui-switch` | install a UI from a release asset, a zip file or a URL (interactive) |
-| `home-hosted ui-update` | bring an installed UI up to date, or pick a release (`--old`, `--check`) |
+| `home-hosted ui-update` | bring an installed UI up to date automatically (official UI) or pick a release (`--old`, `--check`) |
 | `home-hosted ui-revert` | go back to the stock panel UI after uploading your own |
 
 <details>
@@ -390,16 +385,6 @@ for a launcher that pins one; a workspace picked in the UI keeps its own. `start
 <details>
 <summary><b>🧭 Upgrading, and why the panel sometimes refuses to start</b></summary>
 
-> **Breaking in 0.7 — workspaces.** State moved under `$HHOSTED_HOME/.hh`: global files at its top
-> level, one directory per workspace. Settings split into panel-wide **Global settings** and
-> per-workspace **Workspace settings**, backups became two-level, and `--config` now points at the
-> default workspace's servers file. The old `servers.config.json` becomes
-> `.hh/default/servers.config.json`.
-
-Relocation is automatic: the CLI relocates a pre-`.hh` `$HHOSTED_HOME` before any command runs, so an
-existing instance keeps working after the upgrade. `home-hosted migrate` reports what it moved and
-stamps every file for this release:
-
 ```bash
 home-hosted migrate --dry-run   # print the steps, write nothing
 home-hosted migrate             # ask, then write — keeps a .bak beside each rewritten file
@@ -582,7 +567,10 @@ run.json                     the running panel (pid, url, token, mode 0600)
 <details>
 <summary><b>Which ports does it use?</b></summary>
 
-Just the control panel, `3999` by default. Supervised servers use the ports you give them.
+The control panel, `3999` by default. Supervised servers use the ports you give them. The reverse
+proxy is the one panel-wide listener, and only when you switch it on: `80`/`443` for automatic HTTPS,
+or `4480`/`4443` unprivileged with your router forwarding to them
+([REVERSE_PROXY.md](./docs/REVERSE_PROXY.md#ports)).
 
 </details>
 
@@ -591,7 +579,9 @@ Just the control panel, `3999` by default. Supervised servers use the ports you
 
 Yes. Process trees are sampled from Win32_Process, termination uses `taskkill /T`, and the shipped
 examples avoid POSIX-only commands. CPU temperature and swap are best-effort where the OS does not
-expose them to an unprivileged process, and adopting a self-restarted process is Linux/macOS only.
+expose them to an unprivileged process. Adopting a self-restarted process works on Windows too, off
+its argv instead of the environment marker; a launcher whose real process is a `.cmd` shim is the one
+case it cannot see through, and `kill` is the answer there.
 
 </details>
 
@@ -634,7 +624,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 inside [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/deepseek-harness)
 
 <sub><i>+ PR to add yours</i></sub>