yaport 0.1.0 → 0.1.2

package/dist/server/cli.js

@@ -1,12 +1,14 @@
+import { homedir, tmpdir } from "node:os";
 import express from "express";
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { statSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ZodError, z } from "zod";
 import { createHash, randomUUID } from "node:crypto";
+import { isIP } from "node:net";
+import { promisify } from "node:util";
 //#region src/shared/sshTimeouts.ts
 var CONNECT_TIMEOUT_SECONDS_OPTIONS = [
 	8,
@@ -35,7 +37,7 @@ var connectionEndpointSchema = z.object({
 var connectTimeoutSchema = timeoutChoiceSchema(CONNECT_TIMEOUT_SECONDS_OPTIONS, "连接超时");
 var commandTimeoutSchema = timeoutChoiceSchema(COMMAND_TIMEOUT_SECONDS_OPTIONS, "命令超时");
 var machineInputSchema = z.object({
-	name: z.string().trim().min(1).max(80),
+	name: z.preprocess((value) => typeof value === "string" && value.trim() === "" ? void 0 : value, z.string().trim().max(80).optional()),
 	host: connectionEndpointSchema.shape.host,
 	password: connectionEndpointSchema.shape.password,
 	port: connectionEndpointSchema.shape.port,
@@ -43,10 +45,20 @@ var machineInputSchema = z.object({
 	connectTimeoutSeconds: connectTimeoutSchema.optional(),
 	commandTimeoutSeconds: commandTimeoutSchema.optional(),
 	jumpHosts: z.array(connectionEndpointSchema).max(2).optional()
+}).superRefine((input, context) => {
+	validateEndpointUser(input, context, ["user"]);
+	input.jumpHosts?.forEach((jumpHost, index) => {
+		validateEndpointUser(jumpHost, context, [
+			"jumpHosts",
+			index,
+			"user"
+		]);
+	});
 }).transform((input) => {
 	const connectTimeoutSeconds = input.connectTimeoutSeconds ?? 15;
 	return {
 		...input,
+		name: input.name ?? defaultMachineName(input),
 		connectTimeoutSeconds,
 		commandTimeoutSeconds: input.commandTimeoutSeconds ?? defaultCommandTimeoutSeconds(connectTimeoutSeconds)
 	};
@@ -61,6 +73,18 @@ var emptyMachineFile = { machines: [] };
 function timeoutChoiceSchema(options, label) {
 	return z.coerce.number().int().refine((value) => options.includes(value), { message: `${label}必须是 ${options.join(" / ")} 秒之一。` });
 }
+function validateEndpointUser(endpoint, context, path) {
+	if (!endpoint.user && isIP(endpoint.host)) context.addIssue({
+		code: "custom",
+		path,
+		message: "IP 地址连接必须填写用户；OpenSSH alias 可以留空。"
+	});
+}
+function defaultMachineName(endpoint) {
+	const userPrefix = endpoint.user ? `${endpoint.user}@` : "";
+	const portSuffix = endpoint.port ? `:${endpoint.port}` : "";
+	return `${userPrefix}${endpoint.host}${portSuffix}`;
+}
 var JsonMachineStore = class {
 	filePath;
 	constructor(filePath) {
@@ -82,6 +106,29 @@ var JsonMachineStore = class {
 		await this.write({ machines: [...file.machines, machine] });
 		return machine;
 	}
+	async delete(id) {
+		const file = await this.read();
+		const machines = file.machines.filter((machine) => machine.id !== id);
+		if (machines.length === file.machines.length) return false;
+		await this.write({ machines });
+		return true;
+	}
+	async update(id, input) {
+		const file = await this.read();
+		const machineIndex = file.machines.findIndex((machine) => machine.id === id);
+		if (machineIndex === -1) return;
+		const existingMachine = file.machines[machineIndex];
+		const machine = {
+			...existingMachine,
+			...preserveEndpointSecrets(input, existingMachine),
+			id: existingMachine.id,
+			createdAt: existingMachine.createdAt
+		};
+		const machines = [...file.machines];
+		machines[machineIndex] = machine;
+		await this.write({ machines });
+		return machine;
+	}
 	async read() {
 		try {
 			const raw = await readFile(this.filePath, "utf8");
@@ -104,22 +151,126 @@ var JsonMachineStore = class {
 		await chmod(this.filePath, 384);
 	}
 };
+function preserveEndpointSecrets(input, existingMachine) {
+	const nextMachine = { ...input };
+	if (!nextMachine.password && existingMachine.password && sameEndpoint(nextMachine, existingMachine)) nextMachine.password = existingMachine.password;
+	if (nextMachine.jumpHosts) nextMachine.jumpHosts = nextMachine.jumpHosts.map((jumpHost, index) => {
+		const existingJumpHost = existingMachine.jumpHosts?.[index];
+		if (!jumpHost.password && existingJumpHost?.password && sameEndpoint(jumpHost, existingJumpHost)) return {
+			...jumpHost,
+			password: existingJumpHost.password
+		};
+		return jumpHost;
+	});
+	return nextMachine;
+}
+function sameEndpoint(first, second) {
+	return first.host === second.host && first.port === second.port && first.user === second.user;
+}
+//#endregion
+//#region src/server/caddyExternalRoutes.ts
+function parseCaddyExternalRoutes(caddyfile) {
+	return extractSiteAddresses(stripComments$1(caddyfile)).flatMap((address) => ({
+		port: address.port,
+		serverName: address.serverName,
+		source: "caddy",
+		url: caddyRouteUrl(address)
+	}));
+}
+function extractSiteAddresses(caddyfile) {
+	const addresses = [];
+	for (const header of extractTopLevelBlockHeaders(caddyfile)) for (const rawAddress of header.split(",")) {
+		const address = parseCaddyAddress(rawAddress.trim());
+		if (address) addresses.push(address);
+	}
+	return addresses;
+}
+function extractTopLevelBlockHeaders(caddyfile) {
+	const headers = [];
+	let depth = 0;
+	let lineStart = 0;
+	for (let index = 0; index < caddyfile.length; index += 1) {
+		const character = caddyfile[index];
+		if (character === "{") {
+			if (depth === 0) {
+				const header = caddyfile.slice(lineStart, index).trim();
+				if (header) headers.push(header);
+			}
+			depth += 1;
+			continue;
+		}
+		if (character === "}") {
+			depth = Math.max(0, depth - 1);
+			continue;
+		}
+		if (character === "\n" && depth === 0) lineStart = index + 1;
+	}
+	return headers;
+}
+function parseCaddyAddress(rawAddress) {
+	const candidate = rawAddress.trim();
+	if (candidate.startsWith("http://") || candidate.startsWith("https://")) return parseUrlAddress(candidate);
+	const address = candidate.replace(/\/.*$/, "").trim();
+	if (!address || address === "_" || address.includes("$") || address.startsWith("*.") || address.startsWith(":")) return;
+	const portMatch = address.match(/^(.+):(\d+)$/);
+	const serverName = portMatch ? portMatch[1] : address;
+	const port = portMatch ? Number(portMatch[2]) : 443;
+	if (!isDisplayableServerName$1(serverName) || !isValidPort(port)) return;
+	return {
+		port,
+		scheme: port === 443 ? "https" : "http",
+		serverName
+	};
+}
+function parseUrlAddress(address) {
+	try {
+		const url = new URL(address);
+		const scheme = url.protocol === "https:" ? "https" : "http";
+		const serverName = url.hostname;
+		const port = url.port ? Number(url.port) : scheme === "https" ? 443 : 80;
+		if (!isDisplayableServerName$1(serverName) || !isValidPort(port)) return;
+		return {
+			port,
+			scheme,
+			serverName
+		};
+	} catch {
+		return;
+	}
+}
+function stripComments$1(config) {
+	return config.split("\n").map((line) => line.replace(/(^|[^\\])#.*/, "$1")).join("\n");
+}
+function isDisplayableServerName$1(serverName) {
+	return Boolean(serverName) && !serverName.includes("*") && /^[A-Za-z0-9.-]+$/.test(serverName);
+}
+function isValidPort(port) {
+	return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+function caddyRouteUrl(address) {
+	if (address.scheme === "https" && address.port === 443) return `https://${address.serverName}`;
+	return `${address.scheme}://${address.serverName}:${address.port}`;
+}
 //#endregion
 //#region src/server/nginxExternalRoutes.ts
-function parseNginxExternalRoutes(config) {
+function parseNginxExternalRoutes(config, source = "nginx") {
 	return extractServerBlocks(stripComments(config)).flatMap((block) => {
 		const validNames = block.serverNames.filter(isDisplayableServerName);
 		return block.listens.flatMap((listen) => validNames.map((serverName) => ({
 			port: listen.port,
 			serverName,
-			source: "nginx",
+			source,
 			url: routeUrl(serverName, listen)
 		})));
 	});
 }
 function attachExternalRoutes(ports, routes) {
 	const routesByPort = /* @__PURE__ */ new Map();
-	for (const route of routes) routesByPort.set(route.port, [...routesByPort.get(route.port) ?? [], route]);
+	for (const route of routes) {
+		const currentRoutes = routesByPort.get(route.port) ?? [];
+		if (currentRoutes.some((currentRoute) => sameExternalRoute(currentRoute, route))) continue;
+		routesByPort.set(route.port, [...currentRoutes, route]);
+	}
 	return ports.map((port) => {
 		const externalRoutes = routesByPort.get(port.port);
 		if (!externalRoutes?.length) return port;
@@ -129,6 +280,9 @@ function attachExternalRoutes(ports, routes) {
 		};
 	});
 }
+function sameExternalRoute(left, right) {
+	return left.port === right.port && left.serverName === right.serverName && left.source === right.source && left.url === right.url;
+}
 function stripComments(config) {
 	return config.split("\n").map((line) => line.replace(/(^|[^\\])#.*/, "$1")).join("\n");
 }
@@ -246,6 +400,33 @@ function parseProcess(value) {
 	};
 }
 //#endregion
+//#region src/server/sshConnection.ts
+var SSH_CONTROL_SOCKET_DIRECTORY = "/tmp/yaport-ssh";
+async function ensureSshControlSocketDirectory() {
+	await mkdir(SSH_CONTROL_SOCKET_DIRECTORY, {
+		recursive: true,
+		mode: 448
+	});
+}
+function buildSshControlPath(machine) {
+	return join(SSH_CONTROL_SOCKET_DIRECTORY, machineConnectionHash(machine).slice(0, 40));
+}
+function machineConnectionHash(machine) {
+	return createHash("sha256").update(JSON.stringify(machineConnectionIdentity(machine))).digest("hex");
+}
+function machineConnectionIdentity(machine) {
+	return {
+		host: machine.host,
+		port: machine.port,
+		user: machine.user,
+		jumpHosts: machine.jumpHosts?.map((jumpHost) => ({
+			host: jumpHost.host,
+			port: jumpHost.port,
+			user: jumpHost.user
+		}))
+	};
+}
+//#endregion
 //#region src/server/sshPortInventory.ts
 var SshCommandError = class extends Error {
 	stderr;
@@ -255,9 +436,8 @@ var SshCommandError = class extends Error {
 		this.name = "SshCommandError";
 	}
 };
-var CONTROL_SOCKET_DIRECTORY = "/tmp/yaport-ssh";
-var NGINX_EXTERNAL_ROUTE_CACHE_MS = 300 * 1e3;
-var nginxExternalRouteCache = /* @__PURE__ */ new Map();
+var PROXY_EXTERNAL_ROUTE_CACHE_MS = 300 * 1e3;
+var proxyExternalRouteCache = /* @__PURE__ */ new Map();
 async function collectPortInventory(machine, runner = runSsh, options = {}) {
 	const sshOptions = buildSshOptions(machine);
 	const sshArgsOptions = await buildSshArgsOptions(machine, options);
@@ -267,7 +447,7 @@ async function collectPortInventory(machine, runner = runSsh, options = {}) {
 		"-lntup"
 	], sshArgsOptions), sshOptions);
 	const ports = parseSsListeningPorts(stdout);
-	const [portsWithCommandsResult, externalRoutesResult] = await Promise.allSettled([attachProcessCommands(machine, ports, runner, sshOptions, sshArgsOptions), readCachedNginxExternalRoutes(machine, runner, sshOptions, sshArgsOptions)]);
+	const [portsWithCommandsResult, externalRoutesResult] = await Promise.allSettled([attachProcessCommands(machine, ports, runner, sshOptions, sshArgsOptions), readCachedProxyExternalRoutes(machine, ports, runner, sshOptions, sshArgsOptions)]);
 	return attachExternalRoutes(portsWithCommandsResult.status === "fulfilled" ? portsWithCommandsResult.value : ports, externalRoutesResult.status === "fulfilled" ? externalRoutesResult.value : []);
 }
 async function attachProcessCommands(machine, ports, runner, sshOptions, sshArgsOptions) {
@@ -294,24 +474,33 @@ async function attachProcessCommands(machine, ports, runner, sshOptions, sshArgs
 		return ports;
 	}
 }
-async function readCachedNginxExternalRoutes(machine, runner, sshOptions, sshArgsOptions) {
+async function readCachedProxyExternalRoutes(machine, ports, runner, sshOptions, sshArgsOptions) {
+	const proxySources = proxySourcesForPorts(ports);
+	if (proxySources.length === 0) return [];
 	const cacheKey = machineConnectionCacheKey(machine);
-	const cached = nginxExternalRouteCache.get(cacheKey);
+	const cached = proxyExternalRouteCache.get(cacheKey);
 	if (cached && cached.expiresAt > Date.now()) return cached.routes;
-	try {
-		const routes = parseNginxExternalRoutes((await runner(buildSshArgs(machine, ["nginx", "-T"], sshArgsOptions), sshOptions)).stdout);
-		nginxExternalRouteCache.set(cacheKey, {
-			expiresAt: Date.now() + NGINX_EXTERNAL_ROUTE_CACHE_MS,
-			routes
-		});
-		return routes;
-	} catch {
-		nginxExternalRouteCache.set(cacheKey, {
-			expiresAt: Date.now() + NGINX_EXTERNAL_ROUTE_CACHE_MS,
-			routes: []
-		});
-		return [];
+	const routes = (await Promise.allSettled(proxySources.map((source) => readProxyExternalRoutes(machine, source, runner, sshOptions, sshArgsOptions)))).flatMap((result) => result.status === "fulfilled" ? result.value : []);
+	proxyExternalRouteCache.set(cacheKey, {
+		expiresAt: Date.now() + PROXY_EXTERNAL_ROUTE_CACHE_MS,
+		routes
+	});
+	return routes;
+}
+function proxySourcesForPorts(ports) {
+	const sources = /* @__PURE__ */ new Set();
+	for (const port of ports) {
+		const processName = port.processName?.toLowerCase() ?? "";
+		if (processName.includes("nginx")) sources.add("nginx");
+		if (processName.includes("openresty")) sources.add("openresty");
+		if (processName.includes("tengine")) sources.add("tengine");
+		if (processName.includes("caddy")) sources.add("caddy");
 	}
+	return [...sources];
+}
+async function readProxyExternalRoutes(machine, source, runner, sshOptions, sshArgsOptions) {
+	if (source === "caddy") return parseCaddyExternalRoutes((await runner(buildSshArgs(machine, ["cat", "/etc/caddy/Caddyfile"], sshArgsOptions), sshOptions)).stdout);
+	return parseNginxExternalRoutes((await runner(buildSshArgs(machine, [source, "-T"], sshArgsOptions), sshOptions)).stdout, source);
 }
 function buildSshOptions(machine) {
 	const entries = buildAskPassEntries(machine);
@@ -332,11 +521,8 @@ function parsePsCommands(output) {
 }
 async function buildSshArgsOptions(machine, options) {
 	if (!options.reuseConnection) return {};
-	await mkdir(CONTROL_SOCKET_DIRECTORY, {
-		recursive: true,
-		mode: 448
-	});
-	return { controlPath: join(CONTROL_SOCKET_DIRECTORY, machineConnectionHash(machine).slice(0, 40)) };
+	await ensureSshControlSocketDirectory();
+	return { controlPath: buildSshControlPath(machine) };
 }
 function buildSshArgs(machine, command, options = {}) {
 	const hasPasswords = buildAskPassEntries(machine).length > 0;
@@ -344,32 +530,17 @@ function buildSshArgs(machine, command, options = {}) {
 	if (hasPasswords) args.push("-o", "PasswordAuthentication=yes", "-o", "KbdInteractiveAuthentication=yes", "-o", "NumberOfPasswordPrompts=1");
 	args.push("-o", `ConnectTimeout=${machine.connectTimeoutSeconds ?? 15}`);
 	if (options.controlPath) args.push("-o", "ControlMaster=auto", "-o", "ControlPersist=5m", "-o", `ControlPath=${options.controlPath}`);
-	if (machine.jumpHosts?.length) args.push("-J", machine.jumpHosts.map(formatJumpHost).join(","));
+	if (machine.jumpHosts?.length) args.push("-J", machine.jumpHosts.map(formatJumpHost$1).join(","));
 	if (machine.port) args.push("-p", String(machine.port));
 	return [
 		...args,
-		formatSshTarget(machine),
+		formatSshTarget$1(machine),
 		...command
 	];
 }
 function machineConnectionCacheKey(machine) {
 	return `${machine.id}:${machineConnectionHash(machine)}`;
 }
-function machineConnectionHash(machine) {
-	return createHash("sha256").update(JSON.stringify(machineConnectionIdentity(machine))).digest("hex");
-}
-function machineConnectionIdentity(machine) {
-	return {
-		host: machine.host,
-		port: machine.port,
-		user: machine.user,
-		jumpHosts: machine.jumpHosts?.map((jumpHost) => ({
-			host: jumpHost.host,
-			port: jumpHost.port,
-			user: jumpHost.user
-		}))
-	};
-}
 function buildAskPassEntries(machine) {
 	return [...machine.jumpHosts ?? [], machine].flatMap((endpoint) => endpoint.password ? [{
 		password: endpoint.password,
@@ -379,11 +550,11 @@ function buildAskPassEntries(machine) {
 function buildPromptKeys(endpoint) {
 	return [...endpoint.user ? [`${endpoint.user}@${endpoint.host}`] : [], endpoint.host];
 }
-function formatJumpHost(jumpHost) {
-	const target = formatSshTarget(jumpHost);
+function formatJumpHost$1(jumpHost) {
+	const target = formatSshTarget$1(jumpHost);
 	return jumpHost.port ? `${target}:${jumpHost.port}` : target;
 }
-function formatSshTarget(target) {
+function formatSshTarget$1(target) {
 	return target.user ? `${target.user}@${target.host}` : target.host;
 }
 async function runSsh(args, options) {
@@ -486,6 +657,61 @@ process.exit(1);
 `;
 }
 //#endregion
+//#region src/server/sshTerminal.ts
+var UnsupportedTerminalError = class extends Error {
+	constructor(platform) {
+		super(`当前系统暂不支持自动打开 Terminal：${platform}`);
+		this.name = "UnsupportedTerminalError";
+	}
+};
+function buildInteractiveSshArgs(machine, options = {}) {
+	const args = [];
+	if (options.controlPath) args.push("-o", "ControlMaster=auto", "-o", "ControlPersist=5m", "-o", `ControlPath=${options.controlPath}`);
+	if (machine.jumpHosts?.length) args.push("-J", machine.jumpHosts.map(formatJumpHost).join(","));
+	if (machine.port) args.push("-p", String(machine.port));
+	args.push(formatSshTarget(machine));
+	return args;
+}
+async function openSshTerminal(machine, options = {}) {
+	const platform = options.platform ?? process.platform;
+	if (platform !== "darwin") throw new UnsupportedTerminalError(platform);
+	const spawnCommand = options.spawnCommand ?? spawn;
+	await ensureSshControlSocketDirectory();
+	await runCommand(spawnCommand, "osascript", [
+		"-e",
+		"tell application \"Terminal\" to activate",
+		"-e",
+		`tell application "Terminal" to do script ${appleScriptString(["ssh", ...buildInteractiveSshArgs(machine, { controlPath: buildSshControlPath(machine) })].map(shellQuote).join(" "))}`
+	]);
+}
+function runCommand(spawnCommand, command, args) {
+	return new Promise((resolve, reject) => {
+		const child = spawnCommand(command, args, { stdio: "ignore" });
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`打开 Terminal 失败，退出码 ${code ?? "unknown"}。`));
+		});
+	});
+}
+function formatJumpHost(jumpHost) {
+	const target = formatSshTarget(jumpHost);
+	return jumpHost.port ? `${target}:${jumpHost.port}` : target;
+}
+function formatSshTarget(target) {
+	return target.user ? `${target.user}@${target.host}` : target.host;
+}
+function shellQuote(value) {
+	if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function appleScriptString(value) {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+//#endregion
 //#region src/server/app.ts
 function createApp(dependencies) {
 	const app = express();
@@ -502,6 +728,36 @@ function createApp(dependencies) {
 		const machine = await dependencies.machineStore.add(input);
 		response.status(201).json({ machine: stripMachineSecrets$1(machine) });
 	}));
+	app.put("/api/machines/:id", asyncHandler(async (request, response) => {
+		const input = machineInputSchema.parse(request.body);
+		const machine = await dependencies.machineStore.update(String(request.params.id), input);
+		if (!machine) {
+			response.status(404).json({ error: "Remote machine not found." });
+			return;
+		}
+		response.json({ machine: stripMachineSecrets$1(machine) });
+	}));
+	app.delete("/api/machines/:id", asyncHandler(async (request, response) => {
+		if (!await dependencies.machineStore.delete(String(request.params.id))) {
+			response.status(404).json({ error: "Remote machine not found." });
+			return;
+		}
+		response.status(204).send();
+	}));
+	app.post("/api/machines/:id/terminal", asyncHandler(async (request, response) => {
+		const machineId = String(request.params.id);
+		const machine = await dependencies.machineStore.get(machineId);
+		if (!machine) {
+			response.status(404).json({ error: "Remote machine not found." });
+			return;
+		}
+		if (!dependencies.openSshTerminal) {
+			response.status(501).json({ error: "Terminal opening is not configured." });
+			return;
+		}
+		await dependencies.openSshTerminal(machine);
+		response.json({ ok: true });
+	}));
 	app.get("/api/machines/:id/ports", asyncHandler(async (request, response) => {
 		const machineId = String(request.params.id);
 		const machine = await dependencies.machineStore.get(machineId);
@@ -535,6 +791,13 @@ function createApp(dependencies) {
 			});
 			return;
 		}
+		if (error instanceof UnsupportedTerminalError) {
+			response.status(501).json({
+				error: "Unsupported terminal.",
+				message: error.message
+			});
+			return;
+		}
 		response.status(500).json({ error: "Unexpected server error." });
 	});
 	return app;
@@ -631,7 +894,8 @@ function openBrowser(url) {
 async function createYaportHttpApp(mode, dataFile) {
 	const app = createApp({
 		machineStore: new JsonMachineStore(dataFile),
-		collectPortInventory: (machine, options) => collectPortInventory(machine, void 0, options)
+		collectPortInventory: (machine, options) => collectPortInventory(machine, void 0, options),
+		openSshTerminal
 	});
 	if (mode === "production") {
 		const clientDirectory = resolve(dirname(fileURLToPath(import.meta.url)), "../client");
@@ -670,16 +934,235 @@ function formatUrlHost(host) {
 	return host;
 }
 //#endregion
+//#region src/server/serviceManager.ts
+var execFileAsync = promisify(execFile);
+var SERVICE_LABEL = "com.boenfu.yaport";
+var SYSTEMD_SERVICE_NAME = "yaport.service";
+var UnsupportedServicePlatformError = class extends Error {
+	constructor(platform) {
+		super(`System service is only supported on macOS and Linux. Current platform: ${platform}.`);
+	}
+};
+async function installYaportService(options) {
+	const definition = buildYaportServiceDefinition(options);
+	const runCommand = options.runCommand ?? defaultRunCommand;
+	await mkdir(dirname(definition.filePath), { recursive: true });
+	await mkdir(join(options.home, ".yaport"), { recursive: true });
+	await writeFile(definition.filePath, definition.contents, "utf8");
+	for (const command of definition.installCommands) await runCommand(command.command, command.args, { allowFailure: command.allowFailure });
+	return definition;
+}
+async function uninstallYaportService(options) {
+	const definition = buildYaportServiceDefinition(options);
+	const runCommand = options.runCommand ?? defaultRunCommand;
+	for (const command of definition.uninstallCommands) await runCommand(command.command, command.args, { allowFailure: command.allowFailure });
+	await rm(definition.filePath, { force: true });
+	return definition;
+}
+async function printYaportServiceStatus(options) {
+	const runCommand = options.runCommand ?? defaultRunCommand;
+	if (options.platform === "darwin") {
+		printCommandResult(await runCommand("launchctl", ["print", launchdServiceTarget(options.uid)], { allowFailure: true }));
+		return;
+	}
+	if (options.platform === "linux") {
+		printCommandResult(await runCommand("systemctl", [
+			"--user",
+			"status",
+			SYSTEMD_SERVICE_NAME
+		], { allowFailure: true }));
+		return;
+	}
+	throw new UnsupportedServicePlatformError(String(options.platform));
+}
+function buildYaportServiceDefinition(options) {
+	if (options.platform === "darwin") return buildLaunchAgentDefinition(options);
+	if (options.platform === "linux") return buildSystemdDefinition(options);
+	throw new UnsupportedServicePlatformError(String(options.platform));
+}
+function buildLaunchAgentDefinition(options) {
+	const filePath = join(options.home, "Library/LaunchAgents", `${SERVICE_LABEL}.plist`);
+	const programArguments = serviceProgramArguments(options);
+	const logDirectory = join(options.home, ".yaport");
+	const target = `gui/${options.uid ?? process.getuid?.() ?? 0}`;
+	return {
+		filePath,
+		contents: `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArguments.map((argument) => `    <string>${escapeXml(argument)}</string>`).join("\n")}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(options.home)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(join(logDirectory, "service.log"))}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(join(logDirectory, "service.error.log"))}</string>
+</dict>
+</plist>
+`,
+		installCommands: [
+			{
+				command: "launchctl",
+				args: [
+					"bootout",
+					target,
+					filePath
+				],
+				allowFailure: true
+			},
+			{
+				command: "launchctl",
+				args: [
+					"bootstrap",
+					target,
+					filePath
+				]
+			},
+			{
+				command: "launchctl",
+				args: ["enable", `${target}/${SERVICE_LABEL}`]
+			},
+			{
+				command: "launchctl",
+				args: [
+					"kickstart",
+					"-k",
+					`${target}/${SERVICE_LABEL}`
+				]
+			}
+		],
+		uninstallCommands: [{
+			command: "launchctl",
+			args: [
+				"bootout",
+				target,
+				filePath
+			],
+			allowFailure: true
+		}, {
+			command: "launchctl",
+			args: ["disable", `${target}/${SERVICE_LABEL}`],
+			allowFailure: true
+		}]
+	};
+}
+function buildSystemdDefinition(options) {
+	const filePath = join(options.home, ".config/systemd/user", SYSTEMD_SERVICE_NAME);
+	const execStart = serviceProgramArguments(options).map(systemdQuote).join(" ");
+	return {
+		filePath,
+		contents: `[Unit]
+Description=Yaport local web UI
+After=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${systemdQuote(options.home)}
+ExecStart=${execStart}
+Restart=on-failure
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=default.target
+`,
+		installCommands: [{
+			command: "systemctl",
+			args: ["--user", "daemon-reload"]
+		}, {
+			command: "systemctl",
+			args: [
+				"--user",
+				"enable",
+				"--now",
+				SYSTEMD_SERVICE_NAME
+			]
+		}],
+		uninstallCommands: [{
+			command: "systemctl",
+			args: [
+				"--user",
+				"disable",
+				"--now",
+				SYSTEMD_SERVICE_NAME
+			],
+			allowFailure: true
+		}, {
+			command: "systemctl",
+			args: ["--user", "daemon-reload"]
+		}]
+	};
+}
+function serviceProgramArguments(options) {
+	return [
+		options.nodePath,
+		options.cliPath,
+		"serve",
+		"--host",
+		options.host,
+		"--port",
+		String(options.port),
+		"--data-file",
+		options.dataFile,
+		"--no-open"
+	];
+}
+function launchdServiceTarget(uid) {
+	return `gui/${uid ?? process.getuid?.() ?? 0}/${SERVICE_LABEL}`;
+}
+async function defaultRunCommand(command, args, options = {}) {
+	try {
+		return await execFileAsync(command, args, { encoding: "utf8" });
+	} catch (error) {
+		if (options.allowFailure) return {
+			stderr: errorWithOutput(error).stderr,
+			stdout: errorWithOutput(error).stdout
+		};
+		throw error;
+	}
+}
+function printCommandResult(result) {
+	if (result?.stdout) console.log(result.stdout.trimEnd());
+	if (result?.stderr) console.error(result.stderr.trimEnd());
+}
+function errorWithOutput(error) {
+	if (error && typeof error === "object") {
+		const output = error;
+		return {
+			stderr: typeof output.stderr === "string" ? output.stderr : "",
+			stdout: typeof output.stdout === "string" ? output.stdout : ""
+		};
+	}
+	return {};
+}
+function escapeXml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function systemdQuote(value) {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/%/g, "%%")}"`;
+}
+//#endregion
 //#region src/server/cli.ts
 var usage = `Usage: yaport [serve options]
 Usage: yaport serve [options]
-Usage: yaport add-machine --name <name> --host <host> [connection options]
+Usage: yaport add-machine --host <host> [connection options]
+Usage: yaport service <install|uninstall|status> [options]
 
 Start the 丫口 local web UI.
 
 Commands:
   serve                 Start the local web UI. This is the default command.
   add-machine           Add a remote machine to the local 丫口 data file.
+  service               Install, uninstall, or inspect the user-level autostart service.
 
 Serve options:
   --host <host>          Host to bind. Default: ${DEFAULT_HOST}
@@ -689,11 +1172,12 @@ Serve options:
   -h, --help             Print this help message
 
 add-machine required options:
-  --name <name>          Display name in the UI.
   --host <host>          SSH host, IP, or OpenSSH alias. For "ssh erya", use --host erya.
 
 add-machine connection options:
+  --name <name>          Display name in the UI. Defaults to user@host:port when omitted.
   --user <user>          SSH user. Omit for OpenSSH aliases that already define User.
+                         Required when --host is an IP address.
   --port <port>          SSH port. Omit for OpenSSH aliases that already define Port.
   --password <value>     SSH password for the target machine. Prefer --password-env.
   --password-env <env>   Read the target machine SSH password from an environment variable.
@@ -718,20 +1202,33 @@ add-machine output options:
   --json                 Print deterministic JSON. Passwords are never printed.
   --data-file <path>     Remote machine config file. Default lookup: ./.yaport, then ~/.yaport.
 
+service options:
+  install                Create and start a user-level service. macOS uses LaunchAgent; Linux uses systemd --user.
+  uninstall              Stop and remove the user-level service.
+  status                 Print service status using launchctl or systemctl --user.
+  --host <host>          Host used by the installed service. Default: ${DEFAULT_HOST}
+  --port <port>          Port used by the installed service. Default: ${DEFAULT_PORT}
+  --data-file <path>     Machine config file used by the installed service. Default lookup: ./.yaport, then ~/.yaport.
+  --json                 Print deterministic JSON for install/uninstall.
+
 Examples:
-  yaport add-machine --name Erya --host erya --json
+  yaport add-machine --host erya --json
   TARGET_PASSWORD='[redacted-target-password]' yaport add-machine --name Prod --host 10.0.0.5 --user root --password-env TARGET_PASSWORD --json
   JUMP_PASSWORD='[redacted-jump-password]' TARGET_PASSWORD='[redacted-target-password]' yaport add-machine --name Prod --host prod.internal --user app --password-env TARGET_PASSWORD --connect-timeout 30 --command-timeout 90 --jump1-host jump.internal --jump1-user ops --jump1-password-env JUMP_PASSWORD --json
+  yaport service install --port 5173 --json
+  yaport service status
+  yaport service uninstall
 
 Agent notes:
   - Prefer --json for machine-readable output.
   - Prefer --password-env and --jumpN-password-env to avoid putting passwords in process arguments.
-  - Omit --user and --port when --host is an OpenSSH alias such as "erya".
+  - Omit --user and --port when --host is an OpenSSH alias such as "erya"; IP hosts must include --user.
   - The command is non-interactive. Missing required flags fail fast with a non-zero exit code.
 `;
 function parseCliOptions(argv, env = process.env) {
 	if (argv[0] === "add-machine") return parseAddMachineOptions(argv.slice(1), env);
 	if (argv[0] === "serve") return parseServeOptions(argv.slice(1), env);
+	if (argv[0] === "service") return parseServiceOptions(argv.slice(1), env);
 	return parseServeOptions(argv, env);
 }
 function parseServeOptions(argv, env) {
@@ -854,7 +1351,7 @@ function parseAddMachineOptions(argv, env) {
 	}
 	if (options.help) return options;
 	const input = machineInputSchema.parse({
-		name: requiredValue(machine.name, "--name"),
+		...machine.name !== void 0 ? { name: machine.name } : {},
 		host: requiredValue(machine.host, "--host"),
 		...machine.connectTimeoutSeconds ? { connectTimeoutSeconds: machine.connectTimeoutSeconds } : {},
 		...machine.commandTimeoutSeconds ? { commandTimeoutSeconds: machine.commandTimeoutSeconds } : {},
@@ -866,6 +1363,50 @@ function parseAddMachineOptions(argv, env) {
 		input
 	};
 }
+function parseServiceOptions(argv, env) {
+	const action = argv[0];
+	const options = {
+		command: "service",
+		action: action === "uninstall" || action === "status" ? action : "install",
+		dataFile: env.YAPORT_DATA_FILE ?? defaultDataFile(),
+		help: false,
+		host: env.HOST ?? "127.0.0.1",
+		json: false,
+		port: Number(env.PORT ?? 5173)
+	};
+	const optionStartIndex = action === "install" || action === "uninstall" || action === "status" ? 1 : 0;
+	if (!action || action === "-h" || action === "--help") options.help = true;
+	else if (action !== "install" && action !== "uninstall" && action !== "status") throw new Error("service action must be install, uninstall, or status.");
+	for (let index = optionStartIndex; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "-h" || arg === "--help") {
+			options.help = true;
+			continue;
+		}
+		if (arg === "--json") {
+			options.json = true;
+			continue;
+		}
+		if (arg === "--host") {
+			options.host = readValue(argv, index, arg);
+			index += 1;
+			continue;
+		}
+		if (arg === "--port") {
+			options.port = Number(readValue(argv, index, arg));
+			index += 1;
+			continue;
+		}
+		if (arg === "--data-file") {
+			options.dataFile = readValue(argv, index, arg);
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown option: ${arg}`);
+	}
+	if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) throw new Error("Port must be an integer between 1 and 65535.");
+	return options;
+}
 function readValue(argv, optionIndex, optionName) {
 	const value = argv[optionIndex + 1];
 	if (!value || value.startsWith("-")) throw new Error(`${optionName} requires a value.`);
@@ -929,6 +1470,10 @@ async function main() {
 		await addMachine(options);
 		return;
 	}
+	if (options.command === "service") {
+		await runServiceCommand(options);
+		return;
+	}
 	await startYaportServer({
 		host: options.host,
 		port: options.port,
@@ -937,6 +1482,40 @@ async function main() {
 		open: options.open
 	});
 }
+async function runServiceCommand(options) {
+	const serviceOptions = {
+		cliPath: process.argv[1],
+		dataFile: options.dataFile,
+		home: homedir(),
+		host: options.host,
+		nodePath: process.execPath,
+		platform: process.platform,
+		port: options.port,
+		uid: process.getuid?.()
+	};
+	if (options.action === "install") {
+		printServiceResult(options, "installed", (await installYaportService(serviceOptions)).filePath);
+		return;
+	}
+	if (options.action === "uninstall") {
+		printServiceResult(options, "uninstalled", (await uninstallYaportService(serviceOptions)).filePath);
+		return;
+	}
+	await printYaportServiceStatus(serviceOptions);
+}
+function printServiceResult(options, status, filePath) {
+	if (options.json) {
+		console.log(JSON.stringify({
+			action: options.action,
+			filePath,
+			service: "yaport",
+			status
+		}, null, 2));
+		return;
+	}
+	console.log(`Yaport service ${status}.`);
+	console.log(`Service file: ${filePath}`);
+}
 async function addMachine(options) {
 	if (!options.input) throw new Error("Missing add-machine input.");
 	const publicMachine = stripMachineSecrets(await new JsonMachineStore(options.dataFile).add(options.input));