home-hosted 0.2.0 → 0.4.0

package/SERVERS.md

@@ -0,0 +1,101 @@
+# Servers
+
+Every supervised process is one entry in `$HHOSTED_HOME/servers.config.json`. Add it with **➕ Add
+server** in the panel, or write it by hand — the panel writes the same file.
+
+```json
+{
+  "id": "myapp",
+  "command": "node",
+  "args": ["server.js"],
+  "cwd": "./apps/myapp",
+  "port": 8080,
+  "autostart": true,
+  "env": { "NODE_ENV": "production" },
+  "health": { "mode": "http", "http": { "path": "/healthz" } }
+}
+```
+
+Relative paths resolve against the directory you ran `home-hosted` from, so a project can keep its
+servers and its state together.
+
+## Field reference
+
+| field | what it does |
+| --- | --- |
+| `command`, `args`, `cwd` | what to run, with `{placeholders}` resolved per entry |
+| `env`, `dataEnvs`, `envFile` | environment; `dataEnvs` also marks data directories for backups, `envFile` keeps secrets out of the config |
+| `port`, `bind` | enables the readiness wait, health checks and the conflict preflight; `local` keeps it on `127.0.0.1` |
+| `onPortConflict` | `block` (default), `warn`, or `adopt` — see below |
+| `health.mode` | `port` (TCP connect) or `http` (path, expected status, expected body) |
+| `health.unhealthyThreshold`, `forceRestartAfterMs` | how many failed probes before the card warns, and when to restart anyway |
+| `restart.*` | backoff: `maxRetries`, `baseDelayMs`, `factor`, `maxDelayMs`, `resetAfterMs` |
+| `stop.*` | `signal`, `killGroup`, `graceMs`, and `killPortHolders` to sweep a leftover listener |
+| `dependsOn` | ids that must be healthy first; stopped in reverse order |
+| `resources.maxRssBytes` | restart when the process tree grows past a limit |
+| `bootstrap` | one command to run once before the first start (migrations, warmups) |
+| `backupPaths` | extra paths this entry owns, included in backups |
+
+### Placeholders
+
+| placeholder | resolves to |
+| --- | --- |
+| `{id}` `{label}` | the entry's id, and its label (falling back to the id) |
+| `{port}` | its configured port, empty when it has none |
+| `{bind}` `{host}` `{displayHost}` | `local`/`lan`/an address; the address it binds (`127.0.0.1`, `0.0.0.0`); the address to *show* (`127.0.0.1`, the LAN IP) |
+| `{lanIp}` | this machine's LAN address, or `127.0.0.1` |
+| `{cwd}` | the entry's working directory (its `cwd`, else the project directory) |
+| `{projectDir}` | where you ran `home-hosted` (or `--project`) — `$HHOSTED_PROJECT` |
+| `{dataRoot}` | the state directory — `$HHOSTED_HOME`, default `~/.home-hosted` |
+| `{home}` | the current user's home directory |
+
+Unknown placeholders stay visible instead of silently becoming empty, and `${VAR}` reads from the
+environment (including `envFile`). Every supervised process also gets `HHOSTED_SERVER_ID` and
+`HHOSTED_CONTROL_PORT`, so a service can tell which entry it is and how to reach the panel.
+
+`dataEnvs` is the one that pays for itself twice: the value is exported to the process *and* the path
+is picked up by Backups, so a data directory is declared once.
+
+## A busy port
+
+Preflight runs before every start, so two servers cannot silently fight over one port.
+
+| `onPortConflict` | what happens when something already listens |
+| --- | --- |
+| `block` *(default)* | the entry goes to **conflict** with `port 4000 is already in use (pid 4242)`, and does not start |
+| `warn` | it starts anyway — useful when the listener is a leftover you are replacing |
+| `follow` | if the listener is a **detached restart of this same entry**, the panel adopts it as-is; anything else blocks, exactly like `block` |
+| `reclaim` | same detection, but it stops that successor and starts a fully supervised process of its own |
+
+### When a program restarts itself
+
+Some programs restart themselves by launching a new detached process and exiting — a plugin doing an
+update, a `re-exec` on config change. The panel used to see the successor's port as a conflict and sit
+there blocked while the service was actually up.
+
+Every process gets `HHOSTED_SERVER_ID` in its environment and a successor inherits it, so the preflight
+can tell a successor from a stranger (Linux `/proc`, macOS `ps -E`; Windows has no per-process
+environment, so there you get the conflict banner and the free-port button). Two policies act on that:
+
+| policy | what it does | trade-off |
+| --- | --- | --- |
+| `follow` | adopts the successor: pid, health probe, CPU/RSS, stop, and it starts its own process again when the successor exits | **keeps exactly what the program set up**, but its output is not captured — the pipe belongs to whoever spawned it, so that entry's log in the panel goes quiet |
+| `reclaim` | stops the successor, then starts a fully supervised process of its own | **full features** — live logs, resources, stop semantics all behave like any other entry — at the cost of one restart |
+
+Both are shown as **detached** in the panel while adopted, both can be stopped and restarted like any
+other entry, and neither will ever start a second copy on top of a **stranger**: that still blocks,
+exactly like `block`.
+
+If the holder is ours under a different policy, the conflict message says so, which is how the setting
+is discovered:
+
+```text
+port 4374 is already in use (pid 912) — pid 912 is a detached restart of this entry:
+set onPortConflict to "follow" to adopt it, or "reclaim" to replace it with a supervised process
+```
+
+## Editing fields
+
+Changes from the panel are atomic and validated before they are written. Editing an entry in the file
+by hand is picked up without a restart; a value the schema rejects is refused with the exact path, and
+the panel keeps running on the config it already had.

