home-hosted 0.6.1 → 0.6.3

package/AGENTS.md

@@ -7,7 +7,8 @@ and serves a UI. User docs: `README.md`, `docs/SERVERS.md` (entries and port con
 
 State lives only in `$HHOSTED_HOME` (default `~/.home-hosted`): `servers.config.json`,
 `.control-secrets.json` (0600: password hash, API token hash, Telegram bot token), `.logs/`, `.tls/`,
-`.backups/`, `.ui/`, and `run.json` — the live daemon's pid/url/token, 0600. The package ships **no
+`.backups/`, `.ui/`, `.state/` (a persistent entry's nanny state, plus its 0600 spawn spec until the
+nanny reads it), and `run.json` — the live daemon's pid/url/token, 0600. The package ships **no
 servers**: never commit a config, a seed entry, or a path that names one.
 
 ## Commands
@@ -31,21 +32,39 @@ pnpm run media                     # regenerate docs/media (mockups, both served
 The published bin is `home-hosted`, with an `hh` alias: both names run the same CLI.
 
 Releases are dispatched from `.github/workflows/release.yml` with a version (and a `dry-run` switch
-that stops before pushing). It verifies the version against `package.json`, lints/types/tests,
-builds the CLI plus the stock UI and every UI zip, lets changelogen write the changelog and tag
+that stops before pushing). It verifies the version, lints/types/tests, builds the CLI plus the stock
+UI and every UI zip, lets changelogen write the changelog, bump `package.json`, commit and tag
 `v<version>`, creates the GitHub release with the UI bundles attached, and publishes to npm through
 trusted publishing (OIDC, no token). npm only offers a trusted publisher for a package that already
 exists, so the first release has to be published by hand.
 
+### Which version to dispatch
+
+Below 1.0 the **minor is the breaking channel**: a fix or a non-breaking feature is a **patch**
+(`0.6.2` → `0.6.3`), while a minor (`0.6.3` → `0.7.0`) means someone has to read the release notes and
+act. A `feat:` commit does not decide this — ask what the user has to do about it.
+
+Never edit `package.json` by hand; changelogen bumps, commits and tags inside the workflow:
+
+```sh
+gh workflow run release.yml -f version=0.6.3          # -f dry-run=true to rehearse
+```
+
+`scripts/check-release-version.mjs` refuses a patch while a breaking commit is pending, and warns on
+a minor without one.
+
 ## Architecture (and why)
 
 - `src/cli.ts` — the CLI's thin root. Two things happen before [citty](https://github.com/unjs/citty)
   is asked anything: `--home`/`--project` are peeled off and applied (`src/cli/args.ts`), and the
   curated dispatch — `help`/`version`, `unknown command`, and the `-p 4000` shorthand for `up` — is
   decided, because `#src/helpers/paths.ts` resolves at import time. Its static imports stay node
-  builtins, citty and those two path-free local modules; every command is a lazy
+  builtins, citty and the two path-free local modules (`src/cli/args.ts`, `src/helpers/runtime.ts`);
+  every command is a lazy
   `() => import('#src/cli/<command>')` in citty's `subCommands`, so a command module *may* use static
-  `#src` imports (that is the whole point of the pre-pass). citty's `runMain` is deliberately not
+  `#src` imports (that is the whole point of the pre-pass). The hidden `__nanny` is dispatched by an
+  early branch, not `subCommands`, so it stays out of the curated help and the unknown-command
+  message — the panel spawns it, nobody types it. citty's `runMain` is deliberately not
   used: it prints its own usage and `console.error`s before `process.exit(1)`, replacing `fail()`'s
   one error shape; the root calls `runCommand` and catches. `src/cli/<command>.ts` is one command per
   file — citty owns dispatch and argument parsing, with `--no-autostart`/`--no-install` declared as
