home-hosted 0.6.6 → 0.6.8

package/AGENTS.md

@@ -3,13 +3,15 @@
 `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 `$HHOSTED_HOME/servers.config.json`
 and serves a UI. User docs: `README.md`, `docs/SERVERS.md` (entries and port conflicts),
-`docs/NOTIFICATIONS.md`; UI authors: `docs/UI_CREATION.md`.
+`docs/NOTIFICATIONS.md`, `docs/DDNS.md`; UI authors: `docs/UI_CREATION.md`.
 
 State lives only in `$HHOSTED_HOME` (default `~/.home-hosted`): `servers.config.json`,
-`.control-secrets.json` (0600: password hash, API token hash, Telegram bot token), `.logs/`, `.tls/`,
-`.backups/`, `.ui/`, `.state/` (a persistent entry's nanny state, plus its 0600 spawn spec until the
-nanny reads it), and `run.json` — the live daemon's pid/url/token, 0600. The package ships **no
-servers**: never commit a config, a seed entry, or a path that names one.
+`.control-secrets.json` (0600: password hash, API token hash, Telegram bot token, and DDNS
+credentials sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET`), `.logs/`, `.tls/`, `.backups/`,
+`.ui/`, `.state/` (a persistent entry's nanny state, plus its 0600 spawn spec until the nanny reads
+it, plus `ddns.json` — the last address each target confirmed), and `run.json` — the live daemon's
+pid/url/token, 0600. The package ships **no servers**: never commit a config, a seed entry, or a path
+that names one.
 
 ## Commands
 
@@ -91,14 +93,15 @@ a minor without one.
   `processCarriesServerId` for the environment marker and `processTreePids` for tree ownership),
   `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), health-check, host, telegram,
+  `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.
 - `src/services/` — stateful orchestration: supervisor, control-server, config-watch, state,
-  auth + exposure, dependencies, history, log-buffer/log-files, notifications, host-monitor, 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.
+  auth + exposure, dependencies, history, log-buffer/log-files, notifications, host-monitor, ddns,
+  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.
 - `src/middleware/auth.ts` — the `/api/*` guard, and `requestIdentity()`, the one place a request's
   credentials are read: the `hh_session` cookie or `Authorization: Bearer <api token>`. A token is
   a first-class credential (same authority as a signed-in browser) and is verified from the secrets
@@ -127,10 +130,10 @@ a minor without one.
 - `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`, `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 three `.md` files are published; the
-  media is a build artifact.
+- `docs/` — the topic docs (`SERVERS.md`, `NOTIFICATIONS.md`, `DDNS.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
+  published; the media is a build artifact.
 
 ## Conventions
 
@@ -147,7 +150,9 @@ a minor without one.
   envelope `{ message, code, detail }`. Never hand-roll `c.json({ error })`.
 - Document routes with `describeRoute` + `jsonBody(schema)`; `jsonBody` needs a real schema.
 - Patch schemas carry no defaults; nested groups (`restart`/`health`/`stop`/`auth`/`tls`/`telegram`/
-  `http`) merge key-by-key, and an explicit `null` clears a key.
+  `http`) merge key-by-key, and an explicit `null` clears a key. `ddns` is the exception: its
+  `accounts`/`domains` lists are **replaced** (a merge cannot express removing a hostname), and only
+  `ipv4`/`ipv6` merge.
 - Two-sided bounds read inclusively (`'1 <= number.integer <= 512'`). `test/shared/contracts.test.ts`
   pins every boundary and the patch/schema parity — update it with any schema change.
 - A new field in a **response** DTO is optional (`'x?'`) and its clients read it defensively. An
@@ -163,6 +168,12 @@ a minor without one.
 - A destructive action that is one click away confirms in a **popover** (`KillPortButton.vue`),
   never by arming the same button for a second press: an impatient double click on an arming
   button fires it. Keep the safe choice first in the popover's tab order.
+- **Docs ship with the change.** A user-visible change updates the docs that describe it
+  (`README.md`, `docs/*.md`) in the same commit — do not forget them; a stale doc is a bug like
+  stale code.
+- **UIs move together.** `uis/stock` is not the only client: a change to it — or to a shared
+  contract it reads — lands in every other UI under `uis/`, and each altered UI bumps its
+  `ui.json` per the rule above.
 
 ## Compatibility
 
@@ -192,6 +203,9 @@ either is a last resort, and never an accidental one.
 - **Unknown keys are dropped from the resolved config, kept on disk, and listed in a startup
   warning.** Dropping one is the normal way a newer config looks here, so it must never fail the
   group it sits in (that used to reset `control` — port, bind, auth policy — to schema defaults).
+  A *write* to a group validates the same tolerant way (`parseTolerant` via the store), so a key this
+  release does not know never blocks a save — removing a key from a schema must not brick the page
+  that writes it.
 - **Migrations ship inside the package** (`src/config/migrations.ts`), are ordered, idempotent and
   described in one line each. `home-hosted migrate` prints the plan, keeps `servers.config.json.bak`,
   refuses to write a config it cannot read, and needs consent: `--yes`, `HHOSTED_MIGRATE=allow`, or a
