home-hosted 0.4.0 → 0.5.0

package/{SERVERS.md → docs/SERVERS.md}

@@ -26,7 +26,7 @@ servers and its state together.
 | `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 |
+| `onPortConflict` | `block` (default), `warn`, `follow`, or `reclaim` — 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` |
@@ -34,7 +34,7 @@ servers and its state together.
 | `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 |
+| `backupPaths`, `backupIgnoreGenerated` | extra paths this entry owns, included in backups; the flag (on by default) skips the known build and dependency directories inside them — `node_modules`, `dist`, `.next`, framework caches |
 
 ### Placeholders
 
@@ -96,6 +96,17 @@ set onPortConflict to "follow" to adopt it, or "reclaim" to replace it with a su
 
 ## 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.
+Changes from the panel are atomic and validated before they are written. Editing the file by hand —
+an editor, a `git checkout`, a config-management tool — is picked up within a couple of seconds, no
+restart needed:
+
+- **A definition you changed** takes effect on that entry's next start; a running process is not
+  restarted under you.
+- **A definition you added** appears (and starts itself if it is `autostart`); **one you removed** is
+  stopped and forgotten.
+- **A file the schema rejects, or one that cannot be parsed**, is reported in the panel with the
+  exact path and the running config is left alone. Fix it and it reloads on its own — a typo never
+  stops a server.
+
+A save from the panel's own UI is the panel's write: it replaces the file, so hand-edits made while
+it runs are lost by that next save. Edit, then let the panel read it back, before using the UI.

package/{UI_CREATION.md → docs/UI_CREATION.md}

@@ -11,12 +11,12 @@ 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`.
+> Follow `docs/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
+live in [`mockups/`](./mockups) — or ask for something else entirely; the server does not
 care what your UI looks like.
 
 ## Install it
@@ -33,6 +33,9 @@ $HHOSTED_HOME/.ui/            ← where your build lives
 (`zip -r ui.zip dist` works too). `ui.json` is optional; it is what the settings page shows as
 installed.
 
+Without the settings page, `home-hosted ui-switch` installs one from a GitHub release asset (its
+default), from a local `.zip` (`--file ./ui.zip`), or from a URL (`--file https://…/ui.zip`).
+
 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.
 
@@ -102,6 +105,11 @@ 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.
 
+An entry body is partial by design: `POST /api/servers` and `PATCH /api/servers/:id` take only the
+fields the person decided, and the panel's **Server defaults** fill the rest. Sending a value the
+person never chose freezes it against those defaults, so build the body as a diff
+(`inheritBaseline` and `diffFields` in `src/shared/patch-diff.ts`).
+
 ### Failures
 
 Every failing request answers with one envelope:
@@ -128,6 +136,30 @@ Send `?logs=0` to skip log frames, or `?serverId=<id>` to follow one server. The
 `sseMessageSchema` in `src/shared/contracts.ts` — the server validates against it before writing, so
 that schema is also your best type source.
 
+## Editing settings without fighting the stream
+
+Two things the API will not tell you, and both are what people report as bugs:
+
+- **A live frame must never overwrite a half-typed edit.** Every frame carries freshly built
+  objects, so a watcher that copies state into a form on each change reverts whatever is being
+  typed. The settings are also not one payload: host thresholds and the backups policy come from
+  `GET /api/settings`, which lands *after* the first SSE frame — a single "has anything changed?"
+  guard reads that late arrival as a pending edit, leaves those fields showing schema defaults
+  forever, and offers to "revert" a change nobody made. Fill each block on its own, and only while
+  that block is untouched since it was last filled (`uis/stock/src/components/settings/settingsForm.ts`).
+- **A boolean setting is a switch, not a checkbox.** Keep checkboxes for picking items out of a set
+  (a restore plan), where the control is the list entry. `uis/stock/src/components/ui/ToggleSwitch.vue`
+  is the reference.
+- **Decide to open the stream from the session, not from the auth flags.** With authentication off,
+  `authRequired` and `authenticated` are both `false` from the first paint to the last, so a watcher
+  on those two never re-runs when the session lands: no event stream is opened, the connection badge
+  sits on "Connecting", and the dashboard shows one stale snapshot forever. Turn the two flags into a
+  single decision (`wait` | `connect` | `login`) and watch that — see
+  `uis/stock/src/composables/useSession.ts`.
+
+A pending-edit summary pays for itself: show how many fields changed, and let the list be opened —
+`describeChanges` and `countLeaves` in `src/shared/patch-diff.ts` turn a patch into those rows.
+
 ## Building one in this repo
 
 The repo's own UIs are Vite apps: `uis/<name>/` holds `index.html`, `src/`, a `tsconfig.json`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "home-hosted",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "packageManager": "pnpm@12.5.1",
   "description": "A self-hosted control panel that keeps your home server processes alive - with a UI you can replace.",
   "author": "NamesMT <dangquoctrung123@gmail.com>",
@@ -38,12 +38,12 @@
   "files": [
     "AGENTS.md",
     "LICENSE",
-    "NOTIFICATIONS.md",
     "README.md",
-    "SERVERS.md",
-    "UI_CREATION.md",
     "bin",
     "dist",
+    "docs/NOTIFICATIONS.md",
+    "docs/SERVERS.md",
+    "docs/UI_CREATION.md",
     "uis/stock/dist"
   ],
   "engines": {
@@ -53,6 +53,7 @@
     "up": "tsx src/cli.ts up",
     "down": "tsx src/cli.ts down",
     "status": "tsx src/cli.ts status",
+    "restart": "tsx src/cli.ts restart",
     "start": "tsx src/cli.ts up --foreground",
     "dev": "node scripts/dev.mjs",
     "build": "pnpm run build:ui && pnpm run build:server",
@@ -77,6 +78,7 @@
     "@scalar/hono-api-reference": "^0.12.4",
     "@zip.js/zip.js": "^2.17.0",
     "arktype": "^2.2.3",
+    "citty": "^0.2.2",
     "consola": "^3.4.2",
     "grammy": "^1.46.0",
     "hono": "^4.13.8",
@@ -91,15 +93,18 @@
     "@types/node": "^24.13.3",
     "@vitejs/plugin-vue": "^6.0.9",
     "@vitest/coverage-v8": "^5.0.1",
+    "@vue/test-utils": "^2.5.1",
     "clsx": "^2.1.1",
     "eslint": "^10.11.0",
     "gifenc": "^1.0.3",
+    "happy-dom": "^20.14.5",
     "lint-staged": "^17.5.1",
     "lucide-vue-next": "^1.0.0",
     "playwright": "^1.63.0",
     "pngjs": "^7.0.0",
     "reka-ui": "^2.10.5",
     "simple-git-hooks": "^2.14.0",
+    "splitpanes": "^4.1.2",
     "tailwind-merge": "^3.7.0",
     "tailwindcss": "^4.3.3",
     "tsx": "^4.23.15",