@clinebot/core 0.0.35 → 0.0.37

package/src/hub/connect.ts

@@ -0,0 +1,156 @@
+import type {
+	HubCommandEnvelope,
+	HubReplyEnvelope,
+	HubTransportFrame,
+} from "@clinebot/shared";
+import {
+	type HubEndpointOverrides,
+	resolveHubEndpointOptions,
+} from "./defaults";
+import {
+	createHubServerUrl,
+	readHubDiscovery,
+	resolveHubOwnerContext,
+} from "./discovery";
+
+export interface HubConnection {
+	send(envelope: HubCommandEnvelope): Promise<HubReplyEnvelope>;
+	close(): void;
+}
+
+export interface HubCommandRequest
+	extends Omit<HubCommandEnvelope, "version" | "clientId"> {
+	version?: HubCommandEnvelope["version"];
+	clientId?: string;
+}
+
+function normalizeHubConnectionError(error: unknown, url: string): Error {
+	if (error instanceof Error) {
+		return error;
+	}
+	if (
+		error &&
+		typeof error === "object" &&
+		"message" in error &&
+		typeof (error as { message?: unknown }).message === "string" &&
+		(error as { message: string }).message.trim()
+	) {
+		return new Error((error as { message: string }).message.trim());
+	}
+	const eventType =
+		error &&
+		typeof error === "object" &&
+		"type" in error &&
+		typeof (error as { type?: unknown }).type === "string"
+			? (error as { type: string }).type.trim()
+			: "";
+	return new Error(
+		eventType
+			? `Failed to connect to hub at ${url} (${eventType} event before socket open).`
+			: `Failed to connect to hub at ${url}.`,
+	);
+}
+
+function hasExplicitEndpoint(overrides: HubEndpointOverrides): boolean {
+	return (
+		overrides.host !== undefined ||
+		overrides.port !== undefined ||
+		overrides.pathname !== undefined
+	);
+}
+
+export async function resolveHubUrl(
+	overrides: HubEndpointOverrides = {},
+): Promise<string> {
+	const endpoint = resolveHubEndpointOptions(overrides);
+	if (!hasExplicitEndpoint(overrides)) {
+		const owner = resolveHubOwnerContext();
+		const discovery = await readHubDiscovery(owner.discoveryPath);
+		if (discovery?.url) {
+			return discovery.url;
+		}
+	}
+	return createHubServerUrl(endpoint.host, endpoint.port, endpoint.pathname);
+}
+
+export async function connectToHub(url: string): Promise<HubConnection> {
+	return await new Promise((resolve, reject) => {
+		const ws = new WebSocket(url);
+		const pending = new Map<
+			string,
+			{
+				resolve: (reply: HubReplyEnvelope) => void;
+				reject: (error: unknown) => void;
+			}
+		>();
+		let counter = 0;
+
+		ws.addEventListener("open", () => {
+			resolve({
+				send(envelope) {
+					const requestId = envelope.requestId ?? `hub-client-${++counter}`;
+					return new Promise<HubReplyEnvelope>((res, rej) => {
+						pending.set(requestId, { resolve: res, reject: rej });
+						const frame: HubTransportFrame = {
+							kind: "command",
+							envelope: { ...envelope, requestId },
+						};
+						ws.send(JSON.stringify(frame));
+					});
+				},
+				close() {
+					ws.close();
+				},
+			});
+		});
+
+		ws.addEventListener("message", (event) => {
+			const frame = JSON.parse(String(event.data)) as HubTransportFrame;
+			if (frame.kind === "reply" && frame.envelope.requestId) {
+				const entry = pending.get(frame.envelope.requestId);
+				if (entry) {
+					pending.delete(frame.envelope.requestId);
+					entry.resolve(frame.envelope);
+				}
+			}
+		});
+
+		ws.addEventListener("close", () => {
+			for (const entry of pending.values()) {
+				entry.reject(new Error("Hub connection closed"));
+			}
+			pending.clear();
+		});
+
+		ws.addEventListener("error", (error) => {
+			reject(normalizeHubConnectionError(error, url));
+		});
+	});
+}
+
+export async function probeHubConnection(url: string): Promise<boolean> {
+	try {
+		const connection = await connectToHub(url);
+		connection.close();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function sendHubCommand(
+	overrides: HubEndpointOverrides,
+	envelope: HubCommandRequest,
+): Promise<HubReplyEnvelope> {
+	const url = await resolveHubUrl(overrides);
+	const connection = await connectToHub(url);
+	try {
+		return await connection.send({
+			version: envelope.version ?? "v1",
+			clientId: envelope.clientId ?? "hub-client",
+			...envelope,
+		});
+	} finally {
+		connection.close();
+	}
+}

package/src/hub/daemon-entry.ts

@@ -0,0 +1,122 @@
+import { initVcr } from "@clinebot/shared";
+import { resolveHubEndpointOptions } from "./defaults";
+import { createLocalHubScheduleRuntimeHandlers } from "./runtime-handlers";
+import { startHubWebSocketServer } from "./server";
+import { resolveSharedHubOwnerContext } from "./workspace";
+
+initVcr(process.env.CLINE_VCR);
+
+function parseArgs(argv: string[]): {
+	cwd: string;
+	host?: string;
+	port?: number;
+	pathname?: string;
+} {
+	let cwd = process.cwd();
+	let host: string | undefined;
+	let port: number | undefined;
+	let pathname: string | undefined;
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		const value = argv[index + 1];
+		if (arg === "--cwd" && value) {
+			cwd = value;
+			index += 1;
+			continue;
+		}
+		if (arg === "--host" && value) {
+			host = value;
+			index += 1;
+			continue;
+		}
+		if (arg === "--port" && value) {
+			const parsed = Number(value);
+			if (Number.isFinite(parsed)) {
+				port = parsed;
+			}
+			index += 1;
+			continue;
+		}
+		if (arg === "--pathname" && value) {
+			pathname = value;
+			index += 1;
+		}
+	}
+
+	return { cwd, host, port, pathname };
+}
+
+async function main(): Promise<void> {
+	const options = parseArgs(process.argv.slice(2));
+	process.chdir(options.cwd);
+
+	const endpoint = resolveHubEndpointOptions({
+		host: options.host,
+		port: options.port,
+		pathname: options.pathname,
+	});
+
+	const server = await startHubWebSocketServer({
+		host: endpoint.host,
+		port: endpoint.port,
+		pathname: endpoint.pathname,
+		owner: resolveSharedHubOwnerContext(),
+		runtimeHandlers: createLocalHubScheduleRuntimeHandlers(),
+		cronOptions: { workspaceRoot: options.cwd },
+	});
+
+	const shutdown = async (): Promise<void> => {
+		await server.close();
+		process.exit(0);
+	};
+
+	let fatalShutdownStarted = false;
+	const shutdownFatal = (label: string, error: unknown): void => {
+		if (fatalShutdownStarted) {
+			return;
+		}
+		fatalShutdownStarted = true;
+		const message =
+			error instanceof Error ? error.stack || error.message : String(error);
+		process.stderr.write(`[hub-daemon] ${label}: ${message}\n`);
+		void server
+			.close()
+			.catch((closeError) => {
+				const closeMessage =
+					closeError instanceof Error
+						? closeError.stack || closeError.message
+						: String(closeError);
+				process.stderr.write(
+					`[hub-daemon] shutdown after ${label} failed: ${closeMessage}\n`,
+				);
+			})
+			.finally(() => {
+				process.exit(1);
+			});
+	};
+
+	process.on("SIGINT", () => {
+		void shutdown();
+	});
+	process.on("SIGTERM", () => {
+		void shutdown();
+	});
+	process.on("uncaughtException", (error) => {
+		shutdownFatal("uncaughtException", error);
+	});
+	process.on("unhandledRejection", (reason) => {
+		shutdownFatal("unhandledRejection", reason);
+	});
+
+	await new Promise<void>(() => {
+		// keep daemon process alive
+	});
+}
+
+void main().catch((error) => {
+	const message =
+		error instanceof Error ? error.stack || error.message : String(error);
+	process.stderr.write(`[hub-daemon] fatal: ${message}\n`);
+	process.exit(1);
+});

package/src/hub/daemon.ts

@@ -0,0 +1,284 @@
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	CLINE_RUN_AS_HUB_DAEMON_ENV,
+	isHubDaemonProcess,
+	withResolvedClineBuildEnv,
+} from "@clinebot/shared";
+import { requestHubShutdown, verifyHubConnection } from "./client";
+import {
+	type HubEndpointOverrides,
+	resolveHubEndpointOptions,
+} from "./defaults";
+import {
+	clearHubDiscovery,
+	createHubServerUrl,
+	type HubServerDiscoveryRecord,
+	probeHubServer,
+	readHubDiscovery,
+	resolveClineDataDir,
+	resolveHubBuildId,
+	writeHubDiscovery,
+} from "./discovery";
+import { resolveSharedHubOwnerContext } from "./workspace";
+
+const HUB_STARTUP_TIMEOUT_MS = 8_000;
+const HUB_STARTUP_POLL_MS = 200;
+const HUB_RETIRE_TIMEOUT_MS = 3_000;
+const HUB_RETIRE_POLL_MS = 100;
+
+function endpointArgs(endpoint: HubEndpointOverrides): string[] {
+	return [
+		...(endpoint.host ? ["--host", endpoint.host] : []),
+		...(typeof endpoint.port === "number"
+			? ["--port", String(endpoint.port)]
+			: []),
+		...(endpoint.pathname ? ["--pathname", endpoint.pathname] : []),
+	];
+}
+
+function openDetachedHubLogFile(): { fd: number; logPath: string } | undefined {
+	try {
+		const logPath = join(resolveClineDataDir(), "logs", "hub-daemon.log");
+		mkdirSync(dirname(logPath), { recursive: true });
+		return { fd: openSync(logPath, "a"), logPath };
+	} catch {
+		return undefined;
+	}
+}
+
+function isCompatibleHubRecord(record: HubServerDiscoveryRecord): boolean {
+	const recordBuildId = record.buildId?.trim();
+	return !!recordBuildId && recordBuildId === resolveHubBuildId();
+}
+
+async function waitForHubToRetire(
+	url: string,
+	timeoutMs: number,
+): Promise<boolean> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const healthy = await probeHubServer(url).catch(() => undefined);
+		if (!healthy?.url) {
+			return true;
+		}
+		await new Promise((resolve) => setTimeout(resolve, HUB_RETIRE_POLL_MS));
+	}
+	return false;
+}
+
+async function retireIncompatibleHub(
+	record: HubServerDiscoveryRecord,
+	discoveryPath: string,
+): Promise<void> {
+	if (isCompatibleHubRecord(record)) {
+		return;
+	}
+	await requestHubShutdown(record.url).catch(() => false);
+	if (record.pid) {
+		try {
+			process.kill(record.pid, "SIGTERM");
+		} catch {
+			// Best-effort cleanup only. A compatible hub may still start on a fallback port.
+		}
+	}
+	await waitForHubToRetire(record.url, HUB_RETIRE_TIMEOUT_MS);
+	await clearHubDiscovery(discoveryPath).catch(() => undefined);
+}
+
+function resolveDaemonEntryPath(): string {
+	const extension = import.meta.url.endsWith(".ts") ? "ts" : "js";
+	return fileURLToPath(new URL(`./daemon-entry.${extension}`, import.meta.url));
+}
+
+function resolveLaunchCommand(
+	workspaceRoot: string,
+	endpoint: HubEndpointOverrides,
+): {
+	launcher: string;
+	args: string[];
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+} {
+	const daemonEntryPath = resolveDaemonEntryPath();
+	const execPath = process.execPath?.trim();
+	if (!execPath) {
+		throw new Error("unable to resolve runtime executable for hub daemon");
+	}
+	const isBunRuntime = basename(execPath).toLowerCase().includes("bun");
+	const useDevelopmentConditions =
+		isBunRuntime && daemonEntryPath.toLowerCase().endsWith(".ts");
+	return {
+		launcher: execPath,
+		args: [
+			...(useDevelopmentConditions ? ["--conditions=development"] : []),
+			daemonEntryPath,
+			"--cwd",
+			workspaceRoot,
+			...endpointArgs(endpoint),
+		],
+		cwd: workspaceRoot,
+		env: {
+			...withResolvedClineBuildEnv(process.env),
+			CLINE_NO_INTERACTIVE: "1",
+			[CLINE_RUN_AS_HUB_DAEMON_ENV]: "1",
+		},
+	};
+}
+
+export function spawnDetachedHubServer(
+	workspaceRoot: string,
+	endpoint: HubEndpointOverrides = {},
+): void {
+	if (isHubDaemonProcess()) {
+		return;
+	}
+	const command = resolveLaunchCommand(workspaceRoot, endpoint);
+	const logFile = openDetachedHubLogFile();
+	try {
+		const child = spawn(command.launcher, command.args, {
+			detached: true,
+			stdio: logFile ? ["ignore", logFile.fd, logFile.fd] : "ignore",
+			env: command.env,
+			cwd: command.cwd,
+		});
+		child.unref();
+	} finally {
+		if (logFile) {
+			closeSync(logFile.fd);
+		}
+	}
+}
+
+export function prewarmDetachedHubServer(
+	workspaceRoot: string,
+	endpoint: HubEndpointOverrides = {},
+): void {
+	if (isHubDaemonProcess()) {
+		return;
+	}
+	const owner = resolveSharedHubOwnerContext();
+	const hasExplicitPort =
+		endpoint.port !== undefined || !!process.env.CLINE_HUB_PORT?.trim();
+	const resolvedEndpoint = resolveHubEndpointOptions(endpoint);
+	const expectedUrl = createHubServerUrl(
+		resolvedEndpoint.host,
+		resolvedEndpoint.port,
+		resolvedEndpoint.pathname,
+	);
+	void readHubDiscovery(owner.discoveryPath)
+		.then(async (discovered) => {
+			if (discovered?.url) {
+				const healthy = await probeHubServer(discovered.url);
+				if (
+					healthy?.url &&
+					isCompatibleHubRecord(healthy) &&
+					(await verifyHubConnection(healthy.url))
+				) {
+					return;
+				}
+				if (healthy?.url) {
+					await retireIncompatibleHub(healthy, owner.discoveryPath);
+				} else {
+					await clearHubDiscovery(owner.discoveryPath).catch(() => undefined);
+				}
+			}
+			const expected = await probeHubServer(expectedUrl);
+			if (
+				expected?.url &&
+				isCompatibleHubRecord(expected) &&
+				(await verifyHubConnection(expected.url))
+			) {
+				await writeHubDiscovery(owner.discoveryPath, expected);
+				return;
+			}
+			if (expected?.url) {
+				await retireIncompatibleHub(expected, owner.discoveryPath);
+			}
+			const shouldUseFallbackPort =
+				!hasExplicitPort && resolvedEndpoint.port !== 0;
+			const spawnEndpoint = shouldUseFallbackPort
+				? { ...resolvedEndpoint, port: 0 }
+				: resolvedEndpoint;
+			spawnDetachedHubServer(workspaceRoot, spawnEndpoint);
+		})
+		.catch(() => {
+			// best-effort prewarm only
+		});
+}
+
+export async function ensureDetachedHubServer(
+	workspaceRoot: string,
+	endpointOverrides: HubEndpointOverrides = {},
+): Promise<string> {
+	const owner = resolveSharedHubOwnerContext();
+	const hasExplicitPort =
+		endpointOverrides.port !== undefined ||
+		!!process.env.CLINE_HUB_PORT?.trim();
+	const endpoint = resolveHubEndpointOptions(endpointOverrides);
+	const expectedUrl = createHubServerUrl(
+		endpoint.host,
+		endpoint.port,
+		endpoint.pathname,
+	);
+	const discovered = await readHubDiscovery(owner.discoveryPath);
+	if (discovered?.url) {
+		const healthy = await probeHubServer(discovered.url);
+		if (
+			healthy?.url &&
+			isCompatibleHubRecord(healthy) &&
+			(await verifyHubConnection(healthy.url))
+		) {
+			return healthy.url;
+		}
+		if (healthy?.url) {
+			await retireIncompatibleHub(healthy, owner.discoveryPath);
+		} else {
+			await clearHubDiscovery(owner.discoveryPath).catch(() => undefined);
+		}
+	}
+	const expected = await probeHubServer(expectedUrl);
+	if (
+		expected?.url &&
+		isCompatibleHubRecord(expected) &&
+		(await verifyHubConnection(expected.url))
+	) {
+		await writeHubDiscovery(owner.discoveryPath, expected);
+		return expected.url;
+	}
+	if (expected?.url) {
+		await retireIncompatibleHub(expected, owner.discoveryPath);
+	}
+	const shouldUseFallbackPort = !hasExplicitPort && endpoint.port !== 0;
+	const spawnEndpoint = shouldUseFallbackPort
+		? { ...endpoint, port: 0 }
+		: endpoint;
+	spawnDetachedHubServer(workspaceRoot, spawnEndpoint);
+	const deadline = Date.now() + HUB_STARTUP_TIMEOUT_MS;
+	while (Date.now() < deadline) {
+		const nextDiscovery = await readHubDiscovery(owner.discoveryPath);
+		if (nextDiscovery?.url) {
+			const healthy = await probeHubServer(nextDiscovery.url);
+			if (
+				healthy?.url &&
+				isCompatibleHubRecord(healthy) &&
+				(await verifyHubConnection(healthy.url))
+			) {
+				return healthy.url;
+			}
+		}
+		const nextExpected = await probeHubServer(expectedUrl);
+		if (
+			nextExpected?.url &&
+			isCompatibleHubRecord(nextExpected) &&
+			(await verifyHubConnection(nextExpected.url))
+		) {
+			await writeHubDiscovery(owner.discoveryPath, nextExpected);
+			return nextExpected.url;
+		}
+		await new Promise((resolve) => setTimeout(resolve, HUB_STARTUP_POLL_MS));
+	}
+	throw new Error("Timed out waiting for detached hub startup.");
+}

