xcode-mcli 0.1.0

package/src/commands/tool-command.ts

@@ -0,0 +1,150 @@
+import type { Command } from "commander";
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { runtimeError } from "../core/errors.ts";
+import { callDaemonTool } from "../runtime/daemon-host.ts";
+import {
+	printCommandResult,
+	printVerboseTool,
+	toCommandData,
+} from "../runtime/output.ts";
+import { resolveTabIdentifier } from "../runtime/tab-resolver.ts";
+
+type ToolCommandResult = {
+	structuredContent?: unknown;
+	text: string;
+};
+
+type ToolCommandDefinitionInput<TOptions> = {
+	buildArguments: (options: TOptions) => Promise<Record<string, unknown>> | Record<string, unknown>;
+	configure?: (command: Command) => void;
+	description: string;
+	path: readonly [string, ...string[]];
+	requiresTab?: boolean;
+	toolName: string;
+	optionsSchema: z.ZodType<TOptions>;
+};
+
+const toolCommandResultSchema = z.object({
+	structuredContent: z.unknown().optional(),
+	text: z.string().default(""),
+});
+
+function defaultToolText(result: ToolCommandResult): string {
+	const text = result.text.trimEnd();
+	if (text.length > 0) {
+		return text;
+	}
+	if (result.structuredContent !== undefined) {
+		return JSON.stringify(result.structuredContent, null, 2);
+	}
+	return "";
+}
+
+function readTabIdentifierOption(options: unknown): string | undefined {
+	if (!options || typeof options !== "object") {
+		return undefined;
+	}
+	if (!("tabIdentifier" in options)) {
+		return undefined;
+	}
+	const candidate = options.tabIdentifier;
+	if (typeof candidate !== "string") {
+		return undefined;
+	}
+	return candidate;
+}
+
+export function addTabIdentifierOption(command: Command): void {
+	command.option("--tab-identifier <id>", "Active Xcode window tab identifier.");
+}
+
+export function collectRepeatedStrings(
+	value: string,
+	previous: string[] | undefined,
+): string[] {
+	return [...(previous ?? []), value];
+}
+
+export function parseKeyValuePairs(values: string[]): Record<string, string>[] {
+	const result: Record<string, string>[] = [];
+	let current: Record<string, string> = {};
+	for (const value of values) {
+		const separatorIndex = value.indexOf("=");
+		if (separatorIndex <= 0) {
+			throw runtimeError(`Invalid key=value input: ${value}`);
+		}
+		const key = value.slice(0, separatorIndex);
+		const parsedValue = value.slice(separatorIndex + 1);
+		current[key] = parsedValue;
+		if (current.targetName && current.testIdentifier) {
+			result.push(current);
+			current = {};
+		}
+	}
+	if (Object.keys(current).length > 0) {
+		throw runtimeError("Incomplete test specifier. Expected both targetName and testIdentifier.");
+	}
+	return result;
+}
+
+export async function resolveWriteContent(input: {
+	content?: string;
+	contentFile?: string;
+}): Promise<string> {
+	if (typeof input.content === "string") {
+		return input.content;
+	}
+	if (typeof input.contentFile === "string") {
+		return readFile(input.contentFile, "utf8");
+	}
+	throw runtimeError("Expected --content or --content-file.");
+}
+
+export function requireYes(
+	input: { condition: boolean; commandName: string; yes?: boolean },
+): void {
+	if (input.condition && input.yes) {
+		return;
+	}
+	if (input.condition) {
+		throw runtimeError(`Command requires --yes: ${input.commandName}`);
+	}
+}
+
+export function createToolCommand<TOptions>(input: ToolCommandDefinitionInput<TOptions>) {
+	return defineCommand({
+		path: input.path,
+		description: input.description,
+		toolName: input.toolName,
+		configure: input.configure,
+		optionsSchema: input.optionsSchema,
+		run: async ({ commandPath, globals, options }) => {
+			const toolArguments = await input.buildArguments(options);
+			if (input.requiresTab && typeof toolArguments.tabIdentifier !== "string") {
+				toolArguments.tabIdentifier = await resolveTabIdentifier({
+					explicitTabIdentifier: readTabIdentifierOption(options),
+				});
+			}
+			printVerboseTool(globals, input.toolName);
+			const result = toolCommandResultSchema.parse(
+				await callDaemonTool({
+					name: input.toolName,
+					arguments: toolArguments,
+				}),
+			);
+			printCommandResult({
+				commandPath,
+				globals,
+				text: defaultToolText(result),
+				data: toCommandData(result),
+				tabIdentifier: typeof toolArguments.tabIdentifier === "string"
+					? toolArguments.tabIdentifier
+					: undefined,
+				tool: input.toolName,
+			});
+		},
+	});
+}

