home-hosted 0.7.10 → 0.7.12

package/AGENTS.md

@@ -24,6 +24,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
 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/
 pnpm dev --ui noc-console          # the same, for another UI; --port/--ui-port override
 pnpm run build                     # dist/cli.js + the stock UI (uis/stock/dist)
@@ -53,6 +54,19 @@ UI and every UI zip, lets changelogen write the changelog, bump `package.json`,
 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.
 
+Four workflows, and the split is deliberate:
+
+| workflow | runs on | what it proves |
+| --- | --- | --- |
+| `quickcheck.yml` / `test.yml` | every push and PR | lint, types, the whole suite with coverage — Linux only |
+| `cross-platform.yml` | the release gate, or by hand | the same suite on macOS and Windows |
+| `release.yml` | dispatched with a version | the platform gate, then tag, publish, release assets |
+
+The platform gate is not a per-push job on purpose: it is the expensive half, and it is what makes a
+platform-specific break fail before shipping rather than on someone's machine. It also runs on a
+`dry-run`, because that is exactly what a rehearsal needs to exercise. Every job carries a
+`timeout-minutes`, so a wedged runner is reported instead of sitting out GitHub's 6-hour default.
+
 ### Which version to dispatch
 
 Below 1.0 the **minor is the breaking channel**: a fix or a non-breaking feature is a **patch**

package/README.md

@@ -344,6 +344,7 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | `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 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`) |
 | `home-hosted migrate` | relocate a pre-workspaces state directory and stamp every config for this release (`--dry-run`, `--yes`) |
@@ -362,6 +363,7 @@ up, restart       -c/--config -p/--port --host --open --no-autostart --foregroun
 
 down              (no flags)
 status            --json
+logs              --lines <n> --follow --json
 start, stop       <id> [-w/--workspace <id>]   (both need the panel up)
 init              --dir --name --pm --no-install -y/--yes
 set-password      --clear
@@ -507,6 +509,24 @@ specific:
 
 ## ❓ FAQ
 
+<details>
+<summary><b>The panel is up but something is wrong — where do I look?</b></summary>
+
+`home-hosted logs` prints the panel's own console output, which is where it reports what it is
+doing and anything it could not finish:
+
+```bash
+home-hosted logs              # the last 50 lines
+home-hosted logs --follow     # keep printing, like tail -f
+home-hosted logs --lines all  # the whole thing, including the rotation
+```
+
+It is the same file `status` names, and reading it needs no session or API token — a panel that
+is answering badly is exactly when you cannot get one. `up` prints the tail automatically when
+the panel fails to start.
+
+</details>
+
 <details>
 <summary><b>Is it a systemd replacement?</b></summary>
 

package/dist/cli.js

@@ -5,6 +5,7 @@ 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 { Buffer as Buffer$1 } from "node:buffer";
 import os from "node:os";
 import { describeRoute, openAPIRouteHandler, resolver, validator } from "hono-openapi";
 import { createFactory } from "hono/factory";
@@ -13,7 +14,6 @@ import { isDevelopment } from "std-env";
 import { DetailedError } from "@namesmt/utils";
 import { type } from "arktype";
 import crypto, { X509Certificate, createPrivateKey, createPublicKey, randomBytes } from "node:crypto";
-import { Buffer as Buffer$1 } from "node:buffer";
 import { streamSSE } from "hono/streaming";
 import { autoRetry } from "@grammyjs/auto-retry";
 import { Bot } from "grammy";
@@ -306,6 +306,112 @@ var init_runtime = __esmMin((() => {
 	NANNY_COMMAND = "__nanny";
 }));
 //#endregion