@@ -69,12 +88,17 @@ exists, so the first release has to be published by hand.
   `migrations.ts` (the schema constant and the ordered step registry), `secrets.ts`, `seed.ts`.
 - `src/providers/` — stateless leaves: `process` (spawn, `terminate`, `terminatePid` for a process we
   adopted), `port` (probe, holder lookup, `terminatePids`), `proc` (the sampler, plus
-  `processCarriesServerId` for the environment marker), `identity` (which port holder is this entry's
-  own successor: marker first, then resolved image + argv), health-check, host, telegram, archive.
+  `processCarriesServerId` for the environment marker and `processTreePids` for tree ownership),
+  `identity` (which port holder is this entry's own successor: marker first, then resolved image +
+  argv), `nanny` (a persistent entry's spec/state files and the liveness rules for one),
+  `log-tail` (an offset reader that survives rotation and truncation), health-check, host, telegram,
+  archive.
 - `src/services/` — stateful orchestration: supervisor, control-server, config-watch, state,
   auth + exposure, dependencies, history, log-buffer/log-files, notifications, host-monitor, backups,
   tls, ui, plus `init` (the scaffold behind `home-hosted init`: a manifest, a `.gitignore`, and the
-  prompts stay in the CLI). It names no server — the scaffold must stay as neutral as the supervisor.
+  prompts stay in the CLI), `nanny` (the process a persistent entry runs under) and `log-relay` (the
+  tailer that feeds its lines to the supervisor). It names no server — the scaffold must stay as
+  neutral as the supervisor.
 - `src/middleware/auth.ts` — the `/api/*` guard, and `requestIdentity()`, the one place a request's
   credentials are read: the `hh_session` cookie or `Authorization: Bearer <api token>`. A token is
   a first-class credential (same authority as a signed-in browser) and is verified from the secrets
@@ -202,6 +226,22 @@ either is a last resort, and never an accidental one.
   answer for them. `src/providers/identity.ts` owns the matching, and the argv it is given comes from
   the supervisor's single `resolveSpawn()`, the same one the spawn itself used — keep it to one
   resolver, because a second one that expands or filters args differently re-opens these cases.
