xcode-mcli 0.1.0

package/src/core/command-definition.ts

@@ -0,0 +1,131 @@
+import { Command } from "commander";
+import { z } from "zod";
+import type { output, ZodType } from "zod";
+
+import type { CommandDefinition } from "./contracts.ts";
+import { attachCommandMetadata, runtimeError, usageError } from "./errors.ts";
+
+function commandPathToString(path: readonly string[]): string {
+	return path.join(" ");
+}
+
+function formatInvalidOptionsMessage(commandPath: readonly string[]): string {
+	return `Invalid options for command: ${commandPathToString(commandPath)}`;
+}
+
+function parseOptions<TSchema extends ZodType>(
+	commandPath: readonly string[],
+	optionsSchema: TSchema,
+	value: unknown,
+): output<TSchema> {
+	const result = optionsSchema.safeParse(value);
+	if (result.success) {
+		return result.data;
+	}
+	throw usageError(formatInvalidOptionsMessage(commandPath));
+}
+
+function readCommand(actionArgs: unknown[]): Command {
+	const candidate = actionArgs[actionArgs.length - 1];
+	if (candidate instanceof Command) {
+		return candidate;
+	}
+	throw runtimeError("Failed to read command context.");
+}
+
+const globalOptionsSchema = z.object({
+	json: z.boolean().default(false),
+	verbose: z.boolean().default(false),
+});
+
+function readGlobalOptions(command: Command) {
+	return globalOptionsSchema.parse(command.optsWithGlobals());
+}
+
+function addSharedGlobalOptions(command: Command): void {
+	command.option("--json", "Print command results as JSON.");
+	command.option("--verbose", "Print extra execution details.");
+}
+
+function registerCommandAction<TSchema extends ZodType>(input: {
+	command: Command;
+	definition: CommandDefinition<TSchema>;
+	projectDir: string;
+}): void {
+	input.command.action(async (...actionArgs: unknown[]) => {
+		const command = readCommand(actionArgs);
+		const parsedOptions = parseOptions(
+			input.definition.path,
+			input.definition.optionsSchema,
+			command.optsWithGlobals(),
+		);
+		try {
+			await input.definition.run({
+				commandPath: input.definition.path,
+				globals: readGlobalOptions(command),
+				projectDir: input.projectDir,
+				options: parsedOptions,
+			});
+		} catch (error) {
+			throw attachCommandMetadata(error, {
+				commandName: commandPathToString(input.definition.path),
+				toolName: input.definition.toolName,
+			});
+		}
+	});
+}
+
+function findOrCreateGroupCommand(program: Command, groupName: string): Command {
+	const existingGroup = program.commands.find((candidate) => candidate.name() === groupName);
+	if (existingGroup) {
+		return existingGroup;
+	}
+	return program.command(groupName).description(`${groupName} commands.`).exitOverride();
+}
+
+function createLeafCommand(parent: Command, input: {
+	name: string;
+	description: string;
+}): Command {
+	return parent.command(input.name).description(input.description).exitOverride();
+}
+
+function createRegisteredCommand(
+	program: Command,
+	definition: CommandDefinition<ZodType>,
+): Command {
+	const path = [...definition.path];
+	const leaf = path.pop();
+	if (!leaf) {
+		throw runtimeError("Command path cannot be empty.");
+	}
+	let parent = program;
+	for (const groupName of path) {
+		parent = findOrCreateGroupCommand(parent, groupName);
+	}
+	return createLeafCommand(parent, {
+		name: leaf,
+		description: definition.description,
+	});
+}
+
+export function registerCommand<TSchema extends ZodType>(input: {
+	program: Command;
+	definition: CommandDefinition<TSchema>;
+	projectDir: string;
+}): void {
+	const command = createRegisteredCommand(input.program, input.definition);
+	addSharedGlobalOptions(command);
+	input.definition.configure?.(command);
+	registerCommandAction({
+		command,
+		definition: input.definition,
+		projectDir: input.projectDir,
+	});
+}
+
+export function defineCommand<TSchema extends ZodType>(
+	definition: CommandDefinition<TSchema>,
+): CommandDefinition<TSchema> {
+	return definition;
+}

package/src/core/command-dispatch.ts

