xcode-mcli 0.1.0

package/src/runtime/output.ts

@@ -0,0 +1,128 @@
+import { EXIT_USAGE_ERROR } from "../constants.ts";
+import type { GlobalOptions } from "../core/contracts.ts";
+import type { TemplateError } from "../core/errors.ts";
+
+type CommandResultInput = {
+	commandPath: readonly string[];
+	data?: unknown;
+	globals: GlobalOptions;
+	tabIdentifier?: string;
+	text?: string;
+	tool?: string;
+};
+
+type CommandErrorInput = {
+	argv: string[];
+	error: TemplateError;
+};
+
+function commandPathToString(commandPath: readonly string[]): string {
+	return commandPath.join(" ");
+}
+
+type JsonSuccessEnvelope = {
+	command: string;
+	data: unknown;
+	ok: true;
+	tabIdentifier?: string;
+	tool?: string;
+};
+
+const GLOBAL_BOOLEAN_FLAGS = new Set(["--help", "--json", "--verbose", "--version"]);
+const GLOBAL_VALUE_FLAGS = new Set(["--tab-identifier"]);
+
+function toJsonSuccessEnvelope(input: CommandResultInput): JsonSuccessEnvelope {
+	return {
+		ok: true,
+		command: commandPathToString(input.commandPath),
+		data: input.data ?? {},
+		tabIdentifier: input.tabIdentifier,
+		tool: input.tool,
+	};
+}
+
+function readGlobalOptionsFromArgv(argv: string[]): GlobalOptions {
+	return {
+		json: argv.includes("--json"),
+		verbose: argv.includes("--verbose"),
+	};
+}
+
+function readCommandNameFromArgv(argv: string[]): string {
+	const commandTokens: string[] = [];
+	let reachedCommand = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const token = argv[index];
+		if (typeof token !== "string") {
+			break;
+		}
+		if (!reachedCommand && GLOBAL_BOOLEAN_FLAGS.has(token)) {
+			continue;
+		}
+		if (!reachedCommand && GLOBAL_VALUE_FLAGS.has(token)) {
+			index += 1;
+			continue;
+		}
+		if (token.startsWith("-")) {
+			break;
+		}
+		reachedCommand = true;
+		commandTokens.push(token);
+	}
+	return commandTokens.join(" ");
+}
+
+function readErrorKind(error: TemplateError): "runtime" | "usage" {
+	return error.exitCode === EXIT_USAGE_ERROR ? "usage" : "runtime";
+}
+
+export function toCommandData(input: {
+	structuredContent?: unknown;
+	text?: string;
+}): unknown {
+	if (input.structuredContent !== undefined) {
+		return input.structuredContent;
+	}
+	const text = input.text?.trimEnd() ?? "";
+	if (text.length > 0) {
+		return {
+			text,
+		};
+	}
+	return {};
+}
+
+export function printVerboseTool(globals: GlobalOptions, toolName: string): void {
+	if (!globals.verbose) {
+		return;
+	}
+	console.error(`Xcode MCP tool: ${toolName}`);
+}
+
+export function printCommandResult(input: CommandResultInput): void {
+	if (input.globals.json) {
+		console.log(JSON.stringify(toJsonSuccessEnvelope(input)));
+		return;
+	}
+	console.log(input.text ?? "");
+}
+
+export function printCommandError(input: CommandErrorInput): void {
+	const globals = readGlobalOptionsFromArgv(input.argv);
+	if (!globals.json) {
+		console.error(input.error.message);
+		return;
+	}
+	console.log(
+		JSON.stringify({
+			ok: false,
+			command: input.error.commandName ?? readCommandNameFromArgv(input.argv),
+			tool: input.error.toolName,
+			error: {
+				kind: readErrorKind(input.error),
+				message: input.error.message,
+				details: input.error.details,
+			},
+		}),
+	);
+}

package/src/runtime/tab-resolver.ts

