cursor-agent-bridge 0.1.2 → 0.1.4

package/dist/cli.mjs

@@ -1,16 +1,700 @@
 #!/usr/bin/env node
-import { t as startServer } from "./server-CuHDT_fJ.mjs";
-//#region src/cli.ts
+import { i as CursorRunner, n as engines, r as version, s as toOpenAIModelList, t as startServer } from "./server-Bk7ol2lA.mjs";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+//#region src/cli-args.ts
 function readArg(name, fallback) {
 	const index = process.argv.indexOf(name);
-	return index >= 0 ? process.argv[index + 1] : fallback;
+	if (index < 0) return fallback;
+	const value = process.argv[index + 1];
+	if (!value || value.startsWith("-")) throw new Error(`Missing value for ${name}`);
+	return value;
+}
+function parsePort(value, fallback) {
+	if (value === void 0) return fallback;
+	const port = Number(value);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`Invalid port: ${value}`);
+	return port;
+}
+function readHostAndPort(defaultHost = "127.0.0.1", defaultPort = 4646) {
+	return {
+		host: readArg("--host", process.env.HOST) ?? defaultHost,
+		port: parsePort(readArg("--port", process.env.PORT), defaultPort)
+	};
+}
+//#endregion
+//#region src/codex-config.ts
+const DEFAULT_CODEX_PROFILE = "cursor";
+function resolveCodexConfigPath(profile = DEFAULT_CODEX_PROFILE, homeDir = homedir()) {
+	assertValidProfile(profile);
+	return join(homeDir, ".codex", `${profile}.config.toml`);
+}
+function buildBaseUrl(host, port) {
+	return `http://${host}:${port}/v1`;
+}
+function buildCodexConfigToml(options) {
+	const profile = options.profile ?? "cursor";
+	assertValidProfile(profile);
+	const baseUrl = buildBaseUrl(options.host, options.port);
+	return `model_provider = ${formatTomlString(profile)}
+model = "auto"
+
+[model_providers.${profile}]
+name = "Cursor Agent Bridge"
+base_url = ${formatTomlString(baseUrl)}
+wire_api = "responses"
+`;
+}
+function parseCodexConfig(content, profile = DEFAULT_CODEX_PROFILE) {
+	assertValidProfile(profile);
+	const fields = {};
+	const providerSection = `model_providers.${profile}`;
+	let section = "";
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#")) continue;
+		const sectionMatch = line.match(/^\[(.+)\]$/);
+		if (sectionMatch) {
+			section = sectionMatch[1] ?? "";
+			continue;
+		}
+		const assignment = line.match(/^([A-Za-z0-9_.-]+)\s*=\s*(.+)$/);
+		if (!assignment) continue;
+		const key = assignment[1] ?? "";
+		const value = parseTomlValue(assignment[2] ?? "");
+		if (section === providerSection) {
+			if (key === "name") fields.providerName = value;
+			if (key === "base_url") fields.baseUrl = value;
+			if (key === "wire_api") fields.wireApi = value;
+			continue;
+		}
+		if (section) continue;
+		if (key === "model_provider") fields.modelProvider = value;
+		if (key === "model") fields.model = value;
+	}
+	return fields;
+}
+function checkCodexConfig(content, options) {
+	const profile = options.profile ?? "cursor";
+	const expectedBaseUrl = buildBaseUrl(options.host, options.port);
+	const fields = parseCodexConfig(content, profile);
+	const issues = [];
+	if (fields.modelProvider !== profile) issues.push(`model_provider should be "${profile}"${fields.modelProvider ? `, found "${fields.modelProvider}"` : ", but it is missing"}`);
+	if (fields.baseUrl !== expectedBaseUrl) issues.push(`base_url should be "${expectedBaseUrl}"${fields.baseUrl ? `, found "${fields.baseUrl}"` : ", but it is missing"}`);
+	if (fields.wireApi !== "responses") issues.push(`wire_api should be "responses"${fields.wireApi ? `, found "${fields.wireApi}"` : ", but it is missing"}`);
+	return {
+		ok: issues.length === 0,
+		issues
+	};
+}
+async function writeCodexConfig(options) {
+	let existing;
+	try {
+		existing = await readFile(options.filePath, "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	if (existing === void 0) {
+		await mkdir(dirname(options.filePath), { recursive: true });
+		await writeFile(options.filePath, buildCodexConfigToml(options), "utf8");
+		return {
+			path: options.filePath,
+			created: true,
+			updated: false
+		};
+	}
+	const merged = mergeCodexConfig(existing, options);
+	if ("error" in merged) throw new Error(merged.error);
+	if (!merged.changed) return {
+		path: options.filePath,
+		created: false,
+		updated: false
+	};
+	await writeFile(options.filePath, merged.content, "utf8");
+	return {
+		path: options.filePath,
+		created: false,
+		updated: true
+	};
+}
+function mergeCodexConfig(existing, options) {
+	const profile = options.profile ?? "cursor";
+	assertValidProfile(profile);
+	const providerSection = `model_providers.${profile}`;
+	const expected = buildCodexConfigToml(options);
+	const parsed = parseCodexConfig(existing, profile);
+	if (parsed.modelProvider && parsed.modelProvider !== profile && !options.force) return { error: `model_provider is "${parsed.modelProvider}". Re-run with --force to switch it to "${profile}".` };
+	const lines = existing.split("\n");
+	const output = [];
+	let section = "";
+	let inProviderSection = false;
+	let sawModelProvider = false;
+	let sawModel = false;
+	let sawProviderSection = false;
+	const handledProviderKeys = /* @__PURE__ */ new Set();
+	for (const rawLine of lines) {
+		const trimmed = rawLine.trim();
+		const sectionMatch = trimmed.match(/^\[(.+)\]$/);
+		if (sectionMatch) {
+			if (inProviderSection) appendMissingProviderKeys();
+			section = sectionMatch[1] ?? "";
+			inProviderSection = section === providerSection;
+			if (inProviderSection) sawProviderSection = true;
+			output.push(rawLine);
+			continue;
+		}
+		const assignment = trimmed.match(/^([A-Za-z0-9_.-]+)\s*=\s*(.+)$/);
+		if (!assignment) {
+			output.push(rawLine);
+			continue;
+		}
+		const key = assignment[1] ?? "";
+		if (!section) {
+			if (key === "model_provider") {
+				sawModelProvider = true;
+				output.push(`model_provider = ${formatTomlString(profile)}`);
+				continue;
+			}
+			if (key === "model") {
+				sawModel = true;
+				if (parsed.model === void 0 || options.force) output.push("model = \"auto\"");
+				else output.push(rawLine);
+				continue;
+			}
+		}
+		if (inProviderSection) {
+			if (key === "name") {
+				handledProviderKeys.add("name");
+				output.push("name = \"Cursor Agent Bridge\"");
+				continue;
+			}
+			if (key === "base_url") {
+				handledProviderKeys.add("base_url");
+				output.push(`base_url = ${formatTomlString(buildBaseUrl(options.host, options.port))}`);
+				continue;
+			}
+			if (key === "wire_api") {
+				handledProviderKeys.add("wire_api");
+				output.push("wire_api = \"responses\"");
+				continue;
+			}
+		}
+		output.push(rawLine);
+	}
+	if (inProviderSection) appendMissingProviderKeys();
+	const missingTopLevel = [];
+	if (!sawModelProvider) missingTopLevel.push(`model_provider = ${formatTomlString(profile)}`);
+	if (!sawModel) missingTopLevel.push("model = \"auto\"");
+	let content = output.join("\n").trimEnd();
+	if (missingTopLevel.length > 0) content = `${missingTopLevel.join("\n")}\n${content}`;
+	if (!sawProviderSection) {
+		const providerBlock = expected.split("\n").slice(3).join("\n");
+		content = `${content}\n\n${providerBlock}\n`;
+	}
+	const changed = normalizeToml(content) !== normalizeToml(existing);
+	return {
+		content: `${content.trimEnd()}\n`,
+		changed
+	};
+	function appendMissingProviderKeys() {
+		if (!handledProviderKeys.has("name")) output.push("name = \"Cursor Agent Bridge\"");
+		if (!handledProviderKeys.has("base_url")) output.push(`base_url = ${formatTomlString(buildBaseUrl(options.host, options.port))}`);
+		if (!handledProviderKeys.has("wire_api")) output.push("wire_api = \"responses\"");
+	}
+}
+function assertValidProfile(profile) {
+	if (/^[A-Za-z0-9_-]+$/.test(profile)) return;
+	throw new Error("Invalid Codex profile. Use only letters, numbers, underscores, or hyphens.");
+}
+function formatTomlString(value) {
+	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\b", "\\b").replaceAll("	", "\\t").replaceAll("\n", "\\n").replaceAll("\f", "\\f").replaceAll("\r", "\\r")}"`;
+}
+function normalizeToml(content) {
+	return content.replace(/\r\n/g, "\n").trimEnd();
+}
+function parseTomlValue(raw) {
+	const trimmed = stripInlineTomlComment(raw).trim();
+	if (trimmed.startsWith("\"") && trimmed.endsWith("\"")) return unescapeTomlString(trimmed.slice(1, -1));
+	if (trimmed.startsWith("'") && trimmed.endsWith("'")) return trimmed.slice(1, -1);
+	return trimmed;
+}
+function unescapeTomlString(value) {
+	return value.replace(/\\(["\\btnfr])/g, (_match, escaped) => ({
+		"\"": "\"",
+		"\\": "\\",
+		b: "\b",
+		t: "	",
+		n: "\n",
+		f: "\f",
+		r: "\r"
+	})[escaped] ?? escaped);
+}
+function stripInlineTomlComment(raw) {
+	let quote;
+	for (let index = 0; index < raw.length; index += 1) {
+		const char = raw[index];
+		if ((char === "\"" || char === "'") && raw[index - 1] !== "\\") {
+			quote = quote === char ? void 0 : quote ?? char;
+			continue;
+		}
+		if (!quote && char === "#") return raw.slice(0, index);
+	}
+	return raw;
+}
+//#endregion
+//#region src/doctor.ts
+const execFileAsync$1 = promisify(execFile);
+async function runDoctor(options) {
+	const checks = [];
+	const fetchFn = options.fetchFn ?? fetch;
+	const execFileFn = options.execFileFn ?? execFileAsync$1;
+	const readFileFn = options.readFileFn ?? readFile;
+	const agentPath = options.agentPath ?? process.env.CURSOR_AGENT_PATH ?? "agent";
+	const profile = options.profile ?? "cursor";
+	const codexConfigPath = options.codexConfigPath ?? resolveCodexConfigPath(profile);
+	checks.push(checkNodeVersion(options.nodeVersionRange ?? engines.node));
+	checks.push({
+		name: "bridge-version",
+		ok: true,
+		message: `cursor-agent-bridge ${version}`
+	});
+	const agentCheck = await checkAgentExecutable(agentPath, execFileFn);
+	checks.push(agentCheck);
+	if (agentCheck.ok) checks.push(await checkAgentLogin(agentPath, options.runner));
+	checks.push(await checkBridgeHealth(options.host, options.port, fetchFn));
+	if (!options.skipCodexConfig) checks.push(await checkCodexConfigFile({
+		codexConfigPath,
+		host: options.host,
+		port: options.port,
+		profile,
+		readFileFn
+	}));
+	return {
+		ok: checks.every((check) => check.ok),
+		checks
+	};
+}
+function formatDoctorReport(result) {
+	const lines = result.checks.map((check) => {
+		const prefix = check.ok ? "✓" : "✗";
+		const hint = check.hint ? `\n  → ${check.hint}` : "";
+		return `${prefix} ${check.name}: ${check.message}${hint}`;
+	});
+	lines.push("");
+	lines.push(result.ok ? "All checks passed. Codex can use Cursor Agent through the bridge." : "Some checks failed. Fix the items above before starting Codex.");
+	return `${lines.join("\n")}\n`;
+}
+function checkNodeVersion(requiredRange) {
+	const current = process.version.slice(1);
+	const minimum = parseMinimumNodeVersion(requiredRange);
+	const ok = compareNodeVersion(current, minimum) >= 0;
+	return ok ? {
+		name: "node-version",
+		ok,
+		message: `Node ${current} satisfies ${requiredRange}`
+	} : {
+		name: "node-version",
+		ok,
+		message: `Node ${current} does not satisfy ${requiredRange}`,
+		hint: `Install Node ${minimum} or newer.`
+	};
+}
+async function checkAgentExecutable(agentPath, execFileFn) {
+	try {
+		await execFileFn(agentPath, ["--help"], { timeout: 5e3 });
+		return {
+			name: "agent-cli",
+			ok: true,
+			message: `Cursor Agent CLI found at ${agentPath}`
+		};
+	} catch (error) {
+		return {
+			name: "agent-cli",
+			ok: false,
+			message: error instanceof Error ? error.message : "Cursor Agent CLI not found",
+			hint: "Install the Cursor Agent CLI and ensure `agent` is on PATH, or set CURSOR_AGENT_PATH."
+		};
+	}
+}
+async function checkAgentLogin(agentPath, runner = new CursorRunner({ agentPath })) {
+	try {
+		const models = await runner.listModels({ refresh: true });
+		if (models.length === 0) return {
+			name: "agent-login",
+			ok: false,
+			message: "Cursor Agent responded, but returned no models",
+			hint: "Run `agent login` and confirm `agent --list-models` returns models."
+		};
+		return {
+			name: "agent-login",
+			ok: true,
+			message: `Cursor Agent is logged in (${models.length} models available)`
+		};
+	} catch (error) {
+		return {
+			name: "agent-login",
+			ok: false,
+			message: error instanceof Error ? error.message : "Cursor Agent login check failed",
+			hint: "Run `agent login` and retry `cursor-agent-bridge doctor`."
+		};
+	}
+}
+async function checkBridgeHealth(host, port, fetchFn) {
+	const url = `http://${host}:${port}/health`;
+	try {
+		const response = await fetchFn(url, { signal: AbortSignal.timeout(3e3) });
+		if (!response.ok) return {
+			name: "bridge-health",
+			ok: false,
+			message: `${url} returned HTTP ${response.status}`,
+			hint: "Start the bridge with `cursor-agent-bridge serve` or `cursor-agent-bridge launch-agent install`."
+		};
+		const payload = await response.json();
+		return {
+			name: "bridge-health",
+			ok: true,
+			message: payload.version ? `Bridge is listening on ${url} (version ${payload.version})` : `Bridge is listening on ${url}`
+		};
+	} catch (error) {
+		return {
+			name: "bridge-health",
+			ok: false,
+			message: error instanceof Error ? error.message : "Bridge health check failed",
+			hint: "Start the bridge with `cursor-agent-bridge serve` or `cursor-agent-bridge launch-agent install`."
+		};
+	}
+}
+async function checkCodexConfigFile(options) {
+	try {
+		const result = checkCodexConfig(await options.readFileFn(options.codexConfigPath, "utf8"), {
+			host: options.host,
+			port: options.port,
+			profile: options.profile
+		});
+		if (result.ok) return {
+			name: "codex-config",
+			ok: true,
+			message: `Codex config looks correct at ${options.codexConfigPath}`
+		};
+		return {
+			name: "codex-config",
+			ok: false,
+			message: result.issues.join("; "),
+			hint: "Run `cursor-agent-bridge config write` or `cursor-agent-bridge config print`."
+		};
+	} catch (error) {
+		if (error.code === "ENOENT") return {
+			name: "codex-config",
+			ok: false,
+			message: `Codex config not found at ${options.codexConfigPath}`,
+			hint: "Run `cursor-agent-bridge config write` to create it."
+		};
+		return {
+			name: "codex-config",
+			ok: false,
+			message: error instanceof Error ? error.message : "Codex config check failed",
+			hint: "Verify the Codex config path and file permissions."
+		};
+	}
+}
+function parseMinimumNodeVersion(range) {
+	const match = range.match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+	if (!match) return "0.0.0";
+	return `${match[1]}.${match[2]}.${match[3] ?? 0}`;
+}
+function compareNodeVersion(left, right) {
+	const toParts = (value) => value.split(".").map((part) => Number.parseInt(part, 10) || 0);
+	const [leftMajor = 0, leftMinor = 0, leftPatch = 0] = toParts(left);
+	const [rightMajor = 0, rightMinor = 0, rightPatch = 0] = toParts(right);
+	if (leftMajor !== rightMajor) return leftMajor - rightMajor;
+	if (leftMinor !== rightMinor) return leftMinor - rightMinor;
+	return leftPatch - rightPatch;
+}
+//#endregion
+//#region src/launch-agent.ts
+const defaultLabel = "com.xwartz.cursor-agent-bridge";
+const defaultLogDir = join(homedir(), ".codex", "logs");
+function getLaunchAgentPaths(label = defaultLabel) {
+	return {
+		label,
+		plistPath: join(homedir(), "Library", "LaunchAgents", `${label}.plist`),
+		stdoutPath: join(defaultLogDir, "cursor-agent-bridge.log"),
+		stderrPath: join(defaultLogDir, "cursor-agent-bridge.err.log")
+	};
+}
+function createLaunchAgentPlist(options) {
+	const label = options.label ?? defaultLabel;
+	const host = options.host ?? "127.0.0.1";
+	const port = options.port ?? 4646;
+	const paths = getLaunchAgentPaths(label);
+	const args = [
+		resolve(options.cliPath),
+		"serve",
+		"--host",
+		host,
+		"--port",
+		String(port)
+	];
+	const env = { PATH: [
+		dirname(resolve(options.cliPath)),
+		join(homedir(), ".local", "bin"),
+		"/usr/local/bin",
+		"/opt/homebrew/bin",
+		"/usr/bin",
+		"/bin",
+		"/usr/sbin",
+		"/sbin"
+	].join(":") };
+	if (options.agentPath) env.CURSOR_AGENT_PATH = options.agentPath;
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapePlist(label)}</string>
+
+  <key>ProgramArguments</key>
+  <array>
+${args.map((arg) => `    <string>${escapePlist(arg)}</string>`).join("\n")}
+  </array>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(env).map(([key, value]) => `    <key>${escapePlist(key)}</key>\n    <string>${escapePlist(value)}</string>`).join("\n")}
+  </dict>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>StandardOutPath</key>
+  <string>${escapePlist(paths.stdoutPath)}</string>
+
+  <key>StandardErrorPath</key>
+  <string>${escapePlist(paths.stderrPath)}</string>
+</dict>
+</plist>
+`;
+}
+function installLaunchAgent(options) {
+	ensureMacOS();
+	const paths = getLaunchAgentPaths(options.label ?? defaultLabel);
+	mkdirSync(dirname(paths.plistPath), { recursive: true });
+	mkdirSync(defaultLogDir, { recursive: true });
+	if (existsSync(paths.plistPath)) bootout(paths.plistPath);
+	writeFileSync(paths.plistPath, createLaunchAgentPlist(options));
+	chmodSync(paths.plistPath, 420);
+	execFileSync("launchctl", [
+		"bootstrap",
+		launchctlDomain(),
+		paths.plistPath
+	], { stdio: "pipe" });
+	return paths;
+}
+function uninstallLaunchAgent(label = defaultLabel) {
+	ensureMacOS();
+	const paths = getLaunchAgentPaths(label);
+	bootout(paths.plistPath);
+	rmSync(paths.plistPath, { force: true });
+	return paths;
+}
+function printLaunchAgentStatus(label = defaultLabel) {
+	ensureMacOS();
+	return execFileSync("launchctl", ["print", `${launchctlDomain()}/${label}`], { encoding: "utf8" });
+}
+function bootout(plistPath) {
+	try {
+		execFileSync("launchctl", [
+			"bootout",
+			launchctlDomain(),
+			plistPath
+		], { stdio: "pipe" });
+	} catch {}
+}
+function launchctlDomain() {
+	return `gui/${process.getuid?.() ?? execFileSync("id", ["-u"], { encoding: "utf8" }).trim()}`;
+}
+function ensureMacOS() {
+	if (process.platform !== "darwin") throw new Error("LaunchAgent management is only available on macOS.");
+}
+function escapePlist(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+//#endregion
+//#region src/upgrade.ts
+const execFileAsync = promisify(execFile);
+const PACKAGE_NAME = "cursor-agent-bridge";
+const DEFAULT_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const REGISTRY_TIMEOUT_MS = 1e4;
+function compareSemver(left, right) {
+	const toParts = (value) => {
+		const [major = 0, minor = 0, patch = 0] = value.split(".").map((part) => Number.parseInt(part, 10) || 0);
+		return [
+			major,
+			minor,
+			patch
+		];
+	};
+	const [leftMajor, leftMinor, leftPatch] = toParts(left);
+	const [rightMajor, rightMinor, rightPatch] = toParts(right);
+	if (leftMajor !== rightMajor) return leftMajor < rightMajor ? -1 : 1;
+	if (leftMinor !== rightMinor) return leftMinor < rightMinor ? -1 : 1;
+	if (leftPatch !== rightPatch) return leftPatch < rightPatch ? -1 : 1;
+	return 0;
+}
+async function fetchLatestVersion(options) {
+	const registryUrl = options?.registryUrl ?? DEFAULT_REGISTRY_URL;
+	const fetchFn = options?.fetchFn ?? fetch;
+	const timeoutMs = options?.timeoutMs ?? REGISTRY_TIMEOUT_MS;
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetchFn(registryUrl, { signal: controller.signal });
+		if (!response.ok) throw new Error(`Registry returned ${response.status}`);
+		const payload = await response.json();
+		if (!payload.version) throw new Error("Registry response missing version");
+		return payload.version;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+async function commandExists(command, execFileFn) {
+	try {
+		await execFileFn("which", [command]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function detectPackageManager(preference, execFileFn = execFileAsync) {
+	if (preference === "npm") return "npm";
+	if (preference === "pnpm") return "pnpm";
+	if (!await commandExists("pnpm", execFileFn)) return "npm";
+	try {
+		await execFileFn("pnpm", [
+			"list",
+			"-g",
+			PACKAGE_NAME,
+			"--json"
+		], { env: process.env });
+		return "pnpm";
+	} catch {
+		return "npm";
+	}
+}
+function buildInstallCommand(manager, target) {
+	const packageSpec = `${PACKAGE_NAME}${target === "latest" ? "@latest" : `@${target.replace(/^@/, "")}`}`;
+	if (manager === "pnpm") return {
+		command: "pnpm",
+		args: [
+			"add",
+			"-g",
+			packageSpec
+		]
+	};
+	return {
+		command: "npm",
+		args: [
+			"install",
+			"-g",
+			packageSpec
+		]
+	};
+}
+function printManualUpgradeHint(errorLog) {
+	errorLog("Upgrade manually:");
+	errorLog(`  pnpm add -g ${PACKAGE_NAME}@latest`);
+	errorLog(`  npm install -g ${PACKAGE_NAME}@latest`);
+}
+async function resolveTargetVersion(target, registryUrl, fetchFn) {
+	if (target === "latest") return fetchLatestVersion({
+		registryUrl,
+		fetchFn
+	});
+	return target.replace(/^@/, "");
+}
+async function runInstall(manager, target, spawnFn) {
+	const { command, args } = buildInstallCommand(manager, target);
+	return new Promise((resolve, reject) => {
+		const child = spawnFn(command, args, {
+			stdio: "inherit",
+			env: process.env
+		});
+		child.on("error", reject);
+		child.on("close", (code) => resolve(code ?? 1));
+	});
 }
+async function runUpgrade(options) {
+	const log = options.log ?? console.log;
+	const errorLog = options.errorLog ?? console.error;
+	const checkOnly = options.checkOnly ?? false;
+	const target = options.target ?? "latest";
+	const managerPreference = options.manager ?? "auto";
+	const registryUrl = options.registryUrl ?? DEFAULT_REGISTRY_URL;
+	const fetchFn = options.fetchFn ?? fetch;
+	const spawnFn = options.spawnFn ?? ((command, args, spawnOptions) => spawn(command, args, spawnOptions));
+	const execFileFn = options.execFileFn ?? execFileAsync;
+	const existsFn = options.existsFn ?? existsSync;
+	let targetVersion;
+	try {
+		targetVersion = await resolveTargetVersion(target, registryUrl, fetchFn);
+	} catch (error) {
+		errorLog(`Failed to check for updates: ${error instanceof Error ? error.message : String(error)}`);
+		printManualUpgradeHint(errorLog);
+		return 1;
+	}
+	if (compareSemver(options.currentVersion, targetVersion) >= 0) {
+		log(`${PACKAGE_NAME} is up to date (${options.currentVersion})`);
+		return 0;
+	}
+	if (checkOnly) {
+		log(`Update available: ${options.currentVersion} -> ${targetVersion}`);
+		return 1;
+	}
+	let manager;
+	manager = await detectPackageManager(managerPreference, execFileFn);
+	log(`Installing ${PACKAGE_NAME}@${targetVersion} via ${manager}...`);
+	try {
+		const exitCode = await runInstall(manager, target, spawnFn);
+		if (exitCode !== 0) {
+			errorLog(`${manager} install failed with exit code ${exitCode}`);
+			printManualUpgradeHint(errorLog);
+			return exitCode;
+		}
+	} catch (error) {
+		errorLog(`Install failed: ${error instanceof Error ? error.message : String(error)}`);
+		printManualUpgradeHint(errorLog);
+		return 1;
+	}
+	log(`Installed ${PACKAGE_NAME}@${targetVersion}`);
+	log("Run `cursor-agent-bridge --version` to verify the upgrade.");
+	const launchAgentPlist = getLaunchAgentPaths().plistPath;
+	if (existsFn(launchAgentPlist)) log("LaunchAgent detected. Run `cursor-agent-bridge launch-agent install` to refresh the service.");
+	return 0;
+}
+//#endregion
+//#region src/cli.ts
 const command = process.argv[2] && !process.argv[2]?.startsWith("-") ? process.argv[2] : "serve";
 if (command === "help" || process.argv.includes("--help") || process.argv.includes("-h")) {
 	console.log(`cursor-agent-bridge
 
 Usage:
   cursor-agent-bridge serve [--host 127.0.0.1] [--port 4646]