@@ -0,0 +1,97 @@
+import { Command, CommanderError } from "commander";
+
+import { commandDefinitions } from "../commands/index.ts";
+import { registerCommand } from "./command-definition.ts";
+import { usageError } from "./errors.ts";
+import { readPackageVersion } from "./package-version.ts";
+
+function hasJsonFlag(argv: string[]): boolean {
+	return argv.includes("--json");
+}
+
+async function createProgram(projectDir: string, argv: string[]): Promise<Command> {
+	const packageVersion = await readPackageVersion();
+	const jsonMode = hasJsonFlag(argv);
+	const program = new Command();
+	program
+		.name("xcode-mcli")
+		.description("Stable macOS CLI wrapper for Apple's Xcode MCP bridge.")
+		.helpOption("--help", "Display help for command.")
+		.version(packageVersion, "--version", "Show package version.")
+		.option("--json", "Print command results as JSON.")
+		.option("--verbose", "Print extra execution details.")
+		.option("--tab-identifier <id>", "Active Xcode window tab identifier.")
+		.configureOutput({
+			writeErr: (value) => {
+				if (jsonMode) {
+					return;
+				}
+				process.stderr.write(value);
+			},
+		})
+		.showSuggestionAfterError()
+		.exitOverride();
+	for (const definition of commandDefinitions) {
+		registerCommand({
+			program,
+			definition,
+			projectDir,
+		});
+	}
+	return program;
+}
+
+function isCommanderError(error: unknown): error is CommanderError {
+	return error instanceof CommanderError;
+}
+
+function isDisplayedHelpError(error: CommanderError): boolean {
+	return error.code === "commander.helpDisplayed" || error.message === "(outputHelp)";
+}
+
+function isDisplayedVersionError(error: CommanderError): boolean {
+	return error.code === "commander.version";
+}
+
+function isDisplayedOutputError(error: CommanderError): boolean {
+	return isDisplayedHelpError(error) || isDisplayedVersionError(error);
+}
+
+function toUsageMessage(error: CommanderError): string {
+	const message = error.message.trim();
+	if (message) {
+		return message;
+	}
+	return "Invalid command usage.";
+}
+
+function handleParseError(error: unknown): void {
+	if (!isCommanderError(error)) {
+		throw error;
+	}
+	if (isDisplayedOutputError(error)) {
+		return;
+	}
+	throw usageError(toUsageMessage(error));
+}
+
+async function parseProgram(program: Command, argv: string[]): Promise<void> {
+	await program.parseAsync(argv, { from: "user" });
+}
+
+export async function runXcodeMcli(argv: string[], projectDir: string): Promise<void> {
+	const program = await createProgram(projectDir, argv);
+	if (argv.length === 0) {
+		program.outputHelp();
+		return;
+	}
+	try {
+		await parseProgram(program, argv);
+	} catch (error) {
+		handleParseError(error);
+	}
+}
+
+export async function runXcodeMcliFromProcess(): Promise<void> {
+	await runXcodeMcli(process.argv.slice(2), process.cwd());
+}

package/src/core/contracts.ts

@@ -0,0 +1,25 @@
+import type { Command } from "commander";
+import type { output, ZodType } from "zod";
+
+export type GlobalOptions = {
+	json: boolean;
+	verbose: boolean;
+};
+
+export type CommandRunContext<TOptions> = {
+	commandPath: CommandPath;
+	globals: GlobalOptions;
+	projectDir: string;
+	options: TOptions;
+};
+
+export type CommandPath = readonly [string, ...string[]];
+
+export type CommandDefinition<TSchema extends ZodType = ZodType> = {
+	path: CommandPath;
+	description: string;
+	configure?: (command: Command) => void;
+	optionsSchema: TSchema;
+	toolName?: string;
+	run: (context: CommandRunContext<output<TSchema>>) => Promise<void>;
+};

package/src/core/errors.ts

@@ -0,0 +1,52 @@
+import { EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../constants.ts";
+
+export class TemplateError extends Error {
+	public commandName?: string;
+	public details?: unknown;
+	public readonly exitCode: number;
+	public toolName?: string;
+
+	constructor(message: string, exitCode: number) {
+		super(message);
+		this.name = "TemplateError";
+		this.exitCode = exitCode;
+	}
+}
+
+export function usageError(message: string): TemplateError {
+	const error = new TemplateError(message, EXIT_USAGE_ERROR);
+	error.name = "UsageError";
+	return error;
+}
+
+export function runtimeError(message: string, details?: unknown): TemplateError {
+	const error = new TemplateError(message, EXIT_RUNTIME_ERROR);
+	error.name = "RuntimeError";
+	error.details = details;
+	return error;
+}
+
+export function toTemplateError(error: unknown): TemplateError {
+	if (error instanceof TemplateError) {
+		return error;
+	}
+	if (error instanceof Error) {
+		return runtimeError(error.message);
+	}
+	return runtimeError(String(error));
+}
+
+export function attachCommandMetadata(
+	error: unknown,
+	input: {
+		commandName: string;
+		toolName?: string;
+	},
+): TemplateError {
+	const wrapped = toTemplateError(error);
+	wrapped.commandName = input.commandName;
+	if (input.toolName) {
+		wrapped.toolName = input.toolName;
+	}
+	return wrapped;
+}

package/src/core/package-version.ts

@@ -0,0 +1,30 @@
+import * as fs from "node:fs/promises";
+
+import { runtimeError } from "./errors.ts";
+
+const PACKAGE_JSON_PATH = new URL("../../package.json", import.meta.url);
+
+const PACKAGE_VERSION_ERROR_MESSAGE =
+	"Failed to read package version. Set a valid version in package.json.";
+
+export async function readPackageVersion(): Promise<string> {
+	let raw: string;
+	try {
+		raw = await fs.readFile(PACKAGE_JSON_PATH, "utf8");
+	} catch {
+		throw runtimeError(PACKAGE_VERSION_ERROR_MESSAGE);
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw runtimeError(PACKAGE_VERSION_ERROR_MESSAGE);
+	}
+	if (typeof parsed === "object" && parsed && !Array.isArray(parsed)) {
+		const version = Reflect.get(parsed, "version");
+		if (typeof version === "string" && version.trim()) {
+			return version.trim();
+		}
+	}
+	throw runtimeError(PACKAGE_VERSION_ERROR_MESSAGE);
+}

package/src/runtime/daemon-host-entry.ts

@@ -0,0 +1,8 @@
+import { runDaemonHost } from "./daemon-host.ts";
+
+try {
+	await runDaemonHost();
+} catch (error) {
+	console.error(error);
+	process.exit(1);
+}