xcode-mcli 0.1.0

package/skill/references/compatibility.md

@@ -0,0 +1,91 @@
+# Compatibility
+
+## Objective
+
+`xcode-mcli` can verify its Xcode MCP compatibility by diffing the live discovered MCP surface against a pinned baseline snapshot.
+
+The compatibility contract is the normalized result of:
+
+- `initialize`
+- `tools/list`
+- `prompts/list`
+- `resources/list`
+
+The pinned Apple Xcode 26.3 baseline is:
+
+```text
+skill/references/apple-xcode-26.3.surface.json
+```
+
+That snapshot currently records:
+
+- protocol version `2025-06-18`
+- `20` tools
+- `0` prompts
+- `0` resources
+
+## Commands
+
+Capture the current live surface:
+
+```bash
+xcode-mcli surface snapshot
+```
+
+Write a canonical snapshot file:
+
+```bash
+xcode-mcli surface snapshot --output-file skill/references/apple-xcode-26.3.surface.json
+```
+
+Verify the current Xcode MCP surface against the pinned 26.3 baseline:
+
+```bash
+xcode-mcli surface verify --baseline-file skill/references/apple-xcode-26.3.surface.json
+```
+
+Convenience npm scripts:
+
+```bash
+npm run compat:xcode-mcp:snapshot
+npm run compat:xcode-mcp:pin-26.3
+npm run compat:xcode-mcp:verify
+```
+
+## Verification Behavior
+
+`surface snapshot` normalizes the discovered surface before printing or writing it:
+
+- sorts tools, prompts, and resources by `name`
+- sorts object keys recursively
+- preserves extra server metadata such as `title` and `outputSchema`
+
+`surface verify` compares:
+
+- protocol version
+- tool additions, removals, and changed definitions
+- prompt additions, removals, and changed definitions
+- resource additions, removals, and changed definitions
+
+An exact match exits successfully.
+
+A mismatch exits with a runtime error. In `--json` mode, the error envelope includes structured `error.details` with the categorized diff.
+
+## Upgrade Flow
+
+When a new Xcode release arrives:
+
+1. Run `npm run compat:xcode-mcp:verify`.
+2. If it passes, the pinned baseline still matches the live Xcode MCP contract.
+3. If it fails, inspect the categorized diff.
+4. Confirm whether the change is additive, behavioral, or breaking for the CLI.
+5. Update `xcode-mcli` if the wrapper needs to support the new contract.
+6. Re-pin the baseline with `npm run compat:xcode-mcp:pin-26.3` or a new versioned snapshot path.
+
+For machine-readable inspection:
+
+```bash
+xcode-mcli surface verify \
+  --baseline-file skill/references/apple-xcode-26.3.surface.json \
+  --json
+```

package/skill/references/setup.md

@@ -0,0 +1,120 @@
+# Setup
+
+## Requirements
+
+- macOS
+- Xcode installed
+- `Xcode Tools` enabled in `Settings > Intelligence`
+- Node.js 25+
+
+## Install
+
+From the repo:
+
+```bash
+npm install
+```
+
+Global install:
+
+```bash
+npm install -g xcode-mcli
+```
+
+## First Run
+
+Verify the bridge and initialize the local state root:
+
+```bash
+xcode-mcli setup
+```
+
+If `setup` reports `Failed to call xcrun mcpbridge --help.`, enable `Xcode Tools` in `Settings > Intelligence` and run `xcode-mcli setup` again.
+
+Then confirm Xcode access:
+
+```bash
+xcode-mcli windows list
+```
+
+If exactly one Xcode workspace window is open, many tab-aware commands can resolve it automatically.
+
+To pin the active tab explicitly:
+
+```bash
+xcode-mcli windows use --tab-identifier windowtab1
+```
+
+## Daemon
+
+The daemon auto-starts on the first daemon-backed command.
+
+Explicit lifecycle commands:
+
+```bash
+xcode-mcli daemon start
+xcode-mcli daemon status
+xcode-mcli daemon restart
+xcode-mcli daemon stop
+```
+
+## State Root
+
+The default state root is:
+
+```text
+~/Library/Application Support/xcode-mcli
+```
+
+Files used there:
+
+- `daemon.sock`
+- `daemon.pid`
+- `daemon.log`
+- `state.json`
+
+## Common Commands
+
+```bash
+xcode-mcli windows list
+xcode-mcli files read --tab-identifier windowtab1 --file-path Path/To/File.swift
+xcode-mcli build log --tab-identifier windowtab1
+xcode-mcli project build --tab-identifier windowtab1
+xcode-mcli tests list --tab-identifier windowtab1
+```
+
+## Machine Output
+
+Use `--json` for a stable wrapper envelope:
+
+```bash
+xcode-mcli --json windows list
+```
+
+Use `--verbose` to print the exact Xcode MCP tool name to `stderr` for tool-backed commands:
+
+```bash
+xcode-mcli --json --verbose windows list
+```
+
+`--json`, `--verbose`, and `--tab-identifier <id>` can be passed before the command path or after the specific command.
+
+## Compatibility Check
+
+Verify the pinned Apple Xcode 26.3 MCP surface:
+
+```bash
+npm run compat:xcode-mcp:verify
+```
+
+Capture the current live surface:
+
+```bash
+npm run compat:xcode-mcp:snapshot
+```
+
+Pin a canonical baseline file:
+
+```bash
+npm run compat:xcode-mcp:pin-26.3
+```