+//#region src/helpers/daemon-log.ts
+var daemon_log_exports = /* @__PURE__ */ __exportAll({
+	followLog: () => followLog,
+	readLog: () => readLog,
+	rotateLog: () => rotateLog,
+	tailLog: () => tailLog
+});
+function rotateLog(file) {
+	try {
+		if (fs.statSync(file).size < LOG_ROTATE_BYTES) return;
+		fs.rmSync(`${file}.1`, { force: true });
+		fs.renameSync(file, `${file}.1`);
+	} catch {}
+}
+/**
+* The last `lines` lines, or `''` when there is no log to read.
+*
+* Split on the trailing newline rather than after it: a log file ends with one, so a plain
+* `split('\n').slice(-lines)` counts that empty last element as a line and quietly returns
+* one fewer than asked for.
+*/
+function tailLog(file, lines = 15) {
+	return withoutTrailingBlank(readLogLines(file)).slice(-lines).join("\n");
+}
+function readLogLines(file) {
+	try {
+		return fs.readFileSync(file, "utf8").split("\n");
+	} catch {
+		return [];
+	}
+}
+/** A file ending in a newline splits into a final empty element; it is not a line. */
+function withoutTrailingBlank(lines) {
+	return lines.at(-1) === "" ? lines.slice(0, -1) : lines;
+}
+/**
+* One rotation boundary's worth of lines, oldest first.
+*
+* The current file plus its `.1` ancestor, so `logs` shows what happened just before a
+* rotation rather than starting blank. `lines <= 0` means the whole thing.
+*/
+function readLog(file, lines) {
+	const parts = [];
+	for (const candidate of [`${file}.1`, file]) try {
+		parts.push(fs.readFileSync(candidate, "utf8"));
+	} catch {}
+	const all = withoutTrailingBlank(parts.join("").split("\n"));
+	return lines > 0 ? all.slice(-lines) : all;
+}
+/**
+* Prints the last `lines` of the log, then keeps printing whatever is appended.
+*
+* Polled rather than watched on purpose. `config-watch` documents why: an editor's save
+* replaces the inode, and `fs.watch` is undependable on some filesystems. A foreground
+* command also has to notice the rotation `up` performs, which shows up simply as the file
+* getting *smaller* — and a poll sees that without any special case.
+*
+* Resolves when the caller's signal arrives, so the command exits the way a pager would.
+*/
+async function followLog(file, lines, write, pollMs = 250) {
+	const initial = readLog(file, lines);
+	if (initial.length > 0) write(`${initial.join("\n")}\n`);
+	let offset = sizeOf(file);
+	let stopped = false;
+	const stop = () => {
+		stopped = true;
+	};
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+	try {
+		for (;;) {
+			await new Promise((resolve) => setTimeout(resolve, pollMs));
+			if (stopped) break;
+			const size = sizeOf(file);
+			if (size < offset) offset = 0;
+			if (size === offset) continue;
+			try {
+				const handle = fs.openSync(file, "r");
+				try {
+					const length = size - offset;
+					const buffer = Buffer$1.alloc(length);
+					fs.readSync(handle, buffer, 0, length, offset);
+					write(buffer.toString("utf8").replace(/\n+$/, "\n"));
+				} finally {
+					fs.closeSync(handle);
+				}
+				offset = size;
+			} catch {}
+		}
+	} finally {
+		process.removeListener("SIGINT", stop);
+		process.removeListener("SIGTERM", stop);
+	}
+}
+function sizeOf(file) {
+	try {
+		return fs.statSync(file).size;
+	} catch {
+		return 0;
+	}
+}
+var LOG_ROTATE_BYTES;
+var init_daemon_log = __esmMin((() => {
+	LOG_ROTATE_BYTES = 5242880;
+}));
+//#endregion
 //#region src/helpers/version.ts
 var version_exports = /* @__PURE__ */ __exportAll({
 	appVersion: () => appVersion,
@@ -6018,7 +6124,7 @@ function createLogsRoute(deps) {
 	});
 }
 var MIN_TAIL, MAX_TAIL, DEFAULT_TAIL, idParam$2, downloadQuery, historyQuery;
