home-hosted 0.7.12 → 0.7.14

package/AGENTS.md

@@ -23,6 +23,7 @@ seed entry, or a path that names one.
 
 ```sh
 pnpm run up|down|restart|status    # detached; `down` asks /_hh/shutdown, signals are the fallback
+                                   # `restart <id>` restarts one server via /_hh, panel stays up
 pnpm run start                     # up --foreground (systemd, docker, a foreground shell)
 pnpm exec tsx src/cli.ts logs      # the panel's own console output (--lines, --follow, --json)
 pnpm dev                           # tsx-watch panel :6000 + the stock UI's Vite :6001 (proxies /api), state in .dev-state/

package/README.md

@@ -340,10 +340,11 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | --- | --- |
 | `home-hosted up` | start the panel detached, and keep it alive in the background |
 | `home-hosted down` | stop it cleanly — supervised processes included, persistent entries left running |
-| `home-hosted restart` | `down`, then `up` |
+| `home-hosted restart` | `down`, then `up` — or `restart <id>` to restart one server, leaving the panel up |
 | `home-hosted status` | pid, URL, health, uptime, state and log paths (`--json` for scripts) |
 | `home-hosted start <id>` | start one server in the default workspace — and anything it `dependsOn` (`--workspace <id>`) |
 | `home-hosted stop <id>` | stop one server, nothing else (`--workspace <id>`) |
+| `home-hosted restart <id>` | restart one server, nothing else (`--workspace <id>`) — the same as the panel's per-server Restart |
 | `home-hosted logs` | read the panel's own console output — the file `up` redirects it into (`--lines`, `--follow`, `--json`) |
 | `home-hosted set-password` | set the panel password without opening a browser |
 | `home-hosted set-token` | set the API token scripts and agents use (`--generate`, `--clear`) |
@@ -359,12 +360,13 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 `home-hosted <command> --help` prints what that command takes.
 
 ```text
-up, restart       -c/--config -p/--port --host --open --no-autostart --foreground --print-config
+up                -c/--config -p/--port --host --open --no-autostart --foreground --print-config
 
 down              (no flags)
 status            --json
 logs              --lines <n> --follow --json
 start, stop       <id> [-w/--workspace <id>]   (both need the panel up)
+restart           [<id>] [-w/--workspace <id>]  (no id: the panel; with one: that server)
 init              --dir --name --pm --no-install -y/--yes
 set-password      --clear
 set-token         --generate --clear
