home-hosted 0.4.0 → 0.5.0

package/dist/cli.js

@@ -1,10 +1,10 @@
-import { exec, execFile, spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
-import path from "node:path";
 import process from "node:process";
-import readline from "node:readline";
 import { fileURLToPath } from "node:url";
-import { parseArgs, promisify } from "node:util";
+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 os from "node:os";
 import { DetailedError } from "@namesmt/utils";
 import { describeRoute, openAPIRouteHandler, resolver, validator } from "hono-openapi";
@@ -23,6 +23,7 @@ import { Scalar } from "@scalar/hono-api-reference";
 import http from "node:http";
 import https from "node:https";
 import net from "node:net";
+import { parseArgs, promisify } from "node:util";
 import { Readable, Writable } from "node:stream";
 import { finished } from "node:stream/promises";
 import { BlobReader, ZipReader, ZipWriter, configure } from "@zip.js/zip.js";
@@ -47,6 +48,214 @@ var __exportAll = (all, no_symbols) => {
 	return target;
 };
 //#endregion
+//#region src/cli/args.ts
+/** `--home`/`--project` are handled for every command, so they are peeled off first. */
+function extractDirFlags(argv) {
+	const rest = [];
+	let project;
+	let home;
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index];
+		const equals = arg.indexOf("=");
+		const name = equals === -1 ? arg : arg.slice(0, equals);
+		if (name !== "--project" && name !== "--home") {
+			rest.push(arg);
+			continue;
+		}
+		const value = equals === -1 ? argv[++index] : arg.slice(equals + 1);
+		if (value === void 0 || value.length === 0) return {
+			rest,
+			project,
+			home,
+			error: `${name} needs a directory`
+		};
+		if (name === "--project") project = value;
+		else home = value;
+	}
+	return {
+		rest,
+		project,
+		home
+	};
+}
+/** Set before any state module is imported, so it decides where state lives. */
+function applyDirFlags(flags) {
+	if (flags.project !== void 0) process.env.HHOSTED_PROJECT = path.resolve(flags.project);
+	if (flags.home !== void 0) process.env.HHOSTED_HOME = path.resolve(flags.home);
+}
+/**
+* What the stripped argv means, before citty sees it.
+*
+* `help`/`version` are commands here, not flags, and a help or version flag on a
+* command is answered the same way instead of being parsed as one of that
+* command's options. A first token that starts with `-` is the one-shot form
+* (`home-hosted -p 4000`), so `up` is prepended. Anything else has to name a
+* command, which keeps the old `unknown command:` text exact.
+*/
+function resolveInvocation(argv, commands) {
+	if (argv.length === 0) return {
+		kind: "command",
+		argv: ["up"]
+	};
+	const first = argv[0];
+	if (HELP_TOKENS.has(first)) return { kind: "help" };
+	if (VERSION_TOKENS.has(first)) return { kind: "version" };
+	if (first.startsWith("-")) return {
+		kind: "command",
+		argv: ["up", ...argv]
+	};
+	if (!commands.includes(first)) return {
+		kind: "unknown",
+		command: first
+	};
+	for (const arg of argv.slice(1)) {
+		if (HELP_FLAGS.has(arg)) return { kind: "help" };
+		if (VERSION_FLAGS.has(arg)) return { kind: "version" };
+	}
+	return {
+		kind: "command",
+		argv
+	};
+}
+/** citty takes camelCase definitions; the flag a person types is kebab-case. */
+function kebab(name) {
+	return name.replace(CAMEL, (match) => `-${match.toLowerCase()}`);
+}
+function aliasesOf(def) {
+	if (def === void 0 || !("alias" in def) || def.alias === void 0) return [];
+	return Array.isArray(def.alias) ? def.alias : [def.alias];
+}
+function findArg(argsDef, name) {
+	for (const [key, def] of Object.entries(argsDef)) {
+		if (def === void 0) continue;
+		if ((/* @__PURE__ */ new Set([
+			key,
+			kebab(key),
+			...aliasesOf(def)
+		])).has(name)) return def;
+		if (def.type === "boolean" && (name === `no-${key}` || name === `no-${kebab(key)}`)) return def;
+	}
+}
+/**
+* citty parses permissively (`strict: false`), so a mistyped flag would quietly do
+* nothing — `--autostart` where `--no-autostart` was meant would start the panel
+* with the wrong policy. This keeps the refusal the command line always had, from
+* citty's own definitions rather than a second list.
+*
+* A command that declares no arguments parses its own argv (and rejects its own
+* unknown flags), so it is left alone. Returns the message to print, or null.
+*/
+function rejectUnknownFlags(argv, argsDef) {
+	if (argsDef === void 0 || Object.keys(argsDef).length === 0) return null;
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index];
+		if (token === "--") return null;
+		if (!token.startsWith("-") || token.length === 1) return `Unexpected argument '${token}'`;
+		const body = token.startsWith("--") ? token.slice(2) : token.slice(1);
+		const equals = body.indexOf("=");
+		const name = equals === -1 ? body : body.slice(0, equals);
+		const def = name.length === 0 ? void 0 : findArg(argsDef, name);
+		if (def === void 0) return `Unknown option '${token}'`;
+		if (def.type === "string" && equals === -1 && argv[index + 1] === void 0) return `Option '${token}' needs a value`;
+		if (def.type === "string" && equals === -1) index += 1;
+	}
+	return null;
+}
+/**
+* The daemon gets the same instructions, but never `--foreground` (that is what
+* makes it the daemon) and never `--print-config` (that one is answered in the
+* calling process).
+*/
+function buildDaemonArgv(flags) {
+	const args = ["up", "--foreground"];
+	if (flags.config !== void 0) args.push("--config", flags.config);
+	if (flags.port !== void 0) args.push("--port", String(flags.port));
+	if (flags.host !== void 0) args.push("--host", flags.host);
+	if (!flags.autostart) args.push("--no-autostart");
+	if (flags.open) args.push("--open");
+	return args;
+}
+var HELP_TOKENS, VERSION_TOKENS, HELP_FLAGS, VERSION_FLAGS, CAMEL;
+var init_args = __esmMin((() => {
+	HELP_TOKENS = /* @__PURE__ */ new Set([
+		"help",
+		"--help",
+		"-h"
+	]);
+	VERSION_TOKENS = /* @__PURE__ */ new Set([
+		"version",
+		"--version",
+		"-v"
+	]);
+	HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h"]);
+	VERSION_FLAGS = /* @__PURE__ */ new Set(["--version", "-v"]);
+	CAMEL = /[A-Z]/g;
+}));
+//#endregion
+//#region src/cli/io.ts
+/** One shape for every failure: a red `error <message>` on stderr and exit 1. */
+function fail(message) {
+	process.stderr.write(`${paint("31", "error")} ${message}\n`);
+	process.exit(1);
+}
+function delay$3(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** A plain y/N question, for decisions that are not secrets. */
+function prompt(question) {
+	return new Promise((resolve) => {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer);
+		});
+	});
+}
+/** Reads a line with echo suppressed, so the password never lands in scrollback. */
+function promptHidden(question) {
+	return new Promise((resolve) => {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+			terminal: true
+		});
+		const onData = () => {
+			readline.clearLine(process.stdout, 0);
+			readline.cursorTo(process.stdout, 0);
+			process.stdout.write(question);
+		};
+		process.stdin.on("data", onData);
+		rl.question(question, (answer) => {
+			process.stdin.off("data", onData);
+			rl.close();
+			process.stdout.write("\n");
+			resolve(answer);
+		});
+	});
+}
+/** Asks a yes/no question with a default, so an empty answer is a real answer. */
+async function confirm(question, fallback) {
+	const answer = (await prompt(`${question} ${fallback ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+	if (answer.length === 0) return fallback;
+	return answer === "y" || answer === "yes";
+}
+var isTty, paint, dim, bold, green, style;
+var init_io = __esmMin((() => {
+	isTty = () => process.stdout.isTTY === true;
+	paint = (code, text) => isTty() ? `\x1B[${code}m${text}\x1B[0m` : text;
+	dim = (text) => paint("2", text);
+	bold = (text) => paint("1", text);
+	green = (text) => paint("32", text);
+	style = {
+		bold,
+		dim,
+		green
+	};
+}));
+//#endregion
 //#region src/helpers/cookies.ts
 function parseCookies(header) {
 	const cookies = {};
@@ -88,7 +297,7 @@ function parseBind(value) {
 	const parsed = bindSchema(value);
 	return parsed instanceof type.errors ? null : parsed;
 }
-var bindSchema, portSchema, restartSchema, httpCheckSchema, resourcesSchema, healthSchema, stopSchema, bootstrapSchema, bootstrapOrNullSchema, logBufferLinesSchema, serverSchema, authSchema, telegramSchema, notificationsSchema, logsSchema, tlsSchema, hostSchema, backupsSchema, controlSchema, defaultsSchema, restartPatchSchema, httpCheckPatchSchema, resourcesPatchSchema, healthPatchSchema, stopPatchSchema, authPatchSchema, telegramPatchSchema, notificationsPatchSchema, hostPatchSchema, backupsPatchSchema, logsPatchSchema, tlsPatchSchema, controlPatchSchema, defaultsPatchSchema, editableFields, serverPatchSchema, serverCreateSchema, settingsPatchSchema, authStatusSchema, tlsStatusSchema, telegramStatusSchema, notificationViewSchema, sessionViewSchema, loginSchema, passwordValueSchema, passwordSchema, serverStatusSchema, healthStateSchema, portStateSchema, logStreamSchema, logLineSchema, historyEventSchema, serverHistorySchema, processResourcesSchema, hostDiskSchema, hostViewSchema, backupFileSchema, backupPathSchema, backupsViewSchema, restoreItemSchema, restorePlanSchema, backupCreateSchema, restoreRequestSchema, serverViewSchema, controlViewSchema, appStateSchema, logQuerySchema, freePortResultSchema, logHistoryQuerySchema, logFileInfoSchema, logServerViewSchema, logServersViewSchema, notificationActionSchema, telegramTokenSchema, apiErrorSchema, uiMetaSchema, tlsUploadSchema;
+var bindSchema, portSchema, restartSchema, httpCheckSchema, resourcesSchema, healthSchema, stopSchema, bootstrapSchema, bootstrapOrNullSchema, logBufferLinesSchema, serverSchema, authSchema, telegramSchema, notificationsSchema, logsSchema, tlsSchema, hostSchema, backupsSchema, controlSchema, defaultsSchema, restartPatchSchema, httpCheckPatchSchema, resourcesPatchSchema, healthPatchSchema, stopPatchSchema, authPatchSchema, telegramPatchSchema, notificationsPatchSchema, hostPatchSchema, backupsPatchSchema, logsPatchSchema, tlsPatchSchema, controlPatchSchema, defaultsPatchSchema, editableFields, serverPatchSchema, serverCreateSchema, settingsPatchSchema, authStatusSchema, tlsStatusSchema, telegramStatusSchema, notificationViewSchema, sessionViewSchema, loginSchema, passwordValueSchema, passwordSchema, serverStatusSchema, healthStateSchema, portStateSchema, logStreamSchema, logLineSchema, historyEventSchema, serverHistorySchema, processResourcesSchema, hostDiskSchema, hostViewSchema, backupFileSchema, backupPathSchema, backupsViewSchema, restoreItemSchema, restorePlanSchema, backupCreateSchema, restoreRequestSchema, serverViewSchema, controlViewSchema, appStateSchema, logQuerySchema, freePortResultSchema, logHistoryQuerySchema, logFileInfoSchema, logServerViewSchema, logServersViewSchema, notificationActionSchema, telegramTokenSchema, apiErrorSchema, uiMetaSchema, uiStatusSchema, tlsUploadSchema, settingsViewSchema, settingsSavedSchema;
 var init_contracts = __esmMin((() => {
 	bindSchema = type("\"local\" | \"lan\" | /^\\d{1,3}(?:\\.\\d{1,3}){3}$/");
 	portSchema = type("1 <= number.integer <= 65535 | null");
@@ -173,7 +382,12 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		envFile: "string = \"\"",
 		resources: resourcesSchema.default(() => ({})),
 		/** Paths included in backups for this server (templates allowed). */
-		backupPaths: type("string[]").default(() => [])
+		backupPaths: type("string[]").default(() => []),
+		/**
+		* Skip well-known build output and dependency directories (`node_modules`,
+		* `dist`, `.next`, caches, …) inside the paths this entry declares.
+		*/
+		backupIgnoreGenerated: "boolean = true"
 	}).onUndeclaredKey("reject");
 	authSchema = type({
 		enabled: "boolean = true",
@@ -355,7 +569,8 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		dependsOn: type("string[]").optional(),
 		envFile: "string?",
 		resources: resourcesPatchSchema.optional(),
-		backupPaths: type("string[]").optional()
+		backupPaths: type("string[]").optional(),
+		backupIgnoreGenerated: "boolean?"
 	};
 	serverPatchSchema = type(editableFields).onUndeclaredKey("reject");
 	serverCreateSchema = type({
@@ -507,7 +722,9 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		origin: "string",
 		/** false when a parent path already covers it, or it would swallow the archive dir. */
 		included: "boolean",
-		note: "string | null"
+		note: "string | null",
+		/** The declaring entry asked for generated directories to be skipped. */
+		ignoreGenerated: "boolean?"
 	});
 	backupsViewSchema = type({
 		enabled: "boolean",
@@ -676,7 +893,7 @@ password: passwordValueSchema.optional() }).onUndeclaredKey("reject");
 		uploadedAt: "number",
 		files: "number.integer >= 1"
 	});
-	type({
+	uiStatusSchema = type({
 		/** A user-supplied UI is being served instead of the stock one. */
 		custom: "boolean",
 		/** Where that UI lives, whether or not it exists yet. */
@@ -687,6 +904,20 @@ password: passwordValueSchema.optional() }).onUndeclaredKey("reject");
 		certificate: "string >= 1",
 		privateKey: "string >= 1"
 	}).onUndeclaredKey("reject");
+	settingsViewSchema = type({
+		control: controlViewSchema,
+		defaults: defaultsSchema,
+		logs: logsSchema,
+		notifications: notificationViewSchema,
+		host: hostSchema,
+		backups: backupsViewSchema,
+		ui: uiStatusSchema
+	});
+	settingsSavedSchema = settingsViewSchema.and(type({
+		/** The listener is moving; reconnect at `targetUrl` when it stops being null. */
+		rebinding: "boolean",
+		targetUrl: "string | null"
+	}));
 }));
 //#endregion
 //#region src/helpers/openapi.ts
@@ -757,7 +988,6 @@ function isLoopbackRequest(c) {
 var init_loopback = __esmMin((() => {}));
 //#endregion
 //#region src/helpers/atomic.ts
-var atomic_exports = /* @__PURE__ */ __exportAll({ writeFileAtomic: () => writeFileAtomic });
 /**
 * Write via a temp file in the same directory, then rename: readers never see a
 * half-written file, and a crash cannot truncate the previous config.
@@ -772,17 +1002,6 @@ function writeFileAtomic(file, content, options = {}) {
 var init_atomic = __esmMin((() => {}));
 //#endregion
 //#region src/config/secrets.ts
-var secrets_exports = /* @__PURE__ */ __exportAll({
-	API_TOKEN_PREFIX: () => "hh_",
-	SecretsStore: () => SecretsStore,
-	apiTokenRecord: () => apiTokenRecord,
-	deriveKey: () => deriveKey,
-	generateApiToken: () => generateApiToken,
-	hashApiToken: () => hashApiToken,
-	hashPassword: () => hashPassword,
-	verifyApiToken: () => verifyApiToken,
-	verifyPassword: () => verifyPassword
-});
 function deriveKey(password, salt, cost, keylen) {
 	return crypto.scryptSync(password.normalize("NFKC"), salt, keylen, { ...cost });
 }
@@ -819,6 +1038,7 @@ function verifyApiToken(token, record) {
 	if (token.length === 0) return false;
 	const expected = Buffer$1.from(record.hash, "base64");
 	const actual = Buffer$1.from(hashApiToken(token), "base64");
+	if (actual.length !== expected.length) return false;
 	return crypto.timingSafeEqual(actual, expected);
 }
 function apiTokenRecord(token, now = Date.now()) {
@@ -1539,7 +1759,7 @@ function resolveProjectDir() {
 function resolveUserPath(target, base = projectDir) {
 	let value = target;
 	if (value === "~") value = os.homedir();
-	else if (value.startsWith("~/")) value = path.join(os.homedir(), value.slice(2));
+	else if (value.startsWith("~/") || value.startsWith("~\\")) value = path.join(os.homedir(), value.slice(2));
 	return path.isAbsolute(value) ? value : path.resolve(base, value);
 }
 var dataRoot, projectDir, defaultConfigPath, configSchemaPath, defaultSecretsPath, defaultLogsDir, defaultHistoryPath, defaultTlsDir, runtimePath, daemonLogPath;
@@ -1667,8 +1887,8 @@ function createBackupsRoute(deps) {
 			200: { description: "the archive (application/zip)" },
 			404: ERROR_RESPONSES[404]
 		}
-	}), (c) => {
-		const file = deps.backups.resolve(c.req.param("name"));
+	}), validate("param", nameParam), (c) => {
+		const file = deps.backups.resolve(c.req.valid("param").name);
 		if (file === null) throw new DetailedError("unknown backup", {
 			statusCode: 404,
 			code: "UNKNOWN_BACKUP"
@@ -1686,8 +1906,8 @@ function createBackupsRoute(deps) {
 			200: { description: "Removed" },
 			404: ERROR_RESPONSES[404]
 		}
-	}), (c) => {
-		if (!deps.backups.remove(c.req.param("name"))) throw new DetailedError("unknown backup", {
+	}), validate("param", nameParam), (c) => {
+		if (!deps.backups.remove(c.req.valid("param").name)) throw new DetailedError("unknown backup", {
 			statusCode: 404,
 			code: "UNKNOWN_BACKUP"
 		});
@@ -1731,8 +1951,8 @@ function createBackupsRoute(deps) {
 				});
 				const uploads = path.join(deps.backups.directory, "uploads");
 				fs.mkdirSync(uploads, { recursive: true });
-				uploadedTo = path.join(uploads, `upload-${Date.now()}.zip`);
-				fs.writeFileSync(uploadedTo, Buffer$1.from(await file.arrayBuffer()));
+				uploadedTo = path.join(uploads, `upload-${crypto.randomUUID()}.zip`);
+				fs.writeFileSync(uploadedTo, Buffer$1.from(await file.arrayBuffer()), { mode: 384 });
 				archive = uploadedTo;
 				const rawInclude = typeof body.include === "string" && body.include.length > 0 ? body.include : null;
 				let include;
@@ -1782,7 +2002,7 @@ function createBackupsRoute(deps) {
 		}
 	});
 }
-var MAX_UPLOAD_BYTES;
+var MAX_UPLOAD_BYTES, nameParam;
 var init_backups$1 = __esmMin((() => {
 	init_factory();
 	init_logger();
@@ -1792,6 +2012,7 @@ var init_backups$1 = __esmMin((() => {
 	init_state$1();
 	init_contracts();
 	MAX_UPLOAD_BYTES = 268435456;
+	nameParam = type({ name: "string >= 1" });
 }));
 //#endregion
 //#region src/helpers/deferred.ts
@@ -1867,7 +2088,7 @@ function createEventsRoute(deps) {
 			let closed = false;
 			const send = (message) => {
 				if (closed) return queue;
-				if (message.type === "log" && pending > MAX_PENDING_WRITES) return queue;
+				if (message.type === "log" && pending > MAX_PENDING_WRITES$1) return queue;
 				pending += 1;
 				queue = queue.then(() => stream.writeSSE({
 					event: message.type,
@@ -1903,11 +2124,11 @@ function createEventsRoute(deps) {
 		});
 	});
 }
-var MAX_PENDING_WRITES, PING_INTERVAL_MS, eventsQuery;
+var MAX_PENDING_WRITES$1, PING_INTERVAL_MS, eventsQuery;
 var init_events$1 = __esmMin((() => {
 	init_factory();
 	init_validator();
-	MAX_PENDING_WRITES = 200;
+	MAX_PENDING_WRITES$1 = 200;
 	PING_INTERVAL_MS = 15e3;
 	eventsQuery = type({
 		/** Only this server's frames. */
@@ -2287,12 +2508,6 @@ var init_notifications$1 = __esmMin((() => {
 }));
 //#endregion
 //#region src/config/migrations.ts
-var migrations_exports = /* @__PURE__ */ __exportAll({
-	CONFIG_SCHEMA: () => 1,
-	applyConfigMigrations: () => applyConfigMigrations,
-	configMigrations: () => configMigrations,
-	planConfigMigrations: () => planConfigMigrations
-});
 /** What would have to run to bring `from` up to `to`. */
 function planConfigMigrations(from, options = {}) {
 	const to = options.to ?? 1;
@@ -2319,6 +2534,24 @@ var init_migrations = __esmMin((() => {
 }));
 //#endregion
 //#region src/config/schema.ts
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Resolves one entry against the panel's server defaults. A group (`restart`,
+* `health`, `health.http`, `stop`) merges key by key, so an entry that decides one
+* member does not silently fall back to the *schema* default for the others — which
+* is the whole point of the panel having defaults at all.
+*/
+function mergeDefaults(defaults, entry) {
+	const merged = { ...entry };
+	for (const [key, value] of Object.entries(defaults)) {
+		const current = merged[key];
+		if (current === void 0) merged[key] = value;
+		else if (isRecord$2(value) && isRecord$2(current)) merged[key] = mergeDefaults(value, current);
+	}
+	return merged;
+}
 var metaSchema, configSchema, CONFIG_KEYS;
 var init_schema = __esmMin((() => {
 	init_contracts();
@@ -2383,10 +2616,6 @@ var init_version = __esmMin((() => {
 }));
 //#endregion
 //#region src/config/parse.ts
-var parse_exports = /* @__PURE__ */ __exportAll({
-	parseConfig: () => parseConfig,
-	stampConfig: () => stampConfig
-});
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -2485,10 +2714,7 @@ function parseConfig(raw, options = {}) {
 	const seen = /* @__PURE__ */ new Set();
 	(Array.isArray(raw.servers) ? raw.servers : []).forEach((entry, index) => {
 		const label = `servers[${index}]`;
-		const parsed = parseTolerant(isRecord$1(entry) ? {
-			...defaults,
-			...entry
-		} : entry, serverSchema, label, unknownKeys);
+		const parsed = parseTolerant(isRecord$1(entry) ? mergeDefaults(defaults, entry) : entry, serverSchema, label, unknownKeys);
 		if (parsed.error !== null) {
 			const id = isRecord$1(entry) ? entry.id : void 0;
 			errors.push(`${label}${typeof id === "string" ? ` ("${id}")` : ""}: ${parsed.error}`);
@@ -2655,6 +2881,8 @@ var init_store = __esmMin((() => {
 		file;
 		seed;
 		raw = {};
+		/** The bytes behind the live config, so a watcher can tell a real edit from our own write. */
+		lastText = null;
 		resolvedConfig;
 		error = null;
 		warnings = [];
@@ -2703,29 +2931,75 @@ var init_store = __esmMin((() => {
 		}
 		/**
 		* Reads the file and tells the listeners, so whatever wrote it — the settings
-		* page, or a restored backup landing on disk — becomes the live config.
+		* page, a restored backup, or the file watcher — becomes the live config.
 		*/
 		load() {
 			this.read();
 			this.notify();
 		}
+		/**
+		* The watcher's entry point: re-reads the file only when its bytes changed.
+		*
+		* `changed` means the file on disk is different from what the live config was
+		* read from, `applied` means that difference was accepted — a file this release
+		* cannot read is reported and the config already running is left alone, which is
+		* what keeps an editor's typo from stopping every server.
+		*/
+		reloadFromDisk() {
+			let text;
+			try {
+				text = fs.readFileSync(this.file, "utf8");
+			} catch {
+				this.error = `${path.basename(this.file)} is gone`;
+				return {
+					changed: false,
+					applied: false,
+					error: this.error
+				};
+			}
+			if (text === this.lastText) {
+				if (this.error !== null) {
+					this.error = null;
+					this.load();
+				}
+				return {
+					changed: false,
+					applied: false,
+					error: null
+				};
+			}
+			const before = this.resolvedConfig;
+			this.load();
+			return {
+				changed: true,
+				applied: this.resolvedConfig !== before,
+				error: this.error
+			};
+		}
 		read() {
 			if (!fs.existsSync(this.file)) {
 				const seed = stampConfig(structuredClone(this.seed));
-				writeFileAtomic(this.file, `${JSON.stringify(seed, null, 2)}\n`);
+				const text = `${JSON.stringify(seed, null, 2)}\n`;
+				writeFileAtomic(this.file, text);
+				this.lastText = text;
 				this.raw = seed;
 				this.apply(seed);
 				return;
 			}
+			let text;
 			let parsed;
 			try {
-				parsed = JSON.parse(fs.readFileSync(this.file, "utf8"));
+				text = fs.readFileSync(this.file, "utf8");
+				parsed = JSON.parse(text);
 			} catch (error) {
 				this.error = `cannot parse ${path.basename(this.file)}: ${error.message}`;
-				this.raw = {};
-				this.resolvedConfig = this.resolveFallback();
+				if (this.resolvedConfig === void 0) {
+					this.raw = {};
+					this.resolvedConfig = this.resolveFallback();
+				}
 				return;
 			}
+			this.lastText = text;
 			this.apply(parsed);
 		}
 		notify() {
@@ -2818,10 +3092,7 @@ var init_store = __esmMin((() => {
 			if ((fs.existsSync(configSchemaPath) ? fs.readFileSync(configSchemaPath, "utf8") : null) !== schema) writeFileAtomic(configSchemaPath, schema);
 		}
 		validateServer(entry, label) {
-			const parsed = serverSchema({
-				...this.defaults,
-				...entry
-			});
+			const parsed = serverSchema(mergeDefaults(this.defaults, entry));
 			if (parsed instanceof type.errors) throw new ConfigError(`${label}: ${formatErrors(parsed)}`);
 			return {
 				...parsed,
@@ -2830,7 +3101,9 @@ var init_store = __esmMin((() => {
 		}
 		commit(draft) {
 			const stamped = stampConfig(draft);
-			writeFileAtomic(this.file, `${JSON.stringify(stamped, null, 2)}\n`);
+			const text = `${JSON.stringify(stamped, null, 2)}\n`;
+			writeFileAtomic(this.file, text);
+			this.lastText = text;
 			this.raw = stamped;
 			this.apply(stamped);
 			this.notify();
@@ -2968,14 +3241,19 @@ function createServersRoute(deps) {
 		if (!deps.store.getServer(id)) throw unknownServer(id);
 		return streamSSE(c, async (stream) => {
 			let closed = false;
+			let pending = 0;
 			let queue = Promise.resolve();
 			const send = (data, event) => {
 				if (closed) return;
+				if (event === "log" && pending > MAX_PENDING_WRITES) return;
+				pending += 1;
 				queue = queue.then(() => stream.writeSSE({
 					event,
 					data
 				})).catch(() => {
 					closed = true;
+				}).finally(() => {
+					pending -= 1;
 				});
 			};
 			const unsubscribe = deps.hub.subscribe(id, (message) => {
@@ -3112,7 +3390,7 @@ function createServersRoute(deps) {
 		}
 	});
 }
-var idParam, serverResponse, serversResponse, okResponse;
+var idParam, MAX_PENDING_WRITES, serverResponse, serversResponse, okResponse;
 var init_$_routes = __esmMin((() => {
 	init_store();
 	init_factory();
@@ -3120,6 +3398,7 @@ var init_$_routes = __esmMin((() => {
 	init_validator();
 	init_contracts();
 	idParam = type({ id: "string >= 1" });
+	MAX_PENDING_WRITES = 200;
 	serverResponse = type({ server: serverViewSchema });
 	serversResponse = type({ servers: serverViewSchema.array() });
 	okResponse = type({ ok: "boolean" });
@@ -3132,7 +3411,14 @@ function sanitizeName(name) {
 	return cleaned.length > 0 ? cleaned.slice(0, 60) : "custom-ui";
 }
 function createSettingsRoute(deps) {
-	return appFactory.createApp().get("/settings", (c) => c.json({
+	return appFactory.createApp().get("/settings", describeRoute({
+		tags: ["panel"],
+		summary: "The panel, server defaults, logs, notifications, host and backups",
+		responses: { 200: {
+			description: "The settings",
+			content: jsonBody(settingsViewSchema)
+		} }
+	}), (c) => c.json({
 		control: buildControlView(deps.store, deps.auth, deps.controlServer.endpoint, deps.tls),
 		defaults: deps.store.defaults,
 		logs: deps.store.config.logs,
@@ -3144,7 +3430,10 @@ function createSettingsRoute(deps) {
 		tags: ["panel"],
 		summary: "Edit the panel, server defaults, logs, notifications, host and backups",
 		responses: {
-			200: { description: "Saved; the listener may be moving" },
+			200: {
+				description: "Saved; the listener may be moving",
+				content: jsonBody(settingsSavedSchema)
+			},
 			400: ERROR_RESPONSES[400]
 		}
 	}), validate("json", settingsPatchSchema), async (c) => {
@@ -3736,11 +4025,12 @@ async function isPortFree(port, host = "127.0.0.1", timeoutMs = 1e3) {
 	return !await probePort(host, port, timeoutMs);
 }
 /**
-* Kills whatever holds the port. Only used as a last resort for wrappers that
-* spawn their real server detached, where a process-group signal cannot reach it.
+* Kills whatever holds the port, minus `exclude` (the panel's own process tree).
+* Only used as a last resort for wrappers that spawn their real server detached,
+* where a process-group signal cannot reach it.
 */
-async function killPortHolders(port) {
-	const pids = await listPortHolders(port);
+async function killPortHolders(port, exclude) {
+	const pids = (await listPortHolders(port)).filter((pid) => !exclude?.has(pid));
 	for (const pid of pids) try {
 		process.kill(pid, "SIGKILL");
 	} catch {}
@@ -3760,7 +4050,7 @@ function signalPid$1(pid, name) {
 		process.kill(pid, name);
 	} catch {}
 }
-function delay$3(ms) {
+function delay$2(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
@@ -3775,12 +4065,12 @@ async function terminatePids(pids, options = {}) {
 	const deadline = Date.now() + graceMs;
 	let alive = aliveBefore.filter(isProcessAlive);
 	while (alive.length > 0 && Date.now() < deadline) {
-		await delay$3(100);
+		await delay$2(100);
 		alive = alive.filter(isProcessAlive);
 	}
 	const stopped = aliveBefore.filter((pid) => !alive.includes(pid));
 	for (const pid of alive) signalPid$1(pid, "SIGKILL");
-	if (alive.length > 0 && graceMs > 0) await delay$3(150);
+	if (alive.length > 0 && graceMs > 0) await delay$2(150);
 	return {
 		stopped,
 		forced: alive
@@ -4421,8 +4711,9 @@ var init_proc = __esmMin((() => {
 */
 function resolveCommand(command, ...searchDirs) {
 	if (command.includes("/") || command.includes("\\")) return command;
-	for (const dir of searchDirs) {
-		const local = path.join(dir, "node_modules", ".bin", command);
+	const candidates = process.platform === "win32" && path.extname(command) === "" ? [command, ...WINDOWS_SHIM_EXTENSIONS.map((extension) => `${command}${extension}`)] : [command];
+	for (const dir of searchDirs) for (const candidate of candidates) {
+		const local = path.join(dir, "node_modules", ".bin", candidate);
 		if (fs.existsSync(local)) return local;
 	}
 	return command;
@@ -4431,6 +4722,10 @@ function resolveCommand(command, ...searchDirs) {
 function resolveCwd(cwd, base = projectDir) {
 	return path.resolve(base, cwd);
 }
+/** Node cannot spawn a Windows `.cmd`/`.bat` shim without a shell (EINVAL). */
+function needsShell(command) {
+	return process.platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+}
 function spawnManaged(spec) {
 	return spawn(spec.command, spec.args, {
 		cwd: spec.cwd,
@@ -4444,6 +4739,7 @@ function spawnManaged(spec) {
 			"pipe",
 			"pipe"
 		],
+		shell: needsShell(spec.command),
 		windowsHide: true
 	});
 }
@@ -4509,14 +4805,14 @@ async function terminatePid(pid, options) {
 	if (!alive(pid)) return "exited";
 	signalPid(pid, options.signal, options.killGroup);
 	const deadline = Date.now() + Math.max(0, options.graceMs);
-	while (Date.now() < deadline && alive(pid)) await delay$2(50);
+	while (Date.now() < deadline && alive(pid)) await delay$1(50);
 	if (!alive(pid)) return "exited";
 	signalPid(pid, "SIGKILL", options.killGroup);
 	const hardDeadline = Date.now() + 2e3;
-	while (Date.now() < hardDeadline && alive(pid)) await delay$2(50);
+	while (Date.now() < hardDeadline && alive(pid)) await delay$1(50);
 	return "force-killed";
 }
-function delay$2(ms) {
+function delay$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function waitForExit$1(child, timeoutMs) {
@@ -4534,10 +4830,16 @@ function waitForExit$1(child, timeoutMs) {
 		child.once("exit", onExit);
 	});
 }
-var execFileAsync$1;
+var execFileAsync$1, WINDOWS_SHIM_EXTENSIONS;
 var init_process = __esmMin((() => {
 	init_paths();
 	execFileAsync$1 = promisify(execFile);
+	WINDOWS_SHIM_EXTENSIONS = [
+		".cmd",
+		".exe",
+		".bat",
+		".ps1"
+	];
 }));
 //#endregion
 //#region src/services/dependencies.ts
@@ -4584,8 +4886,9 @@ function dependenciesOf(server, servers) {
 var init_dependencies = __esmMin((() => {}));
 //#endregion
 //#region src/services/log-buffer.ts
-var LogBuffer, LineSplitter;
+var MAX_PENDING_CHARS, LogBuffer, LineSplitter;
 var init_log_buffer = __esmMin((() => {
+	MAX_PENDING_CHARS = 65536;
 	LogBuffer = class {
 		capacity;
 		lines = [];
@@ -4621,17 +4924,21 @@ var init_log_buffer = __esmMin((() => {
 			const parts = this.pending.split("\n");
 			this.pending = parts.pop() ?? "";
 			for (const part of parts) this.emit(stream, part.replace(/\r$/, ""));
+			while (this.pending.length > MAX_PENDING_CHARS) {
+				this.emit(stream, this.pending.slice(0, MAX_PENDING_CHARS));
+				this.pending = this.pending.slice(MAX_PENDING_CHARS);
+			}
 		}
 		flush(stream) {
 			if (this.pending.length === 0) return;
-			this.emit(stream, this.pending);
+			this.emit(stream, this.pending.replace(/\r$/, ""));
 			this.pending = "";
 		}
 	};
 }));
 //#endregion
 //#region src/services/supervisor.ts
-function delay$1(ms) {
+function delay(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /** The placeholder set every server entry can use; shared with path resolvers. */
@@ -4685,7 +4992,9 @@ var init_supervisor = __esmMin((() => {
 			this.options = options;
 			this.sync();
 			this.store.onChange(() => this.sync());
-			this.tickTimer = setInterval(() => void this.tick(), TICK_INTERVAL_MS);
+			this.tickTimer = setInterval(() => {
+				this.tick().catch((error) => logger.error("the supervisor tick failed", error));
+			}, TICK_INTERVAL_MS);
 			this.tickTimer.unref();
 		}
 		getState() {
@@ -4857,7 +5166,7 @@ var init_supervisor = __esmMin((() => {
 				return (await Promise.all(this.occupancyHosts(entry).map((host) => isPortFree(port, host)))).every(Boolean);
 			};
 			if (await freeOnAll()) return true;
-			await delay$1(PORT_RELEASE_RECHECK_MS);
+			await delay(PORT_RELEASE_RECHECK_MS);
 			return freeOnAll();
 		}
 		clearLogs(id) {
@@ -4890,7 +5199,7 @@ var init_supervisor = __esmMin((() => {
 					if (this.statusOf(target) !== "running") return false;
 					return target.health !== "unhealthy";
 				};
-				while (!isReady() && Date.now() < deadline) await delay$1(250);
+				while (!isReady() && Date.now() < deadline) await delay(250);
 				if (!isReady()) {
 					const status = this.statusOf(target);
 					this.log(entry, "system", `dependency "${dependency.id}" is ${status}/${target.health} — starting anyway`);
@@ -4932,6 +5241,7 @@ var init_supervisor = __esmMin((() => {
 			entry.nextRetryAt = null;
 			entry.stopping = true;
 			if (entry.child === null && entry.pid === null) {
+				entry.stopping = false;
 				entry.status = "stopped";
 				this.publishServer(entry);
 				return { ok: true };
@@ -4941,11 +5251,8 @@ var init_supervisor = __esmMin((() => {
 			if ((entry.child === null && entry.pid !== null ? await terminatePid(entry.pid, entry.config.stop) : await terminate(entry.child, entry.config.stop)) === "force-killed") this.log(entry, "system", "force-killed after grace period");
 			const { port, stop } = entry.config;
 			if (stop.killPortHolders && port !== null) {
-				const leftover = await listPortHolders(port);
-				if (leftover.length > 0) {
-					this.log(entry, "system", `port ${port} still held by pid ${leftover.join(", ")} — killing`);
-					await killPortHolders(port);
-				}
+				const leftover = await killPortHolders(port, this.supervisedPids());
+				if (leftover.length > 0) this.log(entry, "system", `port ${port} was still held by pid ${leftover.join(", ")} — killed`);
 			}
 			entry.stopping = false;
 			entry.child = null;
@@ -4993,7 +5300,9 @@ var init_supervisor = __esmMin((() => {
 				const config = wanted.get(id);
 				if (!config) {
 					this.entries.delete(id);
-					this.stopEntry(entry);
+					this.stopEntry(entry).catch((error) => {
+						logger.error(`could not stop the removed server ${id}`, error);
+					});
 					continue;
 				}
 				const bufferChanged = entry.config.logBufferLines !== config.logBufferLines;
@@ -5003,7 +5312,9 @@ var init_supervisor = __esmMin((() => {
 					entry.logs = new LogBuffer(config.logBufferLines);
 					entry.logs.extend(kept);
 				}
-				if (!config.enabled && this.isActive(entry)) this.stopEntry(entry);
+				if (!config.enabled && this.isActive(entry)) this.stopEntry(entry).catch((error) => {
+					logger.error(`could not stop the disabled server ${id}`, error);
+				});
 			}
 			for (const [id, config] of wanted) if (!this.entries.has(id)) this.entries.set(id, this.createEntry(config));
 			this.publishState();
@@ -5051,7 +5362,7 @@ var init_supervisor = __esmMin((() => {
 			};
 			let free = await freeOnAll();
 			if (!free) {
-				await delay$1(PORT_RELEASE_RECHECK_MS);
+				await delay(PORT_RELEASE_RECHECK_MS);
 				free = await freeOnAll();
 			}
 			entry.portState = free ? "free" : "in-use";
@@ -5067,7 +5378,7 @@ var init_supervisor = __esmMin((() => {
 				this.log(entry, "system", `port ${port} is held by pid ${own.join(", ")}, a detached restart of this entry — replacing it with a supervised process`);
 				const { forced } = await terminatePids(own);
 				if (forced.length > 0) this.log(entry, "system", `pid ${forced.join(", ")} ignored SIGTERM and was killed`);
-				await delay$1(PORT_RELEASE_RECHECK_MS);
+				await delay(PORT_RELEASE_RECHECK_MS);
 				if (await freeOnAll()) {
 					entry.portState = "free";
 					return { kind: "free" };
@@ -5289,7 +5600,7 @@ var init_supervisor = __esmMin((() => {
 					this.publishServer(entry);
 					return;
 				}
-				await delay$1(300);
+				await delay(300);
 			}
 			if (entry.child === child && entry.status === "starting") {
 				entry.status = "running";
@@ -5342,7 +5653,9 @@ var init_supervisor = __esmMin((() => {
 				this.log(entry, "system", `restart ${entry.restarts}/${restart.maxRetries} in ${backoffMs}ms`);
 				entry.retryTimer = setTimeout(() => {
 					entry.retryTimer = null;
-					this.start(entry.config.id, { retry: true });
+					this.start(entry.config.id, { retry: true }).catch((error) => {
+						logger.error(`could not restart ${entry.config.id}`, error);
+					});
 				}, backoffMs);
 				entry.retryTimer.unref();
 			} else {
@@ -5375,7 +5688,9 @@ var init_supervisor = __esmMin((() => {
 					await this.restart(entry.config.id);
 					continue;
 				}
-				if (entry.status === "backoff" && entry.nextRetryAt !== null && now >= entry.nextRetryAt && entry.retryTimer === null) this.start(entry.config.id, { retry: true });
+				if (entry.status === "backoff" && entry.nextRetryAt !== null && now >= entry.nextRetryAt && entry.retryTimer === null) this.start(entry.config.id, { retry: true }).catch((error) => {
+					logger.error(`could not restart ${entry.config.id}`, error);
+				});
 			}
 			this.publishState();
 		}
@@ -5549,6 +5864,69 @@ var init_supervisor = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region src/shared/generated.ts
+/**
+* True when a path *relative to the declared root* looks generated. Accepts
+* either separator, so a `path.relative` result can be passed straight in.
+*/
+function isGeneratedPath(relative) {
+	const segments = relative.split(/[\\/]+/).filter((segment) => segment.length > 0 && segment !== ".");
+	if (segments.length === 0) return false;
+	if (FILE_NAME_SET.has(segments[segments.length - 1])) return true;
+	return segments.some((segment) => DIR_NAME_SET.has(segment));
+}
+var GENERATED_DIRS, GENERATED_FILES, DIR_NAME_SET, FILE_NAME_SET;
+var init_generated = __esmMin((() => {
+	GENERATED_DIRS = [
+		"node_modules",
+		"bower_components",
+		"jspm_packages",
+		".yarn",
+		".pnpm",
+		".pnpm-store",
+		".npm",
+		".next",
+		".nuxt",
+		".svelte-kit",
+		".astro",
+		".output",
+		".vercel",
+		".netlify",
+		".angular",
+		"dist",
+		"build",
+		"out",
+		".cache",
+		".parcel-cache",
+		".turbo",
+		".vite",
+		".rollup.cache",
+		".swc",
+		"coverage",
+		".nyc_output",
+		"__pycache__",
+		".pytest_cache",
+		".mypy_cache",
+		".ruff_cache",
+		".tox",
+		"target",
+		".gradle",
+		".dart_tool"
+	];
+	GENERATED_FILES = [
+		".DS_Store",
+		"Thumbs.db",
+		"desktop.ini",
+		".eslintcache",
+		".stylelintcache",
+		"npm-debug.log",
+		"yarn-error.log",
+		"pnpm-debug.log"
+	];
+	DIR_NAME_SET = new Set(GENERATED_DIRS);
+	FILE_NAME_SET = new Set(GENERATED_FILES);
+}));
+//#endregion
 //#region src/services/backups.ts
 /**
 * Structural allowlist for archive entries. A regex alone is not enough: `..`
@@ -5584,21 +5962,23 @@ function resolveBackupPaths(servers, includePaths = []) {
 		dataRoot,
 		home: os.homedir()
 	};
-	const add = (value, origin, vars) => {
+	const add = (value, origin, vars, ignoreGenerated) => {
 		if (value.trim().length === 0) return;
 		const resolved = path.normalize(resolveUserPath(expandEnv(resolveTemplate(value, vars), process.env)));
 		declared.push({
 			path: resolved,
 			origin,
 			depth: path.normalize(resolved).split(path.sep).filter(Boolean).length,
-			order: declared.length
+			order: declared.length,
+			ignoreGenerated
 		});
 	};
-	for (const value of includePaths) add(value, "global", globalVars);
+	for (const value of includePaths) add(value, "global", globalVars, false);
 	for (const config of servers) {
 		const vars = serverTemplateVars(config);
-		for (const [name, value] of Object.entries(config.dataEnvs)) add(value, `${config.id}:${name}`, vars);
-		for (const value of config.backupPaths) add(value, `${config.id}:backupPaths`, vars);
+		const ignoreGenerated = config.backupIgnoreGenerated !== false;
+		for (const [name, value] of Object.entries(config.dataEnvs)) add(value, `${config.id}:${name}`, vars, ignoreGenerated);
+		for (const value of config.backupPaths) add(value, `${config.id}:backupPaths`, vars, ignoreGenerated);
 	}
 	const sorted = [...declared].sort((a, b) => a.depth - b.depth || a.order - b.order);
 	return sorted.map((entry, index) => {
@@ -5607,14 +5987,16 @@ function resolveBackupPaths(servers, includePaths = []) {
 			path: entry.path,
 			origin: entry.origin,
 			included: true,
-			note: null
+			note: null,
+			ignoreGenerated: entry.ignoreGenerated
 		};
 		const note = parent.path === entry.path ? `already declared by ${parent.origin}` : `covered by ${parent.path}`;
 		return {
 			path: entry.path,
 			origin: entry.origin,
 			included: false,
-			note
+			note,
+			ignoreGenerated: entry.ignoreGenerated
 		};
 	});
 }
@@ -5684,6 +6066,7 @@ var init_backups = __esmMin((() => {
 	init_template();
 	init_archive();
 	init_supervisor();
+	init_generated();
 	MANIFEST = "manifest.json";
 	ALLOWED_ROOTS = /* @__PURE__ */ new Set([
 		"config",
@@ -5770,7 +6153,7 @@ var init_backups = __esmMin((() => {
 					if (!declared.included || !fs.existsSync(declared.path)) continue;
 					const slug = slugifyPath(declared.path);
 					if (data.some((entry) => entry.slug === slug)) continue;
-					this.copyInto(staging, path.join("data", slug), declared.path);
+					this.copyInto(staging, path.join("data", slug), declared.path, declared.ignoreGenerated === true);
 					data.push({
 						slug,
 						path: declared.path,
@@ -6080,15 +6463,21 @@ var init_backups = __esmMin((() => {
 			const present = new Set(listed.map((file) => file.name));
 			for (const name of [...this.flags.keys()]) if (!present.has(name)) this.flags.delete(name);
 		}
-		copyInto(staging, relative, source) {
+		copyInto(staging, relative, source, ignoreGenerated = false) {
 			if (!fs.existsSync(source)) return;
 			const target = path.join(staging, relative);
 			fs.mkdirSync(path.dirname(target), { recursive: true });
 			const archiveDir = path.resolve(this.resolveDir());
+			const root = path.resolve(source);
 			fs.cpSync(source, target, {
 				recursive: true,
 				force: true,
-				filter: (from) => !isInside(archiveDir, path.resolve(from))
+				filter: (from) => {
+					const resolved = path.resolve(from);
+					if (isInside(archiveDir, resolved)) return false;
+					if (!ignoreGenerated || resolved === root) return true;
+					return !isGeneratedPath(path.relative(root, resolved));
+				}
 			});
 		}
 		prune() {
@@ -6102,6 +6491,76 @@ var init_backups = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region src/services/config-watch.ts
+var DEFAULT_DEBOUNCE_MS, DEFAULT_POLL_MS, ConfigWatch;
+var init_config_watch = __esmMin((() => {
+	DEFAULT_DEBOUNCE_MS = 150;
+	DEFAULT_POLL_MS = 2e3;
+	ConfigWatch = class {
+		options;
+		debounceMs;
+		pollMs;
+		watcher = null;
+		debounceTimer = null;
+		pollTimer = null;
+		disposed = false;
+		constructor(options) {
+			this.options = options;
+			this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+			this.pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+		}
+		start() {
+			if (this.disposed || this.watcher !== null) return;
+			try {
+				this.watcher = fs.watch(path.dirname(this.options.file), (_event, filename) => {
+					if (filename !== null && filename !== path.basename(this.options.file)) return;
+					this.schedule();
+				});
+				this.watcher.on("error", (error) => {
+					this.options.onError?.(error);
+					this.closeWatcher();
+				});
+				this.watcher.unref();
+			} catch (error) {
+				this.options.onError?.(error);
+			}
+			if (this.pollMs > 0) {
+				this.pollTimer = setInterval(() => this.check(), this.pollMs);
+				this.pollTimer.unref();
+			}
+		}
+		/** One check, exactly what the poll does — tests drive this instead of waiting. */
+		check() {
+			this.schedule();
+		}
+		dispose() {
+			this.disposed = true;
+			if (this.debounceTimer !== null) {
+				clearTimeout(this.debounceTimer);
+				this.debounceTimer = null;
+			}
+			if (this.pollTimer !== null) {
+				clearInterval(this.pollTimer);
+				this.pollTimer = null;
+			}
+			this.closeWatcher();
+		}
+		/** One reload per burst: an editor writing in pieces is still one edit. */
+		schedule() {
+			if (this.disposed || this.debounceTimer !== null) return;
+			this.debounceTimer = setTimeout(() => {
+				this.debounceTimer = null;
+				if (!this.disposed) this.options.onChange();
+			}, this.debounceMs);
+			this.debounceTimer.unref();
+		}
+		closeWatcher() {
+			this.watcher?.close();
+			this.watcher = null;
+		}
+	};
+}));
+//#endregion
 //#region src/services/control-server.ts
 var ControlServer;
 var init_control_server = __esmMin((() => {
@@ -6804,7 +7263,7 @@ var init_notifications = __esmMin((() => {
 				ok: false,
 				error: "no bot token configured"
 			};
-			const result = await sendTelegramMessage(token, chatId, formatTelegramMessage("✅ home-hosted-2 test", ["notifications are wired up correctly"]));
+			const result = await sendTelegramMessage(token, chatId, formatTelegramMessage("✅ home-hosted test", ["notifications are wired up correctly"]));
 			this.remember(result.ok ? "test message sent" : result.error ?? "test failed");
 			return result;
 		}
@@ -7341,12 +7800,50 @@ async function runControlPlane(options) {
 		notifications,
 		hostMonitor
 	});
+	/**
+	* A config edited by hand — a text editor, a `git checkout`, a config-management
+	* tool — is picked up without a restart. A revision this release cannot read is
+	* reported in the state frame and the panel keeps running what it had, so a typo
+	* never stops a server. A definition that *did* change takes effect on that
+	* entry's next start; a newly added entry with `autostart` starts now, the way it
+	* would after a restart, and a removed one is stopped and forgotten.
+	*/
+	let lastConfigError = store.configError;
+	const configWatch = new ConfigWatch({
+		file: store.path,
+		onChange: () => {
+			const before = new Set(store.servers.map((server) => server.id));
+			const result = store.reloadFromDisk();
+			if (store.configError !== lastConfigError) {
+				if (store.configError === null) logger.info("the config file is readable again");
+				else logger.error(`${store.configError} — keeping the config already running`);
+				lastConfigError = store.configError;
+			}
+			if (!result.applied) {
+				if (result.changed && result.error === null) logger.info("the config file changed, but not in a way that changes the config");
+				return;
+			}
+			const added = store.servers.filter((server) => !before.has(server.id));
+			const removed = [...before].filter((id) => !store.getServer(id));
+			logger.info(`config reloaded from disk — ${store.servers.length} server(s)${added.length === 0 ? "" : `, ${added.length} added`}${removed.length === 0 ? "" : `, ${removed.length} removed`}`);
+			if (!options.autostart) return;
+			for (const server of added) {
+				if (!server.enabled || !server.autostart) continue;
+				supervisor.start(server.id).catch((error) => {
+					logger.error(`could not start the added server ${server.id}`, error);
+				});
+			}
+		},
+		onError: (error) => logger.warn(`cannot watch ${path.basename(store.path)} for changes: ${error instanceof Error ? error.message : String(error)}`)
+	});
+	configWatch.start();
 	let shuttingDown = false;
 	const shutdown = async (reason) => {
 		if (shuttingDown) return;
 		shuttingDown = true;
 		logger.info(`${reason} — stopping ${supervisor.views().length} server(s)`);
 		clearRuntime();
+		configWatch.dispose();
 		auth.dispose();
 		await supervisor.dispose();
 		logFiles.dispose();
@@ -7417,8 +7914,14 @@ async function runControlPlane(options) {
 			logger.error("could not start the restored servers", error);
 		});
 	};
-	process.on("SIGINT", () => void shutdown("SIGINT"));
-	process.on("SIGTERM", () => void shutdown("SIGTERM"));
+	const onSignal = (signal) => {
+		shutdown(signal).catch((error) => {
+			logger.error(`shutdown after ${signal} failed`, error);
+			process.exit(1);
+		});
+	};
+	process.on("SIGINT", () => onSignal("SIGINT"));
+	process.on("SIGTERM", () => onSignal("SIGTERM"));
 }
 var packageRoot;
 var init_src = __esmMin((() => {
@@ -7435,6 +7938,7 @@ var init_src = __esmMin((() => {
 	init_port();
 	init_auth$1();
 	init_backups();
+	init_config_watch();
 	init_control_server();
 	init_events();
 	init_exposure();
@@ -7450,257 +7954,30 @@ var init_src = __esmMin((() => {
 	packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 }));
 //#endregion
-//#region src/services/init.ts
-var init_exports = /* @__PURE__ */ __exportAll({
-	PACKAGE_MANAGERS: () => PACKAGE_MANAGERS,
-	detectPackageManager: () => detectPackageManager,
-	installArgs: () => installArgs,
-	isEmptyDir: () => isEmptyDir,
-	projectGitignore: () => projectGitignore,
-	projectManifest: () => projectManifest,
-	projectScripts: () => projectScripts,
-	runCommand: () => runCommand,
-	scaffold: () => scaffold
+//#region src/cli/up.ts
+var up_exports = /* @__PURE__ */ __exportAll({
+	runUp: () => runUp,
+	toUpFlags: () => toUpFlags,
+	upArgs: () => upArgs,
+	upCommand: () => upCommand
 });
-/** The scripts every scaffolded project gets; all of them keep state inside the project. */
-function projectScripts() {
-	const withState = (args) => `home-hosted ${args} --home ./state`;
+/** citty only parses; the port's range and the boolean defaults are decided here. */
+function toUpFlags(args) {
+	let port;
+	if (args.port !== void 0) {
+		port = Number.parseInt(args.port, 10);
+		if (!Number.isInteger(port) || port <= 0 || port > 65535) fail(`invalid port: ${args.port}`);
+	}
 	return {
-		"up": withState("up"),
-		"down": withState("down"),
-		"restart": withState("restart"),
-		"status": withState("status"),
-		"set-password": withState("set-password"),
-		"set-token": withState("set-token"),
-		"migrate": withState("migrate")
+		config: args.config,
+		port,
+		host: args.host,
+		autostart: args.autostart !== false,
+		open: args.open === true,
+		foreground: args.foreground === true,
+		printConfig: args.printConfig === true
 	};
 }
-/** `home-hosted` is pinned to the version that wrote the project, and open to newer ones. */
-function projectManifest(name) {
-	return `${JSON.stringify({
-		name,
-		version: "0.1.0",
-		private: true,
-		description: "Servers supervised by home-hosted.",
-		type: "module",
-		engines: { node: ">=24.0.0" },
-		scripts: projectScripts(),
-		dependencies: { "home-hosted": `^${appVersion()}` }
-	}, null, 2)}\n`;
-}
-/**
-* State is generated, so it stays out — except the file that declares the servers,
-* which is the one thing worth committing.
-*/
-function projectGitignore() {
-	return `node_modules/
-
-# home-hosted: state is local, the server definitions are tracked
-state/*
-!state/servers.config.json
-data/
-`;
-}
-function isEmptyDir(dir) {
-	try {
-		return fs.readdirSync(dir).every((entry) => entry === ".git");
-	} catch {
-		return true;
-	}
-}
-function assertUsableDir(dir) {
-	let stats = null;
-	try {
-		stats = fs.statSync(dir);
-	} catch {
-		return;
-	}
-	if (!stats.isDirectory()) throw new Error(`${dir} exists and is not a directory`);
-	if (!isEmptyDir(dir)) throw new Error(`${dir} is not empty — pick another directory, or empty it first`);
-}
-/** Writes the project skeleton. Nothing is installed or initialized here. */
-function scaffold(options) {
-	const dir = path.resolve(options.dir);
-	assertUsableDir(dir);
-	const existed = fs.existsSync(dir);
-	fs.mkdirSync(dir, { recursive: true });
-	const files = [["package.json", projectManifest(options.name)], [".gitignore", projectGitignore()]];
-	for (const [name, contents] of files) fs.writeFileSync(path.join(dir, name), contents);
-	return {
-		dir,
-		created: !existed,
-		files: files.map(([name]) => name),
-		installed: false,
-		git: false
-	};
-}
-/** The package manager this machine actually has, preferring pnpm. */
-function detectPackageManager(exists) {
-	return PACKAGE_MANAGERS.find((pm) => exists(pm)) ?? "npm";
-}
-/** How to run one of the project's scripts with a given package manager. */
-function runCommand(pm, script) {
-	return pm === "npm" ? `npm run ${script}` : `${pm} run ${script}`;
-}
-/** Install arguments for a scaffolded project (the manifest already lists the dependency). */
-function installArgs(pm) {
-	return pm === "yarn" ? [] : ["install"];
-}
-var PACKAGE_MANAGERS;
-var init_init = __esmMin((() => {
-	init_version();
-	PACKAGE_MANAGERS = [
-		"pnpm",
-		"npm",
-		"yarn",
-		"bun"
-	];
-}));
-//#endregion
-//#region src/cli.ts
-/**
-* The command line. Everything here works before the state directories are known
-* (so `--home`/`--project` can point them somewhere), which is why the modules
-* that read those paths are imported dynamically instead of at the top.
-*/
-var CLI_ENTRY = fileURLToPath(import.meta.url);
-var DEFAULT_PORT = 3999;
-var LOG_ROTATE_BYTES = 5242880;
-var USAGE = `home-hosted — a control panel for the processes on your home server
-
-Usage
-  home-hosted up [options]      start it in the background (detached)
-  home-hosted down              stop it, and everything it supervises
-  home-hosted restart [options] down, then up
-  home-hosted status [--json]   is it running, where, and how to reach it
-  home-hosted set-password      set the panel password without the API
-  home-hosted set-token         set the API token that scripts and agents use
-  home-hosted migrate           bring the config up to this release's schema
-  home-hosted init              scaffold a project that keeps its state in the repo
-  home-hosted ui-revert         go back to the stock control panel UI
-
-Options for up/restart
-  -c, --config <file>   servers config (default: <state>/servers.config.json)
-  -p, --port <port>     control panel port (default: ${DEFAULT_PORT})
-      --host <bind>     local | lan | an ipv4 address (default: local)
-      --open            open the panel in a browser once it is up
-      --no-autostart    do not start the entries marked autostart
-      --foreground      run in this process instead of detaching (systemd/docker)
-      --print-config    print the effective config and exit
-
-Options for set-token
-      --generate        create a strong token and print it once
-      --clear           remove the token, so it stops working
-
-Options for migrate
-      --dry-run         print what would change, write nothing
-  -y, --yes             apply without asking (or set HHOSTED_MIGRATE=allow)
-
-Options for init
-      --dir <dir>       where to scaffold (default: ./my-servers)
-      --name <name>     package name (default: the directory name)
-      --pm <manager>    pnpm | npm | yarn | bun (default: the first one installed)
-      --no-install      write the files, install nothing
-  -y, --yes             take every default, ask nothing
-
-Everywhere
-      --home <dir>      state directory (default: $HHOSTED_HOME or ~/.home-hosted)
-      --project <dir>   base for relative entry paths (default: the current directory)
-  -h, --help            this text
-  -v, --version         the version
-
-Environment
-  HHOSTED_HOME          where config, secrets, logs, TLS and backups live
-  HHOSTED_PROJECT       base for relative entry paths
-  HHOSTED_PASSWORD      the password for a non-interactive set-password
-  HHOSTED_TOKEN         the token for a non-interactive set-token
-`;
-var isTty = () => process.stdout.isTTY === true;
-var paint = (code, text) => isTty() ? `\x1B[${code}m${text}\x1B[0m` : text;
-var dim = (text) => paint("2", text);
-var bold = (text) => paint("1", text);
-var green = (text) => paint("32", text);
-function fail(message) {
-	process.stderr.write(`${paint("31", "error")} ${message}\n`);
-	process.exit(1);
-}
-function delay(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/** `--home`/`--project` are handled for every command, so they are peeled off first. */
-function extractDirFlags(argv) {
-	const rest = [];
-	let project;
-	let home;
-	for (let index = 0; index < argv.length; index++) {
-		const arg = argv[index];
-		const equals = arg.indexOf("=");
-		const name = equals === -1 ? arg : arg.slice(0, equals);
-		if (name !== "--project" && name !== "--home") {
-			rest.push(arg);
-			continue;
-		}
-		const value = equals === -1 ? argv[++index] : arg.slice(equals + 1);
-		if (value === void 0 || value.length === 0) fail(`${name} needs a directory`);
-		if (name === "--project") project = value;
-		else home = value;
-	}
-	return {
-		rest,
-		project,
-		home
-	};
-}
-/** Set before any state module is imported, so it decides where state lives. */
-function applyDirFlags(flags) {
-	if (flags.project !== void 0) process.env.HHOSTED_PROJECT = path.resolve(flags.project);
-	if (flags.home !== void 0) process.env.HHOSTED_HOME = path.resolve(flags.home);
-}
-function parseUpFlags(argv) {
-	const { values } = parseArgs({
-		args: argv,
-		options: {
-			"config": {
-				type: "string",
-				short: "c"
-			},
-			"port": {
-				type: "string",
-				short: "p"
-			},
-			"host": { type: "string" },
-			"no-autostart": { type: "boolean" },
-			"open": { type: "boolean" },
-			"foreground": { type: "boolean" },
-			"print-config": { type: "boolean" }
-		},
-		allowPositionals: false
-	});
-	let port;
-	if (values.port !== void 0) {
-		port = Number.parseInt(values.port, 10);
-		if (!Number.isInteger(port) || port <= 0 || port > 65535) fail(`invalid port: ${values.port}`);
-	}
-	return {
-		config: values.config,
-		port,
-		host: values.host,
-		autostart: values["no-autostart"] !== true,
-		open: values.open === true,
-		foreground: values.foreground === true,
-		printConfig: values["print-config"] === true
-	};
-}
-/** The daemon gets the same instructions, but never `--foreground`. */
-function daemonFlags(flags) {
-	const args = [];
-	if (flags.config !== void 0) args.push("--config", flags.config);
-	if (flags.port !== void 0) args.push("--port", String(flags.port));
-	if (flags.host !== void 0) args.push("--host", flags.host);
-	if (!flags.autostart) args.push("--no-autostart");
-	if (flags.open) args.push("--open");
-	return args;
-}
 /**
 * How to run this CLI again in the same runtime. Under tsx that means passing the
 * resolved loader too, because the daemon's working directory is the project's,
@@ -7730,10 +8007,9 @@ function tailLog(file, lines = 15) {
 		return "";
 	}
 }
-async function up(argv) {
-	const flags = parseUpFlags(argv);
+async function runUp(flags, entry) {
 	const { runControlPlane } = await Promise.resolve().then(() => (init_src(), src_exports));
-	if (flags.foreground) {
+	if (flags.foreground || flags.printConfig) {
 		await runControlPlane({
 			configPath: flags.config,
 			port: flags.port,
@@ -7758,10 +8034,8 @@ async function up(argv) {
 	const log = fs.openSync(daemonLogPath, "a");
 	const child = spawn(process.execPath, [
 		...runtimeArgs(),
-		CLI_ENTRY,
-		"up",
-		"--foreground",
-		...daemonFlags(flags)
+		entry,
+		...buildDaemonArgv(flags)
 	], {
 		detached: true,
 		cwd: projectDir,
@@ -7800,10 +8074,69 @@ async function waitForStartup(child, timeoutMs = 2e4) {
 		const runtime = readRuntime();
 		if (runtime !== null && runtime.pid === child.pid) return runtime;
 		if (Date.now() > deadline) return null;
-		await delay(150);
+		await delay$3(150);
 	}
 }
-async function down() {
+function upCommand(entry) {
+	return defineCommand({
+		meta: {
+			name: "up",
+			description: "start the panel in the background (detached)"
+		},
+		args: upArgs,
+		run: async ({ args }) => {
+			await runUp(toUpFlags(args), entry);
+		}
+	});
+}
+var DEFAULT_PORT$1, LOG_ROTATE_BYTES, upArgs;
+var init_up = __esmMin((() => {
+	init_args();
+	init_io();
+	DEFAULT_PORT$1 = 3999;
+	LOG_ROTATE_BYTES = 5242880;
+	upArgs = {
+		config: {
+			type: "string",
+			alias: "c",
+			description: "servers config (default: <state>/servers.config.json)"
+		},
+		port: {
+			type: "string",
+			alias: "p",
+			description: `control panel port (default: ${DEFAULT_PORT$1})`
+		},
+		host: {
+			type: "string",
+			description: "local | lan | an ipv4 address (default: local)"
+		},
+		autostart: {
+			type: "boolean",
+			default: true,
+			negativeDescription: "do not start the entries marked autostart"
+		},
+		open: {
+			type: "boolean",
+			description: "open the panel in a browser once it is up"
+		},
+		foreground: {
+			type: "boolean",
+			description: "run in this process instead of detaching (systemd/docker)"
+		},
+		printConfig: {
+			type: "boolean",
+			description: "print the effective config and exit"
+		}
+	};
+}));
+//#endregion
+//#region src/cli/down.ts
+var down_exports = /* @__PURE__ */ __exportAll({
+	downCommand: () => downCommand,
+	runDown: () => runDown
+});
+/** `down` stops the panel and everything it supervises. */
+async function runDown() {
 	const { clearRuntime, isProcessAlive, readRuntime, requestShutdown } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
 	const runtime = readRuntime();
 	if (runtime === null) {
@@ -7833,7 +8166,7 @@ async function waitForExit(pid, timeoutMs) {
 	const deadline = Date.now() + timeoutMs;
 	while (Date.now() < deadline) {
 		if (!isProcessAlive(pid)) return true;
-		await delay(200);
+		await delay$3(200);
 	}
 	return !isProcessAlive(pid);
 }
@@ -7855,22 +8188,54 @@ function forceStop(pid) {
 	}
 	signal(pid, "SIGKILL");
 }
-async function restart(argv) {
-	await down();
-	await up(argv);
-}
-async function status(argv) {
-	const { values } = parseArgs({
-		args: argv,
-		options: { json: { type: "boolean" } },
-		allowPositionals: false
+var downCommand;
+var init_down = __esmMin((() => {
+	init_io();
+	downCommand = defineCommand({
+		meta: {
+			name: "down",
+			description: "stop it, and everything it supervises"
+		},
+		run: async () => {
+			await runDown();
+		}
 	});
+}));
+//#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. */
+function restartCommand(entry) {
+	return defineCommand({
+		meta: {
+			name: "restart",
+			description: "down, then up"
+		},
+		args: upArgs,
+		run: async ({ args }) => {
+			await runDown();
+			await runUp(toUpFlags(args), entry);
+		}
+	});
+}
+var init_restart = __esmMin((() => {
+	init_down();
+	init_up();
+}));
+//#endregion
+//#region src/cli/status.ts
+var status_exports = /* @__PURE__ */ __exportAll({
+	runStatus: () => runStatus,
+	statusArgs: () => statusArgs,
+	statusCommand: () => statusCommand
+});
+async function runStatus(json) {
 	const { isProcessAlive, probeRuntime, readRuntime } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
 	const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
 	const { dataRoot } = await Promise.resolve().then(() => (init_paths(), paths_exports));
 	const runtime = readRuntime();
 	if (runtime === null) {
-		if (values.json) process.stdout.write(`${JSON.stringify({ running: false }, null, 2)}\n`);
+		if (json) process.stdout.write(`${JSON.stringify({ running: false }, null, 2)}\n`);
 		else process.stdout.write("home-hosted is not running\n");
 		process.exitCode = 1;
 		return;
@@ -7880,7 +8245,7 @@ async function status(argv) {
 		reachable: false,
 		degraded: false
 	};
-	if (values.json) {
+	if (json) {
 		const { token: _token, ...safe } = runtime;
 		process.stdout.write(`${JSON.stringify({
 			running,
@@ -7918,71 +8283,163 @@ function formatDuration(ms) {
 	if (hours < 24) return `${hours}h ${minutes % 60}m`;
 	return `${Math.floor(hours / 24)}d ${hours % 24}h`;
 }
-/** A plain y/N question, for decisions that are not secrets. */
-function prompt(question) {
-	return new Promise((resolve) => {
-		const rl = readline.createInterface({
-			input: process.stdin,
-			output: process.stdout
-		});
-		rl.question(question, (answer) => {
-			rl.close();
-			resolve(answer);
-		});
+var statusArgs, statusCommand;
+var init_status = __esmMin((() => {
+	init_io();
+	statusArgs = { json: {
+		type: "boolean",
+		description: "print machine-readable JSON"
+	} };
+	statusCommand = defineCommand({
+		meta: {
+			name: "status",
+			description: "is it running, where, and how to reach it"
+		},
+		args: statusArgs,
+		run: async ({ args }) => {
+			await runStatus(args.json === true);
+		}
 	});
+}));
+//#endregion
+//#region src/cli/set-password.ts
+var set_password_exports = /* @__PURE__ */ __exportAll({
+	runSetPassword: () => runSetPassword,
+	setPasswordArgs: () => setPasswordArgs,
+	setPasswordCommand: () => setPasswordCommand
+});
+async function runSetPassword(clear) {
+	const store = new SecretsStore(defaultSecretsPath);
+	if (clear) {
+		store.clearPassword();
+		process.stdout.write(`cleared the control panel password in ${defaultSecretsPath}\n`);
+		process.stdout.write(`${dim("authentication stays disabled until you enable it again in the settings page")}\n`);
+		return;
+	}
+	const interactive = process.stdin.isTTY === true;
+	let password = process.env.HHOSTED_PASSWORD;
+	if (password === void 0 && interactive) {
+		password = await promptHidden("New control panel password: ");
+		const again = await promptHidden("Repeat it: ");
+		if (password !== again) fail("the passwords do not match");
+	}
+	if (password === void 0 || password.length === 0) fail("no password given: run interactively, or set HHOSTED_PASSWORD for a non-interactive run");
+	store.setPassword(password);
+	process.stdout.write(`${green("password stored")} in ${defaultSecretsPath} (mode 0600)\n`);
+	if (password.length < 8) process.stdout.write(`${dim(`"${password}" is short — easy to guess if the panel is reachable beyond loopback`)}\n`);
+	process.stdout.write(`${dim("restart the panel for it to take effect: home-hosted restart")}\n`);
 }
-/** Reads a line with echo suppressed, so the password never lands in scrollback. */
-function promptHidden(question) {
-	return new Promise((resolve) => {
-		const rl = readline.createInterface({
-			input: process.stdin,
-			output: process.stdout,
-			terminal: true
-		});
-		const onData = () => {
-			readline.clearLine(process.stdout, 0);
-			readline.cursorTo(process.stdout, 0);
-			process.stdout.write(question);
-		};
-		process.stdin.on("data", onData);
-		rl.question(question, (answer) => {
-			process.stdin.off("data", onData);
-			rl.close();
-			process.stdout.write("\n");
-			resolve(answer);
-		});
+var setPasswordArgs, setPasswordCommand;
+var init_set_password = __esmMin((() => {
+	init_io();
+	init_secrets();
+	init_paths();
+	setPasswordArgs = { clear: {
+		type: "boolean",
+		description: "remove the password, which disables authentication"
+	} };
+	setPasswordCommand = defineCommand({
+		meta: {
+			name: "set-password",
+			description: "set the panel password without the API"
+		},
+		args: setPasswordArgs,
+		run: async ({ args }) => {
+			await runSetPassword(args.clear === true);
+		}
 	});
+}));
+//#endregion
+//#region src/cli/set-token.ts
+var set_token_exports = /* @__PURE__ */ __exportAll({
+	runSetToken: () => runSetToken,
+	setTokenArgs: () => setTokenArgs,
+	setTokenCommand: () => setTokenCommand
+});
+async function runSetToken(generate, clear) {
+	if (generate && clear) fail("use either --generate or --clear, not both");
+	const store = new SecretsStore(defaultSecretsPath);
+	if (clear) {
+		if (!store.apiTokenSet) {
+			process.stdout.write("no API token is set — nothing to clear\n");
+			return;
+		}
+		store.clearApiToken();
+		process.stdout.write(`${green("API token cleared")} in ${defaultSecretsPath} — it stops working immediately\n`);
+		return;
+	}
+	let token = process.env.HHOSTED_TOKEN ?? null;
+	if (generate) token = generateApiToken();
+	else if (token === null && process.stdin.isTTY === true) token = await promptHidden("API token: ");
+	if (token !== null) token = token.trim();
+	if (token === null || token.length === 0) fail("no token given: run `home-hosted set-token --generate`, set HHOSTED_TOKEN, or paste one interactively");
+	store.setApiToken(token);
+	process.stdout.write(`${green(generate ? "token generated" : "token stored")} in ${defaultSecretsPath} (mode 0600)\n`);
+	if (generate) {
+		process.stdout.write(`  ${bold(token)}\n`);
+		process.stdout.write(`${dim("  shown once — only its SHA-256 is kept on disk, so copy it now")}\n`);
+	} else process.stdout.write(`${dim(`  stored as ${token.slice(0, 8)}… — the file keeps only its hash`)}\n`);
+	const { readRuntime } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
+	const runtime = readRuntime();
+	const base = (runtime?.url ?? `http://127.0.0.1:${DEFAULT_PORT}`).replace(/\/+$/, "");
+	if (runtime !== null) {
+		const verified = await verifyToken(base, token);
+		if (verified === true) process.stdout.write(`${dim(`verified: ${base}/api/auth/session accepted it`)}\n`);
+		else if (verified === false) process.stdout.write(`${dim(`the panel at ${base} did not accept it — is it running with this state directory?`)}\n`);
+	}
+	process.stdout.write(`Use it from a script or an agent:\n`);
+	process.stdout.write(`  ${bold(`curl -H "Authorization: Bearer ${generate ? token : "<token>"}" ${base}/api/state`)}\n`);
+	process.stdout.write(`${dim("It needs no restart, outlives sessions, and holds the same access as a signed-in browser.")}\n`);
+	process.stdout.write(`${dim("Remove it any time with: home-hosted set-token --clear")}\n`);
+	if (store.usingDefaultPassword) process.stdout.write(`${dim("The panel password is still the default — change it before the panel is reachable beyond loopback.")}\n`);
 }
-/**
-* Brings `servers.config.json` up to the schema this release understands.
-*
-* Deliberately loud and deliberate: it prints every step first, backs the file up
-* before writing, refuses to write a config it cannot read, and never runs on its
-* own — a detached daemon cannot prompt, so consent comes from `--yes`, from
-* `HHOSTED_MIGRATE=allow`, or from a person at a terminal.
-*/
-async function migrateConfig(argv) {
-	const { values } = parseArgs({
-		args: argv,
-		options: {
-			"config": {
-				type: "string",
-				short: "c"
-			},
-			"dry-run": { type: "boolean" },
-			"yes": {
-				type: "boolean",
-				short: "y"
-			}
+/** Asks the live panel whether it accepts the token, without failing when it cannot. */
+async function verifyToken(base, token) {
+	if (!base.startsWith("http://")) return null;
+	try {
+		const response = await fetch(`${base}/api/auth/session`, { headers: { authorization: `Bearer ${token}` } });
+		if (!response.ok) return false;
+		return (await response.json()).authenticated === true;
+	} catch {
+		return null;
+	}
+}
+var DEFAULT_PORT, setTokenArgs, setTokenCommand;
+var init_set_token = __esmMin((() => {
+	init_io();
+	init_secrets();
+	init_paths();
+	DEFAULT_PORT = 3999;
+	setTokenArgs = {
+		generate: {
+			type: "boolean",
+			description: "create a strong token and print it once"
 		},
-		allowPositionals: false
+		clear: {
+			type: "boolean",
+			description: "remove the token, so it stops working"
+		}
+	};
+	setTokenCommand = defineCommand({
+		meta: {
+			name: "set-token",
+			description: "set the API token that scripts and agents use"
+		},
+		args: setTokenArgs,
+		run: async ({ args }) => {
+			await runSetToken(args.generate === true, args.clear === true);
+		}
 	});
-	const { defaultConfigPath } = await Promise.resolve().then(() => (init_paths(), paths_exports));
-	const { applyConfigMigrations, CONFIG_SCHEMA, planConfigMigrations } = await Promise.resolve().then(() => (init_migrations(), migrations_exports));
-	const { parseConfig, stampConfig } = await Promise.resolve().then(() => (init_parse(), parse_exports));
-	const { writeFileAtomic } = await Promise.resolve().then(() => (init_atomic(), atomic_exports));
-	const { appVersion } = await Promise.resolve().then(() => (init_version(), version_exports));
-	const file = values.config ?? defaultConfigPath;
+}));
+//#endregion
+//#region src/cli/migrate.ts
+var migrate_exports = /* @__PURE__ */ __exportAll({
+	migrateArgs: () => migrateArgs,
+	migrateCommand: () => migrateCommand,
+	runMigrate: () => runMigrate
+});
+async function runMigrate(config, dryRun, yes) {
+	const file = config ?? defaultConfigPath;
 	if (!fs.existsSync(file)) fail(`no config at ${file} — nothing to migrate`);
 	let raw;
 	try {
@@ -7991,12 +8448,12 @@ async function migrateConfig(argv) {
 		fail(`cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
 	}
 	const meta = typeof raw.meta === "object" && raw.meta !== null ? raw.meta : {};
-	const from = typeof meta.schema === "number" ? meta.schema : CONFIG_SCHEMA;
+	const from = typeof meta.schema === "number" ? meta.schema : 1;
 	const plan = planConfigMigrations(from);
 	if (plan.tooNew) fail(`${file} was written by home-hosted ${meta.writtenBy ?? "a newer release"} (config schema ${from});\n  this release understands schema ${plan.to}. Install that version, or edit the file yourself.`);
 	const stamped = stampConfig(raw);
 	const upToDate = plan.steps.length === 0;
-	if (upToDate && values["dry-run"] !== true && JSON.stringify(stamped) !== JSON.stringify(raw)) {
+	if (upToDate && !dryRun && JSON.stringify(stamped) !== JSON.stringify(raw)) {
 		writeFileAtomic(file, `${JSON.stringify(stamped, null, 2)}\n`);
 		process.stdout.write(`${green("config stamped")} in ${file} — written by home-hosted ${appVersion()}, schema ${plan.to}\n`);
 		return;
@@ -8007,11 +8464,11 @@ async function migrateConfig(argv) {
 	}
 	process.stdout.write(`migrating ${file}: config schema ${from} → ${plan.to}\n`);
 	for (const [index, step] of plan.steps.entries()) process.stdout.write(`  ${index + 1}. ${step.describe}\n`);
-	if (values["dry-run"] === true) {
+	if (dryRun) {
 		process.stdout.write(`${dim(`nothing was written (--dry-run, ${plan.steps.length} step(s) pending)`)}\n`);
 		return;
 	}
-	if (!(values.yes === true || (process.env.HHOSTED_MIGRATE ?? "").toLowerCase() === "allow")) {
+	if (!(yes || (process.env.HHOSTED_MIGRATE ?? "").toLowerCase() === "allow")) {
 		if (process.stdin.isTTY !== true) fail(`this config needs ${plan.steps.length} migration(s) and this session cannot ask.\n  re-run with --yes, or set HHOSTED_MIGRATE=allow for unattended runs`);
 		const answer = await prompt(`Apply ${plan.steps.length} migration(s) to ${path.basename(file)}? [y/N] `);
 		if (!/^yes$|^y$/i.test(answer.trim())) {
@@ -8019,60 +8476,172 @@ async function migrateConfig(argv) {
 			return;
 		}
 	}
-	const { config, applied } = applyConfigMigrations(raw, from);
-	const parsed = parseConfig(config);
+	const { config: migrated, applied } = applyConfigMigrations(raw, from);
+	const parsed = parseConfig(migrated);
 	if (parsed.config === null) fail(`the migration produced a config this release cannot read:\n  ${parsed.errors.join("\n  ")}`);
 	const backup = `${file}.bak`;
 	fs.copyFileSync(file, backup);
-	writeFileAtomic(file, `${JSON.stringify(stampConfig(config), null, 2)}\n`);
+	writeFileAtomic(file, `${JSON.stringify(stampConfig(migrated), null, 2)}\n`);
 	process.stdout.write(`${green(`migrated to schema ${plan.to}`)} (${applied.length} step(s)) in ${file}\n`);
 	process.stdout.write(`  ${dim(`previous file kept at ${backup}`)}\n`);
 	for (const key of parsed.unknownKeys) process.stdout.write(`  ${dim(`still ignoring an unrecognized key: ${key}`)}\n`);
 }
-/** Asks a yes/no question with a default, so an empty answer is a real answer. */
-async function confirm(question, fallback) {
-	const answer = (await prompt(`${question} ${fallback ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
-	if (answer.length === 0) return fallback;
-	return answer === "y" || answer === "yes";
+var migrateArgs, migrateCommand;
+var init_migrate = __esmMin((() => {
+	init_io();
+	init_migrations();
+	init_parse();
+	init_atomic();
+	init_paths();
+	init_version();
+	migrateArgs = {
+		config: {
+			type: "string",
+			alias: "c",
+			description: "servers config (default: <state>/servers.config.json)"
+		},
+		dryRun: {
+			type: "boolean",
+			description: "print what would change, write nothing"
+		},
+		yes: {
+			type: "boolean",
+			alias: "y",
+			description: "apply without asking (or set HHOSTED_MIGRATE=allow)"
+		}
+	};
+	migrateCommand = defineCommand({
+		meta: {
+			name: "migrate",
+			description: "bring the config up to this release's schema"
+		},
+		args: migrateArgs,
+		run: async ({ args }) => {
+			await runMigrate(args.config, args.dryRun === true, args.yes === true);
+		}
+	});
+}));
+//#endregion
+//#region src/services/init.ts
+/** The scripts every scaffolded project gets; all of them keep state inside the project. */
+function projectScripts() {
+	const withState = (args) => `home-hosted ${args} --home ./state`;
+	return {
+		"up": withState("up"),
+		"down": withState("down"),
+		"restart": withState("restart"),
+		"status": withState("status"),
+		"set-password": withState("set-password"),
+		"set-token": withState("set-token"),
+		"migrate": withState("migrate")
+	};
 }
+/** `home-hosted` is pinned to the version that wrote the project, and open to newer ones. */
+function projectManifest(name) {
+	return `${JSON.stringify({
+		name,
+		version: "0.1.0",
+		private: true,
+		description: "Servers supervised by home-hosted.",
+		type: "module",
+		engines: { node: ">=24.0.0" },
+		scripts: projectScripts(),
+		dependencies: { "home-hosted": `^${appVersion()}` }
+	}, null, 2)}\n`;
+}
+/**
+* State is generated, so it stays out — except the file that declares the servers,
+* which is the one thing worth committing.
+*/
+function projectGitignore() {
+	return `node_modules/
+
+# home-hosted: state is local, the server definitions are tracked
+state/*
+!state/servers.config.json
+data/
+`;
+}
+function isEmptyDir(dir) {
+	try {
+		return fs.readdirSync(dir).every((entry) => entry === ".git");
+	} catch {
+		return true;
+	}
+}
+function assertUsableDir(dir) {
+	let stats = null;
+	try {
+		stats = fs.statSync(dir);
+	} catch {
+		return;
+	}
+	if (!stats.isDirectory()) throw new Error(`${dir} exists and is not a directory`);
+	if (!isEmptyDir(dir)) throw new Error(`${dir} is not empty — pick another directory, or empty it first`);
+}
+/** Writes the project skeleton. Nothing is installed or initialized here. */
+function scaffold(options) {
+	const dir = path.resolve(options.dir);
+	assertUsableDir(dir);
+	const existed = fs.existsSync(dir);
+	fs.mkdirSync(dir, { recursive: true });
+	const files = [["package.json", projectManifest(options.name)], [".gitignore", projectGitignore()]];
+	for (const [name, contents] of files) fs.writeFileSync(path.join(dir, name), contents);
+	return {
+		dir,
+		created: !existed,
+		files: files.map(([name]) => name),
+		installed: false,
+		git: false
+	};
+}
+/** The package manager this machine actually has, preferring pnpm. */
+function detectPackageManager(exists) {
+	return PACKAGE_MANAGERS.find((pm) => exists(pm)) ?? "npm";
+}
+/** How to run one of the project's scripts with a given package manager. */
+function runCommand$1(pm, script) {
+	return pm === "npm" ? `npm run ${script}` : `${pm} run ${script}`;
+}
+/** Install arguments for a scaffolded project (the manifest already lists the dependency). */
+function installArgs(pm) {
+	return pm === "yarn" ? [] : ["install"];
+}
+var PACKAGE_MANAGERS;
+var init_init$1 = __esmMin((() => {
+	init_version();
+	PACKAGE_MANAGERS = [
+		"pnpm",
+		"npm",
+		"yarn",
+		"bun"
+	];
+}));
+//#endregion
+//#region src/cli/init.ts
+var init_exports = /* @__PURE__ */ __exportAll({
+	initArgs: () => initArgs,
+	initCommand: () => initCommand,
+	runInit: () => runInit
+});
 function which(command) {
 	return spawnSync(command, ["--version"], {
 		stdio: "ignore",
 		shell: process.platform === "win32"
 	}).status === 0;
 }
-/**
-* Scaffolds a project that keeps its whole setup — state, data and the server
-* definitions — inside its own directory. Interactive by nature, but `--yes`
-* takes every default so an agent or a CI job can run it unattended.
-*/
-async function initProject(argv) {
-	const { values } = parseArgs({
-		args: argv,
-		options: {
-			"dir": { type: "string" },
-			"name": { type: "string" },
-			"pm": { type: "string" },
-			"no-install": { type: "boolean" },
-			"yes": {
-				type: "boolean",
-				short: "y"
-			}
-		},
-		allowPositionals: false
-	});
-	const { detectPackageManager, installArgs, PACKAGE_MANAGERS, runCommand, scaffold } = await Promise.resolve().then(() => (init_init(), init_exports));
-	const assumeYes = values.yes === true;
+async function runInit(options) {
+	const assumeYes = options.yes;
 	if (!assumeYes && process.stdin.isTTY !== true) fail("init needs a terminal to ask in.\n  take the defaults with: home-hosted init --yes [--dir <dir>]");
-	const defaultDir = values.dir ?? "./my-servers";
+	const defaultDir = options.dir ?? "./my-servers";
 	const dir = assumeYes ? defaultDir : (await prompt(`Project directory (${defaultDir}) `)).trim() || defaultDir;
 	const defaultName = path.basename(path.resolve(dir));
-	const name = values.name ?? (assumeYes ? defaultName : (await prompt(`Package name (${defaultName}) `)).trim() || defaultName);
-	let pm = values.pm;
+	const name = options.name ?? (assumeYes ? defaultName : (await prompt(`Package name (${defaultName}) `)).trim() || defaultName);
+	let pm = options.pm;
 	if (pm !== void 0 && !PACKAGE_MANAGERS.includes(pm)) fail(`unknown package manager: ${pm} (expected one of ${PACKAGE_MANAGERS.join(", ")})`);
 	const detected = detectPackageManager(which);
 	if (pm === void 0) pm = assumeYes ? detected : (await prompt(`Package manager (${detected}) `)).trim() || detected;
-	const install = values["no-install"] === true ? false : assumeYes || await confirm("Install the dependencies now?", true);
+	const install = options.noInstall ? false : assumeYes || await confirm("Install the dependencies now?", true);
 	const git = assumeYes ? which("git") : which("git") && await confirm("Initialize a git repository?", true);
 	try {
 		const result = scaffold({
@@ -8108,180 +8677,581 @@ async function initProject(argv) {
 	const where = relative.length === 0 || relative.startsWith("..") ? target : relative;
 	const cd = relative.length === 0 ? "" : `cd ${where} && `;
 	process.stdout.write(`\nNext:\n`);
-	process.stdout.write(`  ${bold(`${cd}${runCommand(pm, "up")}`)}     start the panel (default password \`hh\`)\n`);
+	process.stdout.write(`  ${bold(`${cd}${runCommand$1(pm, "up")}`)}     start the panel (default password \`hh\`)\n`);
 	process.stdout.write(`  ${dim("then change that password under Settings → Authentication, and add your servers")}\n`);
-	process.stdout.write(`  ${dim(`${runCommand(pm, "set-token")} --generate    for scripts and agents`)}\n`);
+	process.stdout.write(`  ${dim(`${runCommand$1(pm, "set-token")} --generate    for scripts and agents`)}\n`);
 }
-/** Drops a user-installed UI so the stock panel serves again. */
-async function uiRevert() {
-	const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
-	const { dataRoot } = await Promise.resolve().then(() => (init_paths(), paths_exports));
-	const ui = new UiService({ dataRoot });
-	if (!ui.custom) {
-		process.stdout.write("no custom UI is installed — the stock panel is already in use\n");
-		return;
+var initArgs, initCommand;
+var init_init = __esmMin((() => {
+	init_io();
+	init_init$1();
+	initArgs = {
+		dir: {
+			type: "string",
+			description: "where to scaffold (default: ./my-servers)"
+		},
+		name: {
+			type: "string",
+			description: "package name (default: the directory name)"
+		},
+		pm: {
+			type: "string",
+			description: "pnpm | npm | yarn | bun (default: the first one installed)"
+		},
+		install: {
+			type: "boolean",
+			default: true,
+			negativeDescription: "write the files, install nothing"
+		},
+		yes: {
+			type: "boolean",
+			alias: "y",
+			description: "take every default, ask nothing"
+		}
+	};
+	initCommand = defineCommand({
+		meta: {
+			name: "init",
+			description: "scaffold a project that keeps its state in the repo"
+		},
+		args: initArgs,
+		run: async ({ args }) => {
+			await runInit({
+				dir: args.dir,
+				name: args.name,
+				pm: args.pm,
+				noInstall: args.install === false,
+				yes: args.yes === true
+			});
+		}
+	});
+}));
+//#endregion
+//#region src/cli/ui-switch.ts
+var ui_switch_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_REPO: () => DEFAULT_REPO,
+	MAX_DOWNLOAD_BYTES: () => MAX_DOWNLOAD_BYTES,
+	defaultReleaseTag: () => defaultReleaseTag,
+	fallbackUiName: () => fallbackUiName,
+	isGithubHost: () => isGithubHost,
+	isOwnRepo: () => isOwnRepo,
+	isUiAsset: () => isUiAsset,
+	matchAsset: () => matchAsset,
+	parseFileSource: () => parseFileSource,
+	parseRepoSlug: () => parseRepoSlug,
+	releaseApiUrl: () => releaseApiUrl,
+	uiSwitch: () => uiSwitch,
+	uiSwitchCommand: () => uiSwitchCommand
+});
+/** `owner/name`, the only slug GitHub releases are addressed by. */
+function parseRepoSlug(value) {
+	const match = /^([\w.-]+)\/([\w.-]+)$/.exec(value.trim());
+	if (match === null) return null;
+	return {
+		owner: match[1],
+		name: match[2]
+	};
+}
+/** The repo the default tag rule is about; `DEFAULT_REPO` is its only definition. */
+function isOwnRepo(repo) {
+	return `${repo.owner}/${repo.name}`.toLowerCase() === DEFAULT_REPO.toLowerCase();
+}
+/**
+* Our own release tag matches this CLI's version, so a UI is paired with the panel
+* it was built for. Another repo has no such pairing, so its latest release is used.
+* `null` means "latest".
+*/
+function defaultReleaseTag(repo, version) {
+	return isOwnRepo(repo) ? `v${version}` : null;
+}
+function releaseApiUrl(repo, tag) {
+	const base = `https://api.github.com/repos/${repo.owner}/${repo.name}/releases`;
+	if (tag === null || tag.length === 0 || tag === "latest") return `${base}/latest`;
+	return `${base}/tags/${encodeURIComponent(tag)}`;
+}
+/** Generous and predictable: a UI bundle is an asset whose name ends in `.zip`. */
+function isUiAsset(name) {
+	return /\.zip$/i.test(name.trim());
+}
+/**
+* Resolves `--asset`: an exact name, a case-insensitive name, or a single
+* unambiguous substring (`--asset stock` for `home-hosted-ui-stock.zip`).
+*/
+function matchAsset(names, query) {
+	const wanted = query.trim();
+	if (wanted.length === 0) return {
+		ok: false,
+		error: "no asset name was given"
+	};
+	const exact = names.find((name) => name === wanted);
+	if (exact !== void 0) return {
+		ok: true,
+		name: exact
+	};
+	const lower = wanted.toLowerCase();
+	const insensitive = names.filter((name) => name.toLowerCase() === lower);
+	if (insensitive.length === 1) return {
+		ok: true,
+		name: insensitive[0]
+	};
+	const partial = names.filter((name) => name.toLowerCase().includes(lower));
+	if (partial.length === 0) return {
+		ok: false,
+		error: `no asset matches "${wanted}" (available: ${names.join(", ") || "none"})`
+	};
+	if (partial.length > 1) return {
+		ok: false,
+		error: `"${wanted}" matches more than one asset: ${partial.join(", ")} — use the full name`
+	};
+	return {
+		ok: true,
+		name: partial[0]
+	};
+}
+/** `^https?://` means a URL; anything else is a filesystem path with `~` expanded. */
+function parseFileSource(value) {
+	const trimmed = value.trim();
+	if (/^https?:\/\//i.test(trimmed)) return {
+		kind: "url",
+		url: trimmed
+	};
+	return {
+		kind: "path",
+		path: expandHome(trimmed)
+	};
+}
+function expandHome(value) {
+	if (value === "~") return os.homedir();
+	if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(os.homedir(), value.slice(2));
+	return value;
+}
+/**
+* A token is only ever sent to GitHub: `--file <url>` may point anywhere, and a
+* credential must not leak to a host the user did not vouch for.
+*/
+function isGithubHost(url) {
+	try {
+		const host = new URL(url).hostname.toLowerCase();
+		return host === "github.com" || host.endsWith(".github.com") || host === "githubusercontent.com" || host.endsWith(".githubusercontent.com");
+	} catch {
+		return false;
 	}
-	ui.revert();
-	process.stdout.write(`${green("custom UI removed")} — the stock panel is back; refresh the browser\n`);
 }
-async function setPassword(argv) {
+/** What `UiService` names the install when the archive carries no `ui.json`. */
+function fallbackUiName(source) {
+	const stripped = path.basename(source).replace(/\.zip$/i, "").replace(/^home-hosted-ui-/i, "");
+	return stripped.length > 0 ? stripped : "custom-ui";
+}
+async function uiSwitch(argv, io) {
 	const { values } = parseArgs({
 		args: argv,
-		options: { clear: { type: "boolean" } },
+		options: {
+			repo: { type: "string" },
+			tag: { type: "string" },
+			asset: { type: "string" },
+			file: { type: "string" },
+			list: { type: "boolean" },
+			token: { type: "string" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			}
+		},
 		allowPositionals: false
 	});
-	const { defaultSecretsPath } = await Promise.resolve().then(() => (init_paths(), paths_exports));
-	const { SecretsStore } = await Promise.resolve().then(() => (init_secrets(), secrets_exports));
-	const store = new SecretsStore(defaultSecretsPath);
-	if (values.clear === true) {
-		store.clearPassword();
-		process.stdout.write(`cleared the control panel password in ${defaultSecretsPath}\n`);
-		process.stdout.write(`${dim("authentication stays disabled until you enable it again in the settings page")}\n`);
+	const { appVersion } = await Promise.resolve().then(() => (init_version(), version_exports));
+	const context = {
+		io,
+		version: appVersion(),
+		token: values.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? null
+	};
+	if (values.file !== void 0) {
+		if (values.repo !== void 0 || values.tag !== void 0 || values.asset !== void 0 || values.list === true) throw new Error("--file installs a zip directly; it cannot be combined with --repo, --tag, --asset or --list");
+		await installFromFile(values.file, context);
 		return;
 	}
-	const interactive = process.stdin.isTTY === true;
-	let password = process.env.HHOSTED_PASSWORD;
-	if (password === void 0 && interactive) {
-		password = await promptHidden("New control panel password: ");
-		const again = await promptHidden("Repeat it: ");
-		if (password !== again) fail("the passwords do not match");
+	const repo = parseRepoSlug(values.repo ?? "NamesMT/home-hosted");
+	if (repo === null) throw new Error(`invalid --repo "${values.repo}" — expected an "owner/name" slug, e.g. ${DEFAULT_REPO}`);
+	const requestedTag = values.tag ?? defaultReleaseTag(repo, context.version);
+	const release = await fetchRelease(repo, requestedTag, context);
+	const skipped = release.assets.filter((asset) => !isUiAsset(asset.name ?? "")).map((asset) => asset.name ?? "?");
+	const usable = release.assets.filter((asset) => isUiAsset(asset.name ?? ""));
+	const where = `${repo.owner}/${repo.name}@${release.tag}`;
+	if (values.list === true) {
+		if (usable.length === 0) throw new Error(noAssetsMessage(where, skipped, requestedTag));
+		const lines = [`${io.style.bold(where)} — ${usable.length} usable UI asset(s)`];
+		for (const asset of usable) lines.push(`  ${asset.name}`);
+		if (skipped.length > 0) lines.push(io.style.dim(`  skipped (not a .zip): ${skipped.join(", ")}`));
+		io.write(`${lines.join("\n")}\n`);
+		return;
 	}
-	if (password === void 0 || password.length === 0) fail("no password given: run interactively, or set HHOSTED_PASSWORD for a non-interactive run");
-	store.setPassword(password);
-	process.stdout.write(`${green("password stored")} in ${defaultSecretsPath} (mode 0600)\n`);
-	if (password.length < 8) process.stdout.write(`${dim(`"${password}" is short — easy to guess if the panel is reachable beyond loopback`)}\n`);
-	process.stdout.write(`${dim("restart the panel for it to take effect: home-hosted restart")}\n`);
+	if (usable.length === 0) throw new Error(noAssetsMessage(where, skipped, requestedTag));
+	const chosen = await chooseAsset(usable, values, context);
+	if (chosen === null) {
+		io.write("cancelled — nothing was installed\n");
+		return;
+	}
+	await installFromUrl(assetDownloadUrl(chosen), fallbackUiName(chosen.name ?? ""), context);
 }
-/**
-* The bearer credential for scripts and agents. Unlike a session it survives a
-* restart, so an agent can set it up once and then just send the header.
-*/
-async function setToken(argv) {
-	const { values } = parseArgs({
-		args: argv,
-		options: {
-			generate: { type: "boolean" },
-			clear: { type: "boolean" }
+async function fetchRelease(repo, tag, context) {
+	const url = releaseApiUrl(repo, tag);
+	let response;
+	try {
+		response = await fetch(url, { headers: apiHeaders(context) });
+	} catch (error) {
+		throw new Error(`could not reach GitHub: ${describeError(error)}`);
+	}
+	if (!response.ok) throw new Error(describeReleaseFailure(response.status, repo, tag));
+	const body = await response.json();
+	return {
+		tag: body.tag_name ?? tag ?? "latest",
+		assets: Array.isArray(body.assets) ? body.assets : []
+	};
+}
+async function chooseAsset(assets, values, context) {
+	const { io } = context;
+	if (values.asset !== void 0) {
+		const matched = matchAsset(assets.map((asset) => asset.name ?? ""), values.asset);
+		if (!matched.ok) throw new Error(matched.error);
+		return assets.find((asset) => asset.name === matched.name);
+	}
+	if (!(process.stdin.isTTY === true && values.yes !== true)) {
+		if (assets.length === 1) return assets[0];
+		throw new Error([
+			`${assets.length} UI assets are available and this session cannot ask which one:`,
+			...assets.map((asset) => `  ${asset.name}`),
+			"  pick one with --asset <name>, or list them with --list"
+		].join("\n"));
+	}
+	io.write(`${[io.style.bold("Available UI assets"), ...assets.map((asset, index) => `  ${index + 1}) ${asset.name}`)].join("\n")}\n`);
+	for (;;) {
+		const answer = (await io.prompt(`Select an asset [1-${assets.length}] (empty to cancel) `)).trim();
+		if (answer.length === 0) return null;
+		if (/^\d+$/.test(answer)) {
+			const index = Number.parseInt(answer, 10);
+			if (index >= 1 && index <= assets.length) return assets[index - 1];
+		}
+		const matched = matchAsset(assets.map((asset) => asset.name ?? ""), answer);
+		if (matched.ok) return assets.find((asset) => asset.name === matched.name);
+		io.write(`  ${io.style.dim(matched.error)}\n`);
+	}
+}
+async function installFromFile(value, context) {
+	const source = parseFileSource(value);
+	if (source.kind === "path") {
+		if (!fs.existsSync(source.path)) throw new Error(`no file at ${source.path}`);
+		if (!fs.statSync(source.path).isFile()) throw new Error(`${source.path} is not a file`);
+		await installArchive(source.path, fallbackUiName(source.path), context);
+		return;
+	}
+	await installFromUrl(source.url, fallbackUiName(new URL(source.url).pathname), context);
+}
+async function installFromUrl(url, fallbackName, context) {
+	const headers = {
+		"accept": "application/octet-stream",
+		"user-agent": `home-hosted/${context.version}`
+	};
+	if (context.token !== null && context.token.length > 0 && isGithubHost(url)) headers.authorization = `Bearer ${context.token}`;
+	const download = await downloadToTemp(url, headers, context);
+	try {
+		await installArchive(download.file, fallbackName, context);
+	} finally {
+		fs.rmSync(download.dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Streams to `os.tmpdir()` so a large body is never buffered in memory. */
+async function downloadToTemp(url, headers, context) {
+	let response;
+	try {
+		response = await fetch(url, {
+			headers,
+			redirect: "follow"
+		});
+	} catch (error) {
+		throw new Error(`could not reach ${url}: ${describeError(error)}`);
+	}
+	if (!response.ok) throw new Error(describeDownloadFailure(response.status, url));
+	const declared = Number(response.headers.get("content-length") ?? "0");
+	if (!Number.isFinite(declared) || declared < 0) throw new Error(`the download from ${url} reported an unusable size`);
+	if (declared > 536870912) throw new Error(tooLargeMessage(declared));
+	if (response.body === null) throw new Error(`the download from ${url} had no body`);
+	const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "hh2-ui-"));
+	const file = path.join(dir, "ui.zip");
+	const handle = await fs.promises.open(file, "w");
+	let received = 0;
+	try {
+		for await (const chunk of response.body) {
+			received += chunk.length;
+			if (received > 536870912) throw new Error(tooLargeMessage(received));
+			await handle.write(chunk);
+		}
+	} catch (error) {
+		await handle.close();
+		fs.rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+		throw error instanceof Error ? error : new Error(String(error));
+	}
+	await handle.close();
+	context.io.write(`${context.io.style.dim(`downloaded ${formatBytes(received)}`)}\n`);
+	return {
+		dir,
+		file
+	};
+}
+async function installArchive(archivePath, fallbackName, context) {
+	const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
+	const { dataRoot } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+	const ui = new UiService({ dataRoot });
+	const result = await ui.install(archivePath, fallbackName);
+	if (!result.ok) throw new Error(`nothing was installed: ${result.error}`);
+	const { meta } = result;
+	const label = meta.version === null ? meta.name : `${meta.name} ${meta.version}`;
+	context.io.write(`${context.io.style.green("UI installed")} — ${label}\n`);
+	context.io.write(`  ${context.io.style.dim("state")}  ${ui.directory}\n`);
+	context.io.write(`  ${context.io.style.dim("files")}  ${meta.files}\n`);
+	context.io.write(`refresh the browser to see it\n`);
+}
+function apiHeaders(context) {
+	const headers = {
+		"accept": "application/vnd.github+json",
+		"user-agent": `home-hosted/${context.version}`,
+		"x-github-api-version": "2022-11-28"
+	};
+	if (context.token !== null && context.token.length > 0) headers.authorization = `Bearer ${context.token}`;
+	return headers;
+}
+function assetDownloadUrl(asset) {
+	const url = asset.url ?? asset.browser_download_url;
+	if (url === void 0 || url.length === 0) throw new Error(`the release metadata for "${asset.name ?? "an asset"}" carries no download URL`);
+	return url;
+}
+function noAssetsMessage(where, skipped, tag) {
+	const lines = [`no usable UI assets in ${where} (expected a .zip)`];
+	lines.push(skipped.length > 0 ? `  skipped: ${skipped.join(", ")}` : "  the release has no assets at all");
+	if (tag !== null && tag !== "latest") lines.push("  installing a different version silently is worse than failing: try the newest release with --tag latest");
+	return lines.join("\n");
+}
+function describeReleaseFailure(status, repo, tag) {
+	const slug = `${repo.owner}/${repo.name}`;
+	if (status === 404) {
+		if (tag !== null && tag !== "latest") return `no release tagged "${tag}" in ${slug}\n  list what exists with: home-hosted ui-switch --repo ${slug} --tag latest --list`;
+		return `no repository or published release at ${slug}\n  check the --repo slug (owner/name), and that the repository is public`;
+	}
+	if (status === 403 || status === 429) return `GitHub refused the request (HTTP ${status}) — the unauthenticated API rate limit is per address.\n  set a token to raise it: --token <token>, or GITHUB_TOKEN / GH_TOKEN`;
+	if (status === 401) return "GitHub rejected the token (HTTP 401) — check --token, GITHUB_TOKEN or GH_TOKEN";
+	return `GitHub answered HTTP ${status} while reading the release of ${slug}`;
+}
+function describeDownloadFailure(status, url) {
+	const github = isGithubHost(url);
+	if (status === 404) return github ? `the asset is gone (HTTP 404) — ${url}\n  the release may have been rebuilt since it was listed; run the command again` : `nothing is served at that URL (HTTP 404) — ${url}`;
+	if (status === 403 || status === 429) return github ? `GitHub refused the download (HTTP ${status}) — a token raises the rate limit: --token <token>, or GITHUB_TOKEN / GH_TOKEN` : `the host refused the download (HTTP ${status}) — ${url}`;
+	if (status === 401 && github) return "GitHub rejected the token on the download (HTTP 401) — check --token, GITHUB_TOKEN or GH_TOKEN";
+	return `the download failed (HTTP ${status}) — ${url}`;
+}
+function tooLargeMessage(bytes) {
+	return `the download is ${formatBytes(bytes)}, larger than the ${MAX_DOWNLOAD_BYTES / 1024 / 1024}MB a UI may be`;
+}
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1048576) return `${Math.round(bytes / 1024)} KB`;
+	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+var DEFAULT_REPO, MAX_DOWNLOAD_BYTES, uiSwitchCommand;
+var init_ui_switch = __esmMin((() => {
+	init_io();
+	DEFAULT_REPO = "NamesMT/home-hosted";
+	MAX_DOWNLOAD_BYTES = 536870912;
+	uiSwitchCommand = defineCommand({
+		meta: {
+			name: "ui-switch",
+			description: "install a UI from a release asset, a zip file or a URL"
 		},
-		allowPositionals: false
-	});
-	if (values.generate === true && values.clear === true) fail("use either --generate or --clear, not both");
-	const { defaultSecretsPath } = await Promise.resolve().then(() => (init_paths(), paths_exports));
-	const { generateApiToken, SecretsStore } = await Promise.resolve().then(() => (init_secrets(), secrets_exports));
-	const store = new SecretsStore(defaultSecretsPath);
-	if (values.clear === true) {
-		if (!store.apiTokenSet) {
-			process.stdout.write("no API token is set — nothing to clear\n");
-			return;
+		run: async ({ rawArgs }) => {
+			await uiSwitch(rawArgs, {
+				write: (text) => process.stdout.write(text),
+				prompt,
+				style
+			});
 		}
-		store.clearApiToken();
-		process.stdout.write(`${green("API token cleared")} in ${defaultSecretsPath} — it stops working immediately\n`);
+	});
+}));
+//#endregion
+//#region src/cli/ui-revert.ts
+var ui_revert_exports = /* @__PURE__ */ __exportAll({
+	runUiRevert: () => runUiRevert,
+	uiRevertCommand: () => uiRevertCommand
+});
+/** `ui-revert` drops a user-installed UI so the stock panel serves again. */
+async function runUiRevert() {
+	const ui = new UiService({ dataRoot });
+	if (!ui.custom) {
+		process.stdout.write("no custom UI is installed — the stock panel is already in use\n");
 		return;
 	}
-	let token = process.env.HHOSTED_TOKEN ?? null;
-	if (values.generate === true) token = generateApiToken();
-	else if (token === null && process.stdin.isTTY === true) token = await promptHidden("API token: ");
-	if (token !== null) token = token.trim();
-	if (token === null || token.length === 0) fail("no token given: run `home-hosted set-token --generate`, set HHOSTED_TOKEN, or paste one interactively");
-	store.setApiToken(token);
-	const generated = values.generate === true;
-	process.stdout.write(`${green(generated ? "token generated" : "token stored")} in ${defaultSecretsPath} (mode 0600)\n`);
-	if (generated) {
-		process.stdout.write(`  ${bold(token)}\n`);
-		process.stdout.write(`${dim("  shown once — only its SHA-256 is kept on disk, so copy it now")}\n`);
-	} else process.stdout.write(`${dim(`  stored as ${token.slice(0, 8)}… — the file keeps only its hash`)}\n`);
-	const { readRuntime } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
-	const runtime = readRuntime();
-	const base = (runtime?.url ?? `http://127.0.0.1:${DEFAULT_PORT}`).replace(/\/+$/, "");
-	if (runtime !== null) {
-		const verified = await verifyToken(base, token);
-		if (verified === true) process.stdout.write(`${dim(`verified: ${base}/api/auth/session accepted it`)}\n`);
-		else if (verified === false) process.stdout.write(`${dim(`the panel at ${base} did not accept it — is it running with this state directory?`)}\n`);
-	}
-	process.stdout.write(`Use it from a script or an agent:\n`);
-	process.stdout.write(`  ${bold(`curl -H "Authorization: Bearer ${generated ? token : "<token>"}" ${base}/api/state`)}\n`);
-	process.stdout.write(`${dim("It needs no restart, outlives sessions, and holds the same access as a signed-in browser.")}\n`);
-	process.stdout.write(`${dim("Remove it any time with: home-hosted set-token --clear")}\n`);
-	if (store.usingDefaultPassword) process.stdout.write(`${dim("The panel password is still the default — change it before the panel is reachable beyond loopback.")}\n`);
+	ui.revert();
+	process.stdout.write(`${green("custom UI removed")} — the stock panel is back; refresh the browser\n`);
 }
-/** Asks the live panel whether it accepts the token, without failing when it cannot. */
-async function verifyToken(base, token) {
-	if (!base.startsWith("http://")) return null;
+var uiRevertCommand;
+var init_ui_revert = __esmMin((() => {
+	init_io();
+	init_paths();
+	init_ui();
+	uiRevertCommand = defineCommand({
+		meta: {
+			name: "ui-revert",
+			description: "go back to the stock control panel UI"
+		},
+		run: async () => {
+			await runUiRevert();
+		}
+	});
+}));
+//#endregion
+//#region src/cli.ts
+init_args();
+init_io();
+/**
+* The command line, and nothing else. Two things happen before citty is asked
+* anything: `--home`/`--project` are peeled off and applied (because
+* `#src/helpers/paths.ts` resolves at import time), and the curated surface —
+* `help`, `version`, `unknown command`, and the `-p 4000` shorthand for `up` —
+* is decided. The command modules are then resolved lazily by citty, so their
+* own `#src` imports are safe: by the time one is imported, the directories are
+* already in the environment.
+*
+* The only static imports here are node builtins, citty, and the two path-free
+* local modules the pre-pass needs; every command (and so every state-reading
+* module) is a dynamic import behind `subCommands`.
+*/
+var CLI_ENTRY = fileURLToPath(import.meta.url);
+var USAGE = `home-hosted — a control panel for the processes on your home server
+
+Usage
+  home-hosted up [options]      start it in the background (detached)
+  home-hosted down              stop it, and everything it supervises
+  home-hosted restart [options] down, then up
+  home-hosted status [--json]   is it running, where, and how to reach it
+  home-hosted set-password      set the panel password without the API
+  home-hosted set-token         set the API token that scripts and agents use
+  home-hosted migrate           bring the config up to this release's schema
+  home-hosted init              scaffold a project that keeps its state in the repo
+  home-hosted ui-switch         install a UI from a release asset, a zip file or a URL
+  home-hosted ui-revert         go back to the stock control panel UI
+
+Options for up/restart
+  -c, --config <file>   servers config (default: <state>/servers.config.json)
+  -p, --port <port>     control panel port (default: 3999)
+      --host <bind>     local | lan | an ipv4 address (default: local)
+      --open            open the panel in a browser once it is up
+      --no-autostart    do not start the entries marked autostart
+      --foreground      run in this process instead of detaching (systemd/docker)
+      --print-config    print the effective config and exit
+
+Options for set-token
+      --generate        create a strong token and print it once
+      --clear           remove the token, so it stops working
+
+Options for migrate
+      --dry-run         print what would change, write nothing
+  -y, --yes             apply without asking (or set HHOSTED_MIGRATE=allow)
+
+Options for init
+      --dir <dir>       where to scaffold (default: ./my-servers)
+      --name <name>     package name (default: the directory name)
+      --pm <manager>    pnpm | npm | yarn | bun (default: the first one installed)
+      --no-install      write the files, install nothing
+  -y, --yes             take every default, ask nothing
+
+Options for ui-switch
+      --repo <owner/name>   release repo (default: NamesMT/home-hosted)
+      --tag <tag>           release tag (default: this release's tag, or latest for another repo)
+      --asset <name>        asset to install (exact or unambiguous match)
+      --file <path|url>     install a zip from a local path or an http(s) URL
+      --list                list the usable assets and install nothing
+      --token <token>       GitHub token (or GITHUB_TOKEN / GH_TOKEN)
+  -y, --yes                 take the only asset instead of asking
+
+Everywhere
+      --home <dir>      state directory (default: $HHOSTED_HOME or ~/.home-hosted)
+      --project <dir>   base for relative entry paths (default: the current directory)
+  -h, --help            this text
+  -v, --version         the version
+
+Environment
+  HHOSTED_HOME          where config, secrets, logs, TLS and backups live
+  HHOSTED_PROJECT       base for relative entry paths
+  HHOSTED_PASSWORD      the password for a non-interactive set-password
+  HHOSTED_TOKEN         the token for a non-interactive set-token
+  GITHUB_TOKEN          a GitHub token for ui-switch (GH_TOKEN also works)
+`;
+function manifestVersion() {
 	try {
-		const response = await fetch(`${base}/api/auth/session`, { headers: { authorization: `Bearer ${token}` } });
-		if (!response.ok) return false;
-		return (await response.json()).authenticated === true;
+		return JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
 	} catch {
-		return null;
+		return "0.0.0";
 	}
 }
 function version() {
-	const manifest = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-	process.stdout.write(`${manifest.version ?? "0.0.0"}\n`);
+	process.stdout.write(`${manifestVersion()}\n`);
 }
+/**
+* citty owns dispatch and argument parsing. Each entry is a lazy import, so a
+* command's `#src` modules are only evaluated once `applyDirFlags()` has run.
+*/
+var COMMANDS = {
+	"up": () => Promise.resolve().then(() => (init_up(), up_exports)).then((module) => module.upCommand(CLI_ENTRY)),
+	"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),
+	"set-password": () => Promise.resolve().then(() => (init_set_password(), set_password_exports)).then((module) => module.setPasswordCommand),
+	"set-token": () => Promise.resolve().then(() => (init_set_token(), set_token_exports)).then((module) => module.setTokenCommand),
+	"migrate": () => Promise.resolve().then(() => (init_migrate(), migrate_exports)).then((module) => module.migrateCommand),
+	"init": () => Promise.resolve().then(() => (init_init(), init_exports)).then((module) => module.initCommand),
+	"ui-switch": () => Promise.resolve().then(() => (init_ui_switch(), ui_switch_exports)).then((module) => module.uiSwitchCommand),
+	"ui-revert": () => Promise.resolve().then(() => (init_ui_revert(), ui_revert_exports)).then((module) => module.uiRevertCommand)
+};
+var rootCommand = defineCommand({
+	meta: {
+		name: "home-hosted",
+		version: manifestVersion(),
+		description: "a control panel for the processes on your home server"
+	},
+	subCommands: COMMANDS
+});
+var commandNames = Object.keys(COMMANDS);
 async function main() {
-	const { rest, ...dirFlags } = extractDirFlags(process.argv.slice(2));
-	const [command = "", ...args] = rest;
-	if (command === "" && rest.length === 0) {
-		applyDirFlags(dirFlags);
-		await up([]);
+	const dirFlags = extractDirFlags(process.argv.slice(2));
+	if (dirFlags.error !== void 0) fail(dirFlags.error);
+	applyDirFlags(dirFlags);
+	const invocation = resolveInvocation(dirFlags.rest, commandNames);
+	if (invocation.kind === "help") {
+		process.stdout.write(USAGE);
 		return;
 	}
-	switch (command) {
-		case "up":
-			applyDirFlags(dirFlags);
-			await up(args);
-			return;
-		case "down":
-			applyDirFlags(dirFlags);
-			await down();
-			return;
-		case "restart":
-			applyDirFlags(dirFlags);
-			await restart(args);
-			return;
-		case "status":
-			applyDirFlags(dirFlags);
-			await status(args);
-			return;
-		case "set-password":
-			applyDirFlags(dirFlags);
-			await setPassword(args);
-			return;
-		case "set-token":
-			applyDirFlags(dirFlags);
-			await setToken(args);
-			return;
-		case "migrate":
-			applyDirFlags(dirFlags);
-			await migrateConfig(args);
-			return;
-		case "init":
-			applyDirFlags(dirFlags);
-			await initProject(args);
-			return;
-		case "ui-revert":
-			applyDirFlags(dirFlags);
-			await uiRevert();
-			return;
-		case "help":
-		case "--help":
-		case "-h":
-			process.stdout.write(USAGE);
-			return;
-		case "version":
-		case "--version":
-		case "-v":
-			version();
-			return;
-		default:
-			if (command.startsWith("-")) {
-				applyDirFlags(dirFlags);
-				await up(rest);
-				return;
-			}
-			process.stderr.write(`unknown command: ${command}\n\n${USAGE}`);
-			process.exit(1);
+	if (invocation.kind === "version") {
+		version();
+		return;
+	}
+	if (invocation.kind === "unknown") {
+		process.stderr.write(`unknown command: ${invocation.command}\n\n${USAGE}`);
+		process.exit(1);
+	}
+	const sub = COMMANDS[invocation.argv[0]];
+	const command = typeof sub === "function" ? await sub() : sub;
+	const problem = rejectUnknownFlags(invocation.argv.slice(1), command?.args);
+	if (problem !== null) fail(problem);
+	try {
+		await runCommand(rootCommand, { rawArgs: invocation.argv });
+	} catch (error) {
+		fail(error instanceof Error ? error.message : String(error));
 	}
 }
 main().catch((error) => {