package/skill/references/troubleshooting.md

@@ -0,0 +1,160 @@
+# Troubleshooting
+
+## `setup` fails to locate `mcpbridge`
+
+Run:
+
+```bash
+xcode-mcli setup
+```
+
+If it fails with `Failed to locate xcrun mcpbridge.`:
+
+- confirm Xcode is installed
+- confirm `Xcode Tools` is enabled in `Settings > Intelligence`
+- confirm `xcrun` resolves from your shell
+
+If it fails with `Failed to call xcrun mcpbridge --help.`:
+
+- enable `Xcode Tools` in `Settings > Intelligence`
+- run `xcode-mcli setup` again
+
+## `windows list` returns no useful workspace
+
+Make sure Xcode is open with a workspace or project window.
+
+Then run:
+
+```bash
+xcode-mcli windows list
+```
+
+## A tab-aware command fails because no active window is selected
+
+Use one of these paths:
+
+```bash
+xcode-mcli windows list
+xcode-mcli windows use --tab-identifier windowtab1
+```
+
+Or pass the tab directly on the command:
+
+```bash
+xcode-mcli files read --tab-identifier windowtab1 --file-path Path/To/File.swift
+```
+
+## Multiple Xcode windows are open
+
+Pick one explicitly:
+
+```bash
+xcode-mcli windows list
+xcode-mcli windows use --tab-identifier windowtab1
+```
+
+## Xcode permission prompts appear
+
+The first tool-backed command may trigger an Xcode permission prompt for the CLI process.
+
+If you change terminals, shells, or Node installations, macOS may ask again because the calling process identity changed.
+
+## The daemon looks stale
+
+Restart it:
+
+```bash
+xcode-mcli daemon restart
+```
+
+Or stop and start it:
+
+```bash
+xcode-mcli daemon stop
+xcode-mcli daemon start
+```
+
+Inspect status:
+
+```bash
+xcode-mcli daemon status
+```
+
+## JSON output is mixed with diagnostic text
+
+`--json` writes the stable envelope to `stdout`.
+
+For tool-backed commands, `--verbose` writes the tool name to `stderr`.
+
+This keeps `stdout` parseable:
+
+```bash
+xcode-mcli windows list --json --verbose
+```
+
+## Mutating commands fail with a confirmation error
+
+These commands require `--yes`:
+
+- `files rm`
+- `files update`
+- `files write`
+- `files mv --overwrite-existing`
+
+Example:
+
+```bash
+xcode-mcli files write --tab-identifier windowtab1 --file-path Path/To/File.swift --content 'let x = 1' --yes
+```
+
+## `files mkdir` or other mutating commands fail with an Xcode tool error
+
+Some Xcode mutating tools depend on project structure resolution inside the active workspace.
+
+If `files mkdir` reports a message telling you to run `XcodeLS` first, warm the structure with:
+
+```bash
+xcode-mcli files ls --path .
+```
+
+Then retry the mutating command against a path inside an existing project-recognized subtree.
+
+If Xcode returns a group-resolution failure for a path that is not already represented in the project structure, use a disposable path under an existing group such as a known source folder.
+
+## Inspecting daemon state
+
+The default state root is:
+
+```text
+~/Library/Application Support/xcode-mcli
+```
+
+Important files:
+
+- `daemon.sock`
+- `daemon.pid`
+- `daemon.log`
+- `state.json`
+
+## `surface verify` reports a mismatch
+
+Run:
+
+```bash
+npm run compat:xcode-mcp:verify
+```
+
+If it fails, inspect the categorized diff with:
+
+```bash
+xcode-mcli surface verify --baseline-file skill/references/apple-xcode-26.3.surface.json --json
+```
+
+Review whether the live Xcode release changed:
+
+- protocol version
+- tool definitions
+- prompt definitions
+- resource definitions
+
+If the live contract is the one you want to support, re-pin the baseline snapshot after updating the wrapper behavior that depends on it.

