@dong-victor/dsh-better-sidebar-starter 0.1.0

package/lib/index.js

@@ -0,0 +1,1030 @@
+import { execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { WebSocket, WebSocketServer } from "ws";
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+//#region src/host/processManager.ts
+/**
+* Process manager: spawns child processes for run configurations, collects
+* stdout/stderr into a ring buffer, and fans logs out to WebSocket subscribers.
+* One instance per spawned process. Instances persist briefly after exit
+* so late-attaching browsers can read the final log.
+* @module dsh-better-sidebar-starter/host/processManager
+*/
+/**
+* Resolve JAVA_HOME from the system when it is not already in the process
+* environment. Checks (in order):
+* 1. process.env.JAVA_HOME
+* 2. Windows registry (HKLM\SOFTWARE\JavaSoft\JDK / JRE)
+* 3. Common install paths
+* 4. `which java` → parent dir (Unix)
+* Returns null if not found.
+*/
+function resolveJavaHome() {
+	if (process.env.JAVA_HOME && process.env.JAVA_HOME.trim() !== "") {
+		const home = process.env.JAVA_HOME.trim();
+		if (existsSync(join(home, "bin", process.platform === "win32" ? "java.exe" : "java"))) return home;
+	}
+	if (process.platform === "win32") {
+		for (const regPath of [
+			"HKLM\\SOFTWARE\\JavaSoft\\JDK",
+			"HKLM\\SOFTWARE\\JavaSoft\\Java Development Kit",
+			"HKLM\\SOFTWARE\\JavaSoft\\JRE",
+			"HKLM\\SOFTWARE\\WOW6432Node\\JavaSoft\\JDK",
+			"HKLM\\SOFTWARE\\WOW6432Node\\JavaSoft\\Java Development Kit",
+			"HKLM\\SOFTWARE\\WOW6432Node\\JavaSoft\\JRE"
+		]) try {
+			const match = execFileSync("reg", [
+				"query",
+				regPath,
+				"/s",
+				"/v",
+				"JavaHome"
+			], {
+				encoding: "utf8",
+				timeout: 3e3,
+				windowsHide: true
+			}).match(/JavaHome\s+REG_SZ\s+(.+)/);
+			if (match !== null) {
+				const home = match[1].trim();
+				if (existsSync(home)) return home;
+			}
+		} catch {}
+		const userHome = process.env.USERPROFILE ?? "";
+		const candidates = [
+			join(process.env.PROGRAMFILES ?? "C:\\Program Files", "Java"),
+			join(process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)", "Java"),
+			join(userHome, ".jdks"),
+			join(userHome, ".jdks", "jbr-21.0.11")
+		];
+		for (const base of candidates) try {
+			if (!existsSync(base)) continue;
+			const dirs = execFileSync("cmd", [
+				"/c",
+				"dir",
+				"/b",
+				"/ad",
+				base
+			], {
+				encoding: "utf8",
+				timeout: 3e3,
+				windowsHide: true
+			}).split("\n").map((s) => s.trim()).filter((s) => s !== "");
+			let best = null;
+			let bestVer = -1;
+			for (const d of dirs) {
+				const home = join(base, d);
+				if (!existsSync(join(home, "bin", "java.exe"))) continue;
+				const verMatch = d.match(/(\d+)(?:\.|$)/);
+				const score = (verMatch !== null ? parseInt(verMatch[1], 10) : 0) + (/jdk|corretto|temurin/i.test(d) ? 1e3 : 0);
+				if (score > bestVer) {
+					bestVer = score;
+					best = home;
+				}
+			}
+			if (best !== null) return best;
+		} catch {}
+	} else try {
+		const javaPath = execFileSync("which", ["java"], {
+			encoding: "utf8",
+			timeout: 3e3
+		}).trim();
+		if (javaPath !== "") {
+			const realPath = execFileSync("readlink", ["-f", javaPath], {
+				encoding: "utf8",
+				timeout: 3e3
+			}).trim();
+			const home = realPath.replace(/\/bin\/java$/, "");
+			if (home !== realPath && existsSync(home)) return home;
+		}
+	} catch {}
+	return null;
+}
+/** Resolve the Maven bin dir. Priority: config.runtime.mvn > a configured
+*  MVN_PATH > process.env.MAVEN_HOME > `where mvn` / `which mvn`. */
+function resolveMavenBin(configRuntime, globalEnv) {
+	const rtMvn = configRuntime?.mvn?.trim();
+	if (rtMvn) {
+		if (existsSync(rtMvn)) {
+			const base = /mvn(\.cmd|\.bat)?$/i.test(rtMvn) ? rtMvn.replace(/[/\\]mvn(\.cmd|\.bat)?$/i, "") : rtMvn;
+			const binDir = /[/\\]bin$/i.test(base) ? base : join(base, "bin");
+			const exe = process.platform === "win32" ? "mvn.cmd" : "mvn";
+			if (existsSync(join(binDir, exe))) return binDir;
+		}
+	}
+	const gMvn = globalEnv.MVN_PATH?.trim();
+	if (gMvn) {
+		const binDir = /[/\\]bin$/i.test(gMvn) ? gMvn : join(gMvn, "bin");
+		const exe = process.platform === "win32" ? "mvn.cmd" : "mvn";
+		if (existsSync(join(binDir, exe))) return binDir;
+	}
+	const mh = process.env.MAVEN_HOME?.trim();
+	if (mh) {
+		const binDir = /[/\\]bin$/i.test(mh) ? mh : join(mh, "bin");
+		const exe = process.platform === "win32" ? "mvn.cmd" : "mvn";
+		if (existsSync(join(binDir, exe))) return binDir;
+	}
+	try {
+		const which = process.platform === "win32" ? "where" : "which";
+		const arg = process.platform === "win32" ? "mvn.cmd" : "mvn";
+		const out = execFileSync(which, [arg], {
+			encoding: "utf8",
+			timeout: 3e3,
+			windowsHide: true
+		}).split("\n")[0]?.trim();
+		if (out) {
+			const lastSep = Math.max(out.lastIndexOf("/"), out.lastIndexOf("\\"));
+			return lastSep >= 0 ? out.substring(0, lastSep) : out;
+		}
+	} catch {}
+	return null;
+}
+/** Build the spawn env. Priority: config.runtime > globalEnv > process.env >
+*  auto-detect. Injects tool bin dirs into PATH (fixes missing mvn/node/etc). */
+function buildEnv(config, globalEnv) {
+	const env = {
+		...process.env,
+		...globalEnv,
+		...config.env
+	};
+	const isWin = process.platform === "win32";
+	const sep = isWin ? ";" : ":";
+	const toolBins = [];
+	const javaHome = config.runtime?.java?.trim() || globalEnv.JAVA_HOME?.trim() || (process.env.JAVA_HOME?.trim() && existsSync(join(process.env.JAVA_HOME, "bin", isWin ? "java.exe" : "java")) ? process.env.JAVA_HOME.trim() : "");
+	let resolvedJava = javaHome && existsSync(join(javaHome, "bin", isWin ? "java.exe" : "java")) ? javaHome : "";
+	if (!resolvedJava) resolvedJava = resolveJavaHome() ?? "";
+	if (resolvedJava) {
+		env.JAVA_HOME = resolvedJava;
+		toolBins.push(join(resolvedJava, "bin"));
+	}
+	const nodeHome = config.runtime?.node?.trim() || globalEnv.NODE_PATH?.trim() || process.env.NODE_PATH?.trim() || "";
+	let resolvedNode = "";
+	if (nodeHome) {
+		const binDir = /[/\\]bin$/i.test(nodeHome) ? nodeHome : join(nodeHome, "bin");
+		const nodeExe = isWin ? "node.exe" : "node";
+		if (existsSync(join(binDir, nodeExe))) resolvedNode = binDir;
+		else if (existsSync(join(nodeHome, nodeExe))) resolvedNode = nodeHome;
+	}
+	if (resolvedNode) {
+		env.NODE_PATH = resolvedNode.replace(/[/\\]bin$/, "");
+		toolBins.push(resolvedNode);
+	}
+	const pythonHome = config.runtime?.python?.trim() || globalEnv.PYTHON_PATH?.trim() || process.env.PYTHON_PATH?.trim() || "";
+	let resolvedPython = "";
+	if (pythonHome) {
+		const binDir = /[/\\]bin$/i.test(pythonHome) ? pythonHome : join(pythonHome, "bin");
+		const pyNames = isWin ? ["python.exe"] : ["python", "python3"];
+		const hasPy = pyNames.some((n) => existsSync(join(binDir, n)));
+		const hasPyRoot = pyNames.some((n) => existsSync(join(pythonHome, n)));
+		if (hasPy) resolvedPython = binDir;
+		else if (hasPyRoot) resolvedPython = pythonHome;
+	}
+	if (resolvedPython) {
+		env.PYTHON_PATH = resolvedPython.replace(/[/\\]bin$/, "");
+		toolBins.push(resolvedPython);
+	}
+	const mvnBin = resolveMavenBin(config.runtime, globalEnv);
+	if (mvnBin) {
+		env.MAVEN_HOME = mvnBin.replace(/[/\\]bin$/, "");
+		toolBins.push(mvnBin);
+	}
+	if (isWin) {
+		const windir = process.env.WINDIR ?? process.env.SystemRoot ?? "C:\\Windows";
+		const sys32 = process.env.SystemRoot ? join(process.env.SystemRoot, "System32") : "C:\\Windows\\System32";
+		const sysNative = process.env.SystemRoot ? join(process.env.SystemRoot, "SysWOW64") : "C:\\Windows\\SysWOW64";
+		for (const d of [
+			windir,
+			sys32,
+			sysNative
+		]) if (d && !toolBins.includes(d)) toolBins.push(d);
+	}
+	if (toolBins.length > 0) {
+		const existing = env.PATH ?? "";
+		env.PATH = [...toolBins, existing].filter(Boolean).join(sep);
+	}
+	return env;
+}
+/** Ring buffer cap (1 MB of text; each entry's text counted as UTF-16 length). */
+const RING_BUFFER_MAX_CHARS = 1e6;
+/** How long an exited instance stays available for late log reads. */
+const EXIT_RETENTION_MS = 3e4;
+/**
+* Process manager owns the instance table and the WebSocket fan-out.
+* Call `spawn(config, cwd)` to start, `stop(instanceId)` to kill, and
+* `attach(instanceId, ws)` to subscribe a browser to the log stream.
+*/
+var ProcessManager = class {
+	processes = /* @__PURE__ */ new Map();
+	/** Spawn a config as a child process. Returns the new RunInstance. */
+	spawnConfig(config, resolvedCwd, globalEnv = {}) {
+		const id = randomUUID();
+		const now = Date.now();
+		let finalCommand = config.command;
+		if (config.type === "springboot") {
+			const parts = [config.command];
+			const jvm = config.jvmArgs?.trim() ?? "";
+			const appArgs = config.args?.trim() ?? "";
+			if (/spring-boot\s*:/i.test(config.command) || /^mvn\w*\s+spring-boot/i.test(config.command)) {
+				if (jvm !== "") parts.push(`-Dspring-boot.run.jvmArguments="${jvm}"`);
+				if (appArgs !== "") parts.push(`-Dspring-boot.run.arguments="${appArgs}"`);
+			} else {
+				if (jvm !== "") parts.push(jvm);
+				if (appArgs !== "") parts.push(appArgs);
+			}
+			finalCommand = parts.join(" ");
+		} else if (config.args && config.args.trim()) finalCommand = `${config.command} ${config.args.trim()}`;
+		const instance = {
+			id,
+			configId: config.id,
+			configName: config.name,
+			configType: config.type,
+			command: finalCommand,
+			cwd: resolvedCwd,
+			status: "running",
+			pid: 0,
+			startedAt: now,
+			exitedAt: null,
+			exitCode: null
+		};
+		const managed = {
+			instance,
+			child: null,
+			logs: [],
+			logChars: 0,
+			subscribers: /* @__PURE__ */ new Set(),
+			exitTimer: null
+		};
+		let child;
+		try {
+			const cmd = process.platform === "win32" && !/^chcp\s/i.test(finalCommand) ? `chcp 65001 >nul && ${finalCommand}` : finalCommand;
+			child = spawn(cmd, {
+				cwd: resolvedCwd,
+				env: buildEnv(config, globalEnv),
+				shell: true,
+				detached: process.platform !== "win32",
+				windowsHide: false
+			});
+		} catch (error) {
+			instance.status = "error";
+			instance.exitCode = -1;
+			instance.exitedAt = Date.now();
+			this.processes.set(id, managed);
+			this.scheduleCleanup(managed);
+			const msg = error instanceof Error ? error.message : String(error);
+			this.appendLog(managed, "stderr", `Failed to spawn: ${msg}\n`);
+			return instance;
+		}
+		managed.child = child;
+		instance.pid = child.pid ?? 0;
+		this.processes.set(id, managed);
+		child.stdout?.on("data", (chunk) => {
+			this.appendLog(managed, "stdout", chunk.toString("utf8"));
+		});
+		child.stderr?.on("data", (chunk) => {
+			this.appendLog(managed, "stderr", chunk.toString("utf8"));
+		});
+		child.on("error", (error) => {
+			this.appendLog(managed, "stderr", `Process error: ${error.message}\n`);
+			this.setExited(managed, "error", -1);
+		});
+		child.on("close", (code) => {
+			this.setExited(managed, "exited", code ?? 0);
+		});
+		return instance;
+	}
+	/** Stop a running instance (kills the process tree). No-op if not running. */
+	stop(instanceId) {
+		const managed = this.processes.get(instanceId);
+		if (managed === void 0) return false;
+		if (managed.instance.status !== "running") return false;
+		if (managed.child === null) return false;
+		const pid = managed.child.pid;
+		if (pid === void 0) return false;
+		try {
+			if (process.platform === "win32") execFileSync("taskkill", [
+				"/T",
+				"/F",
+				"/PID",
+				String(pid)
+			], {
+				windowsHide: true,
+				stdio: "ignore"
+			});
+			else try {
+				process.kill(-pid, "SIGTERM");
+			} catch {
+				process.kill(pid, "SIGTERM");
+			}
+		} catch {
+			try {
+				managed.child.kill("SIGTERM");
+			} catch {}
+		}
+		this.setExited(managed, "killed", null);
+		return true;
+	}
+	/** List all instances (running + recently exited). */
+	listInstances() {
+		return Array.from(this.processes.values()).map((m) => m.instance);
+	}
+	/** Get one instance by id. */
+	getInstance(instanceId) {
+		return this.processes.get(instanceId)?.instance;
+	}
+	/** Get buffered logs for an instance. */
+	getLogs(instanceId) {
+		return this.processes.get(instanceId)?.logs ?? [];
+	}
+	/** Subscribe a WebSocket to an instance's log stream. */
+	attach(instanceId, ws) {
+		const managed = this.processes.get(instanceId);
+		if (managed === void 0) return false;
+		managed.subscribers.add(ws);
+		ws.on("close", () => {
+			managed.subscribers.delete(ws);
+		});
+		ws.on("error", () => {
+			managed.subscribers.delete(ws);
+		});
+		return true;
+	}
+	/** Append a log entry to the ring buffer and fan out to subscribers. */
+	appendLog(managed, stream, text) {
+		const entry = {
+			stream,
+			text,
+			ts: Date.now()
+		};
+		managed.logs.push(entry);
+		managed.logChars += text.length;
+		while (managed.logChars > RING_BUFFER_MAX_CHARS && managed.logs.length > 1) {
+			const dropped = managed.logs.shift();
+			if (dropped !== void 0) managed.logChars -= dropped.text.length;
+		}
+		const msg = JSON.stringify({
+			type: "log",
+			entry
+		});
+		for (const ws of managed.subscribers) try {
+			if (ws.readyState === WebSocket.OPEN) ws.send(msg);
+		} catch {}
+	}
+	/** Mark an instance as exited and notify subscribers. */
+	setExited(managed, status, exitCode) {
+		if (managed.instance.status !== "running") return;
+		managed.instance.status = status;
+		managed.instance.exitedAt = Date.now();
+		managed.instance.exitCode = exitCode;
+		const msg = JSON.stringify({
+			type: "status",
+			status,
+			exitCode
+		});
+		for (const ws of managed.subscribers) try {
+			if (ws.readyState === WebSocket.OPEN) ws.send(msg);
+		} catch {}
+		this.scheduleCleanup(managed);
+	}
+	/** Schedule instance removal after the retention window. */
+	scheduleCleanup(managed) {
+		if (managed.exitTimer !== null) return;
+		managed.exitTimer = setTimeout(() => {
+			this.processes.delete(managed.instance.id);
+		}, EXIT_RETENTION_MS);
+	}
+	/** Stop all running processes and dispose (plugin teardown). */
+	dispose() {
+		for (const managed of this.processes.values()) {
+			if (managed.exitTimer !== null) clearTimeout(managed.exitTimer);
+			if (managed.instance.status === "running" && managed.child !== null) try {
+				const pid = managed.child.pid;
+				if (pid !== void 0) {
+					if (process.platform === "win32") execFileSync("taskkill", [
+						"/T",
+						"/F",
+						"/PID",
+						String(pid)
+					], {
+						windowsHide: true,
+						stdio: "ignore"
+					});
+					else try {
+						process.kill(-pid, "SIGTERM");
+					} catch {
+						process.kill(pid, "SIGTERM");
+					}
+				}
+			} catch {}
+		}
+		this.processes.clear();
+	}
+};
+//#endregion
+//#region src/host/fence.ts
+function header(headers, name) {
+	const value = headers[name];
+	return typeof value === "string" ? value : void 0;
+}
+/** Normalized URL of a Host-header authority, or undefined when unparsable. */
+function parseAuthority(authority) {
+	try {
+		return new URL(`http://${authority}`);
+	} catch {
+		return;
+	}
+}
+/** Whether a normalized URL hostname names the local loopback authority. */
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	const parts = hostname.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** Canonical authority form: hostname, or hostname:port when a port was written. */
+function canonicalAuthority(entry, entryUrl) {
+	const port = entryUrl.port !== "" ? entryUrl.port : new URL(`https://${entry}`).port;
+	return port === "" ? entryUrl.hostname : `${entryUrl.hostname}:${port}`;
+}
+/** Whether the request authority matches a trustedHosts entry (exact or port-less). */
+function isTrustedAuthority(hostUrl, trustedHosts) {
+	return trustedHosts.some((entry) => {
+		const entryUrl = parseAuthority(entry);
+		if (entryUrl === void 0) return false;
+		return canonicalAuthority(entry, entryUrl) === entryUrl.hostname ? entryUrl.hostname === hostUrl.hostname : entryUrl.host === hostUrl.host;
+	});
+}
+/**
+* Decide whether one request may reach the plugin routes.
+* @param request - node HTTP request facts (headers).
+* @param trustedHosts - non-loopback authorities this deployment serves.
+* @returns true when the Host is ours (loopback or trusted) and browser markers are same-origin.
+*/
+function isTrustedApiRequest(request, trustedHosts) {
+	const host = header(request.headers, "host");
+	if (host === void 0) return false;
+	const hostUrl = parseAuthority(host);
+	if (hostUrl === void 0) return false;
+	if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(hostUrl, trustedHosts)) return false;
+	if (header(request.headers, "sec-fetch-site") === "cross-site") return false;
+	const origin = header(request.headers, "origin");
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/host/gate.ts
+/**
+* Session-scoped path gate for the starter plugin routes. Every config/instance
+* request carries a sessionId (+ optional client cwd) and a path; this gate
+* resolves the session's AUTHORITATIVE working directory from the session
+* store (the same source dsh-better-sidebar uses) and requires the
+* (canonicalized) target to live inside it — a path outside the
+* conversation's cwd is refused, exactly like the sidebar's own fs routes.
+* @module dsh-better-sidebar-starter/host/gate
+*/
+/** Case-insensitive (on win32) containment check with both separators normalized. */
+function isPathInside(root, child) {
+	if (root === "" || child === "") return false;
+	const norm = (value) => value.replaceAll("\\", "/").replace(/\/+$/, "");
+	const normRoot = norm(root);
+	const normChild = norm(child);
+	if (process.platform === "win32") {
+		const a = normRoot.toLowerCase();
+		const b = normChild.toLowerCase();
+		if (b === a) return true;
+		return b.startsWith(`${a}/`);
+	}
+	if (normChild === normRoot) return true;
+	return normChild.startsWith(`${normRoot}/`);
+}
+/** The session's authoritative working directory (header cwd wins, then the
+*  client-provided cwd, then the process cwd — never throws for a blank one). */
+function sessionCwdOf(ctx, sessionId, clientCwd) {
+	const headerCwd = ctx.sessions.get(sessionId)?.header.cwd;
+	if (headerCwd !== void 0 && headerCwd !== "") return headerCwd;
+	if (clientCwd !== void 0 && clientCwd !== "") return clientCwd;
+	return process.cwd();
+}
+/**
+* Build a gate bound to one session scope. The requested path may be
+* absolute (the common case — the sidebar passes absolute paths) or
+* relative to the session cwd; the canonicalized result is required to be
+* inside the (canonicalized) session cwd.
+*/
+function createSessionGate(ctx, sessionId, clientCwd) {
+	return async (raw) => {
+		if (typeof raw !== "string" || raw === "") return {
+			ok: false,
+			error: "empty path"
+		};
+		const cwd = sessionCwdOf(ctx, sessionId, clientCwd);
+		let target = isAbsolute(raw) ? raw : join(cwd, raw);
+		let canonicalCwd;
+		try {
+			target = await realpath(target);
+			canonicalCwd = await realpath(cwd);
+		} catch {
+			return {
+				ok: false,
+				error: "path does not resolve on disk"
+			};
+		}
+		if (!isPathInside(canonicalCwd, target)) return {
+			ok: false,
+			error: "path is outside the session working directory"
+		};
+		return {
+			ok: true,
+			canonical: target
+		};
+	};
+}
+//#endregion
+//#region src/host/configStore.ts
+/**
+* Config store: CRUD for run configurations, persisted as JSON in the
+* session's working directory (`<cwd>/.dsh/run-configs.json`). All paths
+* are canonical (already passed through the session gate) — this service
+* trusts its caller for path safety.
+* @module dsh-better-sidebar-starter/host/configStore
+*/
+const FILE_VERSION = 1;
+const CONFIG_DIR = ".dsh";
+const CONFIG_FILE = "run-configs.json";
+/** Resolve the config file path inside a canonical session cwd. */
+function configFilePath(cwd) {
+	return join(cwd, CONFIG_DIR, CONFIG_FILE);
+}
+/** Read all configs from the session's working directory. */
+async function readConfigs(cwd) {
+	const filePath = configFilePath(cwd);
+	let raw;
+	try {
+		raw = await readFile(filePath, "utf8");
+	} catch {
+		return [];
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed.configs)) return [];
+		return parsed.configs.filter((c) => typeof c === "object" && c !== null && typeof c.id === "string" && typeof c.name === "string" && typeof c.type === "string" && typeof c.command === "string" && typeof c.cwd === "string" && typeof c.env === "object" && c.env !== null && (typeof c.jvmArgs === "string" || c.jvmArgs === void 0) && (typeof c.args === "string" || c.args === void 0) && (typeof c.runtime === "object" || c.runtime === void 0) && typeof c.createdAt === "number" && typeof c.updatedAt === "number" && (c.lastRunAt === null || typeof c.lastRunAt === "number"));
+	} catch {
+		return [];
+	}
+}
+/** Write all configs to the session's working directory (atomic-ish: mkdir then write). */
+async function writeConfigs(cwd, configs) {
+	const filePath = configFilePath(cwd);
+	await mkdir(dirname(filePath), { recursive: true });
+	await writeFile(filePath, JSON.stringify({
+		configs,
+		version: FILE_VERSION
+	}, null, 2), "utf8");
+}
+/** Create a new config or update an existing one (matched by id). */
+async function upsertConfig(cwd, input) {
+	const configs = await readConfigs(cwd);
+	const now = Date.now();
+	if (input.id !== void 0) {
+		const idx = configs.findIndex((c) => c.id === input.id);
+		if (idx >= 0) {
+			const existing = configs[idx];
+			const updated = {
+				...existing,
+				name: input.name,
+				type: input.type ?? existing.type,
+				command: input.command ?? existing.command,
+				cwd: input.cwd ?? existing.cwd,
+				env: input.env ?? existing.env,
+				jvmArgs: input.jvmArgs ?? existing.jvmArgs,
+				args: input.args ?? existing.args,
+				runtime: input.runtime ?? existing.runtime,
+				updatedAt: now
+			};
+			configs[idx] = updated;
+			await writeConfigs(cwd, configs);
+			return updated;
+		}
+	}
+	const config = {
+		id: input.id ?? randomUUID(),
+		name: input.name,
+		type: input.type ?? "custom",
+		command: input.command ?? "",
+		cwd: input.cwd ?? ".",
+		env: input.env ?? {},
+		jvmArgs: input.jvmArgs ?? "",
+		args: input.args ?? "",
+		runtime: input.runtime,
+		createdAt: now,
+		updatedAt: now,
+		lastRunAt: null
+	};
+	configs.push(config);
+	await writeConfigs(cwd, configs);
+	return config;
+}
+/** Delete a config by id. Returns true if the config existed and was removed. */
+async function deleteConfig(cwd, id) {
+	const configs = await readConfigs(cwd);
+	const idx = configs.findIndex((c) => c.id === id);
+	if (idx < 0) return false;
+	configs.splice(idx, 1);
+	await writeConfigs(cwd, configs);
+	return true;
+}
+/** Stamp a config's lastRunAt (called when an instance starts). */
+async function stampLastRun(cwd, id) {
+	const configs = await readConfigs(cwd);
+	const idx = configs.findIndex((c) => c.id === id);
+	if (idx < 0) return;
+	configs[idx].lastRunAt = Date.now();
+	await writeConfigs(cwd, configs);
+}
+//#endregion
+//#region src/host/routes.ts
+/** Route family base. */
+const STARTER_API = {
+	configs: "/api/dsh-better-sidebar-starter/configs",
+	instances: "/api/dsh-better-sidebar-starter/instances",
+	run: "/api/dsh-better-sidebar-starter/run",
+	stop: "/api/dsh-better-sidebar-starter/stop",
+	logsWs: "/api/dsh-better-sidebar-starter/logs",
+	detectEnv: "/api/dsh-better-sidebar-starter/detect-env"
+};
+/** Cap on JSON request bodies. */
+const MAX_JSON_BODY_BYTES = 1048576;
+/** One noServer WebSocket server for log streams. */
+const logsWss = new WebSocketServer({ noServer: true });
+function writeJson(res, status, body) {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"referrer-policy": "no-referrer"
+	});
+	res.end(payload);
+}
+async function readJsonBody(req) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		const buffer = chunk;
+		size += buffer.length;
+		if (size > MAX_JSON_BODY_BYTES) return void 0;
+		chunks.push(buffer);
+	}
+	try {
+		const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+		return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+function queryParam(url, name) {
+	const value = url.searchParams.get(name);
+	return value === null ? void 0 : value;
+}
+/**
+* Build every starter route plus the logs WebSocket upgrade.
+* @param deps - ctx, kernels (process manager), fence.
+* @returns routes and the upgrade route.
+*/
+function makeRoutes(deps) {
+	const { ctx, kernels, fence } = deps;
+	const guard = (req, res, method) => {
+		if (!fence(req)) {
+			writeJson(res, 403, { error: "forbidden" });
+			return false;
+		}
+		if (req.method !== method) {
+			writeJson(res, 405, { error: `method not allowed: ${req.method ?? ""}` });
+			return false;
+		}
+		return true;
+	};
+	/** Resolve the session cwd (canonicalized through the gate). */
+	const resolveCwd = async (url, res) => {
+		const sessionId = queryParam(url, "sessionId");
+		if (sessionId === void 0 || sessionId === "") {
+			writeJson(res, 400, { error: "sessionId is required" });
+			return null;
+		}
+		const cwd = sessionCwdOf(ctx, sessionId, queryParam(url, "cwd"));
+		const verdict = await createSessionGate(ctx, sessionId, queryParam(url, "cwd"))(cwd);
+		if (!verdict.ok) {
+			writeJson(res, 400, { error: `workspace gate: ${verdict.error}` });
+			return null;
+		}
+		return verdict.canonical;
+	};
+	return {
+		routes: [
+			{
+				kind: "exact",
+				path: STARTER_API.configs,
+				handler: async (req, res) => {
+					if (!fence(req)) {
+						writeJson(res, 403, { error: "forbidden" });
+						return;
+					}
+					const url = new URL(req.url ?? "/", "http://localhost");
+					const method = req.method ?? "GET";
+					if (method === "GET") {
+						const cwd = await resolveCwd(url, res);
+						if (cwd === null) return;
+						writeJson(res, 200, { configs: await readConfigs(cwd) });
+						return;
+					}
+					if (method === "POST") {
+						const cwd = await resolveCwd(url, res);
+						if (cwd === null) return;
+						const body = await readJsonBody(req);
+						if (body === void 0 || body.config === void 0 || typeof body.config !== "object") {
+							writeJson(res, 400, { error: "invalid JSON body: { config } required" });
+							return;
+						}
+						const input = body.config;
+						if (typeof input.name !== "string" || input.name.trim() === "") {
+							writeJson(res, 400, { error: "config.name is required" });
+							return;
+						}
+						writeJson(res, 200, { config: await upsertConfig(cwd, {
+							id: typeof input.id === "string" ? input.id : void 0,
+							name: input.name,
+							type: typeof input.type === "string" ? input.type : "custom",
+							command: typeof input.command === "string" ? input.command : "",
+							cwd: typeof input.cwd === "string" ? input.cwd : ".",
+							env: typeof input.env === "object" && input.env !== null ? input.env : {},
+							jvmArgs: typeof input.jvmArgs === "string" ? input.jvmArgs : "",
+							args: typeof input.args === "string" ? input.args : "",
+							runtime: typeof input.runtime === "object" && input.runtime !== null ? input.runtime : void 0
+						}) });
+						return;
+					}
+					if (method === "DELETE") {
+						const cwd = await resolveCwd(url, res);
+						if (cwd === null) return;
+						const id = queryParam(url, "id");
+						if (id === void 0) {
+							writeJson(res, 400, { error: "id is required" });
+							return;
+						}
+						const removed = await deleteConfig(cwd, id);
+						for (const inst of kernels.listInstances()) if (inst.configId === id && inst.status === "running") kernels.stop(inst.id);
+						writeJson(res, 200, {
+							ok: true,
+							removed
+						});
+						return;
+					}
+					writeJson(res, 405, { error: `method not allowed: ${method}` });
+				}
+			},
+			{
+				kind: "exact",
+				path: STARTER_API.instances,
+				handler: async (req, res) => {
+					if (!guard(req, res, "GET")) return;
+					const sessionId = queryParam(new URL(req.url ?? "/", "http://localhost"), "sessionId");
+					if (sessionId === void 0 || sessionId === "") {
+						writeJson(res, 400, { error: "sessionId is required" });
+						return;
+					}
+					writeJson(res, 200, { instances: kernels.listInstances() });
+				}
+			},
+			{
+				kind: "exact",
+				path: STARTER_API.run,
+				handler: async (req, res) => {
+					if (!guard(req, res, "POST")) return;
+					const url = new URL(req.url ?? "/", "http://localhost");
+					const cwd = await resolveCwd(url, res);
+					if (cwd === null) return;
+					const body = await readJsonBody(req);
+					if (body === void 0 || typeof body.configId !== "string") {
+						writeJson(res, 400, { error: "invalid JSON body: { configId } required" });
+						return;
+					}
+					const config = (await readConfigs(cwd)).find((c) => c.id === body.configId);
+					if (config === void 0) {
+						writeJson(res, 404, { error: "config not found" });
+						return;
+					}
+					const { isAbsolute, resolve } = await import("node:path");
+					const configCwd = config.cwd === "." || config.cwd === "" ? cwd : isAbsolute(config.cwd) ? config.cwd : resolve(cwd, config.cwd);
+					const verdict = await createSessionGate(ctx, queryParam(url, "sessionId") ?? "", queryParam(url, "cwd"))(configCwd);
+					if (!verdict.ok) {
+						writeJson(res, 400, { error: `config cwd gate: ${verdict.error}` });
+						return;
+					}
+					await stampLastRun(cwd, config.id);
+					const globalEnv = typeof body.globalEnv === "object" && body.globalEnv !== null ? body.globalEnv : {};
+					writeJson(res, 200, { instance: kernels.spawnConfig(config, verdict.canonical, globalEnv) });
+				}
+			},
+			{
+				kind: "exact",
+				path: STARTER_API.stop,
+				handler: async (req, res) => {
+					if (!guard(req, res, "POST")) return;
+					const body = await readJsonBody(req);
+					if (body === void 0 || typeof body.instanceId !== "string") {
+						writeJson(res, 400, { error: "invalid JSON body: { instanceId } required" });
+						return;
+					}
+					writeJson(res, 200, {
+						ok: true,
+						stopped: kernels.stop(body.instanceId)
+					});
+				}
+			},
+			{
+				kind: "exact",
+				path: STARTER_API.detectEnv,
+				handler: async (req, res) => {
+					if (!fence(req)) {
+						writeJson(res, 403, { error: "forbidden" });
+						return;
+					}
+					const { existsSync } = await import("node:fs");
+					const { join } = await import("node:path");
+					const { execFileSync } = await import("node:child_process");
+					const isWin = process.platform === "win32";
+					const result = {};
+					result.home = process.env.USERPROFILE ?? process.env.HOME ?? "";
+					result._diagSystemRoot = process.env.SystemRoot ?? process.env.WINDIR ?? "(none)";
+					result._diagPathHasSystem32 = (process.env.PATH ?? "").toLowerCase().includes("system32");
+					if (process.env.JAVA_HOME && process.env.JAVA_HOME.trim() !== "") {
+						const home = process.env.JAVA_HOME.trim();
+						if (existsSync(join(home, "bin", isWin ? "java.exe" : "java"))) result.javaHome = home;
+					}
+					if (result.javaHome === void 0) {
+						const userHome = process.env.USERPROFILE ?? process.env.HOME ?? "";
+						const scanRoots = isWin ? [join(userHome, ".jdks")] : [
+							"/Library/Java/JavaVirtualMachines",
+							join(userHome, "Library/Java/JavaVirtualMachines"),
+							"/opt/homebrew/opt",
+							"/usr/lib/jvm",
+							"/usr/java"
+						];
+						const listDirs = (base) => {
+							if (!existsSync(base)) return [];
+							if (isWin) return execFileSync("cmd", [
+								"/c",
+								"dir",
+								"/b",
+								"/ad",
+								base
+							], {
+								encoding: "utf8",
+								timeout: 3e3,
+								windowsHide: true
+							}).split("\n").map((s) => s.trim()).filter((s) => s !== "");
+							return execFileSync("ls", [
+								"-1",
+								"-p",
+								base
+							], {
+								encoding: "utf8",
+								timeout: 3e3
+							}).split("\n").map((s) => s.trim().replace(/\/$/, "")).filter((s) => s !== "");
+						};
+						for (const base of scanRoots) try {
+							const dirs = listDirs(base);
+							let best = null;
+							let bestScore = -1;
+							for (const d of dirs) {
+								const home = join(base, d);
+								if (existsSync(join(home, "bin", isWin ? "java.exe" : "java"))) {
+									const verMatch = d.match(/(\d+)(?:\.|$)/);
+									const score = (verMatch ? parseInt(verMatch[1], 10) : 0) + (/jdk|corretto|temurin|zulu|liberica/i.test(d) ? 1e3 : 0);
+									if (score > bestScore) {
+										bestScore = score;
+										best = home;
+									}
+								}
+							}
+							if (best !== null) {
+								result.javaHome = best;
+								break;
+							}
+						} catch {}
+					}
+					if (process.env.NODE_PATH && process.env.NODE_PATH.trim() !== "") result.nodePath = process.env.NODE_PATH.trim();
+					else try {
+						const nodeBin = execFileSync(isWin ? "where" : "which", isWin ? ["node.exe"] : ["node"], {
+							encoding: "utf8",
+							timeout: 3e3,
+							windowsHide: true
+						}).split("\n")[0]?.trim();
+						if (nodeBin) {
+							const lastSep = Math.max(nodeBin.lastIndexOf("/"), nodeBin.lastIndexOf("\\"));
+							result.nodePath = lastSep >= 0 ? nodeBin.substring(0, lastSep) : nodeBin;
+						}
+					} catch {}
+					if (process.env.PYTHON_PATH && process.env.PYTHON_PATH.trim() !== "") result.pythonPath = process.env.PYTHON_PATH.trim();
+					else try {
+						const pyBin = execFileSync(isWin ? "where" : "which", isWin ? ["python.exe"] : ["python3"], {
+							encoding: "utf8",
+							timeout: 3e3,
+							windowsHide: true
+						}).split("\n")[0]?.trim();
+						if (pyBin) {
+							const lastSep = Math.max(pyBin.lastIndexOf("/"), pyBin.lastIndexOf("\\"));
+							result.pythonPath = lastSep >= 0 ? pyBin.substring(0, lastSep) : pyBin;
+						}
+					} catch {}
+					if (process.env.MAVEN_HOME && process.env.MAVEN_HOME.trim() !== "") result.mvnPath = process.env.MAVEN_HOME.trim();
+					else if (process.env.MVN_PATH && process.env.MVN_PATH.trim() !== "") result.mvnPath = process.env.MVN_PATH.trim();
+					else try {
+						const mvnBin = execFileSync(isWin ? "where" : "which", isWin ? ["mvn.cmd"] : ["mvn"], {
+							encoding: "utf8",
+							timeout: 3e3,
+							windowsHide: true
+						}).split("\n")[0]?.trim();
+						if (mvnBin) {
+							const lastSep = Math.max(mvnBin.lastIndexOf("/"), mvnBin.lastIndexOf("\\"));
+							result.mvnPath = lastSep >= 0 ? mvnBin.substring(0, lastSep) : mvnBin;
+						}
+					} catch {}
+					writeJson(res, 200, result);
+				}
+			}
+		],
+		upgrade: {
+			path: STARTER_API.logsWs,
+			handler: (req, socket, head) => {
+				if (!fence(req)) {
+					socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+					socket.destroy();
+					return;
+				}
+				const instanceId = queryParam(new URL(req.url ?? "/", "http://localhost"), "instanceId");
+				if (instanceId === void 0 || instanceId === "") {
+					socket.write("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+					socket.destroy();
+					return;
+				}
+				const instance = kernels.getInstance(instanceId);
+				if (instance === void 0) {
+					socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
+					socket.destroy();
+					return;
+				}
+				logsWss.handleUpgrade(req, socket, head, (ws) => {
+					const logs = kernels.getLogs(instanceId);
+					ws.send(JSON.stringify({
+						type: "history",
+						entries: logs
+					}));
+					ws.send(JSON.stringify({
+						type: "status",
+						status: instance.status,
+						exitCode: instance.exitCode
+					}));
+					kernels.attach(instanceId, ws);
+				});
+			}
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/** Plugin identity for cordis.yml rows / the bundle patch. */
+const name = "dsh-better-sidebar-starter";
+/** Services required before mounting: the webserver routes, the session
+*  store (authoritative cwd for the path gate), and the web runtime's
+*  trusted hosts (the /api gateway's trust source). */
+const inject = [
+	"webServer",
+	"sessions",
+	"webRuntime"
+];
+/** Plugin body: mount the fenced starter routes and the process lifecycle. */
+function apply(ctx) {
+	const fence = (req) => isTrustedApiRequest(req, ctx.webRuntime.trustedHosts);
+	const kernels = new ProcessManager();
+	ctx.effect(() => {
+		const { routes, upgrade } = makeRoutes({
+			ctx,
+			kernels,
+			fence
+		});
+		const disposers = routes.map((route) => ctx.webServer.register(route));
+		disposers.push(ctx.webServer.registerUpgrade(upgrade));
+		return () => {
+			for (const dispose of disposers) try {
+				dispose();
+			} catch {}
+		};
+	}, "dsh-better-sidebar-starter: routes");
+	ctx.effect(() => () => {
+		kernels.dispose();
+	}, "dsh-better-sidebar-starter: teardown");
+}
+//#endregion
+export { apply, inject, name };