xcode-mcli 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# xcode-mcli
+
+`xcode-mcli` is a macOS CLI for Apple's Xcode MCP bridge exposed through `xcrun mcpbridge`.
+
+It gives you a daemon-backed terminal interface to the current Xcode MCP tool surface without registering Xcode MCP inside Codex or another MCP client.
+
+## Requirements
+
+- macOS
+- Xcode with `Xcode Tools` enabled in `Settings > Intelligence`
+- Node.js 25+
+
+## Install
+
+```bash
+npm install
+```
+
+For a global install:
+
+```bash
+npm install -g xcode-mcli
+```
+
+## Quick Start
+
+```bash
+xcode-mcli setup
+xcode-mcli windows list
+xcode-mcli windows use --tab-identifier windowtab1
+xcode-mcli files read --tab-identifier windowtab1 --file-path Path/To/File.swift
+xcode-mcli project build --tab-identifier windowtab1
+```
+
+The daemon auto-starts on the first daemon-backed command.
+
+## Output Modes
+
+- Default output is concise text.
+- `--json` prints a stable wrapper envelope.
+- `--verbose` prints the exact Xcode MCP tool name to `stderr` for tool-backed commands.
+
+Example:
+
+```bash
+xcode-mcli --json --verbose windows list
+```
+
+`--json`, `--verbose`, and `--tab-identifier <id>` can be passed either before the command path or after the specific command.
+
+## Command Groups
+
+- `setup`
+- `daemon`
+- `windows`
+- `project`
+- `docs`
+- `snippet`
+- `build`
+- `issues`
+- `tests`
+- `preview`
+- `files`
+
+## Docs
+
+- [docs/api-reference.md](docs/api-reference.md)
+- [docs/compatibility.md](docs/compatibility.md)
+- [docs/setup.md](docs/setup.md)
+- [docs/troubleshooting.md](docs/troubleshooting.md)
+
+## Compatibility
+
+Pin and verify the Xcode MCP surface with:
+
+```bash
+npm run compat:xcode-mcp:verify
+```
+
+The pinned Apple Xcode 26.3 baseline lives at:
+
+```text
+skill/references/apple-xcode-26.3.surface.json
+```
+
+## Development
+
+```bash
+npm test
+make lint
+make verify
+```

package/bin/xcode-mcli.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { runXcodeMcliFromProcess } from "../src/core/command-dispatch.ts";
+import { toTemplateError } from "../src/core/errors.ts";
+import { printCommandError } from "../src/runtime/output.ts";
+
+try {
+	await runXcodeMcliFromProcess();
+} catch (error) {
+	const wrapped = toTemplateError(error);
+	printCommandError({
+		argv: process.argv.slice(2),
+		error: wrapped,
+	});
+	process.exit(wrapped.exitCode);
+}

package/config/mcporter.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
+  "mcpServers": {
+    "xcode": {
+      "description": "Apple Xcode MCP via xcrun mcpbridge",
+      "command": "xcrun",
+      "args": ["mcpbridge"],
+      "lifecycle": "keep-alive"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "xcode-mcli",
+	"version": "0.1.0",
+	"description": "Stable macOS CLI wrapper for Apple's Xcode MCP bridge.",
+	"type": "module",
+	"private": false,
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pyronaur/xcode-mcli.git"
+	},
+	"homepage": "https://github.com/pyronaur/xcode-mcli#readme",
+	"bugs": {
+		"url": "https://github.com/pyronaur/xcode-mcli/issues"
+	},
+	"files": [
+		"bin",
+		"config",
+		"skill",
+		"src"
+	],
+	"bin": {
+		"xcode-mcli": "./bin/xcode-mcli.ts"
+	},
+	"engines": {
+		"node": ">=25"
+	},
+	"scripts": {
+		"compat:xcode-mcp:pin-26.3": "node ./bin/xcode-mcli.ts surface snapshot --output-file skill/references/apple-xcode-26.3.surface.json",
+		"compat:xcode-mcp:snapshot": "node ./bin/xcode-mcli.ts surface snapshot",
+		"compat:xcode-mcp:verify": "node ./bin/xcode-mcli.ts surface verify --baseline-file skill/references/apple-xcode-26.3.surface.json",
+		"lint": "npm run lint:dprint:fix && npm run lint:oxlint:fix && npm run typecheck && npm run jscpd && npm run knip",
+		"lint-dry": "npm run lint:dprint && npm run lint:oxlint && npm run typecheck && npm run jscpd && npm run knip",
+		"lint:dprint": "dprint check",
+		"lint:oxlint": "oxlint --type-aware --tsconfig tsconfig.json .",
+		"lint:dprint:fix": "dprint fmt",
+		"lint:oxlint:fix": "oxlint --type-aware --tsconfig tsconfig.json --fix .",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"jscpd": "jscpd --config .jscpd.json",
+		"knip": "knip",
+		"test": "vitest run --maxWorkers 1 --fileParallelism false"
+	},
+	"dependencies": {
+		"commander": "^14.0.1",
+		"zod": "^4.1.8"
+	},
+	"devDependencies": {
+		"@types/node": "^24.5.2",
+		"dprint": "^0.52.0",
+		"jscpd": "^4.0.8",
+		"knip": "^5.85.0",
+		"oxlint": "^1.50.0",
+		"oxlint-plugin-inhuman": "^0.1.7",
+		"oxlint-tsgolint": "^0.15.0",
+		"typescript": "^5",
+		"vitest": "^3.2.4"
+	}
+}