package/src/commands/daemon-restart.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { restartDaemon } from "../runtime/daemon-host.ts";
+import { printCommandResult } from "../runtime/output.ts";
+
+export const daemonRestartCommand = defineCommand({
+	path: ["daemon", "restart"],
+	description: "Restart the daemon.",
+	optionsSchema: z.object({}),
+	run: async ({ commandPath, globals }) => {
+		await restartDaemon();
+		printCommandResult({
+			commandPath,
+			globals,
+			text: "Daemon restarted.",
+			data: {
+				running: true,
+			},
+		});
+	},
+});

package/src/commands/daemon-start.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { startDaemon } from "../runtime/daemon-host.ts";
+import { printCommandResult } from "../runtime/output.ts";
+
+export const daemonStartCommand = defineCommand({
+	path: ["daemon", "start"],
+	description: "Start the daemon.",
+	optionsSchema: z.object({}),
+	run: async ({ commandPath, globals }) => {
+		await startDaemon();
+		printCommandResult({
+			commandPath,
+			globals,
+			text: "Daemon started.",
+			data: {
+				running: true,
+			},
+		});
+	},
+});

package/src/commands/daemon-status.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { readDaemonStatus } from "../runtime/daemon-host.ts";
+import { printCommandResult } from "../runtime/output.ts";
+
+export const daemonStatusCommand = defineCommand({
+	path: ["daemon", "status"],
+	description: "Show daemon status.",
+	optionsSchema: z.object({}),
+	run: async ({ commandPath, globals }) => {
+		const status = await readDaemonStatus();
+		printCommandResult({
+			commandPath,
+			globals,
+			text: status.running
+				? `Daemon is running with PID ${status.pid}.`
+				: "Daemon is not running.",
+			data: status.running
+				? {
+					running: true,
+					pid: status.pid,
+				}
+				: {
+					running: false,
+				},
+		});
+	},
+});

package/src/commands/daemon-stop.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { stopDaemon } from "../runtime/daemon-host.ts";
+import { printCommandResult } from "../runtime/output.ts";
+
+export const daemonStopCommand = defineCommand({
+	path: ["daemon", "stop"],
+	description: "Stop the daemon.",
+	optionsSchema: z.object({}),
+	run: async ({ commandPath, globals }) => {
+		await stopDaemon();
+		printCommandResult({
+			commandPath,
+			globals,
+			text: "Daemon stopped.",
+			data: {
+				running: false,
+			},
+		});
+	},
+});

package/src/commands/index.ts

@@ -0,0 +1,26 @@
+import type { CommandDefinition } from "../core/contracts.ts";
+import { daemonRestartCommand } from "./daemon-restart.ts";
+import { daemonStartCommand } from "./daemon-start.ts";
+import { daemonStatusCommand } from "./daemon-status.ts";
+import { daemonStopCommand } from "./daemon-stop.ts";
+import { projectBuildCommand } from "./project-build.ts";
+import { setupCommand } from "./setup.ts";
+import { surfaceSnapshotCommand } from "./surface-snapshot.ts";
+import { surfaceVerifyCommand } from "./surface-verify.ts";
+import { windowsListCommand } from "./windows-list.ts";
+import { windowsUseCommand } from "./windows-use.ts";
+import { xcodeToolCommandDefinitions } from "./xcode-tool-commands.ts";
+
+export const commandDefinitions: CommandDefinition[] = [
+	setupCommand,
+	daemonStartCommand,
+	daemonRestartCommand,
+	daemonStatusCommand,
+	daemonStopCommand,
+	projectBuildCommand,
+	surfaceSnapshotCommand,
+	surfaceVerifyCommand,
+	windowsListCommand,
+	windowsUseCommand,
+	...xcodeToolCommandDefinitions,
+];

package/src/commands/project-build.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { callDaemonTool } from "../runtime/daemon-host.ts";
+import {
+	printCommandResult,
+	printVerboseTool,
+	toCommandData,
+} from "../runtime/output.ts";
+import { resolveTabIdentifier } from "../runtime/tab-resolver.ts";
+
+const projectBuildOptionsSchema = z.object({
+	tabIdentifier: z.string().trim().min(1).optional(),
+});
+const projectBuildResultSchema = z.object({
+	structuredContent: z.unknown().optional(),
+	text: z.string().default(""),
+});
+
+export const projectBuildCommand = defineCommand({
+	path: ["project", "build"],
+	description: "Build the active Xcode project.",
+	toolName: "BuildProject",
+	configure: (command) => {
+		command.option("--tab-identifier <id>", "Active Xcode window tab identifier.");
+	},
+	optionsSchema: projectBuildOptionsSchema,
+	run: async ({ commandPath, globals, options }) => {
+		const tabIdentifier = await resolveTabIdentifier({
+			explicitTabIdentifier: options.tabIdentifier,
+		});
+		printVerboseTool(globals, "BuildProject");
+		const result = projectBuildResultSchema.parse(
+			await callDaemonTool({
+				name: "BuildProject",
+				arguments: {
+					tabIdentifier,
+				},
+			}),
+		);
+		printCommandResult({
+			commandPath,
+			globals,
+			text: result.text.trimEnd(),
+			data: toCommandData(result),
+			tabIdentifier,
+			tool: "BuildProject",
+		});
+	},
+});

