home-hosted 0.4.1 → 0.6.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`, `reclaim`, or `kill` — 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
 
@@ -66,6 +66,7 @@ Preflight runs before every start, so two servers cannot silently fight over one
 | `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 |
+| `kill` | stops **whatever holds the port** — no ownership test — then starts. The blunt one: see below |
 
 ### When a program restarts itself
 
@@ -74,14 +75,32 @@ update, a `re-exec` on config change. The panel used to see the successor's port
 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:
+can tell a successor from a stranger — read from `/proc` on Linux and `ps -E` on macOS. **Windows
+cannot read another process's environment**, so there the entry's own argv answers instead: a process
+holding the port is the successor when its image and its arguments are both the entry's own. That
+fallback also covers a Linux or macOS program that restarted itself in a way that dropped the marker.
+Two policies act on the result:
 
 | 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 |
 
+Identification is deliberately strict, because `reclaim` kills what it identifies: the image has to be
+the entry's resolved command **and** the arguments have to be the entry's own, compared literally — an
+argument sharing a basename with another program's is not a match. When **more than one** holder
+matches, the panel refuses to guess and blocks, naming the pids. These are the cases that still block
+rather than being identified:
+
+- a successor that re-execs under a **different image**, or rewrites its own arguments;
+- an argument read back ambiguously — on macOS `ps` joins argv with spaces, so an argument that itself
+  contains a space cannot be told from two arguments;
+- a Windows entry launched through an `npm`/`pnpm` **`.cmd` shim**: the shim runs under `cmd.exe`, so
+  the process actually holding the port is `node.exe` and its argv never mentions the shim;
+- a Windows entry whose `CommandLine` PowerShell cannot read.
+
+`kill` exists precisely for those cases: it does not need to identify anything.
+
 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`.
@@ -91,11 +110,45 @@ 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
+set onPortConflict to "follow" to adopt it, "reclaim" to replace it with a supervised process,
+or "kill" to stop whatever holds the port
 ```
 
+### The `kill` policy
+
+`follow` and `reclaim` need to know *whose* port it is. When they cannot answer that — a program that
+re-execs under a different image, or two holders that both look like the entry — `kill` skips the
+question:
+
+1. SIGTERM every listener on the port, escalating to SIGKILL after `stop.graceMs`.
+2. Wait for the port to actually accept nothing, then start as usual.
+3. If the port is somehow still held, the entry goes to **conflict** with the pids it tried —
+   it does **not** retry in a loop.
+
+It is the one policy that will stop a **stranger** whose port you have configured, so the log says
+which pids it stopped and why. It will not touch the panel itself or any process the panel
+supervises: a port held by a sibling entry is a config mistake and still blocks, exactly as it does
+under `block`. If it is a stray leftover you would rather inspect first, the **Free port** button on
+the server card does the same thing on demand.
+
+Because a detached successor is not something the panel supervises, `kill` ends up doing what
+`reclaim` does for your own restarted process — stops it and starts a supervised child — without ever
+asking whether it was yours. Only `follow` ever adopts, and only `reclaim` will refuse to act on a
+holder it cannot prove is yours.
+
 ## 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.1",
+  "version": "0.6.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>",
@@ -33,17 +33,18 @@
   },
   "main": "./dist/cli.js",
   "bin": {
-    "home-hosted": "bin/home-hosted.mjs"
+    "home-hosted": "bin/home-hosted.mjs",
+    "hh": "bin/home-hosted.mjs"
   },
   "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 +54,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 +79,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",
@@ -102,6 +105,7 @@
     "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",