package/UI_CREATION.md

@@ -1,77 +1,106 @@
 # Building a UI for home-hosted
 
-The panel's UI is **a static site, and it is replaceable**. The stock one ships in the
-package; yours is a folder of files that the control plane serves instead — same API, same
-authentication, no server changes and no fork.
+The panel's UI is **a static site, and it is replaceable**. The stock one ships in the package;
+yours is a folder of files the control plane serves instead — same API, same authentication, no
+server changes and no fork.
+
+## Ask an AI to build it
+
+The whole contract is this file, so a coding agent can do the work. Point it at this repo and be
+specific about what you want:
+
+> Help me build a UI for `home-hosted`: a nostalgic game theme. Servers as a party menu, health as
+> HP bars, logs in a text-box pane, keyboard navigation, and a save-state corner for backups.
+> Follow `UI_CREATION.md`.
+
+Then zip the build and install it (below). Useful constraints to include in the prompt: the API is
+same-origin (relative `/api/...`), `401 { code: 'AUTH_REQUIRED' }` means "show the login screen",
+live data should come from SSE, and assets must be self-hosted. Existing directions to borrow from
+live in [`docs/mockups/`](./docs/mockups) — or ask for something else entirely; the server does not
+care what your UI looks like.
+
+## Install it
 
 ```text
-$HHOSTED_HOME/.ui/            ← your build lives here
+$HHOSTED_HOME/.ui/            ← where your build lives
   index.html                  ← required, at the root
   assets/…
   ui.json                     ← optional: { "name": "my-panel", "version": "2.1.0" }
 ```
 
-## Install it
-
-**Settings → Interface** → pick a `.zip` and *Install UI* (refresh to see it). Or drop the
-files in `$HHOSTED_HOME/.ui` yourself. The zip may contain the files at its root, or inside
-one wrapper directory (`zip -r ui.zip dist` also works).
+**Settings → Interface** → pick a `.zip` → *Install UI* (refresh to see it). Or drop the files into
+`$HHOSTED_HOME/.ui` yourself. The zip may hold the files at its root or inside one wrapper directory
+(`zip -r ui.zip dist` works too). `ui.json` is optional; it is what the settings page shows as
+installed.
 
-There is no build step on the server side: whatever you upload is served as-is. So ship
-plain HTML/JS/CSS, or the output of your own Vite/Next/Astro build with relative asset paths.
+Nothing is built on the server side: whatever you upload is served as-is, so ship plain
+HTML/JS/CSS or the output of your own Vite/Next/Astro build with relative asset paths.
 
 **If it breaks:** `home-hosted ui-revert` puts the stock panel back (or *Revert to stock* in
-the settings page). The CLI also prints a reminder on startup while a custom UI is active,
-because a broken UI must never lock you out of your own server.
+Settings). The CLI also prints a reminder at startup while a custom UI is active — a broken UI must
+never lock you out of your own machine.
 
 ## Rules of the road
 