+  Ownership covers the entry's whole **tree**, not the pid it recorded (`processTreePids`): a nanny
+  puts the real server one generation down, and so does any wrapper entry. The panel's own tree is
+  deliberately excluded — "ours" has to mean a process a server owns.
+- **A persistent entry is run by its own nanny, not by the panel.** `persistent: true` makes the panel
+  spawn the hidden `__nanny` (`src/services/nanny.ts`), which owns the child's pipes, writes its JSONL
+  and mirrors its exit — the only arrangement that outlives the panel *and* keeps logging. The panel
+  skips such an entry in `stopAll()`/`dispose()` (`down` reports what it left running), reattaches on
+  boot through `.state/<id>.json` before any port preflight (`nannyIsAlive` = live pid **and** a fresh
+  heartbeat, the `HHOSTED_SERVER_ID` marker or the argv), tails that file for live logs, and reads
+  `lastExit` once so a crash nobody watched is reported. The spawn spec is consumed by the read and
+  swept at boot — it carries expanded env. Two lifetimes are pinned: the nanny **exits with its child**
+  (an inherited pipe would keep it alive, and the panel would report a healthy entry whose server is a
+  detached stranger), and a stop reaches the child by pid from the state file, because `SIGKILL` and
+  `killGroup: false` cannot be forwarded — which is why a self-restarting program belongs on `reclaim`.
+  The nanny never restarts anything: retries and health stay the supervisor's. `logs.persist: false`
+  keeps that file out of the Logs page but never stops it being written — it is the transport.
 - **A port is only ever freed by re-listing its listeners.** `POST /api/servers/:id/free-port` never
   trusts a pid quoted in a message, and refuses any listener in `supervisedPids()` (the panel plus
   every entry's child) instead of killing it — a port held by a sibling is a config mistake.
@@ -268,7 +308,9 @@ either is a last resort, and never an accidental one.
   the live output view empty until a remount — a test that reads the array itself will not catch it.
 - An adopted process is not a `ChildProcess`, so nothing reports its exit: the tick polls liveness and
   hands the entry back to the normal `afterExit` path. Its output is not captured either — it was
-  redirected by whoever spawned it.
+  redirected by whoever spawned it. The exception is a persistent entry, whose output the panel
+  *does* capture: its nanny writes the JSONL, and `log-relay` tails it into the same buffer and SSE
+  frames a pipe would feed.
 - `stop.killPortHolders` frees a port only from a *listener* that is not our own process tree. Broad
   `lsof -ti:<port>` sweeps and pid-as-text parses have killed supervisors in the field; don't add one.
   `free-port` reuses the same lookup and adds the supervisor's own pid set on top.

package/README.md

@@ -40,8 +40,9 @@ You run a handful of services at home. The usual choices are extremes — 🧟 `
 forget about, 📜 a hand-written systemd unit per service (times six), or 🐳 a whole docker/k8s
 stack??? - too extreme! — plus 😩 monitoring, rebooting and changing the host machine, yuck!
 
-🙂 home-hosted, well, joins in somewhere: a panel/supervisor that starts them, watches them, restarts what dies, and
-puts the whole stack on one page, with deep backup support.
+🙂✨ home-hosted enhances on top: a panel/supervisor that starts them, watches them, restarts what
+dies, and puts the whole stack on one page, with deep backup support — whether a server is a plain
+command or a `docker compose` stack.
 
 ```text
                    ┌──────────────────────────────────────┐
@@ -54,8 +55,13 @@ puts the whole stack on one page, with deep backup support.
    ┌─────────┐               ┌─────────┐                ┌─────────┐
    │ gateway │               │ files   │                │ bot     │
    │ :4000   │               │ :4010   │                │  ...    │
-   └─────────┘               └─────────┘                └─────────┘
-     health ✓                  health ✓                  restarts ↻
+   └────┬────┘               └─────────┘                └─────────┘
+        │ compose up -d
+        ▼
+   ┌────────────┬────────────┬────────────┐
+   │  gateway   │  postgres  │   redis    │          restarts ↻
+   └────────────┴────────────┴────────────┘
+     health ✓ (the published port is the probe)
 ```
 
 |  |  |
@@ -147,7 +153,7 @@ data/                         # per-server data directories, declared through da
 
 One clone, `pnpm install --frozen-lockfile`, `pnpm run up` — the setup is up on any machine with Node.
 Worked example, with per-server data inside the project:
-**[hhosted-9router-dsh](https://github.com/NamesMT/hhosted-9router-dsh)**.
+**[hhosted-ai-pack](https://github.com/NamesMT/hhosted-ai-pack)**.
 
 <sub>Call them as `pnpm run up` — `pnpm up` is pnpm's own update, not your script.</sub>
 
@@ -190,8 +196,8 @@ home-hosted set-token --generate
 #   hh_9uA2…                     (printed once; only its hash is kept, mode 0600)
 
 curl -H "Authorization: Bearer hh_9uA2…" http://127.0.0.1:3999/api/state
-curl -H "Authorization: Bearer hh_9uA2…" -X POST http://127.0.0.1:3999/api/servers/9router/restart
-curl -N -H "Authorization: Bearer hh_9uA2…" 'http://127.0.0.1:3999/api/events?serverId=9router'   # SSE
+curl -H "Authorization: Bearer hh_9uA2…" -X POST http://127.0.0.1:3999/api/servers/omniroute/restart
+curl -N -H "Authorization: Bearer hh_9uA2…" 'http://127.0.0.1:3999/api/events?serverId=omniroute'   # SSE
 home-hosted status --json        # machine-readable: pid, url, health, paths
 ```
 
@@ -284,7 +290,7 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | command | |
 | --- | --- |
 | `home-hosted up` | start the panel detached, and keep it alive in the background |
-| `home-hosted down` | stop it cleanly — supervised processes included |
+| `home-hosted down` | stop it cleanly — supervised processes included, persistent entries left running |
 | `home-hosted restart` | `down`, then `up` |
 | `home-hosted status` | pid, URL, health, uptime, state and log paths (`--json` for scripts) |
 | `home-hosted set-password` | set the panel password without opening a browser |
@@ -396,7 +402,7 @@ archive and restore. Definitions come back, data lands where *this* machine's co
 `autostart` entries come up immediately.
 
 It works because an archive carries its own `servers.config.json` and paths are matched by the
-**declaration** (`9router:DATA_DIR`), not by an absolute path from the source machine. A restore never
+**declaration** (`omniroute:DATA_DIR`), not by an absolute path from the source machine. A restore never
 writes where no config declares.
 
 </details>
@@ -448,6 +454,10 @@ panel itself (`--foreground`) and for system services; use home-hosted for the r
 `home-hosted down` stops them — that is the point of the command. `SIGTERM`/`SIGINT` are handled
 the same way: every supervised process tree is stopped before the panel exits.
 
+An entry marked `persistent` is the exception, and `down` names it instead of stopping it: it runs
+under its own nanny process, keeps logging, and is reattached by the next panel
+([SERVERS.md](./docs/SERVERS.md#persistent-entries)).
+
 </details>
 
 <details>
@@ -529,6 +539,17 @@ types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 
 ---
 
+<details>
+<summary><b>🔗 Interesting resources</b></summary>
+
+- [dsh-home-hosted](https://github.com/NamesMT/dsh-home-hosted) — home-hosted servers management with boot autostart from [DeepSeek Harness](https://github.com/deepseek-ai/dsh)
+
+<sub><i>+ PR to add yours</i></sub>
+
+</details>
+
+---
+
 <div align="center">
 
 **MIT**