package/src/commands/windows-list.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { callDaemonTool } from "../runtime/daemon-host.ts";
+import { setLastSeenWindows } from "../runtime/daemon-state.ts";
+import {
+	printCommandResult,
+	printVerboseTool,
+	toCommandData,
+} from "../runtime/output.ts";
+import {
+	readWindowsFromToolResult,
+	xcodeWindowsToolResultSchema,
+} from "../runtime/xcode-windows.ts";
+
+export const windowsListCommand = defineCommand({
+	path: ["windows", "list"],
+	description: "List open Xcode windows.",
+	toolName: "XcodeListWindows",
+	optionsSchema: z.object({}),
+	run: async ({ commandPath, globals }) => {
+		printVerboseTool(globals, "XcodeListWindows");
+		const result = xcodeWindowsToolResultSchema.parse(
+			await callDaemonTool({
+				name: "XcodeListWindows",
+				arguments: {},
+			}),
+		);
+		const windows = readWindowsFromToolResult(result);
+		await setLastSeenWindows(windows);
+		printCommandResult({
+			commandPath,
+			globals,
+			text: result.text.trimEnd(),
+			data: windows.length > 0
+				? {
+					windows,
+				}
+				: toCommandData(result),
+			tool: "XcodeListWindows",
+		});
+	},
+});

package/src/commands/windows-use.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { setActiveTabIdentifier } from "../runtime/daemon-state.ts";
+import { printCommandResult } from "../runtime/output.ts";
+
+const windowsUseOptionsSchema = z.object({
+	tabIdentifier: z.string().trim().min(1),
+});
+
+export const windowsUseCommand = defineCommand({
+	path: ["windows", "use"],
+	description: "Select the active Xcode window tab.",
+	configure: (command) => {
+		command.option("--tab-identifier <id>", "Active Xcode window tab identifier.");
+	},
+	optionsSchema: windowsUseOptionsSchema,
+	run: async ({ commandPath, globals, options }) => {
+		await setActiveTabIdentifier(options.tabIdentifier);
+		printCommandResult({
+			commandPath,
+			globals,
+			text: `Active Xcode tab set to ${options.tabIdentifier}.`,
+			tabIdentifier: options.tabIdentifier,
+			data: {
+				tabIdentifier: options.tabIdentifier,
+			},
+		});
+	},
+});

package/src/commands/xcode-tool-commands.ts

