home-hosted 0.6.0 → 0.6.2

package/dist/cli.js

@@ -897,10 +897,20 @@ password: passwordValueSchema.optional() }).onUndeclaredKey("reject");
 		detail: "unknown"
 	}).onUndeclaredKey("reject");
 	uiMetaSchema = type({
-		name: "string",
-		version: "string | null",
-		uploadedAt: "number",
-		files: "number.integer >= 1"
+		"name?": "string",
+		"version?": "string | null",
+		/** Set by the panel, not by the author. */
+		"uploadedAt?": "number",
+		/** Counted by the panel, not declared. */
+		"files?": "number.integer >= 1",
+		/** `owner/name` of the UI's own repository, for `ui-update`. */
+		"repo?": "string",
+		/** The release tag this build came from, e.g. `v0.6.0`. */
+		"tag?": "string",
+		/** The release asset name, e.g. `home-hosted-ui-noc-console`. */
+		"asset?": "string",
+		/** When the UI was built, in unix epoch seconds. */
+		"unix?": "number.integer >= 0"
 	});
 	uiStatusSchema = type({
 		/** A user-supplied UI is being served instead of the stock one. */
@@ -6811,7 +6821,7 @@ var init_config_watch = __esmMin((() => {
 			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;
+					if (filename !== null && path.basename(filename) !== path.basename(this.options.file)) return;
 					this.schedule();
 				});
 				this.watcher.on("error", (error) => {
@@ -7775,6 +7785,104 @@ function isSafeUiEntry(entry) {
 	if (cleaned.length === 0) return false;
 	return cleaned.split("/").every((segment) => segment !== "" && segment !== "." && segment !== ".." && !segment.includes(":"));
 }
+function withInstallLock(dataRoot, run) {
+	const key = path.resolve(dataRoot);
+	const next = (installLocks.get(key) ?? Promise.resolve()).then(run, run);
+	installLocks.set(key, next.catch(() => {}));
+	return next;
+}
+/** Renames the staged tree into place, keeping the old one until that has certainly worked. */
+function commitSwap(dataRoot, resting, staged, meta) {
+	return withInstallLock(dataRoot, async () => {
+		try {
+			fs.renameSync(staged, resting);
+		} catch {
+			const previous = `${resting}.previous-${process.pid}-${Date.now()}`;
+			const hadPrevious = fs.existsSync(resting);
+			if (hadPrevious) fs.renameSync(resting, previous);
+			try {
+				fs.renameSync(staged, resting);
+			} catch (error) {
+				try {
+					fs.rmSync(resting, {
+						recursive: true,
+						force: true
+					});
+					if (hadPrevious && fs.existsSync(previous)) fs.renameSync(previous, resting);
+					fs.rmSync(previous, {
+						recursive: true,
+						force: true
+					});
+				} catch {
+					return {
+						ok: false,
+						error: `${describeError$1(error)} — the previous UI is kept at ${previous}`
+					};
+				}
+				return {
+					ok: false,
+					error: describeError$1(error)
+				};
+			}
+			fs.rmSync(previous, {
+				recursive: true,
+				force: true
+			});
+		}
+		sweepBackups(dataRoot, resting);
+		return {
+			ok: true,
+			meta
+		};
+	});
+}
+function sweepBackups(dataRoot, resting) {
+	const prefix = `${path.basename(resting)}.previous-`;
+	for (const entry of readDataRoot(dataRoot)) if (entry.startsWith(prefix)) fs.rmSync(path.join(dataRoot, entry), {
+		recursive: true,
+		force: true
+	});
+}
+/** The most recently abandoned UI tree, or null when there is not one. */
+function newestBackup(dataRoot, resting) {
+	const prefix = `${path.basename(resting)}.previous-`;
+	let best = null;
+	let bestStamp = -1;
+	for (const entry of readDataRoot(dataRoot)) {
+		if (!entry.startsWith(prefix)) continue;
+		const full = path.join(dataRoot, entry);
+		if (!fs.existsSync(path.join(full, "index.html"))) continue;
+		const stamp = Number(entry.slice(prefix.length).split("-").pop() ?? "");
+		if (Number.isFinite(stamp) && stamp > bestStamp) {
+			bestStamp = stamp;
+			best = full;
+		}
+	}
+	return best;
+}
+/** Dropped staging trees and superseded backups, once the live UI is whole. */
+function sweepJunk(dataRoot) {
+	let swept = 0;
+	for (const entry of readDataRoot(dataRoot)) {
+		if (!entry.startsWith(".ui-staging-") && !entry.startsWith(`.ui.previous-`)) continue;
+		fs.rmSync(path.join(dataRoot, entry), {
+			recursive: true,
+			force: true
+		});
+		swept += 1;
+	}
+	return swept;
+}
+function readDataRoot(dataRoot) {
+	try {
+		return fs.readdirSync(dataRoot);
+	} catch {
+		return [];
+	}
+}
+function describeError$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 /**
 * Where the site actually starts: the archive root, or a single wrapper directory
 * (`zip -r ui.zip dist` is a common way to build one).
@@ -7802,7 +7910,7 @@ function countFiles(root) {
 	})) if (entry.isFile() && entry.name !== META) total += 1;
 	return Math.max(1, total);
 }
-var META, MAX_ENTRIES, MAX_BYTES, MAX_NAME, manifestSchema, UiService;
+var META, MAX_ENTRIES, MAX_BYTES, MAX_NAME, manifestSchema, UiService, installLocks;
 var init_ui = __esmMin((() => {
 	init_atomic();
 	init_archive();
@@ -7813,7 +7921,11 @@ var init_ui = __esmMin((() => {
 	MAX_NAME = 120;
 	manifestSchema = type({
 		"name?": "string",
-		"version?": "string"
+		"version?": "string",
+		"repo?": "string",
+		"tag?": "string",
+		"asset?": "string",
+		"unix?": "number.integer >= 0"
 	});
 	UiService = class {
 		options;
@@ -7853,14 +7965,14 @@ var init_ui = __esmMin((() => {
 		* swapped in, so a failed upload leaves the previous UI (or the stock one)
 		* serving.
 		*/
-		async install(archivePath, fallbackName = "custom-ui") {
+		async install(archivePath, fallbackName = "custom-ui", installedTag) {
 			if (!isZipArchive(archivePath)) return {
 				ok: false,
 				error: "the upload is not a zip archive"
 			};
-			const staging = path.join(this.options.dataRoot, `.ui-staging-${Date.now()}`);
+			const staging = path.join(this.options.dataRoot, `.ui-staging-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
 			try {
-				return await this.stage(archivePath, staging, fallbackName);
+				return await this.stage(archivePath, staging, fallbackName, installedTag);
 			} catch (error) {
 				return {
 					ok: false,
@@ -7882,7 +7994,7 @@ var init_ui = __esmMin((() => {
 			});
 			return existed;
 		}
-		async stage(archivePath, staging, fallbackName) {
+		async stage(archivePath, staging, fallbackName, installedTag) {
 			let entries;
 			try {
 				entries = await listZip(archivePath);
@@ -7921,101 +8033,499 @@ var init_ui = __esmMin((() => {
 				name: manifest?.name ?? fallbackName,
 				version: manifest?.version ?? null,
 				uploadedAt: Date.now(),
-				files: countFiles(root)
+				files: countFiles(root),
+				...manifest?.repo === void 0 ? {} : { repo: manifest.repo },
+				...installedTag !== void 0 ? { tag: installedTag } : manifest?.tag === void 0 ? {} : { tag: manifest.tag },
+				...manifest?.asset === void 0 ? {} : { asset: manifest.asset },
+				...manifest?.unix === void 0 ? {} : { unix: manifest.unix }
 			};
-			const previous = `${this.directory}.previous`;
-			fs.rmSync(previous, {
-				recursive: true,
-				force: true
-			});
-			if (fs.existsSync(this.directory)) fs.renameSync(this.directory, previous);
-			try {
-				fs.renameSync(root, this.directory);
-				writeFileAtomic(path.join(this.directory, META), `${JSON.stringify(meta, null, 2)}\n`);
-			} catch (error) {
-				fs.rmSync(this.directory, {
-					recursive: true,
-					force: true
-				});
-				if (fs.existsSync(previous)) fs.renameSync(previous, this.directory);
-				return {
-					ok: false,
-					error: error instanceof Error ? error.message : String(error)
-				};
-			} finally {
-				fs.rmSync(previous, {
-					recursive: true,
-					force: true
-				});
+			writeFileAtomic(path.join(root, META), `${JSON.stringify(meta, null, 2)}\n`);
+			return commitSwap(this.options.dataRoot, this.directory, root, meta);
+		}
+		/**
+		* Puts a half-finished install back together, and is safe to call on every boot.
+		*
+		* An install that was interrupted between its two renames — a kill, a power cut, a
+		* crash — leaves `.ui` missing with the user's only copy sitting in a `.previous-*`
+		* sibling. Without this the panel would quietly serve the stock UI forever, because
+		* `custom` is false and nothing ever looked at the backup.
+		*/
+		recover() {
+			const resting = this.directory;
+			let restored = null;
+			if (!fs.existsSync(path.join(resting, "index.html"))) {
+				const backup = newestBackup(this.options.dataRoot, resting);
+				if (backup !== null) {
+					fs.rmSync(resting, {
+						recursive: true,
+						force: true
+					});
+					fs.renameSync(backup, resting);
+					restored = path.basename(backup);
+				}
 			}
 			return {
-				ok: true,
-				meta
+				restored,
+				swept: sweepJunk(this.options.dataRoot)
 			};
 		}
 	};
+	installLocks = /* @__PURE__ */ new Map();
 }));
 //#endregion
-//#region src/index.ts
-var src_exports = /* @__PURE__ */ __exportAll({
-	packageRoot: () => packageRoot,
-	runControlPlane: () => runControlPlane
-});
-function packageVersion() {
+//#region src/providers/ui-release.ts
+/** `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]
+	};
+}
+function repoSlug(repo) {
+	return `${repo.owner}/${repo.name}`;
+}
+/** The repo the default tag rule is about; `DEFAULT_REPO` is its only definition. */
+function isOwnRepo(repo) {
+	return repoSlug(repo).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)}`;
+}
+/** Every published release, newest first, as GitHub orders them. */
+function releasesApiUrl(repo, perPage = 30) {
+	return `https://api.github.com/repos/${repo.owner}/${repo.name}/releases?per_page=${perPage}`;
+}
+/** Generous and predictable: a UI bundle is an asset whose name ends in `.zip`. */
+function isUiAsset(name) {
+	return /\.zip$/i.test(name.trim());
+}
+/**
+* Resolves a wanted 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 {
-		return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "0.0.0";
+		const host = new URL(url).hostname.toLowerCase();
+		return host === "github.com" || host.endsWith(".github.com") || host === "githubusercontent.com" || host.endsWith(".githubusercontent.com");
 	} catch {
-		return "0.0.0";
+		return false;
 	}
 }
-/** A probe target for a `lan` bind, which is not connectable as `0.0.0.0`. */
-function probeHostFor(bindHost) {
-	return bindHost === "0.0.0.0" || bindHost === "::" ? "127.0.0.1" : bindHost;
+function timeoutSignal(ms) {
+	return typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(ms) : void 0;
 }
-/**
-* Runs the control plane in *this* process until it is stopped. `home-hosted up`
-* detaches a child that calls this; `--foreground` (systemd, docker) calls it
-* directly.
-*/
-async function runControlPlane(options) {
-	const existing = readRuntime();
-	if (existing !== null && existing.pid !== process.pid && isProcessAlive$1(existing.pid)) {
-		logger.error(`already running (pid ${existing.pid}) at ${existing.url} — run \`home-hosted down\` first`);
-		process.exit(1);
+function isTimeout(error) {
+	return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+/** 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";
+}
+/** One release's assets, or a message that says what was wrong with the answer. */
+async function fetchRelease(repo, tag, context) {
+	const url = releaseApiUrl(repo, tag);
+	let response;
+	try {
+		response = await fetch(url, {
+			headers: apiHeaders(context),
+			signal: timeoutSignal(REQUEST_TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new Error(isTimeout(error) ? `GitHub did not answer within ${REQUEST_TIMEOUT_MS / 1e3}s` : `could not reach GitHub: ${describeError(error)}`);
 	}
-	if (existing !== null) clearRuntime();
-	const configPath = options.configPath ?? defaultConfigPath;
-	const store = new ConfigStore(configPath, SEED_CONFIG);
-	store.load();
-	store.writeJsonSchema();
-	if (store.configError !== null) {
-		logger.error(`refusing to start: ${store.configError}`);
-		logger.info(`fix ${store.path}, or install the release that wrote it`);
-		process.exit(1);
+	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 : []
+	};
+}
+/** Every published release, newest first. Drafts and unusable entries are dropped. */
+async function fetchReleases(repo, context, perPage = 30) {
+	let response;
+	try {
+		response = await fetch(releasesApiUrl(repo, perPage), {
+			headers: apiHeaders(context),
+			signal: timeoutSignal(REQUEST_TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new Error(isTimeout(error) ? `GitHub did not answer within ${REQUEST_TIMEOUT_MS / 1e3}s` : `could not reach GitHub: ${describeError(error)}`);
 	}
-	if (store.pendingMigrations.length > 0) {
-		logger.error(`refusing to start: ${store.path} needs ${store.pendingMigrations.length} migration(s) before ${appVersion()} can use it`);
-		logger.info("run `home-hosted migrate` to see and apply them");
-		process.exit(1);
+	if (!response.ok) throw new Error(describeReleaseFailure(response.status, repo, null));
+	const body = await response.json();
+	if (!Array.isArray(body)) return [];
+	return body.filter((release) => release.draft !== true && typeof release.tag_name === "string").map((release) => ({
+		tag: release.tag_name,
+		assets: Array.isArray(release.assets) ? release.assets : [],
+		publishedAt: typeof release.published_at === "string" ? release.published_at : null
+	}));
+}
+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;
+}
+/** 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",
+			signal: timeoutSignal(DOWNLOAD_TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new Error(isTimeout(error) ? `the download stalled for ${DOWNLOAD_TIMEOUT_MS / 1e3}s: ${url}` : `could not reach ${url}: ${describeError(error)}`);
 	}
-	const secrets = new SecretsStore(defaultSecretsPath);
-	const auth = new AuthService(secrets, () => store.config.control.auth);
-	const tls = new TlsStore(defaultTlsDir);
-	const logFiles = new LogFiles(defaultLogsDir, () => store.config.logs);
-	const history = new HistoryStore(defaultHistoryPath);
-	const notifications = new NotificationService(secrets, () => store.config.notifications, () => store.config.logs);
-	const hostMonitor = new HostMonitor(() => store.config.host, (target) => resolveUserPath(resolveTemplate(target, {
-		projectDir,
-		dataRoot,
-		home: os.homedir()
-	})), notifications);
-	let onConfigRestored;
-	const backups = new BackupService({
-		dataRoot,
-		getConfig: () => store.config.backups,
-		getSources: () => ({
-			configPath: store.path,
-			secretsPath: secrets.path,
+	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(), "hh-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();
+	if (context.quiet !== true) context.io.write(`${context.io.style.dim(`downloaded ${formatBytes(received)}`)}\n`);
+	return {
+		dir,
+		file
+	};
+}
+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 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 = repoSlug(repo);
+	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);
+}
+/**
+* Tag ordering: `v1.2.3` beats `v1.2.2`, a prerelease loses to its release, and anything
+* that is not a version sorts below every version that is. Enough to answer "is this
+* release newer than the one the UI came from" without a semver dependency.
+*/
+function compareTags(a, b) {
+	const left = parseTag(a);
+	const right = parseTag(b);
+	if (left === null && right === null) return a.localeCompare(b);
+	if (left === null) return -1;
+	if (right === null) return 1;
+	for (let index = 0; index < 3; index++) {
+		const difference = (left.parts[index] ?? 0) - (right.parts[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0;
+	if (left.prerelease.length === 0) return 1;
+	if (right.prerelease.length === 0) return -1;
+	for (let index = 0; index < Math.max(left.prerelease.length, right.prerelease.length); index++) {
+		const one = left.prerelease[index];
+		const two = right.prerelease[index];
+		if (one === void 0) return -1;
+		if (two === void 0) return 1;
+		if (one === two) continue;
+		const numeric = /^\d+$/;
+		if (numeric.test(one) && numeric.test(two)) return Number(one) - Number(two);
+		if (numeric.test(one)) return -1;
+		if (numeric.test(two)) return 1;
+		return one.localeCompare(two);
+	}
+	return 0;
+}
+function parseTag(tag) {
+	const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/.exec(tag.trim());
+	if (match === null) return null;
+	return {
+		parts: [
+			Number(match[1]),
+			Number(match[2] ?? 0),
+			Number(match[3] ?? 0)
+		],
+		prerelease: match[4] === void 0 ? [] : match[4].split(".")
+	};
+}
+var DEFAULT_REPO, MAX_DOWNLOAD_BYTES, REQUEST_TIMEOUT_MS, DOWNLOAD_TIMEOUT_MS;
+var init_ui_release = __esmMin((() => {
+	DEFAULT_REPO = "NamesMT/home-hosted";
+	MAX_DOWNLOAD_BYTES = 536870912;
+	REQUEST_TIMEOUT_MS = 3e4;
+	DOWNLOAD_TIMEOUT_MS = 12e4;
+}));
+//#endregion
+//#region src/services/ui-update.ts
+/**
+* `ui.json` says which release this build came from. Anything else — an unofficial UI,
+* or one that never declared itself — is left for `home-hosted ui-update`.
+*/
+function officialTagFor(meta, runningVersion) {
+	if (meta === null || typeof meta.repo !== "string") return null;
+	const repo = parseRepoSlug(meta.repo);
+	if (repo === null || !isOwnRepo(repo)) return null;
+	return {
+		tag: `v${runningVersion}`,
+		repo: `${repo.owner}/${repo.name}`
+	};
+}
+async function syncOfficialUi(ui, runningVersion = appVersion()) {
+	if (!ui.custom) return { kind: "not-custom" };
+	const meta = ui.readMeta();
+	if (meta === null) return { kind: "no-identity" };
+	const repo = meta.repo === void 0 ? null : parseRepoSlug(meta.repo);
+	if (repo === null) return { kind: "no-identity" };
+	if (!isOwnRepo(repo)) return { kind: "foreign" };
+	const target = `v${runningVersion}`;
+	if (meta.tag === target) return {
+		kind: "current",
+		tag: target
+	};
+	const context = {
+		io: {
+			write: () => {},
+			style: {
+				bold: (t) => t,
+				dim: (t) => t,
+				green: (t) => t
+			}
+		},
+		version: runningVersion,
+		token: process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? null,
+		quiet: true
+	};
+	try {
+		const release = await fetchRelease(repo, target, context);
+		const names = release.assets.map((asset) => asset.name ?? "").filter(isUiAsset);
+		if (names.length === 0) throw new Error(`no UI asset in ${DEFAULT_REPO}@${release.tag}`);
+		const wanted = meta.asset ?? "";
+		const matched = wanted.length > 0 ? matchAsset(names, wanted) : {
+			ok: true,
+			name: names[0]
+		};
+		if (!matched.ok) throw new Error(matched.error);
+		const asset = release.assets.find((entry) => entry.name === matched.name);
+		if (asset === void 0) throw new Error(`no asset named ${matched.name} in ${release.tag}`);
+		const download = await downloadToTemp(assetDownloadUrl(asset), {
+			"accept": "application/octet-stream",
+			"user-agent": `home-hosted/${runningVersion}`
+		}, context);
+		try {
+			const result = await ui.install(download.file, matched.name.replace(/\.zip$/i, ""), release.tag);
+			if (!result.ok) throw new Error(result.error);
+		} finally {
+			(await import("node:fs")).rmSync(download.dir, {
+				recursive: true,
+				force: true
+			});
+		}
+		return {
+			kind: "updated",
+			tag: release.tag
+		};
+	} catch (error) {
+		return {
+			kind: "failed",
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+/**
+* The startup hook. Never awaited by the caller and never allowed to throw: the panel
+* serves the UI it already has while this runs, and the next request picks up the new
+* one, because `UiService.resolveDir()` is read per request.
+*/
+function autoUpdateOfficialUi(ui, runningVersion = appVersion()) {
+	if (!ui.custom) return;
+	const meta = ui.readMeta();
+	const plan = officialTagFor(meta, runningVersion);
+	if (plan === null || meta?.tag === plan.tag) return;
+	logger.info(`ui:      ${meta?.name ?? "custom UI"} ${meta?.version ?? ""} came from ${meta?.tag ?? "an unknown release"}; this panel is ${plan.tag} — updating`);
+	syncOfficialUi(ui, runningVersion).then((result) => {
+		if (result.kind === "updated") logger.info(`ui:      updated to ${result.tag} — refresh the browser`);
+		else if (result.kind === "failed") logger.warn(`ui:      could not update to ${plan.tag}: ${result.error}`);
+	}).catch((error) => {
+		logger.warn(`ui:      could not update: ${error instanceof Error ? error.message : String(error)}`);
+	});
+}
+var init_ui_update$1 = __esmMin((() => {
+	init_logger();
+	init_version();
+	init_ui_release();
+}));
+//#endregion
+//#region src/index.ts
+var src_exports = /* @__PURE__ */ __exportAll({
+	packageRoot: () => packageRoot,
+	runControlPlane: () => runControlPlane
+});
+function packageVersion() {
+	try {
+		return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+/** A probe target for a `lan` bind, which is not connectable as `0.0.0.0`. */
+function probeHostFor(bindHost) {
+	return bindHost === "0.0.0.0" || bindHost === "::" ? "127.0.0.1" : bindHost;
+}
+/**
+* Runs the control plane in *this* process until it is stopped. `home-hosted up`
+* detaches a child that calls this; `--foreground` (systemd, docker) calls it
+* directly.
+*/
+async function runControlPlane(options) {
+	const existing = readRuntime();
+	if (existing !== null && existing.pid !== process.pid && isProcessAlive$1(existing.pid)) {
+		logger.error(`already running (pid ${existing.pid}) at ${existing.url} — run \`home-hosted down\` first`);
+		process.exit(1);
+	}
+	if (existing !== null) clearRuntime();
+	const configPath = options.configPath ?? defaultConfigPath;
+	const store = new ConfigStore(configPath, SEED_CONFIG);
+	store.load();
+	store.writeJsonSchema();
+	if (store.configError !== null) {
+		logger.error(`refusing to start: ${store.configError}`);
+		logger.info(`fix ${store.path}, or install the release that wrote it`);
+		process.exit(1);
+	}
+	if (store.pendingMigrations.length > 0) {
+		logger.error(`refusing to start: ${store.path} needs ${store.pendingMigrations.length} migration(s) before ${appVersion()} can use it`);
+		logger.info("run `home-hosted migrate` to see and apply them");
+		process.exit(1);
+	}
+	const secrets = new SecretsStore(defaultSecretsPath);
+	const auth = new AuthService(secrets, () => store.config.control.auth);
+	const tls = new TlsStore(defaultTlsDir);
+	const logFiles = new LogFiles(defaultLogsDir, () => store.config.logs);
+	const history = new HistoryStore(defaultHistoryPath);
+	const notifications = new NotificationService(secrets, () => store.config.notifications, () => store.config.logs);
+	const hostMonitor = new HostMonitor(() => store.config.host, (target) => resolveUserPath(resolveTemplate(target, {
+		projectDir,
+		dataRoot,
+		home: os.homedir()
+	})), notifications);
+	let onConfigRestored;
+	const backups = new BackupService({
+		dataRoot,
+		getConfig: () => store.config.backups,
+		getSources: () => ({
+			configPath: store.path,
+			secretsPath: secrets.path,
 			tlsDir: tls.directory,
 			paths: resolveBackupPaths(store.servers, store.config.backups.includePaths)
 		}),
@@ -8064,6 +8574,8 @@ async function runControlPlane(options) {
 		dataRoot,
 		stockDir: path.join(packageRoot, "uis", "stock", "dist")
 	});
+	const uiRecovery = ui.recover();
+	if (uiRecovery.restored !== null) logger.warn(`ui:      restored the installed UI from ${uiRecovery.restored} — an earlier update was interrupted`);
 	const hub = new EventHub();
 	let app;
 	const token = newToken();
@@ -8192,6 +8704,7 @@ async function runControlPlane(options) {
 	if (ui.custom) {
 		const meta = ui.status().meta;
 		logger.warn(`custom UI in use${meta === null ? "" : ` (${meta.name}${meta.version === null ? "" : ` ${meta.version}`})`} — if it breaks, run \`home-hosted ui-revert\``);
+		autoUpdateOfficialUi(ui, runtime.version);
 	}
 	for (const warning of store.configWarnings) logger.warn(warning);
 	for (const entry of supervisor.views()) logger.info(`  ${entry.id.padEnd(12)} ${entry.config.command} ${entry.config.args.join(" ")}`.trimEnd());
@@ -8248,6 +8761,7 @@ var init_src = __esmMin((() => {
 	init_supervisor();
 	init_tls();
 	init_ui();
+	init_ui_update$1();
 	init_contracts();
 	packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 }));
@@ -9029,117 +9543,30 @@ var init_init = __esmMin((() => {
 var ui_switch_exports = /* @__PURE__ */ __exportAll({
 	DEFAULT_REPO: () => DEFAULT_REPO,
 	MAX_DOWNLOAD_BYTES: () => MAX_DOWNLOAD_BYTES,
+	apiHeaders: () => apiHeaders,
+	assetDownloadUrl: () => assetDownloadUrl,
+	compareTags: () => compareTags,
 	defaultReleaseTag: () => defaultReleaseTag,
+	describeError: () => describeError,
+	describeReleaseFailure: () => describeReleaseFailure,
+	downloadToTemp: () => downloadToTemp,
 	fallbackUiName: () => fallbackUiName,
+	fetchRelease: () => fetchRelease,
+	fetchReleases: () => fetchReleases,
+	formatBytes: () => formatBytes,
 	isGithubHost: () => isGithubHost,
 	isOwnRepo: () => isOwnRepo,
 	isUiAsset: () => isUiAsset,
 	matchAsset: () => matchAsset,
+	noAssetsMessage: () => noAssetsMessage,
 	parseFileSource: () => parseFileSource,
 	parseRepoSlug: () => parseRepoSlug,
 	releaseApiUrl: () => releaseApiUrl,
+	releasesApiUrl: () => releasesApiUrl,
+	repoSlug: () => repoSlug,
 	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;
-	}
-}
-/** 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,
@@ -9191,21 +9618,6 @@ async function uiSwitch(argv, io) {
 	}
 	await installFromUrl(assetDownloadUrl(chosen), fallbackUiName(chosen.name ?? ""), context);
 }
-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) {
@@ -9260,47 +9672,6 @@ async function installFromUrl(url, fallbackName, context) {
 		});
 	}
 }
-/** 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(), "hh-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));
@@ -9314,66 +9685,282 @@ async function installArchive(archivePath, fallbackName, context) {
 	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;
+var uiSwitchCommand;
+var init_ui_switch = __esmMin((() => {
+	init_io();
+	init_ui_release();
+	init_ui_release();
+	uiSwitchCommand = defineCommand({
+		meta: {
+			name: "ui-switch",
+			description: "install a UI from a release asset, a zip file or a URL"
+		},
+		run: async ({ rawArgs }) => {
+			await uiSwitch(rawArgs, {
+				write: (text) => process.stdout.write(text),
+				prompt,
+				style
+			});
+		}
+	});
+}));
+//#endregion
+//#region src/cli/ui-update.ts
+var ui_update_exports = /* @__PURE__ */ __exportAll({
+	impliedAsset: () => impliedAsset,
+	planUiUpdate: () => planUiUpdate,
+	uiUpdate: () => uiUpdate,
+	uiUpdateCommand: () => uiUpdateCommand,
+	usableCandidates: () => usableCandidates
+});
+/**
+* Which of a release list applies to what is installed. A candidate is only offered when
+* its assets carry the asset the person is actually using, so a UI is never swapped for a
+* different flavour by an update.
+*/
+function usableCandidates(releases, asset, order, currentTag) {
+	const found = [];
+	for (const release of releases) {
+		const matched = matchAsset(release.assets.map((entry) => entry.name ?? "").filter(isUiAsset), asset);
+		if (!matched.ok) continue;
+		if (currentTag !== null) {
+			const difference = compareTags(release.tag, currentTag);
+			if (order === "newer" && difference <= 0) continue;
+			if (order === "older" && difference >= 0) continue;
+		}
+		found.push({
+			tag: release.tag,
+			asset: matched.name
+		});
+	}
+	return found;
 }
-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;
+/** What the asset the UI is using is likely called, when it never declared one. */
+function impliedAsset(identity) {
+	if (identity.asset !== null && identity.asset.length > 0) return identity.asset;
+	if (identity.name.length > 0) return `${identity.name}.zip`;
+	return null;
 }
-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");
+/**
+* The decision, with no I/O in it: given what is installed and this panel's release,
+* what should `ui-update` do? `releases` is only consulted for someone else's UI.
+*/
+function planUiUpdate(installed, runningTag, releases = [], order = "newer") {
+	if (installed === null) return { kind: "stock" };
+	const repo = installed.repo === null ? null : parseRepoSlug(installed.repo);
+	if (repo === null) return {
+		kind: "unidentifiable",
+		identity: installed
+	};
+	if (isOwnRepo(repo)) return {
+		kind: "official",
+		identity: installed,
+		target: runningTag
+	};
+	const asset = impliedAsset(installed);
+	if (asset === null) return {
+		kind: "unidentifiable",
+		identity: installed
+	};
+	return {
+		kind: "choice",
+		identity: installed,
+		asset,
+		candidates: usableCandidates(releases, asset, order, installed.tag)
+	};
 }
-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`;
+/** `home-hosted ui-update` — see the module comment for the three cases. */
+async function uiUpdate(argv, io) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			tag: { type: "string" },
+			asset: { type: "string" },
+			token: { type: "string" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			},
+			old: { type: "boolean" },
+			check: { type: "boolean" },
+			repo: { type: "string" }
+		},
+		allowPositionals: false
+	});
+	const { appVersion } = await Promise.resolve().then(() => (init_version(), version_exports));
+	const { dataRoot } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+	const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
+	const context = {
+		io: {
+			write: io.write,
+			style: io.style
+		},
+		ask: process.stdin.isTTY === true && values.yes !== true ? io.prompt : null,
+		version: appVersion(),
+		token: values.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? null
+	};
+	const installed = identityOf(new UiService({ dataRoot }).status().meta);
+	if (installed === null) {
+		io.write(`${io.style.dim("the stock UI is in use — it ships with the panel and is always current")}\n`);
+		return;
 	}
-	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}`;
+	if (values.repo !== void 0) {
+		const repo = parseRepoSlug(values.repo);
+		if (repo === null) throw new Error(`invalid --repo "${values.repo}" — expected an "owner/name" slug, e.g. ${DEFAULT_REPO}`);
+		installed.repo = repoSlug(repo);
+	}
+	const order = values.old === true ? "older" : "newer";
+	const repo = installed.repo === null ? null : parseRepoSlug(installed.repo);
+	if (values.tag !== void 0 && repo === null) throw new Error(["--tag needs a repository to fetch from, and this UI does not declare one", `  pass it: home-hosted ui-update --repo ${DEFAULT_REPO} --tag ${values.tag}`].join("\n"));
+	if (values.check === true && repo !== null) {
+		if (isOwnRepo(repo)) {
+			printCheck(io, installed, values.tag ?? `v${context.version}`);
+			return;
+		}
+		const releases = await fetchReleases(repo, context);
+		const asset = impliedAsset(installed);
+		printCheck(io, installed, null, asset === null ? [] : usableCandidates(releases, asset, order, installed.tag));
+		return;
+	}
+	if (values.tag !== void 0 && repo !== null) {
+		await installTag(repo, values.asset ?? installed.asset ?? null, values.tag, context);
+		return;
+	}
+	let releases = [];
+	if (repo !== null && !isOwnRepo(repo)) releases = await fetchReleases(repo, context);
+	const plan = planUiUpdate(installed, `v${context.version}`, releases, order);
+	if (plan.kind === "unidentifiable") {
+		io.write(`${io.style.bold("this UI does not say where it came from")} — nothing to follow automatically\n`);
+		printIdentity(io, plan.identity);
+		io.write(`  ${io.style.dim("point it at a repo to make this work: home-hosted ui-update --repo owner/name")}\n`);
+		return;
+	}
+	if (plan.kind === "official") {
+		if (plan.identity.tag === plan.target) {
+			io.write(`${io.style.green("already current")} — ${io.style.bold(plan.identity.name)} is at ${plan.target}\n`);
+			return;
+		}
+		io.write(`${io.style.bold(`${plan.identity.name} ${plan.identity.version ?? ""}`.trim())} is on ${plan.identity.tag ?? "an unknown tag"}; this panel is ${plan.target} — updating\n`);
+		await installTag(repo, plan.identity.asset ?? values.asset ?? null, plan.target, context);
+		return;
+	}
+	if (plan.kind !== "choice") return;
+	io.write(`${io.style.bold(plan.identity.name)} ${plan.identity.version ?? ""} — ${repoSlug(repo)}@${plan.identity.tag ?? "unknown tag"}\n`);
+	io.write(`  ${io.style.dim(`asset: ${plan.asset}`)}\n`);
+	if (plan.candidates.length === 0) {
+		const direction = order === "newer" ? "newer" : "older";
+		io.write(`no ${direction} releases carry ${plan.asset}\n`);
+		if (order === "newer") io.write(`  ${io.style.dim("list older releases with: home-hosted ui-update --old")}\n`);
+		return;
+	}
+	const chosen = await chooseCandidate(plan.candidates, context, order);
+	if (chosen === null) {
+		io.write("cancelled — nothing was installed\n");
+		return;
+	}
+	await installTag(repo, chosen.asset, chosen.tag, context);
 }
-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 identityOf(meta) {
+	if (meta === null) return null;
+	return {
+		name: meta.name ?? "custom-ui",
+		version: meta.version ?? null,
+		repo: meta.repo ?? null,
+		tag: meta.tag ?? null,
+		asset: meta.asset ?? null,
+		unix: meta.unix ?? null
+	};
 }
-function tooLargeMessage(bytes) {
-	return `the download is ${formatBytes(bytes)}, larger than the ${MAX_DOWNLOAD_BYTES / 1024 / 1024}MB a UI may be`;
+function printIdentity(io, identity) {
+	io.write(`  name     ${identity.name}\n`);
+	io.write(`  version  ${identity.version ?? "unspecified"}\n`);
+	io.write(`  repo     ${identity.repo ?? "unspecified"}${identity.tag === null ? "" : ` @ ${identity.tag}`}\n`);
+	if (identity.unix !== null) io.write(`  built    ${(/* @__PURE__ */ new Date(identity.unix * 1e3)).toISOString()}\n`);
 }
-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 printCheck(io, identity, target, candidates = []) {
+	if (target !== null) {
+		if (identity.tag === target) {
+			io.write(`${io.style.green("up to date")} — ${identity.version ?? identity.name} at ${target}\n`);
+			return;
+		}
+		io.write(`update available: ${identity.tag ?? "unknown"} → ${target}\n`);
+		return;
+	}
+	if (candidates.length === 0) {
+		io.write(`up to date — no release carries ${identity.asset ?? identity.name}.zip\n`);
+		return;
+	}
+	io.write(`${candidates.length} release(s) available:\n`);
+	for (const candidate of candidates) io.write(`  ${candidate.tag}  ${io.style.dim(candidate.asset)}\n`);
 }
-function describeError(error) {
-	return error instanceof Error ? error.message : String(error);
+async function chooseCandidate(candidates, context, order) {
+	const headline = order === "newer" ? "Newer releases" : "Older releases";
+	const { io } = context;
+	io.write(`${io.style.bold(headline)}\n`);
+	for (const [index, candidate] of candidates.entries()) io.write(`  ${index + 1}) ${candidate.tag}\n`);
+	if (context.ask === null) {
+		if (candidates.length === 1) return candidates[0];
+		throw new Error([
+			`${candidates.length} releases are available and this session cannot ask which one:`,
+			...candidates.map((candidate) => `  ${candidate.tag}`),
+			"  run it in a terminal, or pass --tag <tag>"
+		].join("\n"));
+	}
+	for (;;) {
+		const answer = (await context.ask(`Select a release [1-${candidates.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 <= candidates.length) return candidates[index - 1];
+		}
+		const byTag = candidates.find((candidate) => candidate.tag === answer);
+		if (byTag !== void 0) return byTag;
+		io.write(`  ${io.style.dim(`no such choice — enter 1-${candidates.length} or a tag`)}\n`);
+	}
 }
-var DEFAULT_REPO, MAX_DOWNLOAD_BYTES, uiSwitchCommand;
-var init_ui_switch = __esmMin((() => {
+/** Fetches one release's asset and installs it, reporting what landed. */
+async function installTag(repo, wantedAsset, tag, context) {
+	const release = await fetchRelease(repo, tag, context);
+	const names = release.assets.map((asset) => asset.name ?? "").filter(isUiAsset);
+	let assetName;
+	if (wantedAsset !== null && wantedAsset.length > 0) {
+		const matched = matchAsset(names, wantedAsset);
+		if (!matched.ok) throw new Error(`${matched.error}\n  in ${repo.owner}/${repo.name}@${release.tag}`);
+		assetName = matched.name;
+	} else if (names.length === 1) assetName = names[0];
+	else throw new Error(`${names.length} UI assets in ${repo.owner}/${repo.name}@${release.tag} — name one with --asset`);
+	const download = await downloadToTemp(assetDownloadUrl(release.assets.find((entry) => entry.name === assetName)), {
+		"accept": "application/octet-stream",
+		"user-agent": `home-hosted/${context.version}`,
+		...context.token !== null && context.token.length > 0 ? { authorization: `Bearer ${context.token}` } : {}
+	}, context);
+	try {
+		const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
+		const { dataRoot } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+		const result = await new UiService({ dataRoot }).install(download.file, assetName);
+		if (!result.ok) throw new Error(`nothing was installed: ${result.error}`);
+		const { meta } = result;
+		const { io } = context;
+		io.write(`${io.style.green("UI updated")} — ${meta.name} ${meta.version ?? ""} at ${release.tag}\n`);
+		io.write(`  ${io.style.dim("refresh the browser to see it")}\n`);
+	} finally {
+		fs.rmSync(download.dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+var uiUpdateCommand;
+var init_ui_update = __esmMin((() => {
 	init_io();
-	DEFAULT_REPO = "NamesMT/home-hosted";
-	MAX_DOWNLOAD_BYTES = 536870912;
-	uiSwitchCommand = defineCommand({
+	init_ui_release();
+	uiUpdateCommand = defineCommand({
 		meta: {
-			name: "ui-switch",
-			description: "install a UI from a release asset, a zip file or a URL"
+			name: "ui-update",
+			description: "update the installed UI to match this panel, or pick a release"
 		},
 		run: async ({ rawArgs }) => {
-			await uiSwitch(rawArgs, {
+			await uiUpdate(rawArgs, {
 				write: (text) => process.stdout.write(text),
 				prompt,
 				style
@@ -9448,6 +10035,7 @@ var SYNOPSIS = {
 	"migrate": "home-hosted migrate",
 	"init": "home-hosted init",
 	"ui-switch": "home-hosted ui-switch",
+	"ui-update": "home-hosted ui-update",
 	"ui-revert": "home-hosted ui-revert"
 };
 var SUMMARIES = {
@@ -9460,6 +10048,7 @@ var SUMMARIES = {
 	"migrate": "bring the config up to this release's schema",
 	"init": "scaffold a project that keeps its state in the repo",
 	"ui-switch": "install a UI from a release asset, a zip file or a URL",
+	"ui-update": "bring the installed UI up to date, or pick a release",
 	"ui-revert": "go back to the stock control panel UI"
 };
 /** Every section lays its left column out at this width, so the two views align. */
@@ -9514,6 +10103,18 @@ var UI_SWITCH_SECTION = {
 		["-y, --yes", "take the only asset instead of asking"]
 	]
 };
+var UI_UPDATE_SECTION = {
+	heading: "Options for ui-update",
+	lines: [
+		["--check", "report whether an update is available and install nothing"],
+		["--tag <tag>", "install that release instead of asking"],
+		["--asset <name>", "asset to install (defaults to the one in use)"],
+		["--old", "list older releases instead of newer ones"],
+		["--repo <owner/name>", "for a UI that does not declare its own repo"],
+		["--token <token>", "GitHub token (or GITHUB_TOKEN / GH_TOKEN)"],
+		["-y, --yes", "take the only release instead of asking"]
+	]
+};
 var EVERYWHERE_SECTION = {
 	heading: "Everywhere",
 	lines: [
@@ -9588,7 +10189,8 @@ var SECTIONS = {
 	"set-token": SET_TOKEN_SECTION,
 	"migrate": MIGRATE_SECTION,
 	"init": INIT_SECTION,
-	"ui-switch": UI_SWITCH_SECTION
+	"ui-switch": UI_SWITCH_SECTION,
+	"ui-update": UI_UPDATE_SECTION
 };
 /**
 * `home-hosted <command> --help`: the usage line, that command's own options,
@@ -9634,6 +10236,7 @@ var COMMANDS = {
 	"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-update": () => Promise.resolve().then(() => (init_ui_update(), ui_update_exports)).then((module) => module.uiUpdateCommand),
 	"ui-revert": () => Promise.resolve().then(() => (init_ui_revert(), ui_revert_exports)).then((module) => module.uiRevertCommand)
 };
 var rootCommand = defineCommand({