@@ -0,0 +1,44 @@
+import { runtimeError } from "../core/errors.ts";
+import { callDaemonTool } from "./daemon-host.ts";
+import {
+	readDaemonState,
+	setActiveTabIdentifier,
+	setLastSeenWindows,
+} from "./daemon-state.ts";
+import { readWindowsFromToolResult, xcodeWindowsToolResultSchema } from "./xcode-windows.ts";
+
+export async function resolveTabIdentifier(input: {
+	explicitTabIdentifier?: string;
+}): Promise<string> {
+	const explicitTabIdentifier = input.explicitTabIdentifier?.trim();
+	if (explicitTabIdentifier) {
+		await setActiveTabIdentifier(explicitTabIdentifier);
+		return explicitTabIdentifier;
+	}
+	const daemonState = await readDaemonState();
+	if (daemonState.activeTabIdentifier) {
+		return daemonState.activeTabIdentifier;
+	}
+	const result = xcodeWindowsToolResultSchema.parse(
+		await callDaemonTool({
+			name: "XcodeListWindows",
+			arguments: {},
+		}),
+	);
+	const windows = readWindowsFromToolResult(result);
+	await setLastSeenWindows(windows);
+	if (windows.length === 1) {
+		const firstWindow = windows[0];
+		if (!firstWindow) {
+			throw runtimeError("No active Xcode workspace window found.");
+		}
+		await setActiveTabIdentifier(firstWindow.tabIdentifier);
+		return firstWindow.tabIdentifier;
+	}
+	if (windows.length === 0) {
+		throw runtimeError("No active Xcode workspace window found.");
+	}
+	throw runtimeError(
+		"Multiple Xcode windows are open. Run `xcode-mcli windows list` and `windows use --tab-identifier <id>`.",
+	);
+}

package/src/runtime/xcode-client.ts

