@clinebot/core 0.0.34 → 0.0.36

package/src/hub/daemon-entry.ts

@@ -0,0 +1,87 @@
+import { resolveHubEndpointOptions } from "./defaults";
+import { createLocalHubScheduleRuntimeHandlers } from "./runtime-handlers";
+import { startHubWebSocketServer } from "./server";
+import { resolveSharedHubOwnerContext } from "./workspace";
+
+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(),
+	});
+
+	const shutdown = async (): Promise<void> => {
+		await server.close();
+		process.exit(0);
+	};
+
+	process.on("SIGINT", () => {
+		void shutdown();
+	});
+	process.on("SIGTERM", () => {
+		void shutdown();
+	});
+
+	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,181 @@
+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 { withResolvedClineBuildEnv } from "@clinebot/shared";
+import { verifyHubConnection } from "./client";
+import {
+	type HubEndpointOverrides,
+	resolveHubEndpointOptions,
+} from "./defaults";
+import {
+	createHubServerUrl,
+	probeHubServer,
+	readHubDiscovery,
+	resolveClineDataDir,
+	writeHubDiscovery,
+} from "./discovery";
+import { resolveSharedHubOwnerContext } from "./workspace";
+
+const HUB_STARTUP_TIMEOUT_MS = 8_000;
+const HUB_STARTUP_POLL_MS = 200;
+
+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 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",
+		},
+	};
+}
+
+export function spawnDetachedHubServer(
+	workspaceRoot: string,
+	endpoint: HubEndpointOverrides = {},
+): void {
+	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 {
+	const owner = resolveSharedHubOwnerContext();
+	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 && (await verifyHubConnection(healthy.url))) {
+					return;
+				}
+			}
+			const expected = await probeHubServer(expectedUrl);
+			if (expected?.url && (await verifyHubConnection(expected.url))) {
+				await writeHubDiscovery(owner.discoveryPath, expected);
+				return;
+			}
+			const spawnEndpoint =
+				expected?.url && resolvedEndpoint.port !== 0
+					? { ...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 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 && (await verifyHubConnection(healthy.url))) {
+			return healthy.url;
+		}
+	}
+	const expected = await probeHubServer(expectedUrl);
+	if (expected?.url && (await verifyHubConnection(expected.url))) {
+		await writeHubDiscovery(owner.discoveryPath, expected);
+		return expected.url;
+	}
+	const spawnEndpoint =
+		expected?.url && endpoint.port !== 0 ? { ...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 && (await verifyHubConnection(healthy.url))) {
+				return healthy.url;
+			}
+		}
+		const nextExpected = await probeHubServer(expectedUrl);
+		if (nextExpected?.url && (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,43 @@
+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 = 25463;
+export const DEFAULT_HUB_PATHNAME = "/hub";
+
+export interface HubEndpointOverrides {
+	host?: string;
+	port?: number;
+	pathname?: string;
+}
+
+export function resolveDefaultHubHost(): string {
+	return process.env[HUB_HOST_ENV]?.trim() || DEFAULT_HUB_HOST;
+}
+
+export function resolveDefaultHubPort(): number {
+	const raw = process.env[HUB_PORT_ENV]?.trim();
+	if (!raw) {
+		return DEFAULT_HUB_PORT;
+	}
+	const port = Number.parseInt(raw, 10);
+	if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+		return DEFAULT_HUB_PORT;
+	}
+	return port;
+}
+
+export function resolveDefaultHubPathname(): string {
+	return process.env[HUB_PATHNAME_ENV]?.trim() || DEFAULT_HUB_PATHNAME;
+}
+
+export function resolveHubEndpointOptions(
+	overrides: HubEndpointOverrides = {},
+): Required<HubEndpointOverrides> {
+	return {
+		host: overrides.host ?? resolveDefaultHubHost(),
+		port: overrides.port ?? resolveDefaultHubPort(),
+		pathname: overrides.pathname ?? resolveDefaultHubPathname(),
+	};
+}

package/src/hub/discovery.ts

@@ -0,0 +1,247 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveClineDataDir, resolveClineDir } from "@clinebot/shared/storage";
+import corePackage from "../../package.json";
+
+const HUB_DISCOVERY_ENV = "CLINE_HUB_DISCOVERY_PATH";
+const HUB_BUILD_ID_ENV = "CLINE_HUB_BUILD_ID";
+const HUB_STARTUP_LOCK_MAX_AGE_MS = 30_000;
+const HUB_STARTUP_LOCK_WAIT_MS = 15_000;
+const HUB_STARTUP_LOCK_POLL_MS = 100;
+
+export interface HubServerDiscoveryRecord {
+	hubId: string;
+	protocolVersion: string;
+	buildId?: string;
+	host: string;
+	port: number;
+	url: string;
+	pid?: number;
+	startedAt: string;
+	updatedAt: string;
+}
+
+export interface HubOwnerContext {
+	ownerId: string;
+	discoveryPath: string;
+}
+
+function sanitizeKey(value: string): string {
+	return value.replace(/[^a-zA-Z0-9_.-]+/g, "_");
+}
+
+function hashValue(value: string): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+function isPidAlive(pid: number | undefined): boolean {
+	if (!Number.isInteger(pid) || !pid || pid <= 0) {
+		return false;
+	}
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error instanceof Error && "code" in error
+			? String((error as NodeJS.ErrnoException).code) === "EPERM"
+			: false;
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function getStartupLockDir(discoveryPath: string): string {
+	return `${discoveryPath}.lock`;
+}
+
+async function readStartupLockRecord(
+	lockDir: string,
+): Promise<{ pid: number; acquiredAt: string } | undefined> {
+	try {
+		const parsed = JSON.parse(
+			await readFile(join(lockDir, "owner.json"), "utf8"),
+		) as Partial<{ pid: number; acquiredAt: string }>;
+		if (
+			typeof parsed.pid !== "number" ||
+			typeof parsed.acquiredAt !== "string"
+		) {
+			return undefined;
+		}
+		return { pid: parsed.pid, acquiredAt: parsed.acquiredAt };
+	} catch {
+		return undefined;
+	}
+}
+
+async function removeStartupLock(lockDir: string): Promise<void> {
+	await rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+}
+
+export function resolveHubBuildId(): string {
+	return process.env[HUB_BUILD_ID_ENV]?.trim() || String(corePackage.version);
+}
+
+export function resolveHubOwnerContext(
+	ownerBasis: string = process.argv[1]?.trim() || process.cwd(),
+): HubOwnerContext {
+	const ownerId = `hub-${hashValue(ownerBasis)}`;
+	const discoveryPath =
+		process.env[HUB_DISCOVERY_ENV]?.trim() ||
+		join(
+			resolveClineDataDir(),
+			"locks",
+			"hub",
+			"owners",
+			`${sanitizeKey(ownerId)}.json`,
+		);
+	return { ownerId, discoveryPath };
+}
+
+export function createInMemoryHubOwnerContext(
+	label = `hub-${Date.now().toString(36)}`,
+): HubOwnerContext {
+	return resolveHubOwnerContext(label);
+}
+
+export async function readHubDiscovery(
+	discoveryPath: string,
+): Promise<HubServerDiscoveryRecord | undefined> {
+	try {
+		const parsed = JSON.parse(
+			await readFile(discoveryPath, "utf8"),
+		) as Partial<HubServerDiscoveryRecord>;
+		if (
+			typeof parsed.hubId !== "string" ||
+			typeof parsed.protocolVersion !== "string" ||
+			typeof parsed.host !== "string" ||
+			typeof parsed.port !== "number" ||
+			typeof parsed.url !== "string" ||
+			typeof parsed.startedAt !== "string" ||
+			typeof parsed.updatedAt !== "string"
+		) {
+			return undefined;
+		}
+		return {
+			hubId: parsed.hubId,
+			protocolVersion: parsed.protocolVersion,
+			buildId: typeof parsed.buildId === "string" ? parsed.buildId : undefined,
+			host: parsed.host,
+			port: parsed.port,
+			url: parsed.url,
+			pid: typeof parsed.pid === "number" ? parsed.pid : undefined,
+			startedAt: parsed.startedAt,
+			updatedAt: parsed.updatedAt,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+export async function writeHubDiscovery(
+	discoveryPath: string,
+	record: HubServerDiscoveryRecord,
+): Promise<void> {
+	await mkdir(dirname(discoveryPath), { recursive: true });
+	await writeFile(
+		discoveryPath,
+		`${JSON.stringify(record, null, 2)}\n`,
+		"utf8",
+	);
+}
+
+export async function clearHubDiscovery(discoveryPath: string): Promise<void> {
+	await rm(discoveryPath, { force: true }).catch(() => undefined);
+}
+
+export async function withHubStartupLock<T>(
+	discoveryPath: string,
+	callback: () => Promise<T>,
+): Promise<T> {
+	const lockDir = getStartupLockDir(discoveryPath);
+	await mkdir(dirname(lockDir), { recursive: true });
+	const deadline = Date.now() + HUB_STARTUP_LOCK_WAIT_MS;
+
+	while (true) {
+		try {
+			await mkdir(lockDir, { recursive: false });
+			await writeFile(
+				join(lockDir, "owner.json"),
+				`${JSON.stringify(
+					{ pid: process.pid, acquiredAt: new Date().toISOString() },
+					null,
+					2,
+				)}\n`,
+				"utf8",
+			);
+			try {
+				return await callback();
+			} finally {
+				await removeStartupLock(lockDir);
+			}
+		} catch (error) {
+			const code =
+				error instanceof Error && "code" in error
+					? String((error as NodeJS.ErrnoException).code)
+					: "";
+			if (code !== "EEXIST") {
+				throw error;
+			}
+			const record = await readStartupLockRecord(lockDir);
+			const lockAge = record
+				? Date.now() - Date.parse(record.acquiredAt)
+				: HUB_STARTUP_LOCK_MAX_AGE_MS + 1;
+			if (
+				!record ||
+				!isPidAlive(record.pid) ||
+				lockAge > HUB_STARTUP_LOCK_MAX_AGE_MS
+			) {
+				await removeStartupLock(lockDir);
+				continue;
+			}
+			if (Date.now() >= deadline) {
+				throw new Error(`Timed out waiting for hub startup lock ${lockDir}`);
+			}
+			await sleep(HUB_STARTUP_LOCK_POLL_MS);
+		}
+	}
+}
+
+export async function probeHubServer(
+	url: string,
+): Promise<HubServerDiscoveryRecord | undefined> {
+	try {
+		const response = await fetch(toHubHealthUrl(url));
+		if (!response.ok) {
+			return undefined;
+		}
+		return (await response.json()) as HubServerDiscoveryRecord;
+	} catch {
+		return undefined;
+	}
+}
+
+export function createHubServerUrl(
+	host: string,
+	port: number,
+	pathname = "/hub",
+): string {
+	return new URL(`ws://${host}:${port}${pathname}`).toString();
+}
+
+export function toHubHealthUrl(wsUrl: string): string {
+	const parsed = new URL(wsUrl);
+	parsed.protocol = parsed.protocol === "wss:" ? "https:" : "http:";
+	parsed.pathname = "/health";
+	parsed.search = "";
+	return parsed.toString();
+}
+
+export function isDiscoveryFilePresent(pathname: string): boolean {
+	return existsSync(pathname);
+}
+
+export { resolveClineDataDir, resolveClineDir };

package/src/hub/index.ts

@@ -0,0 +1,14 @@
+export * from "./browser-websocket";
+export * from "./client";
+export * from "./connect";
+export * from "./daemon";
+export * from "./defaults";
+export * from "./discovery";
+export * from "./native-transport";
+export * from "./runtime-handlers";
+export * from "./server";
+export * from "./session-client";
+export * from "./start-shared-server";
+export * from "./transport";
+export * from "./ui-client";
+export * from "./workspace";

package/src/hub/native-transport.ts

@@ -0,0 +1,31 @@
+import type {
+	HubCommandEnvelope,
+	HubEventEnvelope,
+	HubReplyEnvelope,
+} from "@clinebot/shared";
+import type { HubCommandTransport } from "./transport";
+
+export interface NativeHubTransport {
+	handleCommand(envelope: HubCommandEnvelope): Promise<HubReplyEnvelope>;
+	subscribe(
+		clientId: string,
+		listener: (event: HubEventEnvelope) => void,
+		options?: { sessionId?: string },
+	): () => void;
+}
+
+export class NativeHubTransportAdapter implements HubCommandTransport {
+	constructor(private readonly transport: NativeHubTransport) {}
+
+	command(envelope: HubCommandEnvelope): Promise<HubReplyEnvelope> {
+		return this.transport.handleCommand(envelope);
+	}
+
+	subscribe(
+		clientId: string,
+		listener: (event: HubEventEnvelope) => void,
+		options?: { sessionId?: string },
+	): () => void {
+		return this.transport.subscribe(clientId, listener, options);
+	}
+}