package/src/commands/setup.ts

@@ -0,0 +1,26 @@
+import { mkdir } from "node:fs/promises";
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { resolveStateRoot } from "../runtime/env.ts";
+import { printCommandResult } from "../runtime/output.ts";
+import { findMcpbridgePath, verifyMcpbridgeHelp } from "../runtime/xcrun.ts";
+
+export const setupCommand = defineCommand({
+	path: ["setup"],
+	description: "Prepare xcode-mcli for use with Xcode MCP.",
+	optionsSchema: z.object({}),
+	run: async ({ commandPath, globals }) => {
+		await mkdir(resolveStateRoot(), { recursive: true });
+		await findMcpbridgePath();
+		await verifyMcpbridgeHelp();
+		printCommandResult({
+			commandPath,
+			globals,
+			text: "xcode-mcli setup complete.",
+			data: {
+				message: "xcode-mcli setup complete.",
+			},
+		});
+	},
+});

package/src/commands/surface-snapshot.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { printCommandResult } from "../runtime/output.ts";
+import {
+	captureXcodeMcpSurfaceSnapshot,
+	writeXcodeMcpSurfaceSnapshotFile,
+} from "../runtime/xcode-surface.ts";
+
+export const surfaceSnapshotCommand = defineCommand({
+	path: ["surface", "snapshot"],
+	description: "Capture the live Xcode MCP surface.",
+	optionsSchema: z.object({
+		outputFile: z.string().trim().min(1).optional(),
+	}),
+	configure: (command) => {
+		command.option("--output-file <path>", "Write the canonical snapshot to a file.");
+	},
+	run: async ({ commandPath, globals, options, projectDir }) => {
+		const snapshot = await captureXcodeMcpSurfaceSnapshot();
+		if (options.outputFile) {
+			const outputPath = await writeXcodeMcpSurfaceSnapshotFile({
+				projectDir,
+				filePath: options.outputFile,
+				snapshot,
+			});
+			printCommandResult({
+				commandPath,
+				globals,
+				text: `Wrote Xcode MCP surface snapshot to ${outputPath}`,
+				data: {
+					outputFile: outputPath,
+					snapshot,
+				},
+			});
+			return;
+		}
+		printCommandResult({
+			commandPath,
+			globals,
+			text: JSON.stringify(snapshot, null, 2),
+			data: snapshot,
+		});
+	},
+});

package/src/commands/surface-verify.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+import { defineCommand } from "../core/command-definition.ts";
+import { runtimeError } from "../core/errors.ts";
+import { printCommandResult } from "../runtime/output.ts";
+import {
+	captureXcodeMcpSurfaceSnapshot,
+	diffXcodeMcpSurfaceSnapshots,
+	readXcodeMcpSurfaceSnapshotFile,
+	xcodeMcpSurfaceDiffHasChanges,
+} from "../runtime/xcode-surface.ts";
+
+export const surfaceVerifyCommand = defineCommand({
+	path: ["surface", "verify"],
+	description: "Compare the live Xcode MCP surface against a baseline snapshot.",
+	optionsSchema: z.object({
+		baselineFile: z.string().trim().min(1),
+	}),
+	configure: (command) => {
+		command.requiredOption(
+			"--baseline-file <path>",
+			"Path to a canonical Xcode MCP surface snapshot.",
+		);
+	},
+	run: async ({ commandPath, globals, options, projectDir }) => {
+		const baseline = await readXcodeMcpSurfaceSnapshotFile(projectDir, options.baselineFile);
+		const live = await captureXcodeMcpSurfaceSnapshot();
+		const diff = diffXcodeMcpSurfaceSnapshots({
+			baseline,
+			live,
+		});
+		if (xcodeMcpSurfaceDiffHasChanges(diff)) {
+			throw runtimeError("Xcode MCP surface does not match the baseline snapshot.", diff);
+		}
+		printCommandResult({
+			commandPath,
+			globals,
+			text: "Xcode MCP surface matches the baseline snapshot.",
+			data: {
+				baselineFile: options.baselineFile,
+				compatible: true,
+				diff,
+			},
+		});
+	},
+});