@@ -377,7 +379,8 @@ every command     --home <dir> --project <dir>       (or $HHOSTED_HOME, $HHOSTED
 env vars          HHOSTED_PASSWORD, HHOSTED_MIGRATE=allow, HHOSTED_TOKEN, GITHUB_TOKEN or GH_TOKEN
 ```
 
-`up` and `restart` share the same flags: `restart` is `down`, then `up` with exactly what it was given.
+`up` and `restart` share the same flags: bare `restart` is `down`, then `up` with exactly what it was
+given. Given a server id — `restart web` — it restarts only that entry, and the panel keeps running.
 `-c/--config` is the **default workspace's** servers file (`<state>/.hh/default/servers.config.json`),
 for a launcher that pins one; a workspace picked in the UI keeps its own. `start`/`stop` omit
 `--workspace` to act in the panel's default workspace.

package/dist/cli.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { defineCommand, runCommand } from "citty";
 import path from "node:path";
 import readline from "node:readline";
-import { exec, execFile, spawn, spawnSync } from "node:child_process";
+import { exec, execFile, execFileSync, spawn, spawnSync } from "node:child_process";
 import { Buffer as Buffer$1 } from "node:buffer";
 import os from "node:os";
 import { describeRoute, openAPIRouteHandler, resolver, validator } from "hono-openapi";
@@ -3299,6 +3299,18 @@ function createControlRoute(deps) {
 		assertLocalCall(c, "start or stop a server");
 		const result = await requireWorkspace(deps.panel.requireWorkspace.bind(deps.panel), c.req.valid("query").workspace).supervisor.stop(c.req.param("id"));
 		return c.json(result, statusForAction(result));
+	}).post("/servers/:id/restart", describeRoute({
+		tags: ["panel"],
+		summary: "Restart one server, without a session (local token required)",
+		responses: {
+			200: { description: "Restarted" },
+			403: { description: "Bad token, or not a local caller" },
+			404: { description: "No such server" }
+		}
+	}), validate("query", workspaceQuerySchema), async (c) => {
+		assertLocalCall(c, "restart a server");
+		const result = await requireWorkspace(deps.panel.requireWorkspace.bind(deps.panel), c.req.valid("query").workspace).supervisor.restart(c.req.param("id"));
+		return c.json(result, statusForAction(result));
 	});
 }
 var init_control = __esmMin((() => {
@@ -14091,9 +14103,34 @@ var init_control_server = __esmMin((() => {
 }));
 //#endregion
 //#region src/providers/host.ts
+/**
+* Whether a cached reading may be reused.
+*
+* Separate from the reading itself so the rule can be tested anywhere — the read is
+* `sysctl`/PowerShell, which no CI runner but macOS and Windows can perform, and a bug here
+* would be one that only shows up as either a stale alert or a spawn storm.
+*
+* A stamp in the future (a backwards wall-clock step) counts as stale: with a plain
+* `now - at < ttl` it computes a negative age, which is "fresh", and the reading would stick
+* until wall time caught back up — potentially hours after an NTP correction.
+*/
+function isSwapCacheFresh(cache, now, ttlMs = SWAP_CACHE_MS) {
+	if (cache === null) return false;
+	const age = now - cache.at;
+	return age >= 0 && age < ttlMs;
+}
 /** Swap usage per platform: /proc on Linux, sysctl on macOS, CIM on Windows. */
-async function swapUsedPercent() {
+async function swapUsedPercent(now = Date.now()) {
 	if (process.platform === "linux") return 0;
+	if (isSwapCacheFresh(swapCache, now)) return swapCache.percent;
+	const percent = await readSwapUsedPercent();
+	swapCache = {
+		at: now,
+		percent
+	};
+	return percent;
+}
+async function readSwapUsedPercent() {
 	if (process.platform === "darwin") try {
 		const { stdout } = await execFileAsync("sysctl", ["-n", "vm.swapusage"], { timeout: 3e3 });
 		const total = /total\s*=\s*([\d.]+)M/.exec(stdout)?.[1];
@@ -14119,7 +14156,20 @@ async function swapUsedPercent() {
 	}
 	return 0;
 }
-/** `/proc/meminfo` counts cache as available, which `os.freemem()` does not. */
+/**
+* Memory used, as a percentage of what the machine actually has.
+*
+* The definition matters more than the arithmetic, and it differs per platform:
+*
+* - Linux: `/proc/meminfo`'s `MemAvailable` already excludes cache, because Linux counts
+*   page cache as reclaimable. `os.freemem()` happens to read the same value here.
+* - macOS: **`os.freemem()` is wrong for this.** libuv reports `host_statistics64`'s
+*   `free_count` alone, while macOS keeps as much RAM as it can in *inactive* and
+*   speculative* pages — file cache it drops on demand. A perfectly healthy Mac therefore
+*   reads as 90%+ used, which is the report a user brought back from a 0.7.3 panel. Read
+*   `vm_stat` and count what macOS itself counts as available.
+* - Windows: `os.freemem()` is the free physical page count, which is the ordinary reading.
+*/
 function memoryInfo() {
 	try {
 		const info = fs.readFileSync("/proc/meminfo", "utf8");
@@ -14134,14 +14184,81 @@ function memoryInfo() {
 		};
 	} catch {
 		const total = os.totalmem();
-		const free = os.freemem();
+		const available = availableMemoryBytes(process.platform, os.freemem());
 		return {
-			memoryUsedPercent: total > 0 ? (total - free) / total * 100 : 0,
+			memoryUsedPercent: total > 0 && available !== null ? Math.max(0, Math.min(100, (total - available) / total * 100)) : 0,
 			swapUsedPercent: 0
 		};
 	}
 }
 /**
+* Which "available memory" reading a platform's fallback should use.
+*
+* Split out from `memoryInfo` because the branch it decides is otherwise unreachable off
+* macOS: Linux answers from `/proc/meminfo` first, so the fallback never runs there and no
+* Linux test can prove which reader was chosen. Taking the platform and the OS reading as
+* arguments makes the decision testable on any runner, which matters — using the wrong
+* reader here is the whole macOS bug.
+*/
+function availableMemoryBytes(platform, osFree, vmStat) {
+	if (platform !== "darwin") return osFree;
+	return macAvailableBytes(vmStat);
+}
+/**
+* What macOS counts as available: free + inactive + speculative pages.
+*
+* `vm_stat` reports pages, so the page size is needed — and it is not always 4096 (Apple
+* silicon uses 16384 for the physical page size, and `vm_stat` has printed a `page size of`
+* header since macOS 11). Both are handled: the header when it is there, `getpagesize` when
+* it is not.
+*
+* Returns `null` when the reading cannot be taken, so the caller reports "unknown" rather
+* than inventing a percentage.
+*/
+function macAvailableBytes(vmStat) {
+	try {
+		const text = vmStat ?? execFileSync("vm_stat", {
+			timeout: 3e3,
+			encoding: "utf8"
+		});
+		const pageSize = Number.parseInt(/page size of (\d+) bytes/.exec(text)?.[1] ?? "", 10);
+		const pages = (label) => {
+			const found = new RegExp(`^${label}:\\s+(\\d+)`, "m").exec(text)?.[1];
+			return Number.parseInt(found ?? "", 10);
+		};
+		const size = Number.isFinite(pageSize) && pageSize > 0 ? pageSize : getPageSize();
+		if (!Number.isFinite(size) || size <= 0) return null;
+		let totalPages = 0;
+		let sawAny = false;
+		for (const label of [
+			"Pages free",
+			"Pages inactive",
+			"Pages speculative",
+			"Pages purgeable"
+		]) {
+			const value = pages(label);
+			if (Number.isFinite(value)) {
+				totalPages += value;
+				sawAny = true;
+			}
+		}
+		return sawAny ? totalPages * size : null;
+	} catch {
+		return null;
+	}
+}
+/** The OS page size, without adding a dependency for one sysconf. */
+function getPageSize() {
+	try {
+		return Number.parseInt(execFileSync("getconf", ["PAGESIZE"], {
+			timeout: 3e3,
+			encoding: "utf8"
+		}).trim(), 10);
+	} catch {
+		return NaN;
+	}
+}
+/**
 * Best-effort CPU temperature from Linux thermal zones / hwmon. macOS and
 * Windows expose no unprivileged sensor, so those platforms report null and the
 * UI simply hides the reading.
@@ -14233,9 +14350,11 @@ function emptyHostView(config) {
 		sampledAt: null
 	};
 }
-var execFileAsync;
+var execFileAsync, SWAP_CACHE_MS, swapCache;
 var init_host = __esmMin((() => {
 	execFileAsync = promisify(execFile);
+	SWAP_CACHE_MS = 6e4;
+	swapCache = null;
 }));
 //#endregion
 //#region src/services/host-monitor.ts
@@ -16782,17 +16901,107 @@ var init_down = __esmMin((() => {
 	});
 }));
 //#endregion
+//#region src/cli/server.ts
+var server_exports = /* @__PURE__ */ __exportAll({
+	restartServerCommand: () => restartServerCommand,
+	runServerAction: () => runServerAction,
+	startCommand: () => startCommand,
+	stopCommand: () => stopCommand
+});
+async function runServerAction(action, id, workspace) {
+	const { clearRuntime, isProcessAlive, readRuntime, requestControl } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
+	const runtime = readRuntime();
+	if (runtime === null || !isProcessAlive(runtime.pid)) {
+		if (runtime !== null) clearRuntime();
+		fail("home-hosted is not running — start it with `home-hosted up`");
+	}
+	const query = workspace === void 0 || workspace.length === 0 ? "" : `?workspace=${encodeURIComponent(workspace)}`;
+	const answer = await requestControl(runtime, `/_hh/servers/${encodeURIComponent(id)}/${action}${query}`);
+	if (answer === null) fail(`the control panel is not answering on ${runtime.probeUrl}`);
+	const body = answer.body ?? {};
+	if (body.ok !== true) {
+		const reason = body.error ?? body.message;
+		if (reason !== void 0) fail(reason);
+		if (answer.status === 404) fail(`the panel on ${runtime.url} is home-hosted ${runtime.version}, which does not know this command — restart it on this release`);
+		fail(`the panel answered ${answer.status}`);
+	}
+	const verb = action === "start" ? "started" : action === "stop" ? "stopped" : "restarted";
+	process.stdout.write(`${green(verb)} ${workspace === void 0 ? "" : `${workspace}/`}${id}\n`);
+}
+function serverCommand(action) {
+	return defineCommand({
+		meta: {
+			name: action,
+			description: DESCRIPTION[action]
+		},
+		args: {
+			id: {
+				type: "positional",
+				required: false,
+				description: "the server id from the workspace's servers.config.json"
+			},
+			workspace: {
+				type: "string",
+				alias: "w",
+				description: "the workspace to act in (default: the panel's default workspace)"
+			}
+		},
+		run: async ({ args }) => {
+			const id = typeof args.id === "string" ? args.id.trim() : "";
+			if (id.length === 0) fail(`${action} needs a server id — see \`home-hosted status\` or the workspace's servers.config.json`);
+			await runServerAction(action, id, typeof args.workspace === "string" ? args.workspace.trim() : void 0);
+		}
+	});
+}
+var DESCRIPTION, startCommand, stopCommand, restartServerCommand;
+var init_server = __esmMin((() => {
+	init_io();
+	DESCRIPTION = {
+		start: "start one server (the panel keeps running)",
+		stop: "stop one server (the panel keeps running)",
+		restart: "restart one server (the panel keeps running)"
+	};
+	startCommand = serverCommand("start");
+	stopCommand = serverCommand("stop");
+	restartServerCommand = serverCommand("restart");
+}));
+//#endregion
 //#region src/cli/restart.ts
 var restart_exports = /* @__PURE__ */ __exportAll({ restartCommand: () => restartCommand });