@@ -0,0 +1,460 @@
+import type { Command } from "commander";
+import { z } from "zod";
+
+import {
+	addTabIdentifierOption,
+	collectRepeatedStrings,
+	createToolCommand,
+	parseKeyValuePairs,
+	requireYes,
+	resolveWriteContent,
+} from "./tool-command.ts";
+
+const severitySchema = z.enum(["error", "warning", "remark"]);
+const outputModeSchema = z.enum(["content", "files_with_matches", "count"]);
+const optionalTabIdentifierShape = {
+	tabIdentifier: z.string().trim().min(1).optional(),
+};
+const yesAndOptionalTabShape = {
+	yes: z.boolean().default(false),
+	...optionalTabIdentifierShape,
+};
+const sourceFileTimeoutShape = {
+	sourceFilePath: z.string().trim().min(1),
+	timeout: z.coerce.number().positive().optional(),
+	...optionalTabIdentifierShape,
+};
+const tabOnlyCommandSpecs = [
+	{
+		description: "List tests from the active test plan.",
+		path: ["tests", "list"] as const,
+		toolName: "GetTestList",
+	},
+	{
+		description: "Run all tests from the active test plan.",
+		path: ["tests", "run-all"] as const,
+		toolName: "RunAllTests",
+	},
+];
+const filteredCommandSpecs = [
+	{
+		description: "Read the current or latest build log.",
+		path: ["build", "log"] as const,
+		toolName: "GetBuildLog",
+	},
+	{
+		description: "List navigator issues.",
+		path: ["issues", "list"] as const,
+		toolName: "XcodeListNavigatorIssues",
+	},
+];
+
+function createTabOnlyCommand(input: (typeof tabOnlyCommandSpecs)[number]) {
+	return createToolCommand({
+		path: input.path,
+		description: input.description,
+		toolName: input.toolName,
+		requiresTab: true,
+		optionsSchema: z.object(optionalTabIdentifierShape),
+		configure: addTabIdentifierOption,
+		buildArguments: (options) => options,
+	});
+}
+
+function createFilteredCommand(input: (typeof filteredCommandSpecs)[number]) {
+	return createToolCommand({
+		path: input.path,
+		description: input.description,
+		toolName: input.toolName,
+		requiresTab: true,
+		optionsSchema: z.object({
+			glob: z.string().trim().min(1).optional(),
+			pattern: z.string().trim().min(1).optional(),
+			severity: severitySchema.optional(),
+			...optionalTabIdentifierShape,
+		}),
+		configure: (command) => {
+			command.option("--glob <glob>", "Filter results by glob.");
+			command.option("--pattern <regex>", "Filter results by regex.");
+			command.option("--severity <level>", "Minimum issue severity.");
+			addTabIdentifierOption(command);
+		},
+		buildArguments: (options) => options,
+	});
+}
+
+function configureSourceFileTimeoutCommand(command: Command, input: {
+	includePreviewDefinitionIndex?: boolean;
+	sourceHelp: string;
+}): void {
+	command.requiredOption("--source-file-path <path>", input.sourceHelp);
+	if (input.includePreviewDefinitionIndex) {
+		command.option(
+			"--preview-definition-index-in-file <n>",
+			"Zero-based preview definition index.",
+		);
+	}
+	command.option("--timeout <seconds>", "Execution timeout in seconds.");
+	addTabIdentifierOption(command);
+}
+
+const docsSearchCommand = createToolCommand({
+	path: ["docs", "search"],
+	description: "Search Apple documentation through Xcode MCP.",
+	toolName: "DocumentationSearch",
+	optionsSchema: z.object({
+		query: z.string().trim().min(1),
+		framework: z.array(z.string()).default([]),
+	}),
+	configure: (command) => {
+		command.requiredOption("--query <text>", "Search query text.");
+		command.option(
+			"--framework <name>",
+			"Restrict search to a framework.",
+			collectRepeatedStrings,
+			[],
+		);
+	},
+	buildArguments: (options) => ({
+		query: options.query,
+		frameworks: options.framework,
+	}),
+});
+
+const snippetExecuteCommand = createToolCommand({
+	path: ["snippet", "execute"],
+	description: "Execute a Swift snippet in Xcode source context.",
+	toolName: "ExecuteSnippet",
+	requiresTab: true,
+	optionsSchema: z.object({
+		codeSnippet: z.string().min(1),
+		...sourceFileTimeoutShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--code-snippet <swift>", "Swift snippet to execute.");
+		configureSourceFileTimeoutCommand(command, {
+			sourceHelp: "Source file path.",
+		});
+	},
+	buildArguments: (options) => ({
+		codeSnippet: options.codeSnippet,
+		sourceFilePath: options.sourceFilePath,
+		timeout: options.timeout,
+		tabIdentifier: options.tabIdentifier,
+	}),
+});
+
+const previewRenderCommand = createToolCommand({
+	path: ["preview", "render"],
+	description: "Render a SwiftUI preview.",
+	toolName: "RenderPreview",
+	requiresTab: true,
+	optionsSchema: z.object({
+		previewDefinitionIndexInFile: z.coerce.number().int().nonnegative().optional(),
+		...sourceFileTimeoutShape,
+	}),
+	configure: (command) => {
+		configureSourceFileTimeoutCommand(command, {
+			includePreviewDefinitionIndex: true,
+			sourceHelp: "Preview source file path.",
+		});
+	},
+	buildArguments: (options) => options,
+});
+
+const testsRunSomeCommand = createToolCommand({
+	path: ["tests", "run-some"],
+	description: "Run selected tests from the active test plan.",
+	toolName: "RunSomeTests",
+	requiresTab: true,
+	optionsSchema: z.object({
+		test: z.array(z.string()).min(2),
+		...optionalTabIdentifierShape,
+	}),
+	configure: (command) => {
+		command.option(
+			"--test <key=value>",
+			"Repeatable test specifier field.",
+			collectRepeatedStrings,
+			[],
+		);
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => ({
+		tabIdentifier: options.tabIdentifier,
+		tests: parseKeyValuePairs(options.test),
+	}),
+});
+
+const filesGlobCommand = createToolCommand({
+	path: ["files", "glob"],
+	description: "Glob Xcode project files.",
+	toolName: "XcodeGlob",
+	requiresTab: true,
+	optionsSchema: z.object({
+		path: z.string().trim().min(1).optional(),
+		pattern: z.string().trim().min(1).optional(),
+		...optionalTabIdentifierShape,
+	}),
+	configure: (command) => {
+		command.option("--path <path>", "Project navigator path.");
+		command.option("--pattern <glob>", "Glob pattern.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => options,
+});
+
+const filesGrepCommand = createToolCommand({
+	path: ["files", "grep"],
+	description: "Grep Xcode project files.",
+	toolName: "XcodeGrep",
+	requiresTab: true,
+	optionsSchema: z.object({
+		glob: z.string().trim().min(1).optional(),
+		headLimit: z.coerce.number().int().positive().optional(),
+		ignoreCase: z.boolean().default(false),
+		linesAfter: z.coerce.number().int().nonnegative().optional(),
+		linesBefore: z.coerce.number().int().nonnegative().optional(),
+		linesContext: z.coerce.number().int().nonnegative().optional(),
+		multiline: z.boolean().default(false),
+		outputMode: outputModeSchema.optional(),
+		path: z.string().trim().min(1).optional(),
+		pattern: z.string().trim().min(1),
+		showLineNumbers: z.boolean().default(false),
+		type: z.string().trim().min(1).optional(),
+		...optionalTabIdentifierShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--pattern <regex>", "Content regex.");
+		command.option("--glob <glob>", "Filter files by glob.");
+		command.option("--head-limit <n>", "Limit matches.");
+		command.option("--ignore-case", "Case-insensitive search.");
+		command.option("--lines-after <n>", "Lines of trailing context.");
+		command.option("--lines-before <n>", "Lines of leading context.");
+		command.option("--lines-context <n>", "Lines of surrounding context.");
+		command.option("--multiline", "Enable multiline regex.");
+		command.option("--output-mode <mode>", "Output mode.");
+		command.option("--path <path>", "Project navigator path.");
+		command.option("--show-line-numbers", "Show line numbers.");
+		command.option("--type <type>", "File type filter.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => options,
+});
+
+const filesLsCommand = createToolCommand({
+	path: ["files", "ls"],
+	description: "List Xcode project files.",
+	toolName: "XcodeLS",
+	requiresTab: true,
+	optionsSchema: z.object({
+		ignore: z.array(z.string()).default([]),
+		path: z.string().trim().min(1),
+		recursive: z.boolean().default(false),
+		...optionalTabIdentifierShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--path <path>", "Project navigator path.");
+		command.option("--ignore <pattern>", "Ignore pattern.", collectRepeatedStrings, []);
+		command.option("--recursive", "Recurse through directories.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => options,
+});
+
+const filesMvCommand = createToolCommand({
+	path: ["files", "mv"],
+	description: "Move a file or group in Xcode.",
+	toolName: "XcodeMV",
+	requiresTab: true,
+	optionsSchema: z.object({
+		destinationPath: z.string().trim().min(1),
+		operation: z.string().trim().min(1).optional(),
+		overwriteExisting: z.boolean().default(false),
+		sourcePath: z.string().trim().min(1),
+		yes: z.boolean().default(false),
+		...optionalTabIdentifierShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--source-path <path>", "Source path.");
+		command.requiredOption("--destination-path <path>", "Destination path.");
+		command.option("--operation <operation>", "Move operation.");
+		command.option("--overwrite-existing", "Overwrite an existing destination.");
+		command.option("--yes", "Confirm the overwrite.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => {
+		requireYes({
+			condition: options.overwriteExisting,
+			commandName: "files mv --overwrite-existing",
+			yes: options.yes,
+		});
+		return options;
+	},
+});
+
+const filesMkdirCommand = createToolCommand({
+	path: ["files", "mkdir"],
+	description: "Create a directory in Xcode.",
+	toolName: "XcodeMakeDir",
+	requiresTab: true,
+	optionsSchema: z.object({
+		directoryPath: z.string().trim().min(1),
+		...optionalTabIdentifierShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--directory-path <path>", "Directory path.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => options,
+});
+
+const filesRmCommand = createToolCommand({
+	path: ["files", "rm"],
+	description: "Remove files or groups in Xcode.",
+	toolName: "XcodeRM",
+	requiresTab: true,
+	optionsSchema: z.object({
+		deleteFiles: z.boolean().default(false),
+		path: z.string().trim().min(1),
+		recursive: z.boolean().default(false),
+		...yesAndOptionalTabShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--path <path>", "Path to remove.");
+		command.option("--delete-files", "Delete underlying files.");
+		command.option("--recursive", "Remove recursively.");
+		command.option("--yes", "Confirm removal.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => {
+		requireYes({
+			condition: true,
+			commandName: "files rm",
+			yes: options.yes,
+		});
+		return options;
+	},
+});
+
+const filesReadCommand = createToolCommand({
+	path: ["files", "read"],
+	description: "Read a file in Xcode.",
+	toolName: "XcodeRead",
+	requiresTab: true,
+	optionsSchema: z.object({
+		filePath: z.string().trim().min(1),
+		limit: z.coerce.number().int().positive().optional(),
+		offset: z.coerce.number().int().nonnegative().optional(),
+		...optionalTabIdentifierShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--file-path <path>", "File path.");
+		command.option("--limit <n>", "Line limit.");
+		command.option("--offset <line>", "Line offset.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => options,
+});
+
+const issuesFileCommand = createToolCommand({
+	path: ["issues", "file"],
+	description: "Refresh issues for one file.",
+	toolName: "XcodeRefreshCodeIssuesInFile",
+	requiresTab: true,
+	optionsSchema: z.object({
+		filePath: z.string().trim().min(1),
+		...optionalTabIdentifierShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--file-path <path>", "File path.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => options,
+});
+
+const filesUpdateCommand = createToolCommand({
+	path: ["files", "update"],
+	description: "Replace text in a file through Xcode.",
+	toolName: "XcodeUpdate",
+	requiresTab: true,
+	optionsSchema: z.object({
+		filePath: z.string().trim().min(1),
+		newString: z.string(),
+		oldString: z.string(),
+		replaceAll: z.boolean().default(false),
+		...yesAndOptionalTabShape,
+	}),
+	configure: (command) => {
+		command.requiredOption("--file-path <path>", "File path.");
+		command.requiredOption("--old-string <text>", "Text to replace.");
+		command.requiredOption("--new-string <text>", "Replacement text.");
+		command.option("--replace-all", "Replace every match.");
+		command.option("--yes", "Confirm update.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: (options) => {
+		requireYes({
+			condition: true,
+			commandName: "files update",
+			yes: options.yes,
+		});
+		return options;
+	},
+});
+
+const filesWriteCommand = createToolCommand({
+	path: ["files", "write"],
+	description: "Write file content through Xcode.",
+	toolName: "XcodeWrite",
+	requiresTab: true,
+	optionsSchema: z
+		.object({
+			content: z.string().optional(),
+			contentFile: z.string().trim().min(1).optional(),
+			filePath: z.string().trim().min(1),
+			...yesAndOptionalTabShape,
+		})
+		.refine((value) => value.content || value.contentFile, {
+			message: "Expected --content or --content-file.",
+			path: ["content"],
+		}),
+	configure: (command) => {
+		command.requiredOption("--file-path <path>", "File path.");
+		command.option("--content <text>", "Content to write.");
+		command.option("--content-file <path>", "Read content from a file.");
+		command.option("--yes", "Confirm write.");
+		addTabIdentifierOption(command);
+	},
+	buildArguments: async (options) => {
+		requireYes({
+			condition: true,
+			commandName: "files write",
+			yes: options.yes,
+		});
+		return {
+			filePath: options.filePath,
+			content: await resolveWriteContent(options),
+			tabIdentifier: options.tabIdentifier,
+		};
+	},
+});
+
+export const xcodeToolCommandDefinitions = [
+	docsSearchCommand,
+	snippetExecuteCommand,
+	...filteredCommandSpecs.map(createFilteredCommand),
+	...tabOnlyCommandSpecs.map(createTabOnlyCommand),
+	previewRenderCommand,
+	testsRunSomeCommand,
+	filesGlobCommand,
+	filesGrepCommand,
+	filesLsCommand,
+	filesMvCommand,
+	filesMkdirCommand,
+	filesRmCommand,
+	filesReadCommand,
+	issuesFileCommand,
+	filesUpdateCommand,
+	filesWriteCommand,
+];

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const EXIT_SUCCESS = 0;
+export const EXIT_RUNTIME_ERROR = 1;
+export const EXIT_USAGE_ERROR = 2;