dsh-home-hosted 0.7.3 → 0.7.5

package/README.md

@@ -103,6 +103,7 @@ the server management, not the thing this plugin is.
 | `home_hosted_servers_edit` | `create` · `update` · `delete` |
 | `home_hosted_autostart_manage` | `install` · `uninstall` |
 | `home_hosted_ui_manage` | `status` · `update` · `revert` · `switch` (official asset or local zip) |
+| `home_hosted_panel_logs` | The panel's own console output. Needs no API token, so it works when the panel is up but not answering. |
 
 Every server tool names its `workspace`, because an id is only unique inside one.
 
@@ -163,6 +164,16 @@ the CLI, so a row for it could only crash-loop.) Server entries of every other k
 
 </details>
 
+<details>
+<summary><b>Read more</b></summary>
+
+Topic docs, one per area — written for whoever has to touch it next:
+
+[Boot autostart](docs/BOOT.md) · [the panel](docs/PANEL.md) · [server entries](docs/ENTRIES.md) ·
+[workspaces and several panels](docs/WORKSPACES.md) · [agent tools](docs/AGENT-TOOLS.md)
+
+</details>
+
 <details>
 <summary><b>Managed entry and port policy</b></summary>
 

package/docs/AGENT-TOOLS.md

@@ -6,9 +6,10 @@ 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
+Eight 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;
+UI, `panel_logs` reads the panel's console, 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

package/docs/BOOT.md

@@ -191,6 +191,53 @@ fallback gets a command that works.
 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.
 