-1. **Static only.** No server code, no environment variables, no filesystem. Anything you
-   need comes from the API.
-2. **Same origin, relative paths.** Call `/api/...` (never an absolute host): the panel may
-   be reached over loopback, a LAN address, TLS or a proxy.
-3. **`index.html` at the root** (or inside a single wrapper directory). Deep links work:
-   unknown paths fall back to `index.html`, so client-side routing is fine.
-4. **Keep the login flow.** The API answers `401` with `{"code":"AUTH_REQUIRED"}` when a
-   session is missing — route to your login screen and `POST /api/auth/login`.
-5. **Self-host your assets.** An offline home server should not need a CDN.
-6. **Limits:** a zip of at most 20 000 entries / 512 MB uncompressed, no absolute paths, no
-   `..`, no symlinks, no drive letters.
+1. **Static only.** No server code, no filesystem, no environment variables. Everything comes from
+   the API.
+2. **Same origin, relative paths.** Call `/api/...`, never an absolute host: the panel may be
+   reached over loopback, a LAN address, TLS or a proxy.
+3. **`index.html` at the root** (or in a single wrapper directory). Unknown paths fall back to it,
+   so client-side routing and deep links just work.
+4. **Keep the login flow.** Without a session the API answers `401` with `{"code":"AUTH_REQUIRED"}` —
+   show your login screen and `POST /api/auth/login`.
+5. **Self-host your assets.** An offline home server should not need a CDN, and neither should its
+   panel.
+6. **Limits:** ≤ 20 000 entries, ≤ 512 MB uncompressed, no absolute paths, no `..`, no symlinks, no
+   drive letters.
+7. **Offline and plain-http friendly.** Assume a LAN over `http://`: no `Secure`-only cookies, no
+   hard-coded port, no https-only APIs.
 
 ## The API
 
-Two ways to consume it, both generated from the same ArkType schemas the server validates
-with:
+Both routes below are generated from the same ArkType schemas the server validates with, so they
+cannot drift:
 
-| | |
-| --- | --- |
 | approach | how |
 | --- | --- |
-| **OpenAPI** | `GET /openapi/spec.json` (no session needed); browse it at `GET /openapi/ui` |
-| **Typed RPC** | building inside this repo: `import type { AppType } from '@server/app'` + `hc<AppType>()`, as `uis/stock/src/lib/rpc.ts` does |
-| **Generated types** | `npx openapi-typescript http://127.0.0.1:3999/openapi/spec.json -o src/api.d.ts` |
+| **OpenAPI** | `GET /openapi/spec.json` (no session needed); browse it at `/openapi/ui` |
+| **Typed RPC** | inside this repo: `import type { AppType } from '@server/app'` + `hc<AppType>()`, as `uis/stock/src/lib/rpc.ts` does |
+| **Generated types** | `pnpm dlx openapi-typescript http://127.0.0.1:3999/openapi/spec.json -o src/api.d.ts` |
 
-The stock UI (`uis/stock/src/lib/api.ts`) is the reference client: `fetch` for everything, with
-ArkType validating the responses at runtime. Either style is fine.
+`uis/stock/src/lib/api.ts` is the reference client: plain `fetch`, with ArkType validating the
+responses at runtime. Either style is fine.
 
-### The endpoints you will actually use
+### Endpoints you will actually use
 
 | endpoint | what it gives you |
 | --- | --- |
-| `GET /api/state` | everything: panel settings, servers with live status, host vitals. Live clients should use SSE instead |
-| `GET /api/events` | **the live feed.** `event: hello` carries the full state, then `state`, `server` and `log` frames |
+| `GET /api/state` | everything: panel settings, servers with live status, host vitals |
+| `GET /api/events` | **the live feed**: `hello` carries the full state, then `state`, `server`, `log` |
 | `GET /api/servers/:id/stream` | one server's `server` + `log` frames |
 | `POST /api/servers/:id/{start,stop,restart}`, `/api/servers/{start-all,stop-all}` | lifecycle |
