home-hosted 0.2.0

package/UI_CREATION.md

@@ -0,0 +1,148 @@
+# 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.
+
+```text
+$HHOSTED_HOME/.ui/            ← your build lives here
+  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).
+
+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.
+
+**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.
+
+## 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.
+
+## The API
+
+Two ways to consume it, both generated from the same ArkType schemas the server validates
+with:
+
+| | |
+| --- | --- |
+| 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` |
+
+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.
+
+### The 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/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.
+
+### Failures
+
+Every failing request answers with one envelope:
+
+```json
+{ "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).
+
+### 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 |
+| `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.
+
+## Adding a UI to 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.
+
+```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
+```
+
+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`).
+
+## 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/
+
+# 2. make sure the API base is relative, then zip the build
+cd dist && zip -r ../my-panel.zip . && cd ..
+
+# 3. Settings → Interface → Install UI, and 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
+`http://127.0.0.1:3999` the same way.
+
+## Checklist
+
+- [ ] `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)
+- [ ] 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

package/bin/home-hosted.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * The published entry point. It prefers the built CLI and falls back to the
+ * TypeScript sources, so a linked checkout works before its first build.
+ */
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(fileURLToPath(new URL('..', import.meta.url)))
+const built = path.join(root, 'dist', 'cli.js')
+const args = process.argv.slice(2)
+const hasBuild = fs.existsSync(built)
+
+const commandArgs = hasBuild
+  ? [built, ...args]
+  : ['--import', 'tsx', path.join(root, 'src', 'cli.ts'), ...args]
+
+const child = spawn(process.execPath, commandArgs, {
+  // The caller's directory is the project: relative entry paths resolve there.
+  cwd: hasBuild ? process.cwd() : root,
+  env: { ...process.env, HHOSTED_PROJECT: process.env.HHOSTED_PROJECT ?? process.cwd() },
+  stdio: 'inherit',
+})
+
+child.once('error', (error) => {
+  process.stderr.write(`home-hosted could not start: ${error.message}\n`)
+  process.exit(1)
+})
+child.once('exit', (code, signal) => {
+  process.exit(code ?? (signal === null ? 0 : 1))
+})