home-hosted 0.2.0 → 0.4.0

package/AGENTS.md

@@ -2,12 +2,13 @@
 
 `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`; UI authors: `UI_CREATION.md`.
+and serves a UI. User docs: `README.md`, `SERVERS.md` (entries and port conflicts),
+`NOTIFICATIONS.md`; UI authors: `UI_CREATION.md`.
 
 State lives only in `$HHOSTED_HOME` (default `~/.home-hosted`): `servers.config.json`,
-`.control-secrets.json` (0600), `.logs/`, `.tls/`, `.backups/`, `.ui/`, 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), `.logs/`, `.tls/`,
+`.backups/`, `.ui/`, 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
 
@@ -21,11 +22,18 @@ pnpm run quickcheck                # eslint + tsc + vue-tsc for every UI under u
 pnpm exec vitest run               # `pnpm test` is vitest in watch mode
 pnpm run check                     # quickcheck + vitest run --coverage
 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)
 ```
 
-Releases are dispatched from `.github/workflows/release.yml` with a version: changelogen writes the
-changelog, bumps, commits and tags, the GitHub release carries the UI zips, and npm publishes through
-trusted publishing.
+Releases are dispatched from `.github/workflows/release.yml` with a version (and a `dry-run` switch
+that stops before pushing). It verifies the version against `package.json`, lints/types/tests,
+builds the CLI plus the stock UI and every UI zip, lets changelogen write the changelog and tag
+`v<version>`, creates the GitHub release with the UI bundles attached, and publishes to npm through
+trusted publishing (OIDC, no token). npm only offers a trusted publisher for a package that already
+exists, so the first release has to be published by hand.
 
 ## Architecture (and why)
 
@@ -40,11 +48,21 @@ trusted publishing.
 - `src/api/**` — one file per URL group (`$.routes.ts` = several routes), mirroring the path.
 - `src/shared/contracts.ts` — every ArkType schema (config, API and SSE DTOs), shared with the UIs;
   the OpenAPI spec is generated from it, never hand-written.
-- `src/config/` — `schema.ts` (on-disk shape), `store.ts` (validate/merge/atomic commit, reports
-  `configError` instead of throwing on a bad file), `secrets.ts`, `seed.ts`.
-- `src/providers/` — stateless leaves: process, port, proc, health-check, host, telegram, archive.
+- `src/config/` — `schema.ts` (on-disk shape, including the `meta` stamp), `parse.ts` (the tolerant
+  reader: unknown keys are reported and kept, everything else blocking), `store.ts` (validate/merge/
+  atomic commit, reports `configError`/`configWarnings` instead of throwing on a bad file),
+  `migrations.ts` (the schema constant and the ordered step registry), `secrets.ts`, `seed.ts`.
+- `src/providers/` — stateless leaves: `process` (spawn, `terminate`, `terminatePid` for a process we
+  adopted), `port` (probe, holder lookup, `terminatePids`), `proc` (the sampler, plus
+  `processCarriesServerId` for ownership), health-check, host, telegram, archive.
 - `src/services/` — stateful orchestration: supervisor, control-server, state, auth + exposure,
-  dependencies, history, log-buffer/log-files, notifications, host-monitor, backups, tls, ui.
+  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). 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 `hh2_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
+  file on every request, so `set-token` needs no restart.
 - `src/helpers/` — paths (`dataRoot` vs `projectDir`), daemon (run.json + a loopback probe that
   bypasses `fetch`, so TLS with a self-signed pair still answers), error, validator, atomic,
   template, env-file, openapi, factory.
@@ -53,6 +71,11 @@ trusted publishing.
   `src/shared`, `@server` → `src` (**types only** — never import runtime server code into a UI).
 - `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/` — `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`.
 
 ## Conventions
 
@@ -66,7 +89,49 @@ trusted publishing.
   `http`) merge key-by-key, and an explicit `null` clears a key.
 - 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
+  upgrade writes a new `uis/stock/dist` to disk while the old panel process is still serving, so a
+  new UI meets an older payload for a while — a required field there rejects the whole frame and
+  blanks the app. Request bodies and config keep their strict, defaulted shape.
 - Conventional commits; ESLint via `@antfu/eslint-config`; sparse comments.
+- 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.
+
+## Compatibility
+
+Two surfaces outlive the release that wrote them: **configs absolutely, UIs within reason.** Breaking
+either is a last resort, and never an accidental one.
+
+- **A config written by an older release has to load in a newer one.** That direction is the priority:
+  add fields with defaults, never repurpose or remove one, and treat every existing key as permanent.
+- **Both directions matter, and both are now handled.** An unrecognized key is read, reported and
+  left on disk instead of failing anything: it is the normal way a config from a newer release looks
+  here. Anything that is not merely unrecognized — a wrong value, a duplicate id, an unreadable file —
+  stops the panel instead of being papered over with defaults.
+- **The UI moves in minor steps.** Routes, response fields and SSE frames are additive: keep the old
+  one and add the new one. A new response field is optional (`'x?'`) and read defensively, because an
+  upgrade writes a new `uis/stock/dist` while the old panel process keeps serving — and a
+  user-uploaded UI may be older than the panel it talks to.
+- **Breaking is allowed; silent is not.** When nothing compatible can be done, say so in the final
+  answer *and* in the commit message with a `BREAKING CHANGE:` footer, naming the exact migration the
+  user must run.
+- **A config records what wrote it.** Every write stamps a top-level `meta`
+  (`{ writtenBy, schema }`): the release that wrote the file and the config shape it wrote. An
+  unstamped file reads as the current schema, so nothing that existed before needed changing.
+- **Nobody runs a config this release cannot read.** `up` refuses to start — exit 1, the exact
+  problem printed — when the file is unparseable, has an invalid value or a duplicate id, carries a
+  newer `meta.schema`, or has a registered migration pending. A panel that is *already* running keeps
+  the config it has and only reports the error, so a bad edit never disturbs supervision.
+- **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).
+- **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
+  person at a terminal. A detached daemon never migrates on its own. Starting a fetch of migration
+  code from GitHub was considered and rejected: the panel supervises processes, so remote code is an
+  RCE surface, and a migration would age against a newer store API anyway.
 
 ## Rules that matter
 
@@ -75,8 +140,18 @@ trusted publishing.
 - **Paths.** `dataRoot` is state; `projectDir` is the base for relative entry paths. `{id}{port}`
   `{host}{bind}{cwd}{projectDir}{dataRoot}{home}` and `${ENV}` expand in config; there is no
   package-relative state.
-- **Secrets never enter the config.** Password hash, bot token and TLS key live in the 0600 secrets
-  file; the config holds policy.
+- **Secrets never enter the config.** Password hash, API token hash, bot token and TLS key live in
+  the 0600 secrets file; the config holds policy.
+- **A port holder that carries `HHOSTED_SERVER_ID` for this entry is our own successor, not a
+  stranger.** A program that restarts itself leaves a detached process behind; with
+  `follow` the panel adopts it as-is (pid, liveness, health, resources, stop — but not its output);
+  with `reclaim` it stops that successor and starts a fully supervised child instead. Both are strictly
+  better than blocking forever on a port that is already serving, and neither ever touches a stranger.
+  Ownership is read from the environment — `/proc` on Linux, `ps -E` on macOS, impossible on Windows —
+  and `stop.killPortHolders` stays the fallback.
+- **A port is only ever freed by re-listing its listeners.** `POST /api/servers/:id/free-port` never
+  trusts a pid quoted in a message, and refuses any listener in `supervisedPids()` (the panel plus
+  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.
 - **UIs are external clients.** Nothing in `src/**` may know a UI's markup or files;
@@ -97,8 +172,17 @@ trusted publishing.
   `stopping` first: overlapping calls would double-spawn or resurrect a stopped process. Tests must
   call `supervisor.dispose()`.
 - Port preflight re-probes after 300 ms — a just-closed listener can still complete a handshake.
+- Vue does not notify a computed's subscribers when its recomputed value is `Object.is`-equal to the
+  old one, so anything mutated in place silently freezes every value derived from it. The log buffers
+  (`uis/stock/src/composables/useControlPlane.ts`) therefore hand out a **new array per batch**, and
+  the `version` counter only exists to make the views re-read at all. Getting this wrong is what kept
+  the live output view empty until a remount — a test that reads the array itself will not catch it.
+- An adopted process is not a `ChildProcess`, so nothing reports its exit: the tick polls liveness and
+  hands the entry back to the normal `afterExit` path. Its output is not captured either — it was
+  redirected by whoever spawned it.
 - `stop.killPortHolders` frees a port only from a *listener* that is not our own process tree. Broad
   `lsof -ti:<port>` sweeps and pid-as-text parses have killed supervisors in the field; don't add one.
+  `free-port` reuses the same lookup and adds the supervisor's own pid set on top.
 - `ServerView.config.port` is normalized to `number | null`; the hand-narrowed types in
   `contracts.ts` are deliberate.
 - ArkType: an optional property (`'x?'`) rejects an explicit `undefined` (omit the key). Fields a UI
@@ -110,6 +194,10 @@ trusted publishing.
   encryption flags are cached and refreshed in the background.
 - `vite.server.config.ts` targets `node22` while `engines` requires >= 24 — deliberate margin, leave it.
 - `pnpm test` watches; CI runs `vitest run`.
+- `pnpm run media` drives Chromium through Playwright, which needs fonts *and* the X/NSS/Mesa
+  libraries. In a bare container point `FONTCONFIG_PATH` at a `fonts.conf` covering any TTF and
+  `LD_LIBRARY_PATH` at a directory holding those libraries — without fonts, Skia panics instead of
+  rendering, and the failure looks like a broken page rather than a missing package.
 
 ## Where to extend
 
@@ -123,6 +211,6 @@ trusted publishing.
 
 ## Publishing
 
-`pnpm pack` runs `prepack` (a full build) and ships `bin/`, `dist/`, `uis/stock/dist`, `README.md`,
-`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`, `SERVERS.md`,
+`NOTIFICATIONS.md`, `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/NOTIFICATIONS.md

@@ -0,0 +1,69 @@
+# Notifications
+
+home-hosted can push supervision events to a Telegram chat. It is the only transport today, it is
+opt-in, and the bot token never leaves the secrets file.
+
+## Setup
+
+1. Talk to [@BotFather](https://t.me/BotFather), run `/newbot`, and copy the token it prints.
+2. In the panel: **Settings → Notifications**, paste the token, press **Detect chats**.
+3. Send your bot a message from the chat you want the alerts in — a bot cannot open a conversation —
+   then pick that chat from the list (or paste its id).
+4. Press **Test**: the chat gets a message, and the panel shows the result and its timestamp.
+5. Turn on **Enabled**, then choose which events you want.
+
+<details>
+<summary><b>Doing it without the UI</b></summary>
+
+```bash
+TOKEN='123456:ABC...'
+
+curl -X POST http://127.0.0.1:3999/api/notifications/token \
+  -H 'content-type: application/json' -H "Authorization: Bearer $HH_TOKEN" \
+  -d "{\"botToken\":\"$TOKEN\"}"
+
+# which chats can this bot see (after you message it once)?
+curl -X POST http://127.0.0.1:3999/api/notifications/detect-chats \
+  -H 'content-type: application/json' -H "Authorization: Bearer $HH_TOKEN" \
+  -d "{\"botToken\":\"$TOKEN\"}"
+
+curl -X POST http://127.0.0.1:3999/api/notifications/test \
+  -H 'content-type: application/json' -H "Authorization: Bearer $HH_TOKEN" \
+  -d '{"chatId":"123456789"}'
+```
+
+`detect-chats` and `test` accept an override, so a token can be tried before it is saved.
+`DELETE /api/notifications/token` removes it.
+
+</details>
+
+## What it sends
+
+| event | toggle | default |
+| --- | --- | --- |
+| a server gave up restarting | `onCrash` | ✅ |
+| a server exceeded its memory limit | `onCrash` | ✅ |
+| a health check is failing | `onUnhealthy` | ✅ |
+| a server was force-restarted (health timeout) | `onForcedRestart` | ✅ |
+| a server recovered | `onRecovered` | ⬜ |
+| host thresholds breached, and recovered | `onHost` | ✅ |
+
+Host thresholds themselves — disk, memory, swap, load, temperature — are **Settings → Host**.
+
+## Quiet periods
+
+`cooldownMs` (default two minutes) is per **server and reason**, so a flapping process cannot flood
+the chat: it says "down", stays quiet while it flaps, and speaks again once the window passes. `0`
+disables the throttle.
+
+## Where the token lives
+
+`$HHOSTED_HOME/.control-secrets.json`, mode `0600`, next to the password and API-token hashes. It is
+never written into `servers.config.json`, so committing or sharing a config cannot leak it — and
+`GET /api/settings` reports `tokenSet: true|false`, never the token itself.
+
+## Delivery failures
+
+Sends are fire-and-forget: supervision never waits on a chat API. A failure is logged and the last
+result is shown in **Settings → Notifications** (`lastResult`, `lastResultAt`), so a wrong chat id is
+visible there instead of silently swallowing alerts.