home-hosted 0.3.0 → 0.4.0

package/UI_CREATION.md

@@ -66,7 +66,7 @@ cannot drift:
 | --- | --- |
 | **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** | `npx openapi-typescript http://127.0.0.1:3999/openapi/spec.json -o src/api.d.ts` |
+| **Generated types** | `pnpm dlx openapi-typescript http://127.0.0.1:3999/openapi/spec.json -o src/api.d.ts` |
 
 `uis/stock/src/lib/api.ts` is the reference client: plain `fetch`, with ArkType validating the
 responses at runtime. Either style is fine.
@@ -79,6 +79,7 @@ responses at runtime. Either style is fine.
 | `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 |
+| `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, …) |
@@ -93,6 +94,11 @@ responses at runtime. Either style is fine.
 `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.
 
@@ -143,8 +149,8 @@ Only `stock` ships inside the npm package; the rest are release assets you insta
 ```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. keep the API base relative, then zip the build
 cd dist && zip -r ../my-panel.zip . && cd ..
@@ -153,8 +159,9 @@ cd dist && zip -r ../my-panel.zip . && cd ..
 ```
 
 Your client needs the session cookie, which the browser sends automatically once you log in on that
-origin. 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.
+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