@@ -0,0 +1,192 @@
+import { spawn } from "node:child_process";
+import { z } from "zod";
+
+import { runtimeError } from "../core/errors.ts";
+import { resolveXcrunPath } from "./env.ts";
+import { JsonRpcPeer } from "./mcp-jsonrpc.ts";
+import { type XcodeToolDefinition, xcodeToolDefinitionSchema } from "./xcode-tool-definition.ts";
+import { normalizeXcodeToolText } from "./xcode-windows.ts";
+
+type McpSurfaceEntry = {
+	name: string;
+	[key: string]: unknown;
+};
+
+type XcodeMcpSurface = {
+	protocolVersion: string;
+	prompts: McpSurfaceEntry[];
+	resources: McpSurfaceEntry[];
+	tools: XcodeToolDefinition[];
+};
+
+type XcodeToolCallResult = {
+	content: Array<Record<string, unknown>>;
+	isError: boolean;
+	structuredContent?: unknown;
+	text: string;
+};
+
+type XcodeBridgeClient = {
+	bridgeProcessId?: number;
+	callTool(
+		input: { arguments: Record<string, unknown>; name: string },
+	): Promise<XcodeToolCallResult>;
+	close(): Promise<void>;
+	listPrompts(): Promise<McpSurfaceEntry[]>;
+	listResources(): Promise<McpSurfaceEntry[]>;
+	listTools(): Promise<XcodeToolDefinition[]>;
+	protocolVersion: string;
+};
+
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const initializeResultSchema = z.object({
+	protocolVersion: z.string().min(1),
+});
+const mcpSurfaceEntrySchema = z.object({
+	name: z.string().min(1),
+}).catchall(z.unknown());
+
+function readTextContent(content: Array<Record<string, unknown>>): string {
+	return normalizeXcodeToolText(
+		content
+			.filter((item) => item.type === "text" && typeof item.text === "string")
+			.map((item) => String(item.text))
+			.join(""),
+	);
+}
+
+function parseStructuredContentFromText(text: string): unknown {
+	const trimmed = text.trim();
+	if (trimmed.length === 0) {
+		return undefined;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object") {
+		return undefined;
+	}
+	if ("message" in parsed && typeof parsed.message === "string") {
+		return undefined;
+	}
+	return parsed;
+}
+
+function toToolCallResult(result: unknown): XcodeToolCallResult {
+	const payload = toolCallResultSchema.parse(result ?? {});
+	const content = payload.content;
+	const text = readTextContent(content);
+	return {
+		content,
+		isError: payload.isError,
+		structuredContent: payload.structuredContent ?? parseStructuredContentFromText(text),
+		text,
+	};
+}
+
+async function initializeClient(peer: JsonRpcPeer): Promise<string> {
+	const result = initializeResultSchema.parse(
+		await peer.request("initialize", {
+			protocolVersion: MCP_PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: {
+				name: "xcode-mcli",
+				version: "0.1.0",
+			},
+		}),
+	);
+	if (!result.protocolVersion) {
+		throw runtimeError("Bridge initialize did not return a protocol version.");
+	}
+	peer.notify("notifications/initialized", {});
+	return result.protocolVersion;
+}
+
+const listToolsResultSchema = z.object({
+	tools: z.array(xcodeToolDefinitionSchema).default([]),
+});
+const listPromptsResultSchema = z.object({
+	prompts: z.array(mcpSurfaceEntrySchema).default([]),
+});
+const listResourcesResultSchema = z.object({
+	resources: z.array(mcpSurfaceEntrySchema).default([]),
+});
+const toolCallResultSchema = z.object({
+	content: z.array(z.record(z.string(), z.unknown())).default([]),
+	isError: z.boolean().default(false),
+	structuredContent: z.unknown().optional(),
+});
+
+export async function createXcodeBridgeClient(): Promise<XcodeBridgeClient> {
+	const child = spawn(resolveXcrunPath(), ["mcpbridge"], {
+		stdio: ["pipe", "pipe", "pipe"],
+		env: process.env,
+	});
+	const peer = new JsonRpcPeer(child);
+	const protocolVersion = await initializeClient(peer);
+	let cachedTools: XcodeToolDefinition[] | null = null;
+	let cachedPrompts: McpSurfaceEntry[] | null = null;
+	let cachedResources: McpSurfaceEntry[] | null = null;
+	return {
+		protocolVersion,
+		bridgeProcessId: child.pid,
+		listTools: async () => {
+			if (cachedTools) {
+				return cachedTools;
+			}
+			const result = listToolsResultSchema.parse(await peer.request("tools/list", {}));
+			cachedTools = result.tools;
+			return cachedTools;
+		},
+		listPrompts: async () => {
+			if (cachedPrompts) {
+				return cachedPrompts;
+			}
+			const result = listPromptsResultSchema.parse(await peer.request("prompts/list", {}));
+			cachedPrompts = result.prompts;
+			return cachedPrompts;
+		},
+		listResources: async () => {
+			if (cachedResources) {
+				return cachedResources;
+			}
+			const result = listResourcesResultSchema.parse(
+				await peer.request("resources/list", {}),
+			);
+			cachedResources = result.resources;
+			return cachedResources;
+		},
+		callTool: async ({ name, arguments: toolArguments }) => {
+			const result = await peer.request("tools/call", {
+				name,
+				arguments: toolArguments,
+			});
+			return toToolCallResult(result);
+		},
+		close: async () => {
+			await peer.close();
+		},
+	};
+}
+
+export async function readXcodeMcpSurface(): Promise<XcodeMcpSurface> {
+	const client = await createXcodeBridgeClient();
+	try {
+		const [tools, prompts, resources] = await Promise.all([
+			client.listTools(),
+			client.listPrompts(),
+			client.listResources(),
+		]);
+		return {
+			protocolVersion: client.protocolVersion,
+			tools,
+			prompts,
+			resources,
+		};
+	} finally {
+		await client.close();
+	}
+}

package/src/runtime/xcode-surface.ts

