wiki-viewer 2.9.2 → 2.9.3

package/bin/cli/service.js

@@ -0,0 +1,304 @@
+import { execFileSync, execSync } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { configPath, logDir, loadConfig, saveConfig, parseEnvFlags } from "./config.js";
+import { computeServerEnv, parseServeArgs } from "./serve.js";
+import { looksLikeSshTarget } from "../shared/ssh-target.js";
+
+const selfScript = fileURLToPath(import.meta.url);
+
+export const SERVICE_NAME = "wiki-viewer";
+export const LAUNCHD_LABEL = "com.wiki-viewer";
+
+export function platform() {
+	if (process.platform === "linux") return "linux";
+	if (process.platform === "darwin") return "macos";
+	return null;
+}
+
+export function requireSupportedPlatform() {
+	const p = platform();
+	if (!p) {
+		console.error(`Error: service management is only supported on Linux (systemd) and macOS (launchd), not ${process.platform}.`);
+		process.exit(1);
+	}
+	return p;
+}
+
+export function run(cmd, args, opts = {}) {
+	return execFileSync(cmd, args, { stdio: "inherit", ...opts });
+}
+
+export function runQuiet(cmd, args) {
+	try {
+		return execFileSync(cmd, args, { stdio: ["ignore", "pipe", "pipe"] }).toString();
+	} catch (e) {
+		return null;
+	}
+}
+
+export function installSystemd(nodeBin, scriptPath) {
+	const unitDir = path.join(os.homedir(), ".config", "systemd", "user");
+	mkdirSync(unitDir, { recursive: true });
+	const unitPath = path.join(unitDir, `${SERVICE_NAME}.service`);
+
+	const nodeDir = path.dirname(nodeBin);
+	const sysPath = `${nodeDir}:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`;
+	const rgEnv = process.env.WIKI_VIEWER_RG
+		? `\nEnvironment=WIKI_VIEWER_RG=${process.env.WIKI_VIEWER_RG}`
+		: "";
+	const unit = `[Unit]
+Description=wiki-viewer local file viewer
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${nodeBin} ${scriptPath} service run
+Restart=on-failure
+RestartSec=3
+Environment=NODE_ENV=production
+Environment=PATH=${sysPath}${rgEnv}
+
+[Install]
+WantedBy=default.target
+`;
+	writeFileSync(unitPath, unit);
+	console.log(`Wrote unit ${unitPath}`);
+
+	const user = os.userInfo().username;
+	try {
+		execFileSync("loginctl", ["enable-linger", user], { stdio: "ignore" });
+		console.log(`Enabled linger for ${user} (starts at boot)`);
+	} catch {
+		console.log(`Note: could not enable linger automatically. For boot persistence run:`);
+		console.log(`  sudo loginctl enable-linger ${user}`);
+	}
+
+	run("systemctl", ["--user", "daemon-reload"]);
+	run("systemctl", ["--user", "enable", "--now", `${SERVICE_NAME}.service`]);
+	console.log("\nService installed and started.");
+	console.log("  Status: wiki-viewer service status");
+	console.log("  Logs:   wiki-viewer service logs");
+}
+
+export function installLaunchd(nodeBin, scriptPath) {
+	const agentsDir = path.join(os.homedir(), "Library", "LaunchAgents");
+	mkdirSync(agentsDir, { recursive: true });
+	mkdirSync(logDir, { recursive: true });
+	const plistPath = path.join(agentsDir, `${LAUNCHD_LABEL}.plist`);
+	const outLog = path.join(logDir, "out.log");
+	const errLog = path.join(logDir, "err.log");
+
+	const plist = `<?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>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodeBin}</string>
+    <string>${scriptPath}</string>
+    <string>service</string>
+    <string>run</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${outLog}</string>
+  <key>StandardErrorPath</key>
+  <string>${errLog}</string>
+</dict>
+</plist>
+`;
+	writeFileSync(plistPath, plist);
+	console.log(`Wrote plist ${plistPath}`);
+
+	runQuiet("launchctl", ["unload", plistPath]);
+	run("launchctl", ["load", "-w", plistPath]);
+	console.log("\nService installed and started.");
+	console.log("  Status: wiki-viewer service status");
+	console.log("  Logs:   wiki-viewer service logs");
+}
+
+// A persistent service bakes an absolute path to this script into the unit /
+// plist (ExecStart). If we're running from a package-manager scratch cache
+// (`npx wiki-viewer …`, `pnpm dlx …`, or an OS temp dir), that path is deleted
+// the moment the cache is pruned, leaving a service that silently fails on the
+// next reboot. Detect it and refuse, pointing the user at a global install.
+export function ephemeralInstallReason() {
+	const p = selfScript;
+	const sep = path.sep;
+	if (p.includes(`${sep}_npx${sep}`)) return "an npx cache";
+	if (p.includes(`${sep}dlx-`)) return "a pnpm/yarn dlx cache";
+	const tmp = os.tmpdir();
+	if (p === tmp || p.startsWith(tmp + sep)) return "a temporary directory";
+	return null;
+}
+
+export function requirePersistentInstall() {
+	const reason = ephemeralInstallReason();
+	if (!reason) return;
+	console.error(`Error: cannot install a service from ${reason}.`);
+	console.error(`  wiki-viewer is running from ${selfScript},`);
+	console.error(`  which your package manager will delete. A service pointed there would`);
+	console.error(`  break after the next cache cleanup or reboot.`);
+	console.error(``);
+	console.error(`  Install it globally first, then install the service:`);
+	console.error(`    npm install -g ${SERVICE_NAME}`);
+	console.error(`    ${SERVICE_NAME} service install ...`);
+	process.exit(1);
+}
+
+function fnmRoot() {
+	return process.env.FNM_DIR || path.join(os.homedir(), ".local", "share", "fnm");
+}
+
+export function resolveServiceNode() {
+	const exec = process.execPath;
+	const looksFnm = exec.includes("/fnm/") || exec.includes("/.fnm/") || exec.includes("fnm_multishells") || exec.includes("/fnm/node-versions/") || exec.includes("/.local/share/fnm/");
+	if (looksFnm) {
+		const fnmDefault = path.join(fnmRoot(), "aliases", "default", "bin", "node");
+		if (existsSync(fnmDefault)) return fnmDefault;
+	}
+	return exec;
+}
+
+export function resolveServiceScript() {
+	const script = selfScript;
+	const pinned = path.join(fnmRoot(), "node-versions") + path.sep;
+	if (!script.startsWith(pinned)) return script;
+	const parts = path.relative(path.join(fnmRoot(), "node-versions"), script).split(path.sep);
+	if (parts[1] !== "installation") return script;
+	const durable = path.join(fnmRoot(), "aliases", "default", ...parts.slice(2));
+	return existsSync(durable) ? durable : script;
+}
+
+export function versionManagedNodeWarning(nodePath) {
+	const markers = ["/.nvm/", "/.asdf/", "/.volta/", "/n/versions/", "/fnm_multishells/", "/node-versions/"];
+	if (!markers.some((m) => nodePath.includes(m))) return null;
+	return (
+		`The service will run Node from a version-manager path:\n` +
+		`     ${nodePath}\n` +
+		`   If you upgrade or remove that Node version, the service will stop working.\n` +
+		`   Set a stable default (e.g. \`fnm default <version>\`) or install wiki-viewer\n` +
+		`   under a system Node, then re-run the install.`
+	);
+}
+
+export function serviceInstall(args) {
+	const p = requireSupportedPlatform();
+	requirePersistentInstall();
+
+	const cli = parseServeArgs(args);
+	const envFlags = parseEnvFlags(args);
+	const existing = loadConfig();
+	const mergedEnv = { ...(existing.env ?? {}), ...envFlags };
+	const cliIsSsh = cli.rootDir != null && looksLikeSshTarget(cli.rootDir);
+
+	const cfg = {
+		...existing,
+		rootDir: cli.rootDir != null
+			? (cliIsSsh ? cli.rootDir : path.resolve(cli.rootDir))
+			: existing.rootDir ?? null,
+		host: cli.userSpecifiedHost ? cli.host : existing.host ?? "localhost",
+		port: cli.userSpecifiedPort ? cli.port : existing.port ?? "3000",
+		https: cli.useHttps ?? existing.https ?? false,
+	};
+
+	if (cliIsSsh) {
+		cfg.ssh = { ...(cli.sshKey ? { key: cli.sshKey } : {}), ...(cli.sshPort ? { port: cli.sshPort } : {}), ...(cli.sshReadOnly ? { readOnly: true } : {}) };
+	}
+	if (Object.keys(mergedEnv).length) cfg.env = mergedEnv;
+	else delete cfg.env;
+	if (cliIsSsh && cli.sshPassword) {
+		console.log("⚠️   --ssh-password is ignored for services (non-interactive). Use ssh-agent or --ssh-key.\n");
+	}
+	saveConfig(cfg);
+	console.log(`Saved config to ${configPath}`);
+	console.log(`  dir:   ${cfg.rootDir ?? "(choose in browser)"}`);
+	console.log(`  host:  ${cfg.host}`);
+	console.log(`  port:  ${cfg.port}`);
+	console.log(`  https: ${cfg.https}`);
+	if (cfg.env) {
+		console.log(`  env:   ${Object.keys(cfg.env).join(", ")}`);
+	}
+	console.log("");
+
+	const { warnings } = computeServerEnv({ host: cfg.host, port: String(cfg.port), useHttps: Boolean(cfg.https), configEnv: cfg.env ?? {} });
+	for (const w of warnings) console.log(`\n⚠️   ${w}\n`);
+
+	const nodeWarning = versionManagedNodeWarning(resolveServiceNode());
+	if (nodeWarning) console.log(`⚠️   ${nodeWarning}\n`);
+
+	const nodeBin = resolveServiceNode();
+	const scriptPath = resolveServiceScript();
+	if (p === "linux") installSystemd(nodeBin, scriptPath);
+	else installLaunchd(nodeBin, scriptPath);
+}
+
+export function serviceUninstall() {
+	const p = requireSupportedPlatform();
+	if (p === "linux") {
+		runQuiet("systemctl", ["--user", "disable", "--now", `${SERVICE_NAME}.service`]);
+		const unitPath = path.join(os.homedir(), ".config", "systemd", "user", `${SERVICE_NAME}.service`);
+		if (existsSync(unitPath)) { rmSync(unitPath); console.log(`Removed ${unitPath}`); }
+		runQuiet("systemctl", ["--user", "daemon-reload"]);
+	} else {
+		const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+		runQuiet("launchctl", ["unload", "-w", plistPath]);
+		if (existsSync(plistPath)) { rmSync(plistPath); console.log(`Removed ${plistPath}`); }
+	}
+	console.log("Service uninstalled.");
+}
+
+export function serviceStatus() {
+	const p = platform();
+	if (p === "linux") {
+		try { run("systemctl", ["--user", "status", `${SERVICE_NAME}.service`, "--no-pager"]); }
+		catch { /* systemctl exits non-zero when inactive; output already shown */ }
+	} else if (p === "macos") {
+		const out = runQuiet("launchctl", ["list"]);
+		if (out) {
+			const line = out.split("\n").find((l) => l.includes(LAUNCHD_LABEL));
+			console.log(line ? line.trim() : `${LAUNCHD_LABEL}: not loaded`);
+		}
+	}
+}
+
+export function serviceLogs() {
+	const p = platform();
+	if (p === "linux") {
+		run("journalctl", ["--user", "-u", `${SERVICE_NAME}.service`, "-n", "100", "-f"]);
+	} else if (p === "macos") {
+		const outLog = path.join(logDir, "out.log");
+		const errLog = path.join(logDir, "err.log");
+		run("tail", ["-n", "100", "-f", outLog, errLog]);
+	}
+}
+
+export function serviceIsInstalled() {
+	const p = platform();
+	if (p === "linux") {
+		return existsSync(path.join(os.homedir(), ".config", "systemd", "user", `${SERVICE_NAME}.service`));
+	}
+	if (p === "macos") {
+		return existsSync(path.join(os.homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`));
+	}
+	return false;
+}
+
+export function serviceRestart() {
+	const p = platform();
+	if (p === "linux") {
+		run("systemctl", ["--user", "restart", `${SERVICE_NAME}.service`]);
+	} else if (p === "macos") {
+		const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+		runQuiet("launchctl", ["unload", plistPath]);
+		run("launchctl", ["load", "-w", plistPath]);
+	}
+}

package/bin/cli/update.js

@@ -0,0 +1,58 @@
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import os from "node:os";
+import { readFileSync } from "node:fs";
+import { appRoot } from "./serve.js";
+import { serviceIsInstalled, serviceRestart } from "./service.js";
+
+const selfScript = fileURLToPath(import.meta.url);
+
+export function detectPackageManager() {
+	const ua = process.env.npm_config_user_agent ?? "";
+	if (ua.startsWith("pnpm")) return "pnpm";
+	if (ua.startsWith("yarn")) return "yarn";
+	if (selfScript.includes(`${path.sep}pnpm${path.sep}`)) return "pnpm";
+	return "npm";
+}
+
+export function runQuiet(cmd, args) {
+	try {
+		return execFileSync(cmd, args, { stdio: ["ignore", "pipe", "pipe"] }).toString();
+	} catch (e) {
+		return null;
+	}
+}
+
+export function update() {
+	const pkg = JSON.parse(readFileSync(path.join(appRoot, "package.json"), "utf8"));
+	const name = pkg.name;
+	console.log(`Current ${name}: v${pkg.version}`);
+
+	const latest = (runQuiet("npm", ["view", `${name}@latest`, "version"]) || "").trim();
+	if (latest && latest === pkg.version) {
+		console.log(`Already on the latest version (v${latest}). Nothing to do.`);
+		return;
+	}
+	if (latest) console.log(`Latest: v${latest}`);
+
+	const pm = detectPackageManager();
+	const cmd = pm === "pnpm" ? ["pnpm", ["add", "-g", `${name}@latest`, "--prefer-offline"]]
+			: pm === "yarn" ? ["yarn", ["global", "add", `${name}@latest`]]
+			: ["npm", ["install", "-g", `${name}@latest`, "--prefer-offline"]];
+
+	console.log(`Updating via ${pm}…`);
+	try {
+		execFileSync(cmd[0], cmd[1], { stdio: "inherit" });
+	} catch {
+		console.error(`Error: update failed. Try manually: ${cmd[0]} ${cmd[1].join(" ")}`);
+		process.exit(1);
+	}
+
+	if (serviceIsInstalled()) {
+		console.log("Restarting service…");
+		try { serviceRestart(); console.log("Service restarted."); }
+		catch { console.log("Note: could not restart service automatically. Run: wiki-viewer service restart"); }
+	}
+	console.log("Update complete.");
+}

package/bin/cli/wizard.js

@@ -0,0 +1,134 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { loadConfig, saveConfig, configPath } from "./config.js";
+import { makePrompter } from "./prompt.js";
+import { computeServerEnv, start, resolveRunOptions, isLocalHost } from "./serve.js";
+import {
+	platform,
+	requirePersistentInstall,
+	resolveServiceNode,
+	resolveServiceScript,
+	versionManagedNodeWarning,
+	installSystemd,
+	installLaunchd,
+} from "./service.js";
+
+const WIZARD_ENV_VARS = [
+	{ key: "AUTH_ALLOWED_DOMAIN", hint: "Restrict signup to an email domain, e.g. example.com" },
+	{ key: "AUTH_ALLOWED_EMAILS", hint: "Restrict signup to specific emails (comma-separated)" },
+	{ key: "GOOGLE_CLIENT_ID", hint: "Google OAuth client ID (enables Google sign-in)" },
+	{ key: "GOOGLE_CLIENT_SECRET", hint: "Google OAuth client secret" },
+	{ key: "AUTH_DISABLE_PASSWORD", hint: "Set to 1 to allow Google sign-in only (requires Google keys)" },
+	{ key: "AUTH_TRUSTED_PROVIDERS", hint: "Auto-link these providers to existing accounts, e.g. google" },
+	{ key: "WIKI_OWNER_HOSTS", hint: "Extra hostnames trusted for the AI panel owner cookie" },
+	{ key: "AGENT_RATE_LIMIT", hint: "Per-minute agent API rate limit (default 60)" },
+];
+
+export async function runWizard() {
+	const io = makePrompter();
+	const existing = loadConfig();
+
+	const ask = async (label, def) => {
+		const suffix = def ? ` [${def}]` : "";
+		const answer = (await io.prompt(`${label}${suffix}: `)).trim();
+		return answer || def || "";
+	};
+	const askYesNo = async (label, defYes) => {
+		const def = defYes ? "Y/n" : "y/N";
+		const answer = (await io.prompt(`${label} [${def}]: `)).trim().toLowerCase();
+		if (!answer) return defYes;
+		return answer === "y" || answer === "yes";
+	};
+
+	try {
+		console.log("\nwiki-viewer setup\n");
+		console.log("Answer a few questions. Press Enter to accept the [default].\n");
+
+		const dirInput = await ask(
+			"Directory to serve (blank = choose later in the browser)",
+			existing.rootDir ?? process.cwd(),
+		);
+		const rootDir = dirInput ? path.resolve(dirInput) : null;
+		if (rootDir && !existsSync(rootDir)) {
+			console.log(`  Note: ${rootDir} does not exist yet; it will be served once created.`);
+		}
+
+		const host = await ask(
+			"Host to bind (localhost for this machine only, 0.0.0.0 for the network)",
+			existing.host ?? "localhost",
+		);
+
+		const port = await ask("Port", String(existing.port ?? "3000"));
+
+		const httpsDefault = existing.https ?? (!isLocalHost(host) && host !== "0.0.0.0");
+		const useHttps = await askYesNo(
+			"Enable HTTPS? (recommended for any non-localhost access)",
+			Boolean(httpsDefault),
+		);
+
+		const env = { ...(existing.env ?? {}) };
+		const wantEnv = await askYesNo(
+			"\nConfigure app settings now? (OAuth, signup allowlist, rate limit)",
+			false,
+		);
+		if (wantEnv) {
+			console.log("Leave blank to skip a setting.\n");
+			for (const { key, hint } of WIZARD_ENV_VARS) {
+				const cur = env[key];
+				const val = await ask(`  ${key} — ${hint}`, cur);
+				if (val) env[key] = val;
+				else delete env[key];
+			}
+		}
+
+		const cfg = { ...existing, rootDir, host, port, https: useHttps };
+		if (Object.keys(env).length) cfg.env = env;
+		else delete cfg.env;
+
+		console.log("\nConfiguration:");
+		console.log(`  directory : ${rootDir ?? "(choose in browser)"}`);
+		console.log(`  host      : ${host}`);
+		console.log(`  port      : ${port}`);
+		console.log(`  https     : ${useHttps}`);
+		if (cfg.env) console.log(`  app env   : ${Object.keys(cfg.env).join(", ")}`);
+
+		const { warnings } = computeServerEnv({ host, port: String(port), useHttps, configEnv: cfg.env ?? {} });
+		for (const w of warnings) console.log(`\n⚠️   ${w}`);
+
+		console.log("");
+		console.log("What next?");
+		console.log("  1) Install as a service (starts now and on every reboot)");
+		console.log("  2) Run once now (foreground)");
+		console.log("  3) Save config only");
+		const choice = (await io.prompt("Choose [1/2/3]: ")).trim() || "1";
+
+		saveConfig(cfg);
+		console.log(`\nSaved ${configPath}`);
+
+		io.close();
+
+		if (choice === "1") {
+			const p = platform();
+			if (!p) {
+				console.log("Service install is only supported on Linux and macOS.");
+				console.log("Run it yourself with: wiki-viewer service run");
+				return;
+			}
+			requirePersistentInstall();
+			const nodeWarning = versionManagedNodeWarning(resolveServiceNode());
+			if (nodeWarning) console.log(`\n⚠️   ${nodeWarning}\n`);
+			const nodeBin = resolveServiceNode();
+			const scriptPath = resolveServiceScript();
+			if (p === "linux") installSystemd(nodeBin, scriptPath);
+			else installLaunchd(nodeBin, scriptPath);
+		} else if (choice === "2") {
+			start(resolveRunOptions([]));
+		} else {
+			console.log("\nStart it any time with:");
+			console.log("  wiki-viewer service install   # persistent service");
+			console.log("  wiki-viewer service run       # run from this config");
+		}
+	} finally {
+		io.close();
+	}
+}

package/bin/shared/ssh-target.js

@@ -0,0 +1,154 @@
+/**
+ * Shared SSH target parsing and sshfs argv construction.
+ *
+ * This module is consumed by both the Node/JS CLI (`bin/wiki-viewer.js`) and
+ * the TypeScript server (`src/lib/sshfs.ts`) via direct import, so the logic
+ * stays in one place and cannot drift. It exports defensive validators only —
+ * it never calls `process.exit`.
+ */
+
+import { existsSync } from "node:fs";
+
+// Defense-in-depth: reject these even though callers never pass fields through
+// a shell.
+export const FORBIDDEN_SSH_CHARS = new RegExp("[;|&$`<>(){}\\n\\r\\0]");
+
+/**
+ * @typedef {Object} ParsedSshTarget
+ * @property {string} [user]
+ * @property {string} host
+ * @property {string} remotePath
+ */
+
+/**
+ * @typedef {"agent" | "keyfile" | "password"} SshAuthMethod
+ */
+
+/**
+ * @typedef {Object} BuildSshfsOptions
+ * @property {ParsedSshTarget} target
+ * @property {string} mountpoint
+ * @property {number | string} [port]
+ * @property {SshAuthMethod} [authMethod]
+ * @property {string} [keyPath]
+ * @property {string} [password]
+ * @property {boolean} [readOnly]
+ * @property {string[]} [extraOptions]
+ */
+
+/**
+ * Heuristic used by the CLI to decide whether a positional argument should be
+ * treated as a directory or as an SSH target.
+ *
+ * @param {string} s
+ * @returns {boolean}
+ */
+export function looksLikeSshTarget(s) {
+	if (!s || FORBIDDEN_SSH_CHARS.test(s)) return false;
+	// [user@]host:/abs/path — host has no slash, remote path is absolute. An
+	// existing local path (e.g. a real dir literally named like this) wins.
+	return /^([\w.-]+@)?[\w.-]+:\/.+/.test(s) && !existsSync(s);
+}
+
+/**
+ * Parse an SSH target of the form `[user@]host:/abs/path`.
+ *
+ * @param {string} target
+ * @returns {ParsedSshTarget | null}
+ */
+export function parseSshTarget(target) {
+	if (!target || FORBIDDEN_SSH_CHARS.test(target)) return null;
+	const trimmed = target.trim();
+
+	const colon = trimmed.indexOf(":");
+	if (colon <= 0) return null;
+	const hostPart = trimmed.slice(0, colon);
+	const remotePath = trimmed.slice(colon + 1);
+
+	if (!remotePath.startsWith("/")) return null;
+	if (remotePath.includes("..")) return null;
+
+	let user;
+	let host = hostPart;
+	const at = hostPart.indexOf("@");
+	if (at >= 0) {
+		user = hostPart.slice(0, at);
+		host = hostPart.slice(at + 1);
+		if (!user) return null;
+	}
+	if (!host) return null;
+	if (!/^[a-zA-Z0-9.\-]+$/.test(host)) return null;
+	if (user && !/^[a-zA-Z0-9._\-]+$/.test(user)) return null;
+
+	return { user, host, remotePath };
+}
+
+/**
+ * Validate an explicit private key path.
+ *
+ * @param {string} keyPath
+ * @returns {boolean}
+ */
+export function isValidKeyPath(keyPath) {
+	if (!keyPath || FORBIDDEN_SSH_CHARS.test(keyPath)) return false;
+	if (keyPath.includes("..")) return false;
+	return keyPath.startsWith("/") || keyPath.startsWith("~/");
+}
+
+/**
+ * Build the sshfs argv (excluding the binary name).
+ *
+ * @param {BuildSshfsOptions} opts
+ * @returns {string[]}
+ */
+export function buildSshfsArgs(opts) {
+	const { target, mountpoint, port } = opts;
+	const userPart = target.user ? `${target.user}@` : "";
+	const args = [`${userPart}${target.host}:${target.remotePath}`, mountpoint];
+
+	if (
+		port &&
+		Number.isInteger(Number(port)) &&
+		Number(port) > 0 &&
+		Number(port) < 65536
+	) {
+		args.push("-p", String(port));
+	}
+
+	// Infer authentication method if the caller did not provide an explicit one.
+	/** @type {SshAuthMethod} */
+	let authMethod = opts.authMethod ?? "agent";
+	if (!opts.authMethod) {
+		if (opts.password != null) authMethod = "password";
+		else if (opts.keyPath) authMethod = "keyfile";
+	}
+
+	const o = [
+		"reconnect",
+		"ServerAliveInterval=15",
+		"ServerAliveCountMax=3",
+		"compression=yes",
+		"cache=yes",
+		"kernel_cache",
+		"StrictHostKeyChecking=accept-new",
+		"BatchMode=yes",
+	];
+
+	if (opts.readOnly) o.push("ro");
+	if (authMethod === "keyfile" && opts.keyPath) {
+		o.push(`IdentityFile=${opts.keyPath}`);
+		o.push("IdentitiesOnly=yes");
+	}
+	if (authMethod === "password") {
+		const idx = o.indexOf("BatchMode=yes");
+		if (idx >= 0) o.splice(idx, 1);
+		o.push("password_stdin");
+		o.push("PreferredAuthentications=password,keyboard-interactive");
+		o.push("PubkeyAuthentication=no");
+		o.push("NumberOfPasswordPrompts=1");
+	}
+	if (opts.extraOptions) o.push(...opts.extraOptions);
+
+	args.push("-o", o.join(","));
+	return args;
+}