home-hosted 0.6.5 → 0.6.7

package/AGENTS.md

@@ -3,13 +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 `$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, DDNS credentials),
+`.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 +92,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 +129,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
 
@@ -247,6 +249,9 @@ either is a last resort, and never an accidental one.
   every entry's child) instead of killing it — a port held by a sibling is a config mistake.
 - **Never expose beyond loopback without auth and a non-default password.** `checkExposure()` is the
   single rule, enforced at startup, on every settings write, and in the UI.
+- **The CLI drives a running panel through `/_hh`, never `/api`.** `down` and `start`/`stop` read
+  run.json's token and speak over loopback through one guard (`assertLocalCall`), so they need no
+  session, password or API token — and a new local command must not open an unauthenticated `/api` route.
 - **UIs are external clients.** Nothing in `src/**` may know a UI's markup or files;
   `$HHOSTED_HOME/.ui` overrides the packaged UI at runtime.
 - **A restore writes only where a config says** — archive allowlist, `origin` matching first,
@@ -344,10 +349,12 @@ either is a last resort, and never an accidental one.
   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.
+- **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

@@ -79,8 +79,8 @@ some arguments, and the environment you give it:
 { "id": "gateway", "command": "node", "args": ["server.js"], "port": 4000, "autostart": true }
 ```
 
-<sub>Manage them from the panel, `home-hosted status --json`, or `GET /api/state`; `GET /healthz` is
-the same status line for your own monitor, no session needed.</sub>
+<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>
 
 ---
 
@@ -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,6 +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 — 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`) |
@@ -311,6 +314,7 @@ up, restart       -c/--config -p/--port --host --open --no-autostart --foregroun
 
 down              (no flags)
 status            --json
+start, stop       <id>   (the server's id in servers.config.json; both need the panel up)
 init              --dir --name --pm --no-install -y/--yes
 set-password      --clear
 set-token         --generate --clear
@@ -381,9 +385,18 @@ 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).**
 
 ---