@@ -346,11 +360,14 @@ either is a last resort, and never an accidental one.
 - **Server field**: `serverSchema` + its patch in contracts, merge keys in `config/store.ts` when
   nested, the form in `uis/stock/src/components/settings/`, and the contract tests.
 - **UI**: a new `uis/<name>/` with a `vite.config.ts` from the shared factory;
-  `node scripts/build-uis.mjs <name> --zip`. The contract is `docs/UI_CREATION.md`.
-- **Capability**: a stateless `src/providers/*` returning plain data.
+  `node scripts/build-uis.mjs <name> --zip`. The contract is `docs/UI_CREATION.md`. A change to one
+  UI (`stock`, `noc-console`) is carried to the others in the same commit.
+- **Capability**: a stateless `src/providers/*` returning plain data; a DDNS provider is one file plus
+  a registry line (`src/providers/ddns/index.ts`), and the settings form, credentials and validation
+  follow from its metadata — see `docs/DDNS.md`.
 
 ## Publishing
 
-`pnpm pack` runs `prepack` (a full build) and ships `bin/`, `dist/`, `uis/stock/dist`, `README.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
+`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
 build; `vue`/`vue-router` are devDependencies because the UIs are prebuilt.

package/README.md

@@ -255,7 +255,8 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 📈 **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 and host thresholds — [setup here](./docs/NOTIFICATIONS.md). |
+| 🔔 **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) |
 | 💾 **Backups** | One click for config, secrets, TLS and your declared 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. |
@@ -293,8 +294,8 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | `home-hosted down` | stop it cleanly — supervised processes included, persistent entries left running |
 | `home-hosted restart` | `down`, then `up` |
 | `home-hosted status` | pid, URL, health, uptime, state and log paths (`--json` for scripts) |
-| `home-hosted start <id>` | start one server, leaving the panel and its other servers alone |
-| `home-hosted stop <id>` | stop one server — the panel stays up |
+| `home-hosted start <id>` | start one server — and anything it `dependsOn` |
+| `home-hosted stop <id>` | stop one server, nothing else |
 | `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` | bring `servers.config.json` up to this release's schema (`--dry-run`, `--yes`) |
@@ -374,8 +375,10 @@ Everything binds `127.0.0.1` until you say otherwise.
   never taken from the message, and anything the panel supervises is refused, not killed. A server
   that [restarts itself](./docs/SERVERS.md#when-a-program-restarts-itself) can be followed, or replaced
   with a supervised copy.
-- **Secrets never enter the config**: the password hash, the API token hash and the Telegram bot
-  token live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`; the TLS pair in `.tls/`.
+- **Secrets never enter the config**: the password hash, the API token hash, the Telegram bot
+  token and the DDNS credentials live in `$HHOSTED_HOME/.control-secrets.json` with mode `0600`; the
+  TLS pair in `.tls/`. DDNS credentials are sealed with AES-256-GCM under `HHOSTED_DDNS_SECRET`
+  (default `hh` — set your own).
 - **Behind a proxy** turn on `trustProxy` and let `cookieSecure: auto` add `Secure` on https, or
   upload a PEM pair and let home-hosted terminate TLS itself.
 
@@ -384,18 +387,29 @@ 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
-failing health check, a forced restart, a recovery, or a host threshold (disk, memory, swap, load,
-temperature). 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).**
+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).**
+
+---
+
+## 🌐 Dynamic DNS
+
+**Settings → Dynamic DNS** keeps a list of hostnames pointed at this machine's public IP — add an
+account, paste its credentials, add hostnames. The panel checks the address on an interval and calls a
+provider only when it actually changed, and the last confirmed address survives a restart. Provider
+tokens stay in the secrets file. **Providers and the config shape: [DDNS.md](./docs/DDNS.md).**
 
 ---
 
 ## 💾 Backups
 
 **Settings → Backups** archives the config, secrets, TLS pair and every data directory your entries
-declare — 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.
+declare — an ordinary `.zip`, or WinZip AES-256 with a password, restored per path. *Create backup…*
+lists what the archive will hold and lets you drop any item; *Restore…* shows the same list from an
+archive before anything is written. Known build output and dependency directories (`node_modules`,
+`dist`, `.next`, framework caches) are skipped per entry; `backupIgnoreGenerated: false` captures them
+anyway.
 
 <details>
 <summary><b>🚚 One archive is a whole setup</b></summary>
@@ -406,7 +420,9 @@ archive and restore. Definitions come back, data lands where *this* machine's co
 
 It works because an archive carries its own `servers.config.json` and paths are matched by the
 **declaration** (`omniroute:DATA_DIR`), not by an absolute path from the source machine. A restore never
-writes where no config declares.
+writes where no config declares. A declaration using `{projectDir}`, `{dataRoot}` or `{home}` follows
+the restoring panel (`{projectDir}` is `HHOSTED_PROJECT` or the panel's cwd, not `HHOSTED_HOME`); a
+literal absolute path is restored to that same path.
 
 </details>