+  cursor-agent-bridge doctor [--host 127.0.0.1] [--port 4646] [--profile cursor] [--file ~/.codex/cursor.config.toml] [--skip-codex-config]
+  cursor-agent-bridge config print [--host 127.0.0.1] [--port 4646] [--profile cursor]
+  cursor-agent-bridge config check [--file ~/.codex/cursor.config.toml] [--host 127.0.0.1] [--port 4646] [--profile cursor]
+  cursor-agent-bridge config write [--file ~/.codex/cursor.config.toml] [--host 127.0.0.1] [--port 4646] [--profile cursor] [--force]
+  cursor-agent-bridge models [--json] [--refresh]
+  cursor-agent-bridge launch-agent install [--host 127.0.0.1] [--port 4646] [--agent-path agent]
+  cursor-agent-bridge launch-agent uninstall
+  cursor-agent-bridge launch-agent status
+  cursor-agent-bridge upgrade [--check] [--target latest] [--manager auto|npm|pnpm]
 
 Environment:
   HOST                Listen host, default 127.0.0.1
@@ -19,12 +703,151 @@ Environment:
 `);
 	process.exit(0);
 }
+if (command === "version" || process.argv.includes("--version")) {
+	console.log(version);
+	process.exit(0);
+}
+if (command === "upgrade") {
+	const checkOnly = process.argv.includes("--check");
+	const target = readArg("--target", "latest") ?? "latest";
+	const manager = readArg("--manager", "auto") ?? "auto";
+	if (manager !== "auto" && manager !== "npm" && manager !== "pnpm") {
+		console.error("Invalid --manager value. Use auto, npm, or pnpm.");
+		process.exit(1);
+	}
+	const exitCode = await runUpgrade({
+		currentVersion: version,
+		checkOnly,
+		target,
+		manager
+	});
+	process.exit(exitCode);
+}
+if (command === "doctor") try {
+	const { host, port } = readHostAndPort();
+	const profile = readArg("--profile", "cursor") ?? "cursor";
+	const codexConfigPath = readArg("--file", void 0);
+	const result = await runDoctor({
+		host,
+		port,
+		profile,
+		skipCodexConfig: process.argv.includes("--skip-codex-config"),
+		...process.env.CURSOR_AGENT_PATH ? { agentPath: process.env.CURSOR_AGENT_PATH } : {},
+		...codexConfigPath ? { codexConfigPath } : {}
+	});
+	process.stdout.write(formatDoctorReport(result));
+	process.exit(result.ok ? 0 : 1);
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}
+if (command === "config") {
+	const action = process.argv[3] ?? "print";
+	try {
+		const { host, port } = readHostAndPort();
+		const profile = readArg("--profile", "cursor") ?? "cursor";
+		const filePath = readArg("--file", void 0) ?? resolveCodexConfigPath(profile);
+		if (action === "print") {
+			process.stdout.write(buildCodexConfigToml({
+				host,
+				port,
+				profile
+			}));
+			console.error(`Start Codex with: codex --profile ${profile}`);
+			process.exit(0);
+		}
+		if (action === "check") {
+			const result = checkCodexConfig(await readFile(filePath, "utf8"), {
+				host,
+				port,
+				profile
+			});
+			if (result.ok) {
+				console.log(`Codex config looks correct: ${filePath}`);
+				process.exit(0);
+			}
+			for (const issue of result.issues) console.error(issue);
+			process.exit(1);
+		}
+		if (action === "write") {
+			const result = await writeCodexConfig({
+				filePath,
+				host,
+				port,
+				profile,
+				force: process.argv.includes("--force")
+			});
+			if (result.created) console.log(`Created Codex config at ${result.path}`);
+			else if (result.updated) console.log(`Updated Codex config at ${result.path}`);
+			else console.log(`Codex config already up to date at ${result.path}`);
+			console.log(`Start Codex with: codex --profile ${profile}`);
+			process.exit(0);
+		}
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+	console.error(`Unknown config action: ${action}`);
+	process.exit(1);
+}
+if (command === "models") try {
+	const models = await new CursorRunner({ ...process.env.CURSOR_AGENT_PATH ? { agentPath: process.env.CURSOR_AGENT_PATH } : {} }).listModels({ refresh: process.argv.includes("--refresh") });
+	if (process.argv.includes("--json")) {
+		console.log(JSON.stringify(toOpenAIModelList(models), null, 2));
+		process.exit(0);
+	}
+	for (const model of models) console.log(model.id);
+	process.exit(0);
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}
+if (command === "launch-agent") {
+	const action = process.argv[3] ?? "status";
+	try {
+		if (action === "install") {
+			const { host, port } = readHostAndPort();
+			const agentPath = readArg("--agent-path", process.env.CURSOR_AGENT_PATH);
+			const paths = installLaunchAgent({
+				cliPath: process.argv[1] ?? "cursor-agent-bridge",
+				host,
+				port,
+				...agentPath ? { agentPath } : {}
+			});
+			console.log(`Installed ${paths.label}`);
+			console.log(paths.plistPath);
+			process.exit(0);
+		}
+		if (action === "uninstall") {
+			const paths = uninstallLaunchAgent();
+			console.log(`Uninstalled ${paths.label}`);
+			process.exit(0);
+		}
+		if (action === "status") {
+			process.stdout.write(printLaunchAgentStatus());
+			process.exit(0);
+		}
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+	console.error(`Unknown launch-agent action: ${action}`);
+	process.exit(1);
+}
 if (command !== "serve") {
 	console.error(`Unknown command: ${command}`);
 	process.exit(1);
 }
-const host = readArg("--host", process.env.HOST) ?? "127.0.0.1";
-const port = Number(readArg("--port", process.env.PORT) ?? 4646);
+let host;
+let port;
+try {
+	const options = readHostAndPort();
+	host = options.host;
+	port = options.port;
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}
 const server = await startServer({
 	host,
 	port,