package/skill/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: xcode
+description: Drive Apple Xcode through the local `xcode-mcli` CLI instead of attaching the Xcode MCP server. Use when Codex needs Xcode MCP-equivalent capabilities from the terminal, including window discovery, tab selection, project builds, documentation search, test listing or execution, preview rendering, snippet execution, issue inspection, file reads or mutations, or compatibility verification against pinned Xcode MCP snapshots.
+---
+
+# Xcode
+
+## Overview
+
+Use `xcode-mcli` as the terminal wrapper for Apple's Xcode MCP bridge.
+
+Prefer this skill when the task needs Xcode access but the Xcode MCP server should stay detached from the agent context.
+
+## Locate The CLI
+
+Use one of these paths:
+
+- Global install: `xcode-mcli`
+- Repo checkout: `node ./bin/xcode-mcli.ts`
+
+When working from the repo checkout, use the `xcode-mcli` repository root as the default project root unless the user says otherwise.
+
+## Start Here
+
+1. Run `xcode-mcli setup`.
+2. If the first live Xcode call triggers a macOS approval dialog, wait for the user to click `Allow`.
+3. Run `xcode-mcli windows list`.
+4. If needed, pin the active tab with `xcode-mcli windows use --tab-identifier <id>`.
+5. Run the tool-backed command you need.
+
+## Working Rules
+
+- Prefer `--json` when the result will be parsed or inspected programmatically.
+- Use `--verbose` when you need the exact Xcode MCP tool name printed to `stderr`.
+- Pass `--tab-identifier <id>` explicitly when multiple Xcode windows are open.
+- Treat `files rm`, `files update`, `files write`, and `files mv --overwrite-existing` as destructive because they require `--yes`.
+- Assume test execution uses the active Xcode destination from the current Xcode window.
+- If a live Xcode command appears stalled, account for the user possibly needing to approve Xcode access before treating it as a failure.
+
+## Read The Right Reference
+
+- Read `references/setup.md` for install, first-run, daemon, and state-root behavior.
+- Read `references/api-reference.md` for every CLI command, flag, JSON contract, and CLI-to-tool mapping.
+- Read `references/troubleshooting.md` for approval prompts, tab resolution issues, daemon recovery, mutating command caveats, and test-destination behavior.
+- Read `references/compatibility.md` when validating a new Xcode release or checking CLI parity against the pinned MCP baseline.
+- Read `references/apple-xcode-26.3.surface.json` when you need the exact verbatim Xcode MCP tool descriptions, `inputSchema`, `outputSchema`, or top-level surface shape copied from live Xcode 26.3.
+
+## Searching The Verbatim Surface Snapshot
+
+The snapshot file is large. Search it by tool name first.
+
+Useful patterns:
+
+- `BuildProject`
+- `DocumentationSearch`
+- `RunSomeTests`
+- `XcodeRead`
+- `XcodeWrite`
+- `XcodeListWindows`
+
+When exact parameter or output details matter, trust the JSON snapshot over memory.
+
+## Compatibility Workflow
+
+When Xcode changes:
+
+1. Run `npm run compat:xcode-mcp:verify` from the `xcode-mcli` repository root.
+2. If it fails, read `references/compatibility.md`.
+3. Inspect the exact live-vs-baseline diff with `xcode-mcli surface verify --baseline-file skill/references/apple-xcode-26.3.surface.json --json`.
+4. Use `references/apple-xcode-26.3.surface.json` as the pinned baseline reference.

package/skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Xcode CLI"
+  short_description: "Use xcode-mcli for Xcode MCP parity"
+  default_prompt: "Use $xcode to drive Apple Xcode through the local xcode-mcli CLI instead of attaching the Xcode MCP server."

package/skill/references/api-reference.md