@@ -0,0 +1,166 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { z } from "zod";
+
+import { runtimeError } from "../core/errors.ts";
+import { readXcodeMcpSurface } from "./xcode-client.ts";
+
+type SurfaceItem = {
+	name: string;
+	[key: string]: unknown;
+};
+
+type SurfaceDelta = {
+	added: string[];
+	changed: string[];
+	removed: string[];
+};
+
+export type XcodeMcpSurfaceSnapshot = {
+	protocolVersion: string;
+	prompts: SurfaceItem[];
+	resources: SurfaceItem[];
+	tools: SurfaceItem[];
+};
+
+export type XcodeMcpSurfaceDiff = {
+	protocolVersionChanged: boolean;
+	prompts: SurfaceDelta;
+	resources: SurfaceDelta;
+	tools: SurfaceDelta;
+};
+
+const surfaceItemSchema = z.object({
+	name: z.string().min(1),
+}).catchall(z.unknown());
+
+const xcodeMcpSurfaceSnapshotSchema = z.object({
+	protocolVersion: z.string().min(1),
+	prompts: z.array(surfaceItemSchema).default([]),
+	resources: z.array(surfaceItemSchema).default([]),
+	tools: z.array(surfaceItemSchema).default([]),
+});
+
+function sortObjectKeys(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map((item) => sortObjectKeys(item));
+	}
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+	return Object.fromEntries(
+		Object.entries(value)
+			.sort(([left], [right]) => left.localeCompare(right))
+			.map(([key, itemValue]) => [key, sortObjectKeys(itemValue)]),
+	);
+}
+
+function normalizeNamedItems(items: SurfaceItem[]): SurfaceItem[] {
+	return items
+		.map((item) => surfaceItemSchema.parse(sortObjectKeys(item)))
+		.sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function createSurfaceDelta(input: {
+	baseline: SurfaceItem[];
+	live: SurfaceItem[];
+}): SurfaceDelta {
+	const baselineByName = new Map(input.baseline.map((item) => [item.name, item]));
+	const liveByName = new Map(input.live.map((item) => [item.name, item]));
+	const added = [...liveByName.keys()].filter((name) => !baselineByName.has(name)).sort();
+	const removed = [...baselineByName.keys()].filter((name) => !liveByName.has(name)).sort();
+	const changed = [...baselineByName.keys()]
+		.filter((name) => liveByName.has(name))
+		.filter((name) => {
+			return JSON.stringify(baselineByName.get(name)) !== JSON.stringify(liveByName.get(name));
+		})
+		.sort();
+	return {
+		added,
+		changed,
+		removed,
+	};
+}
+
+function hasDelta(delta: SurfaceDelta): boolean {
+	return delta.added.length > 0 || delta.changed.length > 0 || delta.removed.length > 0;
+}
+
+export function normalizeXcodeMcpSurfaceSnapshot(
+	snapshot: XcodeMcpSurfaceSnapshot,
+): XcodeMcpSurfaceSnapshot {
+	const parsed = xcodeMcpSurfaceSnapshotSchema.parse(snapshot);
+	return {
+		protocolVersion: parsed.protocolVersion,
+		prompts: normalizeNamedItems(parsed.prompts),
+		resources: normalizeNamedItems(parsed.resources),
+		tools: normalizeNamedItems(parsed.tools),
+	};
+}
+
+export async function captureXcodeMcpSurfaceSnapshot(): Promise<XcodeMcpSurfaceSnapshot> {
+	return normalizeXcodeMcpSurfaceSnapshot(await readXcodeMcpSurface());
+}
+
+export function diffXcodeMcpSurfaceSnapshots(input: {
+	baseline: XcodeMcpSurfaceSnapshot;
+	live: XcodeMcpSurfaceSnapshot;
+}): XcodeMcpSurfaceDiff {
+	const baseline = normalizeXcodeMcpSurfaceSnapshot(input.baseline);
+	const live = normalizeXcodeMcpSurfaceSnapshot(input.live);
+	return {
+		protocolVersionChanged: baseline.protocolVersion !== live.protocolVersion,
+		prompts: createSurfaceDelta({
+			baseline: baseline.prompts,
+			live: live.prompts,
+		}),
+		resources: createSurfaceDelta({
+			baseline: baseline.resources,
+			live: live.resources,
+		}),
+		tools: createSurfaceDelta({
+			baseline: baseline.tools,
+			live: live.tools,
+		}),
+	};
+}
+
+export function xcodeMcpSurfaceDiffHasChanges(diff: XcodeMcpSurfaceDiff): boolean {
+	return diff.protocolVersionChanged
+		|| hasDelta(diff.prompts)
+		|| hasDelta(diff.resources)
+		|| hasDelta(diff.tools);
+}
+
+export async function readXcodeMcpSurfaceSnapshotFile(
+	projectDir: string,
+	filePath: string,
+): Promise<XcodeMcpSurfaceSnapshot> {
+	const resolvedPath = resolve(projectDir, filePath);
+	try {
+		return normalizeXcodeMcpSurfaceSnapshot(
+			JSON.parse(await readFile(resolvedPath, "utf8")),
+		);
+	} catch (error) {
+		if (error instanceof Error) {
+			throw runtimeError(
+				`Failed to read Xcode MCP surface snapshot from ${resolvedPath}. ${error.message}`,
+			);
+		}
+		throw runtimeError(`Failed to read Xcode MCP surface snapshot from ${resolvedPath}.`);
+	}
+}
+
+export async function writeXcodeMcpSurfaceSnapshotFile(input: {
+	filePath: string;
+	projectDir: string;
+	snapshot: XcodeMcpSurfaceSnapshot;
+}): Promise<string> {
+	const resolvedPath = resolve(input.projectDir, input.filePath);
+	await mkdir(dirname(resolvedPath), { recursive: true });
+	await writeFile(
+		resolvedPath,
+		`${JSON.stringify(normalizeXcodeMcpSurfaceSnapshot(input.snapshot), null, 2)}\n`,
+	);
+	return resolvedPath;
+}

package/src/runtime/xcode-tool-definition.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export type XcodeToolDefinition = {
+	description?: string;
+	inputSchema?: Record<string, unknown>;
+	name: string;
+	[key: string]: unknown;
+};
+
+export const xcodeToolDefinitionSchema = z.object({
+	name: z.string().min(1),
+	description: z.string().optional(),
+	inputSchema: z.record(z.string(), z.unknown()).optional(),
+}).catchall(z.unknown());

package/src/runtime/xcode-windows.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+const wrappedMessageSchema = z.object({
+	message: z.string(),
+});
+
+export const xcodeWindowSchema = z.object({
+	tabIdentifier: z.string().min(1),
+	workspacePath: z.string().min(1),
+});
+
+export const xcodeWindowsToolResultSchema = z.object({
+	structuredContent: z
+		.object({
+			windows: z.array(xcodeWindowSchema),
+		})
+		.optional(),
+	text: z.string().default(""),
+});
+
+export function readWindowsFromToolResult(input: {
+	structuredContent?: {
+		windows: Array<z.infer<typeof xcodeWindowSchema>>;
+	};
+	text: string;
+}): Array<z.infer<typeof xcodeWindowSchema>> {
+	return input.structuredContent?.windows ?? parseWindowsFromText(input.text);
+}
+
+export function normalizeXcodeToolText(text: string): string {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("{")) {
+		return text;
+	}
+	let decoded: unknown;
+	try {
+		decoded = JSON.parse(trimmed);
+	} catch {
+		return text;
+	}
+	const parsed = wrappedMessageSchema.safeParse(decoded);
+	if (!parsed.success) {
+		return text;
+	}
+	return parsed.data.message;
+}
+
+export function parseWindowsFromText(text: string): Array<z.infer<typeof xcodeWindowSchema>> {
+	return normalizeXcodeToolText(text)
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.startsWith("* tabIdentifier: "))
+		.flatMap((line) => {
+			const match = /^\* tabIdentifier: ([^,]+), workspacePath: (.+)$/.exec(line);
+			if (!match?.[1] || !match[2]) {
+				return [];
+			}
+			return [
+				{
+					tabIdentifier: match[1],
+					workspacePath: match[2],
+				},
+			];
+		});
+}