-| `GET /api/servers`, `POST /api/servers`, `PATCH` / `DELETE /api/servers/:id` | the entries themselves |
-| `GET /api/logs`, `GET /api/logs/:id?tail=&search=&stream=`, `GET /api/logs/:id/download?file=` | persisted logs |
-| `GET` / `PATCH /api/settings`, `POST` / `DELETE /api/settings/tls` and `/api/settings/ui` | the panel's own configuration |
-| `POST /api/backups`, `GET /api/backups`, `POST /api/backups/restore`, `GET /api/backups/:name/download`, `DELETE /api/backups/:name` | archives |
-| `POST` / `DELETE /api/notifications/token`, `POST /api/notifications/test`, `POST /api/notifications/detect-chats` | Telegram |
-| `GET /healthz` | liveness, **no session** — 503 when an autostart server has crashed |
-| `GET /api/metrics` | Prometheus text |
-
-`GET /healthz` and `GET /openapi/*` are the only unauthenticated reads; the SPA shell itself
-is public too, so your app can load before a session exists.
+| `POST /api/servers/:id/free-port` | ask whatever holds that server's port to stop (`403`-safe: supervised listeners are refused) |
+| `GET` / `POST /api/servers`, `PATCH` / `DELETE /api/servers/:id` | the entries themselves |
+| `GET /api/logs`, `/api/logs/:id?tail=&search=`, `/api/logs/:id/download?file=` | persisted logs |
+| `GET` / `PATCH /api/settings` | the panel's own config (`control.label`, host thresholds, backups, …) |
+| `POST` / `DELETE /api/settings/ui` | install or revert a UI — what the settings page calls |
+| `POST` / `DELETE /api/settings/tls` | upload or clear a PEM pair |
+| `GET` / `POST /api/backups`, `/api/backups/restore`, `/api/backups/:name/download` | archives |
+| `POST` / `DELETE /api/notifications/token`, `/api/notifications/test`, `/detect-chats` | Telegram |
+| `POST /api/auth/login`, `GET /api/auth/session`, `POST /api/auth/logout` | the session |
+| `GET /healthz` | liveness — **no session**, and `503` when an autostart server has crashed |
+| `GET /api/metrics` | Prometheus text (needs a session) |
+
+`GET /healthz` and `GET /openapi/*` are the only unauthenticated reads; the SPA shell itself is
+public, so your app can load before a session exists.
+
+Anything calling the API from outside a browser — a script, a test, an agent, a native shell — can
+skip the login dance with an API token: `home-hosted set-token --generate` prints one once, and
+`Authorization: Bearer <token>` authenticates every `/api` request with the same authority as a
+signed-in session. The browser app you ship should still use the cookie.
+
+Two settings worth reflecting: `control.label` is the panel's own name (the stock shell shows it),
+and `GET /api/settings` includes `ui` — which UI is being served, and its metadata.
 
 ### Failures
 
@@ -81,58 +110,57 @@ Every failing request answers with one envelope:
 { "message": "unknown server \"web\"", "code": "UNKNOWN_SERVER", "detail": { "…": "…" } }
 ```
 
-`code` is stable and machine-readable (`AUTH_REQUIRED` drives the login redirect); `detail`
-carries validation issues or context when there is any. Status codes are the usual ones
-(400 bad input, 401 no session, 403 bad token/origin, 404 unknown id, 409 conflict, 413 too
-large).
+`code` is stable and machine-readable (`AUTH_REQUIRED` drives the login redirect); `detail` carries
+validation issues when there are any. Status codes are the usual ones: 400 bad input, 401 no
+session, 403 bad token or origin, 404 unknown id, 409 conflict, 413 too large.
 
 ### SSE frames
 
 | `event:` | `data:` |
 | --- | --- |
-| `hello` | `{ ts, state }` — the first frame, with the complete snapshot |
-| `state` | `{ ts, state }` — anything changed: a status, a resource sample, the host vitals |
+| `hello` | `{ ts, state }` — the first frame, the complete snapshot |
+| `state` | `{ ts, state }` — anything changed: a status, a resource sample, host vitals |
 | `server` | `{ ts, serverId, server }` — one entry, after an action or a probe |
 | `log` | `{ ts, serverId, lines }` — new output (dropped under backpressure, never state) |
 | `ping` | the current time, every 15 s |
 
-The exact frames are in `src/shared/contracts.ts` (`sseMessageSchema`) — the server validates
-against them before writing, so that schema is also your best type source.
-
-Send `?logs=0` to skip log frames, or `?serverId=<id>` for one server. The server pings every
-15 s.
+Send `?logs=0` to skip log frames, or `?serverId=<id>` to follow one server. The exact shapes are
+`sseMessageSchema` in `src/shared/contracts.ts` — the server validates against it before writing, so
+that schema is also your best type source.
 
-## Adding a UI to this repo
+## Building one in this repo
 
-`uis/<name>/` is a Vite app: `index.html`, `src/`, a `tsconfig.json` (copy a sibling's) and a 2-line
-`vite.config.ts` calling `createUiConfig` from `uis/vite.shared.ts`. `public/ui.json` names it.
+The repo's own UIs are Vite apps: `uis/<name>/` holds `index.html`, `src/`, a `tsconfig.json`
+(copied from a sibling) and a two-line `vite.config.ts` calling `createUiConfig` from
+`uis/vite.shared.ts`, with `public/ui.json` naming it. Yours does not have to be Vite — only the
+output matters.
 
 ```sh