@@ -0,0 +1,409 @@
+# API Reference
+
+## Overview
+
+`xcode-mcli` exposes Xcode MCP through command groups that map to the current Xcode MCP tool surface.
+
+Text mode is the default.
+
+`--json` returns a stable wrapper envelope:
+
+```json
+{
+  "ok": true,
+  "command": "windows list",
+  "tool": "XcodeListWindows",
+  "data": {
+    "windows": []
+  }
+}
+```
+
+Failure shape:
+
+```json
+{
+  "ok": false,
+  "command": "files read",
+  "tool": "XcodeRead",
+  "error": {
+    "kind": "runtime",
+    "message": "...",
+    "details": {}
+  }
+}
+```
+
+For tool-backed commands, `--verbose` prints `Xcode MCP tool: <ToolName>` to `stderr`.
+
+## Shared Flags
+
+- `--json`
+  Prints the stable JSON wrapper envelope.
+- `--verbose`
+  Prints the exact Xcode MCP tool name to `stderr` for tool-backed commands.
+- `--tab-identifier <id>`
+  Provides the active Xcode tab identifier for tab-aware commands.
+
+Shared flags can be passed before the command path or after the specific command.
+
+## Setup
+
+### `xcode-mcli setup`
+
+Prepares the local state root and verifies `xcrun mcpbridge`.
+
+Flags:
+
+- `--json`
+- `--verbose`
+
+## Surface
+
+### `xcode-mcli surface snapshot [--output-file <path>]`
+
+Discovers the live Xcode MCP surface through `initialize`, `tools/list`, `prompts/list`, and `resources/list`.
+
+Flags:
+
+- `--output-file <path>` optional
+- `--json`
+- `--verbose`
+
+Without `--output-file`, text mode prints the canonical snapshot JSON.
+
+With `--output-file`, the command writes the normalized snapshot to disk and prints the resolved path.
+
+### `xcode-mcli surface verify --baseline-file <path>`
+
+Compares the live discovered Xcode MCP surface against a baseline snapshot file.
+
+Flags:
+
+- `--baseline-file <path>` required
+- `--json`
+- `--verbose`
+
+Success data includes:
+
+- `baselineFile`
+- `compatible`
+- `diff`
+
+Failure JSON includes categorized diff details in `error.details`.
+
+## Daemon
+
+### `xcode-mcli daemon start`
+
+Starts the daemon.
+
+### `xcode-mcli daemon status`
+
+Shows whether the daemon is running and prints its PID when available.
+
+### `xcode-mcli daemon stop`
+
+Stops the daemon.
+
+### `xcode-mcli daemon restart`
+
+Restarts the daemon.
+
+Daemon commands support:
+
+- `--json`
+- `--verbose`
+
+## Windows
+
+### `xcode-mcli windows list`
+
+Calls `XcodeListWindows`.
+
+Flags:
+
+- `--json`
+- `--verbose`
+
+### `xcode-mcli windows use --tab-identifier <id>`
+
+Stores the active tab identifier in daemon state.
+
+Flags:
+
+- `--tab-identifier <id>` required
+- `--json`
+- `--verbose`
+
+## Project
+
+### `xcode-mcli project build`
+
+Calls `BuildProject`.
+
+Flags:
+
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+If `--tab-identifier` is omitted, the CLI resolves it from the cached active tab or a single open Xcode window.
+
+## Docs
+
+### `xcode-mcli docs search --query <text> [--framework <name> ...]`
+
+Calls `DocumentationSearch`.
+
+Flags:
+
+- `--query <text>` required
+- `--framework <name>` repeatable
+- `--tab-identifier <id>` optional and ignored by the v1 resolver
+- `--json`
+- `--verbose`
+
+## Snippet
+
+### `xcode-mcli snippet execute --code-snippet <swift> --source-file-path <path> [--timeout <seconds>] [--tab-identifier <id>]`
+
+Calls `ExecuteSnippet`.
+
+Flags:
+
+- `--code-snippet <swift>` required
+- `--source-file-path <path>` required
+- `--timeout <seconds>` optional
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+## Build
+
+### `xcode-mcli build log [--glob <glob>] [--pattern <regex>] [--severity <level>] [--tab-identifier <id>]`
+
+Calls `GetBuildLog`.
+
+Flags:
+
+- `--glob <glob>` optional
+- `--pattern <regex>` optional
+- `--severity <level>` optional
+  Allowed values: `error`, `warning`, `remark`
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+## Issues
+
+### `xcode-mcli issues list [--glob <glob>] [--pattern <regex>] [--severity <level>] [--tab-identifier <id>]`
+
+Calls `XcodeListNavigatorIssues`.
+
+Flags:
+
+- `--glob <glob>` optional
+- `--pattern <regex>` optional
+- `--severity <level>` optional
+  Allowed values: `error`, `warning`, `remark`
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli issues file --file-path <path> [--tab-identifier <id>]`
+
+Calls `XcodeRefreshCodeIssuesInFile`.
+
+Flags:
+
+- `--file-path <path>` required
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+## Tests
+
+### `xcode-mcli tests list [--tab-identifier <id>]`
+
+Calls `GetTestList`.
+
+Flags:
+
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli tests run-all [--tab-identifier <id>]`
+
+Calls `RunAllTests`.
+
+Flags:
+
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli tests run-some --test <key=value> --test <key=value> [--tab-identifier <id>]`
+
+Calls `RunSomeTests`.
+
+Each selected test needs both fields:
+
+- `targetName=<target>`
+- `testIdentifier=<identifier>`
+
+Flags:
+
+- `--test <key=value>` repeatable
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+## Preview
+
+### `xcode-mcli preview render --source-file-path <path> [--preview-definition-index-in-file <n>] [--timeout <seconds>] [--tab-identifier <id>]`
+
+Calls `RenderPreview`.
+
+Flags:
+
+- `--source-file-path <path>` required
+- `--preview-definition-index-in-file <n>` optional
+- `--timeout <seconds>` optional
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+## Files
+
+### `xcode-mcli files glob [--path <path>] [--pattern <glob>] [--tab-identifier <id>]`
+
+Calls `XcodeGlob`.
+
+Flags:
+
+- `--path <path>` optional
+- `--pattern <glob>` optional
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli files grep --pattern <regex> [--glob <glob>] [--head-limit <n>] [--ignore-case] [--lines-after <n>] [--lines-before <n>] [--lines-context <n>] [--multiline] [--output-mode <mode>] [--path <path>] [--show-line-numbers] [--type <type>] [--tab-identifier <id>]`
+
+Calls `XcodeGrep`.
+
+Flags:
+
+- `--pattern <regex>` required
+- `--glob <glob>` optional
+- `--head-limit <n>` optional
+- `--ignore-case` optional
+- `--lines-after <n>` optional
+- `--lines-before <n>` optional
+- `--lines-context <n>` optional
+- `--multiline` optional
+- `--output-mode <mode>` optional
+  Allowed values: `content`, `files_with_matches`, `count`
+- `--path <path>` optional
+- `--show-line-numbers` optional
+- `--type <type>` optional
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli files ls --path <path> [--ignore <pattern> ...] [--recursive] [--tab-identifier <id>]`
+
+Calls `XcodeLS`.
+
+Flags:
+
+- `--path <path>` required
+- `--ignore <pattern>` repeatable
+- `--recursive` optional
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli files mv --source-path <path> --destination-path <path> [--operation <operation>] [--overwrite-existing] [--yes] [--tab-identifier <id>]`
+
+Calls `XcodeMV`.
+
+Flags:
+
+- `--source-path <path>` required
+- `--destination-path <path>` required
+- `--operation <operation>` optional
+- `--overwrite-existing` optional
+- `--yes` required when `--overwrite-existing` is set
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli files mkdir --directory-path <path> [--tab-identifier <id>]`
+
+Calls `XcodeMakeDir`.
+
+Flags:
+
+- `--directory-path <path>` required
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli files rm --path <path> [--delete-files] [--recursive] --yes [--tab-identifier <id>]`
+
+Calls `XcodeRM`.
+
+Flags:
+
+- `--path <path>` required
+- `--delete-files` optional
+- `--recursive` optional
+- `--yes` required
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli files read --file-path <path> [--offset <line>] [--limit <n>] [--tab-identifier <id>]`
+
+Calls `XcodeRead`.
+
+Flags:
+
+- `--file-path <path>` required
+- `--offset <line>` optional
+- `--limit <n>` optional
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli files update --file-path <path> --old-string <text> --new-string <text> [--replace-all] --yes [--tab-identifier <id>]`
+
+Calls `XcodeUpdate`.
+
+Flags:
+
+- `--file-path <path>` required
+- `--old-string <text>` required
+- `--new-string <text>` required
+- `--replace-all` optional
+- `--yes` required
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`
+
+### `xcode-mcli files write --file-path <path> (--content <text> | --content-file <path>) --yes [--tab-identifier <id>]`
+
+Calls `XcodeWrite`.
+
+Flags:
+
+- `--file-path <path>` required
+- `--content <text>` optional
+- `--content-file <path>` optional
+- one of `--content` or `--content-file` is required
+- `--yes` required
+- `--tab-identifier <id>` optional
+- `--json`
+- `--verbose`