@writepanda/mcp 1.180.0 → 1.191.0

package/bin/appConnection.mjs

@@ -0,0 +1,201 @@
+// How the MCP server finds and reaches the running PandaStudio app.
+//
+// Two kinds of caller spawn this server:
+//
+//   • External agents (Claude Desktop, Claude Code, Codex, Cursor…). The app
+//     may not be running, so a call reads the token/port files the app writes
+//     and, when nothing answers, launches the app and waits for it.
+//
+//   • The app's own chat panel (PANDASTUDIO_CALLER=in-app). The app is running
+//     by definition: it spawned us, and it hands us its live port and token in
+//     the environment. Launching "the app" from here is always wrong, and
+//     waiting 60-90 s for it hid every real failure behind the client's
+//     generic "Request timed out". So in-app calls never launch anything and
+//     fail within seconds with the actual reason, prefixed with
+//     IN_APP_UNAVAILABLE so the app can show it (and a Retry) in the chat.
+//
+// Kept free of MCP-sdk imports so the pure parts are unit-testable.
+
+import { readFile } from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+
+/** Prefix of every in-app "can't reach PandaStudio" tool error. The app's
+ *  agent runner matches it (electron/agent/toolsUnavailable.ts). */
+export const IN_APP_UNAVAILABLE = "PANDASTUDIO_TOOLS_UNAVAILABLE";
+
+export function isInAppCaller(env = process.env) {
+	return env.PANDASTUDIO_CALLER === "in-app";
+}
+
+export function configDir(env = process.env, platform = process.platform) {
+	if (env.PANDASTUDIO_CONFIG_DIR) return env.PANDASTUDIO_CONFIG_DIR;
+	if (platform === "win32") {
+		const appData = env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+		return path.join(appData, "pandastudio");
+	}
+	return path.join(os.homedir(), ".config", "pandastudio");
+}
+
+/** A text file's value without whitespace or a UTF-8 byte-order mark (an
+ *  editor or a sync tool on Windows can add one, and Number() of
+ *  "<BOM>7878" is NaN). */
+export function cleanFileValue(raw) {
+	const s = String(raw);
+	return (s.charCodeAt(0) === 0xfeff ? s.slice(1) : s).trim();
+}
+
+/** Credentials the app passed in the environment (in-app spawns only). */
+export function envCredentials(env = process.env) {
+	const port = Number(env.PANDASTUDIO_AUTOMATION_PORT);
+	const token = env.PANDASTUDIO_AUTOMATION_TOKEN;
+	if (!Number.isInteger(port) || port <= 0 || typeof token !== "string" || !token) return null;
+	return { port, token, source: "env" };
+}
+
+/** Credentials from the token/port files. Errors name the file and the cause. */
+export async function fileCredentials(dir = configDir()) {
+	const portFile = path.join(dir, "port");
+	const tokenFile = path.join(dir, "token");
+	let portRaw;
+	let tokenRaw;
+	try {
+		portRaw = await readFile(portFile, "utf-8");
+		tokenRaw = await readFile(tokenFile, "utf-8");
+	} catch (err) {
+		const file = portRaw === undefined ? portFile : tokenFile;
+		throw new Error(`can't read ${file} (${err?.code ?? err?.message ?? err})`);
+	}
+	const port = Number(cleanFileValue(portRaw));
+	const token = cleanFileValue(tokenRaw);
+	if (!Number.isInteger(port) || port <= 0) {
+		throw new Error(`invalid port in ${portFile}: ${JSON.stringify(portRaw.slice(0, 20))}`);
+	}
+	if (!token) throw new Error(`empty token in ${tokenFile}`);
+	return { port, token, source: "files" };
+}
+
+/**
+ * One health probe of the automation server:
+ *   up   — it answered 200
+ *   busy — connected (or still connecting) but no answer within `timeoutMs`:
+ *          the app's main process is stalled
+ *   down — refused / reset / any other socket error: nothing is listening
+ * `detail` says what happened, for error messages.
+ */
+export function probeHealth(port, timeoutMs = 1500) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const done = (state, detail) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			req.destroy();
+			resolve({ state, detail });
+		};
+		const req = http.get({ host: "127.0.0.1", port, path: "/v1/health", agent: false }, (res) => {
+			res.resume();
+			if (res.statusCode === 200) done("up", "HTTP 200");
+			else done("down", `HTTP ${res.statusCode} from /v1/health`);
+		});
+		req.on("error", (err) => done("down", err?.code ?? err?.message ?? String(err)));
+		const timer = setTimeout(() => done("busy", `no answer within ${timeoutMs} ms`), timeoutMs);
+	});
+}
+
+/**
+ * Wait for the automation server, tolerating a stalled main process for up to
+ * `busyWaitMs`. Returns the last probe ({state:"up"} on success).
+ */
+export async function waitForHealth(
+	port,
+	{ probeMs = 1500, busyWaitMs = 30_000, onBusy, probe = probeHealth } = {},
+) {
+	const deadline = Date.now() + busyWaitMs;
+	let warned = false;
+	for (;;) {
+		const r = await probe(port, probeMs);
+		if (r.state === "up" || r.state === "down" || Date.now() >= deadline) return r;
+		if (!warned && onBusy) onBusy();
+		warned = true;
+		probeMs = Math.min(probeMs * 2, 5000);
+	}
+}
+
+function unavailable(reason) {
+	const err = new Error(`${IN_APP_UNAVAILABLE}: ${reason}`);
+	err.inAppUnavailable = true;
+	return err;
+}
+
+/**
+ * Resolve working credentials for an in-app call, or throw an
+ * IN_APP_UNAVAILABLE error with the reason. Never launches anything.
+ *
+ * Order: the credentials the app handed us (env), then the files (the app
+ * restarted its automation server on another port since it spawned us). The
+ * whole thing stays well inside the MCP client's 60 s request timeout.
+ */
+export async function connectInApp({
+	env = process.env,
+	dir = configDir(env),
+	probeMs = 1500,
+	busyWaitMs = 20_000,
+	probe = probeHealth,
+	readFiles = fileCredentials,
+} = {}) {
+	const attempts = [];
+	const candidates = [];
+	const fromEnv = envCredentials(env);
+	if (fromEnv) candidates.push(fromEnv);
+	let fileError = null;
+	try {
+		const fromFiles = await readFiles(dir);
+		if (!fromEnv || fromFiles.port !== fromEnv.port || fromFiles.token !== fromEnv.token) {
+			candidates.push(fromFiles);
+		}
+	} catch (err) {
+		fileError = err?.message ?? String(err);
+	}
+	if (candidates.length === 0) {
+		throw unavailable(
+			`PandaStudio didn't pass its automation address to the tools and ${fileError ?? "the token/port files are missing"}.`,
+		);
+	}
+	for (const c of candidates) {
+		const r = await waitForHealth(c.port, { probeMs, busyWaitMs, probe });
+		if (r.state === "up") return c;
+		attempts.push(
+			r.state === "busy"
+				? `127.0.0.1:${c.port} accepted the connection but didn't answer for ${Math.round(busyWaitMs / 1000)} s (the app is busy or stuck)`
+				: `127.0.0.1:${c.port} (from ${c.source === "env" ? "the app" : dir}) is unreachable: ${r.detail}`,
+		);
+	}
+	throw unavailable(`PandaStudio's automation server didn't answer. ${attempts.join("; ")}.`);
+}
+
+/**
+ * Environment for LAUNCHING the desktop app. This server runs as Electron in
+ * node mode (ELECTRON_RUN_AS_NODE=1), and a child inherits that: spawning
+ * PandaStudio.exe / PandaStudio.app with it set starts a bare Node REPL that
+ * exits at once instead of the app, so an agent's "launch it and wait" always
+ * timed out. Drop it, and everything that only means something to this process.
+ */
+export function appLaunchEnv(env = process.env) {
+	const out = {};
+	for (const [k, v] of Object.entries(env)) {
+		const upper = k.toUpperCase();
+		if (
+			upper === "ELECTRON_RUN_AS_NODE" ||
+			upper === "ELECTRON_NO_ATTACH_CONSOLE" ||
+			upper === "PANDASTUDIO_CALLER" ||
+			upper === "PANDASTUDIO_AUTOMATION_PORT" ||
+			upper === "PANDASTUDIO_AUTOMATION_TOKEN"
+		) {
+			continue;
+		}
+		out[k] = v;
+	}
+	return out;
+}