dsh-home-hosted 0.6.3 → 0.7.0

package/README.md

@@ -2,18 +2,21 @@
 
 # 📌 dsh-home-hosted
 
-**Your whole home stack, up after every reboot — your `dsh` web server included.**
+**Prompt your servers into existence — keep them running and manage them via dsh / `home-hosted` panel UI.**
+
+<sub>Your whole home stack, up after every reboot — your `dsh` web included.</sub>
 
 A [DeepSeek Harness](https://github.com/deepseek-ai/dsh) plugin for
 [home-hosted](https://github.com/NamesMT/home-hosted), the panel that supervises your services.
-Declare the servers once; this page manages the panel, the boot entry and the entries.
+Ask for a Gitea, a Jellyfin, an FTP server; `dsh-home-hosted` sets up the entries and manages them
+— panel, ports, restarts and boot autostart included.
 <sub>Nothing is installed or started until you say so.</sub>
 
 [![npm](https://img.shields.io/npm/v/dsh-home-hosted?label=npm&color=blue)](https://www.npmjs.com/package/dsh-home-hosted)
 [![CI](https://github.com/NamesMT/dsh-home-hosted/actions/workflows/ci.yml/badge.svg)](https://github.com/NamesMT/dsh-home-hosted/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/dsh-home-hosted?color=green)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org)
-[![dsh](https://img.shields.io/badge/dsh-%3E%3D0.1.7--rc.2-5b21b6)](https://github.com/deepseek-ai/dsh)
+[![dsh](https://img.shields.io/badge/dsh-%3E%3D0.2.0--rc.1-5b21b6)](https://github.com/deepseek-ai/dsh)
 
 [🚀 Quick start](#-quick-start) · [🎛️ What the plugin does](#-what-the-plugin-does) · [🤖 Agent tools](#-agent-tools) · [🧩 Depth](#-depth)
 
@@ -35,52 +38,59 @@ Declare the servers once; this page manages the panel, the boot entry and the en
 dsh plugin --profile web add dsh-home-hosted
 ```
 
-Open **Settings → Home Hosted**, turn on **Manage dsh**, and enable autostart.
-<sub>Reboot once; `dsh` comes back without you touching anything.</sub>
+Open **Settings → Home Hosted** and add your servers — or just ask the agent:
+
+> add a Gitea on 3000, and a Jellyfin on 8096
+
+Then, optionally, turn on **Manage dsh** and **Autostart**, so the panel — and everything in it —
+comes back after a reboot.
 
 ## 🤔 Why
 
-A panel restart shouldn't kill a prompt mid-flight, and a reboot shouldn't cost you an SSH session.
+Ever tried setting up a media server, a Gitea and a few more yourself — then keeping them all
+managed?
+
+`dsh-home-hosted` uses [home-hosted](https://github.com/NamesMT/home-hosted) to do it: prompt for
+the servers you want, let it write and configure the entries, and manage them all from dsh or the
+panel — ports, health, restarts and autostart included.
 
 ```text
-                 reboot
-                   │
-                   ▼
-  OS boot entry ──▶ home-hosted panel ──▶ ┌─────────────┐
-  systemd ·                    │          │ dsh web ✓   │
-   launchd ·                   │          └─────────────┘
-    XDG · Run key              │
-                               ├────────▶ ┌─────────────┐
-                               │          │ docker      │
-                               │          │ compose     │
-                               │          └─────────────┘
-                               │
-                               └────────▶ ┌─────────────┐
-                                          │ postgres    │
-                                          │ :5432       │
-                                          └─────────────┘
+   you ──▶ "add a Gitea, a Jellyfin, a cache…"
+             │
+             ▼
+   dsh-home-hosted ──▶ home-hosted panel ──▶ ┌──────────────┐
+     page · agent              │             │ gitea  :3000 │
+                               │             └──────────────┘
+                               ├──────────▶ ┌──────────────┐
+                               │             │ jellyfin     │
+                               │             │ :8096        │
+                               │             └──────────────┘
+                               └──────────▶ ┌──────────────┐
+                                             │ postgres     │
+                                             │ :5432        │
+                                             └──────────────┘
+
+   ★ OS boot entry ──▶ the panel comes back, and so does everything in it
+     systemd · launchd · XDG · Run key
 ```
 
 **`dsh` is one entry in the panel, not the whole product.** The panel is the supervisor: it starts
-each entry, watches it, restarts what dies and reclaims its port. Add your compose stack, your
-database, your bot — manage them from the page, or hand the entry ids to an agent.
+each entry, watches it, restarts what dies and reclaims its port. Add your Gitea, your Jellyfin,
+your compose stack, your database — manage them from the page, or hand the entry ids to an agent.
 
-A plugin cannot run at boot, so this one writes the OS entry while dsh runs and the OS takes over.
-One managed entry (`dsh`) is kept alive under home-hosted's nanny, so a panel restart leaves it
-running.
+Managing `dsh` itself is the bonus: the entry that keeps your harness up is a highlight on top of
+the server management, not the thing this plugin is.
 
 ## 🎛️ What the plugin does
 
 | | |
 |---|---|
-| 🚀 **Boot autostart** | Installs, verifies and removes the OS entry. Opt in per machine. |
-| 🛡️ **Survives a panel restart** | The managed entry runs under home-hosted's nanny, so restarting the panel leaves it running. |
-| 📦 **Ships its own panel** | The pinned `home-hosted` is a dependency, so boot runs the version this plugin is tested against. |
-| 🖥️ **Server control** | Add, edit, start, stop and restart entries — written through the panel's API, so nothing restarts behind your back. |
-| 🗂 **Workspaces** | The panel manages one workspace for the `dsh` entry; the page and the agent tools reach **every** workspace it serves, counts included. |
+| 🖥️ **Servers, set up by prompt** | Add, edit, start, stop and restart entries — Gitea, Jellyfin, FTP, a compose stack. Written through the panel's API, so nothing restarts behind your back. |
+| 🏠 **The whole home-hosted panel** | Not just servers: [BYOU](https://github.com/NamesMT/home-hosted#-bring-your-own-ui-byou) custom UIs, [workspaces](https://github.com/NamesMT/home-hosted#-workspaces), a [reverse proxy](https://github.com/NamesMT/home-hosted/blob/main/docs/REVERSE_PROXY.md) with automatic HTTPS, [backups](https://github.com/NamesMT/home-hosted#-backups) (zip or AES-256), [notifications](https://github.com/NamesMT/home-hosted/blob/main/docs/NOTIFICATIONS.md), [dynamic DNS](https://github.com/NamesMT/home-hosted/blob/main/docs/DDNS.md), health probes, live logs and host vitals. |
+| 🤖 **Agent tools** | On by default, session permissions still gate every write. |
+| 🚀 **Boot autostart** | *Highlight:* installs, verifies and removes the OS entry, so the panel starts at boot. Opt in per machine. |
 | 🧭 **Token warnings that mean something** | A missing or refused API token is called out on the page, with one click to mint a working one. |
 | 🪟 **Knows the other panels** | Several panels on one machine? The agent is told which one this plugin manages, and asks before touching another. |
-| 🤖 **Agent tools** | On by default, session permissions still gate every write. |
 
 ## 🤖 Agent tools
 
@@ -141,6 +151,18 @@ re-finds your build at boot, so a rebuild, a moved checkout or a fresh profile d
 
 </details>
 
+<details>
+<summary><b>dsh Desktop</b></summary>
+
+The Desktop client is supported, with one exception. Everything server-side works as it does in the
+browser: the page, the agent tools, workspaces, the panel, and boot autostart.
+
+**Manage dsh** is web-only and shown disabled there, because Desktop starts its own reserved profile
+in Electron — it is never one of the panel's server entries. (`dsh --profile desktop` is refused by
+the CLI, so a row for it could only crash-loop.) Server entries of every other kind are unaffected.
+
+</details>
+
 <details>
 <summary><b>Managed entry and port policy</b></summary>
 
@@ -148,6 +170,7 @@ One entry (`dsh`), one toggle: the panel keeps it alive, restarts it and reclaim
 detached restart is recognised on macOS and Linux (`follow`); Windows cannot prove identity through
 a `.cmd` shim, so it uses `onPortConflict: kill`. The plugin pins home-hosted 0.7+, so every key it
 writes is one that panel parses.
+<sub>Web only — see **dsh Desktop** above.</sub>
 
 </details>
 

package/docs/AGENT-TOOLS.md

@@ -0,0 +1,30 @@
+# Agent tools
+
+What the model is given, and what gates it.
+
+Related: [server entries](ENTRIES.md)
+
+## Agent tools are merged and on by default
+
+Seven tools, not ten: `servers_lifecycle` carries start/stop/restart, `servers_edit` carries
+create/update/delete, `autostart_manage` carries install/uninstall, `ui_manage` drives the panel's own
+UI, and `workspaces_list` is the read-only way to see every workspace. They register on by default;
+what gates a mutating call is the session's own permission mode, not a plugin-level default.
+
+A description is read at the approval prompt, so each is one line a person can glance at: what the tool
+does, and only the consequence they could not predict (restarting this session's own entry ends it;
+installing an entry stops the panel). Mechanics belong in the argument schemas and the docs.
+
+Structured parameters are declared as objects, never as `type: 'json'`: an author-only `json` node
+projects to a schema with no `type` at all, and a real session then delivers something the handler
+cannot read — `create`/`update` were unusable because of it while every test passed, since tests call
+the handler directly. A declared object is validated by the runtime before the handler, so a wrong
+shape is rejected with the parameter named.
+
+## Approvals follow the session's sandbox
+
+A mutating agent tool asks the approval service only when the calling session is *not* already
+`danger-full-access` (`ctx.sandboxPolicy.resolve({ session })`). Asking anyway made a Full-access run
+fail whenever the deployment's approvals auto-reject — the session had already granted exactly what the
+tool was asking about. Below full access the tool still asks and still fails closed, and the refusal
+names the mode and the remedy.

package/docs/BOOT.md

@@ -0,0 +1,154 @@
+# Boot autostart
+
+How the panel comes back after a reboot, and the account it comes back as.
+
+Related: [the panel](PANEL.md) · [server entries](ENTRIES.md)
+
+## A plugin cannot act at boot
+
+The plugin runs inside dsh. At boot nothing runs yet, so autostart cannot be a runtime behaviour: the
+plugin installs an OS entry while dsh runs, and the OS starts home-hosted from then on. Every plugin
+start re-asserts that entry (rewrite-if-changed), which is also what repairs a node path that moved
+after an upgrade.
+
+## One boot artifact per state root
+
+The boot artifact name follows the state root too, keyed on the *machine* default: `home-hosted` only
+for `~/.dsh/dsh-home-hosted`, `home-hosted-<hash>` otherwise. Keying it on the running process's
+`$DSH_HOME` would name every install's default state dir `home-hosted` and reintroduce the collision.
+An install that used to write the old name retires it once its own artifact is in place, and only an
+artifact carrying this plugin's marker is ever removed.
+
+## Boot entries run the panel as a person
+
+Two mechanisms drop privilege by name — a systemd `User=` and a launchd `UserName` — and both used to
+take that name from `$USER`. That is right in the common case and wrong in the one case it exists for:
+`sudo` and `pkexec` rewrite `USER`, `LOGNAME` and `HOME` to the *target* account, so a panel started
+from a root shell read `USER=root`, and a mechanism that already runs as root got an entry that either
+repeated root or, with the name dropped, silently kept it. `os.userInfo()` is no help: it reports the
+euid.
+
+So the account comes from whoever this process is. An elevating tool's `SUDO_UID`/`PKEXEC_UID` is an
+instruction and is used while it resolves, so a stale value inherited from an ancestor cannot collapse
+the entry to root; otherwise this session's own login — its database row, else the row for this uid;
+otherwise the owner of the state root or the panel root, which names the person a root-launched panel
+belongs to; and only then, honestly, root. The uid is the fact and `$UID` is a claim: a shell variable
+rather than an exported one, so when it is present at all it was inherited. It is read only when the
+platform gives no uid, and it also feeds the launchd domain (`gui/$UID`).
+
+Two answers are refused rather than written, and both fail loudly:
+
+- **`User=root`**, because an entry with no `User=` already runs as root — naming it only dresses up the
+  silent default this change exists to surface;
+- **a name the user database cannot place.** systemd matches names case-sensitively and cannot resolve
+  what it does not know, so `User=<such a name>` makes the unit refuse to start (`status=217/USER`) and
+  `Restart=always` turns that into a crash-loop that never mentions the account. An LDAP or NIS login
+  has no `/etc/passwd` row, so those operators set `User=` themselves; the warning says so.
+
+`HOME` is written into every spec, because `Environment=HOME=` **overrides `User=`** — verified on real
+systemd. So it has to be the account's home: left at the installer's it is root's under `sudo`, and the
+panel would run as the person with `~` pointing at `/root`, dying with a permission error that never
+mentions its own user. It is written only when it differs, so an unchanged install stays byte-identical
+and startup `reconcile()` does not rewrite the entry. When an account resolves but its home is not
+knowable, the line is **omitted** instead: systemd then supplies the right one from NSS.
+
+An installed entry that already runs as the wrong account is reported by `status()`, and the
+`enabled-failing` repair heals it by installing again. A *working* entry is deliberately left alone:
+re-installing stops the panel and hands it to the entry, which is a person's decision.
+
+## KillMode=process: a restart must not take the entries with it
+
+`persistent: true` puts an entry under a nanny the panel spawns, and the nanny is what makes it outlive
+the panel: it owns the child's pipes, so a panel stop, restart or kill cannot break them. The nanny is
+spawned `detached`, which gives it its own session — but *not* its own cgroup, and systemd's default
+`KillMode=control-group` signals every process in the unit's cgroup. So a `systemctl stop`/`restart` —
+which is what this plugin's own activation, and any `Restart=always`, runs — takes the nanny down with
+the panel, quietly falsifying the guarantee the design depends on. `KillMode=process` signals the unit's
+main process alone.
+
+That main process is the generated launcher, not the panel, so the launcher has to hand a signal on: it
+`spawn`s the CLI and forwards `SIGTERM`/`SIGINT`/`SIGQUIT`/`SIGHUP` to it, then exits with the child's
+outcome. A `spawnSync` launcher cannot do this — it is blocked in the syscall when the signal lands, so
+the signal kills the launcher and orphans the panel while the unit exits and `Restart=` loops on
+"already running". The generated launchers are covered by an execution test that signals the real
+artifact and asserts the panel received the stop.
+
+An ordinary entry is spawned `detached` too, so the same applies to every supervised server and not only
+the nannies: the panel re-adopts a survivor by its port, which is what makes keeping them the right
+answer rather than a leak. It belongs on both units.
+
+## macOS: agent or daemon
+
+A `LaunchAgent` starts at login; starting before login means a `LaunchDaemon` in
+`/Library/LaunchDaemons`, which is root-owned and needs a one-time `sudo`. The daemon is therefore
+offered even when this process cannot elevate: install stages the plist and returns the three commands
+to run. The daemon plist names the invoking user in `UserName`, Apple's sanctioned way to avoid running
+the panel as root — resolved by the rule above, never from `$USER`. The recommendation still prefers a
+mechanism this process can install on its own so "Automatic" stays a single click.
+
+Reachable launchd is not a requirement: a plist in `~/Library/LaunchAgents` is loaded at the next login
+whether or not the process that wrote it can reach `gui/$UID` (SSH sessions often cannot). So the agent
+stays `available` and its install reports "loads at the next login" instead of refusing; only the
+`bootstrap`/`enable`/`print` steps need the domain, and they are skipped when it is unreachable. The
+daemon scope still needs root for `/Library/LaunchDaemons`.
+
+## Enabling autostart hands the panel over
+
+An install alone proves nothing. The panel the plugin started keeps running, so nothing shows whether
+the entry would ever start one — and the CLI refuses to start a second panel while `run.json` names a
+live pid, so `enable --now` on a freshly written unit leaves it *failed* while an orphan panel holds the
+port. So a successful install hands the running panel to the entry: the panel stops, and the entry
+starts it. That is the only way to know autostart works rather than merely that a file was written.
+
+The stop takes the panel's servers with it, and this plugin is usually one of them, so the work goes to
+a generated detached helper (`bin/panel-activate.mjs`) that outlives the process. Its order is the
+whole design:
+
+1. prove the start can work — the unit file the plugin wrote exists and `systemctl is-enabled` agrees —
+   while the panel is still up, because a start that could never work must not be attempted once the
+   old panel is gone. It proves *installed and enabled*, never *already active*: `enable --now` has
+   just started the unit while the panel still holds `run.json`, and home-hosted refuses a second
+   panel, so the unit is `activating` or `failed` at exactly the moment this runs;
+2. on a switch, stop the panel through the *previous* mechanism (`systemctl stop`, `launchctl kill`):
+   its own restart policy (`Restart=always`, `KeepAlive`) would bring the panel back the moment `down`
+   returned, racing the new entry;
+3. stop it with the CLI's `down`, then wait for the pid, escalating to SIGTERM and SIGKILL;
+4. start the entry;
+5. only then remove the other mechanisms' entries.
+
+The stop is always the CLI's `down`, never the new mechanism's own `restart`: the entry would then be
+starting a *second* panel, which home-hosted refuses while `run.json` names a live pid, so a
+restart-in-place over an orphan only produces a failed unit. Waiting on the pid matters for the same
+reason.
+
+Retirement is last, and deliberately not part of `install()`. Switching mechanism has to uninstall the
+old one, but the old entry is often what is currently running the panel: removing it during the install
+would stop the panel — and this plugin — before the new entry was ever told to start. So the ladder
+carries the other mechanisms' removal steps in the activation plan, and each provider's
+`retireCommands()` is the no-`--now` form for the same reason. launchd has no unload-without-stopping,
+so its retirement is only safe once the panel is down and the new entry is up.
+
+A mechanism that cannot start anything now answers `activate() → null`: a `Run` value and a `.desktop`
+file are read by the shell or the session at login. Nothing is stopped then — leaving a working panel
+up beats killing it for an entry that would not bring it back. A handover that could not be spawned is
+reported with the exact commands, and the panel is still up.
+
+Enabling and switching differ only in the retirement: a switch already has an entry keeping the panel
+alive, so its plan carries the old mechanism's removal.
+
+## Privilege
+
+Boot scope needs privilege somewhere on every platform: a system unit, or `loginctl enable-linger` on
+Linux; a LaunchDaemon on macOS; an elevated task on Windows. Login scope needs none. When this process
+cannot elevate, the page shows the exact commands instead of prompting for a password — a headless
+panel has no askpass and `sudo -n` is the only honest probe.
+
+That refusal is shown with the status it answered, and the page retires it as soon as the status moves:
+a person runs the commands and presses Re-check. The persisted last attempt follows the same rule, so a
+failed install is not re-shown once an entry exists.
+
+Switching those entries to a `User=` later is not just a unit edit. The moment a panel runs as root,
+everything it writes — `<home>/.hh`, its workspaces, logs and `snapshots.json` — is root-owned, so the
+unprivileged account the unit now names cannot write its own state and the panel fails to boot with a
+permission error that never mentions ownership. Moving an install from root to a user therefore needs
+`chown -R <user> <home>` (and the plugin state dir) first.