dd-sdk-ios:xcode-file-management

# dd-sdk-ios Xcode File Management

## Overview

The dd-sdk-ios project is both an SPM package **and** an Xcode workspace with `.pbxproj` files. SPM builds discover files automatically, but **Xcode does not** — it requires explicit registration in `.pbxproj`. The Xcode MCP server (available from Xcode 26.3+) handles this automatically. Always use it.

## Prerequisites

The Xcode MCP server requires **Xcode 26.3+** and must be enabled in Claude Code settings. Verify it's active by checking that `XcodeListWindows` is available. If not, stop and ask the user to enable the Xcode MCP server before proceeding with file operations.

## The Rule

**Never use `Write`, `Bash mv/mkdir/rm`, or `Edit` for file creation, deletion, or movement in this project.**

Use Xcode MCP tools instead — they update the filesystem AND the `.pbxproj` in one atomic operation.

## Target Membership

Target membership is **implicit** — Xcode MCP infers the target from the navigator path where the file is placed. A file added under `DatadogLogs/` is automatically assigned to the `DatadogLogs` target. No explicit target specification is needed.

## Quick Reference

| Operation | Use This Tool | Never Use |
|-----------|--------------|-----------|
| Create file | `XcodeWrite` | `Write`, `Bash touch/cat` |
| Delete file | `XcodeRM` | `Bash rm` |
| Move / rename | `XcodeMV` | `Bash mv` |
| Create directory/group | `XcodeMakeDir` | `Bash mkdir` |
| Read file | `XcodeRead` | (either is fine) |
| Search files | `XcodeGlob`, `XcodeGrep` | (either is fine) |

## Common Rationalizations — All Wrong

| Excuse | Reality |
|--------|---------|
| "SPM auto-discovers files, pbxproj doesn't matter" | The Xcode workspace has `.pbxproj` files. They must stay in sync or Xcode breaks. |
| "It's faster to use bash" | A file invisible to Xcode causes build failures and confuses teammates. |
| "I'll update pbxproj manually after" | pbxproj is binary-adjacent XML; manual edits cause merge conflicts and corruption. |
| "The file is just temporary" | Temporary files still break the build if Xcode can't see them. |

## Example

```
# ✅ Add a new source file
XcodeWrite(
  tabIdentifier: <tab>,
  filePath: "DatadogLogs/Sources/LogBatcher.swift",
  content: "..."
)
# → Creates file on disk AND registers it in pbxproj + target membership

# ✅ Move a file
XcodeMV(
  tabIdentifier: <tab>,
  sourcePath: "DatadogLogs/Sources/LogBatcher.swift",
  destinationPath: "DatadogLogs/Sources/Batching/LogBatcher.swift"
)
# → Moves file on disk AND updates pbxproj reference

# ❌ Wrong — file created on disk but invisible to Xcode
Write(file_path: ".../DatadogLogs/Sources/LogBatcher.swift", content: "...")
```

## Getting the tabIdentifier

```python
XcodeListWindows()  # → returns tabIdentifier for open workspace
```

## Path Format

Xcode MCP uses **project navigator paths**, not filesystem paths. Use `XcodeLS` to discover them:

```python
XcodeLS(tabIdentifier: <tab>, path: "DatadogLogs")
# → ["ConsoleLogger.swift", "Feature/LogsFeature.swift", ...]
# Note: paths are relative to the Xcode group, not the filesystem root
```

To create `DatadogLogs/Sources/Foo.swift` on disk, use the navigator path `DatadogLogs/Foo.swift`.

## After File Operations

After adding files to a module, verify the build still works:

```python
BuildProject(tabIdentifier: <tab>)
```