godot-daedalus_backend 1.0.2 → 1.0.4

package/README.md

@@ -40,7 +40,7 @@ npm install godot-daedalus_backend
 After installing the package, start it through the published bin command:
 
 ```powershell
-$env:PORT = "8080"
+$env:PORT = "38180"
 godot-daedalus-backend
 ```
 
@@ -71,6 +71,29 @@ Then run:
 npm run daedalus
 ```
 
+## Daedalus Manager
+
+The package also ships `godot-daedalus-manager`, a JSON-first manager CLI used by the Godot plugin for stable install, update, launch, rollback, and diagnostics workflows.
+
+```powershell
+godot-daedalus-manager --json status --project "D:\GodotProjects\example"
+godot-daedalus-manager --json backend install
+godot-daedalus-manager --json backend start --port 38180
+godot-daedalus-manager --json backend stop
+godot-daedalus-manager --json backend rollback
+```
+
+Backend installs are versioned under `%APPDATA%\.godot_daedalus\backend\versions\<version>`. The manager switches `%APPDATA%\.godot_daedalus\backend\current.json` after a new version is staged, avoiding in-place edits of a running `node_modules` directory.
+
+Frontend plugin updates are staged rather than hot-applied. GitHub releases should provide:
+
+```text
+godot-daedalus-plugin-vX.Y.Z.zip
+godot-daedalus-plugin-vX.Y.Z.manifest.json
+```
+
+The zip must contain `addons/godot_daedalus/plugin.cfg`. The manifest must include `version`, `tag`, `sha256`, `assetName`, and optionally `minGodotVersion`.
+
 ## Run The Godot MCP Server
 
 The standalone Godot MCP server requires a Godot project path:

package/bin/godot-daedalus-manager.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runTsxEntry } from "./run-tsx-entry.js";
+
+runTsxEntry("src/manager/cli.ts");

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "godot-daedalus_backend",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "TypeScript backend for the Godot Daedalus editor assistant plugin.",
   "main": "./src/main.ts",
   "bin": {
     "godot-daedalus-backend": "bin/godot-daedalus-backend.js",
+    "godot-daedalus-manager": "bin/godot-daedalus-manager.js",
     "godot-daedalus-mcp": "bin/godot-daedalus-mcp.js",
     "godot-daedalus-terminal-mcp": "bin/godot-daedalus-terminal-mcp.js"
   },

package/src/main.ts

@@ -1,7 +1,7 @@
 import { createServer } from "./server/websocket-server.js";
 import { McpHost } from "./mcp/mcp-host.js";
 
-const DEFAULT_PORT: number = 8080;
+const DEFAULT_PORT: number = 38180;
 const portText: string = process.env.PORT ?? String(DEFAULT_PORT);
 const port: number = Number.parseInt(portText, 10);
 

package/src/manager/backend.ts

@@ -0,0 +1,363 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir, readdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { createConnection } from "node:net";
+import { BACKEND_BIN_NAME, BACKEND_PACKAGE_NAME, DEFAULT_BACKEND_PORT, type BackendCurrentFile, type BackendPidFile } from "./types.js";
+import { ManagerError } from "./manager-error.js";
+import { assertInside, getManagerPaths, type ManagerPaths } from "./paths.js";
+import { readJsonFile, writeJsonFile } from "./json-file.js";
+import { runCommand, stopProcess, isProcessAlive, type CommandResult } from "./process.js";
+
+const MAX_BACKEND_VERSIONS: number = 3;
+
+export async function getLatestBackendVersion(): Promise<string | null> {
+	const result: CommandResult = await runCommand(getNpmCommand(), ["view", BACKEND_PACKAGE_NAME, "version"], { timeoutMs: 20000 });
+	if (result.exitCode !== 0) {
+		return null;
+	}
+
+	const version: string = result.stdout.trim().split(/\s+/)[0] ?? "";
+	return version.length === 0 ? null : version;
+}
+
+export async function getCurrentBackend(): Promise<BackendCurrentFile | null> {
+	const paths: ManagerPaths = getManagerPaths();
+	return readJsonFile<BackendCurrentFile>(paths.backendCurrentPath);
+}
+
+export async function installBackend(versionSpec: string = "latest"): Promise<{ version: string; path: string }> {
+	const paths: ManagerPaths = getManagerPaths();
+	await mkdir(paths.backendVersionsDir, { recursive: true });
+	const packageSpec: string = await resolveBackendPackageSpec(versionSpec);
+	const stagingName: string = versionSpec.match(/^\d+\.\d+\.\d+$/) !== null || versionSpec === "latest"
+		? `${packageSpec.replace(`${BACKEND_PACKAGE_NAME}@`, "")}.staging`
+		: `manual-${Date.now()}.staging`;
+	const stagingDir: string = assertInside(paths.backendVersionsDir, join(paths.backendVersionsDir, stagingName));
+	const previous: BackendCurrentFile | null = await getCurrentBackend();
+
+	await rm(stagingDir, { recursive: true, force: true });
+	await mkdir(stagingDir, { recursive: true });
+	const installResult: CommandResult = await runCommand(getNpmCommand(), ["install", "--prefix", stagingDir, "--prefer-online", packageSpec], { timeoutMs: 120000 });
+	if (installResult.exitCode !== 0) {
+		await rm(stagingDir, { recursive: true, force: true });
+		throw new ManagerError({
+			code: "install_failed",
+			message: `Failed to install ${packageSpec}`,
+			details: installResult.stderr || installResult.stdout,
+			suggestedAction: "Check your npm registry/network, then try again."
+		});
+	}
+
+	const installedVersion: string = await readInstalledBackendVersion(stagingDir);
+	const versionDir: string = assertInside(paths.backendVersionsDir, join(paths.backendVersionsDir, installedVersion));
+	const packageJsonPath: string = join(stagingDir, "node_modules", BACKEND_PACKAGE_NAME, "package.json");
+	await rm(versionDir, { recursive: true, force: true });
+	await rename(stagingDir, versionDir);
+
+	await writeJsonFile(paths.backendCurrentPath, {
+		version: installedVersion,
+		path: versionDir,
+		...(previous === null ? {} : { previousVersion: previous.version }),
+		updatedAt: new Date().toISOString()
+	} satisfies BackendCurrentFile);
+	await pruneBackendVersions(installedVersion, previous?.version);
+	return { version: installedVersion, path: versionDir };
+}
+
+async function resolveBackendPackageSpec(versionSpec: string): Promise<string> {
+	if (versionSpec === "latest") {
+		return `${BACKEND_PACKAGE_NAME}@${await requireLatestBackendVersion()}`;
+	}
+	if (versionSpec.match(/^\d+\.\d+\.\d+(?:[-+].*)?$/) !== null) {
+		return `${BACKEND_PACKAGE_NAME}@${versionSpec}`;
+	}
+	return versionSpec;
+}
+
+export async function startBackend(port: number = DEFAULT_BACKEND_PORT): Promise<BackendPidFile> {
+	const paths: ManagerPaths = getManagerPaths();
+	const current: BackendCurrentFile | null = await getCurrentBackend();
+	if (current === null) {
+		throw new ManagerError({
+			code: "not_installed",
+			message: "Daedalus backend is not installed.",
+			suggestedAction: "Run godot-daedalus-manager backend install --json."
+		});
+	}
+
+	const existingPid: BackendPidFile | null = await readJsonFile<BackendPidFile>(paths.backendPidPath);
+	if (existingPid !== null && isProcessAlive(existingPid.pid)) {
+		return existingPid;
+	}
+
+	await mkdir(paths.logsDir, { recursive: true });
+	await mkdir(paths.backendRuntimeDir, { recursive: true });
+	const logPath: string = join(paths.logsDir, `backend_${current.version}_${Date.now()}.log`);
+	const out = createWriteStream(logPath, { flags: "a" });
+	const packageRoot: string = join(current.path, "node_modules", BACKEND_PACKAGE_NAME);
+	const entryPath: string = join(packageRoot, "src", "main.ts");
+	const child = (await import("node:child_process")).spawn(
+		process.execPath,
+		["--import", "tsx", entryPath],
+		{
+			cwd: packageRoot,
+			env: { ...process.env, PORT: String(port) },
+			detached: true,
+			windowsHide: true,
+			stdio: ["ignore", "pipe", "pipe"]
+		}
+	);
+	child.stdout.pipe(out, { end: false });
+	child.stderr.pipe(out, { end: false });
+	child.unref();
+
+	const pidFile: BackendPidFile = {
+		pid: child.pid ?? 0,
+		version: current.version,
+		port,
+		url: `ws://localhost:${port}`,
+		logPath,
+		startedAt: new Date().toISOString()
+	};
+	await writeJsonFile(paths.backendPidPath, pidFile);
+	return pidFile;
+}
+
+export async function stopBackend(): Promise<{ stopped: boolean; pid: number | null; details: string }> {
+	const paths: ManagerPaths = getManagerPaths();
+	const pidFile: BackendPidFile | null = await readJsonFile<BackendPidFile>(paths.backendPidPath);
+	if (pidFile === null) {
+		return { stopped: false, pid: null, details: "No backend pid file found." };
+	}
+
+	if (!isProcessAlive(pidFile.pid)) {
+		await rm(paths.backendPidPath, { force: true });
+		return { stopped: false, pid: pidFile.pid, details: "Backend process was already stopped." };
+	}
+
+	const result: CommandResult = await stopProcess(pidFile.pid);
+	if (result.exitCode === 0 || !isProcessAlive(pidFile.pid)) {
+		await rm(paths.backendPidPath, { force: true });
+		return { stopped: true, pid: pidFile.pid, details: result.stdout || result.stderr };
+	}
+
+	throw new ManagerError({
+		code: "process_failed",
+		message: `Failed to stop backend process ${pidFile.pid}`,
+		details: result.stderr || result.stdout,
+		logPath: pidFile.logPath
+	});
+}
+
+export async function rollbackBackend(): Promise<BackendCurrentFile> {
+	const paths: ManagerPaths = getManagerPaths();
+	const current: BackendCurrentFile | null = await getCurrentBackend();
+	if (current === null || current.previousVersion === undefined) {
+		throw new ManagerError({
+			code: "not_installed",
+			message: "No previous backend version is available for rollback."
+		});
+	}
+
+	const previousDir: string = join(paths.backendVersionsDir, current.previousVersion);
+	const previousStats = await stat(previousDir).catch((): null => null);
+	if (previousStats === null || !previousStats.isDirectory()) {
+		throw new ManagerError({
+			code: "not_installed",
+			message: `Previous backend version is missing: ${current.previousVersion}`
+		});
+	}
+
+	const rollbackFile: BackendCurrentFile = {
+		version: current.previousVersion,
+		path: previousDir,
+		previousVersion: current.version,
+		updatedAt: new Date().toISOString()
+	};
+	await writeJsonFile(paths.backendCurrentPath, rollbackFile);
+	return rollbackFile;
+}
+
+export async function healthBackend(url: string = `ws://localhost:${DEFAULT_BACKEND_PORT}`): Promise<{ ok: boolean; url: string; error: string | null; result?: unknown }> {
+	try {
+		const parsedUrl: URL = new URL(url);
+		const port: number = parsedUrl.port === "" ? 80 : Number.parseInt(parsedUrl.port, 10);
+		const host: string = parsedUrl.hostname;
+		const path: string = `${parsedUrl.pathname}${parsedUrl.search}`;
+		const key: string = randomBytes(16).toString("base64");
+		return await new Promise((resolveHealth): void => {
+			const socket = createConnection({ host, port });
+			let buffer: Buffer = Buffer.alloc(0);
+			let handshakeDone: boolean = false;
+			let settled: boolean = false;
+			const finish = (result: { ok: boolean; url: string; error: string | null; result?: unknown }): void => {
+				if (settled) {
+					return;
+				}
+				settled = true;
+				clearTimeout(timer);
+				socket.destroy();
+				resolveHealth(result);
+			};
+			const timer = setTimeout((): void => {
+				finish({ ok: false, url, error: "Timed out waiting for backend health." });
+			}, 2500);
+			socket.on("connect", (): void => {
+				socket.write([
+					`GET ${path === "" ? "/" : path} HTTP/1.1`,
+					`Host: ${host}:${port}`,
+					"Upgrade: websocket",
+					"Connection: Upgrade",
+					`Sec-WebSocket-Key: ${key}`,
+					"Sec-WebSocket-Version: 13",
+					"",
+					""
+				].join("\r\n"));
+			});
+			socket.on("data", (chunk: Buffer): void => {
+				buffer = Buffer.concat([buffer, chunk]);
+				if (!handshakeDone) {
+					const headerEnd: number = buffer.indexOf("\r\n\r\n");
+					if (headerEnd < 0) {
+						return;
+					}
+					const headerText: string = buffer.subarray(0, headerEnd).toString("utf8");
+					if (!headerText.startsWith("HTTP/1.1 101")) {
+						finish({ ok: false, url, error: `Unexpected WebSocket handshake: ${headerText.split("\r\n")[0] ?? headerText}` });
+						return;
+					}
+					handshakeDone = true;
+					buffer = buffer.subarray(headerEnd + 4);
+					socket.write(createClientTextFrame(JSON.stringify({ id: "manager-health", method: "backend.health", params: {} })));
+				}
+				const frame = tryReadServerTextFrame(buffer);
+				if (frame === null) {
+					return;
+				}
+				const parsed: unknown = JSON.parse(frame.text);
+				finish({ ok: true, url, error: null, result: parsed });
+			});
+			socket.on("error", (error: Error): void => {
+				finish({ ok: false, url, error: error.message });
+			});
+		});
+	} catch (error: unknown) {
+		return { ok: false, url, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function createClientTextFrame(text: string): Buffer {
+	const payload: Buffer = Buffer.from(text, "utf8");
+	const mask: Buffer = randomBytes(4);
+	const headerLength: number = payload.length < 126 ? 6 : 8;
+	const frame: Buffer = Buffer.alloc(headerLength + payload.length);
+	frame[0] = 0x81;
+	if (payload.length < 126) {
+		frame[1] = 0x80 | payload.length;
+		mask.copy(frame, 2);
+		for (let index: number = 0; index < payload.length; index += 1) {
+			frame[6 + index] = payload[index]! ^ mask[index % 4]!;
+		}
+		return frame;
+	}
+	frame[1] = 0x80 | 126;
+	frame.writeUInt16BE(payload.length, 2);
+	mask.copy(frame, 4);
+	for (let index: number = 0; index < payload.length; index += 1) {
+		frame[8 + index] = payload[index]! ^ mask[index % 4]!;
+	}
+	return frame;
+}
+
+function tryReadServerTextFrame(buffer: Buffer): { text: string; bytesRead: number } | null {
+	if (buffer.length < 2) {
+		return null;
+	}
+	const opcode: number = buffer[0]! & 0x0f;
+	let payloadLength: number = buffer[1]! & 0x7f;
+	let offset: number = 2;
+	if (payloadLength === 126) {
+		if (buffer.length < 4) {
+			return null;
+		}
+		payloadLength = buffer.readUInt16BE(2);
+		offset = 4;
+	} else if (payloadLength === 127) {
+		return null;
+	}
+	if (buffer.length < offset + payloadLength) {
+		return null;
+	}
+	if (opcode !== 1) {
+		return null;
+	}
+	return {
+		text: buffer.subarray(offset, offset + payloadLength).toString("utf8"),
+		bytesRead: offset + payloadLength
+	};
+}
+
+export async function getInstalledBackendVersion(): Promise<string | null> {
+	const current: BackendCurrentFile | null = await getCurrentBackend();
+	return current?.version ?? null;
+}
+
+export async function getRunningBackend(): Promise<BackendPidFile | null> {
+	const paths: ManagerPaths = getManagerPaths();
+	const pidFile: BackendPidFile | null = await readJsonFile<BackendPidFile>(paths.backendPidPath);
+	if (pidFile === null || !isProcessAlive(pidFile.pid)) {
+		return null;
+	}
+	return pidFile;
+}
+
+async function requireLatestBackendVersion(): Promise<string> {
+	const latest: string | null = await getLatestBackendVersion();
+	if (latest === null) {
+		throw new ManagerError({
+			code: "network_error",
+			message: "Could not read latest backend version from npm.",
+			suggestedAction: "Check npm network access, then try again."
+		});
+	}
+	return latest;
+}
+
+async function readInstalledBackendVersion(versionDir: string): Promise<string> {
+	const manifestText: string = await readFile(join(versionDir, "node_modules", BACKEND_PACKAGE_NAME, "package.json"), "utf8");
+	const manifest = JSON.parse(manifestText) as { version?: unknown };
+	if (typeof manifest.version !== "string" || manifest.version.trim() === "") {
+		throw new ManagerError({ code: "install_failed", message: "Installed backend package has no version." });
+	}
+	return manifest.version;
+}
+
+async function pruneBackendVersions(currentVersion: string, previousVersion: string | undefined): Promise<void> {
+	const paths: ManagerPaths = getManagerPaths();
+	const entries = await readdir(paths.backendVersionsDir, { withFileTypes: true }).catch(() => []);
+	const keep: Set<string> = new Set([currentVersion, ...(previousVersion === undefined ? [] : [previousVersion])]);
+	const versions = entries
+		.filter((entry) => entry.isDirectory() && !entry.name.endsWith(".staging"))
+		.map((entry) => entry.name)
+		.sort()
+		.reverse();
+	for (const version of versions) {
+		if (keep.has(version)) {
+			continue;
+		}
+		if (keep.size < MAX_BACKEND_VERSIONS) {
+			keep.add(version);
+			continue;
+		}
+		await rm(assertInside(paths.backendVersionsDir, join(paths.backendVersionsDir, version)), { recursive: true, force: true });
+	}
+}
+
+export function sha256Text(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function getNpmCommand(): string {
+	return process.platform === "win32" ? "npm.cmd" : "npm";
+}

package/src/manager/cli.ts

@@ -0,0 +1,182 @@
+import { DEFAULT_BACKEND_PORT, type ManagerResult } from "./types.js";
+import { toManagerFailure, ManagerError } from "./manager-error.js";
+import { installBackend, rollbackBackend, startBackend, stopBackend, healthBackend, getLatestBackendVersion } from "./backend.js";
+import { applyFrontendUpdate, downloadAndStageFrontend, getLatestFrontendVersion, rollbackFrontend } from "./frontend.js";
+import { readStatus } from "./status.js";
+
+type ParsedArgs = {
+	json: boolean;
+	command: string[];
+	options: Map<string, string | true>;
+};
+
+async function main(): Promise<void> {
+	const args: ParsedArgs = parseArgs(process.argv.slice(2));
+	try {
+		const result: ManagerResult = await handleCommand(args);
+		writeResult(result, args.json);
+		process.exitCode = result.ok ? 0 : 1;
+	} catch (error: unknown) {
+		const failure = toManagerFailure(error);
+		writeResult(failure, args.json);
+		process.exitCode = 1;
+	}
+}
+
+async function handleCommand(args: ParsedArgs): Promise<ManagerResult> {
+	const [first, second] = args.command;
+	if (first === undefined || first === "help" || first === "--help") {
+		return { ok: true, help: getHelpText() };
+	}
+
+	if (first === "status") {
+		return { ok: true, status: await readStatus(getOptionalStringOption(args, "project")) };
+	}
+
+	if (first === "doctor") {
+		return {
+			ok: true,
+			status: await readStatus(getOptionalStringOption(args, "project")),
+			node: process.version,
+			platform: process.platform
+		};
+	}
+
+	if (first === "backend") {
+		if (second === "install" || second === "update") {
+			return { ok: true, backend: await installBackend(getStringOption(args, "version") ?? "latest") };
+		}
+		if (second === "start") {
+			return { ok: true, backend: await startBackend(getNumberOption(args, "port") ?? DEFAULT_BACKEND_PORT) };
+		}
+		if (second === "stop") {
+			return { ok: true, backend: await stopBackend() };
+		}
+		if (second === "health") {
+			return { ok: true, health: await healthBackend(getStringOption(args, "url") ?? `ws://localhost:${DEFAULT_BACKEND_PORT}`) };
+		}
+		if (second === "rollback") {
+			return { ok: true, backend: await rollbackBackend() };
+		}
+		if (second === "latest") {
+			return { ok: true, version: await getLatestBackendVersion() };
+		}
+	}
+
+	if (first === "frontend") {
+		if (second === "check") {
+			return { ok: true, status: (await readStatus(getOptionalStringOption(args, "project"))).frontend };
+		}
+		if (second === "download" || second === "stage") {
+			const version: string | null = getStringOption(args, "version") ?? await getLatestFrontendVersion();
+			if (version === null) {
+				throw new ManagerError({ code: "network_error", message: "Could not resolve latest frontend version." });
+			}
+			return { ok: true, frontend: await downloadAndStageFrontend(version) };
+		}
+		if (second === "apply") {
+			return { ok: true, frontend: await applyFrontendUpdate(getRequiredStringOption(args, "project")) };
+		}
+		if (second === "rollback") {
+			return { ok: true, frontend: await rollbackFrontend(getRequiredStringOption(args, "project")) };
+		}
+	}
+
+	throw new ManagerError({
+		code: "invalid_arguments",
+		message: `Unknown manager command: ${args.command.join(" ")}`,
+		details: getHelpText()
+	});
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+	const command: string[] = [];
+	const options: Map<string, string | true> = new Map();
+	let json: boolean = false;
+	for (let index: number = 0; index < argv.length; index += 1) {
+		const arg: string = argv[index]!;
+		if (arg === "--json") {
+			json = true;
+			continue;
+		}
+		if (arg.startsWith("--")) {
+			const name: string = arg.slice(2);
+			const next: string | undefined = argv[index + 1];
+			if (next !== undefined && !next.startsWith("--")) {
+				options.set(name, next);
+				index += 1;
+			} else {
+				options.set(name, true);
+			}
+			continue;
+		}
+		command.push(arg);
+	}
+	return { json, command, options };
+}
+
+function getStringOption(args: ParsedArgs, name: string): string | null {
+	const value: string | true | undefined = args.options.get(name);
+	return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+function getOptionalStringOption(args: ParsedArgs, name: string): string | undefined {
+	return getStringOption(args, name) ?? undefined;
+}
+
+function getRequiredStringOption(args: ParsedArgs, name: string): string {
+	const value: string | null = getStringOption(args, name);
+	if (value === null) {
+		throw new ManagerError({ code: "invalid_arguments", message: `Missing required option --${name}` });
+	}
+	return value;
+}
+
+function getNumberOption(args: ParsedArgs, name: string): number | null {
+	const value: string | null = getStringOption(args, name);
+	if (value === null) {
+		return null;
+	}
+	const parsed: number = Number.parseInt(value, 10);
+	if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+		throw new ManagerError({ code: "invalid_arguments", message: `Invalid --${name}: ${value}` });
+	}
+	return parsed;
+}
+
+function writeResult(result: ManagerResult, json: boolean): void {
+	if (json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+
+	if (result.ok) {
+		console.log(JSON.stringify(result, null, 2));
+	} else {
+		console.error(result.message);
+		if (result.details !== undefined) {
+			console.error(result.details);
+		}
+	}
+}
+
+function getHelpText(): string {
+	return [
+		"godot-daedalus-manager [--json] <command>",
+		"",
+		"Commands:",
+		"  status [--project <path>]",
+		"  doctor [--project <path>]",
+		"  backend install|update [--version <version>]",
+		"  backend start [--port <port>]",
+		"  backend stop",
+		"  backend health [--url <ws://...>]",
+		"  backend rollback",
+		"  frontend check [--project <path>]",
+		"  frontend download|stage [--version <version>]",
+		"  frontend apply --project <path>",
+		"  frontend rollback --project <path>"
+	].join("\n");
+}
+
+await main();

package/src/manager/frontend.ts

@@ -0,0 +1,233 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { copyFile, mkdir, readdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { FRONTEND_ADDON_DIR_NAME, FRONTEND_REPOSITORY, type FrontendManifest, type PendingFrontendUpdate } from "./types.js";
+import { ManagerError } from "./manager-error.js";
+import { assertInside, getManagerPaths, resolveProjectPluginDir, type ManagerPaths } from "./paths.js";
+import { readJsonFile, writeJsonFile } from "./json-file.js";
+import { runCommand } from "./process.js";
+
+export async function getInstalledFrontendVersion(projectPath: string | undefined): Promise<string | null> {
+	const pluginDir: string | null = resolveProjectPluginDir(projectPath);
+	if (pluginDir === null) {
+		return null;
+	}
+
+	const pluginCfgPath: string = join(pluginDir, "plugin.cfg");
+	const text: string = await readFile(pluginCfgPath, "utf8").catch((): string => "");
+	const match: RegExpMatchArray | null = text.match(/version="([^"]+)"/);
+	return match?.[1] ?? null;
+}
+
+export async function getLatestFrontendVersion(): Promise<string | null> {
+	const response: Response = await fetch(`https://api.github.com/repos/${FRONTEND_REPOSITORY}/releases/latest`, {
+		headers: { "User-Agent": "godot-daedalus-manager" }
+	});
+	if (!response.ok) {
+		return null;
+	}
+	const data = await response.json() as { tag_name?: unknown };
+	if (typeof data.tag_name !== "string") {
+		return null;
+	}
+	return data.tag_name.replace(/^v/, "");
+}
+
+export async function getPendingFrontendVersion(): Promise<string | null> {
+	const paths: ManagerPaths = getManagerPaths();
+	const pending: PendingFrontendUpdate | null = await readJsonFile<PendingFrontendUpdate>(paths.pendingFrontendUpdatePath);
+	return pending?.version ?? null;
+}
+
+export async function downloadAndStageFrontend(version: string): Promise<PendingFrontendUpdate> {
+	const manifest: FrontendManifest = await downloadFrontendManifest(version);
+	validateFrontendManifest(manifest);
+	const paths: ManagerPaths = getManagerPaths();
+	await mkdir(paths.frontendDownloadsDir, { recursive: true });
+	await mkdir(paths.frontendStagedDir, { recursive: true });
+	const zipPath: string = assertInside(paths.frontendDownloadsDir, join(paths.frontendDownloadsDir, manifest.assetName));
+	const stagedDir: string = assertInside(paths.frontendStagedDir, join(paths.frontendStagedDir, manifest.version));
+
+	await downloadFile(getReleaseAssetUrl(manifest.tag, manifest.assetName), zipPath);
+	const hash: string = await sha256File(zipPath);
+	if (hash.toLowerCase() !== manifest.sha256.toLowerCase()) {
+		throw new ManagerError({
+			code: "hash_mismatch",
+			message: "Downloaded frontend package hash does not match manifest.",
+			details: `Expected ${manifest.sha256}, got ${hash}`
+		});
+	}
+
+	await rm(stagedDir, { recursive: true, force: true });
+	await mkdir(stagedDir, { recursive: true });
+	await extractZip(zipPath, stagedDir);
+	const stagedPluginCfg: string = join(stagedDir, "addons", FRONTEND_ADDON_DIR_NAME, "plugin.cfg");
+	const stagedStats = await stat(stagedPluginCfg).catch((): null => null);
+	if (stagedStats === null || !stagedStats.isFile()) {
+		throw new ManagerError({
+			code: "manifest_invalid",
+			message: "Frontend package does not contain addons/godot_daedalus/plugin.cfg."
+		});
+	}
+
+	const pending: PendingFrontendUpdate = {
+		version: manifest.version,
+		sourceZipPath: zipPath,
+		stagedDir,
+		manifest,
+		createdAt: new Date().toISOString()
+	};
+	await writeJsonFile(paths.pendingFrontendUpdatePath, pending);
+	return pending;
+}
+
+export async function applyFrontendUpdate(projectPath: string | undefined): Promise<{ applied: boolean; version: string | null; backupDir?: string }> {
+	const pluginDir: string | null = resolveProjectPluginDir(projectPath);
+	if (pluginDir === null) {
+		throw new ManagerError({
+			code: "invalid_arguments",
+			message: "frontend apply requires --project <Godot project root>."
+		});
+	}
+
+	const paths: ManagerPaths = getManagerPaths();
+	const pending: PendingFrontendUpdate | null = await readJsonFile<PendingFrontendUpdate>(paths.pendingFrontendUpdatePath);
+	if (pending === null) {
+		return { applied: false, version: null };
+	}
+
+	const stagedPluginDir: string = join(pending.stagedDir, "addons", FRONTEND_ADDON_DIR_NAME);
+	const stagedStats = await stat(stagedPluginDir).catch((): null => null);
+	if (stagedStats === null || !stagedStats.isDirectory()) {
+		throw new ManagerError({
+			code: "frontend_update_missing",
+			message: "Pending frontend update staged directory is missing."
+		});
+	}
+
+	const backupDir: string = `${pluginDir}.backup-${Date.now()}`;
+	await rm(backupDir, { recursive: true, force: true });
+	await rename(pluginDir, backupDir).catch(async (): Promise<void> => {
+		await rm(backupDir, { recursive: true, force: true });
+	});
+	try {
+		await copyDirectory(stagedPluginDir, pluginDir);
+		await rm(paths.pendingFrontendUpdatePath, { force: true });
+		return { applied: true, version: pending.version, backupDir };
+	} catch (error: unknown) {
+		await rm(pluginDir, { recursive: true, force: true });
+		await rename(backupDir, pluginDir).catch((): void => undefined);
+		throw error;
+	}
+}
+
+export async function rollbackFrontend(projectPath: string | undefined): Promise<{ rolledBack: boolean }> {
+	const pluginDir: string | null = resolveProjectPluginDir(projectPath);
+	if (pluginDir === null) {
+		throw new ManagerError({ code: "invalid_arguments", message: "frontend rollback requires --project <Godot project root>." });
+	}
+	const parent: string = dirname(pluginDir);
+	const entries = await readdir(parent, { withFileTypes: true });
+	const backup = entries
+		.filter((entry) => entry.isDirectory() && entry.name.startsWith(`${FRONTEND_ADDON_DIR_NAME}.backup-`))
+		.map((entry) => entry.name)
+		.sort()
+		.reverse()[0];
+	if (backup === undefined) {
+		return { rolledBack: false };
+	}
+	await rm(pluginDir, { recursive: true, force: true });
+	await rename(join(parent, backup), pluginDir);
+	return { rolledBack: true };
+}
+
+export function validateFrontendManifest(manifest: FrontendManifest): void {
+	if (!manifest.version.match(/^\d+\.\d+\.\d+$/)) {
+		throw new ManagerError({ code: "manifest_invalid", message: "Frontend manifest version must be X.Y.Z." });
+	}
+	if (manifest.tag !== `v${manifest.version}`) {
+		throw new ManagerError({ code: "manifest_invalid", message: "Frontend manifest tag must match version." });
+	}
+	if (!manifest.assetName.endsWith(".zip")) {
+		throw new ManagerError({ code: "manifest_invalid", message: "Frontend manifest assetName must be a zip file." });
+	}
+	if (!manifest.sha256.match(/^[a-fA-F0-9]{64}$/)) {
+		throw new ManagerError({ code: "manifest_invalid", message: "Frontend manifest sha256 is invalid." });
+	}
+}
+
+async function downloadFrontendManifest(version: string): Promise<FrontendManifest> {
+	const tag: string = version.startsWith("v") ? version : `v${version}`;
+	const assetName: string = `godot-daedalus-plugin-${tag}.manifest.json`;
+	const response: Response = await fetch(getReleaseAssetUrl(tag, assetName), {
+		headers: { "User-Agent": "godot-daedalus-manager" }
+	});
+	if (!response.ok) {
+		throw new ManagerError({
+			code: "network_error",
+			message: `Could not download frontend manifest ${assetName}.`,
+			details: `${response.status} ${response.statusText}`
+		});
+	}
+	return await response.json() as FrontendManifest;
+}
+
+function getReleaseAssetUrl(tag: string, assetName: string): string {
+	return `https://github.com/${FRONTEND_REPOSITORY}/releases/download/${encodeURIComponent(tag)}/${encodeURIComponent(assetName)}`;
+}
+
+async function downloadFile(url: string, destination: string): Promise<void> {
+	const response: Response = await fetch(url, { headers: { "User-Agent": "godot-daedalus-manager" } });
+	if (!response.ok || response.body === null) {
+		throw new ManagerError({
+			code: "network_error",
+			message: `Could not download ${url}`,
+			details: `${response.status} ${response.statusText}`
+		});
+	}
+	await mkdir(dirname(destination), { recursive: true });
+	await pipeline(response.body, createWriteStream(destination));
+}
+
+async function sha256File(filePath: string): Promise<string> {
+	const hash = createHash("sha256");
+	hash.update(await readFile(filePath));
+	return hash.digest("hex");
+}
+
+async function extractZip(zipPath: string, destination: string): Promise<void> {
+	if (process.platform === "win32") {
+		const result = await runCommand("powershell.exe", [
+			"-NoProfile",
+			"-ExecutionPolicy",
+			"Bypass",
+			"-Command",
+			`Expand-Archive -LiteralPath '${zipPath.replaceAll("'", "''")}' -DestinationPath '${destination.replaceAll("'", "''")}' -Force`
+		], { timeoutMs: 60000 });
+		if (result.exitCode !== 0) {
+			throw new ManagerError({ code: "process_failed", message: "Failed to extract frontend zip.", details: result.stderr || result.stdout });
+		}
+		return;
+	}
+	const result = await runCommand("unzip", ["-q", zipPath, "-d", destination], { timeoutMs: 60000 });
+	if (result.exitCode !== 0) {
+		throw new ManagerError({ code: "process_failed", message: "Failed to extract frontend zip.", details: result.stderr || result.stdout });
+	}
+}
+
+async function copyDirectory(source: string, destination: string): Promise<void> {
+	await mkdir(destination, { recursive: true });
+	const entries = await readdir(source, { withFileTypes: true });
+	for (const entry of entries) {
+		const sourcePath: string = join(source, entry.name);
+		const destinationPath: string = join(destination, entry.name);
+		if (entry.isDirectory()) {
+			await copyDirectory(sourcePath, destinationPath);
+		} else if (entry.isFile()) {
+			await mkdir(dirname(destinationPath), { recursive: true });
+			await copyFile(sourcePath, destinationPath);
+		}
+	}
+}

package/src/manager/json-file.ts

@@ -0,0 +1,24 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export async function readJsonFile<T>(filePath: string): Promise<T | null> {
+	try {
+		return JSON.parse(await readFile(filePath, "utf8")) as T;
+	} catch (error: unknown) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+			return null;
+		}
+		throw error;
+	}
+}
+
+export async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
+	await mkdir(dirname(filePath), { recursive: true });
+	const tempPath: string = `${filePath}.${process.pid}.tmp`;
+	await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+	await rename(tempPath, filePath);
+}
+
+export async function removeIfExists(path: string): Promise<void> {
+	await rm(path, { recursive: true, force: true });
+}

package/src/manager/manager-error.ts

@@ -0,0 +1,46 @@
+import type { ManagerErrorCode, ManagerFailure } from "./types.js";
+
+export class ManagerError extends Error {
+	public readonly code: ManagerErrorCode;
+	public readonly details: string | undefined;
+	public readonly logPath: string | undefined;
+	public readonly suggestedAction: string | undefined;
+
+	public constructor(params: {
+		code: ManagerErrorCode;
+		message: string;
+		details?: string;
+		logPath?: string;
+		suggestedAction?: string;
+	}) {
+		super(params.message);
+		this.name = "ManagerError";
+		this.code = params.code;
+		this.details = params.details;
+		this.logPath = params.logPath;
+		this.suggestedAction = params.suggestedAction;
+	}
+
+	public toFailure(): ManagerFailure {
+		return {
+			ok: false,
+			code: this.code,
+			message: this.message,
+			...(this.details === undefined ? {} : { details: this.details }),
+			...(this.logPath === undefined ? {} : { logPath: this.logPath }),
+			...(this.suggestedAction === undefined ? {} : { suggestedAction: this.suggestedAction })
+		};
+	}
+}
+
+export function toManagerFailure(error: unknown): ManagerFailure {
+	if (error instanceof ManagerError) {
+		return error.toFailure();
+	}
+
+	return {
+		ok: false,
+		code: "unknown_error",
+		message: error instanceof Error ? error.message : String(error)
+	};
+}

package/src/manager/paths.ts

@@ -0,0 +1,69 @@
+import { join, resolve, sep } from "node:path";
+import { getAppDataDir } from "../app-paths.js";
+import { FRONTEND_ADDON_DIR_NAME } from "./types.js";
+import { ManagerError } from "./manager-error.js";
+
+export type ManagerPaths = {
+	appDir: string;
+	backendDir: string;
+	backendVersionsDir: string;
+	backendCurrentPath: string;
+	backendRuntimeDir: string;
+	backendPidPath: string;
+	logsDir: string;
+	frontendDir: string;
+	frontendDownloadsDir: string;
+	frontendStagedDir: string;
+	pendingFrontendUpdatePath: string;
+};
+
+export function getManagerAppDir(): string {
+	const override: string | undefined = process.env.GODOT_DAEDALUS_APP_DIR;
+	if (override !== undefined && override.trim() !== "") {
+		return resolve(override);
+	}
+
+	return getAppDataDir();
+}
+
+export function getManagerPaths(): ManagerPaths {
+	const appDir: string = getManagerAppDir();
+	const backendDir: string = join(appDir, "backend");
+	const frontendDir: string = join(appDir, "frontend");
+	return {
+		appDir,
+		backendDir,
+		backendVersionsDir: join(backendDir, "versions"),
+		backendCurrentPath: join(backendDir, "current.json"),
+		backendRuntimeDir: join(backendDir, "runtime"),
+		backendPidPath: join(backendDir, "runtime", "backend.pid.json"),
+		logsDir: join(appDir, "logs"),
+		frontendDir,
+		frontendDownloadsDir: join(frontendDir, "downloads"),
+		frontendStagedDir: join(frontendDir, "staged"),
+		pendingFrontendUpdatePath: join(frontendDir, "pending_frontend_update.json")
+	};
+}
+
+export function assertInside(parentDir: string, childPath: string): string {
+	const resolvedParent: string = resolve(parentDir);
+	const resolvedChild: string = resolve(childPath);
+	if (resolvedChild !== resolvedParent && !resolvedChild.startsWith(`${resolvedParent}${sep}`)) {
+		throw new ManagerError({
+			code: "invalid_path",
+			message: `Refusing to operate outside managed directory: ${resolvedChild}`,
+			details: `Allowed root: ${resolvedParent}`
+		});
+	}
+
+	return resolvedChild;
+}
+
+export function resolveProjectPluginDir(projectPath: string | undefined): string | null {
+	if (projectPath === undefined || projectPath.trim() === "") {
+		return null;
+	}
+
+	const projectRoot: string = resolve(projectPath);
+	return assertInside(projectRoot, join(projectRoot, "addons", FRONTEND_ADDON_DIR_NAME));
+}

package/src/manager/process.ts

@@ -0,0 +1,98 @@
+import { spawn } from "node:child_process";
+
+export type CommandResult = {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+};
+
+export function runCommand(command: string, args: readonly string[], options: {
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	timeoutMs?: number;
+} = {}): Promise<CommandResult> {
+	return new Promise<CommandResult>((resolve): void => {
+		const invocation = buildInvocation(command, args);
+		const child = spawn(invocation.command, invocation.args, {
+			cwd: options.cwd,
+			env: options.env ?? process.env,
+			windowsHide: true,
+			stdio: ["ignore", "pipe", "pipe"]
+		});
+		let stdout: string = "";
+		let stderr: string = "";
+		let settled: boolean = false;
+		const timeout = options.timeoutMs === undefined
+			? null
+			: setTimeout((): void => {
+				if (settled) {
+					return;
+				}
+				child.kill("SIGTERM");
+			}, options.timeoutMs);
+
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (chunk: string): void => {
+			stdout += chunk;
+		});
+		child.stderr.on("data", (chunk: string): void => {
+			stderr += chunk;
+		});
+		child.on("error", (error: Error): void => {
+			if (settled) {
+				return;
+			}
+			settled = true;
+			if (timeout !== null) {
+				clearTimeout(timeout);
+			}
+			resolve({ exitCode: 1, stdout, stderr: stderr + error.message });
+		});
+		child.on("exit", (code: number | null): void => {
+			if (settled) {
+				return;
+			}
+			settled = true;
+			if (timeout !== null) {
+				clearTimeout(timeout);
+			}
+			resolve({ exitCode: code ?? 1, stdout, stderr });
+		});
+	});
+}
+
+function buildInvocation(command: string, args: readonly string[]): { command: string; args: string[] } {
+	if (process.platform !== "win32" || (!command.endsWith(".cmd") && !command.endsWith(".bat"))) {
+		return { command, args: [...args] };
+	}
+
+	const comspec: string = process.env.COMSPEC ?? "cmd.exe";
+	const commandLine: string = [command, ...args].map(quoteWindowsCommandPart).join(" ");
+	return { command: comspec, args: ["/d", "/s", "/c", commandLine] };
+}
+
+function quoteWindowsCommandPart(value: string): string {
+	if (!/[ \t&()^"]/u.test(value)) {
+		return value;
+	}
+
+	return `"${value.replaceAll("\"", "\\\"")}"`;
+}
+
+export function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function stopProcess(pid: number): Promise<CommandResult> {
+	if (process.platform === "win32") {
+		return runCommand("taskkill", ["/PID", String(pid), "/T", "/F"], { timeoutMs: 10000 });
+	}
+
+	return runCommand("kill", ["-TERM", String(pid)], { timeoutMs: 10000 });
+}

package/src/manager/semver.ts

@@ -0,0 +1,29 @@
+export function parseSemver(value: string): [number, number, number] | null {
+	const match: RegExpMatchArray | null = value.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+	if (match === null) {
+		return null;
+	}
+
+	return [Number.parseInt(match[1]!, 10), Number.parseInt(match[2]!, 10), Number.parseInt(match[3]!, 10)];
+}
+
+export function isVersionNewer(candidate: string, current: string): boolean {
+	const left: [number, number, number] | null = parseSemver(candidate);
+	const right: [number, number, number] | null = parseSemver(current);
+	if (left === null || right === null) {
+		return false;
+	}
+
+	for (let index: number = 0; index < 3; index += 1) {
+		const leftValue: number = left[index]!;
+		const rightValue: number = right[index]!;
+		if (leftValue > rightValue) {
+			return true;
+		}
+		if (leftValue < rightValue) {
+			return false;
+		}
+	}
+
+	return false;
+}

package/src/manager/status.ts

@@ -0,0 +1,27 @@
+import { DEFAULT_BACKEND_PORT, type BackendPidFile, type ManagerStatus } from "./types.js";
+import { getInstalledBackendVersion, getLatestBackendVersion, getRunningBackend, healthBackend } from "./backend.js";
+import { getInstalledFrontendVersion, getLatestFrontendVersion, getPendingFrontendVersion } from "./frontend.js";
+
+export async function readStatus(projectPath: string | undefined): Promise<ManagerStatus> {
+	const running: BackendPidFile | null = await getRunningBackend();
+	const url: string = running?.url ?? `ws://localhost:${DEFAULT_BACKEND_PORT}`;
+	const health = await healthBackend(url);
+	return {
+		frontend: {
+			installedVersion: await getInstalledFrontendVersion(projectPath),
+			latestVersion: await getLatestFrontendVersion(),
+			pendingVersion: await getPendingFrontendVersion()
+		},
+		backend: {
+			installedVersion: await getInstalledBackendVersion(),
+			latestVersion: await getLatestBackendVersion(),
+			runningVersion: running?.version ?? null,
+			pid: running?.pid ?? null
+		},
+		health: {
+			ok: health.ok,
+			url,
+			error: health.error
+		}
+	};
+}

package/src/manager/types.ts

@@ -0,0 +1,86 @@
+export const DEFAULT_BACKEND_PORT: number = 38180;
+export const BACKEND_PACKAGE_NAME: string = "godot-daedalus_backend";
+export const BACKEND_BIN_NAME: string = "godot-daedalus-backend";
+export const FRONTEND_REPOSITORY: string = "LuYingYiLong/godot-daedalus";
+export const FRONTEND_ADDON_DIR_NAME: string = "godot_daedalus";
+
+export type JsonObject = Record<string, unknown>;
+
+export type ManagerErrorCode =
+	| "invalid_arguments"
+	| "invalid_path"
+	| "not_installed"
+	| "network_error"
+	| "install_failed"
+	| "health_failed"
+	| "process_failed"
+	| "manifest_invalid"
+	| "hash_mismatch"
+	| "frontend_update_missing"
+	| "unknown_error";
+
+export type ManagerFailure = {
+	ok: false;
+	code: ManagerErrorCode;
+	message: string;
+	details?: string;
+	logPath?: string;
+	suggestedAction?: string;
+};
+
+export type ManagerSuccess<T extends JsonObject = JsonObject> = {
+	ok: true;
+} & T;
+
+export type ManagerResult<T extends JsonObject = JsonObject> = ManagerSuccess<T> | ManagerFailure;
+
+export type BackendCurrentFile = {
+	version: string;
+	path: string;
+	previousVersion?: string;
+	updatedAt: string;
+};
+
+export type BackendPidFile = {
+	pid: number;
+	version: string;
+	port: number;
+	url: string;
+	logPath: string;
+	startedAt: string;
+};
+
+export type FrontendManifest = {
+	version: string;
+	tag: string;
+	sha256: string;
+	assetName: string;
+	minGodotVersion?: string;
+};
+
+export type PendingFrontendUpdate = {
+	version: string;
+	sourceZipPath: string;
+	stagedDir: string;
+	manifest: FrontendManifest;
+	createdAt: string;
+};
+
+export type ManagerStatus = {
+	frontend: {
+		installedVersion: string | null;
+		latestVersion: string | null;
+		pendingVersion: string | null;
+	};
+	backend: {
+		installedVersion: string | null;
+		latestVersion: string | null;
+		runningVersion: string | null;
+		pid: number | null;
+	};
+	health: {
+		ok: boolean;
+		url: string;
+		error: string | null;
+	};
+};

package/src/ping-client.ts

@@ -1,6 +1,6 @@
 import WebSocket from "ws";
 
-const url: string = process.env.WS_URL ?? "ws://localhost:8080";
+const url: string = process.env.WS_URL ?? "ws://localhost:38180";
 const socket: WebSocket = new WebSocket(url);
 
 socket.on("open", (): void => {

package/src/server/backend-health.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BACKEND_HEALTH_NAME: string = "godot-daedalus-backend";
+const PACKAGE_ROOT: string = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const PACKAGE_JSON_PATH: string = resolve(PACKAGE_ROOT, "package.json");
+
+type PackageManifest = {
+	name?: unknown;
+	version?: unknown;
+};
+
+export type BackendHealthResult = {
+	name: string;
+	version: string;
+	pid: number;
+	mode: "development" | "runtime";
+};
+
+let cachedPackageVersion: string | null = null;
+
+export function getBackendPackageVersion(): string {
+	if (cachedPackageVersion !== null) {
+		return cachedPackageVersion;
+	}
+
+	const envVersion: string | undefined = process.env.npm_package_version;
+	if (envVersion !== undefined && envVersion.trim() !== "") {
+		cachedPackageVersion = envVersion.trim();
+		return cachedPackageVersion;
+	}
+
+	try {
+		const manifestText: string = readFileSync(PACKAGE_JSON_PATH, "utf8");
+		const manifest: PackageManifest = JSON.parse(manifestText) as PackageManifest;
+		if (typeof manifest.version === "string" && manifest.version.trim() !== "") {
+			cachedPackageVersion = manifest.version.trim();
+			return cachedPackageVersion;
+		}
+	} catch {
+		// health 不能因为版本元数据不可读而阻断 WebSocket 启动。
+	}
+
+	cachedPackageVersion = "0.0.0";
+	return cachedPackageVersion;
+}
+
+export function getBackendRuntimeMode(): "development" | "runtime" {
+	if (process.env.NODE_ENV === "development" || process.env.npm_lifecycle_event === "dev") {
+		return "development";
+	}
+
+	return "runtime";
+}
+
+export function createBackendHealthResult(): BackendHealthResult {
+	return {
+		name: BACKEND_HEALTH_NAME,
+		version: getBackendPackageVersion(),
+		pid: process.pid,
+		mode: getBackendRuntimeMode()
+	};
+}

package/src/server/websocket-server.ts

@@ -91,6 +91,7 @@ import {
 	serializePendingApprovalState,
 	type PendingApprovalState
 } from "../session/approval-persistence.js";
+import { createBackendHealthResult } from "./backend-health.js";
 
 const tokenCounterPromise: Promise<TokenCounter> = createTokenCounter();
 let sessionCompressorPromptCache: string | undefined;
@@ -2292,12 +2293,7 @@ async function handleRequest(socket: WebSocket, request: ClientRequest, session:
 				type: "response",
 				id: request.id,
 				ok: true,
-				result: {
-					name: "godot-daedalus-backend",
-					version: "1.0.1",
-					pid: process.pid,
-					mode: process.env.NODE_ENV === "development" || process.env.npm_lifecycle_event === "dev" ? "development" : "runtime"
-				}
+				result: createBackendHealthResult()
 			});
 			break;