package/src/hub/defaults.ts

@@ -0,0 +1,70 @@
+import {
+	CLINE_HUB_DEV_PORT,
+	CLINE_HUB_PORT,
+	resolveClineBuildEnv,
+} from "@clinebot/shared";
+
+const HUB_HOST_ENV = "CLINE_HUB_HOST";
+const HUB_PORT_ENV = "CLINE_HUB_PORT";
+const HUB_PATHNAME_ENV = "CLINE_HUB_PATHNAME";
+
+export const DEFAULT_HUB_HOST = "127.0.0.1";
+export const DEFAULT_HUB_PORT = CLINE_HUB_PORT;
+export const DEFAULT_HUB_PATHNAME = "/hub";
+
+export interface HubEndpointOverrides {
+	host?: string;
+	port?: number;
+	pathname?: string;
+}
+
+export interface ResolveHubDefaultsOptions {
+	env?: NodeJS.ProcessEnv;
+	execArgv?: string[];
+}
+
+function fallbackHubPort(options: ResolveHubDefaultsOptions): number {
+	return resolveClineBuildEnv(options) === "development"
+		? CLINE_HUB_DEV_PORT
+		: DEFAULT_HUB_PORT;
+}
+
+export function resolveDefaultHubHost(
+	options: ResolveHubDefaultsOptions = {},
+): string {
+	const env = options.env ?? process.env;
+	return env[HUB_HOST_ENV]?.trim() || DEFAULT_HUB_HOST;
+}
+
+export function resolveDefaultHubPort(
+	options: ResolveHubDefaultsOptions = {},
+): number {
+	const env = options.env ?? process.env;
+	const raw = env[HUB_PORT_ENV]?.trim();
+	if (!raw) {
+		return fallbackHubPort(options);
+	}
+	const port = Number.parseInt(raw, 10);
+	if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+		return fallbackHubPort(options);
+	}
+	return port;
+}
+
+export function resolveDefaultHubPathname(
+	options: ResolveHubDefaultsOptions = {},
+): string {
+	const env = options.env ?? process.env;
+	return env[HUB_PATHNAME_ENV]?.trim() || DEFAULT_HUB_PATHNAME;
+}
+
+export function resolveHubEndpointOptions(
+	overrides: HubEndpointOverrides = {},
+	options: ResolveHubDefaultsOptions = {},
+): Required<HubEndpointOverrides> {
+	return {
+		host: overrides.host ?? resolveDefaultHubHost(options),
+		port: overrides.port ?? resolveDefaultHubPort(options),
+		pathname: overrides.pathname ?? resolveDefaultHubPathname(options),
+	};
+}