+## Where the entry's own output goes
+
+A boot-run panel's output does **not** go to the panel's own console
+(`<home>/.hh/.logs/home-hosted.log`, which `panel_logs` reads and `docs/PANEL.md` describes).
+Each mechanism sends it somewhere different, and the status line now names where:
+
+| mechanism | where the output goes |
+| --- | --- |
+| `systemd-user` / `systemd-system` | the journal — the unit sets no `StandardOutput=`, so the detail names `journalctl --user -u <unit>` or `journalctl -u <unit>` |
+| `launchd-agent` / `launchd-daemon` | `<logDir>/<label>.out.log` and `<label>.err.log`, the two paths the generated plist carries |
+| `xdg-autostart` | nowhere persistent: a `.desktop` entry with `Terminal=false` has its output discarded by the session |
+| `windows-run` / `windows-task` | nowhere persistent either |
+
+So the hint appears only where a file or a query actually exists — and only once the entry is
+installed, because naming a log for an entry that was never written sends someone to a
+command that finds nothing. The launchd paths come from one computation
+(`launchdLogPaths`), shared with the plist builder, so the plist and the status line cannot
+name different files.
+
+## What counts as "failing"
+
+A unit's state comes from `systemctl show -p Result`. The value is compared against systemd's own
+failure enum — `failed`, `exit-code`, `signal`, `timeout`, `core-dump`, `watchdog`,
+`start-limit-hit`, `oom-kill` — and anything else, `success` included, is not a failure. `oom-kill`
+is the one worth reading correctly: it is what a container limit or the OOM killer produces, and a
+unit that died that way reading as merely "disabled" is how someone stops looking for it.
+
+## The page says what a mechanism name means
+
+The picker's values are the identifiers the setting stores — `systemd-system`, `systemd-user`,
+`xdg-autostart`, `launchd-agent` — and they are not self-explanatory, so the page prints the host's own
+one-line reason for the chosen one ("systemd is not the init system here (no /run/systemd/system)", "a
+LaunchAgent loads at login, not at boot", "this needs root here, so the plugin stages the plist and
+shows the sudo commands"). Those sentences come from `BootCandidate.reason`, which the host already
+computed for every mechanism, available or not.
+
+Because `auto` is not a mechanism but "let the host decide", the page also names what that decision
+would be: `BootStatus.recommended` is the host's own `recommend()` answer, and `install()` falls through
+to it when nothing is installed (`pickOf(mechanism ?? before.mechanism ?? before.recommended)`). So
+"Automatic" says which mechanism the next install would use, instead of leaving a person to install it
+and read the result. The sentence is only shown while nothing is installed under that mechanism, and it
+is absent — never "undefined" — when an older panel does not send the field.
+
+The `Details` block describes the mechanism that is actually **installed**, which is a different one
+while a switch is pending, so both it and the picker read one shared lookup rather than each formatting
+the name their own way.
+
 ## Privilege
 
 Boot scope needs privilege somewhere on every platform: a system unit, or `loginctl enable-linger` on

package/docs/DESIGN.md

@@ -38,7 +38,7 @@ its page.
 `onPortConflict: kill` arrived in home-hosted 0.6.0 and `persistent` in 0.6.3, and an older panel
 handed either key can refuse to *boot* from the config. The plugin used to consult the answering
 panel's version and refuse or drop them (`KILL_UNSUPPORTED`). That is gone on purpose: it pins
-`home-hosted@^0.7.3` and autostarts its own copy, so a panel older than those keys is only reachable by
+`home-hosted@^0.7.19` and autostarts its own copy, so a panel older than those keys is only reachable by
 deliberately preferring an old global install — and this is pre-1.0. Supporting older panels again means
 bringing that check back from history, not re-deriving it.
 

package/docs/ENTRIES.md

@@ -61,6 +61,31 @@ The generated entry always binds loopback (`bind: 'local'`, `--host 127.0.0.1`):
 `--host 0.0.0.0` as a usage error, so repeating a running harness's network bind would produce an
 entry that can never start.
 
+## The page's editor covers the common fields on purpose
+
+`src/client/entry-editor.tsx` renders eight entry fields — id, command, args, working directory,
+label, port, autostart and port-conflict policy — and the panel's `serverSchema` has 23. The other
+fifteen (`enabled`, `bind`, `persistent`, `env`, `dataEnvs`, `envFile`, `bootstrap`, `dependsOn`,
+`resources`, `backupPaths`, `logBufferLines`, `backupIgnoreGenerated`, `health`, `restart`, `stop`)
+are **deliberately out of scope**, not forgotten.
+
+The page says so where it happens: *"Entries are managed in the home-hosted panel:"* followed by a
+link to that panel, whose own editor sets every field. So the dsh page is a convenience for the
+common ones, and the panel remains the place a full config is written.
+
+Two properties make that safe, and both are deliberate:
+
+- **A minimal diff cannot destroy what it does not render.** An edit sends only the fields that
+  differ from the stored entry, so `bootstrap`, `envFile` or a `restart` policy is left exactly as it
+  was — the editor cannot silently reset a key it does not show.
+- **The scope is a recorded decision, not an accident.** `EDITOR_FIELDS` and `OUT_OF_SCOPE_FIELDS`
+  are exported, and `test/client/entry-editor` reads the panel's own schema and fails if any field is
+  neither rendered nor declared. A field the panel grows therefore cannot become reachable there and
+  silently absent here — it fails until somebody decides which it is.
+
+The same file asserts the *rendered* labels, not just the list: a field can be declared and never
+drawn, which is the exact shape this guards against.
+
 ## Persistence keeps dsh alive across a panel restart
 
 A managed entry asks for `persistent: true`: home-hosted then runs it under its nanny, which owns the
@@ -82,6 +107,13 @@ triggers its file watcher. A write to a workspace's `servers.config.json` does
   `autostart: false`, then flip `autostart`. A later write to an existing entry is a *changed
   definition*, which only takes effect at that entry's next start.
 
+The file path has one subtlety worth knowing: the panel's API **merges** the nested groups
+(`restart`, `health`, `stop`) key by key, and so must this write, or a partial patch would replace the
+group and silently drop every sibling key — `{ restart: { maxRetries: 1 } }` would wipe `baseDelayMs`
+and the rest, and the entry would fall back to the panel's defaults. The plugin mirrors the panel's own
+`SERVER_MERGE_KEYS`/`CONTROL_MERGE_KEYS`, and a test reads those from the installed panel so the copy
+cannot fall behind it.
+
 ## What the plugin owns
 
 Exactly `autostart`, `onPortConflict`, `persistent` and `stop.killPortHolders` (`OWNED_ENTRY_KEYS`).

package/docs/PANEL.md

@@ -13,11 +13,38 @@ globally. An operator's `homeHostedCommand` always wins — that is an instructi
 
 The range is stated twice and both must agree: `dependencies['home-hosted']` in `package.json` and
 `EXPECTED_RANGE` in `resolve.ts` (what the page offers to install, and warns about when a global copy
-is older). Bumping one alone makes the page recommend a range the plugin is not built against. A bump
-is therefore those two plus the version-coupled tests — *unless* the release moved something this
-plugin names: a path under `.hh`, `CONFIG_SCHEMA`, `serverSchema`, `/api/settings`, or a CLI
-subcommand. 0.7.2 (the panel's reverse proxy, all under `.hh/.proxy/`) moved none of them, and neither
-did 0.7.3 (DNS-01 through the panel's own DNS accounts, and a Namecheap API provider).
+is older). Bumping one alone makes the page recommend a range the plugin is not built against.
+`test/resolve` **enforces** that agreement — it was a rule the docs stated and nothing checked, so
+setting the manifest to `^0.7.99` while the constant stayed put failed nothing until the guard
+existed. The same file asserts `MIN_SUPPORTED_VERSION` lies inside the advertised range, since a floor
+above it would advertise a copy the plugin then refuses.
+
+A bump is therefore those two plus the version-coupled tests — *unless* the release moved something
+this plugin names: a path under `.hh`, `CONFIG_SCHEMA`, `serverSchema`, `/api/settings`, or a CLI
+subcommand. Check that by **use**, not by filename: a file appearing in a diff cannot show that a
+change reaches us, and the two disagree as soon as a comment lands in a schema file.
+
+**0.7.18 and 0.7.19 did move one, and no filename showed it.** Upstream `applyPatch` now deletes a
+top-level key set to `null` (`1f58a5d`), where it used to write it through; `serverSchema.label` also
+began to admit `null` (`45d689e`). This plugin keeps its own copy of that function for the file
+fallback, and the copies had drifted — the nested branch deleted, the top-level branch wrote the
+`null` — so a top-level `null` that the panel deletes would have been stored, producing a config it
+refuses to boot (`servers[0] ("smoke"): cwd must be a string (was null)`). One `applyPatchFields` now
+serves both paths, and the refusal a `null` group gets is one rule `src/service.ts` reads too.
+
+No shipped caller could reach the harmful case, and saying so is part of the finding: the agent tool
+layer validates `patch` against the panel's own field types, so only `port` and `bootstrap` can carry
+a `null` at all — exactly the two whose schema is `… | null` — while the page emits `port` alone. The
+drift was real but latent; it is fixed because a copy of the panel's function is a fork of its
+semantics, and the next field to allow `null` would have made it reachable.
+
+Verified against a real 0.7.19 panel and its own CLI: `PATCH {port:null}` deletes the key; only `port`
+and `bootstrap` have a schema that admits `null`; `_hh` is still exactly four routes; and every route,
+subcommand and flag this plugin drives is unchanged. The console **file** — `.hh/.logs/home-hosted.log`
+plus its `.1`, and the 5 MB rotation — is unchanged too, and this plugin's reader still matches
+`home-hosted logs` line for line. A capability that needs a *newer* 0.7.x degrades rather than raising
+the floor: `logs` (0.7.12) is a file read either way, and `restart <id>` (0.7.13) falls back to the
+stop/start pair it replaced.
 
 That copy resolves to a pnpm path carrying a version and a peer hash, which moves on the next install
 and disappears when the profile is rebuilt. A boot entry that baked it in would fail exactly when it
@@ -65,6 +92,74 @@ response says the page will disconnect; the helper logs to `bin/panel-takeover.l
 can still carry `ok: false` — the page reads the payload's `detail`/`output` rather than trusting
 `envelope.ok`, so a refused control action says why instead of looking like a no-op.
 
+## The console is readable when nothing else is
+
+A panel that is up but misbehaving is exactly when its API is hardest to reach: the token may be
+stale, `writeVia` may be `file`, and the thing that explains the symptom is what the panel printed
+while starting. So `panel.console` reads `<root>/.hh/.logs/home-hosted.log` off disk — no session, no
+API token, no CLI, and no dependence on the panel answering — and the `panel_logs` agent tool exposes
+it. It reads one rotation too (`<log>.1`), because the end of the file that just rotated away is
+usually where a crash is, and it matches `home-hosted logs` line for line (verified against a real
+panel at every count).
+
+The read **grows its window** rather than sizing one from the count. A line's length is unbounded —
+a stack trace, a JSON dump or a verbose error is one line and can be kilobytes — so a window sized
+per *line* silently returns fewer lines than asked for: on 500 lines of ~2 KB, `lines: 100` returned
+50. The window instead grows backwards until `limit` lines are present or the file start is reached,
+so a bounded request never reads an unbounded file and a short line still stops after one block
+(20 lines of a 37.9 MB log reads 64 KiB). Home-hosted's own `readTail` grows for the same reason.
+
+The rotation is joined the way **concatenating the files** joins it, not by gluing two line arrays.
+A panel killed mid-write leaves `.1`'s last line unterminated, and concatenation makes that line and
+the live file's first line one line (`rot2-partial` + `live1` → `rot2-partiallive1`); array-joining
+invents a line break the log never had, and then "the last 2 lines" is one short. Sufficiency is
+therefore counted in **separators** (`limit + 1`), the same test `logs` makes — counting lines stops
+one early for exactly that reason.
+
+A missing log is an empty one, not an error: a panel that has just started has nothing to say, and
+reporting that as a failure would make the one diagnostic that always works look broken. The new tool
+is **not** added to an existing settings file's allow-list — a tool that did not exist when that file
+was written could not have been deselected, but granting it silently would expand a deliberate
+selection, so the page's checkbox is how it is chosen.
+
+## What `/_hh` does not offer, deliberately
+
+`/_hh` is the one unauthenticated surface a local caller can use, and it is deliberately tiny. Read
+out of `src/api/control.ts` (mounted before the `/api/*` guard in `src/app.ts`), it registers exactly
+**four** routes: `POST /shutdown`, and `POST /servers/:id/{start,stop,restart}`. Every one needs the
+token from `run.json` plus a loopback peer, which is the whole point — a local `down` needs no session,
+password or API token.
+
+There is **no local-token path to the reverse proxy, backups, TLS, notifications or the config**. Those
+live behind `/api/*` and a real credential. So a plugin capability over any of them would have to mint
+a token and speak `/api`, and it must not add an unauthenticated `/api` route of its own to avoid that
+— that is the rule the plugin is built on (the CLI drives a running panel through `/_hh`, never
+`/api`). `_acme` is the only other route outside the guard (loopback-only, credentials the panel
+generates, a single `/:action` for DNS-01); this plugin never touches it.
+
+The practical consequence for a foreign panel is the three mechanisms `docs/WORKSPACES.md` lists: its
+config file, its own CLI, or a token the user is asked about. A panel the user has not confirmed is
+never reached by a fourth route invented here.
+
+## Two RPC endpoints have no caller, and that is fine
+
+`servers.get` and `entries.restore` are handled by the service, typed in `RpcEndpoint`, and tested —
+but no client or agent tool invokes either, which is the shape worth checking rather than assuming.
+
+Both are **redundant surface, not unreachable capability**:
+
+- `entries.restore`'s job is reached through `entries.remove`, which restores an entry this plugin
+  merely adopted instead of deleting it (`removeManagedEntry` → the `adopted` branch). That is proven
+  behaviourally, not by reading: `test/service` removes an adopted entry and asserts the panel got no
+  `DELETE` and the entry's own `onPortConflict` came back.
+- `servers.get` returns one entry's view, and `servers.list` — which every consumer uses — returns
+  every entry's view for the workspace.
+
+They are left in place rather than deleted: they are a coherent RPC surface for a caller that wants
+one entry, deleting them is a wire change for no user-visible gain, and the capability each names is
+already reachable. Recorded here so the next reader does not have to re-derive whether it was an
+oversight.
+
 ## Credentials
 
 home-hosted keeps only an API token's hash, so a token this plugin did not create can never be

package/docs/WORKSPACES.md

@@ -11,6 +11,23 @@ settings, secrets, logs and nanny state under `.hh/<workspace>/`, while the list
 vitals, backups, UI and `run.json` stay at `.hh/`. A server id is therefore only unique *inside* a
 workspace, and every call has to say which one it means.
 
+The same rule reaches the page. The servers section is not remounted when the viewed workspace
+changes, so anything it holds about a server has to carry the workspace it was made in — otherwise an
+editor or a confirmation opened on workspace A's `web` stays live under workspace B and re-binds to
+*B's* `web`. The displayed list is replaced on switch, so the ids simply stop matching; the plugin's
+own in-flight keys (`busyKey`) already included the workspace, and the section's local selections now
+do too.
+
+The scoping is verified by driving the section under `happy-dom` and clicking it — open the editor,
+switch workspace, read the screen — not only by calling the resolver, so the wiring for all three
+selections is exercised. A control case re-renders in the *same* workspace and asserts the editor
+stays open, so the failure cannot be mistaken for "it closed for some other reason".
+
+The same lesson applies to the boot section's own stored state: `bootAttemptView` used to drop the
+mechanism, so its note could only be gated on `state` and a persisted refusal survived a change of
+preference — with the *old* mechanism's copy-pasteable commands. The view carries it now, and both
+the fresh and persisted paths compare it.
+
 The plugin manages exactly one workspace — **the panel's `default`**, fixed — because its intent (the
 `dsh` entry, snapshots, reconcile) is a promise about one entry in one place. Making that a setting
 bought nothing but a way to write into the wrong workspace, so it is a constant. The page and the agent
@@ -58,8 +75,13 @@ that endpoint has, least invasive first:
   (`.hh/<workspace>/servers.config.json`, its default workspace unless the call names another) — no
   credential, but no live status either, and a running panel applies a changed definition at that
   entry's next start;
-- `cli` runs the CLI against its state root — the only runtime path the panel itself offers
-  (`start`/`stop`; a restart is a stop then a start, because the CLI has no server restart);
+- `cli` runs the CLI against its state root — the only runtime path the panel itself offers.
+  `start`/`stop` act on one entry; a restart is now the CLI's own `restart <id>` (home-hosted
+  0.7.13), which is what the panel's UI does and leaves no window in which the entry is down. A
+  local panel older than that refused the command before touching anything, so the plugin falls
+  back to the stop-then-start pair and reports `downgraded` in the result — the refusal is
+  detected from the CLI's own text, including the `Unexpected argument` a 0.7.12 CLI prints for
+  the positional id;
 - `api` mints a token for that panel, enrols it and uses its HTTP API — the only way to get live
   status, and it replaces any token that panel had, which the question says outright.