package/src/runtime/xcrun.ts

@@ -0,0 +1,39 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+
+import { runtimeError } from "../core/errors.ts";
+import { resolveXcrunPath } from "./env.ts";
+
+const execFile = promisify(execFileCallback);
+const XCODE_TOOLS_GUIDANCE = "Enable Xcode Tools in Settings > Intelligence.";
+
+function toXcrunRuntimeError(error: unknown, message: string) {
+	if (error instanceof Error) {
+		return runtimeError(`${message} ${error.message}`);
+	}
+	return runtimeError(message);
+}
+
+export async function findMcpbridgePath(): Promise<string> {
+	try {
+		const { stdout } = await execFile(resolveXcrunPath(), ["--find", "mcpbridge"]);
+		const bridgePath = stdout.trim();
+		if (bridgePath.length > 0) {
+			return bridgePath;
+		}
+		throw runtimeError("xcrun did not return a mcpbridge path.");
+	} catch (error) {
+		throw toXcrunRuntimeError(error, "Failed to locate xcrun mcpbridge.");
+	}
+}
+
+export async function verifyMcpbridgeHelp(): Promise<void> {
+	try {
+		await execFile(resolveXcrunPath(), ["mcpbridge", "--help"]);
+	} catch (error) {
+		throw toXcrunRuntimeError(
+			error,
+			`Failed to call xcrun mcpbridge --help. ${XCODE_TOOLS_GUIDANCE}`,
+		);
+	}
+}