-var init_logs = __esmMin((() => {
+var init_logs$1 = __esmMin((() => {
 	init_factory();
 	init_openapi$1();
 	init_validator();
@@ -8372,20 +8478,7 @@ var init_proxy$1 = __esmMin((() => {
 				return;
 			}
 			await this.assertPortsFree(this.config.httpPort, this.config.httpsPort);
-			const result = await this.request("POST", "/load", rendered).catch((error) => {
-				this.lastError = `the engine did not accept the configuration: ${error instanceof Error ? error.message : String(error)}`;
-				throw new DetailedError(this.lastError, {
-					statusCode: 502,
-					code: "ENGINE_UNREACHABLE"
-				});
-			});
-			if (result.status >= 400) {
-				this.lastError = engineMessage(result.body) ?? `the engine rejected the configuration (HTTP ${result.status})`;
-				throw new DetailedError(this.lastError, {
-					statusCode: 400,
-					code: "PROXY_CONFIG_REJECTED"
-				});
-			}
+			await this.postConfiguration(rendered);
 			this.rememberConfig(text);
 			this.rememberApplied(this.config.httpPort, this.config.httpsPort);
 			const swept = this.sweepUnroutedCertificates();
@@ -8431,22 +8524,34 @@ var init_proxy$1 = __esmMin((() => {
 			}
 			return removed;
 		}
-		/** Hands a configuration to the running engine without touching the file on disk. */
-		async loadIntoEngine(rendered) {
+		/**
+		* Posts one rendered configuration to the engine's admin endpoint and reports a refusal.
+		*
+		* The three call sites used to spell this out themselves, and one of them forgot to record
+		* `lastError` — which is what `status()` shows as the proxy's state, so a configuration the
+		* engine refused could leave the panel reporting the proxy as healthy. Keeping both the
+		* message and the state in one place is the point.
+		*/
+		async postConfiguration(rendered) {
 			const result = await this.request("POST", "/load", rendered).catch((error) => {
-				throw new DetailedError(`the engine did not accept the configuration: ${error instanceof Error ? error.message : String(error)}`, {
+				this.lastError = `the engine did not accept the configuration: ${error instanceof Error ? error.message : String(error)}`;
+				throw new DetailedError(this.lastError, {
 					statusCode: 502,
 					code: "ENGINE_UNREACHABLE"
 				});
 			});
 			if (result.status >= 400) {
-				const message = engineMessage(result.body) ?? `the engine rejected the configuration (HTTP ${result.status})`;
-				throw new DetailedError(message, {
+				this.lastError = engineMessage(result.body) ?? `the engine rejected the configuration (HTTP ${result.status})`;
+				throw new DetailedError(this.lastError, {
 					statusCode: 400,
 					code: "PROXY_CONFIG_REJECTED"
 				});
 			}
 		}
+		/** Hands a configuration to the running engine without touching the file on disk. */
+		async loadIntoEngine(rendered) {
+			await this.postConfiguration(rendered);
+		}
 		/** Advances `previous.json` only for a configuration the engine accepted. */
 		rememberConfig(text) {
 			if (fs.existsSync(this.options.configPath)) writeFileAtomic(this.options.previousConfigPath, fs.readFileSync(this.options.configPath, "utf8"), { mode: 384 });
@@ -8511,14 +8616,7 @@ var init_proxy$1 = __esmMin((() => {
 			});
 			const current = fs.existsSync(this.options.configPath) ? fs.readFileSync(this.options.configPath, "utf8") : null;
 			const previous = fs.readFileSync(this.options.previousConfigPath, "utf8");
-			const result = await this.request("POST", "/load", JSON.parse(previous));
-			if (result.status >= 400) {
-				this.lastError = engineMessage(result.body) ?? `the engine rejected the configuration (HTTP ${result.status})`;
-				throw new DetailedError(this.lastError, {
-					statusCode: 400,
-					code: "PROXY_CONFIG_REJECTED"
-				});
-			}
+			await this.postConfiguration(JSON.parse(previous));
 			writeFileAtomic(this.options.configPath, previous, { mode: 384 });
 			if (current === null) fs.rmSync(this.options.previousConfigPath, { force: true });
 			else writeFileAtomic(this.options.previousConfigPath, current, { mode: 384 });
@@ -10314,7 +10412,7 @@ var init_app = __esmMin((() => {
 	init_ddns$1();
 	init_events();
 	init_health();
-	init_logs();
+	init_logs$1();
 	init_metrics();
 	init_notifications$1();
 	init_proxy();
@@ -14991,6 +15089,7 @@ function stateSignature(state) {
 		state.host.alerts.join(","),
 		state.backups.files.length,
 		state.backups.entries.length,
+		`${state.ui.custom}:${state.ui.meta?.name ?? ""}:${state.ui.meta?.version ?? ""}`,
 		state.proxy === void 0 ? "" : [
 			state.proxy.config.enabled,
 			state.proxy.status.state,
@@ -16446,21 +16545,6 @@ function toUpFlags(args) {
 		printConfig: args.printConfig === true
 	};
 }
-/** One rotation is enough for a console log. */
-function rotateLog(file) {
-	try {
-		if (fs.statSync(file).size < LOG_ROTATE_BYTES) return;
-		fs.rmSync(`${file}.1`, { force: true });
-		fs.renameSync(file, `${file}.1`);
-	} catch {}
-}
-function tailLog(file, lines = 15) {
-	try {
-		return fs.readFileSync(file, "utf8").split("\n").slice(-lines).join("\n").trimEnd();
-	} catch {
-		return "";
-	}
-}
 async function runUp(flags, entry) {
 	const { runControlPlane } = await Promise.resolve().then(() => (init_src(), src_exports));
 	if (flags.foreground || flags.printConfig) {
@@ -16545,14 +16629,14 @@ function upCommand(entry) {
 		}
 	});
 }
-var DEFAULT_PORT$1, LOG_ROTATE_BYTES, upArgs;
+var DEFAULT_PORT$1, upArgs;
 var init_up = __esmMin((() => {
 	init_args();
 	init_io();
+	init_daemon_log();
 	init_runtime();
 	init_version();
 	DEFAULT_PORT$1 = 3999;
-	LOG_ROTATE_BYTES = 5242880;
 	upArgs = {
 		config: {
 			type: "string",
@@ -16798,6 +16882,82 @@ var init_status = __esmMin((() => {
 	});
 }));
 //#endregion
+//#region src/cli/logs.ts
+var logs_exports = /* @__PURE__ */ __exportAll({
+	logsArgs: () => logsArgs,
+	logsCommand: () => logsCommand,
+	runLogs: () => runLogs
+});
+/** `all` or a negative count means the whole log; a bad number is not worth a hard failure. */
+function parseLines(raw) {
+	if (raw === void 0) return DEFAULT_LINES;
+	if (raw.trim().toLowerCase() === "all") return 0;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed)) return DEFAULT_LINES;
+	return parsed < 0 ? 0 : parsed;
+}
+async function runLogs(input) {
+	const { daemonLogPath } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+	const { readLog } = await Promise.resolve().then(() => (init_daemon_log(), daemon_log_exports));
+	const lines = parseLines(input.lines);
+	if (input.follow === true) {
+		const { followLog } = await Promise.resolve().then(() => (init_daemon_log(), daemon_log_exports));
+		await followLog(daemonLogPath, lines === 0 ? DEFAULT_LINES : lines, (chunk) => process.stdout.write(chunk));
+		return;
+	}
+	const output = readLog(daemonLogPath, lines);
+	if (input.json === true) {
+		process.stdout.write(`${JSON.stringify({
+			path: daemonLogPath,
+			lines: output
+		}, null, 2)}\n`);
+		return;
+	}
+	if (output.length === 0) {
+		process.stdout.write(`${dim(`no output yet — ${daemonLogPath}`)}\n`);
+		return;
+	}
+	process.stdout.write(`${bold(daemonLogPath)}\n`);
+	for (const line of output) process.stdout.write(`${line}\n`);
+}
+var logsArgs, DEFAULT_LINES, logsCommand;
+var init_logs = __esmMin((() => {
+	init_io();
+	logsArgs = {
+		lines: {
+			type: "string",
+			description: "how many lines to show (default 50, `all` for everything)"
+		},
+		follow: {
+			type: "boolean",
+			description: "keep printing as the panel writes (like tail -f)"
+		},
+		json: {
+			type: "boolean",
+			description: "print machine-readable JSON"
+		}
+	};
+	DEFAULT_LINES = 50;
+	logsCommand = defineCommand({
+		meta: {
+			name: "logs",
+			description: "show the panel's own console output"
+		},
+		args: logsArgs,
+		async run({ args }) {
+			try {
+				await runLogs({
+					lines: args.lines,
+					follow: args.follow,
+					json: args.json
+				});
+			} catch (error) {
+				fail(error instanceof Error ? error.message : String(error));
+			}
+		}
+	});
+}));
+//#endregion
 //#region src/cli/server.ts
 var server_exports = /* @__PURE__ */ __exportAll({
 	runServerAction: () => runServerAction,
@@ -17973,6 +18133,7 @@ var SYNOPSIS = {
 	"down": "home-hosted down",
 	"restart": "home-hosted restart [options]",
 	"status": "home-hosted status [--json]",
+	"logs": "home-hosted logs [--lines <n>] [--follow] [--json]",
 	"start": "home-hosted start <id> [--workspace <id>]",
 	"stop": "home-hosted stop <id> [--workspace <id>]",
 	"set-password": "home-hosted set-password",
@@ -17988,6 +18149,7 @@ var SUMMARIES = {
 	"down": "stop it, and everything it supervises",
 	"restart": "down, then up",
 	"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",
 	"stop": "stop one server, leaving the panel up",
 	"set-password": "set the panel password without the API",
@@ -18016,6 +18178,14 @@ var STATUS_SECTION = {
 	heading: "Options for status",
 	lines: [["--json", "print machine-readable JSON"]]
 };
+var LOGS_SECTION = {
+	heading: "Options for logs",
+	lines: [
+		["--lines <n>", "how many lines to show (default 50, `all` for everything)"],
+		["--follow", "keep printing as the panel writes (like tail -f)"],
+		["--json", "print machine-readable JSON"]
+	]
+};
 var SERVER_SECTION = {
 	heading: "Arguments for start/stop",
 	lines: [["<id>", "the server id from servers.config.json"]]
@@ -18138,6 +18308,7 @@ var USAGE = [
 var UP_COMMANDS = /* @__PURE__ */ new Set(["up", "restart"]);
 var SECTIONS = {
 	"status": STATUS_SECTION,
+	"logs": LOGS_SECTION,
 	"start": SERVER_SECTION,
 	"stop": SERVER_SECTION,
 	"set-password": SET_PASSWORD_SECTION,
@@ -18186,6 +18357,7 @@ var COMMANDS = {
 	"down": () => Promise.resolve().then(() => (init_down(), down_exports)).then((module) => module.downCommand),
 	"restart": () => Promise.resolve().then(() => (init_restart(), restart_exports)).then((module) => module.restartCommand(CLI_ENTRY)),
 	"status": () => Promise.resolve().then(() => (init_status(), status_exports)).then((module) => module.statusCommand),
+	"logs": () => Promise.resolve().then(() => (init_logs(), logs_exports)).then((module) => module.logsCommand),
 	"start": () => Promise.resolve().then(() => (init_server(), server_exports)).then((module) => module.startCommand),
 	"stop": () => Promise.resolve().then(() => (init_server(), server_exports)).then((module) => module.stopCommand),
 	"set-password": () => Promise.resolve().then(() => (init_set_password(), set_password_exports)).then((module) => module.setPasswordCommand),