-/** `restart` is `down`, then `up` with exactly the flags it was given. */
+/**
+* `restart` restarts the panel (`down`, then `up`) — or, given a server id, just that entry.
+*
+* The id is optional on purpose. `restart` already meant the panel, and it still does when
+* called the way it always was; adding a positional would have been a hard error before this
+* ("Unexpected argument 'web'"), so nothing existing changes meaning. The per-server case is
+* what the UI's Restart button has always done and the shell could not.
+*/
 function restartCommand(entry) {
 	return defineCommand({
 		meta: {
 			name: "restart",
-			description: "down, then up"
+			description: "down then up — or one server, given an id"
+		},
+		args: {
+			...upArgs,
+			id: {
+				type: "positional",
+				required: false,
+				description: "restart just this server instead of the panel"
+			},
+			workspace: {
+				type: "string",
+				alias: "w",
+				description: "the workspace to act in (default: the panel's default workspace)"
+			}
 		},
-		args: upArgs,
 		run: async ({ args }) => {
+			const id = typeof args.id === "string" ? args.id.trim() : "";
+			if (id.length > 0) {
+				await runServerAction("restart", id, typeof args.workspace === "string" ? args.workspace.trim() : void 0);
+				return;
+			}
+			if (args.workspace !== void 0) fail("restart --workspace needs a server id — `home-hosted restart <id> --workspace <id>`");
 			await runDown();
 			await runUp(toUpFlags(args), entry);
 		}
@@ -16800,6 +17009,8 @@ function restartCommand(entry) {
 }
 var init_restart = __esmMin((() => {
 	init_down();
+	init_io();
+	init_server();
 	init_up();
 }));
 //#endregion
@@ -16958,63 +17169,6 @@ var init_logs = __esmMin((() => {
 	});
 }));
 //#endregion
-//#region src/cli/server.ts
-var server_exports = /* @__PURE__ */ __exportAll({
-	runServerAction: () => runServerAction,
-	startCommand: () => startCommand,
-	stopCommand: () => stopCommand
-});
-async function runServerAction(action, id, workspace) {
-	const { clearRuntime, isProcessAlive, readRuntime, requestControl } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
-	const runtime = readRuntime();
-	if (runtime === null || !isProcessAlive(runtime.pid)) {
-		if (runtime !== null) clearRuntime();
-		fail("home-hosted is not running — start it with `home-hosted up`");
-	}
-	const query = workspace === void 0 || workspace.length === 0 ? "" : `?workspace=${encodeURIComponent(workspace)}`;
-	const answer = await requestControl(runtime, `/_hh/servers/${encodeURIComponent(id)}/${action}${query}`);
-	if (answer === null) fail(`the control panel is not answering on ${runtime.probeUrl}`);
-	const body = answer.body ?? {};
-	if (body.ok !== true) {
-		const reason = body.error ?? body.message;
-		if (reason !== void 0) fail(reason);
-		if (answer.status === 404) fail(`the panel on ${runtime.url} is home-hosted ${runtime.version}, which does not know this command — restart it on this release`);
-		fail(`the panel answered ${answer.status}`);
-	}
-	process.stdout.write(`${green(action === "start" ? "started" : "stopped")} ${workspace === void 0 ? "" : `${workspace}/`}${id}\n`);
-}
-function serverCommand(action) {
-	return defineCommand({
-		meta: {
-			name: action,
-			description: action === "start" ? "start one server (the panel keeps running)" : "stop one server (the panel keeps running)"
-		},
-		args: {
-			id: {
-				type: "positional",
-				required: false,
-				description: "the server id from the workspace's servers.config.json"
-			},
-			workspace: {
-				type: "string",
-				alias: "w",
-				description: "the workspace to act in (default: the panel's default workspace)"
-			}
-		},
-		run: async ({ args }) => {
-			const id = typeof args.id === "string" ? args.id.trim() : "";
-			if (id.length === 0) fail(`${action} needs a server id — see \`home-hosted status\` or the workspace's servers.config.json`);
-			await runServerAction(action, id, typeof args.workspace === "string" ? args.workspace.trim() : void 0);
-		}
-	});
-}
-var startCommand, stopCommand;
-var init_server = __esmMin((() => {
-	init_io();
-	startCommand = serverCommand("start");
-	stopCommand = serverCommand("stop");
-}));
-//#endregion
 //#region src/cli/set-password.ts
 var set_password_exports = /* @__PURE__ */ __exportAll({
 	runSetPassword: () => runSetPassword,
@@ -18131,7 +18285,7 @@ var HEADER = "home-hosted — a control panel for the processes on your home ser
 var SYNOPSIS = {
 	"up": "home-hosted up [options]",
 	"down": "home-hosted down",
-	"restart": "home-hosted restart [options]",
+	"restart": "home-hosted restart [<id>] [options]",
 	"status": "home-hosted status [--json]",
 	"logs": "home-hosted logs [--lines <n>] [--follow] [--json]",
 	"start": "home-hosted start <id> [--workspace <id>]",
@@ -18147,7 +18301,7 @@ var SYNOPSIS = {
 var SUMMARIES = {
 	"up": "start it in the background (detached)",
 	"down": "stop it, and everything it supervises",
-	"restart": "down, then up",
+	"restart": "down then up — or one server, given an id",
 	"status": "is it running, where, and how to reach it",
 	"logs": "show the panel's own console output",
 	"start": "start one server, leaving the panel up",
@@ -18190,6 +18344,14 @@ var SERVER_SECTION = {
 	heading: "Arguments for start/stop",
 	lines: [["<id>", "the server id from servers.config.json"]]
 };
+var RESTART_SECTION = {
+	heading: "Options for restart",
+	lines: [
+		["<id>", "restart just this server, leaving the panel up (optional)"],
+		["-w, --workspace <id>", "the workspace to act in, with an id"],
+		...UP_SECTION.lines
+	]
+};
 var SET_PASSWORD_SECTION = {
 	heading: "Options for set-password",
 	lines: [["--clear", "remove the password, which disables authentication"]]
@@ -18309,6 +18471,7 @@ var UP_COMMANDS = /* @__PURE__ */ new Set(["up", "restart"]);
 var SECTIONS = {
 	"status": STATUS_SECTION,
 	"logs": LOGS_SECTION,
+	"restart": RESTART_SECTION,
 	"start": SERVER_SECTION,
 	"stop": SERVER_SECTION,
 	"set-password": SET_PASSWORD_SECTION,
@@ -18326,7 +18489,7 @@ var SECTIONS = {
 function commandHelp(command) {
 	const synopsis = SYNOPSIS[command];
 	if (synopsis === void 0) return USAGE;
-	const section = UP_COMMANDS.has(command) ? UP_SECTION : SECTIONS[command];
+	const section = SECTIONS[command] ?? (UP_COMMANDS.has(command) ? UP_SECTION : void 0);
 	const options = section === void 0 ? dim("no options") : renderSection(section);
 	return [
 		dim(HEADER),