-node scripts/build-uis.mjs <name> --zip   # builds it and writes uis/dist/home-hosted-ui-<name>.zip
-pnpm run build:uis                        # every UI, zipped; the release attaches them as assets
+node scripts/build-uis.mjs <name> --zip   # builds it, writes uis/dist/home-hosted-ui-<name>.zip
+pnpm run build:uis                        # every UI, zipped; releases attach them as assets
 ```
 
-Only `stock` ships inside the npm package — the others are release assets you upload from
-Settings → Interface. `pnpm run quickcheck` type-checks every UI, and `pnpm test` (vitest) picks up
-any `test/*.test.ts` you add (use relative imports; the `@` alias points at `stock`).
+Only `stock` ships inside the npm package; the rest are release assets you install from Settings.
+`pnpm run quickcheck` type-checks every UI, and `pnpm test` picks up any `test/*.test.ts` you add
+(use relative imports — the `@` alias points at `stock`).
 
 ## A worked example
 
 ```bash
 # 1. any static framework; the only requirement is a static output
 npm create vite@latest my-panel -- --template vue-ts
-cd my-panel && npm install
-npm run build                       # → dist/
+cd my-panel && pnpm install
+pnpm run build                      # → dist/
 
-# 2. make sure the API base is relative, then zip the build
+# 2. keep the API base relative, then zip the build
 cd dist && zip -r ../my-panel.zip . && cd ..
 
-# 3. Settings → Interface → Install UI, and refresh
+# 3. Settings → Interface → Install UI, then refresh
 ```
 
-Your client needs the session cookie, which the browser sends automatically once you log in
-on that origin. For local development, `pnpm dev` in this repo runs the panel on 3999 and a
-Vite dev server on 3998 with `/api` proxied, so you can point your own dev server at
+Your client needs the session cookie, which the browser sends automatically once you log in on that
+origin (a non-browser client uses an API token instead, above). For local development `pnpm dev` runs
+the panel on 3999 and a Vite dev server on 3998 with `/api` proxied — point your own dev server at
 `http://127.0.0.1:3999` the same way.
 
 ## Checklist
@@ -140,9 +168,8 @@ Vite dev server on 3998 with `/api` proxied, so you can point your own dev serve
 - [ ] `index.html` at the root of the zip, assets referenced relatively
 - [ ] only `/api/...` calls, no absolute origins, no hard-coded port
 - [ ] `401 { code: 'AUTH_REQUIRED' }` handled with a login screen
-- [ ] live data from SSE (a panel that only polls feels broken)
+- [ ] live data from SSE — a panel that only polls feels broken
 - [ ] deep links render (the server falls back to `index.html`)
-- [ ] assets self-hosted; no CDN dependencies
-- [ ] works offline over plain http on a LAN (no `Secure`-only cookies, no https assumptions)
-- [ ] `ui.json` with a name and version, so *Settings → Interface* can tell you what is
-      installed
+- [ ] assets self-hosted, no CDN
+- [ ] works over plain http on a LAN
+- [ ] `ui.json` with a name and version, so Settings can tell you what is installed